Better doc.

[ir-tcl-moved-to-github.git] / doc / ir-tcl.sgml

diff --git a/doc/ir-tcl.sgml b/doc/ir-tcl.sgml
index aba6909..afb810e 100644 (file)
--- a/doc/ir-tcl.sgml
+++ b/doc/ir-tcl.sgml
@@ -1,13 +1,13 @@
 <!doctype linuxdoc system>
 
 <!--
 <!doctype linuxdoc system>
 
 <!--

-  $Id: ir-tcl.sgml,v 1.9 1995-06-25 10:25:33 adam Exp $
+  $Id: ir-tcl.sgml,v 1.14 1996-01-10 09:18:59 adam Exp $

 -->
 
 <article>
 <title>IrTcl User's Guide and Reference
 <author>Index Data, <tt/info@index.ping.dk/
 -->
 
 <article>
 <title>IrTcl User's Guide and Reference
 <author>Index Data, <tt/info@index.ping.dk/

-<date>$Revision: 1.9 $
+<date>$Revision: 1.14 $

 <abstract>
 This document describes IrTcl &mdash; an information retrieval toolkit for
 Tcl and Tk that provides access to the Z39.50/SR protocol.
 <abstract>
 This document describes IrTcl &mdash; an information retrieval toolkit for
 Tcl and Tk that provides access to the Z39.50/SR protocol.

@@ -40,8 +40,8 @@ See &lsqb;ref 2&rsqb; for more information about the XTI/mOSI implementation.
 <itemize>
 <item> A simple command line shell &mdash; useful for
 testing purposes.
 <itemize>
 <item> A simple command line shell &mdash; 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 &mdash; makes it very easy to implement GUI clients.

 </itemize>
 
 <sect>Compilation and installation
 </itemize>
 
 <sect>Compilation and installation

@@ -50,22 +50,16 @@ makes it very easy to implement GUI clients.
 In order to compile you need:
 <itemize>
 <item> An ANSI C compiler such as GNU C.
 In order to compile you need:
 <itemize>
 <item> An ANSI C compiler such as GNU C.

-<item> Tcl 7.3. 
-<item> YAZ version 1.0b or higher
+<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>
 </itemize>
 
 As an option you may want:
 <itemize>

-<item> Tk 3.6.
-<item> XTI/mosi
+<item> Tk. Version 3.6, 4.0 and 4.1 has been tested.
+<item> XTI/mOSI

 </itemize>
 
 </itemize>
 

-Newer versions of Tcl and Tk have been released. These packages
-will <em/not/ work with <sf/IrTcl/. The <sf/IrTcl/ package will
-probably be able to use the newer versions soon. Fortunately this
-move will not change the <sf/IrTcl/ API &mdash; only the Tk code of the
-test client will be modified.
-

 Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/. 
 
 Type:
 Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/. 
 
 Type:

@@ -101,32 +95,36 @@ $ make install
 Summary of files installed (the names refer to the Makefile variables):
 
 <descrip>
 Summary of files installed (the names refer to the Makefile variables):
 
 <descrip>

-<tag><tt>ir-tk</tt></tag> The Tk client. Installed in <tt>BINDIR</tt> &mdash;
-defaults to <tt>/usr/local/bin</tt>. When ir-tk starts it reads
-<tt>client.tcl</tt>. If the files doesn't exist in the current
-directory it tries to read it from <tt>IRTCLDIR</tt> - defaults
-to <tt>/usr/local/lib/irtcl</tt>.
-<tag><tt>ir-tcl</tt></tag> The Tcl client. Installed in <tt>BINDIR</tt> &mdash;
-defaults to <tt>/usr/local/bin</tt>.
+<tag><tt>ir-tk</tt></tag> The <sf/IrTcl/ shell for Tk.
+ Installed in <tt>BINDIR</tt> &mdash; 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> &mdash; 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>
+ &mdash; defaults to <tt>/usr/local/lib/irtcl</tt>.

 <tag><tt>libirtcl.a</tt></tag> The <sf/IrTcl/ library. 
 <tag><tt>libirtcl.a</tt></tag> The <sf/IrTcl/ library. 

-Installed in <tt>LIBDIR</tt> &mdash; defaults to <tt>/usr/local/lib</tt>.
+ Installed in <tt>LIBDIR</tt> &mdash; defaults to <tt>/usr/local/lib</tt>.

 <tag><tt>ir-tcl.h</tt></tag> The <sf/IrTcl/ header file.
 <tag><tt>ir-tcl.h</tt></tag> The <sf/IrTcl/ header file.

