FML functions are not directly available for COBOL programs. A procedure called FINIT is available to initialize a record for receiving FML data, and the
FVSTOF and
FVFTOS procedures are available to convert a COBOL record into an FML buffer, and vice-versa. For detailed descriptions of these procedures, see
Programming an Oracle Tuxedo ATMI Application Using COBOL. The COBOL interface is not described further here.
A second interface, FML32, uses 32-bit values for the field lengths and identifiers. It allows for about 30 million fields, and field and buffer lengths of about 2 billion bytes. The definitions, types, and function prototypes for FML32 are in fml32.h; functions reside in
-lfml32. All definitions, types, and function names for FML32 have a “32” suffix (for example,
MAXFBLEN32,
FBFR32,
FLDID32,
FLDLEN32,
F_OVHD32,
Fchg32, and error code
Ferror32). Also the environment variables are suffixed with “32” (for example,
FLDTBLDIR32,
FIELDTBLS32,
VIEWFILES32, and
VIEWDIR32). For FML32, a fielded buffer pointer is of type “
FBFR32 *”, a field length has the type
FLDLEN32, and the number of occurrences of a field has the type
FLDOCC32. The default required alignment for FML32 buffers is 4-byte alignment.
F32to16 converts a 32-bit FML buffer to a 16-bit FML buffer. It does this by converting the buffer on a field-by-field basis and then creating the index for the fielded buffer. A field is converted by generating a FLDID from a FLDID32, and copying the field value (and field length for
string and
carray fields).
dest and
src are pointers to the destination and source fielded buffers, respectively. The source buffer is not changed.
The field types for embedded buffers (FLD_PTR,
FLD_FML32, and
FLD_VIEW32) are supported only for FML32. Buffers containing
FLD_PTR,
FLD_FML32,
FLD_MBSTRING, or
FLD_VIEW32 fields cause
F32to16 to fail with an
FBADFLD error. There is no impact when
F16to32 is called for these functions.
1.
|
For functions that require a pointer to a fielded buffer (FBFR), this parameter is first. If a function takes two-fielded buffer pointers (such as the transfer functions), the destination buffer comes first, followed by the source buffer. A fielded buffer pointer must point to an area that is aligned on a short boundary (or an error is returned with Ferror set to FALIGNERR) and the area must be a fielded buffer (or an error is returned with Ferror set to FNOTFLD).
|
•
|
\0 for string (1 byte in length)
|
Fldid returns the field identifier for a given valid field name and loads the field name/field ID mapping tables from the field table files, if they do not already exist.
Here name is a valid field name.
Fname returns the field name for a given valid field identifier and loads the field ID/name mapping tables from the field table files, if they do not already exist.
Here fieldid is a valid field identifier.
Fldno extracts the field number from a given field identifier.
Here fieldid is a valid field identifier.
Fldtype extracts the field type (an integer, as defined in
fml.h) from a given field identifier.
Here fieldid is a valid field identifier.
Ftype returns a pointer to a string containing the name of the type of a field given a field identifier.
Here fieldid is a valid field identifier. For example, the following code returns a pointer to one of the following strings:
short,
long,
char,
float,
double,
string,
carray,
mbstring,
FLD_PTR,
FLD_FML32, or
FLD_VIEW32.
FLDID
Fmkfldid(int type, FLDID
num)
•
|
num is a field number. (It should be an unused field number to avoid confusion with existing fields.)
|
The functions described in this section are provided for writing stand-alone FML programs. If you are using the Oracle Tuxedo ATMI functions, keep in mind that for tasks such as allocating and freeing message buffers, you must call ATMI functions such as tpalloc(3c),
tprealloc(3c), and
tpfree(3c), instead of FML functions such as
Falloc, Falloc32(3fml),
Frealloc, Frealloc32(3fml), and
Ffree, Ffree32(3fml).
In this section, the variable fbfr refers to a pointer to a fielded buffer. Never attempt to declare fielded buffers themselves; declare only pointers to fielded buffers.
Fielded (or
Fielded32) is used to test whether the specified buffer is fielded.
Fielded returns true (
1) if the buffer is fielded. It returns false (
0) if the buffer is not fielded but does not set
Ferror.
•
|
F is the number of fields.
|
•
|
V is the space, in bytes, for field values.
|
Once you obtain the estimate of space from Fneeded, you can allocate the desired number of bytes using
malloc(3) and set up a pointer to the allocated memory space. For example, the following code allocates space for a fielded buffer large enough to contain 25 fields and 300 bytes of values.
The Fvneeded function determines the amount of space (in bytes) needed for a
VIEW buffer. The function takes a pointer to the name of the
VIEW as an argument.
The Fvneeded function returns the size of the
VIEW in number of bytes.
The Finit function initializes an allocated memory space as a fielded buffer.
int
Finit(FBFR *fbfr, FLDLEN
buflen)
•
|
fbfr is a pointer to an uninitialized fielded buffer.
|
•
|
buflen is the length of the buffer, in bytes.
|
A call to Finit to initialize the memory space allocated in the previous example looks like the following code:
Now fbfr points to an initialized, empty fielded buffer. Up to
Fneeded(NF, NV) bytes minus a small amount (
F_OVHD as defined in
fml.h) are available in the buffer to hold fields.
Calls to Fneeded,
malloc(3) and
Finit may be replaced by a single call to
Falloc, which allocates the desired amount of space and initializes the buffer.
•
|
F is the number of fields.
|
•
|
V is the space for field values, in bytes.
|
A call to Falloc that provides the same functionality created by the calls to
Fneeded,
malloc(), and
Finit described in the previous three sections, must be written as follows:
Ffree is used to free memory space allocated as a fielded buffer.
Ffree32 does not free the memory area referenced by a pointer in a
FLD_PTR field.
Here fbfr is a pointer to a fielded buffer. Consider the following example:
Ffree is preferable to
free(3), because
Ffree invalidates a fielded buffer, whereas
free(3) does not. It is necessary to invalidate fielded buffers because
malloc(3) re-uses memory that has been freed without clearing it. Thus, if
free(3) is used,
malloc can return a piece of memory that looks like a valid fielded buffer, but is not.
Be careful not to enter code such as the following:
Fsizeof returns the size of a fielded buffer in bytes.
Here fbfr is a pointer to a fielded buffer. In the following code, for example,
Fsizeof returns the same number that
Fneeded returned when the fielded buffer was originally allocated:
Funused may be used to determine how much space is available in a fielded buffer for additional data.
Here fbfr is a pointer to a fielded buffer. Consider the following example:
Note that Funused does not indicate the
location, in the buffer, of the unused bytes; only the
number of unused bytes is specified.
Fused may be used to determine how much space is used in a fielded buffer for data and overhead.
Here fbfr is a pointer to a fielded buffer. Consider the following example:
Note that Fused does not indicate the
location, in the buffer, of the used bytes; only the
number of used bytes is specified.
If you have allocated space with tpalloc(3c), you must call
tprealloc(3c) to reallocate that space. Being able to resize the buffer can be useful if, for example, a buffer runs out of space while a new field value is being added. Simply by calling
Frealloc you can increase the size of the buffer. In other situations you may want to call
Frealloc to decrease the size of the buffer.
FBFR *
Frealloc(FBFR *fbfr, FLDOCC
nf, FLDLEN
nv)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
nf is the new number of fields or 0.
|
•
|
nv is the new space for field values, in bytes.
|
If the amount of additional space requested in the call to Frealloc is contiguous to the old buffer,
newfbfr and
fbfr in the previous examples are the same. However, defensive programming dictates that you should declare
newfbfr as a safeguard in case either a new value or NULL is returned. If
Frealloc fails, do not use
fbfr again.
If src points to a fielded buffer and
dest points to an area of storage big enough to hold it, then the following code might be used to move the fielded buffer:
FBFR *src;
char *
dest;
. . .
memcpy(dest, src, Fsizeof(src));
The function memcpy, one of the C run-time memory management functions, moves the number of bytes indicated by its third argument from the area pointed to by its second argument to the area pointed to by its first argument.
While memcpy may be used to copy a fielded buffer, the destination copy of the buffer looks just like the source copy. In particular, for example, the destination copy has the same number of unused bytes as the source buffer.
Fmove acts like
memcpy, but does not need an explicit length (which is computed).
int
Fmove(char *dest, FBFR *
src)
•
|
dest is a pointer to the destination buffer.
|
•
|
src is a pointer to the source fielded buffer.
|
For values of type FLD_PTR,
Fmove32 transfers the buffer pointer. The application programmer must manage the reallocation and freeing of buffers when the associated pointer is moved. The buffer pointed to by a
FLD_PTR field must be allocated using the
tpalloc(3c) call.
Fcpy is used to overwrite one fielded buffer with another.
int
Fcpy(FBFR *dest, FBFR *
src)
•
|
dest is a pointer to the destination fielded buffer.
|
•
|
src is a pointer to the source fielded buffer.
|
Fcpy preserves the overall buffer length of the overwritten fielded buffer and therefore is useful for expanding or reducing the size of a fielded buffer. Consider the following example:
Unlike Fmove, where
dest could point to an uninitialized area,
Fcpy expects
dest to point to an initialized fielded buffer (allocated using
Falloc).
Fcpy also verifies that
dest is big enough to accommodate the data from the source buffer.
For values of type FLD_PTR,
Fcpy32 copies the buffer pointer. The application programmer must manage the reallocation and freeing of buffers when the associated pointer is copied. The buffer pointed to by a
FLD_PTR field must be allocated using the
tpalloc(3c) call.
The Fadd function adds a new field value to the fielded buffer.
int
Fadd(FBFR *fbfr, FLDID
fieldid, char *
value, FLDLEN
len)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
value is a pointer to a new value. Its type is shown as char*, but when it is used, its type must be the same type as the value to be added (see below).
|
•
|
len is the length of the value if its type is FLD_CARRAY or FLD_MBSTRING.
|
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 (
FLD_CARRAY or
FLD_MBSTRING), 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.
For pointer fields, Fadd32 stores the pointer value. The buffer pointed to by a
FLD_PTR field must be allocated using the
tpalloc(3c) call. For embedded FML32 buffers,
Fadd32 stores the entire
FLD_FML32 field value, except for the index.
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:
The Fappend function appends a new field value to the fielded buffer.
int
Fappend(FBFR *fbfr, FLDID
fieldid, char *
value, FLDLEN
len)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
value is a pointer to a new value. Its type is shown as char *, but when it is used, its type must be the same type as the value to be appended (see below).
|
•
|
len is the length of the value if its type is FLD_CARRAY or FLD_MBSTRING.
|
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.
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 (
FLD_CARRAY or
FLD_MBSTRING), the length must be specified; the length is defined as type
FLDLEN.
Fchg changes the value of a field in the buffer.
int
Fchg(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc, char *
value, FLDLEN
len)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
oc is the occurrence number of the field.
|
•
|
value is a pointer to a new value. Its type is shown as char *, but when it is used, its type must be the same type as the value to be added (see “Fadd” on page 6‑17).
|
•
|
len is the length of the value if its type is FLD_CARRAY or FLD_MBSTRING.
|
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 (
FLD_CARRAY or
FLD_MBSTRING), 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).
For pointer fields, Fchg32 stores the pointer value. The buffer pointed to by a
FLD_PTR field must be allocated using the
tpalloc(3c) call. For embedded FML32 buffers,
Fchg32 stores the entire
FLD_FML32 field value, except the index.
For embedded VIEW32 buffers, Fchg32 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
Fchg32. The
FVIEWFLD structure is as follows:
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 fieldid of a fbfr1 field is less than the field ID of the corresponding field of fbfr2.
|
•
|
The value of a fbfr1 field is less than the value of the corresponding field of fbfr2.
|
•
|
fbfr1 is shorter than fbfr2.
|
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.
The Fdel function deletes the specified field occurrence.
int
Fdel(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
oc is the occurrence number.
|
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 deletes all occurrences of the specified field from the buffer.
int
Fdelall(FBFR *fbfr, FLDID
fieldid)
•
|
fbfr is a pointer to a fielded buffer.
|
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 deletes all occurrences of all fields listed in the array of field identifiers,
fieldid[].
int
Fdelete(FBFR *fbfr, FLDID *
fieldid)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
fieldid is a pointer to the list of field identifiers to be deleted.
|
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 finds the value of the specified field occurrence in the buffer.
char *
Ffind(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc, FLDLEN *
len)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
oc is the occurrence number.
|
•
|
len is the length of the value found.
|
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:
char *
Ffindlast(FBFR *fbfr, FLDID
fieldid, FLDOCC *
oc, FLDLEN *
len)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
oc is a pointer to the occurrence number of the last field occurrence found.
|
•
|
len is a pointer to the length of the value found.
|
Ffindlast acts like
Ffind, 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 as the value of the occurrence when calling the function, the occurrence number is not returned. This function does not check for occurrences of the specified field in embedded buffers.
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;)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
value is a pointer to a new value. Its type is shown as char*, but when it is used, its type must be the same type as the value to be added (see “Fadd” on page 6‑17).
|
•
|
len is the length of the value if its type is FLD_CARRAY or FLD_MBSTRING.
|
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.
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)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
oc is the occurrence number.
|
•
|
loc is a pointer to a buffer to copy the field value into.
|
•
|
maxlen is a pointer to the length of the source buffer on calling the function, and a pointer to the length of the field on return.
|
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:
Like Fget,
Fgetalloc finds and makes a copy of a buffer field, but it acquires space for the field via a call to
malloc(3).
char *
Fgetalloc(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc, FLDLEN *
extralen)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
oc is the occurrence number.
|
•
|
extralen is a pointer to the additional length to be acquired on calling the function, and a pointer to the actual length acquired on return.
|
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:
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)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
oc is a pointer to the occurrence number of the last field occurrence.
|
•
|
loc is a pointer to a buffer to copy the field value into.
|
•
|
maxlen is a pointer to the length of the source buffer on calling the function, and a pointer to the length of the field on return.
|
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 finds the next field in the buffer after the specified field occurrence.
int
Fnext(FBFR *fbfr, FLDID *
fieldid, FLDOCC *
oc, char *
value, FLDLEN *
len)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
fieldid is a pointer to a field identifier.
|
•
|
oc is a pointer to the occurrence number.
|
•
|
value is a pointer of the same type as the value contained in the next field.
|
•
|
len is a pointer to the length of *value.
|
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.
If the value parameter is not NULL, the
length parameter is also assumed to be non-NULL.
Fnum returns the number of fields contained in the specified buffer, or
-1 on error.
Here fbfr is a pointer to a fielded buffer. The following code, for example, prints the number of fields in the specified buffer:
Each FLD_FML32 and
FLD_VIEW32 field is counted as a single field, regardless of the number of fields it contains.
Foccur returns the number of occurrences for the specified field in the buffer:
FLDOCC
Foccur(FBFR *fbfr, FLDID
fieldid)
•
|
fbfr is a pointer to a fielded buffer.
|
Fpres returns true (1) if the specified field occurrence exists. Otherwise, it returns false (0).
int
Fpres(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
oc is the occurrence number.
|
Fpres does not check for occurrences of the specified field within an embedded buffer.
Fvals works like
Ffind for
string values but guarantees that a pointer to a value is returned.
Fvall works like
Ffind for
long and
short values, but returns the actual value of the field as a
long, instead of as a pointer to the value.
char*
Fvals(FBFR *fbfr,FLDID fieldid,FLDOCC oc)
char*
Fvall(FBFR *fbfr,FLDID fieldid,FLDOCC oc)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
oc is the occurrence number.
|
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).
•
|
dest is a pointer to a destination fielded buffer.
|
•
|
src is a pointer to a source fielded buffer.
|
•
|
fieldid is a field identifier or an array of field identifiers.
|
Fconcat adds fields from the source buffer to the fields that already exist in the destination buffer.
If dest has fields A, B, and two occurrences of C, and
src has fields A, C, and D, the resulting
dest has two occurrences of field A (destination field A and source field A), field B, three occurrences of field C (two from
dest and the third from
src), and field D.
Fjoin is used to join two fielded buffers based on matching field ID/occurrence.
int
Fjoin(FBFR *dest, FBFR *
src)
Fojoin is similar to
Fjoin, but it does not delete fields from the destination buffer that have no corresponding field ID/occurrence in the source buffer.
int
Fojoin(FBFR *dest, FBFR *
src)
Using the input buffers from the previous example, dest contains the source field value A, the destination field value B, the source field value C, and the second destination field value C. As with
Fjoin, this function can fail for lack of space (
FNOSPACE) and can be reissued again after more space has been allocated to complete the operation.
Fproj is used to update a buffer in place so that only the desired fields are kept. (The result, in other words, is a projection on specified fields.) If updating buffers results in the removal of a pointer field (
FLD_PTR), the memory area referenced by the pointer is not modified or freed.
int
Fproj(FBFR *fbfr, FLDID *
fieldid)
Fprojcpy is similar to
Fproj but the desired fields are placed in a destination buffer. If updating buffers results in the removal of a pointer field (
FLD_PTR), the memory area referenced by the pointer is not modified or freed.
int
Fprojcpy(FBFR *dest, FBFR *
src, FLDID *
fieldid)
Fupdate updates the destination buffer with the field values in the source buffer.
If the src buffer has fields A, C, and D, and the
dest buffer has fields A, B, and two occurrences of C, the updated destination buffer contains: the source field value A, the destination field value B, the source field value C, the second destination field value C, and the source field value D.
For pointers, Fupdate32 stores the pointer value. The buffer pointed to by a
FLD_PTR field must be allocated using the
tpalloc(3c) call. For embedded FML32 buffers,
Fupdate32 stores the entire
FLD_FML32 field value, except the index.
For embedded VIEW32 buffers, Fupdate32 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
Fupdate32. The
FVIEWFLD structure is as follows:
int
Fvftos(FBFR *fbfr, char *
cstruct, char *
view)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
cstruct is a pointer to a structure.
|
•
|
view is a pointer to a view name string.
|
•
|
If a field in the fielded buffer contains data of type string or carray, characters are copied into the structure up to the size of the mapped structure member (that is, source values that are too long are truncated). If the source value is shorter than the mapped structure member, the remainder of the member value is padded with null (0) characters. String values are always terminated with a null character (even if this means truncating the value).
|
#include <stdio.h>
#include "fml.h"
#include "custdb.flds.h"
#include "custdb.h"
struct custdb cust;
FBFR *fbfr;
. . .
fbfr = Falloc(800,1000);
Fvinit((char *)&cust,"custdb"); /* initialize cust */
str = "string1";
Fadd(fbfr,ACTION,str,(FLDLEN)8);
str = "abc";
Fadd(fbfr,BUG_CURS,str,(FLDLEN)4);
Fvftos(fbfr,(char *)&cust,"custdb");
. . .
int
Fvstof(FBFR *fbfr, char *
cstruct, int
mode, char *
view)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
cstruct is a pointer to a structure.
|
•
|
mode is one of the following: FUPDATE, FJOIN, FOJOIN, or FCONCAT.
|
•
|
view is a pointer to a view name string.
|
Fvnull is used to determine whether an occurrence in a C structure contains the null value for that field.
int
Fvnull(char *cstruct, char *
cname, FLDOCC
oc, char *
view)
•
|
cstruct is a pointer to a structure.
|
•
|
cname is a pointer to the name of a structure member.
|
•
|
oc is the index to a particular element.
|
•
|
view is a pointer to a view name string.
|
•
|
1 if an occurrence is null
|
•
|
0 if an occurrence is not null
|
int
Fvsinit(char *cstruct, char *
view)
•
|
cstruct is a pointer to a structure.
|
•
|
view is a pointer to a view name string.
|
int
Fvopt(char *cname, int
option, char *
view)
•
|
cname is the name of a structure member.
|
•
|
option is one of the options listed below.
|
•
|
view is a pointer to a view name string.
|
int
Fvselinit(char *cstruct, char *
cname, char *
view)
•
|
cstruct is a pointer to a structure.
|
•
|
cname is a pointer to the name of a structure member.
|
•
|
view is a pointer to a view name string.
|
The RECORD description files are used at run time to manipulate the RECORD structures using RECORDFILES and
RECORDDIR environment variables.
RECORDFILES should contain a comma-separated list of record description files for the application. Files given as full pathnames are used as is; files listed as relative path names are searched for through the list of directories specified by
RECORDDIR.
RECORDDIR specifies a colon-separated list of directories to find RECORD description files with relative filenames.
A RECORD buffer pointer is of type RECORD *;
tpalloc ("
RECORD",
subtype,
size) returns a pointer of type
RECORD *. The maximum length of record name (
subtype) is 32 bytes; if the length of record name is greater than 16,
tptypes (
char *ptr,
char *type,
char *subtype) populates the first 16 bytes of subtype while
RECORD * pointer points to the beginning of full-length record name.
The F_error32() function is provided to produce a message on the standard error output. It takes one parameter (a string); it prints the argument string appended with a colon and a blank, and then prints an error message followed by a newline character. The error message displayed is the one defined for the error number currently in
Ferror32, which is set when errors occur.
Fstrerror32() can be used to retrieve from a message catalog to the text of an error message; it returns a pointer that can be used as an argument to userlog.
The Rinit() function initializes the allocated RECORD buffer.
The Rget() function retrieves an item or whole record from a RECORD buffer; the source data in RECORD is automatically converted to the type of the destination data.
The Rset() function sets an item or whole record to a RECORD buffer.
|
|
|
|
|
Name of the item or whole record to be set. If name is NULL or its length is zero, whole record is set.
|
|
|
|
Data type of the item. Please refer to Table 6‑10 for the list of valid datatype. When the whole record is set, datatype is ignored (can be set to zero).
|
|
Length of the application data in the buffer referenced by data. If the length of the object referenced by data can be inferred from its datatype (for example, if a value of type C_FLOAT is of length sizeof(float), the objects are C_SHORT, C_LONG, C_CHAR, C_FLOAT, C_DOUBLE, C_INT, C_DECIMAL, C_UINT, C_ULONG, C_LLONG, and C_USHORT), len is ignored.
|
|
flags indicates the data format. flags in Rset() is the same as flags in Rinit(). The format is applied to whole record.
|
The Frneeded() function is used to determine the space that must be allocated for a RECORD buffer.
On success, Frneeded() returns the space that must be allocated for a RECORD buffer. This function returns -1 on error and sets
Ferror32 to indicate the error condition.
The Fvftor32() function transfers data from a fielded buffer to a RECORD buffer.
Fvftor32() is used with 32-bit FML. The sub FML32 in FML32 buffer will be converted to corresponding group in RECORD buffer.
The Fvrtof32() function transfers data from a RECORD buffer to a fielded structure.
Fvrtof32() is used for 32-bit FML. The group in RECORD buffer will be convert to sub FML in FML32 buffer.
|
|
|
|
|
|
|
Name of the group item or the whole record to be transferred. If name is NULL or its length is zero, the whole record is retrieved.
|
|
Values can be: FUPDATE/FOJOIN/FJOIN/FCONCAT.
•
|
FUPDATE updates the destination buffer with the values in the RECORD buffer. For fields that match on fieldid/occurrence, the field value is updated in the destination buffer with the value in the source buffer. Fields in the destination buffer that have no corresponding field in the source buffer are left untouched. Fields in the source buffer that have no corresponding field in the destination buffer are added to the destination buffer.
|
•
|
FJOIN joins record buffer and fielded buffers based on the matching fieldid/occurrence. For fields that match on fieldid/occurrence, the field value is updated in the destination buffer with the value in the source buffer. Fields in the destination buffer that have no corresponding fieldid/occurrence in the source buffer are deleted. If joining buffers results in the removal of a FLD_PTR field, the memory area referenced by the pointer is not modified or freed.
|
•
|
FOJOIN is similar to FJOIN, but it keeps fields from the destination buffer fbfr that have no corresponding fieldid/occurrence in the source buffer rec. Fields that exist in the source buffer that have no corresponding fieldid/occurrence in the destination buffer are not added to the destination buffer. If joining buffers results in the removal of a FLD_PTR field, the memory area referenced by the pointer is not modified or freed.
|
•
|
FCONCAT adds fields from the source record buffer to the fields that already exist in the destination buffer. Occurrences in the destination buffer, if any, are maintained and new occurrences from the source buffer are added with greater occurrence numbers for the field.
|
|
|
|
The Fvrtos32() function transfers data from a RECORD buffer to a C structure.
viewname is not found in the files that
VIEWDIR or
VIEWFILES specifies.
While trying to find viewname, the program fails to find one of the files that
VIEWDIR or
VIEWFILES specifies.
viewname is not found in the files that
VIEWDIR or
VIEWFILES specifies.
While trying to find viewname, one of the files that
VIEWDIR or
VIEWFILES specifies is corrupted or not a
viewfile.
The Fvstor32() function transfers data from a C structure to a RECORD buffer.
viewname is not found in the files that
VIEWDIR or
VIEWFILES specifies.
While trying to find viewname, the program fails to find one of the files that
VIEWDIR or
VIEWFILES specifies.
viewname is not found in the files that
VIEWDIR or
VIEWFILES specifies.
While trying to find viewname, one of the files specified that
VIEWDIR or
VIEWFILES specifies is corrupted or not a viewfile.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
•
|
C_STRING, C_CHAR: EBCDIC and ASCII conversion
|
|
•
|
1 Binary integer type includes C_SHORT, C_USHORT, C_INT, C_UINT, C_LONG, C_ULONG.
|
•
|
2 If target's size is greater than src's, the rest of target is set as 0; otherwise, the src's content is truncated and copied to tgt.
|
•
|
3 If external variable's size is greater than rec's, when Rget() is invoked, the rest of external variable is set as 0; when Rset() is invoked, only rec->rsize's length of external variable is copied to rec. If external variable's size is less than rec's, when Rget() is invoked, the length pointed by the argument len of rec is copied to external's; when Rset() is invoked, the rest of rec's is set as ' ' (if rec's enc is ebcdic, it is 0x40).
|
•
|
4 Only supports numeric fields; Zoned Decimal is not supported.
|
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)
•
|
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 its type is FLD_CARRAY.
|
•
|
type is the type of the value.
|
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:
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)
•
|
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 its type is FLD_CARRAY.
|
•
|
type is the type of the value.
|
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)
•
|
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 its type is FLD_CARRAY.
|
•
|
type is the type of the value.
|
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)
•
|
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.
|
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.
CFfind returns a pointer to a converted value of the desired field.
char *
CFfind(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc, FLDLEN
len, int
type)
•
|
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.
|
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:
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.
|
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)
•
|
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.
|
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.
|
The functions CFadd,
CFchg,
CFget,
CFgetalloc, and
CFfind use the function
Ftypcvt to perform the appropriate data conversion. The
Ftypcvt32 function fails for the
FLD_PTR,
FLD_FML32, and
FLD_VIEW32 field types. The synopsis of
Ftypcvt usage is as follows (it does not follow the parameter order conventions).
char *
Ftypcvt(FLDLEN *tolen, int
totype, char *
fromval, int
fromtype, FLDLEN
fromlen)
•
|
tolen is a pointer to the length of the converted value.
|
•
|
totype is the type to which to convert.
|
•
|
fromval is a pointer to the value from which to convert.
|
•
|
fromtype is the type from which to convert.
|
•
|
fromlen is the length of the from value if the from type is FLD_CARRAY.
|
Ftypcvt converts from the value
*fromval, which has type
fromtype, and length
fromlen if
fromtype is type
FLD_CARRAY (otherwise
fromlen is inferred from
fromtype), to a value of type
totype.
Ftypcvt returns a pointer to the converted value, and sets
*tolen to the converted length, upon success. Upon failure,
Ftypcvt returns NULL. Consider the following example, in which the
CFchg function is used:
CFchg(fbfr,fieldid,oc,value,len,type)
FBFR *fbfr; /* fielded buffer */
FLDID fieldid; /* field to be changed */
FLDOCC oc; /* occurrence of field to be changed */
char *value; /* location of new value */
FLDLEN len; /* length of new value */
int type; /* type of new value */
{
char *convloc; /* location of post-conversion value */
FLDLEN convlen; /* length of post-conversion value */
extern char *Ftypcvt;
/* convert value to fielded buffer type */
if((convloc = Ftypcvt(&convlen,FLDTYPE(fieldid),value,type,len)) == NULL)
return(-1);
if(Fchg(fbfr,fieldid,oc,convloc,convlen) < 0)
return(-1);
return(1);
}
The user may call Ftypcvt directly to do field value conversion without adding or modifying a fielded buffer.
•
|
When a type char is being converted to any numeric type, or when a numeric type is being converted to a char, the char is considered to be a “shorter short.” For example, to convert a char to a float, use the method shown in the following code:
|
To convert a short to a
char, use the method shown in the next example:
•
|
A char is converted to a string by appending a NULL character. In this regard, a char is not a “shorter short.” If it were, assignment would be done by converting it to a short, and then converting the short to a string via sprintf. In the same sense, a string is converted to a char by assigning the first character of the string to the character.
|
•
|
The carray type is used to store an arbitrary sequence of bytes. In this sense, it can encode any user data type. Nevertheless, the following conversions are specified for carray types:
|
•
|
A carray is converted to a string by appending the NULL byte to the carray. In this sense, a carray can be used to store a string, less the overhead of the trailing NULL. (This approach does not always save space, since fields are aligned on short boundaries within a fielded buffer.) A string is converted to a carray by removing its terminating NULL byte.
|
•
|
When a carray is converted to any numeric, it is first converted to a string, and the string is then converted to a numeric. Likewise, a numeric is converted to a carray, by first being converted to a string, and then the string is converted to a carray.
|
•
|
A carray is converted to a char by assigning the first character of the array to the char. Likewise, a char is converted to a carray by assigning it as the first byte of the array, and setting the length of the array to 1.
|
Note that a carray of length 1 and a
char have the following differences:
•
|
A char has only the overhead of its associated fieldid, while a carray contains a length code, in addition to the associated fieldid.
|
•
|
A carray is converted to a numeric by first becoming a string, and then undergoing an atoi call; a char becomes a numeric by typecasting. For example, a char with value ASCII ‘1’ (decimal 49) converts to a short of value 49; a carray of length 1, with the single byte an ASCII ‘1’ converts to a short of value 1. Likewise a char ‘a’ (decimal 97) converts to a short of value 97; the carray ‘a’ converts to a short of value 0 (since atoi (“ a”) produces a 0 result).
|
•
|
When converting to or from a dec_t type, the associated conversion function as described in decimal(3) is used ( _gp_deccvasc, _gp_deccvdbl, _gp_deccvflt, _gp_deccvint, _gp_deccvlong, _gp_dectoasc, _gp_dectodbl, _gp_dectoflt, _gp_dectoint, and _gp_dectolong).
|
|
|
|
src and dest are the same type; no conversion required
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
decimal(3c) conversion function
|
As indicated in the example, the FLD_MBSTRING field is capable of carrying information identifying the code-set
character encoding, or simply
encoding, of its user data. In the example, the client-request
FLD_MBSTRING field holds Japanese user data represented by the Shift-JIS (SJIS) encoding, while the server-reply
FLD_MBSTRING field holds Japanese user data represented by the Extended UNIX Code (EUC) encoding. The multibyte character encoding feature reads environment variables
TPMBENC and
TPMBACONV to determine the source encoding, the target encoding, and the state (on or off) of automatic encoding conversion.
For an FML32 typed buffer holding many FLD_MBSTRING fields, using global encoding is a more efficient way to transport multibyte user data via FML32 buffers than adding a character encoding name to each
FLD_MBSTRING field. Using the
Fmbpack32() function, application developers can choose global encoding or individual encoding for each
FLD_MBSTRING field created via
Fmbpack32(). Only one global encoding name is allowed per FML32 buffer.
This function converts the multibyte characters in an FLD_MBSTRING field in an FML32 typed buffer to a named target encoding. Specifically,
tpconvfmb32() compares the source encoding name specified for the
FLD_MBSTRING field
with the target encoding name defined in
target_encoding; if the encoding names are different,
tpconvfmb32() converts the
FLD_MBSTRING field data to the target encoding.
This function converts the multibyte characters in an MBSTRING field in a VIEW32 typed buffer to a named target encoding. Specifically,
tpconvvmb32() compares the source encoding name specified for the
MBSTRING field with the target encoding name defined in
target_encoding; if the encoding names are different,
tpconvvmb32() converts the
MBSTRING field data to the target encoding.
When a fielded buffer is initialized by Finit or
Falloc, an index is automatically set up. This index is used to expedite fielded buffer accesses and is transparent to you. As fields are added to or deleted from the fielded buffer, the index is automatically updated.
Here fbfr is a pointer to a fielded buffer.
The function Findex may be used at any time to index an unindexed fielded buffer.
int
Findex(FBFR *fbfr. FLDOCC
intvl)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
intvl is the indexing interval.
|
The second argument to Findex specifies the indexing interval for the buffer. If 0 is specified, the value
FSTDXINT (defined in
fml.h) is used. The user may ensure that all fields are indexed by specifying an interval of 1.
int
Frstrindex(FBFR *fbfr, FLDOCC
numidx)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
numidx is the value returned by the Funindex function.
|
Funindex discards the index of a fielded buffer and returns the number of index entries the buffer had before the index was stripped.
Here fbfr is a pointer to a fielded buffer.
Fwrite discards the buffer index, writing only as much of the fielded buffer as has been used (as returned by
Fused).
Fread restores the index of a buffer by calling
Findex. The buffer is indexed with the same indexing interval with which it was written by
Fwrite.
Fread32 ignores the
FLD_PTR field type.
The user is responsible for calling Fchksum, writing the checksum value out, along with the fielded buffer, and checking it on input.
Fwrite does not write the checksum automatically. For pointer fields (
FLD_PTR), the name of the pointer field in the checksum calculation (rather than the pointer or the data referenced by the pointer) is included.
The Fprint function prints a fielded buffer on the standard output in text format.
Here fbfr is a pointer to a fielded buffer.
Ffprint is similar to
Fprint, except that it sends text to a specified output stream, as in the following line:
Ffprint(FBFR *fbfr, FILE *
iop)
•
|
fbfr is a pointer to a fielded buffer.
|
•
|
iop is a pointer of type FILE to the output stream.
|
For values of type FLD_PTR,
Fprint32 prints the field name or field identifier and the pointer value in hexadecimal. Although this function prints pointer information, the
Fextread32 function ignores the
FLD_PTR field type. For values of type
FLD_FML32,
Fprint32 recursively prints the FML32 buffer, with leading tabs added for each level of nesting. For values of type
FLD_VIEW32, this function prints the VIEW32 field name and structure member name/value pairs.
Fextread may be used to construct a fielded buffer from its printed format, that is, from the output of
Fprint (hexadecimal values output by
Fprint are interpreted properly).
Fextread accepts an optional flag preceding the field name/field identifier specification in the output of
Fprint, as shown in the following table.
If an error has occurred, -1 is returned, and
Ferror is set accordingly. If the end of the file is reached before a blank line,
Ferror is set to
FSYNTAX.
For a fielded buffer evaluation, any field that is referenced in a Boolean expression must exist in a field table. This implies that the FLDTBLDIR and
FIELDTBLS environment variables are set, as described in
“Setting Up Your Environment for FML and VIEWS” on page 4‑1 before using the Boolean compilation function. The field types used in Booleans are those allowed for FML fields:
short,
long,
float,
double,
char,
string, and
carray. Along with the field name, the field type is kept in the field table. Thus, the field type can always be determined.
For a VIEW evaluation, any field that is referenced in a Boolean expression must exist as a C structure element name, not the associated fielded buffer name, in the VIEW. This implies that the VIEWDIR and
VIEWFILES environment variables are set, as described in
“Setting Up Your Environment for FML and VIEWS” on page 4‑1 before using the Boolean compilation function. The field types used in Booleans are those allowed for FML VIEWS:
short,
long,
float,
double,
char,
string,
carray, plus
int and
dec_t. Along with the field name, the field type is kept in the view definition. Thus, the field type can always be determined.
As an example, consider ‘hello’ and
‘hell\\6f’. They are equivalent strings because the hexadecimal code for an ‘
o’ is
6f.
•
|
To compare a constant (that is, a quoted) string to a numeric, it converts the numeric to a string, and does a lexical comparison.
|
•
|
To compare a long and a double, it converts the long to a double.
|
+ expression
-
expression
~
expression
!
expression
expression *
expression
expression /
expression
expression %
expression
The binary * operator indicates multiplication. The
* operator is associative and expressions with several multiplications at the same level may be rearranged by the compiler.
The binary / operator indicates division. When positive integers are divided, truncation is toward 0, but the form of truncation is machine-dependent if either operand is negative.
The binary % operator yields the remainder from the division of the first expression by the second. The usual arithmetic conversions are performed. The operands must not be
float or
double.
expression +
expression
expression -
expression
The result of the + operator is the sum of the operands. The
+ operator is associative and expressions with several additions at the same level may be rearranged by the compiler. The operands must not both be
strings; if one is a
string, it is converted to the arithmetic type of the other.
The result of the - operator is the difference of the operands. The usual arithmetic conversions are performed. The operands must not both be
strings; if one is a
string, it is converted to the arithmetic type of the other.
expression ==
expression
expression !=
expression
expression %%
expression
expression !%
expression
The == (equal to) and the
!= (not equal to) operators yield 0 if the specified relation is false and 1 if it is true. The type of the result is
long. The usual arithmetic conversions are performed.
The %% operator takes, as its second expression, a regular expression against which it matches its first expression. The second expression (the regular expression) must be a quoted string. The first expression may be an FML field name or a quoted string. This operator yields a 1 if the first expression is fully matched by the second expression (the regular expression). The operator yields a 0 in all other cases.
The !% operator is the
not regular expression match operator. It takes exactly the same operands as the
%% operator, but yields exactly the opposite results. The relationship between
%% and
!% is analogous to the relationship between
== and
!=.
expression <
expression
expression >
expression
expression <=
expression
expression >=
expression
The operators < (less than),
> (greater than),
<= (less than or equal to) and
>= (greater than or equal to) all yield 0 if the specified relation is false and 1 if it is true. The type of the result is
long. The usual arithmetic conversions are performed.
The ^ operator groups left-to-right:
The && operator groups left-to-right. It returns 1 if both its operands are non-zero; otherwise, it returns 0. The
&& operator guarantees left-to-right evaluation. However, it is
not guaranteed that the second operand is not evaluated if the first operand is 0; this is different from the C language. The operands need not have the same type. The result is always a
long.
The || operator groups left-to-right:
It returns 1 if either of its operands is non-zero; otherwise, it returns
0. The
|| operator guarantees left-to-right evaluation. However, it is not guaranteed that the second operand is not evaluated if the first operand is non-zero; this is different from the C language. The operands need not have the same type, and the result is always a
long.
Fboolco compiles a Boolean expression for FML and returns a pointer to an evaluation tree:
Here *expression is a pointer to an expression to be compiled. This function fails if any of the following field types is used:
FLD_PTR,
FLD_FML32, or
FLD_VIEW32. If one of these field types is encountered,
Ferror is set to
FEBADOP.
Fvboolco compiles a Boolean expression for a VIEW and returns a pointer to an evaluation tree:
Here *expression is a pointer to an expression to be compiled, and
*viewname is a pointer to the view name for which the fields are evaluated.
Space is allocated using malloc(3) to hold the evaluation tree. For example, the following code compiles a Boolean expression that checks whether the
FIRSTNAME field is in the buffer, whether it begins with ‘J’ and ends with ‘n’ (such as “John” or “Joan”), and whether the
SEX field is equal to ‘M’.
Use the free(3) function to free the space allocated to an evaluation tree when the Boolean expression will no longer be used. Compiling many Boolean expressions without freeing the evaluation tree when it is no longer needed may cause a program to run out of data space.
Fboolpr prints a compiled expression to the specified file stream. The expression is fully parenthesized, as it was parsed (as indicated by the evaluation tree).
•
|
*tree is a pointer to a Boolean tree previously compiled by Fboolco.
|
•
|
*iop is a pointer of type FILE to an output file stream.
|
Fvboolpr prints a compiled expression to the specified file stream.
•
|
*tree is a pointer to a Boolean tree previously compiled by Fvboolco.
|
•
|
*iop is a pointer of type FILE to an output file stream.
|
•
|
*viewname is the name of the view whose fields are used.
|
Executing Fboolpr on the expression compiled above produces the following results:
•
|
fbfr is the fielded buffer referenced by an evaluation tree produced by Fboolco.
|
•
|
tree is a pointer to an evaluation tree that references the fielded buffer pointed to by fbfr.
|
int
Fvboolev(FBFR *fbfr,char *
tree,char *
viewname)
double
Fvfloatev(FBFR *fbfr,char *
tree,char *
viewname)
Fboolev returns true (1) if the fielded buffer matches the Boolean conditions specified in the evaluation tree. This function does not change either the fielded buffer or the evaluation tree. Using the evaluation tree compiled above, the following code prints “Buffer selected”:
#include <stdio.h>
#include "fml.h"
#include "fldtbl.h"
FBFR *fbfr;
. . .
Fchg(fbfr,FIRSTNAME,0,"John",0);
Fchg(fbfr,SEX,0,"M",0);
if(Fboolev(fbfr,tree) > 0)
fprintf(stderr,"Buffer selected\n");
else
fprintf(stderr,"Buffer not selected\n");
Ffloatev and
Ffloatev32 are similar to
Fboolev, but return the value of the expression as a
double. For example, the following code prints “6.6”:
If Fboolev is used instead of
Ffloatev in the previous example, a 1 is printed.
The Fvstot function transfers data from a C structure to a target record type. The
Fvttos function transfers data from a target record to a C structure.
trecord is a pointer to the target record.
cstruct is a pointer to a C structure.
viewname is a pointer to the name of a compiled view description. The
VIEWDIR and
VIEWFILES environment variables are used to find the directory and file containing the compiled view description.
1.
|
Call Fvftos to convert the FML buffer to a C structure.
|
2.
|
Call Fvstot to convert to a target record.
|
1.
|
Call Fvttos to convert to a C structure.
|
2.
|
Call Fvstof to convert the structure to an FML buffer.
|
dec_t(m, n) <=> S9(2*
m-(
n+1))V9(
n)COMP-3
An alternate character translation table can be used at run time by calling Fcodeset. The
translation_table must point to 512 bytes of binary data. The first 256 bytes of data are interpreted as the ASCII-to-EBCDIC translation table. The second 256 bytes of data are interpreted as the EBCDIC-to-ASCII table. Any data after the 512th byte is ignored. If the pointer is NULL, the default translation is used.