--- /dev/null
+.\" 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)"
--- /dev/null
+.\" 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)"
projects / ir-tcl-moved-to-github.git / commitdiff