TBCREATE—create a new table

The TBCREATE service creates a new table in virtual storage, and opens it for processing.

TBCREATE allows specification of the variable names that correspond to columns in the table. These variables will be stored in each row of the table. Additional "extension" variables can be specified for a particular row when the row is written to the table.

One or more variables can be defined as keys for accessing the table. If no keys are defined, only the current row pointer can be used for update operations.

Command invocation format


>>-ISPEXEC--TBCREATE--table-name--+---------------------+------->
                                  '-KEYS(key-name-list)-'   

                         .-WRITE---.                
>--+------------------+--+---------+--+---------+--------------->
   '-NAMES(name-list)-'  '-NOWRITE-'  '-REPLACE-'   

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

Call invocation format


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


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

                                           .-'WRITEbbb'-.   
>--,-+-key-name-list-+--,-+-name-list-+--,-+-'b'--------+------->
     '-'b'-----------'    '-'b'-------'    '-'NOWRITEb'-'   

>--,-+-'REPLACEb'-+--,-+-library-+--,-+-'SHAREbbb'-+-);--------><
     '-'b'--------'    '-'b'-----'    '-'b'--------'

Parameters

table-name: Specifies the name of the table to be created. The name can be from one to eight alphanumeric characters in length and should begin with an alphabetic character.
key-name-list: Specifies the variables, by name, that are to be used as keys for accessing the table. See name-list for the specification of name lists. If this parameter is omitted, the table will not be accessible by keys.
name-list: Specifies the non-key variables, by name, to be stored in each row of the table.
If key-name-list and name-list are omitted, the table can contain only extension variables that must be specified when a row is written to the table.
WRITE: Specifies that the table is permanent, to be written to disk by the TBSAVE or TBCLOSE service. The disk copy is not actually created until the TBSAVE or TBCLOSE service is invoked.
The WRITE/NOWRITE usage of a shared table must be consistent on all TBCREATE and TBOPEN 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 that the table is for temporary use only. When processing is complete, a temporary table should be deleted by the TBEND or TBCLOSE service.
REPLACE: Specifies that an existing table is to be replaced. If a table of the same name is currently open, it is deleted from virtual storage before the new table is created, and return code 4 is issued. If the WRITE parameter is also specified and a duplicate table name exists in the table input library, the table is created and return code 4 is issued. The duplicate table is not deleted from the input library. However, if TBSAVE or TBCLOSE is issued for the table, the existing table is replaced with the current table.
A table currently existing in virtual storage in shared mode cannot be replaced. If this is attempted, a return code of 8 results. Further, a shared table cannot be replaced by a non-shared table, and vice versa.
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 input library name is ISPTLIB.
SHARE: Specifies that the created table can be shared between all logical screens while the user is in split-screen mode. A table can be "created" by one screen only. That is, once one screen has issued a TBCREATE SHARE for a given table, another screen is not permitted to issue a TBCREATE for the same table.
A successful TBCREATE or TBOPEN 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.
4: Normal completion—a duplicate table exists but REPLACE was specified.
8: Either the table already exists and REPLACE was not specified, or REPLACE was specified and the table is in SHARE mode.
12: Table in use; ENQ failed.
16: WRITE mode specified and alternate table input library not allocated. TBCREATE checks the input library to determine if a duplicate table exists. See return code 8.
20: Severe error.

Examples

Example 1

In a CLIST, create a permanent table, TELBOOK, to contain the variable TABKEY and other variables, the names of which are specified in dialog variable TABVARS. The key field is TABKEY.

ISPEXEC TBCREATE TELBOOK KEYS(TABKEY) NAMES(&TABVARS )

Example 2

In a PL/I program, create a permanent table, TELBOOK, to contain the variable TABKEY and other variables, the names of which are specified in program variable TABVARS. The variable TABVARS has been made accessible to ISPF by a previous VDEFINE operation. The key field is TABKEY. Set the program variable BUFFER to contain:

TBCREATE TELBOOK KEYS(TABKEY) NAMES(&TABVARS)

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

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('TBCREATE','TELBOOK ','TABKEY  ',TABVARS);

Example 3

In a PL/I program, create a permanent non-keyed table, NKTBL, where FNAME, LNAME, PHONE, and LOC are the non-key table variables.

CALL ISPLINK ('TBCREATE','NKTBL ',' ',
            '(FNAME LNAME PHONE LOC)');