Buffer Update Functions

The functions listed in this section access and update entire fielded buffers, rather than individual fields in the buffers. These functions use, at most, three parameters:

Fconcat

Fconcat adds fields from the source buffer to the fields that already exist in the destination buffer.

int
Fconcat(FBFR *dest, FBFR *src)

Occurrences in the destination buffer are maintained (that is, they are retained and not modified) and new occurrences from the source buffer are added with greater occurrence numbers than any existing occurrences for each field. The fields are maintained in field identifier order.

Consider the following example:

FBFR *src, *dest;
. . .
if(Fconcat(dest,src) < 0)
       F_error("pgm_name");

If dest has fields A, B, and two occurrences of C, and src has fields A, C, and D, the resulting dest has two occurrences of field A (destination field A and source field A), field B, three occurrences of field C (two from dest and the third from src), and field D.

This operation fails if there is not enough space for the new fields (FNOSPACE); in this case, the destination buffer remains unchanged.

Fjoin

Fjoin is used to join two fielded buffers based on matching field ID/occurrence.

int
Fjoin(FBFR *dest, FBFR *src)

For fields that match on field ID/occurrence, the field value is updated in the destination buffer with the value from the source buffer. Fields in the destination buffer that have no corresponding field ID/occurrence in the source buffer are deleted. Fields in the source buffer that have no corresponding field ID/occurrence in the destination buffer are not added to the destination buffer. Thus

if(Fjoin(dest,src) < 0)
     F_error("pgm_name");

Using the input buffers in the previous example results in a destination buffer that has source field value A and source field value C. This function may fail due to lack of space if the new values are larger than the old (FNOSPACE); in this case, the destination buffer will have been modified. However, if this happens, the destination buffer may be reallocated using Frealloc and the Fjoin function repeated (even if the destination buffer has been partially updated, repeating the function gives the correct results).

If joining buffers results in the removal of a pointer field (FLD_PTR), the memory area referenced by the pointer is not modified or freed.

Fojoin

Fojoin is similar to Fjoin, but it does not delete fields from the destination buffer that have no corresponding field ID/occurrence in the source buffer.

int
Fojoin(FBFR *dest, FBFR *src)

Note that fields in the source buffer for which there are no corresponding field ID/occurrence pairs in the destination buffer are not added to the destination buffer. Consider the following example:

if(Fojoin(dest,src) < 0)
      F_error("pgm_name");

Using the input buffers from the previous example, dest contains the source field value A, the destination field value B, the source field value C, and the second destination field value C. As with Fjoin, this function can fail for lack of space (FNOSPACE) and can be reissued again after more space has been allocated to complete the operation.

If joining buffers results in the removal of a pointer field (FLD_PTR), the memory area referenced by the pointer is not modified or freed.

Fproj

Fproj is used to update a buffer in place so that only the desired fields are kept. (The result, in other words, is a projection on specified fields.) If updating buffers results in the removal of a pointer field (FLD_PTR), the memory area referenced by the pointer is not modified or freed.

int
Fproj(FBFR *fbfr, FLDID *fieldid)

These fields are specified in an array of field identifiers passed to the function. The update is performed directly in the fielded buffer. Consider the following example:

#include "fldtbl.h"
FBFR *fbfr;
FLDID fieldid[20];
. . .
fieldid[0] = A;   /* field id for field A */
fieldid[1] = D;   /* field id for field D */
fieldid[2] = BADFLDID;   /* sentinel value */
if(Fproj(fbfr, fieldid) < 0)
      F_error("pgm_name");

If the buffer has fields A, B, C, and D, the example results in a buffer that contains only occurrences of fields A and D. Note that the entries in the array of field identifiers do not need to be in any specific order, but the last value in the array of field identifiers must be field identifier 0 (BADFLDID).

Fprojcpy

Fprojcpy is similar to Fproj but the desired fields are placed in a destination buffer. If updating buffers results in the removal of a pointer field (FLD_PTR), the memory area referenced by the pointer is not modified or freed.

int
Fprojcpy(FBFR *dest, FBFR *src, FLDID *fieldid)

Any fields in the destination buffer are first deleted and the results of the projection on the source buffer are copied into the destination buffer. Using the above example, the following code places the results of the projection in the destination buffer:

if(Fprojcpy(dest, src, fieldid) < 0)
       F_error("pgm_name");

The entries in the array of field identifiers may be rearranged; if the entries are not in numeric order, the field identifier array is sorted.

Fupdate

Fupdate updates the destination buffer with the field values in the source buffer.

int
Fupdate(FBFR *dest, FBFR *src)

For fields that match on field ID/occurrence, the field value is updated in the destination buffer with the value in the source buffer (like Fjoin). Fields on the destination buffer that have no corresponding field on the source buffer are left untouched (like Fojoin). Fields on the source buffer that have no corresponding field on the destination buffer are added to the destination buffer (like Fconcat). Consider the following example:

if(Fupdate(dest,src) < 0)
     F_error("pgm_name");

If the src buffer has fields A, C, and D, and the dest buffer has fields A, B, and two occurrences of C, the updated destination buffer contains: the source field value A, the destination field value B, the source field value C, the second destination field value C, and the source field value D.

typedef struct { 
     TM32U vflags;                /* flags - currently unused */ 
     char vname[FVIEWNAMESIZE+1]; /* name of view */ 
     char *data;                  /* pointer to view structure */ 
} FVIEWFLD;