RECORD Features

This topic includes the following sections:

•	RECORD Features

•	RECORD Description File

•	Setting up Your Environment for RECORD

RECORD Features

The RECORD facility is particularly useful when the data is transferred between COBOL language and C language. Under such condition, RECORD buffer type can be used in C language, and copybook is used in COBOL language.

The RECORD facility has the following features:

•	The cpy2record tool is used to generate record descriptions (stored in binary format) that are interpreted by your application programs at run time. For more information, see cpy2record in Oracle Tuxedo Command Reference.

•

At run time, record descriptions are read into a record file cache on demand and remain there until the cache is full. When the cache is full and a record description that is not in the cache is needed, the least recently accessed record description is removed from the cache to make room for the new one.

•	When transferring data between RECORD buffers and COBOL records, the source data is automatically converted to the type of the destination data. For instance, a string field may be converted between EBCDIC and ASCII formats.

A source record file is an ordinary text file that contains one or more source record descriptions, and often the existing COBOL copybook file is used. Source record files are used as input to cpy2record, which generates the record description files.

Following table lists cpy2record supported clauses in COBOL copybook file.

 

Table 3‑1 cpy2record Supported Clauses in COBOL Copybook File

Supported Clause	Description
OCCURS	OCCURS specifies tables whose elements can be referred to by indexing or subscripting. Fixed-length tables are supported; the following phrases are not supported: ASCENDING KEY and DESCENDING KEY phrases, INDEXED BY phrase, and OCCURS DEPENDING ON phrases (variable-length tables).
PICTURE	PICTURE specifies the general characteristics and editing requirements of an elementary item. The supported symbols in PICTURE clause are A, B, E, G, N, P, S, V, X, Z, 9, 0, /, ,, ., +, -, *, C, and D.
SIGN	SIGN specifies the position and mode of representation of the operational sign for the signed numeric item to which it applies.
USAGE	USAGE specifies the format in which data is represented in storage. The supported phrases are: BINARY, COMP, COMP-1, COMP-2, COMP-3, COMP-4, COMP-5, COMPUTATIONAL, COMPUTATIONAL-1, COMPUTATIONAL-2, COMPUTATIONAL-3, COMPUTATIONAL-4, COMPUTATIONAL-5, DISPLAY, DISPLAY-1, NATIONAL, and PACKED-DECIMAL. Unsupported phrases are: NATIVE, INDEX, POINTER, PROCEDURE-POINTER, FUNCTION-POINTER, and OBJECT REFERENCE.

Note:

The following clauses in COBOL copybook file are not supported by cpy2record: BLANK WHEN ZERO, EXTERNAL, GLOBAL, JUSTIFIED, GROUP-USAGE, RENAMES, and SYNCHRONIZED.

There are many supported RECORD functions; see RECORD Functions in Programming An Oracle Tuxedo ATMI Application Using FML for more information. Upon calling any record function, the named record description file, if found, is loaded into the record file cache automatically; see RECORD Description File for more information. Each file specified in the environment variable RECORDFILES is searched in order. The first record description file with the specified name is loaded. Subsequent record description files with the same name, if any, are ignored.

RECORD Description File

A RECORD description is created and stored in a source copybook. Often you can get it from existed mainframe COBOL copybook. The source RECORD description is compiled by cpy2record to create a RECORD object file and can then be used in C programs.

Each rname (the field name in copybook) does not have corresponding fbname (the name of the field in the fielded buffer) and vname (the identifier for the structure member) defined.

The cname in VIEW definition is not the same as field name in copybook (cname is lower-cased; hyphen is converted to underscore; the same name appends sequence number). RECORD items must keep the VIEW member name to do the conversion.

To support RECORD conversion between VIEW32/FML32, you can manually set vname and fbname for each rname after column 72 in the copybook or after *> in free-format COBOL. If not set explicitly, fbname and vname are the same as rname. The vname or fbname in RECORD description file should remain unique. If there are many same vname of fbname within the same level, when converting VIEW32 or FML32 to RECORD buffer, the first one is used.

If the #vname and #fbname is not set after column 72, the rname is used as the default fbname; for vname, hyphen in rname is converted to underscore and, uppercase is convert to lowercase (if you set option -i, uppercase is not converted to lowercase).

The view name is defined in @vname(); the fbname is defined in @fbname().

Listing 3‑1 RECORD Description File Example

# copybook definition #vname #fbname

01 A.

05 B.

10 E PIC S9(9) COMP-5. @vname(e_v) @fbname(FB_E)

10 F.

15 K PIC X(4).

15 L PIC S9(8) COMP.

05 C PIC S9(4).

05 D OCCURS 10 TIMES.

10 G PIC S9999 SIGN LEADING.

10 H PIC S9(5)V9(2) PACKED-DECIMAL.

10 I USAGE COMP-1.

10 J PIC X(10).

 

Setting up Your Environment for RECORD

The following variables are used throughout FML to access record files:

•

RECORDFILES - this variable should contain a comma-separated list of record description files for the application. Files given as full path names are used as is; files listed as relative path names are searched for through the list of directories specified by RECORDDIR variable. If RECORDFILES is not set, the single file name record.R is used (RECORDDIR still applies; see below).

•	RECORDDIR - this variable specifies a colon-separated list of directories to be used to find record files with relative filenames. Its usage is similar to the PATH environment variable. If RECORDDIR is not set or is NULL, then its value is taken to be the current directory.