1 <!doctype linuxdoc system>
4 $Id: ir-tcl.sgml,v 1.14 1996-01-10 09:18:59 adam Exp $
8 <title>IrTcl User's Guide and Reference
9 <author>Index Data, <tt/info@index.ping.dk/
10 <date>$Revision: 1.14 $
12 This document describes IrTcl — an information retrieval toolkit for
13 Tcl and Tk that provides access to the Z39.50/SR protocol.
21 This document describes the <sf/IrTcl/ information retrieval toolkit,
22 which offers a high-level, client interface to the Z39.50 and SR protocols.
23 The toolkit is based on the Tcl/Tk toolkit developed by Prof. John
24 K. Ousterhout at the University of California [ref 1].
25 Tcl is a simple, somewhat shell-like, interpreted language. What
26 makes Tcl attractive is that it also offers a C API, which makes
27 extensions to the language possible. The most important Tcl extension is
28 probably Tk — A Motif look-and-feel interface to the X window
31 To interface the Z39.50/SR protocol <sf/IrTcl/ uses <bf/YAZ/.
32 <bf/YAZ/ offers two transport types: RFC1729/BER on TCP/IP and the mOSI
34 However, the mOSI transport is only an option, and hence it is not
35 needed unless you wish to communicate within an OSI environment.
36 See [ref 2] for more information about the XTI/mOSI implementation.
38 <sf/IrTcl/ provides two system environments:
41 <item> A simple command line shell — useful for
43 <item> A simple command line shell which operates within the Tk
44 environment — makes it very easy to implement GUI clients.
47 <sect>Compilation and installation
50 In order to compile you need:
52 <item> An ANSI C compiler such as GNU C.
53 <item> Tcl. Version 7.3 and 7.4 has been tested.
54 <item> YAZ version 1.0b3 or higher.
57 As an option you may want:
59 <item> Tk. Version 3.6, 4.0 and 4.1 has been tested.
63 Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/.
70 This command tries to configure <sf/IrTcl/ for your system and creates
73 If the <tt>configure</tt> command cannot locate Tcl and Tk in your standard
74 locations for libraries searched by your C compiler it will guess
75 that the libraries are located in <tt>/usr/local/lib</tt> and that
76 the header files are located in <tt>/usr/local/include</tt>.
77 If this is incorrect you will have to modify the <tt>Makefile</tt> yourself.
79 Compile <sf/IrTcl/ by typing:
84 If you don't have Tk you will only be able to create the <tt>ir-tcl</tt>
85 program and you must type <tt>make ir-tcl</tt> instead.
87 If successful, this will make <tt>ir-tcl</tt>, <tt>ir-tk</tt> (if
88 Tk is present) and a library called <tt>libirtcl.a</tt>.
90 To install the programs and support files type:
95 Summary of files installed (the names refer to the Makefile variables):
98 <tag><tt>ir-tk</tt></tag> The <sf/IrTcl/ shell for Tk.
99 Installed in <tt>BINDIR</tt> — defaults to
100 <tt>/usr/local/bin</tt>. <tt>ir-tk</tt> works like
101 <tt>wish</tt> &mdash without arguments it reads commands from stdin.
102 A source file may be specified by option <tt>-f</tt>. <tt>ir-tk</tt>
103 accept the same set of options as <tt>wish</tt>.
104 <tag><tt>ir-tcl</tt></tag> The <sf/IrTcl/ shell for Tcl. Installed in
105 <tt>BINDIR</tt> — defaults to <tt>/usr/local/bin</tt>.
106 <tag><tt>client.tcl</tt></tag> A graphical client for <tt>ir-tk</tt>.
107 The client is installed as an executable script called <tt>irclient</tt> in
108 <tt>BINDIR</tt>. This client needs a number of files, bitmaps, etc.
109 The client looks for the files in the current directory &mdash if
110 this fails it tries to look in the directory <tt>IRTCLDIR</tt>
111 — defaults to <tt>/usr/local/lib/irtcl</tt>.
112 <tag><tt>libirtcl.a</tt></tag> The <sf/IrTcl/ library.
113 Installed in <tt>LIBDIR</tt> — defaults to <tt>/usr/local/lib</tt>.
114 <tag><tt>ir-tcl.h</tt></tag> The <sf/IrTcl/ header file.
115 Installed in <tt>INCDIR</tt> — defaults to <tt>/usr/local/include</tt>.
116 <tag><tt>clientrc.tcl</tt></tag> A setup file with definitions
117 of target and queries. Read and updated by <tt>client.tcl</tt>. Installed
118 in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
119 <tag><tt>formats/*</tt></tag> Display format files written
120 in Tk. Read by <tt>client.tcl</tt>. Installed
121 in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
122 <tag><tt>bitmaps/*</tt></tag> Various bitmap files. Read by
123 <tt>client.tcl</tt>. Installed
124 in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
125 <tag><tt>LICENSE</tt></tag> LICENSE file. Read by
126 <tt>client.tcl</tt>. Installed
127 in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
133 The <tt>ir-tcl</tt> program is a shell like <tt>tclsh</tt> except that
134 <tt>ir-tcl</tt> features the new set of information retrieval commands.
135 Normally <tt>ir-tcl</tt> waits on <tt/stdin/ (for you to type commands) and
136 on sockets events (connected to Z39.50/SR targets).
137 You simply type the Tcl commands line by line. A filename may be specified as
138 argument to <tt>ir-tcl</tt> in which case the file specified is evaluated
144 <tt>ir-tk</tt> is a program that works like <tt>wish</tt> except that
145 <tt>ir-tk</tt> include the new set of commands. All options accepted
146 by <tt>wish</tt> are also accepted by <tt>ir-tk</tt>.
148 The enclosed script <tt>client.tcl</tt> for <tt>ir-tk</tt> is a graphical
149 client which demonstates an example of a user interface for the Z39.50/SR
151 At first the script was relatively small but it has grown since the
152 beginning. At present it is about 3000 lines.
154 The client can be started directly from the top level directory
155 of <sf/IrTcl/ by typing:
157 $ ir-tk -f client.tcl
160 Or, if you have installed <sf/IrTcl/ you may also type:
165 The client lets up define targets and query types within the interface.
166 Hence, you will not need to modify configation files.
168 Stuff concerning targets can be found in the pull down menu 'Target'
169 with the following options:
171 <tag>Connect</tag> Establishes connection to a target.
172 <tag>Disconnect</tag> Closes a target connection.
173 <tag>About</tag> Shows implementation Id, implementation Version, etc
174 for the current target.
175 <tag>Setup</tag> Pops up a target definition window. You may alter
177 <tag>Setup new</tag> Lets you define a new target.
180 The term query type refers to a collection of search fields. The
181 pull down menu Options|Query deals with queries. You may
182 insert/modify/remove query types.
184 <sect>Overview of the API
187 Basically, <sf/IrTcl/ is a set of commands introduced to Tcl.
188 When extending Tcl there are two approaches: action-oriented commands
189 and object-oriented commands.
191 Action-oriented commands manipulate
192 Tcl variables and each command introduces only one action.
193 The string manipulation commands in Tcl are action oriented.
195 Object-oriented commands are added for every declared
196 variable (object). Object-oriented commands usually provide a set of
197 actions (methods) to manipulate the object.
198 The widgets in Tk (X objects) are examples of the object-oriented style.
200 <sf/IrTcl/ commands are object-oriented. The main reason
201 for this is that the data structures involved in the IR protocol
202 are not easily represented by Tcl data structures.
203 Also, the <sf/IrTcl/ objects tend to exist for a relativly long time.
204 Note that although we use the term object-oriented commands, this
205 does not mean that the programming style is strictly object-oriented. For
206 example, there is such no such thing as inheritance.
208 We are now ready to present the three commands introduced to Tcl by
212 <tag/ir/ The ir object represents a connection to a target. More
213 precisely it describes a Z-association.
214 <tag/ir-set/ The ir-set describes a result set, which is
215 conceptually a collection of records returned by the target.
216 The ir-set object may retrieve records from a target by means of
217 the ir object; it may read/write records from/to a local file or it may be
218 updated with a user-edited record.
219 <tag/ir-scan/ The scan object represents a list of scan lines
220 retrieved from a target.
225 To create a new IR object called <tt/z-assoc/ write:
232 Each object provides a set of <em/settings/ which may either be
233 readable, writeable of both. All settings immediately follow
234 the name of the object. If a value is present the setting
235 is set to <em/value/.
239 We wish to set the preferred-message-size to 18000 on the
243 z-assoc preferredMessageSize 18000
246 To read the current value of preferred-message-size use:
249 z-assoc preferredMessageSize
253 One important category consists of settings is those that relate to the
254 event-driven model. When <sf/IrTcl/ receives responses from the target, i.e.
255 init responses, search responses, etc., a <em/callback/ routine
256 is called. Callback routines are represented in Tcl as
257 a list, which is re-interpreted prior to invocation.
258 The method is similar to the one used in Tk to capture X events.
260 For each SR/Z39.50 request there is a corresponding object action. The most
261 important actions are:
263 <tag/connect/ Establishes connection with a target
264 <tag/init/ Sends an initialize request.
265 <tag/search/ Sends a search request.
266 <tag/present/ Sends a present request.
267 <tag/scan/ Sends a scan request.
272 This example shows a complete connect - init - search - present scenario.
274 First an IR object, called <tt/z/, is created.
275 Also a result set <tt/z.1/ is introduced by the <tt/ir-set/
276 and it is specified that the result set uses <tt/z/ as its association.
278 The setting <tt/databaseNames/ is set to the
279 database <tt/books/ to which the following searches are directed.
280 A callback is then defined and a connection is established to
281 <tt/fake.com/ by the <tt/connect/ action.
282 If the connect succeeds the <tt/connect-response/ is called.
284 In the Tcl procedure, <tt/connect-response/, a callback is defined
285 <em/before/ the init request is executed.
286 The Tcl procedure <tt/init-response/ is called when a
287 init response is returned from the target.
289 The <tt/init-response/ procedure sets up a <tt/search-response/
290 callback handler and sends a search-request by using a query which
291 consists of a single word <tt/science/.
293 When the <tt/search-response/ procedure is called it defines
294 a variable <tt/hits/ and sets it to the value of the setting
295 <tt/resultCount/. If <tt/hits/ is positive a present-request is
296 sent — asking for 5 records from position 1.
298 Finally, a present response is received and the number of records
299 returned is stored in the variable <tt/ret/.
303 z databaseNames books
305 z callback {connect-response}
308 proc connect-response {} {
309 z callback {init-response}
313 proc init-response {} {
314 z callback {search-response}
318 proc search-response {} {
319 set hits [z.1 resultCount]
322 z callback {present-response}
327 proc present-response {} {
328 set ret [z.1 numberOfRecordsReturned]
329 puts "$ret records returned"
334 The previous example program doesn't care about error conditions.
335 If errors occur in the program they will be trapped by the Tcl error
336 handler. This is not always appropriate. However, Tcl offers a
337 <tt/catch/ command to support error handling by the program itself.
342 The ir object describes an association with a target.
343 This section covers the connect-init-disconnect actions provided
345 An ir object is created by the <tt/ir/ command and the
346 created object enters a 'not connected' state, because it isn't
347 connected to a target yet.
352 A connection is established by the <tt/connect/ action which is
353 immediately followed by a hostname. A number of settings affect the
354 <tt/connect/ action. Obviously, these settings should be set
355 <bf/before/ connecting. The settings are:
358 <tag><tt>comstack </tt><tt>mosi|tcpip</tt></tag>
360 <tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
361 Protocol type - ANSI/NISO Z39.50 or ISO SR.
362 <tag><tt>callback </tt><em>list</em></tag>
363 Tcl script called when the connection is established.
364 <tag><tt>failback </tt><em>list</em></tag>
365 Fatal error Tcl script. Called on protocol errors or if target
369 If the connect is unsuccessful either the connect action itself
370 will return an error code or the failback handler is invoked.
372 In general, the <tt>failback</tt> handler is invoked when serious
373 unrecoverable errors occur when communicating with the target.
374 In this case the <sf/IrTcl/ system shuts down the connection.
375 The <tt>failback</tt> handler might inspect the <tt>failInfo</tt>
376 setting to determine the cause of the failure; it returns
377 two elements. The first is an error integer; the second is an
378 english representation of the error. The error codes and
379 the corresponding messages are:
382 <tag><tt>0</tt></tag>ok
383 <tag><tt>1</tt></tag>connect failed
384 <tag><tt>2</tt></tag>connection closed
385 <tag><tt>3</tt></tag>connection closed
386 <tag><tt>4</tt></tag>failed to decode incoming APDU
387 <tag><tt>5</tt></tag>unknown APDU
390 Note: in case 3 the connection was closed during read a read operation
391 whereas in case 4 it was closed during a write operation.
396 If the connect operation succeeds the <tt/init/ action should be used.
397 The init related settings are:
400 <tag><tt>preferredMessageSize </tt><em>integer</em></tag>
401 Preferred-message-size. Default value is 30000.
402 <tag><tt>maximumRecordSize </tt><em>integer</em></tag>
403 Maximum-record-size. Default value is 30000.
404 <tag><tt>idAuthentication </tt><em>string</em> ...</tag>
405 Id-authentication. There are three forms. If any empty is
406 given, the Id-authentication is not used. If one non-empty string
407 is given, the 'open' authentication is used. If three strings are
408 specified, the version 'id-pass' authentication (version 3 only)
409 is used in which case the first string is groupId; the second string
410 is userId and the third string is password.
411 <tag><tt>implementationName </tt><em>string</em></tag>
412 Implementation-name of origin system.
413 <tag><tt>implementationId</tt></tag>
414 Implementation-id of origin system. This setting is read-only.
415 <tag><tt>implementationVersion</tt></tag>
416 Implementation-version of origin system. This settings is read-only.
417 <tag><tt>options </tt><em>list</em></tag>
418 Options to be negotiated in the init service. The list contains
419 the options that are set. Possible values are <tt>search</tt>,
420 <tt>present</tt>, <tt>delSet</tt>, <tt>resourceReport</tt>,
421 <tt>triggerResourceCtrl</tt>, <tt>resourceCtrl</tt>,
422 <tt>accessCtrl</tt>, <tt>scan</tt>, <tt>sort</tt>,
423 <tt>extendedServices</tt>, <tt>level-1Segmentation</tt>,
424 <tt>level-2Segmentation</tt>, <tt>concurrentOperations</tt> and
425 <tt>namedResultSets</tt>. Currently the default options are:
426 <tt>search</tt>, <tt>present</tt>, <tt>scan</tt> and
427 <tt>namedResultSets</tt>. The <tt>options</tt> setting is set to its default
428 value when an ir object is created and when a <tt>disconnect</tt>
430 <tag><tt>protocolVersion </tt><em>integer</em></tag>
431 Protocol version: 2, 3, etc. Default is 2.
432 <tag><tt>referenceId </tt><em>string</em></tag>
433 Reference-id of init operation. If <em>string</em> is empty no
434 reference-id is used.
435 <tag><tt>initResponse </tt><em>list</em></tag>
436 Init-response Tcl script.
437 <tag><tt>callback </tt><em>list</em></tag>
438 General response Tcl script. Only used if <tt>initResponse</tt>
442 The init-response handler should inspect some of the settings shown
446 <tag><tt>initResult </tt>returns <em>boolean</em></tag>
447 Init response status. True if init operation was successful;
449 <tag><tt>preferredMessageSize </tt>returns <em>integer</em></tag>
450 Preferred-message-size after negotiation.
451 <tag><tt>maximumRecordSize </tt>returns <em>integer</em></tag>
452 Maximum-record-size after negotiation.
453 <tag><tt>targetImplementationName </tt>returns <em>string</em></tag>
454 Implementation-name of target system.
455 <tag><tt>targetImplementationId </tt>returns <em>string</em></tag>
456 Implementation-id of target system.
457 <tag><tt>targetImplementationVersion </tt>returns <em>string</em></tag>
458 Implementation-version of target system.
459 <tag><tt>options </tt>returns <em>list</em></tag>
460 Options after negotiation. The list contains the options that are set.
461 <tag><tt>protocolVersion </tt>returns <em>integer</em></tag>
462 Protocol version: 2, 3, etc after negotiation.
463 <tag><tt>userInformationField </tt>returns <em>string</em></tag>
464 User information field.
465 <tag><tt>referenceId </tt>returns <em>string</em></tag>
466 Reference-id of init response.
471 Consider a client with the ability to access multiple targets.
473 We define a list of targets that we wish to connect to.
474 Each item in the list describes the target parameters with
475 the following four components: association-name, comstack-type,
476 protocol-type and a hostname.
478 The list for the two targets: ISO/SR target DANBIB and TCP/Z39.50
479 target Data Research, will be defined as:
481 set targetList { {danbib mosi SR 0103/find2.denet.dk:4500}
482 {drs tcpip Z39 dranet.dra.com} }
485 The Tcl code below defines, connect and initialize the
486 targets in <tt/targetList/:
489 foreach target $targetList {
490 set assoc [lindex $target 0]
492 $assoc comstack [lindex $target 1]
493 $assoc protocol [lindex $target 2]
494 $assoc failback [list fail-response $assoc]
495 $assoc callback [list connect-response $assoc]
496 $assoc connect [lindex $target 3]
499 proc connect-response {assoc} {
500 $assoc callback [list init-response $assoc]
504 proc fail-response {assoc} {
505 puts "$assoc closed connection or protocol error"
508 proc init-response {assoc} {
509 if {[$assoc initResult]} {
510 puts "$assoc initialized ok"
512 puts "$assoc didn't initialize"
517 <tt/target/ is bound to each item in the list of targets.
518 The <tt/assoc/ is set to the ir object name.
519 Then, the comstack, protocol and failback are set for the <tt/assoc/ object.
520 The ir object name is argument to the <tt/fail-response/ and
521 <tt/connect-response/ routines.
522 Note the use of the Tcl <tt/list/ command which
523 is necessary here because the argument contains variables
524 (<tt/assoc/) that should be substituted before the handler is defined.
525 After the connect operation, the <tt/init-response/ handler
526 is defined in much the same way as the failback handler.
527 And, finally, an init request is executed.
534 To terminate the connection the <tt/disconnect/ action should be used.
535 This action has no parameters.
536 Another connection may be established by a new <tt/connect/ action on
542 This section covers the queries used by <sf/IrTcl/, and how searches and
543 presents are handled.
545 A search operation and a result set is described by the ir set object.
546 The ir set object is defined by the <tt/ir-set/ command which
547 has two parameters. The first is the name of the new ir set object, and
548 the second, which is optional, is the name of an assocation — an ir
549 object. The second argument is required if the ir set object should be able
550 to perform searches and presents. However, it is not required if
551 only ``local'' operations is done with the ir set object.
553 When the ir set object is created a number of settings are inherited
554 from the ir object, such as the selected databass, query type,
555 etc. Thus, the ir object contains what we could call default
561 Search requests are sent by the <tt/search/ action which
562 takes a query as parameter. There are two types of queries,
563 RPN and CCL, controlled by the setting <tt/queryType/.
564 A string representation for the query is used in <sf/IrTcl/ since
565 Tcl has reasonably powerful string manipulaton capabilities.
566 The RPN query used in <sf/IrTcl/ is the prefix query notation also used in
567 the <bf/YAZ/ test client.
569 The CCL query is an uninterpreted octet-string which is parsed by the target.
570 We refer to the standard: ISO 8777. Note that only a few targets
571 actually support the CCL query and the interpretation of
572 the standard may vary.
574 The prefix query notation (which is converted to RPN) offer a few
578 <tag><tt>@attr </tt><em>list op</em></tag>
579 The attributes in list are applied to op
580 <tag><tt>@and </tt><em>op1 op2</em></tag>
581 Boolean <em/and/ on op1 and op2
582 <tag><tt>@or </tt><em>op1 op2</em></tag>
583 Boolean <em/or/ on op1 and op2
584 <tag><tt>@not </tt><em>op1 op2</em></tag>
585 Boolean <em/not/ on op1 and op2
586 <tag><tt>@prox </tt><em>list op1 op2</em></tag>
587 Proximity operation on op1 and op2. Not implemented yet.
588 <tag><tt>@set </tt><em>name</em></tag>
592 It is simple to build RPN queries in <sf/IrTcl/. Search terms
593 are sequences of characters, as in:
598 Boolean operators use the prefix notation (instead of the suffix/RPN),
601 @and science technology
604 Search terms may be associated with attributes. These
605 attributes are indicated by the <tt/@attr/ operator.
606 Assuming the bib-1 attribute set, we can set the use-attribute
607 (type is 1) to title (value is 4):
613 Also, it is possible to apply attributes to a range of search terms.
614 In the query below, both search terms have use=title but the <tt/tech/
615 term is right truncated:
618 @attr 1=4 @and @attr 5=1 tech beta
624 The settings that affect the search are listed below:
627 <tag><tt>databaseNames </tt><em>list</em></tag>
629 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
630 Small set upper bound. Default 0.
631 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
632 Large set lower bound. Default 2.
633 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
634 Medium set present number. Default 0.
635 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>
636 Replace-indicator. Default true (1).
637 <tag><tt>setName </tt><em>string</em></tag>
639 <tag><tt>queryType rpn|ccl</tt></tag>
640 Query type-1 or query type-2. Default rpn (type-1).
641 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
642 Preferred record syntax — UNIMARC, USMARC, etc.
643 <tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
644 small-set-element-set names. If <em>string</em> is empty
645 the element set is not set. Default is empty (not set).
646 <tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
647 medium-set-element-set names. If <em>string</em> is empty
648 the element set is not set. Default is empty (not set).
649 <tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
650 Next result set position.
651 <tag><tt>referenceId </tt><em>string</em></tag>
652 Reference-id. If <em>string</em> is empty no reference-id is used.
653 <tag><tt>searchResponse </tt><em>list</em></tag>
654 Search-response Tcl script.
655 <tag><tt>callback </tt><em>list</em></tag>
656 General response Tcl script. Only used if searchResponse is not specified.
657 This setting is valid only for the <tt/ir/ object — not the
661 Setting the <tt/databaseNames/ is mandatory. All other settings
662 have reasonable defaults.
663 The search-response handler, specified by the <tt/callback/ - or
664 the <tt/searchResponse/ setting,
665 should read some of the settings shown below:
668 <tag><tt>searchStatus</tt> returns <em>boolean</em></tag>
669 Search-status. True if search operation was successful; false
671 <tag><tt>responseStatus </tt>returns <em>list</em></tag>
672 Response status information.
673 <tag><tt>resultCount </tt>returns <em>integer</em></tag>
675 <tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
676 Number of records returned.
677 <tag><tt>referenceId </tt>returns <em>string</em></tag>
678 Reference-id of search response.
681 The <tt/responseStatus/ signals one of three conditions which
682 is indicated by the value of the first item in the list:
685 <tag><tt>NSD</tt></tag> indicates that the target has returned one or
686 more non-surrogate diagnostic messages. The <tt/NSD/ item is followed by
687 a list with all non-surrogate messages. Each non-surrogate message consists
688 of three items. The first item of the three items is the error
689 code (integer); the next item is a textual representation of the error
690 code in plain english; the third item is additional information, possibly
691 empty if no additional information was returned by the target.
693 <tag><tt>DBOSD</tt></tag> indicates a successful operation where the
694 target has returned one or more records. Each record may be
695 either a database record or a surrogate diagnostic.
697 <tag><tt>OK</tt></tag> indicates a successful operation — no records are
698 returned from the target.
703 We continue with the multiple-targets example.
704 The <tt/init-response/ procedure will attempt to make searches:
707 proc init-response {assoc} {
708 puts "$assoc connected"
709 ir-set ${assoc}.1 $assoc
710 $assoc.1 queryType rpn
711 $assoc.1 databaseNames base-a base-b
712 $assoc callback [list search-response $assoc ${assoc}.1]
713 $assoc.1 search "@attr 1=4 @and @attr 5=1 tech beta"
717 An ir set object is defined and the
718 ir object is told about the name of ir object.
719 The ir set object use the name of the ir object as prefix.
721 Then, the query-type is defined to be RPN, i.e. we will
722 use the prefix query notation later on.
724 Two databases, <tt/base-a/ and <tt/base-b/, are selected.
726 A <tt/search-response/ handler is defined with the
727 ir object and the ir-set object as parameters and
728 the search is executed.
730 The first part of the <tt/search-response/ looks like:
732 proc search-response {assoc rset} {
733 set status [$rset responseStatus]
734 set type [lindex $status 0]
735 if {$type == "NSD"} {
736 set code [lindex $status 1]
737 set msg [lindex $status 2]
738 set addinfo [lindex $status 3]
739 puts "NSD $code: $msg: $addinfo"
742 set hits [$rset resultCount]
743 if {$type == "DBOSD"} {
744 set ret [$rset numberOfRecordsReturned]
749 The response status is stored in variable <tt/status/ and
750 the first element indicates the condition.
751 If non-surrogate diagnostics are returned they are displayed.
752 Otherwise, the search was a success and the number of hits
753 is read. Finally, it is tested whether the search response
754 returned records (database or diagnostic).
756 Note that we actually didn't inspect the search status (setting
757 <tt/searchStatus/) to determine whether the search was successful or not,
758 because the standard specifies that one or more non-surrogate
759 diagnostics should be returned by the target in case of errors.
763 If one or more records are returned from the target they
764 will be stored in the result set object.
765 In the case in which the search response contains records, it is
766 very similar to the present response case. Therefore, some settings
767 are common to both situations.
772 The <tt/present/ action sends a present request. The <tt/present/ is
773 followed by two optional integers. The first integer is the
774 result-set starting position — defaults to 1. The second integer
775 is the number of records requested — defaults to 10.
776 The settings which could be modified before a <tt/present/
780 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
781 preferred record syntax — UNIMARC, USMARC, etc.
782 <tag><tt>elementSetNames </tt><em>string</em></tag>
783 Element-set names. If <em>string</em> is empty
784 the element set is not set. Default is empty (not set).
785 <tag><tt>referenceId </tt><em>string</em></tag>
786 Reference-id. If <em>string</em> is empty no reference-id is used.
787 <tag><tt>presentResponse </tt><em>list</em></tag>
788 Present-response Tcl script.
789 <tag><tt>callback </tt><em>list</em></tag>
790 General response Tcl script. Only used if presentResponse is not specified
791 This setting is valid only for the <tt/ir/ object — not the
795 The present-response handler should inspect the settings
796 shown in table below.
797 Note that <tt/responseStatus/ and <tt/numberOfRecordsReturned/
798 settings were also used in the search-response case.
800 As in the search response case, records returned from the
801 target are stored in the result set object.
804 <tag><tt>presentStatus </tt>returns <em>boolean</em></tag>
806 <tag><tt>responseStatus </tt>returns <em>list</em></tag>
807 Response status information.
808 <tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
809 Number of records returned.
810 <tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
811 Next result set position.
812 <tag><tt>referenceId </tt>returns <em>string</em></tag>
813 Reference-id of present response.
819 Search responses and present responses may result in
820 one or more records stored in the ir set object if
821 the <tt/responseStatus/ setting indicates database or
822 surrogate diagnostics (<tt/DBOSD/). The individual
823 records, indexed by an integer position offset, should then be
826 If element set names have been specified either in the
827 search requests (<tt>smallSetElementSetNames</tt> /
828 <tt>mediumSetElementSetNames</tt>) or present requests
829 (<tt>elementSetNames</tt>) the individual records in the
830 ir set object are assigned appropriate element set ids.
831 In this mode records at a given position are treated different as
832 long as they have difference element set ids.
833 To inspect records with a particular element set id in subsequent
834 operations use the <tt>recordElements</tt> setting followed by the id.
835 If you have more than one record at a given position and you do not
836 use <tt>recordElements</tt> the record selected at the given position
839 The action <tt>type</tt> followed by an integer returns information
840 about a given position in an ir set. There are three possiblities:
843 <tag><tt/SD/</tag> The item is a surrogate diagnostic record.
844 <tag><em/empty/</tag> There is no record at the specified position.
845 <tag><tt/DB/</tag> The item is a database record.
848 To handle the first case, surrogate diagnostic record, the
849 <tt/Diag/ action should be used. It returns three
850 items: error code (integer), text representation in plain english
851 (string), and additional information (string, possibly empty).
853 In the second case, no record, note that there still might
854 be a record at the position but with an id that differs from that
855 specified by <tt>recordElements</tt>.
857 In the third case, database record, the <tt/recordType/ action should
858 be used. It returns the record type at the given position.
859 Some record types are:
876 We continue our search-response example. In the case,
877 <tt/DBOSD/, we should inspect the result set items.
878 Recall that the ir set name was passed to the
879 search-response handler as argument <tt/rset/.
882 if {$type == "DBOSD"} {
883 set ret [$rset numberOfRecordsReturned]
884 for {set i 1} {$i<=$ret} {incr i} {
885 set itype [$rset type $i]
886 if {$itype == "SD"} {
887 set diag [$rset Diag $i]
888 set code [lindex $diag 0]
889 set msg [lindex $diag 1]
890 set addinfo [lindex $diag 2]
891 puts "$i: NSD $code: $msg: $addinfo"
892 } elseif {$itype == "DB"} {
893 set rtype [$rset recordType $i]
894 puts "$i: type is $rtype"
899 Each item in the result set is examined.
900 If an item is a diagnostic message it is displayed; otherwise
901 if it's a database record its type is displayed.
908 In the case, where there is a MARC record at a given position we
909 want to display it somehow. The action <tt/getMarc/ is what we need.
910 The <tt/getMarc/ is followed by a position integer and the type of
911 extraction we want to make: <tt/field/ or <tt/line/.
913 The <tt/field/ and <tt/line/ type are followed by three
914 parameters that serve as extraction masks.
915 They are called tag, indicator and field.
916 If the mask matches a tag/indicator/field of a record the information
917 is extracted. Two characters have special meaning in masks: the
918 dot (any character) and star (any number of any character).
920 The <tt/field/ type returns one or more lists of field information
921 that matches the mask specification. Only the content of fields
924 The <tt/line/ type, on the other hand, returns a Tcl list that
925 completely describe the layout of the MARC record — including
928 The <tt/field/ type is sufficient and efficient in the case, where only a
929 small number of fields are extracted, and in the case where no
930 further processing (in Tcl) is necessary.
932 However, if the MARC record is to be edited or altered in any way, the
933 <tt/line/ extraction is more powerful — only limited by the Tcl
938 Consider the record below:
943 008 910710c19910701nju 00010 eng
947 100 10 $a Jack Collins
948 245 10 $a How to program a computer
954 Assuming this record is at position 1 in ir-set <tt/z.1/, we
955 might extract the title-field (245 * a), with the following command:
957 z.1 getMarc 1 field 245 * a
962 {How to program a computer}
965 Using the <tt/line/ instead of <tt/field/ gives:
967 {245 {10} {{a {How to program a computer}} }}
970 If we wish to extract the whole record as a list, we use:
972 z.1 getMarc 1 line * * *
977 {001 {} {{{} { 11224466 }} }}
979 {005 {} {{{} 00000000000000.0} }}
980 {008 {} {{{} {910710c19910701nju 00010 eng }} }}
981 {010 { } {{a { 11224466 }} }}
982 {040 { } {{a DLC} {c DLC} }}
983 {050 {00} {{a 123-xyz} }}
984 {100 {10} {{a {Jack Collins}} }}
985 {245 {10} {{a {How to program a computer}} }}
986 {260 {1 } {{a Penguin} }}
987 {263 { } {{a 8710} }}
988 {300 { } {{a {p. cm.}} }}
995 This example demonstrates how Tcl can be used to examine
996 a MARC record in the list notation.
998 The procedure <tt/extract-format/ makes an extraction of
999 fields in a MARC record based on a number of masks.
1000 There are 5 parameters, <tt/r/: a
1001 record in list notation, <tt/tag/: regular expression to
1002 match the record tags, <tt/ind/: regular expression to
1003 match indicators, <tt/field/: regular expression to
1004 match fields, and finally <tt/text/: regular expression to
1005 match the content of a field.
1008 proc extract-format {r tag ind field text} {
1010 if {[regexp $tag [lindex $line 0]] && \
1011 [regexp $ind [lindex $line 1]]} {
1012 foreach f [lindex $line 2] {
1013 if {[regexp $field [lindex $f 0]]} {
1014 if {[regexp $text [lindex $f 1]]} {
1024 To match <tt/comput/ followed by any number of character(s) in the
1025 245 fields in the record from the previous example, we could use:
1027 set r [z.1 getMarc 1 line * * *]
1029 extract-format $r 245 .. . comput
1033 How to program a computer
1038 The <tt/putMarc/ action does the opposite of <tt/getMarc/. It
1039 copies a record in Tcl list notation to a ir set object and is
1040 needed if a result-set must be updated by a Tcl modified (user-edited)
1046 In <sf/IrTcl/ a SUTRS record is treated as one single string. To retrieve
1047 a SUTRS record use the <tt>getSutrs</tt> followed by an index.
1052 To perform scan, a scan object must be created by the <tt>ir-scan</tt>
1053 command. This command has two arguments — name of the scan object and
1054 name of the ir object. Basically, the scan object, provides one <tt>scan</tt>
1055 action which sends a scan request to the target. The <tt>action</tt>
1056 is followed by a string describing starting point of the term list. The
1057 format used is a simple subset of the query used in search requests. Only
1058 <tt>@attr</tt> specifications and simple terms are allowed.
1059 The settings that affect the scan are:
1062 <tag><tt>stepSize </tt><em>integer</em></tag>
1063 Step size. Default is 0.
1064 <tag><tt>numberOfTermsRequested </tt><em>integer</em></tag>
1065 Number of terms requested. Default is 20.
1066 <tag><tt>preferredPositionInResponse </tt><em>integer</em></tag>
1067 Preferred position in response. Default is 1.
1068 <tag><tt>databaseNames </tt><em>list</em></tag>
1069 Database names. Note that this setting is not (yet) supported for
1070 the scan object. You must set this for the ir object instead.
1071 <tag><tt>referenceId </tt><em>string</em></tag>
1072 Reference-id. If <em>string</em> is empty no reference-id is used.
1073 <tag><tt>scanResponse </tt><em>list</em></tag>
1074 Scan-response Tcl script.
1075 <tag><tt>callback </tt><em>list</em></tag>
1076 General response Tcl script. Only used if <tt>scanResponse</tt>
1078 This setting is valid only for the <tt/ir/ object — not the
1082 The scan object normally holds one or more scan line entries upon
1083 successful completion. The table below summarizes the settings
1084 that should be used in a response handler.
1087 <tag><tt>scanStatus </tt>returns <em>integer</em></tag>
1088 Scan status. An integer between 0 and 6.
1089 <tag><tt>numberOfTermsReturned </tt>returns <em>integer</em></tag>
1090 Number of terms returned.
1091 <tag><tt>positionOfTerm </tt>returns <em>integer</em></tag>
1092 An integer describing the position of term.
1093 <tag><tt>scanLine </tt>returns <em>list</em></tag>
1094 This function returns information about a given scan line (entry) at a given
1095 index specified by the integer. The first scan line is numbered zero;
1096 the second 1 and so on. A list is returned by the <tt>scanLine</tt>
1097 setting. The first element is <tt>T</tt> if the scan line
1098 is a normal term and <tt>SD</tt> if the scan line is a surrogate
1099 diagnostic. In the first case (normal) the scan term is second element
1100 in the list and the number of occurences is the third element.
1101 In the other case (surrogate diagnostic), the second element
1102 is the diagnostic code, the third a text representation of the error
1103 code and the fourth element is additional information.
1104 <tag><tt>referenceId </tt>returns <em>string</em></tag>
1105 Reference-id of scan response.
1110 We will scan for the terms after <tt>science</tt> in the Title index.
1111 We will assume that an ir object called <tt>z-assoc</tt> has already
1115 z-assoc callback {scan-response}
1116 ir-scan z-scan z-assoc
1117 z-scan scan "@attr 1=4 science"
1119 proc scan-response {} {
1120 set status [z-scan status]
1122 set no [z-scan numberOfTermsReturned]
1123 for {set i 0} {$i < $no} {incr i} {
1124 set line [z-scan scanLine $i]
1125 set type [lindex $line 0]
1127 puts [lindex $line 1]
1128 } elseif {$type == "SD"} {
1129 puts [lindex $line 1]
1140 Copyright © 1995, Index Data.
1142 Permission to use, copy, modify, distribute, and sell this software and
1143 its documentation, in whole or in part, for any purpose, is hereby granted,
1146 1. This copyright and permission notice appear in all copies of the
1147 software and its documentation. Notices of copyright or attribution
1148 which appear at the beginning of any file must remain unchanged.
1150 2. The names of Index Data or the individual authors may not be used to
1151 endorse or promote products derived from this software without specific
1152 prior written permission.
1154 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
1155 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
1156 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1157 IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
1158 INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
1159 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
1160 NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
1161 LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
1164 <sect>About Index Data
1167 Index Data is a consulting and software-development enterprise that
1168 specialises in library and information management systems. Our
1169 interests and expertise span a broad range of related fields, and one
1170 of our primary, long-term objectives is the development of a powerful
1171 information management
1172 system with open network interfaces and hypermedia capabilities.
1174 We make this software available free of charge, on a fairly unrestrictive
1175 license; as a service to the networking community, and to further the
1176 development of quality software for open network communication.
1178 We'll be happy to answer questions about the software, and about ourselves
1184 2200 København N&nl
1190 Phone: +45 3536 3672
1192 Email: info@index.ping.dk
1200 <tag>1 Ousterhout, John K.:</tag>
1201 Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
1202 0-201-63337-X). Source and documentation
1203 can be found in <tt>URL:ftp://ftp.cs.berkeley.edu/pub/tcl</tt>
1205 <tag>2 Furniss, Peter:</tag>
1206 RFC 1698: Octet Sequences for Upper-Layer OSI to Support
1207 Basic Communications Applications.