9.186 SCANSTRING
Note: Built-In Function Rules Usage Options
Scans a string for the first occurrence of a pattern.
Arguments
This table shows the arguments used in this function.
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
A
|
Req
|
String to be scanned
|
1
|
Unlimited
|
|
|
|
2
|
A
|
Req
|
Pattern to be located. Enter in upper and/or lower case as required.
This parameter is ignored for RDMLX Lists. Any value can be specified. Whatever the list entry length is, it will be saved correctly.
|
1
|
Unlimited
|
|
|
|
3
|
N
|
Opt
|
Position to start scan Range: 1 - maximum possible length of the string to be scanned.
Default: 1
|
1
|
11
|
0
|
0
|
|
4
|
A
|
Opt
|
Compare in uppercase?
1 = No, compare all cases
0 = Yes, compare upper case.
Default: 1
See Note.
|
1
|
1
|
|
|
|
5
|
A
|
Opt
|
Trim trailing pattern blanks?
1 = Yes
0 = No
Default: 1 -trim trailing blanks from wild card pattern.
|
1
|
1
|
|
|
|
6
|
A
|
Opt
|
Wild card in scan pattern Values:
Blank = no wild card activated.
Non-blank = wild card activated.
Default: no wild card.
Do not use a blank as the left most character of the pattern. An error will result if you do this.
|
1
|
1
|
|
|
|
Return Values
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
N
|
Req
|
Position of first occurrence in string or error code.
Any one of these values may be returned:
+p = Occurrence of pattern found at position "p"
0 = Pattern not found in string to be scanned.
-1 = Error. Pattern is longer than string.
-2 = Error. Pattern length is less than 1.
-3 = Error. First char in pattern is wild.
-4 = Error. Pattern is blank and trim requested.
-5 = Error. Starting position is invalid .
|
1
|
3
|
0
|
0
|
|
Note
The result is converted to upper case for string comparison. Following is an example of some results.
|
String to search for
|
Upper Case parameter?
|
Result
|
Found?
|
|
ABC
|
1 (No)
|
123abc4
|
Yes
|
|
123ABC4
|
Yes
|
|
ABC
|
0 (Yes)
|
123abc4
|
No
|
|
123ABC4
|
Yes
|
|
abc
|
1 (No)
|
123abc4
|
No
|
|
123ABC4
|
No
|
|
abc
|
0 (Yes)
|
123abc4
|
Yes
|
|
123ABC4
|
No
|
|
Example
This code searches for the string "where" in the text "find where it exists".
Function Options(*DIRECT)
Define Field(#PATTERN) Reffld(#SKILCODE) Label('Find Pattern') Default(WHERE)
Define Field(#STARTPOS) Reffld(#STD_IDNOS) Label('Start Pos') Default(1)
Override Field(#STD_FLAG) Label('Case (1/0)?') Default('''1''')
Define Field(#TRIM) Reffld(#STD_FLAG) Label('Trim (1/0)') Default('''1''')
Define Field(#WILD) Reffld(#STD_FLAG) Label('WildCard?') Default('')
Override Field(#STD_IDNOS) Label('Occurs at Pos.') Edit_Code(L)
Change Field(#STD_TEXTS) To('''Find where it exists''')
Begin_Loop
Request Fields((#STD_TEXTS *LOWER) #PATTERN #STARTPOS #STD_FLAG #TRIM #WILD (#STD_IDNOS *OUT))
Use Builtin(SCANSTRING) With_Args(#STD_TEXTS #PATTERN #STARTPOS #STD_FLAG) To_Get (#STD_IDNOS)
End_Loop
