Field Validations are used to verify that a field value matches a valid value. One of four types of field validations may be defined:
Checkbox - value entered must be one of two values - most often used with checkbox entry items.
Range - value entered must be within the numeric or date range
Check - value entered must match item within a “check string” – a string of valid values separated by the “|” character.
Validation Table – value entered must match a value within a validation table object. A special validation table called a Code Validation Table provides a way to easily assign a set of valid codes and descriptions to any field.
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.
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.
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.
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.
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:
You can specify a larger number of valid values than can easily fit within a check string
You can specify and display a description for each value
You can dynamically maintain your list of values (i.e., the values do not have to be coded directly in your program)
You can make the list choices optional (i.e., you can display a list of suggested values during data entry but users are not required to make a selection from the list)
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:
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
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
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
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
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
Function_name is the name of the validation function;
iField is the field number of the field that sent function_name. The field number can be used to retrieve any information about the field; and,
type and CurrentValue are the data type and current value of the field that sent function_name.
This allows you to write generalized validation-method functions that can be re-used for other fields and tables.
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.
Defining Data Dictionary Field Attributes