Clarion Community Help

In database oriented programs there are some fundamental operations that occur over and over again. Among these repetitive operations is the saving and restoring of field values, and comparing current field values against previous values.

The ABC Library provides two classes (FieldPairsClass and BufferedPairsClass) that supply this basic buffer management. These classes are completely generic so that they may apply to any pairs of fields, regardless of the fields' origins.

The fundamental benefit of these classes is their generality; that is, they let you move data between pairs of structures such as FILE or QUEUE buffers, and compare the data, without knowing in advance what the buffer structures look like or, for that matter, without requiring that the fields even reside in conventional buffer structures.

In some ways the FieldPairsClass is similar to Clarion's deep assignment operator (:=: see the Language Reference for a description of this operator). However, the FieldPairsClass has the following advantages over deep assignment:

·Field pair labels need not be an exact match

·Field pairs are not limited to GROUPs, RECORDs, and QUEUEs

·Field pairs are not restricted to a single source and a single destination

·You can compare the sets of fields for equivalence

·You can mimic a data structure where no structure exists

The FieldPairsClass has the disadvantage of not handling arrays (because the FieldPairsClass relies on the ANY datatype which only accepts references to simple datatypes). See the Language Reference for more information on the ANY datatype.

FieldPairsClass Concepts

The FieldPairsClass lets you move data between field pairs, and lets you compare the field pairs to detect whether any changes occurred since the last operation.

This class provides methods that let you identify or “set up” the targeted field pairs.

Once the field pairs are identified, you call a single method to move all the fields in one direction (left to right), and another method to move all the fields in the other direction (right to left). You simply have to remember which entity (set of fields) you described as “left” and which entity you described as “right.” A third method compares the two sets of fields and returns a value to indicate whether or not they are equivalent.

The paired fields need not be contiguous in memory, nor do they need to be part of a structure. You can build a virtual structure simply by adding a series of otherwise unrelated fields to a FieldPairs object. The other FieldPairs methods then operate on this virtual structure.

FieldPairsClass Relationship to Other Application Builder Classes

The ViewManager and the BrowseClass use the FieldPairsClass and BufferedPairsClass to accomplish various tasks.

The BufferedPairsClass is derived from the FieldPairs class, so it provides all the functionality of the FieldPairsClass; however, this class also provides a third buffer area (a “save” area), plus the ability to compare the save area with the primary buffers, and the ability to restore data from the save area to the primary buffers (to implement a standard “cancel” operation).

FieldPairsClass ABC Template Implementation

Various ABC Library objects instantiate the FieldPairsClass as needed; therefore, the template generated code does not directly reference the FieldPairsClass (or BufferedPairsClass).

FieldPairsClass Source Files

The FieldPairsClass source code is installed by default in the Clarion \LIBSRC folder. The specific files and their respective components are:

FieldPairsClass Conceptual Example

The FieldPairs classes are very abstract, so here is a concrete example to help your understanding. The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate a FieldPairsClass object.

Let's assume you have a Customer file declared as:

Customer FILE,DRIVER('TOPSPEED'),PRE(CUST),CREATE,BINDABLE

ByNumber KEY(CUST:CustNo),NOCASE,OPT,PRIMARY

Record   RECORD,PRE()

CustNo    LONG

Name      STRING(30)

Phone     STRING(20)

Zip       DECIMAL(5)

        END

       END

And you have a Customer queue declared as:

CustQ   QUEUE

CustNo   LONG

Name     STRING(30)

Phone    STRING(20)

Zip      DECIMAL(5)

       END

And you want to move data between the file buffer and the queue buffer.

INCLUDE('ABUTIL.INC')           !declare FieldPairs Class

Fields  FieldPairsClass          !declare Fields object

CODE

Fields.Init                               !initialize FieldPairs object

Fields.AddPair(CUST:CustNo, CustQ.CustNo) !establish CustNo pair

Fields.AddPair(CUST:Name,  CustQ.Name)    !establish Name pair

Fields.AddPair(CUST:Phone, CustQ.Phone)   !establish Phone pair

Fields.AddPair(CUST:Zip,  CustQ.Zip)      !establish Zip pair

Fields.AssignLeftToRight   !copy from Customer FILE to CustQ QUEUE

IF Fields.Equal()          !compare the CustQ QUEUE and Customer FILE

 MESSAGE('Buffers are equal')

ELSE

 MESSAGE('Buffers not equal')

END

Fields.AssignRightToLeft   !copy from CustQ QUEUE to Customer FILE

Fields.Kill                !terminate FieldPairs object