Housekeeping Statements
Housekeeping consist of initiating a run unit, binding records to storage areas, readying areas, and terminating the run unit. This article describes how to code DML statements that request the execution of housekeeping functions, and includes the following information:
idmscu19
Housekeeping consist of initiating a run unit, binding records to storage areas, readying areas, and terminating the run unit. This article describes how to code DML statements that request the execution of housekeeping functions, and includes the following information:
2
2
BIND RUN-UNIT Statement
The first database function executed within your program must be a BIND RUN-UNIT in order to establish a session with the DBMS. You can code this in one of two ways:
- By coding a BIND RUN-UNIT statement.
- By coding a COPY IDMS SUBSCHEMA-BINDS statement.
The COPY IDMS SUBSCHEMA-BINDS causes the precompiler to generate the BIND RUN-UNIT statement followed by BIND RECORD statements for every subschema record whose description is included in the program.
In deciding which statement to use, consider the following:
- If coding the BIND RUN-UNIT statement explicitly, you should first move the name of the program to the PROGRAM-NAME field within the IDMS communications block. The precompiler does this for you if you are using COPY IDMS SUBSCHEMA-BINDS.
- COPY IDMS SUBSCHEMA-BINDS should only be used if an autostatus protocol is in effect since otherwise error checking is not performed after each of the generated DML statements.
- Optional clauses on the BIND RUN-UNIT statement allow the specification of the target database to access, the subschema to use, and the dictionary from which to load the subschema. These options are not available when using COPY IDMS SUBSCHEMA-BINDS.
The following COBOL example binds a run unit to the EMPDEMO database:
MOVE 'MYPROG' TO PROGRAM-NAME. BIND RUN-UNIT DBNAME 'EMPDEMO'. PERFORM IDMS-STATUS. BIND RECORD Statement
If your program serially initiates and terminates multiple run units, you should re-initialize the ERROR-STATUS field to 1400 before starting each subsequent run unit.
BIND RECORD Statement
Before a record can be accessed, you must bind it to a specific location in variable storage by issuing a BIND RECORD function. To do this, you either:
- Code a BIND RECORD statement for each record to be accessed.
- Code a COPY IDMS SUBSCHEMA-BINDS statement. See the preceding section for more information on this statement.
The following example binds the DEPARTMENT and EMPLOYEE records to their respective locations in variable storage.
BIND DEPARTMENT. PERFORM IDMS-STATUS. BIND EMPLOYEE. PERFORM IDMS-STATUS.
READY Statement
Each database area containing records to be accessed must be readied. The following example readies both the EMP-DEMO-REGION and the ORG-DEMO-REGION areas:
READY EMP-DEMO-REGION USAGE-MODE IS PROTECTED UPDATE. PERFORM IDMS-STATUS. READY ORG-DEMO-REGION USAGE-MODE IS RETRIEVAL. PERFORM IDMS-STATUS.
The specified usage mode allows records within the EMP-DEMO-REGION to be updated (stored, modified, and erased) but prevents them from being updated by other programs running concurrently; records within the ORG-DEMO-REGION can only be retrieved (no updating will be allowed).
You can code a single ready statement if all areas within the subschema are to be readied with the same mode. The following statement readies all areas in a shared update mode:
READY USAGE-MODE IS UPDATE. PERFORM IDMS-STATUS.
It is possible to define default usage modes for areas within a subschema. A program using such a subschema need not code a READY statement. If the program does code a READY statement, it must ready every area that it will access unless the FORCE option was specified for the default usage mode. Areas using the default usage mode combined with the FORCE option are automatically readied even if the run-unit already issued READY for other areas.
Your program should ready all areas that it intends to access before issuing any other DML request (other than BIND RUN-UNIT and BIND RECORD). This avoids deadlocks between programs that ready areas in conflicting ways such as shared update and protected update.
Termination Statements
After a program has completed its database access activities successfully, it must issue the FINISH function to "close" the database and commit any changes that it has made. The following example shows how to code the FINISH DML statement in COBOL:
FINISH. PERFORM IDMS-STATUS.
It is also possible to commit changes without terminating the run unit. This is often done at the completion of a logical unit of work to free up records that have been updated so that other programs can access them, while keeping the run unit open so that more work can be done. To do this, a COMMIT DML statement is used instead of a FINISH, as shown in the following example that commits changes but maintains the run unit's currencies:
COMMIT. PERFORM IDMS-STATUS.
An option on the COMMIT statement nullifies currencies in addition to committing database changes.
If an error is encountered during program execution that prevents successful completion of the logical unit of work, the program should issue a ROLLBACK DML statement instead of a FINISH as shown in the following example in which database changes are rolled back and the run unit terminated:
ROLLBACK. PERFORM IDMS-STATUS.
An option on the ROLLBACK statement permits the run unit to continue after the database changes have been rolled back.
Database changes are only rolled back automatically when the run unit is executing under central version. In local mode, the database must be manually recovered.