Open for Read (OR)

Open for Read

This command loads into the specified TSR a copy of a specified generation of a specified table—the status of the table is opened for read.

MOVE 'OR'                   TO xxxx-COMMAND.
CALL 'TBLBASE' USING        TB-PARM
                            xxxx-COMMAND-AREA
                            [PASSWORD
                            [GENERATION]].

memcpy( tbCommArea.tbCommand, "OR", 2 );
TBLBASE( &tbParm, &tbCommArea, pReadPassword,
         nGeneration );

PASSWORD (OPTIONAL)—if the table has been defined with a read password then the correct read password must be supplied in the PASSWORD parameter. A valid write password is also acceptable.

GENERATION (OPTIONAL)—the GENERATION parameter may be specified as a relative generation (negative number) or as an absolute generation (positive) number; zero may be used to designate the current generation. If GENERATION is given, and the table has no password, a dummy PASSWORD parameter must be specified as a placeholder in the parameter list.

The TSR of record is the local TSR if there is no VTS name in the TB-PARM, otherwise it is the VTS-TSR specified in the TB-PARM.

The table to be opened is located by searching through a list of libraries, the LIB-LIST.

When the table is found on a library, the table definition is retrieved, an appropriate area in the TSR is allocated, and the table is loaded into that area.

If the GENERATION parameter is not specified and the table is found in the library list, the current generation is loaded.

If the GENERATION parameter is specified:

• If a matching generation of the table is found on a regular library, that generation is loaded.
• If the table is found on a regular library but there is no matching generation number, the table is not loaded and ERROR is set to 8.
• If the table is found on a VTS-TSR and the TSR of record is a local TSR, the generation in the VTS-TSR is used even if it does not match the generation specified.

ERROR is set to 0 if the table is found and loaded into the TSR. FOUND is always set to N.

ERROR 0009 occurs when the table is not found.

ERROR 0008 occurs when the table is found on a regular library but there is no matching generation number.

ERROR 0030 occurs when an incorrect password is used.

ERROR 0033 occurs when a later generation exists in the library than the one already loaded in the TSR.

ERROR 0086 occurs when an open is attempted on an Alternate Index when a Data Table is already opened via a link to a VTS-TSR.

A read password only protects the document from being opened for read or write, it does not provide read protection when it is open in the TSR. Others using the tableBASE API can also view the table contents.

An OR issued for an absolute generation of a table already open for read or write has no affect. The data is not reloaded.

If a relative generation is used to open a table, and subsequently another OR is aimed at the same relative generation, problems can arise. New generations may be created by other tasks, transactions and/or regions, changing the relative number, and therefore pointing to an incorrect generation of the table. ERROR code 0033 is returned to indicate this problem to the user.

If the table to be opened already resides in a VTS-TSR that is used from the LIB-LIST, the table will be linked to the copy in the VTS-TSR. No copy will be created in the local TSR.

If a table is opened, either by an implicit or explicit OR, in a DB2 region or multi-task batch region, or a CICS TS or IMS TM region for shared access by multiple users, users will be permitted to issue read-only commands or the CN command. In a single-task batch region, a table opened for read may also be updated, but it cannot be stored back in the library unless a subsequent OW is done.