VA FileMan Programmer Manual: GETS^DIQ( )

Contents:

Main

Database Server (DBS) API

GETS^DIQ( ): Data Retriever (Multiple Fields)

Reference Type	Category	ICR #
Supported	Database Server (DBS)	2056

Description

The GETS^DIQ API retrieves one or more fields of data from a record or sub-records and places the values in a target array.

Format

GETS^DIQ(file,iens,field[,flags],target_root[,msg_root])

Input Parameters

file	(Required) File or subfile number.
iens	(Required) Standard IENS indicating internal entry numbers.
field	(Required) Can be one of the following: A single field number. A list of field numbers separated by semicolons. A range of field numbers, in the form M:N; where M and N are the end points of the inclusive range. All field numbers within this range are retrieved. Asterisk () For all fields at the top-level (no sub-Multiple record). Double asterisk () For all fields including all fields and data in sub-Multiple fields. Field number of a Multiple followed by an to indicate all fields and records in the sub-Multiple for that field.
flags	(Optional) Flags to control processing. The possible values are:
	E	Returns External values in nodes ending with E.
	I	Returns Internal values in nodes ending with I; otherwise, external is returned.
	N	Does Not return NULL values.
	R	Resolves field numbers to field names in target array subscripts.
	Z	WORD-PROCESSING fields include Zero nodes.
	A#	Audit Trail is used to retrieve the value of "FIELD" at a particular point in time. # is a date/time in VA FileMan internal format (e.g., 3021015.08). The values retrieved are the (audited) values of the fields as of that date/time.
target_root	(Required) The name of a closed root reference.
msg_root	(Optional) The name of a closed root reference that is used to pass error messages.

Output

target_root

The output array is in the FDA format:

    TARGET_ROOT(FILE,IENS,FIELD)=DATA

WORD-PROCESSING (WP) fields have data descendent from the field nodes in the output array.

Examples

Example 1

Figure 216 retrieves the values of all fields for a record.

Figure 216: GETS^DIQ API—Example 1: Input and Output

    >D GETS^DIQ(999000,"1,","**","","ARRAY") <Enter>

    >ZW <Enter>
    ARRAY(999000,"1,",.01)=TEST1
    ARRAY(999000,"1,",1)=OCT 01, 1992
    ARRAY(999000,"1,",2)=YES
    ARRAY(999000,"1,",3)=1
    ARRAY(999000,"1,",4)=DTM-PC
    ARRAY(999000,"1,",5)=SUPPORTED
    ARRAY(999000,"1,",6)=S Y="SET Y=TO THIS"
    ARRAY(999000,"1,",8)=AUDIT,Z
    ARRAY(999000,"1,",9)=ACCESS,Z
    ARRAY(999000,"1,",10)=GRP,Z
    ARRAY(999000,"1,",11)=DESCRIP,Z
    ARRAY(999000,"1,",12)=ARRAY(999000,"1,",12)
    ARRAY(999000,"1,",12,1)=THIS WP LINE 1
    ARRAY(999000,"1,",12,2)=WP LINE2
    ARRAY(999000,"1,",12,3)=AND SO ON
    ARRAY(999000,"1,",13)=LASTNAME,FIRST
    ARRAY(999000.07,"1,1,",.01)=TEST1 ONE
    ARRAY(999000.07,"1,1,",1)=
    ARRAY(999000.07,"2,1,",.01)=TEST1 TWO
    ARRAY(999000.07,"2,1,",1)=
    ARRAY(999000.07,"3,1,",.01)=TEST1 THREE
    ARRAY(999000.07,"3,1,",1)=
    ARRAY(999000.07,"4,1,",.01)=TEST1 FOUR
    ARRAY(999000.07,"4,1,",1)=MUMPS

Example 2

Figure 217 retrieves the values of all fields for a record, excluding Multiples.

