API Set for Data Standardization ICR (5078)

Name

Value

NUMBER

5078

IA #

5078

DATE CREATED

2008/01/23

CUSTODIAL PACKAGE

TOOLKIT

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

XTIDTRM

NAME

API Set for Data Standardization

GENERAL DESCRIPTION

High Level Examples

Assume the following replacement relationships:


A --> B --> C --> D      A is replaced by B     G is replaced by C
^ ^         ^ ^           B is replaced by C     H is replaced by C
|  \        |  \          C is replaced by D     I is replaced by F
|   \       |   \         D has no replacement   J is replaced by F
|    \      |    \        E is replaced by A     K is replaced by H
|     F     |     H       F is replaced by A     L is replaced by H
|    ^ ^    |    ^ ^
|   /   \   |   /   \
E  I     J  G  K     L

$$GETRPLC(B) would return C

$$RPLCMNT(B) would return D

$$RPLCVALS(J) would return the requested field values from entry D

$$RPLCTRL(G) in both directions would return D and the output array would be
set as follows:

OutArr("BY",A) = B                  OutArr("FOR",A,E) = ""
OutArr("BY",B) = C                  OutArr("FOR",A,F) = ""
OutArr("BY",C) = D                  OutArr("FOR",B,A) = ""
OutArr("BY",D) = ""                 OutArr("FOR",C,B) = ""
OutArr("BY",E) = A                  OutArr("FOR",C,G) = ""
OutArr("BY",F) = A                  OutArr("FOR",C,H) = ""
OutArr("BY",G) = C                  OutArr("FOR",D,C) = ""
OutArr("BY",H) = C                  OutArr("FOR",F,I) = ""
OutArr("BY",I) = F                  OutArr("FOR",F,J) = ""
OutArr("BY",J) = F                  OutArr("FOR",H,K) = ""
OutArr("BY",K) = H                  OutArr("FOR",H,L) = ""
OutArr("BY",L) = H

$$RPLCTRL(L) in the forward direction would return D and the output array
would be set as follows:

OutArr("BY",C) = D                  OutArr("FOR",C,H) = ""
OutArr("BY",D) = ""                 OutArr("FOR",D,C) = ""
OutArr("BY",H) = C                  OutArr("FOR",H,L) = ""
OutArr("BY",L) = H

$$RPLCTRL(B) in the backward direction would return D and the output array
would be set as follows:

OutArr("BY",A) = B                  OutArr("FOR",A,E) = ""
OutArr("BY",E) = A                  OutArr("FOR",A,F) = ""
OutArr("BY",F) = A                  OutArr("FOR",B,A) = ""
OutArr("BY",I) = F                  OutArr("FOR",F,I) = ""
OutArr("BY",J) = F                  OutArr("FOR",F,J) = ""

$$RPLCLST(G) in both directions would return D and the output array would be
set as follows:

OutArr(1) = G ^ 0                   OutArr("INDEX",A) = 8
OutArr(2) = C ^ 0                   OutArr("INDEX",B) = 7
OutArr(3) = D ^ 1                   OutArr("INDEX",C) = 2
OutArr(4) = H ^ 0                   OutArr("INDEX",D) = 3
OutArr(5) = K ^ 0                   OutArr("INDEX",E) = 9
OutArr(6) = L ^ 0                   OutArr("INDEX",F) = 10
OutArr(7) = B ^ 0                   OutArr("INDEX",G) = 1
OutArr(8) = A ^ 0                   OutArr("INDEX",H) = 4
OutArr(9) = E ^ 0                   OutArr("INDEX",I) = 11
OutArr(10) = F ^ 0                  OutArr("INDEX",J) = 12
OutArr(11) = I ^ 0                  OutArr("INDEX",K) = 5
OutArr(12) = J ^ 0                  OutArr("INDEX",L) = 6

$$RPLCLST(L) in the forward direction would return D and the output array
would be set as follows if the status history was also included:

