<!doctype linuxdoc system>
<!--
- $Id
+ $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>May 1995
+<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>
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 -- 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:
+<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>
+<sect1>UNIX
+<p>
+In order to compile the software on UNIX you need:
+<itemize>
+<item> An ANSI C compiler such as GNU C.
+<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> 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.
+<item> <htmlurl url="http://www.scriptics.com" name="Tk">.
+Version 8.0 and 8.2 has been tested.
+<item> XTI/mOSI
</itemize>
-<sect>Overview
+Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/.
+
+Type:
+<tscreen><verb>
+$ ./configure
+</verb></tscreen>
+
+This command tries to configure <sf/IrTcl/ for your system and creates
+a <tt>Makefile</tt>.
+
+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>
+
+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/.
+
+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>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>.
+
+<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>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>.
+
+<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>.
+
+<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>.
+</descrip>
+
+<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>
+
+<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>
+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.
+
+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.
+
+Stuff concerning targets can be found in the pull down menu 'Target'
+with the following options:
+<descrip>
+<tag>Connect</tag> Establishes connection to a target.
+<tag>Disconnect</tag> Closes a target connection.
+<tag>About</tag> Shows implementation Id, implementation Version, etc
+ for the current target.
+<tag>Setup</tag> Pops up a target definition window. You may alter
+ a target definition.
+<tag>Setup new</tag> Lets you define a new target.
+</descrip>
+
+The term query type refers to a collection of search fields. The
+pull down menu Options|Query deals with queries. You may
+insert/modify/remove query types.
+
+<sect>Overview of the API
<p>
Basically, <sf/IrTcl/ is a set of commands introduced to Tcl.
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 -- 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
+ir-set z.1 z
+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}
+ 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
}
}
<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. A number of settings affect the
+<tt/connect/ action. Obviously, these settings should be set
+<bf/before/ connecting. The settings 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
+ Comstack type.
+<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.
<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>
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>
- Preferred-message-size
+ Preferred-message-size. Default value is 30000.
<tag><tt>maximumRecordSize </tt><em>integer</em></tag>
- Maximum-record-size
-<tag><tt>idAuthentication </tt><em>string</em></tag>
- Id-authentication
+ Maximum-record-size. Default value is 30000.
+<tag><tt>idAuthentication </tt><em>string</em> ...</tag>
+ Id-authentication. There are three forms. If any empty is
+ given, the Id-authentication is not used. If one non-empty string
+ is given, the 'open' authentication is used. If three strings are
+ specified, the version 'id-pass' authentication (version 3 only)
+ is used in which case the first string is groupId; the second string
+ is userId and the third string is password.
<tag><tt>implementationName </tt><em>string</em></tag>
- Implementation-name of origin system
-<tag><tt>implementationId </tt><em>string</em></tag>
- Implementation-id of origin system
+ Implementation-name of origin system.
+<tag><tt>implementationId</tt></tag>
+ Implementation-id of origin system. This setting is read-only.
+<tag><tt>implementationVersion</tt></tag>
+ Implementation-version of origin system. This settings is read-only.
<tag><tt>options </tt><em>list</em></tag>
- Options to be negotiated in init. The list contains the options that
-are set.
+ Options to be negotiated in the init service. The list contains
+ the options that are set. Possible values are <tt>search</tt>,
+ <tt>present</tt>, <tt>delSet</tt>, <tt>resourceReport</tt>,
+ <tt>triggerResourceCtrl</tt>, <tt>resourceCtrl</tt>,
+ <tt>accessCtrl</tt>, <tt>scan</tt>, <tt>sort</tt>,
+ <tt>extendedServices</tt>, <tt>level-1Segmentation</tt>,
+ <tt>level-2Segmentation</tt>, <tt>concurrentOperations</tt> and
+ <tt>namedResultSets</tt>. Currently the default options are:
+ <tt>search</tt>, <tt>present</tt>, <tt>scan</tt> and
+ <tt>namedResultSets</tt>. The <tt>options</tt> setting is set to its default
+ value when an ir object is created and when a <tt>disconnect</tt>
+ action is performed.
<tag><tt>protocolVersion </tt><em>integer</em></tag>
- Protocol version: 2, 3, etc.
+ 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
+ Init-response Tcl script.
<tag><tt>callback </tt><em>list</em></tag>
- General response Tcl script. Only used if initResponse is not specified
+ General response Tcl script. Only used if <tt>initResponse</tt>
+ 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>
- Init response status
-<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>
- Implementation-name of target system
-<tag><tt>targetImplementationId </tt><em>string</em></tag>
- Implementation-id of target system
-<tag><tt>targetImplementationVersion </tt><em>string</em></tag>
- Implementation-version of target system
-<tag><tt>options </tt><em>list</em></tag>
- Options negotiated after 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>
- User information field
+<tag><tt>initResult </tt>returns <em>boolean</em></tag>
+ Init response status. True if init operation was successful;
+ false otherwise.
+<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>returns <em>string</em></tag>
+ Implementation-id of target system.
+<tag><tt>targetImplementationVersion </tt>returns <em>string</em></tag>
+ Implementation-version of target system.
+<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/
+
Consider a client with the ability to access multiple targets.
We define a list of targets that we wish to connect to.
The list for the two targets: ISO/SR target DANBIB and TCP/Z39.50
target Data Research, will be defined as:
<tscreen><verb>
-set targetList { {danbib mosi sr 0103/find2.denet.dk:4500}
- {drs tcpip z39 dranet.dra.com} }
+set targetList { {danbib mosi SR 0103/find2.denet.dk:4500}
+ {drs tcpip Z39 dranet.dra.com} }
</verb></tscreen>
The Tcl code below defines, connect and initialize the
targets in <tt/targetList/:
<tscreen><verb>
-\foreach target $targetList {
+foreach target $targetList {
set assoc [lindex $target 0]
ir $assoc
$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]
- $assoc initResponse [list init-response $assoc]
+}
+
+proc connect-response {assoc} {
+ $assoc callback [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.
After the connect operation, the <tt/init-response/ handler
is defined in much the same way as the failback handler.
And, finally, an init request is executed.
+
<bf/End of example/
<sect1>Disconnect
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.
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
+<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>
-Table ref{tab:irsearchrequest} lists settings that affect the search.
-Setting the <tt/databaseNames/ is mandatory. All other settings
-have reasonable defaults.
+The settings that affect the search are listed below:
-</article>
-
-\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. Default 0.
+<tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
+ Large set lower bound. Default 2.
+<tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
+ Medium set present number. Default 0.
+<tag><tt>replaceIndicator </tt><em>boolean</em></tag>
+ Replace-indicator. Default true (1).
+<tag><tt>setName </tt><em>string</em></tag>
+ 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. Default rpn (type-1).
+<tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
+ Preferred record syntax -- UNIMARC, USMARC, etc.
+<tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
+ 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. 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.
+<tag><tt>callback </tt><em>list</em></tag>
+ 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
+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> returns <em>boolean</em></tag>
+ Search-status. True if search operation was successful; false
+ otherwise.
+<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>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
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 -- 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:
ir-set ${assoc}.1 $assoc
$assoc.1 queryType rpn
$assoc.1 databaseNames base-a base-b
- $assoc.1 searchResponse [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>
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]
...
}
<tt/searchStatus/) to determine whether the search was successful or not,
because the standard specifies that one or more non-surrogate
diagnostics should be returned by the target in case of errors.
+
<bf/End of example/
If one or more records are returned from the target they
<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 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 -- 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.
+<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
-shown in table ref{tab:irpresentresponse}.
+shown in table below.
Note that <tt/responseStatus/ and <tt/numberOfRecordsReturned/
settings were also used in the search-response case.
-As in the search-response case, records returned from the
+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>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:
-<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><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, 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
+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 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]
+ } elseif {$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/
<sect1>MARC records
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/
+
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.
needed if a result-set must be updated by a Tcl modified (user-edited)
record.
+<sect1>SUTRS
+
+<p>
+In <sf/IrTcl/ a SUTRS record is treated as one single string. To retrieve
+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>
-<em/To be written/
+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
+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
+format used is a simple subset of the query used in search requests. Only
+<tt>@attr</tt> specifications and simple terms are allowed.
+The settings that affect the scan are:
+
+<descrip>
+<tag><tt>stepSize </tt><em>integer</em></tag>
+ Step size. Default is 0.
+<tag><tt>numberOfTermsRequested </tt><em>integer</em></tag>
+ Number of terms requested. Default is 20.
+<tag><tt>preferredPositionInResponse </tt><em>integer</em></tag>
+ Preferred position in response. Default is 1.
+<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. 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
+successful completion. The table below summarizes the settings
+that should be used in a response handler.
+
+<descrip>
+<tag><tt>scanStatus </tt>returns <em>integer</em></tag>
+ Scan status. An integer between 0 and 6.
+<tag><tt>numberOfTermsReturned </tt>returns <em>integer</em></tag>
+ Number of terms returned.
+<tag><tt>positionOfTerm </tt>returns <em>integer</em></tag>
+ An integer describing the position of term.
+<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>
+ setting. The first element is <tt>T</tt> if the scan line
+ is a normal term and <tt>SD</tt> if the scan line is a surrogate
+ diagnostic. In the first case (normal) the scan term is second element
+ in the list and the number of occurences is the third element.
+ 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/
+
+We will scan for the terms after <tt>science</tt> in the Title index.
+We will assume that an ir object called <tt>z-assoc</tt> has already
+been created.
+
+<tscreen><verb>
+ z-assoc callback {scan-response}
+ ir-scan z-scan z-assoc
+ z-scan scan "@attr 1=4 science"
+
+ proc scan-response {} {
+ set status [z-scan status]
+ if {$status == 0} {
+ set no [z-scan numberOfTermsReturned]
+ for {set i 0} {$i < $no} {incr i} {
+ set line [z-scan scanLine $i]
+ set type [lindex $line 0]
+ if {$type == "T"} {
+ puts [lindex $line 1]
+ } elseif {$type == "SD"} {
+ puts [lindex $line 1]
+ }
+ }
+ }
+ }
+</verb></tscreen>
+<bf/End of examle/
+
+<sect>License
+
+<p>
+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,
+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.
-\appendix
-\pagebreak
+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><verb>
+Index Data
+Ryesgade 3
+2200 Copenhagen N
+Denmark
+</verb></tscreen>
+<p>
+<tscreen><verb>
+Phone: +45 3536 3672
+Fax : +45 3536 0449
+Email: info@indexdata.dk
+</verb></tscreen>
<sect>References
<p>
-\label{sec:references}
-<itemize>
-<item> <bf/Ousterhout, John K./:
+<descrip>
+<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/
-and mirrors.
-<item> <bf/Furniss, Peter/:
-RFC 1698: Octet Sequences for Upper-Layer OSI to Support
-Basic Communications Applications.
-</itemize>
+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