Install Perl HL7 Toolkit on XAMPP OS X Mavericks

Perl version HL7 Toolkit is in its alpha stage but offers general support to HL7 V.2 messaging.

The Perl HL7 toolkit consists of:

Net::HL7, a lightweight Perl API for parsing, formatting, manipulating, sending and receiving HL7 messages,
hl7d, an implementation of a forking HL7 server for inbound interfaces, and
hl7qd, an HL7 queue daemon for outbound interfaces.

For basic testing, we'll need Perl module like Net::HL7 installed properly and a running HL7 server like hl7d daemon.

OS X Mavericks comes with its own version of Perl which is suitable for running scripts for system administration whereas most users should avoid touching it for development.

Alternatively, users can install their favourite version of Perl to run the scripts with specific modules installed on the system.

For web development, bundled package like XAMPP is accompanied with latest version of Perl which collaborates with Apache module mod_perl to delivery services to Internet users.

With CPAN already installed under XAMPP folder, it's easy to install the toolkit.

For the very first time using of CPAN under XAMPP by simply typing

$ /Applications/XAMPP/xamppfiles/bin/cpan

in Terminal Window, you'll be asked questions to setup the environment and you can almost give default answer to every single question of this. Once done, you're ready to install Perl module to support HL7 within XAMPP.

To run HL7 toolkit, you'll need Perl module Net::HL7:

$ /Applications/XAMPP/xamppfiles/bin/cpan install Net::HL7

Before all these, just need to make sure the version of Perl running as default to be in the path of XAMPP installation, i.e., /Applications/XAMPP/xamppfiles/bin/

For sure, please run a test like this:

$ which perl
/Applications/XAMPP/xamppfiles/bin/perl

Please notice that most Perl scripts may start with the beginning statement like this:

#!/usr/bin/perl

This actually points to the default installation of Perl whereas desired Perl modules like Net::HL7 might not exist at all.

To test whether your version of Perl has desired module installed, please try this command:

$ perl -e 'use XXXX::xxxx;'

If the specific module is not installed, general error message would be like this even after installing your favourite Perl module with CPAN:

Can't locate XXXX/xxxx.pm in @INC contains: ...

So, basically, you should not run Perl script by just typing ./?????.pl in Terminal. Instead, using full path of Perl to call the script:

$ /Applications/XAMPP/xamppfiles/bin/perl ./?????.pl

This ensure that your desired version of Perl is used to run the script.

To install hl7d server, you may download the package to local drive via this link:
http://hl7toolkit.sourceforge.net/#hl7d

Unzip the *.tar.gz file to extract a folder with source code for building:

$ tar -xzf hl7d-(version).tgz

And then start installation in good old fashion style:

$ cd hl7d-
$ perl Makefile.PL PREFIX=
$ make
$ make test (none yet, but read the output!)
$ make install

You can also copy sample scripts to hl7d's installation directory.

$ cp t/* /usr/local/hl7d-(version)/t/

For Perl version of hl7d server, there is a little change to make it running successfully under OS X environment.

After the installation of hl7d, please change the line for LocalPort setting in hl7d.pl as follow:

# establish SERVER socket, bind and listen.
#
my $server = new Net::HL7::Daemon
    (
  #LocalPort => $cfg{PORT},
         LocalPort => 12002,
         Listen    => $cfg{LISTEN}
     );
$server or die "Couldn't create daemon";

This makes sure hl7d daemon starts properly at port 12002.

To start hl7d server in debug mode, please type in the command:

$ /usr/local/hl7d-/hl7d.pl --nodetach --debug

And then you can try sample client Perl scripts within /usr/local/hl7d-/t/ subfolder in another Terminal Window. When succeeded, you will receive messages from the Terminal which hl7d server is running.

For PHP web application in XAMPP, you must install another module Net_Socket first:

$ /Applications/XAMPP/xamppfiles/bin/pear install Net_Socket

To test out PHP script running within XAMPP web application, you can create test.php file:

<?php
require_once "Net/HL7/Segments/MSH.php";
require_once "Net/HL7/Message.php";
require_once "Net/HL7/Connection.php";
require_once 'Net/Socket.php';

$msg  = new Net_HL7_Message();
$msg->addSegment(new Net_HL7_Segments_MSH());

$seg1 = new Net_HL7_Segment("PID");

$seg1->setField(3, "XXX");

$msg->addSegment($seg1);

echo "
Trying to connect
";
$socket = new Net_Socket();
$success = $socket->connect("localhost", 12002);

if ($success instanceof PEAR_Error) {
    echo "
Error: {$success->getMessage()}
";
    exit(-1);
}

$conn = new Net_HL7_Connection($socket);

echo "
Sending message\n" . $msg->toString(true) . "
";

$resp = $conn->send($msg);

$resp || exit(-1);

echo "
Received answer\n" . $resp->toString(true) . "
";

$conn->close();
?>