VA FileMan Programmer Manual: VAL^DIE( )

Contents:

Main

Database Server (DBS) API

VAL^DIE(): Validator

Reference Type	Category	ICR #
Supported	Database Server (DBS)	2053

Description

The VAL^DIE API (aka Validator) takes the external form of user input and determines 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 VA FileMan internal value when necessary. It is this internal value that is stored. If the Validator determines that the value passed is invalid, a caret (^) 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 VA FileMan Data Array (FDA) to prepare for a later Filer call (FILE^DIE).

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	Do not 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. The value parameter can take several forms depending on the data type involved, such as a partial, unambiguous match for a POINTER) and any of the supported ways to input dates (e.g., "TODAY" or "11/3/93").
.RESULT	(Required) Local variable that receives output from call: If the value input parameter is valid, the internal value is returned. If the value input parameter is 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 the following arrays are put: Error Help Message 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 input parameter of YES would also have been acceptable and would have resulted in the same output as shown in Figure 175:

Figure 175: VAL^DIE API—Example: Input and Output

    >S FILE=16200,FIELD=5,IENS="3,",FLAG="EHFR",VALUE="Y" <Enter>

    >D VAL^DIE(FILE,IENS,FIELD,FLAG,VALUE,.ANSWER,"MYFDA(1)") <Enter>

    >ZW ANSWER <Enter>
    ANSWER=Y
    ANSWER(0)=YES

    >ZW MYFDA(1) <Enter>
    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, Table 58 lists the possible primary error messages returned with the VAL^DIE API:

Table 58: VAL^DIE API—Error Codes Returned

Code	Description
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 a value input parameter starting with a question mark (?). Help should be requested using the HELP^DIE API. If the R flag is sent, it verifies that the entry is present, and that editing is not blocked because the entry is being archived. If the field is uneditable, it rejects the input if there is already data in the field. If the passed value is NULL or @, signifying data deletion, it rejects the input if the: Field is required. Field is a key field. 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 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 a DATA TYPE field value of VARIABLE POINTER, the value input parameter can include the VARIABLE POINTER's PREFIX, MESSAGE, or FILENAME followed by a period (.) before the lookup value. If no file is specified in this way, all 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 files, the call fails (i.e., the value input parameter is not valid).
Note for SET OF CODES	For a DATA TYPE field value of SET OF CODES, the value input parameter 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 DATA TYPE field values of FREE TEXT, NUMBER, and MUMPS—The external value is created by passing value through the INPUT transform (if any) and then the OUTPUT transform (if any). DATE/TIME—The external value is the standard VA FileMan external DATE/TIME format. POINTERs and VARIABLE POINTERs—The external value is the .01 of the entry in the pointed-to file. 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 the FILE^DIE (the Filer) API 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: May 2026