To simplify the specification of parameters for FML functions, a convention has been adopted for the sequence of those parameters. FML parameters appear in the following sequence.
- 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).
- For I/O functions, a pointer to a stream follows the fielded buffer pointer.
- For functions that need one, a field identifier (type FLDID) appears next (in the
case of Fnext, it is a pointer to a field identifier).
- For functions that need a field occurrence (type FLDOCC), this parameter comes
next. (For Fnext, it is a pointer to an occurrence number.)
- In functions in which a field value is passed to or from the function, a pointer to
the beginning of the field value is given next. (It is defined as a character pointer
but may be cast from any other pointer type.)
- When a field value is passed to a function that contains a character array
(carray) field, you must specify its length as the next parameter (type FLDLEN).
For functions that retrieve a field value, a pointer to the length of the retrieval
buffer must be passed to the function and this length parameter is set to the length
of the value retrieved.
- A few functions require special parameters and differ from the preceding
conventions. These special parameters appear after the above parameters. They
are discussed in the descriptions of individual functions.
- The following NULL values are defined for the various field types:
- 0 for short and long
- 0.0 for float and double
- \0 for string (1 byte in length)
- A zero-length string for carray