Accept one field from the terminal
|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall U_FLD(data_area, [window_id], [row], column | field#, [paint], [length], & [begin_position], [mode], [help_id][, wait_time])
Arguments
data_area
(required if row is passed) Returned with the set of characters that was input. (a)
window_id
(optional) The ID of the window (created by U_LDWND) from which the input will come. If not passed, the current input window is used. (n)
row
(optional) The window row from which this subroutine will be reading. (n)
column | field#
The column (if row is also specified) from which to read or the field number (if row is not specified) at which to do the input. (n)
paint
(optional) The paint character. (a)
length
(optional) The initial data length and is returned with the final data length on exit. (n)
begin_position
(optional) The initial field position and is returned with the final input position on exit. (n)
mode
(optional) An insert/overstrike mode variable. (Ignored on Windows.) (n)
0 = Overstrike. (default)
1 = Insert.
help_id
(optional) The help identifier. (a)
wait_time
(optional) The time-out limit for I/O processing to be completed before returning to the calling routine. (n)
Never time out.
Use the global value (see g_wait_time). (default)
Time out immediately.
Wait up to n seconds (where n is a positive value) for I/O processing to be complete.
Discussion
U_FLD accepts a set of characters from the terminal. It is designed to perform field input in a non-input window. You cannot use it with an input window (one defined by the .INPUT script command or by the IB_INPUT subroutine). See I_INPFLD and I_INPUT for information about performing input in an input window.
This subroutine allows menu or shortcut processing.
If you want input performed at a specific row and column within the window, pass a non-zero value to row and the column number as the next argument (which UI Toolkit will assume to be column). Together these two arguments define the position within the window at which to do the input. This is known as a “position-mode call.”
When processing a position-mode call, the data_area argument is required and specifies the maximum length of the input. If no field set is defined, UI Toolkit will create and use one with a single field.
If you want input performed on a field number, omit row and pass the window field number as the following required argument. (When row is not passed, UI Toolkit assumes this next argument to be the field#). This is known as a “field-mode call.”
When processing a field-mode call, the data_area field is optional. If data_area is not present, it is the responsibility of the calling routine to ensure that the specified field’s contents match the passed parameters and to retrieve the input data from the window field upon completion of the call. The maximum width of the input is determined by the length of the specified window field, regardless of the size of any data_area that is specified.
If length is present, it is the number of data characters in the field upon entry and exit. The initial data length in the field will be length’s entering value. On exit, length will be loaded with the final data length. If length is not specified, the entering data length is assumed to be 0.
If the entering data length is non-zero, the number of characters from data_area are placed in the leftmost part of the field before the initial input.
If begin_position is present, it is the position of input within the field upon entry and exit. The initial input will begin at this character position (a value of 1 means the input position is at the field’s first character, 2 means it’s at the second character, and so forth). On exit, begin_position will be loaded with the final input position.
If begin_position is not present or has a value of zero, the initial position will be the initial data length plus one.
If mode is present and non-zero, the input will be performed in insert mode. Any characters at and to the right of the initial input position (as determined by the entering data length and the initial position) will be “pushed around” as data is entered and deleted during input.
On Unix and OpenVMS, if mode is not present or has a value of zero, input will be performed in overstrike mode. Characters to the right of the input position will be replaced by entered characters, while characters to the left will be replaced by the paint character on deletes.
On Windows, U_FLD recognizes the following menu entries, which are described in Appendix B: Reserved Menu Entries:
E_CLEAR
E_COPY
E_CUT
E_MARK
E_PASTE.
If g_select is set on return, a menu entry has been selected, and g_entnam contains the name of the selected entry. If the selected menu entry begins with “U_” the EUTILS_METHOD subroutine is called and the input is redone. If the selected menu entry is “O_HELP,” the EHELP_METHOD subroutine is called, with the help_id as its argument.
You will need to clear g_select after you satisfy the event.
The field gi_sts will be loaded with the type of the input. If the input is NORMAL_INPUT (zero), the input was terminated normally by a Enter. If gi_sts is non-zero, the input was terminated by a special entry.
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.
Examples
The first example returns the set of characters that was input to the variable custnam. This input comes from the 4th field of the window whose ID is stored in wndid[i].
xcall u_fld(custnam, wndid[i],, 4)
The second example also returns the characters that were input to custnam. Input comes from the current input window at position (15,30). The routine passes the identifier “cushelp” to the EHELP_METHOD subroutine.
xcall u_fld(custnam,, 15, 30,,,,,"cushelp")
