Toolkit V. 7.3 APIs Banner [skip navigation]
VHA Office of Information - Health Systems Design and Development (HSD&D) Banner

GETIREF^XTID(): Get IREF

Reference Type: Supported, Category: Data Standardization, Integration Agreement: 4631

Description

This API searches and returns a list of terms/concepts for a given VHA Unique ID (VUID) (i.e., "vuid" input parameter). Filtering of the list is applied when the remaining input parameters are defined (i.e., "file," "field," and "master").

Format

  GETIREF^XTID([file],[field],vuid,array,master)

Input Parameters

file:

(optional) VistA file/subfile number where term/concept is defined:

  • Defined—If defined, the search is limited to those term/concepts that exist in that file and have the VUID assigned to the "vuid" input parameter.

  • Not Defined—If not defined, the search will include term/concepts that have the VUID assigned to the "vuid" input parameter and may exist in both file terms and in SET OF CODES terms.
field:

(optional) Field number in the "file" input parameter where term/concept is defined:

  • Not Defined—The search will find those terms/concepts that have the VUID assigned to the "vuid" input parameter and will be limited to those terms/concepts found in the file defined in the “file” input parameter.

  • Defined—The search will find those terms/concepts that have the VUID assigned to the "vuid" input parameter and will be limited to those terms/concepts that exist in the given file/field combination.
    • Entered as .01. It represents the terms defined in the file entered in the "file" input parameter.

    • Otherwise, the field number entered must be a SET OF CODES data type field in the file entered in the "file" input parameter.
vuid:

(required) The VHA Unique ID (VUID) specified in order to limit the search.
array:

(required) The name of the array (local or global) where results of the search will be stored.
master:

(optional) Flag to limit the search of terms based on the value of the MASTER ENTRY FOR VUID field:

  • 0—Include all terms.

  • 1—Include only those terms designated as MASTER ENTRY FOR VUID.

Output

array:

Returns the given array populated as follows:

  • Populated Array:

    @TARRAY=<list count>
    @TARRAY@(<file#>,<field#>,<internal reference>)=<status info>

    where the <status info> is defined as follows:

    <internal value>^<VA FileMan effective date/time>^<external value>^<master entry?>

  • Empty Array—Unpopulated array when no entries are found.

    @TARRAY=<list count>

  • Error Array—When an error occurs, the array is populated as follows:

    @TARRAY("ERROR")="<error message>"

Example 1

>N array S array="MYARRAY"

>S file=16000009,field=.01,vuid=12343,master=0

>D GETIREF^XIID(file,field,vuid,array,master)

>ZW MYARRAY

MYARRAY=2
MYARRAY(16000009,.01,"1,")=1^3050202.153242^ACTIVE^0
MYARRAY(16000009,.01,"3,")=0^3050215.07584^INACTIVE^1

Example 2

When no entries are found, the named array is populated as follows:

>ZW MYARRAY

MYARRAY=0

Example 3

When an error occurs, the named array is populated as follows:

>ZW MYARRAY

MYARRAY("ERROR")="<error message>"

 

VA (Internet) / VA (Intranet) / OI / HSD&D / Site Map / Terms of Use / VA Privacy Policy / Accessibility

Reviewed/Updated: November 15, 2006

If you have questions, need more information, or are having accessibility problems with this website, please contact us by E-Mail: Webmasters, Phone: 510-768-6800, or FAX: 510-768-6850.