LISP-KQML Interface

This is a LISP interface to the C library of UMBC/LORAL KQML Software.

Development System

The LISP interface to the C KRIL library is built using the Lucid Common Lisp on Sun Microsystems. It supports all the calls that the C library supports. These can be broadly classified according to the following categories :

LISP Implementation vs. LISP Interface

The library calls to LISP implementation and the LISP interface calls differ a lot. The names of the functions are different and also the arguments to them differ as there is a lot of new functionality added in the C library which can be taken advantage of by the LISP Interface.

Registration

The LISP implementation used the function announce-service to register with the ANS. The only argument was the name of the agent. The LISP interface uses the kqml-initialize function.

The Handlers were registered using the define-handler function in the LISP implementation. LISP interface has the kqml-register function.

Build Messages

The function make-msg(performative, content &rest args) in LISP implementation is now replaced by the kqml-build-msg function.

Manipulation

In LISP implementation, there were only msg-field and msg-content functions to access the fields. In the LISP interface, there are a whole suite of functions to read and set the fields of the KQML messages. These can be found in the Manipulating KQML Messages section of the Development System.

Send

The function in LISP Implementation was send-msg(msg, &opt host). In the Interface, it is kqml-send.

Print

This is a utility provided by the Interface to print the KQML messages to the screen. See kqml-print-msg.

Parse

The function kqml-parse-buffer is provided by the LISP interface to parse the nested KQML messages.

General

The function kqml-msg-to-str is provided by the Interface as a general utility function to convert the KQML messages into strings.

Portability

The interface was developed using Lucid Common LISP on the SUN systems. It uses the foreign language interface provided by Lucid Common LISP to access the functions in the C library. If we have to use a different LISP to build agents, the interface will not work. The interface needs to be ported to that LISP before it can be used. Depending on the foreign interface supported by the LISP being used, the complexity of porting this interface is decided.

Regarding the C library, the library is portable across the SGIs using SVR4 Unix system, SUNs using SUNOS and Solaris. It is also supported on the LINUX system. It assumes that the underlying protocol is TCP/IP as of now.

Known Bugs and Fixes

Registration Functions

The functions in this group are the kqml_initialize and kqml_register functions.

kqml-initialize(Agent-Name, ANS-lookup-function)

This function is used to register the agent with the parent ANS. If the agent is an ANS itself, as of now, it does nothing but include itself in the database. In future, the agent will look for a parent ANS even if it is an ANS itself. This routine also spawns the router for the agent. If it is an ANS, the ANS-lookup-function is provided. Otherwise, it is set to nil. The function returns 0 on success and negative numbers to indicate an error.

kqml-register(Handler-Function, Performative, Blocking)

The handlers for the performatives that are supported by the application are all specified using the kqml-register function. The function returns a list of KQML messages as the result. The blocking field is as of now set to 1. It has been defined for possible future use.

Building KQML Messages

kqml-build-msg(Performative, Content, Receiver, Reply-with, &rest Args)

The performative, content, receiver and reply-with parameters are mandatory. The other fields of the KQML messages can be specified after these arguments along with the values for these fields. This function returns the KQML message.

Manipulating KQML Messages

The functions to manipulate the KQML messages can be divided into two categories, namely, functions to read the fields of the message and those to set the values of the message.

Reading the Fields in the KQML Message

kqml-get-field-count(Message)

This function returns the number of fields in the KQML message passed to it as the parameter.

kqml-get-performative(Message)

This function returns the performative of the KQML message.

kqml-get-field(Field-Name, Message)

This function returns three values : the value of the field specified, the length of the value and the type of the value, i.e., a KQML word, expression, quoted expression etc.

kqml-get-ith-field(Field-Number, Message)

This function returns the ith field in the KQML message passed to it as an argument. It returns the values returned by kqml-get-field and also the field name of the ith field in the message as its first return value.

Setting the fields in the KQML Message

kqml-put-performative(Message, Performative)

This function sets the performative of the Message to performative. It returns the modified message as its return value.

kqml-put-field(Field-Name, Message, Value)

This function takes the Field-Name and searches the Message for the field. If the field exists in the message, it replaces the value with the new Value. If the field doesn't exist in the Message, it is appended to the Message. The function returns the modified message.

kqml-put-embedded-msg(Field-Name, Message, Embedded-Message)

This function takes as arguments the KQML message and the message to be embedded in this message. It makes the embedded message the value of the field specified. Returns the modified message.

Sending KQML Messages

kqml-send(Timeout, Message)

This function is used to send out the messages. The first field is the timeout specification for the message. The system will wait for this amount of time before returning with an error. If the timeout is specified as -1, the default timeout value of 30 seconds is assumed. The function returns nil if it is unable to send the message or a reply is not expected. It returns the reply message when a reply is expected.

kqml-deliver(Message)

This function is used by an application program which is supporting the monitor and subscribe performatives. Messages are sent to the appropriate subscribers. Returns a -1 on error, 0 if delivered to some of the subscribers and 1 if delivered to all the subscribers.

Printing KQML Messages

kqml-print-msg(Message)

This function prints the KQML message specified on the terminal. It prints the fields along with their values, the length of the value of the field and the type of the value in terms of KQML specification. Returns nothing.

Parsing KQML Messages

kqml-parse-buffer(Str)

This function parses a string and returns the KQML message. Used when the KQML message consists of embedded messages like in the advertise performative. Usually the Content field has an embedded message and the message returned by this function can be used to manipulate the fields or read the fields of the embedded message.

General Purpose Functions

kqml-msg-to-str(Message)

This function converts a KQML message into a string. Returns the string.