ECHKFLD_METHOD
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
subroutine ECHKFLD_METHOD a_input ,a a_type ,a a_text ,a a_status ,n a_inpinfo ,a
Arguments
a_input
The contents of the input field. (a)
a_type
The user_type string specified in the .FIELD USER qualifier. (a)
a_text
(optional) The user_text string specified in the .FIELD USER qualifier. (a)
a_status
Must be returned with a value of zero if the input is valid, and with a non-zero value if the input is invalid. Refer to tools.def for the list of valid return values. (n)
a_inpinfo
The structure of input information. (a)
ECHKFLD_METHOD is a subroutine that you write and name. The name of your subroutine is registered with UI Toolkit using the E_METHOD subroutine This subroutine replaces the default field validation that Toolkit does for the current field.
We recommend using an input field change method (%ICHANGE_METHOD) instead of ECHKFLD_METHOD. Unlike ECHKFLD_METHOD, your %ICHANGE_METHOD adds to Toolkit functionality rather than replaces it. %ICHANGE_METHOD also provides access to the structure defined in inpinf.def and to the 20 optional arguments passed to I_INPUT and L_INPUT. See %ICHANGE_METHOD for more information. |
The UI Toolkit input routine calls your ECHKFLD_METHOD subroutine to validate the contents of the current input field. It is only called if the field definition uses the user_type argument from the .FIELD USER qualifier.
You will never call ECHKFLD_METHOD directly; it is called only by UI Toolkit.
Note that the length of the text passed in a_input is defined by the input length for the field. It is not limited by either the display length or the view length.
If a_status is returned non-zero, UI Toolkit will display the appropriate error message. (See ECHKFLD_METHOD section of the tools.def file for the error flags.) If you return an a_status value of D_EMITTEDERR, no error message will be emitted, but input will be performed again for the field. This assumes that you have emitted any appropriate messages from within ECHKFLD_METHOD.
The inpinf.def file defines a_inpinfo. See IARRIVE_METHOD for information.
S/DE Repository allows you to specify a subtype (or class) for user-defined fields. The default subtype is alpha, but you can optionally specify numeric or date. To access this subtype within the Toolkit user-defined processing routines, use the window ID and field number contained within the inputinfo structure (the a_inpinfo argument). Pass these two values to the I_FLDINF subroutine to retrieve the gs_inpfld structure (the controls argument) which contains the gs_class (user subtype) value. For user-defined alpha fields; gs_class = 0; for user-defined numeric fields, gs_class = 1; for user-defined date fields, gs_class = 2.
If ECHKFLD_METHOD doesn’t exist, your code will still run but UI Toolkit will not check whether the data entered by the user meets any user-defined criteria.
The ECHKFLD_METHOD subroutine works together with the EDSPFLD_METHOD and EEDTDSP_METHOD subroutines (which you write also). See the EDSPFLD_METHOD Discussion for more information on the steps that occur when a user-defined field is displayed, edited, and validated. If you have both Exxx_METHODs and an %ICHANGE_METHOD specified, the %ICHANGE_METHOD will be called after the Exxx_METHODs for the user-defined field.
Be sure that you write ECHKFLD_METHOD in such a way that it returns the validated data in storage format. EDSPFLD_METHOD, which is called by ECHKFLD_METHOD, needs the data in proper storage format to display the data correctly.
The following is a sample window script for both the following example and the example for the EDSPFLD_METHOD subroutine:
.input window, 1, 17 .placement 5, 29 .title " Zip Test " .field zip, a10, pos(1, 2), prompt("Zip "), – user(, "TYP_ZIPCODE"), uc .end
See also
- Overloading UI Toolkit routines for more information on creating this subroutine
- Appendix D: Methods
This following example shows how to use ECHKFLD_METHOD, EDSPFLD_METHOD, and EEDTDSP_METHOD to validate a ZIP Code field.
The ECHKFLD_METHOD example checks the length of the input. If the length is either five or nine digits, the value is a U.S. code. If the length is six characters, it is a Canadian postal code. The routine verifies that U.S. ZIP Codes contain only numbers.
If the ZIP Code contains any errors, the subroutine sets the a_status return variable to D_EMITTEDERR (a non-zero value). This tells the Toolkit input routine that the input is invalid and needs to be re-entered. When the subroutine verifies that the input is valid, it returns a value of zero in a_status, which tells the Toolkit input routine that the input is valid and to call EDSPFLD_METHOD to display the data.
For an example that shows how you can use ECHKFLD_METHOD and EDSPFLD_METHOD to handle user-defined field types, see the EDSPFLD_METHOD Examples. |
subroutine echkfld_method a_input ,a ;Characters input by user a_type ,a ;User-defined designation of this field a_text ,a ;Optional user string associated with this field a_status ,n ;Returned with zero if input valid a_inpinfo ,a ;Input information .include "WND:tools.def" record len ,i4 num ,i4 proc clear a_status ;Assume valid at outset case (a_type) of begincase "TYP_ZIPCODE": ;Accept either 5 or 9 digits only begin len = %trim(a_input) if (len.eq.1 .and. a_input.eq." ") len = 0 ;(Trim returns 1 if all blanks) if (len.eq.5 .or. len.eq.9) then begin onerror bad_digit num = a_input offerror a_input = num,"xxxxxxxxx" exit bad_digit, xcall u_message("Only 5 or 9 digits are valid", D_ERROR) a_status = D_EMITTEDERR end else if (len.eq.6)then ;Canadian ZIP Code format nop ;All characters valid, do nothing else if (len.ne.0) ;Ignore empty field begin xcall u_message("Invalid U.S. or Canadian zip", D_ERROR) a_status = D_EMITTEDERR end end ;Enter code of other user-types here endcase xreturn endsubroutine
The EDSPFLD_METHOD example puts a space between the numbers in a Canadian postal code (for example, 1G3 234) and inserts a hyphen in nine-digit U.S. ZIP Codes. To get this space, it manipulates the input (1G3234) and then calls Synergy DBL routines to display the data. It then passes the displayed result into the a_dest argument.
subroutine edspfld_method a_buf ,a ;Characters input by user a_typ ,a ;User-defined designation of this field a_usr ,a ;Optional user string associated with this field a_inpid ,n ;Window ID a_fld ,n ;Window field number a_dest ,a ;Optional destination area in storage record. ; If present, this routine must fill with the ; storage representation. a_attr ,n ;Attribute for display a_color ,n ;Color for display a_inpinfo ,a ;Input information .include "WND:tools.def" .include "WND:windows.def" record dsptxt ,a20 dsp10 ,a10 @dsptxt dspcz1 ,a3 @dsptxt dspczd ,a1 @dspcz1+3 dspcz2 ,a3 @dspczd+1 numzip ,d9 firstfour ,d4 @numzip canzip ,a6 canz1 ,a3 @canzip canz2 ,a3 @canz1+3 proc clear numzip, canzip, dsptxt case (a_typ) of begincase "TYP_ZIPCODE ": begin onerror (20) canadian ;Assume numeric, numzip = a_buf ; otherwise Canadian if (.not.firstfour) then ;Either 5 or 9 digits begin dsp10 = numzip(5:5), "XXXXX" [left] numzip=numzip*10000 end else dsp10 = numzip, "XXXXX-XXXX" if (^passed(a_dest)) ^d(a_dest) = numzip if (FALSE) ;Enter here if error #20 from above begin canadian, canzip = a_buf ;Canadian ZIP Code dspczl = canzl ;Load first 3 characters dspcz2 = canz2 ;Load second 3 characters if (^passed(a_dest)) a_dest = canzip end end ;Enter code for other user-types here endcase xcall w_flds(a_inpid, WF_PUT, a_fld, dsptxt, WF_ATTR, & a_fld, a_attr, WF_COLOR, a_fld, a_color) xreturn endsubroutine
This EEDTDSP_METHOD example left-justifies editable numeric text.
subroutine eedtdsp_method a_data ,a ;Data as stored a_type ,a ;Data type a_text ,a ;User text a_edit ,a ;Returned edit data a_inpinfo ,a ;Input information .align record numeric ,i4 ;Numeric test field proc case a_type of begincase "TYP_ZIPCODE ": call zipcode endcase else a_edit = a_data xreturn zipcode, onerror (20) canzip numeric = a_data offerror a_edit = numeric [left] ;Left-justify numeric return canzip, offerror a_edit = a_data ;Just move alphanumeric return endsubroutine