---

field_tables(5)

Name

field_tables-FML mapping files for field names

Description

The Field Manipulation Language functions implement and manage fielded buffers. Each field in a fielded buffer is tagged with an identifying integer. Fields that can variable in length (for example, a string) have an additional length modifier. The buffer then consists of a series of numeric-identifier/data pairs and numeric-identifier/length/data triples.

The numeric-identifier of a field is called its "field identifier" (fldid), and is typedef'd by FLDID. A field is named by relating an alphanumeric string (the name) to a FLDID in a field table.

The original FML interface supports 16-bit field identifiers, field lengths, and buffer sizes. A newer 32-bit interface, FML32, supports larger identifiers, field lengths, and buffer sizes. All types, function names, etc. are suffixed with "32" (for example, the field identifier type definition is FLDID32).

Field Identifiers

FML functions allow field values to be typed. Currently supported types include char, string, short, long, float, double, and character array. Constants for field types are defined in fml.h (fml32.h for FML32). So that fielded buffers can be truly self-describing, the type of a field is carried along with the field by encoding the field type in the FLDID. Thus, a FLDID is composed of two elements: a field type, and a field number. Field numbers must be above 100; the numbers 1-100 are reserved for system use.

Field Mapping

For efficiency, it is desirable that the field name to field identifier mapping be available at compile time. For utility, it is also desirable that these mappings be available at run time. To accommodate both these goals, FML represents field tables in text files, and provides commands to generate corresponding C header files. Thus, compile time mapping is done by the C preprocessor, cpp, by the usual #define macro. Run-time mapping is done by the function Fldid(\|) ( Fldid32(\|) for FML32), which maps its argument, a field name, to a field identifier by consulting the source field table files.

Field Table Files

Files containing field tables have the following format:

• blank lines and lines beginning with # are ignored.

• lines beginning with $ are ignored by the mapping functions but are passed through (without the $) to header files generated by mkfldhdr(1) (the command name is mkfldhdr32 for FML32). For example, this would allow the application to pass C comments, what strings, etc. to the generated header file.

• lines beginning with the string *base contain a base for offsetting subsequent field numbers. This optional feature provides an easy way to group and renumber sets of related fields.

• lines that don't begin with either * nor # should have the form:

  name    rel-numb   type

  where:

  • name is the identifier for the field. It should not exceed cpp restrictions.

  • rel-numb is the relative numeric value of the field. It is added to the current base to obtain the field number of the field.

  • type is the type of the field, and is specified as one of: char, string, short, long, float, double, carray.

Entries are white-space separated (any combination of tabs and spaces).

Conversion of Field Tables to Header Files

The command mkfldhdr (or mkfldhdr32) converts a field table, as described above, into a file suitable for processing by the C compiler. Each line of the generated header file is of the form:

#define  name  fldid

where name is the name of the field, and fldid is its field identifier. The field identifier includes the field type and field number, as previously discussed. The field number is an absolute number, that is, base + rel-number. The resulting file is suitable for inclusion in a C program.

Environment Variables

Functions such as Fldid(), which access field tables, and commands such as mkfldhdr(1) and vuform(1), which use them, both need the shell variables FLDTBLDIR and FIELDTBLS (FLDTBLDIR32 and FIELDTBLS32 for FML32) to specify the source directories and files, respectively, from which the in-memory version of field tables should be created. FIELDTBLS specifies a comma-separated list of field table file names. If FIELDTBLS has no value, fld.tbl is used as the name of the field table file. The FLDTBLDIR environment variable is a colon-separated list of \%directories in which to look for each field table whose name is not an absolute path name. (The search for field tables is very similar to the search for executable commands using the PATH variable) If FLDTBLDIR is not defined, it is taken to be the current directory. Thus, if FIELDTBLS and FLDTBLDIR are not set, the default is to take fld.tbl from the current directory.

The use of multiple field tables is a convenient way to separate groups of fields, such as groups of fields that exist in a database from those which are used only by the application. However, in general field names should be unique across all field tables, since such tables are capable of being converted to C header files (by the mkfldhdr command), and identical field names would produce a compiler name conflict warning. In addition, the function Fldid, which maps a name to a FLDID, does so by searching the multiple tables, and stops upon finding the first successful match.

Example

The following is a sample field table in which the base shifts from 500 to 700:

# employee ID fields are based at 500 
*base 500
 
#name  rel-numb  type  comment
#----  --------  ----  -------
EMPNAM  1     string emp's name
EMPID   2     long  emp's id
EMPJOB  3     char  job type: D,M,F or T
SRVCDAY  4     carray service date
 
# address fields are based at 700
 
*base 700  
 
EMPADDR  1     string street address
EMPCITY  2     string city
EMPSTATE 3     string state
EMPZIP  4     long  zip code

The associated header file would be

#define EMPADDR  ((FLDID)41661) /* number: 701 type: string */ 
#define EMPCITY  ((FLDID)41662) /* number: 702 type: string */
#define EMPID   ((FLDID)8694)  /* number: 502 type: long */
#define EMPJOB  ((FLDID)16887) /* number: 503 type: char */
#define EMPNAM  ((FLDID)41461) /* number: 501 type: string */
#define EMPSTATE ((FLDID)41663) /* number: 703 type: string */
#define EMPZIP  ((FLDID)8896)  /* number: 704 type: long */
#define SRVCDAY  ((FLDID)49656) /* number: 504 type: carray */

See Also

mkfldhdr(1), TUXEDO FML Guide

---

---