Print Page as PDF
DBIA4245 ICR (4245)

DBIA4245    ICR (4245)

Name Value
NUMBER 4245
IA # 4245
DATE CREATED 2003/11/06
CUSTODIAL PACKAGE LAB SERVICE
CUSTODIAL ISC Dallas
USAGE Controlled Subscription
TYPE Routine
DBIC APPROVAL STATUS APPROVED
ROUTINE LRPXAPI
NAME DBIA4245
GENERAL DESCRIPTION
APIs for retrieving Lab data.

Arguments enclosed with brackets are optional. Arguments without brackets are
required. Arguments preceded by a period should be called by reference.

STATUS Active
ID LRPXAPI
COMPONENT/ENTRY POINT
COMPONENT/ENTRY POINT COMPONENT DESCRIPTION VARIABLES
TESTS(.i,d,[t],[m],[.n],[c],[d1],[d2])


Returns lab items on a patient. In the case of Chemistry this would be the
tests, with Micro or AP it could be various items. Obtains only the tests a
patient has results for; therefore, useful to screen for only those tests on
selection. Results are not returned, just the tests (items).

arguments

.i    local array of items returned(ien)=ien^name
or
NMSP: namespace string
^TMP(NMSP,$J,ien)=ien^name
where ien is pointer value in file 60 or for
Micro and AP data will be (item)=item^item name
d     DFN
[t]   type of data [C M A] chem, micro, or AP
default: C
[m]   max number of tests returned per call
default: 100
[.n]  next: returns 0 unless more tests available
[c]   condition expression: use V, F, and S as variables
for value, flag and specimen
[d1]  first date of date range
default: any time in the future (no limits)
[d2]  second date of date range
default: any time in the past (no limits)

examples

Return tests on patient.
D TESTS^LRPXAPI(.TESTS,DFN)
returns:
TESTS(173)=173^CREATININE
TESTS(174)=174^UREA NITROGEN
TESTS(175)=175^GLUCOSE

Micro items collected during May 2002.
D TESTS^LRPXAPI(.TESTS,DFN,"M",,,30020501,30020530)

All tests having abnormal results and storing them into
a TMP global to avoid allocation errors.
F  D  Q:'MORE
. D TESTS^LRPXAPI(.ITEMS,DFN,"C",100,.MORE,"F]""""",FROM,TO)
. M ^TMP("LRPXAPP",$J)=ITEMS

RESULTS(.v,d,[i],[m],[.n],[c],[d1],[d2])


Returns lab results on a patient for either Chem, Micro, or AP. The results
may be for an item, a type, or partial type.  Useful for obtaining all lab
results, results for a test, all results for a date range, or the last
results.

arguments

.v    local array of test values returned(lridt_" "_test)
=date^test^comment^data
or
NMSP: namespace string^TMP(NMSP,$J,lridt_" "_test)
=date^test^comment^data
where date is collection date, test is pointer value in
file 60, comment is 1 if it exists   else 0, data is
result node (value^flag^...etc...) Micro and AP data
return (-date_" "_item)=date^item^node^data
d     DFN
[i]   item or type [C M A] Chem, Micro, or AP
may also be an item or item or type [C M A]
may also be an item or partial type ("M;S;360",
"A;M;142", "M;A;", "A;D;")
default: C
[m]   max number of collection times results returned per call
default: 10
[.n]  next: returns 0 unless more results available
[c]   condition expression: use V, F, and S as variables for
value, flag and specimen; MUMPS operators are used
[d1]  first date of date range
default: any time in the future (no limits)
[d2]  second date of date range
default: any time in the past (no limits)

examples

Get results for last 10 collections of Chem tests and store in ^TMP("ZZ",$J.
D RESULTS^LRPXAPI("ZZ",DFN)

Return last lab results on patient. This example returns three test results
from the last collection time.
D RESULTS^LRPXAPI(.ZZZ,DFN,"C",1) returns:
ZZZ("7019484.887 173")=2980514.113^173^0^23^H^!^5^72!.9!
ZZZ("7019484.887 174")=2980514.113^174^0^14^^!^5^72!11!24
ZZZ("7019484.887 176")=2980514.113^176^0^23^L*^!^5^72!135

This example would return all critical results on a patient
(assuming there are no more than 100 results available).
D RESULTS^LRPXAPI(.EX,17,"C",,"F[""*""") returns:
EX("7019484.887 1160")=2980514.113^1160^0^4^L*^!^5^72!
EX("7019484.887 176")=2980514.113^176^0^23^L*^!^5^72!135!

