Print Page as PDF
HL7 Capacity Management Phase II API ICR (3488)

HL7 Capacity Management Phase II API    ICR (3488)

Name Value
NUMBER 3488
IA # 3488
DATE CREATED 2001/12/03
CUSTODIAL PACKAGE HEALTH LEVEL SEVEN
CUSTODIAL ISC San Francisco
USAGE Supported
TYPE Routine
DBIC APPROVAL STATUS APPROVED
ROUTINE HLUCM
NAME HL7 Capacity Management Phase II API
GENERAL DESCRIPTION
Returns Health Level 7 (HL7) activity totals for a
parameter-supplied time range.  Additional control over the Hl7 activity
included in the totals is available using passed parameters.  (See HL*1.6*103
for additional information.)

COMPARISON OF $$CM & $$CM2:
---------------------------
Patch HL*1.6*79 holds phase I software, and is associated with DBIA# 3484.
Phase I software is almost identical to phase II software, except in the
number of "messages" returned by the two APIs.    The call point for

DBIA# 3484 - phase I software - is $$CM^HLUCM.  The call point for this DBIA -
phase II software - is $$CM2^HLUCM.

$$CM^HLUCM returns the number of discrete message occurring during a
parameter-defined period of time.  $$CM2^HLUCM returns the number of "message
units" during the same period of time.  All other totals returned by both
parameters are identical.

A message is an individual message, such as an application acknowledgement.  A
message unit is made up of all related messages.

The difference between a message (phase I, $$CM^HLUCM) and a message unit
(phase II, $$CM2^HLUCM) can be illustrated using the following sequence of
events.

* Baltimore sends a message to Washington.  * Washington sends back a commit
acknowledgement to Baltimore.  * Washington sends an application
acknowledgement to Washington.  * Baltimore sends back to Washington a commit
acknowledgement
for the just sent application acknowledgement.

In the above example, $$CM^HLUCM would report a count of 4 messages.
$$CM2^HLUCM would report a count of 1 message, or "message unit." (Since all 4
messages are "related", they are combined into one reported "message.")
STATUS Active
KEYWORDS
  • HL7
  • CM
  • CAPACITY MANAGEMENT
DURATION Till Otherwise Agreed
ID HLUCM
COMPONENT/ENTRY POINT
COMPONENT/ENTRY POINT COMPONENT DESCRIPTION VARIABLES
$$CM2
The syntax for the $$CM2 call point is:

$$CM2(SDT,EDT,NMSP,PROT,SAVE,COND,ERR)

The passable parameters for this call pointer are explained below.

SDT -  Start date/time in Fileman format. (E.g.,
3011123.1234)
EDT -  End date/time in Fileman format.
NMSP - Namespace(s) of entries to be included.
PROT - Protocol(s) to be included.
SAVE - Free text name of inital subscript in ^TMP(SAVE,$j)
global created by this call point.
COND - Conditions under which matching entries are to
be collected.
ERR -  Location for error information returned by the $$CM
call point.  ERR is passed by reference.

The above information regarding the $$CM2 call point is provided as an
overview of its capabilities.  Refer to the documentation included in patch
HL*1.6*103 for complete explanation.
VARIABLES TYPE VARIABLES DESCRIPTION
$$CM2 Output
Calling $$CM2^HLUCM(SDT,EDT,NMSP,PROT,SAVE,COND,ERR)
returns a 3 piece string of data.  The pieces of data are:

Piece 1 = Number of characters in all messages found by the API call.
Piece 2 = Number of message units found by the API call.
Piece 3 = Total transmission and receipt time for all message units
found by API call.

Calling $$CM2^HLUCM returns this 3 piece string of data.  In addition, when
the API is called, it creates some ^TMP global data holding additional
information about the messages found. Full information about the global
created can be found in the patch HL*1.6*103 documentation.  However, a brief
overview of the data structure is provided below.

The fifth parameter passed into the $$CM2^HLUCM API is SAVE.  This parameter
specifies the initial subscript to be used in the ^TMP global data.  (See the
SAVE variable for more information.)  For example, if the save parameter is
passed as "DATA", the ^TMP global data is stored in ^TMP("DATA",$J,...).

The ^TMP global data created by the $$CM2^HLUCM call point is subdivided (by
sorting subscripts) into the following sections:

Totals by transmission time, namespace, and protocol.
Totals by namespace, incoming/outgoing, namespace, transmission
time, and protocol.
Totals by namepsace, local/remote, namespace, transmission
time, and protocol.
Totals by protocol, namespace, and time.

