%L_FINDWND

Construct a find window for L_SELECT

window_id = %L_FINDWND(list_id, window_name, field_name, [prompt], [search]
&           [, nofindspec])

Return value

window_id

The ID of the created window or zero if an error occurred. (^VAL)

Arguments

list_id

The ID of the list. (n)

window_name

A unique name for the window to be constructed (a maximum of 15 characters). (a)

field_name

The name of the field on which to base the find. (a)

prompt

(optional) The prompt for input. (a)

(optional) The true/false flag that, when returned, will indicate whether an existing window_name was found. (n)

nofindspec

(optional) The true/false flag that indicates whether this function should perform without calling L_FINDSPEC. (n)

Discussion

%L_FINDWND creates an input window for a find string, based on a field within the input window associated with a list. The resulting input window is designed to be passed to L_SELECT as the find_window argument.

By using this function, you assure that the data storage format of the input find string will match that of the target field, including length, type, and enumeration. This function also optionally calls L_FINDSPEC to establish the position and length of the target field for the find. The assumption here is that the optional data passed to L_SELECT matches the input window data structure containing the target field. Even if this is not a correct assumption, however, you can call L_FINDSPEC subsequently to adjust.

Window_name must be a unique window name. If search is passed and a window with window_name already exists, search is returned true and no construction of the window occurs (L_FINDSPEC can still be called). Search is returned false if the window did not already exist. If search is not passed and the window already exists, a fatal error occurs.

Field_name must be the name of an input field within the input window associated with the list indicated by list_id. If not, a fatal error occurs.

If prompt is passed, it will be used as the prompt for the input field in the constructed window. Otherwise, the default find prompt will be used, which is defined in the message file (syntxt.ism), facility DTK, mnemonic FINDPRMPT. Prompt is positioned at row 2, column 2 of the constructed window, and the field immediately follows (one space is added to the trimmed value of the default prompt, if used—if prompt is passed, it must contain any trailing spaces desired).

The window is sized to have one empty row and one empty column before and after the input field (including prompt).

The input field inherits all attributes of the target field, except for the following:

Prompt position
Prompt
Field position
Break (always false)
Auto (always false)
Allow (unless enumerated)
Range

The constructed window only contains an input field for the find string itself. It does not provide access to the other find parameters. (See the information on the find_window, find_init, and find_column arguments in L_SELECT.)

By default, this function calls L_FINDSPEC to establish the position and length of the target field for the find. If nofindspec is passed and true, this will not occur.

You do not need to declare this function to use it. It is defined in tools.def.

Examples

In the following example, %L_FINDWND is called to construct an input window named “i_findacct” for entering an account number to find. If a window by that name already exists, the existing window will be used instead and srch will be returned true.

findid = %l_findwnd(acct_list, "i_findacct", "account_num","Find account ", srch)
xcall u_window(D_PLACE, findid, 12, 40, D_REMOVE, findid)
xcall l_select(acct_list, req, acct_rec,,,,,,,,, findid)

The account number field will inherit attributes from the “account_num” field in the input window associated with the list whose ID is acct_lst. The prompt for the field will be “Find account.”

L_FINDSPEC will be called by %L_FINDWND to establish the position and length of the find data as the position and length of the “account_num” field within a structure in the list’s input window.

Next, U_WINDOW is called to establish the placement of the resulting window. Then the window is removed so that it will not be visible until needed. The ID is passed to L_SELECT so that the window can be “popped up” when the user selects the S_FIND menu entry.