doc/ir-tcl.sgml

   1 <!doctype linuxdoc system>
   2
   3 <!--
   4   $Id: ir-tcl.sgml,v 1.3 1995-05-30 09:44:22 adam Exp $
   5 -->
   6
   7 <article>
   8 <title>IrTcl User's Guide and Reference
   9 <author>Index Data, <tt/info@index.ping.dk/
  10 <date>$Date: 1995-05-30 09:44:22 $
  11 <abstract>
  12 This document describes IrTcl &mdash an information retrieval toolkit for
  13 Tcl and Tk that provides access to the Z39.50/SR protocol.
  14 </abstract>
  15
  16 <toc>
  17
  18 <sect>Introduction
  19
  20 <p>
  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 &lsqb;ref 1&rsqb;.
  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
  29 system.
  30
  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
  33 protocol stack.
  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 &lsqb;ref 2&rsqb; for more information about the XTI/mOSI implementation.
  37
  38 <sf/IrTcl/ provides two system environments:
  39
  40 <itemize>
  41 <item> A simple command line shell &mdash useful for
  42 testing purposes.
  43 <item> A system which operates within the Tk environment which
  44 makes it very easy to implement GUI clients.
  45 </itemize>
  46
  47 <sect>Overview
  48
  49 <p>
  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.
  53
  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.
  57
  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.
  62
  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.
  70
  71 We are now ready to present the three commands introduced to Tcl by
  72 <sf/IrTcl/:
  73
  74 <descrip>
  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.
  84 </descrip>
  85
  86 <bf/Example/
  87
  88 To create a new IR object called <tt/z-assoc/ write:
  89 <tscreen><verb>
  90    ir z-assoc
  91 </verb></tscreen>
  92
  93 <bf/End of example/
  94
  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
  98 is set to <em/value/.
  99
 100 <bf/Example/
 101
 102 We wish to set the preferred-message-size to 18000 on the
 103 <tt/z-assoc/ object:
 104
 105 <tscreen><verb>
 106    z-assoc preferredMessageSize 18000
 107 </verb></tscreen>
 108
 109 To read the current value of preferred-message-size use:
 110
 111 <tscreen><verb>
 112    z-assoc preferredMessageSize
 113 </verb></tscreen>
 114 <bf/End of example/
 115
 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.
 122
 123 For each SR/Z39.50 request there is a corresponding object action. The most
 124 important actions are:
 125 <descrip>
 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.
 131 </descrip>
 132
 133 <bf/Example/
 134
 135 This example shows a complete connect - init - search - present scenario.
 136
 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.
 140
 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.
 146
 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.
 151
 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/.
 155
 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.
 160
 161 Finally, a present response is received and the number of records
 162 returned is stored in the variable <tt/ret/.
 163
 164 <tscreen><verb>
 165 ir z
 166 ir-set z.1 z
 167 z databaseNames books
 168 z callback {connect-response}
 169 z connect fake.com
 170
 171 proc connect-response {} {
 172     z callback {init-response}
 173     z init
 174 }
 175
 176 proc init-response {} {
 177     z.1 callback {search-response}
 178     z.1 search science
 179 }
 180
 181 proc search-response {} {
 182     set hits [z.1 resultCount]
 183     puts "$hits hits"
 184     if {$hits > 0} {
 185         z.1 callback {present-response}
 186         z.1 present 1 5
 187     }
 188 }
 189
 190 proc present-response {} {
 191     set ret [z.1 numberOfRecordsReturned]
 192     puts "$ret records returned"
 193 }
 194 </verb></tscreen>
 195 <bf/End of example/
 196
 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.
 201
 202 <sect>Associations
 203
 204 <p>
 205 The ir object describes an association with a target.
 206 This section covers the connect-init-disconnect actions provided
 207 by the ir object.
 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.
 211
 212 <sect1>Connect
 213
 214 <p>
 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:
 219
 220 <descrip>
 221 <tag><tt>comstack </tt><tt>mosi|tcpip</tt></tag>
 222  Comstack type
 223 <tag><tt>protocol </tt><tt>Z3950|SR</tt></tag>
 224  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
 229  closes connection
 230 </descrip>
 231
 232 If the connect is unsuccessful either the connect action itself
 233 will return an error code or the failback handler is invoked.
 234
 235 <sect1>Init
 236
 237 <p>
 238 If the connect operation succeeds the <tt/init/ action should be used.
 239 The init related settings are:
 240
 241 <descrip>
 242 <tag><tt>preferredMessageSize </tt><em>integer</em></tag>
 243  Preferred-message-size
 244 <tag><tt>maximumRecordSize </tt><em>integer</em></tag>
 245  Maximum-record-size
 246 <tag><tt>idAuthentication </tt><em>string</em></tag>
 247  Id-authentication
 248 <tag><tt>implementationName </tt><em>string</em></tag>
 249  Implementation-name of origin system
 250 <tag><tt>implementationId </tt><em>string</em></tag>
 251  Implementation-id of origin system
 252 <tag><tt>options </tt><em>list</em></tag>
 253  Options to be negotiated in init. The list contains the options that
 254 are set.
 255 <tag><tt>protocolVersion </tt><em>integer</em></tag>
 256  Protocol version: 2, 3, etc.
 257 <tag><tt>initResponse </tt><em>list</em></tag>
 258  Init-response Tcl script
 259 <tag><tt>callback </tt><em>list</em></tag>
 260  General response Tcl script. Only used if initResponse is not specified
 261 </descrip>
 262
 263 The init-response handler should inspect some of the settings shown
 264 below:
 265
 266 <descrip>
 267 <tag><tt>initResult </tt><em>boolean</em></tag>
 268  Init response status
 269 <tag><tt>preferredMessageSize </tt><em>integer</em></tag>
 270  Preferred-message-size
 271 <tag><tt>maximumRecordSize </tt><em>integer</em></tag>
 272  Maximum-record-size
 273 <tag><tt>targetImplementationName </tt><em>string</em></tag>
 274  Implementation-name of target system
 275 <tag><tt>targetImplementationId </tt><em>string</em></tag>
 276  Implementation-id of target system
 277 <tag><tt>targetImplementationVersion </tt><em>string</em></tag>
 278  Implementation-version of target system
 279 <tag><tt>options </tt><em>list</em></tag>
 280  Options negotiated after init. The list contains the options that are set.
 281 <tag><tt>protocolVersion </tt><em>integer</em></tag>
 282  Protocol version: 2, 3, etc.
 283 <tag><tt>userInformationField </tt><em>string</em></tag>
 284  User information field
 285 </descrip>
 286
 287 <bf/Example/
 288
 289 Consider a client with the ability to access multiple targets.
 290
 291 We define a list of targets that we wish to connect to.
 292 Each item in the list describes the target parameters with
 293 the following four components: association-name, comstack-type,
 294 protocol-type and a hostname.
 295
 296 The list for the two targets: ISO/SR target DANBIB and TCP/Z39.50
 297 target Data Research, will be defined as:
 298 <tscreen><verb>
 299 set targetList { {danbib mosi sr 0103/find2.denet.dk:4500}
 300                  {drs tcpip z39 dranet.dra.com} }
 301 </verb></tscreen>
 302
 303 The Tcl code below defines, connect and initialize the
 304 targets in <tt/targetList/:
 305
 306 <tscreen><verb>
 307 \foreach target $targetList {
 308     set assoc [lindex $target 0]
 309     ir $assoc
 310     $assoc comstack [lindex $target 1]
 311     $assoc protocol [lindex $target 2]
 312     $assoc failback [list fail-response $assoc]
 313     $assoc callback [list connect-response $assoc]
 314     $assoc connect [lindex $target 3]
 315 }
 316
 317 proc connect-response {assoc} {
 318     $assoc initResponse [list init-response $assoc]
 319     $assoc init
 320 }
 321
 322 proc fail-response {assoc} {
 323     puts "$assoc closed connection or protocol error"
 324 }
 325
 326 proc init-response {assoc} {
 327     if {[$assoc initResult]} {
 328         puts "$assoc initialized ok"
 329     } else {
 330         puts "$assoc didn't initialize"
 331     }
 332 }
 333 </verb></tscreen>
 334
 335 <tt/target/ is bound to each item in the list of targets.
 336 The <tt/assoc/ is set to the ir object name.
 337 Then, the comstack, protocol and failback are set for the <tt/assoc/ object.
 338 The ir object name is argument to the <tt/fail-response/ and
 339 <tt/connect-response/ routines.
 340 Note the use of the Tcl <tt/list/ command which
 341 is necessary here because the argument contains variables
 342 (<tt/assoc/) that should be substituted before the handler is defined.
 343 After the connect operation, the <tt/init-response/ handler
 344 is defined in much the same way as the failback handler.
 345 And, finally, an init request is executed.
 346 <bf/End of example/
 347
 348 <sect1>Disconnect
 349
 350 <p>
 351 To terminate the connection the <tt/disconnect/ action should be used.
 352 This action has no parameters.
 353 Another connection may be established by a new <tt/connect/ action on
 354 the same ir object.
 355
 356 <sect>Result sets
 357
 358 <p>
 359 This section covers the queries used by <sf/IrTcl/, and how searches and
 360 presents are handled.
 361
 362 A search operation and a result set is described by the ir set object.
 363 The ir set object is defined by the <tt/ir-set/ command which
 364 has two parameters. The first is the name of the new ir set object, and
 365 the second, which is optional, is the name of an assocation &mdash an ir
 366 object. The second argument is required if the ir set object should be able
 367 to perform searches and presents. However, it is not required if
 368 only ``local'' operations is done with the ir set object.
 369
 370 When the ir set object is created a number of settings are inherited
 371 from the ir object, such as the selected databass, query type,
 372 etc. Thus, the ir object contains what we could call default
 373 settings.
 374
 375 <sect1>Queries
 376
 377 <p>
 378 Search requests are sent by the <tt/search/ action which
 379 takes a query as parameter. There are two types of queries,
 380 RPN and CCL, controlled by the setting <tt/queryType/.
 381 A string representation for the query is used in <sf/IrTcl/ since
 382 Tcl has reasonably powerful string manipulaton capabilities.
 383 The RPN query used in <sf/IrTcl/ is the prefix query notation also used in
 384 the <bf/YAZ/ test client.
 385
 386 The CCL query is an uninterpreted octet-string which is parsed by the target.
 387 We refer to the standard: ISO 8777. Note that only a few targets
 388 actually support the CCL query and the interpretation of
 389 the standard may vary.
 390
 391 The prefix query notation (which is converted to RPN) offer a few
 392 operators. They are:
 393
 394 <descrip>
 395 <tag><tt>@attr </tt><em>list op</em></tag>
 396  The attributes in list are applied to op
 397 <tag><tt>@and </tt><em>op1 op2</em></tag>
 398  Boolean <em/and/ on op1 and op2
 399 <tag><tt>@or </tt><em>op1 op2</em></tag>
 400  Boolean <em/or/ on op1 and op2
 401 <tag><tt>@not </tt><em>op1 op2</em></tag>
 402  Boolean <em/not/ on op1 and op2
 403 <tag><tt>@prox </tt><em>list op1 op2</em></tag>
 404  Proximity operation on op1 and op2
 405 <tag><tt>@set </tt><em>name</em></tag>
 406  Result set reference
 407 </descrip>
 408
 409 It is simple to build RPN queries in <sf/IrTcl/. Search terms
 410 are sequences of characters, as in:
 411 <tscreen><verb>
 412    science
 413 </verb></tscreen>
 414
 415 Boolean operators use the prefix notation (instead of the suffix/RPN),
 416 as in:
 417 <tscreen><verb>
 418    @and science technology
 419 </verb></tscreen>
 420
 421 Search terms may be associated with attributes. These
 422 attributes are indicated by the <tt/@attr/ operator.
 423 Assuming the bib-1 attribute set, we can set the use-attribute
 424 (type is 1) to title (value is 4):
 425
 426 <tscreen><verb>
 427    @attr 1=4 science
 428 </verb></tscreen>
 429
 430 Also, it is possible to apply attributes to a range of search terms.
 431 In the query below, both search terms have use=title but the <tt/tech/
 432 term is right truncated:
 433
 434 <tscreen><verb>
 435    @attr 1=4 @and @attr 5=1 tech beta
 436 </verb></tscreen>
 437
 438 <sect1>Search
 439
 440 <p>
 441 The settings that affect the search are listed below:
 442
 443 <descrip>
 444 <tag><tt>databaseNames </tt><em>list</em></tag>
 445  database-names
 446 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
 447  small set upper bound
 448 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
 449  large set lower bound
 450 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
 451  medium set present number
 452 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>
 453  replace-indicator
 454 <tag><tt>setName </tt><em>string</em></tag>
 455  name of result set
 456 <tag><tt>queryType rpn|ccl</tt></tag>
 457  query type-1 or query type-2
 458 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
 459  preferred record syntax &mdash UNIMARC, USMARC, etc.
 460 <tag><tt>smallSetElementSetNames </tt><em>string</em></tag>
 461  small-set-element-set names
 462 <tag><tt>mediumSetElementSetNames </tt><em>string</em></tag>
 463  medium-set-element-set names
 464 <tag><tt>searchResponse </tt><em>list</em></tag>
 465  Search-response Tcl script
 466 <tag><tt>callback </tt><em>list</em></tag>
 467  General response Tcl script. Only used if searchResponse is not specified
 468 </descrip>
 469
 470 Setting the <tt/databaseNames/ is mandatory. All other settings
 471 have reasonable defaults.
 472 The search-response handler, specified by the <tt/callback/ - or
 473 the <tt/searchResponse/ setting,
 474 should read some of the settings shown below:
 475
 476 <descrip>
 477 <tag><tt>searchStatus </tt><em>boolean</em></tag>
 478  search-status
 479 <tag><tt>responseStatus </tt><em>list</em></tag>
 480  response status information
 481 <tag><tt>resultCount </tt><em>integer</em></tag>
 482  result-count
 483 <tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
 484  number of records retrieved
 485 </descrip>
 486
 487 The <tt/responseStatus/ signals one of three conditions which
 488 is indicated by the value of the first item in the list:
 489
 490 <descrip>
 491 <tag><tt>NSD</tt></tag> indicates that the target has returned one or
 492 more non-surrogate diagnostic messages. The <tt/NSD/ item is followed by
 493 a list with all non-surrogate messages. Each non-surrogate message consists
 494 of three items. The first item of the three items is the error
 495 code (integer); the next item is a textual representation of the error
 496 code in plain english; the third item is additional information, possibly
 497 empty if no additional information was returned by the target.
 498
 499 <tag><tt>DBOSD</tt></tag> indicates a successful operation where the
 500 target has returned one or more records. Each record may be
 501 either a database record or a surrogate diagnostic.
 502
 503 <tag><tt>OK</tt></tag> indicates a successful operation &mdash no records are
 504 returned from the target.
 505 </descrip>
 506
 507 <bf/Example/
 508
 509 We continue with the multiple-targets example.
 510 The <tt/init-response/ procedure will attempt to make searches:
 511
 512 <tscreen><verb>
 513 proc init-response {assoc} {
 514     puts "$assoc connected"
 515     ir-set ${assoc}.1 $assoc
 516     $assoc.1 queryType rpn
 517     $assoc.1 databaseNames base-a base-b
 518     $assoc.1 searchResponse [list search-response $assoc ${assoc}.1]
 519     $assoc.1 search "@attr 1=4 @and @attr 5=1 tech beta"
 520 }
 521 </verb></tscreen>
 522
 523 An ir set object is defined and the
 524 ir object is told about the name of ir object.
 525 The ir set object use the name of the ir object as prefix.
 526
 527 Then, the query-type is defined to be RPN, i.e. we will
 528 use the prefix query notation later on.
 529
 530 Two databases, <tt/base-a/ and <tt/base-b/, are selected.
 531
 532 A <tt/search-response/ handler is defined with the
 533 ir object and the ir-set object as parameters and
 534 the search is executed.
 535
 536 The first part of the <tt/search-response/ looks like:
 537 <tscreen><verb>
 538 proc search-response {assoc rset} {
 539     set status [$rset responseStatus]
 540     set type [lindex $status 0]
 541     if {$type == NSD} {
 542         set code [lindex $status 1]
 543         set msg [lindex $status 2]
 544         set addinfo [lindex $status 3]
 545         puts "NSD $code: $msg: $addinfo"
 546         return
 547     }
 548     set hits [$rset resultCount]
 549     if {$type == DBOSD} {
 550         set ret [$rset numberOfRecordsReturned]
 551         ...
 552     }
 553 }
 554 </verb></tscreen>
 555 The response status is stored in variable <tt/status/ and
 556 the first element indicates the condition.
 557 If non-surrogate diagnostics are returned they are displayed.
 558 Otherwise, the search was a success and the number of hits
 559 is read. Finally, it is tested whether the search response
 560 returned records (database or diagnostic).
 561
 562 Note that we actually didn't inspect the search status (setting
 563 <tt/searchStatus/) to determine whether the search was successful or not,
 564 because the standard specifies that one or more non-surrogate
 565 diagnostics should be returned by the target in case of errors.
 566 <bf/End of example/
 567
 568 If one or more records are returned from the target they
 569 will be stored in the result set object.
 570 In the case in which the search response contains records, it is
 571 very similar to the present response case. Therefore, some settings
 572 are common to both situations.
 573
 574 <sect1>Present
 575
 576 <p>
 577 The <tt/present/ action sends a present request. The <tt/present/ is
 578 followed by two optional integers. The first integer is the
 579 result-set starting position &mdash defaults to 1. The second integer
 580 is the number of records requested &mdash defaults to 10.
 581 The settings which could be modified before a <tt/present/
 582 action are:
 583
 584 <descrip>
 585 <tag><tt>preferredRecordSyntax </tt><em>string</em></tag>
 586  preferred record syntax &mdash UNIMARC, USMARC, etc.
 587 <tag><tt>elementSetElementSetNames </tt><em>string</em></tag>
 588  element-set names
 589 <tag><tt>presentResponse </tt><em>list</em></tag>
 590  Present-response Tcl script
 591 <tag><tt>callback </tt><em>list</em></tag>
 592  General response Tcl script. Only used if presentResponse is not specified
 593 </descrip>
 594
 595 The present-response handler should inspect the settings
 596 shown in table ref{tab:irpresentresponse}.
 597 Note that <tt/responseStatus/ and <tt/numberOfRecordsReturned/
 598 settings were also used in the search-response case.
 599
 600 As in the search-response case, records returned from the
 601 target are stored in the result set object.
 602
 603 <descrip>
 604 <tag><tt>presentStatus </tt><em>boolean</em></tag>
 605  present-status
 606 <tag><tt>responseStatus </tt><em>list</em></tag>
 607  Response status information
 608 <tag><tt>numberOfRecordsReturned </tt><em>integer</em></tag>
 609  number of records returned
 610 <tag><tt>nextResultSetPosition </tt><em>integer</em></tag>
 611  next result set position
 612 </descrip>
 613
 614 <sect1>Records
 615
 616 <p>
 617 Search responses and present responses may result in
 618 one or more records stored in the ir set object if
 619 the <tt/responseStatus/ setting indicates database or
 620 surrogate diagnostics (<tt/DBOSD/). The individual
 621 records, indexed by an integer position, should be
 622 inspected.
 623
 624 The action <tt/Type/ followed by an integer returns information
 625 about a given position in an ir set. There are three possiblities:
 626
 627 <descrip>
 628 <tag><tt/SD/</tag> The item is a surrogate diagnostic record.
 629 <tag><tt/DB/</tag> The item is a database record.
 630 <tag><em/empty/</tag> There is no record at the specified position.
 631 </descrip>
 632
 633 To handle the first case, surrogate diagnostic record, the
 634 <tt/Diag/ action should be used. It returns three
 635 items: error code (integer), text representation in plain english
 636 (string), and additional information (string, possibly empty).
 637
 638 In the second case, database record, the <tt/recordType/ action should
 639 be used. It returns the record type at the given position.
 640 Some record types are:
 641
 642 <tscreen>
 643 UNIMARC
 644 INTERMARC
 645 CCF
 646 USMARC
 647 UKMARC
 648 NORMARC
 649 LIBRISMARC
 650 DANMARC
 651 FINMARC
 652 SUTRS
 653 </tscreen>
 654
 655 <bf/Example/
 656
 657 We continue our search-response example. In the case,
 658 <tt/DBOSD/, we should inspect the result set items.
 659 Recall that the ir set name was passed to the
 660 search-response handler as argument <tt/rset/.
 661
 662 <tscreen><verb>
 663     if {$type == DBOSD} {
 664         set ret [$rset numberOfRecordsReturned]
 665         for {set i 1} {$i<=$ret} {incr i} {
 666             set itype [$rset Type $i]
 667             if {$itype == SD} {
 668                 set diag [$rset Diag $i]
 669                 set code [lindex $diag 0]
 670                 set msg [lindex $diag 1]
 671                 set addinfo [lindex $diag 2]
 672                 puts "$i: NSD $code: $msg: $addinfo"
 673             } else if {$itype == DB} {
 674                 set rtype [$rset RecordType $i]
 675                 puts "$i: type is $rtype"
 676             }
 677         }
 678     }
 679 </verb></tscreen>
 680 Each item in the result set is examined.
 681 If an item is a diagnostic message it is displayed; otherwise
 682 if it's a database record its type is displayed.
 683 <bf/End of example/
 684
 685 <sect1>MARC records
 686
 687 <p>
 688 In the case, where there is a MARC record at a given position we
 689 want to display it somehow. The action <tt/getMarc/ is what we need.
 690 The <tt/getMarc/ is followed by a position integer and the type of
 691 extraction we want to make: <tt/field/ or <tt/line/.
 692
 693 The <tt/field/ and <tt/line/ type are followed by three
 694 parameters that serve as extraction masks.
 695 They are called tag, indicator and field.
 696 If the mask matches a tag/indicator/field of a record the information
 697 is extracted. Two characters have special meaning in masks: the
 698 dot (any character) and star (any number of any character).
 699
 700 The <tt/field/ type returns one or more lists of field information
 701 that matches the mask specification. Only the content of fields
 702 is returned.
 703
 704 The <tt/line/ type, on the other hand, returns a Tcl list that
 705 completely describe the layout of the MARC record &mdash including
 706 tags, fields, etc.
 707
 708 The <tt/field/ type is sufficient and efficient in the case, where only a
 709 small number of fields are extracted, and in the case where no
 710 further processing (in Tcl) is necessary.
 711
 712 However, if the MARC record is to be edited or altered in any way, the
 713 <tt/line/ extraction is more powerful &mdash only limited by the Tcl
 714 language itself.
 715
 716 <bf/Example/
 717
 718 Consider the record below:
 719 <tscreen><verb>
 720 001       11224466
 721 003    DLC
 722 005    00000000000000.0
 723 008    910710c19910701nju           00010 eng
 724 010    $a    11224466
 725 040    $a DLC $c DLC
 726 050 00 $a 123-xyz
 727 100 10 $a Jack Collins
 728 245 10 $a How to program a computer
 729 260 1  $a Penguin
 730 263    $a 8710
 731 300    $a p. cm.
 732 </verb></tscreen>
 733
 734 Assuming this record is at position 1 in ir-set <tt/z.1/, we
 735 might extract the title-field (245 * a), with the following command:
 736 <tscreen><verb>
 737 z.1 getMarc 1 field 245 * a
 738 </verb></tscreen>
 739
 740 which gives:
 741 <tscreen><verb>
 742 {How to program a computer}
 743 </verb></tscreen>
 744
 745 Using the <tt/line/ instead of <tt/field/ gives:
 746 <tscreen><verb>
 747 {245 {10} {{a {How to program a computer}} }}
 748 </verb></tscreen>
 749
 750 If we wish to extract the whole record as a list, we use:
 751 <tscreen><verb>
 752 z.1 getMarc 1 line * * *
 753 </verb></tscreen>
 754
 755 giving:
 756 <tscreen><verb>
 757 {001 {} {{{} {   11224466 }} }}
 758 {003 {} {{{} DLC} }}
 759 {005 {} {{{} 00000000000000.0} }}
 760 {008 {} {{{} {910710c19910701nju           00010 eng  }} }}
 761 {010 {  } {{a {   11224466 }} }}
 762 {040 {  } {{a DLC} {c DLC} }}
 763 {050 {00} {{a 123-xyz} }}
 764 {100 {10} {{a {Jack Collins}} }}
 765 {245 {10} {{a {How to program a computer}} }}
 766 {260 {1 } {{a Penguin} }}
 767 {263 {  } {{a 8710} }}
 768 {300 {  } {{a {p. cm.}} }}
 769 </verb></tscreen>
 770
 771 <bf/End of example/
 772
 773 <bf/Example/
 774
 775 This example demonstrates how Tcl can be used to examine
 776 a MARC record in the list notation.
 777
 778 The procedure <tt/extract-format/ makes an extraction of
 779 fields in a MARC record based on a number of masks.
 780 There are 5 parameters, <tt/r/: a
 781 record in list notation, <tt/tag/: regular expression to
 782 match the record tags, <tt/ind/: regular expression to
 783 match indicators, <tt/field/: regular expression to
 784 match fields, and finally <tt/text/: regular expression to
 785 match the content of a field.
 786
 787 <tscreen><verb>
 788 proc extract-format {r tag ind field text} {
 789     foreach line $r {
 790         if {[regexp $tag [lindex $line 0]] && \
 791                 [regexp $ind [lindex $line 1]]} {
 792             foreach f [lindex $line 2] {
 793                 if {[regexp $field [lindex $f 0]]} {
 794                     if {[regexp $text [lindex $f 1]]} {
 795                         puts [lindex $f 1]
 796                     }
 797                 }
 798             }
 799         }
 800     }
 801 }
 802 </verb></tscreen>
 803
 804 To match <tt/comput/ followed by any number of character(s) in the
 805 245 fields in the record from the previous example, we could use:
 806 <tscreen><verb>
 807 set r [z.1 getMarc 1 line * * *]
 808
 809 extract-format $r 245 .. . comput
 810 </verb></tscreen>
 811 which gives:
 812 <tscreen><verb>
 813 How to program a computer
 814 </verb></tscreen>
 815
 816 <bf/End of example/
 817
 818 The <tt/putMarc/ action does the opposite of <tt/getMarc/. It
 819 copies a record in Tcl list notation to a ir set object and is
 820 needed if a result-set must be updated by a Tcl modified (user-edited)
 821 record.
 822
 823 <sect>Scan
 824
 825 <p>
 826 <em/To be written/
 827
 828 <sect>References
 829
 830 <p>
 831
 832 <descrip>
 833 <tag>1 Ousterhout, John K.:</tag>
 834 Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN
 835 0-201-63337-X). Source and documentation
 836 can be found in <tt>URL:ftp://ftp.cs.berkeley.edu/pub/tcl</tt>
 837 and mirrors.
 838 <tag>2 Furniss, Peter:</tag>
 839 RFC 1698: Octet Sequences for Upper-Layer OSI to Support
 840 Basic Communications Applications.
 841 </descrip>
 842
 843 </article>