L_SELECT

Do list selection processing

WSupported on Windows
USupported on Unix
VSupported on OpenVMS
NSupported in Synergy .NET
xcall L_SELECT(list_id, request, [data], [disabled], [skip_disabled], [find_prompt], 
&     [find_length], [character], [select_column], [help_id], [pre_input_routine], 
&     [find_window], [find_init], [find_column], [wait_time]
&     [, a_methoddata1, ..., a_methoddata20])

Arguments

list_id

The ID of the list. (n)

request

The request flag. Passed requests that L_SELECT can accept are the same requests honored by L_PROCESS. (See L_PROCESS for more information on these requests.) These are the returned requests that L_SELECT can generate: (n)

D_LNOP

Item was selected, or unknown menu entry was selected.

D_LLOADBOT

Need an item at the bottom.

D_LLOADTOP

Need an item at the top.

D_LABORT

Cannot proceed; delete the list.

data

(optional) The associated non-window data. (a)

disabled

(optional) The disabled item status. (n)

skip_disabled

(optional) The true/false flag that indicates whether disabled items will be skipped. (n)

find_prompt

(optional) The prompt to the user to enter a string for which to search. (a)

find_length

(optional) The maximum length (between 1 and 256 characters) allowed for a search string. (n)

character

(optional) The ASCII value of the character the user typed. (n)

select_column

(optional) The selection column ID. (n)

help_id

(optional) The help identifier. (a)

pre_input_routine

(optional) The name of a subroutine to call before character input is performed. (a)

find_window

(optional) The ID of the input window for find. (n)

find_init

(optional) The true/false flag that indicates whether L_SELECT will initialize the find window. (n)

find_column

(optional) The input column for find. (n)

wait_time

(optional) The time-out limit for I/O processing to be completed before returning to the calling routine. (n)

D_FOREVER or -1

Never time out.

D_GLOBAL or -2

Use the global value (see g_wait_time). (default)

D_IMMEDIATE or 0

Time out immediately.

n

Wait up to n seconds (where n is a positive value) for I/O processing to be complete.

a_methoddata1 through a_methoddata20

(optional) Up to 20 additional data arguments that can be passed to L_SELECT. L_SELECT, in turn, passes them directly to each field’s methods. This allows you to communicate additional information to your input field methods. (any)

Discussion

L_SELECT provides selection processing similar to S_SELECT, except using a list. The list (or some part of it) is presented to the user, and the user can navigate the list, find specific values, and finally, select an item. The advantage to using a list is that it can be virtually any length, but only the necessary items are loaded.

If the list is an ActiveX list, when a user selects a cell in the list, by default only the cell is highlighted. You can, however, instruct Toolkit to highlight the entire row by setting the RowMode property to any non-zero value. For more information, see Published properties for ActiveX Toolkit lists.

List_id is the ID of a list that was previously created with the L_CREATE subroutine.

Request is the request flag for the L_PROCESS subroutine. The L_SELECT subroutine translates menu entries into request flag values, but the calling routine must either specify the name of the LLOAD_METHOD subroutine for loading list items or provide the items to load into the window itself. LLOAD_METHOD can be specified using the .LISTCLASS script command, or the L_CLASS or L_METHOD subroutines.

Request should be set to D_LNOP (0) the first time L_SELECT is called. L_SELECT will call the load method, or return with request set to either D_LLOADBOT or D_LLOADTOP (depending on the options set when the list was created) until no more items are currently needed. The load method or the calling routine must do either one of the following:

Between the time you get a load bottom or load top request and the time you return to L_SELECT, do not do any screen I/O (for example, M_PROCESS or U_UPDATE).

If a load method has been specified, L_SELECT calls it every time a new list item is needed, and does not return to the calling routine.

If L_SELECT returns request set to D_LABORT, an unsupportable situation has occurred, and the calling routine should delete the list.

L_SELECT honors the following menu entries and translates them into list requests:

L_SELECT Menu Translations

Menu entry

List request

S_UP

D_LUP

S_DOWN

D_LDOWN

S_LEFTa

D_LLEFT

S_RIGHTa

