NAME

CMDHL7Listener - Receive and acknowledge HL7 v2.x Delimited

messages over MLLP

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

DESCRIPTION
Listen, on the specified TCP Port, for incoming HL7 v2.x
Delimited messages, generating and sending generic HL7 v2.x
acknowledgements for each. Optionally, with the -s option,
store incoming messages as files in the specified file system
directory, with file names derived from message content.

-p PORT, --port=PORT
TCP Port on which to listen for connections

-s DIRECTORY, --store=DIRECTORY
[Optional] File system directory in which to store
received messages as files with the file name pattern
derived from Message Control Id [MSH-10], Message Type
[MSH-9-1], Trigger Event [MSH-9-2] and current time in
milliseconds. An example would be 000000_CTLID_
2008091012529_ADT_A03_1293578341691.hl7 where 000000
_CTLID_2008091012529 is the content of the MSH-10, ADT
is the content of the MSH-9-1, A03 is the content of
the MSH-9-2 and 1293578341691 is the number of
milliseconds since the epoch as given by Java's
System.currentTimeMillis().

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

-b SENDINGFACILITY, --sendingFacility=SENDINGFACILITY
[Optional] string to use as MSH-4-1, Sending Facility.
If absent, the MSH-6-1 from the message will be used.

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

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

-g, --gluttonStoreAsXML
[Optional] Store received HL7 v2 messages in XML
format. If -s/--storePath is not provided this switch
has no effect.

-c CONTROLIDPREFIX, --controlIdPrefix=CONTROLIDPREFIX
[Optional] string to prefix a generated Message Control
Id (MSH-10) which will consist of this string followed

1
 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.

-z, --performanceMeasurement
[Optional] Whether to enable performance measurement
instrucmentation and statistics collection.
If -c/--controlIdPrefix is not provided this switch has
no effect.
It is assumed that the value provided by -c to the
listener is the same as that provided to the sender.

-f NUMBER, --fromSequece=NUMBER
[Optional] Specifies the MSH-10 Sequence Number part
from which to start accumulating run statistics. If -z
is not specified this switch has no effect. If -c is
not specified this switch has no effect.

-t NUMBER, --toSequece=NUMBER
[Optional] Specifies the MSH-10 Sequence Number part at
which to stop collecting statistics and to emit them to
stdout. If -c is not specified this switch has no
effect.

The listener supports HL7 v2.1 through 2.6, including 2.3.1 and
2.5.1, as implemented in HAPI 1.0.1 libraries. It generates
acknowledgements to match the version of the message and swaps
MSH-3, MSH-4 and MSH-5, MSH-6 from the original message for the
Acknowledgement.

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 CMDHL7Listener_v0.7.jar --port=22100 --store=.\files

Listen on port 22100

Store messages as files in the subdirectory files of

2
the current working directory

Example output emitted when a message is processed:

29/12/2010 6:58:53 AM au.id.czapski.hl7.CMDHL7Listener

main
INFO: Port: 22100
29/12/2010 6:58:53 AM au.id.czapski.hl7.CMDHL7Listener
main
INFO: Store in: .\files
29/12/2010 6:58:53 AM ca.uhn.log.HapiLogImpl info
INFO: au.id.czapski.hl7.SimpleACKApplication registered
to handle *^* messages
29/12/2010 6:58:53 AM ca.uhn.log.HapiLogImpl info
INFO: SimpleServer running on port 22100
29/12/2010 7:19:01 AM ca.uhn.log.HapiLogImpl info
INFO: Accepted connection from 127.0.0.1
29/12/2010 7:19:01 AM ca.uhn.log.HapiLogImpl info
INFO: Responder got message: MSH|^~
\&|SystemA|HosA|PI|MDM|2008091012529||ADT^A03|000000
_CTLID_2008091012529|P|
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 7:19:01 AM ca.uhn.log.HapiLogImpl info
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 7:19:01 AM ca.uhn.log.HapiLogImpl info
INFO: Instantiating msg of class
ca.uhn.hl7v2.model.v231.message.ADT_A03
29/12/2010 7:19:01 AM
au.id.czapski.hl7.SimpleACKApplication processMessage
INFO: Received 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 7:19:01 AM
au.id.czapski.hl7.SimpleACKApplication processMessage
INFO: Sending Applicaiton: SystemA
29/12/2010 7:19:01 AM
au.id.czapski.hl7.SimpleACKApplication processMessage
INFO: FileName: .\files\000000_CTLID_2008091012529
_ADT_A03_1293578341691.hl7
29/12/2010 7:19:01 AM ca.uhn.log.HapiLogImpl info
INFO: hapi.home is set to C:\tools\CMDHL7\.
29/12/2010 7:19:01 AM

3
 au.id.czapski.hl7.SimpleACKApplication processMessage
INFO: Sending ACK:
MSH|^~\&|PI|MDM|SystemA|HosA|20101229071901.753+0800
||ACK|1|P|2.3.1
MSA|AA|000000_CTLID_2008091012529

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

KNOWN ISSUES
There is no way to tell the listener to stop. I run this from a
command window and use Control C to stop it.

If the target directory for --store cannot be written an ugly

message - "Can't write file - ignoring directive" - is emitted
to the standard output, the message is not written to the file
and the listener continues anyway.

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.

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 the 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
4
CMDHL7Proxy, CMDHL7Sender

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