<!doctype linuxdoc system>
<!--
- $Id: ir-tcl.sgml,v 1.25 1998-01-16 11:01:20 adam Exp $
+ $Id: ir-tcl.sgml,v 1.33 2003-03-05 22:32:36 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.25 $
+<date>$Date: 2003-03-05 22:32:36 $
<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.1 -- 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.
-
-<sf/IrTcl/ is normally implemented as a <it/dynamic/ library (DLL)
-which is dynamically loaded by using the Tcl command <tt/load/.
-However, <sf/IrTcl/ can be compiled as a traditional <it/static/
-library as well.
+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 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
<p>
-In order to compile you need:
+<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://sunscript.sun.com/TclTkCore/" name="Tcl">.
- Version 7.5, 7.6 and 8.0 has been tested.
-<item> <htmlurl url="http://www.indexdata.dk/yaz.html" name="YAZ">
- version 1.4 or higher.
-</itemize>
-
-As an option you may want:
-<itemize>
-<item> <htmlurl url="http://sunscript.sun.com/TclTkCore/" name="Tk">.
-Version 4.1, 4.2 and 8.0 has been tested.
-<item> XTI/mOSI
+<item> <htmlurl url="http://www.scriptics.com" name="Tcl">.
+ Version 8.0 and 8.3 has been tested.
+<item> <htmlurl url="http://www.indexdata.dk/yaz/" name="YAZ">
+ 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 your Tcl shell in order to locate this file. For example
-if <tt/tclsh/ is located in <tt>/home/joe/bin</tt>, configure will
+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 Tcl shell in your path, you can specify the prefix
-by adding <tt>--prefix=</tt>prefix to the configure command, i.e.
+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 --prefix=/home/joe
+$ ./configure --with-tclconfig=/home/joe/lib
</verb></tscreen>
-The prefix is also used to determine where <sf/IrTcl/ is installed.
The <sf/IrTcl/ executables are installed in prefix/bin and libraries
and support files are installed in prefix/irtcl.
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>
<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.
-
-<tag><tt>ir-tk</tt></tag> The <sf/IrTcl/ shell for Tk. This shell
- is not needed when using a Tk that support for shared libraries is present.
- 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>.
+This file is only generated when using newer versions of Tcl/Tk.
<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
<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
+<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>.
in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
</descrip>
-<sect1>Using Tcl
-
<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
%
</verb></tscreen>
+<sect1>WIN32
+<p>
+
+<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
+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.
+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.
-To start the client using a dynamic library use:
+To start the client with dynamic library support use:
<tscreen><verb>
$ wish -f client.tcl
</verb></tscreen>
-Note: some installations a slightly different name for wish, eg.
-<tt/wish8.0/.
-
-To start the client without dynamic library support use:
-<tscreen><verb>
-$ ir-tk -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/.
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>
<sect>License
<p>
-Copyright © 1995-1998, Index Data.
+Copyright © 1995-2003, 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>
<p>
<descrip>
-<tag>1 Ousterhout, John K.:</tag>
+<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). The Tcl/Tk toolkit home page is
-<tt><htmlurl url="http://www.sunscript.com"
- name="http://www.sunscript.com"></tt>.
-The primary ftp site is <tt><htmlurl url="ftp://ftp.smli.com/pub/tcl/"
-name="ftp://ftp.smli.com/pub/tcl/"></tt>.
-<tag>2 Welch, Brent B.:</tag>
+<htmlurl url="http://tcl.activestate.com"
+ name="http://tcl.activestate.com">.
+The primary download area is
+<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
(ISBN 0-13-616830-2).
projects / ir-tcl-moved-to-github.git / blobdiff