Communications Blocks and Error Detection › IDMS Communications Block › Field Descriptions

Field Descriptions

Program Status Fields

The IDMS communications block contains the following fields that describe program status information:

• PGMNAME (offsets 0-7) is an 8-byte alphanumeric field that contains the name of the program being executed. This field is initialized automatically at the beginning of program execution if the program contains an @COPY IDMS SUBSCHEMA-BINDS statement. Otherwise, it must be initialized by the programmer.
• ERRSTAT (offsets 8-11) is a 4-byte alphanumeric field that contains a value indicating the outcome of the DML statement that calls the DBMS. The ERRSTAT field must be initialized to 1400 by the program. The DBMS updates this field immediately before returning control to the user program after performing (attempting) a requested database service.

  The ERRSTAT field and its use are described under Testing for DML Error-Status Codes later in this chapter.

  Note: A program that consists of two or more run units must reinitialize the ERRSTAT field to 1400 after finishing one run unit and before binding the next.

• DBKEY (offsets 12-15) is a 4-byte (fullword) binary field that contains the database key (db-key) of the last record accessed by the run unit. For example, after successful execution of an @FIND command, DBKEY is updated with the db-key of the located record. DBKEY is not changed if the call to the DBMS results in an error condition.
• RECNAME (offsets 16-31) is a 16-byte alphanumeric field that contains the name of the last record accessed successfully by the run unit. This field is left justified and padded with spaces on the right.
• AREANAME (offsets 32-47) is a 16-byte alphanumeric field that contains the name of the last area accessed successfully by the run unit. This field is left justified and padded with spaces on the right.
• ERRORSET (offsets 48-63) is a 16-byte alphanumeric field that contains the name of the set involved in the last operation to produce an error condition. This field is left justified and padded with spaces on the right.
• ERRORREC (offsets 64-79) is a 16-byte alphanumeric field that contains the name of the record involved in the last operation to produce an error condition. This field is left justified and padded with spaces on the right.
• ERRAREA (offsets 80-95) is a 16-byte alphanumeric field that contains the name of the area involved in the last operation to produce an error condition. This field is left justified and padded with spaces on the right.
• IDBMSCOM (offsets 96-195) is a 100-byte alphanumeric array that is used internally by CA IDMS/DB for specification of runtime function information.
• PGINFO (offsets 96-99) is a 4-byte binary field that represents the page information associated with the last record accessed by the rununit. For example, after successful execution of an @FIND command, PGINFO is updated with the page information of the located record.

  Page information is not changed if the call to the DBMS results in a nonzero status condition.

  Page information is a 4-byte field consisting of the following sub-fields:

  • Bytes 1-2: Page group number (PGINFGRP)
  • Bytes 3-4: Dbkey radix (PGINFDBK)

  The PGINFO field overlays part of the IDBMSCOM area in the subschema control.

  The dbkey radix portion of the page information can be used in interpreting a dbkey for display purposes and in formatting a dbkey from page and line numbers. The dbkey radix represents the number of bits within a dbkey value that are reserved for the line number of a record. By default, this value is 8, meaning that up to 255 records can be stored on a single page of the area. Given a dbkey, you can separate its associated page number by dividing the dbkey by 2 raised to the power of the dbkey radix. For example, if the dbkey radix is 4, you would divide the dbkey value by 2**4. The resulting value is the page number of the dbkey. To separate the line number, you would multiply the page number by 2 raised to the power of the dbkey radix and subtract this value from the dbkey value. The result would be the line number of the dbkey. The following two formulas can be used to calculate the page and line numbers from a dbkey value:

  Page-number = dbkey value / (2 ** dbkey radix)
  Line-number = dbkey value - (page-number * ( 2 ** dbkey radix))
  

• DIRDBKEY (offsets 196-199) is a 4-byte (fullword binary) field that contains a user-specified db-key value or a null db-key value of -1. This field is used for storing a record with a location mode of direct. DIRDBKEY must be initialized by the user; it is not updated by the DBMS.

  Note: (native VSAM users) The DIRDBKEY field can be used only when storing a record in a native VSAM relative record data set (RRDS). This field must be initialized by the user to the relative record number of the record being stored.

• Reserved for system (offsets 200-206) is a 7-byte alphanumeric field reserved for CA IDMS/DB use.
• FILLER (offset 207) is a 1-byte field used to ensure fullword alignment.
• RECOCCUR (offsets 208-211) is a 4-byte (fullword) binary field that contains a record-occurrence sequence identifier used internally by the DBMS.
• DMLSEQ (offsets 212-215) is a 4-byte (fullword) binary field that contains the source-level sequence number generated by the DML macros, if DEBUG is specified. It is not used by the runtime system, with the exception of SYSIDMS DMLTRACE=ON tracing.

Updating the Fields

After a call to the DBMS, one or more of the fields described above may be updated, depending on the DML statement issued and whether or not the statement was executed successfully.

Example of Updating Fields

The following figure illustrates the updating process; only those fields accessed by the runtime system are shown. Fields used internally by the DBMS are not shown. Blank fields are not updated by DML statements.

Key for this figure: