| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
| Reference Type | Category | ICR # |
|---|---|---|
| Supported | Database Server (DBS) | 2055 |
The $$EXTERNAL^DILFD extrinsic function converts any internal value to its external format. It does the following:
OUTPUT transforms are applied to their fields.
REF: For more information about how VA FileMan handles OUTPUT transforms and POINTERs, see the "Details and Features" section.
$$EXTERNAL^DILFD(file,field[,flags],internal[,msg_root])
| file |
(Required) The number of the file or subfile that contains the field that describes the internal value passed. |
|
| field |
(Required) The number of the field that describes the internal value passed. |
|
| flags |
(Optional) To control processing. A single-character code that explains how to handle OUTPUT transforms found along POINTER chains. The default describes how fields not found along a POINTER chain are always handled, regardless of whether a flag is passed. REF: For definition and explanation of POINTER chains, see the "Details and Features" section. The default, if no flag is passed, is the way this function generally handles OUTPUT transforms. If a field has an OUTPUT transform, the transform is applied to the internal value of the field and VA FileMan does not process the value further. This means it is the responsibility of the OUTPUT transform to:
The default handling of POINTER chains, therefore, is to follow the chain either until:
The possible values are: |
|
| F | If the First field in a POINTER chain has an OUTPUT transform, apply the transform to that first field and quit. Ignore any other OUTPUT transforms found along the POINTER chain. Except for this function, VA FileMan regularly handles OUTPUT transforms this way. | |
| L | If the Last field in a POINTER chain has an OUTPUT transform, apply the transform to that last field and quit. Ignore any other OUTPUT transforms found along the POINTER chain. | |
| U | Use the first OUTPUT transform found on the last field in the POINTER chain. Following the POINTER chain, watch for OUTPUT transforms. When one is found, remember it, but keep following the POINTER chain. When the last field in the chain is reached, apply the remembered transform to that last field. | |
| internal |
(Required) The internal value that is to be converted to its external format. |
|
| msg_root |
(Optional) The array that should receive any error messages. This must be a closed array reference and can be either local or global. For example, if msg_root equals "OROUT(42)", any errors generated appear in OROUT(42,"DIERR"). If the msg_root is not passed, errors are returned descendent from ^TMP("DIERR",$J). |
|
This function evaluates to an external format value, as defined by a field in a file in the database. In the event of an error, this function outputs the empty string instead.
Figure 193: $$EXTERNAL^DILFD API—Example 1: Input and Output
>W $$EXTERNAL^DILFD(19,4,"","A") <Enter>
action
Figure 194: $$EXTERNAL^DILFD API—Example 2: Input and Output
>W $$EXTERNAL^DILFD(4.302,.01,"",2940209.0918) <Enter>
FEB 09, 1994@09:18
Figure 195: $$EXTERNAL^DILFD API—Example 3: Input and Output
>W $$EXTERNAL^DILFD(3.7,.01,"",DUZ) <Enter>
FMPATIENT,27
Figure 196: $$EXTERNAL^DILFD API—Example 4: Input and Output
>W $$EXTERNAL^DILFD(3298428.1,.01,"",1) <Enter>
11111 1 11111
Figure 197: $$EXTERNAL^DILFD API—Example 5: Input and Output
>W $$EXTERNAL^DILFD(3298428.1,.01,"F",1) <Enter>
11111 1 11111
Figure 198: $$EXTERNAL^DILFD API—Example 6: Input and Output
>W $$EXTERNAL^DILFD(3298428.1,.01,"L",1) <Enter>
22222 TOAD 22222
Figure 199: $$EXTERNAL^DILFD API—Example 7: Input and Output
>W $$EXTERNAL^DILFD(3298428.1,.01,"U",1) <Enter>
11111 TOAD 11111
Figure 200: $$EXTERNAL^DILFD API—Example 8: Input and Output
>W $$EXTERNAL^DILFD(3298428.1,.01,"GGG",1) W DIERR D ^%G <Enter>
1^1
Global ^TMP("DIERR"
TMP("DIERR"
^TMP("DIERR",731987397,1) = 301
^TMP("DIERR",731987397,1,"PARAM",0) = 1
^TMP("DIERR",731987397,1,"PARAM",1) = GGG
^TMP("DIERR",731987397,1,"TEXT",1) = The passed flag(s) 'GGG' are unknown or
inconsistent.
^TMP("DIERR",731987397,"E",301,1) =
Table 64 lists the possible error codes returned with the $$EXTERNAL^DILFD API:
Table 64: $$EXTERNAL^DILFD API—Error Codes Returned
| Code | Description |
|---|---|
| 202 | The input parameter is missing or invalid. |
| 301 | The passed flag(s) are unknown or inconsistent. |
| 348 | The passed value points to a file that does not exist or lacks a Header Node. |
| 401 | File # does not exist. |
| 403 | File # lacks a Header Node. |
| 404 | The Header node of the file lacks a file number. |
| 501 | File # does not contain a field. |
| 510 | The data type cannot be determined. |
| 537 | Corrupted pointer definition. |
| 603 | Entry lacks the required Field #. |
| 648 | The value points to a file that does not exist or lacks a Header Node. |
The internal value of a field is the way it is stored in the database. The external value is the way a user expects the field to look. (See also "OUTPUT Transforms.") VA FileMan must perform the transformation whenever such a value is displayed. The data types that undergo this process are listed in Table 65:
Table 65: $$EXTERNAL^DILFD API—VA FileMan Data Types
| Data Type | Description |
|---|---|
| DATE/TIME | The internal value is a numeric code, while the
external is readable text. For example, the internal value of:
2940214.085938Has an external value of: FEB 14,1994@ 08:59:57 |
| NUMERIC | The internal and external values are identical. |
| SET OF CODES | The full external value is decoded from abbreviated internal value. Each SET OF CODES field defines which codes are allowed and what they mean. For example, the internal value of F can have the external value of FEMALE for a certain field. |
| FREE TEXT | The internal and external values are identical. |
| WORD-PROCESSING | $$EXTERNAL^DILFD does not handle this data type. |
| COMPUTED | This data type does not have an internal value, so $$EXTERNAL^DILFD does not handle this data type. |
| POINTER TO A FILE | The internal value of this field is the internal entry number of one record in the pointed-to file. The external format of a POINTER value is the external format of the .01 field of the record identified by the POINTER's internal value. The definition of a POINTER must always identify the pointed-to file. For example, if 1 is the internal value of a POINTER to the STATE (#5) file, then the external value is ALABAMA, because the .01 of the STATE (#5) file is defined as FREE TEXT (needing no transform) and the .01 field of record #1 in the STATE (#5) file is ALABAMA. |
| VARIABLE POINTER | Unlike the DATA TYPE field with a value of POINTER,
the internal value of a VARIABLE POINTER identifies the pointed-to file. Like
the POINTER, the VARIABLE POINTER's external format is the external value of
the .01 field of the pointed-to record. The Prefix.Value notation many users
are familiar with is not the external format of a VARIABLE POINTER; that is
merely a user interface convention. For example, the internal value:
1;DIC(5,It has the external format of: ALABAMA(It is the VARIABLE POINTER equivalent of the previous example.) |
| MUMPS | The internal and external values are identical. |
OUTPUT transforms assume full responsibility for transforming the internal value to its external format. So, transforms on sets of codes work with values like F, not FEMALE; those on POINTERs deal with 1, not ALABAMA; etc. This includes following POINTER Chains to their conclusions.
A POINTER chain is a list of one or more POINTER fields that point to one another in sequence, the final POINTER of which points to a file with a non-POINTER .01 field. Thus, for example, if the .01 field of File A points to the STATE (#5) file, that is a POINTER chain with one link. If File B points to File A, that makes a POINTER chain with two links. Chains can be made up of any mix of POINTERs and VARIABLE POINTERs. Every field in the chain except the first one must be a .01 field, since POINTERs point to files, not fields; the first POINTER field may or may not be a .01 field.
When VA FileMan converts a POINTER or VARIABLE POINTER to its external value, it must follow the links to the final field and convert that field to its external value. An OUTPUT transform on a POINTER field, therefore, must do the same. The flags available for this function allow developers to try out different ways of handling OUTPUT transforms on POINTER fields. These flags only alter this function's behavior, however. The rest of VA FileMan continues to treat OUTPUT transforms on POINTER chains as described under the F flag (under "Input Parameters").
Reviewed/Updated: May 2026