Next Previous Contents

3. Overview of the API

Basically, IrTcl is a set of commands introduced to Tcl. When extending Tcl there are two approaches: action-oriented commands and object-oriented commands.

Action-oriented commands manipulate Tcl variables and each command introduces only one action. The string manipulation commands in Tcl are action oriented.

Object-oriented commands are added for every declared variable (object). Object-oriented commands usually provide a set of actions (methods) to manipulate the object. The widgets in Tk (X objects) are examples of the object-oriented style.

IrTcl commands are object-oriented. The main reason for this is that the data structures involved in the IR protocol are not easily represented by Tcl data structures. Also, the IrTcl objects tend to exist for a relativly long time. Note that although we use the term object-oriented commands, this does not mean that the programming style is strictly object-oriented. For example, there is such no such thing as inheritance.

We are now ready to present the three commands introduced to Tcl by IrTcl:

ir

The ir object represents a connection to a target. More precisely it describes a Z-association.

ir-set

The ir-set describes a result set, which is conceptually a collection of records returned by the target. The ir-set object may retrieve records from a target by means of the ir object; it may read/write records from/to a local file or it may be updated with a user-edited record.

ir-scan

The scan object represents a list of scan lines retrieved from a target.

Example

To create a new IR object called z-assoc write:

   ir z-assoc

End of example

Each object provides a set of settings which may either be readable, writeable of both. All settings immediately follow the name of the object. If a value is present the setting is set to value.

Example

We wish to set the preferred-message-size to 18000 on the z-assoc object:

   z-assoc preferredMessageSize 18000

To read the current value of preferred-message-size use:

   z-assoc preferredMessageSize
End of example

One important category consists of settings is those that relate to the event-driven model. When IrTcl receives responses from the target, i.e. init responses, search responses, etc., a callback routine is called. Callback routines are represented in Tcl as a list, which is re-interpreted prior to invocation. The method is similar to the one used in Tk to capture X events.

For each Z39.50 request there is a corresponding object action. The most important actions are:

connect

Establishes connection with a target

init

Sends an initialize request.

search

Sends a search request.

present

Sends a present request.

scan

Sends a scan request.

Example

This example shows a complete connect - init - search - present scenario.

First an IR object, called z, is created. Also a result set z.1 is introduced by the ir-set and it is specified that the result set uses z as its association.

The setting databaseNames is set to the database books to which the following searches are directed. A callback is then defined and a connection is established to fake.com by the connect action. If the connect succeeds the connect-response is called.

In the Tcl procedure, connect-response, a callback is defined before the init request is executed. The Tcl procedure init-response is called when a init response is returned from the target.

The init-response procedure sets up a search-response callback handler and sends a search-request by using a query which consists of a single word science.

When the search-response procedure is called it defines a variable hits and sets it to the value of the setting resultCount. If hits is positive a present-request is sent -- asking for 5 records from position 1.

Finally, a present response is received and the number of records returned is stored in the variable ret.

ir z
z databaseNames books
ir-set z.1 z
z callback {connect-response}
z connect fake.com

proc connect-response {} {
    z callback {init-response}
    z init
}

proc init-response {} {
    z callback {search-response}
    z.1 search science
}

proc search-response {} {
    set hits [z.1 resultCount]
    puts "$hits hits"
    if {$hits > 0} {
        z callback {present-response}
        z.1 present 1 5
    }
}

proc present-response {} {
    set ret [z.1 numberOfRecordsReturned]
    puts "$ret records returned"
}
End of example

The previous example program doesn't care about error conditions. If errors occur in the program they will be trapped by the Tcl error handler. This is not always appropriate. However, Tcl offers a catch command to support error handling by the program itself.


Next Previous Contents