GETIMS CALL (Retrieve an IMS segment)

This IEB call retrieves the next segment selected by the view, skipping any intervening segments that are not selected by the view.

Figure 1. Syntax (using a view)

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.
NEXT: Retrieves the next segment in the database that matches the criteria specified in the view.
ROOT: Retrieves the root segment in the hierarchical path of the current segment. If you use specify ROOT with USING_VIEW, and the root segment is not selected by the view, then ROOT retrieves the first selected segment after that root segment.
TOP: Without USING_VIEW, TOP retrieves the first root segment in the database. With USING_VIEW, TOP retrieves the first segment in the database that is selected by the view; this is not necessarily a root segment.
USING_VIEW: Restricts GETIMS to retrieving segments that are selected by the view, which you must have already loaded by calling the VIEWIMS function before this call to GETIMS.

Returns zero if successful, otherwise nonzero. A return code of 4 indicates that the GETIMS('NEXT USING_VIEW') reached the end of the database.

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 indicates an IMS status code of:

FH: Unavailable DEDB area
BA: 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.

You can use GETIMS either with or without a view. If you use a view, then GETIMS only retrieves segments selected by the view. For example, GETIMS('NEXT USING_VIEW') retrieves the next segment selected by the view, skipping any intervening segments that are not selected by the view.