SSA coding formats

Use the following formats to code segment search arguments in assembler language, C language, COBOL, Pascal, and PL/I.

Assembler language SSA definition examples

The following code example shows how you would define a qualified SSA without command codes. If you want to use command codes with this SSA, code the asterisk (*) and command codes between the 8-byte segment name field and the left parenthesis that begins the qualification statement.

*        CONSTANT AREA
⋮
SSANAME  DS    0CL26
ROOT     DC    CL8'ROOT    '
         DC    CL1'('
         DC    CL8'KEY     '
         DC    CL2' ='
NAME     DC    CLn'vv...v'
         DC    CL1')'

This SSA looks like this:

ROOTbbbb(KEYbbbbbb=vv...v)

C language SSA definition examples

An unqualified SSA that does not use command codes looks like this in C:

    const struct {
    char seg_name_u[8];
    char blank[1];
} unqual_ssa = {"NAME    ", " "};

You can use an SSA that is coded like this for each DL/I call that needs an unqualified SSA by supplying the name of the segment type you want during program execution. Note that the string size declarations are such that the C null terminators do not appear within the structure.

You can, of course, declare this as a single string:

const char unqual_ssa[] = "NAME      "; /* 8 chars + 1 blank  */

DL/I ignores the trailing null characters.

You can define SSAs in any of the ways explained for the I/O area.

The easiest way to create a qualified SSA is using the sprintf function. However, you can also define it using a method similar to that used by COBOL or PL/I.

The following is an example of a qualified SSA without command codes. To use command codes with this SSA, code the asterisk (*) and command codes between the 8-byte segment name field and the left parenthesis that begins the qualification statement.

struct {
    seg_name       char[8];
    seg_qual       char[1];
    seg_key_name   char[8];
    seg_opr        char[2];
    seg_key_value  char[n];
    seg_end_char   char[1];
} qual_ssa = {"ROOT    ", "(", "KEY     ", " =", "vv...vv", ")"};

Another way is to define the SSA as a string, using sprintf. Remember to use the preprocessor directive #include <stdio.h>.

char qual_ssa[8+1+8+2+6+1+1]; /* the final 1 is for the  */
                                    /* trailing '\0' of string */
sprintf(qual_ssa,
        ",
        "ROOT", "KEY", "=", "vvvvv");

Alternatively, if only the value were changing, the sprintf call can be:

sprintf(qual_ssa,
        "ROOT    (KEY      =, "vvvvv");
      /* 12345678 12345678 */

In both cases, the SSA looks like this:

ROOTbbbb(KEYbbbbbb=vv…v)

COBOL SSA definition examples

An unqualified SSA that does not use command codes looks like this in COBOL:

DATA DIVISION.
WORKING-STORAGE SECTION.
⋮
01  UNQUAL-SSA.
    02 SEG-NAME    PICTURE X(08)   VALUE '........'.
    02 FILLER      PICTURE X       VALUE ' '.

By supplying the name of the segment type you want during program execution, you can use an SSA coded like the one in this example for each DL/I call that needs an unqualified SSA.

Use a 01 level working storage entry to define each SSA that the program is to use. Then use the name you have given the SSA as the parameter in the DL/I call, in this case:

UNQUAL-SSA,

The following SSA is an example of a qualified SSA that does not use command codes. If you use command codes in this SSA, code the asterisk (*) and the command code between the 8-byte segment name field and the left parenthesis that begins the qualification statement.

DATA DIVISION.
WORKING-STORAGE SECTION.
⋮
01  QUAL-SSA-MAST.
    02 SEG-NAME-M       PICTURE X(08)   VALUE 'ROOT    '.
    02 BEGIN-PAREN-M    PICTURE X       VALUE '('.
    02 KEY-NAME-M       PICTURE X(08)   VALUE 'KEY     '.
    02 REL-OPER-M       PICTURE X(02)   VALUE ' ='.
    02 KEY-VALUE-M      PICTURE X(n)    VALUE 'vv...v'.
    02 END-PAREN-M      PICTURE X       VALUE ')'.

The SSA looks like this:

ROOTbbbb(KEYbbbbbb=vv...v)

Pascal SSA definition examples

An unqualified SSA that does not use command codes looks like this in Pascal:

type
  STRUCT = record
             SEG_NAME  : ALFA;
             BLANK     : CHAR;
           end;
const
  UNQUAL_SSA = STRUCT('NAME',' ');

You can also declare this SSA as a single string:

const
  UNQUAL_SSA = 'NAME     ';

The SSA shown in the following example is a qualified SSA that does not use command codes. If you use command codes in this SSA, code the asterisk (*) and the command code between the 8-byte segment name field and the left parenthesis that begins the qualification statement.

type
  STRUCT = record
             SEG_NAME       : ALFA;
             SEG_QUAL       : CHAR;
             SEG_KEY_NAME   : ALFA;
             SEG_OPR        : CHAR;
             SEG_KEY_VALUE  : packed array[1..n] of CHAR;
             SEG_END_CHAR   : CHAR;
           end;
const
  QUAL_SSA = STRUCT('ROOT','(','KEY',' =','vv...v',')');

This SSA looks like this:

ROOTbbbb(KEYbbbbbb=vv...v)

PL/I SSA definition examples

An unqualified SSA that does not use command codes looks like this in PL/I:

DCL 1  UNQUAL_SSA     STATIC UNALIGNED,
    2      SEG_NAME_U CHAR(8) INIT('NAME    '),
    2      BLANK      CHAR(1) INIT(' ');

You can use a SSA that is coded like this for each DL/I call that needs an unqualified SSA by supplying the name of the segment type you want during program execution.

In PL/I you define SSAs in structure declarations. The unaligned attribute is required for SSA data interchange with IMS. The SSA character string must reside contiguously in storage. For example, assignment of variable key values might cause IMS to construct an invalid SSA if the key value has changed the aligned attribute.

A separate SSA structure is required for each segment type that the program accesses because the value of the key fields differs among segment types. After you have initialized the fields (other than the key values), the SSA should not need to be changed again. You can define SSAs in any of the ways explained for the I/O area.

The following is an example of a qualified SSA without command codes. If you use command codes in this SSA, code the asterisk (*) and command codes between the 8-byte segment name field and the left parenthesis that begins the qualification statement.

DCL 1    QUAL_SSA              STATIC UNALIGNED,
         2       SEG_NAME                   CHAR(8) INIT('ROOT    '),
         2       SEG_QUAL                   CHAR(1) INIT('('),
         2       SEG_KEY_NAME               CHAR(8) INIT('KEY     '),
         2       SEG_OPR                    CHAR(2) INIT(' ='),
         2       SEG_KEY_VALUE              CHAR(n) INIT('vv...v'),
         2       SEG_END_CHAR               CHAR(1) INIT(')');

This SSA looks like this:

ROOTbbbb(KEYbbbbbb=vv...v)