| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
The following arrays are discussed in this section:
Text in the DIHELP array has several sources:
NOTE: In other contexts, the Loader puts text under the DIMSG subscript. However, when executing Executable Help, the Loader puts the text under the DIHELP subscript instead.
The DBS call in Figure 96 returns help for a particular field:
Figure 96: Database Server (DBS) API—DIHELP Array: Input to Return Help for a Particular Field
>D HELP^DIE(file,iens,field,type_of_help,msg_root)
type_of_help is a set of flags that allows the client application to specify which help text (e.g., help prompt, description, list of SET OF CODES, executable help, etc.) to return. Alternatively, a single or double question mark returns the same information that is currently returned in scrolling mode.
REF: For details, see the documentation for the Helper call.
If msg_root is not specified as a target, the help is returned in ^TMP("DIHELP", $J) as described in the "How Information Is Returned" section. The local variable DIHELP equals the total number of nodes returned.
Text in the array that contains help is subscripted with integers. If more than one kind of help is being returned, a NULL node is put between them.
If a flag is set by the client application when the CHK^DIE or VAL^DIE calls are made, help is returned when a value is found to be invalid. The help is returned in the standard way described in the "How Information Is Returned" section.
A main source of the DIMSG array is output from the Loader: EN^DDIOL. WRITEs that are currently embedded in the database must be changed to calls to EN^DDIOL if the DBS is to be used. When running applications in scrolling mode, the Loader simply WRITEs the text to the screen. However, if the node containing the EN^DDIOL call is executed from within one of the DBS calls, the DBS returns text in an array, usually subscripted by DIMSG.
REF: For more detailed information about EN^DDIOL(): Message Loader, see its description in the "Classic VA FileMan API" section.
When the user is not in scrolling mode, the Loader most frequently places the text into the DIMSG array with the local variable DIMSG set equal to the total number of lines in the array. There are certain situations, however, where the output is put into another array. As mentioned in the DIHELP Array, when the DBS HELP^DIE call is used to get help, the output of an EN^DDIOL call embedded in executable help is placed into the DIHELP array.
Like DIHELP, the DIMSG array is simply a list of lines of text.
Suppose an INPUT transform currently contains:
Figure 97: Database Server (DBS) API—DIMSG Array: Sample INPUT Transform
N Y S Y=$L(X) K:Y>30!(Y<3) X I '$D(X) W !,"Your input was "_Y_
" characters long.",!,"This is the wrong length."
It can be changed to:
Figure 98: Database Server (DBS) API—DIMSG Array: Changing INPUT Transform: Executed in Scrolling Mode
N Y S Y=$L(X) K:Y>30!(Y<3) X I '$D(X) S Y(1)="Your input was "_Y_
" characters long.",Y(2)="This is the wrong length." D EN^DDIOL(.Y)
This change would have no effect if the user were in scrolling mode; the same message is written to the screen. However, if the second INPUT transform were executed from a silent call, nothing is written and the "DIMSG" array returned to the client application might look like Figure 99:
Figure 99: Database Server (DBS) API—DIMSG Array: Changing INPUT Transform: Executed from a Silent Call
^TMP("DIMSG",$J,1)="Your input was 2 characters long."
^TMP("DIMSG",$J,2)="This is the wrong length."
When an error condition is encountered during a DBS call, an error message and other information is placed in the DIERR array. In addition, the DIERR variable is returned with the following two pieces of information:
Thus, a $D check on the DIERR variable after the completion of the call allows the client application to determine if an error occurred. Both of the following errors are returned:
The information contained in the DIERR array is designed to give the client application-specific information about the kind of error that occurred to allow for intelligent error handling and to provide readable error messages. Figure 100 is an example of error reporting following a Filer call:
Figure 100: Database Server (DBS) API—DIERR Array: Sample Input and Output
>W $G(DIERR) <Enter>
2^2
>D ^%G <Enter>
Global ^TMP("DIERR",$J
TMP("DIERR",$J
^TMP("DIERR",731990208,1) = 305
^TMP("DIERR",731990208,1,"PARAM",0) = 1
^TMP("DIERR",731990208,1,"PARAM",1) = ^TMP("MYWPDATA",$J)
^TMP("DIERR",731990208,1,"TEXT",1) = The array with a root of
'^TMP("MYWPDATA",$J)' has no data associated with it.
^TMP("DIERR",731990208,2) = 501
^TMP("DIERR",731990208,2,"PARAM",0) = 3
^TMP("DIERR",731990208,2,"PARAM",1) = 89
^TMP("DIERR",731990208,2,"PARAM","FIELD") = 89
^TMP("DIERR",731990208,2,"PARAM","FILE") = 16200
^TMP("DIERR",731990208,2,"TEXT",1) = File #16200 does not contain a field 89.
^TMP("DIERR",731990208,"E",305,1) =
^TMP("DIERR",731990208,"E",501,2) =
The DIERR variable acts like a flag. In Figure 100, it reports that two errors occurred and that they have a total of two lines of text.
The ^TMP("DIERR",$J) global contains information about the errors.
^TMP("DIERR",$J,sequence#) = error number
In this case, two errors were returned: errors #305 and #501. Each error number corresponds to an entry in the DIALOG (#.84) file. The actual text of each error is stored in nodes descendent from "TEXT":
^TMP("DIERR",$J,sequence#,"TEXT",line#) = line of text
The ^TMP("DIERR",$J,sequence#,"PARAM") subtree contains specific parameters that can be returned with each error:
^TMP("DIERR",$J,sequence#,"PARAM",0) = number of parameters returned
with the error
^TMP("DIERR",$J,sequence#,"PARAM","param_name") = parameter value
The VA FileMan error messages and their associated parameters are documented in "Appendix A—VA FileMan Error Codes." For example, Appendix A indicates that three parameters are returned with error #501:
So, in Figure 100, for error #501, the "PARAM" nodes indicate that the error corresponds to (fictitious) File #16200, Field #89.
Finally, the "E" cross-reference in the ^TMP("DIERR",$J) global allows you to determine quickly whether a particular error occurred. For example, if you wanted to do some special error processing if a DBS call generated error #305, you could check:
$D(^TMP("DIERR",$J,"E",305))
The DIERR array is more complicated than the other arrays discussed, thereby making more information available to the client application for error handling.
Reviewed/Updated: May 2026