TBSKIP—move the row pointer

The TBSKIP service moves the current row pointer (CRP) of a table forward or backward by a specified number of rows and retrieves the row to which it is pointing unless the NOREAD parameter is specified.

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

Command invocation format


>>-ISPEXEC--TBSKIP--table-name--+----------------+-------------->
                                '-NUMBER(number)-'   

>--+--------------------+--+-------------------+---------------->
   '-SAVENAME(var-name)-'  '-ROWID(rowid-name)-'   

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

Call invocation format


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


>>-CALL--ISPLINK--('TBSKIPbb'--,--table-name--,-+-number-+------>
                                                '-'b'----'   

>--,-+-var-name-+--,-+-rowid-name-+--,-+-rowid-+---------------->
     '-'b'------'    '-'b'--------'    '-'b'---'   

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

Parameters

table-name

Specifies the name of the table to be used.

number

Specifies the direction and number of rows to move the CRP. This parameter must be a positive or negative integer. A positive integer moves the CRP toward the bottom of the table. A negative integer moves it toward the top. Zero is an allowable value that results in retrieving the current row.

For a call, this parameter must be a fullword fixed binary number.

A default skip of +1 exists if the ROW and NUMBER parameters are both omitted. When the ROW parameter is specified, no default skip of +1 is assumed if the NUMBER parameter is omitted.

var-name

Specifies the name of a variable into which a list of extension variable names contained in the row is 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 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.

rowid

Specifies the numeric value that uniquely identifies the row to be accessed. This value is obtained by using the ROWID(rowid-name) parameter.

A default skip of +1 exists if the ROW and NUMBER parameters are both omitted. When the ROW parameter is specified, no default skip of +1 is assumed if the NUMBER parameter is omitted.

NOREAD

Specifies that the variables contained in the requested row not 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: CRP would have gone beyond the number of rows in the table. This includes a table empty condition, with CRP set to TOP (zero). The rowid remains unchanged.
12: Table is not open.
16: Variable value has been truncated, or insufficient space is provided to return all extension variable names.
20: Severe error.

Example

In the table TELBOOK, move the current row pointer (CRP) to the next row. After the move, copy values from variables in that row to variables in the function variable pool having names that are the same as the names of the variables in the row.

ISPEXEC TBSKIP TELBOOK

Set the program variable BUFFER to contain:

TBSKIP TELBOOK

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

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

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