| 1 | Character string | Input | Char(*) |
| 2 | Length of character string | Input | Packed(3,0) |
| 3 | Starting position | Input | Packed(3,0) |
| 4 | Character pattern | Input | Char(*) |
| 5 | Length of character pattern | Input | Packed(3,0) |
| 6 | Translate characters | Input | Char((1) |
| 7 | Trim trailing blanks | Input | Char((1) |
| 8 | Wildcard character | Input | Char(1) |
| 9 | Character string result | Output | Packed(3,0) |
The Scan for String Pattern (QCLSCAN) API is used to scan a string of characters to see if the string contains a pattern. This function is similar to the scan function supported within source entry utility (SEU) and on the display presented by the Display Spooled File (DSPSPLF) command. In addition, the QCLSCAN API also allows you to specify a 1-byte character in the pattern that matches with any character in the string to be searched, and a start position, which allows you to search the same string more than once.
A typical use of the QCLSCAN API is to allow the work station user to retrieve all records that contain a specified pattern. For example, if the database has records with book titles, the work station user may want to retrieve all those books with the pattern CHICAGO in the title. The work station user enters CHICAGO on the device display. The application program reads the database, calling the QCLSCAN API at least once for each record to test for the pattern. The application program only processes the records that pass the test for the pattern CHICAGO.
Another alternative for this task is using the Open Query File (OPNQRYF) command. If you are searching an entire database member, the OPNQRYF command normally produces faster results. If you are searching a small subset of a member or the file is already open, QCLSCAN normally produces faster results.
Scanning a field can require many lines of code in a high-level language and can cause a significant amount of overhead. Calling the QCLSCAN API and passing it a parameter list may be a simpler and faster way to do the scan.
None.
A character field from 1 through 999 characters that contains the string to be scanned for the pattern.
The length of the string to be scanned. If this length is greater than the actual length of the string, unexpected results can occur.
The position in the string where the scan is to start. The position must be greater than zero and not greater than the string length. Normally this value is 1. If the same string has multiple sets of patterns, this allows the string to remain the same while only the start position is varied to find the additional patterns.
The pattern being scanned for.
The length of the pattern. If this length is greater than the actual length of the pattern, unexpected results can occur.
A variable that indicates to translate lowercase characters in the specified character string to uppercase characters. If this field contains a 1, the program translates lowercase characters of the string to uppercase before the scan using the coded character set identifier (CCSID) for the current job. If the translation cannot be done using the CCSID for the job, *CCSID37 is used. This does not change the user's data. Note that if 1 is specified and the pattern contains lowercase characters, a match never occurs. If 1 is specified, and the data to be searched contains noncharacter data (for example, packed or binary), unexpected results can occur.
A fixed-length pattern field filled (left-justified) by a variable number of characters. If this variable contains a 1, trailing blanks are trimmed from the end of the pattern before the scan is started.
A variable that you can specify in the pattern, in positions that should not be tested when scanning for a match. When this character appears in the pattern, any character in the data is considered a match. A value of blank indicates that all characters of the pattern take part in the scan. If the wildcard character is the first character in the pattern, an error will occur.
The value is returned to the user program when the call completes.
If the value returned is positive, the result is the position of the first character of the pattern in the string.
If the value returned is zero, the pattern was not found.
If the value returned is negative, one of the following errors occurred:
| -1 | The pattern is longer than the string. |
| -2 | The pattern length is less than 1. |
| -3 | The first character of the pattern is a wildcard character. |
| -4 | The pattern is blank and the trim trailing blanks parameter value is 1. |
| -5 | The starting position within the string is not valid. |
| Top | Program and CL Command APIs | APIs by category |