| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
This entry point performs the following functions:
If the DIALOG entry has POST MESSAGE ACTION code, this code is executed after the message has been built, but before quitting.
BLD^DIALOG(DIALOG#,[.]TEXT_PARAM,[.]OUTPUT_PARAM, OUTPUT_ARRAY,FLAGS)
| DIALOG# |
(Required) Record number from the DIALOG 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's in a |window| in the referenced DIALOG entry's text. The value of each node should be in external, printable format and will be 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 by reference. |
|
| [.]OUTPUT_PARAM |
(Optional) This is useful mainly if you are returning error messages as part of an API for other programmers 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 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 will be returned as expected but, in addition, dialog parameter values will be 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. BUT the subscript for such a parameter in the output array is always 1. |
|
| OUTPUT_ARRAY |
(Optional) If provided, the text will be 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 Reader, ^DIR. Text is output in the format needed for input to the Reader. NOTE: You are responsible for cleaning up the output array or global before calling BLD^DIALOG. 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 similar to the default output format of the ^TMP global, so that MSG^DIALOG can be called to either Write the array to the current device or to a simple local array. | |
If the OUTPUT_ARRAY input parameter is not passed, Dialog text is returned in ^TMP under the "DIERR", "DIHELP", or "DIMSG" subscripts as documented in the DBS "Contents of Arrays" section. If the DIALOG text is returned in a local array instead, the name of the array and leading subscript(s) are defined by the name of the array passed to this routine.
In addition to the DIALOG text, a local variable is returned. The local variable is one of the following:
| 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: (1) If the variable to be used (DIHELP, DIERR, or DIMSG) already exists before calling BLD^DIALOG, the number or numbers already stored in the variable are incremented (not overwritten) to reflect the cumulative total over repetitive calls to BLD^DIALOG.
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.
(2) 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.
The DIALOG entry numbers shown in the examples below are for demonstration purposes and are not distributed as part of the VA FileMan package.
Example 1
In the case of errors, the output looks like the following example. ^TMP("DIERR",$J,error_number) is set equal to the IEN from the DIALOG 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 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:
DIPAROUT(1)=TEST FILE
DIPAROUT("FILE")=662001
>D BLD^DIALOG(10999,"Myfile",.DIPAROUT)
The output looks like:
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
Here we generate a second error to show how it is appended to the previous error in the ^TMP global:
DIPARIN(1)='B'
DIPARIN("FILE")=662001
DIPAROUT(1)='B'
DIPAROUT("FILE")=662001
>D BLD^DIALOG(10202,.DIPARIN,.DIPAROUT)
Now the output looks like this:
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, we build the same error message as in Example 1, but this time we put the output into a local array. Notice that we 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.
>D BLD^DIALOG(10999,"Myfile",.DIPAROUT,"MYARRAY")
The output looks like:
DIERR=1^1
MYARRAY(1)=Entries in file Myfile cannot be edited.
Example 4
In this example, we build the same error message as in Example 3, again sending the output to a local array. This time, however, we will pass the F flag in the FLAGS parameter so that all of the error information is returned in a format similar to that of the ^TMP global, but without the $J subscript. In this format, the developer could then call MSG^DIALOG 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 FileMan write the remaining messages.
>D BLD^DIALOG(10999,"Myfile",.DIPAROUT,"MYARRAY","F")
The output looks like:
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, we 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.
>D BLD^DIALOG(10335,"PRINT")
The output looks like:
DIHELP=4
^TMP("DIHELP",591469242,1) = This number will be 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
Now we build the same help message as Example 5 but put it into a local array.
>D BLD^DIALOG(10335,"PRINT","","MYARRAY")
Now the output looks like:
DIHELP=4
MYARRAY(1)=This number will be 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 final example, we 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 FileMan Reader, ^DIR, this call puts the text into the format that the Reader expects. It does not set the DIMSG, DIHELP, or DIERR variables.
>D BLD^DIALOG(10335,"PRINT","","DIR(""?"")")
The output looks like:
DIR("?")=your operating system.
DIR("?",1)=This number will be 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
None
Reviewed/Updated: March 10, 2007