GN command

Format

A For each parent segment (optional)

B For the object segment (optional)

Notes:

• ¹ If you leave out the SEGMENT option, specify the INTO option as shown.
• ² Specify INTO on parent segments for a path command.
• ³ If you use multiple qualification statements, specify a length for each, using FIELDLENGTH. For example: FIELDLENGTH(24,8)
• ⁴ You can use either the KEYS option or the WHERE option, but not both on one segment level.

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.

FIRST

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

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.

CURRENT

Qualifies the command, and specifies that you want to use the level of and levels above the current position as qualifications for this segment.

SEGMENT(name), SEGMENT((area))

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

You can have as many levels of qualification for a GN command as there are levels in the database's hierarchy. Using fully qualified commands with the WHERE or KEYS option clearly identifies the hierarchical path and the segment you want, and is useful in documenting the command. However, you do not need to qualify a GN command, because you can specify a GN command without the SEGMENT option.

Once you have established position in the database record, issuing a GN command without a SEGMENT option retrieves the next segment occurrence in sequential order.

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 GN 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 the 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. (It 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. It 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, and 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. It can be any expression in the host language that converts to the integer data type; if it is a variable, it 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 the VS COBOL II) compiler, you must specify KEYLENGTH with the KEYS option.

KEYS(area)

Qualifies the command with the segment's concatenated key. You can use either KEYS or WHERE for a segment level, but not both.

Area specifies an area in your program containing the segment's concatenated key.

WHERE(qualification statement)

Qualifies the command, specifying the segment occurrence. Its argument is one or more qualification statements, each of which compares the value of a field in a segment to a value you supply. Each qualification statement consists of:

• The name of a field in a segment
• The relational operator, which indicates how you want the two values compared
• The name of a data area in your program containing the value that is compared against the value of the field

Usage

Use the GN command to sequentially retrieve segments from the database. Each time you issue a GN command, IMS DB retrieves the next segment, as described by the options you include in the command. Before issuing a GN command, you should establish position in the database record by issuing a GU command.

You do not have to use a segment option with a GN command. However, you should qualify your GN commands as much as possible with the KEYS or WHERE options after the SEGMENT option.

Examples

We need a list of all patients who have been to this clinic.

EXEC DLI GN
   SEGMENT(PATIENT) INTO(PATAREA);

Each time your program issued this command, the current position moves forward to the next database record.

What are the names of the patients we have seen since the beginning of this month?

EXEC DLI GN
   SEGMENT(PATIENT) INTO(PATAREA)
   SEGMENT(ILLNESS) INTO(ILLAREA) WHERE(ILLDATE>=ILLDATE1);

EXEC DLI GN INTO(PATAREA);

Explanation: If you just retrieved the PATIENT segment for patient 04124 and then issued this command, you retrieve the first ILLNESS segment for patient 04124.

Restrictions

With an unqualified GN command, the retrieved segment type might not be the one expected. Therefore, specify an I/O area large enough to contain the largest segment accessible to your program.

Use either the KEYS option or the WHERE option, but not both on one segment level.