OutArr(1) = L ^ 0                   OutArr("INDEX",C) = 3
OutArr(1,3080101.0954) = 0          OutArr("INDEX",D) = 4
OutArr(2) = H ^ 0                   OutArr("INDEX",H) = 2
OutArr(2,3080101.1308) = 1          OutArr("INDEX",L) = 1
OutArr(2,3080105.09) = 0
OutArr(3) = C ^ 0
OutArr(3,3080105.0859) = 1
OutArr(3,3080112.1722) = 0
OutArr(4) = D ^ 1
OutArr(4,3080112.1723) = 1

$$RPLCLST(B) in the backward direction would return D and the output array
would be set as follows:

OutArr(1) = A ^ 0                   OutArr("INDEX",A) = 1
OutArr(2) = E ^ 0                   OutArr("INDEX",E) = 2
OutArr(3) = F ^ 0                   OutArr("INDEX",F) = 3
OutArr(4) = I ^ 0                   OutArr("INDEX",I) = 4
OutArr(5) = J ^ 0                   OutArr("INDEX",J) = 5

STATUS

Active

KEYWORDS

VUID
DATA STANDARDIZATION
TERM
REPLACEMENT TERM

XTIDTRM

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

$$RPLCMNT

$$RPLCMNT^XTIDTRM recursively traverses the REPLACED
BY VHA STANDARD TERM field (#99.97) until the final replacement term is
reached.

Usage:

S X=$$RPLCMNT^XTIDTRM(FILE,IEN)

Sets X to IEN_";"_FileNumber of the entry that ultimately replaces the input
entry.

Notes:

Null is returned on error. This typically will occur when the input entry does
not exist.

If the input entry is not replaced by another term then a reference to the
input term will be returned.

VARIABLES	TYPE	VARIABLES DESCRIPTION
FILE	Input	File number
IEN	Input	Entry number

$$RPLCVALS

$$RPLCVALS^XTIDTRM retrieves one or more fields of
data from an entry's replacement term.  The REPLACED BY VHA STANDARD TERM
field (#99.97) is recursively traversed until the final replacement term is
reached.  The requested field(s) of the final replace replacement term are
returned.

This effectively bundles $$RPLCMNT^XTIDTRM and GETS^DIQ into a single call.

Usage:

S X=$$RPLCVALS^XTIDTRM(File,IEN,Fields,Flags,OutArr)

Sets X to IEN_";"_FileNumber of the entry that ultimately replaces the input
entry.

Notes:

Null is returned on error.  This typically will occur when the input entry
does not exist.

If an error occurs when extracting the requested fields from the final
replacement term then a reference to the final replacement term will still be
returned and OUTARR will be KILLed.

If the input entry is not replaced by another term then a reference to the
input term will be returned and OutArr( ) will contain the field values for
the input entry.

VARIABLES	TYPE	VARIABLES DESCRIPTION
FILE	Input	File Number
IEN	Input	Entry number
FIELDS	Input	Field(s) to get values for. See definition of FIELD parameter in GETS^DIQ for detailed description.
FLAGS	Input	Flag(s) that control output format. See definition of FLAGS parameter in GETS^DIQ for detailed description.
OUTARR	Both	I: Array to put output field values into (closed root) O: The output array is in FDA format. See GETS^DIQ for example output.

$$RPLCTRL

$$RPLCTRL^XTIDTRM traverses the REPLACED BY VHA
STANDARD TERM field (#99.97) forwards and backwards to find all terms that are
replacement terms for the input entry and all terms that the input entry is a
replacement for.  This is recursively done so that each potential branch of
replacement terms forwards and backwards is traversed.

Usage:

S X=$$RPLCTRL^XTIDTRM(File,IEN,Drctn,OutArr)

Sets X to IEN_";"_FileNumber of the entry that ultimately replaces the input
entry.

Notes:

Null is returned on error.  This typically will occur when the input entry
does not exist.

If the input entry is not replaced by another term then a reference to the
input term will be returned.

VARIABLES	TYPE	VARIABLES DESCRIPTION
FILE	Input	File number
IEN	Input	Entry number
DRCTN	Input	Flags denoting which direction(s) to follow the trail of replacement terms. Possible flag values are: F = Follow the trail forwards B = Follow the trail backwards * = Follow the trail in both directions (same as FB/BF) (optional - defaults to 'F')
OUTARR	Both	I: Array to put trail of replacement terms into (closed root). O: The output array will contain the trail of replacement terms. OutArr("BY",Term) = Replacement Term means: Entry 'Term' is replaced BY entry 'Replacement Term' OutArr("FOR",Replacement Term, Term) = "" means: Entry 'Replacement Term' is a replacement FOR entry 'Term' Term and Replacement Term will be in the format IEN;FileNumber

$$RPLCLST

$$RPLCLST^XTIDTRM traverses the REPLACED BY VHA
STANDARD TERM field (#99.97) forwards and backwards to find all terms that are
replacement terms for the input entry and all terms that the input entry is a
replacement for.  This is recursively done so that each potential branch of
replacement terms forwards and backwards is traversed.

Usage:

S X=$$RPLCLST^XTIDTRM(File,IEN,Drctn,StatDate,StatHst,OutArr)

Sets X=IEN_";"_FileNumber of the entry that ultimately replaces the input
entry.

Notes:

Null is returned on error.  This typically will occur when the input entry
does not exist.

If the input entry is not replaced by another term then a reference to the
input term will be returned.

VARIABLES	TYPE	VARIABLES DESCRIPTION
FILE	Input	File number
IEN	Input	Entry number
DRCTN	Input	Flags denoting which direction(s) to follow the trail of replacement terms. Possible flag values are: F = Follow the trail forwards B = Follow the trail backwards * = Follow the trail in both directions (same as FB/BF) (optional - defaults to 'F')
STATDATE	Input	FileMan date/time to return term's status on (optional - defaults to current date/time)
STATHST	Input	Flag denoting if a term's full status history should be included in the output 0 = No 1 = Yes (optional - defaults to 0)
OUTARR	Both	I: Array to put trail of replacement terms into (closed root) O: The output array will contain the list terms that the input entry is somehow related to. OutArr(1..n) = Term ^ StatusCode [based on input StatDate] OutArr(1..n,StatusDateTime) = StatusCode on this date/time The above node is only returned if StatHst is set to '1' (yes) OutArr("INDEX",Term) = 1..n Term will be in the format IEN;FileNumber StatusCode: 1 = Active 0 = Inactive StatusDateTime will be in FileMan format

$$GETRPLC

$$GETRPLC^XTIDTRM gets the REPLACED BY VHA STANDARD
TERM field (#99.97) for a given entry.

Usage:

S X=$$GETRPLC^XTIDTRM(File,IEN)

Sets X to IEN_";"_FileNumber of entry that replaces the input entry.

Notes:

Null is returned on error.  This typically will occur when the input entry
does not exist.

If the input entry is not replaced by another term then a reference to the
input term will be returned.

VARIABLES	TYPE	VARIABLES DESCRIPTION
FILE	Input	File Number
IEN	Input	Entry number

$$SETRPLC

$$SETRPLC^XTIDTRM sets the REPLACED BY VHA STANDARD
TERM field (#99.97).

Usage:

S X=$$SETRPLC^XTIDTRM(File,IEN,Rplcmnt)

Sets X to 1 if Pointer to replacement term stored (ie success)
or 0 if Unable to store pointer to replacement term (ie failure)

VARIABLES	TYPE	VARIABLES DESCRIPTION
FILE	Input	File number
IEN	Input	Entry number
RPLCMNT	Input	Entry number of replacement term

DATE ACTIVATED

2015/06/08