D_LRIGHT

S_TOP

D_LTOP

S_BOTTOM

D_LBOTTOM

S_PGUP

D_LPGUP

S_PGDN

D_LPGDN

S_PGTOP

D_LPGTOP

S_PGBOT

D_LPGBOT

S_FIND

D_LFIND (after prompting for a find string and calling L_FINDSPEC)

S_FINDNEXT

D_LFIND

S_FINDDIR

(Toggle find direction)

a. Must first be activated using L_RETURNKEY.

You can also translate menu entries yourself. If the user selects a menu entry that L_SELECT does not recognize, the calling routine can map it to any request code recognized by L_PROCESS.

As shown in the above table, both the S_FIND and S_FINDNEXT menu entries use D_LFIND, but S_FIND’s operation does some additional processing. S_FIND first pops up an input window for the user to input specifications for the find operation, then it calls L_FINDSPEC to set the characteristics, and lastly it calls L_PROCESS. You can call L_FINDSPEC before calling L_SELECT to establish “find” defaults.

When either an S_FIND or an S_FINDNEXT is being performed, L_SELECT will display a message on the information line. This message is contained in the syntxt file under the facility DTK, mnemonic FIND_MSG.

If L_SELECT will be displaying a find window (honoring S_FIND), you have three options:

If you would prefer either of the last two options (creating your own find window), see the information on find_window below.

Whether or not the data argument is passed must correspond to whether it was passed in the L_CREATE subroutine when the list was created. Data is required here if it was also passed to L_CREATE. If data is passed here but was not passed to L_CREATE, a fatal error occurs.

Data is the optional associated non-window data for the list. (Non-window data is additional information that you don’t want displayed, but that you want to be maintained with the list.) Whenever this subroutine returns, the data for the current item is loaded in data, and the list’s associated input window contains the display data for that item.

Disabled is a true/false flag that indicates whether the current item is disabled. Whether or not the disabled argument is passed must correspond to whether it was passed to other list routines such as L_CHR, L_DATA, L_INPFLD, L_INPUT and L_PROCESS. See L_PROCESS for more information about the disabled item status.

If disabled is passed and has a value of true, the current item is disabled and cannot be selected. If skip_disabled is passed and has a value of true, the positional indicator cannot move to a disabled item after it is loaded; the indicator will move past the item automatically. The disabled argument is returned with the disabled status for the current item.

If the user presses Enter, Tab, or Shift+Tab, or if an unknown menu entry is selected, L_SELECT returns, setting request to D_LNOP. The data argument will contain the associated data for the item, and the list’s input window will contain the display data for the item. Note the following:

Character helps you determine whether the user typed a printable character while positioned on an enabled item. If character is not passed and the user enters any key other than Enter or a menu shortcut, the terminal bell will ring and processing will continue.

If character is passed, one of the following may occur:

The user can select a menu entry while on a disabled item if skip_disabled is not passed or has a value of false, in which case the optional character argument will be returned with a value of zero.

On Windows, select_column and find_column are, by default, ignored if passed. These columns usually contain reserved menu entries that are automatically supported by the Windows environments.

On Unix and OpenVMS, if select_column is passed, the specified selection column will be placed before selection processing occurs, and it will be removed on exit. If find_column is passed, the menu column with that ID is placed before performing input to find_window, and removed afterwards.

The default behavior for each environment’s handling of columns is controlled by the g_plc_col_args flag, which is defined in the distributed tkctl.def file. See g_plc_col_args for information.

If the operation times out, g_select is set to true and g_entnam set to the entry name specified in g_time_entry, which is defined in tkctl.def. See g_time_entry.

If pre_input_routine is passed, L_SELECT will pass the specified pre-input routine the list ID. If a menu entry is selected while in the pre-input routine, L_SELECT will honor the menu name if L_SELECT recognizes it. If L_SELECT doesn’t recognize the name, L_SELECT will return the name to the calling routine.

If specified, the pre_input_routine must be available. In other words, it must either be contained within the current program image, or in an executable library (ELB) that was either linked to or opened with OPENELB. The default state, if no pre_input_routine is specified anywhere, is for L_SELECT to return to the caller when input is ready to be performed.

