Validation unit
A form's Validation Unit property controls the granularity of validation in the form. The validation unit can be an item, record, block, or form. Most Form Builder applications validate at the item level.
When validation occurs
Form Builder performs validation when
Form Builder navigates out of the validation unit. This occurs when the end user presses certain function keys or clicks the mouse outside the validation unit, or a trigger executes certain built-ins.
A trigger invokes the ENTER built-in, or the end user presses [Enter].
A trigger invokes the COMMIT_FORM built-in, or the end user presses [Commit]. In this case Form Builder validates the form regardless of the validation unit.
A trigger invokes the VALIDATE built-in.
Form Builder does not perform validation in Enter Query mode. This allows the end user to enter query criteria that Form Builder would find invalid.
How validation proceeds
Internally, Form Builder maintains a status for each item, record, block, and form. For purposes of validation, each potential validation unit has a validation status with one of two values:
Valid
Unvalidated
The Valid status means that Form Builder does not need to examine the validation unit. The Unvalidated status, a combination of states known internally as New and Changed, means that Form Builder needs to validate the items in the validation unit. The distinction between New and Changed appears only rarely in the validation process (see the note in the Record entry in the table that follows).
A third state occurs if validation fails, but in that case Form Builder does not proceed until the situation is corrected, so the failed status does not enter into the validation process.
Form Builder validates a validation unit according to following processes:
Item
If the item's status is Valid, the process stops. If the status is Unvalidated, Form Builder performs standard validation checks, then fires the WHEN-VALIDATE-ITEM trigger. (See, however, the Defer Required Enforcement property.)
Record
If the record's status is Valid, the process stops. If the status is Unvalidated, Form Builder validates each item in the record, then fires the WHEN-VALIDATE-RECORD trigger.
Note: if the validation is as a result of a call to the VALIDATE trigger and the record's internal status is New, the process stops.
Block
Form Builder validates all records in the block.
Form
Form Builder validates all blocks in the form.
Item validation status
Unvalidated
Form Builder sets the status of an item to Unvalidated when any of the following occurs:
Form Builder creates a record.
The end user types a value into the item, or a trigger causes a value to be stored into the item.
Note: Form Builder sets the status of the item to Unvalidated even if the new value is the same as the old value. For example, if an item with Valid status has the value 10 and the end user types 10 into the item, Forms Builder sets the status of the item to Unvalidated.
? When Form Builder duplicates a record (in response to the DUPLICATE_RECORD built-in or the [Duplicate Record] key), any item that has Unvalidated status in the original has Unvalidated status in the duplicate.
Valid
Form Builder sets the status of an item to Valid in the following cases:
? When Form Builder successfully validates an item, it sets the item's status to Valid, even if validation changes the item's value (through a WHEN-VALIDATE-ITEM, WHEN-VALIDATE-RECORD, or POST-CHANGE trigger). Form Builder does not re-validate the changed value.
Caution: This behavior avoids validation loops, but a trigger error can cause Form Builder to commit an invalid value to the database.
? When Form Builder fetches records from the database, it sets their status to Valid, even if a Post-Change trigger that fires during the fetch changes item values.
? When Form Builder successfully commits data to the database, it sets the status of all items in the form to Valid. Form Builder does not validate changes caused by triggers that fire during the commit transaction.
Note: See Changing Data During Commit Processing for exceptions to this rule.
? When Form Builder duplicates a record (in response to the DUPLICATE_RECORD built-in or the [Duplicate Record] key), any item that has Valid status in the original has Valid status in the duplicate.
Record validation status
Each record has a validation status of Unvalidated or Valid.
Note: a record's validation status is not equivalent to the value of the SYSTEM.RECORD_STATUS system variable.
Unvalidated
Form Builder sets the status of a record to Unvalidated in the following cases:
? When Form Builder creates a record, it sets its status to Unvalidated.
? When Form Builder sets the status of an item in the record to Unvalidated, it sets the status of the record to Unvalidated.
? When Form Builder duplicates a record (in response to the DUPLICATE_RECORD built-in or the [Duplicate Record] key), it sets the status of the duplicate record to Unvalidated.
Valid
Form Builder sets the status of a record to Valid in the following cases:
When Form Builder validates a record, it validates each item that does not already have a status of Valid. If all items have Valid status at the completion of this process, and if the WHEN-VALIDATE-RECORD trigger, if any, returns without raising the Form_Trigger_Failure exception, Form Builder sets the status of the record to Valid.
Form Builder sets to Valid the status of records fetched from the database.
When Form Builder successfully commits data to the database, it sets the status of each record in the form to Valid. Form Builder does not validate changes caused by triggers that fire during the commit transaction.
Note: See Changing Data During Commit Processing for exceptions to this rule.
? When Form Builder (in response to the DUPLICATE_RECORD built-in or the [Duplicate Record] key) duplicates a record that has Valid status, it sets the status of the duplicate record to Valid.
Standard validation checks
Form Builder uses the requirements specified in the Data and List of Values (LOV) sections of the property palette to validate an item.
Validation sequence for text items
For text items, Form Builder performs one of the following sequences of validation steps, depending on whether the item's value is null or not-null. If the text item fails a validation step, Form Builder notes the failure and omits the subsequent validation steps.
When the item's value is null:
1. If the item's Required property has a setting of Yes, the item fails validation -- unless item-level validation is occurring and one of the following is true:
? The form's Defer Required Enforcement property has the setting Yes or 4.5. (For a discussion of validation behavior in these cases, see Defer Required Enforcement property.)
? The item instance does not allow end-user update.
Under either of the above exceptional conditions, Form Builder defers validating the null item until record-level validation. (Note that if the item instance does not allow end-user update, validation is deferred even if Defer Required Enforcement is set to No.)
2 If the item's Required property has a setting of No, then the WHEN-VALIDATE-ITEM trigger is fired. If the trigger raises the Form_Trigger_Failure exception, the item fails this validation step.
When the item's value is not null:
1. Check data type. If the value does not match the item's data type, the item fails this validation step.
Form Builder tries to convert a user-entered value to the item's data type.
If the item has a format mask, Form Builder uses it. If the item has no format mask and its data type is DATE or DATETIME, Form Builder uses the input format mask derived at Form Builder startup.
If the item has no format mask and is of data type NUMBER or ALPHA, Form Builder checks for a valid numeric or alphabetic text string.
2. Check length. If the value does not match the item's Fixed Length property, the item fails this validation step.
3. Check range. If the value does not match the item's Lowest Allowed Value and Highest Allowed Value properties, the item fails this validation step.
4 If the item's Use LOV for Validation property has the value Yes, verify that the value appears in the item's list of values.
5. Fire the POST-CHANGE trigger. If the trigger raises the Form_Trigger_Failure exception, the item fails this validation step.
6. Fire the WHEN-VALIDATE-ITEM trigger. If the trigger raises the Form_Trigger_Failure exception, the item fails this validation step.
Validation sequence for non-text items
If the item's Item Type property does not have the value Text Item, Form Builder follows the above sequence, but omits steps 3 through 5. It also omits step 2 unless the Item Type property has the value List Item and the List Style property has the value Combo Box.
Validation of synchronized items
If items, say B and C, have their Synchronize with Item properties set to the name of another item, say A, then A, B, and C form a set of synchronized items. A is the master item of the set, and B and C are subordinate items. Synchronized items were called mirror items in earlier versions of Form Builder.
The items of a synchronized set share a common data value, but can have different item properties. Form Builder takes data-specific properties and triggers from the master item and ignores those properties and triggers for the subordinate items.
When validating the value assigned to a synchronized set of items, Form Builder uses the following data-specific properties and triggers from the master item:
? Required property
? Highest Allowed Value property
? Lowest Allowed Value property
? Initial Value
? POST-CHANGE trigger
? WHEN-VALIDATE-ITEM trigger
If the subordinate item has values for these properties or specifications for these triggers, Form Builder ignores them and issues a warning.
Form Builder takes the remaining validation properties from the item through which the data value is set—either programmatically or by end user action. In particular, Form Builder uses the Fixed Length and Validate from List properties of that item.
The SYSTEM.TRIGGER_ITEM variable contains the name of the item through which the data value was set. This allows code in the POST-CHANGE or WHEN-VALIDATE-ITEM trigger to refer to properties of that item, even though these triggers are defined for the master item.
Form Builder considers a value that has not been set programmatically or by the end user to be set by the master item, because that is the source Form Builder uses for the initial value.
During record-level validation, Form Builder validates the item through which the data value was set. If validation fails, Form Builder gives focus to that item, unless the item instance does not allow end user input. In that case, Form Builder tries to give focus to another item of the synchronized set that does allow end user input. If it fails to find one, it tries to give focus to an item of the set for which the Enabled property has the value Yes.
No comments:
Post a Comment