Common Considerations
Contents
idmscu
Contents
Every program that uses navigational DML to access a CA IDMS database must do the following:
- Identify the program's operating mode, the environment in which it will execute. Common operating modes are BATCH, BATCH-AUTOSTATUS, and IDMS-DC although many other environments are supported.
- Identify the subschema, the program's view of the database to be accessed. The subschema must include all record types, set types, and areas required by the program.
- Include descriptions of the IDMS communications block and the database records to be accessed. These descriptions are copied from the IDD into the program by the precompiler.
- Detect and handle error conditions encountered during the execution of a DML function.
Identifying the Operating Mode
The program identifies the operating mode in which it will execute through a DML statement called a precompiler-directive that varies based on the language in which the program is written. COBOL programs identify the operating mode in a special section of the ENVIRONMENT DIVISION called the IDMS-CONTROL SECTION, as illustrated in the following example that identifies this as a batch application:
IDMS-CONTROL SECTION. PROTOCOL MODE IS BATCH.
The operating mode affects the form and content of the calling sequences produced by the DML precompiler.
DEBUG can be specified as an option of the operating mode. If specified, each DML statement in the program is identified by a sequence number that can be used to determine the last DML statement that was executed when an error occurs. This can be very useful in debugging navigational applications.
Identifying the Subschema
A subschema is a program's view of the database and typically includes a subset of the records, record elements, sets, and areas defined in the schema describing the database to be accessed. A subschema can also limit the types of DML functions that can be issued by programs that use it.
The subschema to be used by the program is identified through a precompiler-directive statement that varies based on the language in which the program is written. COBOL programs identify the subschema in a special section of the DATA DIVISION called the SCHEMA SECTION, as illustrated below:
SCHEMA SECTION. DB EMPSS01 WITHIN EMPSCHM VERSION 100.
In this example, EMPSS01 is the name of the subschema. Version 100 of EMPSCHM is the schema under which it is defined.
Including Data Descriptions
Descriptions of the following structures must be included in the program in order to reserve space for them in variable storage.
- IDMS Communications Block- CA IDMS uses the IDMS communications block to post status information back to the application program concerning requested database services. The description of the IDMS communications block is generated as a record named SUBSCHEMA-CTRL (in COBOL) and is often referred to as the subschema control block.
- Subschema Names (COBOL only)- COBOL programs require the generation of a name literal for the subschema, and each record, set, and area included in the subschema.
- Subschema Records- The description of each database record to be accessed by the program must be included. Only records contained in the subschema may be accessed and the generated description reflects the subschema's view of the record rather than that of the schema.
The programmer controls how and where the data descriptions are generated using precompiler-directive statements. For example, the COBOL programmer can automatically generate all required descriptors at the end of the WORKING-STORAGE section by extending the PROTOCOL statement as follows:
IDMS-CONTROL SECTION. PROTOCOL MODE IS BATCH DEBUG IDMS-RECORDS WITHIN WORKING-STORAGE.
Alternatively, the COBOL programmer can generate the descriptions at the end of the LINKAGE SECTION by specifying:
IDMS-RECORDS WITHIN LINKAGE.
To have complete control over where structure descriptions are generated, the COBOL programmer can specify:
IDMS-RECORDS MANUAL.
The programmer then inserts a COPY statement, as shown below, at the point where the descriptions are to be generated:
COPY IDMS SUBSCHEMA-DESCRIPTION.
Additional forms of the COPY IDMS statement permit COBOL programmers to generate descriptions for the IDMS communications block, subschema names and subschema records separately, and control the level numbers that are generated.
See Copying Record Definitions and Their Synonyms for more information on copying information from IDD.
IDMS Communications Block
The IDMS communications block is the main interface block between your program and the DBMS. Whenever your program issues a call to the DBMS for a database operation, the DBMS returns information about the outcome of the requested service into the IDMS communications block. In particular, it contains the following fields (described using COBOL field names):
Field
| Description
|
PROGRAM-NAME | Name of the program; supplied by the program |
ERROR-STATUS | 4-digit code indicating the outcome of the last database service; all zeros indicates successful completion |
DBKEY | Database key of current of run unit |
RECORD-NAME | Last record type successfully accessed |
AREA-NAME | Area name of last record type successfully accessed |
ERROR-SET | Name of set last involved in an error condition |
ERROR-RECORD | Last record type involved in an error condition |
ERROR-AREA | Name of area last involved in an error condition |
PAGE-INFO | Page information for current of run unit |
DIRECT-DBKEY | Suggested database key for storing a record direct |
DML-SEQUENCE | Number of the DML statement last executed if DEBUG was specified in the operating mode |
Error Handling
CA IDMS reports the completion status of a requested DML function by placing a 4-digit alphanumeric code in the ERROR-STATUS field of the IDMS communications block. The ERROR-STATUS field should be examined following every executable DML command to determine whether the request was successful or not.
The following table identifies some of the most common error status values that can be returned and the corresponding condition names that are generated as part of the IDMS communications block record description (SUBSCHEMA-CTRL) for COBOL. For PL/I, these names may optionally be generated as named constants.
Code
| Explanation
| Level-88 Name
|
0000 | Request completed successfully | DB-STATUS-OK |
0326 | Record not found on a FIND or OBTAIN using a CALC key, db-key, index, or sort key | DB-REC-NOT-FOUND |
0307 | End of set or end of area was encountered on a FIND or OBTAIN NEXT or PRIOR in a set or area. | DB-END-OF-SET |
For COBOL and PL/I programs, CA IDMS provides an error checking routine called IDMS-STATUS that can be copied into the program. IDMS-STATUS checks the completion status of the latest DML request that was issued. If the function did not complete successfully, IDMS-STATUS performs a user-supplied routine called IDMS-ABORT (COBOL only), displays status information, and aborts the program. The status information, retrieved from the IDMS communications block, includes PROGRAM-NAME, ERROR-STATUS, ERROR-RECORD, ERROR-SET, ERROR-AREA, RECORD-NAME, AREA-NAME, DBKEY, page group, dbkey format and DML-SEQUENCE.
CA IDMS delivers IDMS-STATUS in 2 flavors. The new flavor includes DBKEY, page group and dbkey format and is defined in the dictionaries as versions 11 and higher. The old flavor does not expand any additional call to the internal formatting routine and thus does not display DBKEY, page group or dbkey format. The old flavor is defined as versions 1 to 5. The higher versions always take precedence. If you prefer to use an older version, you can drop the new versions 11 and higher from the dictionary which causes the old versions to be copied into the program instead. Another option is to select the requested version in the program using the VERSION clause of the COPY IDMS statement (INCLUDE IDMS statement in PL/I).
The COBOL example below shows how the IDMS-STATUS routine is copied into the program using the COPY IDMS statement. The example also shows the user-supplied IDMS-ABORT routine that must be coded by the COBOL programmer.
COPY IDMS IDMS-STATUS. IDMS-ABORT SECTION. IDMS-ABORT-EXIT. EXIT.
After every executable DML function, the program should do the following:
- Check the ERROR-STATUS field for any expected error codes. COBOL condition names (level 88s) have been provided with the standard SUBSCHEMA-CTRL definition for the most common ERROR-STATUS values.
- PERFORM IDMS-STATUS to check for any unexpected error codes.
For example, after issuing an OBTAIN CALC request, the program should check for an ERROR-STATUS value of '0326' (DB-REC-NOT-FOUND) and otherwise perform the IDMS-STATUS routine as follows:
OBTAIN CALC STUDENT. IF DB-REC-NOT-FOUND ... ... ELSE PERFORM IDMS-STATUS.
CA IDMS provides a set of protocols (operating modes) for COBOL programs that automatically perform the IDMS-STATUS routine as part of expanding the DML statement. These modes are referred to as "autostatus" protocols and have names such as BATCH-AUTOSTATUS. When using an autostatus protocol, expected ERROR-STATUS values can be specified as ON parameters in the DML statement. The following example illustrates the use of the ON clause to check for an '0326' ERROR-STATUS value when issuing an OBTAIN CALC request.
OBTAIN CALC STUDENT ON DB-REC-NOT-FOUND ... ...