TBSARG—define a search argument

The TBSARG service establishes a search argument for scanning a table by using the TBSCAN or TBDISPL services. When TBSARG is used in conjunction with TBDISPL, the panel definition referred to by the TBDISPL request must contain a specification of ROWS(SCAN) on the )MODEL statement in the panel definition.

The direction of the scan, forward or backward, can be specified. The conditions that terminate the subsequent scan can also be specified.

The search argument is specified in dialog variables that correspond to columns in the table, including key variables. A value of null for one of the dialog variables means that the corresponding table variable is not to be examined during the search. However, the variable will be examined if the NOBSCAN parameter was specified when the variable was defined using the VDEFINE service.

Generally, TBSARG is used before TBSCAN or TBDISPL operations to establish search arguments for these operations. To set up a search argument, set table variables in the function pool to nulls by using TBVCLEAR. Next, set a value in each variable in the function pool that is to be part of the search argument. Then, issue TBSARG to establish this variables as the search argument to be used in subsequently requested TBSCAN or TBDISPL operations.

Use the NAMECOND list to establish search argument conditions. For any table variable that was given a value in the function pool, but is not specified in the NAMECOND list, the default is EQ.

Only extension variables can be included in the search argument. They are included by specifying their names in the name-list parameter. The values of these variables become part of the search argument. A null value in an extension variable is a valid search argument.

A search argument of the form AAA* means that only the characters up to the asterisk (*) 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 to be 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(*)

You can use either a DBCS or a MIX (DBCS and EBCDIC) 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 4-character DBCS string and ** is a single DBCS character representing the asterisk (*).
MIX (DBCS and EBCDIC) format string
```
eeee[DBDBDBDBDB]*
```
where eeee represents a 4-character EBCDIC string, DBDBDBDBDB represents a 5-character DBCS string, [ and ] represent shift-out and shift-in characters, and * is an asterisk in single-byte format.

The position of the current row pointer (CRP) is not affected by the TBSARG service.

TBSARG replaces all previously set search arguments for the specified table.

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--TBSARG--table-name--+--------------------+---------->
                                '-ARGLIST(name-list)-'   

   .-NEXT-----.                                  
>--+----------+--+---------------------------+-----------------><
   '-PREVIOUS-'  '-NAMECOND(name-cond-pairs)-'

Call invocation format


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


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

     .-'NEXTbbbb'-.                             
>--,-+-'b'--------+--,-+-name-cond-pairs-+-);------------------><
     '-'PREVIOUS'-'    '-'b'-------------'

Parameters

table-name

Specifies the name of the table for which an argument is to be established.

name-list

Specifies a list of extension variables, by name, whose values are to be used as part of the search argument. See Invoking the ISPF services for specification of name lists.

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.

name-cond-pairs

Specifies a list of names and conditions for determining the search argument conditions for scanning a table. There must be one condition specified for every name specified in the list. This list is used to associate a particular operator (condition) with a previously established scan argument. This parameter does not affect how the search arguments are established.

The name-cond-pairs syntax is as follows:

(name1,condition1,name2,condition2  ...)

Each "name" must be the name of a key field, name field, or name of an extension variable for the table. If the specified name does not exist, a severe error is encountered.

The "condition" specifies the scan condition for the "name" (column) to which it is paired. The search arguments are specified in dialog variables that correspond to columns in the table, and this determines the columns that take place in the search.

The valid condition-values are EQ, NE, LE, LT, GE, and GT. If some or all condition-value-pairs are not specified, the default is EQ for those columns participating in the search. Each argument and its associated operator are treated as separate entities, not as subfields of a single argument. The condition-values LE, LT, GE, and GT might be immediately followed by a date indicator. 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 from 1 to 7 indicating the offset within the variable value where the year begins. The year should be a 2-digit year, because a century value is inserted in front of the 2-digit year for compare purposes. These meanings are associated with the condition-values:

EQ: Specifies that the search is for an equal condition between the argument value and the row value. This is the default.
NE: Specifies that the search is for a row value not equal to the argument value.
LE: Specifies that the search is for a row value less than or equal to the argument value.
LT: Specifies that the search is for a row value less than the argument value.
GE: Specifies that the search is for a row value greater than or equal to the argument value.
GT: Specifies that the search is for a row value 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: All column variables are null, and the name-list parameter was not specified; no argument is established.
12: Table is not open.
20: Severe error.

Examples

Establish a search argument to be used by a TBSCAN operation of the table TELBOOK. Assume that LNAME and ZIPCODE are columns in table TELBOOK. Specify a scan direction of forward and terminate the scan when the row value for the LNAME column is equal to "JOHNSON" and the ZIPCODE column is greater than 08007.

Invoke TBVCLEAR for table TELBOOK
Set variable LNAME to JOHNSON
Set variable ZIPCODE to 08007
Issue this request:

ISPEXEC TBSARG TELBOOK NEXT NAMECOND(LNAME,EQ,ZIPCODE,GT)

Set the program variable BUFFER to contain:

TBSARG TELBOOK NEXT NAMECOND(LNAME,EQ,ZIPCODE,GT)

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

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('TBSARG  ','TELBOOK ',' ','NEXT    ',
              '(LNAME,EQ,ZIPCODE,GT)');

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 this TBSARG request:

ISPEXEC TBSARG DATETBL NEXT NAMECOND(DATE1,GTY1)