I_FORCE

Force data to or from an input field

xcall I_FORCE([new_data][, old_data])

Arguments

new_data

(optional) The new data to force. (a)

old_data

(optional) Returned with the current contents of the force buffer. (a)

Discussion

I_FORCE forces a data string as input to the next field. This operation is equivalent to entering the desired data for the field from the terminal. (Note, however, that this routine does not do any of the actual forced data processing. It simply sets up the force buffers so the field input routine can access the data. The data will be the input delivered to the next field processed by I_INPUT or I_INPFLD.)

The force buffer is the location to which UI Toolkit copies the contents of an input field if the user selects a menu entry before pressing Enter. (Note that the length of the data in the force buffer is not set.) The field is then reset to its initial entering state. You can use I_FORCE with the old_data argument to obtain the field’s contents at the time the menu entry was selected; if old_data is passed, the current contents of the force buffer are copied to old_data prior to any new data processing.

If new_data is passed, its contents are loaded into the force buffer. If a null string (“”) is passed as new_data, the force buffer is cleared and any pending I_FORCE is canceled.

If I_FORCE is being used in a selection window field and new_data is not a selection in the selection window, a beep will sound and new_data will not be accepted into the field. UI Toolkit will then wait for input (with the selection window dropped down if the field is empty).

The force buffer is cleared when a field exits without pending input. As a result, I_FORCE returns only the pending input for the last field accessed.

A call to I_FORCE is valid at any time. If a hot entry is processed by EUTILS_METHOD during input window processing and I_FORCE is called, the input field that was “interrupted” will have the value of the I_FORCE argument.

You can override UI Toolkit’s default behavior of canceling pending input by registering an EENTRST_METHOD subroutine. See Environment Routines for more information.

See also

I_PUTFLD routine for information about putting data into a field
I_DSPFLD routine for information about displaying data in a field

Examples

This example searches for the data string input by the user and places the string it finds back into the input field.

xcall i_input(wnd,, data, inpcol, selcol, edtcol)
if (g_select)
  case g_entnam of
   begincase
"SEARCH":                             ; If input terminated by user
     begin                            ; and user wants to look up
       xcall i_force(, string)        ; a name, see if user entered
       xcall lookup(g_fldnam, string) ; a partial name. Go do
       xcall i_force(string)          ; the search and put the
     end                              ; found information back
     .                                ; into the field.
     .
     .
   endcase