1 <!doctype linuxdoc system>
4 $Id: ir-tcl.sgml,v 1.8 1995-06-19 13:06:23 adam Exp $
8 <title>IrTcl User's Guide and Reference
9 <author>Index Data, <tt/info@index.ping.dk/
10 <date>$Revision: 1.8 $
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. A number of settings affect the
217 <tt/connect/ action. Obviously, these settings should be set
218 <bf/before/ connecting. The settings 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>implementationVersion</tt></tag>
258 Implementation-version of origin system. This settings is read-only.
259 <tag><tt>options </tt><em>list</em></tag>
260 Options to be negotiated in the init service. The list contains
261 the options that are set. Possible values are <tt>search</tt>,
262 <tt>present</tt>, <tt>delSet</tt>, <tt>resourceReport</tt>,
263 <tt>triggerResourceCtrl</tt>, <tt>resourceCtrl</tt>,
264 <tt>accessCtrl</tt>, <tt>scan</tt>, <tt>sort</tt>,
265 <tt>extendedServices</tt>, <tt>level-1Segmentation</tt>,
266 <tt>level-2Segmentation</tt>, <tt>concurrentOperations</tt> and
267 <tt>namedResultSets</tt>. Currently the default options are:
268 <tt>search</tt>, <tt>present</tt>, <tt>scan</tt> and
269 <tt>namedResultSets</tt>. The <tt>options</tt> setting is set to its default
270 value when an ir object is created and when a <tt>disconnect</tt>
272 <tag><tt>protocolVersion </tt><em>integer</em></tag>
273 Protocol version: 2, 3, etc. Default is 2.
274 <tag><tt>initResponse </tt><em>list</em></tag>
275 Init-response Tcl script. Note: not implemented - use <tt>callback</tt>
277 <tag><tt>callback </tt><em>list</em></tag>
278 General response Tcl script. Only used if <tt>initResponse</tt>
282 The init-response handler should inspect some of the settings shown
286 <tag><tt>initResult </tt><em>boolean</em></tag>
287 Init response status. True if init operation was successful;
289 <tag><tt>preferredMessageSize </tt><em>integer</em></tag>
290 Preferred-message-size.
291 <tag><tt>maximumRecordSize </tt><em>integer</em></tag>
293 <tag><tt>targetImplementationName </tt><em>string</em></tag>
294 Implementation-name of target system.
295 <tag><tt>targetImplementationId </tt><em>string</em></tag>
296 Implementation-id of target system.
297 <tag><tt>targetImplementationVersion </tt><em>string</em></tag>
298 Implementation-version of target system.
299 <tag><tt>options </tt><em>list</em></tag>
300 Options negotiated in init. The list contains the options that are set.
301 <tag><tt>protocolVersion </tt><em>integer</em></tag>
302 Protocol version: 2, 3, etc.
303 <tag><tt>userInformationField </tt><em>string</em></tag>
304 User information field.
309 Consider a client with the ability to access multiple targets.
311 We define a list of targets that we wish to connect to.
312 Each item in the list describes the target parameters with
313 the following four components: association-name, comstack-type,
314 protocol-type and a hostname.
316 The list for the two targets: ISO/SR target DANBIB and TCP/Z39.50
317 target Data Research, will be defined as:
319 set targetList { {danbib mosi SR 0103/find2.denet.dk:4500}
320 {drs tcpip Z39 dranet.dra.com} }
323 The Tcl code below defines, connect and initialize the
324 targets in <tt/targetList/:
327 foreach target $targetList {
328 set assoc [lindex $target 0]
330 $assoc comstack [lindex $target 1]
331 $assoc protocol [lindex $target 2]
332 $assoc failback [list fail-response $assoc]
333 $assoc callback [list connect-response $assoc]
334 $assoc connect [lindex $target 3]
337 proc connect-response {assoc} {
338 $assoc callback [list init-response $assoc]
342 proc fail-response {assoc} {
343 puts "$assoc closed connection or protocol error"
346 proc init-response {assoc} {
347 if {[$assoc initResult]} {
348 puts "$assoc initialized ok"
350 puts "$assoc didn't initialize"
355 <tt/target/ is bound to each item in the list of targets.
356 The <tt/assoc/ is set to the ir object name.
357 Then, the comstack, protocol and failback are set for the <tt/assoc/ object.
358 The ir object name is argument to the <tt/fail-response/ and
359 <tt/connect-response/ routines.
360 Note the use of the Tcl <tt/list/ command which
361 is necessary here because the argument contains variables
362 (<tt/assoc/) that should be substituted before the handler is defined.
363 After the connect operation, the <tt/init-response/ handler
364 is defined in much the same way as the failback handler.
365 And, finally, an init request is executed.
372 To terminate the connection the <tt/disconnect/ action should be used.
373 This action has no parameters.
374 Another connection may be established by a new <tt/connect/ action on
380 This section covers the queries used by <sf/IrTcl/, and how searches and
381 presents are handled.
383 A search operation and a result set is described by the ir set object.
384 The ir set object is defined by the <tt/ir-set/ command which
385 has two parameters. The first is the name of the new ir set object, and
386 the second, which is optional, is the name of an assocation &mdash an ir
387 object. The second argument is required if the ir set object should be able
388 to perform searches and presents. However, it is not required if
389 only ``local'' operations is done with the ir set object.
391 When the ir set object is created a number of settings are inherited
392 from the ir object, such as the selected databass, query type,
393 etc. Thus, the ir object contains what we could call default
399 Search requests are sent by the <tt/search/ action which
400 takes a query as parameter. There are two types of queries,
401 RPN and CCL, controlled by the setting <tt/queryType/.
402 A string representation for the query is used in <sf/IrTcl/ since
403 Tcl has reasonably powerful string manipulaton capabilities.
404 The RPN query used in <sf/IrTcl/ is the prefix query notation also used in
405 the <bf/YAZ/ test client.
407 The CCL query is an uninterpreted octet-string which is parsed by the target.
408 We refer to the standard: ISO 8777. Note that only a few targets
409 actually support the CCL query and the interpretation of
410 the standard may vary.
412 The prefix query notation (which is converted to RPN) offer a few
416 <tag><tt>@attr </tt><em>list op</em></tag>
417 The attributes in list are applied to op
418 <tag><tt>@and </tt><em>op1 op2</em></tag>
419 Boolean <em/and/ on op1 and op2
420 <tag><tt>@or </tt><em>op1 op2</em></tag>
421 Boolean <em/or/ on op1 and op2
422 <tag><tt>@not </tt><em>op1 op2</em></tag>
423 Boolean <em/not/ on op1 and op2
424 <tag><tt>@prox </tt><em>list op1 op2</em></tag>
425 Proximity operation on op1 and op2. Not implemented yet.
426 <tag><tt>@set </tt><em>name</em></tag>
430 It is simple to build RPN queries in <sf/IrTcl/. Search terms
431 are sequences of characters, as in:
436 Boolean operators use the prefix notation (instead of the suffix/RPN),
439 @and science technology
442 Search terms may be associated with attributes. These
443 attributes are indicated by the <tt/@attr/ operator.
444 Assuming the bib-1 attribute set, we can set the use-attribute
445 (type is 1) to title (value is 4):
451 Also, it is possible to apply attributes to a range of search terms.
452 In the query below, both search terms have use=title but the <tt/tech/
453 term is right truncated:
456 @attr 1=4 @and @attr 5=1 tech beta
462 The settings that affect the search are listed below:
465 <tag><tt>databaseNames </tt><em>list</em></tag>
467 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
468 small set upper bound. Default 0.
469 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
470 large set lower bound. Default 2.
471 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
472 medium set present number. Default 0.
473 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>
475 <tag><tt>setName </tt><em>string</em></tag>
477 <tag><tt>queryType rpn|ccl</tt></tag>
478 query type-1 or query type-2
479 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
480 preferred record syntax &mdash UNIMARC, USMARC, etc.
481 <tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
482 small-set-element-set names. Not implemented yet.
483 <tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
484 medium-set-element-set names. Not implemented yet.
485 <tag><tt>searchResponse </tt><em>list</em></tag>
486 Search-response Tcl script. Not implemented yet. Use <tt>callback</tt>
488 <tag><tt>callback </tt><em>list</em></tag>
489 General response Tcl script. Only used if searchResponse is not specified
492 Setting the <tt/databaseNames/ is mandatory. All other settings
493 have reasonable defaults.
494 The search-response handler, specified by the <tt/callback/ - or
495 the <tt/searchResponse/ setting,
496 should read some of the settings shown below:
499 <tag><tt>searchStatus </tt><em>boolean</em></tag>
500 search-status. True if search operation was successful; false
502 <tag><tt>responseStatus </tt><em>list</em></tag>
503 response status information.
504 <tag><tt>resultCount </tt><em>integer</em></tag>
506 <tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
507 number of records returned.
510 The <tt/responseStatus/ signals one of three conditions which
511 is indicated by the value of the first item in the list:
514 <tag><tt>NSD</tt></tag> indicates that the target has returned one or
515 more non-surrogate diagnostic messages. The <tt/NSD/ item is followed by
516 a list with all non-surrogate messages. Each non-surrogate message consists
517 of three items. The first item of the three items is the error
518 code (integer); the next item is a textual representation of the error
519 code in plain english; the third item is additional information, possibly
520 empty if no additional information was returned by the target.
522 <tag><tt>DBOSD</tt></tag> indicates a successful operation where the
523 target has returned one or more records. Each record may be
524 either a database record or a surrogate diagnostic.
526 <tag><tt>OK</tt></tag> indicates a successful operation &mdash no records are
527 returned from the target.
532 We continue with the multiple-targets example.
533 The <tt/init-response/ procedure will attempt to make searches:
536 proc init-response {assoc} {
537 puts "$assoc connected"
538 ir-set ${assoc}.1 $assoc
539 $assoc.1 queryType rpn
540 $assoc.1 databaseNames base-a base-b
541 $assoc.1 callback [list search-response $assoc ${assoc}.1]
542 $assoc.1 search "@attr 1=4 @and @attr 5=1 tech beta"
546 An ir set object is defined and the
547 ir object is told about the name of ir object.
548 The ir set object use the name of the ir object as prefix.
550 Then, the query-type is defined to be RPN, i.e. we will
551 use the prefix query notation later on.
553 Two databases, <tt/base-a/ and <tt/base-b/, are selected.
555 A <tt/search-response/ handler is defined with the
556 ir object and the ir-set object as parameters and
557 the search is executed.
559 The first part of the <tt/search-response/ looks like:
561 proc search-response {assoc rset} {
562 set status [$rset responseStatus]
563 set type [lindex $status 0]
564 if {$type == "NSD"} {
565 set code [lindex $status 1]
566 set msg [lindex $status 2]
567 set addinfo [lindex $status 3]
568 puts "NSD $code: $msg: $addinfo"
571 set hits [$rset resultCount]
572 if {$type == "DBOSD"} {
573 set ret [$rset numberOfRecordsReturned]
578 The response status is stored in variable <tt/status/ and
579 the first element indicates the condition.
580 If non-surrogate diagnostics are returned they are displayed.
581 Otherwise, the search was a success and the number of hits
582 is read. Finally, it is tested whether the search response
583 returned records (database or diagnostic).
585 Note that we actually didn't inspect the search status (setting
586 <tt/searchStatus/) to determine whether the search was successful or not,
587 because the standard specifies that one or more non-surrogate
588 diagnostics should be returned by the target in case of errors.
592 If one or more records are returned from the target they
593 will be stored in the result set object.
594 In the case in which the search response contains records, it is
595 very similar to the present response case. Therefore, some settings
596 are common to both situations.
601 The <tt/present/ action sends a present request. The <tt/present/ is
602 followed by two optional integers. The first integer is the
603 result-set starting position &mdash defaults to 1. The second integer
604 is the number of records requested &mdash defaults to 10.
605 The settings which could be modified before a <tt/present/
609 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
610 preferred record syntax &mdash UNIMARC, USMARC, etc.
611 <tag><tt>elementSetElementSetNames </tt><em>string</em></tag>
613 <tag><tt>presentResponse </tt><em>list</em></tag>
614 Present-response Tcl script. Not implemented yet. Use <tt>callback</tt>
616 <tag><tt>callback </tt><em>list</em></tag>
617 General response Tcl script. Only used if presentResponse is not specified
620 The present-response handler should inspect the settings
621 shown in table below.
622 Note that <tt/responseStatus/ and <tt/numberOfRecordsReturned/
623 settings were also used in the search-response case.
625 As in the search response case, records returned from the
626 target are stored in the result set object.
629 <tag><tt>presentStatus </tt><em>boolean</em></tag>
631 <tag><tt>responseStatus </tt><em>list</em></tag>
632 Response status information
633 <tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
634 number of records returned
635 <tag><tt>nextResultSetPosition </tt><em>integer</em></tag>
636 next result set position
642 Search responses and present responses may result in
643 one or more records stored in the ir set object if
644 the <tt/responseStatus/ setting indicates database or
645 surrogate diagnostics (<tt/DBOSD/). The individual
646 records, indexed by an integer position, should be
649 The action <tt/type/ followed by an integer returns information
650 about a given position in an ir set. There are three possiblities:
653 <tag><tt/SD/</tag> The item is a surrogate diagnostic record.
654 <tag><tt/DB/</tag> The item is a database record.
655 <tag><em/empty/</tag> There is no record at the specified position.
658 To handle the first case, surrogate diagnostic record, the
659 <tt/Diag/ action should be used. It returns three
660 items: error code (integer), text representation in plain english
661 (string), and additional information (string, possibly empty).
663 In the second case, database record, the <tt/recordType/ action should
664 be used. It returns the record type at the given position.
665 Some record types are:
682 We continue our search-response example. In the case,
683 <tt/DBOSD/, we should inspect the result set items.
684 Recall that the ir set name was passed to the
685 search-response handler as argument <tt/rset/.
688 if {$type == "DBOSD"} {
689 set ret [$rset numberOfRecordsReturned]
690 for {set i 1} {$i<=$ret} {incr i} {
691 set itype [$rset type $i]
692 if {$itype == "SD"} {
693 set diag [$rset Diag $i]
694 set code [lindex $diag 0]
695 set msg [lindex $diag 1]
696 set addinfo [lindex $diag 2]
697 puts "$i: NSD $code: $msg: $addinfo"
698 } elseif {$itype == "DB"} {
699 set rtype [$rset recordType $i]
700 puts "$i: type is $rtype"
705 Each item in the result set is examined.
706 If an item is a diagnostic message it is displayed; otherwise
707 if it's a database record its type is displayed.
714 In the case, where there is a MARC record at a given position we
715 want to display it somehow. The action <tt/getMarc/ is what we need.
716 The <tt/getMarc/ is followed by a position integer and the type of
717 extraction we want to make: <tt/field/ or <tt/line/.
719 The <tt/field/ and <tt/line/ type are followed by three
720 parameters that serve as extraction masks.
721 They are called tag, indicator and field.
722 If the mask matches a tag/indicator/field of a record the information
723 is extracted. Two characters have special meaning in masks: the
724 dot (any character) and star (any number of any character).
726 The <tt/field/ type returns one or more lists of field information
727 that matches the mask specification. Only the content of fields
730 The <tt/line/ type, on the other hand, returns a Tcl list that
731 completely describe the layout of the MARC record &mdash including
734 The <tt/field/ type is sufficient and efficient in the case, where only a
735 small number of fields are extracted, and in the case where no
736 further processing (in Tcl) is necessary.
738 However, if the MARC record is to be edited or altered in any way, the
739 <tt/line/ extraction is more powerful &mdash only limited by the Tcl
744 Consider the record below:
749 008 910710c19910701nju 00010 eng
753 100 10 $a Jack Collins
754 245 10 $a How to program a computer
760 Assuming this record is at position 1 in ir-set <tt/z.1/, we
761 might extract the title-field (245 * a), with the following command:
763 z.1 getMarc 1 field 245 * a
768 {How to program a computer}
771 Using the <tt/line/ instead of <tt/field/ gives:
773 {245 {10} {{a {How to program a computer}} }}
776 If we wish to extract the whole record as a list, we use:
778 z.1 getMarc 1 line * * *
783 {001 {} {{{} { 11224466 }} }}
785 {005 {} {{{} 00000000000000.0} }}
786 {008 {} {{{} {910710c19910701nju 00010 eng }} }}
787 {010 { } {{a { 11224466 }} }}
788 {040 { } {{a DLC} {c DLC} }}
789 {050 {00} {{a 123-xyz} }}
790 {100 {10} {{a {Jack Collins}} }}
791 {245 {10} {{a {How to program a computer}} }}
792 {260 {1 } {{a Penguin} }}
793 {263 { } {{a 8710} }}
794 {300 { } {{a {p. cm.}} }}
801 This example demonstrates how Tcl can be used to examine
802 a MARC record in the list notation.
804 The procedure <tt/extract-format/ makes an extraction of
805 fields in a MARC record based on a number of masks.
806 There are 5 parameters, <tt/r/: a
807 record in list notation, <tt/tag/: regular expression to
808 match the record tags, <tt/ind/: regular expression to
809 match indicators, <tt/field/: regular expression to
810 match fields, and finally <tt/text/: regular expression to
811 match the content of a field.
814 proc extract-format {r tag ind field text} {
816 if {[regexp $tag [lindex $line 0]] && \
817 [regexp $ind [lindex $line 1]]} {
818 foreach f [lindex $line 2] {
819 if {[regexp $field [lindex $f 0]]} {
820 if {[regexp $text [lindex $f 1]]} {
830 To match <tt/comput/ followed by any number of character(s) in the
831 245 fields in the record from the previous example, we could use:
833 set r [z.1 getMarc 1 line * * *]
835 extract-format $r 245 .. . comput
839 How to program a computer
844 The <tt/putMarc/ action does the opposite of <tt/getMarc/. It
845 copies a record in Tcl list notation to a ir set object and is
846 needed if a result-set must be updated by a Tcl modified (user-edited)
852 To perform scan, a scan object must be created by the <tt>ir-scan</tt>
853 command. This command has two arguments - name of the scan object and
854 name of the ir object. Basically, the scan object, provides one <tt>scan</tt>
855 action which sends a scan request to the target. The <tt>action</tt>
856 is followed by a string describing starting point of the term list. The
857 format used is a simple subset of the query used in search requests. Only
858 <tt>@attr</tt> specifications and simple terms are allowed.
859 The settings that affect the scan are:
862 <tag><tt>stepSize </tt><em>integer</em></tag>
863 Step size. Default is 0.
864 <tag><tt>numberOfTermsRequested </tt><em>integer</em></tag>
865 Number of terms requested. Default is 20.
866 <tag><tt>preferredPositionInResponse </tt><em>integer</em></tag>
867 Preferred position in response. Default is 1.
868 <tag><tt>databaseNames </tt><em>list</em></tag>
869 Database names. Note that this setting is not (yet) supported for
870 the scan object. You must set this for the ir object instead.
871 <tag><tt>callback </tt><em>list</em></tag>
872 General response Tcl script. This setting is not (yet) supported for
873 the scan object. You must set this for the ir object instead.
876 The scan object normally holds one or more scan line entries upon
877 successful completion. The table below summarizes the settings
878 that should be used in a response handler.
881 <tag><tt>scanStatus</tt></tag>
882 Scan status. An integer between 0 and 6.
883 <tag><tt>numberOfTermsReturned </tt><em>integer</em></tag>
884 Number of terms returned.
885 <tag><tt>positionOfTerm</tt></tag>
886 An integer describing the position of term.
887 <tag><tt>scanLine </tt> <em>integer</em></tag>
888 This function returns information about a given scan line (entry) at a given
889 index specified by the integer. The first scan line is numbered zero;
890 the second 1 and so on. A list is returned by the <tt>scanLine</tt>
891 setting. The first element is <tt>T</tt> if the scan line
892 is a normal term and <tt>SD</tt> if the scan line is a surrogate
893 diagnostic. In the first case (normal) the scan term is second element
894 in the list and the number of occurences is the third element.
895 In the other case (surrogate diagnostic), the second element
896 is the diagnostic code, the third a text representation of the error
897 code and the fourth element is additional information.
902 We will scan for the terms after <tt>science</tt> in the Title index.
903 We will assume that an ir object called <tt>z-assoc</tt> has already
907 z-assoc callback {scan-response}
908 ir-scan z-scan z-assoc
909 z-scan scan "@attr 1=4 science"
911 proc scan-response {} {
912 set status [z-scan status]
914 set no [z-scan numberOfTermsReturned]
915 for {set i 0} {$i < $no} {incr i} {
916 set line [z-scan scanLine $i]
917 set type [lindex $line 0]
919 puts [lindex $line 1]
920 } elseif {$type == "SD"} {
921 puts [lindex $line 1]
932 Copyright (c) 1995, Index Data.
934 Permission to use, copy, modify, distribute, and sell this software and
935 its documentation, in whole or in part, for any purpose, is hereby granted,
938 1. This copyright and permission notice appear in all copies of the
939 software and its documentation. Notices of copyright or attribution
940 which appear at the beginning of any file must remain unchanged.
942 2. The names of Index Data or the individual authors may not be used to
943 endorse or promote products derived from this software without specific
944 prior written permission.
946 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
947 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
948 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
949 IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
950 INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
951 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
952 NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
953 LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
956 <sect>About Index Data
959 Index Data is a consulting and software-development enterprise that
960 specialises in library and information management systems. Our
961 interests and expertise span a broad range of related fields, and one
962 of our primary, long-term objectives is the development of a powerful
963 information management
964 system with open network interfaces and hypermedia capabilities.
966 We make this software available free of charge, on a fairly unrestrictive
967 license; as a service to the networking community, and to further the
968 development of quality software for open network communication.
970 We'll be happy to answer questions about the software, and about ourselves
976 2200 København N&nl
984 Email: info@index.ping.dk
992 <tag>1 Ousterhout, John K.:</tag>
993 Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
994 0-201-63337-X). Source and documentation
995 can be found in <tt>URL:ftp://ftp.cs.berkeley.edu/pub/tcl</tt>
997 <tag>2 Furniss, Peter:</tag>
998 RFC 1698: Octet Sequences for Upper-Layer OSI to Support
999 Basic Communications Applications.