TBCREATE

Edit online

Creates and opens a new table.

Type

Table services function

Format

TBCREATE(name ['keys'] ['names'] [write]  [replace] [share] [handle])
name
The name of the table to be created. A table name has a maximum of 44 characters. It is composed of 2 to 5 qualifiers, with a period between each one. Qualifiers must each be 1 to 8 characters long. Table names are always folded to upper case by the Dialog Manager.
'keys'
A list of 1- to 8-character key variables, separated by blanks or commas. Key variables are used to ensure a row is unique.
'names'
A list of 1- to 8-character name variables, separated by blanks or commas.
write
Specifies whether (0; the default) or not (1) write access is granted. This is a Boolean value.
replace
Specifies whether (1) or not (0; the default) an existing, permanent table can be replaced. This is a Boolean value. If True is specified, the permanent table is removed from the tables data base immediately.
share
Specifies whether (1) or not (0; the default) a table can be shared (opened multiple times) by multiple users. This is a Boolean value.
handle
Specifies the variable name to be updated with the handle of the associated table instance.

Return Codes

0
TBCREATE completed normally.
4
TBCREATE completed normally. A duplicate table name exists, but replace was specified.
8
name exists on the table data base, and replace was not specified as 1 (true).
12
name is in use.
20
Severe error, probably invalid name, keys, or names.

Usage Notes®

  1. If keys are not specified, only the CRP can be used to access the table.
  2. Each key and name is a column of the table.
  3. write access (a value of 0) allows the user to write a table back to the table data base via TBSAVE or TBCLOSE, and thus overwrite any existing table data base copy.
  4. Users who issue TBOPEN for an existing table and specify a share value of 1 (yes) share one copy of the table. Updates from one user are propagated to all users sharing the table.
  5. The following table shows the possible combinations of write and share and the results:
    Share Write Result
    0 (No) 1 (No)

    Each user gets an in-memory copy of the table that can be updated. No user can cause the table to be written to the table data base.

    If another user opens the table with share=yes or write=yes, the table is not read from the data base; a copy is made of the in-memory data.
    1 (Yes) 1 (No)

    Each user has the same copy of the table and can update the in-memory copy. The table is not written to the table data base.

    If any user opens the table with share=no and write=yes, this request fails.
    0 (No) 0 (Yes)

    Only one user can open the table (except share=no, write=no). The user can save the table to the table data base with TBSAVE or TBCLOSE.

    If a user has the table open with share=yes or write=yes, this request fails.
    1 (Yes) 0 (Yes)

    Each user has the same copy of the table and can update the in-memory copy. Each user can save the table to the table data base with TBSAVE or TBCLOSE.

    If a user has the table open with share=no and write=yes, this request fails.
  6. If the current dialog thread ends, a TBCLOSE is automatically issued for any tables erroneously left open.
  7. Table handles are useful when:
    • A dialog thread needs to have multiple current row pointers (and therefore multiple opens) for a single table. Each handle represents an "instance" of a table and has its own CRP.
    • A dialog thread has dozens or more open tables. Accessing a table by handle provides a slight performance improvement.

Example

In the following example, TBCREATE is used to create a table named CUSTOMER.RECORDS. The table has a key variable of AcctID and name variables of CustName, Phone, and Status. TBCREATE specifies write access, replace table, and share access.


set TabName 'CUSTOMER.RECORDS'
set RC (tbcreate(&TabName
         'AcctID'                           /* key variable   */
         'CustName Phone Status'            /* name variables *
         0                                  /* write = yes    */
         0                                  /* replace = yes  */
         1))                                /* share = yes    */

if &RC = 8 log('Table &TabName already exists' 0 1 1)
else if &RC != 0 log('Table error on TBCREATE, RC=&RC' 0 1 1)

See Also

TBOPEN