HL7 MESSAGE ADMINISTRATION ICR (2164)

Name

Value

NUMBER

2164

IA #

2164

DATE CREATED

1997/10/30

CUSTODIAL PACKAGE

HEALTH LEVEL SEVEN

CUSTODIAL ISC

San Francisco

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

HLMA

NAME

HL7 MESSAGE ADMINISTRATION

ORIGINAL NUMBER

2161

GENERAL DESCRIPTION

API to generate a HL7 message.

STATUS

Active

HLMA

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

GENERATE

The
GENERATE^HLMA(HLEID,HLARYTYP,HLFORMAT,HLRSLT,HLMTIEN,HLP) entry point to used
to generate a HL7 message.  It returns a unique message ID if a message is
successfully generated.

VARIABLES	TYPE	VARIABLES DESCRIPTION
HLEID	Input	The name or IEN of the event driver protocol in the Protocol File (#101).
HLARYTYP	Input	Array type. One of the following codes: LM = local array containing a single message LB = local array containing a batch of messages GM = global array containing a single message GB = global array containing a batch of messages
HLFORMAT	Input	Format of array, 1 for pre-formatted in HL7 format, otherwise 0
HLRESLT	Both	The variable that will be returned to the calling application with either a error message or a unique message ID.
HLMTIEN	Input	Optional IEN of entry in Message Text file where the message being generated is to be stored. This parameter is only passed for a batch type message.
HLP	Input	The HLP parameter is passed-by-reference. The HLP subscripts that are processed by GENERATE^HLMA are identical to the DIRECT^HLMA HLP subscripts. These subscripts are listed below. o HLP("PRIORITY") = I for immediate or D for deferred o HLP("SECURITY") = A 1 to 40 character string o HLP("CONTPTR") = Continuation pointer, a 1 to 180 character string o HLP("NAMESPACE") = Free-text value, 4 character limit, stored that is to be stored in the NAMESPACE field (#16) in the HL Message Text file (#772.) o HLP("SUBSCRIBER") = Free-text, multi-piece value, used to control the routing-related fields in the MSH segment. See patch HL1.693 documentation for full details.

DIRECT

The
DIRECT^HLMA(HLEID,HLARYTYP,HLFORMAT,HLRSLT,HLMTIEN,HLP) entry point is used to
generate a HL7 message.  It returns a unique message ID if a message was
successfully generated.  Unlike the GENERATE^HLMA API, the DIRECT^HLMA API
opens the connection directly for message delivery.  (GENERATE^HLMA delivers
messages via queued background job.) Applications that use the DIRECT API must
provide the guaranteed delivery if needed.

Call INIT^HLFNC2 before making this call, to set up HL7 environment variables
needed to build your message and needed by DIRECT^HLMA.

The DIRECT^HLMA call has the same input parameters as GENERATE^HLMA. Like
GENERATE^HLMA, it expects segments for the message to be already loaded in the
HLA("HLS") local array or the^TMP("HLS") global array. For more information on
the expected format of HLA("HLS") or^TMP("HLS"), please see the GENERATE^HLMA
call.

To select the subscriber to transmit to, this call first checks the contents
of the HLL("LINKS")array; it will use first record it finds. If that array is
empty, it uses the first subscriber protocol it finds in the Subscribers
multiple of the event driver protocol.

Upon return, DIRECT^HLMA does not invoke the event driver protocol's
GENERATE/PROCESS ACK ROUTINE to processes the acknowledgment. When control is
returned to the calling routine, the environment is left in the same condition
as if you were in the "processing routine environment" when receiving an
acknowledgment; the variables HLNEXT,HLNODE, and HLQUIT are defined so that
you can process the response. Note that DIRECT^HLMA supports:

o All acknowledgment modes (including deferred acknowledgments
o Batch message transmission The timeout for the synchronous
transmission is determined by the settings of the TCP used.

Example:

D DIRECT^HLMA("EVENT DRIVER PROTOCOL","GB",1,.MYRESULT)
I +$P(MYRESULT,U,2) D ERR Q  ; message was not transmitted
I HLMTIEN D PROCESS ; response was returned from target system

VARIABLES	TYPE	VARIABLES DESCRIPTION
HLEID	Input	The name or IEN of the event driver protocol in the Protocol File (#101).
HLARYTYP	Input	Array type. One of the following codes: LM = local array containing a single message LB = local array containing a batch of messages GM = global array containing a single message GB = global array containing a batch of messages
HLFORMAT	Input	Format of array, 1 for pre-formatted in HL7 format, otherwise 0
HLRESLT	Both	The variable that will be returned to the calling application with either a error message or a unique message ID. If the call is successful (message sent), the Result parameter is returned with piece 1 equal to the message ID of the message created. If the call failed (message was not sent), the Result parameter is returned with the following three pieces of data: message ID(0 if none assigned)^error code^error description If the call failed, +$P(RESULT,U,2) returns True.
HLMTIEN	Input	Optional IEN of entry in Message Text file where the message being generated is to be stored. This parameter is only passed for a batch type message.
HLP	Input	The HLP parameter is passed-by-reference. The HLP subscripts that are processed by DIRECT^HLMA are identical to the GENERATE^HLMA HLP subscripts. These subscripts are listed below. o HLP("PRIORITY") = I for immediate or D for deferred o HLP("SECURITY") = A 1 to 40 character string o HLP("CONTPTR") = Continuation pointer, a 1 to 180 character string o HLP("NAMESPACE") = Free-text value, 4 character limit, stored that is to be stored in the NAMESPACE field (#16) in the HL Message Text file (#772.) o HLP("SUBSCRIBER") = Free-text, multi-piece value, used to control the routing-related fields in the MSH segment. See patch HL1.693 documentation for full details.