Open for Read (OR)

Command title

Open for Read

Description

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.

COBOL syntax

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

C syntax

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

Parameters

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.

Explanation

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 library list is being searched the following occurs:

  • If the TSR of record is a local TSR, both regular and VTS-TSRs on the library list are searched. Processing stops when the table name is found on the first library in the library list.
  • If the TSR of record is a VTS-TSR, only regular libraries on the library list are searched. VTS-TSRs on the library list are bypassed. Processing stops when the table name is found on the first regular library on the library 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.

Return value

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.

Notes

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.

Exceptions

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.

See also

Modify Library Search Order (ML) —for information on the library search list

Set Indirect (SI)

Create Alternate Index Definition (CA)

Invoke Alternate Index (IA)

Opening an Alternate Index

Implicit table opens