BEA Logo BEA MessageQ Release 5.0

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy


   MessageQ Doc Home   |   FML Programmer's Guide   |   Previous Topic   |   Next Topic   |   Contents   

Field Definition and Use



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

These and related activities are described in this chapter.

Defining Fields

This section discusses

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:

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:

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; = 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.