Defining and Using Fields

This topic includes the following sections:

•	Preparing to Use FML and VIEWS

•	Defining Fields for FML and VIEWS

•	Mapping Fields to C Structures and COBOL Records

Preparing to Use FML and VIEWS

Before you can begin to work with FML fielded buffers, or to use the VIEWS functions that move fields between structures and fielded buffers, you must:

•	Define fields.

•	Make field definitions available to application programs (through field table files and mapping functions at run time, or through C header files at compile time).

•	Compile source view descriptions into object view descriptions, and generate corresponding C header files and COBOL COPY files.

These tasks and related activities are described here.

Defining Fields for FML and VIEWS

This topic includes the following sections:

•	Defining Field Names and Identifiers

•	Creating Field Table Files

•	Mapping Field Names to Field IDs

•	Loading Field Tables

•	Converting Field Tables to Header Files

Defining Field Names and Identifiers

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

A field number must fall in one of the following ranges:

•	For FML: between 1 and 8191, inclusive

•	For FML32: between 1 and 33,554,431, inclusive

Field number 0 and the corresponding field identifier 0 are reserved to indicate a bad field identifier (BADFLDID). When FML is used with other software that also uses fields, additional restrictions may be imposed on field numbers.

The Oracle Tuxedo system conforms to the following conventions for field numbers.

 

FML 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 Oracle Tuxedo system does not strictly enforce applications from using them.

The mappings between field identifiers and field names are contained in either field table files or field header files. If you are using field table files you must convert field name references in C programs with the mapping functions described later in this section. Field header files allow the C preprocessor (cpp(1) in UNIX reference manuals) to resolve name-to-field ID mappings when a program is compiled.

The functions and programs that access field tables use the environment variables FLDTBLDIR and FIELDTBLS to specify the source directories and field table files, respectively, that are to be used. (FLDTBLDIR32 and FIELDTBLS32 are used for the same purpose with FML32.) You should set these environment variables as described in “Setting Up Your Environment for FML and VIEWS” on page 3‑1.

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.

Creating 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 a dollar sign ($) are ignored by the mapping functions but are passed through (without the $) to header files generated by mkfldhdr. (Refer to mkfldhdr, mkfldhdr32(1) in Oracle Tuxedo Command Reference.) The ability to have lines ignored by the mapping functions is useful, for example, when an application passes C comments, what strings, and so on, to the generated C header file.

Note:

In COBOL applications, however, such lines are not passed through to the COBOL copy files.

•	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 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. It is specified as one of the following: short, long, float, double, char, string, carray, mbstring, ptr, fml32, or view32.

•	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 field in each group will be numbered 501 and 701, respectively.

Listing 4‑1 System 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 name
EMPID 2 long - emp id
EMPJOB 3 char - job type
SRVCDAY 4 carray - service date
*base 700
# all address fields are now relative to 700
EMPADDR 1 string - street address
EMPCITY 2 string - city
EMPSTATE 3 string - state
EMPZIP 4 long - zip code

 

Mapping Field Names to Field IDs

Run-time mapping is done by the Fldid() and Fname() functions, which consult the set of field table files specified by the FLDTBLDIR and FIELDTBLS environment variables. (If FML32 is being used, the Fldid32() and Fname32() functions reference the FLDTBLDIR32 and FIELDTBLS32 environment variables.)

Fldid maps its argument, a field name, to a fieldid, as shown in the following code:

char *name;
extern FLDID Fldid();
FLDID id;
...
id = Fldid(name);

Fname does the reverse translation by mapping its argument, a fieldid, to a field name, as shown in the following code:

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

Identifier-to-name mapping is rarely used; it is rare that one has a field identifier and wants to know the corresponding name. One situation in which the field identifier-to-field name mapping can be used is in a buffer print routine designed to display, in an intelligible form, the contents of a fielded buffer.

See Also

•	Fldid, Fldid32(3fml) in Oracle Tuxedo ATMI FML Function Reference

•	Fname, Fname32(3fml) in Oracle Tuxedo ATMI FML Function Reference

Loading Field Tables

Upon the first call, Fldid() loads the field table files and performs the required search. Thereafter, the files are kept loaded. Fldid() returns the field identifier corresponding to its argument on success, and returns BADFLDID on failure, with Ferror set to FBADNAME. (If FML32 is being used, Ferror32 is set, instead.)

To recover the data space used by the field tables loaded by Fldid(), you may unload all of the files by calling the Fnmid_unload() function.

The function Fname() acts in a fashion similar to Fldid(), but it 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, Fname() returns a pointer to a character string containing the name corresponding to the fldid argument. On failure, Fname() returns NULL.

