X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fir-tcl.sgml;h=40ce2b4829d84d3763339f2c98764458b28dc257;hb=d026c3e06f6e19e5ed4174ab1a504a4b5af79183;hp=4cdde116cd8d30af777a81d618f35aa4e7a83dda;hpb=c594394608a2d72bd7b73dfa20bbe5cde7187637;p=ir-tcl-moved-to-github.git diff --git a/doc/ir-tcl.sgml b/doc/ir-tcl.sgml index 4cdde11..40ce2b4 100644 --- a/doc/ir-tcl.sgml +++ b/doc/ir-tcl.sgml @@ -1,17 +1,17 @@
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> @@ -20,26 +20,19 @@ Tcl and Tk that provides access to the Z39.50/SR protocol. <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 @@ -50,16 +43,9 @@ In order to compile the software on UNIX you need: <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/. @@ -72,7 +58,7 @@ $ ./configure 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 @@ -99,8 +85,8 @@ normal static library, <tt/libirtcl.a/. 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> @@ -119,19 +105,11 @@ Summary of files installed (the names refer to the Makefile variables): 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 @@ -162,18 +140,17 @@ This file is only generated when using newer versions of Tcl/Tk. </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 @@ -183,8 +160,8 @@ and the dynamic version goes like: <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 @@ -220,11 +197,9 @@ short-cut to start this. 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. @@ -236,15 +211,10 @@ $ wish -f client.tcl 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. @@ -336,7 +306,7 @@ is called. Callback routines are represented in Tcl as 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 @@ -435,9 +405,10 @@ immediately followed by a hostname. A number of settings affect the <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> @@ -554,10 +525,10 @@ Each item in the list describes the target parameters with 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> @@ -717,7 +688,7 @@ The settings that affect the search are listed below: <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> @@ -1134,6 +1105,12 @@ record. 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. @@ -1437,7 +1414,7 @@ been created. <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, @@ -1480,14 +1457,14 @@ in general. <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> @@ -1503,11 +1480,11 @@ 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 -<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