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   |   Programming   |   Topic List   |   Previous   |   Next   |   Contents

   Programming a BEA Tuxedo Application Using FML

FML provides a set of routines that perform data conversion upon reading or writing a fielded buffer.

Generally, the functions behave like their non-conversion counterparts, except that they provide conversion from a user type to the native field type when writing to a buffer, and from the native type to a user type when reading from a buffer.

The native type of a field is the type specified for it in its field table entry and encoded in its field identifier. (The only exception to this rule is CFfindocc, which, although it is a read operation, converts from the user-specified type to the native type before calling Ffindocc.) The function names are the same as their non-conversion FML counterparts except that they include a "C" prefix.

The following field types are not supported for conversion functions: pointers (FLD_PTR), embedded FML32 buffers (FLD_FML32), and embedded VIEW32 buffers (FLD_VIEW32). If one of these field types is encountered during the execution of an FML32 conversion function, Ferror is set to FEBADOP.

The CFadd function adds a user-supplied item to a buffer creating a new field occurrence within the buffer.

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

Here:

• fbfr is a pointer to a fielded buffer.

• fieldid is the field identifier of the field to be added.

• value is a pointer to the value to be added.

• len is the length of the value, if of type carray.

• type is the type of the value.

Before the field addition, the data item is converted from a user-supplied type to the type specified in the field table as the fielded buffer storage type of the field. If the source type is FLD_CARRAY (character array), the length argument should be set to the length of the array. Consider the following example.

For more information, refer to CFadd, CFadd32(3fml) in the BEA Tuxedo FML Function Reference.

The function CFchg acts like CFadd, except that it changes the value of a field (after conversion of the supplied value).

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

Here:

• fbfr is a pointer to a fielded buffer.

• fieldid is the field identifier of the field to be changed.

• oc is the occurrence number of the field to be changed.

• value is a pointer to the value to be added.

• len is the length of the value, if of type carray.

• type is the type of the value.

For example, the following code changes the first occurrence (occurrence 0) of field ZIP to the specified value, doing any needed conversion.

For more information, refer to CFchg, CFchg32(3fml) in the BEA Tuxedo FML Function Reference.

CFget is the conversion analog of Fget. The difference is that it copies a converted value to the user-supplied buffer.

int
CFget(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *buf, FLDLEN *len, int type)

Here:

• fbfr is a pointer to a fielded buffer.

• fieldid is the field identifier of the field to be retrieved.

• oc is the occurrence number of the field.

• buf is a pointer to the post-conversion buffer.

• len is the length of the value, if of type carray.

• type is the type of the value.

Using the previous example, the following code gets the value that was just stored in the buffer (regardless of which format is being used) and converts it back to a long integer.

For more information, refer to CFget, CFget32(3fml) in the BEA Tuxedo FML Function Reference.

CFgetalloc is like Fgetalloc; you are responsible for freeing the space allocated with malloc for the returned (converted) value with free.

char *
CFgetalloc(FBFR *fbfr, FLDID fieldid, FLDOCC oc, int type, FLDLEN *extralen)

Here:

• fbfr is a pointer to a fielded buffer.

• fieldid is the field identifier of the field to be converted.

• oc is the occurrence number of the field.

• type is the type to which the value is converted.

• extralen on calling the function is a pointer to the extra allocation amount; on return, it is a pointer to the size of the total allocated area.

In the declaration above, the return value to CFgetalloc 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.

For more information, refer to CFgetalloc, CFgetalloc32(3fml) in the BEA Tuxedo FML Function Reference.

CFfind returns a pointer to a converted value of the desired field.

char *
CFfind(FBFR *fbfr, FLDID fieldid, FLDOCC oc, FLDLEN len, int type)

Here:

• fbfr is a pointer to a fielded buffer.

• fieldid is the field identifier of the field to be retrieved.

• oc is the occurrence number of the field.

• len is the length of the post-conversion value.

• type is the type to which the value is converted.

In the previous declaration the return value to CFfind 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.

Like Ffind, this pointer should be considered "read only." For example, the following code returns a pointer to a long containing the value of the first occurrence of the ZIP field.

char *CFfind;
FLDLEN len;
long *value;
. . .
if((value=(long *)CFfind(fbfr,ZIP,occurrence,&len,FLD_LONG))== NULL)
   F_error("pgm_name");

If the length pointer is NULL, then the length of the value found is not returned. Unlike Ffind, the value returned is guaranteed to be properly aligned for the corresponding user-specified type.

Note: The duration of the validity of the pointer returned by CFfind is guaranteed only until the next buffer operation, even if it is non-destructive, since the converted value is retained in a single private buffer. This differs from the value returned by Ffind, which is guaranteed until the next modification of the buffer.

For more information, refer to CFfind, CFfind32(3fml) in the BEA Tuxedo FML Function Reference.

CFfindocc 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 after it has been converted to the type of the field identifier.

FLDOCC
CFfindocc(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len, int type)

Here:

• fbfr is a pointer to a fielded buffer.

• fieldid is the field identifier of the field to be retrieved.

• value is a pointer to the unconverted matching value.

• len is the length of the unconverted matching value.

• type is the type of the unconverted matching value.

For example, the following code converts the string to the type of fieldid ZIP (possibly a long) and sets oc to the occurrence for the specified zip code.

For more information, refer to CFfindocc, CFfindocc32(3fml) in the BEA Tuxedo FML Function Reference.