HLO BUILD MESSAGE APIS ICR (4716)

Name

Value

NUMBER

4716

IA #

4716

DATE CREATED

2005/08/19

CUSTODIAL PACKAGE

HEALTH LEVEL SEVEN

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

HLOAPI

NAME

HLO BUILD MESSAGE APIS

GENERAL DESCRIPTION

These APIs are used to build HLO messages.

STATUS

Active

DURATION

Till Otherwise Agreed

HLOAPI

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

$$NEWMSG(.PARMS,.HLMSTATE,.ERROR)

This API is to be used by applications that need to
send an HL7 message via HLO.  It starts the message building process.

VARIABLES	TYPE	VARIABLES DESCRIPTION
PARMS	Input	PARMS ("COUNTRY") - A three-character country code (optional). ("CONTINUATION POINTER") - Indicates a fragmented message. ("EVENT") - A three-character event type (required). ("FIELD SEPARATOR") - Field separator (optional, defaults to "\|"). ("ENCODING CHARACTERS") - Four HL7 encoding characters (optional, defaults to "(^~\&"). ("MESSAGE STRUCTURE") - MSH 9, component 3 - a code from the standard HL7table ((optional). ("MESSAGE TYPE")- A three-character message type (required). ("PROCESSING MODE") - MSH 11, component 2 - A one character code (optional). ("VERSION") - The HL7 Version ID, for example, "2.4" (optional, defaults to 2.4).
HLMSTATE	Output	Used by the HL7 package to track the progress of the message.
ERROR	Output	Optional. Returns an error message on failure.
$$NEWMSG	Output	Returns 1 on success, 0 on failure.

$$NEWBATCH(.PARMS,.HLMSTATE,.ERROR)

This API is to be used by applications that need to
send a batch of HL7 message via HLO.  It starts the batch building process.

VARIABLES	TYPE	VARIABLES DESCRIPTION
PARMS	Input	("COUNTRY") - A three-character country code (optional). ("FIELD SEPARATOR") - Field separator (optional, defaults to " \|"). ("ENCODING CHARACTERS") - Four HL7 encoding characters (optional, defaults to "^~\&"). ("VERSION") - HL7 Version ID, for example, "2.4" (optional, defaults to 2.4).
HLMSTATE	Output	Used by the HL7 package to track the progress of the message.
ERROR	Output	Returns an error message on failure.
$$NEWBATCH	Output	Function returns 1 on success, 0 on failure.

$$ADDMSG(.HLMSTATE,.PARMS,.ERROR)

Used by applications to add a message to a batch that
is in the process of being built.

VARIABLES	TYPE	VARIABLES DESCRIPTION
$$ADDMSG	Output	The function returns 1 on success, 0 on failure.
HLMSTATE	Both	An array used by the HL7 package to track the progress of the message as it is being built.
PARMS	Input	("EVENT") - A three-character event type (required). ("MESSAGE TYPE") - A three-character message type (required).
ERROR	Output	Optional - returns an error message on failure.

SET(.SEG,VALUE,FIELD,COMP,SUBCOMP,REP)

Used to set a value into a segment that is in the
process of being built.

VARIABLES	TYPE	VARIABLES DESCRIPTION
SEG	Both	The array where the segment is being built.
VALUE	Input	The individual value to be set into the segment.
FIELD	Input	The sequence # of the field (optional, defaults to 0) Note: FIELD=0 is used to denote the segment type.
COMP	Input	The # of the component (optional, defaults to 1).
SUBCOMP	Input	The # of the subcomponent (optional, defaults to 1).
REP	Input	The occurrence# (optional, defaults to 1) For a non-repeating field, the occurrence # need not be provided, because it would be 1.

$$ADDSEG(.HLMSTATE,.SEG,.ERROR)

Used to add a segment that has just been built to a
message that is still in the process of being built.

VARIABLES	TYPE	VARIABLES DESCRIPTION
$$ADDSEG	Output	Function returns 1 on success, 0 on failure.
HLMSTATE	Both	Used by the HL7 package to track the progress of the message as it is being built.
SEG	Input	Required. Contains the segment built by calls to SET prior to calling $$ADDSEG. Note#1: The message control segments, including the MSH and BHS segments, are added automatically. Note#2: The 0th field must be a 3 character segment type. Note#3: SEG is killed upon successfully adding the segment.
ERROR	Output	Returns an error message on failure.

MOVEMSG(.HLMSTATE,.ARY)

If a message was built using any other method than
the HLO APIs and resides in an array, it will be moved into HLO. This API
allows segment builders that were created prior to HLO to be used within HLO.

VARIABLES

TYPE

VARIABLES DESCRIPTION

HLMSTATE

Both

Created by calling $$NEWMSG^HLOAPI or
$$NEWBATCH^HLOAPI. It tracks the progress of the message as its is being
built.

ARY

Input

The name of the local or global variable where the
message was built.  It is accessed via indirection to move the message into
HLO.

$$MOVESEG(.HLMSTATE,.SEG,.ERROR)

Adds a segment built in the 'traditional' way as an
array of lines into the HLO message under construction.

VARIABLES

TYPE

VARIABLES DESCRIPTION

HLMSTATE

Both

This variable contains the message that is being
built.

SEG

Input

This variable contains the segment that is to be
appended to the message.

ERROR

Output

If the segment is not appended to the message, an
error message is returned.

DATE ACTIVATED

2012/12/26