ECHKFLD_METHOD

Perform user field validation

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

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.

Note

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

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.

Note

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