1 <!doctype linuxdoc system>
4 $Id: ir-tcl.sgml,v 1.15 1996-01-10 11:15:41 adam Exp $
8 <title>IrTcl User's Guide and Reference
9 <author><htmlurl url="http://130.225.252.168/" name="Index Data">,
10 <tt><htmlurl url="mailto:info@index.ping.dk" name="info@index.ping.dk"></tt>
11 <date>$Revision: 1.15 $
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/ provides two system environments:
42 <item> A simple command line shell -- useful for
44 <item> A simple command line shell which operates within the Tk
45 environment -- makes it very easy to implement GUI clients.
48 <sect>Compilation and installation
51 In order to compile you need:
53 <item> An ANSI C compiler such as GNU C.
54 <item> <htmlurl url="http://www.sunlabs.com/research/tcl/" name="Tcl">.
55 Version 7.3, 7.4 and 7.5 has been tested.
56 <item> <htmlurl url="http://130.225.252.168/yaz.html" name="Yaz">
57 version 1.0 patch level 3 or higher.
60 As an option you may want:
62 <item> <htmlurl url="http://www.sunlabs.com/research/tcl/" name="Tk">.
63 Version 3.6, 4.0 and 4.1 has been tested.
67 Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/.
74 This command tries to configure <sf/IrTcl/ for your system and creates
77 If the <tt>configure</tt> command cannot locate Tcl and Tk in your standard
78 locations for libraries searched by your C compiler it will guess
79 that the libraries are located in <tt>/usr/local/lib</tt> and that
80 the header files are located in <tt>/usr/local/include</tt>.
81 If this is incorrect you will have to modify the <tt>Makefile</tt> yourself.
83 Compile <sf/IrTcl/ by typing:
88 If you don't have Tk you will only be able to create the <tt>ir-tcl</tt>
89 program and you must type <tt>make ir-tcl</tt> instead.
91 If successful, this will make <tt>ir-tcl</tt>, <tt>ir-tk</tt> (if
92 Tk is present) and a library called <tt>libirtcl.a</tt>.
94 To install the programs and support files type:
99 Summary of files installed (the names refer to the Makefile variables):
102 <tag><tt>ir-tk</tt></tag> The <sf/IrTcl/ shell for Tk.
103 Installed in <tt>BINDIR</tt> -- defaults to
104 <tt>/usr/local/bin</tt>. <tt>ir-tk</tt> works like
105 <tt>wish</tt> &mdash without arguments it reads commands from stdin.
106 A source file may be specified by option <tt>-f</tt>. <tt>ir-tk</tt>
107 accept the same set of options as <tt>wish</tt>.
108 <tag><tt>ir-tcl</tt></tag> The <sf/IrTcl/ shell for Tcl. Installed in
109 <tt>BINDIR</tt> -- defaults to <tt>/usr/local/bin</tt>.
110 <tag><tt>client.tcl</tt></tag> A graphical client for <tt>ir-tk</tt>.
111 The client is installed as an executable script called <tt>irclient</tt> in
112 <tt>BINDIR</tt>. This client needs a number of files, bitmaps, etc.
113 The client looks for the files in the current directory &mdash if
114 this fails it tries to look in the directory <tt>IRTCLDIR</tt>
115 -- defaults to <tt>/usr/local/lib/irtcl</tt>.
116 <tag><tt>libirtcl.a</tt></tag> The <sf/IrTcl/ library.
117 Installed in <tt>LIBDIR</tt> -- defaults to <tt>/usr/local/lib</tt>.
118 <tag><tt>ir-tcl.h</tt></tag> The <sf/IrTcl/ header file.
119 Installed in <tt>INCDIR</tt> -- defaults to <tt>/usr/local/include</tt>.
120 <tag><tt>clientrc.tcl</tt></tag> A setup file with definitions
121 of target and queries. Read and updated by <tt>client.tcl</tt>. Installed
122 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
123 <tag><tt>formats/*</tt></tag> Display format files written
124 in Tk. Read by <tt>client.tcl</tt>. Installed
125 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
126 <tag><tt>bitmaps/*</tt></tag> Various bitmap files. Read by
127 <tt>client.tcl</tt>. Installed
128 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
129 <tag><tt>LICENSE</tt></tag> LICENSE file. Read by
130 <tt>client.tcl</tt>. Installed
131 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
137 The <tt>ir-tcl</tt> program is a shell like <tt>tclsh</tt> except that
138 <tt>ir-tcl</tt> features the new set of information retrieval commands.
139 Normally <tt>ir-tcl</tt> waits on <tt/stdin/ (for you to type commands) and
140 on sockets events (connected to Z39.50/SR targets).
141 You simply type the Tcl commands line by line. A filename may be specified as
142 argument to <tt>ir-tcl</tt> in which case the file specified is evaluated
148 <tt>ir-tk</tt> is a program that works like <tt>wish</tt> except that
149 <tt>ir-tk</tt> include the new set of commands. All options accepted
150 by <tt>wish</tt> are also accepted by <tt>ir-tk</tt>.
152 The enclosed script <tt>client.tcl</tt> for <tt>ir-tk</tt> is a graphical
153 client which demonstates an example of a user interface for the Z39.50/SR
155 At first the script was relatively small but it has grown since the
156 beginning. At present it is about 3000 lines.
158 The client can be started directly from the top level directory
159 of <sf/IrTcl/ by typing:
161 $ ir-tk -f client.tcl
164 Or, if you have installed <sf/IrTcl/ you may also type:
169 The client lets up define targets and query types within the interface.
170 Hence, you will not need to modify configation files.
172 Stuff concerning targets can be found in the pull down menu 'Target'
173 with the following options:
175 <tag>Connect</tag> Establishes connection to a target.
176 <tag>Disconnect</tag> Closes a target connection.
177 <tag>About</tag> Shows implementation Id, implementation Version, etc
178 for the current target.
179 <tag>Setup</tag> Pops up a target definition window. You may alter
181 <tag>Setup new</tag> Lets you define a new target.
184 The term query type refers to a collection of search fields. The
185 pull down menu Options|Query deals with queries. You may
186 insert/modify/remove query types.
188 <sect>Overview of the API
191 Basically, <sf/IrTcl/ is a set of commands introduced to Tcl.
192 When extending Tcl there are two approaches: action-oriented commands
193 and object-oriented commands.
195 Action-oriented commands manipulate
196 Tcl variables and each command introduces only one action.
197 The string manipulation commands in Tcl are action oriented.
199 Object-oriented commands are added for every declared
200 variable (object). Object-oriented commands usually provide a set of
201 actions (methods) to manipulate the object.
202 The widgets in Tk (X objects) are examples of the object-oriented style.
204 <sf/IrTcl/ commands are object-oriented. The main reason
205 for this is that the data structures involved in the IR protocol
206 are not easily represented by Tcl data structures.
207 Also, the <sf/IrTcl/ objects tend to exist for a relativly long time.
208 Note that although we use the term object-oriented commands, this
209 does not mean that the programming style is strictly object-oriented. For
210 example, there is such no such thing as inheritance.
212 We are now ready to present the three commands introduced to Tcl by
216 <tag/ir/ The ir object represents a connection to a target. More
217 precisely it describes a Z-association.
218 <tag/ir-set/ The ir-set describes a result set, which is
219 conceptually a collection of records returned by the target.
220 The ir-set object may retrieve records from a target by means of
221 the ir object; it may read/write records from/to a local file or it may be
222 updated with a user-edited record.
223 <tag/ir-scan/ The scan object represents a list of scan lines
224 retrieved from a target.
229 To create a new IR object called <tt/z-assoc/ write:
236 Each object provides a set of <em/settings/ which may either be
237 readable, writeable of both. All settings immediately follow
238 the name of the object. If a value is present the setting
239 is set to <em/value/.
243 We wish to set the preferred-message-size to 18000 on the
247 z-assoc preferredMessageSize 18000
250 To read the current value of preferred-message-size use:
253 z-assoc preferredMessageSize
257 One important category consists of settings is those that relate to the
258 event-driven model. When <sf/IrTcl/ receives responses from the target, i.e.
259 init responses, search responses, etc., a <em/callback/ routine
260 is called. Callback routines are represented in Tcl as
261 a list, which is re-interpreted prior to invocation.
262 The method is similar to the one used in Tk to capture X events.
264 For each SR/Z39.50 request there is a corresponding object action. The most
265 important actions are:
267 <tag/connect/ Establishes connection with a target
268 <tag/init/ Sends an initialize request.
269 <tag/search/ Sends a search request.
270 <tag/present/ Sends a present request.
271 <tag/scan/ Sends a scan request.
276 This example shows a complete connect - init - search - present scenario.
278 First an IR object, called <tt/z/, is created.
279 Also a result set <tt/z.1/ is introduced by the <tt/ir-set/
280 and it is specified that the result set uses <tt/z/ as its association.
282 The setting <tt/databaseNames/ is set to the
283 database <tt/books/ to which the following searches are directed.
284 A callback is then defined and a connection is established to
285 <tt/fake.com/ by the <tt/connect/ action.
286 If the connect succeeds the <tt/connect-response/ is called.
288 In the Tcl procedure, <tt/connect-response/, a callback is defined
289 <em/before/ the init request is executed.
290 The Tcl procedure <tt/init-response/ is called when a
291 init response is returned from the target.
293 The <tt/init-response/ procedure sets up a <tt/search-response/
294 callback handler and sends a search-request by using a query which
295 consists of a single word <tt/science/.
297 When the <tt/search-response/ procedure is called it defines
298 a variable <tt/hits/ and sets it to the value of the setting
299 <tt/resultCount/. If <tt/hits/ is positive a present-request is
300 sent -- asking for 5 records from position 1.
302 Finally, a present response is received and the number of records
303 returned is stored in the variable <tt/ret/.
307 z databaseNames books
309 z callback {connect-response}
312 proc connect-response {} {
313 z callback {init-response}
317 proc init-response {} {
318 z callback {search-response}
322 proc search-response {} {
323 set hits [z.1 resultCount]
326 z callback {present-response}
331 proc present-response {} {
332 set ret [z.1 numberOfRecordsReturned]
333 puts "$ret records returned"
338 The previous example program doesn't care about error conditions.
339 If errors occur in the program they will be trapped by the Tcl error
340 handler. This is not always appropriate. However, Tcl offers a
341 <tt/catch/ command to support error handling by the program itself.
346 The ir object describes an association with a target.
347 This section covers the connect-init-disconnect actions provided
349 An ir object is created by the <tt/ir/ command and the
350 created object enters a 'not connected' state, because it isn't
351 connected to a target yet.
356 A connection is established by the <tt/connect/ action which is
357 immediately followed by a hostname. A number of settings affect the
358 <tt/connect/ action. Obviously, these settings should be set
359 <bf/before/ connecting. The settings are:
362 <tag><tt>comstack </tt><tt>mosi|tcpip</tt></tag>
364 <tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
365 Protocol type - ANSI/NISO Z39.50 or ISO SR.
366 <tag><tt>callback </tt><em>list</em></tag>
367 Tcl script called when the connection is established.
368 <tag><tt>failback </tt><em>list</em></tag>
369 Fatal error Tcl script. Called on protocol errors or if target
373 If the connect is unsuccessful either the connect action itself
374 will return an error code or the failback handler is invoked.
376 In general, the <tt>failback</tt> handler is invoked when serious
377 unrecoverable errors occur when communicating with the target.
378 In this case the <sf/IrTcl/ system shuts down the connection.
379 The <tt>failback</tt> handler might inspect the <tt>failInfo</tt>
380 setting to determine the cause of the failure; it returns
381 two elements. The first is an error integer; the second is an
382 english representation of the error. The error codes and
383 the corresponding messages are:
386 <tag><tt>0</tt></tag>ok
387 <tag><tt>1</tt></tag>connect failed
388 <tag><tt>2</tt></tag>connection closed
389 <tag><tt>3</tt></tag>connection closed
390 <tag><tt>4</tt></tag>failed to decode incoming APDU
391 <tag><tt>5</tt></tag>unknown APDU
394 Note: in case 3 the connection was closed during read a read operation
395 whereas in case 4 it was closed during a write operation.
400 If the connect operation succeeds the <tt/init/ action should be used.
401 The init related settings are:
404 <tag><tt>preferredMessageSize </tt><em>integer</em></tag>
405 Preferred-message-size. Default value is 30000.
406 <tag><tt>maximumRecordSize </tt><em>integer</em></tag>
407 Maximum-record-size. Default value is 30000.
408 <tag><tt>idAuthentication </tt><em>string</em> ...</tag>
409 Id-authentication. There are three forms. If any empty is
410 given, the Id-authentication is not used. If one non-empty string
411 is given, the 'open' authentication is used. If three strings are
412 specified, the version 'id-pass' authentication (version 3 only)
413 is used in which case the first string is groupId; the second string
414 is userId and the third string is password.
415 <tag><tt>implementationName </tt><em>string</em></tag>
416 Implementation-name of origin system.
417 <tag><tt>implementationId</tt></tag>
418 Implementation-id of origin system. This setting is read-only.
419 <tag><tt>implementationVersion</tt></tag>
420 Implementation-version of origin system. This settings is read-only.
421 <tag><tt>options </tt><em>list</em></tag>
422 Options to be negotiated in the init service. The list contains
423 the options that are set. Possible values are <tt>search</tt>,
424 <tt>present</tt>, <tt>delSet</tt>, <tt>resourceReport</tt>,
425 <tt>triggerResourceCtrl</tt>, <tt>resourceCtrl</tt>,
426 <tt>accessCtrl</tt>, <tt>scan</tt>, <tt>sort</tt>,
427 <tt>extendedServices</tt>, <tt>level-1Segmentation</tt>,
428 <tt>level-2Segmentation</tt>, <tt>concurrentOperations</tt> and
429 <tt>namedResultSets</tt>. Currently the default options are:
430 <tt>search</tt>, <tt>present</tt>, <tt>scan</tt> and
431 <tt>namedResultSets</tt>. The <tt>options</tt> setting is set to its default
432 value when an ir object is created and when a <tt>disconnect</tt>
434 <tag><tt>protocolVersion </tt><em>integer</em></tag>
435 Protocol version: 2, 3, etc. Default is 2.
436 <tag><tt>referenceId </tt><em>string</em></tag>
437 Reference-id of init operation. If <em>string</em> is empty no
438 reference-id is used.
439 <tag><tt>initResponse </tt><em>list</em></tag>
440 Init-response Tcl script.
441 <tag><tt>callback </tt><em>list</em></tag>
442 General response Tcl script. Only used if <tt>initResponse</tt>
446 The init-response handler should inspect some of the settings shown
450 <tag><tt>initResult </tt>returns <em>boolean</em></tag>
451 Init response status. True if init operation was successful;
453 <tag><tt>preferredMessageSize </tt>returns <em>integer</em></tag>
454 Preferred-message-size after negotiation.
455 <tag><tt>maximumRecordSize </tt>returns <em>integer</em></tag>
456 Maximum-record-size after negotiation.
457 <tag><tt>targetImplementationName </tt>returns <em>string</em></tag>
458 Implementation-name of target system.
459 <tag><tt>targetImplementationId </tt>returns <em>string</em></tag>
460 Implementation-id of target system.
461 <tag><tt>targetImplementationVersion </tt>returns <em>string</em></tag>
462 Implementation-version of target system.
463 <tag><tt>options </tt>returns <em>list</em></tag>
464 Options after negotiation. The list contains the options that are set.
465 <tag><tt>protocolVersion </tt>returns <em>integer</em></tag>
466 Protocol version: 2, 3, etc after negotiation.
467 <tag><tt>userInformationField </tt>returns <em>string</em></tag>
468 User information field.
469 <tag><tt>referenceId </tt>returns <em>string</em></tag>
470 Reference-id of init response.
475 Consider a client with the ability to access multiple targets.
477 We define a list of targets that we wish to connect to.
478 Each item in the list describes the target parameters with
479 the following four components: association-name, comstack-type,
480 protocol-type and a hostname.
482 The list for the two targets: ISO/SR target DANBIB and TCP/Z39.50
483 target Data Research, will be defined as:
485 set targetList { {danbib mosi SR 0103/find2.denet.dk:4500}
486 {drs tcpip Z39 dranet.dra.com} }
489 The Tcl code below defines, connect and initialize the
490 targets in <tt/targetList/:
493 foreach target $targetList {
494 set assoc [lindex $target 0]
496 $assoc comstack [lindex $target 1]
497 $assoc protocol [lindex $target 2]
498 $assoc failback [list fail-response $assoc]
499 $assoc callback [list connect-response $assoc]
500 $assoc connect [lindex $target 3]
503 proc connect-response {assoc} {
504 $assoc callback [list init-response $assoc]
508 proc fail-response {assoc} {
509 puts "$assoc closed connection or protocol error"
512 proc init-response {assoc} {
513 if {[$assoc initResult]} {
514 puts "$assoc initialized ok"
516 puts "$assoc didn't initialize"
521 <tt/target/ is bound to each item in the list of targets.
522 The <tt/assoc/ is set to the ir object name.
523 Then, the comstack, protocol and failback are set for the <tt/assoc/ object.
524 The ir object name is argument to the <tt/fail-response/ and
525 <tt/connect-response/ routines.
526 Note the use of the Tcl <tt/list/ command which
527 is necessary here because the argument contains variables
528 (<tt/assoc/) that should be substituted before the handler is defined.
529 After the connect operation, the <tt/init-response/ handler
530 is defined in much the same way as the failback handler.
531 And, finally, an init request is executed.
538 To terminate the connection the <tt/disconnect/ action should be used.
539 This action has no parameters.
540 Another connection may be established by a new <tt/connect/ action on
546 This section covers the queries used by <sf/IrTcl/, and how searches and
547 presents are handled.
549 A search operation and a result set is described by the ir set object.
550 The ir set object is defined by the <tt/ir-set/ command which
551 has two parameters. The first is the name of the new ir set object, and
552 the second, which is optional, is the name of an assocation -- an ir
553 object. The second argument is required if the ir set object should be able
554 to perform searches and presents. However, it is not required if
555 only ``local'' operations is done with the ir set object.
557 When the ir set object is created a number of settings are inherited
558 from the ir object, such as the selected databass, query type,
559 etc. Thus, the ir object contains what we could call default
565 Search requests are sent by the <tt/search/ action which
566 takes a query as parameter. There are two types of queries,
567 RPN and CCL, controlled by the setting <tt/queryType/.
568 A string representation for the query is used in <sf/IrTcl/ since
569 Tcl has reasonably powerful string manipulaton capabilities.
570 The RPN query used in <sf/IrTcl/ is the prefix query notation also used in
571 the <bf/YAZ/ test client.
573 The CCL query is an uninterpreted octet-string which is parsed by the target.
574 We refer to the standard: ISO 8777. Note that only a few targets
575 actually support the CCL query and the interpretation of
576 the standard may vary.
578 The prefix query notation (which is converted to RPN) offer a few
582 <tag><tt>@attr </tt><em>list op</em></tag>
583 The attributes in list are applied to op
584 <tag><tt>@and </tt><em>op1 op2</em></tag>
585 Boolean <em/and/ on op1 and op2
586 <tag><tt>@or </tt><em>op1 op2</em></tag>
587 Boolean <em/or/ on op1 and op2
588 <tag><tt>@not </tt><em>op1 op2</em></tag>
589 Boolean <em/not/ on op1 and op2
590 <tag><tt>@prox </tt><em>list op1 op2</em></tag>
591 Proximity operation on op1 and op2. Not implemented yet.
592 <tag><tt>@set </tt><em>name</em></tag>
596 It is simple to build RPN queries in <sf/IrTcl/. Search terms
597 are sequences of characters, as in:
602 Boolean operators use the prefix notation (instead of the suffix/RPN),
605 @and science technology
608 Search terms may be associated with attributes. These
609 attributes are indicated by the <tt/@attr/ operator.
610 Assuming the bib-1 attribute set, we can set the use-attribute
611 (type is 1) to title (value is 4):
617 Also, it is possible to apply attributes to a range of search terms.
618 In the query below, both search terms have use=title but the <tt/tech/
619 term is right truncated:
622 @attr 1=4 @and @attr 5=1 tech beta
628 The settings that affect the search are listed below:
631 <tag><tt>databaseNames </tt><em>list</em></tag>
633 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
634 Small set upper bound. Default 0.
635 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
636 Large set lower bound. Default 2.
637 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
638 Medium set present number. Default 0.
639 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>
640 Replace-indicator. Default true (1).
641 <tag><tt>setName </tt><em>string</em></tag>
643 <tag><tt>queryType rpn|ccl</tt></tag>
644 Query type-1 or query type-2. Default rpn (type-1).
645 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
646 Preferred record syntax -- UNIMARC, USMARC, etc.
647 <tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
648 small-set-element-set names. If <em>string</em> is empty
649 the element set is not set. Default is empty (not set).
650 <tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
651 medium-set-element-set names. If <em>string</em> is empty
652 the element set is not set. Default is empty (not set).
653 <tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
654 Next result set position.
655 <tag><tt>referenceId </tt><em>string</em></tag>
656 Reference-id. If <em>string</em> is empty no reference-id is used.
657 <tag><tt>searchResponse </tt><em>list</em></tag>
658 Search-response Tcl script.
659 <tag><tt>callback </tt><em>list</em></tag>
660 General response Tcl script. Only used if searchResponse is not specified.
661 This setting is valid only for the <tt/ir/ object -- not the
665 Setting the <tt/databaseNames/ is mandatory. All other settings
666 have reasonable defaults.
667 The search-response handler, specified by the <tt/callback/ - or
668 the <tt/searchResponse/ setting,
669 should read some of the settings shown below:
672 <tag><tt>searchStatus</tt> returns <em>boolean</em></tag>
673 Search-status. True if search operation was successful; false
675 <tag><tt>responseStatus </tt>returns <em>list</em></tag>
676 Response status information.
677 <tag><tt>resultCount </tt>returns <em>integer</em></tag>
679 <tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
680 Number of records returned.
681 <tag><tt>referenceId </tt>returns <em>string</em></tag>
682 Reference-id of search response.
685 The <tt/responseStatus/ signals one of three conditions which
686 is indicated by the value of the first item in the list:
689 <tag><tt>NSD</tt></tag> indicates that the target has returned one or
690 more non-surrogate diagnostic messages. The <tt/NSD/ item is followed by
691 a list with all non-surrogate messages. Each non-surrogate message consists
692 of three items. The first item of the three items is the error
693 code (integer); the next item is a textual representation of the error
694 code in plain english; the third item is additional information, possibly
695 empty if no additional information was returned by the target.
697 <tag><tt>DBOSD</tt></tag> indicates a successful operation where the
698 target has returned one or more records. Each record may be
699 either a database record or a surrogate diagnostic.
701 <tag><tt>OK</tt></tag> indicates a successful operation -- no records are
702 returned from the target.
707 We continue with the multiple-targets example.
708 The <tt/init-response/ procedure will attempt to make searches:
711 proc init-response {assoc} {
712 puts "$assoc connected"
713 ir-set ${assoc}.1 $assoc
714 $assoc.1 queryType rpn
715 $assoc.1 databaseNames base-a base-b
716 $assoc callback [list search-response $assoc ${assoc}.1]
717 $assoc.1 search "@attr 1=4 @and @attr 5=1 tech beta"
721 An ir set object is defined and the
722 ir object is told about the name of ir object.
723 The ir set object use the name of the ir object as prefix.
725 Then, the query-type is defined to be RPN, i.e. we will
726 use the prefix query notation later on.
728 Two databases, <tt/base-a/ and <tt/base-b/, are selected.
730 A <tt/search-response/ handler is defined with the
731 ir object and the ir-set object as parameters and
732 the search is executed.
734 The first part of the <tt/search-response/ looks like:
736 proc search-response {assoc rset} {
737 set status [$rset responseStatus]
738 set type [lindex $status 0]
739 if {$type == "NSD"} {
740 set code [lindex $status 1]
741 set msg [lindex $status 2]
742 set addinfo [lindex $status 3]
743 puts "NSD $code: $msg: $addinfo"
746 set hits [$rset resultCount]
747 if {$type == "DBOSD"} {
748 set ret [$rset numberOfRecordsReturned]
753 The response status is stored in variable <tt/status/ and
754 the first element indicates the condition.
755 If non-surrogate diagnostics are returned they are displayed.
756 Otherwise, the search was a success and the number of hits
757 is read. Finally, it is tested whether the search response
758 returned records (database or diagnostic).
760 Note that we actually didn't inspect the search status (setting
761 <tt/searchStatus/) to determine whether the search was successful or not,
762 because the standard specifies that one or more non-surrogate
763 diagnostics should be returned by the target in case of errors.
767 If one or more records are returned from the target they
768 will be stored in the result set object.
769 In the case in which the search response contains records, it is
770 very similar to the present response case. Therefore, some settings
771 are common to both situations.
776 The <tt/present/ action sends a present request. The <tt/present/ is
777 followed by two optional integers. The first integer is the
778 result-set starting position -- defaults to 1. The second integer
779 is the number of records requested -- defaults to 10.
780 The settings which could be modified before a <tt/present/
784 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
785 preferred record syntax -- UNIMARC, USMARC, etc.
786 <tag><tt>elementSetNames </tt><em>string</em></tag>
787 Element-set names. If <em>string</em> is empty
788 the element set is not set. Default is empty (not set).
789 <tag><tt>referenceId </tt><em>string</em></tag>
790 Reference-id. If <em>string</em> is empty no reference-id is used.
791 <tag><tt>presentResponse </tt><em>list</em></tag>
792 Present-response Tcl script.
793 <tag><tt>callback </tt><em>list</em></tag>
794 General response Tcl script. Only used if presentResponse is not specified
795 This setting is valid only for the <tt/ir/ object -- not the
799 The present-response handler should inspect the settings
800 shown in table below.
801 Note that <tt/responseStatus/ and <tt/numberOfRecordsReturned/
802 settings were also used in the search-response case.
804 As in the search response case, records returned from the
805 target are stored in the result set object.
808 <tag><tt>presentStatus </tt>returns <em>boolean</em></tag>
810 <tag><tt>responseStatus </tt>returns <em>list</em></tag>
811 Response status information.
812 <tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
813 Number of records returned.
814 <tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
815 Next result set position.
816 <tag><tt>referenceId </tt>returns <em>string</em></tag>
817 Reference-id of present response.
823 Search responses and present responses may result in
824 one or more records stored in the ir set object if
825 the <tt/responseStatus/ setting indicates database or
826 surrogate diagnostics (<tt/DBOSD/). The individual
827 records, indexed by an integer position offset, should then be
830 If element set names have been specified either in the
831 search requests (<tt>smallSetElementSetNames</tt> /
832 <tt>mediumSetElementSetNames</tt>) or present requests
833 (<tt>elementSetNames</tt>) the individual records in the
834 ir set object are assigned appropriate element set ids.
835 In this mode records at a given position are treated different as
836 long as they have difference element set ids.
837 To inspect records with a particular element set id in subsequent
838 operations use the <tt>recordElements</tt> setting followed by the id.
839 If you have more than one record at a given position and you do not
840 use <tt>recordElements</tt> the record selected at the given position
843 The action <tt>type</tt> followed by an integer returns information
844 about a given position in an ir set. There are three possiblities:
847 <tag><tt/SD/</tag> The item is a surrogate diagnostic record.
848 <tag><em/empty/</tag> There is no record at the specified position.
849 <tag><tt/DB/</tag> The item is a database record.
852 To handle the first case, surrogate diagnostic record, the
853 <tt/Diag/ action should be used. It returns three
854 items: error code (integer), text representation in plain english
855 (string), and additional information (string, possibly empty).
857 In the second case, no record, note that there still might
858 be a record at the position but with an id that differs from that
859 specified by <tt>recordElements</tt>.
861 In the third case, database record, the <tt/recordType/ action should
862 be used. It returns the record type at the given position.
863 Some record types are:
880 We continue our search-response example. In the case,
881 <tt/DBOSD/, we should inspect the result set items.
882 Recall that the ir set name was passed to the
883 search-response handler as argument <tt/rset/.
886 if {$type == "DBOSD"} {
887 set ret [$rset numberOfRecordsReturned]
888 for {set i 1} {$i<=$ret} {incr i} {
889 set itype [$rset type $i]
890 if {$itype == "SD"} {
891 set diag [$rset Diag $i]
892 set code [lindex $diag 0]
893 set msg [lindex $diag 1]
894 set addinfo [lindex $diag 2]
895 puts "$i: NSD $code: $msg: $addinfo"
896 } elseif {$itype == "DB"} {
897 set rtype [$rset recordType $i]
898 puts "$i: type is $rtype"
903 Each item in the result set is examined.
904 If an item is a diagnostic message it is displayed; otherwise
905 if it's a database record its type is displayed.
912 In the case, where there is a MARC record at a given position we
913 want to display it somehow. The action <tt/getMarc/ is what we need.
914 The <tt/getMarc/ is followed by a position integer and the type of
915 extraction we want to make: <tt/field/ or <tt/line/.
917 The <tt/field/ and <tt/line/ type are followed by three
918 parameters that serve as extraction masks.
919 They are called tag, indicator and field.
920 If the mask matches a tag/indicator/field of a record the information
921 is extracted. Two characters have special meaning in masks: the
922 dot (any character) and star (any number of any character).
924 The <tt/field/ type returns one or more lists of field information
925 that matches the mask specification. Only the content of fields
928 The <tt/line/ type, on the other hand, returns a Tcl list that
929 completely describe the layout of the MARC record -- including
932 The <tt/field/ type is sufficient and efficient in the case, where only a
933 small number of fields are extracted, and in the case where no
934 further processing (in Tcl) is necessary.
936 However, if the MARC record is to be edited or altered in any way, the
937 <tt/line/ extraction is more powerful -- only limited by the Tcl
942 Consider the record below:
947 008 910710c19910701nju 00010 eng
951 100 10 $a Jack Collins
952 245 10 $a How to program a computer
958 Assuming this record is at position 1 in ir-set <tt/z.1/, we
959 might extract the title-field (245 * a), with the following command:
961 z.1 getMarc 1 field 245 * a
966 {How to program a computer}
969 Using the <tt/line/ instead of <tt/field/ gives:
971 {245 {10} {{a {How to program a computer}} }}
974 If we wish to extract the whole record as a list, we use:
976 z.1 getMarc 1 line * * *
981 {001 {} {{{} { 11224466 }} }}
983 {005 {} {{{} 00000000000000.0} }}
984 {008 {} {{{} {910710c19910701nju 00010 eng }} }}
985 {010 { } {{a { 11224466 }} }}
986 {040 { } {{a DLC} {c DLC} }}
987 {050 {00} {{a 123-xyz} }}
988 {100 {10} {{a {Jack Collins}} }}
989 {245 {10} {{a {How to program a computer}} }}
990 {260 {1 } {{a Penguin} }}
991 {263 { } {{a 8710} }}
992 {300 { } {{a {p. cm.}} }}
999 This example demonstrates how Tcl can be used to examine
1000 a MARC record in the list notation.
1002 The procedure <tt/extract-format/ makes an extraction of
1003 fields in a MARC record based on a number of masks.
1004 There are 5 parameters, <tt/r/: a
1005 record in list notation, <tt/tag/: regular expression to
1006 match the record tags, <tt/ind/: regular expression to
1007 match indicators, <tt/field/: regular expression to
1008 match fields, and finally <tt/text/: regular expression to
1009 match the content of a field.
1012 proc extract-format {r tag ind field text} {
1014 if {[regexp $tag [lindex $line 0]] && \
1015 [regexp $ind [lindex $line 1]]} {
1016 foreach f [lindex $line 2] {
1017 if {[regexp $field [lindex $f 0]]} {
1018 if {[regexp $text [lindex $f 1]]} {
1028 To match <tt/comput/ followed by any number of character(s) in the
1029 245 fields in the record from the previous example, we could use:
1031 set r [z.1 getMarc 1 line * * *]
1033 extract-format $r 245 .. . comput
1037 How to program a computer
1042 The <tt/putMarc/ action does the opposite of <tt/getMarc/. It
1043 copies a record in Tcl list notation to a ir set object and is
1044 needed if a result-set must be updated by a Tcl modified (user-edited)
1050 In <sf/IrTcl/ a SUTRS record is treated as one single string. To retrieve
1051 a SUTRS record use the <tt>getSutrs</tt> followed by an index.
1056 To perform scan, a scan object must be created by the <tt>ir-scan</tt>
1057 command. This command has two arguments -- name of the scan object and
1058 name of the ir object. Basically, the scan object, provides one <tt>scan</tt>
1059 action which sends a scan request to the target. The <tt>action</tt>
1060 is followed by a string describing starting point of the term list. The
1061 format used is a simple subset of the query used in search requests. Only
1062 <tt>@attr</tt> specifications and simple terms are allowed.
1063 The settings that affect the scan are:
1066 <tag><tt>stepSize </tt><em>integer</em></tag>
1067 Step size. Default is 0.
1068 <tag><tt>numberOfTermsRequested </tt><em>integer</em></tag>
1069 Number of terms requested. Default is 20.
1070 <tag><tt>preferredPositionInResponse </tt><em>integer</em></tag>
1071 Preferred position in response. Default is 1.
1072 <tag><tt>databaseNames </tt><em>list</em></tag>
1073 Database names. Note that this setting is not (yet) supported for
1074 the scan object. You must set this for the ir object instead.
1075 <tag><tt>referenceId </tt><em>string</em></tag>
1076 Reference-id. If <em>string</em> is empty no reference-id is used.
1077 <tag><tt>scanResponse </tt><em>list</em></tag>
1078 Scan-response Tcl script.
1079 <tag><tt>callback </tt><em>list</em></tag>
1080 General response Tcl script. Only used if <tt>scanResponse</tt>
1082 This setting is valid only for the <tt/ir/ object -- not the
1086 The scan object normally holds one or more scan line entries upon
1087 successful completion. The table below summarizes the settings
1088 that should be used in a response handler.
1091 <tag><tt>scanStatus </tt>returns <em>integer</em></tag>
1092 Scan status. An integer between 0 and 6.
1093 <tag><tt>numberOfTermsReturned </tt>returns <em>integer</em></tag>
1094 Number of terms returned.
1095 <tag><tt>positionOfTerm </tt>returns <em>integer</em></tag>
1096 An integer describing the position of term.
1097 <tag><tt>scanLine </tt>returns <em>list</em></tag>
1098 This function returns information about a given scan line (entry) at a given
1099 index specified by the integer. The first scan line is numbered zero;
1100 the second 1 and so on. A list is returned by the <tt>scanLine</tt>
1101 setting. The first element is <tt>T</tt> if the scan line
1102 is a normal term and <tt>SD</tt> if the scan line is a surrogate
1103 diagnostic. In the first case (normal) the scan term is second element
1104 in the list and the number of occurences is the third element.
1105 In the other case (surrogate diagnostic), the second element
1106 is the diagnostic code, the third a text representation of the error
1107 code and the fourth element is additional information.
1108 <tag><tt>referenceId </tt>returns <em>string</em></tag>
1109 Reference-id of scan response.
1114 We will scan for the terms after <tt>science</tt> in the Title index.
1115 We will assume that an ir object called <tt>z-assoc</tt> has already
1119 z-assoc callback {scan-response}
1120 ir-scan z-scan z-assoc
1121 z-scan scan "@attr 1=4 science"
1123 proc scan-response {} {
1124 set status [z-scan status]
1126 set no [z-scan numberOfTermsReturned]
1127 for {set i 0} {$i < $no} {incr i} {
1128 set line [z-scan scanLine $i]
1129 set type [lindex $line 0]
1131 puts [lindex $line 1]
1132 } elseif {$type == "SD"} {
1133 puts [lindex $line 1]
1144 Copyright © 1995, Index Data.
1146 Permission to use, copy, modify, distribute, and sell this software and
1147 its documentation, in whole or in part, for any purpose, is hereby granted,
1150 1. This copyright and permission notice appear in all copies of the
1151 software and its documentation. Notices of copyright or attribution
1152 which appear at the beginning of any file must remain unchanged.
1154 2. The names of Index Data or the individual authors may not be used to
1155 endorse or promote products derived from this software without specific
1156 prior written permission.
1158 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
1159 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
1160 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1161 IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
1162 INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
1163 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
1164 NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
1165 LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
1168 <sect>About Index Data
1171 Index Data is a consulting and software-development enterprise that
1172 specialises in library and information management systems. Our
1173 interests and expertise span a broad range of related fields, and one
1174 of our primary, long-term objectives is the development of a powerful
1175 information management
1176 system with open network interfaces and hypermedia capabilities.
1178 We make this software available free of charge, on a fairly unrestrictive
1179 license; as a service to the networking community, and to further the
1180 development of quality software for open network communication.
1182 We'll be happy to answer questions about the software, and about ourselves
1188 2200 København N&nl
1194 Phone: +45 3536 3672
1196 Email: info@index.ping.dk
1204 <tag>1 Ousterhout, John K.:</tag>
1205 Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
1206 0-201-63337-X). The Tcl/Tk toolkit home page is
1207 <tt><htmlurl url="http://www.sunlabs.com/research/tcl/"
1208 name="http://www.sunlabs.com/research/tcl"></tt>.
1209 The primary ftp site is <tt><htmlurl url="ftp://ftp.smli.com/pub/tcl/"
1210 name="ftp://ftp.smli.com/pub/tcl/"></tt>.
1211 A mirror site can be found at <tt><htmlurl url="ftp://ftp.aud.alcatel.com/tcl/"
1212 name="ftp://ftp.aud.alcatel.com/tcl/"></tt>.
1213 <tag>2 Furniss, Peter:</tag>
1214 RFC 1698: Octet Sequences for Upper-Layer OSI to Support
1215 Basic Communications Applications.