VA FileMan Programmer Manual: BLD^DIALOG

Contents:

Main

Database Server (DBS) API

BLD^DIALOG(): DIALOG Extractor

Reference Type	Category	ICR #
Supported	Database Server (DBS)	2050

Description

The BLD^DIALOG API performs the following functions:

Extracts a dialog from a VA FileMan DIALOG (#.84) file entry.
Substitutes dialog parameters into the text if requested.
Returns the text in an array.

If the DIALOG (#.84) file entry has a POST MESSAGE ACTION code, this code is executed after the message has been built, but before quitting.

Format

BLD^DIALOG(dialog#[,[.]text_param][,[.]output_param][, output_array][,flags])

Input Parameters

DIALOG#	(Required) Record number from the DIALOG (#.84) file for the text to be returned.
[.]TEXT_PARAM	(Optional) Local array containing the dialog parameters to substitute into the resulting text. Set the subscript of each node in this array to a dialog parameter that is in a \|window\| in the referenced DIALOG (#.84) file entry's text. The value of each node should be in external, printable format and is substituted in the DIALOG text for that dialog parameter. If there is only one parameter in the list, you can pass its value in a local variable or as a literal; otherwise, pass it by reference.
[.]OUTPUT_PARAM	(Optional) This is useful mainly if you are returning error messages as part of an API for other developers to use. Use it to pass dialog parameters back to the user of your API, such that they can be accessed individually instead of just being embedded in the error text. Use only with DIALOG (#.84) file entries of type Error. Pass this local array by reference. Subscript each node by the parameter name and set the node to the corresponding parameter value. The parameter values can be in any format (external or internal). For example, if you pass DIPAROUT by reference and want to pass back standalone values for the “1” and “FILE” parameters in the output array along with dialog text, set DIPAROUT to: DIPAROUT(1)=TEST FILE DIPAROUT("FILE")=662001 Dialog text is returned as expected but, in addition, dialog parameter values are returned in: ^TMP("DIERR",$J,msg#,"PARAM",1) ^TMP("DIERR",$J,msg#,"PARAM","FILE") NOTE: If you only want to return one parameter, you can pass its value in a local variable or as a literal rather than in an array by reference. However, the subscript for such a parameter in the output array is always 1.
OUTPUT_ARRAY	(Optional) If provided, the text is output in the local or global array named by this parameter. If this parameter is NULL, output is returned in the ^TMP global, under the "DIERR", "DIHELP", or "DIMSG" subscripts as documented in the DBS “Contents of Arrays” section. If you specify DIR("A") or DIR("?") as the output array, special handling is provided for populating the output array for use in a call to the Response Reader, ^DIR. Text is output in the format needed for input to the Response Reader. NOTE: You are responsible for cleaning up the output array or global before calling the BLD^DIALOG API. If the array already exists, BLD^DIALOG simply appends its output to the current contents of the output array, under a new message subscript.
FLAGS	(Optional) Flags to control processing. The possible values are:
	S	Suppress the blank line that is normally inserted between discrete blocks of text that are built by separate calls to this routine.
	F	Format the local array like the default output format of the ^TMP global, so that you can call the MSG^DIALOG API to either WRITE the array to the current device or to a simple local array.

Output

If the OUTPUT_ARRAY input parameter is not passed, DIALOG (#.84) file text is returned in ^TMP under the "DIERR", "DIHELP", or "DIMSG" subscripts as documented in the DBS “Contents of Arrays” section. If the DIALOG (#.84) file text is returned in a local array instead, the name of the array and leading subscripts are defined by the name of the array passed to this routine.

In addition to the DIALOG (#.84) file text, a local variable is returned. Table 42 lists the local variables:

Table 42: BLD^DIALOG API—Output Variables Returned

Variable Name	Returned if Dialog Type Is:	Variable Value
DIERR	Error	Piece 1: # of discrete error messages returned Piece 2: Total # of lines of text returned
DIHELP	Help	Total # of lines of text returned
DIMSG	General Message	Total # of lines of text returned

NOTE:

If the variable to be used (DIHELP, DIERR, or DIMSG) already exists before calling the BLD^DIALOG API, the number or numbers already stored in the variable are incremented (not overwritten) to reflect the cumulative total over repetitive calls to the BLD^DIALOG API.
The local variable (DIHELP, DIERR, or DIMSG) is not set if you ask for text to be built in the special variables DIR("A") and DIR("?"), used as input to ^DIR.
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

The DIALOG (#.84) file entry numbers shown in the examples below are for demonstration purposes and are not distributed as part of VA FileMan.

Example 1

In the case of errors, the output looks like the following example (Figure 120). ^TMP("DIERR",$J,error_number) is set equal to the IEN from the DIALOG (#.84) file. The actual error text is contained descendent from the "TEXT" subscript. If output parameters were passed to the routine, they are returned descendent from the "PARAM" subscript, where "PARAM",0) contains the total number of output parameters. Finally, there is an entry descendent from "E", where the next subscript is the IEN from the DIALOG (#.84) file, and the final subscript refers to the error number in this output array. This serves as a sort of cross-reference by error code. When errors are generated by a routine called from developers' code, this cross-reference can be used by the developer to quickly check whether a specified error had been generated:

Figure 120: BLD^DIALOG API—Example 1: Input

    DIPAROUT(1)=TEST FILE
    DIPAROUT("FILE")=662001

    >D BLD^DIALOG(10999,"Myfile",.DIPAROUT)

The output looks like Figure 121:

Figure 121: BLD^DIALOG API—Example 1: Output

    DIERR=1^1

    ^TMP("DIERR",591465626,1) = 10999
    ^TMP("DIERR",591465626,1,"PARAM",0) = 2
    ^TMP("DIERR",591465626,1,"PARAM",1) = TEST FILE
    ^TMP("DIERR",591465626,1,"PARAM","FILE") = 662001
    ^TMP("DIERR",591465626,1,"TEXT",1) = Entries in file Myfile cannot 
       be edited.
    ^TMP("DIERR",591465626,"E",10999,1) =

Example 2

In this example (Figure 122), you generate a second error to show how it is appended to the previous error in the ^TMP global:

Figure 122: BLD^DIALOG API—Example 2: Input

    DIPARIN(1)='B'
    DIPARIN("FILE")=662001
    DIPAROUT(1)='B'
    DIPAROUT("FILE")=662001

    >D BLD^DIALOG(10202,.DIPARIN,.DIPAROUT)

The output looks like Figure 123:

Figure 123: BLD^DIALOG API—Example 2: Output

    DIERR=2^2

    ^TMP("DIERR",591465626,1) = 10999
    ^TMP("DIERR",591465626,1,"PARAM",0) = 2
    ^TMP("DIERR",591465626,1,"PARAM",1) = TEST FILE
    ^TMP("DIERR",591465626,1,"PARAM","FILE") = 662001
    ^TMP("DIERR",591465626,1,"TEXT",1) = Entries in file Myfile cannot
        be edited.
    ^TMP("DIERR",591465626,2) = 10202
    ^TMP("DIERR",591465626,2,"PARAM",0) = 2
    ^TMP("DIERR",591465626,2,"PARAM",1) = 'B'
    ^TMP("DIERR",591465626,2,"PARAM","FILE") = 662001
    ^TMP("DIERR",591465626,2,"TEXT",1) = There is no 'B' index for File
        #662001.
    ^TMP("DIERR",591465626,"E",10999,1) = 
    ^TMP("DIERR",591465626,"E",10202,2) =

Example 3

In this example (Figure 124), you build the same error message as in Example 1, but this time you put the output into a local array. Notice that you do not send a flag in the flags parameter for this call, so only the error text is returned. This would ordinarily be done when the developer planned to process the output from their own routine.

Figure 124: BLD^DIALOG API—Example 3: Input

    >D BLD^DIALOG(10999,"Myfile",.DIPAROUT,"MYARRAY")

The output looks like Figure 125:

Figure 125: BLD^DIALOG API—Example 3: Output

    DIERR=1^1

    MYARRAY(1)=Entries in file Myfile cannot be edited.

Example 4

In this example (Figure 126), you build the same error message as in Example 3, again sending the output to a local array. This time, however, you pass the F flag in the flags parameter; so that all the error information is returned in a format like that of the ^TMP global, but without the $J subscript. In this format, the developer could then call the MSG^DIALOG API to either write the array to the current device or to copy the text into a simple array. This might, for example, be done when the developer wanted to examine the error messages returned and KILL some of them before having VA FileMan write the remaining messages.

Figure 126: BLD^DIALOG API—Example 4: Input

    >D BLD^DIALOG(10999,"Myfile",.DIPAROUT,"MYARRAY","F")

The output looks like Figure 127:

Figure 127: BLD^DIALOG API—Example 4: Output

    DIERR=1^1

    MYARRAY("DIERR",1)=10999
    MYARRAY("DIERR",1,"PARAM",0)=2
    MYARRAY("DIERR",1,"PARAM",1)=TEST FILE
    MYARRAY("DIERR",1,"PARAM","FILE")=662001
    MYARRAY("DIERR",1,"TEXT",1)=Entries in file Myfile cannot be     edited.
    MYARRAY("DIERR","E",10999,1)=

Example 5

In this example (Figure 128), you build a help message with a single input parameter. Notice that the only output is the DIHELP variable and the text. Similarly, other types of messages only return the DIMSG variable and the text.

Figure 128: BLD^DIALOG API—Example 5: Input

    >D BLD^DIALOG(10335,"PRINT")

The output looks like Figure 129:

Figure 129: BLD^DIALOG API—Example 5: Output

    DIHELP=4

    ^TMP("DIHELP",591469242,1) = This number is used to determine
        how large to make the generated
    ^TMP("DIHELP",591469242,2) = compiled PRINT routines. The size
        must be a number greater
    ^TMP("DIHELP",591469242,3) = than 2400, the larger the better, up
        to the maximum routine size for
    ^TMP("DIHELP",591469242,4) = your operating system.

Example 6

In this example (Figure 130), you build the same help message as Example 5 but put it into a local array.

Figure 130: BLD^DIALOG API—Example 6: Input

    >D BLD^DIALOG(10335,"PRINT","","MYARRAY")

The output looks like Figure 131:

Figure 131: BLD^DIALOG API—Example 6: Output

    DIHELP=4

    MYARRAY(1)=This number is used to determine how large to make
        the generated
    MYARRAY(2)=compiled PRINT routines. The size must be a number
        greater
    MYARRAY(3)=than 2400, the larger the better, up to the maximum
        routine size for
    MYARRAY(4)=your operating system.

Example 7

In this example (Figure 132), you build the same help message as in Example 6 but put it into the special array DIR("?"). Note that for the special local variables used for calls to the VA FileMan Response Reader, ^DIR, this call puts the text into the format that the Response Reader expects. It does not set the DIMSG, DIHELP, or DIERR variables.

Figure 132: BLD^DIALOG API—Example 7: Input

    >D BLD^DIALOG(10335,"PRINT","","DIR(""?"")")

The output looks like Figure 133:

Figure 133: BLD^DIALOG API—Example 7: Output

    DIR("?")=your operating system.
    DIR("?",1)=This number is used to determine how large to make the generated
    DIR("?",2)=compiled PRINT routines. The size must be a number greater
    DIR("?",3)=than 2400, the larger the better, up to the maximum routine size for

Error Codes Returned

None.

Reviewed/Updated: May 2026