1 <!doctype linuxdoc system>
4 $Id: ir-tcl.sgml,v 1.10 1995-06-26 10:20:45 adam Exp $
8 <title>IrTcl User's Guide and Reference
9 <author>Index Data, <tt/info@index.ping.dk/
10 <date>$Revision: 1.10 $
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.
54 <item> YAZ version 1.0b or higher
57 As an option you may want:
63 Newer versions of Tcl and Tk have been released. These packages
64 will <em/not/ work with <sf/IrTcl/. The <sf/IrTcl/ package will
65 probably be able to use the newer versions soon. Fortunately this
66 move will not change the <sf/IrTcl/ API — only the Tk code of the
67 test client will be modified.
69 Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/.
76 This command tries to configure <sf/IrTcl/ for your system and creates
79 If the <tt>configure</tt> command cannot locate Tcl and Tk in your standard
80 locations for libraries searched by your C compiler it will guess
81 that the libraries are located in <tt>/usr/local/lib</tt> and that
82 the header files are located in <tt>/usr/local/include</tt>.
83 If this is incorrect you will have to modify the <tt>Makefile</tt> yourself.
85 Compile <sf/IrTcl/ by typing:
90 If you don't have Tk you will only be able to create the <tt>ir-tcl</tt>
91 program and you must type <tt>make ir-tcl</tt> instead.
93 If successful, this will make <tt>ir-tcl</tt>, <tt>ir-tk</tt> (if
94 Tk is present) and a library called <tt>libirtcl.a</tt>.
96 To install the programs and support files type:
101 Summary of files installed (the names refer to the Makefile variables):
104 <tag><tt>ir-tk</tt></tag> The <sf/IrTcl/ shell for Tk.
105 Installed in <tt>BINDIR</tt> — defaults to
106 <tt>/usr/local/bin</tt>. <tt>ir-tk</tt> works like
107 <tt>wish</tt> &mdash without arguments it reads commands from stdin.
108 A source file may be specified by option <tt>-f</tt>. <tt>ir-tk</tt>
109 accept the same set of options as <tt>wish</tt>.
110 <tag><tt>ir-tcl</tt></tag> The <sf/IrTcl/ shell for Tcl. Installed in
111 <tt>BINDIR</tt> — defaults to <tt>/usr/local/bin</tt>.
112 <tag><tt>client.tcl</tt></tag> A graphical client for <tt>ir-tk</tt>.
113 The client is installed as an executable script called <tt>irclient</tt> in
114 <tt>BINDIR</tt>. This client needs a number of files, bitmaps, etc.
115 The client looks for the files in the current directory &mdash if
116 this fails it tries to look in the directory <tt>IRTCLDIR</tt>
117 — defaults to <tt>/usr/local/lib/irtcl</tt>.
118 <tag><tt>libirtcl.a</tt></tag> The <sf/IrTcl/ library.
119 Installed in <tt>LIBDIR</tt> — defaults to <tt>/usr/local/lib</tt>.
120 <tag><tt>ir-tcl.h</tt></tag> The <sf/IrTcl/ header file.
121 Installed in <tt>INCDIR</tt> — defaults to <tt>/usr/local/include</tt>.
122 <tag><tt>clientrc.tcl</tt></tag> A setup file with definitions
123 of target and queries. Read and updated by <tt>client.tcl</tt>. Installed
124 in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
125 <tag><tt>formats/*</tt></tag> Display format files written
126 in Tk. Read by <tt>client.tcl</tt>. Installed
127 in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
128 <tag><tt>bitmaps/*</tt></tag> Various bitmap files. Read by
129 <tt>client.tcl</tt>. Installed
130 in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
131 <tag><tt>LICENSE</tt></tag> LICENSE file. Read by
132 <tt>client.tcl</tt>. Installed
133 in <tt>IRTCLDIR</tt> — defaults to <tt>/usr/local/lib/irtcl</tt>.
139 The <tt>ir-tcl</tt> program is a shell like <tt>tclsh</tt> except that
140 <tt>ir-tcl</tt> features the new set of information retrieval commands.
141 Normally <tt>ir-tcl</tt> waits on <tt/stdin/ (for you to type commands) and
142 on sockets events (connected to Z39.50/SR targets).
143 You simply type the Tcl commands line by line. A filename may be specified as
144 argument to <tt>ir-tcl</tt> in which case the file specified is evaluated
150 <tt>ir-tk</tt> is a program that works like <tt>wish</tt> except that
151 <tt>ir-tk</tt> include the new set of commands.
153 The enclosed script <tt>client.tcl</tt> for <tt>ir-tk</tt>
154 is a graphical client which demonstates an example of a user interface
155 for the Z39.50/SR protocols.
156 At first the script was relatively small but it has grown since the
157 beginning. At present it is about 3000 lines.
159 The client lets up define targets and query types within the interface.
160 Hence, you will not need to modify configation files.
162 Stuff concerning targets can be found in the pull down menu 'Target'
163 with the following options:
165 <tag>Connect</tag> Establishes connection to a target.
166 <tag>Disconnect</tag> Closes a target connection.
167 <tag>About</tag> Shows implementation Id, implementation Version, etc
168 for the current target.
169 <tag>Setup</tag> Pops up a target definition window. You may alter
171 <tag>Setup new</tag> Lets you define a new target.
174 The term query type refers to a collection of search fields. The
175 pull down menu Options|Query deals with queries. You may
176 insert/modify/remove query types.
178 <sect>Overview of the API
181 Basically, <sf/IrTcl/ is a set of commands introduced to Tcl.
182 When extending Tcl there are two approaches: action-oriented commands
183 and object-oriented commands.
185 Action-oriented commands manipulate
186 Tcl variables and each command introduces only one action.
187 The string manipulation commands in Tcl are action oriented.
189 Object-oriented commands are added for every declared
190 variable (object). Object-oriented commands usually provide a set of
191 actions (methods) to manipulate the object.
192 The widgets in Tk (X objects) are examples of the object-oriented style.
194 <sf/IrTcl/ commands are object-oriented. The main reason
195 for this is that the data structures involved in the IR protocol
196 are not easily represented by Tcl data structures.
197 Also, the <sf/IrTcl/ objects tend to exist for a relativly long time.
198 Note that although we use the term object-oriented commands, this
199 does not mean that the programming style is strictly object-oriented. For
200 example, there is such no such thing as inheritance.
202 We are now ready to present the three commands introduced to Tcl by
206 <tag/ir/ The ir object represents a connection to a target. More
207 precisely it describes a Z-association.
208 <tag/ir-set/ The ir-set describes a result set, which is
209 conceptually a collection of records returned by the target.
210 The ir-set object may retrieve records from a target by means of
211 the ir object; it may read/write records from/to a local file or it may be
212 updated with a user-edited record.
213 <tag/ir-scan/ The scan object represents a list of scan lines
214 retrieved from a target.
219 To create a new IR object called <tt/z-assoc/ write:
226 Each object provides a set of <em/settings/ which may either be
227 readable, writeable of both. All settings immediately follow
228 the name of the object. If a value is present the setting
229 is set to <em/value/.
233 We wish to set the preferred-message-size to 18000 on the
237 z-assoc preferredMessageSize 18000
240 To read the current value of preferred-message-size use:
243 z-assoc preferredMessageSize
247 One important category consists of settings is those that relate to the
248 event-driven model. When <sf/IrTcl/ receives responses from the target, i.e.
249 init responses, search responses, etc., a <em/callback/ routine
250 is called. Callback routines are represented in Tcl as
251 a list, which is re-interpreted prior to invocation.
252 The method is similar to the one used in Tk to capture X events.
254 For each SR/Z39.50 request there is a corresponding object action. The most
255 important actions are:
257 <tag/connect/ Establishes connection with a target
258 <tag/init/ Sends an initialize request.
259 <tag/search/ Sends a search request.
260 <tag/present/ Sends a present request.
261 <tag/scan/ Sends a scan request.
266 This example shows a complete connect - init - search - present scenario.
268 First an IR object, called <tt/z/, is created.
269 Also a result set <tt/z.1/ is introduced by the <tt/ir-set/
270 and it is specified that the result set uses <tt/z/ as its association.
272 The setting <tt/databaseNames/ is set to the
273 database <tt/books/ to which the following searches are directed.
274 A callback is then defined and a connection is established to
275 <tt/fake.com/ by the <tt/connect/ action.
276 If the connect succeeds the <tt/connect-response/ is called.
278 In the Tcl procedure, <tt/connect-response/, a callback is defined
279 <em/before/ the init request is executed.
280 The Tcl procedure <tt/init-response/ is called when a
281 init response is returned from the target.
283 The <tt/init-response/ procedure sets up a <tt/search-response/
284 callback handler and sends a search-request by using a query which
285 consists of a single word <tt/science/.
287 When the <tt/search-response/ procedure is called it defines
288 a variable <tt/hits/ and sets it to the value of the setting
289 <tt/resultCount/. If <tt/hits/ is positive a present-request is
290 sent — asking for 5 records from position 1.
292 Finally, a present response is received and the number of records
293 returned is stored in the variable <tt/ret/.
298 z databaseNames books
299 z callback {connect-response}
302 proc connect-response {} {
303 z callback {init-response}
307 proc init-response {} {
308 z.1 callback {search-response}
312 proc search-response {} {
313 set hits [z.1 resultCount]
316 z.1 callback {present-response}
321 proc present-response {} {
322 set ret [z.1 numberOfRecordsReturned]
323 puts "$ret records returned"
328 The previous example program doesn't care about error conditions.
329 If errors occur in the program they will be trapped by the Tcl error
330 handler. This is not always appropriate. However, Tcl offers a
331 <tt/catch/ command to support error handling by the program itself.
336 The ir object describes an association with a target.
337 This section covers the connect-init-disconnect actions provided
339 An ir object is created by the <tt/ir/ command and the
340 created object enters a 'not connected' state, because it isn't
341 connected to a target yet.
346 A connection is established by the <tt/connect/ action which is
347 immediately followed by a hostname. A number of settings affect the
348 <tt/connect/ action. Obviously, these settings should be set
349 <bf/before/ connecting. The settings are:
352 <tag><tt>comstack </tt><tt>mosi|tcpip</tt></tag>
354 <tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
355 Protocol type - ANSI/NISO Z39.50 or ISO SR.
356 <tag><tt>callback </tt><em>list</em></tag>
357 Tcl script called when the connection is established
358 <tag><tt>failback </tt><em>list</em></tag>
359 Fatal error Tcl script. Called on protocol errors or if target
363 If the connect is unsuccessful either the connect action itself
364 will return an error code or the failback handler is invoked.
369 If the connect operation succeeds the <tt/init/ action should be used.
370 The init related settings are:
373 <tag><tt>preferredMessageSize </tt><em>integer</em></tag>
374 Preferred-message-size. Default value is 30000.
375 <tag><tt>maximumRecordSize </tt><em>integer</em></tag>
376 Maximum-record-size. Default value is 30000.
377 <tag><tt>idAuthentication </tt><em>string</em> ...</tag>
378 Id-authentication. There are three forms. If any empty is
379 given, the Id-authentication is not used. If one non-empty string
380 is given, the 'open' authentication is used. If three strings are
381 specified, the version 'id-pass' authentication (version 3 only)
382 is used in which case the first string is groupId; the second string
383 is userId and the third string is password.
384 <tag><tt>implementationName </tt><em>string</em></tag>
385 Implementation-name of origin system.
386 <tag><tt>implementationId</tt></tag>
387 Implementation-id of origin system. This setting is read-only.
388 <tag><tt>implementationVersion</tt></tag>
389 Implementation-version of origin system. This settings is read-only.
390 <tag><tt>options </tt><em>list</em></tag>
391 Options to be negotiated in the init service. The list contains
392 the options that are set. Possible values are <tt>search</tt>,
393 <tt>present</tt>, <tt>delSet</tt>, <tt>resourceReport</tt>,
394 <tt>triggerResourceCtrl</tt>, <tt>resourceCtrl</tt>,
395 <tt>accessCtrl</tt>, <tt>scan</tt>, <tt>sort</tt>,
396 <tt>extendedServices</tt>, <tt>level-1Segmentation</tt>,
397 <tt>level-2Segmentation</tt>, <tt>concurrentOperations</tt> and
398 <tt>namedResultSets</tt>. Currently the default options are:
399 <tt>search</tt>, <tt>present</tt>, <tt>scan</tt> and
400 <tt>namedResultSets</tt>. The <tt>options</tt> setting is set to its default
401 value when an ir object is created and when a <tt>disconnect</tt>
403 <tag><tt>protocolVersion </tt><em>integer</em></tag>
404 Protocol version: 2, 3, etc. Default is 2.
405 <tag><tt>initResponse </tt><em>list</em></tag>
406 Init-response Tcl script. Note: not implemented - use <tt>callback</tt>
408 <tag><tt>callback </tt><em>list</em></tag>
409 General response Tcl script. Only used if <tt>initResponse</tt>
413 The init-response handler should inspect some of the settings shown
417 <tag><tt>initResult </tt><em>boolean</em></tag>
418 Init response status. True if init operation was successful;
420 <tag><tt>preferredMessageSize </tt><em>integer</em></tag>
421 Preferred-message-size.
422 <tag><tt>maximumRecordSize </tt><em>integer</em></tag>
424 <tag><tt>targetImplementationName </tt><em>string</em></tag>
425 Implementation-name of target system.
426 <tag><tt>targetImplementationId </tt><em>string</em></tag>
427 Implementation-id of target system.
428 <tag><tt>targetImplementationVersion </tt><em>string</em></tag>
429 Implementation-version of target system.
430 <tag><tt>options </tt><em>list</em></tag>
431 Options negotiated in init. The list contains the options that are set.
432 <tag><tt>protocolVersion </tt><em>integer</em></tag>
433 Protocol version: 2, 3, etc.
434 <tag><tt>userInformationField </tt><em>string</em></tag>
435 User information field.
440 Consider a client with the ability to access multiple targets.
442 We define a list of targets that we wish to connect to.
443 Each item in the list describes the target parameters with
444 the following four components: association-name, comstack-type,
445 protocol-type and a hostname.
447 The list for the two targets: ISO/SR target DANBIB and TCP/Z39.50
448 target Data Research, will be defined as:
450 set targetList { {danbib mosi SR 0103/find2.denet.dk:4500}
451 {drs tcpip Z39 dranet.dra.com} }
454 The Tcl code below defines, connect and initialize the
455 targets in <tt/targetList/:
458 foreach target $targetList {
459 set assoc [lindex $target 0]
461 $assoc comstack [lindex $target 1]
462 $assoc protocol [lindex $target 2]
463 $assoc failback [list fail-response $assoc]
464 $assoc callback [list connect-response $assoc]
465 $assoc connect [lindex $target 3]
468 proc connect-response {assoc} {
469 $assoc callback [list init-response $assoc]
473 proc fail-response {assoc} {
474 puts "$assoc closed connection or protocol error"
477 proc init-response {assoc} {
478 if {[$assoc initResult]} {
479 puts "$assoc initialized ok"
481 puts "$assoc didn't initialize"
486 <tt/target/ is bound to each item in the list of targets.
487 The <tt/assoc/ is set to the ir object name.
488 Then, the comstack, protocol and failback are set for the <tt/assoc/ object.
489 The ir object name is argument to the <tt/fail-response/ and
490 <tt/connect-response/ routines.
491 Note the use of the Tcl <tt/list/ command which
492 is necessary here because the argument contains variables
493 (<tt/assoc/) that should be substituted before the handler is defined.
494 After the connect operation, the <tt/init-response/ handler
495 is defined in much the same way as the failback handler.
496 And, finally, an init request is executed.
503 To terminate the connection the <tt/disconnect/ action should be used.
504 This action has no parameters.
505 Another connection may be established by a new <tt/connect/ action on
511 This section covers the queries used by <sf/IrTcl/, and how searches and
512 presents are handled.
514 A search operation and a result set is described by the ir set object.
515 The ir set object is defined by the <tt/ir-set/ command which
516 has two parameters. The first is the name of the new ir set object, and
517 the second, which is optional, is the name of an assocation — an ir
518 object. The second argument is required if the ir set object should be able
519 to perform searches and presents. However, it is not required if
520 only ``local'' operations is done with the ir set object.
522 When the ir set object is created a number of settings are inherited
523 from the ir object, such as the selected databass, query type,
524 etc. Thus, the ir object contains what we could call default
530 Search requests are sent by the <tt/search/ action which
531 takes a query as parameter. There are two types of queries,
532 RPN and CCL, controlled by the setting <tt/queryType/.
533 A string representation for the query is used in <sf/IrTcl/ since
534 Tcl has reasonably powerful string manipulaton capabilities.
535 The RPN query used in <sf/IrTcl/ is the prefix query notation also used in
536 the <bf/YAZ/ test client.
538 The CCL query is an uninterpreted octet-string which is parsed by the target.
539 We refer to the standard: ISO 8777. Note that only a few targets
540 actually support the CCL query and the interpretation of
541 the standard may vary.
543 The prefix query notation (which is converted to RPN) offer a few
547 <tag><tt>@attr </tt><em>list op</em></tag>
548 The attributes in list are applied to op
549 <tag><tt>@and </tt><em>op1 op2</em></tag>
550 Boolean <em/and/ on op1 and op2
551 <tag><tt>@or </tt><em>op1 op2</em></tag>
552 Boolean <em/or/ on op1 and op2
553 <tag><tt>@not </tt><em>op1 op2</em></tag>
554 Boolean <em/not/ on op1 and op2
555 <tag><tt>@prox </tt><em>list op1 op2</em></tag>
556 Proximity operation on op1 and op2. Not implemented yet.
557 <tag><tt>@set </tt><em>name</em></tag>
561 It is simple to build RPN queries in <sf/IrTcl/. Search terms
562 are sequences of characters, as in:
567 Boolean operators use the prefix notation (instead of the suffix/RPN),
570 @and science technology
573 Search terms may be associated with attributes. These
574 attributes are indicated by the <tt/@attr/ operator.
575 Assuming the bib-1 attribute set, we can set the use-attribute
576 (type is 1) to title (value is 4):
582 Also, it is possible to apply attributes to a range of search terms.
583 In the query below, both search terms have use=title but the <tt/tech/
584 term is right truncated:
587 @attr 1=4 @and @attr 5=1 tech beta
593 The settings that affect the search are listed below:
596 <tag><tt>databaseNames </tt><em>list</em></tag>
598 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
599 small set upper bound. Default 0.
600 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
601 large set lower bound. Default 2.
602 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
603 medium set present number. Default 0.
604 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>
606 <tag><tt>setName </tt><em>string</em></tag>
608 <tag><tt>queryType rpn|ccl</tt></tag>
609 query type-1 or query type-2
610 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
611 preferred record syntax — UNIMARC, USMARC, etc.
612 <tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
613 small-set-element-set names. Not implemented yet.
614 <tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
615 medium-set-element-set names. Not implemented yet.
616 <tag><tt>searchResponse </tt><em>list</em></tag>
617 Search-response Tcl script. Not implemented yet. Use <tt>callback</tt>
619 <tag><tt>callback </tt><em>list</em></tag>
620 General response Tcl script. Only used if searchResponse is not specified
623 Setting the <tt/databaseNames/ is mandatory. All other settings
624 have reasonable defaults.
625 The search-response handler, specified by the <tt/callback/ - or
626 the <tt/searchResponse/ setting,
627 should read some of the settings shown below:
630 <tag><tt>searchStatus </tt><em>boolean</em></tag>
631 search-status. True if search operation was successful; false
633 <tag><tt>responseStatus </tt><em>list</em></tag>
634 response status information.
635 <tag><tt>resultCount </tt><em>integer</em></tag>
637 <tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
638 number of records returned.
641 The <tt/responseStatus/ signals one of three conditions which
642 is indicated by the value of the first item in the list:
645 <tag><tt>NSD</tt></tag> indicates that the target has returned one or
646 more non-surrogate diagnostic messages. The <tt/NSD/ item is followed by
647 a list with all non-surrogate messages. Each non-surrogate message consists
648 of three items. The first item of the three items is the error
649 code (integer); the next item is a textual representation of the error
650 code in plain english; the third item is additional information, possibly
651 empty if no additional information was returned by the target.
653 <tag><tt>DBOSD</tt></tag> indicates a successful operation where the
654 target has returned one or more records. Each record may be
655 either a database record or a surrogate diagnostic.
657 <tag><tt>OK</tt></tag> indicates a successful operation — no records are
658 returned from the target.
663 We continue with the multiple-targets example.
664 The <tt/init-response/ procedure will attempt to make searches:
667 proc init-response {assoc} {
668 puts "$assoc connected"
669 ir-set ${assoc}.1 $assoc
670 $assoc.1 queryType rpn
671 $assoc.1 databaseNames base-a base-b
672 $assoc.1 callback [list search-response $assoc ${assoc}.1]
673 $assoc.1 search "@attr 1=4 @and @attr 5=1 tech beta"
677 An ir set object is defined and the
678 ir object is told about the name of ir object.
679 The ir set object use the name of the ir object as prefix.
681 Then, the query-type is defined to be RPN, i.e. we will
682 use the prefix query notation later on.
684 Two databases, <tt/base-a/ and <tt/base-b/, are selected.
686 A <tt/search-response/ handler is defined with the
687 ir object and the ir-set object as parameters and
688 the search is executed.
690 The first part of the <tt/search-response/ looks like:
692 proc search-response {assoc rset} {
693 set status [$rset responseStatus]
694 set type [lindex $status 0]
695 if {$type == "NSD"} {
696 set code [lindex $status 1]
697 set msg [lindex $status 2]
698 set addinfo [lindex $status 3]
699 puts "NSD $code: $msg: $addinfo"
702 set hits [$rset resultCount]
703 if {$type == "DBOSD"} {
704 set ret [$rset numberOfRecordsReturned]
709 The response status is stored in variable <tt/status/ and
710 the first element indicates the condition.
711 If non-surrogate diagnostics are returned they are displayed.
712 Otherwise, the search was a success and the number of hits
713 is read. Finally, it is tested whether the search response
714 returned records (database or diagnostic).
716 Note that we actually didn't inspect the search status (setting
717 <tt/searchStatus/) to determine whether the search was successful or not,
718 because the standard specifies that one or more non-surrogate
719 diagnostics should be returned by the target in case of errors.
723 If one or more records are returned from the target they
724 will be stored in the result set object.
725 In the case in which the search response contains records, it is
726 very similar to the present response case. Therefore, some settings
727 are common to both situations.
732 The <tt/present/ action sends a present request. The <tt/present/ is
733 followed by two optional integers. The first integer is the
734 result-set starting position — defaults to 1. The second integer
735 is the number of records requested — defaults to 10.
736 The settings which could be modified before a <tt/present/
740 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
741 preferred record syntax — UNIMARC, USMARC, etc.
742 <tag><tt>elementSetElementSetNames </tt><em>string</em></tag>
744 <tag><tt>presentResponse </tt><em>list</em></tag>
745 Present-response Tcl script. Not implemented yet. Use <tt>callback</tt>
747 <tag><tt>callback </tt><em>list</em></tag>
748 General response Tcl script. Only used if presentResponse is not specified
751 The present-response handler should inspect the settings
752 shown in table below.
753 Note that <tt/responseStatus/ and <tt/numberOfRecordsReturned/
754 settings were also used in the search-response case.
756 As in the search response case, records returned from the
757 target are stored in the result set object.
760 <tag><tt>presentStatus </tt><em>boolean</em></tag>
762 <tag><tt>responseStatus </tt><em>list</em></tag>
763 Response status information
764 <tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
765 number of records returned
766 <tag><tt>nextResultSetPosition </tt><em>integer</em></tag>
767 next result set position
773 Search responses and present responses may result in
774 one or more records stored in the ir set object if
775 the <tt/responseStatus/ setting indicates database or
776 surrogate diagnostics (<tt/DBOSD/). The individual
777 records, indexed by an integer position, should be
780 The action <tt/type/ followed by an integer returns information
781 about a given position in an ir set. There are three possiblities:
784 <tag><tt/SD/</tag> The item is a surrogate diagnostic record.
785 <tag><tt/DB/</tag> The item is a database record.
786 <tag><em/empty/</tag> There is no record at the specified position.
789 To handle the first case, surrogate diagnostic record, the
790 <tt/Diag/ action should be used. It returns three
791 items: error code (integer), text representation in plain english
792 (string), and additional information (string, possibly empty).
794 In the second case, database record, the <tt/recordType/ action should
795 be used. It returns the record type at the given position.
796 Some record types are:
813 We continue our search-response example. In the case,
814 <tt/DBOSD/, we should inspect the result set items.
815 Recall that the ir set name was passed to the
816 search-response handler as argument <tt/rset/.
819 if {$type == "DBOSD"} {
820 set ret [$rset numberOfRecordsReturned]
821 for {set i 1} {$i<=$ret} {incr i} {
822 set itype [$rset type $i]
823 if {$itype == "SD"} {
824 set diag [$rset Diag $i]
825 set code [lindex $diag 0]
826 set msg [lindex $diag 1]
827 set addinfo [lindex $diag 2]
828 puts "$i: NSD $code: $msg: $addinfo"
829 } elseif {$itype == "DB"} {
830 set rtype [$rset recordType $i]
831 puts "$i: type is $rtype"
836 Each item in the result set is examined.
837 If an item is a diagnostic message it is displayed; otherwise
838 if it's a database record its type is displayed.
845 In the case, where there is a MARC record at a given position we
846 want to display it somehow. The action <tt/getMarc/ is what we need.
847 The <tt/getMarc/ is followed by a position integer and the type of
848 extraction we want to make: <tt/field/ or <tt/line/.
850 The <tt/field/ and <tt/line/ type are followed by three
851 parameters that serve as extraction masks.
852 They are called tag, indicator and field.
853 If the mask matches a tag/indicator/field of a record the information
854 is extracted. Two characters have special meaning in masks: the
855 dot (any character) and star (any number of any character).
857 The <tt/field/ type returns one or more lists of field information
858 that matches the mask specification. Only the content of fields
861 The <tt/line/ type, on the other hand, returns a Tcl list that
862 completely describe the layout of the MARC record — including
865 The <tt/field/ type is sufficient and efficient in the case, where only a
866 small number of fields are extracted, and in the case where no
867 further processing (in Tcl) is necessary.
869 However, if the MARC record is to be edited or altered in any way, the
870 <tt/line/ extraction is more powerful — only limited by the Tcl
875 Consider the record below:
880 008 910710c19910701nju 00010 eng
884 100 10 $a Jack Collins
885 245 10 $a How to program a computer
891 Assuming this record is at position 1 in ir-set <tt/z.1/, we
892 might extract the title-field (245 * a), with the following command:
894 z.1 getMarc 1 field 245 * a
899 {How to program a computer}
902 Using the <tt/line/ instead of <tt/field/ gives:
904 {245 {10} {{a {How to program a computer}} }}
907 If we wish to extract the whole record as a list, we use:
909 z.1 getMarc 1 line * * *
914 {001 {} {{{} { 11224466 }} }}
916 {005 {} {{{} 00000000000000.0} }}
917 {008 {} {{{} {910710c19910701nju 00010 eng }} }}
918 {010 { } {{a { 11224466 }} }}
919 {040 { } {{a DLC} {c DLC} }}
920 {050 {00} {{a 123-xyz} }}
921 {100 {10} {{a {Jack Collins}} }}
922 {245 {10} {{a {How to program a computer}} }}
923 {260 {1 } {{a Penguin} }}
924 {263 { } {{a 8710} }}
925 {300 { } {{a {p. cm.}} }}
932 This example demonstrates how Tcl can be used to examine
933 a MARC record in the list notation.
935 The procedure <tt/extract-format/ makes an extraction of
936 fields in a MARC record based on a number of masks.
937 There are 5 parameters, <tt/r/: a
938 record in list notation, <tt/tag/: regular expression to
939 match the record tags, <tt/ind/: regular expression to
940 match indicators, <tt/field/: regular expression to
941 match fields, and finally <tt/text/: regular expression to
942 match the content of a field.
945 proc extract-format {r tag ind field text} {
947 if {[regexp $tag [lindex $line 0]] && \
948 [regexp $ind [lindex $line 1]]} {
949 foreach f [lindex $line 2] {
950 if {[regexp $field [lindex $f 0]]} {
951 if {[regexp $text [lindex $f 1]]} {
961 To match <tt/comput/ followed by any number of character(s) in the
962 245 fields in the record from the previous example, we could use:
964 set r [z.1 getMarc 1 line * * *]
966 extract-format $r 245 .. . comput
970 How to program a computer
975 The <tt/putMarc/ action does the opposite of <tt/getMarc/. It
976 copies a record in Tcl list notation to a ir set object and is
977 needed if a result-set must be updated by a Tcl modified (user-edited)
983 In <sf/IrTcl/ a SUTRS record is treated as one single string. To retrieve
984 a SUTRS record use the <tt>getSutrs</tt> followed by an index.
989 To perform scan, a scan object must be created by the <tt>ir-scan</tt>
990 command. This command has two arguments - name of the scan object and
991 name of the ir object. Basically, the scan object, provides one <tt>scan</tt>
992 action which sends a scan request to the target. The <tt>action</tt>
993 is followed by a string describing starting point of the term list. The
994 format used is a simple subset of the query used in search requests. Only
995 <tt>@attr</tt> specifications and simple terms are allowed.
996 The settings that affect the scan are:
999 <tag><tt>stepSize </tt><em>integer</em></tag>
1000 Step size. Default is 0.
1001 <tag><tt>numberOfTermsRequested </tt><em>integer</em></tag>
1002 Number of terms requested. Default is 20.
1003 <tag><tt>preferredPositionInResponse </tt><em>integer</em></tag>
1004 Preferred position in response. Default is 1.
1005 <tag><tt>databaseNames </tt><em>list</em></tag>
1006 Database names. Note that this setting is not (yet) supported for
1007 the scan object. You must set this for the ir object instead.
1008 <tag><tt>callback </tt><em>list</em></tag>
1009 General response Tcl script. This setting is not (yet) supported for
1010 the scan object. You must set this for the ir object instead.
1013 The scan object normally holds one or more scan line entries upon
1014 successful completion. The table below summarizes the settings
1015 that should be used in a response handler.
1018 <tag><tt>scanStatus</tt></tag>
1019 Scan status. An integer between 0 and 6.
1020 <tag><tt>numberOfTermsReturned </tt><em>integer</em></tag>
1021 Number of terms returned.
1022 <tag><tt>positionOfTerm</tt></tag>
1023 An integer describing the position of term.
1024 <tag><tt>scanLine </tt> <em>integer</em></tag>
1025 This function returns information about a given scan line (entry) at a given
1026 index specified by the integer. The first scan line is numbered zero;
1027 the second 1 and so on. A list is returned by the <tt>scanLine</tt>
1028 setting. The first element is <tt>T</tt> if the scan line
1029 is a normal term and <tt>SD</tt> if the scan line is a surrogate
1030 diagnostic. In the first case (normal) the scan term is second element
1031 in the list and the number of occurences is the third element.
1032 In the other case (surrogate diagnostic), the second element
1033 is the diagnostic code, the third a text representation of the error
1034 code and the fourth element is additional information.
1039 We will scan for the terms after <tt>science</tt> in the Title index.
1040 We will assume that an ir object called <tt>z-assoc</tt> has already
1044 z-assoc callback {scan-response}
1045 ir-scan z-scan z-assoc
1046 z-scan scan "@attr 1=4 science"
1048 proc scan-response {} {
1049 set status [z-scan status]
1051 set no [z-scan numberOfTermsReturned]
1052 for {set i 0} {$i < $no} {incr i} {
1053 set line [z-scan scanLine $i]
1054 set type [lindex $line 0]
1056 puts [lindex $line 1]
1057 } elseif {$type == "SD"} {
1058 puts [lindex $line 1]
1069 Copyright © 1995, Index Data.
1071 Permission to use, copy, modify, distribute, and sell this software and
1072 its documentation, in whole or in part, for any purpose, is hereby granted,
1075 1. This copyright and permission notice appear in all copies of the
1076 software and its documentation. Notices of copyright or attribution
1077 which appear at the beginning of any file must remain unchanged.
1079 2. The names of Index Data or the individual authors may not be used to
1080 endorse or promote products derived from this software without specific
1081 prior written permission.
1083 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
1084 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
1085 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1086 IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
1087 INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
1088 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
1089 NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
1090 LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
1093 <sect>About Index Data
1096 Index Data is a consulting and software-development enterprise that
1097 specialises in library and information management systems. Our
1098 interests and expertise span a broad range of related fields, and one
1099 of our primary, long-term objectives is the development of a powerful
1100 information management
1101 system with open network interfaces and hypermedia capabilities.
1103 We make this software available free of charge, on a fairly unrestrictive
1104 license; as a service to the networking community, and to further the
1105 development of quality software for open network communication.
1107 We'll be happy to answer questions about the software, and about ourselves
1113 2200 København N&nl
1119 Phone: +45 3536 3672
1121 Email: info@index.ping.dk
1129 <tag>1 Ousterhout, John K.:</tag>
1130 Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
1131 0-201-63337-X). Source and documentation
1132 can be found in <tt>URL:ftp://ftp.cs.berkeley.edu/pub/tcl</tt>
1134 <tag>2 Furniss, Peter:</tag>
1135 RFC 1698: Octet Sequences for Upper-Layer OSI to Support
1136 Basic Communications Applications.