PATIENTS(.p,[i],[s],[m],[.n],[c],[d1],[d2])


Returns all patients for a specific test. Useful for finding patients to
study.

arguments

.p    local array of patients returned(dfn)=dfn^name
or
NMSP: namespace string ^TMP(NMSP,$J,dfn)=dfn^name
where name is the patient's name
[i]   item
for Chemistry: test   pointer to file 60
for Micro and AP data - semicolon delimited string
item is optional, a condition can also be used
for identifying patients
a type or partial type can be used type
("M", "A;M;", "M;A;", "A;D;")
if not item or condition, all patients are returned
[s]   source used as a subset of patients
an array or global array reference with DFNs in the
first subscript
default is all patients with lab data
[m]   max number of patients returned per call
default: 100
[.n]  next: returns 0 unless more patients available
[c]   condition expression: use V, F, and S as variables for
value, flag and specimen; MUMPS operators are used
[d1]  first date of date range
default: any time in the future (no limits)
[d2]  second date of date range
default: any time in the past (no limits)

examples

Return all patients (maximum of 100) who've had a glucose over 500.
D PATIENTS^LRPXAPI(.PATS,175,,,,"V>500")

Return all patients (maximum of 100) who've had a glucose in May 2002.
D PATIENTS^LRPXAPI(.PATS,175,,,,30020501,30020530)

