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