ISPF Tables – Searching for the Right Row

When working with ISPF Tables, with or without keys, finding the row with the data that you need to work with can be challenging using whatever programming language you choose. The examples below will use REXX to invoke the ISPF table services.

There are several way to approach this – the brute force method and the table services method.

The Brute Force Method

With the brute force method, the code moves through the ISPF table from the top, using TBTOP, to the bottom using TBSKIP.

By default, TBSKIP will populate REXX variables for all the ISPF table row variables which then makes it easy to compare the table row variables to find the row that you want to work with.

Something like this:

‘tbtop table’	/* start at the top of the table */
key = ‘ABC’		/* we want rows with ABC in the K1 field */
Do forever
‘tbskip table’		/* skip to the next record */
If rc > 0 then leave	/* at the end of the table */
If k1 /= key then iterate		/* not the row we are looking for */
. . . process the row
/* continue the do forever loop looking for other rows with the value we want */
/* or use the leave statement to exit the do forever loop */
end

This isn’t that bad and is reasonably easy to understand, but it is not the most efficient especially if the table has a large number of rows. And it works whether the table has keys or not and makes it easy to look for all rows with the desired variable match.

Table Services Method

The use of the ISPF Table Services at first looks more complex, and it is, but the system overhead can be significantly reduced for ISPF tables with a large number of rows.

The approach is the same with or without keys – with the exception that if you use keys there will not be any duplicated rows.

Tables with Keys

For tables with Keys the process is simplified a little as you will see when you compare this example with the example for Tables without Keys below.

In this example we will be looking for a variable key that matches a row variable that is also a table key.

‘tbtop table’
‘tbvclear table’		/* clear out rexx variables for the table rows */
key = ‘ABC’			/* we want rows with ABC in the K1 field */
‘tbsarg table namecond(key,eq)’ 		/* define search arguments */
                            /* variable key must be equal */
‘tbscan table’					/* scan for our key */
if rc = 0 then do		/* we found our row *?
    */ process the row */
    end

For this we start at the top of the table using tbtop, then use the tbvclear service to clear all the REXX variables that match the ISPF table row variables.

Next we set the row variable, key, to the value we are looking for. ABC in this case.

The tbsarg establishes the scan criteria, in this case the NAMECOND defines that the row variable key must be equal to the current value of the key REXX variable.

The tbscan does the actual table search and returns with a return code of 0 if the row if found and 8 if not found. If the return code is 0 then process that row, and if not then continue doing something else.

Tables without Keys

For tables without keys, it is possible that there are multiple rows with the desired key value. That complicates the search process.

‘tbtop table’
do forever
‘tbvclear table’		/* clear out rexx variables for the table rows */
key = ‘ABC’			/* we want rows with ABC in the K1 field */
‘tbsarg table namecond(key,eq)’ 		/* define search arguments */
                            /* variable key must be equal */
‘tbscan table’					/* scan for our key */
if rc > 0 then leave	/* no row found so leave the do forever loop */
    */ process the row */
end		/* continue do forever until tbscan rc > 0 */

When working with a table without keys it is very possible that there are multiple rows with the same key value.

We always start at the top of the table using tbtop.

The do forever loop is used to check for all rows with the desired key value.

The first thing in the do forever loop is the tbvclear to clear out all the REXX variables in the table row.

Next we set the row variable, key, to the value we are looking for. ABC in this case.

The tbsarg establishes the scan criteria, in this case the NAMECOND defines that the row variable key must be equal to the current value of the key REXX variable.

The tbscan does the actual table search and returns with a return code of 0 if the row if found and 8 if not found. . If the return code is 0 then process that row, and if not then leave the do forever loop.

Using TBSCAN Only - if Not Using TBDISPL ROWS(SCAN)

An alternate approach is to eliminate the tbsarg and use tbscan only by:

1. delete the tbsarg statement
2. update tbscan thus: ‘tbscan table arglist(key)’

This is quicker, and more efficient, if you are not using ISPF Table Display (TBDISPL) services with ROWS(SCAN).

Notes:

1. These snippets "assume" the table has been created and is open.
2. The use of tbget is not required as the tbscan does that automatically.