System-defined fields

Easytrieve provides three categories of system-defined fields:

General fields
File related fields
Report related fields

The fields for each category are described in the sections that follow. Fields not described are not supported by Migration Utility.

General fields (available globally)

CHKP-STATUS

A 2-byte alpha field returned by DLI after a CHKP and XRST call. This field contains spaces for a successful call. Any other value indicates an error. Refer to IMS/DLI Messages and Codes in the IBM IMS/DLI reference for specific values.

DISPLAYSIZE

A 4-byte binary field available in REPORT exits only. It contains the DISPLAYSIZE value, either the default value or the "y" value from the PAGESIZE (x y) coded on the REPORT statement.

Note: This is an Migration Utility option only.

PAGESIZE

A 4-byte binary field available in REPORT exits only. It contains the PAGESIZE value, either the default value or from the PAGESIZE coded on the REPORT statement.

Note: This is an Migration Utility option only.

PATH-ID

2-character path ID for DLI/IMS, available after the RETRIEVE statement. This field contains the last segment ID that was retrieved by the RETRIEVE statement. Note that an optional 2-character ID can be supplied for each segment in the RETRIEVE statement. PATH-ID contains spaces if there is no ID specified for the last retrieved segment in the path.

When using a tickler file to retrieve unique segments, PATH-ID is set to NF for the 'record not found' condition, otherwise it contains the ID of the last accessed segment.

&file-RECFM

A 1-byte alpha field that indicates the file record format:

F: Fixed record length
V: Variable record length
U: Undefined record length

&file is the file name defined in your program.

RETURN-CODE

A 4-byte binary field which is returned to the MVS™ operating system at end of job (program termination).

SYSDATE

An 8-byte date field in MM/DD/YY format. The date is obtained at the start of program execution.

Easytrieve replaces the leading zero by a space when printing on Report Headings or Detail Lines.

Migration Utility replaces the leading zero by a space when printing on Report Headings only. The leading zero is printed on Detail Lines, however.

SYSDATE-LONG

A 10-byte date field in MM/DD/CCYY format. The date is obtained at the start of program execution.

See SYSDATE above for printing rules.

SYSTIME

An 8-byte time field in HH:MM:SS format. The time is obtained at the start of program execution.

See SYSDATE above for printing rules.

File fields (available globally in each activity section)

FILE-STATUS

this is a read only field that contains the status of the most recent I/O operation. File-status is available when status is coded on the I/O statement.

Note: FILE-STATUS is always available in the generated COBOL program.

The Easytrieve status codes are:

0000: Operation is successful
0004: End Of File Reached (EOF)
0008: Record with a duplicate alternate key exists
0012: Duplicate key
0016: Record not found
0020: File is Locked (work stations only)
0024: Logical or physical I/O error

For information about converting COBOL status codes to Easytrieve equivalent codes, refer to the IOCODE=EASYT option on page EASYT. FILE-STATUS customization applies only when running with IOCODE=NATIVE.

In general, testing for ZERO, NOT ZERO or EOF is sufficient. Testing for any other specific values must be adjusted manually in Easytrieve Source or the translated COBOL programs. The COBOL values can be found in the COBOL Programmer Reference Manual (FILE-STATUS information).

FILE-STATUS code in the generated COBOL program is a 2-byte alphanumeric field while in Easytrieve it is a fullword numeric field. Instructions in Easytrieve Program that assign FILE-STATUS to a numeric field are flagged as errors.

When testing for a value other than zero, the value must be a 2-digit constant (literal) enclosed in quotation marks. Here are some of the more frequently checked COBOL status codes:

00: Operation is successful
02: Record with a duplicate alternate key exists (Read)
04: Wrong Length Record
10: End Of File Reached (EOF)
22: Duplicate Key (Write)
23: Record not found
30: Permanent I/O Error
34: Permanent I/O error, file is full (out of space)
39: Incompatible File DCB / Organization
96: DD Statement is missing in JCL (VSAM only)

RECORD-COUNT

A read-only 4-byte binary field that contains the number of logical input operations performed.

RECORD-LENGTH

A 4-byte binary field available for all file types. It contains the length of the last accessed or written file record. For variable-length records, the field contains only the length of the data (the 4 length-related bytes are excluded). For variable-length records, the length must be assigned before the WRITE or PUT operations.

Report fields (available only in report exits)

BREAK-LEVEL: Indicates the break level number
&field BREAK: Tests control break on &field field, where &field is "FINAL" or a CONTROL field name.
&FILE:KEY: The file key of RRN and PDS/PDSE files can be accessed by coding the file name as a qualifier to the KEY field. For example: FILEIN:KEY.
LEVEL: Indicates the control break level. This field is available on the BEFORE-BREAK and AFTER-BREAK report exits only.
LINE-COUNT: A 2-byte binary field that contains the number of lines printed on the current page.
LINE-NUMBER: A 2-byte field that contains the number of the line being printed within the line group.
Note: This counter is not supported by Migration Utility.
PAGE-COUNT: A 2-byte binary field that contains the number of the page being printed.
TALLY: A 10-byte packed decimal field that contains the number of detail records in a control break
WS-PENGI-DATE-9: A 6-digit date (SYSDATE) as obtained by a COBOL ACCEPT statement without insert characters. This is a numeric field and can be used in computations. The format is YYMMDD.
WS-PENGI-DATE-LONG-9: An 8-digit date (SYSDATE-LONG) as obtained by a COBOL ACCEPT statement without insert characters. This is a numeric field and can be used in computations. The format is CCYYMMDD.