Note:

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

As with Fldid(), 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 Fname() may be recovered by a call to the Fidnm_unload() function.

Both mapping functions and other FML functions that use run-time mapping require FIELDTBLS and FLDTBLDIR to be set properly. Otherwise, defaults are used. (For the default values of these environment variables, see “Setting Up Your Environment for FML and VIEWS” on page 3‑1.)

See Also

•	Fldid, Fldid32(3fml) in Oracle Tuxedo ATMI FML Function Reference

•	Fnmid_unload, Fnmid_unload32(3fml) in Oracle Tuxedo ATMI FML Function Reference

•	Fname, Fname32(3fml) in Oracle Tuxedo ATMI FML Function Reference

•	Fidnm_unload, Fidnm_unload32(3fml) in Oracle Tuxedo ATMI FML Function Reference

Converting Field Tables to Header Files

The mkfldhdr (or mkfldhdr32) command converts a field table, as described earlier, into a header file 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.

It is not necessary to use the header file if the run-time mapping functions are used as described in “Mapping Fields to C Structures and COBOL Records” on page 4‑8.

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, are not propagated to the service routine. (Under such circumstances, the service routine uses the mappings it has already compiled.)

mkfldhdr translates each field table specified in the FIELDTBLS environment variable to a corresponding header file, the name of which is formed by adding a .h suffix to the field table name. The resulting files are created, by default, in the current directory. If you want your header files to be created in another directory, you may specify that directory with the -d option on the mkfldhdr command line. For more information, refer to mkfldhdr, mkfldhdr32(1) in Oracle Tuxedo Command Reference.

Examples of Converting Field Tables to Header Files

Examples 1 and 2 show how to set your environment variables and run the mkfldhdr(1) command so that three field table files—${FLDTBLDIR}/maskftbl, ${FLDTBLDIR}/DBftbl, and ${FLDTBLDIR}/miscftbl—are processed, and three include files—maskftbl.h, DBftbl.h and miscftbl.h—are generated in the current directory. For more information, refer to mkfldhdr, mkfldhdr32(1) in Oracle Tuxedo Command Reference.

Example 1

FLDTBLDIR=/project/fldtbls
FIELDTBLS=maskftbl,DBftbl,miscftbl
export FLDTBLDIR FIELDTBLS
mkfldhdr

Example 2

FLDTBLDIR32=/project/fldtbls
FIELDTBLS32=maskftbl,DBftbl,miscftbl
export FLDTBLDIR32 FIELDTBLS32
mkfldhdr32

Example 3

Example 3 is the same as Example 1 with one exception: the output files—maskftbl.h, DBftbl.h and miscftbl.h—are generated in the directory indicated by ${FLDTBLDIR}.

FLDTBLDIR=/project/fldtbls
FIELDTBLS=maskftbl,DBftbl,miscftbl
export FLDTBLDIR FIELDTBLS
mkfldhdr -d${FLDTBLDIR}

mkfldhdr -d${FLDTBLDIR}

Overriding Environment Variables to Run mkfldhdr

You may override the environment variables (or avoid setting them) when using mkfldhdr by specifying, on the command line, the names of the field tables to be converted.

This method does not apply to run-time mapping functions, however. When run-time mapping functions are being used, FLDTBLDIR is assumed to be the current directory and FIELDTBLS is assumed to be the list of parameters that the user specified on the command line. For example, the command:

mkfldhdr myfields

converts the field table file called myfields to a field header file called myfields.h, and puts the new file in the current directory.

For more information, refer to mkfldhdr, mkfldhdr32(1) in Oracle Tuxedo Command Reference.

Mapping Fields to C Structures and COBOL Records

This topic includes the following sections:

•	What Is the VIEWS Facility?

•	Creating Viewfiles

•	Creating View Descriptions

•	Compiling Viewfiles

•	Using Header Files Compiled with viewc

•	Using COBOL COPY Files Created by the View Compiler

•	Displaying Viewfile Information After Compilation

What Is the VIEWS Facility?

FML VIEWS is a mechanism that enables the exchange of data between fielded buffers and C structures or COBOL records. This facility is provided because it is usually more efficient to perform lengthy manipulations on C structures with C functions than on fielded buffers with FML functions. VIEWS also provides a way for a COBOL program to send and receive messages with a C program that handles FML fielded records.

This section explains how to use VIEWS to provide fielded buffer/structure mappings.

Structure of VIEWS

The following diagram shows the various components of VIEWS and how they relate to one another.

Figure 4‑1 Components of the VIEWS Facility

