|Navigation: ABC Library Reference > FieldPairsClass >====== FieldPairsClass Overview ======|
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.
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:
|ABUTIL.CLW||FieldPairsClass method definitions|
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:
And you have a Customer queue declared as:
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
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')
MESSAGE('Buffers not equal')
Fields.AssignRightToLeft !copy from CustQ QUEUE to Customer FILE
Fields.Kill !terminate FieldPairs object