HLO SEND MESSAGE APIS ICR (4717)

Name

Value

NUMBER

4717

IA #

4717

DATE CREATED

2005/08/19

CUSTODIAL PACKAGE

HEALTH LEVEL SEVEN

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

HLOAPI1

NAME

HLO SEND MESSAGE APIS

GENERAL DESCRIPTION

These APIs provide the ability to address a message
that has already been built and put it on an out-going queue for transmission.

STATUS

Active

DURATION

Till Otherwise Agreed

HLOAPI1

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

$$SENDONE(.HLMSTATE,.PARMS,.WHOTO,.ERROR)

Sends the message to a single recipient.  The
recipient is identified in the message header by the Receiving Facility and
the Receiving Application.  The message may optionally be routed through an
interface engine.

VARIABLES	TYPE	VARIABLES DESCRIPTION
$$SENDONE	Output	Function call returns the IEN of the message in file 778 on success, 0 on failure.
HLMSTATE	Both	Used by the HL7 package to track the progress of the message.
PARMS	Input	( "APP ACK RESPONSE")=<tag^routine> to call in response to app ack (i.e., not received). (Optional. This parameter is ignored if the ACK TO parameter is present.) ( "APP ACK TYPE") = <AL,NE> (Optional, defaults to NE). ( "ACCEPT ACK RESPONSE")=<tag^routine> to call in response to a commit ack(optional). ( "ACCEPT ACK TYPE") = <AL,NE> (Optional, defaults to AL). ("FAILURE RESPONSE") - <tag>^<routine> (Optional) The sending application routine to execute when the transmission of the message fails, i.e., the message can not be sent or no commit ack is received. ("QUEUE") - Optional. An application can name its own private queue - just a string under 20 characters, it should be namespaced. ("SECURITY")=Security information to include in the header segment, SEQ 8 (Optional). ("SENDING APPLICATION")=name of sending application (required, 60 max-length).
WHOTO	Input	Required. Specifies a single recipient. ("RECEIVING APPLICATION") - String, 60 char max, required. One of the following four parameters is required to identify the Receiving Facility: ("FACILITY LINK IEN") - IEN of the logical link. ("FACILITY LINK NAME") - Name of the logical link. ("INSTITUTION IEN") - Pointer to the INSTITUTION file. ("STATION NUMBER") - Station # with suffix. One of the following two parameters MAY be provided, optionally, to identify the interface engine to route the message through: ("IE LINK IEN") - Pointer to a logical link for the interface engine. ("IE LINK NAME") - Name of the logical link for the interface engine.
ERROR	Output	Returns an message on error.

$$SENDMANY(.HLMSTATE,.PARMS,.WHOTO)

Sends the message that has already been built to a
list of recipients.

VARIABLES	TYPE	VARIABLES DESCRIPTION
$$SENDMANY	Output	Returns 1 on success, 0 on failure.
HLMSTATE	Both	This array is used to track the progress of the message.
PARMS	Input	( "APP ACK RESPONSE")=<tag^routine> to call in response to app ack (i.e., not received). (Optional. This parameter is ignored if the ACK TO parameter is present.) ( "APP ACK TYPE") = <AL,NE> (Optional, defaults to NE). ( "ACCEPT ACK RESPONSE")=<tag^routine> to call in response to a commit ack (optional). ( "ACCEPT ACK TYPE") = <AL,NE> (Optional, defaults to AL). ("FAILURE RESPONSE") - <tag>^<routine> (Optional) The sending application routine to execute when the transmission of the message fails, i.e., the message can not be sent or no commit ack is received. ("QUEUE") - Optional. An application can name its own private queue - just a string under 20 characters, it should be namespaced. ("SECURITY")=Security information to include in the header segment, SEQ 8 (Optional). ("SENDING APPLICATION")=name of sending application (required, 60 max-length).
WHOTO	Both	For Input: Specifies a list of recipients. Each recipient should be listed individually in array WHOTO(i), where i=a recipient. For each recipient the same subscripts may be defined as in the $$SENDONE API. For example: WHOTO(1,"LINK NAME")="VAALB" WHOTO(1,"RECEIVING APPLICATION")="MPI" WHOTO(2,"STATION NUMBER")=500 WHOTO(2,"RECEIVING APPLICATION")="MPI" For Output: Returns the status of each message to be sent in the format: (<i>,"QUEUED") - 1 if queued to be sent, 0 otherwise. (<i>,"IEN") - IEN, file 778. (<i>,"ERROR") - Error message if an error was encountered (status=0),not defined otherwise.

$$SENDSUB(.HLMSTATE,.PARMS,.MESSAGES)

Send Messages to Subscription Registry Subscribers

VARIABLES	TYPE	VARIABLES DESCRIPTION
$$SENDSUB	Output	Function call returns 1 if a message is queued to be sent to each intended recipient, 0 otherwise.
HLMSTATE	Both	Used by HLO internally to track the progress of the message.
PARMS	Input	Required. Same as $$SENDMANY^HLOAPI1, with one additional subscript: ( "SUBSCRIPTION IEN") -The IEN of an entry in the HLO SUBSCRIPTION REGISTRY file (#779.4), defining the intended recipients of this message
MESSAGES	Output	Returns the status of each message to be sent in this format, where the sub-IEN is the IEN of the recipient in the RECIPIENTS sub-file of the HLO SUBSCRIPTION REGISTRY file (#779.4). (<subien>,"QUEUED") - 1 if queued to be sent, 0 otherwise. (<subien>,"IEN") - IEN, HLO MESSAGES file (#778). (<subien>,"ERROR") - Error message if an error was encountered (status=0),;not defined otherwise.