I_SETINF

Retrieve information about an input set

xcall I_SETINF(window_id, [set_name], [set_num], [next_field], [set_controls]
&     [, processing_state])

Arguments

window_id

The ID of the input window containing the set. (n)

set_name

(optional) The returned set name. (a)

set_num

(optional) The returned set number. (n)

next_field

(optional) The returned next input entry index. (n)

set_controls

(optional) The returned set controls. (a)

processing_state

(optional) The processing state for an input set. One of the following: (n)

D_MODE_NORMAL

Normal input processing mode.

D_MODE_DONE

Done (I_DONE) processing occurring.

D_MODE_DFLT

Default (I_DFLT) processing occurring.

D_MODE_OK

OK (I_OK) processing occurring.

Discussion

I_SETINF retrieves information about an input set. To use it you must .INCLUDE these two distributed .def files in this order:

WND:system.def
WND:setinf.def

Window_id must contain the ID of a loaded input window.

You must specify either set_name or set_num, but you don’t need to specify both. If you specify both and

set_num is non-zero on entry, set_name is returned with the name of the set specified by set_num. (Sets are numbered sequentially as defined by the .SET script qualifier or by the order of calls to IB_SET.)
set_num is zero on entry, set_name is assumed to contain the name of the desired set, and set_num is returned with its ordinal number as defined above.

If next_field is passed, next_field is returned with the ordinal number of the next input field in the set to be processed.

If set_controls is passed, set_controls is returned with the control structure for the indicated set. The format of the control structure is defined in the distributed file setinf.def.

If processing_state is passed, processing_state is returned with a value used to determine whether done, default, or OK processing is in progress on the set. In this case, the processing has not yet completed.

If processing_state returns D_MODE_DONE, this means that I_NEXT(*DONE*) was called for the current set or the user selected I_DONE. All remaining fields are filled with their default values, blank, or zero. Validation and any break processing occurs next. When complete, if any buttons exist on the window, the first button will be focused; otherwise, termination processing will occur.

If processing_state returns D_MODE_DFLT, this means that I_NEXT(*DFLT*) was called for the current set or the user selected I_DFLT. All remaining empty fields that have a default value are filled with defaults. Validation and any break processing occurs next. When complete, the first empty field or first button will be focused, or termination processing will occur, in that order.

If processing_state returns D_MODE_OK, this means that I_OK was selected. Processing is identical to D_MODE_DONE, except that when complete I_INPUT is exited with g_setsts = 0.

Within the distributed setinf.def file, the field gs_setcnt contains the number of fields in the input set. The field gs_setnam is a 16-bit pointer and will not be useful. The array gs_setfld contains one 8-bit value for each field in the set. By using %DECML on each element, you can determine the UI Toolkit field number for each of the fields in the set. You can then use I_FLDINF to retrieve information about each of these fields, including the actual window field numbers (which may differ).

Examples

The following example returns the number of the next input field in context and the control structure for the entries set in gs_fldset.

xcall i_setinf (wndid, "entries",, context, gs_fldset)

The following example returns the name of the third input set in set_name, and the processing state for that set in state.

xcall i_setinf (wndid, set_name, 3,,, state)