Examples: Scanning string patterns

These examples use the QCLSCAN API. A typical use of the QCLSCAN API is to allow the work station user to retrieve all records that contain a specified pattern.

Note: Read the Code license and disclaimer information for important legal information.

Example 1

Assume a 20-character database field containing only uppercase characters and the pattern 'ABC' is scanned for. The user program calls the QCLSCAN API for each database record read. The parameters would be as follows:

Field Name	Result
STRING	The 20-byte field to be scanned
STRLEN	20
STRPOS	1
PATTERN	'ABC'
PATLEN	3
TRANSLATE	'0'
TRIM	'0'
WILD	' '
RESULT	A value returned to your program

The following describes some fields and the results of the scan:

Scan  String                Result  Comments
 1    ABCDEFGHIJKLMNOPQRST   001
 2    XXXXABCXXXXXXXXXXXXX   005
 3    abcXXXXXXXXXXXXXXXXX   000    Translation not requested
 4    XXXABCXXXXXABCXXXXXX   004    First occurrence found; see note
 5    ABABABABBCACCBACBABA   000    Not found
 6    ABABABCABCABCABCABCA   005

Note: In scan 4, the string has two places where the pattern could have been found. Since the STRPOS value is 1, the first value (position 004) was found. If the value of STRPOS had been 4, the result would still have been 004. If the STRPOS value had been in a range of 5 through 12, the result would have been 012.

Example 2

Assume a 25-character database field containing only uppercase characters and a user program that will prompt for the pattern to be scanned, which will not exceed 10 characters. The work station user is allowed to enter 1 through 10 characters to search with and trailing blanks will be trimmed from the pattern. The program would call the QCLSCAN program for each database record read. The program parameters would be as follows:

Field Name	Result
STRING	The 25-byte field to be scanned
STRLEN	25
STRPOS	1
PATTERN	Varies
PATLEN	10
TRANSLATE	'0'
TRIM	'1'
WILD	' '
RESULT	A value returned to your program

The following describes some fields and the results of the scan:

Scan  String                     Pattern        Result  Comments
 1    ABCDEFGHIJKLMNOPQRSTUVWXY  'CDE        '   003
 2    ABCDEFGHIJKLMNOPQRSTUVWXY  'CDEFGH     '   003
 3    ABCDEFGHIJKLMNOPQRSTUVWXY  'CDEFGHIJKL '   003
 4    XXXXABCXXXXXXXXXXXXXXXXXX  'ABCD       '   000    Not found
 5    abcXXXXXXXXXXXXXXXXXXXXXX  'ABC        '   000    Not translated
 6    ABCXXXXXABC EXXXXXXXXXXXX  'ABC E      '   009
 7    XXXABCXXXXXABCXXXXXXXXXXX  'ABC        '   004    See note

Note: In scan 7, the string has two places where the pattern could be found. Since the STRPOS value is 1, only the first value (position 004) is found. If the value of STRPOS were 4, the result would still be 004. If the STRPOS value were in the range of 5 through 12, the result would be 012.

Example 3

Assume a 25-character database field containing either uppercase or lowercase characters. The user program prompts for the pattern to be scanned, which does not exceed 5 characters. The work station user can enter 1 through 5 characters to be found. The system trims trailing blanks from the pattern. If the user enters an asterisk (*) in the pattern, the asterisk is handled as a wild character. The program calls the QCLSCAN program for each database record read. The parameters are as follows:

Field Name	Result
STRING	The 25-byte field to be scanned
STRLEN	25
STRPOS	1
PATTERN	Varies
PATLEN	5
TRANSLATE	'1' (See note 1)
TRIM	'1'
WILD	'*'
RESULT	A value returned to your program

The following describes some fields and the results of the scan:

Scan  String                     Pattern      Result  Comments
 1    ABCDEFGHIJKLMNOPQRSTUVWXY  'CDE      '   003
 2    ABCDEFGHIJKLMNOPQRSTUVWXY  'C*E      '   003
 3    abcdefghijklmnopqrstuvwxy  'C***G    '   003    See note 1
 4    abcdefghijklmnopqrstuvwxy  'ABCD     '   001
 5    abcXXXXXXXXXXXXXXXXXXXXXX  'C*E      '   000    Not found
 6    XXXAbcXXXXXabcXXXXXXXXXXX  'ABC      '   004    See note 2
 7    ABCDEFGHIJKLMNOPQRSTUVWXY  '*BC      '  -003    See note 3
 8    ABCDEFGHIJKLMNOPQRSTUVWXY  '         '  -004    See note 4

Notes:

When field translation is specified (the TRANSLATE parameter is specified as '1'), the string is translated to uppercase characters before scanning occurs; the data in the string is not changed.
In scan 6, the string has two places where the pattern could have been found. Since the STRPOS value is 1, the first value (position 004) was found.
In scan 7, the wild character (*) is the first character in the trimmed pattern. Wild characters cannot be the first character in a pattern.
In scan 8, the trimmed pattern is blank.