Creating Viewfiles

Source viewfiles are standard text files (created through any standard text editor, such as vi) that contain one or more source view descriptions (the actual field-to-structure mappings).

The view compiler produces (among other things) object viewfiles containing the compiled object view descriptions. These object viewfiles can be used, in turn, as input to the view disassembler (viewdis or viewdis32), which translates the object view descriptions back into their source format (for verification or editing). For more information, refer to viewdis, viewdis32(1) in Oracle Tuxedo Command Reference.

You can create and edit source view descriptions, and edit the output of viewdis. You cannot read compiled view descriptions (which are in binary format) directly.

Besides view descriptions, viewfiles may contain comment lines, beginning with # or $. Blank lines and lines beginning with # are ignored by the view compiler, while lines beginning with $ are passed by the view compiler to any header files generated. This convention lets you pass C comments, what strings, and so on, to C header files produced by the view compiler.

Note:

This convention is not observed for COBOL; lines beginning with $ are not passed through to the COBOL copy files.

Creating View Descriptions

Each source view description in a source viewfile consists of three parts:

•

A line beginning with the keyword VIEW (never with a 32 suffix), followed by the name of the view description. This name may be composed of alphanumeric characters, including an underscore. Although viewc accepts names of up to 33 characters, the practical limit in most cases is 16 characters, since this is the maximum length for a subtype accepted by tpalloc(3c).

•	A list of member descriptions.

•	A line beginning with the keyword END.

The first line of each view description must begin with the keyword VIEW, followed by the name of the view description. A member description (or mapping entry) is a line with information about a member in the C structure or COBOL record. A line with the keyword END must be the last line in a view description.

The following listing shows the general structure of a source view description.

Listing 4‑2 Source View Description

VIEW vname
# type cname fbname count flag size null
# ---- ----- ------ ----- ---- ---- ----
--------------member descriptions-------------------
.
.
.
END

 

In the previous listing:

•	vname is the name of the view description, and should be a valid C identifier name, since it is also used as the name of a C structure. Underscores are mapped automatically to dashes in the COBOL COPY file.

•	type is the type of the member, and is specified as one of the following: int, short, long, char, float, double, string, carray, or dec_t. If the value of type is “-”, the default—the value of fbname—is used.

•

cname is the identifier for the structure member, and should be a valid C identifier name, since it is the name of a C structure member. Internally, the cname is truncated to 30 characters, so cnames must be unique within the first 30 characters. Underscores are mapped automatically to dashes in the COBOL COPY file.

•	fbname is the name of the field in the fielded buffer. This name must appear in a field table file.

•	count is the number of elements to be allocated (that is, the maximum number of occurrences to be stored for this member). The value of count must be less than or equal to 65,535 for FML, and less than or equal to 2,147,483,647 for FML32.

•	flag is a comma-separated list of options or “-” (which means that no options are set). For details, see “Specifying flag Options in a View Description” on page 4‑11.

•	size is the size of the member if the type is string, carray, or dec_t. For other types, “-” should be specified; the view compiler computes the size.

•	For string or carray, the value of size must be less than or equal to 65,535 for FML and less than or equal to 2,147,483,647 for FML32.

•

For the dec_t type, the value of size must be two numbers separated by a comma. The first number represents the number of bytes in the decimal value; it must be greater than 0 and less than 10. The second number represents the number of decimal places to the right of the decimal point; it must be greater than 0 and less than twice the number of bytes minus one.

•	null is the user-specified NULL value or “-” to indicate the default NULL value for that field. For details, see “Using NULL Values in VIEWS” on page 4‑14.

Specifying flag Options in a View Description

The following options can be specified as the flag element of a member description in a view description.

C

This option requests the generation of a structure member called the associated count member (ACM), in addition to the structure member described in the member description.

When data is being transferred from a fielded buffer to a structure, each ACM in the structure is set to the number of occurrences transferred to the associated structure member.

•	A value of 0 in an ACM indicates that no fields were transferred to the associated structure member

•	A positive value indicates the number of fields actually transferred to the structure member array.

•	A negative value indicates that there were more fields in the buffer than could be transferred to the structure member array. (The absolute value of the ACM equals the number of fields not transferred to the structure).

During a transfer of data from a structure member array to a fielded buffer, the ACM is used to indicate the number of array elements that should be transferred. For example, if the ACM of a member is set to N, the first N non-NULL fields are transferred to the fielded buffer. If N is greater than the dimension of the array, it defaults to the dimension of the array. In either event, after the transfer takes place, the ACM is set to the actual number of array members transferred to the fielded buffer.

