L_INPUT

Perform input to a set within a list

xcall L_INPUT(list_id, [set_name], record, [data], [disabled], [input_column], 
&     [select_column], [edit_column], [D_NOTERM], [init_char], {reserved}
&     [, a_methoddata1, ..., a_methoddata20])

Arguments

list_id

The ID of the list. (n)

set_name

(optional) The name of the input set. (a)

record

The input set’s record. (a)

data

(optional) The non-window list item data. (a)

disabled

(optional) The disabled item status. (n)

input_column

(optional) The input column ID. (n)

select_column

(optional) The selection column ID. (n)

edit_column

(optional) The edit column ID. (n)

D_NOTERM

(optional) The flag that tells L_INPUT to skip set termination processing. (n)

init_char

(optional) The first character to input (specified as a decimal value). (n)

{reserved}

Placeholder. Add an additional comma if specifying any a_methoddata arguments.

a_methoddata1 through a_methoddata20

(optional) Up to 20 additional data arguments. (any)

Discussion

L_INPUT performs essentially the same function as the input subroutine I_INPUT, but targeted to an input set contained within a list. See I_INPUT for information on the arguments you can pass to L_INPUT and the menu entries recognized by L_INPUT, and note that if you are using L_SELECT, you do not need to call this subroutine because L_SELECT handles list input.

When this subroutine returns, one of the following has occurred:

Input to the set has been completed.
A break field has been entered.
A menu entry has been selected.
tab from the last field of an item in L_INPUT when the list is part of a composite window. This signals “C_NEXT”.
shift+tab from the first field of an item in L_INPUT when the list is part of a composite window. This signals “C_PREV”.

L_INPUT calls L_PROCESS to update the current item before performing input. This means that you should include the fourth argument (data) in order to preserve the list item data.

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. Note the following:

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.
We highly recommended that the list data also contain the input data for the set. Otherwise, confusion may result over the contents of the input set data as list items are changed interactively.
By default, Toolkit does not ensure that data is large enough. If it isn’t, Toolkit generates an error only if g_dtkbounds is set to 1 or greater. See g_dtkbounds.

Disabled is a true/false flag that indicates whether the current item is disabled. Whether or not the disabled argument is passed depends on whether it was passed to L_CREATE. See L_PROCESS for information about the disabled item status.

The D_NOTERM flag is ignored on Windows. The input window is always treated as if D_NOTERM were specified. This is necessary to support item-to-item movement within the list during input.

On Windows, the user can change the current item in the list with the mouse or the page up, page down, home, end, and arrow keys before this subroutine returns. Therefore, if you want any special processing to be done when arriving at or leaving a list item, you will have to write and use an arrive or leave method. (In Windows environments, these keys are “privatized” and unavailable to calling routines unless you use L_RETURNKEY to return the key out of the list. “Privatized” means that they are reserved for the private use of the graphical control, which in this case would be the list.)

L_INPUT has the following limitations on Windows:

Multi-line text fields are not supported within Toolkit lists or ActiveX Toolkit lists.
Selections fields (SELECT or SELWND) are not supported within Toolkit lists.
Radio button fields are not supported within Toolkit lists. Within ActiveX Toolkit lists, radio buttons are rendered as if they were selection fields.
Check box fields are not supported within Toolkit lists.
Drill methods are supported by the menu entry I_DRILL, but no drilldown button is displayed.
Hyperlink methods are supported by the menu entry I_HYPER, but the prompt cannot be clicked on to launch I_HYPER, nor is the prompt rendered green.
Noecho fields do not work properly in Toolkit lists. For ActiveX Toolkit lists, asterisks (*) are displayed.
When using ActiveX Toolkit lists, the first field in the list will be selected regardless of whether or not that field is in the current input set.
We recommend that you use a fixed font for Toolkit lists; columns may not line up as expected when a proportional font is used.
If you do use a proportional font for Toolkit lists, note that bold proportional fonts use an actual bold font, rather than rendering bold as a color change the way fixed fonts do. Consequently, bold characters are more likely to be truncated because Toolkit determines the width of the field or prompt using a non-bold (normal) font.

On UNIX and OpenVMS, if init_char is passed, it is converted to its alpha (ASCII) equivalent and placed into the field as if it were the first character entered by the user. On Windows, init_char is ignored.

A_methoddata1 through a_methoddata20 are up to 20 additional optional arguments that can be passed to L_INPUT. L_INPUT, in turn, passes them directly to each field’s methods. This allows you to communicate additional information to your input field methods.

Toolkit passes the method data arguments to the current list processing routine (L_PROCESS, L_INPUT, or L_SELECT) and to the list methods. Thus, if you pass data arguments to one list processing routine, to ensure these arguments are always available, you must pass them to all the list processing routines.