I_INPUT

Process an input set

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
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. See L_INPUT for more information.)

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.

Note

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:

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:

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

Namea of the break field

n/a

Unrecognized menu entry

Trueb

Truec

Namea of the field that was focused

Namea 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.

See also

Examples

The following example processes the input set cusmas in the input window stored in inpid and places the data in cusmas.

xcall i_input(inpid, "cusmas", cusmas)

The next example processes the input set artran, places the input data in variable artran, and disables set termination processing.

xcall i_input(inpid, "artran", artran,,,, D_NOTERM)

The following example loads the menu column whose ID is stored in inpcol and whose name is input from the window library channel that is stored in g_utlib. The column will not be placed on the menu. The I_INPUT subroutine processes the input set named cusmas and places the data in the record cusmas. The column whose ID is stored in inpcol will be placed on the menu and removed before I_INPUT returns.

xcall m_ldcol(inpcol, g_utlib, "input", D_NOPLC)
  .
  .
  .
xcall i_input(inpid, "cusmas", cusmas, inpcol)

The following code fragment illustrates how you can use the I_INPUT subroutine in a program.

do
  begin
    xcall i_input(inpid, setname, datarec)
    if (g_setsts) then      ;Will be true for menu entries & break fields
      begin
        if (g_select) then          ;Test for menu entry
          using g_entnam select
            ("ABT"), call abort
            ("EXT"), done=TRUE
          endusing
        else
          using g_fldnam select     ;Test for break processing
            ("FLD1"), call fstbreak
            ("FLD2"), call sndbreak
            ("FLD3"), call thdbreak
          endusing
      end
    else                            ;Input complete
      done=TRUE
  end
until (done)