|
|
|
|
|
|
FML Functions
Fintro (3FML)
Name
Fintro-Introduction to FML functions
Synopsis
"#include <fml.h>"
"#include <fml32.h>"
Description
FML is a set of C language functions for defining and manipulating storage structures called fielded buffers, that contain attribute-value pairs called fields. The attribute is the field's identifier, and the associated value represents the field's data content.
Fielded buffers provide an excellent structure for communicating parameterized data between cooperating processes, by providing named access to a set of related fields. Programs that need to communicate with other processes can use the FML software to provide access to fields without concerning themselves with the structures containing them.
FML16 and FML32
There are two "sizes" of FML. The original FML interface is based on 16-bit values for the length of fields and containing information identifying fields. In this introduction, it will be referred to as FML16. FML16 is limited to 8191 unique fields, individual field lengths of up to 64K bytes, and a total fielded buffer size of 64K. The definitions, types, and function prototypes for this interface are in fml.h which must be included in an application program using the FML16 interface; and functions live in -lfml. 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; and functions live in -lfml32. All definitions, types, and function names for FML32 have a "32" suffix (for example, MAXFBLEN32, FLDID32, Fchg32). Also the environment variables are suffixed with "32" (for example, FLDTBLDIR32 and FIELDTBLS32).
FML Buffers
A fielded buffer is composed of field identifier and field value pairs for fixed length fields (for example, long, short), and field identifier, field length, and field value triples for varying length fields.
A field identifier is a tag for an individual data item in a fielded buffer. The field identifier consists of the name of field number and the type of the data in the field. The field number must be in the range 1 to 8191, inclusive, for FML16 and the type definition for a field identifier is FLDID. The field number must be in the range 1 to 33,554,431, inclusive, for FML32 and the type definition for a field identifier is FLDID32. Field numbers 1 to 100 are reserved for system use and should be avoided (although this is not strictly enforced). The field types can be any of the standard C language types: short, long, float, double, and char. Two other types are also supported: string (a series of characters ending with a null character) and carray (character arrays). These types are defined in fml.h and fml32.h as FLD_SHORT, FLD_LONG, FLD_CHAR, FLD_FLOAT, FLD_DOUBLE, FLD_STRING, and FLD_CARRAY.
For FML16, a fielded buffer pointer is of type "FBFR *", a field length has the type FLDLEN, and the number of occurrences of a field has the type FLDOCC. 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.
Fields are referred to by their field identifier in the FML interface. However, it is normally easier for an application programmer to remember a field name. There are two approaches to mapping field names to field identifiers.
Field name/identifier mappings can be made available to FML programs at run-time through field table files, described in field_tables(5). The FML16 interface uses the environment variable FLDTBLDIR to specify a list of directories where field tables can be found, and FIELDTBLS to specify a list of the files in the table directories that are to be used. The FML32 interface uses FLDTBLDIR32 and FIELDTBLS32. Within applications programs, the FML functions Fldid and Fldid32 provide for a run-time translation of a field name to its field identifier and Fname and Fname32 translate a field identifier to its field name.
Compile-time field name/identifier mappings are provided by the use field header files containing macro definitions for the field names. mkfldhdr(1) and mkfldhdr32(1) are provided to make header files out of field table files. These header files are #include'd in C programs, and provide another way to map field names to field identifiers: at compile-time.
Any field in a fielded buffer can occur more than once. Many FML functions take an argument that specifies which occurrence of a field is to be retrieved or modified. If a field occurs more than once, the first occurrence is numbered 0, and additional occurrences are numbered sequentially. The set of all occurrences make up a logical sequence, but no overhead is associated with the occurrence number (that is, it is not stored in the fielded buffer). If another occurrence of a field is added, it is added at the end of the set and is referred to as the next higher occurrence. When an occurrence other than the highest is deleted, all higher occurrences of the field are shifted down by one (for example, occurrence 6 becomes occurrence 5, 5 becomes 4, etc.).
When a fielded buffer has many fields, access is expedited in FML by the use of an internal index. The user is normally unaware of the existence of this index. However, when you store a fielded buffer on disk, or transmit a fielded buffer between processes or between computers, you can save disk space and/or transmittal time by first discarding the index using Funindex or Funindex32, and then reconstructing the index later with Findex or Findex32.
FML16 Conversion to FML32
Existing FML16 applications that are written correctly can easily be changed to use the FML32 interface. All variables used in the calls to the FML functions must use the proper typedefs (FLDID, FLDLEN, and FLDOCC). The application source code can be changed to use the 32-bit functions simply by changing the include of fml.h to inclusion of fml32.h followed by fml1632.h. The fml1632.h contains macros that convert all of the 16-bit type definitions to 32-bit type definitions, and 16-bit functions and macros to 32-bit functions and macros.
Error Handling
Most of the FML functions have one or more error returns. An error condition is indicated by an otherwise impossible returned value. This is usually -1 on error, or 0 for a bad field identifier (BADFLDID) or address. The error type is also made available in the external integer Ferror for FML16 and Ferror32 for FML32. Ferror and Ferror32 are not cleared on successful calls, so they should be tested only after an error has been indicated.
The F_error and F_error32 functions are provided to produce a message on the standard error output. They take one parameter, a string; print the argument string appended with a colon and a blank; and then print an error message followed by a newline character. The error message displayed is the one defined for the error number currently in Ferror or Ferror32, which is set when errors occur.
Fstrerror(3) can be used to retrieve from a message catalog the text of an error message; it returns a pointer that can be used to as an argument to userlog(3).
The error codes that can be produced by an FML function are described on each FML reference page.
See Also
CFadd(3fml), CFchg(3fml), CFfind(3fml), CFfindocc(3fml), CFget(3fml), CFgetalloc(3fml), F_error(3fml), Fadd(3fml), Fadds(3fml), Falloc(3fml), Fboolco(3fml), Fboolev(3fml), Fboolpr(3fml), Fchg(3fml), Fchgs(3fml), Fchksum(3fml), Fcmp(3fml), Fconcat(3fml), Fcpy(3fml), Fdel(3fml), Fdelall(3fml), Fdelete(3fml), Fextread(3fml), Ffind(3fml), Ffindlast(3fml), Ffindocc(3fml), Ffinds(3fml), Ffloatev(3fml), Ffprint(3fml), Ffree(3fml), Fget(3fml), Fgetalloc(3fml), Fgetlast(3fml), Fgets(3fml), Fgetsa(3fml), Fidnm_unload(3fml), Fidxused(3fml), Fielded(3fml), Findex(3fml), Finit(3fml), Fjoin(3fml), Fldid(3fml), Fldno(3fml), Fldtype(3fml), Flen(3fml), Fmkfldid(3fml), Fmove(3fml), Fname(3fml), Fneeded(3fml), Fnext(3fml), Fnmid_unload(3fml), Fnum(3fml), Foccur(3fml), Fojoin(3fml), Fpres(3fml), Fprint(3fml), Fproj(3fml), Fprojcpy(3fml), Fread(3fml), Frealloc(3fml), Frstrindex(3fml), Fsizeof(3fml), Fstrerror(3fml), Ftypcvt(3fml), Ftype(3fml), Funindex(3fml), Funused(3fml), Fupdate(3fml), Fused(3fml), Fvall(3fml), CFadd (3FML) Name CFadd, CFadd32-convert and add field Synopsis#include <stdio.h>
#include "fml.h"
int CFadd(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len, int type)
#include fml32.h>
int
CFadd32(FBFR32 *fbfr, FLDID32 fieldid, char *value, FLDLEN32 len, int type)
Description
CFadd() acts like Fadd() but firstconverts the value from the user-specified type to the type of the fieldid for which the field is added to the fielded buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. value is a pointer to the value to be added. len is the length of the value to be added; it is required only if type is FLD_CARRAY. type is the data type of the field in value.
Before the field is added to the buffer,the type of the data item is converted from type supplied by the user to the type specified in in fieldid. If the source type is FLD_CARRAY (arbitrary character array), the len argument should be set to the length of the array; the length is ignored in all other cases. The value for the field to be converted and added must first be put in a variable, value, since C does not permit constructs such as 12345L.
CFadd32 is used with 32-bit FML.
Return Values
This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, CFadd() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
Allocation of space dynamically using malloc(3) failed when converting from a carray to string.
One of the arguments to the function invoked was invalid, (for example, a NULL value parameter was specified).
A field value is to be added or changed in a field buffer but there is not enough space remaining in the buffer.
A field identifier is specified which is not valid.
A field identifier is specified which is not valid.
See Also
Fintro(3), Fadd(3)
CFchg (3FML)
Name
CFchg, CFchg32-convert and change field
Synopsis
#include <stdio.h>
#include "fml.h"
int CFchg(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *value,
FLDLEN len, int type)
#include "fml32.h"
int CFchg32(FBFR32 *fbfr, FLDID32 fieldid, FLDOCC32 oc,
char *value,
FLDLEN32 len, int type)
Description
CFchg() acts like Fchg() but first converts the value from the user-specified type to the type of the fieldid for which the field is changed in the fielded buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. value is a pointer to a new value. len is the length of the value to be changed; it is required only if type is FLD_CARRAY. type is the data type of value.
If a field occurrence is specified that does not exist, then NULL values are added for the missing occurrences until the desired value can be added (e.g., changing field occurrence 4 for a field that does not exist in a buffer will cause 3 NULL values to be added followed by the specified field value).
CFchg32 is used with 32-bit FML.
Return Values
This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, CFchg() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
[FMALLOC]
Allocation of space dynamically using malloc(3) failed when converting from a carray to string.
One of the arguments to the function invoked was invalid, (for example, a NULL value parameter was specified).
[FNOSPACE]
A field value is to be added or changed in a field buffer but there is not enough space remaining in the buffer.
[FNOTPRES]
A field occurrence is requested but the specified field and/or occurrence was not found in the fielded buffer.
[FBADFLD]
A field identifier is specified which is not valid.
[FTYPERR]
A field identifier is specified which is not valid.
See Also
Fintro(3), CFadd(3), Fchg(3)
CFfind (3FML)
Name
CFfind, CFfind32-find, convert and return pointer
Synopsis
#include <stdio.h>
#include "fml.h"
char * CFfind(FBFR *fbfr, FLDID fieldid, FLDOCC oc, FLDLEN *len,
int type)
#include "fml32.h"
char *
CFfind32(FBFR32 *fbfr, FLDID32 fieldid, FLDOCC32 oc, FLDLEN32 *len, int type)
Description
CFfind() finds a specified field in a buffer, converts it and returns a pointer to the converted value. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. len is used on output and is a pointer to the length of the converted value. type is the data type the user wants the field to be converted to.
Like Ffind(3), the pointer returned by the function should be considered read only. The validity of the pointer returned by CFfind() is guaranteed only until the next buffer operation, even if that operation is non-destructive, since the converted value is retained in a single private buffer. This differs from the value returned by Ffind(3), which is guaranteed until the next modification of the buffer. Unlike Ffind(3), CFfind() aligns the converted value for immediate use by the caller.
CFfind32 is used with 32-bit FML.
Return Values
In the SYNOPSIS section above the return value to CFfind() is described as a character pointer data type (char ** in C). Actually, the pointer returned points to an object that has the same type as the stored type of the field.
This function returns NULL on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, CFfind() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
[FNOTFLD]
The buffer is not a fielded buffer or has not been initialized by Finit().
Allocation of space dynamically using malloc(3) failed when converting from a carray to string.
A field occurrence is requested but the specified field and/or occurrence was not found in the fielded buffer.
A field identifier is specified which is not valid.
A field identifier is specified which is not valid.
See Also
Fintro(3), Ffind(3)
CFfindocc (3FML)
Name
CFfindocc, CFfindocc32-find occurrence of converted value
Synopsis
#include <stdio.h>
#include "fml.h"
FLDOCC
CFfindocc(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len, int
type)
#include "fml32.h"
FLDOCC32
CFfindocc32(FBFR32 *fbfr, FLDID32 fieldid, char *value, FLDLEN32
len, int type)
Description
CFfindocc() acts like Ffindocc() but first converts the value from the user-specified type to the type of fieldid. CFfindocc() looks for an occurrence of the specified field in the buffer that matches a user-supplied value, length and type. CFfindocc() returns the occurrence number of the first field that matches. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. value is a pointer to the value being sought. len is the length of the value to be compared to input value if type is carray. type is the data type of the field in value.
CFfindocc32 is used with 32-bit FML.
Return Values
If the field value is not found or if other errors are detected, -1 is returned and CFfindocc() sets Ferror to indicate the error condition.
Errors
Under the following conditions, CFfindocc() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
Allocation of space dynamically using malloc(3) failed when converting from a carray to string.
One of the arguments to the function invoked was invalid, (for example, a NULL value parameter was specified).
A field occurrence is requested but the specified field and/or occurrence was not found in the fielded buffer.
A field identifier is specified which is not valid.
A field identifier is specified which is not valid.
See Also
Fintro(3), Ffindocc(3)
CFget (3FML)
Name
CFget, CFget32-get field and convert
Synopsis
#include <stdio.h>
#include "fml.h"
int
CFget(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *buf, FLDLEN *len,
int type)
#include "fml32.h"
int
CFget32(FBFR32 *fbfr, FLDID32 fieldid, FLDOCC32 oc, char *buf,
FLDLEN32 *len, int type)
Description
CFget() is the conversion analog of Fget(3). The main difference is that it copies a converted value to the user supplied buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. buf is a pointer to private data area. On input, len is a pointer to the length of the private data area. On return, len is a pointer to the length of the returned value. If the len parameter is NULL on input, it is assumed that the buffer is big enough to contain the field value and the length of the value is not returned. If the buf parameter is NULL, the field value is not returned. type is the data type the user wants the returned value converted to.
CFget32 is used with 32-bit FML.
Return Values
This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, CFget() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
Allocation of space dynamically using malloc(3) failed when converting from a carray to string.
The size of the data area, as specified in len, is not large enough to hold the field value.
A field occurrence is requested but the specified field and/or occurrence was not found in the fielded buffer.
A field identifier is specified which is not valid.
A field identifier is specified which is not valid.
See Also
Fintro(3), Fget(3)
CFgetalloc (3FML)
Name
CFgetalloc, CFgetalloc32-get field, space, convert
Synopsis
#include <stdio.h>
#include "fml.h"
char *
CFgetalloc(FBFR *fbfr, FLDID fieldid, FLDOCC oc, int type, FLDLEN
*extralen)
#include "fml32.h"
char *
CFgetalloc32(FBFR32 *fbfr, FLDID32 fieldid, FLDOCC32 oc, int type,
FLDLEN32 *extralen)
Description
CFgetalloc() gets a specified field from a buffer, allocates space, converts the field to the type specified by the user and returns a pointer to its location. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. type is the data type the user wants the field to be converted to. On call, extralen is a pointer to the length of additional space that may be allocated to receive the value; on return, it is a pointer actual amount of space used. If extralen is NULL, then no additional space is allocated and the actual length is not returned. The user is responsible for freeing the returned (converted) value.
CFgetalloc32 is used with 32-bit FML.
Return Values
On success, CFgetalloc() returns a pointer to the converted value. On error, the function returns NULL and sets Ferror to indicate the error condition.
Errors
Under the following conditions, CFgetalloc() fails and sets Ferror to:
"fielded buffer not aligned"
The buffer does not begin on the proper boundary.
"buffer not fielded"
The buffer is not a fielded buffer or has not been initialized by Finit().
"malloc failed"
Allocation of space dynamically using malloc(3) failed.
"field not present"
A field occurrence is requested but the specified field and/or occurrence was not found in the fielded buffer.
"unknown field number or type"
A field identifier is specified which is not valid.
"invalid field type"
A field identifier is specified which is not valid.
See Also
Fintro(3), Fgetalloc(3)
F_error (3FML)
Name
F_error, F_error32-print error message for last error
Synopsis
#include stdio.h>
#include "fml.h"
extern int Ferror;
void
F_error(char *msg)
#include "fml32.h"
extern int Ferror32;
void
F_error32(char *msg)
Description
The function F_error() works like perror(3) for UNIX System errors; that is, it produces a message on the standard error output (file descriptor 2), describing the last error encountered during a call to a system or library function. The argument string msg is printed first, then a colon and a blank, then the message and a newline. If msg is a null pointer or points to a null string, the colon is not printed. To be of most use, the argument string should include the name of the program that incurred the error. The error number is taken from the external variable Ferror, which is set when errors occur but not cleared when non-erroneous calls are made. In the MS-DOS and OS/2 environments, Ferror is redefined to FMLerror.
To immediately print an error message, F_error() should be called on an error return from another FML function. When the error message is FEUNIX. Uunix_err(3) is called.
F_error32 is used with 32-bit FML.
Return Values
F_error() is declared a void and as such does not have return values.
See Also
Fintro(3), perror(3) in a UNIX System reference manual
Uunix_err(3)
Fadd (3FML)
Name
Fadd, Fadd32-add new field occurrence
Synopsis
#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)
Description
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(3) 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_CARRAY, the length of the value is given in the len argument.For all types other than FLD_CARRAY, the length of the object pointed to by value is inferred from its type (e.g. 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.
Return Values
This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fadd() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
A field value is to be added in a fielded buffer but there is not enough space remaining in the buffer.
A field number is specified which is not valid.
See Also
Fintro(3fml)
CFadd(3fml)
Fadds(3fml)
Fchg(3fml)
Fadds (3FML)
Name
Fadds, Fadds32-convert value from type FLD_STRING and add to buffer
Synopsis
#include <stdio.h>
#include "fml.h"
int
Fadds(FBFR *fbfr, FLDID fieldid, char *value)
#include "fml32.h"
int
Fadds32(FBFR32 *fbfr, FLDID32 fieldid, char *value)
Description
Fadds() has been provided to handle the case of conversion from a user type of FLD_STRING to the field type of fieldid and add it to the fielded buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. value is a pointer to the value to be added.
This function calls CFadd providing a type of FLD_STRING, and a len of 0.
Fadds32 is used with 32-bit FML.
Return Values
This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
A field value is to be added in a fielded buffer but there is not enough space remaining in the buffer.
A field type is specified which is not valid.
One of the arguments to the function invoked was invalid, (for example, specifying a NULL value parameter to Fadds)
Allocation of space dynamically using malloc(3) failed during conversion of carray to string.
A field identifier is specified which is not valid.
See Also
Fintro(3), Fchgs(3), Fgets(3), Fgetsa(3), Ffinds(3), CFchg(3), CFget(3), CFget(3), CFfind(3)
Falloc (3FML)
Name
Falloc, Falloc32-allocate and initialize fielded buffer
Synopsis
#include <stdio.h>
#include "fml.h"
FBFR *
Falloc(FLDOCC F, FLDLEN V)
#include "fml32.h"
FBFR32 *
Falloc32(FLDOCC32 F, FLDLEN32 V)
Description
Falloc() dynamically allocates space using malloc(3) for a fielded buffer and calls Finit() to initialize it. The parameters are the number of fields, F, and the number of bytes of value space, V, for all fields that are to be stored in the buffer.
Falloc32 is used for larger buffers with more fields.
Return Values
This function returns NULL on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Falloc() fails and sets Ferror to:
Allocation of space dynamically using malloc(3) failed.
One of the arguments to the function invoked was invalid, (for example, number of fields is less than 0, V is 0 or total size is greater than 65534).
See Also
Fintro(3), Ffree(3), Fielded(3), Finit(3), Fneeded(3), Frealloc(3), Fsizeof(3), Funused(3), malloc(3)
Fappend (3FML)
Name
Fappend, Fappend32-append new field occurrence
Synopsis
#include <stdio.h>
#include "fml.h"
int
Fappend(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len)
#include "fml32.h"
int
Fappend32(FBFR32 *fbfr, FLDID32 fieldid, char *value, FLDLEN32 len)
Description
Fappend() adds the specified field value to the end of thegiven buffer. Fappend() is useful in building large buffers in that it does not maintain the internal structures and ordering necessary for general purpose FML access. The side effect of this optimization is that a call to Fappend() may be followed only by additional calls to Fappend(), calls to the FML indexing routines Findex(3) and Funindex(3), or calls to Free(3), Fused(3), Funused(3) and Fsizeof(3). Calls to other FML routines made before calling Findex(3) or Funindex(3) will result in an error with Ferror set to FNOTFLD.
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 toby 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(3) must be used).
In the SYNOPSIS section abovethe value argument to Fappend() is described as a character pointer data type (char * in C). Technically, this describes only one particular kind of value passable to Fappend(). 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 Fappend() 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_CARRAY,the length of the value is given in the len argument. For all types other than FLD_CARRAY, the length of the object pointed to by value is inferred from its type (e.g. a value of type FLD_FLOAT is of length sizeof(float)), and the contents of len are ignored.
Fappend32 is used with 32-bit FML.
Return Values
This function returns -1 on error and sets Ferrorto indicate the error condition.
Errors
Under the following conditions, Fappend() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
One of the arguments to the function invoked was invalid. (for example, specifying a NULL value parameter to Fappend)
A field value is to be added in a fielded buffer but there is not enough space remaining in the buffer.
A field number is specified which is not valid.
See Also
Fintro(3), Fadd(3, Ffree(3), Findex(3), Fsizeof(3), Funindex(3), Funused(3), Fused(3)
Fboolco (3FML)
Name
Fboolco, Fboolco32-compile expression, return evaluation tree
Synopsis
#include <stdio.h>
#include "fml.h"
char *
Fboolco(char *expression)
#include "fml32.h"
char *
Fboolco32(char *expression)
Description
Fboolco() compiles a Boolean expression, pointed to by expression, and returns a pointer to the evaluation tree. The expressions recognized are close to the expressions recognized in C. A description of the grammer can be found in the FML Programmer's Guide.
The evaluation tree produced by Fboolco() is used by the other boolean functions listed under SEE ALSO; this avoids having to recompile the expression.
Fboolco32 is used with 32-bit FML.
These functions are not supported on Workstation platforms.
Return Values
This function returns NULL on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fboolco() fails and sets Ferror to:
Allocation of space dynamically using malloc(3) failed.
A syntax error was found in a Boolean expression by Fboolco() other than an unrecognized field name.
A field name is specified which cannot be found in the field tables.
One of the arguments to the function invoked was invalid, (for example, expression is NULL).
Example
#include "stdio.h"
#include "fml.h"
extern char *Fboolco();
char *tree;
...
if((tree=Fboolco("FIRSTNAME %% 'J.*n' & SEX = 'M'")) == NULL)
F_error("pgm_name");
compiles a boolean expression that checks if the FIRSTNAME field is in the buffer, begins with 'J' and ends with 'n' (for example, John, Jean, Jurgen, etc.) and the SEX field equal to 'M'.
The first and second characters of the tree array form the least significant byte and the most significant byte, respectively, of an unsigned 16 bit quantity that gives the length, in bytes, of the entire array. This value is useful for copying or otherwise manipulating the array.
See Also
Fboolev(3), Fboolpr(3), Fldid(3)
Fboolev (3FML)
Name
Fboolev, Fboolev32-evaluate buffer against tree
Synopsis
#include stdio.h>
#include "fml.h"
int
Fboolev(FBFR *fbfr, char *tree)
#include "fml32.h"
int
Fboolev32(FBFR32 *fbfr, char *tree)
Description
Fboolev() takes a pointer to a fielded buffer, fbfr, and a pointer to the evaluation tree returned from Fboolco(), tree, and returns true (1) if the fielded buffer matches the specified Boolean conditions and false (0) if it does not. This function does not change either the fielded buffer or evaluation tree. The evaluation tree is one previously compiled by Fboolco(3).
Fboolev32 is used with 32-bit FML.
These functions are not supported on Workstation platforms.
Return Values
Fboolev() returns 1 if the expression in the buffer matches the evaluation tree. It returns 0 if the expression fails to match the evaluation tree. This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fboolev() fails and sets Ferror to:
The fbfr buffer does not begin on the proper boundary.
The fbfr buffer is not a fielded buffer or has not been initialized by Finit().
Allocation of space dynamically using malloc(3) failed.
One of the arguments to the function invoked was invalid, (for example, specifying a NULL tree parameter).
A syntax error was found in a Boolean expression other than an unrecognized field name.
Example
Using the evaluation tree compiled in the example for Fboolco(3):
#include stdio.h>
#include "fml.h"
#include "fld.tbl.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");
would print "Buffer selected".
See Also
Fintro(3), Fboolco(3), Fboolpr(3)
Fboolpr (3FML)
NAME
Fboolpr, Fboolpr32-print Boolean expression as parsed
Synopsis
#include <stdio.h>
#include "fml.h"
void
Fboolpr(char *tree, FILE *iop)
#include "fml32.h"
void
Fboolpr32(char *tree, FILE *iop)
Description
Fboolpr() prints a compiled expression to the specified output stream. The evaluation tree, tree, is one previously created with Fboolco(3). iop is a pointer of type FILE to the output stream. The output is fully parenthesized, as it was parsed (as indicated by the evaluation tree). The function is useful for debugging.
Fboolpr32 is used with 32-bit FML.
These functions are not supported on Workstation platforms.
Return Values
Fboolpr() is declared as returning a void, so there are no return values.
See Also
Fintro(3), Fboolco(3)
Fchg (3FML)
Name
Fchg, Fchg32-change field occurrence value
Synopsis
#include <stdio.h>
#include "fml.h"
int
Fchg(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *value, FLDLEN len)
#include "fml32.h"
int
Fchg32(FBFR32 *fbfr, FLDID32 fieldid, FLDOCC32 oc, char *value,
FLDLEN32 len)
Description
Fchg() changes the value of a field in the buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. value is a pointer to a new value, its type must be the same type as the value to be changed (see below). len is the length of the value to be changed; it is required only if field type is FLD_CARRAY.
If an occurrence of -1 is specified, then the field value is added as a new occurrence to the buffer. If the specified field occurrence is found, then the field value is modified to the value specified. If a field occurrence is specified that does not exist, then NULL values are added for the missing occurrences until the desired occurrence can be added (for example, changing field occurrence 4 for a field that does not exist on a buffer will cause 3 NULL values to be added followed by the specified field value). NULL values consist of the NULL string (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 and its length is given in len if it is a character array (ignored in other cases). If value is NULL, then the field occurrence is deleted. A value to be deleted that is not found, is considered an error.
In the SYNOPSIS section above the value argument to Fchg() is described as a character pointer data type (char * in C). Technically, this describes only one particular kind of value passable to Fchg(). 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 changed. 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 Fchg() assumes that the object pointed to by value has the same type as the stored type of the field being changed.
Fchg32 is used with 32-bit FML.
Return Values
This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fchg() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
[FNOTFLD]
The buffer is not a fielded buffer or has not been initialized by Finit().
[FNOTPRES]
A field occurrence is requested for deletion but the specified field and/or occurrence was not found in the fielded buffer.
[FNOSPACE]
A field value is to be added or changed in a fielded buffer but there is not enough space remaining in the buffer.
A field identifier is specified which is not valid.
See Also
CFchg(3c)
Fintro(3fml)
Fadd(3fml)
Fcmp(3fml)
Fdel(3fml)
Fchgs (3FML)
Name
Fchgs, Fchgs32-change field occurrence - caller presents string
Synopsis
#include <stdio.h>
#include "fml.h"
int
Fchgs(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *value)
#include "fml32.h"
int
Fchgs32(FBFR32 *fbfr, FLDID32 fieldid, int oc, char *value)
Description
Fchgs(), is provided to handle the case of conversion from a user type of FLD_STRING. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. value is a pointer to the string to be added. The function calls its non-string-function counterpart, CFchg(3), providing a type of FLD_STRING, and a len of 0 to convert from a string to the field type of fieldid.
Fchgs32 is used with 32-bit FML.
Return Values
This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fchgs() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
A field value is to be added or changed in a fielded buffer but there is not enough space remaining in the buffer.
A field identifier is specified which is not valid.
A field identifier is specified which is not valid.
See Also
Fintro(3), Fchg(3), CFchg(3)
Fchksum (3FML)
Name
Fchksum, Fchksum32-compute checksum for fielded buffer
Synopsis
#include <stdio.h>
#include "fml.h"
long
Fchksum(FBFR *fbfr)
#include "fml32.h"
long
Fchksum32(FBFR32 *fbfr)
Description
For extra-reliable I/O, a checksum may be calculated using Fchksum() and stored in a fielded buffer being written out. fbfr is a pointer to a fielded buffer. The stored checksum may be inspected by the receiving process to verify that the entire buffer was received.
Fchksum32 is used with 32-bit FML.
Return Values
On success, Fchksum returns the checksum. This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fchksum() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
See Also
Fintro(3), Fread(3), Fwrite(3)
Fcmp (3FML)
Name
Fcmp, Fcmp32-compare two fielded buffers
Synopsis
#include <stdio.h>
#include "fml.h"
int
Fcmp(FBFR *fbfr1, FBFR *fbfr2)
#include "fml32.h"
int
Fcmp32(FBFR32 *fbfr1, FBFR32 *fbfr2)
Description
Fcmp() compares the field identifiers and then the field values of two FML buffers. fbfr1 and fbfr2 are pointers to the fielded buffers to be compared.
Fcmp32 is used with 32-bit FML.
Return Values
The function returns a 0 if the two buffers are identical. It returns a -1 on any of the following conditions:
Fcmp(\|) returns a 1 if any of the reverse set of conditions is true, for example, the fieldid of a fbfr1 field is greater than the fieldid of the corresponding field of fbfr2. The actual sizes of the buffers (that is, the sizes passed to Falloc()) are not considered; only the data in the buffers. This function returns \-2 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fcmp() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
See Also
Fintro(3), Fadd(3), Fchg(3)
Fconcat (3FML)
Name
Fconcat, Fconcat32-concatenate source to destination buffer
Synopsis
#include <stdio.h>
#include "fml.h"
int
Fconcat(FBFR *dest, FBFR *src)
#include "fml32.h"
int
Fconcat32(FBFR32 *dest, FBFR32 *src)
Description
Fconcat() adds fields from the source buffer to the fields that already exist in the destination buffer. dest and src are pointers to the destination and source fielded buffers, respectively. 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.
Fconcat32 is used with 32-bit FML.
Return Values
This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fconcat() fails and sets Ferror to:
Either the source buffer or the destination buffer does not begin on the proper boundary.
Either the source or the destination buffer is not a fielded buffer or has not been initialized by Finit().
A field value is to be added in a fielded buffer but there is not enough space remaining in the buffer.
See Also
Fintro(3), Fjoin(3), Fupdate(3)
Fcpy (3FML)
Name
Fcpy, Fcpy32-copy source to destination buffer
Synopsis
#include <stdio.h>
#include "fml.h"
int
Fcpy(FBFR *dest, FBFR *src)
#include "fml32.h"
int
Fcpy32(FBFR32 *dest, FBFR32 *src)
Description
Fcpy() is used to copy the contents of one fielded buffer to another fielded buffer. dest and src are pointers to the destination and source fielded buffers respectively. Fcpy() expects the destination to be a fielded buffer, and thus can check that it is large enough to accommodate the data from the source buffer.
Fcpy32 is used with 32-bit FML.
Return Values
This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fcpy() fails and sets Ferror to:
"fielded buffer not aligned"
Either the source buffer or the destination buffer does not begin on the proper boundary.
"buffer not fielded"
Either the source or the destination buffer is not a fielded buffer or has not been initialized by Finit().
"no space in fielded buffer"
The destination buffer is not large enough to hold the source buffer.
See Also
Fintro(3), Fmove(3)
Fdel (3FML)
Name
Fdel, Fdel32-delete field occurrence from buffer
Synopsis
#include stdio.h>
#include "fml.h"
int
Fdel(FBFR *fbfr, FLDID fieldid, FLDOCC oc)
#include "fml32.h"
int
Fdel32(FBFR32 *fbfr, FLDID32 fieldid, FLDOCC32 oc)
Description
Fdel() deletes the specified field occurrence from the buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field.
Note that when multiple occurrences of a field exist in the fielded buffer and a field occurrence is deleted that is not the last occurrence, also higher occurrences in the buffer are shifted down by one. To maintain the same occurrence number for all occurrences, use Fchg(3) to set the field occurrence value to a "null" value.
Fdel32 is used with 32-bit FML.
Return Values
This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fdel() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
A field occurrence is requested but the specified field and/or occurrence was not found in the fielded buffer.
A field identifier is specified which is not valid.
See Also
Fintro(3), Fadd(3), Fchg(3), Fdelall(3), Fdelete(3)
Fdelall (3FML)
Name
Fdelall, Fdelall32-delete all field occurrences from buffer
Synopsis
#include <stdio.h>
#include "fml.h"
int
Fdelall(FBFR *fbfr, FLDID fieldid)
#include "fml32.h"
int
Fdelall32(FBFR32 *fbfr, FLDID32 fieldid)
Description
Fdelall() deletes all occurrences of the specified field in the buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. If no occurrences of the field are found, it is considered an error.
Fdelall32 is used with 32-bit FML.
Return Values
This function returns -1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fdelall() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
A field is requested but the specified field was not found in the fielded buffer.
A field identifier is specified which is not valid.
See Also
Fintro(3), Fdel(3), Fdelete(3)
Fdelete (3FML)
Name
Fdelete, Fdelete32-delete list of fields from buffer
Synopsis
#include <stdio.h>
#include "fml.h"
int
Fdelete(FBFR *fbfr, FLDID *fieldid)
#include "fml32.h"
int
Fdelete32(FBFR32 *fbfr, FLDID32 *fieldid)
Description
Fdelete() deletes all occurrences of all fields listed in the array of field identifiers, fieldid[]. The last entry in the array must be BADFLDID. fbfr is a pointer to a fielded buffer. fieldid is a pointer to an array of field identifiers. This is a more efficient way of deleting several fields from a buffer instead of using several Fdelall() calls. The update is done in-place. The array of field identifiers may be re-arranged by Fdelete() (they are sorted, if not already, in numeric order).
Fdelete() returns success even if no fields are deleted from the fielded buffer.
Fdelete32 is used with 32-bit FML.
Return Values
This function returns \-1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fdelete() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
A field identifier is specified which is not valid.
See Also
Fintro(3), Fdel(3), Fdelall(3)
Fextread (3FML)
Name
Fextread, Fextread32-build fielded buffer from printed format
Synopsis
#include <stdio.h>
#include "fml.h"
int
Fextread(FBFR *fbfr, FILE *iop)
#include "fml32.h"
int
Fextread32(FBFR32 *fbfr, FILE *iop)
Description
Fextread() may be used to construct a fielded buffer from its printed format (that is, from the output of Fprint(3)). The parameters are a pointer to a fielded buffer, fbfr, and a pointer to a file stream, iop. The input file format is basically the same as the output format of Fprint(3), that is:
[flag] fldname or fldid tab> fldval (or fldname, if flag is \Q\Q='')
The optional flags and their meanings are as follows:
If no flag is specified, a new occurrence of the field named by fldname with value fldval is added to the fielded buffer. A trailing newline (-) must be provided following each completed input buffer.
Fextread32 is used with 32-bit FML.
Return Values
This function returns \-1 on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Fextread() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
A field value is to be added or changed in a field buffer but there is not enough space remaining in the buffer.
A field number is specified which is not valid.
A UNIX system call error occurred. The external integer errno should have been set to indicate the error by the system call, and the external integer Uunixerr (values defined in Uunix.h) is set to the system call that returned the error.
A field name is specified which cannot be found in the field tables.
A syntax error was found in the external buffer format. Possible errors are: an unexpected end-of-file indicator, input lines not in the form fieldid or name tab> value two control characters, field values greater than 1000 characters, or an invalid hex escape sequence.
A field to be deleted is not found in the fielded buffer.
Allocation of space dynamically using malloc(3) failed.
The value of iop is NULL.
See Also
Fintro(3), Fprint(3)
Ffind (3FML)
Name
Ffind, Ffind32-find field occurrence in buffer
Synopsis
#include <stdio.h>
#include "fml.h"
char *
Ffind(FBFR *fbfr, FLDID fieldid, FLDOCC oc, FLDLEN *len)
#include "fml32.h"
char *
Ffind32(FBFR32 *fbfr, FLDID32 fieldid, FLDOCC32 oc, FLDLEN32 *len)
Description
Ffind() finds the value of the specified field occurrence in the buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. If the field is found, its length is set into *len, and its location is returned as the value of the function. If the value of len is NULL, then the field length is not returned. Ffind() is useful for gaining read-only access to a field. In no case should the value returned by Ffind() be used to modify the buffer.
In general, the locations of values of types FLD_LONG, FLD_FLOAT, and FLD_DOUBLE are not suitable for direct use as their stored type, since proper alignment within the buffer is not guaranteed. Such values must be copied first to a suitably aligned memory location. Accessing such fields through the conversion function CFfind(3) does guarantee the proper alignment of the found converted value. Buffer modification should only be done by the functions Fadd(3) or Fchg(3). The values returned by Ffind() and Ffindlast() are valid only so long as the buffer remains unmodified.
Ffind32 is used with 32-bit FML.
Return Values
In the SYNOPSIS section above the return value to Ffind() is described as a character pointer data type (char * in C). Actually, the pointer returned points to an object that has the same type as the stored type of the field.
This function returns a pointer to NULL on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Ffind() fails and sets Ferror to:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
A field occurrence is requested but the specified field and/or occurrence was not found in the fielded buffer.
[FBADFLD]
A field identifier is specified which is not valid.
See Also
Fintro(3fml), Ffindlast(3fml), Ffindocc(3fml), Ffinds(3fml)
Ffindlast (3FML)
Name
Ffindlast, Ffindlast32-find last occurrence of field in buffer
Synopsis
#include <stdio.h>
#include "fml.h"
char *
Ffindlast(FBFR *fbfr, FLDID fieldid, FLDOCC *oc, FLDLEN *len) #include "fml32.h"
char *
Ffindlast32(FBFR32 *fbfr, FLDID32 fieldid, FLDOCC32 *oc, FLDLEN32 *len)
Description
Ffindlast() finds the last occurrence of a field in a buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is a pointer to an integer that is used to receive the occurrence number of the field. len is the length of the value. If there are no occurrences of the field in the buffer, NULL is returned. Generally, Ffindlast() acts like Ffind(3). The major difference is that with Ffindlast the user does not supply a field occurrence. Instead, both the value and occurrence number of the last occurrence of the field are returned. In order to return the occurrence number of the last field, the occurrence argument, oc, to Ffindlast() is a pointer-to-integer, and not an integer, as it is to Ffind(). If oc is specified to be NULL, the occurrence number of the last occurrence is not returned. If the value of len is NULL, then the field length is not returned.
In general, the locations of values of types FLD_LONG, FLD_FLOAT, and FLD_DOUBLE are not suitable for direct use as their stored type, since proper alignment within the buffer is not guaranteed. Such values must be copied first to a suitably aligned memory location. Accessing such fields through the conversion function CFfind(3) does guarantee