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.