READY (COBOL)

The READY statement prepares a database area for access by DML functions and specifies the usage mode of the area.
idmscu19
The READY statement prepares a database area for access by DML functions and specifies the usage mode of the area.
The DBA can specify default usage modes in the subschema. Run units that use such a subschema need not issue any READY statements. The areas are readied in the predefined usage modes automatically. However, if a run unit issues a READY statement for one area, it must issue READY statements for all areas that it accesses unless the FORCE option was specified for the default usage mode. Areas using the default usage mode combined with the FORCE option are readied automatically even when the run unit has already issued READY for other areas.
The specified usage mode can be qualified with a PROTECTED option to prevent concurrent updates or an EXCLUSIVE option to prevent concurrent use of areas by other run units that are executing under the central version. Each area can be readied in its own usage mode. Usage modes can be changed by executing a FINISH (COBOL) statement, and then starting a new run unit by issuing a BIND RUN-UNIT statement, the appropriate BIND RECORD statements, and a READY statement specifying the new usage mode.
When the run unit readies database areas, all areas can be readied with a single READY statement or each area can be readied individually. All areas that are affected explicitly or implicitly by the DML statements that the run unit issues must be readied. Other areas that are included in the subschema need not be readied.
The READY statement can appear anywhere within an application program. However, to avoid runtime deadlock, ready all areas before issuing any other DML statements.
The READY statement is used in both the navigational and the non-navigational environments.
Syntax
►►─── READY ─┬─────────────┬──────────────────────────────────────────────────►              └─ 
area-name 
─┘  ►─┬─────────────────────────────────────────────────────┬─ . ────────────────►◄    └─ USAGE-MODE is ─┬─────────────┬───┬─ RETRIEVAL ◄ ─┬─┘                      ├─ PROTECTED ─┤   └─ UPDATE ──────┘                      └─ EXCLUSIVE ─┘
Parameters
  • READY
    area-name
    Specifies an area that is included in the subschema. By default, if you do not specify an area, READY opens all areas in the subschema.
  • USAGE-MODE IS
    Specifies the usage mode in which to open the area.
    • PROTECTED 
      Prevents concurrent updates of the area by run units that are executing under the same central version. After a run unit has readied an area with the PROTECTED option, no other run unit can ready that area in any UPDATE usage mode until the first run unit releases it with a FINISH statement. A run unit cannot ready an area with the PROTECTED option when another run unit has readied the area in UPDATE usage mode or with the EXCLUSIVE option.
      By default, if you do not specify PROTECTED or EXCLUSIVE, the areas are opened in shared mode.
    • EXCLUSIVE 
      Prevents concurrent use of the area by any other run unit that is executing under the central version. After a run unit has readied an area with the EXCLUSIVE option, no other run unit can ready that area in any usage mode until the first run unit releases it. By default, if you do not specify PROTECTED or EXCLUSIVE, the areas are opened in shared mode.
    • RETRIEVAL 
      Opens the area for retrieval only and allows other concurrently executing run units to open the same area in any nonexclusive usage mode. This value is the default.
    • UPDATE 
      Opens the area for both retrieval and update and allows other concurrently executing run units to open the same area in any usage mode other than exclusive or protected.
      • If a READY statement would result in a usage mode conflict for an area, while running under the central version, the run unit issuing the READY is placed in a wait state on the first functional database call.
      • Modification statements involving areas that are opened in one of the update usage modes are not valid when they affect sets that include records in an area that is opened in one of the retrieval usage modes.
Example
The following statement readies all subschema areas in a usage mode of PROTECTED UPDATE:
READY USAGE-MODE IS PROTECTED UPDATE.
Status Codes
After completion of the READY function, the ERROR-STATUS field in the IDMS communications block indicates the outcome:
Status code
Meaning
0000
The request has been serviced successfully.
0910
The subschema specifies an access restriction that prohibits readying the area in the specified usage mode.
0923
The named area is not in the subschema.
0928
The run unit has attempted to ready an area that has been readied previously.
0966
The specified area is not available for update. If the 0966 status code is ignored, subsequent attempts to access the area return a 01 or 09 minor code. Probable causes for the return of the status code are as follows:
If running in local mode, the area is locked against update.
If running under the central version, the area is not available to the program in the desired access mode.
0970
The database or journal file will not ready properly. A JCL error is the probable cause.
0971
The AREA being readied could not be found in the current DBNAME.
0978
A wait for an area would cause a deadlock. We recommend that all areas be readied before the first functional call is issued or that all programs ready areas in the same order.