Field Definition and Use

 

Introduction

Before you can begin to work with FML32 fielded buffers certain details must be taken care of, such as:

• defining fields

• making field definitions available to applications programs (through field table files and mapping functions at run-time, or C header files at compile time)

These and related activities are described in this chapter.

Defining Fields

This section discusses

• how fields are defined in field tables for run-time use

• the available functions for run-time use with the field table files

Field Names and Identifiers

A field identifier (fieldid) is defined using typedef as a FLDID32 for FML32, and is composed of two parts: a field type and a field number (the number uniquely identifies the field).

Field numbers are restricted to be between 1 and 33,554,431, inclusive, for FML32. Field number 0 and the corresponding field identifier 0 is reserved to indicate a bad field identifier (BADFLDID). When FML32 is used with other software that also uses fields, additional restrictions may be imposed on field numbers.

The numbering convention adopted by the BEA MessageQ is as follows:

• field numbers 1-100 are reserved for system use

• field numbers 101-33,554,431 are for application-defined fields with FML32.

The mappings between field identifiers and field names are contained in either field table files or field header files. Using field table files requires that you convert field name references in C programs with the mapping functions described later in this chapter; field header files allow the C preprocessor (cpp(1) in UNIX reference manuals) to resolve name-to-fieldid mappings when a program is compiled.

The functions and programs that access field tables use the environment variables FLDTBLDIR32 and FIELDTBLS32 to specify the source directories and field table files, respectively, which are to be used. These should be set as described in Chapter 3.

The use of multiple field tables allows you to establish separate directories and/or files for separate groups of fields. Note that field names and field numbers should be unique across all field tables, since such tables are capable of being converted into C header files, and field numbers that occur more than once may cause unpredictable results.

Field Table Files

Field table files are created using a standard text editor, such as vi. They have the following format:

• Blank lines and lines beginning with # are ignored.

• Lines beginning with $ ignored by the mapping functions but are passed through (without the $) to header files generated by mkfldhdr32(1); for example, this would allow the application to pass C comments, what strings, etc. to the generated C 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.

• All other lines should have the following form.

  name       rel-number      type      flag      comment

• where:

  • name is the identifier for the field. It should not exceed the C preprocessor identifier restrictions (that is, it should contain only alphanumeric characters and the underscore character). Internally, the name is truncated to 30 characters, so names must be unique within the first 30 characters.

  • rel-number is the relative numeric value of the field; it is added to the current base, if *base is specified, 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.

  • The flag field is reserved for future use; use a dash (-) in this field.

  • comment is an optional field that can be used for clarifying information.

Note that these entries must be separated by white space (blanks or tabs).

Field Table Example

The following is an example field table in which the base shifts from 500 to 700. The first fields in each group will be numbered 501 and 701, respectively.

Listing 4-1 A UNIX Field Table File

---

# following are fields for EMPLOYEE service# employee ID fields are based at 500*base 500#name           rel-number      type           flags   comment#----           ----------      ----           ------  -------EMPNAME         1               string         -       emp nameEMPID           2               long           -       emp idEMPJOB          3               char           -       job typeSRVCDAY         4               carray         -       service date*base 700# all address fields are now relative to 700EMPADDR         1               string         -       street addressEMPCITY         2               string         -       cityEMPSTATE        3               string         -       stateEMPZIP          4               long           -      zip code

---

Mapping Functions

Run-time mapping is done by the Fldid32() and Fname32() functions that consult the set of field table files specified by the FLDTBLDIR32 and FIELDTBLS32 environment variables.

Fldid32() maps its argument, a field name, to a fieldid:

char *name;extern FLDID32 Fldid32();FLDID32 id;...id = Fldid32(name);

Fname() does the reverse translation by mapping its argument, a fieldid, to a field name:

extern char *Fname32();
name = Fname32(id);
. . .

The identifier-to-name mapping is rarely used; that is, it is rare that one has a field identifier and wants to know the corresponding name. One place where the field identifier-to-field name mapping could be used is in a buffer print routine where you want to display, in an intelligible form, the contents of a fielded buffer.

Loading the Field Tables

Upon the first call, Fldid32() loads the field table files and performs the required search. Thereafter, the files are kept loaded. Fldid32() returns the field identifier corresponding to its argument on success, and returns BADFLDID on failure, with Ferror32 set to FBADNAME.

To recover the data space used by the field tables loaded by Fldid32(), the user may unload all of the files by a call to the Fnmid_unload32() function.

The function Fname32() acts in a fashion similar to Fldid32(), but provides a mapping from a field identifier to a field name. It uses the same environment variable scheme for determining the field tables to be loaded, but constructs a separate set of mapping tables. On success, Fname32() returns a pointer to a character string containing the name corresponding to the fldid argument. On failure, Fname32() returns NULL.

Note: The pointer is valid only as long as the table remains loaded.

As with Fldid32(), failure includes either the inability to find or open a field table (FFTOPEN), bad field table syntax (FFTSYNTAX), or a no-hit condition within the field tables (FBADFLD). The table space used by the mapping tables created by Fname32() may be recovered by a call to the function Fidnm_unload32().

Both mapping functions and other FML32 functions that use run-time mapping require FIELDTBLS32 and FLDTBLDIR32 to be set properly. Otherwise, default values are used (see Chapter 3 for the defaults).

Field Header Files

The command mkfldhdr32 converts field tables, as described above, into header files suitable for processing by the C compiler. Each line of the generated header file is of the following form.

#define fname   fieldid

where fname is the name of the field, and fieldid is its field-ID. The field-ID has both the field type and field number encoded in it. The field number is an absolute number, that is, base plus rel-number. The resulting file is suitable for inclusion in a C program.

The header file need not be used if the run-time mapping functions are used as described in the next sub-section. The advantage of compile-time mapping of names to identifiers is speed and a decrease of data space requirements. The disadvantage is that changes made to field name/identifier mappings after, for instance, a service routine has been compiled will not be propagated to the service routine (that is, it will use the mappings it has already compiled).

mkfldhdr32(1) translates each field-table specified in the FIELDTBLS32 environment variable to a corresponding header file, whose name is formed by concatenating a .h suffix to the field-table name. The resulting files are created, by default, in the current directory. The user may specify a creation directory to mkfldhdr32(1) by specifying a -d option followed by the name of the directory in which you want the header files to reside. For example,

FLDTBLDIR32=/project/fldtblsFIELDTBLS32=maskftbl,DBftbl,miscftblexport FLDTBLDIR32 FIELDTBLS32mkfldhdr32

will produce the include files maskftbl.h, DBftbl.h and miscftbl.h in the current directory by processing ${FLDTBLDIR32}/maskftbl, ${FLDTBLDIR32}/DBftbl and ${FLDTBLDIR32}/miscftbl. The command

mkfldhdr32 -d${FLDTBLDIR32}

will process the sample input field-table files and produce the same output files, but will place them in the directory given by ${FLDTBLDIR32}.

You may override the environment variables (or avoid setting them) when using mkfldhdr32 by specifying on the command line the names of the field tables to be converted (this does not apply to the run-time mapping functions). In this case, FLDTBLDIR32 is assumed to be the current directory and FIELDTBLS32 is assumed to be the list of parameters that the user specified on the command line. For example,

mkfldhdr32 myfields

will convert the field table file myfields to a field header file myfields.h, and place it in the current directory.