Field Access and Modification Functions

Fadd

The Fadd function adds a new field value to the fielded buffer.

int
Fadd(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len)

Here:

Fadd, like all other functions that take or return a field value, expects a pointer to a field value, never the value itself.

If the field type is such that the field length is fixed (short, long, char, float, or double) or can be determined (string), the field length need not be given (it is ignored). If the field type is a character array, the length must be specified; the length is defined as type FLDLEN. The following code, for example, gets the field identifier for the desired field and adds the field value to the buffer.

FLDID fieldid, Fldid;
FBFR *fbfr;
. . .
fieldid = Fldid("fieldname");
if(Fadd(fbfr, fieldid, "new value", (FLDLEN)9) < 0)
          F_error("pgm_name");

It is assumed (by default) that the native type of the field is a character array so that the length of the value must be passed to the function. If the value being added is not a character array, the type of value must reflect the type of the value to which it points. The following code, for example, adds a long field value.

long lval;
. . .
lval = 123456789;
if(Fadd(fbfr, fieldid, &lval, (FLDLEN)0) < 0)
          F_error("pgm_name");

For character array fields, null fields may be indicated by a length of 0. For string fields, the null string may be stored since the NULL terminating byte is actually stored as part of the field value: a string consisting of only the NULL terminating byte is considered to have a length of 1. For all other types (fixed length types), you may choose some special value that is interpreted by the application as a NULL, but the size of the value is taken from its field type (for example, a length of 4 for a long), regardless of what value is actually passed. Passing a NULL value address results in an error (FEINVAL).

For embedded VIEW32 buffers, Fadd32 stores a pointer to a structure of type FVIEWFLD, which contains vflags (a flags field, currently unused and set to 0), vname (a character array containing the view name), and data (a pointer to the view data stored as a C structure). The application provides the vname and data to Fadd32. The FVIEWFLD structure is as follows:

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

Fappend

The Fappend function appends a new field value to the fielded buffer.

int
Fappend(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len)

Here:

Fappend appends a new occurrence of the field fieldid with a value located at value to the fielded buffer and puts the buffer into append mode. Append mode provides optimized buffer construction for large buffers constructed of many rows of a common set of fields.

The following example shows the construction, using Fappend, of a 500-row buffer with 5 fields per row:

for (i=0; i 500 ;i++) {
   if ((Fappend(fbfr, LONGFLD1, &lval1[i], (FLDLEN)0) < 0) ||
      (Fappend(fbfr, LONGFLD2, &lval2[i], (FLDLEN)0) < 0) ||
      (Fappend(fbfr, STRFLD1, &str1[i], (FLDLEN)0) < 0) ||
      (Fappend(fbfr, STRFLD2, &str2[i], (FLDLEN)0) < 0) ||
      (Fappend(fbfr, LONGFLD3, &lval3[i], (FLDLEN)0) < 0)) {
      F_error("pgm_name");
     break;
   }
}
Findex(fbfr, 0);

Fappend, like all other functions that take or return a field value, expects a pointer to a field value, never the value itself.

If the field type is such that the field length is fixed (short, long, char, float, or double) or can be determined (string), the field length need not be given (it is ignored). If the field type is a character array, the length must be specified; the length is defined as type FLDLEN.

It is assumed (by default) that the native type of the field is a character array so that the length of the value must be passed to the function. If the value being appended is not a character array, the type of value must reflect the type of the value it points to.

For character array fields, null fields may be indicated by a length of 0. For string fields, the null string may be stored since the NULL terminating byte is actually stored as part of the field value: a string consisting of only the NULL terminating byte is considered to have a length of 1. For all other types (fixed-length types), you may choose some special value that is interpreted by the application as a NULL, but the size of the value is taken from its field type (for example, the length of 4 for a long), regardless of what value is actually passed. Passing a NULL value address results in an error (FEINVAL).

Fchg

Fchg changes the value of a field in the buffer.

int
Fchg(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *value, FLDLEN len)

Here:

For example, the following code changes a field of type carray to a new value stored in value:

FBFR *fbfr;
FLDID fieldid;
FLDOCC oc;
FLDLEN len;
char value[50];
. . .
strcpy(value, "new value");
flen = strlen(value);
if(Fchg(fbfr, fieldid, oc, value, len) < 0)
       F_error("pgm_name");