Get all patients with autopsy results in May 2003
and store in ^TMP("ZZ",$J (maximum of 1000).
D PATIENTS^LRPXAPI("ZZ","A",,1000,,"C=""A""",3030501,3030601)

Find all patients with AP results where disease was CANDIDIASIS.
D PATIENTS^LRPXAPI(.ZZ,"A;D;280") returns
ZZ(1086)=1086^TLNAXU,IXNJH U ZZ(8210)=8210^RDJELITXY,HIZRYI
ZZ(8397)=8397^OYHDA,UXKHUS C

Find all patients with AP results where disease was CANDIDIASIS.
Use those patients as the source for another query for patients with
Micro results where organism was CANDIDA ALBICANS.
D PATIENTS^LRPXAPI(.PTS,"A;D;280")
D PATIENTS^LRPXAPI(.XX,"M;O;5","PTS") returns:
XX(8210)=8210^RDJELUITXY,HIZRYI F
XX(8397)=8397^OYHDA,UXKHUS C

Find a patient with Micro results from blood where organism
was CANDIDA ALBICANS and was sensitive to NITROFURANTOIN.
D PATIENTS^LRPXAPI(.ABC,"M;O;2",,1,,"S=70|A=20|I[""S""") returns
ABC(8999)=8999^CLUULYML,ZLUT F

DATES(.dt,d,[t],[m],[.n],[d1],[d2])


Returns all instances of patient data. This may be for Chemistry, Micro, or AP
data. Useful for finding time occurrences when lab specimens were collected.

arguments

.dt   local array of date/times: (-date)=date
or
NMSP: namespace string ^TMP(NMSP,$J,-date)=date
collated by most recent
d     DFN
[t]   type of data [C M A] Chem, Micro, or AP
default: C
[m]   max number of collection times returned per call
default: 100
[.n]  next: returns 0 unless more collection times available
[d1]  first date of date range
default: any time in the future (no limits)
[d2]  second date of date range
default: any time in the past (no limits)

examples

Return all Chem collection date/times (maximum of 100).
D DATES^LRPXAPI(.OCC,DFN)

The following code gets all Micro occurrences, storing them
into a TMP global. A namespaced label is used (example
"ZZMICRO") and returned as ^TMP(namespace,$J,date)=date.
D DATES^LRPXAPI("ZZMICRO",DFN,"M") returns:
^TMP("ZZMICRO",549459892,-3020811.105354) = 3020811.105354
^TMP("ZZMICRO",549459892,-3020811.105353) = 3020811.105353
^TMP("ZZMICRO",549459892,-3020811.093703) = 3020811.093703

VALUE(.r,d,cdt,t,[c],[.e])


Obtains the result node of a test value. For "CH" results only. This is useful
when getting a result without knowing Lab's variables for retrieval. LRDFN,
LRIDT, LRDN are not needed. DFN, collection date/time and test number are
used. A condition may also be used to only return the value if the condition
is met. If no valid value exists, the result node is returned as "" and error
is 1, else 0.

arguments

.r    result node
d     DFN
cdt   collection date/time
t     test (file 60)
[c]   condition
[.e]  error (1 or 0)

example

Get the value of a lab test.
D VALUE^LRPXAPI(.RESULT,DFN,COL,TEST)
returns the entire result node

Examples showing a patient's result for creatinine   sometimes with
conditions.
D VALUE^LRPXAPI(.RESULT,6,3020319.06,173)
returns RESULT as:
2.1^H^81136.0000!82565.0000!2160!3110!1^4838^72!0.7!1.5!!!!MG
/DL!2!50^^^^605

D VALUE^LRPXAPI(.RESULT,6,3020319.06,173,"F[""H""|S=71",.ERR)
returns: RESULT="" and ERR=1

LRVALUE(.r,l,i,d,[c],[.e])


Obtains the result node of a test value. For "CH" results only. LRDFN, LRIDT,
LRDN are needed. A condition may also be used to only return the value if the
condition is met. If no valid value exists, the result node is returned as ""
and error is 1, else 0.

arguments

.r    result node
l     LRDFN
i     LRIDT
d     LRDN
[c]   condition
[.e]  error

example

Get the value of a lab test.
D LRVALUE^LRPXAPI(.RESULT,LRDFN,LRIDT,LRDN) returns the entire result node

D LRVALUE^LRPXAPI(.RESULT,41,6979171.877447,826) returns RESULT as:
10^H^89081.0000!86678.0000!8129!8691^766^70!.9!2.9!!^^^^605

LRPXRM(.r,n,[i],[t])


Obtains the result node of a test value. If no valid value exists, "" is
returned.

arguments

.r   result node
n    data node in PXRMINDX index
examples:
lrdfn;CH;lridt;lrdn,
lrdfn;MI;lridt;3;org;0
[i]  item
default: if i is not defined, n is assumed to be a "CH"
node (lrdfn;CH;lridt;lrdn),
else .r will be returned as ""
[t] type of data returned where letters can include
V value
S specimen
C comments
default: "VS"

examples

Get the value of a lab test value from a data reference.
S DATAREF=$O(^PXRMINDX(63,"IP",TEST,DFN,COLTIME,"")
D LRPXRM^LRPXAPI(.RESULT,DATAREF,TEST)
S VALUE=$P(RESULT,U)

Examples using data node values.
D LRPXRM^LRPXAPI(.RESULT,"7578;CH;7089488.8858;384",,"V") returns:
1^WBC^9.8


D LRPXRM^LRPXAPI(.RESULT,"96273;CH;6979288.926197;7",,"VSC") returns
RESULT=178^CHLORIDE^103^^81853.0000!82435.0000!
RESULT("COMMENTS")=0
RESULT("SPECIMEN")=72^SERUM

D LRPXRM^LRPXAPI(.RESULT,"52;SP;7049373;2;1;1;2;0","A;D;266") returns:
266^VIRAL HEPATITIS^266

D LRPXRM^LRPXAPI(.ZZ,"6;MI;7018878.8848;3;6;2.0016","M;A;1") returns:
1^AMIKACN^<=2^S^

SPEC(.r,d,cdt,[s],[.e])


Obtains the specimen and collection information. For "CH" results only. The
STYPE parameter may be S for the specimen node, C for comments, V for all
LRDNs, and A for S, C, and V. If no valid specimen data exists, results is
returned undefined and error is 1 (otherwise 0).

arguments

.r    array of results, example:
RESULTS("C",#)=comments
RESULTS("S")=specimen node
RESULTS("V",#)=LRDN
d     DFN
cdt   collection date/time
[s]   STYPE (S: spec node, C: comment, V: test values, A: all)
default is A
[.e]  error (1 or 0)

example

Get values for a lab collection.
D SPEC^LRPXAPI(.RESULTS,DFN,COLTIME,"A")
returns the comments, specimen and test information.

Examples on the same sample.
D SPEC^LRPXAPI(.XX,6544,2900820.2245)
returns:
XX("C",1)=Hemoglobin, Methemoglobin  10.7,1.1
XX("C",2)=Spontaneous
XX("C",3)=Arterial (AR)
XX("S")=2900820.2245^^2900820.2253^2382^8728^BG 0820 40^^^
XX("V",1)=444^21%^
XX("V",2)=446^93.6^
XX("V",3)=447^2.2^
XX("V",4)=449^14.0^L
XX("V",5)=451^31.7^L
XX("V",6)=452^72.2^
XX("V",7)=454^23.7^
XX("V",8)=457^7.482^H

D SPEC^LRPXAPI(.XX,6544,2900820.2245,"C")
returns:
XX("C",1)=Hemoglobin, Methemoglobin  10.7,1.1
XX("C",2)=Spontaneous
XX("C",3)=Arterial (AR)

D SPEC^LRPXAPI(.XX,6544,2900820.2245,"S")
returns:
XX("S")=2900820.2245^^2900820.2253^2382^8728^BG 0820 40^^^

D SPEC^LRPXAPI(.XX,6544,2900820.2245,"V")
returns:
XX("V",1)=444^21%^
XX("V",2)=446^93.6^
XX("V",3)=447^2.2^
XX("V",4)=449^14.0^L
XX("V",5)=451^31.7^L
XX("V",6)=452^72.2^
XX("V",7)=454^23.7^
XX("V",8)=457^7.482^H

LRSPEC(.r,l,i,[s],[.e])


Obtains the specimen and collection information using lab variables. The STYPE
parameter may be S for the specimen node, C for comments, V for all LRDNs, and
A for S, C, and V. If no valid specimen data exists, results is returned
undefined and error is 1 (otherwise 0).

arguments

.r    array of results, example:
RESULTS("C",#)=comments  RESULTS("S")=specimen node
RESULTS("V",#)=LRDN
l     LRDFN
i     LRIDT
[s]   STYPE (S: spec node, C: comment, V: test values, A: all)
default is A
[.e]  error

example

Examples are similar to SPEC^LRPXAPI but with LRDFN and LRIDT
instead of DFN and DATE.
D SPEC^LRPXAPI(.XX,2457,7099178.7755,"C")
returns:
XX("C",1)=Hemoglobin, Methemoglobin  10.7,1.1
XX("C",2)=Spontaneous
XX("C",3)=Arterial (AR)

$$VERIFIED(l,i)


Checks whether the tests in the lab collection have been verified and
available for display. Returns 1 if verified, else 0. Note: Data references
from the ^PXRMINDX indexes are always verified.

arguments

l     LRDFN
i     LRIDT
returns 1 or 0

example

Get a glucose result if verified.
I $$VERIFIED^LRPXAPI(4,LRIDT) D VAL^LRPXAPI(4,LRIDT,2)

$$MIVERIFY(l,i,s)


Checks whether the Micro specimen has been verified and available for display.
Returns 1 if verified, else 0.

arguments

l     LRDFN
i     LRIDT
s     Micro subscript
default "MI"
returns 1 or 0

example

If Micro is not verified then quit.
I '$$MIVERIFY^LRPXAPI(LRDFN,LRIDT) Q

$$APVERIFY(l,i,s)


Checks whether the AP specimen has been verified and available for display.
Returns 1 if verified, else 0.

arguments

l     LRDFN
i     LRIDT
s     AP subscript [AU CY EM SP]
returns 1 or 0

example

If Cytology results are not verified then quit.
I '$$APVERIFY^LRPXAPI(LRDFN,LRIDT,"CY") Q

$$VAL(l,i,d)


Obtains the result node of a "CH" test value. If no valid value exists, "" is
returned.

arguments

l     LRDFN lab patient id
i     LRIDT inverse date/time
d     LRDN data number
returns node values

examples

Get the value of a lab test.
S RESULT=$$VAL^LRPXAPI(15,70021211.1523,2) returns the entire result node

Get just the result of the lab test.
S RESULT=$P($$VAL^LRPXAPI(15,70021211.1523,2),U) gets just the result value

This is the entire node for this result.
W $$VAL^LRPXAPI(922,7009790.899758,4)
1.1^^81114.0000!!2160!!1^1499^72!0.7!1.5!!!!MG/DL!2!50^^^^605

$$REFVAL(n)


Obtains the values from the reference node. If no valid value exists, "" is
returned. Used for any type of data (Chem, Micro, AP).

argument

n     reference node in ^LR
returns node values

examples

Get the reference nodes values.
S RESULT=$$REFVAL^LRPXAPI("6;CH;6988891.9063;605305")
where RESULT is the entire node:
3.7^L^81132.0000!!9830!!1^4838^72!4.0!6.7^^^^605

Get the result from the reference node values
S RESULT=$P($$REFVAL^LRPXAPI("6;CH;6988891.9063;605305"),U)
where RESULT is: 3.7

CH, Micro, and AP nodes can be obtained.
W $$REFVAL^LRPXAPI("6451;SP;7089590;2;1;2;1;1;1;0")
4405

$$COMMENT(l,i)


Returns 1 if any comments exist on this collection sample, else 0. Used only
for "CH" data.

arguments

l     LRDFN
i     LRIDT
returns 1 or 0

example

Check to see if a comment was made on a sample.
I $$COMMENT^LRPXAPI(LRDFN,LRIDT) D FLAG

ACCY(.t,a,d)


Obtains those lab tests for a specific accession. The accession must be for a
yearly accession area. Since the only a portion of the accession date is used
in the accession, the year of the accession must be declared. The year would
be in VA FileMan format or it's first number of the date to indicate the
century.

arguments

t     array of tests returned, (ien)=ien^test name
a     accession, examples: CY 02 922, MI 99 3244
d     beginning date number (for the year 1992 this would be 2
or 2990000, for 2003 this would be 3 or 3030000)

examples

Get the tests from an accession where ACC="SP 02 559".
D ACCY^LRPXAPI(.TESTS,ACC,3) returns:
TESTS(1413)=1413^H & E STAIN
TESTS(5034)=5034^PARAFFIN BLOCK

$$HASITEM(d,i)


Checks if patient has had a test. Useful to filter from a list of lab tests
only those the patient has actually had.

arguments

d     DFN
i     Item   lab test or result from ^PXRMINDX(63 indexes
returns 1 or 0

examples

Screens for only those tests where the patient has results.
S DIC("S")="I $P(^(0),U,4)=""CH"",$$HASITEM^LRPXAPI(DFN,+Y)"

CHNODE(.r,n)


Obtains the values for data stored on the CH node for lab results. These
fields are not documented by the DD. These data store information such as
LOINC and National Lab Test file information. The values are returned in an
array subscripted by the type of information. The presence of values depends
on many factors including the test's definition and proper mapping of Lab to
LOINC and NLT files. These are the elements of the result node:

DATE-R  report status date/time
DATE-T   transmit status date/time
DEF   default value
DELTA-T   type of delta check
DELTA-V   delta value
FLAG   normal range flag
HIGH   reference high
HIGH-C   critical high
HIGH-T   therapeutic high
INSTITUTION   verifying institution
INSTRUMENT   instrument
LEDI   ledi transmission status
LOINC   loinc code for reported test
LOW   reference low
LOW-C   critical low
LOW-T   therapeutic low
MAP   historically mapped
METHOD   method suffix for reported test
NLT-O  nlt code for ordered test
NLT-R   nlt code for reported test
RESULT   test result
SPEC   site/specimen 61 IEN
TEST   lab test 60 IEN
TYPE   test type (output only, both, neither)
UNITS   units
VERIFIER   verifier duz

arguments

.r   array of results, example:
RESULTS("RESULT")=result
RESULTS("FLAG")=flag
RESULTS("UNITS")=units
n    reference node for ^PCRMINDX(63, indexes

example

Display the lab value and units.
D CHNODE^LRPXAPI(.RESULTS,NODE)
W !,RESULTS("RESULT")," ",RESULTS("UNITS")

SUBSCRIBING PACKAGE
SUBSCRIBING PACKAGE ISC SUBSCRIBING DETAILS
CLINICAL REMINDERS Salt Lake City
ORDER ENTRY/RESULTS REPORTING
SPINAL CORD DYSFUNCTION
VIRTUAL PATIENT RECORD
VPR*1*2, released fall of 2013, uses routine LRPXAPI.
VPR is already using the Clinical Reminders indices to pull data from other
VistA applications, and wouldd like to use the index to pull some microbiology
data; LRPXAPI seems the cleanest way to resolve the values in the index and
get the supporting data.
VA POINT OF SERVICE (KIOSKS)
HEALTH MANAGEMENT PLATFORM
HMP's subscription to this ICR expired on 10/27/17 with
the shutdown of HMP.  HMP*2.0*12 released on 10/17/17 is an informational
patch outlining the steps for the sites to shut down the application. If HMP
is reactivated in the future, the HMP project team should review the access
provided by this ICR with the custodial application before reactivating HMP's
subscription to this ICR.
DBA Comments
1/14/14-DT:  Added VPR*1*2, released fall 2013, as subscriber
to pull microbiology data.

1/23/13-MM:  Added Patient Assessment Documentation Package as a subscriber
for NUPA*1*1.  Levi provided concurrence based on Bob Andrews' comments as the
original developer:

I actually wrote those APIs (many years ago). The code is mainly used by CPRS
and Clinical Reminders. The intent of the code was to be able to be used by
any package that wanted to subscribe. So, the PADP project (not familiar with
them) should have no problem using them. 7/9/14-MC: PADP did not complete the
class 3 to class 1 conversion process, but it is still installed at sites.
Sites have the option to utilize the program, however it is no longer
nationally supported.  There will be no further patching of the package. PADP
has been removed as a subscriber to this ICR.  3/25/15-MC: Added VPS as a
subscriber at the request of Carolyn Wheless and approval of Levi Teitelbaum
for VPS*1*15.  11/5/15-MC: Added EHMP as a subscriber at the request of Phil
Burkhalter and approval of Levi Teitelbaum.

11/2/17-DC: HMP's subscription to this ICR expires on 10/27/17 with the
shutdown of HMP.  HMP*2.0*12 released on 10/17/17 is an informational patch
outlining the steps for the sites to shut down the application.            If
HMP is reactivated in the future, the HMP project team should review the
access provided by this ICR with the custodial application before reactivating
HMP's subscription to this ICR. See VistA Document Library for list of retired
HMP ICRs.
MAIL MESSAGE 37463030
DATE/TIME EDITED
DATE/TIME EDITED ACTION AT THE REQUEST OF WITH CONCURRENCE OF
2007/01/24 00:39 SUBSCRIBER ADDED SWESKY,JEFF MCCORMICK,JOHN
2013/01/23 10:07 SUBSCRIBER ADDED DEZORZI,KEVIN TEITELBAUM,LEVI
2013/01/23 10:08 SUBSCRIBER ADDED DEZORZI,KEVIN ANDREWS,BOB
2014/01/14 13:31 SUBSCRIBER ADDED BUECHLER,MELANIE ANZALDUA,CAROL
2015/03/25 08:50 SUBSCRIBER ADDED WHELESS,CAROLYN TEITELBAUM,LEVI
2015/11/05 13:48 SUBSCRIBER ADDED BURKHALTER,WILLIAM TEITELBAUM,LEVI
2017/12/27 16:06 CONTENT CORRECTED LORD,BRIAN ICR,TEAM
Generated from AUG 12, 2020@ IA Listing Descriptions