NAME

CMDHL7Sender - Read a file containing one or more HL7 v2.x

Delimited messages, send them to a HL7 MLLP Listener and
receive HL7 Acknowledgements

SYNOPSIS
java -jar CMDHL7Sender_v0.7 [OPTION]...

DESCRIPTION
Read a file containing one or more HL7 v2.x Delimited messages,
connect to a specified HL7 MLLP Listener, send each message to
the listener and receive an acknowledgement.

-h HOST, --host=HOST
TCP Host to which to connect

-p PORT, --port=PORT
TCP Port to which to connect

-f FILE, --file=FILE
File system path to the file which contains HL7 v2.x
Delimited messages to be sent

-n NUMBER, --number=NUMBER
[Optional] maximum number of messages from a multi-
message file, which to send to the remote listener

-d DELIMITERS, --delimiters=DELIMITERS
[Optional] delimiter string separating HL7 messages in
the multi-message file - defaults to the string \r\r\n

-t TIMEOUTMIILIS, --timeout=TIMEOUTMIILIS
[Optional] number of milliseconds to wait for HL7
acknowledgement before concluding that it will not come
and emitting an error message

-w WAITMILLIS, --wait=WAITMILLIS
[Optional] number of milliseconds to wait between
sending successive messages from a multi-message file.
This switch can be used to throttle the sender. If not
specified the sender sends as fast as it can.

-c CONTROLIDPREFIX, --controlIdPrefix=CONTROLIDPREFIX
[Optional] string to prefix a generated Message Control
Id (MSH-10) which will consist of this string followed
by the underscore, followed by the sequence number of
the message read from the multi-message file. This will
replace the MSH-10 in the message read from the file.
If absent, the MSH-10 from the message read from the
file will be retained as is.

-a SENDINGAPPLICATION, --sendingApplication=SENDINGAPPLICATION
[Optional] string to use as MSH-3-1, Sending
Application.
If absent, the MSH-3-1 from the message read from the
file will be retained as is.

-b SENDINGFACILITY, --sendingFacility=SENDINGFACILITY

1
 [Optional] string to use as MSH-4-1, Sending Facility.
If absent, the MSH-4-1 from the message read from the
file will be retained as is.

-x RECEIVINGAPPLICATION, --
receivingApplication=RECEIVINGAPPLICATION
[Optional] string to use as MSH-5-1, Receiving
Application.
If absent, the MSH-5-1 from the message read from the
file will be retained as is.

-y RECEIVINGFACILITY, --receivingFacility=RECEIVINGFACILITY
[Optional] string to use as MSH-6-1, Receiving
Facility.
If absent, the MSH-6-1 from the message read from the
file will be retained as is.

-r REPEATCOUNT, --repeatCount=REPEATCOUNT
[Optional] How many times to repeat the process of
sending the NUMBER of messages specififed by -n

-z, --performanceMeasurement
[Optional] Whether to enable performance measurement
instrumentation. Replaces MSH-7 with
System.currentTimeMillis. Resets -w to 0.

-i, --ignoreACKs
[Optional] Whether to force MSH-15 and MSH-16 to NE to
tell the remote to not send ACKs and to force
implementation to not wait for ACKs.

-q, --quiet
[Optional] Don't emit performance statistics at end of
run.

The sender supports HL7 v2.1 through 2.6, including 2.3.1 and
2.5.1, as implemented in HAPI 1.0.1 libraries.

The sender sends messages from a single, possibly multi-record,

file and exists as soon as it receives the (last)
acknowledgment. In a multi-record file records are expected to
be separated by a character, or a sequence of characters, which
do not naturally occur in HL7 v2.x delimited messages. By
default the sequence of \r\r\n is used. Optionally a number of
messages to send can be specified. If the file has fewer
messages, or this option is not specified, all messages in the
file will be sent. If the file has more messages only the
specified number will be sent.

The sender will optionally wait for acknowledgements for a

specified number of milliseconds. If this option is not
provided the default HAPI 1.0.1 timeout is used.

The sender will optionally wait a specified number of

milliseconds between sending successive messages from a multi-
message file. This is a throttling mechanism intended to slow
down the sender. If not specified, the sender will send
messages as fast as it can, bearing in mind that it does so
sequentially, sending each message and witting for the
acknowledgement before sending the next one, unless told to --
ignoreACKs, in which case it will force MSH-15 and MSH-16 to NE
and will not wait for ACKS.

2
 The sender can optionally generate MSH-10, Message Control Id,
for each outgoing message, overriding MSH-10 form the message
in the file. The generated message control id consists of the
specified prefix and the message number form the file - for
example HOSA_0000001, where HOSA is the specified prefix,
0000001 is the number of the message in the file (first
message).

The sender can optionally override the MSH-3-1 and MSH-4-1,

sender identification in the messages read from the file. This
is intended to allow reuse of messages for different message
streams.

