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