I_NEXT

Specify the next input field or button to be processed

xcall I_NEXT(window_id, [set_name][, field_spec])

Arguments

window_id

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

set_name

(optional) The name of the input set to use or *CURR* to use the currently loaded set. (a)

field_spec

(optional) The specification for the field or one of the keywords listed below (which must be specified in uppercase). Field_spec must be enclosed in quotation marks. (For information on field specifications, see Field specifications.) (a)

*FRST*

First enabled field.

*LAST*

Last enabled field.

*NEXT*

Next enabled field.

*PREV*

Previous enabled field.

*FCLR*

First empty enabled field. (default)

*NCLR*

Next empty enabled field.

*MENU*

Set the context based on the contents of g_entnam.

*NMBR*, field#

Field# if enabled, otherwise next enabled field after field#.

*BUTTON*, button

Specified button on Windows. Button can be either the name (case-insensitive) or index number of a button.

*NONE*

No field.

*DFLT*

Fill default values on all empty fields with defaults and set context to next enabled empty field.

*DONE*

Complete input on all empty, enabled fields.

*LASTCTL*

Last enabled control (field or button).

*NEXTCTL*

Next enabled control (field or button).

*PREVCTL*

Previous enabled control (field or button).

Discussion

I_NEXT sets the input context. When processing input, Toolkit moves through fields according to their order in the input set; when a user is finished with a field, Toolkit moves to the next active field in the set. With I_NEXT, however, you can determine which field or button (on Windows) Toolkit will advance to. For example, if your application displays an error when a user enters an invalid item code, Toolkit automatically advances to the next field in the input set after the error is displayed. Using I_NEXT, however, you can instead instruct Toolkit to go back to the field that caused the break.

These are the general rules for context changes:

If a field or button specified with I_NEXT is disabled, Toolkit sets the context to the next enabled field or button.
If I_NEXT specifies a field, but all fields in the input set are disabled, Toolkit moves input context to the first enabled button.
If a field or button specified with I_NEXT is disabled and is the last field in the input set or the last button in the window, Toolkit sets the context to the first enabled input field in the set.
If all fields and all buttons in the input set are disabled, Toolkit proceeds to input set completion.

Note that set names are sometimes inaccessible to the utility subroutines. To call I_NEXT from within a utility subroutine, use *CURR* instead of a specific set name. This enables I_NEXT to use the current set even if it can’t access the name of the current set. If set_name is not passed, I_NEXT uses the first input set in the window.

If you don’t pass field_spec, the context is set to the first empty enabled field, which is the equivalent of setting *FCLR*. (An empty field is one that the user hasn’t entered anything in and that has not been displayed using I_DSPFLD or I_DISPLAY.)

Use *NMBR* followed by a numeric argument (field#) to specify the next field by index. This index is a number that represents the field’s position in the input set and is limited to the valid range for the input set. (A value less than 1 or greater than the number of fields in the window will result in a fatal Toolkit error.) For example, the following sets the context to the third field in an input set named setnam.

xcall i_next(inpid, setnam, "*NMBR*", 3)

On Windows, use *BUTTON* followed by a button name or index to move context to a specific button. (On UNIX and OpenVMS, passing *BUTTON* will cause a fatal Toolkit error.) The button argument is required if you pass *BUTTON*.

If button is an alphanumeric value, Toolkit treats it as a case-insensitive name. (If the name is not a valid name for a button in the window, you’ll get a fatal Toolkit error.)
If button is a numeric value, Toolkit treats it as an index, which represents the button’s position in the input set and is limited to the valid range for the input set. (A value less than 1 or greater than the number of buttons in the window will result in a fatal Toolkit error.) For example, the following sets the context to the second button in the window:

xcall i_next(inpid,, "*BUTTON*", 2)

*NONE* prevents I_INPUT from performing input to any field. Instead, Toolkit uses single-keystroke input. This option is rarely used.

Using *DONE* or *DFLT* is like pressing Enter for each remaining field without entering any input. The difference is that *DONE* completes the input set while *DFLT* displays any defaults that are specified in the script file, leaves all other fields unmodified (which does not affect their empty state), and allows input to continue on the next empty field.

On Windows, *NEXTCTL*, *LASTCTL*, and *PREVCTL* set context to the next, last, or previous enabled field or button. On UNIX or OpenVMS, if you are using termination processing, you can use *NEXTCTL*, *LASTCTL*, and *PREVCTL* to set context to the termination message.

If you call I_NEXT with *FCLR* or *NCLR* in a change method, I_NEXT uses the current state of the field set to determine where to move input context. This causes I_NEXT to set input context to the current field if it’s empty. To instead move context to the next enabled empty field, use %M_SIGNAL to signal I_NXTCLR. This moves context to the next empty field (unless you signal some other menu entry at the same time) because I_NXTCLR won’t be processed until the change method has returned and the input has been accepted. And because a menu entry was generated, Toolkit won’t move input context until the menu entry is processed.

If an application is in I_DONE (*DONE*), I_DFLT (*DFLT*), or I_OK processing, calling I_NEXT from a method will cancel that processing and move focus to the field specified by I_NEXT. If you do not want this to happen, test the value of inp_nulinp (which is in the inputinfo group defined in inpinf.def) before calling I_NEXT. If inp_nulinp is non-zero, the application is performing one of these types of processing.

If you pass *MENU*, I_NEXT will set context based on the value of g_entnam at the time that I_NEXT is called. (So with *MENU*, I_NEXT recognizes only menu entries that start with I_, such as I_NEXT, I_PREV, and I_DONE.) This is useful when a menu entry has been signaled outside of an input routine (such as I_INPUT, I_INPFLD, etc.) in order to force that menu entry to be applied upon re-entry to that routine. For example, while within a method in I_INPUT, passing “I_OK” to M_SIGNAL will cause validation of all fields to occur upon exiting the method, and (presuming no validation errors result) I_INPUT will then exit. However, if you make the same call to M_SIGNAL during break processing, then that menu entry will not apply to the next call to I_INPUT unless you also call I_NEXT with *MENU*.