Print Page as PDF
DBIA2343 ICR (2343)

DBIA2343    ICR (2343)

Name Value
NUMBER 2343
IA # 2343
DATE CREATED 1998/03/10
CUSTODIAL PACKAGE KERNEL
CUSTODIAL ISC San Francisco
USAGE Supported
TYPE Routine
DBIC APPROVAL STATUS APPROVED
ROUTINE XUSER
NAME DBIA2343
GENERAL DESCRIPTION
The routine XUSER has supported entry points to lookup
a user, check to determine if a user is active, DEA# details, DETOX#,
authorized to write Controlled Substances, etc.


Amended - Added 1/30/2023 The API's are designed to be backward compatible, so
that calls to APIs that formerly returned DEA information stored in the DEA#
field (#53.2), DEA EXPIRATION DATE field (#747.44), and the SCHEDULE fields
(#55.1-55.6) will now receive the same information from new fields in the DEA
NUMBERS file (#8991.9). Pharmacy code changes that use the new APIs and new
input parameters are in the Pharmacy Operational Updates Release 3 patches
PSO*7*545, PSJ*5*372, and OR*3*499.
STATUS Active
ID XUSER
COMPONENT/ENTRY POINT
COMPONENT/ENTRY POINT COMPONENT DESCRIPTION VARIABLES
$$LOOKUP
Usage  S LRDOC=$$LOOKUP^XUSER("") This extrinsic
function will do a lookup on the NEW PERSON file screening out uses that are
TERMINATED.  By default the call will ask if the correct user was selected.
ie: Select NEW PERSON NAME: XUUSER,THREE
Is XUUSER,THREE the one you want? YES//

If the parameter is set to "Q" then this extra question is suppressed.  If the
parameter is set to "A" then don't select current users who have a termination
date prior to today's date

The return is in the same format as a call to DIC. IEN^NAME Adding new entry's
isn't allowed.
VARIABLES TYPE VARIABLES DESCRIPTION
$$LOOKUP Output
The return is in the same format as a call to DIC.
IEN^NAME
Input
XUF Input
Parameter "Q" or "A" passed in.
$$ACTIVE
This API returns the active status indicator and
latest signon information of a user in the NEW PERSON (#200) file.

Usage S X=$$ACTIVE^XUSER(ien)

Parameter: pointer to the NEW PERSON file.

It returns the following codes:
""  No user record.
0   User can't sign-on.
0^DISUSER  User can't sign-on because of DISUSER flag.
0^TERMINATED^2980310  User terminated on date.
1^NEW  A new user, could sign-on.
1^ACTIVE^2980310.09  An active user, last sign-on date.
VARIABLES TYPE VARIABLES DESCRIPTION
IEN Input
This is the IEN for the entry to be checked.
$$ACTIVE Output

""  No user record.
0   User can't sign-on.
0^DISUSER  User can't sign-on because of DISUSER flag.
0^TERMINATED^2980310  User terminated on date.
1^NEW  A new user, could sign-on.
1^ACTIVE^2980310.09  An active user, last sign-on date.
$$PROVIDER
This entry point was added for CPRS.  The definition
of a provider is any entry in the new person file that doesn't have a
termination date.  A second parameter could be added to invoke other checks.

Usage S X=$$PROVIDER^XUSER(XUDA,XUF) Parameter: IEN=pointer to the NEW PERSON
file.
XUF=flag to control processing
0 or not passed, do not include Visitors
1 include Visitors

It returns the following codes:
""  No user record.
"0^TERMINATED^2980310"  User terminated on date.
"1" Has a record and no termination date.
VARIABLES TYPE VARIABLES DESCRIPTION
XUDA Input
This is the IEN for the entry to be checked.
$$PROVIDER Output

""  No user record.
"0^TERMINATED^2980310"  User terminated on date.
"1" Has a record and no termination date.
XUF Input
Flag to control processing.

0 or not passed, do not include Visitors
1 include Visitors
$$DEA
The initial patch XU*8*580 provides this API and adds
a new field, FACILITY DEA NUMBER (#52), to the INSTITUTION file (#4).

Usage:   S X=$$DEA^XUSER(FLAG,IEN,DATE,DEA)

When the FLAG input parameter is set to one (1), and the IEN input parameter
represents a VA prescriber, and the DEA parameter is not populated, and the
user's DEA number is expired, the value of the VA# (#53.3) field in the NEW
PERSON (#200) file is returned. Non-VA prescribers cannot use VA#; therefore,
the FLAG input parameter is ignored for non-VA prescribers.

A VA prescriber is a user whose NON-VA PRESCRIBER (#53.91) field in the NEW
PERSON (#200) file is not set to YES, and whose PROVIDER TYPE (#53.6) field in
the NEW PERSON file is not set to "FEE BASIS" or "C & A". A non-VA prescriber
is a user whose NON-VA PRESCRIBER (#53.91) field in the NEW PERSON (#200) file
is set to YES, or whose PROVIDER TYPE (#53.6) field in the NEW PERSON file is
set to "FEE BASIS" or "C & A".

With patch XU*8*689, if the DEA input parameter is NULL, this API returns a
user's 'default' Inpatient DEA number, if it exists. This is the DEA number in
the user's NEW DEA #'S multiple field (#53.21) in the NEW PERSON (#200) file,
that points to an entry in the DEA NUMBERS file (#8991.9) for which the USE
FOR INPATIENT ORDERS? Field (#.06) is set to YES. A provider may have more
than one DEA number, but only one of their DEA numbers may be flagged as USE
FOR INPATIENT ORDERS.

When the DATE input parameter is passed in:
1) The DEA number is returned if it is (or was) valid on the
date represented by the DATE input parameter.
2) NULL is returned if the DEA number is (or was) not valid
on the date represented by the DATE input parameter.  When the DATE input
parameter is not passed in:
1) The DEA number is returned if it is valid on the current
date.
2) NULL is returned if it is not valid on the current date.

If the DEA number is expired, the user's VA# (#53.3) field is populated, the
user meets the definition of a VA prescriber, and the PSOEPCS EXPIRED DEA
FAILOVER parameter is not set to NO, the return value will consist of the
facility DEA number with the user's VA# as a suffix, separated by a dash "-".
For example, if the user's DEA number is AB1234567, and their VA# is
AX1234567, the return value would be "AB123467-AX123467".

The definition of a VA prescriber is a user whose NON-VA PRESCRIBER (#53.91)
field in the NEW PERSON (#200) file is not set to YES, and whose PROVIDER TYPE
(#53.6) field in the NEW PERSON file is not set to "FEE BASIS" or "C & A".
VARIABLES TYPE VARIABLES DESCRIPTION
$$DEA Output
Example 1:
---------
The NEW DEA#'s (#53.21) multiple field pointing to active DEA number
"AB1234567" in the DEA NUMBERS file (#8991.9) entry having the USE FOR
INPATIENT ORDERS? field (#.06) set to YES.

The IEN points to a VA prescriber.

FACILITY DEA NUMBER field (#52) is "VA7654321".

VA# field (#53.3) is "789".

If the FLAG input parameter is null or "0", this API would return "AB1234567".

If the FLAG input parameter is "1", this API would return "AB1234567".


Example 2:
---------
The NEW DEA#'s (#53.21) multiple field doesn't contain any DEA numbers.

The IEN input parameter points to a VA prescriber.

FACILITY DEA NUMBER field (#52) is "VA7654321".

VA# field (#53.3) is "789".

If the FLAG input parameter is null or "0", this API would return
"VA7654321-789".

If the FLAG input parameter is "1", this API would return "789"


Example 3:
---------
The NEW DEA#'s (#53.21) multiple field doesn't contain any DEA numbers.
FACILITY DEA NUMBER field (#52) is "VA7654321"

The IEN input parameter points to a VA prescriber.

The VA# field (#53.3) is null.

If the FLAG input parameter is null or "0", this API would return "" (NULL).

If the FLAG input parameter is "1", this API would return "" (NULL).


Example 4:
---------
The NEW DEA#'s (#53.21) multiple field doesn't contain any DEA numbers.

The IEN input parameter points to a VA prescriber.

FACILITY DEA NUMBER field (#52) is "VA7654321".

VA# field (#53.3) is "789".

PROVIDER TYPE field (#53.6) is "FEE BASIS" or "C & A". If the FLAG input
parameter is null or "0", this API would return "" (NULL).

If the FLAG input parameter is "1", this API would return "" (NULL).


Example 5:
----------
The NEW DEA#'s (#53.21) multiple field points to expired DEA "AB1234567" in
the DEA NUMBERS file (#8991.9) having the USE FOR INPATIENT ORDERS? field
(#.06) set to YES.

The IEN input parameter points to a VA prescriber.

FACILITY DEA NUMBER field (#52) is "VA7654321".

VA# field (#53.3) is "789".

If the XPAR parameter 'PSOEPCS EXPIRED DEA FAILOVER' is set to 'Yes', the API
would return "VA7654321-789".

If the XPAR parameter 'PSOEPCS EXPIRED DEA FAILOVER' is set to 'No', the API
would return null ("").


Example 6:
---------
The NEW DEA#'s (#53.21) multiple field pointing to a record in the DEA NUMBERS
file (#8991.9) having the USE FOR INPATIENT ORDERS? field (#.06) set to YES is
"AB1234567".

The IEN input parameter points to a VA prescriber.

The EXPIRATION DATE field (#.04) in the DEA NUMBERS is in the past, for
example, 3201106, representing November 6, 2020.

FACILITY DEA NUMBER (#52) field in the INSTITUTION (#4) file is "VA7654321".

The user pointed to by the IEN parameter has a VA# field (#53.3) equal to
"789".

If the DATE parameter passed in is less than the EXPIRATION DATE of the DEA
number, (e.g., "3201104", representing November 4, 2020), this API returns
"AB1234567".

If the DATE parameter "3201106" passed in is equal to or greater than DEA
EXPIRATION DATE, this API returns "AB1234567-789" if the FLAG input parameter
is not passed in.

If the DATE parameter "3201106" passed in is equal to or greater than DEA
EXPIRATION DATE, this API returns "AB1234567-789" if the FLAG input parameter
is passed in.
IEN Input
This is the New Person file (#200) IEN for the entry
to be checked.


FLAG (optional) Input
This flag controls what is returned when the VA
prescriber does not have a valid DEA number. A user with no valid DEA number
may have no DEA number or an expired DEA number.


* FLAG is null or "0" - This routine will check to see if a VA prescriber has
a value in the VA# (#53.3) field of the NEW PERSON (#200) file and the
FACILITY DEA NUMBER (#52) field of the INSTITUTION (#4) file. If values are
found in both of those fields, this routine will return the following:

FACILITY DEA NUMBER field (#52)_"-"_VA# field(#53.3)


* FLAG is "1" - This routine will check to see if a VA prescriber has a value
in the VA# (#53.3) field of the NEW PERSON (#200) file. If a value is found in
that field, this routine will return that value. Otherwise, this routine
returns an empty string.
DATE (optional) Input
This parameter to enter in VA FileMan format.  The
date to be checked against the DEA# Expiration Date instead of default DT
(today's date).
$$NAME
This entry point returns the full name of the
specified user in a mixed case displayable format; the user's given name (i.e.
First Last) will be returned unless a second parameter of "F" is passed in to
get the Family name (i.e. Last,First)

Usage:  S NAME=$$NAME^XUSER(IEN[,format])


VARIABLES TYPE VARIABLES DESCRIPTION
IEN Input
This is the IEN of the user in the New Person file
#200.
FORMAT(optional) Input
This should be either "F" or "G", to indicate if the
user's name should be returned formatted by Family or Given name,
respectively.  For example,
"F"-Family (e.g., "Xuuser,Two")
"G"(default)-Given (e.g., "Two Xuuser")


$$NAME Output
The full name of the specified user in a mixed case
displayable format; the user's given name (i.e. First Last) will be returned
unless a second parameter of "F" is passed in to get the Family name (i.e.
Last,First)

$$SDEA
The DEA e-Prescribing of Control Substances project
requires an API to utilize the following 'Privileges Algorithm' to check for
prescribing privileges:

- If the Prescriber has a valid Individual DEA number, the
the DEA number's SCHEDULE fields (#2.1-#2.6) in the DEA
NUMBERS file (#8991.9) determine the explicit set of DEA
prescribing permissions.

- If the Prescriber has a no valid Individual DEA numbers,
but has a valid Institutional DEA number, the SCHEDULE
fields (#55.1-#55.6) in the Prescriber's NEW PERSON file
(#200) entry determine the explicit set of DEA prescribing
permissions.

- If the Prescriber has an expired Individual DEA number, no
valid Institutional DEA numbers, the Prescriber's NON-VA
PRESCRIBER field (#53.91) in the NEW PERSON file (#200) is
not set to YES, the PROVIDER TYPE field (#53.6) in the NEW
PERSON file (#200) is not set to "FEE BASIS" or "C & A",
the Prescriber has a VA#, and the PSOEPCS EXPIRED DEA
FAILOVER parameter is not set to NO, the SCHEDULE fields
(#55.1-#55.6) in the Prescriber's NEW PERSON file (#200)
entry determine the explicit set of DEA prescribing
permissions.

- If the Prescriber has an expired Individual DEA number, no
valid Institutional DEA numbers, and the PSOEPCS EXPIRED
DEA FAILOVER parameter is set to NO or the Prescriber's
NON-VA PRESCRIBER field is set to YES, or the Prescriber's
PROVIDER TYPE field is set to "C & A" or "FEE BASIS", then
the VA# is ignored and the Prescriber is not permitted to
prescribe any scheduled medications.

- If the Prescriber has no DEA numbers in the NEW DEA#'s
multiple field (#53.21) in the NEW PERSON file (#200),
their NON-VA PRESCRIBER field (#53.91) in the NEW PERSON
file (#200) is not set to YES, the PROVIDER TYPE field
(#53.6) is not set to "FEE BASIS" or "C & A", and the
Prescriber has a VA#, the SCHEDULE fields (#55.1-#55.6)
in the Prescriber's NEW PERSON file (#200) entry determine
the explicit set of DEA prescribing permissions.

- If the Prescriber has no DEA numbers in the NEW DEA#'s
multiple field (#53.21) in the NEW PERSON file (#200), and
their NON-VA PRESCRIBER field (#53.91) in the NEW PERSON
file (#200) is set to YES or their PROVIDER TYPE field
(#53.6) is set to "FEE BASIS" or "C & A", then the PSOEPCS
EXPIRED DEA FAILOVER parameter is ignored, the VA# is
ignored, and the Prescriber is not permitted to prescribe
any scheduled medications.

(Note: All of these checks do not apply to documentation of
non-VA medication.)

Usage:  S X=$$SDEA^XUSER(FG,IEN,PSDEA,DATE)
VARIABLES TYPE VARIABLES DESCRIPTION
FG (optional) Input
Not used, retained for backward compatibility.
IEN Input
This is the New Person file (#200) IEN for the entry
to be checked.
PSDEA Input
This parameter is DEA schedule.  DEA schedule is a
2-6 position field. It comes from the DRUG file (#50) in Pharmacy. This field
is used, by this API, to verify the provider is allowed to write orders for
specific controlled substances. For example: if the schedule is 2A, this
indicates a controlled substance, schedule 2.

Chart for all values:

0          MANUFACTURED IN PHARMACY

1          SCHEDULE 1 ITEM

2          SCHEDULE 2 ITEM

3          SCHEDULE 3 ITEM

4          SCHEDULE 4 ITEM

5          SCHEDULE 5 ITEM

6          LEGEND ITEM

9          OVER-THE-COUNTER

L          DEPRESSANTS AND STIMULANTS

A          NARCOTICS AND ALCOHOLS

P          DATED DRUGS

I          INVESTIGATIONAL DRUGS

M          BULK COMPOUND ITEMS

C          CONTROLLED SUBSTANCES - NON NARCOTIC

R          RESTRICTED ITEMS

S          SUPPLY ITEMS

B          ALLOW REFILL (SCH. 3, 4, 5 ONLY)

W          NOT RENEWABLE

F          NON REFILLABLE

E          ELECTRONICALLY BILLABLE

N          NUTRITIONAL SUPPLEMENT

U          SENSITIVE DRUG



$$SDEA Output
Returns: DEA# or Facility DEA_"-"_user VA# similar to
the $$DEA call.

1 - No valid DEA number found.

2 - DEA number not authorized for schedule PSDEA.

4^expiration date - DEA# expiration date has expired.  It will check if DEA#
and expiration date are not null.  The expiration date is returned in external
format.
DATE (optional) Input
Date in VA FileMan format. The date to be checked
against the DEA# Expiration Date instead of default DT (today's date).
IDEA (optional) Input
This parameter is a DEA number or "I". If a DEA
number is passed in, the DEA number's permissions are checked. If an "I" is
passed in, only the permissions for the user's DEA number that has the USE FOR
INPATIENT ORDERS? (#.06) field in the DEA NUMBERS (#8991.9) file is checked.
$$DETOX
This API obtains the value stored in the DETOX NUMBER
(#.03) field in the DEA NUMBERS (#8991.9) file.

Usage:  S X=$$DETOX^XUSER(IEN,DATE)
VARIABLES TYPE VARIABLES DESCRIPTION
IEN Input
The IEN of user in NEW PERSON file (#200).
$$DETOX Output
Returns: one of the following:

- User's DETOX number from the DETOX NUMBER (#.03) field in the DEA
NUMBERS (#8991.9) file.

- NULL - DETOX NUMBER from the DETOX NUMBER (#.03) field in the DEA
NUMBERS (#8991.9) file is NULL.
DATE(optional) Input
This parameter to enter in VA FileMan format.  The
date to be checked against the DEA# Expiration Date instead of default DT
(today's date).
$$VDEA
The DEA electronic Prescribing of Controlled
Substances (ePCS) project requires an API to determine if a user in the NEW
PERSON file (#200) is able to sign orders for controlled substances.

Usage:  S X=$$VDEA^XUSER(.RETURN,IEN)
VARIABLES TYPE VARIABLES DESCRIPTION
RETURN Input
This is a reference to an array where the reasons why
the user cannot sign orders for controlled substances and which DEA schedules
the user can prescribe will be returned in. For example,
RETURN("Is permitted to prescribe all schedules.)=""
IEN Input
This is the IEN of the user in the NEW PERSON file
(#200).

$$VDEA Output
Returns:

1 - if the user is able to sign orders for controlled substances.  0 - if the
user is not able to sign orders for controlled substances.
RETURN Output
This array contains the reasons why the user cannot
sign orders for controlled substances and which DEA schedules the user can
prescribe. For example,
RETURN("Is not permitted to prescribe any schedules.")=""
$$PRDEA
The DEA electronic Prescribing of Controlled
Substances (ePCS) module requires an API to determine a provider's Default DEA
number, indicated by the DEA number in NEW DEA#'s multiple field (#53.21) in
the Prescriber's NEW PERSON file (#200) entry pointing to a DEA number in the
DEA NUMBERS file (#8991.9) for which the USER FOR INPATIENT ORDERS? field
(#.06) is set to YES.

Usage:  S X=$$PRDEA^XUSER(IEN)
VARIABLES TYPE VARIABLES DESCRIPTION
IEN Input
This is the IEN of the user in the NEW PERSON File
(#200).
$$PRDEA Output
Returns:  The provider's default DEA number,
indicated by the DEA number in NEW DEA#'s multiple field (#53.21) in the
prescriber's NEW PERSON file (#200) entry pointing to a DEA number in the DEA
NUMBERS File (#8991.9) for which the USER FOR INPATIENT ORDERS? field (#.06)
is set to YES.
$$PRXDT
The expiration date of a provider's DEA number is
required for reporting purposes, to facilitate searches for recently expired
and soon to expire DEA number.

Usage:  S X=$$PRXDT^XUSER(IEN)
VARIABLES TYPE VARIABLES DESCRIPTION
IEN Input
This is the IEN of the user in the NEW PERSON file
(#200).
$$PRXDT Output
Returns: The Prescriber's DEA expiration date from
the EXPIRATION DATE field (#.04) in the DEA NUMBERS file (#8991.8) for which
the USE FOR INPATIENT ORDERS field is set to YES.

Usage:  S X=$$PRXDT^XUSER(IEN)
$$PRSCH
The Prescriber's DEA permissions from their default
DEA number. The permissions are retrieved from the SCHEDULE fields (#2.1-#2.6)
in the DEA NUMBERS file (#8991.8), pointed to by the NEW DEA#'s multiple field
in the NEW PERSON file. The Prescriber's default DEA number is determined by
the USE FOR INPATIENT ORDERS? field (#.06) in the DEA NUMBERS file (#8991.9)
being set to YES.

Usage: S X=$$PRSCH^XUSER
VARIABLES TYPE VARIABLES DESCRIPTION
IEN Input
This is the IEN of the user in the NEW PERSON file
(#200).
$$PRSCH Output
Returns: The Prescriber's DEA permissions from their
default DEA number.  The permissions are retrieved from the SCHEDULE fields
(#2.1-#2.6) in the DEA NUMBERS file (#8991.8), pointed to by the NEW DEA#'s
multiple field in the NEW PERSON file.

The Prescriber's default DEA number is determined by the USE FOR INPATIENT
ORDERS? field (#.06) in the DEA NUMBERS file (#8991.9) being set to YES.  The
DEA permissions are returned in internal format with delimiters. For example,
1^1^1^1^1^1 indicates permissions for all schedules, and 0^0^0^0^0^0 indicates
no permissions. The mapping of the delimited string to the SCHEDULE fields in
the DEA NUMBERS file (#8991.9) is as follows:

Piece   Field #   Field Name
1       2.1       SCHEDULE II NARCOTIC
2       2.2       SCHEDULE II NON-NARCOTIC
3       2.3       SCHEDULE III NARCOTIC
4       2.4       SCHEDULE III NON-NARCOTIC
5       2.5       SCHEDULE IV
6       2.6       SCHEDULE V
DATE ACTIVATED 2023/02/08