VA FileMan V. 22.0 Programmer Manual Banner


Main Chapter Getting Started Manual Advanced User Manual

Database Server (DBS) API

$$GET1^DIQ( ): Single Data Retriever

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.

Input Parameters

(Required) A file number or subfile number.


(Required) Standard IENS indicating internal entry numbers.

FIELD (Required) Field number, or field name, or On-the-fly Computed Expression for the FILE.

(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.

(Required for word processing fields only) The root of an array into which word processing text is copied.


(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)

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")    



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(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,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")
Error Codes Returned
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