ANNOUNCEMENT OF PROTOGEN/HL7 A PARSER/BUILDER GENERATOR FOR THE HL7 PROTOCOL. RELEASE 1.3 Gunther Schadow I uploaded the release 1.3 of my C++ implementation of HL7 and ASTM E31 to dumccss.mc.duke.edu:/incoming The package will finally be installed as: standards/HL7/implementations/ProtoGen/ProtoGen-1.3.tar.z You may as well want to check my WWW page at http://userpage.fu-berlin.de:/~gusw to find the software and other interesting things about ProtoGen and my HL7 project in general. WHAT IS PROTOGEN/HL7 ProtoGen/HL7 is essentially a parser/builder generator that extracts it's rules from the HL7 standard document. The interface to the parser/builder is C++. Thus, the result of the generator is a C++ class library for the HL7 protocol. With the library you can build HL7 client/server applications or batch processors very easily. With the generator you can easily extend and customize the HL7 standard in order to fit the needs and customs of the systems you want to interface. In order to have real communication over networks and serial lines, there are lower layer protocol implementations included in this package. Namely parts of the ANSI X3.28 communication standard is implemented. In addition the `Minimal Lower Layer Protocol' as defined in the HL7 v2.1 standard document in Appendix B is available. The `Hybrid Lower Level Protocol' can be added rather easily by extending the existing source code for the Minimal LLP. Finally I decided to define a new LLP for internal purpose which is meant for easy use with the TCP/IP transport service. ProtoGen/HL7 currently runs on FreeBSD 2.1.0 (4.4BSD) i486 and i586 machines at home, on a FreeBSD 2.1.0 i486 and i586 and HP-UX 9.05 HP-PA machine at the hospital. Ports to SunOS, Ultrix 4.3 and IBM RS6000/AIX3.2 have been made for previous versions of ProtoGen, but are not tested for the new one. Other ports may exist which I am not aware of. The system should be easily ported to any BSD-ish Unix OS. The code is not intended to run under MS-DOS and I can not waste time into a port to MS-DOS, however, I was told of a port to OS/2. If you want a port to Windows NT you should probably think about doing one yourself. As I do neither have nor use any Microsoft products I can only give you help for the ProtoGen code as you have the Gates' headache. When I ported the software that was originally written on my FreeBSD machine to HP-UX, I choosed not to bother with the compiler and tools that came with HP-UX. I rather installed the GNU C/C++ compiler and the GNU tools I was using on the HP-UX machine and went without much trouble. The same procedure is the best strategy for a first port to a new platform: install the GNU developer stuff first. I recommend to get and install the software listed in the next section before you try to install ProtoGen/HL7. All the software I use is freely available via FTP and can be installed with only little effort on most Unix platforms. CHANGES TO PREVIOUS VERSIONS 1.3 Major reorganization of the source tree in order to enhance modularity regarding both, variations, dialects and additions to HL7 as well as other EDI standards. As a first example on extending the ProtoGen approach to other EDI standards there is now an implementation of an ASTM E31 dialect. A new library `Socket' has been added. It will replace the old llp-driver mechanism and allows to interface to other LLPs, communication channels, devices and media through a single API. The address including all kinds of channel specification can be specified by the user at runtime. Channels implemented so far: DEVICES: STD standard input, output or standard error FILE a named file PIPE a pipe from or to a shell command TCP TCP/IP channels UNS UNIX stream (aka local) sockets TTY terminals and other serial devices PROTOCOLS: MLLP minimal lower layer protocol HLLP hybrid lower layer protocol (not completed yet) ILLP internal LLP X328 ANSI X3.28 (debugging not finished) New devices and protocols can be extended using a similar existing driver as a template. The user can specify address using a kind of a universal resource locator at runtime. For example: MLLP:TCP(host.domain:service) -- use MLLP over TCP/IP X328(2.2,B2):TTY(/dev/cua00) -- use ANSI X3.28 on RS232 FILE(path) -- use a file without LLP (implies one message per file) PIPE(shell command) -- pipe to a command using no LLP ILLP:UNS(path) -- use a UNIX stream socket There are still some gaps and bugs in the Socket library and no ProtoGen application currently uses it in practice. But this will be the way other LLPs and devices will be integrated in the future, including MIME conformant mail with PGP encryption. Version 2.3 of HL7 is not yet integrated. This is planned for the next release of ProtoGen/HL7 comming early 1997. However, if only some features of 2.3 are desired earlier, they can still be integrated by customization of the HL7 specification rules base ./hl7/standard/v2.2/hl7.pl Slowly but steadyly moving towards ANSI C++ a process that is not yet completed Bug fixes, of course Automatic HTML document generation is temporarly broken :-( 1.2 Bug fixes Support for Sun 4m SunOS-4.1.3C added Support for RS6000 AIX-3.2 added Config files revised and cleaned up CONF script added to easily link and unlink a configuration Added a little peace of documentation for the LLP driver (see doc/LLP-DRIVER and llp/README) 1.1c Added the missing config_... code 1.1: Improved modularization of modifications to standard HL7. Version 2.2 of HL7 incorporated. You can now choose to build either version, along with The variable members of the generated HL7 classes are now public. Thus you can use the coprehensive notation `X.Y.Z[n].V=M.N.O', rather than the unfriendly getXXX() and setXXX() access functions. In order to provide for correctness you must use the commit() member function after a writing transaction to an object is complete. The unit converter is a new feature. It will greatly faciliate the communication of observation results in OBX segments. The important features are: * You can prepend any ISO prefix to the unit (like ``km''). * You can enter any valid ISO term (like ``kg.m/s2''). * Even those units which are tricky to convert are supported like: mm (Hg) or cm (H2O) * Units with non-proportional conversions, like °F and °C or various units of level, like bel, dB (SPL, V, mV, µV, W, mW ...). * pH which is convertible to mol/l and vice versa (of course). The class Unit inherits from class Code and shows impressingly that a code can be more than a mere list of allowed values. Other ``active'' codes should be: ICD 9/10, SNOMED, etc... HTML documents will now be generated by protogen in order to document the current status of the HL7 library. You can point and click through the whole HL7 standard as it is implemented. The `examples' directory was renamed to `apps'. A LOINC code class is added. You have quick access to the whole LOINC database. LOINC is used for the acid-base-laboratory interface which is found in apps/radiometer. LOINC and units classes are built on top of the `odbm' C++ interface class to the GNU database manager (gdbm). You can use it for your `active' code classes too. See the file support/odbm.h for documentation. The ANYmsg class now allows to easyly build HL7 servers that use the ILLP over TCP/IP. ILLP/TCP functions added (`hl7/lib/supp/illp*'). ILLP now has a security mechanism used by the ANYmsg server. See the file `hl7hosts' for a glimpse of hpw it works. (It is still badly documented, though). The examples (and real work) applications in `apps' are now cleaned up and documented somehow. You can take the program `server.cc' an `*client.cc' as examples about writing HL7 server and client applications. A HL7 client has been added that adds an HL7 interface to a Radiometer ABL300 Acid-base-laboratory. (apps/radiometer). And again a really big bunch of bug fixes 1.0: A *lot* of bugs have been fixed. The build process has greatly improved. The M4 phase during building of the C++ source code has been completely replaced by better output directly from the protogen program. The library source, especially the include files are now very much more readable and more efficient by the use of inline functions. Any class which has parts has an operator[](int) by which you can access the parts by number. This is useful, if you need a dynamic access to the parts of the object. By this method, it will be possible to implement table (or graph) driven interface converters. I reduced the code size enormously by driving the parser with tables instead of pure recursive descend. Also, the constructor with parameters has completely vanished for generated classes, since it accounted for a lot of text segment size whereas it had only limited use. Examples/messages contained lots of errors, mostly illegal codes. A new target named `test' in examples/GNUmakefile, tests the parser/builder. New shell scripts have been added: `edmsg', a frontend to edit hl7 messages with your favorite editor. And `vimsg', a tool to show hl7 messages on the screen. Essentially these tools translate ASCII-CR to ASCII-LF. A sed script named `trncmsg' has been added which removes truncate.sed. `trncmsg' can be called just like an executable with one argument: $ trncmsg truncates extra delimiters, like `foo^^^|bar~|||' to `foo|bar'. Examples for interfacing Oracle DBMS and a proprietary HIS are provided. Real tty (serial line) device support has been added to the llp section. WHAT YOU NEED BEFORE YOU CAN START There are several programs that you need if you want to run ProtoGen/HL7. I am sorry for your inconvenience, but I did not have the time to remove the dependencies on the following particular program versions: * make, GNU version is *required* * GNU C/C++ compiler release 2.7.0 plus libg++ * SWI-Prolog, release 2.1.0 (patch for release 2.1.0 included) * m4, GNU version is safe but any other should do * sed, GNU version is safe problems reported with other brands * awk, GNU version is safe problems reported with other brands * The gdbm library, version 1.7.3 (C++ patch included) * The `socket++' library by Gnanasekaran Swaminathan GNU make is required if you want to get at least somewhere and so is GCC/G++ at the moment. I did not spend any time to care about other C++ compilers, and I made use of GCC/G++ extensions. The FTP site next to you has all the fine GNU programs available. GCC/G++ is ported to all of the common Unix machines, OS/2 and even MS-DOS (BTW: a staring point for a port to DOS). It is save to use the GNU versions of `sed' and `awk' as well, since there are slight differences between implementations of `sed' and `awk' that already caused me some trouble. SWI-Prolog is needed if you want to build or run the `protogen' program for it is a prolog program. The prolog code might be portable to other Prolog systems which follow the Edinburgh standard. Notably Quintus Prolog could do. However, I am not able to do this job, since I don't have any other Prolog system available. SWI-Prolog is a neat Prolog system and it is free. Please consult `archie' for a FTP site that has SWI-Prolog (it's home is swi.psy.uva.nl). You probably won't find the version 2.1.0 of SWI Prolog, which is required, anywhere else than on my WWW page. If you only want to use the HL7 class library, you can go with the ready made source code, that is included. However, this is of limited use if you need to adjust the HL7 standard to your local customs. ProtoGen/HL7 allows you to make changes to the standard and define Z-Segments quite easily. Without Prolog and thus without `protogen' you'll miss this feature. Don't experiment with SWI Prolog versions other than 2.1.0, especially you won't be happy with a newer version! **************************************************************** * PLEASE NOTE: You must apply the patch gen/pl/pl-2.1.0.diff * * to your SWI-Prolog sources if you use versions > 2.0! * **************************************************************** The gdbm-1.7.3 library is used through the odbm interface for the class Unit. It might well work with ndbm, but I didn't try to use it. If you refuse to use gdbm, you'll only have to modify support/odbm.h (mkdb can still be ignored). ***************************************************************** * PLEASE NOTE: The include file gdbm.h is not yet C++ clean, * * thus there is a little patch included in support/gdbm.diff * * that will fix this. You can apply it even to an already * * installed gdbm package, since it doesn't affect the * * library, just the include file. * ***************************************************************** If you want to use the client/server example programs that are included in this package, you will need the socket++ library by Gnanasekaran Swaminathan. It is an iostream extension library. As everything I used, this is freely available software. HOW TO BUILD EVERYTHING You need to edit the configuration files for your system. Currently there is FreeBSD-2.1.0 supported. Edit the files: config.mk site.mk HL7_config.h HL7_site.h to fit your platform. Note that the `configure' facility that was here for some times is now disabled. It was just a dirty hack anyway, and GNU autoconf should be used. I won't add any configuration facility before autoconf. HP-UX used to be supported as well, but I didn't have the time now to test it anew. Make everything by typing: $ make world 2>&1 |tee World.log and cross your fingers that the make process won't bail out due to errors. The whole process may well take an hour's time to finish, depending on your system's performance. During this time, the following steps are performed: (1) build the `compat' and `support' library (bootstrapping) (2) scan the HL7 v2.1 documents for the standard specification (4) build the `protogen' program (3) build C++ source code for the HL7 class library (4) compile the HL7 class library (5) compile the LLP daemon programs (6) compile the applications Item (6) might cause some Error messages to appear, because parts are dependant on special HL7 modifications. See gen/GNUmakefile `extended' on how these modifications have been made. If you don't want to rebuild the C++ library source use $ make all instead of "make world", this will only compile the libraries without trying to generate the source code. When you are lucky and the build process succeeds, you will find all the interface (`.h') files for the HL7 class library in the directory `hl7/include'. The library itself is found as `hl7/lib/libhl7.a'. Now you might want to test the so created library. Go to the `apps' directory and type $ make test You will be notified about any errors. You need to install the include-directory and the library and stuff by $ make install After having installed the files as stated above, you can clean the build directory by issuing the command $ make clean.all or $ make distclean.all HOW TO USE THE LIBRARY There is a documentation for ProtoGen/HL7 currently being written, but is not finished yet. Fragments of this documentation can be found in the `doc' directory. The documentation is written in the texinfo language. This means for you, that you can produce an online documentation as well as a printed copy from the `.texi' files. In order to remake the printed documentation you need the TeX document formatting system and the `fig2dev' program for the figures. In order to make the online manual, you need `makeinfo' which comes with the GNU info.tar.gz package. You need the `info' program or GNU emacs to read the `.info' files. I don't want to force you to install all these programs even though I recommend them and they are all free software; I left the PostScript and info files over for you. There are some text files that describe features and considerations of ProtoGen/HL7 which may have not yet been reflected in the texinfo socumentation. Notably these are the following files: Internal-llp The definition of the LLP I use internally Syntax Reasoning about HL7 structure and syntax and implementation considerations, slightly outdated. error-handling Error handling of GNU's libg++, which I was using. The error handling style is still about to change and will keep doing so until the GNU C++ compiler will support C++ exceptions. tb-format The description of the intermediate format of tables in the process of scanning of the HL7 standard document PLEASE NOTE: The documentation is *about* to be (re-)written. There are many passages that might be out of date or erroneous. The example programs might give you a glimpse, how the HL7 library could be used in practice. There are three programs of interrest along with some sample HL7 messages. The programs are: inout.cc Simply read and write out a HL7 message file that was given at the command line. server.cc A simple HL7 server that waits for connections at a port you specify at the command line. Uses the `internal' LLP. This server program does nothing but respond with an ACK message. client.cc A simple client that connects a server at a port/host that you specify on the command line and sends a message that you specify as well. Receives what ever response it gets from the server. Uses the `internal' LLP. nmdclient.cc Like client.cc but only sends an NMD message and receives an ACK. Oracle In this subdirectories you'll find a program that retrieves data from a patient database and writes it into a HL7 batch. It was a test using ESQL but I found it to be no way to go. Please find the T2C package from my WWW-Page in order to start more structured! CareVue A subdirectory in which support for a proprietary HIS (HP CareVue 9000) is stored. In this directory you can study how to interface a pseudo HL7 application with ProtoGen/HL7. I.e. How to define and use modifications of the standard. radiometer An HL7 interface (client) for the Radiometer ABL300 Acid Base Laboratory. Please note that the examples are still a work in progress. With them I am about to experiment with the library myself. Some of the code is used in a quasi-production setting though, so it gained some maturity already. QUESTIONS AND COMMENTS If you have problems or questions, or if you want to help or comment about this package, please feel free to e-mail me: Gunther Schadow Especially I am interested in how people use ProtoGen/HL7, so if you do, please drop me a line. If you want, I will set up a mailing list for discussions about ProtoGen so that I need not be in the center of all communications between users. Please mail me if you are interested. The whole project has become quite big, and deserves some more helping hands for porting, testing, etc. So, if you can afford some resources it would be a geat progress. ACKNOWLEDGEMENTS David Barr worked on the Ultrix port. Peter Weiss did the SunOS port. NeXUS corp. in Achim, Germany, for financially supported me doing the port to RS6000/AIX. Robb Keayes ported to the NeXT (NextStep 3.3). Enjoy -Gunther Schadow