The L_SELECT subroutine turns both echo and cursor off. You may want to call E_ENTER and E_EXIT around the call to this subroutine, because L_SELECT doesn’t call E_ENTER, nor does it reset the echo and cursor parameters when it’s done.

You can pass find_window to replace L_SELECT’s default find window. Find_window must be either the ID of an input window you have created in a script file, with the IB_xxx subroutines, or with %L_FINDWND.

Note

If D_RETURNBTN will be enabled and the list will be part of a composite window that on Windows has buttons, you will need to add a default button to the find window. This will enable users to close the find window normally. The default find window, for example, has OK and Cancel buttons, with OK as the default.

L_SELECT places and displays the find window within the current display area when the user selects the menu entry “S_FIND”. If you create your own find window with a script, placement of the find window can be specified within your script. If you create the window with the IB_xxx subroutines, you can use U_WINDOW to specify placement. If you use the %L_FINDWND function, the find window will be centered within the current display area by default. To change the placement of the %L_FINDWND window, place and remove the window (without updating the screen) before calling L_SELECT. When L_SELECT calls the %L_FINDWND window, it will place it at the last placement position.

When find_window is specified, L_SELECT calls a UI Toolkit input routine to perform the input in the find_window. L_SELECT passes the input routine the D_NOTERM option (to suppress the input termination message) and passes the finddata data structure:

record finddata
       finddir      ,i4    ;Find direction
       findcase     ,i4    ;Find case
       findtype     ,i4    ;Find type
       findcurr     ,i4    ;Find current item
       findpos      ,i4    ;Search area position
       findlen      ,i4    ;Search area length
       findstrng    ,a80   ;Find string

See the tools.def file for the values associated with finddata’s first four variables (finddir, findcase, findtype, and findcurr). Finddata is preloaded with the current values, as previously specified by a call to L_FINDSPEC (or the default values).

Note that even though findstrng is declared as a80, only positions 1 through findlen will be considered, and only the trimmed input within these bounds will be used for find matching.

Find_window does not have to provide input for or display all of finddata’s options. For example, if you only wanted to allow the user to input the find string, the .STRUCTURE script command for the input window would look something like:

.structure find, <24>, findstrng

If find_init is passed and true, the default set for the window is initialized with I_INIT. Otherwise, the previous find data is displayed into the default set using I_DISPLAY, and I_NEXT is used to position the context of that set to the first field.

See also

WAIT qualifier for the .FIELD command for more information on input time-outs

Examples

The following example processes the selection list identified by lstid. On entry, req contains the request to be processed by L_SELECT. In this example, no initial action has been requested. The paragraph satisfy_request will perform the request returned from L_SELECT. This could be either to load data into the list (assuming no load method is defined for the list) or to abort the list. Satisfy_request will set req to indicate the result of the performed action. The paragraph process_selection is called only when all requests from the list processor are satisfied, and in this case either a menu entry (unrecognized by L_SELECT) has been selected or the user has pressed Enter on an item in the list.

req = D_LNOP
do
  begin
    xcall l_select(lstid, req, lst_data)
    if (req) then
      call satisfy_request    ;Process list requests first
    else
      call process_selection  ;Process a selection
  end
until (g_select)       ;Unrecognized menu entry
satisfy_request,
  case req of
    begincase
;D_LLOADBOT
      call load        ;Load requested item
;D_LLOADTOP
      req = D_LEOF     ;Tell L_SELECT "none available"
;D_LABORT
      g_select = TRUE  ;Force exit from L_SELECT loop
    endcase
  return
process_selection,
  if (g_select) then
    case g_entnam of   ;Process a menu entry
      begincase
         .
         .
         .
       endcase
  else                 ;An item was selected
    g_select = TRUE    ;Force exit from L_SELECT loop
  return

The following call to L_SELECT passes the data associated with the selection list in lst_data and the current disabled status of the item in disabled. Disabled selections will be skipped and the new disabled status returned in disabled.

xcall l_select(lstid, req, lst_data, disabled, TRUE)