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.