TBADD—add a row to a table

The TBADD service adds a new row of variables to a table. The new row is added either immediately following the current row, pointed to by the current row pointer (CRP), or is added at a point appropriate for maintaining the table in the sequence specified in a previously processed TBSORT request. The CRP is set to point to the newly inserted row.

The current contents of all dialog variables that correspond to columns in the table, which were specified by the KEYS and NAMES parameters in a TBCREATE, are saved in the row.

Additional variables, those not specified when the table was created, can also be saved in the row. These "extension" variables apply only to this row, not the entire table. The next time the row is updated, the extension variables must be specified again if they are to be rewritten.

For tables with keys, the table is searched to ensure that the new row has a unique key. The current contents of the key variables, dialog variables that correspond to keys in the table, are used as the search argument.

For tables without keys, no duplicate checking is performed.

To improve performance when you add several rows to a table, you can specify the MULT keyword with the number-of-rows parameter. By specifying the estimated number of rows you expect to add to the table, you supply ISPF the information it needs to more efficiently obtain the necessary storage for all rows when processing the first of these rows (rather than getting storage for one row at a time). The default value for the number-of-rows parameter is one unless the value is modified at ISPF installation.

When successive TBADD service requests with the MULT keyword are executed in a program loop, the first request results in storage being acquired for the multiple number of rows specified. On subsequent TBADD requests in the loop, ISPF checks to see if enough storage remains for the current row being added. If so, ISPF acquires no additional storage. If not, ISPF acquires additional storage as specified by the MULT keyword.

If the first row to be added to the table includes one or more extension variables, ISPF assumes that all rows added by the TBADD service request might include extension variables and takes that into account when obtaining the storage for the rows to be added.

If ISPF is unable to obtain all the storage it has estimated is needed for the number of rows specified (or if not specified, the default number of rows), it gets storage for one row at a time and issues a return code of four. ISPF does not issue an informational message when this condition occurs. At any time, if there remain rows to be added to the table and ISPF is unable to get storage for one row, a severe error (return code 20) results.

Command invocation format


>>-ISPEXEC--TBADD--table-name--+-----------------+--+-------+--->
                               '-SAVE(name-list)-'  '-ORDER-'   

>--+----------------------+------------------------------------><
   '-MULT(number-of-rows)-'

Call invocation format


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


>>-CALL--ISPLINK--('TBADDbbb'--,--table-name--,-+-name-list-+--->
                                                '-'b'-------'   

>--,-+-'ORDERbbb'-+--,-+-number-of-rows-+-);-------------------><
     '-'b'--------'    '-'b'------------'

Parameters

table-name: Specifies the name of the table to be updated.
name-list: Specifies a list of extension variables, by name, that are to be saved in the row, in addition to the variables specified when the table was created.
ORDER: Specifies that the new row is to be added to the table in the order specified in the sort information record. A TBSORT must have been performed for this table before use of this keyword. For tables with keys, the table is searched to ensure that the new row has a unique key. If a row with the same key already exists, the row is not added. This keyword is ignored if the table has never been sorted. If this keyword is omitted, any existing sort information record is nullified and to restore it, another TBSORT is required.
When a newly inserted row has sort field names equal to the sort field names of an existing row, the insertion is made after the existing row.
number-of-rows: Specifies the expected total number of rows to be added to a table during one session. This is a fullword fixed value greater than zero. The default value is one unless changed at ISPF installation. The maximum value that can be specified is 32 767.
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: The number-of-rows parameter was specified but storage was obtained for only a single row.
8: A row with the same key already exists; CRP set to TOP (zero). Returned only for tables with keys.
12: Table is not open.
16: Numeric convert error; see numeric restrictions for TBSORT. Returned only for sorted tables.
20: Severe error.

Example 1

Add a row to the table TELBOOK, based on the sort information record, copying to the row values from function pool variables whose names match those of table variables.

ISPEXEC TBADD TELBOOK ORDER

Set the program variable BUFFER to contain:

TBADD TELBOOK ORDER

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

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('TBADD   ','TELBOOK ',' ','ORDER   ');

Example 2

Add multiple rows to table TELBOOK.

ISPEXEC TBADD TELBOOK MULT(&ROWS)

where &ROWS is a variable containing the number of rows to be added.

ISPEXEC TBADD TELBOOK ORDER MULT(4)

where 4 is the number of rows to be added

CALL ISPLINK ('TBADD   ','TELBOOK ',' ','ORDER   ',ROWS);

where ROWS is a fixed binary variable containing the number of rows to be added.

CALL ISPLINK ('TBADD   ','TELBOOK ',' ',' ',8);

where 8 indicates the number of rows to be added.