Fappend, Fappend32(3fml)

Name

Fappend(), Fappend32() - append new field occurrence

Synopsis

#include <stdio.h>
#include "fml.h" 
int 
Fappend(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len)
#include "fml32.h" 
int 
Fappend32(FBFR32 *fbfr, FLDID32 fieldid, char *value, FLDLEN32 len) 

Description

Fappend() adds the specified field value to the end of the given buffer. Fappend() is useful in building large buffers in that it does not maintain the internal structures and ordering necessary for general purpose FML access. The side effect of this optimization is that a call to Fappend() may be followed only by additional calls to Fappend(), calls to the FML indexing routines Findex() and Funindex(), or calls to Free(), Fused(), Funused() and Fsizeof(). Calls to other FML routines made before calling Findex() or Funindex() will result in an error with Ferror set to FNOTFLD.

fbfr is a pointer to a fielded buffer. fieldid is a field identifier. value is a pointer to a new value;the pointer's type must be the same fieldid type as the value to be added. len is the length of the value to be added; it is required only if type is FLD_CARRAY

The value to be added is contained in the location pointed toby the value parameter. If one or more occurrences of the field already exist, then the value is added as a new occurrence of the field, and is assigned an occurrence number 1 greater than the current highest occurrence (to add a specific occurrence, Fchg() must be used).

In the "Synopsis" section above the value argument to Fappend() is described as a character pointer data type (char * in C). Technically, this describes only one particular kind of value passable to Fappend(). In fact, the type of the value argument should be a pointer to an object of the same type as the type of the fielded-buffer representation of the field being added. For example, if the field is stored in the buffer as type FLD_LONG, then value should be of type pointer-to-long (long * in C). Similarly, if the field is stored as FLD_SHORT, then value should be of type pointer-to-short (short * in C). The important thing is that Fappend() assumes that the object pointed to by value has the same type as the stored type of the field being added.

For values of type FLD_CARRAY,the length of the value is given in the len argument. For all types other than FLD_CARRAY, the length of the object pointed to by value is inferred from its type (for example, a value of type FLD_FLOAT is of length sizeof(float)), and the contents of len are ignored.

Fappend32() is used with 32-bit FML.

A thread in a multithreaded application may issue a call to Fappend() or Fappend32() while running in any context state, including TPINVALIDCONTEXT.

Return Values

This function returns -1 on error and sets Ferror to indicate the error condition.

Errors

Under the following conditions, Fappend() fails and sets Ferror to:

See Also