| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
The VA FileMan DIALOG file is used to store dialog that would normally appear on a screen during interaction with a user. This dialog may include error messages, user help, and other types of prompts. FileMan distributes a set of entries in the DIALOG file.
The VA FileMan calls, BLD^DIALOG or $$EZBLD^DIALOG, are used to move text from the DIALOG file into arrays. The text can then be displayed using the display mode of choice.
Developers may add entries to the DIALOG file. Entries such as error messages, help messages and other general prompts can be placed in the file. The DIALOG file should not be used for storing alternate synonyms either for data or for fields in the data dictionary such as field labels or descriptions.
NOTE: If you wish to add entries to the DIALOG file, you must apply to the DataBase Administrator (DBA) for a numberspace.
Advantages of the DIALOG file for user interaction are:
VA FileMan controls and distributes entries in the DIALOG file in the number range 0 through 10000. These entries should not be edited by other package developers, with the exception of adding foreign language equivalents for text (see the " Internationalization and the DIALOG File" section of the "DIALOG File" chapter for details). Some of the VA FileMan error messages are available for retrieval by other package developers, using the VA FileMan program calls. These messages are listed in the "Error Codes" chapter. Entries within the FileMan number range that are not in the Error Codes listing should not be used as they are subject to change.
Other packages may make entries in the DIALOG file for their own use. The VHA Database Administrator (DBA) will assign number ranges to a subscribing package.
If your package or site already has a file numberspace assigned by the DBA, you can use that number (or numbers) multiplied by 10000 (plus any decimal value between .001 and .999) for adding entries to the DIALOG file. (Ex., Kernel owns file 200, so they can use numbers 2000000 2000000.999. If I'm site 665, I own numberspace 665000 for files, so I can use 6,650,000,000 through 6,650,000,000.999 in the DIALOG file).
If developers do not follow these guidelines, their DIALOG entries may be overwritten when new packages are installed. Note that an entry number does not have to be an integer--up to 3 decimal places can be used to identify an entry.
Developers may enter or edit entries to the DIALOG file using VA FileMan Enter/Edit. The only required fields are the DIALOG NUMBER which uniquely identifies the entry, the TYPE (Error, Help or General Message), and the dialog TEXT.
Dialog text can contain parameter windows delimited by vertical bars. Within a pair of vertical bars, the developer puts a value that will correspond to a subscript in a parameter list. This subscript need not be numeric, but may be meaningful alpha characters such as "FIELD". When the dialog text with windows is retrieved using a call to either BLD^DIALOG or $$EZBLD^DIALOG, a subscripted parameter list is input to the call. The parameters are matched by subscript to the windows in the text, and the values from the parameter list are inserted into the corresponding windows in the text. If parameters are included in the text, the INTERNAL PARAMETERS NEEDED field should be set to YES. A multiple field called PARAMETER is used in documenting these parameters.
For error messages only, a list of output parameters can also be passed to BLD^DIALOG or $$EZBLD^DIALOG. This list is returned by the routine in a standard format. Output parameters might be, for example, file or field numbers which the calling routine may then use to make a decision. Output parameters should also be documented in the PARAMETER multiple described immediately above.
Another important optional field is the POST-MESSAGE ACTION field. If the developer wishes to perform some special action whenever a message is retrieved, M code is simply inserted into this field. The code will then be executed whenever the associated message is retrieved with a call to BLD^DIALOG or $$EZBLD^DIALOG.
The TRANSLATION (LANGUAGE) multiple in the DIALOG file allows a developer to enter text in a language other than English. See the "Internationalization and the DIALOG File" section of the "DIALOG File" chapter for additional information on this feature.
Finally, there is a place to enter documentation for the ROUTINE names and LINE TAGs which use the dialog entries. This is optional internal documentation for the use by developers only.
Following is an example creating a new entry in the DIALOG file.
Select DIALOG: 10001
Are you adding '10001' as a new DIALOG (the 239TH)? Y (YES)
TYPE: ?
Enter code that reflects how this dialogue is used when talking to the users.
Choose from:
1 ERROR
2 GENERAL MESSAGE
3 HELP
TYPE: 3 HELP
PACKAGE: VA FILEMAN DI
DESCRIPTION:
1>Here we enter a description of the help message itself. This
2>description is for our own documentation.
3>
EDIT Option:
INTERNAL PARAMETERS NEEDED: Y YES
TEXT:
1>Here we enter the actual text of the help messages, with
2>parameters designated by vertical bars |1| as shown.
3>
EDIT Option:
Select PARAMETER SUBSCRIPT: 1
Are you adding '1' as a new PARAMETER SUBSCRIPT (the 1ST for this DIALOG)? Y (YES)
PARAMETER DESCRIPTION: Brief description of parameter 1 goes here. For
documentation only.
Select PARAMETER SUBSCRIPT:
POST MESSAGE ACTION: ? This is Standard MUMPS code. This code will be
executed whenever this message is retrieved through a call to BLD^DIALOG
or $$EZBLD^DIALOG
POST MESSAGE ACTION: S MYVAR="HELP #10001 WAS REQUESTED"
Select LANGUAGE:
Select ROUTINE NAME: DIKZ//
ROUTINE NAME: DIKZ//
LINE TAG: //
Reviewed/Updated: March 10, 2007