<!doctype linuxdoc system>
<!--
- $Id
+ $Id: ir-tcl.sgml,v 1.6 1995-06-01 16:36:56 adam Exp $
-->
<article>
<title>IrTcl User's Guide and Reference
<author>Index Data, <tt/info@index.ping.dk/
-<date>May 1995
+<date>$Revision: 1.6 $
<abstract>
-This document describes IrTcl - an information retrieval toolkit for
+This document describes IrTcl &mdash an information retrieval toolkit for
Tcl and Tk that provides access to the Z39.50/SR protocol.
</abstract>
This document describes the <sf/IrTcl/ information retrieval toolkit,
which offers a high-level, client interface to the Z39.50 and SR protocols.
The toolkit is based on the Tcl/Tk toolkit developed by Prof. John
-K. Ousterhout at the University of California [ref 1].
+K. Ousterhout at the University of California [ref 1].
Tcl is a simple, somewhat shell-like, interpreted language. What
makes Tcl attractive is that it also offers a C API, which makes
extensions to the language possible. The most important Tcl extension is
-probably Tk --- A Motif look-and-feel interface to the X window
+probably Tk &mdash A Motif look-and-feel interface to the X window
system.
-To interface the Z39.50/SR protocol <sf/IrTcl/ uses <bf/YAZ.
+To interface the Z39.50/SR protocol <sf/IrTcl/ uses <bf/YAZ/.
<bf/YAZ/ offers two transport types: RFC1729/BER on TCP/IP and the mOSI
protocol stack.
However, the mOSI transport is only an option, and hence it is not
needed unless you wish to communicate within an OSI environment.
-See [ref 2] for more information about the XTI/mOSI implementation.
+See [ref 2] for more information about the XTI/mOSI implementation.
<sf/IrTcl/ provides two system environments:
<itemize>
-<item> A simple command line shell --- useful for
+<item> A simple command line shell &mdash useful for
testing purposes.
<item> A system which operates within the Tk environment which
makes it very easy to implement GUI clients.
We are now ready to present the three commands introduced to Tcl by
<sf/IrTcl/:
-<itemize>
-<item> ir: The ir object represents a connection to a target. More
+<descrip>
+<tag/ir/ The ir object represents a connection to a target. More
precisely it describes a Z-association.
-<item> ir-set: The ir-set describes a result set, which is
+<tag/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.
-<item> ir-scan: The scan object represents a list of scan lines
+<tag/ir-scan/ The scan object represents a list of scan lines
retrieved from a target.
-</itemize>
+</descrip>
<bf/Example/
For each SR/Z39.50 request there is a corresponding object action. The most
important actions are:
-<itemize>
-<item> connect Establishes connection with a target
-<item> init Sends an initialize request.
-<item> search Sends a search request.
-<item> present Sends a present request.
-<item> scan Sends a scan request.
-</itemize>
+<descrip>
+<tag/connect/ Establishes connection with a target
+<tag/init/ Sends an initialize request.
+<tag/search/ Sends a search request.
+<tag/present/ Sends a present request.
+<tag/scan/ Sends a scan request.
+</descrip>
<bf/Example/
-This example shows a complete
-connect - init - search - present scenario.
+
+This example shows a complete connect - init - search - present scenario.
First an IR object, called <tt/z/, is created.
Also a result set <tt/z.1/ is introduced by the <tt/ir-set/
The setting <tt/databaseNames/ is set to the
database <tt/books/ to which the following searches are directed.
-A connection is established to <tt/fake.com/ by the <tt/connect/ action.
-A callback is then defined <em/before/ the init request is executed.
+A callback is then defined and a connection is established to
+<tt/fake.com/ by the <tt/connect/ action.
+If the connect succeeds the <tt/connect-response/ is called.
+
+In the Tcl procedure, <tt/connect-response/, a callback is defined
+<em/before/ the init request is executed.
The Tcl procedure <tt/init-response/ is called when a
-init-response is returned from the target.
+init response is returned from the target.
The <tt/init-response/ procedure sets up a <tt/search-response/
callback handler and sends a search-request by using a query which
When the <tt/search-response/ procedure is called it defines
a variable <tt/hits/ and sets it to the value of the setting
<tt/resultCount/. If <tt/hits/ is positive a present-request is
-sent --- asking for 5 records from position 1.
+sent &mdash asking for 5 records from position 1.
-Finally, a present-response is received and the number of records
+Finally, a present response is received and the number of records
returned is stored in the variable <tt/ret/.
<tscreen><verb>
ir z
ir-set z.1 z
z databaseNames books
+z callback {connect-response}
z connect fake.com
-z callback {init-response}
-z init
+
+proc connect-response {} {
+ z callback {init-response}
+ z init
+}
proc init-response {} {
z.1 callback {search-response}
<p>
A connection is established by the <tt/connect/ action which is
-immediately followed by a hostname. Table ref{tab:irconnect} lists the
-settings that affect the <tt/connect/ action.
-Obviously, these settings should be set <bf/before/ connecting.
+immediately followed by a hostname. Obviously, these settings should
+be set <bf/before/ connecting.
+The settings that affect the <tt/connect/ action are:
<descrip>
<tag><tt>comstack </tt><tt>mosi|tcpip</tt></tag>
Comstack type
<tag><tt>protocol </tt><tt>Z3950|SR</tt></tag>
ANSI/NISO Z39.50 or ISO SR
+<tag><tt>callback </tt><em>list</em></tag>
+ Tcl script called when the connection is established
<tag><tt>failback </tt><em>list</em></tag>
Fatal error Tcl script. Called on protocol errors or if target
closes connection
</descrip>
+If the connect is unsuccessful either the connect action itself
+will return an error code or the failback handler is invoked.
+
<sect1>Init
<p>
If the connect operation succeeds the <tt/init/ action should be used.
-Table ref{tab:irinit} lists the init related settings.
+The init related settings are:
<descrip>
<tag><tt>preferredMessageSize </tt><em>integer</em></tag>
General response Tcl script. Only used if initResponse is not specified
</descrip>
-The init-response handler should inspect some of the settings in table
-ref{tab:irinitresponse}
+The init-response handler should inspect some of the settings shown
+below:
<descrip>
<tag><tt>initResult </tt><em>boolean</em></tag>
</descrip>
<bf/Example/
+
Consider a client with the ability to access multiple targets.
We define a list of targets that we wish to connect to.
$assoc comstack [lindex $target 1]
$assoc protocol [lindex $target 2]
$assoc failback [list fail-response $assoc]
+ $assoc callback [list connect-response $assoc]
$assoc connect [lindex $target 3]
+}
+
+proc connect-response {assoc} {
$assoc initResponse [list init-response $assoc]
$assoc init
}
<tt/target/ is bound to each item in the list of targets.
The <tt/assoc/ is set to the ir object name.
Then, the comstack, protocol and failback are set for the <tt/assoc/ object.
-The ir object name is argument to the <tt/fail-response/ routine.
+The ir object name is argument to the <tt/fail-response/ and
+<tt/connect-response/ routines.
Note the use of the Tcl <tt/list/ command which
is necessary here because the argument contains variables
(<tt/assoc/) that should be substituted before the handler is defined.
A search operation and a result set is described by the ir set object.
The ir set object is defined by the <tt/ir-set/ command which
has two parameters. The first is the name of the new ir set object, and
-the second, which is optional, is the name of an assocation --- an ir
+the second, which is optional, is the name of an assocation &mdash an ir
object. The second argument is required if the ir set object should be able
to perform searches and presents. However, it is not required if
only ``local'' operations is done with the ir set object.
the standard may vary.
The prefix query notation (which is converted to RPN) offer a few
-operators, shown in table ref{tab:prefixop}.
+operators. They are:
<descrip>
<tag><tt>@attr </tt><em>list op</em></tag>
<tag><tt>@not </tt><em>op1 op2</em></tag>
Boolean <em/not/ on op1 and op2
<tag><tt>@prox </tt><em>list op1 op2</em></tag>
- Proximity operation on op1 and op2
+ Proximity operation on op1 and op2. Not implemented yet.
+<tag><tt>@set </tt><em>name</em></tag>
+ Result set reference
</descrip>
It is simple to build RPN queries in <sf/IrTcl/. Search terms
<sect1>Search
<p>
-Table ref{tab:irsearchrequest} lists settings that affect the search.
-Setting the <tt/databaseNames/ is mandatory. All other settings
-have reasonable defaults.
-
-</article>
+The settings that affect the search are listed below:
-\begin{table}[htbf]
-\begin{tabular}{l|l|p{8cm}}
-Setting & Value & Description \\\hline
-databaseNames & list & database-names \\
-smallSetUpperBound & integer & small set upper bound \\
-largeSetLowerBound & integer & large set lower bound \\
-mediumSetPresentNumber & integer & medium set present number \\
-replaceIndicator & boolean & replace-indicator \\
-setName & string & name of result set \\
-queryType & rpn & query type-1 \\
- & ccl & query type-2 \\
-preferredRecordSyntax & string & preferred record syntax.
-See table ref{tab:recordtypes} on page \pageref{tab:recordtypes} \\
-smallSetElementSetNames & string & small-set-element-set names \\
-mediumSetElementSetNames & string & medium-set-element-set names \\
-searchResponse & list & Search-response Tcl script \\
-callback & list & General response Tcl script. Only used
-if searchResponse is not specified \\
-\end{tabular}
-\caption{Search request settings}
-\label{tab:irsearchrequest}
-\end{table}
+<descrip>
+<tag><tt>databaseNames </tt><em>list</em></tag>
+ database-names
+<tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
+ small set upper bound
+<tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
+ large set lower bound
+<tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
+ medium set present number
+<tag><tt>replaceIndicator </tt><em>boolean</em></tag>
+ replace-indicator
+<tag><tt>setName </tt><em>string</em></tag>
+ name of result set
+<tag><tt>queryType rpn|ccl</tt></tag>
+ query type-1 or query type-2
+<tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
+ preferred record syntax &mdash UNIMARC, USMARC, etc.
+<tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
+ small-set-element-set names
+<tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
+ medium-set-element-set names
+<tag><tt>searchResponse </tt><em>list</em></tag>
+ Search-response Tcl script
+<tag><tt>callback </tt><em>list</em></tag>
+ General response Tcl script. Only used if searchResponse is not specified
+</descrip>
+Setting the <tt/databaseNames/ is mandatory. All other settings
+have reasonable defaults.
The search-response handler, specified by the <tt/callback/ - or
the <tt/searchResponse/ setting,
-should read some of the settings shown in table ref{tab:irsearchresponse}.
-
-\begin{table}[htbf]
-\begin{tabular}{l|l|p{8cm}}
-Setting & Value & Description \\\hline
-searchStatus & boolean & search-status \\
-responseStatus & list & response status information \\
-resultCount & integer & result-count \\
-numberOfRecordsReturned & integer & number of records retrieved \\
-\end{tabular}
-\caption{Search response settings}
-\label{tab:irsearchresponse}
-\end{table}
+should read some of the settings shown below:
+
+<descrip>
+<tag><tt>searchStatus </tt><em>boolean</em></tag>
+ search-status
+<tag><tt>responseStatus </tt><em>list</em></tag>
+ response status information
+<tag><tt>resultCount </tt><em>integer</em></tag>
+ result-count
+<tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
+ number of records retrieved
+</descrip>
The <tt/responseStatus/ signals one of three conditions which
is indicated by the value of the first item in the list:
-\begin{description}
-\item[NSD] indicates that the target has returned one or more non-surrogate
-diagnostic messages. The <tt/NSD/ item is followed by a list with
-all non-surrogate messages. Each non-surrogate message consists
+<descrip>
+<tag><tt>NSD</tt></tag> indicates that the target has returned one or
+more non-surrogate diagnostic messages. The <tt/NSD/ item is followed by
+a list with all non-surrogate messages. Each non-surrogate message consists
of three items. The first item of the three items is the error
code (integer); the next item is a textual representation of the error
code in plain english; the third item is additional information, possibly
empty if no additional information was returned by the target.
-\item[DBOSD] indicates a successful operation where the
+<tag><tt>DBOSD</tt></tag> indicates a successful operation where the
target has returned one or more records. Each record may be
either a database record or a surrogate diagnostic.
-\item[OK] indicates a successful operation --- no records are
+<tag><tt>OK</tt></tag> indicates a successful operation &mdash no records are
returned from the target.
-\end{description}
+</descrip>
<bf/Example/
+
We continue with the multiple-targets example.
The <tt/init-response/ procedure will attempt to make searches:
proc search-response {assoc rset} {
set status [$rset responseStatus]
set type [lindex $status 0]
- if {$type == NSD} {
+ if {$type == "NSD"} {
set code [lindex $status 1]
set msg [lindex $status 2]
set addinfo [lindex $status 3]
return
}
set hits [$rset resultCount]
- if {$type == DBOSD} {
+ if {$type == "DBOSD"} {
set ret [$rset numberOfRecordsReturned]
...
}
<p>
The <tt/present/ action sends a present request. The <tt/present/ is
followed by two optional integers. The first integer is the
-result-set starting position --- defaults to 1. The second integer
-is the number of records requested --- defaults to 10.
+result-set starting position &mdash defaults to 1. The second integer
+is the number of records requested &mdash defaults to 10.
The settings which could be modified before a <tt/present/
-action are shown in table ref{tab:irpresentrequest}.
-
-\begin{table}[htbf]
-\begin{tabular}{l|l|p{8cm}}
-Setting & Value & Description \\\hline
-preferredRecordSyntax & string & preferred record syntax.
-See table ref{tab:recordtypes} on page \pageref{tab:recordtypes} \\
-elementSetElementSetNames & string & element-set names \\
-presentResponse & list & Present-response Tcl script \\
-callback & list & General response Tcl script. Only used
-if presentResponse is not specified \\
-\end{tabular}
-\caption{Present request settings}
-\label{tab:irpresentrequest}
-\end{table}
+action are:
+
+<descrip>
+<tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
+ preferred record syntax &mdash UNIMARC, USMARC, etc.
+<tag><tt>elementSetElementSetNames </tt><em>string</em></tag>
+ element-set names
+<tag><tt>presentResponse </tt><em>list</em></tag>
+ Present-response Tcl script
+<tag><tt>callback </tt><em>list</em></tag>
+ General response Tcl script. Only used if presentResponse is not specified
+</descrip>
The present-response handler should inspect the settings
shown in table ref{tab:irpresentresponse}.
As in the search-response case, records returned from the
target are stored in the result set object.
-\begin{table}[htbf]
-\begin{tabular}{l|l|p{8cm}}
-Setting & Value & Description \\\hline
-presentStatus & boolean & present-status \\
-responseStatus & list & Response status information \\
-numberOfRecordsReturned & integer & number of records returned \\
-nextResultSetPosition & integer & next result set position \\
-\end{tabular}
-\caption{Present response settings}
-\label{tab:irpresentresponse}
-\end{table}
+<descrip>
+<tag><tt>presentStatus </tt><em>boolean</em></tag>
+ present-status
+<tag><tt>responseStatus </tt><em>list</em></tag>
+ Response status information
+<tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
+ number of records returned
+<tag><tt>nextResultSetPosition </tt><em>integer</em></tag>
+ next result set position
+</descrip>
<sect1>Records
records, indexed by an integer position, should be
inspected.
-The action <tt/Type/ followed by an integer returns information
+The action <tt/type/ followed by an integer returns information
about a given position in an ir set. There are three possiblities:
-<itemize>
-<item> SD The item is a surrogate diagnostic.
-<item> DB The item is a database record.
-<item> <em/empty/ There is no record at the specified position.
-</itemize>
+<descrip>
+<tag><tt/SD/</tag> The item is a surrogate diagnostic record.
+<tag><tt/DB/</tag> The item is a database record.
+<tag><em/empty/</tag> There is no record at the specified position.
+</descrip>
-To handle the first case, surrogate diagnostic, the
+To handle the first case, surrogate diagnostic record, the
<tt/Diag/ action should be used. It returns three
items: error code (integer), text representation in plain english
(string), and additional information (string, possibly empty).
In the second case, database record, the <tt/recordType/ action should
be used. It returns the record type at the given position.
-Some record types are shown in table ref{tab:recordtypes}.
-
-\begin{table}[htbf]
-\begin{center}
-\begin{tabular}{c}
-Type \\\hline
-UNIMARC \\
-INTERMARC \\
-CCF \\
-USMARC \\
-UKMARC \\
-NORMARC \\
-LIBRISMARC \\
-DANMARC \\
-FINMARC \\
-SUTRS \\
-\end{tabular}
-\end{center}
-\caption{Record types}
-\label{tab:recordtypes}
-\end{table}
+Some record types are:
+
+<tscreen>
+UNIMARC
+INTERMARC
+CCF
+USMARC
+UKMARC
+NORMARC
+LIBRISMARC
+DANMARC
+FINMARC
+SUTRS
+</tscreen>
<bf/Example/
+
We continue our search-response example. In the case,
<tt/DBOSD/, we should inspect the result set items.
Recall that the ir set name was passed to the
search-response handler as argument <tt/rset/.
<tscreen><verb>
- if {$type == DBOSD} {
+ if {$type == "DBOSD"} {
set ret [$rset numberOfRecordsReturned]
for {set i 1} {$i<=$ret} {incr i} {
- set itype [$rset Type $i]
- if {$itype == SD} {
+ set itype [$rset type $i]
+ if {$itype == "SD"} {
set diag [$rset Diag $i]
set code [lindex $diag 0]
set msg [lindex $diag 1]
set addinfo [lindex $diag 2]
puts "$i: NSD $code: $msg: $addinfo"
- } else if {$itype == DB} {
- set rtype [$rset RecordType $i]
+ } else if {$itype == "DB"} {
+ set rtype [$rset recordType $i]
puts "$i: type is $rtype"
}
}
}
</verb></tscreen>
-Each item in the result-set is examined.
+Each item in the result set is examined.
If an item is a diagnostic message it is displayed; otherwise
if it's a database record its type is displayed.
<bf/End of example/
is returned.
The <tt/line/ type, on the other hand, returns a Tcl list that
-completely describe the layout of the MARC record --- including
+completely describe the layout of the MARC record &mdash including
tags, fields, etc.
The <tt/field/ type is sufficient and efficient in the case, where only a
further processing (in Tcl) is necessary.
However, if the MARC record is to be edited or altered in any way, the
-<tt/line/ extraction is more powerful --- only limited by the Tcl
+<tt/line/ extraction is more powerful &mdash only limited by the Tcl
language itself.
<bf/Example/
+
Consider the record below:
<tscreen><verb>
001 11224466
<bf/End of example/
<bf/Example/
+
This example demonstrates how Tcl can be used to examine
a MARC record in the list notation.
<p>
<em/To be written/
-\appendix
-\pagebreak
+<sect>License
+
+<p>
+Copyright (c) 1995, Index Data.
+
+Permission to use, copy, modify, distribute, and sell this software and
+its documentation, in whole or in part, for any purpose, is hereby granted,
+provided that:
+
+1. This copyright and permission notice appear in all copies of the
+software and its documentation. Notices of copyright or attribution
+which appear at the beginning of any file must remain unchanged.
+
+2. The names of Index Data or the individual authors may not be used to
+endorse or promote products derived from this software without specific
+prior written permission.
+
+THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
+EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
+WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
+INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
+NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
+LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+OF THIS SOFTWARE.
+
+<sect>About Index Data
+
+<p>
+Index Data is a consulting and software-development enterprise that
+specialises in library and information management systems. Our
+interests and expertise span a broad range of related fields, and one
+of our primary, long-term objectives is the development of a powerful
+information management
+system with open network interfaces and hypermedia capabilities.
+
+We make this software available free of charge, on a fairly unrestrictive
+license; as a service to the networking community, and to further the
+development of quality software for open network communication.
+
+We'll be happy to answer questions about the software, and about ourselves
+in general.
+
+<tscreen>
+Index Data&nl
+Ryesgade 3&nl
+2200 København N&nl
+DENMARK
+</tscreen>
+
+<p>
+<tscreen><verb>
+Phone: +45 3536 3672
+Fax : +45 3536 0449
+Email: info@index.ping.dk
+</verb></tscreen>
<sect>References
<p>
-\label{sec:references}
-<itemize>
-<item> <bf/Ousterhout, John K./:
+<descrip>
+<tag>1 Ousterhout, John K.:</tag>
Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
0-201-63337-X). Source and documentation
-can be found in <tt/URL:ftp://ftp.cs.berkeley.edu/pub/tcl/
+can be found in <tt>URL:ftp://ftp.cs.berkeley.edu/pub/tcl</tt>
and mirrors.
-<item> <bf/Furniss, Peter/:
+<tag>2 Furniss, Peter:</tag>
RFC 1698: Octet Sequences for Upper-Layer OSI to Support
Basic Communications Applications.
-</itemize>
+</descrip>
</article>