Looking for the latest version? Download socketReader 1.2.4 (60.5 kB)
Home
Name Modified Size Downloads / Week Status
Totals: 42 Items   233.2 MB 66
CHANGELOG.txt 2014-02-01 14.2 kB 11 weekly downloads
README.txt 2014-02-01 23.9 kB 22 weekly downloads
socketReader_windows_1.2.4.tar.xz 2014-02-01 10.0 MB 1515 weekly downloads
socketReader_linux_1.2.4.tar.xz 2014-02-01 9.3 MB 11 weekly downloads
socketReader_source_1.2.4.tar.xz 2014-02-01 60.5 kB 11 weekly downloads
socketReader_hashes_1.2.4.sha256 2014-02-01 297 Bytes 0
socketReader_windows_1.2.3.zip 2013-09-08 17.4 MB 11 weekly downloads
socketReader_linux_1.2.3.tar.bz2 2013-09-08 10.3 MB 11 weekly downloads
socketReader_source_1.2.3.tar.bz2 2013-09-08 63.2 kB 11 weekly downloads
socketReader_hashes_1.2.3.sha256 2013-09-08 296 Bytes 11 weekly downloads
socketReader_windows_1.2.2.zip 2013-08-14 17.4 MB 11 weekly downloads
socketReader_hashes_1.2.2.sha256 2013-08-14 296 Bytes 11 weekly downloads
socketReader_source_1.2.2.tar.bz2 2013-08-14 63.0 kB 33 weekly downloads
socketReader_linux_1.2.2.tar.bz2 2013-08-14 10.3 MB 11 weekly downloads
socketReader_windows_1.2.1.zip 2013-08-07 17.6 MB 11 weekly downloads
socketReader_linux_1.2.1.tar.bz2 2013-08-07 10.3 MB 22 weekly downloads
socketReader_hashes_1.2.1.sha256 2013-08-07 296 Bytes 22 weekly downloads
socketReader_source_1.2.1.tar.bz2 2013-08-07 57.7 kB 22 weekly downloads
example.cfg 2013-08-07 8.3 kB 11 weekly downloads
socketReader_windows_1.2.0.zip 2013-06-29 17.7 MB 11 weekly downloads
socketReader_source_1.2.0.tar.bz2 2013-06-29 56.8 kB 11 weekly downloads
socketReader_linux_1.2.0.tar.bz2 2013-06-29 10.2 MB 22 weekly downloads
socketReader_hashes_1.2.0.sha256 2013-06-29 296 Bytes 22 weekly downloads
socketReader_linux_1.1.0.tar.bz2 2013-01-04 9.9 MB 22 weekly downloads
socketReader_hashes_1.1.0.sha256 2013-01-04 296 Bytes 11 weekly downloads
socketReader_source_1.1.0.tar.bz2 2013-01-04 54.5 kB 11 weekly downloads
socketReader_windows_1.1.0.zip 2013-01-04 17.2 MB 11 weekly downloads
socketReader_hashes_1.0.4.sha256 2012-07-17 296 Bytes 11 weekly downloads
socketReader_windows_1.0.4.zip 2012-07-17 17.1 MB 11 weekly downloads
socketReader_linux_1.0.4.tar.bz2 2012-07-17 11.8 MB 22 weekly downloads
socketReader_source_1.0.4.tar.bz2 2012-07-17 53.7 kB 11 weekly downloads
socketReader_hashes_1.0.3.sha256 2012-07-07 296 Bytes 11 weekly downloads
socketReader_windows_1.0.3.zip 2012-07-07 8.1 MB 11 weekly downloads
socketReader_linux_1.0.3.tar.bz2 2012-07-07 4.2 MB 11 weekly downloads
socketReader_source_1.0.3.tar.bz2 2012-07-07 67.0 kB 11 weekly downloads
socketReader_windows_1.0.2.zip 2011-07-26 8.2 MB 11 weekly downloads
socketReader_source_1.0.2.tar.bz2 2011-07-26 44.1 kB 11 weekly downloads
socketReader_linux_1.0.2.tar.bz2 2011-07-26 4.7 MB 11 weekly downloads
socketReader_windows_1.0.1.zip 2011-07-20 8.2 MB 11 weekly downloads
socketReader_linux_1.0.0.tar.bz2 2011-07-12 4.7 MB 11 weekly downloads
socketReader_windows_1.0.0.zip 2011-07-12 8.2 MB 22 weekly downloads
socketReader_source_1.0.0.tar.bz2 2011-07-12 44.0 kB 11 weekly downloads
SocketReader for HL7 and MLLP -- Version 1.2.4 http://sourceforge.net/projects/hl7socketreader/ License: GPLv3.0 -- see gpl-3.0.txt which is included in this archive. Copyright: Sebastian Weigmann (s_weigmann[at]web.de), All Rights Reserved. This project uses python-hl7 by John Paulett. More info is available at: http://johnpaulett.com/2009/01/10/parsing-hl7-with-python/ You can help to improve software quality by submitting bug reports at: http://sourceforge.net/tracker/?group_id=316605&atid=1331725 Please feel free to submit any other feedback to this site: http://sourceforge.net/tracker/?group_id=316605&atid=2080710 Special Thanks: Richard Erlichman and everybody else involved at AOD Software for their great contribution and patience. 0. Contents: 1. About this software 2. Features 3. Usage 4. Config File Options 5. Deamonizing 6. DISCLAIMER 1. About this software: Many health care software products have excellent features aiding doctors to document patient examinations. Yet, many of them miss efficient means to communicate their results. Many of these programs use protocols based on file transfer for that purpose. SocketReader may be placed in front of the medical software product, serving as a "translator" which transforms socket streams into files containing one message each and vice versa. SocketReader is implemented in Python 2.7 to make development easy while ensuring multi-platform compatibility. It is multi-threaded and supports socket server and socket client modes. When operating it as socket server, it is capable of maintaining multiple client connections, accepting messages from each connection. Messages will be written out to places of your choice on the local file system. When transmitting HL7 2.x messages, SocketReader will send HL7-ACKs to signal successful transmission. Pure ASCII text messages will be wrapped in MLLP and SocketReader will send MLLP-ACKs upon successful transmission. SocketReader is available for 32Bit and 64Bit OSes and was tested on Debian Linux, Ubuntu Linux, Windows XP and Windows 7. 2. Features: SocketReader is capable of sending/receiving messages via TCP/IP as well as reading/writing messages from/to files on the local hard disk using dedicated connectors for each task. SocketReader supports m:n routing between the supported connectors which effectively enables parallel multi-channel message transfer (see illustrations below). This is a single-channel scenario using one connector on the input and one on the output side: INPUT internal Queue OUTPUT socket-in Queue file-out >>-------------------------XXX----------------------------->> Multi-channel scenarios use input and output connectors. Incoming messages from each input connector will be duplicated and then sent to every output connector on the same queue. For any given queue, message streams on all output connectors are the same. Multiple queues may be used in the same SocketReader instance. See the three examples below: INPUT Connector internal Queue OUTPUT Connector file-in_1 Queue_1 file-out_1 >>-------------------------XXX----------------------------->> file-in_2 XXX socket-out_1 >>-------------------------XXX----------------------------->> socket-in_1 XXX >>-------------------------XXX socket-in_2 Queue_2 socket-out_2 >>-------------------------XXX----------------------------->> XXX file-out_2 XXX----------------------------->> file-in_3 Queue_3 socket-out_3 >>-------------------------XXX----------------------------->> You may choose from this set of currently supported connectors: Connector Type: Transmission technique: Direction: file local file system in file local file system out socket server MLLP-wrapped socket stream with MLLP-ACK in socket server MLLP-wrapped socket stream with MLLP-ACK out socket client MLLP-wrapped socket stream with MLLP-ACK in socket client MLLP-wrapped socket stream with MLLP-ACK out socket server MLLP-wrapped socket stream with HL7-ACK in socket server MLLP-wrapped socket stream with HL7-ACK out socket client MLLP-wrapped socket stream with HL7-ACK in socket client MLLP-wrapped socket stream with HL7-ACK out 3. Usage: socketReader uses a config file to read its configuration from and a Unix-like command line interface to provide the full path for it. Command line arguments in square brackets are optional. Synopsis: socketReader [-h | --help] [--version] [--configfile CONFIGFILE] and: socketReaderService install | (start | debug) [--configfile CONFIGFILE] | stop | remove NOTE: When using the socketReader binary, socketReader.py or socketReader.exe and leaving the -c/--configfile option blank, the config file will be expected to be named socketReader.cfg and located in the current working directory. NOTE: When starting socketReaderService the first time, you MUST provide the full path name of your config file by using the -c/--configfile option. Examples: --configfile /etc/socketReader.cfg -c "c:/Program Files/socketReader/socketReader.cfg" WARNING: The SocketReaderService binaries, the config and log files, the queue database files and the paths for incoming and outgoing messages-as-file must not be located on a network drive when running the service. All resources need to be available on locally attached drives. Other configurations are likely to cause undefined behavior, most probably data loss and denial of service conditions. The reason is that Windows service processes run within another context than processes started from within an open user session. Device mappings might therefore not be available to the services. --version Show program's version number and exit. -h or --help Show a help message and exit. 4. Config File Options: The socketReader config file layout is organized in sections. In the socketReader config file, you will need to define multiple sections along with their options. Each section name defines a unique connection. Connections are configured by the options stated within their section. Sections are stated in square brackets, for example: [connection-name]. NOTE: Please see the example.cfg config file for templates. 4.1. The [general] section: The [general] section has a special meaning. Options defined here apply globally. These options are allowed within the [general] section: logfile = FILE (defaults to the empty string) By using this option, you enable logging to FILE. FILE must contain an existing path and the log file name itself Example: logfile = "d:/logs/logfile.log" where d:/logs/ is an existing directory. The log file format is: time stamp - thread name - log level - log message loglvl = critical | error | warning (default) | prod | info | debug Here you may optionally define a log level. These log levels are available, sorted from high to low priority: critical, error, warning, prod, info, debug. For example, if you define info, all log levels but debug will be printed. If you want to see all messages with their contents in your log files, you need to define debug. The default log level warning will print errors and critical log entries only to allow for small log files. Log level prod adds to the warning level log entries indicating unsuccessful message transfer. Also, the full content of these messages will be printed. useconnections = CONNECTION There can be many connections defined in the config file. Here you state the ones you actually want to use. You need to give a comma separated list of connection names (section names without square brackets) here. Example: useconnections = socket-in_2, socket-out_2, file-out_2 4.2. Defining connections: All other sections differ in their supported options according to the connector type you define there. There is a subset of options common to all connections which allows to define the connector type and the queue a connection will use. These options are: transtech = file | socket Here you define which technology will be used for data transmission. At this time, socketReader supports file and socket connectors. Each of them needs to be further configured stating additional options. transdir = in | out Direction of data transfer. A connection may be an incoming (in) or an outgoing (out) connection. Bidirectional data transfer within a single connection is not yet supported. usehl7 = True | False (default) SocketReader always acknowledges the messages it receives via a socket connection. Your messages may be of any kind, for example base64 coded binary files. If your messages are non-hl7, you must not specify this option. socketReader will send MLLP acknowledgements. If your messages are hl7 and your communications server needs to see hl7 acknowledgements for each of its messages, then you must state this option. SocketReader will then answer using hl7 acknowledgements. The default behavior is to just send MLLP acknowledgements. Using this option on file type connections enables the use of the hl7prefix option. queuename = QUEUENAME This option states the name of the queue the connection will use. This binds connections to routes. At least one incoming and one outgoing connection needs to state the same queue name here in order to form a functional route. 4.2.1. Socket connector options: queuedb = PATHNAME Give a full path and filename here. The connection will store undelivered queue contents there when it is asked to shut down. You MUST use slashes "/" as separators within the path name, even if you use Windows! NOTE: This option applies to outgoing socket connections only. useack = True (default) | False Emit / expect acknowledgment messages or not. If set to True, HL7 / MLLP ack messages will be generated or expected. If set to False, no acks are sent or expected. createserversocket = True (default) | False Create a TCP/IP server socket which is the default behavior or create a TCP/IP client socket otherwise. Note that in the latter case you must also specify the ipaddr option! ipaddr = ADDR (defaults to 127.0.0.1) If you start a socket server, this option will bind your socket to the IP address or hostname you specified. If you start a socket client, it will try to connect to the remote IP provided by ipaddr. NOTE: the argument ADDR may be one of the following: - a fully qualified domain name. Example: commserver.yoursite.com - a host name your machine can resolve. Example: commserver - an IP address. Example: 192.168.3.154 port = PORT (defaults to 22222) When establishing a socket, you need to specify a port number for it to operate on (range: 1024..65535). Just replace PORT with an integer of the given range. If omitted, port 22222 will be used. sob = chr(ASCIICODE), eod = chr(ASCIICODE) and eob = chr(ASCIICODE) The MLLP protocol is used as an envelope to your message while it is being transferred via socket. These options default to the standard MLLP delimiter characters which are 0x0b for SOB, 0x1c for EOD and 0x0d for EOB. You may redefine these delimiters if you need to. You must at all costs avoid defining delimiters for SOB and EOB which may occur within your messages. Otherwise socketReader will not be able to tell your messages apart from each other. NOTE: To define non-printable characters, you need to use the Python chr() function. You may define sob = chr(0x0b) or sob = chr(11) which is equivalent to each other. You may also define strings as delimiters, for example: sob = "START-BLOCK", eod = "END-DATA", eob = "END-BLOCK". 4.2.2. File connector options: Incoming and outgoing file connections have very different configuration needs. These will be explained in the two paragraphs 4.2.2.1. and 4.2.2.2. The common options are explained below. messagedir = PATH State the full path to the place socketReader shall write to / read from. Windows users be aware that you do MUST use slashes ("/") instead of backslashes ("\") in your path names. Also, it is strongly recommended to enclose your path name in quotes. This option is always mandatory and does not default to anything useful. If it is omitted, socketReader will refuse to start. newline = True | False (default) Some subsystems may not digest messages read from files if the message is tailed by a newline character. Other subsystems do expect a tailing newline character. This option tells socketReader to add a newline at the end of a message when writing it to a file, respectively removing it if messages are read from files. If this option is not given, no newline character - the plain message only - will be written to file / will be expected at the end of a file. 4.2.2.1. Options for incoming file connections: filemask = FILEMASK Specify a file naming pattern to search for in the path provided by messagedir. You may use the same syntax as you would on a operating system's console. This option defaults to * (all files in the directory). NOTE: File name sorting does NOT use natural sorting! If you have a list of files "f_1.dat, f_2.dat, f_10.dat", they will be read in the following order: f_1.dat, f_10.dat, f_2.dat. This might lead to an out-of-order import of messages. To avoid this, you will need to ensure files are named in an unambiguous way. For example, this list of files would be imported in the order they are stated: "f_01.dat, f_02.dat, f_10.dat". NOTE: Files will be deleted (not moved) after they have been read! If you want them to be moved to another directory, you need to add a separate file output connection to the same queue. Examples: filemask = tokis_*_.hl7 filemask = *.dat cycletime = SECONDS Time interval for searches for new files. The default value is 120. maxfiles = MAXCOUNT When finding a set of files in messagedir, do at most read maxfiles files. This prevents socketReader from getting stuck when it is set on a directory containing very many files. You may specify any number between 1 and 1000. The default value is 50. 4.2.2.2. Options for outgoing file connections: hl7prefix = True | False (default) Each HL7 message carries its own type identifier within field MSH-9. You can use this identifier as part of a prefix for your output file names and thus for example easily distinguish observation results from patient data by filtering for file names containing "ORU" or "ADT". Additionally, the contents of MSH-3 to MSH-6 are used, so you can collect messages of the same type from multiple sources and for multiple target applications running on your machine without having them mixed together indistinguishable. The output files will look like: SRCSYSTEM_SRCFACILITY_DSTSYSTEM_DSTFACILITY_MSGTYPE_timestamp_iterator.suffix for example: ORBIS_UKD_OPUSL_UKD_ADT_20101102124510_00000.hl7 Apparently, this works for HL7 messages only, so the option usehl7 must be set to True, too. prefix = PRE Specify a static string to precede the dynamically generated part of the message file names. The options hl7prefix and prefix are mutually exclusive. The default prefix is the empty string (""). suffix = SUF Here you may specify suffixes for the message files written to your output directory. The default suffix is .dat. 4.3. Debug options: This sort of options exists to help integrate socketReader into your networks. Every connector type has its own valid set of debug options. All of them are given on a single line within the respective sections. For flexibility reasons, these options need to be given in a Python dictionary syntax: debug = {"option1":"value", "option2":"value", "option3":False, "option4":True} If not given, all debug options default to be empty and will have no effect on existing configurations. Please refer to the examples.cfg for a full summary of available options. 5. Deamonizing: For sure, the user would like to run this application as a Linux daemon / Windows service. This section will explain how to deamonize this application. 5.1. Daemon for Linux: Three goals are to achieve here: (1) Start the tool and keep it running while its spawning process dies. (2) Log any output. (3) Stop the process so it won't loose any data (messages not written to disk yet). 5.1.1. Starting a daemon: To start socketReader in daemon mode, type: nohup /path/to/socketReader --configfile /path/to/SR.cfg >> ./stdout.log & The first part of the command line (nohup) will ensure the application will keep running even if the user launching it logs off. The second part starts socketReader in your favorite mode. The third part (>> ./stdout.log) dumps all console output to the file stdout.log in the directory you were when you started socketReader. You may want to state another directory here (just replace the "." with your favorite path). The last part (the &) will send the whole command to the current shell process' background (which means you can start typing other commands right after pressing Enter). Now you have a running daemon instance of socketReader. 5.1.2. Stopping a daemon: To stop all deamonized socketReader processes at once, type: killall socketReader This will send a SIGTERM to all open instances of socketReader. The application will then write out all pending messages and then exit cleanly. To kill a single instance of socketReader, you need to know its process id (pid) and issue "kill pid". To forcibly shutdown all instances of socketReader, type: killall -9 socketReader NOTE: socketReader will be forced to exit immediately! You may loose messages socketReader has already accepted via socket but not yet delivered. To forcibly shutdown a single instance, type "kill -9 pid". You may want to wrap the whole procedure into init or upstart scripts. This task is beyond the scope of this document and left to you. 5.2. Service for Windows: The Windows service API imposes several extra constraints on an application, especially on one which is designed to be written once and run anywhere. I had to write some extra stuff resulting in a special Windows Service Release of socketReader. You will find a file "socketReaderService.exe" bundled with every Windows release which you must use to set up the socketReader service. 5.2.1. Setting up a Windows Service: First, you need to find out how you want to run socketReader, i.e. which options to configure in the config file. Use the standard "socketReader.exe" via Command Shell for that task. Once you have figured out your favorite settings, you are ready to install the service. Step 1: Place the "socketReaderService.exe" and all resources it needs on a locally attached drive, for example here: C:\Program Files\socketReader\socketReaderService.exe NOTE: Any files and paths which are meant to be accessed by a Windows service must NOT reside on a mapped drive (network drive)! Step 2: Open a Command Shell and dive into your socketReader directory. Step 3: Type the following to install the service: socketReaderService.exe install NOTE: You might want to install your service with special service arguments. You can get a list of available options by just typing: socketReaderService.exe NOTE: You can remove "socketReaderService.exe" from the list of Windows services by typing: socketReaderService.exe remove NOTE: You do not configure the socketReader parameters here! Not yet... :) Step 4: Test your newly created service by running it in debug mode with your config file as parameter. Let's assume your config file is located at C:\Program Files\SR\SR.cfg You need to type: socketReaderService.exe debug --configfile "C:\Program Files\SR\SR.cfg" NOTE: You will see the same console output as you are used to when running "socketReader.exe". Pressing Crtl+C will shut down the windows service. NOTE: The parameters you just used are now saved to the windows registry, so "socketReaderService.exe" will automatically use them from now on. In other words, issuing another "socketReaderService.exe debug" will use the arguments it now can fetch from the registry. If you need to point socketReader to another config file, just do Step 4 again. NOTE: Changing the socketReader configuration is as easy as editing the config file in use by socketReader and then restarting the service. Your new settings will be activated upon service restart. Step 5: Test the socketReader service in productive mode. Type: socketReaderService.exe start You will get a notification that the service has been started. Search the processes tab from your task manager for processes called "socketReaderService.exe". Now stop the service by typing: socketReaderService.exe stop All "socketReaderService.exe" processes should be gone now and a message issued to the console window that the service has been shut down. Congratulations! You successfully installed socketReader as a Windows service. NOTE: Stuff written to the Windows registry can be fund here: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\hl7socketreader_configfile 5.2.2. Starting the Service: You can now configure and start your service from the services.msc plugin or by issuing "sc start hl7socketreader_configfile" or "net start hl7socketreader_configfile" from the console. After you started the service, you should persistently see one or more instances of "socketReaderService.exe" in your task manager's processes tab. 5.2.3. Stopping the Service: Issue a "net stop hl7socketreader_configfile" or "sc stop hl7socketreader_configfile" or stop it from services.msc. You should see no instances of "socketReaderService.exe" anymore. 5.2.4. Removing the Service: From the command line window, issue the following command: path\to\sc.exe delete hl7socketreader_configfile or dive into the socketReader directory and type: socketReaderService.exe remove This will delete the registry entries associated with this service but leave your binary files on your hard drive unattended. You can still launch "socketReader.exe" manually from the command line or reinstall the service at any time. 6. DISCLAIMER: THE SOFTWARE IS DELIVERED FREE OF CHARGE AND 'AS IS' WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE SOFTWARE IS ASSUMED BY YOU / THE USER. THE AUTHORS SHALL NOT BE LIABLE FOR LOSS OF DATA, LOSS OF PRODUCTION, LOSS OF PROFIT, LOSS OF USE, LOSS OF HEALTH OR LIFE, LOSS OF CONTRACTS OR FOR ANY OTHER CONSEQUENTIAL, ECONOMIC OR INDIRECT LOSS WHATSOEVER IN RESPECT OF DELIVERY, USE OR DISPOSITION OF THE SOFTWARE.
Source: README.txt, updated 2014-02-01