Reporting Facility Commands › FILE Command › IMS-DL/I Database Definition

IMS-DL/I Database Definition

This format of the FILE command defines the physical attributes of an IMS-DL/I database input file. The IMS-DL/I Database Definition command is coded as follows:

►►─ filename: ─┬─ INPUT ─┬─ DLI ─ RECORD=nnn ─────────────────────────────────►◄
               └─ FILE ──┘

filename:

Is a unique file name within the Reporting Facility program. The Reporting Facility automatically generates a one-character alphanumeric field, with the same name as the file name. It is to be used as a return code in conjunction with the GET command.

DLI

Indicates that this is an IMS-DL/I file. An 80-byte Communications Area is automatically allocated by the Reporting Facility to be used for communication between the DL/I interface program and the Reporting Facility.

On completion of a GET command, the Reporting Facility automatically returns the PCB feedback information to this area in a specific format. Use it in conjunction with the return code to determine the status of the I/O area. The format is as follows:

For a complete description of the contents and utilization of the PCB feedback area, see the relevant IBM publication.

RECORD=nnn

Is an unsigned numeric constant specifying the length of the data portion of the DL/I file to be accessed, plus an additional 255 characters for communication with DL/I. The system reserves the 255 characters of control information to be the first 255 characters of the I/O area.

The data accessed from a DL/I file is returned starting at location 256. The subsequent Format 1 DEFINE commands must define all data to be returned as being relative to 256.

The following is a schematic of the format of the I/O area as required by the DL/I interface program:

1—4

4-character function code

5—6

2–byte packed decimal number, denoting the number of segment search arguments (SSAs) to follow (maximum value is ten)

7—14

8–character segment name, specifying the segment to be retrieved

15—255

Optional SSAs

256—nnn

Returned data

Note the following:

• The GET command accesses the DL/I files. In the case of the primary file, the Reporting Facility accesses the DL/I files automatically. A one-character alphanumeric field, which must be referenced by the same name as the file name on the FILE command, contains the return code from the GET operation.

  During retrieval of records from a DL/I file, two conditions can occur:

  • END-OF-FILE (return code E)
  • NO-RECORD-FOUND (return code N)
• Only GET type commands are supported in the function code bytes 1—4 of the I/O area.
• Where the PSB can contain several PCBs, the DL/I interface program accesses the correct PCB by referring to the contents of bytes 7—14 of the PCB feedback area prior to executing the GET command against the DL/I file.

  Three unique conditions can occur:

  • If bytes 7—14 are blank, the system uses the first PCB.
  • If bytes 7—8 are a valid packed decimal number in the range of 1—255, the system considers it to be the number of the required PCB within the PSB.
  • If bytes 7—14 are non-blank and non-numeric, the system considers it to be a database name and the PCBs are searched for a matching name.

The database name is returned in bytes 7—14 of the PCB feedback area after each DL/I call. You can, at any time, reference a different database simply by changing the contents of this field. You can use this method to access different databases even if only a single DL/I file is defined in the Reporting Facility program.

IBM imposes strict rules for coding SSAs and you must follow them precisely. A typical qualified SSA is structured as follows:

 (key/sequence fieldname = search argument)

The search argument is the comparative value against which the specified key/sequence field is to be checked and must therefore be the same length and format of the key/sequence field.