1 <!doctype linuxdoc system>
4 $Id: ir-tcl.sgml,v 1.23 1997-04-13 19:01:45 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@index.ping.dk" name="info@index.ping.dk"></tt>
11 <date>$Revision: 1.23 $
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://www.indexdata.dk/yaz.html" name="YAZ">
57 version 1.2 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 If you wish to install man pages type:
104 Summary of files installed (the names refer to the Makefile variables):
107 <tag><tt>ir-tk</tt></tag> The <sf/IrTcl/ shell for Tk.
108 Installed in <tt>BINDIR</tt> -- defaults to
109 <tt>/usr/local/bin</tt>. <tt>ir-tk</tt> works like
110 <tt>wish</tt> &mdash without arguments it reads commands from stdin.
111 A source file may be specified by option <tt>-f</tt>. <tt>ir-tk</tt>
112 accept the same set of options as <tt>wish</tt>.
113 <tag><tt>ir-tcl</tt></tag> The <sf/IrTcl/ shell for Tcl. Installed in
114 <tt>BINDIR</tt> -- defaults to <tt>/usr/local/bin</tt>.
115 <tag><tt>client.tcl</tt></tag> A graphical client for <tt>ir-tk</tt>.
116 The client is installed as an executable script called <tt>irclient</tt> in
117 <tt>BINDIR</tt>. This client needs a number of files, bitmaps, etc.
118 The client looks for the files in the current directory &mdash if
119 this fails it tries to look in the directory <tt>IRTCLDIR</tt>
120 -- defaults to <tt>/usr/local/lib/irtcl</tt>.
121 <tag><tt>libirtcl.a</tt></tag> The <sf/IrTcl/ library.
122 Installed in <tt>LIBDIR</tt> -- defaults to <tt>/usr/local/lib</tt>.
123 <tag><tt>ir-tcl.h</tt></tag> The <sf/IrTcl/ header file.
124 Installed in <tt>INCDIR</tt> -- defaults to <tt>/usr/local/include</tt>.
125 <tag><tt>clientrc.tcl</tt></tag> A setup file with definitions
126 of target and queries. Read and updated by <tt>client.tcl</tt>. Installed
127 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
128 <tag><tt>formats/*</tt></tag> Display format files written
129 in Tk. Read by <tt>client.tcl</tt>. Installed
130 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
131 <tag><tt>bitmaps/*</tt></tag> Various bitmap files. Read by
132 <tt>client.tcl</tt>. Installed
133 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
134 <tag><tt>LICENSE</tt></tag> LICENSE file. Read by
135 <tt>client.tcl</tt>. Installed
136 in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
142 The <tt>ir-tcl</tt> program is a shell like <tt>tclsh</tt> except that
143 <tt>ir-tcl</tt> features the new set of information retrieval commands.
144 Normally <tt>ir-tcl</tt> waits on <tt/stdin/ (for you to type commands) and
145 on sockets events (connected to Z39.50/SR targets).
146 You simply type the Tcl commands line by line. A filename may be specified as
147 argument to <tt>ir-tcl</tt> in which case the file specified is evaluated
153 <tt>ir-tk</tt> is a program that works like <tt>wish</tt> except that
154 <tt>ir-tk</tt> include the new set of commands. All options accepted
155 by <tt>wish</tt> are also accepted by <tt>ir-tk</tt>.
157 The enclosed script <tt>client.tcl</tt> for <tt>ir-tk</tt> is a graphical
158 client which demonstates an example of a user interface for the Z39.50/SR
160 At first the script was relatively small but it has grown since the
161 beginning. At present it is about 3000 lines.
163 The client can be started directly from the top level directory
164 of <sf/IrTcl/ by typing:
166 $ ir-tk -f client.tcl
169 Or, if you have installed <sf/IrTcl/ you may also type:
174 The client lets up define targets and query types within the interface.
175 Hence, you will not need to modify configation files.
177 Stuff concerning targets can be found in the pull down menu 'Target'
178 with the following options:
180 <tag>Connect</tag> Establishes connection to a target.
181 <tag>Disconnect</tag> Closes a target connection.
182 <tag>About</tag> Shows implementation Id, implementation Version, etc
183 for the current target.
184 <tag>Setup</tag> Pops up a target definition window. You may alter
186 <tag>Setup new</tag> Lets you define a new target.
189 The term query type refers to a collection of search fields. The
190 pull down menu Options|Query deals with queries. You may
191 insert/modify/remove query types.
193 <sect>Overview of the API
196 Basically, <sf/IrTcl/ is a set of commands introduced to Tcl.
197 When extending Tcl there are two approaches: action-oriented commands
198 and object-oriented commands.
200 Action-oriented commands manipulate
201 Tcl variables and each command introduces only one action.
202 The string manipulation commands in Tcl are action oriented.
204 Object-oriented commands are added for every declared
205 variable (object). Object-oriented commands usually provide a set of
206 actions (methods) to manipulate the object.
207 The widgets in Tk (X objects) are examples of the object-oriented style.
209 <sf/IrTcl/ commands are object-oriented. The main reason
210 for this is that the data structures involved in the IR protocol
211 are not easily represented by Tcl data structures.
212 Also, the <sf/IrTcl/ objects tend to exist for a relativly long time.
213 Note that although we use the term object-oriented commands, this
214 does not mean that the programming style is strictly object-oriented. For
215 example, there is such no such thing as inheritance.
217 We are now ready to present the three commands introduced to Tcl by
221 <tag/ir/ The ir object represents a connection to a target. More
222 precisely it describes a Z-association.
223 <tag/ir-set/ The ir-set describes a result set, which is
224 conceptually a collection of records returned by the target.
225 The ir-set object may retrieve records from a target by means of
226 the ir object; it may read/write records from/to a local file or it may be
227 updated with a user-edited record.
228 <tag/ir-scan/ The scan object represents a list of scan lines
229 retrieved from a target.
234 To create a new IR object called <tt/z-assoc/ write:
241 Each object provides a set of <em/settings/ which may either be
242 readable, writeable of both. All settings immediately follow
243 the name of the object. If a value is present the setting
244 is set to <em/value/.
248 We wish to set the preferred-message-size to 18000 on the
252 z-assoc preferredMessageSize 18000
255 To read the current value of preferred-message-size use:
258 z-assoc preferredMessageSize
262 One important category consists of settings is those that relate to the
263 event-driven model. When <sf/IrTcl/ receives responses from the target, i.e.
264 init responses, search responses, etc., a <em/callback/ routine
265 is called. Callback routines are represented in Tcl as
266 a list, which is re-interpreted prior to invocation.
267 The method is similar to the one used in Tk to capture X events.
269 For each SR/Z39.50 request there is a corresponding object action. The most
270 important actions are:
272 <tag/connect/ Establishes connection with a target
273 <tag/init/ Sends an initialize request.
274 <tag/search/ Sends a search request.
275 <tag/present/ Sends a present request.
276 <tag/scan/ Sends a scan request.
281 This example shows a complete connect - init - search - present scenario.
283 First an IR object, called <tt/z/, is created.
284 Also a result set <tt/z.1/ is introduced by the <tt/ir-set/
285 and it is specified that the result set uses <tt/z/ as its association.
287 The setting <tt/databaseNames/ is set to the
288 database <tt/books/ to which the following searches are directed.
289 A callback is then defined and a connection is established to
290 <tt/fake.com/ by the <tt/connect/ action.
291 If the connect succeeds the <tt/connect-response/ is called.
293 In the Tcl procedure, <tt/connect-response/, a callback is defined
294 <em/before/ the init request is executed.
295 The Tcl procedure <tt/init-response/ is called when a
296 init response is returned from the target.
298 The <tt/init-response/ procedure sets up a <tt/search-response/
299 callback handler and sends a search-request by using a query which
300 consists of a single word <tt/science/.
302 When the <tt/search-response/ procedure is called it defines
303 a variable <tt/hits/ and sets it to the value of the setting
304 <tt/resultCount/. If <tt/hits/ is positive a present-request is
305 sent -- asking for 5 records from position 1.
307 Finally, a present response is received and the number of records
308 returned is stored in the variable <tt/ret/.
312 z databaseNames books
314 z callback {connect-response}
317 proc connect-response {} {
318 z callback {init-response}
322 proc init-response {} {
323 z callback {search-response}
327 proc search-response {} {
328 set hits [z.1 resultCount]
331 z callback {present-response}
336 proc present-response {} {
337 set ret [z.1 numberOfRecordsReturned]
338 puts "$ret records returned"
343 The previous example program doesn't care about error conditions.
344 If errors occur in the program they will be trapped by the Tcl error
345 handler. This is not always appropriate. However, Tcl offers a
346 <tt/catch/ command to support error handling by the program itself.
351 The ir object describes an association with a target.
352 This section covers the connect-init-disconnect actions provided
354 An ir object is created by the <tt/ir/ command and the
355 created object enters a 'not connected' state, because it isn't
356 connected to a target yet.
361 A connection is established by the <tt/connect/ action which is
362 immediately followed by a hostname. A number of settings affect the
363 <tt/connect/ action. Obviously, these settings should be set
364 <bf/before/ connecting. The settings are:
367 <tag><tt>comstack </tt><tt>mosi|tcpip</tt></tag>
369 <tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
370 Protocol type - ANSI/NISO Z39.50 or ISO SR.
371 <tag><tt>callback </tt><em>list</em></tag>
372 Tcl script called when the connection is established.
373 <tag><tt>failback </tt><em>list</em></tag>
374 Fatal error Tcl script. Called on protocol errors or if target
378 If the connect is unsuccessful either the connect action itself
379 will return an error code or the failback handler is invoked.
381 In general, the <tt>failback</tt> handler is invoked when serious
382 unrecoverable errors occur when communicating with the target.
383 In this case the <sf/IrTcl/ system shuts down the connection.
384 The <tt>failback</tt> handler might inspect the <tt>failInfo</tt>
385 setting to determine the cause of the failure; it returns
386 two elements. The first is an error integer; the second is an
387 english representation of the error. The error codes and
388 the corresponding messages are:
391 <tag><tt>0</tt></tag>ok
392 <tag><tt>1</tt></tag>connect failed
393 <tag><tt>2</tt></tag>connection closed
394 <tag><tt>3</tt></tag>connection closed
395 <tag><tt>4</tt></tag>failed to decode incoming APDU
396 <tag><tt>5</tt></tag>unknown APDU
399 Note: in case 3 the connection was closed during read a read operation
400 whereas in case 4 it was closed during a write operation.
405 If the connect operation succeeds the <tt/init/ action should be used.
406 The init related settings are:
409 <tag><tt>preferredMessageSize </tt><em>integer</em></tag>
410 Preferred-message-size. Default value is 30000.
411 <tag><tt>maximumRecordSize </tt><em>integer</em></tag>
412 Maximum-record-size. Default value is 30000.
413 <tag><tt>idAuthentication </tt><em>string</em> ...</tag>
414 Id-authentication. There are three forms. If any empty is
415 given, the Id-authentication is not used. If one non-empty string
416 is given, the 'open' authentication is used. If three strings are
417 specified, the version 'id-pass' authentication (version 3 only)
418 is used in which case the first string is groupId; the second string
419 is userId and the third string is password.
420 <tag><tt>implementationName </tt><em>string</em></tag>
421 Implementation-name of origin system.
422 <tag><tt>implementationId</tt></tag>
423 Implementation-id of origin system. This setting is read-only.
424 <tag><tt>implementationVersion</tt></tag>
425 Implementation-version of origin system. This settings is read-only.
426 <tag><tt>options </tt><em>list</em></tag>
427 Options to be negotiated in the init service. The list contains
428 the options that are set. Possible values are <tt>search</tt>,
429 <tt>present</tt>, <tt>delSet</tt>, <tt>resourceReport</tt>,
430 <tt>triggerResourceCtrl</tt>, <tt>resourceCtrl</tt>,
431 <tt>accessCtrl</tt>, <tt>scan</tt>, <tt>sort</tt>,
432 <tt>extendedServices</tt>, <tt>level-1Segmentation</tt>,
433 <tt>level-2Segmentation</tt>, <tt>concurrentOperations</tt> and
434 <tt>namedResultSets</tt>. Currently the default options are:
435 <tt>search</tt>, <tt>present</tt>, <tt>scan</tt> and
436 <tt>namedResultSets</tt>. The <tt>options</tt> setting is set to its default
437 value when an ir object is created and when a <tt>disconnect</tt>
439 <tag><tt>protocolVersion </tt><em>integer</em></tag>
440 Protocol version: 2, 3, etc. Default is 2.
441 <tag><tt>referenceId </tt><em>string</em></tag>
442 Reference-id of init operation. If <em>string</em> is empty no
443 reference-id is used.
444 <tag><tt>initResponse </tt><em>list</em></tag>
445 Init-response Tcl script.
446 <tag><tt>callback </tt><em>list</em></tag>
447 General response Tcl script. Only used if <tt>initResponse</tt>
451 The init-response handler should inspect some of the settings shown
455 <tag><tt>initResult </tt>returns <em>boolean</em></tag>
456 Init response status. True if init operation was successful;
458 <tag><tt>preferredMessageSize </tt>returns <em>integer</em></tag>
459 Preferred-message-size after negotiation.
460 <tag><tt>maximumRecordSize </tt>returns <em>integer</em></tag>
461 Maximum-record-size after negotiation.
462 <tag><tt>targetImplementationName </tt>returns <em>string</em></tag>
463 Implementation-name of target system.
464 <tag><tt>targetImplementationId </tt>returns <em>string</em></tag>
465 Implementation-id of target system.
466 <tag><tt>targetImplementationVersion </tt>returns <em>string</em></tag>
467 Implementation-version of target system.
468 <tag><tt>options </tt>returns <em>list</em></tag>
469 Options after negotiation. The list contains the options that are set.
470 <tag><tt>protocolVersion </tt>returns <em>integer</em></tag>
471 Protocol version: 2, 3, etc after negotiation.
472 <tag><tt>userInformationField </tt>returns <em>string</em></tag>
473 User information field.
474 <tag><tt>referenceId </tt>returns <em>string</em></tag>
475 Reference-id of init response.
480 Consider a client with the ability to access multiple targets.
482 We define a list of targets that we wish to connect to.
483 Each item in the list describes the target parameters with
484 the following four components: association-name, comstack-type,
485 protocol-type and a hostname.
487 The list for the two targets: ISO/SR target DANBIB and TCP/Z39.50
488 target Data Research, will be defined as:
490 set targetList { {danbib mosi SR 0103/find2.denet.dk:4500}
491 {drs tcpip Z39 dranet.dra.com} }
494 The Tcl code below defines, connect and initialize the
495 targets in <tt/targetList/:
498 foreach target $targetList {
499 set assoc [lindex $target 0]
501 $assoc comstack [lindex $target 1]
502 $assoc protocol [lindex $target 2]
503 $assoc failback [list fail-response $assoc]
504 $assoc callback [list connect-response $assoc]
505 $assoc connect [lindex $target 3]
508 proc connect-response {assoc} {
509 $assoc callback [list init-response $assoc]
513 proc fail-response {assoc} {
514 puts "$assoc closed connection or protocol error"
517 proc init-response {assoc} {
518 if {[$assoc initResult]} {
519 puts "$assoc initialized ok"
521 puts "$assoc didn't initialize"
526 <tt/target/ is bound to each item in the list of targets.
527 The <tt/assoc/ is set to the ir object name.
528 Then, the comstack, protocol and failback are set for the <tt/assoc/ object.
529 The ir object name is argument to the <tt/fail-response/ and
530 <tt/connect-response/ routines.
531 Note the use of the Tcl <tt/list/ command which
532 is necessary here because the argument contains variables
533 (<tt/assoc/) that should be substituted before the handler is defined.
534 After the connect operation, the <tt/init-response/ handler
535 is defined in much the same way as the failback handler.
536 And, finally, an init request is executed.
543 To terminate the connection the <tt/disconnect/ action should be used.
544 This action has no parameters.
545 Another connection may be established by a new <tt/connect/ action on
551 This section covers the queries used by <sf/IrTcl/, and how searches and
552 presents are handled.
554 A search operation and a result set is described by the ir set object.
555 The ir set object is defined by the <tt/ir-set/ command which
556 has two parameters. The first is the name of the new ir set object, and
557 the second, which is optional, is the name of an assocation -- an ir
558 object. The second argument is required if the ir set object should be able
559 to perform searches and presents. However, it is not required if
560 only ``local'' operations is done with the ir set object.
562 When the ir set object is created a number of settings are inherited
563 from the ir object, such as the selected databass, query type,
564 etc. Thus, the ir object contains what we could call default
570 Search requests are sent by the <tt/search/ action which
571 takes a query as parameter. There are two types of queries,
572 RPN and CCL, controlled by the setting <tt/queryType/.
573 A string representation for the query is used in <sf/IrTcl/ since
574 Tcl has reasonably powerful string manipulaton capabilities.
575 The RPN query used in <sf/IrTcl/ is the prefix query notation also used in
576 the <bf/YAZ/ test client.
578 The CCL query is an uninterpreted octet-string which is parsed by the target.
579 We refer to the standard: ISO 8777. Note that only a few targets
580 actually support the CCL query and the interpretation of
581 the standard may vary.
583 The prefix query notation (which is converted to RPN) offer a few
587 <tag><tt>@attr </tt><em>list op</em></tag>
588 The attributes in list are applied to op
589 <tag><tt>@and </tt><em>op1 op2</em></tag>
590 Boolean <em/and/ on op1 and op2
591 <tag><tt>@or </tt><em>op1 op2</em></tag>
592 Boolean <em/or/ on op1 and op2
593 <tag><tt>@not </tt><em>op1 op2</em></tag>
594 Boolean <em/not/ on op1 and op2
595 <tag><tt>@prox </tt><em>list op1 op2</em></tag>
596 Proximity operation on op1 and op2. Not implemented yet.
597 <tag><tt>@set </tt><em>name</em></tag>
599 <tag><tt>@attrset </tt><em>set</em></tag>
600 Whole query uses the specified attribute <em>set</em>. If this operator is
601 used it must be defined at the beginning of the query.
604 It is simple to build RPN queries in <sf/IrTcl/. Search terms
605 are sequences of characters, as in:
610 Boolean operators use the prefix notation (instead of the suffix/RPN),
613 @and science technology
616 Search terms may be associated with attributes. These
617 attributes are indicated by the <tt/@attr/ operator.
618 Assuming the bib-1 attribute set, we can set the use-attribute
619 (type is 1) to title (value is 4):
625 Also, it is possible to apply attributes to a range of search terms.
626 In the query below, both search terms have use=title but the <tt/tech/
627 term is right truncated:
630 @attr 1=4 @and @attr 5=1 tech beta
633 To search for the DatabaseInfo records from an Explain server, we
636 @attrset exp1 @attr 1=1 DatabaseInfo
642 The settings that affect the search are listed below:
645 <tag><tt>databaseNames </tt><em>list</em></tag>
647 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
648 Small set upper bound. Default 0.
649 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
650 Large set lower bound. Default 2.
651 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
652 Medium set present number. Default 0.
653 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>
654 Replace-indicator. Default true (1).
655 <tag><tt>setName </tt><em>string</em></tag>
656 Name of result set. Default name of set is <tt/default/.
657 <tag><tt>queryType rpn|ccl</tt></tag>
658 Query type-1 or query type-2. Default rpn (type-1).
659 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
660 Preferred record syntax -- UNIMARC, USMARC, etc.
661 <tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
662 small-set-element-set names. If <em>string</em> is empty
663 the element set is not set. Default is empty (not set).
664 <tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
665 medium-set-element-set names. If <em>string</em> is empty
666 the element set is not set. Default is empty (not set).
667 <tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
668 Next result set position.
669 <tag><tt>referenceId </tt><em>string</em></tag>
670 Reference-id. If <em>string</em> is empty no reference-id is used.
671 <tag><tt>searchResponse </tt><em>list</em></tag>
672 Search-response Tcl script.
673 <tag><tt>callback </tt><em>list</em></tag>
674 General response Tcl script. Only used if searchResponse is not specified.
675 This setting is valid only for the <tt/ir/ object -- not the
679 Setting the <tt/databaseNames/ is mandatory. All other settings
680 have reasonable defaults.
681 The search-response handler, specified by the <tt/callback/ - or
682 the <tt/searchResponse/ setting,
683 should read some of the settings shown below:
686 <tag><tt>searchStatus</tt> returns <em>boolean</em></tag>
687 Search-status. True if search operation was successful; false
689 <tag><tt>responseStatus </tt>returns <em>list</em></tag>
690 Response status information.
691 <tag><tt>resultCount </tt>returns <em>integer</em></tag>
693 <tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
694 Number of records returned.
695 <tag><tt>referenceId </tt>returns <em>string</em></tag>
696 Reference-id of search response.
699 The <tt/responseStatus/ signals one of three conditions which
700 is indicated by the value of the first item in the list:
703 <tag><tt>NSD</tt></tag> indicates that the target has returned one or
704 more non-surrogate diagnostic messages. The <tt/NSD/ item is followed by
705 a list with all non-surrogate messages. Each non-surrogate message consists
706 of three items. The first item of the three items is the error
707 code (integer); the next item is a textual representation of the error
708 code in plain english; the third item is additional information, possibly
709 empty if no additional information was returned by the target.
711 <tag><tt>DBOSD</tt></tag> indicates a successful operation where the
712 target has returned one or more records. Each record may be
713 either a database record or a surrogate diagnostic.
715 <tag><tt>OK</tt></tag> indicates a successful operation -- no records are
716 returned from the target.
721 We continue with the multiple-targets example.
722 The <tt/init-response/ procedure will attempt to make searches:
725 proc init-response {assoc} {
726 puts "$assoc connected"
727 ir-set ${assoc}.1 $assoc
728 $assoc.1 queryType rpn
729 $assoc.1 databaseNames base-a base-b
730 $assoc callback [list search-response $assoc ${assoc}.1]
731 $assoc.1 search "@attr 1=4 @and @attr 5=1 tech beta"
735 An ir set object is defined and the
736 ir object is told about the name of ir object.
737 The ir set object use the name of the ir object as prefix.
739 Then, the query-type is defined to be RPN, i.e. we will
740 use the prefix query notation later on.
742 Two databases, <tt/base-a/ and <tt/base-b/, are selected.
744 A <tt/search-response/ handler is defined with the
745 ir object and the ir-set object as parameters and
746 the search is executed.
748 The first part of the <tt/search-response/ looks like:
750 proc search-response {assoc rset} {
751 set status [$rset responseStatus]
752 set type [lindex $status 0]
753 if {$type == "NSD"} {
754 set code [lindex $status 1]
755 set msg [lindex $status 2]
756 set addinfo [lindex $status 3]
757 puts "NSD $code: $msg: $addinfo"
760 set hits [$rset resultCount]
761 if {$type == "DBOSD"} {
762 set ret [$rset numberOfRecordsReturned]
767 The response status is stored in variable <tt/status/ and
768 the first element indicates the condition.
769 If non-surrogate diagnostics are returned they are displayed.
770 Otherwise, the search was a success and the number of hits
771 is read. Finally, it is tested whether the search response
772 returned records (database or diagnostic).
774 Note that we actually didn't inspect the search status (setting
775 <tt/searchStatus/) to determine whether the search was successful or not,
776 because the standard specifies that one or more non-surrogate
777 diagnostics should be returned by the target in case of errors.
781 If one or more records are returned from the target they
782 will be stored in the result set object.
783 In the case in which the search response contains records, it is
784 very similar to the present response case. Therefore, some settings
785 are common to both situations.
790 The <tt/present/ action sends a present request. The <tt/present/ is
791 followed by two optional integers. The first integer is the
792 result-set starting position -- defaults to 1. The second integer
793 is the number of records requested -- defaults to 10.
794 The settings which could be modified before a <tt/present/
798 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
799 preferred record syntax -- UNIMARC, USMARC, etc.
800 <tag><tt>elementSetNames </tt><em>string</em></tag>
801 Element-set names. If <em>string</em> is empty
802 the element set is not set. Default is empty (not set).
803 <tag><tt>referenceId </tt><em>string</em></tag>
804 Reference-id. If <em>string</em> is empty no reference-id is used.
805 <tag><tt>presentResponse </tt><em>list</em></tag>
806 Present-response Tcl script.
807 <tag><tt>callback </tt><em>list</em></tag>
808 General response Tcl script. Only used if presentResponse is not specified
809 This setting is valid only for the <tt/ir/ object -- not the
813 The present-response handler should inspect the settings
814 shown in table below.
815 Note that <tt/responseStatus/ and <tt/numberOfRecordsReturned/
816 settings were also used in the search-response case.
818 As in the search response case, records returned from the
819 target are stored in the result set object.
822 <tag><tt>presentStatus </tt>returns <em>boolean</em></tag>
824 <tag><tt>responseStatus </tt>returns <em>list</em></tag>
825 Response status information.
826 <tag><tt>numberOfRecordsReturned </tt>returns <em>integer</em></tag>
827 Number of records returned.
828 <tag><tt>nextResultSetPosition </tt>returns <em>integer</em></tag>
829 Next result set position.
830 <tag><tt>referenceId </tt>returns <em>string</em></tag>
831 Reference-id of present response.
837 Search responses and present responses may result in
838 one or more records stored in the ir set object if
839 the <tt/responseStatus/ setting indicates database or
840 surrogate diagnostics (<tt/DBOSD/). The individual
841 records, indexed by an integer position offset, should then be
844 If element set names have been specified either in the
845 search requests (<tt>smallSetElementSetNames</tt> /
846 <tt>mediumSetElementSetNames</tt>) or present requests
847 (<tt>elementSetNames</tt>) the individual records in the
848 ir set object are assigned appropriate element set ids.
849 In this mode records at a given position are treated different as
850 long as they have difference element set ids.
851 To inspect records with a particular element set id in subsequent
852 operations use the <tt>recordElements</tt> setting followed by the id.
853 If you have more than one record at a given position and you do not
854 use <tt>recordElements</tt> the record selected at the given position
857 The action <tt>type</tt> followed by an integer returns information
858 about a given position in an ir set. There are three possiblities:
861 <tag><tt/SD/</tag> The item is a surrogate diagnostic record.
862 <tag><em/empty/</tag> There is no record at the specified position.
863 <tag><tt/DB/</tag> The item is a database record.
866 To handle the first case, surrogate diagnostic record, the
867 <tt/Diag/ action should be used. It returns three
868 items: error code (integer), text representation in plain english
869 (string), and additional information (string, possibly empty).
871 In the second case, no record, note that there still might
872 be a record at the position but with an id that differs from that
873 specified by <tt>recordElements</tt>.
875 In the third case, database record, the <tt/recordType/ action should
876 be used. It returns the record type at the given position.
877 Some record types are:
894 We continue our search-response example. In the case,
895 <tt/DBOSD/, we should inspect the result set items.
896 Recall that the ir set name was passed to the
897 search-response handler as argument <tt/rset/.
900 if {$type == "DBOSD"} {
901 set ret [$rset numberOfRecordsReturned]
902 for {set i 1} {$i<=$ret} {incr i} {
903 set itype [$rset type $i]
904 if {$itype == "SD"} {
905 set diag [$rset Diag $i]
906 set code [lindex $diag 0]
907 set msg [lindex $diag 1]
908 set addinfo [lindex $diag 2]
909 puts "$i: NSD $code: $msg: $addinfo"
910 } elseif {$itype == "DB"} {
911 set rtype [$rset recordType $i]
912 puts "$i: type is $rtype"
917 Each item in the result set is examined.
918 If an item is a diagnostic message it is displayed; otherwise
919 if it's a database record its type is displayed.
926 In the case, where there is a MARC record at a given position we
927 want to display it somehow. The action <tt/getMarc/ is what we need.
928 The <tt/getMarc/ is followed by a position integer and the type of
929 extraction we want to make: <tt/field/ or <tt/line/.
931 The <tt/field/ and <tt/line/ type are followed by three
932 parameters that serve as extraction masks.
933 They are called tag, indicator and field.
934 If the mask matches a tag/indicator/field of a record the information
935 is extracted. Two characters have special meaning in masks: the
936 dot (any character) and star (any number of any character).
938 The <tt/field/ type returns one or more lists of field information
939 that matches the mask specification. Only the content of fields
942 The <tt/line/ type, on the other hand, returns a Tcl list that
943 completely describe the layout of the MARC record -- including
946 The <tt/field/ type is sufficient and efficient in the case, where only a
947 small number of fields are extracted, and in the case where no
948 further processing (in Tcl) is necessary.
950 However, if the MARC record is to be edited or altered in any way, the
951 <tt/line/ extraction is more powerful -- only limited by the Tcl
956 Consider the record below:
961 008 910710c19910701nju 00010 eng
965 100 10 $a Jack Collins
966 245 10 $a How to program a computer
972 Assuming this record is at position 1 in ir-set <tt/z.1/, we
973 might extract the title-field (245 * a), with the following command:
975 z.1 getMarc 1 field 245 * a
980 {How to program a computer}
983 Using the <tt/line/ instead of <tt/field/ gives:
985 {245 {10} {{a {How to program a computer}} }}
988 If we wish to extract the whole record as a list, we use:
990 z.1 getMarc 1 line * * *
995 {001 {} {{{} { 11224466 }} }}
997 {005 {} {{{} 00000000000000.0} }}
998 {008 {} {{{} {910710c19910701nju 00010 eng }} }}
999 {010 { } {{a { 11224466 }} }}
1000 {040 { } {{a DLC} {c DLC} }}
1001 {050 {00} {{a 123-xyz} }}
1002 {100 {10} {{a {Jack Collins}} }}
1003 {245 {10} {{a {How to program a computer}} }}
1004 {260 {1 } {{a Penguin} }}
1005 {263 { } {{a 8710} }}
1006 {300 { } {{a {p. cm.}} }}
1013 This example demonstrates how Tcl can be used to examine
1014 a MARC record in the list notation.
1016 The procedure <tt/extract-format/ makes an extraction of
1017 fields in a MARC record based on a number of masks.
1018 There are 5 parameters, <tt/r/: a
1019 record in list notation, <tt/tag/: regular expression to
1020 match the record tags, <tt/ind/: regular expression to
1021 match indicators, <tt/field/: regular expression to
1022 match fields, and finally <tt/text/: regular expression to
1023 match the content of a field.
1026 proc extract-format {r tag ind field text} {
1028 if {[regexp $tag [lindex $line 0]] && \
1029 [regexp $ind [lindex $line 1]]} {
1030 foreach f [lindex $line 2] {
1031 if {[regexp $field [lindex $f 0]]} {
1032 if {[regexp $text [lindex $f 1]]} {
1042 To match <tt/comput/ followed by any number of character(s) in the
1043 245 fields in the record from the previous example, we could use:
1045 set r [z.1 getMarc 1 line * * *]
1047 extract-format $r 245 .. . comput
1051 How to program a computer
1056 The <tt/putMarc/ action does the opposite of <tt/getMarc/. It
1057 copies a record in Tcl list notation to a ir set object and is
1058 needed if a result-set must be updated by a Tcl modified (user-edited)
1064 In <sf/IrTcl/ a SUTRS record is treated as one single string. To retrieve
1065 a SUTRS record use the <tt>getSutrs</tt> followed by an index.
1073 Explain records are retrieved like other records. The method,
1074 <tt>getExplain</tt> is followed by an index and, and an optional
1075 Explain record pattern.
1077 The returned record is a canonical representation of the Explain record.
1078 An ASN.1 sequence is represented as a list. Each item in the list
1079 consists of the name of the element, followed by its value if the value
1082 The optional pattern that follows the index after <tt>getExplain</tt>
1083 consists of one or more elements, that is matched against the elements
1084 of the actual record.
1088 One of the few targets that support explain is the ATT research server
1089 at <tt>z3950.research.att.com</tt>.
1091 The targetInfo record was returned by the target and it's stored in
1092 position 1 in the result set, <tt>z.1</tt>. To retrieve the whole
1098 and we get in return
1101 {targetInfo commonInfo {name {Lucent Technologies Research Server}}
1102 recentNews icon {namedResultSets 1} {multipleDBsearch 0}
1103 {maxResultSets 100} {maxResultSize 600000} maxTerms timeoutInterval
1104 {welcomeMessage {strings { {language eng}
1106 {Salutations - this is Lucent Technologies experimental Z39.50 server.
1107 No guarentees, but free and unlimited access!}} } } }
1108 {contactInfo {name {Robert Waldstein}} {description {strings
1110 {text {Librarian system designer - no legal anythings}} } } }
1111 {address {strings { {language eng} {text {Room 3D-591
1114 N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}} }
1115 description nicknames {usageRest {strings { {language eng}
1116 {text {None - as long as nonProfit research}} } } } paymentAddr
1117 {hours {strings { {language eng} {text {Should never be down}} } } }
1118 dbCombinations addresses commonAccessInfo }
1121 The <tt>targetInfo</tt> above indicates the the record is really a
1122 <tt>targetInfo</tt> record. The <tt>commonInfo</tt>, which is optional, is
1123 not supplied by this server. The <tt>name</tt>, however is supplied,
1124 with the value <tt>Lucent Technologies Research Server</tt>.
1126 To retrieve the <tt>contactInfo</tt> from the record above we can
1127 extract the element from the record by using Tcl's list manipulation
1128 facilities, for example by doing
1130 set ti [z.1 getExplain 1]
1131 lindex [lindex $ti 0] 12
1135 contactInfo {name {Robert Waldstein}} {description {strings
1137 {text {Librarian system designer - no legal anythings}} }
1138 } } {address {strings { {language eng} {text {Room 3D-591
1141 N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}}
1144 We can also extract almost the same by doing
1146 z.1 getExplain 1 targetInfo contactInfo
1150 {name {Robert Waldstein}} {description {strings { {language eng}
1151 {text {Librarian system designer - no legal anythings}} } } }
1152 {address {strings { {language eng} {text {Room 3D-591
1155 N.J. USA 07974}} } } } {email wald@lucent.com} {phone {908 582-6171}}
1163 To perform scan, a scan object must be created by the <tt>ir-scan</tt>
1164 command. This command has two arguments -- name of the scan object and
1165 name of the ir object. Basically, the scan object, provides one <tt>scan</tt>
1166 action which sends a scan request to the target. The <tt>action</tt>
1167 is followed by a string describing starting point of the term list. The
1168 format used is a simple subset of the query used in search requests. Only
1169 <tt>@attr</tt> specifications and simple terms are allowed.
1170 The settings that affect the scan are:
1173 <tag><tt>stepSize </tt><em>integer</em></tag>
1174 Step size. Default is 0.
1175 <tag><tt>numberOfTermsRequested </tt><em>integer</em></tag>
1176 Number of terms requested. Default is 20.
1177 <tag><tt>preferredPositionInResponse </tt><em>integer</em></tag>
1178 Preferred position in response. Default is 1.
1179 <tag><tt>databaseNames </tt><em>list</em></tag>
1180 Database names. Note that this setting is not (yet) supported for
1181 the scan object. You must set this for the ir object instead.
1182 <tag><tt>referenceId </tt><em>string</em></tag>
1183 Reference-id. If <em>string</em> is empty no reference-id is used.
1184 <tag><tt>scanResponse </tt><em>list</em></tag>
1185 Scan-response Tcl script.
1186 <tag><tt>callback </tt><em>list</em></tag>
1187 General response Tcl script. Only used if <tt>scanResponse</tt>
1189 This setting is valid only for the <tt/ir/ object -- not the
1193 The scan object normally holds one or more scan line entries upon
1194 successful completion. The table below summarizes the settings
1195 that should be used in a response handler.
1198 <tag><tt>scanStatus </tt>returns <em>integer</em></tag>
1199 Scan status. An integer between 0 and 6.
1200 <tag><tt>numberOfTermsReturned </tt>returns <em>integer</em></tag>
1201 Number of terms returned.
1202 <tag><tt>positionOfTerm </tt>returns <em>integer</em></tag>
1203 An integer describing the position of term.
1204 <tag><tt>scanLine </tt>returns <em>list</em></tag>
1205 This function returns information about a given scan line (entry) at a given
1206 index specified by the integer. The first scan line is numbered zero;
1207 the second 1 and so on. A list is returned by the <tt>scanLine</tt>
1208 setting. The first element is <tt>T</tt> if the scan line
1209 is a normal term and <tt>SD</tt> if the scan line is a surrogate
1210 diagnostic. In the first case (normal) the scan term is second element
1211 in the list and the number of occurences is the third element.
1212 In the other case (surrogate diagnostic), the second element
1213 is the diagnostic code, the third a text representation of the error
1214 code and the fourth element is additional information.
1215 <tag><tt>referenceId </tt>returns <em>string</em></tag>
1216 Reference-id of scan response.
1221 We will scan for the terms after <tt>science</tt> in the Title index.
1222 We will assume that an ir object called <tt>z-assoc</tt> has already
1226 z-assoc callback {scan-response}
1227 ir-scan z-scan z-assoc
1228 z-scan scan "@attr 1=4 science"
1230 proc scan-response {} {
1231 set status [z-scan status]
1233 set no [z-scan numberOfTermsReturned]
1234 for {set i 0} {$i < $no} {incr i} {
1235 set line [z-scan scanLine $i]
1236 set type [lindex $line 0]
1238 puts [lindex $line 1]
1239 } elseif {$type == "SD"} {
1240 puts [lindex $line 1]
1251 Copyright © 1995-1996, Index Data.
1253 Permission to use, copy, modify, distribute, and sell this software and
1254 its documentation, in whole or in part, for any purpose, is hereby granted,
1257 1. This copyright and permission notice appear in all copies of the
1258 software and its documentation. Notices of copyright or attribution
1259 which appear at the beginning of any file must remain unchanged.
1261 2. The names of Index Data or the individual authors may not be used to
1262 endorse or promote products derived from this software without specific
1263 prior written permission.
1265 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
1266 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
1267 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1268 IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
1269 INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
1270 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
1271 NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
1272 LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
1275 <sect>About Index Data
1278 Index Data is a consulting and software-development enterprise that
1279 specialises in library and information management systems. Our
1280 interests and expertise span a broad range of related fields, and one
1281 of our primary, long-term objectives is the development of a powerful
1282 information management
1283 system with open network interfaces and hypermedia capabilities.
1285 We make this software available free of charge, on a fairly unrestrictive
1286 license; as a service to the networking community, and to further the
1287 development of quality software for open network communication.
1289 We'll be happy to answer questions about the software, and about ourselves
1295 2200 København N&nl
1301 Phone: +45 3536 3672
1303 Email: info@index.ping.dk
1311 <tag>1 Ousterhout, John K.:</tag>
1312 Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
1313 0-201-63337-X). The Tcl/Tk toolkit home page is
1314 <tt><htmlurl url="http://www.sunlabs.com/research/tcl/"
1315 name="http://www.sunlabs.com/research/tcl"></tt>.
1316 The primary ftp site is <tt><htmlurl url="ftp://ftp.smli.com/pub/tcl/"
1317 name="ftp://ftp.smli.com/pub/tcl/"></tt>.
1318 A mirror site can be found at <tt>
1319 <htmlurl url="ftp://ftp.neosoft.com/pub/tcl/mirror/ftp.smli.com"
1320 name="ftp://ftp.neosoft.com/pub/tcl/mirror/ftp.smli.com"></tt>.
1321 <tag>2 Furniss, Peter:</tag>
1322 RFC 1698: Octet Sequences for Upper-Layer OSI to Support
1323 Basic Communications Applications.