| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
This procedure takes text from one of the FileMan dialog arrays (for errors, help text, or other text) or from a similarly structured local array, writes it and/or moves it into a simple local array.
The subscripting of these arrays will tell the developer whether the dialog is a "Help" message, an "Error" message, or other dialog, such as a prompt. Different combinations of these messages may be returned from the DBS calls. In addition, error messages will be returned whenever an error occurs, either in the way the call was made or in attempting to interact with the database.
With the DBS calls, it becomes the job of the developer to display dialog to the end user as needed, perhaps in a GUI box or in the bottom portion of a screen-oriented form. The developer can also save error messages in a file.
MSG^DIALOG is designed to make it easier for the developer to use the dialog arrays. The developer can use MSG^DIALOG to do simple formatting of the dialog and to either write dialog to the current device or to move the dialog to a simple local array for further processing.
MSG^DIALOG(FLAGS,.OUTPUT_ARRAY,TEXT_WIDTH,LEFT_MARGIN,INPUT_ROOT)
| FLAGS |
(Optional) Flags to control processing. If none of the text-type flags (E, H or M) is entered, the routine behaves as if E were entered. If no flags are entered, it behaves as if FLAGS contained WE. The possible values are: |
|
| A | Local Array specified by the second parameter receives the text. | |
| W | Writes the text to the current device. | |
| S | Saves the ^TMP or other designated input array (does not kill the array). | |
| E | Error array text is processed. | |
| H | Help array text is processed. | |
| M | Message array text (other text) is processed. | |
| B | Blank lines are suppressed between error messages. | |
| T | Return Total number of lines in the top level node of the local array specified by the second parameter. | |
| .OUTPUT_ARRAY |
(Optional) This parameter contains the name of the local array to which the text is to be written. If FLAGS contains an A, this parameter must be sent. Otherwise, the parameter is ignored. Note that the output array is killed before the text is added, not appended to what is already there. |
|
| TEXT_WIDTH |
(Optional) Maximum line length for formatting text. If specified, the text is broken into lines of this length when writing to the current device or when moving the text to the OUTPUT_ARRAY. Lines are not "joined" to fill out to this width. If you don't specify TEXT_WIDTH:
|
|
| LEFT_MARGIN |
(Optional) Left margin for writing text. If sent, the text is lined up in a column starting at this column number. Otherwise, the text is lined up with the left margin (column 0). This parameter has no effect on text sent to an array (A flag). |
|
| INPUT_ROOT |
(Optional) Closed root of local input array in which text resides. If the text resides in a local array, this parameter must be sent. The last non-variable subscript of the local array must describe the type of text it contains, as the ^TMP global normally does ("DIERR" for errors, "DIHELP" for help text, or "DIMSG" for other text). |
|
If W is passed in the FLAGS parameter, the text is written to the current device. If A is passed in the FLAGS parameter, the text is written to the local array whose name is specified in the second parameter. The format of that array is:
| ARRAY |
Total number of lines (only returned if the T flag is passed in the FLAGS parameter). |
| ARRAY(n) |
A line of formatted text (n=sequential integer starting with 1). |
If FLAGS does NOT contain S, then the input array and associated local variables (DIMSG, DIHELP, DIERR) are killed.
NOTE: If you wish to add entries to the DIALOG file, you must use a numberspace assigned by the Database Administrator. See the Developer Tools, Dialog File section in this manual for more information.
Example 1
In this first example, we want to write the error text to the current device and kill the input array. Notice that because no flags are sent to the call, the default flags for Write Error message (WE) are assumed. Thus, the call will write the single error message "The record is currently locked," from the "DIERR" portion of the ^TMP global. It will also kill ^TMP("DIERR",$J) and the local variable DIERR as follows:
^TMP("DIERR",698526778,1) = 110
^TMP("DIERR",698526778,1,"TEXT",1) = The record is currently
locked.
^TMP("DIERR",698526778,"E",110,1) =
^TMP("DIHELP",698526778,1) = This number will be used to determine
how large to make the generated
^TMP("DIHELP",698526778,2) = compiled PRINT TEMPLATE routines. The
size must be a number greater
^TMP("DIHELP",698526778,3) = than 2400, the larger the better, up
to the maximum routine size for
^TMP("DIHELP",698526778,4) = your operating system.
^TMP("DIMSG",698526778,1) = Records from list on ZZMYARRAY SEARCH
template.
Then, write the error text to the current device and kill the input array:
>D MSG^DIALOG()
The record is currently locked.
Example 2
In this example, we want to write the help text from the "DIHELP" subscripted portion of the ^TMP global, both to the current device and to the local 'MYARRAY' array. In addition, we want to format each line to 50 as follows:
>D MSG^DIALOG("HAW",.MYARRAY,50,5)
This number will be used to determine how large to make the generated compiled PRINT template routines. The size must be a number greater than 2400, the larger the better, up to the maximum routine size for your operating system.
>ZW MYARRAY
MYARRAY(1)=This number will be used to determine how large to
MYARRAY(2)=make the generated
MYARRAY(3)=compiled PRINT TEMPLATE routines. The size must
MYARRAY(4)=be a number greater
MYARRAY(5)=than 2400, the larger the better, up to the
MYARRAY(6)=maximum routine size for
MYARRAY(7)=your operating system.
Example 3
In the third example, help text was returned from a DBS call in a local array. This was done because the developer specified to the DBS call that dialog was to be returned in its own local array rather than in the ^TMP global. Suppose our local array looks like this:
MYHELP("DIHELP",1)=This number will be used to determine how large
to make the generated
MYHELP("DIHELP",2)=compiled PRINT TEMPLATE routines. The size must
be a number greater
MYHELP("DIHELP",3)=than 2400, the larger the better, up to the
maximum routine size for
MYHELP("DIHELP",4)=your operating system.
If the developer wishes to write the text to the current device and to preserve the 'MYHELP' local array, the call and the results will look like this:
>D MSG^DIALOG("WSH","","","","MYHELP")
This number will be used to determine how large to make the generated compiled PRINT template routines. The size must be a number greater than 2400, the larger the better, up to the maximum routine size for your operating system.
None
Reviewed/Updated: March 14, 2007