Figure 217: GETS^DIQ API—Example 2: Input and Output

    >D GETS^DIQ(999000,"1,","*","","ARRAY1") <Enter>

    >ZW <Enter>
    ARRAY1(999000,"1,",.01)=TEST1
    ARRAY1(999000,"1,",1)=OCT 01, 1992
    ARRAY1(999000,"1,",2)=YES
    ARRAY1(999000,"1,",3)=1
    ARRAY1(999000,"1,",4)=DTM-PC
    ARRAY1(999000,"1,",5)=SUPPORTED
    ARRAY1(999000,"1,",6)=S Y="SET Y=TO THIS"
    ARRAY1(999000,"1,",8)=AUDIT,Z
    ARRAY1(999000,"1,",9)=ACCESS,Z
    ARRAY1(999000,"1,",10)=GRP,Z
    ARRAY1(999000,"1,",11)=DESCRIP,Z
    ARRAY1(999000,"1,",12)=ARRAY(999000,"1,",12)
    ARRAY1(999000,"1,",12,1)=THIS WP LINE 1
    ARRAY1(999000,"1,",12,2)=WP LINE2
    ARRAY1(999000,"1,",12,3)=AND SO ON
    ARRAY1(999000,"1,",13)=LASTNAME,FIRST

Example 3

Figure 218 retrieves both internal and external values of three specific fields for a record.

Figure 218: GETS^DIQ API—Example 3: Input and Output

    >D GETS^DIQ(999000,"1,",".01;3;5","IE","ARRAY3") <Enter>

    >ZW <Enter>
    ARRAY3(999000,"1,",.01,"E")=TEST1
    ARRAY3(999000,"1,",.01,"I")=TEST1
    ARRAY3(999000,"1,",3,"E")=1
    ARRAY3(999000,"1,",3,"I")=1
    ARRAY3(999000,"1,",5,"E")=SUPPORTED
    ARRAY3(999000,"1,",5,"I")=

Example 4

Figure 219 retrieves both internal and external values for a range of fields in a record.

Figure 219: GETS^DIQ API—Example 4: Input and Output

    >D GETS^DIQ(999000,"1,",".01:6","IE","ARRAY4") <Enter>

    >ZW <Enter>
    ARRAY4(999000,"1,",.01,"E")=TEST1
    ARRAY4(999000,"1,",.01,"I")=TEST1
    ARRAY4(999000,"1,",1,"E")=OCT 01, 1992
    ARRAY4(999000,"1,",1,"I")=2921001
    ARRAY4(999000,"1,",2,"E")=NO
    ARRAY4(999000,"1,",2,"I")=0
    ARRAY4(999000,"1,",3,"E")=66
    ARRAY4(999000,"1,",3,"I")=66
    ARRAY4(999000,"1,",4,"E")=DTM-PC
    ARRAY4(999000,"1,",4,"I")=9
    ARRAY4(999000,"1,",5,"E")=SUPPORTED
    ARRAY4(999000,"1,",5,"I")=
    ARRAY4(999000,"1,",6,"E")=S Y="SET Y=TO THIS"
    ARRAY4(999000,"1,",6,"I")=S Y="SET Y=TO THIS"

Example 5

Figure 220 retrieves the values of five specific fields, including all values of a Multiple field.

Figure 220: GETS^DIQ API—Example 5: Input and Output

    >D GETS^DIQ(999000,"1,",".01;3;7*;11;13","","ARRAY5") <Enter>

    >ZW <Enter>
    ARRAY5(999000,"1,",.01)=TEST1
    ARRAY5(999000,"1,",3)=1
    ARRAY5(999000,"1,",11)=DESCRIP,Z
    ARRAY5(999000,"1,",13)=LASTNAME,FIRST
    ARRAY5(999000.07,"1,1,",.01)=TEST1 ONE
    ARRAY5(999000.07,"1,1,",1)=
    ARRAY5(999000.07,"2,1,",.01)=TEST1 TWO
    ARRAY5(999000.07,"2,1,",1)=
    ARRAY5(999000.07,"3,1,",.01)=TEST1 THREE
    ARRAY5(999000.07,"3,1,",1)=
    ARRAY5(999000.07,"4,1,",.01)=TEST1 FOUR
    ARRAY5(999000.07,"4,1,",1)=MUMPS 0S

Error Codes Returned

Table 70 lists the possible error codes returned with the GETS^DIQ API:

Table 70: GETS^DIQ API—Error Codes Returned

Code	Description
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.
602	The entry is not available for editing.
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: May 2026