Domain: String functions
The function SEARCH-LIST-INDEX( ) searches a list variable for a string or for a regular expression which has been formed in accordance with POSIX rules. The return value indicates the number of the first list element containing this expression or search string.
Normally, if this type of operation is executed using a loop in the INDEX function, it requires a considerable amount of time. The introduction of this predefined function reduces this execution time considerably since the search is performed in a single step.
Format
SEARCH-LIST-INDEX( ) |
LIST-VARIABLE-NAME = string_expression1 ,PATTERN = string_expression2 ,BEGIN-INDEX = 1 / arithm_expression ,END-INDEX = *LAST / arithm_expression ,BEGIN-COLUMN = 1 / arithm_expression ,END-COLUMN = *LAST / arithm_expression ,PATTERN-TYPE = *STRING / *REGULAR-EXPRESSION ,DIRECTION = *FORWARD / *REVERSE |
Result type
INTEGER
Input parameters
LIST-VARIABLE-NAME= string_expression1
Designates the variable consisting of a list of strings.
PATTERN = string_expression2
Designates the search string or regular expression for which a sequential search operation is to be performed within the list variable specified in LIST-VARIABLE-NAME.
BEGIN-INDEX =
Specifies the first list element or index at which the search is to be started.
List elements which have a smaller index are not checked. If the specified index is greater than the number of elements, the value “0” is returned, i.e. “not found”.
BEGIN-INDEX = 1
The search starts with list element 1, i.e. at the beginning of the list.
BEGIN-INDEX = arithm_expression
The search starts at the specified list element.
END-INDEX =
Specifies the last list element or index up to which the search is to be performed.
If nothing is found up to and including this index, the value “0” is returned.
END-INDEX = *LAST
The search ends with the last list element.
END-INDEX = arithm_expression
The search ends with the specified list element.
BEGIN-COLUMN =
The search operation is restricted to a certain range of columns and is to start at a specified column.
BEGIN-COLUMN indicates the character in the string at which the search for the search string specified in PATTERN is to start in the element involved.
If PATTERN-TYPE = *REGULAR-EXPRESSION is specified, the ‘^’ at the beginning of the search string is no longer part of the actual search string, but is the position exactly in front of the value specified in BEGIN-COLUMN.
The string being searched is empty if the list element contains fewer characters than specified for BEGIN-COLUMN.
BEGIN-COLUMN = 1
The search starts at column 1, i.e. the entire list element is searched.
BEGIN-COLUMN = arithm_expression
The search starts at the specified column, i.e. character, of the list element.
END-COLUMN =
The search is restricted to a certain column range and is to end at a certain column. END-COLUMN indicates the character in the string at which the search for the string specified in PATTERN is to end in the element involved. The characters of the list element which follow the position specified in END-COLUMN are ignored during the search.
If PATTERN-TYPE = *REGULAR-EXPRESSION is specified, the “$” character at the end of the searched string corresponds to exactly the position after the value specified in END-COLUMN (i.e. this character no longer belongs to the actual search string) or to the end of the list element if the list element contains fewer characters than specified in END-COLUMN.
END-COLUMN = *LAST
The search ends at the end of the string or at the end of the list element.
END-COLUMN = arithm_expression
The search ends at the specified column or character in the list element.
PATTERN-TYPE =
Specifies the data type of the search string or regular expression being searched for.
PATTERN-TYPE = *STRING
The data type is STRING.
PATTERN-TYPE = *REGULAR-EXPRESSION
The data type corresponds to that of a regular expression created in accordance with POSIX rules. This replaces any string, even an empty string.
DIRECTION =
Designates the direction in which the search is to take place in the list variable.
DIRECTION = *FORWARD
The search starts at the list element specified in BEGIN-INDEX and ends at the list element specified in END-INDEX.
DIRECTION = *REVERSE
The search runs in the opposite direction, i.e. it begins at the list element specified in END-INDEX and ends at the list element specified in BEGIN-INDEX.
Result
Positive integer indicating the first list element containing the search string specified in PATTERN. This value is greater than or equal to the value specified in BEGIN-INDEX and smaller than or equal to the number of list elements in the specified variable.
0
The search string was not found.
Error messages
SDP0492 NULL BYTE (X'00') NOT ALLOWED IN PATTERN OPERAND AND LIST ELEMENTS
SDP0493 VALUE OF OPERANDS BEGIN-INDEX, END-INDEX, BEGIN-COLUMN AND END-
COLUMN MUST BE GREATER THAN ZERO
SDP0494 SYNTAX ERROR IN REGULAR EXPRESSION FOR OPERAND PATTERN
SDP1008 VARIABLE/LAYOUT '(&00)' DOES NOT EXIST
SDP1096 VARIABLE '(&00)' MUST BE A LIST OF TYPE STRING OR ANY CONTAINING
ONLY STRING VALUES
Example 1
/DECLARE-VARIABLE FILE-NEW(TYPE=*STRING), MULTIPLE-ELEMENTS=*LIST
/READ-VARIABLE *LIST(FILE-NEW), INPUT=*SYSDTA
First line in the file
Second
Third line in the file
4.
5. ........
6. in the file
7. ... in the ...
*END-OF-CMD
/MATCH = 0
/REPEAT
/ MATCH=SEARCH-LIST-INDEX('FILE-NEW',PATTERN='line', BEGIN-INDEX=MATCH+1)
/ SHOW-VARIABLE MATCH
/UNTIL (MATCH == 0)
Output
MATCH = 1 MATCH = 3 MATCH = 0
In this example, SEARCH-LIST-INDEX( ) is used to search a list variable for a string (‘line’) starting at a certain character. The REPEAT loop ensures that the value for BEGIN-INDEX is incremented by 1 until the entire file has been searched.
If the following expression is included in the REPEAT loop, the output is different:
Example 2
/MATCH=SEARCH-LIST-INDEX('FILE-NEW', -
/ PATTERN =' in ', -
/ BEGIN-COLUMN=7,-
/ END-COLUMN=11)
/SHOW-VARIABLE MATCH
Output
MATCH = 7
In this example the list variable FILE-NEW (see example 1) is searched through for the string “ in ”. The search is limited to columns 7 up to and including column 11. Only list element 7 fulfills the search conditions, but list elements 1, 3 and 6 do not.
Example 3
/DECLARE-VARIABLE RECORD-LIST(TYPE=*STRING), MULTIPLE-ELEMENTS=*LIST
/READ-VARIABLE *LIST(RECORD-LIST), INPUT=*SYSDTA
WIEDEMANN BERNHARD 64528
BACHMANN MICHAEL 37214
ARTMANN HELMUT 74634
HEUBACH HUGO 97884
BACH ANDREAS 12012
KIRSCHNER ANITA 76325
*END-OF-CMD
/NAME = 'BACH'
/MATCH=SEARCH-LIST-INDEX('RECORD-LIST',
/ PATTERN ='^&NAME. ', -
/ PATTERN-TYPE=*REGULAR-EXPRESSION -
/ )
/NUMBER = INTEGER(EXTRACT-FIELD(RECORD-LIST#MATCH,3))
/WRITE-TEXT '&NAME. HAS NUMBER &NUMBER.'
Output
BACH HAS NUMBER 12012
RECORD-LIST is searched for the name ‘BACH‘ and one hit is reported. ‘HEUBACH‘ and ‘BACHMANN‘ do not satisfy the criteria for the search string because PATTERN-TYPE = *REGULAR-EXPRESSION was specified: the first does not start with a “B” and the second does not end with a blank after ‘BACH’.
Example 4
/DECLARE-VARIABLE A-LIST (TYPE=*STRING), MULTIPLE-ELEMENTS=*LIST
/ A-LIST#1 = 'ACTIVE '
/ A-LIST#2 = 'WAITING '
/ A-LIST#3 = 'INACTIVE'
/ A-LIST#4 = 'ABORTED '
/ A-LIST#5 = 'ACTIVE '
/ A-LIST#6 = 'LOCKED '
/ A-LIST#7 = 'WAITING '
/ A-LIST#8 = 'ACTIVE '
/ A-LIST#9 = 'ACTIVE '
/ A-LIST#10 = 'INACTIVE'
/WAITING-IDX=SEARCH-LIST-INDEX('A-LIST','WAITING',DIRECTION=*FORWARD)
/SHOW-VARIABLE WAITING-IDX
WAITING-IDX = 2
/WAITING-IDX=SEARCH-LIST-INDEX('A-LIST','WAITING',DIRECTION=*REVERSE)
/SHOW-VARIABLE WAITING-IDX
WAITING-IDX = 7
The “WAITING” string is searched in list variable A-LIST. The forward search reports list element 2 as a hit. The reverse search reports list element 7 as a hit.