Segment search arguments (SSAs)

Segment search arguments (SSAs) specify information for IMS™ to use in processing a DL/I call. Regardless of the datatype for the field specified in a SSA, the SSA treats the field as a binary type and does a binary comparison.

A DL/I call with one or more SSAs is a qualified call, and a DL/I call without SSAs is an unqualified call.

Unqualified SSAs: Contains only a segment name.
Qualified SSAs: Includes one or more qualification statements that name a segment occurrence. The C command and a segment occurrence's concatenated key can be substituted for a qualification statement.

You can use SSA to select segments by name and to specify search criteria for specific segments. Specific segments are described by adding qualification statements to the DL/I call. You can further qualify your calls by using command codes.

Unqualified SSAs

An unqualified SSA gives the name of the segment type that you want to access. In an unqualified SSA, the segment name field is 8 bytes and must be followed by a 1-byte blank. If the actual segment name is fewer than 8 bytes long, it must be padded to the right with blanks. An example of an unqualified SSA follows:

PATIENTbb

Qualified SSAs

To qualify an SSA, you can use either a field or the sequence field of a virtual child. A qualified SSA describes the segment occurrence that you want to access. This description is called a qualification statement and has three parts. The following table shows the structure of a qualified SSA.

Table 1. Qualified SSA structure
SSA Component	Field Length
Segment name	8
(	1
Field name	8
Relative operator	2
Field value	Variable
)	1

Using a qualification statement enables you to give IMS information about the particular segment occurrence that you are looking for. You do this by giving IMS the name of a field within the segment and the value of the field you are looking for. The field and the value are connected by a relational operator (R.O. in the previous table) which tells IMS how you want the two compared. For example, to access the PATIENT segment with the value 10460 in the PATNO field, you could use this SSA:

PATIENTb(PATNObb=b10460)

Start of change Alternatively, if the DL/I call uses command code O, you can use a 4-byte starting offset position and 4-byte data length instead of an 8-byte field name. The starting offset is relative to the physical segment definition and starts with 1. The maximum length that can be retrieved is the maximum segment size for the database type, and the minimum length is 1. The two fields are specified in the following format: 'oooollll'. oooo is the offset position and llll is the length of the data that you want to retrieve. You can use this approach to search for and retrieve data without a field definition. End of change

The qualification statement is enclosed in parentheses. The first field contains the name of the field (Fld Name in the previous table) that you want IMS to use in searching for the segment. The second field contains a relational operator. The relational operator can be any one of the following:

Equal, represented as
- =b
- b=
- EQ
Greater than, represented as
- >b
- b>
- GT
Less than, represented as
- <b
- b<
- LT
Greater than or equal to, represented as
- >=
- =>
- GE
Less than or equal to, represented as
- <=
- =<
- LE
Not equal to, represented as
- ¬=
- =¬
- NE

The third field (Fld Value in the previous table) contains the value that you want IMS to use as the comparative value. The length of Fld Value must be the same length as the field specified by Fld Name.

You can use more than one qualification statement in an SSA. Special cases exist, such as in a virtual logical child segment when the sequence field consists of multiple fields.

Sequence fields of a virtual logical child

As a general rule, a segment can have only one sequence field. However, in the case of the virtual logical-child segment type, multiple FIELD statements can be used to define a noncontiguous sequence field.

When specifying the sequence field for a virtual logical child segment, if the field is not contiguous, the length of the field named in the SSA is the concatenated length of the specified field plus all succeeding sequence fields. The following figure shows a segment with a noncontiguous sequence field.

Figure 1. Segment with a noncontiguous sequence field

Shows sequence fields A and B extending over a segment. Sequence field A is 10 bytes. A noncontiguous sequence field, B, is 11 bytes. The concatenated length is 21.

If the first sequence field is not included in a scattered sequence field in an SSA, IMS treats the argument as a data field specification, rather than as a sequence field.

Related reading: For more information on the virtual logical child segment, refer to IMS Version 13 Database Administration.