You can store Visual FoxPro code in the VPME data dictionary for three field-level functions: Default, PreValidation and PostValidation. We call this “field-level, data-driven developer code.
Tip – Code Validation Type: While you enter code for the Code validation type on the Integrity page, the coding rules and tips presented in this section apply to your Code validation code as well.
Select a field on the Data Builder List page, click the Edit page, then click the Code page to see the three record-level functions for which you can enter code.
When you click the check box for one of the field-level functions, the main window on the Code page becomes editable with an “LPARAMETERS” line entered. The LPARAMETERS line contains more parameters for the PreValidation and PostValidation functions than it does for the Default function. Leave the LPARAMETERS line as is and add your code after it.
The code you enter is stored in memo fields in the Field Data table, SDATADDF.DBF. The code is executed using the EXECSCRIPT() function.
You can use PreValidation and PostValidation code to apply additional validation rules to a field.
You can use PostValidation code to update or calculate other fields using the new field value — this is sometimes called a "relational edit".
For example, in the PostValidation code window shown above, the field being entered and validated is an employee’s employment date. The code updates the employee’s service date with the employment date.
Field-Level Functions Code Entry
The field-level functions for which you can enter code are described below.
· Delete: Enter code that will return a default value for a field. The default value that your code returns will be automatically entered into the field when a user adds a record to a table, view or CursorAdapter. See Field Default Options Property to learn more about setting up default values for a field.
· PreValidation: Enter code to be executed before the value entered into a field is validated. This code can be used to prevent the value from being validated, determine the value to be returned by the validation routine and/or define a message to be displayed.
· PostValidation: Enter code to be executed after the value entered into a field has passed the validation check. The code can change the value returned by the validation routine and/or define a message to be displayed. The code can also be used to change the value of other fields based on the validated field entry.
Field Validation Process
When you write code for Code validation, PreValidation or PostValidation, it is helpful to know what happens when a field is validated. Here’s the field validation process, or flow, that occurs when the focus moves off a field placed on a form based on a VPME form class with a VPME control class:
1. The active control’s Valid event is run.
2. The application object’s RunAdminTool method is run.
3. The application object’s AdminTool_FieldValidation method is run.
4. The active form’s AdminTool_FieldValidation method is run.
5. The data handler’s FieldValidation method is run. If the Integrity Option is “On” or “On/Empty/Null”:
· The business rules class’ PreFieldValidation method is run. If .F. is returned the FieldValidation method is exited.
· The data dictionary (DD) PreFieldvalidation code is run. If .F. is returned the FieldValidation method is exited.
· The DD validation type defined on the Integrity page for the field is performed.
· If the validation fails, an error message is displayed.
· If the validation passes:
· The business rules class’ PostFieldValidation method is run. If .F. is returned, the error message is displayed, and the FieldValidation method is exited.
· The DD PostFieldValidation code is run. If .F. is returned, the error message is displayed, and the FieldValidation method is exited.
Tip: See the VPME 9.1 Technical Reference manual for detailed information about the methods listed above.
Code Validation, PreValidation and PostValidation Coding Tips
This section provides tips that will help you write Code validation, PreValidation and PostValidation code that controls the field validation process.
Stopping the Field Validation Process
Returning .F. from your Code validation, PreValidation or PostValidation code will stop, or abort, the field validation process at that point.
For example, returning .F. from your PreValidation code will stop the validation process and the DD validation type rules you set up for the field and any PostValidation code will not be run.
When the field validation process stops, what happens next is determined by the value in the data handler object’s stoCallingObject.FieldValidationReturnValue property, as described below. (The object reference of the data handler object is stored in “stoCallingObject”.)
Passing or Failing Validation
When the field validation process stops, the value your code has put into the stoCallingObject.FieldValidationReturnValue property signals whether the value entered into the field has passed or failed validation, as follows:
· Fail Validation: An .F. or 0 (zero) in the FieldValidationReturnValue property signals that the field has failed validation, and the focus stays on the field.
· Pass Validation: A .T. (or anything other than .F. or 0) in the FieldValidationReturnValue property signals that the field has passed validation, and the focus moves off the field.
Controlling the Error Message
When a field’s validation fails, an error message is displayed in a system message window in the upper-right corner of the application’s main window.
The default error message is “Invalid Input”. If the field’s Error Expression property contains an entry, the error message resolved from the Error Expression property is displayed.
However, if you want to override the default error message or the Error Expression property entry. set the stoCallingObject.cFieldValidationReturnMessage property to contain the text of the message that you want to display.
If the field’s validation has been set up to allow application users to override an invalid field entry, your Code validation, PreValidation or PostValidation code can disable the ability of a user to enter an override value.
When you want to disable the Override functionality, set the data handler stoCallingObject.lValidOverrideOK property to .F. Then, when stoCallingObject.FieldValidationReturnValue is set to 0 (zero) or .F., the user will not be able to enter an override value.
Code Validation, PreValidation and PostValidation Code Parameters
The parameters passed to your Code validation, PreValidation and PostValidation code are described below along with tips for using the parameters in your code.
· stcDatabase: Name of database or cursoradapter library that contains the table, view or CursorAdapter that contains the field being validated.
· stcTableOrView: Name of the table, view or CursorAdapter that contains the field being validated.
· stcField: Name of the field being validated.
· stValue: The value to be validated. Use this value in your code.
· stcRulesID: The cRulesID form property value. You can use the cRulesID form property to store a value that is passed to your field-level code.
· For example, if your PostValidation code needed to know, say, the current application user’s Status, you can store the user’s status in the cRulesID form property and it will be passed to your code. For the user properties available to you, see Error! Reference source not found..
· stoCallingObject: The object reference of the data handling object. You can use this object reference to access the methods of the data handling object in your code.
· For example, to access the OpenTable method of the data handler, your code could use the method call “stoCallingObject.OpenTable(parameters)” where “parameters” is the parameters list expected by the OpenTable method. See the Data Handler Class chapter in the VPME 9.1 Technical Reference manual to learn about the data handler methods available to you.
Accessing Validation Table/View/CursorAdapter Fields in PostValidation Code
After a foreign key field passes Referential field validation, your PostValidation code can access any field in the Validation table/view/CursorAdapter record that contains the field's valid entry. Let’s explain what this means to you.
The Validation table/view/CursorAdapter contains a list of valid entries for a field. Sometimes it is appropriate to also store data related to the valid entries in the Validation table/view/CursorAdapter.
For example, let’s say you have a Validation table of valid zip codes. You might also store the city and state matching the zip code in each record in the Validation table. Then, when the zip code is entered into a record on a form, your PostValidation code for the zip code field can pull the city and state associated with the zip code into the record.
If you want to put FoxPro code in a field’s PostValidation code that uses fields in the current Validation record, keep the following points in mind:
· The current Validation table/view/CursorAdapter record is the record with a code value that matches the entry in the form field.
· The code that you use in your PostValidation code to pull values from the current Validation record should first check to see that the Validation table/view/CursorAdapter is open with an alias of “f2reftable”. The Validation table/view/CursorAdapter will be opened if the field passes validation. Your code would look like this:
IF USED(‘f2reftable’) AND NOT EOF('f2reftable')
Your Code to use fields from Validation table/view/CursorAdapter