|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
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
