Print Page as PDF
HLO BUILD MESSAGE APIS ICR (4716)

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
ID HLOAPI
COMPONENT/ENTRY POINT
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.

CREATOR MOORE,CHARLES J
DBA Comments
12/17/12-MM:  Jim Moore is adding a new component to ICR
#4716.  MOVESEG~HLOAPI is existing code in the routine but was never included
in the ICR. No patch associated with this change to the ICR.  12/26/12-MM:
ICR reactivated after Jim's updates to add MOVESEG~HLOAPI to the ICR.
DATE ACTIVATED 2012/12/26
MAIL MESSAGE 41001358
DATE/TIME EDITED
DATE/TIME EDITED ACTION AT THE REQUEST OF WITH CONCURRENCE OF
2012/12/17 12:21 DEACTIVATED FOR EDITS MOORE,JIM MOORE,JIM
2012/12/26 12:06 APPROVED MOORE,JIM MOORE,JIM
Generated from JAN 24, 2019@ IA Listing Descriptions