doc/ir-set.n

   1 .\" Copyright (c) 1995, 1996 Index Data
   2 .\" All rights reserved.
   3 .\" $Id: ir-set.n,v 1.1 1996-06-24 13:58:47 adam Exp $
   4 .TH ir-set N  "24 June 1996" "IrTcl" "IR Set"
   5 .SH NAME
   6 ir-set \- IR  set
   7 .SH SYNOPSIS
   8 .BI "ir-set " zs " " za
   9 .sp
  10 .SH DESCRIPTION
  11 The Tcl command
  12 .B ir-set
  13 creates an IR set \fIzs\fR that belongs to the IR association \fIza\fR.
  14 The ir-set describes the result set including records, query, record
  15 syntax, etc. When a result set is created it is not (yet) associated
  16 with a real result set and it contains an empty set of records.
  17 When records are returned by the target they are automatically stored
  18 at their logical result set positions. They may exist more than one
  19 record at a given result set position if the records is marked with
  20 different element set specifications.
  21 .SH SEARCH
  22 Operations that are used to search a target:
  23 .TP
  24 .BI "" zs " databaseNames " db1 " " db2 " " ...
  25 Sets the database(s) to be used in the following search request(s).
  26 .TP
  27 .BI "" zs " setName [" name "]"
  28 Sets/gets the name of the result-set to be (re)searched.
  29 .TP
  30 .BI "" zs " replaceIndicator [" b "]"
  31 Sets/gets the replace-indicator as 0 (false) or 1 (true); default is
  32 1.
  33 .TP
  34 .BI "" zs " queryType [" type "]"
  35 Sets/gets the query-type. \fItype\fR is \fBrpn\fR or \fBccl\fR.
  36 .TP
  37 .BI "" zs " preferredRecordSyntax [" syntax "]"
  38 Sets/gets the preferred-record-syntax. Some record syntaxes include:
  39 \fBUSmarc\fR, \fBUKmarc\fR, \fBUnimarc\fR, \fBSUTRS\fR and \fBGRS-1\fR.
  40 All the available record syntaxes are listed in \fByaz/util/oid.c\fR.
  41 .TP
  42 .BI "" zs " smallSetUpperBound [" value "]"
  43 Sets/gets the small-set-upper-bound. Default is 0.
  44 .TP
  45 .BI "" zs " largeSetLowerBound [" value "]"
  46 Sets/gets the large-set-lower-bound. Default is 2.
  47 .TP
  48 .BI "" zs " mediumSetPresentNumber [" value "]"
  49 Sets/gets the medium-set-present-number. Default is 0.
  50 .TP
  51 .BI "" zs " smallSetElementSetNames [" element "]"
  52 Sets/gets the small-set-element-set-names. Default is that
  53 no small-set-element-set-names are transferred in the search-request.
  54 .TP
  55 .BI "" zs " mediumSetElementSetNames [" element "]"
  56 Sets/gets the medium-set-element-set-names. Default is that
  57 no medium-set-element-set-names are transferred in the search-request.
  58 .TP
  59 .BI "" zs " referenceId [" ID "]"
  60 Sets/gets the reference-ID. Default is that no reference ID is transferred
  61 in the search-request.
  62 .TP
  63 .BI "" zs " search " query
  64 Sends a search request. The \fIquery\fR must follow a syntax according to
  65 the \fBqueryType\fR setting.
  66 .TP
  67 .BI "" zs " responseStatus"
  68 Gets the search/present-response information. The first element indicates
  69 the type of response.
  70 If the element is \fBOK\fR it means that the search operation was
  71 succesful and that no records were returned. If the first element is
  72 \fBNSD\fR an error message is retunred by the target as one or more
  73 non-surrogate diagnostics. In this case, the following elements are
  74 those diagnostics. If the first element is \fBDBOSD\fR one of more
  75 records are returned, each of which is either a database record or a
  76 surrogate diagnostic.
  77 .TP
  78 .BI "" zs " resultCount"
  79 Gets the result-count (number of hits).
  80 .SH PRESENT
  81 Operations that concern retrieving records:
  82 .TP
  83 .BI "" zs " setName [" name "]"
  84 Sets/gets the name of the result-set to be read.
  85 .TP
  86 .BI "" zs " elementSetNames [" element "]"
  87 Sets/gets the element-set-names. Default is that no element-set-names are
  88 transferred in the present-request.
  89 .TP
  90 .BI "" zs " present [" from " [" requested "]]"
  91 Sends a present-request; starting position is given by the
  92 \fIfrom\fR argument (default 1), number-of-terms-requested is given by the
  93 \fIrequested\fR parameter (default 10).
  94 .TP
  95 .BI "" zs " responseStatus"
  96 Gets the search/present-response information. Refer to the
  97 \fBresponseStatus\fR in the section \fBSEARCH\fR above.
  98 .SH RECORDS
  99 Records may be returned in either a search-response or a present-response.
 100 The following operations apply to both cases.
 101 .TP
 102 .BI "" zs " nextResultSetPosition"
 103 Gets the next-result-set-position.
 104 .TP
 105 .BI "" zs " numberOfRecordsReturned"
 106 Gets the number of records returned in the last response.
 107 .TP
 108 .BI "" zs " recordElements " elements
 109 Sets the elements of the records to be inspected in all subsequent
 110 record inspection commands, i.e. those commands that include a
 111 \fIposition\fR parameter. If \fIelements\fR is set to the empty string
 112 (default) a record is always indicated as present no matter what the
 113 elements associated with the record are.
 114 .TP
 115 .BI "" zs " type " position
 116 Inspects the type of record at the \fIposition\fR specified. If no record
 117 is present the message "\fBNo record at position\fR \fIposition\fR" is
 118 returned. If a database record is present at the position, \fBDB\fR is
 119 returned. If a surrogate diagnostic is at the position, \fBSD\fR is
 120 returned.
 121 .TP
 122 .BI "" zs " recordType " position
 123 Inspects the record syntax of the database record at the \fIposition\fR
 124 specified. The empty string is returned if no database record is present
 125 at the position.
 126 .TP
 127 .BI "" zs " diag " position
 128 Inspects the surroagate diagnostic message at the given position.
 129 For each diagnostic message 3 items is returned; the first item is the
 130 error code, the second item is the textual representation of the error
 131 code and the third item is additional information. An error is issued
 132 if there is no surrogate diagnostic record at the position.
 133 .TP
 134 .BI "" zs " getMarc " position " " type " " tag " " indicator " " field
 135 Extracts information about the MARC record at the specified \fIposition\fR.
 136 The \fItag\fR, \fIindicator\fR and \fIfield\fR arguments are used to
 137 to specify which part of the record that should be extracted.
 138 Two special operators are supported:
 139 the \fB?\fR operator matches exactly one character;
 140 the \fB*\fR operator matches the whole item (don't care).
 141 The format of the data returned is determined by the \fItype\fR argument.
 142 If \fItype\fR is \fBfield\fR the matcing part of the record is returned
 143 as a list of MARC tag specifications. Each MARC tag specification item
 144 consists of three elements: tag, indicator and field-list. The field-list
 145 part is a list of field specifications. Each field specification is a tuple
 146 of field and data of the field. Setting \fItype\fR to \fBfield\fR returns
 147 a list of elements in which each element is simply the data of the fields
 148 that matches the specification.
 149 An error is returned if there is no MARC record at the position.
 150 .TP
 151 .BI "" zs " getSutrs " position
 152 Returns the SUTRS record at the given \fIposition\fR as a single
 153 string token. If the record at the position is not present or is not a
 154 SUTRS record an error is returned.
 155 .TP
 156 .BI "" zs " getGrs " position " [" spec " " spec " " ... "]"
 157 Extracts information about the GRS-1 record at the specified \Iposition\fR.
 158 The \fIspec\fR arguments determine the parts of the GRS-1 record to
 159 be extracted. The \fIspec\fR masks the GRS-1 tag at the first level
 160 (top-level), the second \fIspec\fR masks the GRS-1 tags at the
 161 second-level, and so on.
 162 Each \fIspec\fR has the format \fB(\fItag-set\fB,\fItag-value\fB)\fR, where
 163 \fItag-type\fR specifies the tag set and the \fItag-value\fR specifies the
 164 tag value. The GRS-1 record is returned as a Tcl list. Each element consists
 165 of 5 elements: \fItag-set\fR, \fItag-type\fR, \fItag-value\fR,
 166 \fIdata-type\fR, \fIdata\fR. The \fItype-type\fR is either \fBnumeric\fR or
 167 \fBstring\fR. The \fIdata-type\fR is one of: \fBoctets\fR, \fBnumeric\fR,
 168 \fBext\fR, \fBstring\fR, \fBbool\fR, \fBintUnit\fR, \fBempty\fR,
 169 \fBnotRequested\fR, \fBdiagnostic\fR or \fBsubtree\fR.
 170 .SH "SEE ALSO"
 171 .BR ir-assoc "(n)"