Event Monitor APIs - HLEVAPI ICR (4225)

Name

Value

NUMBER

4225

IA #

4225

DATE CREATED

2003/08/26

CUSTODIAL PACKAGE

HEALTH LEVEL SEVEN

CUSTODIAL ISC

San Francisco

USAGE

Controlled Subscription

TYPE

Routine

ROUTINE

HLEVAPI

NAME

Event Monitor APIs - HLEVAPI

GENERAL DESCRIPTION

Enhancement patch HL*1.6*106 contains the VistA HL7
Event Monitor system.  The Event Monitor system facilitates the process of
monitoring the VistA HL7 environment for conditions and events, as well as
notification of the VistA HL7 support and development personnel.

The Event Monitor system includes new files and options, as well as the eight
application program interfaces (APIs) documented in this integration
agreement.

The Event Monitor system is built around:

- Monitors
- Master Job

The Monitor is built around an entry in the HL7 Monitor file (#776.1) that
"points" to an M code API.  The monitor also includes a field that specifies
how many minutes should elapse between every "run" of the monitor.

The Master Job runs every few hours perpetually.  It checks every monitor
entered in the HL7 Monitor file to determine whether the monitor should be
run.  If it is time for a monitor "run", the master job queues a background
job for the specific monitor.

The primary task of the master job is to start individual monitor jobs, and to
record the result of it's evaluation of every monitor; whether it was started
or not, and the reason for the action taken.

The APIs created by patch HL*1.6*106 and included in integration agreements
4225, 4226 and 4227 are:

- $$START^HLEVAPI        - CHECKIN^HLEVAPI         - CHECKOUT^HLEVAPI
- MAILIT^HLEVAPI         - ABORT^HLEVAIP           - VARIABLE^HLEVAPI
- ONOFF^HLEVAPI0         - APPSTAT^HLEVAPI1        - MSGTEXT^HLEVAPI
- RUNDIARY^HLEVAPI1

Application developers wishing to use the Event Monitor system, including
these APIs, must secure permission from the VistA HL7 development team.

--------------------------------------------------------------------------

Please peruse the APIs documented in this integration agreement in the
following order:

- START^HLEVAPI         - CHECKIN^HLEVAPI        - CHECKOUT^HLEVAPI
- VARIABLE^HLEVAPI

The above APIs form a conceptual unit.

The MAILIT^HLEVAPI and the ABORT^HLEVAPI APIs may be reviewed in any order,
but they should be reviewed after the four APIs listed above.

STATUS

Withdrawn

DURATION

Till Otherwise Agreed

HLEVAPI

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

CHECKIN

==========================================================================
Please read the START^HLEVAPI API section before continuing, as that API
section contains important foundation material referred to below.
==========================================================================

The CHECKIN^HLEVAPI API should be called every 30 to 60 seconds during the
running of a monitor.  This API records the time "now" in a timestamp field,
and stores the values of any declared variables.

If the monitor's M code runs for less then 60 seconds, this API does not need
to be called.

The syntax for this call is:

D CHECKIN^HLEVAPI

There are no API parameters.

CHECKOUT

==========================================================================
Please read the START^HLEVAPI API section before continuing, as that API
section contains important foundation material referred to below.
==========================================================================

The CHECKOUT^HLEVAPI API should be called after all M code execution has
completed.  This API stores all declared variables, refreshes the timestamp,
and marks the status of the monitor "run" finished.

The syntax for this call is:

D CHECKOUT^HLEVAPI

There are no API parameters.

MAILIT

When a monitor's M code finishes, a Mailman message
can be sent to local and remote recipients.  The MAILIT^HLEVAPI API is used to
send the message.

The following M code illustrates the use of the MAILIT^HLEVAPI API.

LOOP   ; Looping code to count entries in file 773
;
S VAR("CT")="773-CT" ; Defines the variable to be tracked later
D START^HLEVAPI(.VAR)
;
S IEN=0,CT=0
F  S IEN=$O(^HLMA(IEN)) Q:'IEN  D
.  S CT=CT+1
.  I '(CT#100) D CHECKIN^HLEVAPI
;
D CHECKOUT^HLEVAPI
;
D MAILIT^HLEVAPI(HLEVIENE,HLEVIENJ)
;
Q


The MAILIT^HLEVAPI API has three possible parameters, and the third parameter
is discussed below.  The syntax above is the simplest allowed form and
involves two parameters.  In this example, HLEVIENE and HLEVIENJ are passed as
the two parameters.  These variables are always defined, and so the
application developer doesn't need to define these variables or do anything
other than "just pass the variables."

In the above example, no recipients for the message are in any way "declared"
or defined.  This is because the recipients for the message sent by this API
have already been defined as part of the monitor definition in the HL7 Monitor
file (#776.1) entry.

The following example illustrates how local and remote recipients can be
passed on-the-fly into the MAILIT^HLEVAPI API.

LOOP   ; Looping code to count entries in file 773
;
S VAR("CT")="773-CT" ; Defines the variable to be tracked later
D START^HLEVAPI(.VAR)
;
S IEN=0,CT=0
F  S IEN=$O(^HLMA(IEN)) Q:'IEN  D
.  S CT=CT+1
.  I '(CT#100) D CHECKIN^HLEVAPI
;
D CHECKOUT^HLEVAPI
;
S XMY("FirstLast")=""
S XMY("HL7SystemMonitoring@DNS")=""
D MAILIT^HLEVAPI(HLEVIENE,HLEVIENJ,.XMY)
;
Q

In this example, the XMY local variable array is defined and passed by
reference into MAILIT^HLEVAPI. Any XMY-based recipients created as shown above
are added to the recipients defined in the monitor entry in the HL7 Monitor
file.

-------------------------------------------------------------------------

Please read the documentation included in patch HL*1.6*106 for additional
information about this API and the general use of the Event Monitor system.

VARIABLES	TYPE	VARIABLES DESCRIPTION
HLEVIENE	Input	The HLEVIENE variable is the internal entry number of the

START

M code that is interfaced with the Event Monitor
system using the APIs documented in this interface agreement, and agreements
4226 and 4227 must begin with a call to START^HLEVAPI(), and must call
CHECKOUT^HLEVAPI after all M code execution has completed.  If the time of M
code execution is longer than one minute, M code should call CHECKIN^HLEVAPI
every 30-60 seconds.

The following M code example illustrates how these APIs should be called.

LOOP   ; Looping code to count entries in file 773
;
; Define the variable to be tracked later...
S VAR("CT")="773-CT"
; Call START, passing in by reference the variable...
D START^HLEVAPI(.VAR)
;
S IEN=0,CT=0
F  S IEN=$O(^HLMA(IEN)) Q:'IEN  D
.  S CT=CT+1
.  ; Check in every few seconds...
.  I '(CT#1000) D CHECKIN^HLEVAPI ; Variable CT stored...
;
D CHECKOUT^HLEVAPI ; Variable CT stored here too...
;
Q

In the above example, the variable CT is "declared" and passed into the
START^HLEVAPI API.  (The "773-CT" is an explanation of the variable being
tracked that is included in some report views.)  Since the CT variable has
been declared, the CHECKIN^HLEVAPI and CHECKOUT^HLEVAPI APIs know to record
it's current value when called.

It is not required to pass variables into the START^HLEVAPI API.  If this is
not done, the call to START^HLEVAPI will look the code below.

D START^HLEVAPI()

The VARIABLE^HLEVAPI API allows the declaration of variables on-the-fly, at
any time after the call to START^HLEVAPI.

-------------------------------------------------------------------------

Please read the documentation included in patch HL*1.6*106 for additional
information about this API and the general use of the Event Monitor system.

VARIABLES

TYPE

VARIABLES DESCRIPTION

VAR

Input

The START^HLEVAPI(.VAR) API contains one
pass-by-reference parameter.  The passing of variables into this API is
optional.

The syntax for a call to START^HLEVAPI where variables are passed by reference
is:

S VAR("CT")="CT-773"
D START^HLEVAPI(.CT)

Of course, any number of entries in the VAR() local array are allowed to be
passed into the START^HLEVAPI API.

When VAR("CT")="CT-773" was set above, the variable CT was "declared", and so
will be stored every time CHECKIN^HLEVAPI and CHECKOUT^HLEVAPI is called
subsequently.  And, "CT-773" is a slightly more understandable "explanation"
for the variable being tracked that is included in some screen displays.

The explanation (what is to the right of the equals sign) for a variable must
not exceed 10 characters.

When no variables are declared, the call to START^HLEVAPI will look like this:

D START^HLEVAPI()

-------------------------------------------------------------------------

Please read the documentation included in patch HL*1.6*106 for additional
information about this API and the general use of the Event Monitor system.

ABORT

==========================================================================
Please read the START^HLEVAPI API section before continuing, as that API
section contains important foundation material referred to below.
==========================================================================

The ABORT^HLEVAPI API should be called if the execution of the M code-based
monitor should stop prematurely.  (This usually occurs when the Taskman job
has been externally requested to stop.)

The syntax for this call is:

D ABORT^HLEVAPI("E",REA)

The value "E" should always be passed in the first parameter position, and the
second parameter should include the reason for the monitor termination.  (The
termination reason must not exceed 10 characters.)

The following M code illustrates the use of the ABORT^HLEVAPI API.

LOOP   ; Looping code to count entries in file 773
;
D START^HLEVAPI()
;
S IEN=0,CT=0,ABRT=0
F  S IEN=$O(^HLMA(IEN)) Q:'IEN!(ABRT)  D
.  S CT=CT+1
.  I '(CT#100) D
.  .  D CHECKIN^HLEVAPI
.  .  I $$S^%ZTLOAD S ABRT=1 ; Taskman request to stop
;
I ABRT D ABORT^HLEVAPI("E","Tskmn Req")
I 'ABRT D CHECKOUT^HLEVAPI
;
Q

Note that the ABORT^HLEVAPI API should be called instead of CHECKOUT^HLEVAPI
when the monitor stops prematurely.

VARIABLES	TYPE	VARIABLES DESCRIPTION
REA	Input	The second parameter of the ABORT^HLEVAPI API should contain the reason for premature stoppage of the monitor. This variable must not exceed 10 characters.

VARIABLE

The START^HLEVAPI API allows the declaration of
variables to be tracked and stored by the CHECKIN^HLEVAPI and CHECKOUT^HLEVAPI
APIs.  The VARIABLE^HLEVAPI API is very similar to the method used by
START^HLEVAPI API in variable declaration, but more powerful.

The following M code illustrates the use of the VARIABLE^HLEVAPI API to
declare variables to be tracked on-the-fly.

LOOP   ; Looping code to count entries in file 773
;
D START^HLEVAPI() ; No variables declared and pssed in...
;
S VAR("CT")="CT-773",VAR("HLEV*")="HL Array"
D VARIABLE^HLEVAPI(.VAR)
;
S IEN=0,CT=0
F  S IEN=$O(^HLMA(IEN)) Q:'IEN  D
.  S CT=CT+1
.  I '(CT#100) D CHECKIN^HLEVAPI
;
D CHECKOUT^HLEVAPI
;
Q

In the above example, two "variables" are declared: CT and HLEV*.  The
declaration of the CT variable will result in the storage of the CT variable
every time CHECKIN^HLEVAPI and CHECKOUT^HLEVAPI is called.  With the second
variable HLEV*, the asterisk following "HLEV" is a wild card and instructs the
CHECKIN^HLEVAPI and CHECKOUT^HLEVAPI APIs to store all local variables
beginning with HLEV.  (E.g., this would result in HLEVRSLT and HLEV(25) being
stored.)

VARIABLES	TYPE	VARIABLES DESCRIPTION
VAR	Input	The only parameter for this API is a pass-by-reference variable and is documented above in the VARIABLE^HLEVAPI section.