VA FileMan Programmer Manual: VAL^DIE( )

Contents:

Main

Database Server (DBS) API

VAL^DIE( ): Validator

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:

Returns the resolved external value of the data.
Returns help text for invalid values.
Loads the internal value into the FileMan Data Array (FDA) to prepare for a later Filer call.

Format

VAL^DIE(FILE,IENS,FIELD,FLAGS,VALUE,.RESULT,FDA_ROOT,MSG_ROOT)

Input Parameters

FILE	(Required) File or subfile number.
IENS	(Required) Standard IENS indicating internal entry numbers.
FIELD	(Required) Field number for which data is being validated.
FLAGS	(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.
VALUE	(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").
.RESULT	(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.
FDA_ROOT	(Optional; required if F flag present) Root of FDA into which internal value is loaded if F flag is present.
MSG_ROOT	(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.

Output

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.

Example

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

Error Codes Returned

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.

Details and Features

What is Validated	The Validator takes the following steps in validating the input data: Rejects value starting with "?". Help should be requested using HELP^DIE call. If R flag is sent, verifies that the entry is present and that editing is not blocked because the entry is being archived. If the field is uneditable, rejects the input if there is already data in the field. If the passed value is null or "@", signifying data deletion, rejects the input if the field is required, if the field is a key field, or if the tests present in any "DEL" nodes for the field are not passed. For multiples, the deletion of the last subentry in the multiple is rejected if the multiple is required. Verifies that the value of the field is not DINUMed. Checks all keys in which the field participates to ensure the new value does not create any duplicate keys. Passes the value through the field's INPUT transform and executes any screens on pointer, variable pointer, or set of codes fields. For pointer and variable pointer, values that do not yield at least a partial match are rejected (no LAYGO); ambiguous values are rejected (see note below for variable pointers). If these tests are passed, the input value is accepted and the internal value becomes the value resulting in the execution of the INPUT transform or the pointer value resulting from the lookup. 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