If oc is -1, then the field value is added as a new occurrence to the buffer. If oc is 0 or greater and the field is found, then the field value is modified to the new value specified. If oc is 0 or greater and the field is not found, then NULL occurrences are added to the buffer until the value can be added as the specified occurrence. For example, changing field occurrence 3 for a field that does not exist on a buffer causes three NULL occurrences to be added (occurrences 0, 1 and 2), followed by occurrence 3 with the specified field value. Null values consist of the NULL string "\0" (1 byte in length) for string and character values, 0 for long and short fields, 0.0 for float and double values, and a zero-length string for a character array.

The new or modified value is contained in value. If it is a character array, its length is given in len (len is ignored for other field types). If the value pointer is NULL and the field is found, then the field is deleted. If the field occurrence to be deleted is not found, it is considered an error (FNOTPRES).

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

The buffer must have enough room to contain the modified or added field value, or an error is returned (FNOSPACE).

Fcmp

Fcmp compares the field identifiers and field values of two fielded buffers.

int
Fcmp(FBFR *fbfr1, FBFR *fbfr2)

Here fbfr1 and fbfr2 are pointers to fielded buffers.

The function returns a 0 if the buffers are identical; it returns a -1 on any of the following conditions:

The following criteria are used to determine whether pointers and embedded buffers are equal:

Fcmp returns a 1 if the opposite of any of these conditions is true. For example, Fcmp returns 1 if the field ID of a fbfr2 field is less than the field ID of the corresponding field of fbfr1.

Fdel

The Fdel function deletes the specified field occurrence.

int
Fdel(FBFR *fbfr, FLDID fieldid, FLDOCC oc)

Here:

For example, the following code deletes the first occurrence of the field indicated by the specified field identifier:

FLDOCC occurrence;
. . .
occurrence=0;
if(Fdel(fbfr, fieldid, occurrence) < 0)
            F_error("pgm_name");

If the specified field does not exist, the function returns -1 and Ferror is set to FNOTPRES.

For pointer fields, Fdel32 deletes the FLD_PTR field occurrence without changing the referenced buffer or freeing the pointer. The data buffer is treated as an opaque pointer.

Fdelall

Fdelall deletes all occurrences of the specified field from the buffer.

int
Fdelall(FBFR *fbfr, FLDID fieldid)

Here:

Consider the following example:

if(Fdelall(fbfr, fieldid) < 0)
     F_error("pgm_name");        /* field not present */

If the field is not found, the function returns -1 and Ferror is set to FNOTPRES.

For pointer fields, Fdelall32 deletes the FLD_PTR field occurrence without changing the referenced buffer or freeing the pointer. The data buffer is treated as an opaque pointer.

Fdelete

Fdelete deletes all occurrences of all fields listed in the array of field identifiers, fieldid[].

int
Fdelete(FBFR *fbfr, FLDID *fieldid)

Here:

The update is done directly to the fielded buffer. The array of field identifiers does not need to be in any specific order, but the last entry in the array must be field identifier 0 (BADFLDID). Consider the following example:

#include "fldtbl.h"
FBFR *dest;
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(Fdelete(dest, fieldid) < 0)
         F_error("pgm_name");

If the destination buffer has fields A, B, C, and D, this example results in a buffer that contains only occurrences of fields B and C.

Fdelete provides a more efficient way of deleting several fields from a buffer than using several Fdelall calls.

For pointer fields, Fdelete deletes the FLD_PTR field occurrence without changing the referenced buffer or freeing the pointer. The data buffer is treated as an opaque pointer.

Ffind

Ffind finds the value of the specified field occurrence in the buffer.

char *
Ffind(FBFR *fbfr, FLDID fieldid, FLDOCC oc, FLDLEN *len)

Here:

In the previous declaration the return value to Ffind is shown as a character pointer data type (char* in C). The actual type of the pointer returned is the same as the type of the value to which it points.

The following code provides an example of how this function is used:

#include "fldtbl.h"
FBFR *fbfr;
FLDLEN len;
char* Ffind, *value;
. . .
if((value=Ffind(fbfr,ZIP,0, &len)) == NULL)
      F_error("pgm_name");

If the field is found, its length is returned in len (if len is NULL, the length is not returned), and its location is returned as the value of the function. If the field is not found, NULL is returned, and Ferror is set to FNOTPRES.

Ffind is useful for gaining "read-only" access to a field. The value returned by Ffind should not be used to modify the buffer. Field values should be modified only by the Fadd or Fchg function. This function does not check for occurrences of the specified field in embedded buffers.

