![]() |
![]() |
|
|
Conversion Functions
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.
CFadd
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:
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:
if(CFadd(fbfr,ZIP,"12345",(FLDLEN)0,FLD_STRING) < 0)
F_error("pgm_name");
If the ZIP (zip code) field were stored in a fielded buffer as a long integer, the function would convert "12345" to a long integer representation, before adding it to the fielded buffer pointed to by fbfr (note that the field value length is given as 0 since the function can determine it; the length is needed only for type FLD_CARRAY). The following code puts the same value into the fielded buffer, but does so by presenting it as a long, instead of as a string:
long zipval;
. . .
zipval = 12345;
if(CFadd(fbfr,ZIP,&zipval,(FLDLEN)0,FLD_LONG) < 0)
F_error("pgm_name");
Note that the value must first be put into a variable, since C does not permit the construct &12345L. CFadd returns 1 on success, and -1 on error, in which case Ferror is set appropriately.
For more information, refer to CFadd, CFadd32(3fml) in the BEA Tuxedo ATMI FML Function Reference.
CFchg
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:
For example, the following code changes the first occurrence (occurrence 0) of field ZIP to the specified value, doing any needed conversion:
FLDOCC occurrence;
long zipval;
. . .
zipval = 12345;
occurrence = 0;
if(CFchg(fbfr,ZIP,occurrence,&zipval,(FLDLEN)0,FLD_LONG) < 0)
F_error("pgm_name");
If the specified occurrence is not found, then null occurrences are added to pad the buffer with multiple occurrences until the value can be added as the specified occurrence.
For more information, refer to CFchg, CFchg32(3fml) in the BEA Tuxedo ATMI FML Function Reference.
CFget
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:
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:
FLDLEN len;
. . .
len=sizeof(zipval);
if(CFget(fbfr,ZIP,occurrence,&zipval,&len,FLD_LONG) < 0)
F_error("pgm_name");
If the length pointer is NULL, then the length of the value retrieved and converted is not returned.
For more information, refer to CFget, CFget32(3fml) in the BEA Tuxedo ATMI FML Function Reference.
CFgetalloc
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:
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.
The previously stored value can be retrieved into space allocated automatically for you by the following code:
char *value;
FLDLEN extra;
. . .
extra = 25;
if((value=CFgetalloc(fbfr,ZIP,0,FLD_LONG,&extra)) == NULL)
F_error("pgm_name");
The value extra in the function call indicates that the function should allocate an extra 25 bytes over the amount of space sufficient for the retrieved value. The total amount of space allocated is returned in this variable.
For more information, refer to CFgetalloc, CFgetalloc32(3fml) in the BEA Tuxedo ATMI FML Function Reference.
CFfind
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:
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 "readonly." 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 ATMI FML Function Reference.
CFfindocc
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:
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:
#include "fldtbl.h"
FBFR *fbfr;
FLDOCC oc;
char zipvalue[20];
. . .
strcpy(zipvalue,"123456");
if((oc=CFfindocc(fbfr,ZIP,zipvalue,0,FLD_STRING)) < 0)
F_error("pgm_name");
If the field value is not found, -1 is returned.
Note: Because CFfindocc converts the user-specified value to the native field type before examining the field values, regular expressions work only when the user-specified type and the native field type are both FLD_STRING. Thus, CFfindocc has no utility with regular expressions.
For more information, refer to CFfindocc, CFfindocc32(3fml) in the BEA Tuxedo ATMI FML Function Reference.
![]() |
![]() |
![]() |
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|