General Functionality

This section explains the Adapter’s general functions and features. It includes the following topics:

• Non-blocking I/O

• HL7 Sequence Numbering Protocol

• Failed Message Handling

• Recourse Actions

Non-blocking I/O

The non-blocking I/O feature prevents the Adapter from locking up when attempting to read or write data blocks, allowing the Adapter to continue its operation in case of any communication errors. If the read attempt fails for a configurable number of times, the Adapter exits or resets its connection to the external system, depending on its configuration. In the event of a failed write, the Adapter can resume its write operation to pick up where it previously left off until the entire message is successfully sent.

Without this feature, the Adapter might lock up when a read or write failure occurs and be unresponsive to all external messages, including requests from the user or the Enterprise Monitor (for status).

HL7 Sequence Numbering Protocol

The Adapter can be configured to use HL7 sequence numbering. The negotiation and incrementation of this number is automatically performed by the Adapter. For more details on HL7 sequence numbering, refer to Appendix C (Lower Layer Protocols) of the HL7 Standard for the HL7 version you are using.

When the Adapter is configured for HL7 sequence numbering, the sequence number file opens when the Adapter starts up. If the sequence number file does not exist, one is created and populated with a zero sequence number. The sequence number file is updated on the inbound Adapter when the Adapter generates the HL7 ACK (this process is transparent to the user), and when the outbound Adapter receives the HL7 ACK from the external system.

If you want to change the sequence number at runtime, you need to suspend the Adapter, edit and save the sequence number file, and reactivate the Adapter. To force the Adapter to resynchronize its sequence number with the external system, you need to suspend the Adapter, edit the file so it contains a “-1”, and then reactivate the Adapter.

The minimum HL7 sequence number is 1. The maximum HL7 sequence number is 2 billion. A sequence number of “0“ is used to start a session. If the sequence numbers between the Adapter and the external cannot be reconciled during start or when exchanging messages, the Adapter shuts down and wait for human intervention as dictated by the HL7 Standard.

Failed Message Handling

The Adapter can be configured to send failed or skipped messages (destined for the external system) to a JMS-based error queue. Messages that fail validation are also written to the error queue. Note that the inbound mode of the Adapter will not write messages that fail the MLLP and HLLP validation. These are automatically NAKed and not passed to the Collaboration, but are logged to the Adapter’s log file.

The failed or skipped message is written to the JMS queue and the error type and message are written as the JMS properties:

• Error: the actual error message or NAK

• Error Type: the type of error, such as HL7_NAK_error or HL7_Validation_error.

Skipped messages are those which are continuously NAKed by the external system and thus are skipped if the Adapter is configured accordingly. If the Adapter is configured for any other recourse action other than skip, the message remains in the queue.

Recourse Actions

The TCP/IP HL7 Adapter recourse actions include Reset, Resend, Skip Message, and Exit.

• On Reset, the Adapter drops its connection and then attempts to reconnect.

• On Resend, the sequence number file and journal file are opened again (provided the newly loaded configuration parameters are set for sequence numbering and journaling).

• On Skip Message, the Adapter remains connected, but writes the message to an error queue.

• On Exit, the Adapter closes its journal file and sequence number file (provided these were configured for use). The Adapter terminates its connection with the external system and shuts down. This allows you to modify these files and resolve any errors. Once the corrections are made, the Adapter can be reactivated from the Enterprise Manager.

Stopping the Collaboration with a Fatal Alert

When the Exit recourse action is triggered it logs the error that caused the action. It also shuts down the Collaboration, which in turn causes the HL7 message to roll back, and then sends an alert to the Enterprise Manager.

The Exit Recourse Action calls the fatal alerter in the Collaboration:

alerter.fatal(’’error message’’,’’HL7’’);

The argument error message is the user-configured alert message. The argument HL7 is the source component (this must be “HL7”).

The alerter.fatal("error msg", "HL7") method is only applicable to the packaged TCP/IP HL7 Collaborations.

The Exit recourse action should be applied to any error condition that requires human intervention to correct an error. Once the error condition is resolved, the Collaboration can be restarted from the Enterprise Manager.