Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo FML Function Reference

Fadd(), Fadd32() - add new field occurrence

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

Fadd() adds the specified field value to the given buffer. 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 to by 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 Fadd() is described as a character pointer data type (char * in C). Technically, this describes only one particular kind of value passable to Fadd(). 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 Fadd() 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_PTR, Fadd32() stores the pointer value. The buffer pointed to by a FLD_PTR field must be allocated using the tpalloc() call. For values of type FLD_FML32, Fadd32() stores the entire FLD_FML32 field value, except the index. For values of type FLD_VIEW32, Fadd() stores a pointer to a structure of type FVIEWFLD, that 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().

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 referenced 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.

Fadd32 is used with 32-bit FML.

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

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

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

[FALIGNERR]

"fielded buffer not aligned"
The buffer does not begin on the proper boundary.

[FNOTFLD]

"buffer not fielded" The buffer is not a fielded buffer or has not been initialized by Finit().

[FEINVAL]

"invalid argument to function" One of the arguments to the function invoked was invalid. (For example, specifying a NULL value parameter to Fadd().)

[FNOSPACE]

"no space in fielded buffer"
A field value is to be added in a fielded buffer but there is not enough space remaining in the buffer.

[FBADFLD]

"unknown field number or type"
A field number is specified which is not valid.

Introduction to FML Functions, CFadd, CFadd32(3fml), Fadds, Fadds32(3fml), Fchg, Fchg32(3fml)