doc/ir-set.n

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