I_INPUT

Process an input set

xcall I_INPUT(window_id, [set_name], data_area, [input_column], [select_column], 
&     [text_column], [D_NOTERM], [decimal_value], {reserved}
&     [, a_methoddata1, ..., a_methoddata20])

Arguments

window_id

The ID of the input window to process. (n)

set_name

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

data_area

Where to place the input data (a field or record defined within the calling program). (a)

input_column

(optional) The input column ID. (n)

select_column

(optional) The selection column ID. (n)

text_column

(optional) The text editing column ID. (n)

D_NOTERM

(optional) Disable termination processing. (n)

decimal_value

(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

I_INPUT performs terminal input to the fields in an input set. If the input window has a movable view (or display), the view will be automatically adjusted, if necessary, to include the entire input field. (If you are processing input on a list item, use the L_INPUT subroutine instead of I_INPUT.)

I_INPUT maintains the “context” of an input set. In other words, it remembers the next field to process in an input set. If a field has a break specified (see BREAK, NOBREAK), the context changes to the field after the field with the break, and an I_INPUT command will go to the field after the break. When you first load an input window, the context for all sets is reset. If the context is reset, the first field is the next field to be processed. (You can also reset context with I_INIT.)

The context for each input window set is separate from all other input window sets. You can change the context with the I_NEXT subroutine.

You can call I_INPUT at any time, and it will continue where input processing left off in that set. This means that you can process any number of input sets at any time and not lose context.

You should not call I_INPUT from a button method that’s called during I_INPUT processing; this will cause unpredictable results. Instead, you may be able to code the method to call an input method on the original window or signal a menu entry to handle input without calling I_INPUT directly.

If input is “interrupted” by a menu selection (that is, the user selects a menu entry before pressing Enter), any current contents of that input field are copied into the force buffer (but the length of the data in the force buffer is not set), and the field is reset to its initial entering state (unless you use EENTRST_METHOD to override this behavior). You must call I_FORCE with only the old_data argument to obtain the input that was in the field at the time the menu entry was selected.

If set_name is not present, I_INPUT will, by default, process the first input set in the window.

The data_area is accessed according to the structure specification associated with this input set. This entire data_area is passed to the EUTILS_METHOD subroutine when a hot entry is selected, giving it access to fields other than just the current field. Note that by default, Toolkit does not ensure that data_area is large enough for the fields it references. Toolkit generates an error for this condition only if g_dtkbounds is set to 1 or greater. See g_dtkbounds.

I_INPUT on Windows

If any of the column arguments (input_column, select_column, text_column) are passed, Toolkit will not, by default, place or remove the specified columns. These columns usually contain reserved menu entries that are automatically supported by Windows environments. You can override this default behavior as noted below.

I_INPUT recognizes the following menu entries on Windows, which are described in Appendix B: Reserved Menu Entries:

E_CLEAR	E_PASTE	I_FRST	I_NEXTCTL
E_COPY	I_CANCEL	I_FRSTCLR	I_NXTCLR
E_CUT	I_DFLT	I_HYPER	I_OK
E_MARK	I_DONE	I_LAST	I_PREV
E_MODE	I_DRILL	I_NEXT	I_PREVCTL

Note that regardless of the available menu entries, the Left and Right Arrow keys and the Home, End, and Delete keys are processed within I_INPUT. Additionally, the Up and Down Arrow keys are reserved and processed within I_INPUT for multi-line edit controls, radio buttons, and selection fields. Therefore, with the following exception, these keys are never returned to the calling subroutine. However, when a single-line input field has focus, the Up and Down Arrow keys and the Home, End, and Delete keys can be mapped to menu entries.

If the menu entry I_CANCEL is present on the menu and the user selects it, any input being performed will be canceled, and the field will be reset to its state prior to the start of the input, its initial state. (Note, however, that an EENTRST_METHOD can override I_CANCEL.)

Insert is the default mode for editing. Text field editing is similar to text window editing, except that the text field’s input is terminated when the user presses Enter unless g_txt_rtrn is true.

Note the following for multi-line text fields on Windows:

When pasting within or in front of existing text, text that follows the pasted text will be pushed out of the field (i.e., the data will be truncated) if there is not enough room.
I_INPUT’s handling of line ends in incoming data is controlled by the g_txt_softreturn field, which is defined in tools.def. See g_txt_softreturn for information.

I_INPUT on UNIX and OpenVMS

Field editing and movement within input fields is automatically performed during input processing if the appropriate reserved menu entries are present on a loaded input_column, select_column, or text_column.

If the input_column is present and non-zero, that column will be placed on the menu and removed on exit. If the select_column is present and non-zero, it will be placed on the menu when a field with a selection window is processed. If the text_column is present and non-zero, it will be placed on the menu when a text field is processed. The alternative to specifying any of the “column” arguments is to place the column before calling I_INPUT. (However, then the column may be on the menu even when it has no meaning.)

I_INPUT recognizes the following menu entries, which are described in Appendix B: Reserved Menu Entries. (Note that I_INPUT recognizes the S_ entries [S stands for “selection”] only when processing a selection field.)

E_BMOV	I_CANCEL	I_HYPER	I_PREVCTL
E_CDEL	I_DFLT	I_LAST	O_HELP
E_EMOV	I_DONE	I_NEXT	S_DOWN
E_LCLR	I_DRILL	I_NEXTCTL	S_LEFT
E_LEFT	I_EDIT	I_NXTCLR	S_RIGHT
E_MODE	I_FRST	I_OK	S_UP
E_RIGHT	I_FRSTCLR	I_PREV	U_xxx

I_INPUT also recognizes the following when on a multi-line text field:

E_BOTTOM	E_ILIN	E_PDEL	E_WDEL
E_DIR	E_JOIN	E_PMOV	E_WMOV
E_DOWN	E_LDEL	E_TOP	E_XDOWN
E_EDEL	E_LMOV	E_UP	E_XUP

To edit a field that already contains data, the user can move to that field using one of the field movement input entries (such as I_PREV or I_NEXT) listed above. The “E_” entries perform the field editing functions. These “E_” entries are a subset of the text editing functions supported by the T_EDIT subroutine.

Insert mode is the default for editing. When editing text fields (dimensioned alpha fields) all menu entries for T_EDIT are recognized. Text field editing is very similar to text window editing, except that the text field’s input is terminated when the user presses Enter unless g_txt_rtrn is true.

If the menu entry I_CANCEL is present on the menu and the user selects it, any input being performed will be canceled, and the field will be reset to its initial state (prior to the start of the input).

I_INPUT on all platforms

I_INPUT will call EHELP_METHOD on menu selections whose internal names are “O_HELP”, and will call EUTILS_METHOD on menu selections whose internal names begin with “U_”.

E_XUP and E_XDOWN operate the same as E_UP and E_DOWN, except when the cursor is already on the first row of the field (for E_XUP) or the last row of the field (for E_XDOWN). E_XUP moves the cursor up one row within the field, unless the cursor is already on the top row. In that case, E_XUP is returned to the routine that called I_INPUT. Likewise, E_XDOWN moves the cursor down one row in the field, unless the cursor is already on the bottom row. In that case, E_XDOWN is returned to the calling routine. If you use E_XUP or E_XDOWN, we recommend that you wrap I_INPUT in a routine that handles these menu entries when they are returned.

If I_INPUT encounters an entry name that begins with “I_” that is not in the list above, it generates an error. In other words, if you’re using I_INPUT, none of your application’s menu entry names (except for the reserved ones listed above) should begin with “I_”.

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 D_NOTERM is present, completion processing is disabled. This means that when an input set is completed, control returns directly to the calling subroutine, and the message specified by g_inp_trm_msg is not be displayed.

If a time-out occurs, g_select is set to true and g_entnam is set to the entry name specified in tkctl.def for g_time_entry. By default, g_time_entry is defined as “O_TIMEOUT”.

If passed, decimal_value is converted to its alpha (ASCII) equivalent on UNIX and OpenVMS and placed into the window as if it were the first character entered by the user. Decimal _value is ignored on Windows.

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

Reasons for I_INPUT to return

The I_INPUT subroutine can return for one of the following reasons (or a combination of the third and fourth reasons), which set g_select, g_setsts, g_fldnam, and g_entnam:

Input to the input set is complete. When all active fields in the input set have been processed, I_INPUT displays a termination message, which is defined by g_inp_trm_msg (see g_inp_trm_msg).
The input set has no active fields and there are no active buttons. (In this case, g_setsts is set to false, indicating that input is complete.)
Input to a field that has a break specification is complete.
A menu entry that the input system does not recognize is signaled (through user-interaction or by %M_SIGNAL).
Tab or a call to I_NEXTCTL from the last button (or field if there is no active button) for an input window that is part of a composite window. (This signals “C_NEXT”, which I_INPUT doesn’t recognize but instead passes on to the calling routine.)
Shift+Tab or a call to I_PREVCTL from the first field (or button if there is no active field) for an input window that is part of a composite window. (This signals “C_PREV”, which I_INPUT doesn’t recognize, but instead passes on to the calling routine.)

Use the following table to determine the reason(s) for the return.

Reason	g_select	g_setsts	g_fldnam	g_entnam
Input set complete	False	False	N/A	N/A
Break	N/A	True	Name^a of the break field	N/A
Unrecognized menu entry	True^b	True^c	Name^a of the field that was focused	Name^a of the selected entry

a. Field and entry names are always returned in uppercase characters.

b. An unrecognized menu entry can be signaled through a user interaction or by %M_SIGNAL. After you have processed the event, you must clear g_select.

c. If a button was focused while the user exited input, g_setsts will be set to 255. This means that while a button was focused, the user did one of the following: pressed the button, but its menu entry was not handled by I_INPUT, pressed another button whose entry was not handled by I_INPUT, selected a menu entry (or shortcut) that was not handled, or invoked a method (toolbar or input field, etc.), which signaled a menu entry that was not handled.