| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
Text in the DIHELP array has several sources. Some help text is stored in the new DIALOG file; an example of this sort of help is the text returned by %DT when you enter a "?" at a prompt requiring a date. Other help comes directly from text in the Data Dictionary. Xecutable Help relies on calls to the Loader (see EN^DDIOL) embedded in the executable code. The Loader call takes the place of Writes.
NOTE: In other contexts, the Loader puts text under the DIMSG subscript. However, when executing Xecutable Help, the Loader puts the text under the DIHELP subscript instead.
The following DBS call returns 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 (Help Prompt, Description, list of Set of Codes, Xecutable Help, etc.) to return. Alternatively, a single or double question mark returns the same information that is currently returned in scrolling mode. (See the documentation for the Helper call for details.)
If MSG_ROOT is not specified as a target, the help is returned in ^TMP("DIHELP", $J) as described in the DIHELP Array topic. 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 above.
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. (For more detailed information about EN^DDIOL, see its description in the Classic VA FileMan API section of this manual.)
When the user is not in scrolling mode, the Loader will most frequently place 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 topic, when the DBS HELP^DIE call is used to get help, the output of an EN^DDIOL call embedded in Xecutable 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:
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:
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 this:
^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: the number of errors generated during the call in the first piece and the total number of lines of the error messages in the second. Thus, a $D check on the variable DIERR after the completion of the call allows the client application to determine if an error occurred. Both syntactical (e.g., the root of an array is not in the proper format for subscript indirection) and substantive (e.g., a specified field does not exist in the specified file) 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. Here is an example of error reporting following a Filer call:
>W $G(DIERR)
2^2
>D ^%G
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 the example above, 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 error(s).
^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 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 may 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 in this manual. For example, Appendix A indicates that three parameters are returned with error #501: '1', the field name or number; 'FILE', the File number; and 'FIELD', the Field number. So, in the example above, for error #501, the "PARAM" nodes indicate that the error corresponds to 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: March 10, 2007