The sender can optionally override the MSH-5-1 and MSH-6-1,

receiver identification in the messages read from the file.
This is intended to allow reuse of messages for different
message streams.

The sender can optionally repeat the process of sending a batch

of messages a specified number of times. This enabled the
sender to send more messages than are available in a message
file, generating additonal load. --controlIdPrefix should be
set to cause generation of usinque MSH-10s on all messages.

The sender can optionally ignore ACKs from the partner.

The sender can be configred to suppres display of performance

measurements and message processing statistics at the end of a
run.

CMDHL7Proxy INFO-level messages. The underlying code uses

org.apache.commons.logging mechanism. The logging level can be
managed through the logging.proeprties JRE configuraiton file,
typically in <JDK_Dir>\jre\lib\logging.properties. Once can
override this with "-
Djava.util.logging.config.file=logging.properties" on the
command line, for example:

C:\jdk1.6.0_20\bin\java -
Djava.util.logging.config.file=logging.properties -jar
CMDHL7...

There are a number of properties files provided in teh

distribution - logging_debug.properties,
logging_fine.properties (these two are equivalent),
logging_info.properties, logging_warning.properties and
logging.proeprties, which is equivalent to
logging_info.properties. debug and fine variants result in no
logging being emitted to the console. info emits some logging
information to the console. fine and debug emit a lot of
informaiton to the conole - most of it of minimal usefulnes.
info is probably the most useful logging level for viewing
message exchange. warning if the most useful for running the
code in "production" mode.

EXAMPLES
java -jar CMDHL7Sender_v0.7.jar -h localhost -p 22100 -f c:\hl7
\adt\sources\ADT_A03_output_5099.hl7 -d \r\r\n -n 10 -t 50000 -
w 1000 -c HOSA -a SystemA -b HosA -x SystemX -y HosX

Connect to localhost on port 22100

Use messages from file c:\hl7\adt\sources\ADT_A03

3
_output_5099.hl7
Messages are delimited by \r\r\n (-d \r\r\n)
Send 10 messages (-n 10)
Wait up to 50 seconds for the ACK (-t 50000)
Wait 1 second between each successive message (-w 1000)
Generate MSH-10 with the prefix of HOSA
Substitute SystemA HosA for MSH-3-1 and MSH-4-1
(sending application and sending facility)
Substitute SystemX HosX for MSH-5-1 and MSH-6-1
(receiving application and receiving facility)

Example output emitted when a message is sent:

29/12/2010 8:54:44 AM au.id.czapski.hl7.CMDHL7Sender

main
INFO: Host: localhost
29/12/2010 8:54:44 AM au.id.czapski.hl7.CMDHL7Sender
main
INFO: Port: 22100
29/12/2010 8:54:44 AM au.id.czapski.hl7.CMDHL7Sender
main
INFO: File Path: c:\hl7\adt\sources\ADT_A03_output_
5099.hl7
29/12/2010 8:54:44 AM au.id.czapski.hl7.CMDHL7Sender
main
INFO: wait Millis: 1000
29/12/2010 8:54:44 AM au.id.czapski.hl7.CMDHL7Sender
main
INFO: Delimiter Set: \r\r\n
29/12/2010 8:54:44 AM au.id.czapski.hl7.CMDHL7Sender
main
INFO: Number of messages to send : 10
29/12/2010 8:54:44 AM au.id.czapski.hl7.CMDHL7Sender
main
INFO: Sending Message: MSH|^~\&|SystemA|HosA|PI|MDM|
2008091012529||ADT^A03|000000_CTLID_2008091012529|P|
2.3.1|
||AL|NE
EVN|A03|2008091012529|||JavaCAPS6^^^^^^^USERS
PID|1||A000010^^^HosA^MR^HosA||Kessel^Abigail||
19460101123045|M|||7 South 3rd Circle^^Downham
Market^England -
Norfolk^30828^UK||||||||A20080908014345
PV1|1
|I||I|||GOO^Goodlace^Andrew^^^^^^^^^^MAIN|||EMR||||||||
|V20080908014345^^^^VISIT|||||||||||||||||DISH DIS
P|disch loc|||||||20080908014345|2008091012529
29/12/2010 8:54:44 AM ca.uhn.log.HapiLogImpl info
INFO: Instantiating msg of class
ca.uhn.hl7v2.model.v231.message.ADT_A03
29/12/2010 8:54:45 AM ca.uhn.log.HapiLogImpl info
INFO: Initiator sending message: MSH|^~
\&|SystemA|HosA|SystemX|HosX|2008091012529||ADT^A03
|HOSA_1_129358408501
PID|1||A000010^^^HosA^MR^HosA||Kessel^Abigail||
19460101123045|M|||7 South 3rd Circle^^Downham
Market^England -
PV1|1
|I||I|||GOO^Goodlace^Andrew^^^^^^^^^^MAIN|||EMR||||||||
|V20080908014345^^^^VISIT|||||||||||||||||DISH DIS
P|disch loc|||||||20080908014345|2008091012529
29/12/2010 8:54:45 AM ca.uhn.log.HapiLogImpl info
PID|1||A000010^^^HosA^MR^HosA||Kessel^Abigail||
19460101123045|M|||7 South 3rd Circle^^Downham

