L_FINDSPEC

Specify parameters for a find operation

xcall L_FINDSPEC(list_id, [string], [column], [length], [direction], [case], [type], [current], 
&     [wrap][, find_source])

Arguments

list_id

The ID of the list to search. (n)

string

(optional) The string for which to search. (a)

column

(optional) The first column to search. (n)

length

(optional) The length of the search area (a maximum of 256 characters). (n)

direction

(optional) The direction of the search: (n)

D_LFND_FRWD

Forward. (default)

D_LFND_RVRS

Reverse.

case

(optional) The case-sensitivity flag: (n)

D_LFND_CASE

Case sensitive. (default)

D_LFND_NOCASE

Case insensitive.

type

(optional) The flag that indicates what type of search will occur: (n)

D_LFND_CONTAIN

Search for a literal string. (default)

D_LFND_PATTERN

Search for a wildcard match.

D_LFND_EQ

Search for equality.

D_LFND_NE

Search for inequality.

D_LFND_GT

Search for a string greater than.

D_LFND_LT

Search for a string less than.

D_LFND_GE

Search for a string greater than or equal to.

D_LFND_LE

Search for a string less than or equal to.

current

(optional) The flag that indicates whether the current item is checked as part of the search: (n)

D_LFND_NOCURR

Do not test current item. (default)

D_LFND_CURR

Test current item.

wrap

(optional) The wrap-around find flag: (n)

D_LFND_WRAP

Search to end of list and then wrap around to start at beginning of list until search string is found or original item is re-encountered.

D_LFND_NOWRAP

Search only from the original item to the end of the list. (default)

find_source

(optional) If passed and non-zero, the flag that indicates whether the non-window data or the associated input window (display data) will be searched: (n)

D_LFND_DATA

Search non-window data. (default)

D_LFND_DISPLAY

Search display data.

Discussion

L_FINDSPEC specifies the parameters for subsequent find operations performed by a D_LFIND request in the L_PROCESS subroutine. This subroutine does not perform a search; it merely sets the parameters for subsequent find operations that will occur. If L_FINDSPEC is called more than once, the parameters that it sets are combined. If any of these parameters contradict one another, the parameter that is set last overrides the others.

For example, if you make the following calls to L_FINDSPEC:

xcall l_findspec(trans_lst, find_string,,,D_LFND_RVRS,,D_LFND_NE,,,D_LFND_DATA)
xcall l_findspec(trans_lst, find_string,,,,D_LFND_NOCASE,D_LFND_EQ,,,D_LFND_DISPLAY)

the following search parameters are defined: reverse direction, case insensitivity, search for equality, search display data.

If string is not passed, the previous find string is used. If none exists, a blank string is used.

If find_source is D_LFND_DATA,

the column argument specifies the position to start the search in the non-window data. If column is not passed or is zero, the previously specified value for column is used—even if this was specified in conjunction with D_LFND_DISPLAY. If there is no previous value for column, it is assumed to be 1. The value of the column argument is limited to the length of the non-window data. So, for example, if the non-window data has 60 columns, but column is passed as 61, only 60 are used.
the length argument specifies the length of the area to search. This area begins at the position specified by column. If length is not passed or is zero, the previously specified value for length is used—even if this was specified in conjunction with D_LFND_DISPLAY. If there is no previous value for length and
a data argument was passed to L_CREATE, the length of that argument is used as the initial value for length.
no data argument was passed to L_CREATE, the total number of characters in the associated input window is used as the initial value for length.

The length argument is limited to the number of characters from column to the end of the non-window data. So, for example, if length is passed as 17 and there are 15 characters from column to the end of the non-window data, only 15 characters are used.

If find_source is D_LFND_DISPLAY,

the column argument specifies the position to start the search in the associated input window. A value of 1 specifies the first column in the first row. A value of 2 specifies the second column in the first row, and so forth. If column is greater than the number of columns in the input window, the position wraps to subsequent rows. If column is not passed or is zero, the previously specified value for column is used—even if this was specified in conjunction with D_LFND_DATA. If there is no previous value for column, it is assumed to be 1. The column argument cannot be greater than the number of rows multiplied by the number of columns in the input window. So, for example, if the number of rows multiplied by the number of columns equals 60, but column is passed as 61, only 60 are used.
the length argument specifies the length of the area to search. This area begins at the position specified by column and continues by column, wrapping to subsequent rows if necessary. If length is not passed or is zero, the previously specified value for length is used—even if this was specified in conjunction with D_LFND_DATA. If there is no previous value for length and
a data argument was passed to L_CREATE, the length of that argument is used as the initial value for length.
no data argument was passed to L_CREATE, the total number of characters in the associated input window is used as the initial value for length.

The length argument is limited to the number of characters from column to the last column and row of the input window. So, for example, if length is passed as 17 and there are 15 characters from column to the last column and row of the input window, only 15 characters are used.

If find_source is not passed or is zero, the previously specified value for find_source is used. If there is no previous value for find_source, the value is assumed to be D_LFND_DATA if a data argument was passed to L_CREATE or D_LFND_DISPLAY if no data argument was passed to L_CREATE.

If direction is not passed, the previous direction value will be used. If no previous direction exists, the search will go forward.

You can pass the %I_FLDSTRPOS, %I_FLDSIZE, and/or %I_FLDDIM field information functions in place of passing column and length. An example of these functions used with the L_FINDSPEC subroutine is in the %I_FLDSTRPOS Examples.

If case is not passed, the previous case value will be used. If no previous case value exists, the search will be case sensitive.

If type is not passed, the previous find type is used. If no previous find type exists, D_LFIND searches for a literal string (D_LFND_CONTAIN). The following rules apply to the type flags:

If D_LFND_PATTERN is passed, the Synergy DBL S_MATCH subroutine is used to compare the search string with the designated area of the data argument passed to L_PROCESS.
If D_LFND_CONTAIN is passed, the intrinsic function %INSTR is used instead of S_MATCH.
If D_LFND_EQ, D_LFND_NE, D_LFND_GT, D_LFND_LT, D_LFND_GE, or D_LFND_LE is passed, the corresponding Synergy DBL comparison operator is used.

If current is not passed, the previous testing value will be used. If no previous value exists, D_LFIND won’t test the current item. The following rules apply to the current flags:

If D_LFND_CURR is passed, the search for a matching item during the next find begins with the current item.
If D_LFND_NOCURR is passed, the search begins with the next item in the specified direction.

Examples

The following example defines search parameters for the list identified by order_lst. If this is the first and only call to L_FINDSPEC, the L_PROCESS subroutine will search the list for a case-sensitive match for find_string (a literal string). The search will start with the item that follows the current one and search forward through the list. The entire data area passed to L_PROCESS will be searched. If needed, L_PROCESS will call the load method for this list to retrieve additional items.

xcall l_findspec(order_lst, find_string,,,,,,,D_LFIND_DATA)
req = D_LFIND
xcall l_process(order_lst, req, order_rec)