RETRIEVE command

Use the RETRIEVE command to determine current position in the database in batch and BMP programs.

About the RETRIEVE command:

Format

Read syntax diagramSkip visual syntax diagramEXECDLIRETRIEVEUSING PCB( expression)KEYFEEDBACK( area) FEEDBACKLEN( expression)

Options

USING PCB(expression)
Specifies the DB PCB you want to use for the command. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number.

expression specifies the PCB for which you want to retrieve the concatenated key. It can be any expression in the host language that converts to the integer data type. You can specify either a number or a reference to a halfword containing a number. The value must be a positive integer not greater than the number of PCBs generated for the PSB. The first PCB in the list, the I/O PCB, is 1. The first DB PCB in the list is 2, the second is 3, and so forth.

KEYFEEDBACK(area)
Specifies an area into which the concatenated key for the segment is placed. If the area is not long enough, the key is truncated.
FEEDBACKLEN(expression)
Specifies the length of the key feedback area into which you want the concatenated key retrieved. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (It is required in COBOL programs and optional in PL/I and assembler language programs.)

expression is the length of the key feedback I/O area. It can be any expression in the host language that converts to integer data type; you can specify either a number or a reference to a halfword containing a number. For IBM® COBOL for z/OS® & VM (or VS COBOL II), PL/I, or assembler language, FEEDBACKLEN is optional. For COBOL programs that are not compiled with the IBM COBOL for z/OS & VM (or VS COBOL II) compiler, you must specify FEEDBACKLEN with the KEYFEEDBACK option.

Usage

You can use the RETRIEVE command to retrieve the concatenated key to determine your current position in all the PCBs your program accesses.

After issuing the RETRIEVE command, the segment type and level on which the position is established is returned to the DIBSEGM and DIBSEGLV fields in the DIB. The value in DIBKFBL is set to the actual length of the concatenated key.

Example

EXEC DLI RETRIEVE USING PCB(2) KEYFEEDBACK(KEYAREA);
EXEC DLI RETRIEVE USING PCB(5) KEYFEEDBACK(KEYAREA);
Explanation

These RETRIEVE commands retrieve the concatenated key for the first and fourth DB PCBs. (The first PCB in the list is the I/O PCB, so the first DB PCB is the second one in the list.) After issuing the first RETRIEVE command, you can determine your position in the first DB PCB by examining the concatenated key in KEYAREA, and the values returned in the DIBSEGM and DIBSEGLV fields in the DIB. After issuing the second RETRIEVE command, you can determine your position in the fourth DB PCB by examining the same fields.

Restrictions

Restrictions for the RETRIEVE command:

  • You cannot use this command in a CICS® program.
  • To use this command, you must first define an I/O PCB for your program.