The value returned by Ffind is valid only so long as the buffer remains unmodified. The value is guaranteed to be aligned on a short boundary but may not be aligned on a long or double boundary, even if the field is of that type. (See the conversion functions described later in this document for aligned values.) On processors that require proper alignment of variables, referencing the value when not aligned properly causes a system error, as shown in the following example:

long *l1,l2;
FLDLEN length;
char *Ffind;
. . .
if((l1=(long *)Ffind(fbfr, ZIP, 0, &length)) == NULL)
        F_error("pgm_name");
else
        l2 = *l1;

This code should be re-written as follows:

if((l1==(long *)Ffind(fbfr, ZIP, 0, &length)) == NULL)
         F_error("pgm_name");
else
         memcpy(&l2,l1,sizeof(long));

Ffindlast

This function finds the last occurrence of a field in a fielded buffer and returns a pointer to the field, as well as the occurrence number and length of the field occurrence.

char *
Ffindlast(FBFR *fbfr, FLDID fieldid, FLDOCC *oc, FLDLEN *len)

Here:

In the previous declaration the return value to Ffindlast is shown as a character pointer data type (char* in C). The actual type of the pointer returned is the same as the type of the value to which it points.

The value returned by Ffindlast is valid only as long as the buffer remains unchanged.

Ffindocc

Ffindocc looks at occurrences of the specified field on the buffer and returns the occurrence number of the first field occurrence that matches the user-specified field value.

FLDOCC
Ffindocc(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len;)

Here:

For example, the following code sets oc to the occurrence for the specified zip code:

#include "fldtbl.h"
FBFR *fbfr;
FLDOCC oc;
long zipvalue;
. . .
zipvalue = 123456;
if((oc=Ffindocc(fbfr,ZIP,&zipvalue, 0)) < 0)
       F_error("pgm_name");

Regular expressions are supported for string fields. For example, the following code sets oc to the occurrence of NAME that starts with "J":

#include "fldtbl.h"
FBFR *fbfr;
FLDOCC oc;
char *name;
. . .
name = "J.*"
if ((oc = Ffindocc(fbfr, NAME, name, 1)) < 0)
        F_error("pgm_name");

Note: To enable pattern matching on strings, the fourth argument to Ffindocc must be non-zero. If it is zero, a simple string compare is performed. If the field value is not found, -1 is returned.

For upward compatibility, a circumflex (^) prefix and dollar sign ($) suffix are implicitly added to the regular expression. Thus the previous example is actually interpreted as "^(J.*)$". The regular expression must match the entire string value in the field.

Fget

Use Fget to retrieve a field from a fielded buffer when the value is to be modified.

int
Fget(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *loc, FLDLEN *maxlen)

Here:

The caller provides Fget with a pointer to a private buffer, as well as the length of the buffer. If maxlen is specified as NULL, then it is assumed that the destination buffer is large enough to accommodate the field value, and its length is not returned.

Fget returns an error if the desired field is not in the buffer (FNOTPRES), or if the destination buffer is too small (FNOSPACE). For example, the following code gets the zip code, assuming it is stored as a character array or string:

FLDLEN len;
char value[100];
. . .
len=sizeof(value);
if(Fget(fbfr, ZIP, 0, value, &len) < 0)
          F_error("pgm_name");

If the zip code is stored as a long, it can be retrieved by the following code:

FLDLEN len;
long value;
. . .
len = sizeof(value);
if(Fget(fbfr, ZIP, 0, value, &len) < 0)
          F_error("pgm_name");

Fgetalloc

char *
Fgetalloc(FBFR *fbfr, FLDID fieldid, FLDOCC oc, FLDLEN *extralen)

Here:

In the declaration above the return value to Fgetalloc is shown as a character pointer data type (char* in C). The actual type of the pointer returned is the same as the type of the value to which it points.

On success, Fgetalloc returns a valid pointer to the copy of the properly aligned buffer field; on error it returns NULL. If malloc(3) fails, Fgetalloc returns an error and Ferror is set to FMALLOC.

The last parameter to Fgetalloc specifies an extra amount of space to be acquired if, for instance, the value obtained is to be expanded before re-insertion into the fielded buffer. On success, the length of the allocated buffer is returned in extralen. Consider the following example:

FLDLEN extralen;
FBFR *fieldbfr
char *Fgetalloc;
. . .
extralen = 0;
if (fieldbfr = (FBFR *)Fgetalloc(fbfr, ZIP, 0, &extralen) == NULL)
         F_error("pgm_name");

