VA FileMan V. 22.0 Programmer Manual Banner


 

Main Chapter Getting Started Manual Advanced User Manual

Database Server (DBS) API


VALS^DIE( ): Fields Validator  New/Updated with VA FileMan V. 22.0

The Fields Validator procedure validates data for a group of fields and converts valid data to internal VA FileMan format. It is intended for use with a set of fields that comprise a logical record; fields from more than one file can be validated by a single call. By default, the integrity of any keys affected by the new values is checked.

The Fields Validator performs the same checks performed by VAL^DIE (see for details).

Format
VALS^DIE(FLAGS,FDA_EXT_ROOT,FDA_INT_ROOT,MSG_ROOT)
Input Parameters
FLAGS

(Optional) Flags to control processing. The possible values are:

K

If the file has a Primary Key, this flag indicates that the Primary Key fields, not the .01 field, are to be used for lookup in the Finding and LAYGO/Finding nodes of the FDA. Without this flag, VALS^DIE assumes that you want to file the fields in the Primary Key, rather than use them for lookup, and performs the uniqueness check. This flag is equivalent to the "K" flag in the Updater (UPDATE^DIE).

R

Records identified by IENSs in the FDA_EXT are verified to exist and to be editable. (Same as R flag for VAL^DIE.)

U

Don't perform key validation. Without this flag, the data in the FDA is checked to ensure that no duplicate keys are created and that key field values are not deleted.

FDA_EXT_ROOT

(Required) The root of a standard FDA. This array should contain the external values that you want to validate. This is the input array. See the "Database Server Introduction" for details of the structure of the FDA.

FDA_INT_ROOT

(Required) The root of a standard FDA. This FDA is the output array, and upon return is set equal to the internal values of each validated field. If a field fails validation, its value is set to an up-arrow (^). (NOTE: If a field is valid, the corresponding node in the output array is set to the internal value, not an up-arrow (^), even if that field violates key integrity.) See the "Database Server Introduction" for details of the structure of the FDA

MSG_ROOT

(Optional) The root of an array (local or global) into which error messages are returned. If this parameter is not included, error messages are returned in the default array: ^TMP("DIERR",$J).

Output

See the description of the FDA_INT_ROOT for an explanation of how internal values are returned to the client application.

If an error occurs in any of the validations, the DIERR variable will be set and appropriate error messages will be returned.

Examples
  1. This simple example validates and converts the values for two fields:
    >S MYFDA("EXT",16997,"1,",1)="SOME TEXT"
    
    >S MYFDA("EXT",16997,"1,",2)="JAN 1, 1996"
    
    >D VALS^DIE("","MYFDA(""EXT"")","MYFDA(""INT"")")
    
    >W $G(DIERR)
    
    >ZW MYFDA("INT")
    MYFDA("INT",16997,"1,",1)=SOME TEXT
    MYFDA("INT",16997,"1,",2)=2960101
    


  2. This example reports that one of the values does not pass validation. Note that the value for the invalid field equals ^ in MYFDAINT.
    >S MYFDA("EXT",16997,"1,",1)="SOME TEXT"
    
    >S MYFDA("EXT",16997,"1,",2)="JAN 1, 6"
    
    >D VALS^DIE("","MYFDA(""EXT"")","MYFDA(""INT"")")
    
    >W DIERR
    1^1
    >D ^%G
    
    Global ^TMP("DIERR",$J
            TMP("DIERR",$J
    ^TMP("DIERR",610279233,1) = 701
    ^TMP("DIERR",610279233,1,"PARAM",0) = 4
    ^TMP("DIERR",610279233,1,"PARAM",3) = JAN 1, 6
    ^TMP("DIERR",610279233,1,"PARAM","FIELD") = 2
    ^TMP("DIERR",610279233,1,"PARAM","FILE") = 16997
    ^TMP("DIERR",610279233,1,"PARAM","IENS") = 1,
    ^TMP("DIERR",610279233,1,"TEXT",1) = The value 'JAN 1,
    6' for field REVERSE DATE FIELD IN KEY in file ZZD
    KEYTEST is not valid.
    ^TMP("DIERR",610279233,"E",701,1) =
    Global ^
    
    >ZW MYFDA("INT")
    MYFDA("INT",16997,"1,",1)=SOME TEXT
    MYFDA("INT",16997,"1,",2)=^
    


  3. In this example, the values pass field validation, but an error is returned because they fail the requested key integrity check.
    >K MYFDA
    
    >S MYFDA("EXT",16997,"1,",1)="TEXT INTO SECOND"
    
    >S MYFDA("EXT",16997,"1,",2)="MAR 4, 1996"
    
    >D VALS^DIE("U","MYFDA(""EXT"")","MYFDA(""INT"")")
    
    >W $G(DIERR)
    1^1
    >D ^%G
    
    Global ^TMP("DIERR",$J
            TMP("DIERR",$J
    ^TMP("DIERR",610279233,1) = 740
    ^TMP("DIERR",610279233,1,"PARAM",0) = 3
    ^TMP("DIERR",610279233,1,"PARAM","FILE") = 16997
    ^TMP("DIERR",610279233,1,"PARAM","IENS") = 13,
    ^TMP("DIERR",610279233,1,"PARAM","KEY") = 34
    ^TMP("DIERR",610279233,1,"TEXT",1) = New values are invalid 
    because they create a duplicate Key 'C' for the ZZD KEYTEST file.
    ^TMP("DIERR",610279233,"E",740,1) = 
    Global ^
    
    >ZW MYFDA("INT")
    MYFDA("INT",16997,"1,",1)=TEXT INTO SECOND
    MYFDA("INT",16997,"1,",2)=2960304
    
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.
744 Not all fields in a key have a value.
1610 Help was improperly requested.
Details and Features
Key Integrity Validation

Unless the U flag is passed, the internal values produced by the validation of the values passed in the FDA_EXT are checked to make sure that no key's integrity is violated.

 


Reviewed/Updated: March 10, 2007