TBGET—retrieve a row from a table

The TBGET service accesses a row in a table. If the NOREAD parameter is not specified, the row values are read into the function pool.

For tables with keys, the table is searched for the row to be fetched. 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, the row pointed to by the current row pointer (CRP) is fetched. You can use the TBSCAN, TBSKIP, TBBOTTOM, and TBTOP services to position the CRP.

The CRP is always set to point to the row that was fetched.

All variables in the row, including key and name variables, if any, are stored into the corresponding dialog variables. A list of extension variable names can also be retrieved.

Command invocation format


>>-ISPEXEC--TBGET--table-name--+--------------------+----------->
                               '-SAVENAME(var-name)-'   

>--+-------------------+--+--------+--+--------------------+---><
   '-ROWID(rowid-name)-'  '-NOREAD-'  '-POSITION(crp-name)-'

Call invocation format


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


>>-CALL--ISPLINK--('TBGETbbb'--,--table-name--,-+-var-name-+---->
                                                '-'b'------'   

>--,-+-rowid-name-+--,-+-'NOREADbb'-+--,-+-crp-name-+-);-------><
     '-'b'--------'    '-'b'--------'    '-'b'------'

Parameters

table-name: Specifies the name of the table to be read.
var-name: Specifies the name of a variable into which a list of extension variable names contained in the row will be stored. The list is enclosed in parentheses, and the names within the list are separated by a blank.
rowid-name: Specifies the name of a variable in which a number that uniquely identifies the row being accessed is to be stored. Later, this identifier can be specified in the ROW parameter of TBSKIP to cause the CRP to be positioned to the row. This identifier is not saved on permanent storage by TBSAVE or TBCLOSE. The variable must be an 8-byte character field.
NOREAD: Specifies that the variables contained in the requested row are not to be read into the variable pool.
crp-name: Specifies the name of a variable in which the row number pointed to by the CRP is to be stored. If the CRP is positioned to TOP, the row number returned is zero.
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: Keyed tables: The row specified by the value in the key variables does not exist in any row after the current row pointer, the CRP is set to TOP (ZERO).
Non-keyed tables: the CRP was at TOP and remains at TOP.
12: Table is not open.
16: Variable value has been truncated, or insufficient space was provided to return all extension variable names.
20: Severe error.

Example

In the keyed table TELBOOK, from a row having a specific key value, copy variable values into the respective function pool variables having the same names.

ISPEXEC TBGET TELBOOK

Set the program variable BUFFER to contain:

TBGET TELBOOK

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

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('TBGET   ','TELBOOK ');