-Installed in <tt>INCDIR</tt> &mdash; defaults to <tt>/usr/local/include</tt>.
-<tag><tt>client.tcl</tt></tag> A graphical client written in TK. 
-Installed in <tt>IRTCLDIR</tt> &mdash; defaults to 
-<tt>/usr/local/lib/irtcl</tt>.
+ Installed in <tt>INCDIR</tt> &mdash; defaults to <tt>/usr/local/include</tt>.

 <tag><tt>clientrc.tcl</tt></tag> A setup file with definitions
 <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> &mdash; defaults to <tt>/usr/local/lib/irtcl</tt>.
+ of target and queries. Read and updated by <tt>client.tcl</tt>. Installed
+ in <tt>IRTCLDIR</tt> &mdash; defaults to <tt>/usr/local/lib/irtcl</tt>.

 <tag><tt>formats/*</tt></tag> Display format files written
 <tag><tt>formats/*</tt></tag> Display format files written

-in Tk. Read by <tt>client.tcl</tt>. Installed 
-in <tt>IRTCLDIR</tt> &mdash; defaults to <tt>/usr/local/lib/irtcl</tt>.
+ in Tk. Read by <tt>client.tcl</tt>. Installed 
+ in <tt>IRTCLDIR</tt> &mdash; defaults to <tt>/usr/local/lib/irtcl</tt>.

 <tag><tt>bitmaps/*</tt></tag> Various bitmap files. Read by
 <tag><tt>bitmaps/*</tt></tag> Various bitmap files. Read by

-<tt>client.tcl</tt>. Installed 
-in <tt>IRTCLDIR</tt> &mdash; defaults to <tt>/usr/local/lib/irtcl</tt>.
+ <tt>client.tcl</tt>. Installed 
+ in <tt>IRTCLDIR</tt> &mdash; defaults to <tt>/usr/local/lib/irtcl</tt>.

 <tag><tt>LICENSE</tt></tag> LICENSE file. Read by
 <tag><tt>LICENSE</tt></tag> LICENSE file. Read by

-<tt>client.tcl</tt>. Installed 
-in <tt>IRTCLDIR</tt> &mdash; defaults to <tt>/usr/local/lib/irtcl</tt>.
+ <tt>client.tcl</tt>. Installed 
+ in <tt>IRTCLDIR</tt> &mdash; defaults to <tt>/usr/local/lib/irtcl</tt>.

 </descrip>
 
 <sect1>ir-tcl
 </descrip>
 
 <sect1>ir-tcl

@@ -143,16 +141,26 @@ as a script.
 <sect1>ir-tk
 
 <p>
 <sect1>ir-tk
 
 <p>

-<tt>ir-tk</tt> is a program which basically waits for X events and
-socket events (assocated with Z39.50/SR targets). <tt>ir-tk</tt> normally
-tries to evaluate the file named <tt>client.tcl</tt> when it
-starts. However, this behaviour may be changed by specifying another 
-filename with the <tt>-file</tt> option.
-
-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.
+<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 
 At first the script was relatively small but it has grown since the 

-beginning. At present it is about 3000 lines.
+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. 
 
 The client lets up define targets and query types within the interface.
 Hence, you will not need to modify configation files. 

@@ -292,8 +300,8 @@ returned is stored in the variable <tt/ret/.
 
 <tscreen><verb>
 ir z
 
 <tscreen><verb>
 ir z

-ir-set z.1 z

 z databaseNames books
 z databaseNames books

+ir-set z.1 z

 z callback {connect-response}
 z connect fake.com
 
 z callback {connect-response}
 z connect fake.com
 

@@ -303,7 +311,7 @@ proc connect-response {} {
 }
 
 proc init-response {} {
 }
 
 proc init-response {} {

-    z.1 callback {search-response}
+    z callback {search-response}

     z.1 search science
 }
 
     z.1 search science
 }
 

@@ -311,7 +319,7 @@ proc search-response {} {
     set hits [z.1 resultCount]
     puts "$hits hits"
     if {$hits > 0} {
     set hits [z.1 resultCount]
     puts "$hits hits"
     if {$hits > 0} {

-        z.1 callback {present-response}
+        z callback {present-response}

         z.1 present 1 5
     }
 }
         z.1 present 1 5
     }
 }

@@ -352,15 +360,36 @@ immediately followed by a hostname. A number of settings affect the
 <tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
  Protocol type - ANSI/NISO Z39.50 or ISO SR.
 <tag><tt>callback </tt><em>list</em></tag>
 <tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
  Protocol type - ANSI/NISO Z39.50 or ISO SR.
 <tag><tt>callback </tt><em>list</em></tag>

- Tcl script called when the connection is established
+ Tcl script called when the connection is established.

 <tag><tt>failback </tt><em>list</em></tag>
  Fatal error Tcl script. Called on protocol errors or if target
 <tag><tt>failback </tt><em>list</em></tag>
  Fatal error Tcl script. Called on protocol errors or if target

- closes connection
+ closes connection.

 </descrip>
 
 If the connect is unsuccessful either the connect action itself
 will return an error code or the failback handler is invoked.
 
 </descrip>
 
 If the connect is unsuccessful either the connect action itself
 will return an error code or the failback handler is invoked.
 

+In general, the <tt>failback</tt> handler is invoked when serious
+unrecoverable errors occur when communicating with the target. 
+In this case the <sf/IrTcl/ system shuts down the connection.
+The <tt>failback</tt> handler might inspect the <tt>failInfo</tt>
+setting to determine the cause of the failure; it returns
+two elements. The first is an error integer; the second is an 
+english representation of the error. The error codes and
+the corresponding messages are:
+
+<descrip>
+<tag><tt>0</tt></tag>ok
+<tag><tt>1</tt></tag>connect failed
+<tag><tt>2</tt></tag>connection closed
+<tag><tt>3</tt></tag>connection closed
+<tag><tt>4</tt></tag>failed to decode incoming APDU
+<tag><tt>5</tt></tag>unknown APDU
+</descrip>
+
+Note: in case 3 the connection was closed during read a read operation
+whereas in case 4 it was closed during a write operation.
+

 <sect1>Init
 
 <p>
 <sect1>Init
 
 <p>

@@ -400,9 +429,11 @@ The init related settings are:
  action is performed.
 <tag><tt>protocolVersion </tt><em>integer</em></tag>
  Protocol version: 2, 3, etc. Default is 2.
  action is performed.
 <tag><tt>protocolVersion </tt><em>integer</em></tag>
  Protocol version: 2, 3, etc. Default is 2.

+<tag><tt>referenceId </tt><em>string</em></tag>
+ Reference-id of init operation. If <em>string</em> is empty no 
+ reference-id is used.

 <tag><tt>initResponse </tt><em>list</em></tag>
 <tag><tt>initResponse </tt><em>list</em></tag>

- Init-response Tcl script. Note: not implemented - use <tt>callback</tt>
- instead.
+ Init-response Tcl script.

 <tag><tt>callback </tt><em>list</em></tag>
  General response Tcl script. Only used if <tt>initResponse</tt>
  is not specified.
 <tag><tt>callback </tt><em>list</em></tag>
  General response Tcl script. Only used if <tt>initResponse</tt>
  is not specified.

@@ -412,25 +443,27 @@ The init-response handler should inspect some of the settings shown
 below:
 
 <descrip>
 below:
 
 <descrip>

-<tag><tt>initResult </tt><em>boolean</em></tag>
+<tag><tt>initResult </tt>returns <em>boolean</em></tag>

  Init response status. True if init operation was successful; 
  false otherwise.
  Init response status. True if init operation was successful; 
  false otherwise.

-<tag><tt>preferredMessageSize </tt><em>integer</em></tag>
- Preferred-message-size.
-<tag><tt>maximumRecordSize </tt><em>integer</em></tag>
- Maximum-record-size.
-<tag><tt>targetImplementationName </tt><em>string</em></tag>
+<tag><tt>preferredMessageSize </tt>returns <em>integer</em></tag>
+ Preferred-message-size after negotiation.
+<tag><tt>maximumRecordSize </tt>returns <em>integer</em></tag>
+ Maximum-record-size after negotiation.
+<tag><tt>targetImplementationName </tt>returns <em>string</em></tag>

  Implementation-name of target system.
  Implementation-name of target system.

-<tag><tt>targetImplementationId </tt><em>string</em></tag>
+<tag><tt>targetImplementationId </tt>returns <em>string</em></tag>

  Implementation-id of target system.
  Implementation-id of target system.

-<tag><tt>targetImplementationVersion </tt><em>string</em></tag>
+<tag><tt>targetImplementationVersion </tt>returns <em>string</em></tag>

  Implementation-version of target system.
  Implementation-version of target system.

-<tag><tt>options </tt><em>list</em></tag>
- 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>
+<tag><tt>options </tt>returns <em>list</em></tag>
+ Options after negotiation. The list contains the options that are set.
+<tag><tt>protocolVersion </tt>returns <em>integer</em></tag>
+ Protocol version: 2, 3, etc after negotiation.
+<tag><tt>userInformationField </tt>returns <em>string</em></tag>

  User information field.
  User information field.

+<tag><tt>referenceId </tt>returns <em>string</em></tag>
+ Reference-id of init response.

 </descrip>
 
 <bf/Example/
 </descrip>
 
 <bf/Example/

@@ -592,30 +625,37 @@ The settings that affect the search are listed below:
 
 <descrip>
 <tag><tt>databaseNames </tt><em>list</em></tag>
 
 <descrip>
 <tag><tt>databaseNames </tt><em>list</em></tag>

- database-names.
+ Database-names.

 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>

- small set upper bound. Default 0.
+ Small set upper bound. Default 0.

 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>

- large set lower bound. Default 2.
+ Large set lower bound. Default 2.

 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>

- medium set present number. Default 0.
+ Medium set present number. Default 0.

 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>
 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>

- replace-indicator.
+ Replace-indicator. Default true (1).

 <tag><tt>setName </tt><em>string</em></tag>
 <tag><tt>setName </tt><em>string</em></tag>

- name of result set.
+ Name of result set.

 <tag><tt>queryType rpn|ccl</tt></tag>
 <tag><tt>queryType rpn|ccl</tt></tag>

- query type-1 or query type-2 
+ Query type-1 or query type-2. Default rpn (type-1).

 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>

- preferred record syntax &mdash; UNIMARC, USMARC, etc. 
+ Preferred record syntax &mdash; UNIMARC, USMARC, etc. 

 <tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
 <tag><tt>smallSetElementSetNames </tt><em>string</em></tag>

- small-set-element-set names. Not implemented yet.
+ small-set-element-set names. If <em>string</em> is empty
+ the element set is not set. Default is empty (not set).

 <tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
 <tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>

- medium-set-element-set names. Not implemented yet.
+ medium-set-element-set names. If <em>string</em> is empty
+ the element set is not set. Default is empty (not set).
+<tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
+ Next result set position.
+<tag><tt>referenceId </tt><em>string</em></tag>
+ Reference-id. If <em>string</em> is empty no reference-id is used.

 <tag><tt>searchResponse </tt><em>list</em></tag>
 <tag><tt>searchResponse </tt><em>list</em></tag>

- Search-response Tcl script. Not implemented yet. Use <tt>callback</tt>
- instead.
+ Search-response Tcl script.

 <tag><tt>callback </tt><em>list</em></tag>
 <tag><tt>callback </tt><em>list</em></tag>

- General response Tcl script. Only used if searchResponse is not specified 
+ General response Tcl script. Only used if searchResponse is not specified.
+ This setting is valid only for the <tt/ir/ object &mdash; not the
+ <tt/ir-set/ object.

 </descrip>
 
 Setting the <tt/databaseNames/ is mandatory. All other settings
 </descrip>
 
 Setting the <tt/databaseNames/ is mandatory. All other settings

@@ -625,15 +665,17 @@ the <tt/searchResponse/ setting,
 should read some of the settings shown below:
 
 <descrip>
 should read some of the settings shown below:
 
 <descrip>

-<tag><tt>searchStatus </tt><em>boolean</em></tag>
- search-status. True if search operation was successful; false
+<tag><tt>searchStatus</tt> returns <em>boolean</em></tag>
+ Search-status. True if search operation was successful; false

  otherwise.
  otherwise.

-<tag><tt>responseStatus </tt><em>list</em></tag>
- response status information.
-<tag><tt>resultCount </tt><em>integer</em></tag>
+<tag><tt>responseStatus </tt>returns <em>list</em></tag>
+ Response status information.
+<tag><tt>resultCount </tt>returns <em>integer</em></tag>

  result-count
  result-count

-<tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
- number of records returned.
+<tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
+ Number of records returned.
+<tag><tt>referenceId </tt>returns <em>string</em></tag>
+ Reference-id of search response.

 </descrip>
 
 The <tt/responseStatus/ signals one of three conditions which
 </descrip>
 
 The <tt/responseStatus/ signals one of three conditions which

@@ -667,7 +709,7 @@ proc init-response {assoc} {
     ir-set ${assoc}.1 $assoc
     $assoc.1 queryType rpn
     $assoc.1 databaseNames base-a base-b
     ir-set ${assoc}.1 $assoc
     $assoc.1 queryType rpn
     $assoc.1 databaseNames base-a base-b

-    $assoc.1 callback [list search-response $assoc ${assoc}.1]
+    $assoc callback [list search-response $assoc ${assoc}.1]

     $assoc.1 search "@attr 1=4 @and @attr 5=1 tech beta"
 }
 </verb></tscreen>
     $assoc.1 search "@attr 1=4 @and @attr 5=1 tech beta"
 }
 </verb></tscreen>

@@ -737,13 +779,17 @@ action are:
 <descrip>
 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
  preferred record syntax &mdash; UNIMARC, USMARC, etc.
 <descrip>
 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
  preferred record syntax &mdash; UNIMARC, USMARC, etc.

-<tag><tt>elementSetElementSetNames </tt><em>string</em></tag>
- element-set names 
+<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).
+<tag><tt>referenceId </tt><em>string</em></tag>
+ Reference-id. If <em>string</em> is empty no reference-id is used.

 <tag><tt>presentResponse </tt><em>list</em></tag>
 <tag><tt>presentResponse </tt><em>list</em></tag>

- Present-response Tcl script. Not implemented yet. Use <tt>callback</tt>
- instead.
+ Present-response Tcl script. 

 <tag><tt>callback </tt><em>list</em></tag>
  General response Tcl script. Only used if presentResponse is not specified 
 <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 &mdash; not the
+ <tt/ir-set/ object.

 </descrip>
 
 The present-response handler should inspect the settings
 </descrip>
 
 The present-response handler should inspect the settings

@@ -755,14 +801,16 @@ As in the search response case, records returned from the
 target are stored in the result set object.
 
 <descrip>
 target are stored in the result set object.
 
 <descrip>

-<tag><tt>presentStatus </tt><em>boolean</em></tag>
- present-status 
-<tag><tt>responseStatus </tt><em>list</em></tag>
- Response status information 
-<tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
- number of records returned 
-<tag><tt>nextResultSetPosition </tt><em>integer</em></tag>
- next result set position
+<tag><tt>presentStatus </tt>returns <em>boolean</em></tag>
+ Present-status.
+<tag><tt>responseStatus </tt>returns <em>list</em></tag>
+ Response status information.
+<tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
+ Number of records returned.
+<tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
+ Next result set position.
+<tag><tt>referenceId </tt>returns <em>string</em></tag>
+ Reference-id of present response.

 </descrip>
 
 <sect1>Records
 </descrip>
 
 <sect1>Records

@@ -772,16 +820,29 @@ Search responses and present responses may result in
 one or more records stored in the ir set object if
 the <tt/responseStatus/ setting indicates database or
 surrogate diagnostics (<tt/DBOSD/). The individual
 one or more records stored in the ir set object if
 the <tt/responseStatus/ setting indicates database or
 surrogate diagnostics (<tt/DBOSD/). The individual

-records, indexed by an integer position, should be 
+records, indexed by an integer position offset, should then be 

 inspected.
 
 inspected.
 

-The action <tt/type/ followed by an integer returns information 
+If element set names have been specified either in the
+search requests (<tt>smallSetElementSetNames</tt> /
+<tt>mediumSetElementSetNames</tt>) or present requests 
+(<tt>elementSetNames</tt>) the individual records in the
+ir set object are assigned appropriate element set ids. 
+In this mode records at a given position are treated different as
+long as they have difference element set ids.
+To inspect records with a particular element set id in subsequent
+operations use the <tt>recordElements</tt> setting followed by the id.
+If you have more than one record at a given position and you do not
+use <tt>recordElements</tt> the record selected at the given position
+is undefined.
+
+The action <tt>type</tt> followed by an integer returns information 

 about a given position in an ir set. There are three possiblities:
 
 <descrip>
 <tag><tt/SD/</tag> The item is a surrogate diagnostic record.
 about a given position in an ir set. There are three possiblities:
 
 <descrip>
 <tag><tt/SD/</tag> The item is a surrogate diagnostic record.

-<tag><tt/DB/</tag> The item is a database record.

 <tag><em/empty/</tag> There is no record at the specified position.
 <tag><em/empty/</tag> There is no record at the specified position.

+<tag><tt/DB/</tag> The item is a database record.

 </descrip>
 
 To handle the first case, surrogate diagnostic record, the
 </descrip>
 
 To handle the first case, surrogate diagnostic record, the

@@ -789,7 +850,11 @@ To handle the first case, surrogate diagnostic record, the
 items: error code (integer), text representation in plain english
 (string), and additional information (string, possibly empty).
 
 items: error code (integer), text representation in plain english
 (string), and additional information (string, possibly empty).
 

-In the second case, database record, the <tt/recordType/ action should
+In the second case, no record, note that there still might
+be a record at the position but with an id that differs from that
+specified by <tt>recordElements</tt>.
+
+In the third case, database record, the <tt/recordType/ action should

 be used. It returns the record type at the given position.
 Some record types are:
 
 be used. It returns the record type at the given position.
 Some record types are:
 

@@ -977,15 +1042,15 @@ record.
 
 <sect1>SUTRS
 
 
 <sect1>SUTRS
 

+<p>

 In <sf/IrTcl/ a SUTRS record is treated as one single string. To retrieve
 In <sf/IrTcl/ a SUTRS record is treated as one single string. To retrieve

-a SUTRS string at a given index, the <tt>getSutrs</tt> should be used. 
-The <tt>getSutrs</tt> is immediately followed by a index.
+a SUTRS record use the <tt>getSutrs</tt> followed by an index.

 
 <sect>Scan
 
 <p>
 To perform scan, a scan object must be created by the <tt>ir-scan</tt>
 
 <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 &mdash; 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
 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

@@ -1003,9 +1068,15 @@ The settings that affect the scan are:
 <tag><tt>databaseNames </tt><em>list</em></tag>
  Database names. Note that this setting is not (yet) supported for
  the scan object. You must set this for the ir object instead.
 <tag><tt>databaseNames </tt><em>list</em></tag>
  Database names. Note that this setting is not (yet) supported for
  the scan object. You must set this for the ir object instead.

+<tag><tt>referenceId </tt><em>string</em></tag>
+ Reference-id. If <em>string</em> is empty no reference-id is used.
+<tag><tt>scanResponse </tt><em>list</em></tag>
+ Scan-response Tcl script. 

 <tag><tt>callback </tt><em>list</em></tag>
 <tag><tt>callback </tt><em>list</em></tag>

- General response Tcl script. This setting is not (yet) supported for
- the scan object. You must set this for the ir object instead.
+ General response Tcl script. Only used if <tt>scanResponse</tt>
+ is not specified.
+ This setting is valid only for the <tt/ir/ object &mdash; not the
+ <tt/ir-set/ object.

 </descrip>
 
 The scan object normally holds one or more scan line entries upon
 </descrip>
 
 The scan object normally holds one or more scan line entries upon

@@ -1013,13 +1084,13 @@ successful completion. The table below summarizes the settings
 that should be used in a response handler.
 
 <descrip>
 that should be used in a response handler.
 
 <descrip>

-<tag><tt>scanStatus</tt></tag>
+<tag><tt>scanStatus </tt>returns <em>integer</em></tag>

  Scan status. An integer between 0 and 6.
  Scan status. An integer between 0 and 6.

-<tag><tt>numberOfTermsReturned </tt><em>integer</em></tag>
+<tag><tt>numberOfTermsReturned </tt>returns <em>integer</em></tag>

  Number of terms returned. 
  Number of terms returned. 

-<tag><tt>positionOfTerm</tt></tag>
+<tag><tt>positionOfTerm </tt>returns <em>integer</em></tag>

  An integer describing the position of term.
  An integer describing the position of term.

-<tag><tt>scanLine </tt> <em>integer</em></tag>
+<tag><tt>scanLine </tt>returns <em>list</em></tag>

  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>
  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>

@@ -1030,6 +1101,8 @@ that should be used in a response handler.
  In the other case (surrogate diagnostic), the second element
  is the diagnostic code, the third a text representation of the error
  code and the fourth element is additional information.
  In the other case (surrogate diagnostic), the second element
  is the diagnostic code, the third a text representation of the error
  code and the fourth element is additional information.

+<tag><tt>referenceId </tt>returns <em>string</em></tag>
+ Reference-id of scan response.

 </descrip>
 
 <bf/Example/
 </descrip>
 
 <bf/Example/