To explain the above information more fully, consider the last entry.  What
this means is that totals are sorted by protocol, and within protocol the
totals are sorted by namespace, and within namespace the totals are sorted by
transmission time.

Example data, and additional explanation of the global data created by the API
is in patch HL*1.6*103.
SDT Input
The syntax for the $$CM2 call point is:

$$CM2(SDT,EDT,NMSP,PROT,SAVE,COND,ERR)

The first parameter, SDT, is the start time in Fileman format.  An example
call is shown below.

W $$CM2^HLUCM(3011123.12,3011123.13,"DG","VAFHA08","DATA","BOTH",.ERR)

In this example, SDT has the value of 3011123.12.
EDT Input
The syntax for the $$CM2 call point is:

$$CM2(SDT,EDT,NMSP,PROT,SAVE,COND,ERR)

The second parameter, EDT, is the end time in Fileman format.  An example call
is shown below.

W $$CM2^HLUCM(3011123.12,3011123.13,"DG","VAFHA08","DATA","BOTH",.ERR)

In this example, EDT has the value of 3011123.13.
NMSP Input
The syntax for the $$CM2 call point is:

$$CM2(SDT,EDT,NMSP,PROT,SAVE,COND,ERR)

The third parameter, NMSP, is the NAMESPACE of the entry(s) to be included. An
example call is shown below.

W $$CM2^HLUCM(3011123.12,3011123.13,"DG","VAFHA08","DATA","BOTH",.ERR)

In this example, NMSP has the value of "DG".

See patch HL*1.6*103 documentation for additional details.
PROT Input
The syntax for the $$CM2 call point is:

$$CM2(SDT,EDT,NMSP,PROT,SAVE,COND,ERR)

The fourth parameter, PROT, is the PROTOCOL of the entry(s) to be included.
An example call is shown below.

W $$CM2^HLUCM(3011123.12,3011123.13,"DG","VAFHA08","DATA","BOTH",.ERR)

In this example, PROT has the value of "VAFH A08".

See patch HL*1.6*103 documentation for additional details.
SAVE Input
The syntax for the $$CM2 call point is:

$$CM2(SDT,EDT,NMSP,PROT,SAVE,COND,ERR)

The fifth parameter, SAVE, is the initial subscript to use in the ^TMP global
data. An example call is shown below.

W $$CM2^HLUCM(3011123.12,3011123.13,"DG","VAFH A08","DATA","BOTH",.ERR)

In this example, SAVE has the value of "DATA".  This would cause the creation
of ^TMP("DATA",$J) data.
COND Input
The syntax for the $$CM2 call point is:

$$CM2(SDT,EDT,NMSP,PROT,SAVE,COND,ERR)

The sixth parameter, COND, defines criteria to be used when searching for
messages. An example call is shown below.

W $$CM2^HLUCM(3011123.12,3011123.13,"DG","VAFH A08","DATA","BOTH",.ERR)

In this example, COND has the value of "BOTH".  Passing the value of "BOTH"
requires that each message has to have a namespace of "DG" and a protocol of
"VAFH A08."  In other words, 'both' the namespace and the protocol values have
to be true before a message is counted.

Instead of "BOTH", the value of "EITHER" can be passed.  In the above example,
if "EITHER" had been passed as the value of COND, then messages will be
counted if 'either' the namespace is "DG" or the protocol is "VAFH A08."  In
other words, if either criteria is matched, a message is counted.

See patch HL*1.6*103 documentation for addition information.
ERR Output
The syntax for the $$CM2 call point is:

$$CM2(SDT,EDT,NMSP,PROT,SAVE,COND,ERR)

The seventh parameter, ERR, is the location for error information returned by
the $$CM2 call.  Here is an example call:

W $$CM2^HLUCM(3011123.12,3011123.13,"DG","VAFH A08","DATA","BOTH",.ERR)

In this example, ERR is passed by reference.  No data is present in the ERR
array prior to the call, (and even if it did, the ERR local array is killed as
oneof the initial API actions, in order to ensure that the ERR array is empty
at the start of processing.)  If any problems are encountered by the API, such
as passing in invalid parameter values, information about the error(s) is
placed in the ERR local array and "passed back" to the calling process.

See patch HL*1.6*103 documentation for addition information.

MAIL MESSAGE 33789973
Generated from JAN 24, 2019@ IA Listing Descriptions