IMS SSA: Segment Search Arguments Complete Guide

SSAs (Segment Search Arguments) are the parameters you pass to DL/I calls to control which segments IMS retrieves or processes. They are the IMS equivalent of a WHERE clause in SQL — but procedural, one segment type at a time. Understanding SSAs is essential for writing any non-trivial IMS program.

Two Types of SSA

Every SSA falls into one of two categories:

Unqualified SSA: Specifies only a segment name. IMS returns the next occurrence of that segment type without any field-level filtering.

Qualified SSA: Specifies a segment name plus one or more field qualifications. IMS only returns a segment occurrence if the field conditions are met.

Unqualified SSA Format

An unqualified SSA is exactly 9 bytes: the segment name (1–8 characters) left-justified and padded with a single space:

cobol

01 CUSTOMER-UNQUAL-SSA    PIC X(9) VALUE 'CUSTOMER '.
01 ACCOUNT-UNQUAL-SSA     PIC X(9) VALUE 'ACCOUNT  '.
01 TRANSACT-UNQUAL-SSA    PIC X(9) VALUE 'TRANSACT '.

Use unqualified SSAs when you want the next occurrence regardless of content — for sequential scans, or when you have already positioned at a specific parent and want all children.

Qualified SSA Format

A qualified SSA has this structure:

text

segname(fieldname op value)

In COBOL working storage:

cobol

01 CUSTOMER-QUAL-SSA.
   05 FILLER         PIC X(9)  VALUE 'CUSTOMER('.
   05 SSA-FIELD-NAME PIC X(8)  VALUE 'CUST-KEY'.
   05 SSA-RELOP      PIC X(2)  VALUE ' ='.
   05 SSA-KEY-VALUE  PIC X(10).
   05 FILLER         PIC X(1)  VALUE ')'.

The total length is: 9 (segment+open paren) + 8 (field name) + 2 (operator) + field-length + 1 (close paren).

The relational operators:

Operator	Meaning
`=`	Equal to
`>=`	Greater than or equal
`<=`	Less than or equal
`>`	Greater than
`<`	Less than
`^=`	Not equal to

Multiple Qualifications (Boolean SSAs)

A single SSA can contain multiple field qualifications joined by boolean operators:

cobol

01 ACCOUNT-BOOL-SSA.
   05 FILLER      PIC X(9)  VALUE 'ACCOUNT ('.
   05 FILLER      PIC X(8)  VALUE 'ACCT-TYPE'.
   05 FILLER      PIC X(2)  VALUE ' ='.
   05 FILLER      PIC X(3)  VALUE 'CHK'.
   05 FILLER      PIC X(1)  VALUE '*'.   *> AND
   05 FILLER      PIC X(8)  VALUE 'ACCT-BAL'.
   05 FILLER      PIC X(2)  VALUE ' >'.
   05 FILLER      PIC X(12) VALUE '+000000000000'.
   05 FILLER      PIC X(1)  VALUE ')'.

Boolean connectors:

* — AND (both conditions must be true)
+ — OR (either condition must be true)

IMS evaluates boolean SSAs left to right. There is no operator precedence — use parentheses grouping is not supported, so structure boolean conditions carefully.

Multi-Level SSAs in a Single Call

A DL/I call can include SSAs for multiple levels of the hierarchy simultaneously. The number and order of SSAs corresponds to the hierarchical path from root to the target segment:

cobol

* GU directly to a specific TRANSACTION
CALL 'CBLTDLI' USING GU-FUNC
                     CUSTOMER-PCB
                     TRANSACT-IO-AREA
                     CUSTOMER-QUAL-SSA    *> Level 1
                     ACCOUNT-QUAL-SSA     *> Level 2
                     TRANSACT-QUAL-SSA.   *> Level 3 (target)

IMS navigates through CUSTOMER matching the first SSA, then to ACCOUNT matching the second, then to TRANSACT matching the third. This is the fastest way to access a deeply nested segment when you know the full path.

Command Codes

Command codes modify how IMS processes the SSA. They are appended after the segment name with an asterisk prefix:

cobol

*> SSA with command code D (path call)
01 CUSTOMER-D-SSA PIC X(9) VALUE 'CUSTOMER*D'.

Common command codes:

Code	Effect
D	Path call — return this segment's data in a concatenated I/O area
C	Continue current parentage (used with GNP)
F	First occurrence only
L	Last occurrence
P	Set parentage at this level
U	Maintain position at this level
V	Same as U but return data
Q	Enqueue segment (IMS locking, rarely used)

The D command code (path call) is especially useful — it tells IMS to return data from intermediate segments while navigating to the target, all in one call:

cobol

* Return CUSTOMER and ACCOUNT data while retrieving TRANSACT
CALL 'CBLTDLI' USING GU-FUNC
                     CUSTOMER-PCB
                     PATH-IO-AREA         *> concatenated area
                     CUSTOMER-D-SSA
                     ACCOUNT-D-SSA
                     TRANSACT-QUAL-SSA.

Frequently Asked Questions

Q: What happens if a field name in an SSA does not match any field defined in the DBD? IMS returns status code AJ (bad SSA field name). This is a programming error — the FIELD macro in the DBD must have a matching name. Note that SSA field names are compared case-insensitively and must match the DBD FIELD NAME exactly.

Q: Can I use SSAs with REPL and DLET? No. REPL and DLET operate on the currently held position — they do not accept SSAs. The segment to be updated or deleted is the one retrieved by the preceding GHU, GHN, or GHNP call. SSAs are only used with retrieval calls (GU, GN, GNP and their hold variants) and ISRT.

Q: How do I find the next segment with the same parent without re-doing the GU? Use GNP with an appropriate SSA after the initial GU. GNP with an unqualified SSA returns the next sibling of the same segment type. GNP with a qualified SSA returns the next sibling matching the qualification. This is more efficient than repeatedly calling GU with different key values.

Part of the IMS Mastery Course — Module 12 of 22.