HLO SUBSCRIPTION REGISTRY APIS ICR (4725)

Name

Value

NUMBER

4725

IA #

4725

DATE CREATED

2005/08/19

CUSTODIAL PACKAGE

HEALTH LEVEL SEVEN

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

HLOASUB

NAME

HLO SUBSCRIPTION REGISTRY APIS

GENERAL DESCRIPTION

These APIs allow applications to create and manage
entries in the HLO Subscription Registry.  Each entry is basically a list of
recipients that can be used and reused to address HL7 messages.  Its similar
to a mailing list. See also IA# 4726.

STATUS

Active

DURATION

Till Otherwise Agreed

HLOASUB

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

$$CREATE(OWNER,DESCRIPTION,.ERROR)

This API is used to create a new entry in the HLO
Subscription Registry.

VARIABLES	TYPE	VARIABLES DESCRIPTION
$$CREATE	Output	Function call returns the new IEN in the HLO SUBSCRIPTION REGISTRY file (#779.4) if successful, 0 if error.
OWNER	Input	The name of the owning application. It should be pre-fixed with the owning application's namespace.
DESCRIPTION	Input	Optional. A short description of the subscription registry entry.
ERROR	Output	The function also returns an error message if it fails.

$$ADD(IEN,.WHO,.ERROR)

Add a new recipient to an existing subscription list.

VARIABLES	TYPE	VARIABLES DESCRIPTION
$$ADD	Output	The function returns the subien of the recipient from the RECIPIENTS multiple, 0 on failure.
IEN	Input	The IEN of the entry in the HLO SUBSCRIPTION REGISTRY file (#779.4).
WHO	Input	An array containing the information for a single new recipient to be added to the list. These subscripts are allowed: ("RECEIVING APPLICATION") - String, 60 char max, required. One of the following four parameters must be provided 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	On failure, one of these messages will be returned: "SUBSCRIPITON REGISTRY ENTRY NOT FOUND" "RECEIVING FACILTY LOGICAL LINK NOT FOUND" "RECEIVING APPLICATION NOT FOUND" "INTERFACE ENGINE LOGICAL LINK PROVIDED BUT NOT FOUND" "FAILED TO ACTIVATE SUBSCRIBER"

$$END(IEN,.WHO)

to terminate a recipient from the subscriber list.
The recipient isn't deleted, but the DATE/TIME TERMINATED field is entered
with the current date/time.

VARIABLES

TYPE

VARIABLES DESCRIPTION

$$END

Output

The function returns 1 on success, 0 on failure.

IEN

Input

The IEN of the HLO SUBSCRIPTION REGISTRY file
(#779.4) entry.

WHO

Input

If WHO("SUBIEN") is defined, then it should be the
IEN of the sub-record to be terminated.  Otherwise, set the set the parameter
as per $$ADD^HLOASUB

$$ONLIST(IEN,LINKIEN,APPNAME,FAC1,FAC2,FAC3)

This function is used to check whether or not a
potential recipient is already on a particular subscription list.

VARIABLES	TYPE	VARIABLES DESCRIPTION
$$ONLIST	Output	Function call returns the IEN of the recipient from the RECIPIENTS multiple, 0 on failure.
IEN	Input	The IEN of the HLO SUBSCRIPTION REGISTRY file (#779.4) entry.
LINKIEN	Input	IEN of the logical link.
APPNAME	Input	The name of the receiving application.
FAC1	Input	Component 1 of the receiving facility.
FAC2	Input	Component 2 of the Receiving Facility.
FAC3	Input	Component 3 of the Receiving Facility.

$$NEXT(IEN,.RECIP)

This API is used to loop through a subscription list.
It ignores recipients that have been terminated from the list.

VARIABLES

TYPE

VARIABLES DESCRIPTION

$$NEXT

Output

Function call returns the IEN of the recipient from
the RECIPIENTS multiple, 0 on failure.

IEN

Input

The IEN of the HLO SUBSCRIPTION REGISTRY file
(#779.4) entry.

RECIP

Both

Input: If NULL, it gets the first recipient on the
list, else it uses the value of RECIP("SUBIEN") to find the next recipient.

Output: RECIP - Required. Returns the next recipient on the list. These
subscripts are returned:

("LINK IEN") ("LINK NAME") ("RECEIVING APPLICATION") ("RECEIVING FACILITY",1)
- Component 1 ("RECEIVING FACILITY",2)  - Component 2 ("RECEIVING FACILITY",3)
- Component 3 ("SUBIEN") - The IEN in the multiple, used to find the next on
the list.