4
 Market^England -
PV1|1
|I||I|||GOO^Goodlace^Andrew^^^^^^^^^^MAIN|||EMR||||||||
|V20080908014345^^^^VISIT|||||||||||||||||DISH DIS
P|disch loc|||||||20080908014345|2008091012529
29/12/2010 8:54:45 AM ca.uhn.log.HapiLogImpl info
MSA|AA|HOSA_1_1293584085019ssage: MSH|^~
\&|SystemX|HosX|SystemA|HosA|20101229085445.05+0800
||ACK|3|P|2.3.1
29/12/2010 8:54:45 AM ca.uhn.log.HapiLogImpl info
MSA|AA|HOSA_1_1293584085019|SystemA|HosA|
20101229085445.05+0800||ACK|3|P|2.3.1
29/12/2010 8:54:45 AM ca.uhn.log.HapiLogImpl info
INFO: Instantiating msg of class
ca.uhn.hl7v2.model.v231.message.ACK
29/12/2010 8:54:45 AM au.id.czapski.hl7.CMDHL7Sender
main
INFO: Received response:
MSH|^~\&|SystemX|HosX|SystemA|HosA|20101229085445.05+
0800||ACK|3|P|2.3.1
MSA|AA|HOSA_1_1293584085019

...

INFO: Received response:

MSH|^~\&|SystemX|HosX|SystemA|HosA|20101229085454.769+
0800||ACK|12|P|2.3.1
MSA|AA|HOSA_10_1293584094738

29/12/2010 8:54:54 AM ca.uhn.log.HapiLogImpl info

INFO: SocketException on read() attempt. Socket
appears to have been closed: socket closed
29/12/2010 8:54:54 AM ca.uhn.log.HapiLogImpl info
INFO: Closing connection (no more messages available).

C:\jdk1.6.0_20\bin\java -
Djava.util.logging.config.file=logging_with_debug.properties -
jar CMDHL7Sender_v0.7.jar -d \r\r\n -f c:\hl7\adt\sources
\ADT_A01_output_50000.hl7 -h localhost -p 22100 -t 60000 -a
SNDS -b APPS -x GWYR -y APGR -c A -n 1 -r 1

C:\jdk1.6.0_20\bin\java -
Djava.util.logging.config.file=logging.properties -jar
CMDHL7Sender_v0.7.jar -d \r\r\n -f c:\hl7\adt\sources\ADT_A01
_output_50000.hl7 -h localhost -p 22100 -t 60000 -a SNDS -b
APPS -x GWYR -y APGR -c A -n 1 -r 1

AUTHOR
Michael Czapski.
michael . w . czapski at gmail . com

KNOWN ISSUES
If the CMDHL7Sender does not like the ACK it will go into a
tailspin, out of which the only way out is to kill the process
(Control C in the console window will do that). It will not
like the ack if the ack MSA-2 (Message Control Id) is not
identical to the MSH-10 of the message it is acknowledging, for
example.

5
 The code does not validate supposed HL7 v2.x delimited messages
for correctness. For example a message with invalid TS
(timestamp) data will be happily processed. I deliberately
disabled HAPI's validation to allow this.

If a file containing arbitrary non-HL7 v2.x delimited data is

provided results are undefined - I never tried this but
confidently expect the code to break in horrible ways.

I never tested this code on non-Windows platforms. Being pure

Java I expect it to work on non-Windows platforms all the same.

I never tested this code with JDK other then JDK 1.6.0_20.
Since most of the good stuff comes from the HAPI 1.0.1 I expect
this code to work on any version of Java which HAPI 1.0.1
supports (last time I looked it was JDK 1.4 and up, though
one's experience may vary).

REPORTING BUGS
This is a rough developer tool - I am unlikely to maintain it
or have time to fix bugs - besides, most of the good stuff
comes from the HAPI distribution and I don't look after bugs in
that library (if any - I assume that there are none)

COPYRIGHT
March, 2011

By all means - copy away (just my code - observe what rules

authors of the underlying software felt fit to impose) - but
don't expect me to assume responsibility for the use of the
code or to come knocking on your door for money if you make a
mint using it :-)

This software uses HAPI project libraries (HAPI 1.0.1)

(http://hl7api.sourceforge.net/). License for this code is
available at http://hl7api.sourceforge.net/license.html. I
understand I can use the code for any purpose I see fit.

SEE ALSO
CMDHL7Proxy, CMDHL7Listener

HAPI 1.0.1 - http://hl7api.sourceforge.net/