VA FileMan Programmer Manual: $$KEYVAL^DIE( )

Contents:

Main

Database Server (DBS) API

$$KEYVAL^DIE(): Key Validator

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

Description

The $$KEYVAL^DIE extrinsic function (aka Key Validator) verifies that new values contained in the FDA do not produce an invalid key. All keys in which any field in the FDA participates are checked. If the value for a field in a key being checked is not present in the FDA, the value used to verify the key is obtained from the previously filed data.

Format

$$KEYVAL^DIE([flags,]fda_root[,msg_root])

Input Parameters

FLAGS	(Optional) Flags to control processing. The possible value is:
	Q	Quit when the first problem in the FDA is encountered.
fda_root	(Required) The root of the FDA that contains the data to be checked. The array can be a local or global one. REF: For details of the structure of the FDA, see the Database Server Introduction. The value of fields in the FDA must be the internal value. Do not pass external (e.g., unresolved POINTER values, non-VA FileMan dates) in the FDA. No action is taken on fields in the referenced FDA if those fields do not participate in a key defined in the KEY (#.31) file.
msg_root	(Optional) The root of an array into which error messages are returned. If this parameter is not included, errors are returned in the default array: ^TMP("DIERR",$J).

Output

This Boolean function returns the following:

1—If key integrity is not violated by any value in the FDA.
0—If an invalid key was produced by any of the values.

Error messages and DIERR are also returned when necessary.

Example

In Figure 171, two fields from (fictitious) File #99999 are set into an FDA. These are values for a new record; therefore, the IENS is +1,. The values (".111" and "One Fmuser") are valid internal values for fields .01 and .02. $$KEYVAL^DIE returns 0 indicating that key integrity is violated by these values. The returned error message states the values create a duplicate key. The key that is duplicated is the A key.

Figure 171: $$KEYVAL^DIE API—Example: Input and Output

>K MYERRORS,MYFDA <Enter>

>S MYFDA(99999,"+1,",.01)=.111 <Enter>

>S MYFDA(99999,"+1,",.02)="One Fmuser" <Enter>

>W $$KEYVAL^DIE("","MYFDA","MYERRORS") <Enter>
0
>W DIERR <Enter>
1^1
>ZW MYERRORS <Enter>
MYERRORS("DIERR")=1^1
MYERRORS("DIERR",1)=740
MYERRORS("DIERR",1,"PARAM",0)=3
MYERRORS("DIERR",1,"PARAM","FILE")=99999
MYERRORS("DIERR",1,"PARAM","IENS")=+1,
MYERRORS("DIERR",1,"PARAM","KEY")=11
MYERRORS("DIERR",1,"TEXT",1)=New values are invalid because they create a
duplicate
  Key 'A' for the SAMPLE file.
MYERRORS("DIERR","E",740,1)=

Error Codes Returned

Table 56 lists the possible error codes returned with the $$KEYVAL^DIE API:

Table 56: $$KEYVAL^DIE API—Error Codes Returned

Code	Description
740	A duplicate key is produced by a field's new value.
742	A value for a field in a key is being deleted.
744	Not all fields in a key have a value.

Details and Features

Possible IENS

The only placeholder the IENS in the FDA can contain is the + for records not yet added to the database. You cannot use the ? or ?+ placeholders, since the Key Validator does not attempt to look up an entry to obtain existing values for a key.

REF: For details of the IENS, see the Database Server Introduction.

For description of placeholders, see the UPDATE^DIE API.

Reviewed/Updated: May 2026