<!doctype linuxdoc system>
<!--
- $Id
+ $Id: ir-tcl.sgml,v 1.11 1995-06-30 12:39:49 adam Exp $
-->
<article>
<title>IrTcl User's Guide and Reference
<author>Index Data, <tt/info@index.ping.dk/
-<date>May 1995
+<date>$Revision: 1.11 $
<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:
<itemize>
-<item> A simple command line shell --- useful for
+<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> A simple command line shell which operates within the Tk
+ environment — makes it very easy to implement GUI clients.
</itemize>
-<sect>Overview
+<sect>Compilation and installation
+
+<p>
+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.0b or higher
+</itemize>
+
+As an option you may want:
+<itemize>
+<item> Tk. Version 3.6 and 4.0b4 has been tested.
+<item> XTI/mosi
+</itemize>
+
+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>.
+
+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.
+
+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.
+
+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>.
+
+To install the programs and support files type:
+<tscreen><verb>
+$ make install
+</verb></tscreen>
+
+Summary of files installed (the names refer to the Makefile variables):
+
+<descrip>
+<tag><tt>ir-tk</tt></tag> The <sf/IrTcl/ shell for Tk.
+ 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>.
+<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>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>.
+<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>
+
+<sect1>ir-tcl
+
+<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
+
+<p>
+<tt>ir-tk</tt> is a program that works like <tt>wish</tt> except that
+<tt>ir-tk</tt> include the new set of commands. All options accepted
+by <tt>wish</tt> are also accepted by <tt>ir-tk</tt>.
+
+The enclosed script <tt>client.tcl</tt> for <tt>ir-tk</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.
+
+The client can be started directly from the top level directory
+of <sf/IrTcl/ by typing:
+<tscreen><verb>
+$ ir-tk -f client.tcl
+</verb></tscreen>
+
+Or, if you have installed <sf/IrTcl/ you may also type:
+<tscreen><verb>
+$ irclient
+</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}
<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
</descrip>
+If the connect is unsuccessful either the connect action itself
+will return an error code or the failback handler is invoked.
+
<sect1>Init
<p>
If the connect operation succeeds the <tt/init/ action should be used.
-Table ref{tab:irinit} lists the init related settings.
+The init related settings are:
<descrip>
<tag><tt>preferredMessageSize </tt><em>integer</em></tag>
- 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>initResponse </tt><em>list</em></tag>
- Init-response Tcl script
+ Init-response Tcl script. Note: not implemented - use <tt>callback</tt>
+ instead.
<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
+ Init response status. True if init operation was successful;
+ false otherwise.
<tag><tt>preferredMessageSize </tt><em>integer</em></tag>
- Preferred-message-size
+ Preferred-message-size.
<tag><tt>maximumRecordSize </tt><em>integer</em></tag>
- Maximum-record-size
+ Maximum-record-size.
<tag><tt>targetImplementationName </tt><em>string</em></tag>
- Implementation-name of target system
+ Implementation-name of target system.
<tag><tt>targetImplementationId </tt><em>string</em></tag>
- Implementation-id of target system
+ Implementation-id of target system.
<tag><tt>targetImplementationVersion </tt><em>string</em></tag>
- Implementation-version of target system
+ 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.
+ 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>
- User information field
+ User information field.
</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
</descrip>
It is simple to build RPN queries in <sf/IrTcl/. Search terms
<sect1>Search
<p>
-Table ref{tab:irsearchrequest} lists settings that affect the search.
-Setting the <tt/databaseNames/ is mandatory. All other settings
-have reasonable defaults.
-
-</article>
+The settings that affect the search are listed below:
-\begin{table}[htbf]
-\begin{tabular}{l|l|p{8cm}}
-Setting & Value & Description \\\hline
-databaseNames & list & database-names \\
-smallSetUpperBound & integer & small set upper bound \\
-largeSetLowerBound & integer & large set lower bound \\
-mediumSetPresentNumber & integer & medium set present number \\
-replaceIndicator & boolean & replace-indicator \\
-setName & string & name of result set \\
-queryType & rpn & query type-1 \\
- & ccl & query type-2 \\
-preferredRecordSyntax & string & preferred record syntax.
-See table ref{tab:recordtypes} on page \pageref{tab:recordtypes} \\
-smallSetElementSetNames & string & small-set-element-set names \\
-mediumSetElementSetNames & string & medium-set-element-set names \\
-searchResponse & list & Search-response Tcl script \\
-callback & list & General response Tcl script. Only used
-if searchResponse is not specified \\
-\end{tabular}
-\caption{Search request settings}
-\label{tab:irsearchrequest}
-\end{table}
+<descrip>
+<tag><tt>databaseNames </tt><em>list</em></tag>
+ database-names.
+<tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
+ small set upper bound. 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.
+<tag><tt>setName </tt><em>string</em></tag>
+ name of result set.
+<tag><tt>queryType rpn|ccl</tt></tag>
+ query type-1 or query type-2
+<tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
+ preferred record syntax — UNIMARC, USMARC, etc.
+<tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
+ small-set-element-set names. Not implemented yet.
+<tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
+ medium-set-element-set names. Not implemented yet.
+<tag><tt>searchResponse </tt><em>list</em></tag>
+ Search-response Tcl script. Not implemented yet. Use <tt>callback</tt>
+ instead.
+<tag><tt>callback </tt><em>list</em></tag>
+ General response Tcl script. Only used if searchResponse is not specified
+</descrip>
+Setting the <tt/databaseNames/ is mandatory. All other settings
+have reasonable defaults.
The search-response handler, specified by the <tt/callback/ - or
the <tt/searchResponse/ setting,
-should read some of the settings shown in table ref{tab:irsearchresponse}.
-
-\begin{table}[htbf]
-\begin{tabular}{l|l|p{8cm}}
-Setting & Value & Description \\\hline
-searchStatus & boolean & search-status \\
-responseStatus & list & response status information \\
-resultCount & integer & result-count \\
-numberOfRecordsReturned & integer & number of records retrieved \\
-\end{tabular}
-\caption{Search response settings}
-\label{tab:irsearchresponse}
-\end{table}
+should read some of the settings shown below:
+
+<descrip>
+<tag><tt>searchStatus </tt><em>boolean</em></tag>
+ search-status. 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>
+ result-count
+<tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
+ number of records returned.
+</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.1 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>elementSetElementSetNames </tt><em>string</em></tag>
+ element-set names
+<tag><tt>presentResponse </tt><em>list</em></tag>
+ Present-response Tcl script. Not implemented yet. Use <tt>callback</tt>
+ instead.
+<tag><tt>callback </tt><em>list</em></tag>
+ General response Tcl script. Only used if presentResponse is not specified
+</descrip>
The present-response handler should inspect the settings
-shown in table ref{tab:irpresentresponse}.
+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><em>boolean</em></tag>
+ present-status
+<tag><tt>responseStatus </tt><em>list</em></tag>
+ Response status information
+<tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
+ number of records returned
+<tag><tt>nextResultSetPosition </tt><em>integer</em></tag>
+ next result set position
+</descrip>
<sect1>Records
records, indexed by an integer position, should be
inspected.
-The action <tt/Type/ followed by an integer returns information
+The action <tt/type/ followed by an integer returns information
about a given position in an ir set. There are three possiblities:
-<itemize>
-<item> SD The item is a surrogate diagnostic.
-<item> DB The item is a database record.
-<item> <em/empty/ There is no record at the specified position.
-</itemize>
+<descrip>
+<tag><tt/SD/</tag> The item is a surrogate diagnostic record.
+<tag><tt/DB/</tag> The item is a database record.
+<tag><em/empty/</tag> There is no record at the specified position.
+</descrip>
-To handle the first case, surrogate diagnostic, the
+To handle the first case, surrogate diagnostic record, the
<tt/Diag/ action should be used. It returns three
items: error code (integer), text representation in plain english
(string), and additional information (string, possibly empty).
In the second case, database record, the <tt/recordType/ action should
be used. It returns the record type at the given position.
-Some record types are shown in table ref{tab:recordtypes}.
-
-\begin{table}[htbf]
-\begin{center}
-\begin{tabular}{c}
-Type \\\hline
-UNIMARC \\
-INTERMARC \\
-CCF \\
-USMARC \\
-UKMARC \\
-NORMARC \\
-LIBRISMARC \\
-DANMARC \\
-FINMARC \\
-SUTRS \\
-\end{tabular}
-\end{center}
-\caption{Record types}
-\label{tab:recordtypes}
-\end{table}
+Some record types are:
+
+<tscreen>
+UNIMARC
+INTERMARC
+CCF
+USMARC
+UKMARC
+NORMARC
+LIBRISMARC
+DANMARC
+FINMARC
+SUTRS
+</tscreen>
<bf/Example/
+
We continue our search-response example. In the case,
<tt/DBOSD/, we should inspect the result set items.
Recall that the ir set name was passed to the
search-response handler as argument <tt/rset/.
<tscreen><verb>
- if {$type == DBOSD} {
+ if {$type == "DBOSD"} {
set ret [$rset numberOfRecordsReturned]
for {set i 1} {$i<=$ret} {incr i} {
- set itype [$rset Type $i]
- if {$itype == SD} {
+ set itype [$rset type $i]
+ if {$itype == "SD"} {
set diag [$rset Diag $i]
set code [lindex $diag 0]
set msg [lindex $diag 1]
set addinfo [lindex $diag 2]
puts "$i: NSD $code: $msg: $addinfo"
- } else if {$itype == DB} {
- set rtype [$rset RecordType $i]
+ } 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.
+
<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:
-\appendix
-\pagebreak
+<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>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.
+</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></tag>
+ Scan status. An integer between 0 and 6.
+<tag><tt>numberOfTermsReturned </tt><em>integer</em></tag>
+ Number of terms returned.
+<tag><tt>positionOfTerm</tt></tag>
+ An integer describing the position of term.
+<tag><tt>scanLine </tt> <em>integer</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.
+</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, Index Data.
+
+Permission to use, copy, modify, distribute, and sell this software and
+its documentation, in whole or in part, for any purpose, is hereby granted,
+provided that:
+
+1. This copyright and permission notice appear in all copies of the
+software and its documentation. Notices of copyright or attribution
+which appear at the beginning of any file must remain unchanged.
+
+2. The names of Index Data or the individual authors may not be used to
+endorse or promote products derived from this software without specific
+prior written permission.
+
+THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
+EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
+WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
+INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
+NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
+LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+OF THIS SOFTWARE.
+
+<sect>About Index Data
+
+<p>
+Index Data is a consulting and software-development enterprise that
+specialises in library and information management systems. Our
+interests and expertise span a broad range of related fields, and one
+of our primary, long-term objectives is the development of a powerful
+information management
+system with open network interfaces and hypermedia capabilities.
+
+We make this software available free of charge, on a fairly unrestrictive
+license; as a service to the networking community, and to further the
+development of quality software for open network communication.
+
+We'll be happy to answer questions about the software, and about ourselves
+in general.
+
+<tscreen>
+Index Data&nl
+Ryesgade 3&nl
+2200 København N&nl
+DENMARK
+</tscreen>
+
+<p>
+<tscreen><verb>
+Phone: +45 3536 3672
+Fax : +45 3536 0449
+Email: info@index.ping.dk
+</verb></tscreen>
<sect>References
<p>
-\label{sec:references}
-<itemize>
-<item> <bf/Ousterhout, John K./:
+<descrip>
+<tag>1 Ousterhout, John K.:</tag>
Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
0-201-63337-X). Source and documentation
-can be found in <tt/URL:ftp://ftp.cs.berkeley.edu/pub/tcl/
+can be found in <tt>URL:ftp://ftp.cs.berkeley.edu/pub/tcl</tt>
and mirrors.
-<item> <bf/Furniss, Peter/:
+<tag>2 Furniss, Peter:</tag>
RFC 1698: Octet Sequences for Upper-Layer OSI to Support
Basic Communications Applications.
-</itemize>
+</descrip>
</article>