1 <!doctype linuxdoc system>
4 $Id: ir-tcl.sgml,v 1.24 1998-01-16 09:24:18 adam Exp $
8 <title>IrTcl User's Guide and Reference
9 <author><htmlurl url="http://www.indexdata.dk/" name="Index Data">,
10 <tt><htmlurl url="mailto:info@indexdata.dk" name="info@indexdata.dk"></tt>
11 <date>$Revision: 1.24 $
13 This document describes IrTcl -- an information retrieval toolkit for
14 Tcl and Tk that provides access to the Z39.50/SR protocol.
22 This document describes the <sf/IrTcl/ information retrieval toolkit,
23 which offers a high-level, client interface to the Z39.50 and SR protocols.
24 The toolkit is based on the Tcl/Tk toolkit developed by Prof. John
25 K. Ousterhout at the University of California [ref 1].
26 Tcl is a simple, somewhat shell-like, interpreted language. What
27 makes Tcl attractive is that it also offers a C API, which makes
28 extensions to the language possible. The most important Tcl extension is
29 probably Tk -- A Motif look-and-feel interface to the X window
32 To interface the Z39.50/SR protocol <sf/IrTcl/ uses <bf/YAZ/.
33 <bf/YAZ/ offers two transport types: RFC1729/BER on TCP/IP and the mOSI
35 However, the mOSI transport is only an option, and hence it is not
36 needed unless you wish to communicate within an OSI environment.
37 See [ref 2] for more information about the XTI/mOSI implementation.
39 <sf/IrTcl/ is implemented as a <it/dynamic/ library (DLL) which is
40 dynamically loaded by using the <tt/load/ command. However, <sf/IrTcl/
41 may also be compiled as a traditional <it/static/ library as well.
43 <sect>Compilation and installation
46 In order to compile you need:
48 <item> An ANSI C compiler such as GNU C.
49 <item> <htmlurl url="http://sunscript.sun.com/TclTkCore/" name="Tcl">.
50 Version 7.X and 8.0 has been tested.
51 <item> <htmlurl url="http://www.indexdata.dk/yaz.html" name="YAZ">
52 version 1.4 or higher.
55 As an option you may want:
57 <item> <htmlurl url="http://sunscript.sun.com/TclTkCore/" name="Tk">.
58 Version 3.6, 4.X and 8.0 has been tested.
62 Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/.
69 This command tries to configure <sf/IrTcl/ for your system and creates
72 If the <tt>configure</tt> command cannot locate Tcl and Tk in your standard
73 locations for libraries searched by your C compiler it will guess
74 that the libraries are located in <tt>/usr/local/lib</tt> and that
75 the header files are located in <tt>/usr/local/include</tt>.
76 If this is incorrect you will have to modify the <tt>Makefile</tt> yourself.
78 Compile <sf/IrTcl/ by typing:
83 For Tcl versions that support dynamic libraries the command above
84 will create the shared library, <tt/irtcl.so/, as well as the
85 normal static library, <tt/libirtcl.a/.
87 For Tcl versions that doesn't support dynamic libraries the
88 command will create two shells will build-in <sf/IrTcl/ support --
89 a Tcl shell called <tt/ir-tcl/ and a Tcl/Tk shell called <tt/ir-tk/.
90 The traditional static library, <tt/libirtcl.a/, is build as well.
92 To install the programs and support files type:
97 If you wish to install man pages type:
102 Summary of files installed (the names refer to the Makefile variables):
105 <tag><tt>irtcl.so</tt></tag> The <sf/IrTcl/ shared dynamic library.
106 The actual name of this library vary. Installed in <tt>IRTCLDIR</tt>.
107 This file is only generated when using newer versions of Tcl.
109 <tag><tt>ir-tk</tt></tag> The <sf/IrTcl/ shell for Tk. This shell
110 is not needed when using a Tk that support for shared libraries is present.
111 Installed in <tt>BINDIR</tt> -- defaults to
112 <tt>/usr/local/bin</tt>. <tt>ir-tk</tt> works like
113 <tt>wish</tt> &mdash without arguments it reads commands from stdin.
114 A source file may be specified by option <tt>-f</tt>. <tt>ir-tk</tt>
115 accept the same set of options as <tt>wish</tt>.
117 <tag><tt>ir-tcl</tt></tag> The <sf/IrTcl/ shell for Tcl. This program
118 is not needed when using a Tcl that supports shared libraries. Installed
119 in <tt>BINDIR</tt> -- defaults to <tt>/usr/local/bin</tt>.
121 <tag><tt>client.tcl</tt></tag> A graphical client for <tt>ir-tk</tt>.
122 The client is installed as an executable script called <tt>irclient</tt> in
123 <tt>BINDIR</tt>. This client needs a number of files, bitmaps, etc.
124 The client looks for the files in the current directory &mdash if
125 this fails it tries to look in the directory <tt>IRTCLDIR</tt>
126 -- defaults to <tt>/usr/local/lib/irtcl</tt>.
128 <tag><tt>libirtcl.a</tt></tag> The <sf/IrTcl/ library.
129 Installed in <tt>LIBDIR</tt> -- defaults to <tt>/usr/local/lib</tt>.
131 <tag><tt>ir-tcl.h</tt></tag> The <sf/IrTcl/ header file.
132 Installed in <tt>INCDIR</tt> -- defaults to <tt>/usr/local/include</tt>.
134 <tag><tt>clientrc.tcl</tt></tag> A setup file with definitions
135 of target and queries. Read and updated by <tt>client.tcl</tt>. Installed
136 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
138 <tag><tt>formats/*</tt></tag> Display format files written
139 in Tk. Read by <tt>client.tcl</tt>. Installed
140 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
142 <tag><tt>bitmaps/*</tt></tag> Various bitmap files. Read by
143 <tt>client.tcl</tt>. Installed
144 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
146 <tag><tt>LICENSE</tt></tag> LICENSE file. Read by
147 <tt>client.tcl</tt>. Installed
148 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
154 Basic Tcl is handled by the program <tt/tclsh/. The script
155 must use the <tt/load/ command to load the <sf/IrTcl/ dynamic
156 library. If dynamic libraries are unsupported the <tt/ir-tcl/ program
157 should be used instead, since that program is statically linked
158 with the <sf/IrTcl/ library.
160 So the static, non-dynamic, version goes like this:
165 and the dynamic version goes like:
175 If your Tcl/Tk supports dynamic libraries you can use the
176 <tt/load/ command as described in the previous section. If not,
177 you must use the <tt>ir-tk</tt> shell that acts as <tt>wish</tt>
178 except that it includes the <sf/IrTcl/ commands.
180 The enclosed script <tt>client.tcl</tt> is a graphical client
181 which demonstates an example of a user interface for the Z39.50/SR protocols.
182 At first the script was relatively small but it has grown since the
183 beginning. At present it is about 3000 lines.
185 To start the client using a dynamic library use:
190 Note: some installations a slightly different name for wish, eg.
193 To start the client without dynamic library support use:
195 $ ir-tk -f client.tcl
198 The client lets up define targets and query types within the interface.
199 Hence, you will not need to modify configation files.
201 Stuff concerning targets can be found in the pull down menu 'Target'
202 with the following options:
204 <tag>Connect</tag> Establishes connection to a target.
205 <tag>Disconnect</tag> Closes a target connection.
206 <tag>About</tag> Shows implementation Id, implementation Version, etc
207 for the current target.
208 <tag>Setup</tag> Pops up a target definition window. You may alter
210 <tag>Setup new</tag> Lets you define a new target.
213 The term query type refers to a collection of search fields. The
214 pull down menu Options|Query deals with queries. You may
215 insert/modify/remove query types.
217 <sect>Overview of the API
220 Basically, <sf/IrTcl/ is a set of commands introduced to Tcl.
221 When extending Tcl there are two approaches: action-oriented commands
222 and object-oriented commands.
224 Action-oriented commands manipulate
225 Tcl variables and each command introduces only one action.
226 The string manipulation commands in Tcl are action oriented.
228 Object-oriented commands are added for every declared
229 variable (object). Object-oriented commands usually provide a set of
230 actions (methods) to manipulate the object.
231 The widgets in Tk (X objects) are examples of the object-oriented style.
233 <sf/IrTcl/ commands are object-oriented. The main reason
234 for this is that the data structures involved in the IR protocol
235 are not easily represented by Tcl data structures.
236 Also, the <sf/IrTcl/ objects tend to exist for a relativly long time.
237 Note that although we use the term object-oriented commands, this
238 does not mean that the programming style is strictly object-oriented. For
239 example, there is such no such thing as inheritance.
241 We are now ready to present the three commands introduced to Tcl by
245 <tag/ir/ The ir object represents a connection to a target. More
246 precisely it describes a Z-association.
247 <tag/ir-set/ The ir-set describes a result set, which is
248 conceptually a collection of records returned by the target.
249 The ir-set object may retrieve records from a target by means of
250 the ir object; it may read/write records from/to a local file or it may be
251 updated with a user-edited record.
252 <tag/ir-scan/ The scan object represents a list of scan lines
253 retrieved from a target.
258 To create a new IR object called <tt/z-assoc/ write:
265 Each object provides a set of <em/settings/ which may either be
266 readable, writeable of both. All settings immediately follow
267 the name of the object. If a value is present the setting
268 is set to <em/value/.
272 We wish to set the preferred-message-size to 18000 on the
276 z-assoc preferredMessageSize 18000
279 To read the current value of preferred-message-size use:
282 z-assoc preferredMessageSize
286 One important category consists of settings is those that relate to the
287 event-driven model. When <sf/IrTcl/ receives responses from the target, i.e.
288 init responses, search responses, etc., a <em/callback/ routine
289 is called. Callback routines are represented in Tcl as
290 a list, which is re-interpreted prior to invocation.
291 The method is similar to the one used in Tk to capture X events.
293 For each SR/Z39.50 request there is a corresponding object action. The most
294 important actions are:
296 <tag/connect/ Establishes connection with a target
297 <tag/init/ Sends an initialize request.
298 <tag/search/ Sends a search request.
299 <tag/present/ Sends a present request.
300 <tag/scan/ Sends a scan request.
305 This example shows a complete connect - init - search - present scenario.
307 First an IR object, called <tt/z/, is created.
308 Also a result set <tt/z.1/ is introduced by the <tt/ir-set/
309 and it is specified that the result set uses <tt/z/ as its association.
311 The setting <tt/databaseNames/ is set to the
312 database <tt/books/ to which the following searches are directed.
313 A callback is then defined and a connection is established to
314 <tt/fake.com/ by the <tt/connect/ action.
315 If the connect succeeds the <tt/connect-response/ is called.
317 In the Tcl procedure, <tt/connect-response/, a callback is defined
318 <em/before/ the init request is executed.
319 The Tcl procedure <tt/init-response/ is called when a
320 init response is returned from the target.
322 The <tt/init-response/ procedure sets up a <tt/search-response/
323 callback handler and sends a search-request by using a query which
324 consists of a single word <tt/science/.
326 When the <tt/search-response/ procedure is called it defines
327 a variable <tt/hits/ and sets it to the value of the setting
328 <tt/resultCount/. If <tt/hits/ is positive a present-request is
329 sent -- asking for 5 records from position 1.
331 Finally, a present response is received and the number of records
332 returned is stored in the variable <tt/ret/.
336 z databaseNames books
338 z callback {connect-response}
341 proc connect-response {} {
342 z callback {init-response}
346 proc init-response {} {
347 z callback {search-response}
351 proc search-response {} {
352 set hits [z.1 resultCount]
355 z callback {present-response}
360 proc present-response {} {
361 set ret [z.1 numberOfRecordsReturned]
362 puts "$ret records returned"
367 The previous example program doesn't care about error conditions.
368 If errors occur in the program they will be trapped by the Tcl error
369 handler. This is not always appropriate. However, Tcl offers a
370 <tt/catch/ command to support error handling by the program itself.
375 The ir object describes an association with a target.
376 This section covers the connect-init-disconnect actions provided
378 An ir object is created by the <tt/ir/ command and the
379 created object enters a 'not connected' state, because it isn't
380 connected to a target yet.
385 A connection is established by the <tt/connect/ action which is
386 immediately followed by a hostname. A number of settings affect the
387 <tt/connect/ action. Obviously, these settings should be set
388 <bf/before/ connecting. The settings are:
391 <tag><tt>comstack </tt><tt>mosi|tcpip</tt></tag>
393 <tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
394 Protocol type - ANSI/NISO Z39.50 or ISO SR.
395 <tag><tt>callback </tt><em>list</em></tag>
396 Tcl script called when the connection is established.
397 <tag><tt>failback </tt><em>list</em></tag>
398 Fatal error Tcl script. Called on protocol errors or if target
402 If the connect is unsuccessful either the connect action itself
403 will return an error code or the failback handler is invoked.
405 In general, the <tt>failback</tt> handler is invoked when serious
406 unrecoverable errors occur when communicating with the target.
407 In this case the <sf/IrTcl/ system shuts down the connection.
408 The <tt>failback</tt> handler might inspect the <tt>failInfo</tt>
409 setting to determine the cause of the failure; it returns
410 two elements. The first is an error integer; the second is an
411 english representation of the error. The error codes and
412 the corresponding messages are:
415 <tag><tt>0</tt></tag>ok
416 <tag><tt>1</tt></tag>connect failed
417 <tag><tt>2</tt></tag>connection closed
418 <tag><tt>3</tt></tag>connection closed
419 <tag><tt>4</tt></tag>failed to decode incoming APDU
420 <tag><tt>5</tt></tag>unknown APDU
423 Note: in case 3 the connection was closed during read a read operation
424 whereas in case 4 it was closed during a write operation.
429 If the connect operation succeeds the <tt/init/ action should be used.
430 The init related settings are:
433 <tag><tt>preferredMessageSize </tt><em>integer</em></tag>
434 Preferred-message-size. Default value is 30000.
435 <tag><tt>maximumRecordSize </tt><em>integer</em></tag>
436 Maximum-record-size. Default value is 30000.
437 <tag><tt>idAuthentication </tt><em>string</em> ...</tag>
438 Id-authentication. There are three forms. If any empty is
439 given, the Id-authentication is not used. If one non-empty string
440 is given, the 'open' authentication is used. If three strings are
441 specified, the version 'id-pass' authentication (version 3 only)
442 is used in which case the first string is groupId; the second string
443 is userId and the third string is password.
444 <tag><tt>implementationName </tt><em>string</em></tag>
445 Implementation-name of origin system.
446 <tag><tt>implementationId</tt></tag>
447 Implementation-id of origin system. This setting is read-only.
448 <tag><tt>implementationVersion</tt></tag>
449 Implementation-version of origin system. This settings is read-only.
450 <tag><tt>options </tt><em>list</em></tag>
451 Options to be negotiated in the init service. The list contains
452 the options that are set. Possible values are <tt>search</tt>,
453 <tt>present</tt>, <tt>delSet</tt>, <tt>resourceReport</tt>,
454 <tt>triggerResourceCtrl</tt>, <tt>resourceCtrl</tt>,
455 <tt>accessCtrl</tt>, <tt>scan</tt>, <tt>sort</tt>,
456 <tt>extendedServices</tt>, <tt>level-1Segmentation</tt>,
457 <tt>level-2Segmentation</tt>, <tt>concurrentOperations</tt> and
458 <tt>namedResultSets</tt>. Currently the default options are:
459 <tt>search</tt>, <tt>present</tt>, <tt>scan</tt> and
460 <tt>namedResultSets</tt>. The <tt>options</tt> setting is set to its default
461 value when an ir object is created and when a <tt>disconnect</tt>
463 <tag><tt>protocolVersion </tt><em>integer</em></tag>
464 Protocol version: 2, 3, etc. Default is 2.
465 <tag><tt>referenceId </tt><em>string</em></tag>
466 Reference-id of init operation. If <em>string</em> is empty no
467 reference-id is used.
468 <tag><tt>initResponse </tt><em>list</em></tag>
469 Init-response Tcl script.
470 <tag><tt>callback </tt><em>list</em></tag>
471 General response Tcl script. Only used if <tt>initResponse</tt>
475 The init-response handler should inspect some of the settings shown
479 <tag><tt>initResult </tt>returns <em>boolean</em></tag>
480 Init response status. True if init operation was successful;
482 <tag><tt>preferredMessageSize </tt>returns <em>integer</em></tag>
483 Preferred-message-size after negotiation.
484 <tag><tt>maximumRecordSize </tt>returns <em>integer</em></tag>
485 Maximum-record-size after negotiation.
486 <tag><tt>targetImplementationName </tt>returns <em>string</em></tag>
487 Implementation-name of target system.
488 <tag><tt>targetImplementationId </tt>returns <em>string</em></tag>
489 Implementation-id of target system.
490 <tag><tt>targetImplementationVersion </tt>returns <em>string</em></tag>
491 Implementation-version of target system.
492 <tag><tt>options </tt>returns <em>list</em></tag>
493 Options after negotiation. The list contains the options that are set.
494 <tag><tt>protocolVersion </tt>returns <em>integer</em></tag>
495 Protocol version: 2, 3, etc after negotiation.
496 <tag><tt>userInformationField </tt>returns <em>string</em></tag>
497 User information field.
498 <tag><tt>referenceId </tt>returns <em>string</em></tag>
499 Reference-id of init response.
504 Consider a client with the ability to access multiple targets.
506 We define a list of targets that we wish to connect to.
507 Each item in the list describes the target parameters with
508 the following four components: association-name, comstack-type,
509 protocol-type and a hostname.
511 The list for the two targets: ISO/SR target DANBIB and TCP/Z39.50
512 target Data Research, will be defined as:
514 set targetList { {danbib mosi SR 0103/find2.denet.dk:4500}
515 {drs tcpip Z39 dranet.dra.com} }
518 The Tcl code below defines, connect and initialize the
519 targets in <tt/targetList/:
522 foreach target $targetList {
523 set assoc [lindex $target 0]
525 $assoc comstack [lindex $target 1]
526 $assoc protocol [lindex $target 2]
527 $assoc failback [list fail-response $assoc]
528 $assoc callback [list connect-response $assoc]
529 $assoc connect [lindex $target 3]
532 proc connect-response {assoc} {
533 $assoc callback [list init-response $assoc]
537 proc fail-response {assoc} {
538 puts "$assoc closed connection or protocol error"
541 proc init-response {assoc} {
542 if {[$assoc initResult]} {
543 puts "$assoc initialized ok"
545 puts "$assoc didn't initialize"
550 <tt/target/ is bound to each item in the list of targets.
551 The <tt/assoc/ is set to the ir object name.
552 Then, the comstack, protocol and failback are set for the <tt/assoc/ object.
553 The ir object name is argument to the <tt/fail-response/ and
554 <tt/connect-response/ routines.
555 Note the use of the Tcl <tt/list/ command which
556 is necessary here because the argument contains variables
557 (<tt/assoc/) that should be substituted before the handler is defined.
558 After the connect operation, the <tt/init-response/ handler
559 is defined in much the same way as the failback handler.
560 And, finally, an init request is executed.
567 To terminate the connection the <tt/disconnect/ action should be used.
568 This action has no parameters.
569 Another connection may be established by a new <tt/connect/ action on
575 This section covers the queries used by <sf/IrTcl/, and how searches and
576 presents are handled.
578 A search operation and a result set is described by the ir set object.
579 The ir set object is defined by the <tt/ir-set/ command which
580 has two parameters. The first is the name of the new ir set object, and
581 the second, which is optional, is the name of an assocation -- an ir
582 object. The second argument is required if the ir set object should be able
583 to perform searches and presents. However, it is not required if
584 only ``local'' operations is done with the ir set object.
586 When the ir set object is created a number of settings are inherited
587 from the ir object, such as the selected databass, query type,
588 etc. Thus, the ir object contains what we could call default
594 Search requests are sent by the <tt/search/ action which
595 takes a query as parameter. There are two types of queries,
596 RPN and CCL, controlled by the setting <tt/queryType/.
597 A string representation for the query is used in <sf/IrTcl/ since
598 Tcl has reasonably powerful string manipulaton capabilities.
599 The RPN query used in <sf/IrTcl/ is the prefix query notation also used in
600 the <bf/YAZ/ test client.
602 The CCL query is an uninterpreted octet-string which is parsed by the target.
603 We refer to the standard: ISO 8777. Note that only a few targets
604 actually support the CCL query and the interpretation of
605 the standard may vary.
607 The prefix query notation (which is converted to RPN) offer a few
611 <tag><tt>@attr </tt><em>list op</em></tag>
612 The attributes in list are applied to op
613 <tag><tt>@and </tt><em>op1 op2</em></tag>
614 Boolean <em/and/ on op1 and op2
615 <tag><tt>@or </tt><em>op1 op2</em></tag>
616 Boolean <em/or/ on op1 and op2
617 <tag><tt>@not </tt><em>op1 op2</em></tag>
618 Boolean <em/not/ on op1 and op2
619 <tag><tt>@prox </tt><em>list op1 op2</em></tag>
620 Proximity operation on op1 and op2. Not implemented yet.
621 <tag><tt>@set </tt><em>name</em></tag>
623 <tag><tt>@attrset </tt><em>set</em></tag>
624 Whole query uses the specified attribute <em>set</em>. If this operator is
625 used it must be defined at the beginning of the query.
628 It is simple to build RPN queries in <sf/IrTcl/. Search terms
629 are sequences of characters, as in:
634 Boolean operators use the prefix notation (instead of the suffix/RPN),
637 @and science technology
640 Search terms may be associated with attributes. These
641 attributes are indicated by the <tt/@attr/ operator.
642 Assuming the bib-1 attribute set, we can set the use-attribute
643 (type is 1) to title (value is 4):
649 Also, it is possible to apply attributes to a range of search terms.
650 In the query below, both search terms have use=title but the <tt/tech/
651 term is right truncated:
654 @attr 1=4 @and @attr 5=1 tech beta
657 To search for the DatabaseInfo records from an Explain server, we
660 @attrset exp1 @attr 1=1 DatabaseInfo
666 The settings that affect the search are listed below:
669 <tag><tt>databaseNames </tt><em>list</em></tag>
671 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
672 Small set upper bound. Default 0.
673 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
674 Large set lower bound. Default 2.
675 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
676 Medium set present number. Default 0.
677 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>
678 Replace-indicator. Default true (1).
679 <tag><tt>setName </tt><em>string</em></tag>
680 Name of result set. Default name of set is <tt/default/.
681 <tag><tt>queryType rpn|ccl</tt></tag>
682 Query type-1 or query type-2. Default rpn (type-1).
683 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
684 Preferred record syntax -- UNIMARC, USMARC, etc.
685 <tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
686 small-set-element-set names. If <em>string</em> is empty
687 the element set is not set. Default is empty (not set).
688 <tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
689 medium-set-element-set names. If <em>string</em> is empty
690 the element set is not set. Default is empty (not set).
691 <tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
692 Next result set position.
693 <tag><tt>referenceId </tt><em>string</em></tag>
694 Reference-id. If <em>string</em> is empty no reference-id is used.
695 <tag><tt>searchResponse </tt><em>list</em></tag>
696 Search-response Tcl script.
697 <tag><tt>callback </tt><em>list</em></tag>
698 General response Tcl script. Only used if searchResponse is not specified.
699 This setting is valid only for the <tt/ir/ object -- not the
703 Setting the <tt/databaseNames/ is mandatory. All other settings
704 have reasonable defaults.
705 The search-response handler, specified by the <tt/callback/ - or
706 the <tt/searchResponse/ setting,
707 should read some of the settings shown below:
710 <tag><tt>searchStatus</tt> returns <em>boolean</em></tag>
711 Search-status. True if search operation was successful; false
713 <tag><tt>responseStatus </tt>returns <em>list</em></tag>
714 Response status information.
715 <tag><tt>resultCount </tt>returns <em>integer</em></tag>
717 <tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
718 Number of records returned.
719 <tag><tt>referenceId </tt>returns <em>string</em></tag>
720 Reference-id of search response.
723 The <tt/responseStatus/ signals one of three conditions which
724 is indicated by the value of the first item in the list:
727 <tag><tt>NSD</tt></tag> indicates that the target has returned one or
728 more non-surrogate diagnostic messages. The <tt/NSD/ item is followed by
729 a list with all non-surrogate messages. Each non-surrogate message consists
730 of three items. The first item of the three items is the error
731 code (integer); the next item is a textual representation of the error
732 code in plain english; the third item is additional information, possibly
733 empty if no additional information was returned by the target.
735 <tag><tt>DBOSD</tt></tag> indicates a successful operation where the
736 target has returned one or more records. Each record may be
737 either a database record or a surrogate diagnostic.
739 <tag><tt>OK</tt></tag> indicates a successful operation -- no records are
740 returned from the target.
745 We continue with the multiple-targets example.
746 The <tt/init-response/ procedure will attempt to make searches:
749 proc init-response {assoc} {
750 puts "$assoc connected"
751 ir-set ${assoc}.1 $assoc
752 $assoc.1 queryType rpn
753 $assoc.1 databaseNames base-a base-b
754 $assoc callback [list search-response $assoc ${assoc}.1]
755 $assoc.1 search "@attr 1=4 @and @attr 5=1 tech beta"
759 An ir set object is defined and the
760 ir object is told about the name of ir object.
761 The ir set object use the name of the ir object as prefix.
763 Then, the query-type is defined to be RPN, i.e. we will
764 use the prefix query notation later on.
766 Two databases, <tt/base-a/ and <tt/base-b/, are selected.
768 A <tt/search-response/ handler is defined with the
769 ir object and the ir-set object as parameters and
770 the search is executed.
772 The first part of the <tt/search-response/ looks like:
774 proc search-response {assoc rset} {
775 set status [$rset responseStatus]
776 set type [lindex $status 0]
777 if {$type == "NSD"} {
778 set code [lindex $status 1]
779 set msg [lindex $status 2]
780 set addinfo [lindex $status 3]
781 puts "NSD $code: $msg: $addinfo"
784 set hits [$rset resultCount]
785 if {$type == "DBOSD"} {
786 set ret [$rset numberOfRecordsReturned]
791 The response status is stored in variable <tt/status/ and
792 the first element indicates the condition.
793 If non-surrogate diagnostics are returned they are displayed.
794 Otherwise, the search was a success and the number of hits
795 is read. Finally, it is tested whether the search response
796 returned records (database or diagnostic).
798 Note that we actually didn't inspect the search status (setting
799 <tt/searchStatus/) to determine whether the search was successful or not,
800 because the standard specifies that one or more non-surrogate
801 diagnostics should be returned by the target in case of errors.
805 If one or more records are returned from the target they
806 will be stored in the result set object.
807 In the case in which the search response contains records, it is
808 very similar to the present response case. Therefore, some settings
809 are common to both situations.
814 The <tt/present/ action sends a present request. The <tt/present/ is
815 followed by two optional integers. The first integer is the
816 result-set starting position -- defaults to 1. The second integer
817 is the number of records requested -- defaults to 10.
818 The settings which could be modified before a <tt/present/
822 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
823 preferred record syntax -- UNIMARC, USMARC, etc.
824 <tag><tt>elementSetNames </tt><em>string</em></tag>
825 Element-set names. If <em>string</em> is empty
826 the element set is not set. Default is empty (not set).
827 <tag><tt>referenceId </tt><em>string</em></tag>
828 Reference-id. If <em>string</em> is empty no reference-id is used.
829 <tag><tt>presentResponse </tt><em>list</em></tag>
830 Present-response Tcl script.
831 <tag><tt>callback </tt><em>list</em></tag>
832 General response Tcl script. Only used if presentResponse is not specified
833 This setting is valid only for the <tt/ir/ object -- not the
837 The present-response handler should inspect the settings
838 shown in table below.
839 Note that <tt/responseStatus/ and <tt/numberOfRecordsReturned/
840 settings were also used in the search-response case.
842 As in the search response case, records returned from the
843 target are stored in the result set object.
846 <tag><tt>presentStatus </tt>returns <em>boolean</em></tag>
848 <tag><tt>responseStatus </tt>returns <em>list</em></tag>
849 Response status information.
850 <tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
851 Number of records returned.
852 <tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
853 Next result set position.
854 <tag><tt>referenceId </tt>returns <em>string</em></tag>
855 Reference-id of present response.
861 Search responses and present responses may result in
862 one or more records stored in the ir set object if
863 the <tt/responseStatus/ setting indicates database or
864 surrogate diagnostics (<tt/DBOSD/). The individual
865 records, indexed by an integer position offset, should then be
868 If element set names have been specified either in the
869 search requests (<tt>smallSetElementSetNames</tt> /
870 <tt>mediumSetElementSetNames</tt>) or present requests
871 (<tt>elementSetNames</tt>) the individual records in the
872 ir set object are assigned appropriate element set ids.
873 In this mode records at a given position are treated different as
874 long as they have difference element set ids.
875 To inspect records with a particular element set id in subsequent
876 operations use the <tt>recordElements</tt> setting followed by the id.
877 If you have more than one record at a given position and you do not
878 use <tt>recordElements</tt> the record selected at the given position
881 The action <tt>type</tt> followed by an integer returns information
882 about a given position in an ir set. There are three possiblities:
885 <tag><tt/SD/</tag> The item is a surrogate diagnostic record.
886 <tag><em/empty/</tag> There is no record at the specified position.
887 <tag><tt/DB/</tag> The item is a database record.
890 To handle the first case, surrogate diagnostic record, the
891 <tt/Diag/ action should be used. It returns three
892 items: error code (integer), text representation in plain english
893 (string), and additional information (string, possibly empty).
895 In the second case, no record, note that there still might
896 be a record at the position but with an id that differs from that
897 specified by <tt>recordElements</tt>.
899 In the third case, database record, the <tt/recordType/ action should
900 be used. It returns the record type at the given position.
901 Some record types are:
918 We continue our search-response example. In the case,
919 <tt/DBOSD/, we should inspect the result set items.
920 Recall that the ir set name was passed to the
921 search-response handler as argument <tt/rset/.
924 if {$type == "DBOSD"} {
925 set ret [$rset numberOfRecordsReturned]
926 for {set i 1} {$i<=$ret} {incr i} {
927 set itype [$rset type $i]
928 if {$itype == "SD"} {
929 set diag [$rset Diag $i]
930 set code [lindex $diag 0]
931 set msg [lindex $diag 1]
932 set addinfo [lindex $diag 2]
933 puts "$i: NSD $code: $msg: $addinfo"
934 } elseif {$itype == "DB"} {
935 set rtype [$rset recordType $i]
936 puts "$i: type is $rtype"
941 Each item in the result set is examined.
942 If an item is a diagnostic message it is displayed; otherwise
943 if it's a database record its type is displayed.
950 In the case, where there is a MARC record at a given position we
951 want to display it somehow. The action <tt/getMarc/ is what we need.
952 The <tt/getMarc/ is followed by a position integer and the type of
953 extraction we want to make: <tt/field/ or <tt/line/.
955 The <tt/field/ and <tt/line/ type are followed by three
956 parameters that serve as extraction masks.
957 They are called tag, indicator and field.
958 If the mask matches a tag/indicator/field of a record the information
959 is extracted. Two characters have special meaning in masks: the
960 dot (any character) and star (any number of any character).
962 The <tt/field/ type returns one or more lists of field information
963 that matches the mask specification. Only the content of fields
966 The <tt/line/ type, on the other hand, returns a Tcl list that
967 completely describe the layout of the MARC record -- including
970 The <tt/field/ type is sufficient and efficient in the case, where only a
971 small number of fields are extracted, and in the case where no
972 further processing (in Tcl) is necessary.
974 However, if the MARC record is to be edited or altered in any way, the
975 <tt/line/ extraction is more powerful -- only limited by the Tcl
980 Consider the record below:
985 008 910710c19910701nju 00010 eng
989 100 10 $a Jack Collins
990 245 10 $a How to program a computer
996 Assuming this record is at position 1 in ir-set <tt/z.1/, we
997 might extract the title-field (245 * a), with the following command:
999 z.1 getMarc 1 field 245 * a
1004 {How to program a computer}
1007 Using the <tt/line/ instead of <tt/field/ gives:
1009 {245 {10} {{a {How to program a computer}} }}
1012 If we wish to extract the whole record as a list, we use:
1014 z.1 getMarc 1 line * * *
1019 {001 {} {{{} { 11224466 }} }}
1020 {003 {} {{{} DLC} }}
1021 {005 {} {{{} 00000000000000.0} }}
1022 {008 {} {{{} {910710c19910701nju 00010 eng }} }}
1023 {010 { } {{a { 11224466 }} }}
1024 {040 { } {{a DLC} {c DLC} }}
1025 {050 {00} {{a 123-xyz} }}
1026 {100 {10} {{a {Jack Collins}} }}
1027 {245 {10} {{a {How to program a computer}} }}
1028 {260 {1 } {{a Penguin} }}
1029 {263 { } {{a 8710} }}
1030 {300 { } {{a {p. cm.}} }}
1037 This example demonstrates how Tcl can be used to examine
1038 a MARC record in the list notation.
1040 The procedure <tt/extract-format/ makes an extraction of
1041 fields in a MARC record based on a number of masks.
1042 There are 5 parameters, <tt/r/: a
1043 record in list notation, <tt/tag/: regular expression to
1044 match the record tags, <tt/ind/: regular expression to
1045 match indicators, <tt/field/: regular expression to
1046 match fields, and finally <tt/text/: regular expression to
1047 match the content of a field.
1050 proc extract-format {r tag ind field text} {
1052 if {[regexp $tag [lindex $line 0]] && \
1053 [regexp $ind [lindex $line 1]]} {
1054 foreach f [lindex $line 2] {
1055 if {[regexp $field [lindex $f 0]]} {
1056 if {[regexp $text [lindex $f 1]]} {
1066 To match <tt/comput/ followed by any number of character(s) in the
1067 245 fields in the record from the previous example, we could use:
1069 set r [z.1 getMarc 1 line * * *]
1071 extract-format $r 245 .. . comput
1075 How to program a computer
1080 The <tt/putMarc/ action does the opposite of <tt/getMarc/. It
1081 copies a record in Tcl list notation to a ir set object and is
1082 needed if a result-set must be updated by a Tcl modified (user-edited)
1088 In <sf/IrTcl/ a SUTRS record is treated as one single string. To retrieve
1089 a SUTRS record use the <tt>getSutrs</tt> followed by an index.
1093 A GRS-1 record in <sf/IrTcl/ is represented as a list of elements.
1094 Each element specifies a tag as well as data. The data may
1095 be a subtree, which is represented as a list, and so on.
1097 The method <tt/getGrs/ is followed by a record index and
1098 optional specifiers that selects a specific sub-tree. Each element
1099 consists of 5 elements:
1102 <tag>tag-set</tag> Tag set number.
1104 <tag>value-type</tag> Type of tag value. May be either
1105 <tt/numeric/ of <tt/string/.
1107 <tag>value</tag> The value it self.
1109 <tag>data-type</tag> May be either <tt/octets/, <tt/numeric/,
1110 <tt/ext/, <tt/string/, <tt/bool/, <tt/intUnit/, <tt/empty/,
1111 <tt/notRequested/, <tt/diagnostic/ or <tt/subtree/.
1113 <tag>data</tag>The data associated with element of given type as
1114 indicated before. If data-type is <tt/numeric/ or <tt/string/
1115 then data is encoded as a single Tcl token. The data-type <tt/bool/
1116 is encoded as 0 or 1 for false and true respectively. If the
1117 data-type is <tt/subtree/ the data is a sub-list.
1118 In all other cases, the data is the empty string.
1123 Consider the GRS-1 record below as shown by the Yaz client program:
1126 (1,1) OID: GILS-schema
1128 (2,1) UTAH EARTHQUAKE EPICENTERS
1129 class=4,type=1,value=us
1130 (4,52) UTAH GEOLOGICAL AND MINERAL SURVEY
1131 (3,Local-Subject-Index) APPALACHIAN VALLEY; EARTHQUAKE; EPICENTER
1133 (1,19) Five files of epicenter data arranged by ...
1134 (3,Format) DIGITAL DATA SETS
1135 (3,Data-Category) TERRESTRIAL
1136 (3,Comments) Data are supplied by the University of Utah ...
1139 (2,10) UTAH GEOLOGICAL AND MINERAL SURVEY
1140 (4,2) 606 BLACK HAWK WAY
1141 (4,3) SALT LAKE CITY
1145 (2,14) (801) 581-6831
1146 (4,7) UTAH EARTHQUAKE EPICENTERS
1151 The record may be fetched from the result set, <tt/z.1/, at position 1
1158 { 1 numeric 1 oid 1.2.840.10003.13.2 }
1159 { 1 numeric 14 string 2 }
1160 { 2 numeric 1 string
1161 { UTAH EARTHQUAKE EPICENTERS} }
1162 { 4 numeric 52 string {UTAH GEOLOGICAL AND MINERAL SURVEY} }
1163 { 3 string Local-Subject-Index string
1164 {APPALACHIAN VALLEY; EARTHQUAKE; EPICENTER} }
1165 { 2 numeric 6 subtree
1166 { { 1 numeric 19 string
1167 {Five files of epicenter data arranged by ...} }
1168 { 3 string Format string {DIGITAL DATA SETS} }
1169 { 3 string Data-Category string TERRESTRIAL }
1170 { 3 string Comments string
1171 {Data are supplied by the University of Utah ...} } } }
1172 { 4 numeric 70 subtree
1173 { { 4 numeric 90 subtree
1174 { { 2 numeric 10 string
1175 {UTAH GEOLOGICAL AND MINERAL SURVEY} }
1176 { 4 numeric 2 string {606 BLACK HAWK WAY} }
1177 { 4 numeric 3 string {SALT LAKE CITY} }
1178 { 3 string State string UT }
1179 { 3 string Zip-Code string 84108 }
1180 { 2 numeric 16 string USA }
1181 { 2 numeric 14 string {(801) 581-6831} } } }
1182 { 4 numeric 7 string {UTAH EARTHQUAKE EPICENTERS} } } }
1183 { 4 numeric 1 string ESDD0006 }
1184 { 1 numeric 16 string 198903 }
1187 We can choose only to get the path (2,6) by using:
1194 { 2 numeric 6 subtree { { 1 numeric 19 string
1195 {Five files of epicenter data arranged by ...} }
1196 { 3 string Format string {DIGITAL DATA SETS} }
1197 { 3 string Data-Category string TERRESTRIAL }
1199 string {Data are supplied by the University of Utah ...} } } }
1202 To get the well known (1,19) within the subject (2,6) we use
1204 z.1 getGrs 1 (2,6) (1,19)
1208 { 2 numeric 6 subtree
1209 { { 1 numeric 19 string
1210 {Five files of epicenter data arranged by ...} } } }
1216 Explain records are retrieved like other records. The method,
1217 <tt>getExplain</tt> is followed by an index and and an optional
1218 Explain record pattern.
1220 The returned record is a canonical representation of the Explain record.
1221 An ASN.1 sequence is represented as a list. Each item in the list
1222 consists of the name of the element, followed by its value if the value
1225 The optional pattern that follows the index after <tt>getExplain</tt>
1226 consists of one or more elements, that is matched against the elements
1227 of the actual record.
1231 One of the few targets that support explain is the ATT research server
1232 at <tt>z3950.research.att.com</tt>.
1234 The targetInfo record was returned by the target and it's stored in
1235 position 1 in the result set, <tt>z.1</tt>. To retrieve the whole
1241 and we get in return
1244 {targetInfo commonInfo {name {Lucent Technologies Research Server}}
1245 recentNews icon {namedResultSets 1} {multipleDBsearch 0}
1246 {maxResultSets 100} {maxResultSize 600000} maxTerms timeoutInterval
1247 {welcomeMessage {strings { {language eng}
1249 {Salutations - this is Lucent Technologies experimental Z39.50 server.
1250 No guarentees, but free and unlimited access!}} } } }
1251 {contactInfo {name {Robert Waldstein}} {description {strings
1253 {text {Librarian system designer - no legal anythings}} } } }
1254 {address {strings { {language eng} {text {Room 3D-591
1257 N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}} }
1258 description nicknames {usageRest {strings { {language eng}
1259 {text {None - as long as nonProfit research}} } } } paymentAddr
1260 {hours {strings { {language eng} {text {Should never be down}} } } }
1261 dbCombinations addresses commonAccessInfo }
1264 The <tt>targetInfo</tt> above indicates the the record is really a
1265 <tt>targetInfo</tt> record. The <tt>commonInfo</tt>, which is optional, is
1266 not supplied by this server. The <tt>name</tt>, however is supplied,
1267 with the value <tt>Lucent Technologies Research Server</tt>.
1269 To retrieve the <tt>contactInfo</tt> from the record above we can
1270 extract the element from the record by using Tcl's list manipulation
1271 facilities, for example by doing
1273 set ti [z.1 getExplain 1]
1274 lindex [lindex $ti 0] 12
1278 contactInfo {name {Robert Waldstein}} {description {strings
1280 {text {Librarian system designer - no legal anythings}} }
1281 } } {address {strings { {language eng} {text {Room 3D-591
1284 N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}}
1287 We can also extract almost the same by doing
1289 z.1 getExplain 1 targetInfo contactInfo
1293 {name {Robert Waldstein}} {description {strings { {language eng}
1294 {text {Librarian system designer - no legal anythings}} } } }
1295 {address {strings { {language eng} {text {Room 3D-591
1298 N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}}
1306 To perform scan, a scan object must be created by the <tt>ir-scan</tt>
1307 command. This command has two arguments -- name of the scan object and
1308 name of the ir object. Basically, the scan object, provides one <tt>scan</tt>
1309 action which sends a scan request to the target. The <tt>action</tt>
1310 is followed by a string describing starting point of the term list. The
1311 format used is a simple subset of the query used in search requests. Only
1312 <tt>@attr</tt> specifications and simple terms are allowed.
1313 The settings that affect the scan are:
1316 <tag><tt>stepSize </tt><em>integer</em></tag>
1317 Step size. Default is 0.
1318 <tag><tt>numberOfTermsRequested </tt><em>integer</em></tag>
1319 Number of terms requested. Default is 20.
1320 <tag><tt>preferredPositionInResponse </tt><em>integer</em></tag>
1321 Preferred position in response. Default is 1.
1322 <tag><tt>databaseNames </tt><em>list</em></tag>
1323 Database names. Note that this setting is not (yet) supported for
1324 the scan object. You must set this for the ir object instead.
1325 <tag><tt>referenceId </tt><em>string</em></tag>
1326 Reference-id. If <em>string</em> is empty no reference-id is used.
1327 <tag><tt>scanResponse </tt><em>list</em></tag>
1328 Scan-response Tcl script.
1329 <tag><tt>callback </tt><em>list</em></tag>
1330 General response Tcl script. Only used if <tt>scanResponse</tt>
1332 This setting is valid only for the <tt/ir/ object -- not the
1336 The scan object normally holds one or more scan line entries upon
1337 successful completion. The table below summarizes the settings
1338 that should be used in a response handler.
1341 <tag><tt>scanStatus </tt>returns <em>integer</em></tag>
1342 Scan status. An integer between 0 and 6.
1343 <tag><tt>numberOfTermsReturned </tt>returns <em>integer</em></tag>
1344 Number of terms returned.
1345 <tag><tt>positionOfTerm </tt>returns <em>integer</em></tag>
1346 An integer describing the position of term.
1347 <tag><tt>scanLine </tt>returns <em>list</em></tag>
1348 This function returns information about a given scan line (entry) at a given
1349 index specified by the integer. The first scan line is numbered zero;
1350 the second 1 and so on. A list is returned by the <tt>scanLine</tt>
1351 setting. The first element is <tt>T</tt> if the scan line
1352 is a normal term and <tt>SD</tt> if the scan line is a surrogate
1353 diagnostic. In the first case (normal) the scan term is second element
1354 in the list and the number of occurences is the third element.
1355 In the other case (surrogate diagnostic), the second element
1356 is the diagnostic code, the third a text representation of the error
1357 code and the fourth element is additional information.
1358 <tag><tt>referenceId </tt>returns <em>string</em></tag>
1359 Reference-id of scan response.
1364 We will scan for the terms after <tt>science</tt> in the Title index.
1365 We will assume that an ir object called <tt>z-assoc</tt> has already
1369 z-assoc callback {scan-response}
1370 ir-scan z-scan z-assoc
1371 z-scan scan "@attr 1=4 science"
1373 proc scan-response {} {
1374 set status [z-scan status]
1376 set no [z-scan numberOfTermsReturned]
1377 for {set i 0} {$i < $no} {incr i} {
1378 set line [z-scan scanLine $i]
1379 set type [lindex $line 0]
1381 puts [lindex $line 1]
1382 } elseif {$type == "SD"} {
1383 puts [lindex $line 1]
1394 Copyright © 1995-1998, Index Data.
1396 Permission to use, copy, modify, distribute, and sell this software and
1397 its documentation, in whole or in part, for any purpose, is hereby granted,
1400 1. This copyright and permission notice appear in all copies of the
1401 software and its documentation. Notices of copyright or attribution
1402 which appear at the beginning of any file must remain unchanged.
1404 2. The names of Index Data or the individual authors may not be used to
1405 endorse or promote products derived from this software without specific
1406 prior written permission.
1408 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
1409 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
1410 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1411 IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
1412 INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
1413 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
1414 NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
1415 LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
1418 <sect>About Index Data
1421 Index Data is a consulting and software-development enterprise that
1422 specialises in library and information management systems. Our
1423 interests and expertise span a broad range of related fields, and one
1424 of our primary, long-term objectives is the development of a powerful
1425 information management
1426 system with open network interfaces and hypermedia capabilities.
1428 We make this software available free of charge, on a fairly unrestrictive
1429 license; as a service to the networking community, and to further the
1430 development of quality software for open network communication.
1432 We'll be happy to answer questions about the software, and about ourselves
1443 Phone: +45 3536 3672
1445 Email: info@indexdata.dk
1453 <tag>1 Ousterhout, John K.:</tag>
1454 Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
1455 0-201-63337-X). The Tcl/Tk toolkit home page is
1456 <tt><htmlurl url="http://www.sunscript.com"
1457 name="http://www.sunscript.com"></tt>.
1458 The primary ftp site is <tt><htmlurl url="ftp://ftp.smli.com/pub/tcl/"
1459 name="ftp://ftp.smli.com/pub/tcl/"></tt>.
1460 <tag>2 Welch, Brent B.:</tag>
1461 Practical Programming in Tcl and Tk. Prentice Hall
1462 (ISBN 0-13-616830-2).