Introduction to FML Functions


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Doc Home \| Reference \| Topic List \| Previous \| Next \| Contents

BEA Tuxedo FML Function Reference

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 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, FIELDTBLS32, VIEWFILES32, and VIEWDIR32).

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. The BEA Tuxedo system conforms to the following conventions for field numbers.

FML16 Field Numbers
FML32 Field Numbers

Reserved
Available
Reserved
Available

1-100

101-8191

1-10,000,
30,000,001-33,554,431

10,001-30,000,000

FML16 Field Numbers	FML32 Field Numbers
Reserved	Available	Reserved	Available
1-100	101-8191	1-10,000, 30,000,001-33,554,431	10,001-30,000,000

Applications should avoid using the reserved field numbers, although the BEA Tuxedo system does not strictly enforce applications from using them.

The field types can be any of the standard C language types: short, long, float, double, and char. The following types are also supported: string (a series of characters ending with a null character), carray (character arrays), pointer (a pointer to a buffer), FML32 buffer (an embedded FML32 buffer), and VIEW32 (an embedded VIEW32 buffer). These types are defined in fml.h and fml32.h as FLD_SHORT, FLD_LONG, FLD_CHAR, FLD_FLOAT, FLD_DOUBLE, FLD_STRING, FLD_CARRAY, FLD_PTR, FLD_FML32, and FLD_VIEW32.

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() and mkfldhdr32() are provided to make header files out of field table files (see mkfldhdr, mkfldhdr32(1) for details). 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). 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 BEA Tuxedo that grew out of the FML idea of a fielded buffer. Two of the standard buffer types delivered with BEA Tuxedo are FML typed buffers and VIEW typed buffers. An additional difference of BEA Tuxedo 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() or viewc32(), creating a view object file and can then be used to map data transferred between fielded buffers and C structures in a C program (see viewc, viewc32(1)for details). 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() or viewdis32(), 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 (see viewdis, viewdis32(1) for details).

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 (as described later in this section). 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() or Fvftos32(). A VIEW can be converted to a fielded buffer using Fvstof() or Fvstof32(). 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() function takes care of converting byte ordering, floating point and decimal format, and character sets (ASCII to EBCDIC), and Fvttos() converts back to the native format. 32-bit versions of these functions also exist. The Fcodeset() 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() 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(3c).

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