Sending test messages with the HL7 Simulator
Contents
- Using the Simulator GUI
- Using the Simulator Command Line Application
- HL7 Simulator Input file format
Using the Simulator GUI [top]
The following screenshot explains the various settings available for the HL7 Simulator GUI application:
The Simulator reads each message from the log file, and attempts to send it to the host using the port number specified on the form. The port number is specified in the LLP Listener Connection Settings Port settings (though you can use any llp listener host + port, it does not even need to be Iguana).
When it receives an ACKnowledgment message from the receiver, if the Keep sending messages when ACK received check box has been selected, it will send the next message in the input file.
If it does not receive an ACK message in the required Time out period, the simulator will attempt to resend the last message, repeating the action up to the number of retry times specified in the Retry Count box.
The time delay box specifies how much time to wait after getting the ACK message from the receiver before sending the next one.
Note: The simulator can also be used to deal with odd systems which do not follow the standard HL7 practice of ACKnowledging on the same port as the sender. These systems expect to be able to send their ACKnowledgement messages back to the sender on another socket that the sender is listening to.
By selecting Receive ACKnowledgement Messages via Server Socket, the Simulator can be configured to expect the ACK messages to come back via the port number specified in the box below. This is quite unusual and should not be necessary for most users.
Tip: The HL7 Simulator GUI does not run on the Mac, but you can easily send messages from a Windows machine, simply enter the network address or network name of the target machine in the Host field. For example, when running the Simulator in a Parallels VM, just use the IP address for the Mac (from advanced network setting in system preferences).
Using the Simulator Command Line Application [top]
The command-line version of the HL7 Simulator is named hl7simulator. Where it is located depends on the operating system that you are using:
- In the Windows environment, hl7simulator is located in the directory in which Chameleon is installed (for example, C:\Program Files\iNTERFACEWARE\Chameleon).
- As of version 4.1 of Iguana, hl7simulator is provided for the Linux, Unix and Mac OS X environments. It is located in the directory in which Iguana is installed.
When you start hl7simulator from the command line, you must provide three parameters:
- The host IP address or name to which messages are to be sent;
- The port number to use;
- The file containing the HL7 messages to be sent.
The syntax for hl7simulator is:
hl7simulator --host <host> --port <portnum> --source_file <filename> [<additional optional parameters>]
The following table provides a complete list of the parameters that can be provided to hl7simulator. These parameters can appear in any order.
| Parameter | Description |
|---|---|
| –host <host> | The host to which messages are to be sent. <host> can be an IP address or a host name. This parameter must be provided. |
| –port <portnum> | <portnum> is the port number to use when sending messages. This parameter must be provided. |
| –source_file <filename> | The file containing the HL7 messages to be sent. <filename> specifies the path and file name of the file. If no path is specified, the file is assumed to be in the current directory. This parameter must be provided. |
| –multiple_connect | Disconnect from the host after sending a message, and reconnect when sending the next message. |
| –reconnect_attempts <num> | If not able to connect to the host, try to reconnect <num> times before giving up. If <num> is 0, or if this parameter is not specified, keep trying to reconnect forever. |
| –retry_count <num> | If a message is not sent successfully, try to resend the message <num> times before giving up. If this parameter is not specified, a retry count of 10 is used. |
| –run_once | Only send the messages once; stop when the end of the message file is reached. If this parameter is not specified, hl7simulator sends the messages in the message file repeatedly until terminated. |
| –time_delay <time> | The amount of time to wait, specified in milliseconds, before sending the next message. If this parameter is not specified, a delay of 100 milliseconds is used. |
| –timeout <time> | The amount of time to wait for an ACKnowledgment message from the host before resending a message. <time> is specified in milliseconds; if <time> is 0, hl7simulator will not wait for an ACK. If this parameter is not specified, a timeout of 1000 milliseconds is used. |
Here is an example of the output from hl7simulator:
D:\sample>hl7simulator --port 1234 --host localhost --source_file messages.txt --run_once hl7simulator 1.0.4 -------------HL7 Simulator Started at 17/2/2009 13:31:15------------- Connected to host. Message #82 Time Taken : 9 seconds TPS : 9.111112
As messages are sent, a running count of the message total is displayed in your command prompt window. When hl7simulator stops running or is terminated, it displays the total elapsed time and the number of messages sent per second (shown here as TPS, or transactions per second).
Note: To terminate hl7simulator, type Ctrl-C (press the Ctrl and C keys simultaneously).
If you try to run hl7simulator when there is no Iguana channel listening on the port you specify, you will see messages similar to the following:
D:\sample>hl7simulator --port 1234 --host localhost --source_file message.txt --reconnect_attempts 3 hl7simulator 1.0.4 -------------HL7 Simulator Started at 17/2/2009 13:39:31------------- Error: No connection could be made because the target machine actively refused it. Retrying connect in 1000 ms Error: No connection could be made because the target machine actively refused it. Retrying connect in 1000 ms Error: No connection could be made because the target machine actively refused it. Retrying connect in 1000 ms Connection failed: Connection attempts failed Error: Unable to send a message. Time Taken : 6 seconds TPS : 0.166667
In this case, the –reconnect_attempts parameter specifies how often hl7simulator will try to send the message before giving up.
HL7 Simulator Input file format [top]
The HL7 Simulator takes a text file with HL7 messages in it as its input. Messages from this text file are replayed as a client TCP/IP program using the LLP protocol.
The Simulator is very specific about the format of this message input file. This format requires each message to be formatted on a single line with 0x0D characters separating the segments, and a line feed (0x0A == 10 == \n) and carriage return character (0x0D == 13 == \r) sequence at the end. In an editor like notepad when word wrap is off, it appears like each message is one line in the file.
Note: The easiest way to get files to use the Simulator is to use the HL7 Listener.
The input file cannot be shared by two running instances of the Simulator or Listener. If multiple instances of these applications must be run, each must have its own input/output file.
Note: From version 3.211 and above of Chameleon the simulator is able to handle lab report messages with embedded \n (0x0A) characters in textual data. This is a valid use of the HL7 standard. However, always ensure the messages in your log file do not have embedded \0x0D characters in the textual data since this is illegal. The Simulator looks for \r\n at the end of each message in the log file.