| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
This extrinsic function converts any internal value to its external format. It decodes codes, makes FileMan dates readable, and follows pointer or variable pointer chains to resolve their values. OUTPUT transforms are applied to their fields. For more information about how FileMan handles OUTPUT transforms and pointers, read this function's "Details and Features."
$$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 in. |
|
| FIELD |
(Required) The number of the field that describes the internal value passed in. |
|
| 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. See "Details and Features" in this section for definition and explanation of pointer chains. 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 FileMan does not process the value further. This means it is the responsibility of the OUTPUT transform to resolve codes, transform dates, and follow pointer or variable pointer chains to their destination. The default handling of pointer chains, therefore, is to follow the chain either until the last field is found, at which point the field is transformed according to its data type, or until a field with an OUTPUT transform is found, at which point FileMan applies the OUTPUT transform to the field where it is found and quits. 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. With the exception of this function, 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.
Example 1
>W $$EXTERNAL^DILFD(19,4,"","A")
action
Example 2
>W $$EXTERNAL^DILFD(4.302,.01,"",2940209.0918)
FEB 09, 1994@09:18
Example 3
>W $$EXTERNAL^DILFD(3.7,.01,"",DUZ)
DOE,JOHN
Example 4
>W $$EXTERNAL^DILFD(3298428.1,.01,"",1)
11111 1 11111
Example 5
>W $$EXTERNAL^DILFD(3298428.1,.01,"F",1)
11111 1 11111
Example 6
>W $$EXTERNAL^DILFD(3298428.1,.01,"L",1)
22222 TOAD 22222
Example 7
>W $$EXTERNAL^DILFD(3298428.1,.01,"U",1)
11111 TOAD 11111
Example 8
>W $$EXTERNAL^DILFD(3298428.1,.01,"GGG",1) W DIERR D ^%G
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) =
| 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. |
| Data Types |
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, below.) FileMan must perform the transformation whenever such a value is displayed. The data types that undergo this process are: |
|
| Date/Time | The internal value is a numeric code, while the external is readable text. For example, the internal value of 2940214.085938 has 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 may 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 file, then the external value is ALABAMA, because the .01 of the State file is defined as Free Text (needing no transform) and the .01 field of record # 1 in the State file is ALABAMA. | |
| Variable Pointer | Unlike the Pointer data type, 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, 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 |
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 (see immediately below). |
|
| Pointer Chains |
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 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 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 FileMan continues to treat OUTPUT transforms on pointer chains as described under the F flag (under Input Parameters, above). |
|
Reviewed/Updated: March 10, 2007