| **Navigation:**  [[abc library reference.htm|ABC Library Reference]] > FieldPairsClass >====== FieldPairsClass Overview {{c6h0009.jpg|C6H0009.jpg}} ====== | [[fieldpairsclass.htm|{{btn_prev_n.gif|Previous page}}]][[abc library reference.htm|{{btn_home_n.gif|Return to chapter overview}}]][[fieldpairsclass properties.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

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.

{{tipbox.jpg|TipBox.jpg}}

**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.htm|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  any simple data type .htm|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.

{{notebox.jpg|NoteBox.jpg}}

**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.INC | FieldPairsClass declarations |
|  | 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:

**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**