It is the responsibility of the caller to free space acquired by Fgetalloc.

Fgetlast

Fgetlast is used to retrieve the last occurrence of a field from a fielded buffer when the value is to be modified.

int
Fgetlast(FBFR *fbfr, FLDID fieldid, FLDOCC *oc, char *loc, FLDLEN *maxlen)

Here:

The caller provides Fgetlast with a pointer to a private buffer, as well as the length of the buffer. Fgetlast acts like Fget, except that you do not specify a field occurrence. Instead, both the occurrence number and the value of the last field occurrence are returned. However, if you specify NULL for occ on calling the function, the occurrence number is not returned.

Fnext

Fnext finds the next field in the buffer after the specified field occurrence.

int
Fnext(FBFR *fbfr, FLDID *fieldid, FLDOCC *oc, char *value, FLDLEN *len)

Here:

A fieldid of FIRSTFLDID should be specified to get the first field in a buffer; the field identifier and occurrence number of the first field occurrence are returned in the corresponding parameters. If the field is not NULL, its value is copied into the memory location addressed by the value pointer.

The len parameter is used to determine whether value has enough space allocated to contain the field value. If the amount of space is insufficient, Ferror is set to FNOSPACE. The length of the value is returned in the len parameter. If the value of the field is non-null, then the len parameter is also assumed to contain the length of the currently allocated space for value.

When the field to be retrieved is an embedded VIEW32 buffer, the value parameter points to an FVIEWFLD structure. The Fnext function populates the vname and data fields in the structure. The FVIEWFLD structure is as follows:

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

If the field value is NULL, then the value and length parameters are not changed.

If no more fields are found, Fnext returns 0 (end of buffer) and fieldid, occurrence, and value are left unchanged.

If the value parameter is not NULL, the length parameter is also assumed to be non-NULL.

The following example reads all field occurrences in the buffer:

FLDID fieldid;
FLDOCC occurrence;
char *value[100];
FLDLEN len;
. . .
for(fieldid=FIRSTFLDID,len=sizeof(value);
     Fnext(fbfr,&fieldid,&occurrence,value,&len) > 0;
     len=sizeof(value)) {
   /* code for each field occurrence */
}

Fnum

Fnum returns the number of fields contained in the specified buffer, or -1 on error.

FLDOCC
Fnum(FBFR *fbfr)

Here fbfr is a pointer to a fielded buffer. The following code, for example, prints the number of fields in the specified buffer:

if((cnt=Fnum(fbfr)) < 0)
  F_error("pgm_name");
else
  fprintf(stdout,"%d fields in buffer\n",cnt);

Each FLD_FML32 and FLD_VIEW32 field is counted as a single field, regardless of the number of fields it contains.

Foccur

Foccur returns the number of occurrences for the specified field in the buffer:

FLDOCC
Foccur(FBFR *fbfr, FLDID fieldid)

Here:

Occurrences of a field within an embedded FML32 buffer are not counted.

Zero is returned if the field does not occur in the buffer and -1 is returned on error. For example, the following code prints the number of occurrences of the field ZIP in the specified buffer:

FLDOCC cnt;
. . .
if((cnt=Foccur(fbfr,ZIP)) < 0)
 F_error("pgm_name");
else
 fprintf(stdout,"Field ZIP occurs %d times in buffer\n",cnt);

Fpres

Fpres returns true (1) if the specified field occurrence exists. Otherwise, it returns false (0).

int
Fpres(FBFR *fbfr, FLDID fieldid, FLDOCC oc)

Here:

For example, the following code returns true if the field ZIP exists in the fielded buffer referenced by fbfr:

Fpres(fbfr,ZIP,0)

Fpres does not check for occurrences of the specified field within an embedded buffer.

Fvals and Fvall

char* 
Fvals(FBFR *fbfr,FLDID fieldid,FLDOCC oc)

char*
Fvall(FBFR *fbfr,FLDID fieldid,FLDOCC oc)

In both functions:

For Fvals, if the specified field occurrence is not found, the NULL string, \0, is returned. This function is useful for passing the value of a field to another function without checking the return value. This function is valid only for fields of type string; the NULL string is automatically returned for other field types (that is, no conversion is done).

For Fvall, if the specified field occurrence is not found, then 0 is returned. This function is useful for passing the value of a field to another function without checking the return value. This function is valid only for fields of type long and short; 0 is automatically returned for other field types (that is, no conversion is done).