<!doctype linuxdoc system>
<!--
- $Id: ir-tcl.sgml,v 1.9 1995-06-25 10:25:33 adam Exp $
+ $Id: ir-tcl.sgml,v 1.31 1999-12-10 10:36:13 adam Exp $
-->
<article>
-<title>IrTcl User's Guide and Reference
-<author>Index Data, <tt/info@index.ping.dk/
-<date>$Revision: 1.9 $
+<title>IrTcl User's Guide and Reference
+<author><htmlurl url="http://www.indexdata.dk/" name="Index Data">,
+<tt><htmlurl url="mailto:info@indexdata.dk" name="info@indexdata.dk"></tt>
+<date>$Revision: 1.31 $
<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/.
needed unless you wish to communicate within an OSI environment.
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
-testing purposes.
-<item> A system which operates within the Tk environment which
-makes it very easy to implement GUI clients.
-</itemize>
+<sf/IrTcl/ is usually build as a <it/dynamic/ library (WIN32)
+or shared Object (Unix) which is dynamically loaded by using the Tcl's
+<tt/load/ command. However, <sf/IrTcl/ can be compiled as a
+traditional <it/static/ library as well.
<sect>Compilation and installation
<p>
-In order to compile you need:
+<sect1>UNIX
+<p>
+In order to compile the software on UNIX you need:
<itemize>
<item> An ANSI C compiler such as GNU C.
-<item> Tcl 7.3.
-<item> YAZ version 1.0b or higher
+<item> <htmlurl url="http://www.scriptics.com" name="Tcl">.
+ Version 8.0 and 8.2 has been tested.
+<item> <htmlurl url="http://www.indexdata.dk/yaz/" name="YAZ">
+ version 1.5 or higher.
</itemize>
As an option you may want:
<itemize>
-<item> Tk 3.6.
-<item> XTI/mosi
+<item> <htmlurl url="http://www.scriptics.com" name="Tk">.
+Version 8.0 and 8.2 has been tested.
+<item> XTI/mOSI
</itemize>
-Newer versions of Tcl and Tk have been released. These packages
-will <em/not/ work with <sf/IrTcl/. The <sf/IrTcl/ package will
-probably be able to use the newer versions soon. Fortunately this
-move will not change the <sf/IrTcl/ API — only the Tk code of the
-test client will be modified.
-
-Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/.
+Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/.
Type:
<tscreen><verb>
This command tries to configure <sf/IrTcl/ for your system and creates
a <tt>Makefile</tt>.
-If the <tt>configure</tt> command cannot locate Tcl and Tk in your standard
-locations for libraries searched by your C compiler it will guess
-that the libraries are located in <tt>/usr/local/lib</tt> and that
-the header files are located in <tt>/usr/local/include</tt>.
-If this is incorrect you will have to modify the <tt>Makefile</tt> yourself.
+The <tt>configure</tt> command tries to locate the file <tt/tclConfig.sh/
+which should be generated by Tcl's installation script. Configure
+looks for ther Tcl shell on your system in order to locate this file.
+For example if <tt/tclsh/ is located in <tt>/home/joe/bin</tt>, configure will
+assume that <tt>tclConfig.sh</tt> is installed in <tt>/home/joe/lib</tt>,
+in which case the prefix is <tt>/home/joe</tt>. If you have
+more than one Tcl version installed on your system, or if configure
+cannot find the <tt/tclConfig.sh/, you can specify in which directory
+it is, by supplying option <tt>--with-tclconfig</tt> - for example:
+<tscreen><verb>
+$ ./configure --with-tclconfig=/home/joe/lib
+</verb></tscreen>
+
+The <sf/IrTcl/ executables are installed in prefix/bin and libraries
+and support files are installed in prefix/irtcl.
Compile <sf/IrTcl/ by typing:
<tscreen><verb>
$ make
</verb></tscreen>
-If you don't have Tk you will only be able to create the <tt>ir-tcl</tt>
-program and you must type <tt>make ir-tcl</tt> instead.
+For Tcl versions that support dynamic libraries the command above
+will create the shared library, <tt/irtcl.so/, as well as the
+normal static library, <tt/libirtcl.a/.
-If successful, this will make <tt>ir-tcl</tt>, <tt>ir-tk</tt> (if
-Tk is present) and a library called <tt>libirtcl.a</tt>.
+For Tcl versions that doesn't support dynamic libraries the
+make command will create two shells will build-in <sf/IrTcl/ support --
+a Tcl shell called <tt/ir-tcl/ and a Tcl/Tk shell called <tt/ir-tk/.
+The traditional static library, <tt/libirtcl.a/, is build as well.
To install the programs and support files type:
<tscreen><verb>
$ make install
</verb></tscreen>
+If you wish to install man pages type:
+<tscreen><verb>
+$ make install.man
+</verb></tscreen>
+
Summary of files installed (the names refer to the Makefile variables):
<descrip>
-<tag><tt>ir-tk</tt></tag> The Tk client. Installed in <tt>BINDIR</tt> —
-defaults to <tt>/usr/local/bin</tt>. When ir-tk starts it reads
-<tt>client.tcl</tt>. If the files doesn't exist in the current
-directory it tries to read it from <tt>IRTCLDIR</tt> - defaults
-to <tt>/usr/local/lib/irtcl</tt>.
-<tag><tt>ir-tcl</tt></tag> The Tcl client. Installed in <tt>BINDIR</tt> —
-defaults to <tt>/usr/local/bin</tt>.
+<tag><tt>irtcl.so</tt></tag> The <sf/IrTcl/ shared dynamic library.
+The actual name of this library vary. Installed in <tt>IRTCLDIR</tt>.
+This file is only generated when using newer versions of Tcl/Tk.
+
+<tag><tt>ir-tk</tt></tag> The <sf/IrTcl/ shell for Tk. This shell
+ is not needed when using a Tk version that supports shared libraries.
+ 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. This program
+ is not needed when using a Tcl that supports shared libraries. Installed
+ in <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>.
+
<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>.
-<tag><tt>client.tcl</tt></tag> A graphical client written in TK.
-Installed in <tt>IRTCLDIR</tt> — defaults to
-<tt>/usr/local/lib/irtcl</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>.
+ Installed in <tt>INCDIR</tt> -- defaults to <tt>/usr/local/include</tt>.
+
+<tag><tt>irtdb.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>.
+
<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 Tk. Read by <tt>client.tcl</tt>. Installed
+ 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>.
+ <tt>client.tcl</tt>. Installed
+ 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>.
+ <tt>client.tcl</tt>. Installed
+ in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
</descrip>
-<sect1>ir-tcl
+<p>
+Basic Tcl is handled by the program <tt/tclsh/. The script
+must use the <tt/load/ command to load the <sf/IrTcl/ dynamic
+library. If dynamic libraries are unsupported the <tt/ir-tcl/ program
+should be used instead, since that program is statically linked
+with the <sf/IrTcl/ library.
+So the static, non-dynamic, version goes like this:
+<tscreen><verb>
+ $ ir-tcl
+ %
+</verb></tscreen>
+and the dynamic version goes like:
+<tscreen><verb>
+ $ tclsh
+ % load ./irtcl.tcl
+ %
+</verb></tscreen>
+
+<sect1>WIN32
<p>
-The <tt>ir-tcl</tt> program is a shell like <tt>tclsh</tt> except that
-<tt>ir-tcl</tt> features the new set of information retrieval commands.
-Normally <tt>ir-tcl</tt> waits on <tt/stdin/ (for you to type commands) and
-on sockets events (connected to Z39.50/SR targets).
-You simply type the Tcl commands line by line. A filename may be specified as
-argument to <tt>ir-tcl</tt> in which case the file specified is evaluated
-as a script.
-<sect1>ir-tk
+<sf/IrTcl/ is shipped with a "makefile" for the NMAKE tool that comes
+with Visual C++.
+
+Start an MS-DOS prompt and switch the sub directory <tt>WIN</tt> where
+the file <tt>makefile</tt> is located. Customize the installation
+by editing the <tt>makefile</tt> file (for example by using wordpad).
+
+The following summarises the most important settings in that
+file.
+
+<descrip>
+<tag><tt>YAZDIR</tt></tag> Specifies where YAZ is located.
+<tag><tt>DEBUG</tt></tag> If set to 1, the software is
+compiled with debugging libraries. If set to 0, the software
+is compiled with release (non-debugging) libraries.
+</descrip>
+
+When satisfied with the settings in the makefile type
+<tscreen><verb>
+nmake
+</verb></tscreen>
+
+If compilation was successful the executables <tt>irtcl.dll</tt>
+is put in directory <tt>BIN</tt>.
+
+To start the test client that comes with <sf/IrTcl/ make sure
+both <tt/YAZ.DLL/ and <tt/IRTCL.DLL/ are in current directory
+or in your PATH. Go to the top-level directory of <sf/IrTcl/
+and type "wish -f client.tcl". You might want to make a
+short-cut to start this.
+
+<sect1>Using Tk
<p>
-<tt>ir-tk</tt> is a program which basically waits for X events and
-socket events (assocated with Z39.50/SR targets). <tt>ir-tk</tt> normally
-tries to evaluate the file named <tt>client.tcl</tt> when it
-starts. However, this behaviour may be changed by specifying another
-filename with the <tt>-file</tt> option.
-
-The enclosed script <tt>client.tcl</tt> is a graphical client which
-demonstates an example of a user interface for the Z39.50/SR protocols.
+If your Tcl/Tk supports dynamic libraries you can use the
+<tt/load/ command from within <tt/wish/ as described in the previous
+section.
+If not, you must use the <tt>ir-tk</tt> shell that acts as <tt>wish</tt>
+except that it includes the <sf/IrTcl/ commands.
+
+The enclosed script <tt>client.tcl</tt> is a graphical client
+which demonstates an example of a user interface for the Z39.50/SR protocols.
At first the script was relatively small but it has grown since the
-beginning. At present it is about 3000 lines.
+beginning. At present it is about 3000 lines.
+
+To start the client with dynamic library support use:
+<tscreen><verb>
+$ wish -f client.tcl
+</verb></tscreen>
+
+Note: Substitute the real name for the wish interpreter above, for
+version 8.0 it is probably called <tt/wish8.0/.
+
+To start the client without dynamic library support use:
+<tscreen><verb>
+$ ./ir-tk -f client.tcl
+</verb></tscreen>
The client lets up define targets and query types within the interface.
Hence, you will not need to modify configation files.
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/.
<tscreen><verb>
ir z
-ir-set z.1 z
z databaseNames books
+ir-set z.1 z
z callback {connect-response}
z connect fake.com
}
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.
Proximity operation on op1 and op2. Not implemented yet.
<tag><tt>@set </tt><em>name</em></tag>
Result set reference
+<tag><tt>@attrset </tt><em>set</em></tag>
+ Whole query uses the specified attribute <em>set</em>. If this operator is
+ used it must be defined at the beginning of the query.
</descrip>
It is simple to build RPN queries in <sf/IrTcl/. Search terms
@attr 1=4 @and @attr 5=1 tech beta
</verb></tscreen>
+To search for the DatabaseInfo records from an Explain server, we
+could use
+<tscreen><verb>
+ @attrset exp1 @attr 1=1 DatabaseInfo
+</verb></tscreen>
+
<sect1>Search
<p>
<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. Default name of set is <tt/default/.
<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/
<sect1>SUTRS
+<p>
In <sf/IrTcl/ a SUTRS record is treated as one single string. To retrieve
-a SUTRS string at a given index, the <tt>getSutrs</tt> should be used.
-The <tt>getSutrs</tt> is immediately followed by a index.
+a SUTRS record use the <tt>getSutrs</tt> followed by an index.
+
+<sect1>GRS-1
+<p>
+A GRS-1 record in <sf/IrTcl/ is represented as a list of elements.
+Each element specifies a tag as well as data. The data may
+be a subtree, which is represented as a list, and so on.
+
+The method <tt/getGrs/ is followed by a record index and
+optional specifiers that selects a specific sub-tree. Each element
+consists of 5 elements:
+
+<descrip>
+<tag>tag-set</tag> Tag set number.
+
+<tag>value-type</tag> Type of tag value. May be either
+<tt/numeric/ of <tt/string/.
+
+<tag>value</tag> The value it self.
+
+<tag>data-type</tag> May be either <tt/octets/, <tt/numeric/,
+<tt/ext/, <tt/string/, <tt/bool/, <tt/intUnit/, <tt/empty/,
+<tt/notRequested/, <tt/diagnostic/ or <tt/subtree/.
+
+<tag>data</tag>The data associated with element of given type as
+ indicated before. If data-type is <tt/numeric/ or <tt/string/
+ then data is encoded as a single Tcl token. The data-type <tt/bool/
+ is encoded as 0 or 1 for false and true respectively. If the
+ data-type is <tt/subtree/ the data is a sub-list.
+ In all other cases, the data is the empty string.
+</descrip>
+
+<bf/Example/
+
+Consider the GRS-1 record below as shown by the <bf/YAZ/ client program:
+
+<tscreen><verb>
+(1,1) OID: GILS-schema
+(1,14) 2
+(2,1) UTAH EARTHQUAKE EPICENTERS
+ class=4,type=1,value=us
+(4,52) UTAH GEOLOGICAL AND MINERAL SURVEY
+(3,Local-Subject-Index) APPALACHIAN VALLEY; EARTHQUAKE; EPICENTER
+(2,6)
+ (1,19) Five files of epicenter data arranged by ...
+ (3,Format) DIGITAL DATA SETS
+ (3,Data-Category) TERRESTRIAL
+ (3,Comments) Data are supplied by the University of Utah ...
+(4,70)
+ (4,90)
+ (2,10) UTAH GEOLOGICAL AND MINERAL SURVEY
+ (4,2) 606 BLACK HAWK WAY
+ (4,3) SALT LAKE CITY
+ (3,State) UT
+ (3,Zip-Code) 84108
+ (2,16) USA
+ (2,14) (801) 581-6831
+ (4,7) UTAH EARTHQUAKE EPICENTERS
+(4,1) ESDD0006
+(1,16) 198903
+</verb></tscreen>
+
+The record may be fetched from the result set, <tt/z.1/, at position 1
+by using:
+<tscreen><verb>
+z.1 getGrs 1
+</verb></tscreen>
+which will return:
+<tscreen><verb>
+{ 1 numeric 1 oid 1.2.840.10003.13.2 }
+{ 1 numeric 14 string 2 }
+{ 2 numeric 1 string
+ { UTAH EARTHQUAKE EPICENTERS} }
+{ 4 numeric 52 string {UTAH GEOLOGICAL AND MINERAL SURVEY} }
+{ 3 string Local-Subject-Index string
+ {APPALACHIAN VALLEY; EARTHQUAKE; EPICENTER} }
+{ 2 numeric 6 subtree
+ { { 1 numeric 19 string
+ {Five files of epicenter data arranged by ...} }
+ { 3 string Format string {DIGITAL DATA SETS} }
+ { 3 string Data-Category string TERRESTRIAL }
+ { 3 string Comments string
+ {Data are supplied by the University of Utah ...} } } }
+{ 4 numeric 70 subtree
+ { { 4 numeric 90 subtree
+ { { 2 numeric 10 string
+ {UTAH GEOLOGICAL AND MINERAL SURVEY} }
+ { 4 numeric 2 string {606 BLACK HAWK WAY} }
+ { 4 numeric 3 string {SALT LAKE CITY} }
+ { 3 string State string UT }
+ { 3 string Zip-Code string 84108 }
+ { 2 numeric 16 string USA }
+ { 2 numeric 14 string {(801) 581-6831} } } }
+ { 4 numeric 7 string {UTAH EARTHQUAKE EPICENTERS} } } }
+{ 4 numeric 1 string ESDD0006 }
+{ 1 numeric 16 string 198903 }
+</verb></tscreen>
+
+We can choose only to get the path (2,6) by using:
+
+<tscreen><verb>
+z.1 getGrs 1 (2,6)
+</verb></tscreen>
+and we'll get:
+<tscreen><verb>
+{ 2 numeric 6 subtree { { 1 numeric 19 string
+ {Five files of epicenter data arranged by ...} }
+ { 3 string Format string {DIGITAL DATA SETS} }
+ { 3 string Data-Category string TERRESTRIAL }
+ { 3 string Comments
+ string {Data are supplied by the University of Utah ...} } } }
+</verb></tscreen>
+
+To get the well known (1,19) within the subject (2,6) we use
+<tscreen><verb>
+z.1 getGrs 1 (2,6) (1,19)
+</verb></tscreen>
+and get:
+<tscreen><verb>
+{ 2 numeric 6 subtree
+ { { 1 numeric 19 string
+ {Five files of epicenter data arranged by ...} } } }
+</verb></tscreen>
+<bf/End of example/
+
+<sect1>Explain
+<p>
+Explain records are retrieved like other records. The method,
+<tt>getExplain</tt> is followed by an index and and an optional
+Explain record pattern.
+
+The returned record is a canonical representation of the Explain record.
+An ASN.1 sequence is represented as a list. Each item in the list
+consists of the name of the element, followed by its value if the value
+is supplied.
+
+The optional pattern that follows the index after <tt>getExplain</tt>
+consists of one or more elements, that is matched against the elements
+of the actual record.
+
+<bf/Example/
+
+One of the few targets that support explain is the ATT research server
+at <tt>z3950.research.att.com</tt>.
+
+The targetInfo record was returned by the target and it's stored in
+position 1 in the result set, <tt>z.1</tt>. To retrieve the whole
+record we must use
+<tscreen><verb>
+z.1 getExplain 1
+</verb></tscreen>
+
+and we get in return
+
+<tscreen><verb>
+{targetInfo commonInfo {name {Lucent Technologies Research Server}}
+recentNews icon {namedResultSets 1} {multipleDBsearch 0}
+{maxResultSets 100} {maxResultSize 600000} maxTerms timeoutInterval
+{welcomeMessage {strings { {language eng}
+{text
+{Salutations - this is Lucent Technologies experimental Z39.50 server.
+No guarentees, but free and unlimited access!}} } } }
+{contactInfo {name {Robert Waldstein}} {description {strings
+{ {language eng}
+{text {Librarian system designer - no legal anythings}} } } }
+{address {strings { {language eng} {text {Room 3D-591
+600 Mountain Ave
+Murray Hill
+N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}} }
+description nicknames {usageRest {strings { {language eng}
+{text {None - as long as nonProfit research}} } } } paymentAddr
+{hours {strings { {language eng} {text {Should never be down}} } } }
+dbCombinations addresses commonAccessInfo }
+</verb></tscreen>
+
+The <tt>targetInfo</tt> above indicates the the record is really a
+<tt>targetInfo</tt> record. The <tt>commonInfo</tt>, which is optional, is
+not supplied by this server. The <tt>name</tt>, however is supplied,
+with the value <tt>Lucent Technologies Research Server</tt>.
+
+To retrieve the <tt>contactInfo</tt> from the record above we can
+extract the element from the record by using Tcl's list manipulation
+facilities, for example by doing
+<tscreen><verb>
+set ti [z.1 getExplain 1]
+lindex [lindex $ti 0] 12
+</verb></tscreen>
+which will return
+<tscreen><verb>
+contactInfo {name {Robert Waldstein}} {description {strings
+{ {language eng}
+{text {Librarian system designer - no legal anythings}} }
+} } {address {strings { {language eng} {text {Room 3D-591
+600 Mountain Ave
+Murray Hill
+N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}}
+</verb></tscreen>
+
+We can also extract almost the same by doing
+<tscreen><verb>
+z.1 getExplain 1 targetInfo contactInfo
+</verb></tscreen>
+which will return
+<tscreen><verb>
+{name {Robert Waldstein}} {description {strings { {language eng}
+{text {Librarian system designer - no legal anythings}} } } }
+{address {strings { {language eng} {text {Room 3D-591
+600 Mountain Ave
+Murray Hill
+N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}}
+</verb></tscreen>
+
+<bf/End of example/
<sect>Scan
<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/
<sect>License
<p>
-Copyright © 1995, Index Data.
+Copyright © 1995-1999, 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,
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>
-
+<tscreen><verb>
+Index Data
+Ryesgade 3
+2200 Copenhagen N
+Denmark
+</verb></tscreen>
<p>
<tscreen><verb>
Phone: +45 3536 3672
Fax : +45 3536 0449
-Email: info@index.ping.dk
+Email: info@indexdata.dk
</verb></tscreen>
<sect>References
<p>
<descrip>
-<tag>1 Ousterhout, John K.:</tag>
+<tag>1 IrTcl Homepage</tag>
+<htmlurl url="http://www.indexdata.dk/irtcl/"
+name="http://www.indexdata.dk/irtcl/">
+
+<tag>2 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.
-<tag>2 Furniss, Peter:</tag>
-RFC 1698: Octet Sequences for Upper-Layer OSI to Support
-Basic Communications Applications.
+0-201-63337-X). The Tcl/Tk toolkit home page is
+<htmlurl url="http://www.scriptics.com"
+ name="http://www.scriptics.com">.
+The primary download area is
+<htmlurl url="http://www.scriptics.com/software/download.html"
+name="http://www.scriptics.com/software/download.html">.
+
+<tag>3 Welch, Brent B.:</tag>
+Practical Programming in Tcl and Tk. Prentice Hall
+(ISBN 0-13-616830-2).
+
</descrip>
</article>
projects / ir-tcl-moved-to-github.git / blobdiff