Examples: Scanning string patterns

These examples use the Scan for String Pattern (QCLSCAN) API to retrieve all database records that contain a pattern.

Example 1

Assume that a 20-character database field contains only uppercase characters and the pattern 'ABC' is scanned for. The user program calls the QCLSCAN API for each database record that is read. The parameters follow.

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

Some fields and the results of the scan follow:

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 can be found. Because the STRPOS value is 1, the first value (position 004) is found. If the STRPOS value is 4, the result is still 004. If the STRPOS value is in a range of 5 through 12, the result is 012.

Example 2

Assume that a 25-character database field contains only uppercase characters. The user program prompts for the pattern that does not exceed 10 characters to be scanned for. The workstation user can enter 1 through 10 characters. The system trims trailing blanks from the pattern. The program calls the QCLSCAN API for each database record that is read. The parameters follow.

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

Some fields and the results of the scan follow:

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 can be found. Because the STRPOS value is 1, only the first value (position 004) is found. If the STRPOS value is 4, the result is still 004. If the STRPOS value is in a range of 5 through 12, the result is 012.

Example 3

Assume that a 25-character database field contains either uppercase or lowercase characters. The user program prompts for the pattern that does not exceed 5 characters to be scanned for. The workstation user can enter 1 through 5 characters. 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 API for each database record that is read. The parameters follow.

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

Some fields and the results of the scan follow:

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 can be found. Because the STRPOS value is 1, the first value (position 004) is 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.