GU command

The Get Unique (GU) command is used to directly retrieve specific segments, and to establish a starting position in the database for sequential processing.

Format

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.

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.)

INTO(area)

Specifies an area into which the segment is read.

VARIABLE

Indicates that a segment is variable-length.

LAST

Specifies that you want to retrieve the last segment occurrence of a segment type, or that you want to insert a segment as the last segment occurrence.

SEGMENT(name), SEGMENT((area))

Qualifies the command, specifying the name of the segment type or the area in your program containing the name of the segment type that you want to retrieve, insert, delete, or replace.

To retrieve the first occurrence of a segment type, you need only specify the SEGMENT option. You can specify as many levels of qualification as there are hierarchic levels defined by the PCB you are using.

To establish position at the beginning of the database, issue a GU command with a SEGMENT option that names the root segment type.

If you leave out SEGMENT options for one or more hierarchic levels, DL/I assumes a segment qualification for that level. The qualification that DL/I assumes depends on your current position.

If DL/I has a position established at the missing level, DL/I uses the segment on which position is established.
If DL/I does not have a position established at the missing level, DL/I uses the first occurrence at that level.
If DL/I moves forward from a position established at a higher level, DL/I uses the first occurrence at the missing level that falls within the new path.
If you leave out a SEGMENT option for the root level, and DL/I has position established on a root, DL/I does not move from that root when trying to satisfy the command.
You can have as many levels of qualification for a GU command as there are levels in the database's hierarchy. Using fully qualified commands with the WHERE or KEYS option clearly identifies the hierarchic path and the segment you want, and is useful in documenting the command. However, you do not need to qualify a GU command at all, because you can specify a GU command without the SEGMENT option.

If you specify a SEGMENT option without a KEYS or WHERE option, IMS DB retrieves the first occurrence of that segment type it encounters by searching forward from current position. With an unqualified GU command, the segment type you retrieve might not be the one you expected, so you should specify an I/O area large enough to contain the largest segment your program has access to. (After successfully issuing a retrieval command, you can find out from DIB the segment type retrieved.)

If you fully qualify your command with a WHERE or KEYS option, you would retrieve the next segment in sequential order, as described by the options.

Including the WHERE or KEYS options for parent segments defines the segment occurrences that are to be part of the path to the segment you want retrieved. Omitting the SEGMENT option for a level, or including only the SEGMENT option without a WHERE option, indicates that any path to the option satisfies the command. DL/I uses only the qualified parent segments and the lowest-level SEGMENT option to satisfy the command. DL/I does not assume a qualification for the missing level.

SEGLENGTH(expression)

Specifies the length of the I/O area into which the segment is 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. (SEGLENGTH is required in COBOL programs for any SEGMENT level that specifies the INTO or FROM option.)

Requirement: The value specified for SEGLENGTH must be greater than or equal to the length of the longest segment that can be processed by this call.

OFFSET(expression)

Specifies the offset to the destination parent. The 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. Use OFFSET when you process concatenated segments in logical relationships. OFFSET is required whenever the destination parent is a variable-length segment.

LOCKED

Specifies that you want to retrieve a segment for the exclusive use of your program, until a checkpoint or sync point is reached. This option performs the same function as the Q command code. It applies to both Fast Path and full function. A 1-byte alphabetic character of 'A' is automatically appended as the class for the Q command code.

LOCKCLASS(class)

Specifies that you want to retrieve a segment for the exclusive use of your program until a DEQ command is issued or until a checkpoint or sync point is reached. (DEQ commands are not supported for Fast Path.) Class is a 1-byte alphabetic character (B-J), representing the lock class of the retrieved segment.

For full-function code, the LOCKCLASS option followed by a letter (B-J) designates the class of the lock for the segment. An example is LOCKCLASS('B'). If LOCKCLASS is not followed by a letter in the range B to J, then EXECDLI sets a status code of GL and initiates an ABENDU1041.

Fast Path does not support LOCKCLASS but, for consistency between full function and Fast Path, you must specify LOCKCLASS('x')), where x is a letter in the range B to J. An example is LOCKCLASS('B'). If LOCKCLASS is not followed by a letter in the range B to J, then EXECDLI sets a status code of GL and initiates an ABENDU1041.

MOVENEXT(data_value)

Specifies a subset pointer to be moved to the next segment occurrence after your current segment.

