<!doctype linuxdoc system>
<!--
- $Id: ir-tcl.sgml,v 1.31 1999-12-10 10:36:13 adam Exp $
+ $Id: ir-tcl.sgml,v 1.34 2004-04-26 09:09:06 adam Exp $
-->
<article>
<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 $
+<date>$Date: 2004-04-26 09:09:06 $
<abstract>
-This document describes IrTcl -- an information retrieval toolkit for
-Tcl and Tk that provides access to the Z39.50/SR protocol.
+IrTcl version 1.4.2 -- a Tcl extension that allows you to build
+Z39.50 clients.
</abstract>
<toc>
<p>
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
+which offers a high-level interface for the development of Z39.50
+clients. The toolkit is based on the Tcl/Tk toolkit developed by Prof. John
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
-system.
-
-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.
+The core of Tcl is rather small but it offers a flexible C API
+for easy development of Tcl extensions. The most important Tcl
+extension is probably Tk -- A portale GUI for X/WIN32/MAC.
+
+To interface the Z39.50 protocol <sf/IrTcl/ uses the <bf/YAZ/ toolkit.
<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.
+or a shared object (Unix) which is dynamically loaded by using the Tcl's
+<tt/load/ command. However, <sf/IrTcl/ can also be compiled as a
+traditional <it/static/ library.
<sect>Compilation and installation
<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.
+ Version 8.0 and 8.3 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> <htmlurl url="http://www.scriptics.com" name="Tk">.
-Version 8.0 and 8.2 has been tested.
-<item> XTI/mOSI
+ version 1.6 or higher.
</itemize>
Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/.
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/
+The <tt>configure</tt> script 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
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.
+a Tcl shell called <tt/ir-tcl/. The traditional static
+library, <tt/libirtcl.a/, is build as well.
To install the programs and support files type:
<tscreen><verb>
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>.
+<tag><tt>client.tcl</tt></tag> A graphical client for Tk.
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
</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.
+<sf/IrTcl/ can be used either from the Tcl interpreter
+<tt/tclsh/ or the statically linked program <tt/ir-tcl/.
+Using <tt/tclsh/ is the preferred method. You must load
+the <sf/IrTcl/ library by using the <tt/load/ command.
-So the static, non-dynamic, version goes like this:
+A static, non-dynamic, version goes like this:
<tscreen><verb>
$ ir-tcl
%
</verb></tscreen>
-and the dynamic version goes like:
+and the dynamic version (preferred) goes like:
<tscreen><verb>
$ tclsh
% load ./irtcl.tcl
<sect1>WIN32
<p>
-<sf/IrTcl/ is shipped with a "makefile" for the NMAKE tool that comes
-with Visual C++.
+<sf/IrTcl/ is shipped with a "makefile" for the NMAKE tool part of
+with Microsoft 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
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.
+which demonstates an example of a user interface for the Z39.50 protocol.
At first the script was relatively small but it has grown since the
beginning. At present it is about 3000 lines.
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.
+Hence, you will not need to modify configuration files.
-Stuff concerning targets can be found in the pull down menu 'Target'
+Stuff regarding targets can be found in the pull down menu 'Target'
with the following options:
<descrip>
<tag>Connect</tag> Establishes connection to a target.
a list, which is re-interpreted prior to invocation.
The method is similar to the one used in Tk to capture X events.
-For each SR/Z39.50 request there is a corresponding object action. The most
+For each Z39.50 request there is a corresponding object action. The most
important actions are:
<descrip>
<tag/connect/ Establishes connection with a target
<descrip>
<tag><tt>comstack </tt><tt>mosi|tcpip</tt></tag>
- Comstack type.
+ Comstack type. Note that <tt/mosi/ is no longer supported by <bf/YAZ/.
<tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
- Protocol type - ANSI/NISO Z39.50 or ISO SR.
+ Protocol type - ANSI/NISO Z39.50 or ISO SR. Note, that SR
+ is no longer supported by <bf/YAZ/.
<tag><tt>callback </tt><em>list</em></tag>
Tcl script called when the connection is established.
<tag><tt>failback </tt><em>list</em></tag>
the following four components: association-name, comstack-type,
protocol-type and a hostname.
-The list for the two targets: ISO/SR target DANBIB and TCP/Z39.50
+The list for the two targets: Library of Congress and Z39.50
target Data Research, will be defined as:
<tscreen><verb>
-set targetList { {danbib mosi SR 0103/find2.denet.dk:4500}
+set targetList { {loc tcpip Z39 z3950.loc.gov:7090}
{drs tcpip Z39 dranet.dra.com} }
</verb></tscreen>
<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.
+ Large set lower bound. Default 1.
<tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
Medium set present number. Default 0.
<tag><tt>replaceIndicator </tt><em>boolean</em></tag>
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>XML
+
+<p>
+In <sf/IrTcl/ an XML record is treated as one single string. To retrieve
+a XML record use the <tt>getXml</tt> followed by an index.
+
<sect1>GRS-1
<p>
A GRS-1 record in <sf/IrTcl/ is represented as a list of elements.
<sect>License
<p>
-Copyright © 1995-1999, Index Data.
+Copyright © 1995-2004, Index Data ApS.
Permission to use, copy, modify, distribute, and sell this software and
its documentation, in whole or in part, for any purpose, is hereby granted,
<tscreen><verb>
Index Data
-Ryesgade 3
-2200 Copenhagen N
+Kobmagergade 43
+1150 Copenhagen K
Denmark
</verb></tscreen>
<p>
<tscreen><verb>
-Phone: +45 3536 3672
-Fax : +45 3536 0449
+Phone: +45 3341 0100
+Fax : +45 3341 0101
Email: info@indexdata.dk
</verb></tscreen>
<tag>2 Ousterhout, John K.:</tag>
Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
0-201-63337-X). The Tcl/Tk toolkit home page is
-<htmlurl url="http://www.scriptics.com"
- name="http://www.scriptics.com">.
+<htmlurl url="http://tcl.activestate.com"
+ name="http://tcl.activestate.com">.
The primary download area is
-<htmlurl url="http://www.scriptics.com/software/download.html"
-name="http://www.scriptics.com/software/download.html">.
+<htmlurl url="http://prdownloads.sourceforge.net/tcl/"
+name="http://prdownloads.sourceforge.net/tcl/">.
<tag>3 Welch, Brent B.:</tag>
Practical Programming in Tcl and Tk. Prentice Hall