Communications Blocks and Error Detection › IDMS Communications Block

IDMS Communications Block

The IDMS communications block passes information between the DBMS and the application program. Whenever a run unit issues a call to the DBMS for a database operation, the DBMS returns information about the outcome of the requested service to the ERRSTAT field in the application program's IDMS communications block.

To receive status information from the DBMS, an application program must define the IDMS communications block in variable storage. You must either copy the IDMS communications block from the dictionary into your program's variable storage by using the @COPY IDMS statement or generate the IDMS communications block by using the @SSCTRL statement. The following example illustrates the @COPY IDMS statement before and after it has been expanded by the DML precompiler:

               @COPY IDMS,SUBSCHEMA-CTRL      (Before DML expansion)
               @COPY IDMS,SUBSCHEMA-CTRL      (After DML expansion)
               DS    0D
     SSCTRL    DS    0CL216
     PGMNAME   DC    CL8' '
     ERRSTAT   DC    CL4'1400'
     DBKEY     DS    FL4
     RECNAME   DC    CL16' '
     AREANAME  DC    CL16' '
     ERRORSET  DC    CL16' '
     ERRORREC  DC    CL16' '
     ERRAREA   DC    CL16' '
     SSCIDBCM  DS    0CL100
     IDBMSCOM  DS    100CL1
        ORG   SSCIDBCM
     RDBMSCOM  DS    0CL100
     PGINFO    DS    0CL4
     PGINFGRP  DS    HL2
     PGINFDBK  DS    HL2
               DS    CL96
     DIRDBKEY  DC    FL4'0'
     DBSTATUS  DS    0CL8
     DBSTMTCD  DS    CL2
     DBSTATCD  DS    CL5
               DS    CL1
     RECOCCUR  DC    FL4'0'
     DMLSEQ    DC    FL4'0'

The same expansion would result by using the @SSCTRL statement in your application program instead of the @COPY IDMS,SUBSCHEMA-CTRL statement. The @SSCTRL statement is a macro that generates the variable storage definitions of the IDMS communications block instead of copying the block from the dictionary.

Note: For more information about the differences between these statements, see the DML Precompiler Options .

After every call to the DBMS, the DBMS issues an error-status code that indicates successful or unsuccessful completion of the requested service. This status code is returned to the ERRSTAT field in the IDMS communications block. You should examine the ERRSTAT field after every call to the DBMS. Depending on the error-status code, it may be useful to examine other fields and/or branch to a routine that responds to the condition indicated by the error-status code.

The following figure shows the layout of the 16-byte IDMS communications block; each field is described separately. Starting with offset 200, the layout of the block differs for application programs that run under CICS.

Note: For more information about the 18-byte IDMS communications block, see the 18-Byte Communications Blocks.

                  ┌────────────────────────────────────────┐
                  │ 16-CHARACTER IDMS COMMUNICATIONS BLOCK │
                  └────────────────────────────────────────┘

                                             Length      
                 Field          Data Type   (bytes)        Initial Value
  ┌──────────┐
 *│ 0      7 │   PROGRAM-NAME   Alphanumeric  8            Program Name
  ├────────┬─┘
  │ 8  11  │     ERROR-STATUS   Alphanumeric  4           '1400'
  ├────────┤
  │ 12  15 │     DBKEY          Binary        4(Fullword)  0000
  ├────────┴───┐
  │ 16      31 │ RECORD-NAME    Alphanumeric  16           Spaces
  ├────────────┤
  │ 32      47 │ AREA-NAME      Alphanumeric  16           Spaces
  ├────────────┤
  │ 48      63 │ ERROR-SET      Alphanumeric  16           Spaces
  ├────────────┤
  │ 64      79 │ ERROR-RECORD   Alphanumeric  16           Spaces
  ├────────────┤
  │ 80      95 │ ERROR-AREA     Alphanumeric  16           Spaces
  ├─────────┬──┘
**│ 96   99 │    PAGE-INFO      Binary        4(Fullword)  0000
  └─────────┘
  ┌──────────┐
  │ 96...195 │   IDBMSCOM-AREA   Alphanumeric  100         Low Values
  ├──────────┤
  │ 196  199 │   DIRECT-DBKEY    Binary        4(Fullword) 0000
  └──────────┘
  ┌─────────┐
  │ 200 206 │    DATABASE-STATUS Alphanumeric  7           Spaces
  ├─────┬───┘
  │ 207 │        FILLER          ...           1           ...
  ├─────┴───┐
  │ 208 211 │    RECORD-OCCUR    Binary        4(Fullword) 0000
  ├─────────┤
  │ 212 215 │    DML-SEQUENCE    Binary        4(Fullword) 0000
  └─────────┘

    * word aligned
   ** PAGE-INFO-GROUP overlays bytes 97 and 98 and PAGE-INFO-DBK-FORMAT
     overlays bytes 99 and 100. Both of these fields are binary datatype,
     each with a length of two bytes. Suggested initial values for
     both are 00. Together these two fields represent PAGE-INFO.