|Contents:||Main||Chapter||See Also:||Getting Started Manual||Advanced User Manual|
The purpose of the Validator procedure is to take the external form of user input and determine if that value is valid, i.e., if that value can be put into the VA FileMan database. In addition, the Validator converts the user-supplied value into the FileMan internal value when necessary. It is this internal value that is stored. If the Validator determines that the value passed is invalid, an up-arrow (^) is returned.
Word processing and computed fields cannot be validated. The .01 field of a multiple must be input using FILE = subfile number and FIELD = .01.
Optionally, the Validator does the following:
(Required) File or subfile number.
(Required) Standard IENS indicating internal entry numbers.
(Required) Field number for which data is being validated.
(Optional) Flags to control processing. The possible values are:
|E||External value is returned in RESULT(0).|
|F||FDA node is set for valid data in array identified by FDA_ROOT.|
|H||Help (single ?) is returned if VALUE is not valid.|
|R||Record identified by IENS is verified to exist and to be editable. Do not include "R" if there are placeholders in the IENS.|
|U||Don't perform key validation. Without this flag, the data in VALUE is checked to ensure that no duplicate keys are created and that key field values are not deleted.|
(Required) Value to be validated as input by a user. VALUE can take several forms depending on the data type involved; e.g., a partial, unambiguous match for a pointer; any of the supported ways to input dates (such as "TODAY" or "11/3/93").
(Required) Local variable which receives output from call. If VALUE is valid, the internal value is returned. If not valid, ^ is returned. If E flag is present, external value is returned in RESULT(0).
NOTE: This array is killed at the beginning of each Validator call.
(Optional; required if F flag present) Root of FDA into which internal value is loaded if F flag is present.
(Optional) Root into which error, help, and message arrays are put. If this parameter is not passed, these arrays are put into nodes descendent from ^TMP.
See input parameters .RESULT, FDA_ROOT, and MSG_ROOT.
RESULT = internal value or ^ if the passed VALUE is not valid.
RESULT(0) = external value if the passed VALUE is valid and E flag is present.
This example checks the validity of a value for a set of codes field. Note that the flags indicate that the external value should be returned and that a node in the FDA should be built. In this situation a VALUE of "YES" would also have been acceptable and would have resulted in exactly the same output as shown below:
>S FILE=16200,FIELD=5,IENS="3,",FLAG="EHFR",VALUE="Y" >D VAL^DIE(FILE,IENS,FIELD,FLAG,VALUE,.ANSWER,"MYFDA(1)") >ZW ANSWER ANSWER=Y ANSWER(0)=YES >ZW MYFDA(1) MYFDA(1,16200,"3,",5)=Y
In addition to codes indicating that the input parameters are incorrect and that the file, field, or entry does not exist, primary error messages include:
|120||Error occurred during execution of a FileMan hook.|
|299||Ambiguous value. (Variable Pointer data type only.)|
|405||The file is uneditable.|
|520||The field's data type or INPUT transform is inappropriate.|
|602||The entry cannot be edited.|
|701||Value is invalid.|
|710||The field is uneditable.|
|712||An inappropriate deletion of a field's value is being attempted.|
|740||A duplicate key is produced by a field's new value.|
|742||A value for a field in a key is being deleted.|
|1610||Help was improperly requested.|
|What is Validated||
The Validator takes the following steps in validating the input data:
NOTE: No file or field access security checks on either the file or field level are done.
|Note for Pointers||
The internal entry number of the entry in the pointed-to file that corresponds to the input is returned. If the lookup value partially matches more than one entry in the pointed-to file, the call fails.
|Note for Variable Pointers||
For variable pointer data types, the VALUE may include the variable pointer PREFIX, MESSAGE, or FILENAME followed by a period (.) before the lookup value. If no particular file is specified in this way, all of the pointed-to files are searched. If the lookup value is not found in any file searched or if more than one match is found in any file(s), the call fails - VALUE is not valid.
|Note for Set of Codes||
For set of codes data types, VALUE is treated as case insensitive. If the VALUE is ambiguous, the validation fails.
|Returning External Values||
If the E flag is sent, the Validator returns the external value of VALUE in addition to its internal value. This is returned in RESULT(0). For free text, number and MUMPS data types, the external value is created by passing VALUE through the INPUT transform (if any) and then the OUTPUT transform (if any). For date/time data types, the external value is the standard FileMan external date/time format. For pointers and variable pointers, the external value is the .01 of the entry in the pointed-to file. For set of codes, the external value is the "translation" of the code.
|Validate and File||
If you want to validate a set of data and then file the valid data, make a call to FILE^DIE (the Filer) with an E flag passed in the first parameter. The nodes in the FDA identified by the second parameter should be set to the external, unvalidated value used as input to the Validator. Based on this flag, the Filer calls the Validator for each field and only files the valid, internal values. Error messages are returned for the fields that could not be filed.
NOTE: You cannot mix internal and external values in the FDA when calling the Filer.
Reviewed/Updated: March 10, 2007