HL7 Capacity Management $$CM2F API ICR (4117)

Name

Value

NUMBER

4117

IA #

4117

DATE CREATED

2003/06/05

CUSTODIAL PACKAGE

HEALTH LEVEL SEVEN

CUSTODIAL ISC

San Francisco

USAGE

Controlled Subscription

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

HLUCM

NAME

HL7 Capacity Management $$CM2F 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.

Patch HL*1.6*103 fully documents the $$CM2F^HLUCM API covered by this
integration agreement.  In addition, the patch documentation discusses the
$$CM^HLUCM (DBIA# 3484) and $$CM2^HLUCM (DBIA# 3489) APIs.

COMPARISON OF $$CM, $$CM2 & $$CM2F:
-----------------------------------
$$CM^HLUCM and $$CM2^HLUCM are almost identical to each other.  Both have
identical parameters and both return data in the same format.  The only
difference is that $$CM^HLUCM returns the number of messages during the
user-supplied time range, and $$CM2^HLUCM returns the number of "message
units" within a time range.

Messages are individually transmitted messages.  The initially transmitted
message is considered a "message" by $$CM^HLUCM, and the return
acknowledgement is considers a separate and unique "message."  If a message is
transmitted, and an acknowledgement message returned, $$CM^HLUCM returns a
total of two messages.

Message "units" are collections of functionally related messages.  In the
above example, $$CM^HLUCM counts two messages, but since the message and it's
acknowledgement are functionally related, $$CM2^HLUCM returns a count of one
"unit."

$$CM2F^HLUCM counts message units in an identical manner to $$CM2.  The only
difference between these two APIs is the $$CM2F^HLUCM counts only message
units involving remote sites.  $$CM2^HLUCM (and $$CM^HLUCM, for that matter)
counts both locally and remotely sent message units.

STATUS

Active

KEYWORDS

HL7
CM
CAPACITY MANAGEMENT

DURATION

Till Otherwise Agreed

HLUCM

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

$$CM2F

The syntax for the $$CM2F call point is:

$$CM2F(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.

When $$CM2F is called, only remote message units are counted.

The above information regarding the $$CM2F 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
$$CM2F	Output	Calling $$CM2F^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 $$CM2F^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 HL1.6103 documentation. However, a brief overview of the data structure is provided below. The fifth parameter passed into the $$CM2F^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 $$CM2F^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 HL1.6103.
SDT	Input	The syntax for the $$CM2F call point is: $$CM2F(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 $$CM2F^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 $$CM2F call point is: $$CM2F(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 $$CM2F^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 $$CM2F call point is: $$CM2F(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 $$CM2F^HLUCM(3011123.12,3011123.13,"DG","VAFHA08","DATA","BOTH",.ERR) In this example, NMSP has the value of "DG". See patch HL1.6103 documentation for additional details.
PROT	Input	The syntax for the $$CM2F call point is: $$CM2F(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 $$CM2F^HLUCM(3011123.12,3011123.13,"DG","VAFHA08","DATA","BOTH",.ERR) In this example, PROT has the value of "VAFH A08". See patch HL1.6103 documentation for additional details.
SAVE	Input	The syntax for the $$CM2F call point is: $$CM2F(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 $$CM2F^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 $$CM2F call point is: $$CM2F(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 $$CM2F^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 HL1.6103 documentation for addition information.
ERR	Output	The syntax for the $$CM2F call point is: $$CM2F(SDT,EDT,NMSP,PROT,SAVE,COND,ERR) The seventh parameter, ERR, is the location for error information returned by the $$CM2F call. Here is an example call: W $$CM2F^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 HL1.6103 documentation for addition information.