Field Validations

Field Validations are used to verify that a field value matches a valid value. One of four types of field validations may be defined:

 

In addition, for any field you may define a custom field validation method. This method, a function, is assigned to a field by setting the field’s field validation message. During validation this function will be called. If an error is detected, the function should generate an error and return a non-zero value. This function allows you to create any kind of validation rule you need.

Field validation occurs during forward navigation and during saves.  Using field validations ensures that the data being saved to your database is valid.

Checkbox

 

Set Field_Checkbox_Values field Customer.status to "A" "I"

The Field_Checkbox_Values message sets the field up for use in a checkbox control. A checkbox field can only store one of two values; a true value and a false value.

If the field is represented by a checkbox control (dbCheckbox), then the control will be checked  when the field value equates to true, and is unchecked when the field value equates to false.

If the field is represented by a form control (dbForm) then data entry will be restricted to either the true value or the false value.

When a validation error occurs, the error number and text specified for the field in the Field_Error property are used to report an error. If no text was defined, a standard check-error text will be reported.

Range

 

Set Field_Value_Range field Customer.discount to 0 60

The Field_Value_Range method allows you to define a minimum and maximum range for the field. It is expected that the field and its range will be Numeric or Date. The From value must be lower than the To value.

The validation is performed after the user has entered data into the field’s data-entry form. If the validation fails, then the user is prohibited from leaving the form. (The user may still exit the form by clicking elsewhere on the screen with the mouse).

When a validation error occurs, the error number and text specified for the field in the Field_Error property are used to report an error. If no text was defined, a standard check-error text will be reported.

The validation is also performed when a record is saved. If the validation fails, the save is aborted.

Check

 

Set Field_Value_Check field Customer.region to "N|S|E|W"

The Field_Value_Check message is used when the list of valid field values is limited to a static, small set of simple values. These samples are identified in a "check" string. This consists of a list of valid values separated by the | symbol. For example, the choices A, B and C would be represented by the check string A|B|C. The choices CA, FL, and TX would be represented by the check string CA|FL|TX.

The validation is performed after the user has entered data into the field’s data-entry form. If the validation fails, then the user is prohibited from leaving the form. (The user may still exit the form by clicking elsewhere on the screen with the mouse). The validation is also performed when a record is saved. If the validation fails, the save is aborted.

In addition to being used for validation, these values may also be used with combo-box entry items. If a dbComboForm is assigned to a field using check values, each value in the check string will be loaded into the combo list.

Set Field_Value_Check field Customer.state to "CA|FL|NY|AZ"

The Customer.state example above is probably not a good usage of this validation method. Adding new states to this list requires program changes, and the string may quickly become too large to be practical. In such a case, you will want to use a validation table to provide the values.

When a validation error occurs, the error number and text specified for the field in the Field_Error property are used to report an error. If no text was defined, a standard check-error text will be reported.

The Check validation is limited. A more flexible and reusable way of specifying a list of valid entries is to use a Validation Table.

Validation Tables

 

Set Field_Value_Table Field Customer.Status to oStatusTable

If a field needs to be validated against one of two values, a limited set of values, or a range of values, you can use the checkbox, range or check validations.  In many cases you will find that these types of validations are too limited for your needs. In such a case, you may use field validation tables.

Using a field-validation table has the following advantages:

 

When a validation error occurs, the error number and text specified for the field in the Field_Error property are used to report an error. If no text was defined, a standard check-error text will be reported.

The use of validation tables provides tremendous flexibility. They will be discussed in greater detail in Using Validation Tables. For now, we will introduce the primary validation-table classes:

ValidationTable

This class allows you to maintain a list of valid values.

Object oStatusTable is a ValidationTable

     Procedure Fill_List

          Send add_table_value "O"

          Send add_table_value "C"

          Send add_table_value "D"

     End_Procedure

End_Object

 

DescriptionValidationTable

This class allows you to maintain a list of valid values and their associated descriptions.

Object oStatusTable is a DescriptionValidationTable

     Procedure Fill_List

          Send add_table_value "O"  "Opened"

          Send add_table_value "C"  "Closed"

          Send add_table_value "D"  "Flagged for Deletion"

     End_Procedure

End_Object

 

FileValidationTable

This class allows you to maintain a list of values and descriptions that can be easily loaded from a specified DataFlex table.

Object Status_Table is a FileValidationTable

    Set Main_File to CustStat.File_Number

End_Object

 

CodeValidationTable

This class allows you to load your data and description values from the DataFlex Code List.

Object oStatusTable is a CodeValidationTable

    Set Type_Value to "Status"

End_Object

Any of the above validation tables can be linked to a field with the Field_Value_Table message in a data dictionary.

Set Field_Value_Table Field Customer.Status to oStatusTable

 

Field Validation Methods

 

Set Field_Validate_msg field employee.pay_type to get_valid_pay_type

The Field_Validate_msg property lets you assign a general-purpose message to be sent when a field should be validated. This message will be the message-Id of a function and will get called whenever your program requires a validation. This validation method is used when you need to perform complex validations that can only be expressed with code. Since it is a very open-ended process, it can do just about anything. If the value is valid, the function should return a zero. If the value is invalid, the function should generate an error (probably by sending the UserError message) and return a non-zero value.

This validation method can be used in conjunction with the other validation techniques (checkbox, range, check, validation table) or as a replacement to them.

You must create the validation function(s). This function will get passed the field number and the current field value. Your function may use these values as it sees fit. For this purpose, the value of any other field in the data dictionary may be obtained by getting the Field_Current_Value property. It is important to note that the validation routine should never need to access a value in a DEO.  The information required should be found in the DDO or in one of the DDOs connected to it.

For example, if you have the following member function…

Function ValidateCredit Integer iField Number nValue ;

                        Returns Boolean

 

    Boolean bErr

    String sCustRating

 

    // get the customer rating for this customer from DD buffer

    Get Field_Current_Value field Customer.Rating to sCustRating

 

    // if Customer Rating is A1 their limit is 5000

    If (sCustRating="A1" and nValue > 5000) Begin

        Send UserError "Credit limit may not exceed $5000"

        Move True To bErr

    End

 

    Function_Return bErr

End_Function

To use this function on the Credit_Limit field of a file, you must set the field’s validate method (Field_Validate_msg) to the handle name of the function. The handle name of a function is the name of the function prefixed with “get_” (e.g., get_ValidateCredit).Set Field_Validate_msg field Customer.Credit_Limit to get_ValidateCredit

The declaration prototype for a validation method takes the following general form.

Function function_name integer iField type CurrentValue returns integer

Where:
 

This allows you to write generalized validation-method functions that can be re-used for other fields and tables.

Field Validation Errors

 

Set Field_Error field Customer.Credit_Limit to 0 "Not a legal number"

The Field_Error method allows you to define a specific error number and message to be raised whenever validation fails for the field. This means that each field can have its own specific validation error message.

Normally you do will need to provide a custom error number. In this case, just use zero as your error number.

The error is triggered when one of the following validation tests fails: checkbox, range, check or validation table.  Validation Methods should have their own error texts coded inside the member function.

 

See Also

Defining Data Dictionary Field Attributes