General tips for using the REXX functions defined by IEB and IBB

• A complete concatenated key as a single parameter, CKEY.
• The segment names and key fields for one or more levels in the hierarchical path of the segment you want, as separate parameters.
  For example, given the following segment hierarchy:

  ┌───────────────────────────────────────────────┐
  │ Segment name:    SUBURB                       │
  │ Key field name:  SUBURBK                      │ ◄─ Root segment
  │ Key field value: 'DENMARK'                    │
  └──────────────────────┬────────────────────────┘
                         │
  ┌──────────────────────┴────────────────────────┐
  │ Segment name:    LINKSTR                      │
  │ Key field name:  LINKSTRK                     │ ◄─ This is the segment
  │ Key field value: 'ALPINE                ST  ' │    you want to retrieve
  └───────────────────────────────────────────────┘

  then you would specify:

  GETIMS('SEGMENT=LINKSTR ',
         'WHERE SEGMENT=SUBURB #SUBURBK=DENMARK ',
               'SEGMENT=LINKSTR #LINKSTRK=ALPINE                ST')

  You do not have to specify all the segments in the hierarchical path. If, for example, there is only one LINKSTR segment with the key 'ALPINE ST ' in the entire database, you can specify:

  GETIMS('SEGMENT=LINKSTR',
    'WHERE SEGMENT=LINKSTR #LINKSTRK=ALPINE                ST')

  If 'ALPINE ST ' is the first or only LINKSTR segment under the SUBURB segment with a key of DENMARK, you can specify:

  GETIMS('SEGMENT=LINKSTR',
    'WHERE SEGMENT=SUBURB #SUBURBK=DENMARK')

  You can specify the fields using either the field names (as in the previous examples) or their reference numbers (such as #1, #2). Field values can be placed directly after the equals (=) sign or inside quotation marks after the = sign. Quotation marks are required if the field value contains leading or trailing spaces which would otherwise be ignored. In this way:

  GETIMS('SEGMENT=LINKSTR',
    'WHERE SEGMENT=LINKSTR #LINKSTRK=ALPINE                ST')

  and

  GETIMS('SEGMENT=LINKSTR',
    'WHERE SEGMENT=LINKSTR #LINKSTRK=   ALPINE                ST   ')

  are evaluated as identical, but

  GETIMS('SEGMENT=LINKSTR',
    'WHERE SEGMENT=LINKSTR #LINKSTRK="   ALPINE                ST   "')

  is evaluated differently.

  To list these reference numbers, you can use either the FM/IMS ISPF panels to browse the template for this DBD, or the VIEWIMS DESCRIBE REXX function with IEB.

  You can mix field names and reference numbers in the same WHERE clause.

  Before you can use this type of WHERE clause, you must call the VIEWIMS function, and load a template or view that matches the DBD you are using. This enables the WHERE clause to match the field names or reference numbers with the appropriate fields in the IMS segments.

When the WHERE clause is on a GETIMS, DELIMS or REPLIMS call, you may specify the FIRST parameter or NEXT parameter before it. When the FIRST parameter is specified, the call locates the first segment in the database that satisfies the WHERE clause. When the NEXT parameter is specified, the call locates the next segment in the database after the current segment that satisfies the WHERE clause. The default is NEXT.

When the WHERE clause is on an ISRTIMS call, the call locates the first segment in the database that satisfies the WHERE clause.

If you need to use the FMCONKEY and FMSEGNM values later, you can save them in your own defined variables. These user defined variables can then be used with the SEGMENT and CKEY parameters.