TBOPEN—open a table

The TBOPEN service reads a permanent table from the table input file into virtual storage, and opens it for processing. TBOPEN should not be issued for temporary tables.

An ENQ is issued to ensure that no other user is currently accessing the table. The ENQ applies only to the specified table in the table (member) in the table input library, not the entire library. For the WRITE option, an exclusive ENQ remains in effect until the table is closed. For the NOWRITE option, a shared ENQ remains in effect only during the time that the table is read into storage.

Command invocation format


                                .-WRITE---.   
>>-ISPEXEC--TBOPEN--table-name--+---------+--------------------->
                                '-NOWRITE-'   

>--+------------------+--+-------+-----------------------------><
   '-LIBRARY(library)-'  '-SHARE-'

Call invocation format


>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><


>>-CALL--ISPLINK--('TBOPENbb'--,--table-name-------------------->

     .-'WRITEbbb'-.                                       
>--,-+-'b'--------+--,-+-library-+--,-+-'SHAREbbb'-+-);--------><
     '-'NOWRITEb'-'    '-'b'-----'    '-'b'--------'

Parameters

table-name: Specifies the name of the table to be opened.
WRITE: Specifies that the table is being accessed for update. The updated table can subsequently be saved on disk by use of the TBSAVE or TBCLOSE service. This option is the default.
The WRITE/NOWRITE usage of a shared table must be consistent on all TBOPEN and TBCREATE requests. That is, all requests for a given shared table that result in concurrent use of that table must specify the same WRITE or NOWRITE attribute.
NOWRITE: Specifies read-only access. Upon completion of processing, the virtual storage copy should be deleted by invoking the TBEND or TBCLOSE service.
library: Specifies the name of a DD statement or LIBDEF lib-type that defines the input library. If specified, a generic (non-ISPF) ddname must be used. If this parameter is omitted, the default is ISPTLIB.
SHARE: Specifies that the table in virtual storage can be shared between logical screens while the user is in split-screen mode. The TBOPEN request from the first logical screen reads the table into virtual storage and opens it. Subsequent TBOPEN requests from other logical screens use the same table (and same CRP) that is in virtual storage.
A successful TBOPEN or TBCREATE request causes the use count in the table to be incremented by one. The use count determines the action taken by subsequent TBEND and TBCLOSE requests.
buf-len: Specifies a fullword fixed binary integer containing the length of "buffer".
buffer: Specifies a buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC call for a command procedure.

Return codes

These return codes are possible:

0: Normal completion.
8: Table does not exist.
12: ENQ failed; table was in use by another user or the current user.
16: Table input library was not allocated.
20: Severe error.

Example

Access (open) the table TELBOOK for updating.

ISPEXEC TBOPEN TELBOOK WRITE

Set the program variable BUFFER to contain:

TBOPEN TELBOOK WRITE

Set program variable BUFLEN to the length of the variable BUFFER. Issue the command:

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('TBOPEN  ','TELBOOK ','WRITE   ');