The type of an ACM in the C header file is declared to be short for FML and long for FML32, and its name is generated as C_cname, where cname is the cname entry for which the ACM is declared. For example, an ACM for a member named parts is declared as follows:

short C_parts;

For a COBOL COPY file, the name is generated as C-cname and the type is declared as follows:

•	For FML: PIC S9(4) USAGE COMP-5

•	For FML32: PIC S9(9) USAGE COMP-5

Note:

It is possible for the generated ACM name to conflict with structure members with names that begin with a C_ prefix. Such conflicts are reported by the view compiler, and are considered fatal errors by the compiler. For example, the name C_parts for a structure member conflicts with the name of an ACM generated for the member parts.

F

Specifies one-way mapping from structure or record to fielded buffer. The mapping of a member with this option is effective only when transferring data from structures to fielded buffers. This option is ignored if the -n command-line option is specified.

L

This option is used only for member descriptions of type carray or string to indicate the number of bytes transferred for these possibly variable length fields. If a carray or string field is always used as a fixed length data item, then this option provides no benefit.

The L option generates an associated length member (ALM) for a structure member of type carray or string. When transferring data from a fielded buffer to a structure, the ALM is set to the length of the corresponding transferred fields. If the length of a field in the fielded buffer exceeds the space allocated in the mapped structure member, only the allocated number of bytes is transferred. The corresponding ALM is set to the size of the fielded buffer item. Therefore, if the ALM is greater than the dimension of the structure member array, the fielded buffer information is truncated on transfer.

When data is being transferred from a structure member to a field in a fielded buffer, the ALM is used to indicate the number of bytes to transfer to the fielded buffer, if it is a carray type field. For strings, the ALM is ignored on transfer, but is set afterwards to the number of bytes transferred. Note that because carray field may be of zero length, an ALM of 0 indicates that a zero-length field should be transferred to the fielded buffer, unless the value in the associated structure member is the NULL value.

An ALM is defined in the C header file as an unsigned short for FML and an unsigned long for FML32, and has a generated name of L_cname, where cname is the name of the structure for which the ALM is declared.

If the number of occurrences of the member for which the ALM is declared is 1 (or defaults to 1), then the ALM is declared as:

unsigned short L_cname;

whereas if the number of occurrences is greater than 1, say N, the ALM is declared as:

unsigned short L_cname[N];

and is referred to as an ALM Array. In this case, each element in the ALM array refers to a corresponding occurrence of the structure member (or field). For the COBOL COPY file, the type is declared to be PIC 9(4) USAGE COMP-5 for FML and PIC 9(9) USAGE COMP-5 for FML32, and its name is generated as L-cname. The COBOL OCCURS clause is used to define multiple occurrences if the member occurs multiple times.

Note:

It is possible for the generated ALM name to conflict with structure members with names that begin with an L_ prefix. Such conflicts are reported by the view compiler, and are considered fatal errors by the compiler. For example, the name L_parts for a structure member conflicts with the name of an ALM generated for the member parts.

N

Specifies zero-way mapping; no fielded buffer is mapped to the structure. This option can be used to allocate fillers in C structures or COBOL records. It is ignored if the -n command-line option is specified.

P

This option can be used to affect what VIEWS interprets as a NULL value for string and carray type structure members. If this option is not used, a structure member is NULL if its value is equal to the user-specified NULL value (without considering any trailing NULL characters).

If this option is set, however, a member is NULL if its value is equal to the user-specified NULL value with the last character propagated to full length (without considering any trailing NULL character).

A member whose value is NULL is not transferred to the destination buffer when data is transferred from the C structure or COBOL record to the fielded buffer. For example, a structure member TEST is of type carray[25] and a user-specified NULL value “abcde” is established for it. If the P option is not set, TEST is considered NULL if the first five characters are a, b, c, d, and e, respectively. If the P option is set, TEST is NULL if the first four characters are a, b, c, and d, respectively, and the rest of the carray contains the character “e” (that is, 21 e’s).

This option is ignored if the -n command-line option is specified.

S

Specifies one-way mapping from fielded buffer to structure or record. The mapping of a member with this option is effective only when transferring data from fielded buffers to structures. This option is ignored if the -n command line option is specified.

Using NULL Values in VIEWS

NULL values are used in VIEWS to indicate empty C structure or COBOL record members. Default NULL values are provided; you may also define your own.

The default NULL value for all numeric types is 0 (0.0 for dec_t); for char types, it is “\0”; and for string and carray types, it is “ “.

