Database Server (DBS) API

MSG^DIALOG(): Output Generator

Description

The MSG^DIALOG API takes text from one of the VA FileMan dialog arrays (for errors, help text, or other text) or from a similarly structured local array, writes it, and moves it into a simple local array.

The subscripting of these arrays tells the developer whether the dialog is:

• A “Help” message.
• An “Error” message.
• Other dialog, such as a prompt.

Different combinations of these messages can be returned from the DBS calls. In addition, error messages are 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 Graphical User Interface (GUI) box or in the bottom portion of a screen-oriented form. The developer can also save error messages in a file.

The MSG^DIALOG API is designed to make it easier for the developer to use the dialog arrays. The developer can use the MSG^DIALOG API 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.

Format

MSG^DIALOG([flags][,.output_array][,text_width][,left_margin][,input_root])

Input Parameters

Output

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:

If the flags parameter does not contain S, then the input array and associated local variables (DIMSG, DIHELP, and DIERR) are KILLed.

NOTE: To add entries to the DIALOG (#.84) file, you must use a numberspace assigned by the database administrator (DBA).

REF: For more information on the DIALOG (#.84) file, see the “DIALOG File” section.

Examples

Example 1

In this first example (Figure 137), you 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 writes the single error message “The record is currently locked,” from the “DIERR” portion of the ^TMP global. It also KILLs ^TMP(“DIERR”,$J) and the local variable DIERR as follows (Figure 137):

Figure 137: MSG^DIALOG API—Example 1: “DIERR” Portion of the ^TMP Global

    ^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 is 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 as shown in Figure 138:

Figure 138: MSG^DIALOG API—Example 1: Input and Output

    >D MSG^DIALOG()
    The record is currently locked.

Example 2

In this example (Figure 139 and Figure 140), you 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, you want to format each line to 50 as follows (Figure 139):

Figure 139: MSG^DIALOG API—Example 2: Input

    >D MSG^DIALOG("HAW",.MYARRAY,50,5)

This number is 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.

Figure 140: MSG^DIALOG API—Example 2: Output

    >ZW MYARRAY
    MYARRAY(1)=This number is 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 (Figure 141), 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 the local array looks like this (Figure 141):

Figure 141: MSG^DIALOG API—Example 3: Sample Local Array with Help Text Returned

    MYHELP("DIHELP",1)=This number is 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 look like this (Figure 142):

Figure 142: MSG^DIALOG API—Example 3: Input

    >D MSG^DIALOG("WSH","","","","MYHELP")

This number is 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.

Error Codes Returned

None.

Reviewed/Updated: May 2026