GETIMS CALL (Retrieve an IMS segment)

Figure 1. Syntax (without a view)

WHERE clause

Notes:

¹ To use field_ref or field_name, you must have already loaded a view by preceding this function call with a call to VIEWIMS.
² Specification of a field_ref without qualification of a layout_ref results in the field_ref being associated with the first layout for the segname segment.
³ To fully qualify a field_name, the layout name must be the first qualifier specified. If the layout name is not specified, FM/IMS searches all the layouts for the segname segment in relative order until the group qualifiers and field_name are found. If not found, an error message is displayed and processing terminates.

CHILD: Retrieves the next segment in the hierarchical path of the current segment. If you also specify SEGMENT=getsegm, then GETIMS retrieves the next segment of that name in the hierarchical path of the current segment.
conkey: The concatenated key of the segment you want to retrieve.
field_name: The name of a key field in the segname segment, as specified in the template or view. This can be obtained by printing the view/template using the VIEWIMS DESCRIBE clause or browsing the view/template online.
field_ref: A field reference number of the field within the layout. This can be obtained by printing the view/template using the VIEWIMS DESCRIBE clause or browsing the view/template online.
field_value: The value of the key field specified by field_ref or field_name.
FIRST: Retrieves the first segment in the database that satisfies the WHERE clause.
getsegm: The name of the segment you want to retrieve. If you also specify CHILD, then GETIMS retrieves the next hierarchically dependent segment with this name. Otherwise, the default value is NEXT, and GETIMS retrieves the next segment with this name, regardless of hierarchy.
HOLD: Retrieves the segment with a hold. Code this parameter when the GETIMS call is followed by a REPLIMS call without a WHERE clause, or a DELIMS call without a WHERE clause.
If the segment or one of its parents has a nonunique key or no key, this parameter is mandatory. Without it, the REPLIMS call or DELIMS call fails. The REPLIMS call or DELIMS call will not fail if the segment and its parents have unique keys but, if you do code it, your EXEC executes less DL/I calls and runs more efficiently.
layout_ref: The relative number of layout within segname segment. This can be obtained by printing the view/template using the VIEWIMS DESCRIBE clause.
NEXT: Retrieves the next segment in the database after the current segment.
PARENT: Retrieves the parent segment of the current segment.
If the current segment is a root segment, then GETIMS retrieves that same segment. To avoid looping in this situation, you can use the FMSEGNM REXX variable to check the name of the current segment.
qualifier: One or more qualifiers that identify the field name (field_name). The first qualifier is the segment layout name. Subsequent qualifiers (if any) are the group fields used to identify the specified field name. Omitting the layout name or group fields causes FM/IMS to search the segment layouts for the specified qualifiers and field name.
Note: The layout names and group fields can be obtained by printing the view/template using the VIEWIMS DESCRIBE clause or browsing the view/template online.
ROOT: Retrieves the root segment in the hierarchical path of the current segment.
segname: The name of a segment in the hierarchical path of the segment that you want to retrieve.
TOP: Retrieves the first root segment in the database.

Returns zero if successful, otherwise nonzero. A return code of 4 indicates that a segment was not found for one of the following reasons:

The segment specified by the WHERE clause does not exist.
GETIMS('NEXT') reached the end of the database.
GETIMS('CHILD') reached the end of the hierarchical path (current segment has no children).

If FM/IMS encounters an unavailable HALDB partition or DEDB area, the GETIMS function receives a return code of 8 and the ISPF variable FMSTATUS will indicate an IMS status code of:

FH: an unavailable DEDB area
BA: an unavailable HALDB partition

For nonzero return codes other than 4, check the DL/I status code in the FMSTATUS REXX variable to determine the cause of failure.

If successful, GETIMS passes the contents of the retrieved segment to the INREC and OUTREC REXX variables.

IEB example using GETIMS

⋮
$$FILEM IEB
⋮
$$FILEM     PROC=*

filerc = VIEWIMS('TPLDSN=FMN.IMS.IVP.TEMPLATE')

filerc = GETIMS('NEXT')
filerc = GETIMS()

filerc = GETIMS('SEGMENT=NSTREET ',
               ' WHERE SEGMENT=SUBURB #SUBURB-NAME=CITY BEACH ',
                      'SEGMENT=NSTREET #2=FLOREAT BEACH ')

filerc = GETIMS('SEGMENT=NSTREET ',
               ' WHERE CKEY=CITY BEACH        FLOREAT BEACH ')

/+
⋮