<!doctype linuxdoc system>
<!--
- $Id: ir-tcl.sgml,v 1.14 1996-01-10 09:18:59 adam Exp $
+ $Id: ir-tcl.sgml,v 1.23 1997-04-13 19:01:45 adam Exp $
-->
<article>
-<title>IrTcl User's Guide and Reference
-<author>Index Data, <tt/info@index.ping.dk/
-<date>$Revision: 1.14 $
+<title>IrTcl User's Guide and Reference
+<author><htmlurl url="http://www.indexdata.dk/" name="Index Data">,
+<tt><htmlurl url="mailto:info@index.ping.dk" name="info@index.ping.dk"></tt>
+<date>$Revision: 1.23 $
<abstract>
-This document describes IrTcl — 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 — 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 — useful for
+<item> A simple command line shell -- useful for
testing purposes.
<item> A simple command line shell which operates within the Tk
- environment — makes it very easy to implement GUI clients.
+ environment -- makes it very easy to implement GUI clients.
</itemize>
<sect>Compilation and installation
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.
+<item> <htmlurl url="http://www.sunlabs.com/research/tcl/" name="Tcl">.
+ Version 7.3, 7.4 and 7.5 has been tested.
+<item> <htmlurl url="http://www.indexdata.dk/yaz.html" name="YAZ">
+ version 1.2 or higher.
</itemize>
As an option you may want:
<itemize>
-<item> Tk. Version 3.6, 4.0 and 4.1 has been tested.
+<item> <htmlurl url="http://www.sunlabs.com/research/tcl/" name="Tk">.
+Version 3.6, 4.0 and 4.1 has been tested.
<item> XTI/mOSI
</itemize>
$ make install
</verb></tscreen>
+If you wish to install man pages type:
+<tscreen><verb>
+$ make install.man
+</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
+ 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>.
+ <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>.
+ -- 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>.
+ 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>.
+ 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>.
+ 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>.
+ 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>.
+ 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>.
+ in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
</descrip>
<sect1>ir-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 — 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/.
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 — 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.
Proximity operation on op1 and op2. Not implemented yet.
<tag><tt>@set </tt><em>name</em></tag>
Result set reference
+<tag><tt>@attrset </tt><em>set</em></tag>
+ Whole query uses the specified attribute <em>set</em>. If this operator is
+ used it must be defined at the beginning of the query.
</descrip>
It is simple to build RPN queries in <sf/IrTcl/. Search terms
@attr 1=4 @and @attr 5=1 tech beta
</verb></tscreen>
+To search for the DatabaseInfo records from an Explain server, we
+could use
+<tscreen><verb>
+ @attrset exp1 @attr 1=1 DatabaseInfo
+</verb></tscreen>
+
<sect1>Search
<p>
<tag><tt>replaceIndicator </tt><em>boolean</em></tag>
Replace-indicator. Default true (1).
<tag><tt>setName </tt><em>string</em></tag>
- Name of result set.
+ Name of result set. Default name of set is <tt/default/.
<tag><tt>queryType rpn|ccl</tt></tag>
Query type-1 or query type-2. Default rpn (type-1).
<tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
- Preferred record syntax — UNIMARC, USMARC, etc.
+ Preferred record syntax -- UNIMARC, USMARC, etc.
<tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
small-set-element-set names. If <em>string</em> is empty
the element set is not set. Default is empty (not set).
Search-response Tcl script.
<tag><tt>callback </tt><em>list</em></tag>
General response Tcl script. Only used if searchResponse is not specified.
- This setting is valid only for the <tt/ir/ object — not the
+ This setting is valid only for the <tt/ir/ object -- not the
<tt/ir-set/ object.
</descrip>
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 — no records are
+<tag><tt>OK</tt></tag> indicates a successful operation -- no records are
returned from the target.
</descrip>
<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 — defaults to 1. The second integer
-is the number of records requested — 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 — UNIMARC, USMARC, etc.
+ preferred record syntax -- UNIMARC, USMARC, etc.
<tag><tt>elementSetNames </tt><em>string</em></tag>
Element-set names. If <em>string</em> is empty
the element set is not set. Default is empty (not set).
Present-response Tcl script.
<tag><tt>callback </tt><em>list</em></tag>
General response Tcl script. Only used if presentResponse is not specified
- This setting is valid only for the <tt/ir/ object — not the
+ This setting is valid only for the <tt/ir/ object -- not the
<tt/ir-set/ object.
</descrip>
is returned.
The <tt/line/ type, on the other hand, returns a Tcl list that
-completely describe the layout of the MARC record — 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 — only limited by the Tcl
+<tt/line/ extraction is more powerful -- only limited by the Tcl
language itself.
<bf/Example/
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>GRS-1
+<p>
+To be written.
+
+<sect1>Explain
+<p>
+Explain records are retrieved like other records. The method,
+<tt>getExplain</tt> is followed by an index and, and an optional
+Explain record pattern.
+
+The returned record is a canonical representation of the Explain record.
+An ASN.1 sequence is represented as a list. Each item in the list
+consists of the name of the element, followed by its value if the value
+is supplied.
+
+The optional pattern that follows the index after <tt>getExplain</tt>
+consists of one or more elements, that is matched against the elements
+of the actual record.
+
+<bf/Example/
+
+One of the few targets that support explain is the ATT research server
+at <tt>z3950.research.att.com</tt>.
+
+The targetInfo record was returned by the target and it's stored in
+position 1 in the result set, <tt>z.1</tt>. To retrieve the whole
+record we must use
+<tscreen><verb>
+z.1 getExplain 1
+</verb></tscreen>
+
+and we get in return
+
+<tscreen><verb>
+{targetInfo commonInfo {name {Lucent Technologies Research Server}}
+recentNews icon {namedResultSets 1} {multipleDBsearch 0}
+{maxResultSets 100} {maxResultSize 600000} maxTerms timeoutInterval
+{welcomeMessage {strings { {language eng}
+{text
+{Salutations - this is Lucent Technologies experimental Z39.50 server.
+No guarentees, but free and unlimited access!}} } } }
+{contactInfo {name {Robert Waldstein}} {description {strings
+{ {language eng}
+{text {Librarian system designer - no legal anythings}} } } }
+{address {strings { {language eng} {text {Room 3D-591
+600 Mountain Ave
+Murray Hill
+N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}} }
+description nicknames {usageRest {strings { {language eng}
+{text {None - as long as nonProfit research}} } } } paymentAddr
+{hours {strings { {language eng} {text {Should never be down}} } } }
+dbCombinations addresses commonAccessInfo }
+</verb></tscreen>
+
+The <tt>targetInfo</tt> above indicates the the record is really a
+<tt>targetInfo</tt> record. The <tt>commonInfo</tt>, which is optional, is
+not supplied by this server. The <tt>name</tt>, however is supplied,
+with the value <tt>Lucent Technologies Research Server</tt>.
+
+To retrieve the <tt>contactInfo</tt> from the record above we can
+extract the element from the record by using Tcl's list manipulation
+facilities, for example by doing
+<tscreen><verb>
+set ti [z.1 getExplain 1]
+lindex [lindex $ti 0] 12
+</verb></tscreen>
+which will return
+<tscreen><verb>
+contactInfo {name {Robert Waldstein}} {description {strings
+{ {language eng}
+{text {Librarian system designer - no legal anythings}} }
+} } {address {strings { {language eng} {text {Room 3D-591
+600 Mountain Ave
+Murray Hill
+N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}}
+</verb></tscreen>
+
+We can also extract almost the same by doing
+<tscreen><verb>
+z.1 getExplain 1 targetInfo contactInfo
+</verb></tscreen>
+which will return
+<tscreen><verb>
+{name {Robert Waldstein}} {description {strings { {language eng}
+{text {Librarian system designer - no legal anythings}} } } }
+{address {strings { {language eng} {text {Room 3D-591
+600 Mountain Ave
+Murray Hill
+N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}}
+</verb></tscreen>
+
+<bf/End of example/
+
<sect>Scan
<p>
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
+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
<tag><tt>callback </tt><em>list</em></tag>
General response Tcl script. Only used if <tt>scanResponse</tt>
is not specified.
- This setting is valid only for the <tt/ir/ object — not the
+ This setting is valid only for the <tt/ir/ object -- not the
<tt/ir-set/ object.
</descrip>
<sect>License
<p>
-Copyright © 1995, Index Data.
+Copyright © 1995-1996, 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,
<descrip>
<tag>1 Ousterhout, John K.:</tag>
Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
-0-201-63337-X). Source and documentation
-can be found in <tt>URL:ftp://ftp.cs.berkeley.edu/pub/tcl</tt>
-and mirrors.
+0-201-63337-X). The Tcl/Tk toolkit home page is
+<tt><htmlurl url="http://www.sunlabs.com/research/tcl/"
+ name="http://www.sunlabs.com/research/tcl"></tt>.
+The primary ftp site is <tt><htmlurl url="ftp://ftp.smli.com/pub/tcl/"
+name="ftp://ftp.smli.com/pub/tcl/"></tt>.
+A mirror site can be found at <tt>
+<htmlurl url="ftp://ftp.neosoft.com/pub/tcl/mirror/ftp.smli.com"
+name="ftp://ftp.neosoft.com/pub/tcl/mirror/ftp.smli.com"></tt>.
<tag>2 Furniss, Peter:</tag>
RFC 1698: Octet Sequences for Upper-Layer OSI to Support
Basic Communications Applications.
projects / ir-tcl-moved-to-github.git / blobdiff