Database Server (DBS) API

Example of Call to VA FileMan DBS

One of the DBS calls validates data. If the data is valid, the internal representation of that data is returned. If the data is invalid, a caret (^) is returned along with various messages, optionally including the relevant help text. The Validator call looks like this:

    VAL^DIE(file,iens,field,flags,value,.result,fda_root,msg_root)

REF: For details, see the "Validator" documentation.

Your call might look like Figure 103:

Figure 103: Database Server (DBS) API—Example of Call to VA FileMan DBS: Input

    >D VAL^DIE(999000,"223,",4,"H","AB",.MYANSWER,"","MYMSGS(""WIN3"")")

If MYANSWER equaled ^ after the call, your MYMSGS("WIN3") array might look like Figure 104:

Figure 104: Database Server (DBS) API—Example of Call to VA FileMan DBS: Sample Array Output

    MYMSGS("WIN3","DIERR")=1^1
    MYMSGS("WIN3","DIERR",1)=701
    MYMSGS("WIN3","DIERR",1,"PARAM",0)=4
    MYMSGS("WIN3","DIERR",1,"PARAM",3)="AB"
    MYMSGS("WIN3","DIERR",1,"PARAM","FIELD")=4
    MYMSGS("WIN3","DIERR",1,"PARAM","FILE")=999000
    MYMSGS("WIN3","DIERR",1,"PARAM","IENS")="223"
    MYMSGS("WIN3","DIERR",1,"TEXT",1)="The value 'AB' for field ALPHA DATA in
    file TEST1 is not valid."
    MYMSGS("WIN3","DIERR","E",701,1)=""
    MYMSGS("WIN3","DIHELP")=1
    MYMSGS("WIN3","DIHELP,1)="Answer must be 3-30 characters in length."
    MYMSGS("WIN3","DIMSG")=1
    MYMSGS("WIN3","DIMSG",1)="Your input was 2 characters long."
    MYMSGS("WIN3","DIMSG",2)="This is the wrong length."

• The DIERR portion of this array indicates that error number 701 is being reported. Documentation makes clear that this means that an input value was invalid.
  
  
• The PARAM nodes (also documented) give the client application the relevant file#, field#, IENS, and value. This information might be used by the application in its error handling.
  
  
• The TEXT node contains the error message.

  NOTE: It is customized to include specifics of the current error.

  
  
• The DIHELP node contains single-question-mark help for the field.
  
  
• The DIMSG nodes contain a message generated by the INPUT transform via an EN^DDIOL call.

  (The sample INPUT transform discussed in the "DIMSG Array" section produced this message.)

Now, the client application decides what (if anything) to show the user. In a GUI environment, you might decide to put the error message along with any text from the INPUT transform into a document gadget. A HELP button that could be used by the user to display the help information might be added to the box. VA FileMan's DBS has provided text; the client application is in complete control regarding the use of this text.

Reviewed/Updated: May 2026