<!doctype linuxdoc system>
<!--
- $Id: ir-tcl.sgml,v 1.7 1995-06-19 08:09:35 adam Exp $
+ $Id: ir-tcl.sgml,v 1.13 1995-11-28 17:36:06 adam Exp $
-->
<article>
<title>IrTcl User's Guide and Reference
<author>Index Data, <tt/info@index.ping.dk/
-<date>$Revision: 1.7 $
+<date>$Revision: 1.13 $
<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. Version 7.3 and 7.4 has been tested.
+<item> YAZ version 1.0b3 or higher.
+</itemize>
+
+As an option you may want:
+<itemize>
+<item> Tk. Version 3.6, 4.0 and 4.1 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.
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/.
<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
<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>
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 the init service. The list contains
- the options that are set. These 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>,
+ 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 options setting is set to its default
- value when an ir object is created and when a disconnect is performed.
+ <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. Note: not implemented - use <tt>callback</tt>
instead.
<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.
+ 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/
targets in <tt/targetList/:
<tscreen><verb>
-\foreach target $targetList {
+foreach target $targetList {
set assoc [lindex $target 0]
ir $assoc
$assoc comstack [lindex $target 1]
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.
<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. Not implemented yet.
<tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
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>
<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>
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>
<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 at a given
+ 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 entry
- is a normal term and <tt>SD</tt> if the scan entry is a surrogate
+ 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
<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,
projects / ir-tcl-moved-to-github.git / blobdiff