Section 1

Section 1. Listener Session Information

In Section 1 of the main window you tell your Ad Hoc Listener how you want to receive your HL7 messages. To receive HL7 messages you need to select a valid TCP/IP Port Number.

In Section 1 you will also define the HL7 Acknowledgement behavior which tells your listener when and how to format and return the HL7 ACK (Acknowledgement). A HL7 ACK is itself a very short HL7 message which is returned to the sender (usually) to acknowledge the receipt of their message.

Example ACK Message

There are 3 "behaviors" you can select from:

1.Automatic. Your listener will return an ACK message UNLESS the HL7 message received explicitly says not to (field 15 and 16 of the MSH segment set to NE).

2.Always. Your listener will always return an ACK message.

3.Never. Your listener will never return an ACK message.

There are also 2 additional optional check boxes related to the HL7 Acknowledgement.

Include the Message Event (MSH 9.2) in the Acknowledgement. In a basic HL7 Acknowledgement message the message type (MSH 9.1) is always ACK with NO message event (MSH 9.2) (see the Example ACK Message above). HL7 standards do allow for you to also mirror the message event (MSH 9.2) from the original message in the ACK message. Check this box if you want to do this.

Mirror the Message Control ID (MSH 10.1) in the Acknowledgement. Since the ACK message is itself a stand-alone HL7 message it is created with a unique Message Control ID (MSH 10.1). Some clients may want you to "mirror" the message control ID used by the HL7 message received and use it as the message control ID in the ACK message. Check this box if you want to do this.

ACK Message Example 2

Section 2

Section 2. The Message Envelope and Text Encoding

Honestly you should never have to change the values in Section 2. By default they are set to the HL7 ANSI standard values and displayed in HEX format because they are typically non-printable characters and should only ever be changed by explicit agreement between you and your HL7 Trading Partner.

What is the TCP/IP Message Envelope? When exchanging HL7 messages over TCP/IP you have the HL7 message itself, which is just a stream of text. This stream of text is encapsulated in an envelope of control characters. Each message will start with the BOM (Beginning of Message) character(s) and will end with the EOM (End of Message) character(s). If these characters are incorrect the HL7 Listener will not be able to parse your HL7 messages from the stream. The SOM (Segment Delimiter) character is not technically part of the TCP/IP envelope BUT it is extremely important when exchanging HL7 messages and is the value that causes the most confusion and creates the most errors. If the values in these fields are invalid OR are not the ANSI standard values the Reset the HL7 Message Envelope to ANSI Defaults button will be enabled and you can click it to restore the ANSI values. If you do need to change these values just click the button next to the field you wish to change.

A word about the SOM (Segment Delimiter)

The ANSI standard HL7 segment delimiter is a Carriage Return (CR) which is ASCII character 13 or HEX Value 0D. NOTE that it is NOT a Carriage Return / Line Feed (CRLF) or just a line feed (LF). This means that while HL7 messages are always "text" HL7 data files are NOT plain text files.   A quick tip/trick. The standard Windows Notepad is not really a great text editor. If you can open a HL7 data file in Windows Notepad and you can see all of the HL7 segments neatly aligned along the left margin, then the data file is likely corrupt, or at least NOT an ANSI standard message. WHY? Because by default when Windows Notepad reads a "text" file it is expecting a CRLF at the end of each line, which ANSI standard HL7 messages don't have. The result is that you usually see your HL7 message displayed as just one long continuous line of text. Ideally you should use a good HL7 Viewer/Editor like the UltraPort HL7 Notepad, or if this is not an option then a good general Text editor (many are available for free like NotePad++).   Another very important tool to have. Anyone who works with HL7 on a regular basis should always have a HEX Editor/Viewer to allow you to look at HL7 messages in HEX. The UltraPort HL7 Notepad comes with a built-in Hex Editor.

What is the Preferred Text Encoding? Your selection here doesn't really matter UNLESS you are receiving HL7 messages which contain special characters from the extended ASCII character set (like • € ‚ ƒ … † ‡ ˆ ‰ ‹ Œ ‘ ’ “ ” • – — ˜ ™ › œ Ÿ ¼ ½ ¾ © ®).

In this section you only have 2 choices UTF-8 or ANSI (which is Windows 1252). With your Ad Hoc Listener HL7 messages arrive via a byte[] stream and have no specific text encoding. If everyone played by the rules it shouldn't matter because HL7 messages should be plain ASCII text (only containing values from the first 128 characters of any ASCII table). If they ARE plain ASCII text then it doesn't matter which Preferred Text Encoding you select because for plain ASCII text UTF-8 and ANSI are identical and interchangeable. It's only when text data contains EXTENDED ASCII characters (like the • etc.) that Preferred Text Encoding and Enforce Text Encoding come into play and then it can be very important.

An example of this can be:

If your trading partner is actually sending you HL7 messages which contain special characters and they are in an ANSI stream format the bullet character (•) would be represented by 1 byte (HEX 95), if the stream is UTF-8 the bullet character would be represented by 3 bytes (HEX E2, 80, A2). So the problem comes when a Listener actually has to display the message or write the HL7 message out to a file in the data folder. IF it writes an ANSI message out using UTF-8 encoding (or vice versa) this will cause these special characters to become "garbled" and unrecognizable. Another example might be if you are importing HL7 messages into a database. The database itself has it's own collation, so you might find that importing an ANSI file results in special characters being garbled in your database (or vice versa).

So you can choose the Preferred Text Encoding and your Listener will expect the incoming messages to adhere to that encoding. If you check Enforce Text Encoding your Listener will automatically detect as the messages come in whether they contain any special characters and if they do they will translate those characters into the proper values for your Preferred Text Encoding.

Enforce Text Encoding Example: Your HL7 message contains a bullet character (•) and in the inbound stream and it is ANSI (HEX 95), if your Preferred Text Encoding is UTF-8 we would automatically replace that with the UTF-8 values (HEX E2,80, A2).

Action Buttons

Making It Happen.

Click the Start Session button to open the Listener Session Window. If the Start Session button is disabled it is because you have not completed the form with enough information to deliver the messages.

You can click the Save Settings button to save all of the information you have entered so that it will be automatically set the next time you start the program.

Click Clear Settings to clear your saved settings and reset the form to the default values.

Finally, of course, click Exit to close the program.

Your Next Step: Receiving Messages

This Software Created With CORE HL7