PURPOSE

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.

FML also provides a facility called VIEWS that allows you to map fielded buffers to C structures (and the reverse as well). VIEWS lets you perform lengthy manipulations of data in structures rather than in fielded buffers; applications will run faster if data is transferred to structures for manipulation. VIEWS allows the data independence of fielded buffers to be combined with the efficiency and simplicity of classic record structures.

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 manual page, 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 (e.g., MAXFBLEN32, FLDID32, Fchg32()). Also the environment variables are suffixed with "32" (e.g., FLDTBLDIR32, FIELDTBLS32, VIEWFILES32, and VIEWDIR32).

FML Buffers

A fielded buffer is composed of field identifier and field value pairs for fixed length fields (e.g., 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(3) and Fldid32(3) provide for a run-time translation of a field name to its field identifier and Fname(3) and Fname32(3) 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(3) or Funindex32(3), and then reconstructing the index later with Findex(3) or Findex32(3).

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). Any call to tpalloc for an FML typed buffer should use the FMLTYPE definition instead of "FML". 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.

VIEWS

VIEWS is a part of the Field Manipulation Language that allows the exchange of data between fielded buffers and C structures in a C language program, by specifying mappings of fields to members of C structures. If extensive manipulations of fielded buffer information are to be done, transferring the data to C structures will improve performance. Information in a fielded buffer can be extracted from the fields in a buffer and placed in a C structure using VIEWS functions, manipulated, and the updated values returned to the buffer, again using VIEWS functions.

Typed buffers is a feature of TUXEDO System/T that grew out of the FML idea of a fielded buffer. Two of the standard buffer types delivered with System/T are FML typed buffers and VIEW typed buffers. An additional difference of System/T VIEW buffers is that they can be totally unrelated to an FML fielded buffer. The buffer types FML32 and VIEW32 can also be used.

A view description is created and stored in a source viewfile, as described in viewfile(5). The view description maps fields in fielded buffers to members in C structures. The source view descriptions are compiled, using viewc(1) or viewc32(1), creating a view object file and can then be used to map data transferred between fielded buffers and C structures in a C program. The view compiler also creates C header files that can be included in applications programs to define the structures described in view descriptions. A view disassembler, viewdis(1) or viewdis32(1), is provided to translate object view descriptions into readable form (that is, back into source view descriptions); the output of the disassembler can be re-input to the view compiler

The object files are used at run-time to manipulate the VIEW structures using the VIEWFILES and VIEWDIR environment variables. VIEWFILES should contain a comma separated list of object viewfiles 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 the VIEWDIR variable (see below). VIEWDIR specifies a colon separated list of directories to be used to find view object files with relative file names. For VIEW32 structures, VIEWFILES32 and VIEWDIR32 are used.

In addition to the data types supported by most FML functions, VIEWS supports type int in source view descriptions. When the view description is compiled the view compiler automatically converts any int types to either short or long types, depending on your machine.

A decimal data type is also supported in VIEWS. It is defined as a field of type "dec_t", and the size of the packed decimal value is given as the total number of bytes and the bytes to the right of the decimal point. While this field is not supported directly in FML, conversion of this field is automatic to/from any other field type supported in FML. Packed decimals exist in the COBOL environment as two decimal digits packed into one byte with the low-order half byte used to store the sign. In the C environment, the data type is defined by the dec_t type definition, which contains the decimal exponent, sign, digits, and the packed decimal value.

An FML buffer can be converted to a view using Fvftos(3) or Fvftos32(3). A VIEW can be converted to a fielded buffer using Fvstof(3) or Fvstof32(3). When transferring data between fielded buffers and structures, the source data is automatically converted to the type of the destination data. Multiple field occurrences are supported; they are treated as an array in the structure. Null values are used to indicate empty members in a structure, and can be specified by the user for each structure member in a viewfile. If the user does not specify a null value for a member, default null values are used. It is also possible to inhibit the transfer of data between a C structure member and a field in a fielded buffer, even though a mapping exists between them.

A VIEW can also be converted to and from a target record format. The default target format is IBM System/370 COBOL records. The Fvstot(3) function takes care of converting byte ordering, floating point and decimal format, and character sets (ASCII to EBCDIC), and Fvttos(3) converts back to the native format. 32-bit versions of these functions also exist. The Fcodeset(3) function can be used to specify alternate ASCII/EBCDIC transaction tables.

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(3fml) and its counterpart, Fstrerror32(3fml), can be used to retrieve the text of an error messagefrom a message catalog; it returns a pointer that can be used to as an argument to userlog(3c).

The error codes that can be produced by an FML function are described on each FML manual page.