<!doctype linuxdoc system>
<!--
- $Id: ir-tcl.sgml,v 1.5 1995-05-30 10:59:20 adam Exp $
+ $Id: ir-tcl.sgml,v 1.10 1995-06-26 10:20:45 adam Exp $
-->
<article>
<title>IrTcl User's Guide and Reference
<author>Index Data, <tt/info@index.ping.dk/
-<date>$Revision: 1.5 $
+<date>$Revision: 1.10 $
<abstract>
-This document describes IrTcl &mdash 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 &mdash A Motif look-and-feel interface to the X window
+probably Tk — A Motif look-and-feel interface to the X window
system.
To interface the Z39.50/SR protocol <sf/IrTcl/ uses <bf/YAZ/.
<sf/IrTcl/ provides two system environments:
<itemize>
-<item> A simple command line shell &mdash 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 7.3.
+<item> YAZ version 1.0b or higher
+</itemize>
+
+As an option you may want:
+<itemize>
+<item> Tk 3.6.
+<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/.
+
+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.
+
+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 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.
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 &mdash 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/.
<p>
A connection is established by the <tt/connect/ action which is
-immediately followed by a hostname. Obviously, these settings should
-be set <bf/before/ connecting.
-The settings that affect the <tt/connect/ action are:
+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>
<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 shown
<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/
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]
}
proc connect-response {assoc} {
- $assoc initResponse [list init-response $assoc]
+ $assoc callback [list init-response $assoc]
$assoc init
}
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 &mdash an ir
+the second, which is optional, is the name of an assocation — an ir
object. The second argument is required if the ir set object should be able
to perform searches and presents. However, it is not required if
only ``local'' operations is done with the ir set object.
<descrip>
<tag><tt>databaseNames </tt><em>list</em></tag>
- database-names
+ database-names.
<tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
- small set upper bound
+ small set upper bound. Default 0.
<tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
- large set lower bound
+ large set lower bound. Default 2.
<tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
- medium set present number
+ medium set present number. Default 0.
<tag><tt>replaceIndicator </tt><em>boolean</em></tag>
- replace-indicator
+ replace-indicator.
<tag><tt>setName </tt><em>string</em></tag>
- name of result set
+ name of result set.
<tag><tt>queryType rpn|ccl</tt></tag>
query type-1 or query type-2
<tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
- preferred record syntax &mdash UNIMARC, USMARC, etc.
+ preferred record syntax — UNIMARC, USMARC, etc.
<tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
- small-set-element-set names
+ small-set-element-set names. Not implemented yet.
<tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
- medium-set-element-set names
+ medium-set-element-set names. Not implemented yet.
<tag><tt>searchResponse </tt><em>list</em></tag>
- Search-response Tcl script
+ 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>
<descrip>
<tag><tt>searchStatus </tt><em>boolean</em></tag>
- search-status
+ search-status. True if search operation was successful; false
+ otherwise.
<tag><tt>responseStatus </tt><em>list</em></tag>
- response status information
+ response status information.
<tag><tt>resultCount </tt><em>integer</em></tag>
result-count
<tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
- number of records retrieved
+ number of records returned.
</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 &mdash 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 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 &mdash defaults to 1. The second integer
-is the number of records requested &mdash 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 &mdash UNIMARC, USMARC, etc.
+ 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
+ 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.
<descrip>
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:
<descrip>
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"
}
}
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 &mdash 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 &mdash only limited by the Tcl
+<tt/line/ extraction is more powerful — only limited by the Tcl
language itself.
<bf/Example/
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:
+
+<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 (c) 1995, Index Data.
+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,