<!doctype linuxdoc system>
<!--
- $Id: ir-tcl.sgml,v 1.12 1995-08-28 12:21:52 adam Exp $
+ $Id: ir-tcl.sgml,v 1.18 1996-02-21 15:55:00 quinn Exp $
-->
<article>
-<title>IrTcl User's Guide and Reference
-<author>Index Data, <tt/info@index.ping.dk/
-<date>$Revision: 1.12 $
+<title>IrTcl User's Guide and Reference
+<author><htmlurl url="http://www.indexdata.dk/" name="Index Data">,
+<tt><htmlurl url="mailto:info@index.ping.dk" name="info@index.ping.dk"></tt>
+<date>$Revision: 1.18 $
<abstract>
-This document describes IrTcl — an information retrieval toolkit for
+This document describes IrTcl -- an information retrieval toolkit for
Tcl and Tk that provides access to the Z39.50/SR protocol.
</abstract>
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 -- A Motif look-and-feel interface to the X window
system.
To interface the Z39.50/SR protocol <sf/IrTcl/ uses <bf/YAZ/.
<sf/IrTcl/ provides two system environments:
<itemize>
-<item> A simple command line shell — useful for
+<item> A simple command line shell -- useful for
testing purposes.
<item> A simple command line shell which operates within the Tk
- environment — makes it very easy to implement GUI clients.
+ environment -- makes it very easy to implement GUI clients.
</itemize>
<sect>Compilation and installation
In order to compile you need:
<itemize>
<item> An ANSI C compiler such as GNU C.
-<item> Tcl. Version 7.3 and 7.4 has been tested.
-<item> YAZ version 1.0b3 or higher.
+<item> <htmlurl url="http://www.sunlabs.com/research/tcl/" name="Tcl">.
+ Version 7.3, 7.4 and 7.5 has been tested.
+<item> <htmlurl url="http://130.225.252.168/yaz.html" name="YAZ">
+ version 1.0 patch level 3 or higher.
</itemize>
As an option you may want:
<itemize>
-<item> Tk. Version 3.6 and 4.0 has been tested.
+<item> <htmlurl url="http://www.sunlabs.com/research/tcl/" name="Tk">.
+Version 3.6, 4.0 and 4.1 has been tested.
<item> XTI/mOSI
</itemize>
<descrip>
<tag><tt>ir-tk</tt></tag> The <sf/IrTcl/ shell for Tk.
- Installed in <tt>BINDIR</tt> — defaults to
+ Installed in <tt>BINDIR</tt> -- defaults to
<tt>/usr/local/bin</tt>. <tt>ir-tk</tt> works like
<tt>wish</tt> &mdash without arguments it reads commands from stdin.
A source file may be specified by option <tt>-f</tt>. <tt>ir-tk</tt>
accept the same set of options as <tt>wish</tt>.
<tag><tt>ir-tcl</tt></tag> The <sf/IrTcl/ shell for Tcl. Installed in
- <tt>BINDIR</tt> — defaults to <tt>/usr/local/bin</tt>.
+ <tt>BINDIR</tt> -- defaults to <tt>/usr/local/bin</tt>.
<tag><tt>client.tcl</tt></tag> A graphical client for <tt>ir-tk</tt>.
The client is installed as an executable script called <tt>irclient</tt> in
<tt>BINDIR</tt>. This client needs a number of files, bitmaps, etc.
The client looks for the files in the current directory &mdash if
this fails it tries to look in the directory <tt>IRTCLDIR</tt>
- — defaults to <tt>/usr/local/lib/irtcl</tt>.
+ -- defaults to <tt>/usr/local/lib/irtcl</tt>.
<tag><tt>libirtcl.a</tt></tag> The <sf/IrTcl/ library.
- Installed in <tt>LIBDIR</tt> — defaults to <tt>/usr/local/lib</tt>.
+ Installed in <tt>LIBDIR</tt> -- defaults to <tt>/usr/local/lib</tt>.
<tag><tt>ir-tcl.h</tt></tag> The <sf/IrTcl/ header file.
- Installed in <tt>INCDIR</tt> — defaults to <tt>/usr/local/include</tt>.
+ Installed in <tt>INCDIR</tt> -- defaults to <tt>/usr/local/include</tt>.
<tag><tt>clientrc.tcl</tt></tag> A setup file with definitions
of target and queries. Read and updated by <tt>client.tcl</tt>. Installed
- in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
+ in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
<tag><tt>formats/*</tt></tag> Display format files written
in Tk. Read by <tt>client.tcl</tt>. Installed
- in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
+ in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
<tag><tt>bitmaps/*</tt></tag> Various bitmap files. Read by
<tt>client.tcl</tt>. Installed
- in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
+ in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
<tag><tt>LICENSE</tt></tag> LICENSE file. Read by
<tt>client.tcl</tt>. Installed
- in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
+ in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
</descrip>
<sect1>ir-tcl
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 -- asking for 5 records from position 1.
Finally, a present response is received and the number of records
returned is stored in the variable <tt/ret/.
}
proc init-response {} {
- z.1 callback {search-response}
+ z callback {search-response}
z.1 search science
}
set hits [z.1 resultCount]
puts "$hits hits"
if {$hits > 0} {
- z.1 callback {present-response}
+ z callback {present-response}
z.1 present 1 5
}
}
<tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
Protocol type - ANSI/NISO Z39.50 or ISO SR.
<tag><tt>callback </tt><em>list</em></tag>
- Tcl script called when the connection is established
+ 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
+ closes connection.
</descrip>
If the connect is unsuccessful either the connect action itself
will return an error code or the failback handler is invoked.
+In general, the <tt>failback</tt> handler is invoked when serious
+unrecoverable errors occur when communicating with the target.
+In this case the <sf/IrTcl/ system shuts down the connection.
+The <tt>failback</tt> handler might inspect the <tt>failInfo</tt>
+setting to determine the cause of the failure; it returns
+two elements. The first is an error integer; the second is an
+english representation of the error. The error codes and
+the corresponding messages are:
+
+<descrip>
+<tag><tt>0</tt></tag>ok
+<tag><tt>1</tt></tag>connect failed
+<tag><tt>2</tt></tag>connection closed
+<tag><tt>3</tt></tag>connection closed
+<tag><tt>4</tt></tag>failed to decode incoming APDU
+<tag><tt>5</tt></tag>unknown APDU
+</descrip>
+
+Note: in case 3 the connection was closed during read a read operation
+whereas in case 4 it was closed during a write operation.
+
<sect1>Init
<p>
action is performed.
<tag><tt>protocolVersion </tt><em>integer</em></tag>
Protocol version: 2, 3, etc. Default is 2.
+<tag><tt>referenceId </tt><em>string</em></tag>
+ Reference-id of init operation. If <em>string</em> is empty no
+ reference-id is used.
<tag><tt>initResponse </tt><em>list</em></tag>
- Init-response Tcl script. Note: not implemented - use <tt>callback</tt>
- instead.
+ Init-response Tcl script.
<tag><tt>callback </tt><em>list</em></tag>
General response Tcl script. Only used if <tt>initResponse</tt>
is not specified.
below:
<descrip>
-<tag><tt>initResult </tt><em>boolean</em></tag>
+<tag><tt>initResult </tt>returns <em>boolean</em></tag>
Init response status. True if init operation was successful;
false otherwise.
-<tag><tt>preferredMessageSize </tt><em>integer</em></tag>
- Preferred-message-size.
-<tag><tt>maximumRecordSize </tt><em>integer</em></tag>
- Maximum-record-size.
-<tag><tt>targetImplementationName </tt><em>string</em></tag>
+<tag><tt>preferredMessageSize </tt>returns <em>integer</em></tag>
+ Preferred-message-size after negotiation.
+<tag><tt>maximumRecordSize </tt>returns <em>integer</em></tag>
+ Maximum-record-size after negotiation.
+<tag><tt>targetImplementationName </tt>returns <em>string</em></tag>
Implementation-name of target system.
-<tag><tt>targetImplementationId </tt><em>string</em></tag>
+<tag><tt>targetImplementationId </tt>returns <em>string</em></tag>
Implementation-id of target system.
-<tag><tt>targetImplementationVersion </tt><em>string</em></tag>
+<tag><tt>targetImplementationVersion </tt>returns <em>string</em></tag>
Implementation-version of target system.
-<tag><tt>options </tt><em>list</em></tag>
- Options negotiated in init. The list contains the options that are set.
-<tag><tt>protocolVersion </tt><em>integer</em></tag>
- Protocol version: 2, 3, etc.
-<tag><tt>userInformationField </tt><em>string</em></tag>
+<tag><tt>options </tt>returns <em>list</em></tag>
+ Options after negotiation. The list contains the options that are set.
+<tag><tt>protocolVersion </tt>returns <em>integer</em></tag>
+ Protocol version: 2, 3, etc after negotiation.
+<tag><tt>userInformationField </tt>returns <em>string</em></tag>
User information field.
+<tag><tt>referenceId </tt>returns <em>string</em></tag>
+ Reference-id of init response.
</descrip>
<bf/Example/
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 -- 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.
<descrip>
<tag><tt>databaseNames </tt><em>list</em></tag>
- database-names.
+ Database-names.
<tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
- small set upper bound. Default 0.
+ Small set upper bound. Default 0.
<tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
- large set lower bound. Default 2.
+ Large set lower bound. Default 2.
<tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
- medium set present number. Default 0.
+ Medium set present number. Default 0.
<tag><tt>replaceIndicator </tt><em>boolean</em></tag>
- replace-indicator.
+ Replace-indicator. Default true (1).
<tag><tt>setName </tt><em>string</em></tag>
- name of result set.
+ Name of result set.
<tag><tt>queryType rpn|ccl</tt></tag>
- query type-1 or query type-2
+ Query type-1 or query type-2. Default rpn (type-1).
<tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
- preferred record syntax — UNIMARC, USMARC, etc.
+ Preferred record syntax -- UNIMARC, USMARC, etc.
<tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
- small-set-element-set names. Not implemented yet.
+ small-set-element-set names. If <em>string</em> is empty
+ the element set is not set. Default is empty (not set).
<tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
- medium-set-element-set names. Not implemented yet.
+ medium-set-element-set names. If <em>string</em> is empty
+ the element set is not set. Default is empty (not set).
+<tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
+ Next result set position.
+<tag><tt>referenceId </tt><em>string</em></tag>
+ Reference-id. If <em>string</em> is empty no reference-id is used.
<tag><tt>searchResponse </tt><em>list</em></tag>
- Search-response Tcl script. Not implemented yet. Use <tt>callback</tt>
- instead.
+ Search-response Tcl script.
<tag><tt>callback </tt><em>list</em></tag>
- General response Tcl script. Only used if searchResponse is not specified
+ General response Tcl script. Only used if searchResponse is not specified.
+ This setting is valid only for the <tt/ir/ object -- not the
+ <tt/ir-set/ object.
</descrip>
Setting the <tt/databaseNames/ is mandatory. All other settings
should read some of the settings shown below:
<descrip>
-<tag><tt>searchStatus </tt><em>boolean</em></tag>
- search-status. True if search operation was successful; false
+<tag><tt>searchStatus</tt> returns <em>boolean</em></tag>
+ Search-status. True if search operation was successful; false
otherwise.
-<tag><tt>responseStatus </tt><em>list</em></tag>
- response status information.
-<tag><tt>resultCount </tt><em>integer</em></tag>
+<tag><tt>responseStatus </tt>returns <em>list</em></tag>
+ Response status information.
+<tag><tt>resultCount </tt>returns <em>integer</em></tag>
result-count
-<tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
- number of records returned.
+<tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
+ Number of records returned.
+<tag><tt>referenceId </tt>returns <em>string</em></tag>
+ Reference-id of search response.
</descrip>
The <tt/responseStatus/ signals one of three conditions which
target has returned one or more records. Each record may be
either a database record or a surrogate diagnostic.
-<tag><tt>OK</tt></tag> indicates a successful operation — no records are
+<tag><tt>OK</tt></tag> indicates a successful operation -- no records are
returned from the target.
</descrip>
ir-set ${assoc}.1 $assoc
$assoc.1 queryType rpn
$assoc.1 databaseNames base-a base-b
- $assoc.1 callback [list search-response $assoc ${assoc}.1]
+ $assoc callback [list search-response $assoc ${assoc}.1]
$assoc.1 search "@attr 1=4 @and @attr 5=1 tech beta"
}
</verb></tscreen>
<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 -- defaults to 1. The second integer
+is the number of records requested -- defaults to 10.
The settings which could be modified before a <tt/present/
action are:
<descrip>
<tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
- preferred record syntax — UNIMARC, USMARC, etc.
-<tag><tt>elementSetElementSetNames </tt><em>string</em></tag>
- element-set names
+ preferred record syntax -- UNIMARC, USMARC, etc.
+<tag><tt>elementSetNames </tt><em>string</em></tag>
+ Element-set names. If <em>string</em> is empty
+ the element set is not set. Default is empty (not set).
+<tag><tt>referenceId </tt><em>string</em></tag>
+ Reference-id. If <em>string</em> is empty no reference-id is used.
<tag><tt>presentResponse </tt><em>list</em></tag>
- Present-response Tcl script. Not implemented yet. Use <tt>callback</tt>
- instead.
+ Present-response Tcl script.
<tag><tt>callback </tt><em>list</em></tag>
General response Tcl script. Only used if presentResponse is not specified
+ This setting is valid only for the <tt/ir/ object -- not the
+ <tt/ir-set/ object.
</descrip>
The present-response handler should inspect the settings
target are stored in the result set object.
<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
+<tag><tt>presentStatus </tt>returns <em>boolean</em></tag>
+ Present-status.
+<tag><tt>responseStatus </tt>returns <em>list</em></tag>
+ Response status information.
+<tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
+ Number of records returned.
+<tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
+ Next result set position.
+<tag><tt>referenceId </tt>returns <em>string</em></tag>
+ Reference-id of present response.
</descrip>
<sect1>Records
one or more records stored in the ir set object if
the <tt/responseStatus/ setting indicates database or
surrogate diagnostics (<tt/DBOSD/). The individual
-records, indexed by an integer position, should be
+records, indexed by an integer position offset, should then be
inspected.
-The action <tt/type/ followed by an integer returns information
+If element set names have been specified either in the
+search requests (<tt>smallSetElementSetNames</tt> /
+<tt>mediumSetElementSetNames</tt>) or present requests
+(<tt>elementSetNames</tt>) the individual records in the
+ir set object are assigned appropriate element set ids.
+In this mode records at a given position are treated different as
+long as they have difference element set ids.
+To inspect records with a particular element set id in subsequent
+operations use the <tt>recordElements</tt> setting followed by the id.
+If you have more than one record at a given position and you do not
+use <tt>recordElements</tt> the record selected at the given position
+is undefined.
+
+The action <tt>type</tt> followed by an integer returns information
about a given position in an ir set. There are three possiblities:
<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.
+<tag><tt/DB/</tag> The item is a database record.
</descrip>
To handle the first case, surrogate diagnostic record, the
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
+In the second case, no record, note that there still might
+be a record at the position but with an id that differs from that
+specified by <tt>recordElements</tt>.
+
+In the third case, database record, the <tt/recordType/ action should
be used. It returns the record type at the given position.
Some record types are:
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 -- 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 -- only limited by the Tcl
language itself.
<bf/Example/
<p>
To perform scan, a scan object must be created by the <tt>ir-scan</tt>
-command. This command has two arguments - name of the scan object and
+command. This command has two arguments -- name of the scan object and
name of the ir object. Basically, the scan object, provides one <tt>scan</tt>
action which sends a scan request to the target. The <tt>action</tt>
is followed by a string describing starting point of the term list. The
<tag><tt>databaseNames </tt><em>list</em></tag>
Database names. Note that this setting is not (yet) supported for
the scan object. You must set this for the ir object instead.
+<tag><tt>referenceId </tt><em>string</em></tag>
+ Reference-id. If <em>string</em> is empty no reference-id is used.
+<tag><tt>scanResponse </tt><em>list</em></tag>
+ Scan-response Tcl script.
<tag><tt>callback </tt><em>list</em></tag>
- General response Tcl script. This setting is not (yet) supported for
- the scan object. You must set this for the ir object instead.
+ General response Tcl script. Only used if <tt>scanResponse</tt>
+ is not specified.
+ This setting is valid only for the <tt/ir/ object -- not the
+ <tt/ir-set/ object.
</descrip>
The scan object normally holds one or more scan line entries upon
that should be used in a response handler.
<descrip>
-<tag><tt>scanStatus</tt></tag>
+<tag><tt>scanStatus </tt>returns <em>integer</em></tag>
Scan status. An integer between 0 and 6.
-<tag><tt>numberOfTermsReturned </tt><em>integer</em></tag>
+<tag><tt>numberOfTermsReturned </tt>returns <em>integer</em></tag>
Number of terms returned.
-<tag><tt>positionOfTerm</tt></tag>
+<tag><tt>positionOfTerm </tt>returns <em>integer</em></tag>
An integer describing the position of term.
-<tag><tt>scanLine </tt> <em>integer</em></tag>
+<tag><tt>scanLine </tt>returns <em>list</em></tag>
This function returns information about a given scan line (entry) at a given
index specified by the integer. The first scan line is numbered zero;
the second 1 and so on. A list is returned by the <tt>scanLine</tt>
In the other case (surrogate diagnostic), the second element
is the diagnostic code, the third a text representation of the error
code and the fourth element is additional information.
+<tag><tt>referenceId </tt>returns <em>string</em></tag>
+ Reference-id of scan response.
</descrip>
<bf/Example/
<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</tt>
-and mirrors.
+0-201-63337-X). The Tcl/Tk toolkit home page is
+<tt><htmlurl url="http://www.sunlabs.com/research/tcl/"
+ name="http://www.sunlabs.com/research/tcl"></tt>.
+The primary ftp site is <tt><htmlurl url="ftp://ftp.smli.com/pub/tcl/"
+name="ftp://ftp.smli.com/pub/tcl/"></tt>.
+A mirror site can be found at <tt><htmlurl url="ftp://ftp.aud.alcatel.com/tcl/"
+name="ftp://ftp.aud.alcatel.com/tcl/"></tt>.
<tag>2 Furniss, Peter:</tag>
RFC 1698: Octet Sequences for Upper-Layer OSI to Support
Basic Communications Applications.
projects / ir-tcl-moved-to-github.git / blobdiff