GETFIRST(data_value)

Specifies that you want the search to start with the first segment occurrence in a subset.

SET(data_value)

Specifies unconditionally setting a subset pointer to the current segment.

SETCOND(data_value)

Specifies conditionally setting a subset pointer to the current segment.

SETZERO(data_value)

Specifies setting a subset pointer to zero.

SETPARENT

Sets parentage at the level you want.

FIELDLENGTH(expression)

Specifies the length of the field value in a WHERE option.

KEYLENGTH(expression)

Specifies the length of the concatenated key when you use the KEYS option. The argument can be any expression in the host language that converts to the integer data type; a variable must be declared as a binary halfword value. For IBM® COBOL for z/OS® & VM (or VS COBOL II), PL/I, or assembler language, KEYLENGTH 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 KEYLENGTH with the KEYS option.

WHERE(qualification statement)

Use WHERE to further qualify your GU commands after using SEGMENT. If you fully qualify a GU command, you can retrieve a segment regardless of your position in the database record.

KEYS(area)

Use KEYS to further qualify your GU commands and specify the segment occurrence by using its concatenated key.

If you specify a SEGMENT option without a KEYS or WHERE option, IMS DB retrieves the first occurrence of that segment type it encounters by searching forward from current position. With an unqualified GU command, the segment type you retrieve might not be the one you expected, so you should specify an I/O area large enough to contain the largest segment your program has access to. (After successfully issuing a retrieval command, you can find out from DIB the segment type retrieved.)

If you fully qualify your command with a WHERE or KEYS option, you would retrieve the next segment in sequential order, as described by the options.

Including the WHERE or KEYS options for parent segments defines the segment occurrences that are to be part of the path to the segment you want retrieved. Leaving the SEGMENT option out for a level, or including only the SEGMENT option without a WHERE option, indicates that any path to the option satisfies the command. DL/I uses only the qualified parent segments and the lowest level SEGMENT option to satisfy the command. DL/I does not assume a qualification for the missing level.

Usage

Use the GU command to retrieve specific segments from the database, or to establish a position in the database for sequential processing.

You must at least specify the SEGMENT option with a GU command to indicate the segment type you want to retrieve. (IMS DB retrieves the first occurrence of the segment you named in the SEGMENT argument.)

When you need to retrieve a specific occurrence of a segment type, you can further qualify the command by using the WHERE or KEYS option after the SEGMENT option.

You probably want to further qualify your GU commands with the WHERE or KEYS option, and specify a specific occurrence of a segment type. If you fully qualify a GU command, you can retrieve a segment regardless of your position in the database record.

Examples

Example 1

What illness was Robert James here for most recently? Was he given any medication on that day for that illness? His patient number is 05136.

Explanation: This example requests two pieces of information. To answer the first part of the request and retrieve the most recent ILLNESS segment, issue this GU command (assuming that PATNO1 contains 05163):

EXEC DLI GU
   SEGMENT(PATIENT) WHERE(PATNO=PATNO1)
   SEGMENT(ILLNESS) INTO(AREA);

Once you had retrieved the ILLNESS segment with the date of the patient's most recent visit to the clinic, you can issue another command to find out whether he was treated during that visit. If the date of his most recent visit was January 5, 1988, you can issue the following command to find out whether or not he was treated on that day for that illness (assuming PATNO1 contains 05163, and DATE1 contains 19880105):

EXEC DLI GU
   SEGMENT(PATIENT) WHERE(PATNO=PATNO1)
   SEGMENT(ILLNESS) WHERE(ILLDATE=DATE1)
   SEGMENT(TREATMNT) INTO(TRTAREA) WHERE(DATE=DATE1);

Example 2

What is Joan Carter currently being treated for? Her patient number is 10320.

EXEC DLI GU
   SEGMENT(PATIENT) WHERE(PATNO=PATNO1)
   SEGMENT(ILLNESS) INTO(ILLAREA);

Explanation: In this example you want the ILLNESS segment for the patient whose patient number is 10320.

Example 3

EXEC DLI GU
   SEGMENT(PATIENT)
   SEGMENT(ILLNESS)
   SEGMENT(TREATMNT) INTO(AREA);

Explanation: This example retrieves the first TREATMNT segment and specifies the three levels of qualification.

Restriction

You must at least specify the SEGMENT option to indicate the segment type you want to retrieve.