VA FileMan Programmer Manual: EN^DDIOL

Contents:

Main

Classic VA FileMan API

EN^DDIOL: Message Loader

EN^DDIOL is designed as a replacement for simple WRITE statements in any part of the data dictionary that has a programming 'hook', such as executable help.

As alternate user interfaces are developed for accessing VA FileMan databases, developers are faced with the issue of removing embedded WRITE statements from their data dictionaries. Direct writes should be removed since they might cause the text to display improperly in the new interface. This separation of the user interface from the database definition helps you to prepare your databases for access by any new interface, such as a Graphical User Interface (GUI).

The environment in which the Loader is called determines how it processes the text it is passed.

Mode	How the Text Is Processed
Scrolling mode	Text is written to the screen
ScreenMan mode	Text is written in ScreenMan's Command Area
DBS mode	Text is loaded into an array

In DBS mode, the specific array where the text is placed depends on which DBS call is made and whether an output array was specified in the DBS call.

For example, if a call is made to the Validator (VAL^DIE), and the INPUT transform of the field makes a call to the Loader, the text is placed into ^TMP("DIMSG",$J). If a call is made to the Helper (HELP^DIE), and the executable help of the field makes a call to the Loader, the text is placed into ^TMP("DIHELP",$J). If the call to Validator or the Helper uses the MSG_ROOT parameter, the text is placed in the array specified by MSG_ROOT.

Recommendation: no line of text passed to the Loader should exceed 70 characters in length.

Formats

```
EN^DDIOL(VALUE,"",FORMAT)
```
```
EN^DDIOL(.ARRAY)
```
```
EN^DDIOL("",GLOBAL_ROOT) 
```

Input Parameters

VALUE	(Optional) If there is just one line of text to output, it can be passed in the first parameter.
.ARRAY	(Optional) If there is more than one line of text to output, stored in a local array, then the first parameter of the call is the name of the local array passed by reference and that contains string or numeric literals, where: ARRAY(1) = string 1 ARRAY(2) = string 2 ... ARRAY(n) = string n Formatting instructions can also be included in this array. See "Formatting for Arrays" in Details and Features below.
GLOBAL_ ROOT	(Optional) An alternate way to pass the text to the call is in a global root. In that case, the first parameter is null, and the second parameter contains the name of the global root that contains string or numeric literals, where: @GLOBAL_ROOT@(1,0) = string 1 @GLOBAL_ROOT@(2,0) = string 2 ... @GLOBAL_ROOT@(n,0) = string n or @GLOBAL_ROOT@(1) = string 1 @GLOBAL_ROOT@(2) = string 2 ... @GLOBAL_ROOT@(n) = string n Formatting instructions can also be included in this global array. See "Formatting for Arrays" in Details and Features below.
FORMAT	(Optional) Formatting instructions controlling how the string is written or placed in the array. You can specify: One or more new lines before the string (!, !!, !!!, etc.) Horizontal position of string (?n) FORMAT can be any number of "!" characters optionally followed by "?n", where n is an integer expression. The default FORMAT is "!". This parameter can only be used when call format is used to pass a single string or numeric literal to EN^DDIOL. To pass formatting instructions when text is passed as an array or global to EN^DDIOL, see "Formatting for Arrays" in Details and Features below.

Examples

Example 1

Suppose a Write Identifier node contains the following WRITE statement:

    ^DD(filenumber,0,"ID","W1")=W "   ",$P(^(0),U,2)

An equivalent statement converted to use EN^DDIOL is:

    ^DD(filenumber,0,"ID","W1")=D EN^DDIOL("   "_$P(^(0),U,2),"","?0")

Example 2

The executable help of a field passes one line of text by value to the Loader as illustrated below:

    >D EN^DDIOL("This is one line of text.","","!!?12")

If the call is made in scroll mode (e.g., ^DIE executes the executable help), below is an example of what the Loader writes to the screen:

    This is one line of text.

If the call is made in DBS mode, the Helper (HELP^DIE) executes the executable help. The text is placed into the ^TMP global as shown below:

    ^TMP("DIHELP",$J,1)=""
    ^TMP("DIHELP",$J,2)="        This is one line of text."

Example 3

Below is an example of passing an array of text to the Loader:

    >S A(1)="First line."
    >S A(2)="Second line, preceded by one blank line or node."
    >S A(2,"F")="!!"
    >S A(3)="More text on second line."
    >S A(3,"F")="?55"
    >D EN^DDIOL(.A)

Example 4

Below is an example of passing a global that contains text to the Loader:

    >S ^GLB(1)="First line."
    >S ^GLB(2)="Second line, preceded by one blank line or node."
    >S ^GLB(2,"F")="!!"
    >S ^GLB(3)="More text on second line."
    >S ^GLB(3,"F")="?55"
    >D EN^DDIOL("","^GLB")

Details and Features

Formatting for Arrays

When you pass an array or a global to EN^DDIOL, you can also pass formatting instructions for each line of text in your array or global. These instructions control how the string is written or placed in the output array. You can specify:

One or more new lines before the string (!, !!, !!!, etc.)
Horizontal position of string (?n)

Place the formatting instructions for a line of text in an "F" node descendent from the node containing the text. The value of each "F" node can be any number of "!" characters optionally followed by "?n", where n is an integer expression. The default FORMAT is "!".

For example:

    A(1) = string 1
    A(1,"F") = format (e.g., "!?35", "?10", etc.)

    ^G(1,0) = string 1
    ^G(1,"F") = format

    ^G(1) = string 1
    ^G(1,"F") = format

NOTE: If you use format (1) to pass a single string of text to EN^DDIOL, you can pass the formatting instructions in the third parameter FORMAT.

Reviewed/Updated: March 10, 2007