| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
This extrinsic function retrieves data from a single field in a file.
Data may be retrieved from any field, including computed or word processing fields, and fields specified using relational syntax. A basic call does not require that any local variables be present and the symbol table is not changed by this utility. However, computed expressions may require certain variables to be present and can change the symbol table because the data retriever does execute Data Dictionary nodes.
The text for word processing fields is returned in a target array. If data exists for word processing fields, this function returns the resolved TARGET_ROOT. Otherwise null is returned.
$$GET1^DIQ(FILE,IENS,FIELD,FLAGS,TARGET_ROOT,MSG_ROOT)
| FILE |
(Required) A file number or subfile number. |
|
| IENS |
(Required) Standard IENS indicating internal entry numbers. |
|
| FIELD | (Required) Field number, or field name, or On-the-fly Computed Expression for the FILE. | |
| FLAGS |
(Optional) Flags to control processing. The possible values are: |
|
| I | Internal format is returned. (The default is external.) | |
| Z | Zero node included for word processing fields on target array. | |
| A# | Audit Trail is used to retrieve the value
of 'FIELD' at a particular point in time.
# is a date/time in FileMan internal format (e.g., 3021015.8). The value retrieved is the (audited) value of the field as of that date/time. |
|
| TARGET_ROOT |
(Required for word processing fields only) The root of an array into which word processing text is copied. |
|
| MSG_ROOT |
(Optional) Closed root into which the error message arrays are put. If this parameter is not passed, the arrays are put into nodes descendent from ^TMP. |
|
Example 1
Following is an example of retrieving the value from the .01 field of Record #1 in File #999000:
>W $$GET1^DIQ(999000,"1,",.01)
DOE,JOHN
Example 2
Following is an example of retrieving the internally-formatted value from the SEX field of Record #1 in File #999000:
>S X=$$GET1^DIQ(999000,"1,","SEX","I")
>W X M
Example 3
Use the SUBTYPE pointer field in file 3.5 to navigate to the Terminal type file and retrieve the DESCRIPTION field as follows:
>S X=$$GET1^DIQ(3.5,"55,","SUBTYPE:DESCRIPTION")
>W X WYSE 85
Example 4
Following is an example of retrieving the contents of a word processing field and storing the text in the target array, WP:
>S X=$$GET1^DIQ(999000,"1,",12,"","WP")
>ZW
WP(1)=THIS WP LINE 1
WP(2)=WP LINE2
WP(3)=AND SO ON
X=WP
Example 5
Retrieve the contents of a word processing field, storing the text in the target array, WP. The format parameter "Z" means the target array is formatted like the nodes of a FileMan Word Processing field. If no data exists, WP is equal to null as follows:
>S WP=$$GET1^DIQ(999000,1,12,"Z","WP") ZW WP
WP=WP
WP(1,0)=THIS WP LINE 1
WP(2,0)=WP LINE2
WP(3,0)=AND SO ON
Example 6
Following is an example of retrieving data from a subfile. Here's a partial record entry, number 323, in ^DIZ(999000:
^DIZ(999000,323...
.
.
^DIZ(999000,323,4,2,1,0) = ^999000.163^1^1
^DIZ(999000,323,4,2,1,1,0) = XXX2M3F.01^XXX2M3F1^XXX2M3F2
^DIZ(999000,323,4,2,1,"B","XXX2M3F.01",1) =
^DIZ(999000,323,4,"B","XXX1",1) =
^DIZ(999000,323,4,"B","XXX2",2) =
>S IENS="1,2,323,"
>W $$GET1^DIQ(999000.163,IENS,2) XXX2M3F2
Example 7
Retrieve the value of the .01 field of record #1 in file 999000 as of 1 January, 2000. Suppose that Auditing has been turned on for that field, and that early in 2000, an incorrect spelling of "DOE,JOHN" had been corrected:
>W $$GET1^DIQ(999000,"1,",.01,"A3000000") DORE,JOHN
| 200 | There is an error in one of the variables passed. |
| 202 | Missing or invalid input parameter. |
| 301 | Flags passed are unknown or incorrect. |
| 309 | Either the root of the multiple or the necessary entry numbers are missing. |
| 348 | The passed value points to a file that does not exist or lacks a Header Node. |
| 401 | The specified file or subfile does not exist. |
| 403 | The file lacks a Header Node. |
| 404 | The file Header Node lacks a file #. |
| 501 | The field name or number does not exist. |
| 505 | The field name passed is ambiguous. |
| 510 | The data type for the specified field cannot be determined. |
| 520 | An incorrect kind of field is being processed. |
| 537 | Field has a corrupted pointer definition. |
| 601 | The entry does not exist. |
| 603 | A specific entry in a specific file lacks a value for a required field. |
| 648 | The value points to a file that does not exist or lacks a Header Node. |
Reviewed/Updated: October 2016