1 <!doctype linuxdoc system>
4 $Id: ir-tcl.sgml,v 1.7 1995-06-19 08:09:35 adam Exp $
8 <title>IrTcl User's Guide and Reference
9 <author>Index Data, <tt/info@index.ping.dk/
10 <date>$Revision: 1.7 $
12 This document describes IrTcl &mdash 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 &mdash 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 &mdash useful for
43 <item> A system which operates within the Tk environment which
44 makes it very easy to implement GUI clients.
50 Basically, <sf/IrTcl/ is a set of commands introduced to Tcl.
51 When extending Tcl there are two approaches: action-oriented commands
52 and object-oriented commands.
54 Action-oriented commands manipulate
55 Tcl variables and each command introduces only one action.
56 The string manipulation commands in Tcl are action oriented.
58 Object-oriented commands are added for every declared
59 variable (object). Object-oriented commands usually provide a set of
60 actions (methods) to manipulate the object.
61 The widgets in Tk (X objects) are examples of the object-oriented style.
63 <sf/IrTcl/ commands are object-oriented. The main reason
64 for this is that the data structures involved in the IR protocol
65 are not easily represented by Tcl data structures.
66 Also, the <sf/IrTcl/ objects tend to exist for a relativly long time.
67 Note that although we use the term object-oriented commands, this
68 does not mean that the programming style is strictly object-oriented. For
69 example, there is such no such thing as inheritance.
71 We are now ready to present the three commands introduced to Tcl by
75 <tag/ir/ The ir object represents a connection to a target. More
76 precisely it describes a Z-association.
77 <tag/ir-set/ The ir-set describes a result set, which is
78 conceptually a collection of records returned by the target.
79 The ir-set object may retrieve records from a target by means of
80 the ir object; it may read/write records from/to a local file or it may be
81 updated with a user-edited record.
82 <tag/ir-scan/ The scan object represents a list of scan lines
83 retrieved from a target.
88 To create a new IR object called <tt/z-assoc/ write:
95 Each object provides a set of <em/settings/ which may either be
96 readable, writeable of both. All settings immediately follow
97 the name of the object. If a value is present the setting
102 We wish to set the preferred-message-size to 18000 on the
106 z-assoc preferredMessageSize 18000
109 To read the current value of preferred-message-size use:
112 z-assoc preferredMessageSize
116 One important category consists of settings is those that relate to the
117 event-driven model. When <sf/IrTcl/ receives responses from the target, i.e.
118 init responses, search responses, etc., a <em/callback/ routine
119 is called. Callback routines are represented in Tcl as
120 a list, which is re-interpreted prior to invocation.
121 The method is similar to the one used in Tk to capture X events.
123 For each SR/Z39.50 request there is a corresponding object action. The most
124 important actions are:
126 <tag/connect/ Establishes connection with a target
127 <tag/init/ Sends an initialize request.
128 <tag/search/ Sends a search request.
129 <tag/present/ Sends a present request.
130 <tag/scan/ Sends a scan request.
135 This example shows a complete connect - init - search - present scenario.
137 First an IR object, called <tt/z/, is created.
138 Also a result set <tt/z.1/ is introduced by the <tt/ir-set/
139 and it is specified that the result set uses <tt/z/ as its association.
141 The setting <tt/databaseNames/ is set to the
142 database <tt/books/ to which the following searches are directed.
143 A callback is then defined and a connection is established to
144 <tt/fake.com/ by the <tt/connect/ action.
145 If the connect succeeds the <tt/connect-response/ is called.
147 In the Tcl procedure, <tt/connect-response/, a callback is defined
148 <em/before/ the init request is executed.
149 The Tcl procedure <tt/init-response/ is called when a
150 init response is returned from the target.
152 The <tt/init-response/ procedure sets up a <tt/search-response/
153 callback handler and sends a search-request by using a query which
154 consists of a single word <tt/science/.
156 When the <tt/search-response/ procedure is called it defines
157 a variable <tt/hits/ and sets it to the value of the setting
158 <tt/resultCount/. If <tt/hits/ is positive a present-request is
159 sent &mdash asking for 5 records from position 1.
161 Finally, a present response is received and the number of records
162 returned is stored in the variable <tt/ret/.
167 z databaseNames books
168 z callback {connect-response}
171 proc connect-response {} {
172 z callback {init-response}
176 proc init-response {} {
177 z.1 callback {search-response}
181 proc search-response {} {
182 set hits [z.1 resultCount]
185 z.1 callback {present-response}
190 proc present-response {} {
191 set ret [z.1 numberOfRecordsReturned]
192 puts "$ret records returned"
197 The previous example program doesn't care about error conditions.
198 If errors occur in the program they will be trapped by the Tcl error
199 handler. This is not always appropriate. However, Tcl offers a
200 <tt/catch/ command to support error handling by the program itself.
205 The ir object describes an association with a target.
206 This section covers the connect-init-disconnect actions provided
208 An ir object is created by the <tt/ir/ command and the
209 created object enters a 'not connected' state, because it isn't
210 connected to a target yet.
215 A connection is established by the <tt/connect/ action which is
216 immediately followed by a hostname. Obviously, these settings should
217 be set <bf/before/ connecting.
218 The settings that affect the <tt/connect/ action are:
221 <tag><tt>comstack </tt><tt>mosi|tcpip</tt></tag>
223 <tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
224 Protocol type - ANSI/NISO Z39.50 or ISO SR.
225 <tag><tt>callback </tt><em>list</em></tag>
226 Tcl script called when the connection is established
227 <tag><tt>failback </tt><em>list</em></tag>
228 Fatal error Tcl script. Called on protocol errors or if target
232 If the connect is unsuccessful either the connect action itself
233 will return an error code or the failback handler is invoked.
238 If the connect operation succeeds the <tt/init/ action should be used.
239 The init related settings are:
242 <tag><tt>preferredMessageSize </tt><em>integer</em></tag>
243 Preferred-message-size. Default value is 30000.
244 <tag><tt>maximumRecordSize </tt><em>integer</em></tag>
245 Maximum-record-size. Default value is 30000.
246 <tag><tt>idAuthentication </tt><em>string</em> ...</tag>
247 Id-authentication. There are three forms. If any empty is
248 given, the Id-authentication is not used. If one non-empty string
249 is given, the 'open' authentication is used. If three strings are
250 specified, the version 'id-pass' authentication (version 3 only)
251 is used in which case the first string is groupId; the second string
252 is userId and the third string is password.
253 <tag><tt>implementationName </tt><em>string</em></tag>
254 Implementation-name of origin system.
255 <tag><tt>implementationId</tt></tag>
256 Implementation-id of origin system. This setting is read-only.
257 <tag><tt>options </tt><em>list</em></tag>
258 Options to be negotiated in the init service. The list contains
259 the options that are set. These are <tt>search</tt>, <tt>present</tt>,
260 <tt>delSet</tt>, <tt>resourceReport</tt>, <tt>triggerResourceCtrl</tt>,
261 <tt>resourceCtrl</tt>, <tt>accessCtrl</tt>, <tt>scan</tt>, <tt>sort</tt>,
262 <tt>extendedServices</tt>, <tt>level-1Segmentation</tt>,
263 <tt>level-2Segmentation</tt>, <tt>concurrentOperations</tt> and
264 <tt>namedResultSets</tt>. Currently the default options are:
265 <tt>search</tt>, <tt>present</tt>, <tt>scan</tt> and
266 <tt>namedResultSets</tt>. The options setting is set to its default
267 value when an ir object is created and when a disconnect is performed.
268 <tag><tt>protocolVersion </tt><em>integer</em></tag>
269 Protocol version: 2, 3, etc.
270 <tag><tt>initResponse </tt><em>list</em></tag>
271 Init-response Tcl script. Note: not implemented - use <tt>callback</tt>
273 <tag><tt>callback </tt><em>list</em></tag>
274 General response Tcl script. Only used if <tt>initResponse</tt>
278 The init-response handler should inspect some of the settings shown
282 <tag><tt>initResult </tt><em>boolean</em></tag>
283 Init response status. True if init operation was successful;
285 <tag><tt>preferredMessageSize </tt><em>integer</em></tag>
286 Preferred-message-size.
287 <tag><tt>maximumRecordSize </tt><em>integer</em></tag>
289 <tag><tt>targetImplementationName </tt><em>string</em></tag>
290 Implementation-name of target system.
291 <tag><tt>targetImplementationId </tt><em>string</em></tag>
292 Implementation-id of target system.
293 <tag><tt>targetImplementationVersion </tt><em>string</em></tag>
294 Implementation-version of target system.
295 <tag><tt>options </tt><em>list</em></tag>
296 Options negotiated after init. The list contains the options that are set.
297 <tag><tt>protocolVersion </tt><em>integer</em></tag>
298 Protocol version: 2, 3, etc.
299 <tag><tt>userInformationField </tt><em>string</em></tag>
300 User information field
305 Consider a client with the ability to access multiple targets.
307 We define a list of targets that we wish to connect to.
308 Each item in the list describes the target parameters with
309 the following four components: association-name, comstack-type,
310 protocol-type and a hostname.
312 The list for the two targets: ISO/SR target DANBIB and TCP/Z39.50
313 target Data Research, will be defined as:
315 set targetList { {danbib mosi SR 0103/find2.denet.dk:4500}
316 {drs tcpip Z39 dranet.dra.com} }
319 The Tcl code below defines, connect and initialize the
320 targets in <tt/targetList/:
323 \foreach target $targetList {
324 set assoc [lindex $target 0]
326 $assoc comstack [lindex $target 1]
327 $assoc protocol [lindex $target 2]
328 $assoc failback [list fail-response $assoc]
329 $assoc callback [list connect-response $assoc]
330 $assoc connect [lindex $target 3]
333 proc connect-response {assoc} {
334 $assoc callback [list init-response $assoc]
338 proc fail-response {assoc} {
339 puts "$assoc closed connection or protocol error"
342 proc init-response {assoc} {
343 if {[$assoc initResult]} {
344 puts "$assoc initialized ok"
346 puts "$assoc didn't initialize"
351 <tt/target/ is bound to each item in the list of targets.
352 The <tt/assoc/ is set to the ir object name.
353 Then, the comstack, protocol and failback are set for the <tt/assoc/ object.
354 The ir object name is argument to the <tt/fail-response/ and
355 <tt/connect-response/ routines.
356 Note the use of the Tcl <tt/list/ command which
357 is necessary here because the argument contains variables
358 (<tt/assoc/) that should be substituted before the handler is defined.
359 After the connect operation, the <tt/init-response/ handler
360 is defined in much the same way as the failback handler.
361 And, finally, an init request is executed.
367 To terminate the connection the <tt/disconnect/ action should be used.
368 This action has no parameters.
369 Another connection may be established by a new <tt/connect/ action on
375 This section covers the queries used by <sf/IrTcl/, and how searches and
376 presents are handled.
378 A search operation and a result set is described by the ir set object.
379 The ir set object is defined by the <tt/ir-set/ command which
380 has two parameters. The first is the name of the new ir set object, and
381 the second, which is optional, is the name of an assocation &mdash an ir
382 object. The second argument is required if the ir set object should be able
383 to perform searches and presents. However, it is not required if
384 only ``local'' operations is done with the ir set object.
386 When the ir set object is created a number of settings are inherited
387 from the ir object, such as the selected databass, query type,
388 etc. Thus, the ir object contains what we could call default
394 Search requests are sent by the <tt/search/ action which
395 takes a query as parameter. There are two types of queries,
396 RPN and CCL, controlled by the setting <tt/queryType/.
397 A string representation for the query is used in <sf/IrTcl/ since
398 Tcl has reasonably powerful string manipulaton capabilities.
399 The RPN query used in <sf/IrTcl/ is the prefix query notation also used in
400 the <bf/YAZ/ test client.
402 The CCL query is an uninterpreted octet-string which is parsed by the target.
403 We refer to the standard: ISO 8777. Note that only a few targets
404 actually support the CCL query and the interpretation of
405 the standard may vary.
407 The prefix query notation (which is converted to RPN) offer a few
411 <tag><tt>@attr </tt><em>list op</em></tag>
412 The attributes in list are applied to op
413 <tag><tt>@and </tt><em>op1 op2</em></tag>
414 Boolean <em/and/ on op1 and op2
415 <tag><tt>@or </tt><em>op1 op2</em></tag>
416 Boolean <em/or/ on op1 and op2
417 <tag><tt>@not </tt><em>op1 op2</em></tag>
418 Boolean <em/not/ on op1 and op2
419 <tag><tt>@prox </tt><em>list op1 op2</em></tag>
420 Proximity operation on op1 and op2. Not implemented yet.
421 <tag><tt>@set </tt><em>name</em></tag>
425 It is simple to build RPN queries in <sf/IrTcl/. Search terms
426 are sequences of characters, as in:
431 Boolean operators use the prefix notation (instead of the suffix/RPN),
434 @and science technology
437 Search terms may be associated with attributes. These
438 attributes are indicated by the <tt/@attr/ operator.
439 Assuming the bib-1 attribute set, we can set the use-attribute
440 (type is 1) to title (value is 4):
446 Also, it is possible to apply attributes to a range of search terms.
447 In the query below, both search terms have use=title but the <tt/tech/
448 term is right truncated:
451 @attr 1=4 @and @attr 5=1 tech beta
457 The settings that affect the search are listed below:
460 <tag><tt>databaseNames </tt><em>list</em></tag>
462 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
463 small set upper bound. Default 0.
464 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
465 large set lower bound. Default 2.
466 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
467 medium set present number. Default 0.
468 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>
470 <tag><tt>setName </tt><em>string</em></tag>
472 <tag><tt>queryType rpn|ccl</tt></tag>
473 query type-1 or query type-2
474 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
475 preferred record syntax &mdash UNIMARC, USMARC, etc.
476 <tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
477 small-set-element-set names. Not implemented yet.
478 <tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
479 medium-set-element-set names. Not implemented yet.
480 <tag><tt>searchResponse </tt><em>list</em></tag>
481 Search-response Tcl script. Not implemented yet. Use <tt>callback</tt>
483 <tag><tt>callback </tt><em>list</em></tag>
484 General response Tcl script. Only used if searchResponse is not specified
487 Setting the <tt/databaseNames/ is mandatory. All other settings
488 have reasonable defaults.
489 The search-response handler, specified by the <tt/callback/ - or
490 the <tt/searchResponse/ setting,
491 should read some of the settings shown below:
494 <tag><tt>searchStatus </tt><em>boolean</em></tag>
495 search-status. True if search operation was successful; false
497 <tag><tt>responseStatus </tt><em>list</em></tag>
498 response status information.
499 <tag><tt>resultCount </tt><em>integer</em></tag>
501 <tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
502 number of records returned.
505 The <tt/responseStatus/ signals one of three conditions which
506 is indicated by the value of the first item in the list:
509 <tag><tt>NSD</tt></tag> indicates that the target has returned one or
510 more non-surrogate diagnostic messages. The <tt/NSD/ item is followed by
511 a list with all non-surrogate messages. Each non-surrogate message consists
512 of three items. The first item of the three items is the error
513 code (integer); the next item is a textual representation of the error
514 code in plain english; the third item is additional information, possibly
515 empty if no additional information was returned by the target.
517 <tag><tt>DBOSD</tt></tag> indicates a successful operation where the
518 target has returned one or more records. Each record may be
519 either a database record or a surrogate diagnostic.
521 <tag><tt>OK</tt></tag> indicates a successful operation &mdash no records are
522 returned from the target.
527 We continue with the multiple-targets example.
528 The <tt/init-response/ procedure will attempt to make searches:
531 proc init-response {assoc} {
532 puts "$assoc connected"
533 ir-set ${assoc}.1 $assoc
534 $assoc.1 queryType rpn
535 $assoc.1 databaseNames base-a base-b
536 $assoc.1 callback [list search-response $assoc ${assoc}.1]
537 $assoc.1 search "@attr 1=4 @and @attr 5=1 tech beta"
541 An ir set object is defined and the
542 ir object is told about the name of ir object.
543 The ir set object use the name of the ir object as prefix.
545 Then, the query-type is defined to be RPN, i.e. we will
546 use the prefix query notation later on.
548 Two databases, <tt/base-a/ and <tt/base-b/, are selected.
550 A <tt/search-response/ handler is defined with the
551 ir object and the ir-set object as parameters and
552 the search is executed.
554 The first part of the <tt/search-response/ looks like:
556 proc search-response {assoc rset} {
557 set status [$rset responseStatus]
558 set type [lindex $status 0]
559 if {$type == "NSD"} {
560 set code [lindex $status 1]
561 set msg [lindex $status 2]
562 set addinfo [lindex $status 3]
563 puts "NSD $code: $msg: $addinfo"
566 set hits [$rset resultCount]
567 if {$type == "DBOSD"} {
568 set ret [$rset numberOfRecordsReturned]
573 The response status is stored in variable <tt/status/ and
574 the first element indicates the condition.
575 If non-surrogate diagnostics are returned they are displayed.
576 Otherwise, the search was a success and the number of hits
577 is read. Finally, it is tested whether the search response
578 returned records (database or diagnostic).
580 Note that we actually didn't inspect the search status (setting
581 <tt/searchStatus/) to determine whether the search was successful or not,
582 because the standard specifies that one or more non-surrogate
583 diagnostics should be returned by the target in case of errors.
586 If one or more records are returned from the target they
587 will be stored in the result set object.
588 In the case in which the search response contains records, it is
589 very similar to the present response case. Therefore, some settings
590 are common to both situations.
595 The <tt/present/ action sends a present request. The <tt/present/ is
596 followed by two optional integers. The first integer is the
597 result-set starting position &mdash defaults to 1. The second integer
598 is the number of records requested &mdash defaults to 10.
599 The settings which could be modified before a <tt/present/
603 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
604 preferred record syntax &mdash UNIMARC, USMARC, etc.
605 <tag><tt>elementSetElementSetNames </tt><em>string</em></tag>
607 <tag><tt>presentResponse </tt><em>list</em></tag>
608 Present-response Tcl script. Not implemented yet. Use <tt>callback</tt>
610 <tag><tt>callback </tt><em>list</em></tag>
611 General response Tcl script. Only used if presentResponse is not specified
614 The present-response handler should inspect the settings
615 shown in table below.
616 Note that <tt/responseStatus/ and <tt/numberOfRecordsReturned/
617 settings were also used in the search-response case.
619 As in the search response case, records returned from the
620 target are stored in the result set object.
623 <tag><tt>presentStatus </tt><em>boolean</em></tag>
625 <tag><tt>responseStatus </tt><em>list</em></tag>
626 Response status information
627 <tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
628 number of records returned
629 <tag><tt>nextResultSetPosition </tt><em>integer</em></tag>
630 next result set position
636 Search responses and present responses may result in
637 one or more records stored in the ir set object if
638 the <tt/responseStatus/ setting indicates database or
639 surrogate diagnostics (<tt/DBOSD/). The individual
640 records, indexed by an integer position, should be
643 The action <tt/type/ followed by an integer returns information
644 about a given position in an ir set. There are three possiblities:
647 <tag><tt/SD/</tag> The item is a surrogate diagnostic record.
648 <tag><tt/DB/</tag> The item is a database record.
649 <tag><em/empty/</tag> There is no record at the specified position.
652 To handle the first case, surrogate diagnostic record, the
653 <tt/Diag/ action should be used. It returns three
654 items: error code (integer), text representation in plain english
655 (string), and additional information (string, possibly empty).
657 In the second case, database record, the <tt/recordType/ action should
658 be used. It returns the record type at the given position.
659 Some record types are:
676 We continue our search-response example. In the case,
677 <tt/DBOSD/, we should inspect the result set items.
678 Recall that the ir set name was passed to the
679 search-response handler as argument <tt/rset/.
682 if {$type == "DBOSD"} {
683 set ret [$rset numberOfRecordsReturned]
684 for {set i 1} {$i<=$ret} {incr i} {
685 set itype [$rset type $i]
686 if {$itype == "SD"} {
687 set diag [$rset Diag $i]
688 set code [lindex $diag 0]
689 set msg [lindex $diag 1]
690 set addinfo [lindex $diag 2]
691 puts "$i: NSD $code: $msg: $addinfo"
692 } elseif {$itype == "DB"} {
693 set rtype [$rset recordType $i]
694 puts "$i: type is $rtype"
699 Each item in the result set is examined.
700 If an item is a diagnostic message it is displayed; otherwise
701 if it's a database record its type is displayed.
707 In the case, where there is a MARC record at a given position we
708 want to display it somehow. The action <tt/getMarc/ is what we need.
709 The <tt/getMarc/ is followed by a position integer and the type of
710 extraction we want to make: <tt/field/ or <tt/line/.
712 The <tt/field/ and <tt/line/ type are followed by three
713 parameters that serve as extraction masks.
714 They are called tag, indicator and field.
715 If the mask matches a tag/indicator/field of a record the information
716 is extracted. Two characters have special meaning in masks: the
717 dot (any character) and star (any number of any character).
719 The <tt/field/ type returns one or more lists of field information
720 that matches the mask specification. Only the content of fields
723 The <tt/line/ type, on the other hand, returns a Tcl list that
724 completely describe the layout of the MARC record &mdash including
727 The <tt/field/ type is sufficient and efficient in the case, where only a
728 small number of fields are extracted, and in the case where no
729 further processing (in Tcl) is necessary.
731 However, if the MARC record is to be edited or altered in any way, the
732 <tt/line/ extraction is more powerful &mdash only limited by the Tcl
737 Consider the record below:
742 008 910710c19910701nju 00010 eng
746 100 10 $a Jack Collins
747 245 10 $a How to program a computer
753 Assuming this record is at position 1 in ir-set <tt/z.1/, we
754 might extract the title-field (245 * a), with the following command:
756 z.1 getMarc 1 field 245 * a
761 {How to program a computer}
764 Using the <tt/line/ instead of <tt/field/ gives:
766 {245 {10} {{a {How to program a computer}} }}
769 If we wish to extract the whole record as a list, we use:
771 z.1 getMarc 1 line * * *
776 {001 {} {{{} { 11224466 }} }}
778 {005 {} {{{} 00000000000000.0} }}
779 {008 {} {{{} {910710c19910701nju 00010 eng }} }}
780 {010 { } {{a { 11224466 }} }}
781 {040 { } {{a DLC} {c DLC} }}
782 {050 {00} {{a 123-xyz} }}
783 {100 {10} {{a {Jack Collins}} }}
784 {245 {10} {{a {How to program a computer}} }}
785 {260 {1 } {{a Penguin} }}
786 {263 { } {{a 8710} }}
787 {300 { } {{a {p. cm.}} }}
794 This example demonstrates how Tcl can be used to examine
795 a MARC record in the list notation.
797 The procedure <tt/extract-format/ makes an extraction of
798 fields in a MARC record based on a number of masks.
799 There are 5 parameters, <tt/r/: a
800 record in list notation, <tt/tag/: regular expression to
801 match the record tags, <tt/ind/: regular expression to
802 match indicators, <tt/field/: regular expression to
803 match fields, and finally <tt/text/: regular expression to
804 match the content of a field.
807 proc extract-format {r tag ind field text} {
809 if {[regexp $tag [lindex $line 0]] && \
810 [regexp $ind [lindex $line 1]]} {
811 foreach f [lindex $line 2] {
812 if {[regexp $field [lindex $f 0]]} {
813 if {[regexp $text [lindex $f 1]]} {
823 To match <tt/comput/ followed by any number of character(s) in the
824 245 fields in the record from the previous example, we could use:
826 set r [z.1 getMarc 1 line * * *]
828 extract-format $r 245 .. . comput
832 How to program a computer
837 The <tt/putMarc/ action does the opposite of <tt/getMarc/. It
838 copies a record in Tcl list notation to a ir set object and is
839 needed if a result-set must be updated by a Tcl modified (user-edited)
845 To perform scan, a scan object must be created by the <tt>ir-scan</tt>
846 command. This command has two arguments - name of the scan object and
847 name of the ir object. Basically, the scan object, provides one <tt>scan</tt>
848 action which sends a scan request to the target. The <tt>action</tt>
849 is followed by a string describing starting point of the term list. The
850 format used is a simple subset of the query used in search requests. Only
851 <tt>@attr</tt> specifications and simple terms are allowed.
852 The settings that affect the scan are:
855 <tag><tt>stepSize </tt><em>integer</em></tag>
856 Step size. Default is 0.
857 <tag><tt>numberOfTermsRequested </tt><em>integer</em></tag>
858 Number of terms requested. Default is 20.
859 <tag><tt>preferredPositionInResponse </tt><em>integer</em></tag>
860 Preferred position in response. Default is 1.
861 <tag><tt>databaseNames </tt><em>list</em></tag>
862 Database names. Note that this setting is not (yet) supported for
863 the scan object. You must set this for the ir object instead.
864 <tag><tt>callback </tt><em>list</em></tag>
865 General response Tcl script. This setting is not (yet) supported for
866 the scan object. You must set this for the ir object instead.
869 The scan object normally holds one or more scan line entries upon
870 successful completion. The table below summarizes the settings
871 that should be used in a response handler.
874 <tag><tt>scanStatus</tt></tag>
875 Scan status. An integer between 0 and 6.
876 <tag><tt>numberOfTermsReturned </tt><em>integer</em></tag>
877 Number of terms returned.
878 <tag><tt>positionOfTerm</tt></tag>
879 An integer describing the position of term.
880 <tag><tt>scanLine </tt> <em>integer</em></tag>
881 This function returns information about a given scan line at a given
882 index specified by the integer. The first scan line is numbered zero;
883 the second 1 and so on. A list is returned by the <tt>scanLine</tt>
884 setting. The first element is <tt>T</tt> if the scan entry
885 is a normal term and <tt>SD</tt> if the scan entry is a surrogate
886 diagnostic. In the first case (normal) the scan term is second element
887 in the list and the number of occurences is the third element.
888 In the other case (surrogate diagnostic), the second element
889 is the diagnostic code, the third a text representation of the error
890 code and the fourth element is additional information.
895 We will scan for the terms after <tt>science</tt> in the Title index.
896 We will assume that an ir object called <tt>z-assoc</tt> has already
900 z-assoc callback {scan-response}
901 ir-scan z-scan z-assoc
902 z-scan scan "@attr 1=4 science"
904 proc scan-response {} {
905 set status [z-scan status]
907 set no [z-scan numberOfTermsReturned]
908 for {set i 0} {$i < $no} {incr i} {
909 set line [z-scan scanLine $i]
910 set type [lindex $line 0]
912 puts [lindex $line 1]
913 } elseif {$type == "SD"} {
914 puts [lindex $line 1]
925 Copyright (c) 1995, Index Data.
927 Permission to use, copy, modify, distribute, and sell this software and
928 its documentation, in whole or in part, for any purpose, is hereby granted,
931 1. This copyright and permission notice appear in all copies of the
932 software and its documentation. Notices of copyright or attribution
933 which appear at the beginning of any file must remain unchanged.
935 2. The names of Index Data or the individual authors may not be used to
936 endorse or promote products derived from this software without specific
937 prior written permission.
939 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
940 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
941 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
942 IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
943 INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
944 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
945 NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
946 LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
949 <sect>About Index Data
952 Index Data is a consulting and software-development enterprise that
953 specialises in library and information management systems. Our
954 interests and expertise span a broad range of related fields, and one
955 of our primary, long-term objectives is the development of a powerful
956 information management
957 system with open network interfaces and hypermedia capabilities.
959 We make this software available free of charge, on a fairly unrestrictive
960 license; as a service to the networking community, and to further the
961 development of quality software for open network communication.
963 We'll be happy to answer questions about the software, and about ourselves
969 2200 København N&nl
977 Email: info@index.ping.dk
985 <tag>1 Ousterhout, John K.:</tag>
986 Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
987 0-201-63337-X). Source and documentation
988 can be found in <tt>URL:ftp://ftp.cs.berkeley.edu/pub/tcl</tt>
990 <tag>2 Furniss, Peter:</tag>
991 RFC 1698: Octet Sequences for Upper-Layer OSI to Support
992 Basic Communications Applications.