Here the data type of the field named empid is declared to be a long integer,
name and
addr are declared to be character arrays of 20 and 40 characters respectively, and
gender is declared to be a single character, presumably with a range of
m or
f.
In the header file that is included (with #include) whenever FML functions are used (
fml.h or
fml32.h), field identifiers are defined (with
typedef) as
FLDID (or
FLDID32 for FML32), field value lengths as
FLDLEN (
FLDLEN32 for FML32), and field occurrence numbers as
FLDOCC (
FLDOCC32 for FML32).
The supported field types are short,
long,
float,
double,
char,
string,
carray (character array),
mbstring (multibyte character array—available in Tuxedo release 8.1 or later),
ptr (pointer to a buffer),
fml32 (an embedded FML32 buffer), and
view32 (an embedded VIEW32 buffer). The
mbstring,
ptr,
fml32, and
view32 types are supported only for the FML32 interface. These types are included as
#define statements in
fml.h (or
fml32.h), as shown in the following listing.
FLD_STRING,
FLD_CARRAY, and
FLD_MBSTRING are all arrays, but differ in the following way:
•
|
A FLD_STRING is a variable-length array of non-NULL characters terminated by a NULL.
|
•
|
A FLD_CARRAY or FLD_MBSTRING is a variable-length array of bytes, any of which may be NULL.
|
Functions that add or change a field have a FLDLEN argument that must be filled in when you are dealing with
FLD_CARRAY or
FLD_MBSTRING fields. The size of a string or carray is limited to 65,535 characters in FML, and 2 billion bytes for FML32.
The FLD_PTR field type makes it possible to embed pointers to application data in an FML32 buffer. Applications can add, change, access, and delete pointers to data buffers. The buffer pointed to by a
FLD_PTR field must be allocated using the
tpalloc(3c) call. The
FLD_PTR field type is supported only in FML32.
The FLD_FML32 field type makes it possible to store an entire record as a single field in an FML32 buffer. Similarly, the
FLD_VIEW32 field type allows an entire C structure to be stored as a single field in an FML32 buffer. The
FLD_FML32 and
FLD_VIEW32 field types are supported only in FML32.
VIEWS also supports the dec_t packed decimal type in source view descriptions. This data type is useful for transferring VIEW structures to COBOL programs. In a C program using the
dec_t type, the field must be initialized and accessed using the functions described in
decimal(3c) in the
Oracle Tuxedo ATMI C Function Reference. Within the COBOL program, the field can be accessed directly using a packed decimal (
COMP-3) definition. Because FML does not support a
dec_t field, this field is automatically converted to the data type of the corresponding FML field in the fielded buffer (for example, a string field) when converting from a VIEW to FML.
The environment variable FLDTBLDIR contains a list of directories where field tables can be found. The environment variable
FIELDTBLS contains a list of the files in the table directories that are to be used. For FML32, the environment variable names are
FLDTBLDIR32 and
FIELDTBLS32.
Within application programs, the FML function Fldid() provides for a run-time translation of a field name to its field identifier.
Fname() translates a field identifier to its field name (see
Fldid(3fml) and
Fname(3fml)). (The function names for FML32 are
Fldid32 and
Fname32.) The first invocation of either function causes space in memory to be dynamically allocated for the field tables and the tables to be loaded into the address space of the process. The space can be recovered when the tables are no longer needed. (Refer to
“Loading Field Tables” on page 5‑5 for more information.)
Use mkfldhdr() (or
mkfldhdr32()) to make header files out of field table files. These header files are included (with
#include) in C programs, and provide another way to map field names to field identifiers: at compile time. For more information on
mkfldhdr, mkfldhdr32(1), refer to
Oracle Tuxedo Command Reference.
The Funindex() function enables you to discard the index. When the fielded buffer is read from disk (or received from a sending process), the index can be explicitly reconstructed with the
Findex() function.
•
|
You can create source view descriptions that specify C structure-to-fielded buffer mappings or COBOL record-to-fielded buffer mappings, and make possible the transfer of data between structures and buffers.
|
•
|
The viewc or viewc32 view compiler is used to generate object view descriptions (stored in binary files) that are interpreted by your application programs at run time. The compiler also generates header files that can be used in C programs to define the structures used in view descriptions, and optionally generates COPY files that can be used in COBOL programs to define the records used in the view descriptions. For more information about these view compilers, see viewc, viewc32(1) in Oracle Tuxedo Command Reference.
|
•
|
Data transfers from C structures or COBOL records to fielded buffers can be done in any one of four modes: FUPDATE, FJOIN, FOJOIN, or FCONCAT. These modes are similar to the ones supported by the following FML functions: Fupdate, Fupdate32(3fml), Fjoin, Fjoin32(3fml), Fojoin, Fojoin32(3fml), and Fconcat, Fconcat32(3fml).
|
The FML VIEWS functions are Fvstof(),
Fvftos(),
Fvnull(),
Fvopt(),
Fvselinit(), and
Fvsinit(). For COBOL, the VIEWS facility provides two procedures:
FVSTOF and
FVFTOS. Upon calling any view function, the named object viewfile, if found, is loaded into the viewfile cache automatically. Each file specified in the environment variable
VIEWFILES is searched in order (see
“Setting Up Your Environment for FML and VIEWS” on page 4‑1). The first object viewfile with the specified name is loaded. Subsequent object viewfiles with the same name, if any, are ignored. For more information on the FML VIEWS functions, refer to
Oracle Tuxedo ATMI FML Function Reference.
•
|
BADFLDID is returned for functions that return a FLDID.
|
•
|
-1 is returned for all others.
|
The F_error() (or
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
Ferror, which is set when errors occur.
Fstrerror, Fstrerror32(3fml) can be used to retrieve the text of an error message from a message catalog; it returns a pointer that can be used as an argument to
userlog(3c), or to
F_error() or
F_error32().