This week's API by Example from Carsten Flensburg provides program CBX103, which scans a file for a string and prints a report listing the field, field attributes, and the position within the field for all the records in which the search string appears. A small test program, CBX103T, lets you test the main by entering a file and library name, search string, and whether the search is case-sensitive or not.

Here's some sample output from test program CBX103T showing a search for the string INVP in file TESTPF in library CHUCK:

File     Library  Scan value         RRN   Field name  Pos.  Field value
TESTPF   CHUCK    INVP                11   ATFILE        3   CSINVP

The above shows that the string was found in record 11, field ATFILE, starting in position 3 of that field.

Program CBX103 shows not only how to use the QUSLFLD to retrieve fields and their attributes in a record format, but it also shows how to use the user space and national language support APIs, as well as several C library functions. Here's a list of the APIs and functions used in the program:

List Fields (QUSLFLD)
This API generates a list of fields within a specified file record format name and places the list in a specified user space. You can use the QUSLFLD API only with database file types, such as *PF, *LF, and *DDMF, and device file types, such as *ICFF and *PRTF.
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/quslfld.htm

Create User Space (QUSCRTUS)
This API creates a user space in either the user domain or the system domain.
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/quscrtus.htm

Retrieve Pointer to User Space (QUSPTRUS)
QUSPTRUS retrieves a pointer to the contents of a user-domain user space.
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/qusptrus.htm

Delete User Space (QUSDLTUS)
This API deletes user spaces created with the Create User Space (QUSCRTUS) API.
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/qusdltus.htm

Convert Case (QlgConvertCase)
The QlgConvertCase) API can be used to convert character data to either uppercase or lowercase.
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/QLGCNVCS.htm

C library functions:

Open record file (_Ropen)
This opens the record file specified as defined by the keywords in the mode parameter. If the file does not exist it will not be created.

Close record file (_Rclose)
This API closes the previously opened record file identified by the file pointer parameter.

Read first record (_Rreadf)
This reads the first record in the access pass specified by file pointer in either arrival or keyed order.

Read next record (_Rreadn)
This API reads the next record in the access pass specified by file pointer in either arrival or keyed order.

The C functions are documented at
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/books/c4156071.pdf.

The above source code was written by Carsten Flensburg. For questions regarding this tip, contact Carsten at mailto:flensburg@novasol.dk.