###############################################################################
#
# HL7 API: README
#
###############################################################################

Contents
--------

1.0 Introduction
2.0 Usage
2.1 Creating messages
2.2 Sending/receiving
2.3 Other modules and this API


1.0 Introduction
----------------

This is the Perl HL7 API. It is a very simple, but rather flexible API
for use in Perl applications (or even in C applications, see for
example http://zwebit.sourceforge.net/). The API is not fixed yet, but
has been used in production environments and has evolved in the
process, into a useful level of abstraction.

The focus of this API is on providing functionality for the
composition, manipulation and decomposition of HL7 messages, not
providing hundreds of prefab HL7 messages. In HL7 terms: this API
focuses on the HL7 syntax, not the semantics. This makes the API
support all versions that use the classic HL7 syntax, that is,
versions untill 3.x. This API does not do XML!

Please refer to the POD documentation for detailed examples and the
full API documentation, or consult the generated manual pages on
http://hl7toolkit.sourceforge.net/. The POD man pages will be auto
generated after installation of the package. Use 'man
Net::HL7::Message' for instance, to get the document on the Message
class.

You might also be interested in the hl7d and hl7qd packages, found on
the same site. The hl7d is a a pluggable, forking HL7 server that can
be used to dispatch HL7 messages to for instance database tables,
files, etc. The hl7qd is a queueing daemon that manages HL7 message
queues. This daemon can accept messages on the filesystem, from a
database, etc.


2.0 Usage
---------

2.1 Creating messages
---------------------

The main focus of the HL7 API is on the Net::HL7::Message class,
assuming this class is the one you will most likely use. You can
create HL7 messages in roughly two ways:

1. creating an empty message with the Net::HL7::Message class, adding
   segements as you go;
2. creating a message based on a string representation of a HL7 
   message.

An basic example of the first way is:

	use Net::HL7::Message;
	use Net::HL7::Segment;
	use Net::HL7::Segments::MSH;

	my $msg = new Net::HL7::Message();

and set some segments and fields like:

	my $msh = new Net::HL7::Segments::MSH();
	my $pid = new Net::HL7::Segment("PID");

	$pid->setField(3, "1231313");
	
	$msg->addSegment($msh);
	$msg->addSegment($pid);

The second method goes like:

	use Net::HL7::Message;

	my $str = "MSH|^~\\&|||MyApp||20040202145837|||20040202145837.66528|P|2.4|||AL|NE\r";
	$str .= "QRD|20040202|fld3|||||fld2|fld1";

	my $msg = new Net::HL7::Message($str);

To check whether this yields the desired message, do:

	print $msg->toString(1);


2.2 Sending/receiving
---------------------

When a message has been created, the obvious thing to do with it would
be to send it off to some HL7 server, and handle the result.  This can
be achieved with the Net::HL7::Connection class. A simple example is
this:

	use Net::HL7::Connection;

	... create a message

	my $conn = new Net::HL7::Connection("hl7server.somedomain.org", 12011);

	$conn || die "Couldn't connect";

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

	$resp || die "No response";

	my $msh = $resp->getSegmentByIndex(0);

	... etc

but consult the man page of the Net::HL7::Connection (and even the
Net::HL7::Daemon) for details.


2.3 Other modules and this API
------------------------------

When building some HL7 Perl module, you might want to require a
specific version of this package. You can simply say:

	'PREREQ_PM' => { 'Net::HL7' => 0.66 }

in the Makefile.PL of your Perl thingy that requires this version.

For more detailed usage of every class, please consult the API
documentation on http://hl7toolkit.sourceforge.net/ or generate the
POD's yourself (man perlpod).