From 871eb649def07ab27f6bfc9290fc490653e97a1d Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Mon, 24 Jun 1996 13:58:45 +0000 Subject: [PATCH] Added man pages. --- doc/ir-assoc.n | 122 ++++++++++++++++++++++++++++++++++++++++ doc/ir-set.n | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 293 insertions(+) create mode 100644 doc/ir-assoc.n create mode 100644 doc/ir-set.n diff --git a/doc/ir-assoc.n b/doc/ir-assoc.n new file mode 100644 index 0000000..35ed5b8 --- /dev/null +++ b/doc/ir-assoc.n @@ -0,0 +1,122 @@ +.\" Copyright (c) 1995, 1996 Index Data +.\" All rights reserved. +.\" $Id: ir-assoc.n,v 1.1 1996-06-24 13:58:45 adam Exp $ +.TH ir-assoc N "24 June 1996" "IrTcl" "IR Association" +.SH NAME +ir \- IR association +.SH SYNOPSIS +.BI "ir " z +.sp +.SH DESCRIPTION +The Tcl command +.B ir +creates an IR association, that is an object that describes the +connection between an origin and a target. Initially, the association +is in a non-connected state. +.SH EVENTS +Event-oriented operations: +.TP +.BI "" z " callback " event +Sets the callback handler. This handler is invoked upon normal +completion of requests. +.TP +.BI "" z " eventType" +Gets the type of last event; typically used in callback handlers. +One of the following events are returned: \fBconnect\fR, \fBinit\fR, +\fBsearch\fR, \fBpresent\fR, \fBscan\fR or the empty string which +indicates that no event has occurred (yet). +.TP +.BI "" z " failback " event +Sets the failback handler. The failback handler is called when an +unrecoverable fatal error occur, for example if the connection is lost. +.TP +.BI "" z " failInfo" +Returns information about the latest fatal error; should be examined +in failback handlers. Two elements are returned: +error number and error string. +.SH CONNECTIONS +The operations that affect connecting to a target. +.TP +.BI "" z " connect [" host "]" +Tries to establish a connection with the \fIhost\fR if specified. +In this case, the default callback is invoked if the connect operation +succeeds; otherwise, the default failback or an error is immediately issued. +If the comstack setting is unknown, the +operation also fails. If the \fIhost\fR is not given, the operation +can be used to detect whether the assocation is connected. In this case +the hostname is returned; otherwise the empty string is returned. +.TP +.BI "" z " disconnect" +Shuts down the connection with the current target. An error is +issued if there is no current connection. +.TP +.BI "" z " comstack [" type "]" +Sets/gets the YAZ comstack. \fItype\fR is either \fBtcpip\fR (the default) +or \fBmosi\fR. +.TP +.BI "" z " protocol [" type "]" +Sets/gets the protocol type.\fItype\fR is either \fBZ39\fR (the default) +or \fBSR\fR. +.SH INIT +The following operations concern the initialize fase. +.TP +.BI "" z " init" +Sends an initialize request. +.TP +.BI "" z " idAuthentication " " openID +.TP +.BI "" z " idAuthentication " " groupID userID password +If one argument is passed the old-style open authentication method is +used in the following initialize request - using an empty string as the +authentication string prevents the (optional) authentication. +If three arguments are passed the new version 3 style name/group/password +scheme is used. The current authentication settings are returned +as either 3 elements (name/group/password scheme), 1 element (open style) +or the empty string (no password used). +.TP +.BI "" z " protocolVersion [" version "]" +Sets/gets the protocol version: 2, 3, etc. Before an initialize-request is +sent the protocol version should be set to the preferred version. After +an initalize response is read the version holds the negotiated version. +.TP +.BI "" z " preferredMessageSize [" size "]" +Sets/gets Z39.50/SR preferred-message-size; default is 30000. +.TP +.BI "" z " maxiumumRecordSize [" size "]" +Sets/gets the Z39.50/SR maximum-record-size; default is 30000. +.TP +.BI "" z " implementationId" +Gets the Z39.50/SR implementation-ID. +.TP +.BI "" z " implementationName" +Gets the Z39.50/SR implementation-name. +.TP +.BI "" z " implementationVersion" +Gets the Z39.50/SR implementation-version. +.TP +.BI "" z " options [" option ... "]" +Sets/gets the Z39.50/SR options. These are: \fBsearch\fR, \fBpresent\fR, +\fBdelSet\fR, \fBresourceReport\fR, \fBtriggerResourceCtrl\fR, +\fBresourceCtrl\fR, \fBaccessCtrl\fR, \fBscan\fR, \fBsort\fR, +\fBextendedServices\fR, \fBlevel-1Segmentation\fR, \fBlevel-2Segmentation\fR, +\fBconcurrentOperations\fR and \fBnamedResultSets\fR. +.TP +.BI "" z " targetImplementationName" +Gets the Z39.50/SR implementation-name of the target. +.TP +.BI "" z " targetImplementationId" +Gets the Z39.50/SR implementation-ID of the target. +.TP +.BI "" z " targetImplementationVersion" +Gets the Z39.50/SR implementation-version of the target. +.TP +.BI "" z " initResult" +Gets the initialize-response status as an integer: +0 if connection is rejected by the target; 1 if connection is accepted. +.TP +.BI "" z " userInformationField" +Gets the the user-information-field; this should be inspected when +the connection is rejected by the target (\fBinitResult\fR returns 0). + +.SH "SEE ALSO" +.BR ir-set "(n)" diff --git a/doc/ir-set.n b/doc/ir-set.n new file mode 100644 index 0000000..78896ea --- /dev/null +++ b/doc/ir-set.n @@ -0,0 +1,171 @@ +.\" Copyright (c) 1995, 1996 Index Data +.\" All rights reserved. +.\" $Id: ir-set.n,v 1.1 1996-06-24 13:58:47 adam Exp $ +.TH ir-set N "24 June 1996" "IrTcl" "IR Set" +.SH NAME +ir-set \- IR set +.SH SYNOPSIS +.BI "ir-set " zs " " za +.sp +.SH DESCRIPTION +The Tcl command +.B ir-set +creates an IR set \fIzs\fR that belongs to the IR association \fIza\fR. +The ir-set describes the result set including records, query, record +syntax, etc. When a result set is created it is not (yet) associated +with a real result set and it contains an empty set of records. +When records are returned by the target they are automatically stored +at their logical result set positions. They may exist more than one +record at a given result set position if the records is marked with +different element set specifications. +.SH SEARCH +Operations that are used to search a target: +.TP +.BI "" zs " databaseNames " db1 " " db2 " " ... +Sets the database(s) to be used in the following search request(s). +.TP +.BI "" zs " setName [" name "]" +Sets/gets the name of the result-set to be (re)searched. +.TP +.BI "" zs " replaceIndicator [" b "]" +Sets/gets the replace-indicator as 0 (false) or 1 (true); default is +1. +.TP +.BI "" zs " queryType [" type "]" +Sets/gets the query-type. \fItype\fR is \fBrpn\fR or \fBccl\fR. +.TP +.BI "" zs " preferredRecordSyntax [" syntax "]" +Sets/gets the preferred-record-syntax. Some record syntaxes include: +\fBUSmarc\fR, \fBUKmarc\fR, \fBUnimarc\fR, \fBSUTRS\fR and \fBGRS-1\fR. +All the available record syntaxes are listed in \fByaz/util/oid.c\fR. +.TP +.BI "" zs " smallSetUpperBound [" value "]" +Sets/gets the small-set-upper-bound. Default is 0. +.TP +.BI "" zs " largeSetLowerBound [" value "]" +Sets/gets the large-set-lower-bound. Default is 2. +.TP +.BI "" zs " mediumSetPresentNumber [" value "]" +Sets/gets the medium-set-present-number. Default is 0. +.TP +.BI "" zs " smallSetElementSetNames [" element "]" +Sets/gets the small-set-element-set-names. Default is that +no small-set-element-set-names are transferred in the search-request. +.TP +.BI "" zs " mediumSetElementSetNames [" element "]" +Sets/gets the medium-set-element-set-names. Default is that +no medium-set-element-set-names are transferred in the search-request. +.TP +.BI "" zs " referenceId [" ID "]" +Sets/gets the reference-ID. Default is that no reference ID is transferred +in the search-request. +.TP +.BI "" zs " search " query +Sends a search request. The \fIquery\fR must follow a syntax according to +the \fBqueryType\fR setting. +.TP +.BI "" zs " responseStatus" +Gets the search/present-response information. The first element indicates +the type of response. +If the element is \fBOK\fR it means that the search operation was +succesful and that no records were returned. If the first element is +\fBNSD\fR an error message is retunred by the target as one or more +non-surrogate diagnostics. In this case, the following elements are +those diagnostics. If the first element is \fBDBOSD\fR one of more +records are returned, each of which is either a database record or a +surrogate diagnostic. +.TP +.BI "" zs " resultCount" +Gets the result-count (number of hits). +.SH PRESENT +Operations that concern retrieving records: +.TP +.BI "" zs " setName [" name "]" +Sets/gets the name of the result-set to be read. +.TP +.BI "" zs " elementSetNames [" element "]" +Sets/gets the element-set-names. Default is that no element-set-names are +transferred in the present-request. +.TP +.BI "" zs " present [" from " [" requested "]]" +Sends a present-request; starting position is given by the +\fIfrom\fR argument (default 1), number-of-terms-requested is given by the +\fIrequested\fR parameter (default 10). +.TP +.BI "" zs " responseStatus" +Gets the search/present-response information. Refer to the +\fBresponseStatus\fR in the section \fBSEARCH\fR above. +.SH RECORDS +Records may be returned in either a search-response or a present-response. +The following operations apply to both cases. +.TP +.BI "" zs " nextResultSetPosition" +Gets the next-result-set-position. +.TP +.BI "" zs " numberOfRecordsReturned" +Gets the number of records returned in the last response. +.TP +.BI "" zs " recordElements " elements +Sets the elements of the records to be inspected in all subsequent +record inspection commands, i.e. those commands that include a +\fIposition\fR parameter. If \fIelements\fR is set to the empty string +(default) a record is always indicated as present no matter what the +elements associated with the record are. +.TP +.BI "" zs " type " position +Inspects the type of record at the \fIposition\fR specified. If no record +is present the message "\fBNo record at position\fR \fIposition\fR" is +returned. If a database record is present at the position, \fBDB\fR is +returned. If a surrogate diagnostic is at the position, \fBSD\fR is +returned. +.TP +.BI "" zs " recordType " position +Inspects the record syntax of the database record at the \fIposition\fR +specified. The empty string is returned if no database record is present +at the position. +.TP +.BI "" zs " diag " position +Inspects the surroagate diagnostic message at the given position. +For each diagnostic message 3 items is returned; the first item is the +error code, the second item is the textual representation of the error +code and the third item is additional information. An error is issued +if there is no surrogate diagnostic record at the position. +.TP +.BI "" zs " getMarc " position " " type " " tag " " indicator " " field +Extracts information about the MARC record at the specified \fIposition\fR. +The \fItag\fR, \fIindicator\fR and \fIfield\fR arguments are used to +to specify which part of the record that should be extracted. +Two special operators are supported: +the \fB?\fR operator matches exactly one character; +the \fB*\fR operator matches the whole item (don't care). +The format of the data returned is determined by the \fItype\fR argument. +If \fItype\fR is \fBfield\fR the matcing part of the record is returned +as a list of MARC tag specifications. Each MARC tag specification item +consists of three elements: tag, indicator and field-list. The field-list +part is a list of field specifications. Each field specification is a tuple +of field and data of the field. Setting \fItype\fR to \fBfield\fR returns +a list of elements in which each element is simply the data of the fields +that matches the specification. +An error is returned if there is no MARC record at the position. +.TP +.BI "" zs " getSutrs " position +Returns the SUTRS record at the given \fIposition\fR as a single +string token. If the record at the position is not present or is not a +SUTRS record an error is returned. +.TP +.BI "" zs " getGrs " position " [" spec " " spec " " ... "]" +Extracts information about the GRS-1 record at the specified \Iposition\fR. +The \fIspec\fR arguments determine the parts of the GRS-1 record to +be extracted. The \fIspec\fR masks the GRS-1 tag at the first level +(top-level), the second \fIspec\fR masks the GRS-1 tags at the +second-level, and so on. +Each \fIspec\fR has the format \fB(\fItag-set\fB,\fItag-value\fB)\fR, where +\fItag-type\fR specifies the tag set and the \fItag-value\fR specifies the +tag value. The GRS-1 record is returned as a Tcl list. Each element consists +of 5 elements: \fItag-set\fR, \fItag-type\fR, \fItag-value\fR, +\fIdata-type\fR, \fIdata\fR. The \fItype-type\fR is either \fBnumeric\fR or +\fBstring\fR. The \fIdata-type\fR is one of: \fBoctets\fR, \fBnumeric\fR, +\fBext\fR, \fBstring\fR, \fBbool\fR, \fBintUnit\fR, \fBempty\fR, +\fBnotRequested\fR, \fBdiagnostic\fR or \fBsubtree\fR. +.SH "SEE ALSO" +.BR ir-assoc "(n)" -- 1.7.10.4