VA FileMan V. 22.0 Programmer Manual Banner


Main Chapter Getting Started Manual Advanced User Manual

Classic VA FileMan API

EN^DIQ1: Data Retrieval

This entry point retrieves data from a file for a particular entry. NOTE: The equivalent Database Server calls are GETS^DIQ and $$GET1^DIQ.

It is your responsibility to kill the output array, ^UTILITY("DIQ1",$J), before and after using this call.

Input Variables

The file number or global root.


A string specifying the data fields to retrieve for the given entry. The DR-string may contain:

  • A single number corresponding to the internal number of a field in the file.

  • A range of field numbers, in the form M:N, where M is the first and N the last number of the inclusive range. All fields whose numbers lie within this range will be retrieved.

  • A combination of the above, separated by semicolons. If field numbers .01, 1, 2, 4, 10, 11, 12, 13, 14, 15, and 101 exist for a file, and you want to retrieve the data in these fields, simply write:
        S DR=".01;1;4;10:15;101"

If you want to retrieve values from fields from a subentry in a multiple field, include the top-level field number for the multiple in DR. Then, include the multiple's subfield numbers whose values you want to retrieve in a node in DR, subscripted by the subfile number.

See also DA(subfile_number) below for how to specify which subfile entry to retrieve.

For example, if you want to retrieve data from subfields .01 and 7 for subentry 1 from field 4 which defines the multiple 16000.02, then you write:

    S DIC=16000,DR="4",DA=777
    S DR(16000.02)=".01:7",DA(16000.02)=1
    D EN^DIQ1

The internal number of the entry from which data is to be extracted.


If you want to retrieve values from fields from a subentry in a multiple, set DA to the top-level entry number. Then, include the subentry number in a node in DA, subscripted by the subfile number. See DR(subfile_number) above for how to specify which fields in the subfile entry to retrieve.

You can descend one or more subfile levels; however, you can only retrieve values for one subentry at any given subfile level. The full path from the top level of the file to the lowest-level subfile entry must be fully specified in nodes in DR and DA.


(Optional) The local array name into which the field values will be placed. ^UTILITY("DIQ1",$J, will be used if DIQ is not present. This array name should not begin with DI.


(Optional) This variable is used to control which is returned: internal values, external values, or both. DIQ(0) also indicates when null values are not returned. The DIQ(0) string can contain the values that follow:

I return Internal values
E return External values
N do not return Null values

The format and location of the output from EN^DIQ1 depends on the status of input variables DIQ and DIQ(0) and on whether or not a word processing field is involved.

DIQ and DIQ(0) undefined

Output into:

    ^UTILITY("DIQ1",$J,file#,DA,field#)=external value

This is for backward compatibility. Each field requested will be defined in the utility global but the value may be null. The only exception to this would be when DA held the number of an entry which does not exist. In that case, nothing is returned. The values returned are the external values. Printable values - pointers, sets of codes, etc. - are resolved; dates are in external format.

DIQ(0) defined, DIQ undefined

Output into:

    ^UTILITY("DIQ1",$J,file#,DA,field#,"E")=external value
    ^UTILITY("DIQ1",$J,file#,DA,field#,"I")=internal value

If DIQ(0) contains "E", the external value is returned with a final global subscript of "E".

If DIQ(0) contains "I", the internally stored value is returned with a final global subscript of "I". The internal value is the value stored in the file, for example, the record number of the entry in the pointed-to file, not the resolved value of the pointer. Since computed fields store no data, no nodes are returned for computed fields.

If DIQ(0) contains "N", no nodes are set for either internal or external values if the field is null.

If DIQ(0) contains both "I" and "E", generally two nodes are returned for each field: one with the internal value, one with the external value. However, no nodes are produced for the internal value if the field is computed and no nodes are produced at all for null-valued fields if DIC(0) contains "N". Nodes are subscripted as described above.

DIQ defined

The output is similar except that the data is stored in the specified local array. So if DIQ(0) is not defined, then the output is:

    @(DIQ(file#,DA,field#))=external value

If DIQ(0) is defined, then the output is:

    @DIQ(file#,DA,field#,"E")=external value
    @DIQ(file#,DA,field#,"I")=internal value

Word Processing Field

Output from a word processing field will only be an external value. The status of DIQ(0) has no effect. If DIQ is not defined, it goes into the global nodes that follow:


If DIQ is defined, it goes into:

    @DIQ(file#,DA,field#,1)=External Value 1
    @DIQ(file#,DA,field#,2)=External Value 2
    @DIQ(file#,DA,field#,3)=External Value 3
    @DIQ(file#,DA,field#,4)=External Value 4


Reviewed/Updated: March 4, 2007