| INIT |
API call INIT^HLFNC2(EID,.HL,INT), returns an array
of values in the variable specified by parameter HL. If no error occurs, the
array of values is returned. Otherwise, the single value HL is returned equal
to the following : error code^error messages.
|
| VARIABLES |
TYPE |
VARIABLES DESCRIPTION |
EID |
Input |
(required) Name or IEN of the event driver or
subscriber protocol in the Protocol file (#101) for which the initialization
variables are to be returned.
|
HL |
Both |
(required) Pass by reference. The variable in which
the array of values
will be returned or an error message.
|
INT |
Input |
1 indicates that only array values for internal DHCP
to DHCP message exchange should be initialized.
|
|
MSH |
API call MSH^HLFNC2(.HL,MID,.RESULT,SECURITY), builds
an HL7 Message Header (MSH) segment. The MSH segment is returned in variable
RESULT.
|
| VARIABLES |
TYPE |
VARIABLES DESCRIPTION |
HL |
Input |
(required) Pass by reference. The array of values
returned by the call to INIT^HLFNC2.
|
MID |
Input |
(required) The Message Control ID to be included in
the MSH segment. The Batch Control ID for the batch is returned by the call
to CREATE^HLTF. The application concatenates a sequential number to the batch
ID to create the MID.
|
RESULT |
Output |
(required) Pass by reference. The variable that will
be returned to the calling application that contains the MSH segment. If the
MSH segment is longer than 245 characters there will be a RESULT(1). If the
required variables, HL or MID are missing, RESULT will be null.
|
SECURITY |
Input |
An optional input parameter which includes the
security to be included in field #8 of the MSH segment.
|
|
RSPINIT |
API call RSPINIT^HLFNC2(HL("EIDS"),.MYNSPCHL),
returns an array of values in the variable specified by parameter MYNSPCHL.
If no error occurs, the array of values is returned. Otherwise, the single
value MYNSPCHL is returned equal to the following : error code^error messages.
1. Response message(s) not constructed properly when the HL7 field separator
and encoding characters are different between sending system and receiving
system.
This issue is a result of the Processing Routine utilizing the environmental
variables HL("FS") and HL("ECH") for both parsing the inbound HL7 message and
constructing the outbound response message. After the Processing Routine has
constructed the body of the response message, it calls GENACK^HLMA1 to queue
up the response message. In turn, VistA HL7 constructs the message header
based on the application associated with the subscriber protocol. Thus, the
message header would have a different set of delimiters than the body of the
HL7 message.
This patch does not immediately correct this problem. However, it does
provide a new API that can be used to create environmental variables to assist
the Processing Routine in constructing the response message with the proper
delimiters. This problem will only disappear when all VistA HL7 applications
have migrated to using this new API to assist each in constructing the
response message.
New API: RSPINIT^HLFNC2
RSPINIT(EIDS,HL);Initialize Variables in HL array for Building a Response
Message
;
;This is a subroutine call with parameter passing that returns an
;array of values in the variable specified by the parameter HL. If no
;error occurs, the array of values is returned. Otherwise, the single
;value HL is returned equal to the following: error code^error
message
;
;Required Input Parameters
; EIDS = Name or IEN of the subscriber protocol in
; Protocol file for which the initialization variables are
; to be returned
; HL = The variable in which the array of values will be returned
; This parameter must be passed by reference
;
Usage: D RSPINIT^HLFNC2(HL("EIDS"),.MYHLARRY)
The Processing Routine should call this RSPINIT^HLFNC2 API to create the
environmental variables needed to assist in constructing the response message.
This API should be used especially when there is a possibility of the field
separator and Encoding Characters being different between the sending
application and the receiving application. The second parameter to this API
should be an application namespaced variable passed by reference. This second
parameter should NOT have HL namespace. However, the first parameter should
be the name or IEN of the subscriber protocol. VistA HL7 provides this
information to the Processing Routine through the variable HL("EIDS").
Therefore, HL("EIDS") should be used as the first parameter passed by value.
As before, the Processing Routine should use the environmental variables
HL("FS") and HL("ECH") in parsing the inbound HL7 message. However, the
Processing Routine should use its own namespaced array as the second parameter
of the call to RSPINIT^HLFNC2. For instance, if the second parameter was
MYHLARRY, then the Processing Routine should use MYHLARRY("RFS") and
MYHLARRY("RECH") as the variables containing the delimiters to assist in
constructing the response message.
This RSPINIT^HLFNC2 API may be called by the Processing Routine any time after
the VistA HL7 has called the Processing Routine to process the inbound message
and just before constructing the response message and calling GENACK^HLMA1.
Below is an example of what may be returned in the second parameter:
Description:
============================
MYHLARRY("RAN")=XWB RECEIVER receiving application name
MYHLARRY("RECH")=~|\& response encoding characters
MYHLARRY("RETN")=R08 response event type name
MYHLARRY("RFS")=^ response field separator
MYHLARRY("RMTN")=TBR response message type
Before referencing the return array with the individual subscripts (as shown
above) for the purpose of building the response message, the processing
routine should first check the top level root (i.e.: MYHLARRY) for a possible
error. If an error should occur, RSPINIT^HLFNC2 will return the error code and
text description in the top level root. The format of this of this top level
root when an error occurs will look like the following:
MYHLARRY=Error_Code#^Error_Text
The following is a list of potential errors returned:
o Missing EIDS Input Parameter
o Invalid Subscriber Protocol
o Susbscriber Applicaton Missing in Protocol File
The above list is provided only as an example and the actual error code and
error text description are subject to change. Therefore, the processing
routine should merely check to see if an error was returned. For example,
I $G(MYHLARRY) D ALERT ... Q
D BLDRSPNs
D GENACK^HLMA1(...
Note, the processing routine should check for an error to determine whether it
should proceed with building the response message and subsequently call
GENACK^HLMA1. If an error was returned by RSPINIT^HLFNC2, the processing
routine should not proceed. However, if the processing routine already parsed
and processed the inbound message, it should be aware that the sending
application may continue to resend the same message repeatedly and as such act
accordingly.
|
| VARIABLES |
TYPE |
VARIABLES DESCRIPTION |
EIDS |
Input |
(required) Name or IEN of the subscriber protocol in
the Protocol file (#101) for which the initialization variables are to be
returned. This is the first parameter. The receiving application processing
the inbound message should use HL("EIDS") as this first parameter to
RSPINIT^HLFNC2 API as this variable is created for the application by the HL7
background job. This parameter should be used as a call by value.
|
HL |
Output |
(required) Pass by reference. The variable in which
the array of values will be returned or an error message. The application
should use its own namespaced HL array name.
|
|
