VA FileMan Programmer Manual: CHK^DIE( )

Contents:

Main

Database Server (DBS) API

CHK^DIE(): Data Checker

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

Description

The CHK^DIE API (aka Data Checker) checks user-supplied data against the data dictionary definition of a field. If the input data passes the validation, the internal and, optionally, the external forms of the data are returned. In this respect, CHK^DIE is the inverse of the $$EXTERNAL^DILFD API.

While this API indicates that a user's response is valid according to a field's definition, it does not assure that a value can be filed in a particular record. To verify that a value can be filed, use the VAL^DIE or FILE^DIE calls (with the E flag). CHK^DIE does not have IENS as input; it is ignorant of the state of the data.

Do not pass a value input parameter of NULL or @ to CHK^DIE. This API cannot verify that deletion of values from the database is appropriate. Again, use VAL^DIE or FILE^DIE (with E flag) for this purpose.

Format

CHK^DIE(file,field[,flags],value,.result[,msg_root])

Input Parameters

FILE	(Required) File or subfile number.
FIELD	(Required) Field number for which data is being validated.
FLAGS	(Optional) Flags to control processing. The possible values are:
	H	Help (single "?") is returned if VALUE is not valid.
	E	External value is returned in RESULT(0).
VALUE	(Required) Value to be validated, as entered by a user. The value parameter can take several forms depending on the DATA TYPE field value involved, such as a partial, unambiguous match for a POINTER or any of the supported ways to input dates (e.g., "TODAY" or "11/3/93").
.RESULT	(Required) Local variable that receives output from the call. If value is: Valid—The internal value is returned. Not Valid—^ is returned. If the E flag is passed, external value is returned in RESULT(0). NOTE: This array is KILLed at the beginning of each call.
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 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

In Figure 169, data for a DATA TYPE field value of DATE/TIME is being checked. Note that the external form of the user's input, which was "T-180", is passed. In this case, the value was acceptable, as shown in Figure 169:

Figure 169: CHK^DIE API—Example: Input and Output

    >S FILE=16200,FIELD=201,FLAG="E",VALUE="T-180" <Enter>

    >D CHK^DIE(FILE,FIELD,FLAG,VALUE,.RESULT) <Enter>

    >ZW RESULT <Enter>
    RESULT=2930625
    RESULT(0)=JUN 25,1993

Error Codes Returned

In addition to errors that indicate that the input parameters are invalid, Table 53 lists the possible error codes returned with the CHK^DIE API:

Table 53: CHK^DIE API—Error Codes Returned

Code	Description
120	Error occurred during execution of a FileMan hook.
701	Value is invalid.

Details and Features

What is Checked	This call verifies that the value passed is valid by passing it through the field's INPUT transform. Also, if the field has any screens, those screens must be passed. If the field is a POINTER or VARIABLE POINTER, this call verifies that there is an unambiguous match (or partial match) for value.
Entry Number Caution	No internal entry numbers are available when the INPUT transform or screens for the field are executed. Therefore, the INPUT transform and screens cannot reference any entry numbers using either the DA() array or the D0, D1, D2, etc., variables. Likewise, Executable Help cannot reference an entry number if the H flag is sent.

Reviewed/Updated: May 2026