Kernel Toolkit 7.3 APIs Banner
Office of Information and Technology (OIT) Banner
[skip navigation]

GETIREF^XTID(): Get IREF

Reference Type: Supported, Category: Toolkit—VHA Unique ID (VUID), ICR#: 4631

Description

The GETIREF^XTID 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 following optional input parameters are defined:

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 includes term/concepts that have the VUID assigned to the vuid input parameter and can 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:

  • Defined—The search finds those terms/concepts that have the VUID assigned to the vuid input parameter and is 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.

  • Not Defined—The search finds those terms/concepts that have the VUID assigned to the vuid input parameter and is limited to those terms/concepts found in the file defined in the file input parameter.

vuid:

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

(required) The name of the array (local or global) where results of the search are 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:

  • @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.

  • 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>