The I2A2 External Protocol
Client host applications communicate with net daemon servants of the I2A2 data base managers (DBMs) via an external protocol after a
connection has been established. The
protocol uses ASCII text messages in a simple command-reply sequence -- i.e., the client sends a command ASCII message to the net
daemon and it responds with a reply ASCII message.
That is always the sequence in which messages are exchanged with one exception. When a client host makes a connection to the
net daemon, the connection itself is considered a command message, so the net daemon replies with a
welcome reply message.
Definitions for the external protocol appear in the puidnetd.h header file. Typically they begin with PUIDNETD. Where possible
the PUIDNETD symbol definition will be given in this documentation.
Message Format
The command and reply messages have the same format.
A command or reply begins with a single character. For a command it is the
command character. For a reply
it is the reply character.
Command characters have symbol names in puidnetd.h beginning with PUID_NETD_CMD_; reply characters. with PUIDNETD_REPL_.
The command or reply may be followed by an optional
field terminator character, an ASCII
Vertical Tab (TAB, or VT, decimal 11). The field terminator will be represented in this documentation by its C language escape,
"\t". It's puidnetd.h symbol name is PUIDNETD_MSGTERM
The command or reply may be accompanied by data
fields. Each field must begin with a
field identifier character, be optionally followed by ASCII data characters, and be ended with a field terminator. puidnetd.h
data field identifier symbol names begin with PUIDNETD_DATA. When binary information must be sent as field data, it must be
encoded in base 64.
The command or reply line must end with at least an ASCII New Line character (NL, decimal 10). NL will be represented in this
documentation by its C language escape, "\n".
The NL character may be optionally preceded by an ASCII Carriage Return character (CR, decimal 13). CR will be represented in
this documentation by its C language escape, "\r". Since \r is commonly used in Windows messages, the I2A2 net daemons always
include it in reply messages, right before the ending \n.
Sample Command-Reply Exchange
Here's a sample exchange of a command from a client host application to a net daemon and the net daemon's reply. In this example
the client host application is looking up information about an
alias and the net daemon returns the DBM's
positive acknowledgement that includes information about the PUID.
Command:
l afoobar
l -- is the lookup command (PUIDNETD_CMD_LOOKUP).
-- terminates the command field (PUIDNETD_MSGTERM). (This is optional.)
a -- is the alias field identifier (PUIDNETD_DATA_AKA).
foobar -- is the alias of interest.
-- terminates the alias field (PUIDNETD_MSGTERM).
-- ends the message
Reply:
a NFoo Bar p123123457 afoobar
a -- is the positive acknowledgement (ACK) reply code (PUIDNETD_REPL_ACK).
-- terminates the reply field (PUIDNETD_MSGTERM). (This is optional.)
N -- is the common name field identifier (PUIDNETD_DATA_CNM).
Foo Bar -- is the common name.
-- terminates the canonical name field (PUIDNETD_MSGTERM).
p -- is the PUID field identifier (PUIDNETD_DATA_PUID).
123123457 -- is the PUID value.
-- terminates the PUID field (PUIDNETD_MSGTERM).
a -- is the alias field identifier (PUIDNETD_DATA_AKA).
foobar -- is the alias field value
-- terminates the alias field (PUIDNETD_MSGTERM).
-- ends the reply message.
Message Length
Individual messages are limited to 4,095 characters PUIDNETD_MAXMSGL in puidnetd.h).
Cautions
Here are some cautions the client host application developer should keep in mind about command and reply messages.
The bytes of a command or reply message need not arrive in one return from low-level system read calls like the
UNIX read(2) or SSL_read(). Applications using these calls must acquire an input stream of characters until the
message's terminating \n appears. When read(2) or SSL_read() is used, the application may also have to hold
received characters that follow the \n and supply them as the beginning of the next message.
The sending of two \n characters is the same as the sending of two messages. The net daemon will read the first message, send
a reply to it, then immediately read the second message, and send a reply to it. If the client host application doesn't
realize it has sent two messages -- e.g., it has accidentally ended a message with two \n characters -- and sends a third message,
it may find itself erroneously processing the net daemon's second reply as the reply to the third message. Thus it is very
important when sending \n characters to match the messages they terminate to the corresponding reply messages.
Continuations
With one exception, the body of the message string before the ending \r\n or \n must always end with a \t. The one exception is
when space in the message body is too short to contain the next field.
The message must have room for the continuation character (PUIDNETD_DATA_CONT in puidnetd.h) after the last field (instead of \t)
and the ending \n or \r\n characters.
When a message ends with PUIDNETD_DATA_CONT, the next message is part of it and must begin with the PUIDNETD_CMD_CONT command
character (defined in puidnetd.h) or a PUIDNETD_REPL_NAK reply character (see Exception below). The
fields of the next message become part of the preceding one, continuing until a message ends with \t\r\n. The application must
remember the "real" reply character that appeared in the first message of a continued sequence.
Exception In rare circumstances the sender of a continued message may not be able to complete it. In that case the
sender will indicate the continuation failed and use the PUIDNETD_REPL_NAK reply character instead of PUIDNETD_CMD_CONT. The
receiving application must be prepared to recognize the failure signal and replace the "real" reply character it previously
remembered with PUID_REPL_NAK. The last reply message containing PUID_REPL_NAK will also contain an error explanation code in
the PUIDNETD_DATA_ERRC field.
The I2A2 PUID external C library
contains a function, puidnetd_unpk(3), that will do all the book work required to remember the real reply character and
combine the fields of all parts of the message into one structure. Reading and recognizing the parts of the message is still
the responsibility of the application; puidnetd_unpk(3) merely combines them in a usable form.
Libraries and Examples
The following libraries and examples are provided to assist the client host application developer in managing use of the I2A2 external protocol.
The PUID external C library contains
functions for handling parts of the external protocol.
A C client access library, PUIDCL,
written by Curtis Smith of the PACE Technical Group, is available for some UNIX and Windows systems.
Instructions for using I2A2 from an Apache Web Server may be found
here.
Examples of accessing the I2A2 net daemons from Perl may be found
here.