Escape convention constants can also be used to specify a NULL value. The view compiler recognizes the following escape constants: \ddd (where d is an octal digit), \0, \n, \t, \v, \b, \r, \f, \\, \’, and \”.

String, carray, and char NULL values may be enclosed in double or single quotes. Unescaped quotes within a user-defined NULL value are not accepted by the view compiler.

Alternatively, an element is NULL if its value is the same as the NULL value for that element, except in the following cases:

•	If the P option is set for the structure member, and the structure member is of string or carray type; see the preceding section for details on the P option flag.

•	If a member is of type string, its value must be the same string as the NULL value.

•	If a member is of type carray and the NULL value is of length N, then the first N characters in the carray must be the same as the NULL value.

You can also specify the keyword “NONE” in the NULL field of a view member description, which means there is no NULL value for the member.

The maximum size of default values for string and character array (carray) members is 2660 characters.

Note:

Note that for string members, which usually end with a “\0”, a “\0” is not required as the last character of a user-defined NULL value.

Compiling Viewfiles

viewc is a view compiler program for FML and viewc32 is used for FML32. It takes a source viewfile and produces an object viewfile, which is interpreted at run time to effect the actual mapping of data. At run time, a C compiler must be available for viewc. The command line looks like the following:

viewc [-n] [-d viewdir] [-C] viewfile [viewfile . . . ]

where viewfile is the name of a source viewfile containing source view descriptions. You may specify one or more viewfiles on the command line.

If the -C option is specified, then one COBOL COPY file is created for each VIEW defined in the viewfile. These copy files are created in the current directory.

The -n option can be used when compiling a view description file for a C structure or COBOL record that does not map to an FML buffer.

By default, all views in viewfile are compiled and two or more files are created: an object viewfile (suffixed with “.V”), and a header file (suffixed with “.h”) for each viewfile. For an illustration of the VIEWS components, see the diagram titled “Components of the VIEWS Facility” on page 4‑9.

The name of the object viewfile is viewfile.V. It is created in the current directory. The -d option can be used to specify an alternate directory. Header files are created in the current directory.

Note:

For those operating systems that are not case-sensitive, such as Windows, the object viewfile is given a .vv suffix.

For more information, refer to viewc, viewc32(1) in Oracle Tuxedo Command Reference.

Using Header Files Compiled with viewc

You can use header files created by the view compiler (viewc) in any C application programs to declare a C structure described by views. For example, the following view description:

VIEW test
#TYPE CNAME FBNAME COUNT FLAG SIZE NULL
int empid EMPID 1 - - -1
float salary EMPPAY 1 - - 0
long phone EMPPHONE 4 - - 0
string name EMPNAME 1 - 32 "NO NAME"
END

produces a C header file that looks like this:

struct test {
long empid; /* null=-1 */
float salary; /* null=0.000000 */
long phone[4]; /* null=0 */
char name[32]; /* null="NO NAME" */
};

For more information, refer to viewc, viewc32(1) in Oracle Tuxedo Command Reference.

Using COBOL COPY Files Created by the View Compiler

COBOL COPY files created by the view compiler with the -C option can be used in any COBOL application programs to declare COBOL records described by views. For example, the COBOL COPY file for the previous view description looks like the following in the file TEST.cbl:

* VIEWFILE: "test.v"
* VIEWNAME: "test"
05 EMPID PIC S9(9) USAGE IS COMP-5.
05 SALARY USAGE IS COMP-1.
05 PHONE OCCURS 4 TIMES PIC S9(9) USAGE IS COMP-5.
05 NAME PIC X(32).

Note that the COPY filename is automatically converted to uppercase by the view compiler. The COPY file is included in a COBOL program as follows:

01 MYREC COPY TEST.

For a more complete description of the output in the resulting COPY files, see Programming an Oracle Tuxedo ATMI Application Using COBOL.

Displaying Viewfile Information After Compilation

The view disassembler, viewdis, disassembles an object viewfile produced by the view compiler and displays view information in source viewfile format. In addition, it displays the offsets of structure members in the associated structure.

The ability to view the information in this type of format is useful for verifying that an object view description is correct.

To run the view disassembler, enter the following command:

viewdis objviewfile . . .

By default, objviewfile in the current directory is disassembled. If this file is not found in the current directory, an error message is displayed. You can specify one or more view object files on the command line.

The output of viewdis looks similar to the original source view description. It can be edited and re-input to viewc. The order of the lines in the output of viewdis may be different from the order of the lines in the original source view description, but this difference is irrelevant in determining whether the object file is correct.

For more information, refer to viewdis, viewdis32(1) in Oracle Tuxedo Command Reference.