VA FileMan V. 22.0 Programmer Manual Banner


 

Main Chapter Getting Started Manual Advanced User Manual

Database Server (DBS) API


$$KEYVAL^DIE( ): Key Validator 

The Key Validator extrinsic function 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 values are:

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. See the "Database Server Introduction" for details of the structure of the FDA.

The value of fields in the FDA must be the internal value. Do not pass external (e.g., unresolved pointer values, non-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 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 a 1 if key integrity is not violated by any value in the FDA and a 0 if an invalid key was produced by any of the values. Error messages and DIERR are also returned when necessary.

Example

In the following example, two fields from File #99999 (SAMPLE file) are set into an FDA. These are values for a new record; therefore, the IENS is "+1,". The values (".111" and "Albert Jones") 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.

>K MYERRORS,MYFDA

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

>S MYFDA(99999,"+1,",.02)="Albert Jones"

>W $$KEYVAL^DIE("","MYFDA","MYERRORS")
0
>W DIERR
1^1
>ZW MYERRORS
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
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 will not attempt to lookup an entry to obtain existing values for a key. (See the "Database Server Introduction" for details of the IENS; see UPDATE^DIE for description of placeholders.)

 


Reviewed/Updated: March 10, 2007