%ICHANGE_METHOD

Perform input field change processing

function ICHANGE_METHOD,^val
 a_data_entered         ,a
 a_data_stored          ,a
 a_pending_status       ,n
 a_inpinfo              ,a
 a_inprec               ,a
 a_methoddata1          ,any
        .
        .
	 .
 a_methoddata20         ,any

Return value

%ICHANGE_METHOD must return one of the values listed under a_pending_status below. (n)

Arguments

a_data_entered

A buffer containing the field data as entered by the user. (a)

a_data_stored

A buffer for the final storage of the data. (a)

a_pending_status

The result of Toolkit’s field validations; one of the following (defined in tools.def): (n)

D_OK

Input is valid, proceed.

D_RNGERR

Value not in range.

D_VALERR

Invalid numeric digit.

D_LSTERR

Not an allowed entry.

D_REQERR

Non-zero or non-blank value required.

D_DATERR

Invalid date.

D_NEGERR

Negative value not allowed.

D_OVFERR

Too many digits.

D_TIMERR

Invalid time.

D_NEGOERR

Negative value only allowed.

D_EMITTEDERR

Invalid entry, but error message already emitted.

a_inpinfo

The structure of input information. (a)

a_inprec

(optional) The data_area argument (or the data_location argument for I_INPFLD on Windows) passed to the calling input routine. This is not passed if the calling routine is L_INPFLD. And, on Unix and OpenVMS, this is not passed if the calling routine is I_INPFLD. (a)

a_methoddata1 through a_methoddata20

(optional) Up to 20 additional data arguments. (any)

Discussion

%ICHANGE_METHOD is a function you write and name when you want your program to perform extra actions after a specific input field is validated. By default, a field is not validated until focus is lost. Immediate validation can be specified for check boxes, radio buttons, and combo boxes by using the D_VALSTCHG option in E_STATE. %ICHANGE_METHOD must be declared as a ^VAL function.

This function is called by I_INPUT, I_INPFLD, L_INPUT, and L_INPFLD when a change method is specified for the field being processed. You can specify a change method for the field by using the CHANGE_METHOD qualifier in a .FIELD script command or the D_FLD_CHANGE option in I_FLDMOD or IB_FIELD.

%ICHANGE_METHOD is called only after the new field contents have been subjected to all the specified Toolkit validation tests. %ICHANGE_METHOD has the “last chance” opportunity to override or add to the Toolkit’s functionality.

When %ICHANGE_METHOD is called, a_data_stored contains the storage form of the new data as validated by the Toolkit. If you wish to override the storage form of valid input, you may store the desired information in this argument prior to returning from the method. The following table shows the expected contents of a_data_entered based on field type.

Field type	Contents of a_data_entered
Editable (including enumerated allow list)	Data as entered
Selection list/window (including enumerated and radio buttons)	Text of selected entry
Check box	Blank (for non-checked) or the contents of g_chk_char (for checked). See g_chk_char for more information.

Note that the length of the text passed in a_data_entered is defined by the input length for the field. It is not limited by either the display length or the view length.

If a_pending_status is one of the D_xxxERR values when %ICHANGE_METHOD is called, the contents of a_data_stored are undefined.

A_pending_status contains the result of Toolkit’s validations. %ICHANGE_METHOD can simply return this value or return a different value (as the return value of the function) if you want to override Toolkit’s validation of the field.

If %CHANGE_METHOD returns D_OK, the entry is accepted. Any other return value will revert the entry and storage to its original contents and force re-entry. (You do not need to revert the data in a_data_entered.) If %ICHANGE_METHOD returns any of the values D_RNGERR through D_NEGOERR, the appropriate error message is also displayed. D_EMITTEDERR should be returned when %ICHANGE_METHOD displays its own error message. (This implies that, on Windows, a change of focus within the change method is acceptable and is actually expected when returning D_EMITTEDERR.)

The include file inpinf.def defines a_inpinfo. See IARRIVE_METHOD for more information, but note that you must include inpinf.def as the fourth argument within your change method.

A_inprec is the same record passed to the data_area argument for I_INPUT and L_INPUT and, on Windows, the data_location argument for I_INPFLD. (On Unix and OpenVMS, this argument is not passed if I_INPFLD is the calling routine.) Note that the area of the record occupied by the current field does not yet contain the data being validated.

A_methoddata1 through a_methoddata20 are up to 20 additional optional arguments that can be passed to I_INPUT, I_INPFLD, or L_INPUT. They are passed, in turn, directly to %ICHANGE_METHOD. This enables you to communicate additional information to %ICHANGE_METHOD.

See also

Overloading UI Toolkit routines for more information on creating this function
Appendix D: Methods for important information about method limitations

Examples

In this example, if the user enters a non-zero value in the field, all fields in the set named “rest” are cleared and disabled. Otherwise, these fields are enabled.

function check_full       , ^val
        a_data_entered    ,n
        a_data_stored     ,n
        a_pending_status  ,n
        .include 'WND:inpinf.def'
        a_record          ,a
.include 'WND:tools.def'
proc
       if (g_select)
         freturn D_OK    ;Menu entry signaled, don't do anything special.
       if (a_data_entered) then  ;The value entered is non-zero.
         begin
           xcall i_init(inp_wndid, 'rest', a_record) ;Clear fields in set
           xcall i_disable(D_SET, inp_wndid, 'rest') ; 'rest' and disable them.
         end
       else               ;A non-zero value
         xcall i_enable(D_SET, inp_wndid, 'rest')     ;Enable the fields in 'rest'.
       freturn D_OK       ;Accept the input for this field
end