TBSCAN—search a table

The TBSCAN service searches a table for a row with values that match an argument list. The argument list can be established by use of the TBSARG service, or specified in the name-list for TBSCAN.

The search can be either in a forward or a backward direction. A forward search starts with the row after the current row and continues to the end of the table. A backward search starts with the row before the CRP and continues to the top of the table. If a match is found, the CRP is set to that row. The row is retrieved unless the NOREAD parameter is specified. All variables in the row, including keys and extension variable, if any, are stored in the corresponding variables in the function pool. A list of extension variable names can also be retrieved.

Use of the name-list parameter is optional. If specified, it overrides the search argument set by the TBSARG service for this search only. The values of all variables specified in the name-list parameter become part of the search argument. Key, name, and extension variables can be specified.

A value of the form AAA* means that only the characters up to the "*" are compared. This is called a generic search argument. A generic search argument is specified by placing an asterisk in the last nonblank position of the argument. Asterisks embedded in the argument are treated as data. For example, to perform a generic search for a row value of DATA*12, the generic search argument is:

DATA*12*

The first asterisk is part of the search argument. The second asterisk designates the argument as a generic search argument. In a CLIST, this technique can be used to set a variable to a literal value that ends with an asterisk:

SET &X = AAA&STR(*)

A null value in a variable is a valid search argument.

You can use either a DBCS or a MIX (DBCS and EBCDIC combined) format string as a search argument. If either is used as a generic search argument, it must be specified as follows:

DBCS format string
```
   DBDBDBDB**
```
where DBDBDBDB represents a DBCS string and ** is a single DBCS character representing the asterisk (*).
MIX (DBCS and EBCDIC combined) format string
```
   eeee[DBDBDBDBDB]*
```
where eeee represents an EBCDIC string, DBDBDBDB represents a DBCS string, [ and ] represent shift-out and shift-in characters, and * is an asterisk in single-byte format.

Comparisons between the row values and the argument list are always done on a character basis. That is, the values are considered character data, even if they represent numbers.

Command invocation format


>>-ISPEXEC--TBSCAN--table-name--+--------------------+---------->
                                '-ARGLIST(name-list)-'   

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

   .-NEXT-----.                                       
>--+----------+--+--------+--+--------------------+------------->
   '-PREVIOUS-'  '-NOREAD-'  '-POSITION(crp-name)-'   

>--+--------------------------------+--------------------------><
   '-CONDLIST(condition-value-list)-'

Call invocation format


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


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

                                       .-'NEXTbbbb'-.   
>--,-+-var-name-+--,-+-rowid-name-+--,-+-'b'--------+----------->
     '-'b'------'    '-'b'--------'    '-'PREVIOUS'-'   

>--,-+-'NOREADbb'-+--,-+-crp-name-+----------------------------->
     '-'b'--------'    '-'b'------'   

>--,-+-condition-value-list-+-);-------------------------------><
     '-'b'------------------'

Parameters

table-name

Specifies the name of the table to be searched.

name-list

Specifies a list of key, name, or extension variables, by name, whose values are to be used as the search argument. Use of the name-list parameter is optional. If specified, it overrides the search argument set by the TBSARG service for this search only. If the name-list parameter is omitted, a search argument must have been established by a previous TBSARG command. Otherwise, a severe error occurs. See Invoking the ISPF services for specification of name lists.

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 will be enclosed in parentheses, and the names within the list will be 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.

NEXT

Specifies that the scan is to proceed from the row following the current row to the bottom of the table. This is the default.

PREVIOUS

Specifies that the scan is to proceed from the row preceding the current row to the top of the table. To scan the bottom row, CRP must be positioned to TOP.

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 to zero.

condition-value-list

Specifies a list of values for determining when the scan should end. Each condition-value relates to a search argument for a column or extension variable in the table as specified in the ARGLIST parameter. This parameter is ignored if no ARGLIST parameter is specified. The operators specified in the condition-list correspond one-to-one with the names in the ARGLIST. If there are extra operators, a severe error condition is encountered.

The name-list and condition-value-list syntax is:

ARGLIST(name1,name2, ....)

CONDLIST(condition1, condition2, ...)

The valid condition-values are EQ, NE, LE, LT, GE, and GT. If there are fewer condition-values than search arguments the default is EQ for those columns. Each argument and its associated operator are treated as separate entities, and not as subfields of a single argument.

The condition-values LE, LT, GE, and GT can have a date indicator immediately following them. The date indicator is Yn, where Y indicates that the variable name associated with the condition-value is a date, and n is an integer between 1 and 7 indicating the offset within the variable value where the year begins. The year should be a 2-digit value because a century value is inserted in front of the 2-digit year for comparison purposes.

These meanings are associated with the condition-values:

EQ: Specifies that the scan is to end when an equal condition exists between the argument value and the row value. This is the default.
NE: Specifies that the scan is to end when the row value is not equal to the argument value.
LE: Specifies that the scan is to end when the row value is less than or equal to the argument value.
LT: Specifies that the scan is to end when the row value is less than the argument value.
GE: Specifies that the scan is to end when the row value is greater than or equal to the argument value.
GT: Specifies that the scan is to end when the row value is greater than the argument value.
Yn: Can be used with LE, LT, GE, and GT. It must immediately follow one of the four allowed condition-values. The Y indicates that the paired variable name is a date variable that needs a century value added to a 2-digit year so that dates can be compared correctly. The n is a number from 1 to 7 that gives the offset within the variable value where the year is located.

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: Row does not exist, no match was found; CRP is 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.

Examples

Example 1

For the table TELBOOK:

Move table TELBOOK's CRP to the row that fulfills the search argument as specified in a preceding TBSARG operation. For an example of TBSARG, see the example in the TBSARG description. Copy values from variables in that row to function pool variables whose names match those of the table variables.

ISPEXEC TBSCAN TELBOOK

Set the program variable BUFFER to contain:

TBSCAN TELBOOK

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

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

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

Example 2

For the table TELBOOK:

Use the TBSCAN service to position the CRP of table TELBOOK to the row containing the name JOHNSON in variable LNAME, and the zip code 08007 in variable ZIPCODE. Copy values of the variables in that row to function pool variables whose names match those of the table variables.

Set function pool variable LNAME to JOHNSON.
Set function pool variable ZIPCODE to 08007.
Issue this request:

ISPEXEC TBSCAN TELBOOK ARGLIST(LNAME,ZIPCODE)

Set the program variable BUFFER to contain:

TBSCAN TELBOOK ARGLIST(LNAME,ZIPCODE)

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

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('TBSCAN  ','TELBOOK ','(LNAME,ZIPCODE)');

If the return code is 0, the row was found and values were copied from the row variables to function pool variables.

Example 3

Establish a search argument to be used by a TBSCAN operation of the table DATETBL. Assume DATE1 to be a name variable in table DATETBL and that the dates are in a yy/mm/dd format. Specify a scan direction of forward and terminate the scan when the row value of DATE1 is greater than 99/01/31.

Invoke TBVCLEAR for table DATETBL
Set variable DATE1 to 99/01/31

Issue these requests:

ISPEXEC TBSARG DATETBL NEXT NAMECOND(DATE1,GTY1)
ISPEXEC TBSCAN DATETBL