VA FileMan V. 22.2 Programmer Manual Banner


 

Main Chapter Getting Started Manual Advanced User Manual

DIALOG File


DIALOG File: User Messages

Introduction

The VA FileMan DIALOG (#.84) file is used to store dialog that would normally appear on a screen during interaction with a user. This dialog can include error messages, user help, and other types of prompts. VA FileMan distributes a set of entries in the DIALOG (#.84) file.

The VA FileMan BLD^DIALOG or $$EZBLD^DIALOG APIs are used to move text from the DIALOG (#.84) file into arrays. The text can then be displayed using the display mode of choice.

Developers can add entries to the DIALOG (#.84) file. Entries such as error messages, help messages, and other general prompts can be placed in the file. The DIALOG (#.84) 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: To add entries to the DIALOG (#.84) file, you must use a numberspace assigned by the Database Administrator.

Advantages of the DIALOG (#.84) file for user interaction are:

REF: For details, see the "Internationalization and the DIALOG File" section.

Use of the DIALOG File

VA FileMan controls and distributes entries in the DIALOG (#.84) file in the number range 0 through 10000. These entries should not be edited by other package developers, except for adding foreign language equivalents for text.

REF: For details, see the "Internationalization and the DIALOG File" section.

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 "Appendix A—VA FileMan Error Codes." Entries within the VA FileMan number range that are not in the Error Codes listing should not be used, as they are subject to change.

Other packages can make entries in the DIALOG (#.84) file for their own use. The Database Administrator (DBA) assigns 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 (#.84) file. For example:

If developers do not follow these guidelines, their DIALOG (#.84) file entries can be overwritten when new packages are installed.

NOTE: An entry number does not have to be an integer; up to 3 decimal places can be used to identify an entry.

Creating DIALOG File Entries

Developers can enter or edit entries to the DIALOG (#.84) file using the VA FileMan Enter or Edit File Entries [DIEDIT] option. The only required fields are:

The dialog text can contain parameter windows delimited by vertical bars (||). Within a pair of vertical bars, the developer puts a value that corresponds to a subscript in a parameter list. This subscript does not need to be numeric, but can be meaningful alpha characters, such as "FIELD". When the dialog text with windows is retrieved using a call to either the BLD^DIALOG or $$EZBLD^DIALOG APIs, 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. The PARAMETER Multiple field is used in documenting these parameters.

For error messages only, a list of output parameters can also be passed to the BLD^DIALOG or $$EZBLD^DIALOG APIs. This list is returned by the routine in a standard format. Output parameters might be, for example, file or field numbers that the calling routine can then use to decide. Output parameters should also be documented in the PARAMETER Multiple.

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 is then executed whenever the associated message is retrieved with a call to the BLD^DIALOG or $$EZBLD^DIALOG APIs.

The TRANSLATION (LANGUAGE) Multiple in the DIALOG (#.84) file allows a developer to enter text in a language other than English.

REF: For additional information on this feature, see the "Internationalization and the DIALOG File" section.

Finally, there is a place to enter documentation for the ROUTINE names and LINE TAGs that use the dialog entries. This is optional internal documentation for use by developers only.

Figure 415 is an example creating a new entry in the DIALOG (#.84) file:

Figure 415: DIALOG File—Sample Dialog Creating a New Entry in the DIALOG (#.84) File

    Select DIALOG: 10001 <Enter>
      Are you adding '10001' as a new DIALOG (the 239TH)? Y <Enter> (YES)
    TYPE: ? <Enter>
          Enter code that reflects how this dialog is used when talking to the
    users.
          Choose from:
            1        ERROR
            2        GENERAL MESSAGE
            3        HELP
    TYPE: 3 <Enter> HELP
    PACKAGE: VA FILEMAN <Enter> DI
    DESCRIPTION:
      1>Here you enter a description of the help message itself. This
      2>description is for our own documentation.
      3><Enter>
    EDIT Option: <Enter>
    INTERNAL PARAMETERS NEEDED: Y <Enter> YES
    TEXT:
      1>Here you enter the actual text of the help messages, with
      2>parameters designated by vertical bars |1| as shown.
      3><Enter>
    EDIT Option: <Enter>
    Select PARAMETER SUBSCRIPT: 1 <Enter>
      Are you adding '1' as a new PARAMETER SUBSCRIPT (the 1ST for this
    DIALOG)? Y <Enter> (YES)
      PARAMETER DESCRIPTION: Brief description of parameter 1 goes here. For
       documentation only. <Enter>
    Select PARAMETER SUBSCRIPT: <Enter>
    POST MESSAGE ACTION: ? <Enter> 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" <Enter>
    Select LANGUAGE: <Enter>
    Select ROUTINE NAME: DIKZ// <Enter>
    ROUTINE NAME: DIKZ// <Enter>
    LINE TAG: // <Enter>

 


Reviewed/Updated: May 2026