doc/ir-assoc.n

   1 .\" Copyright (c) 1995, 1996 Index Data
   2 .\" All rights reserved.
   3 .\" $Id: ir-assoc.n,v 1.4 2002-09-16 22:16:10 adam Exp $
   4 .TH ir-assoc n  "24 June 1996" "IrTcl" "IR Association"
   5 .SH NAME
   6 ir \- IR association
   7 .SH SYNOPSIS
   8 .BI "ir " z
   9 .sp
  10 .SH DESCRIPTION
  11 The Tcl command
  12 .B ir
  13 creates an IR association, that is an object that describes the
  14 connection between an origin and a target. Initially, the association
  15 is in a non-connected state.
  16 .SH EVENTS
  17 Event-oriented operations:
  18 .TP
  19 .BI "" z " callback " event
  20 Sets the callback handler. This handler is invoked upon normal
  21 completion of requests.
  22 .TP
  23 .BI "" z " eventType"
  24 Gets the type of last event; typically used in callback handlers.
  25 One of the following events are returned: \fBconnect\fR, \fBinit\fR,
  26 \fBsearch\fR, \fBpresent\fR, \fBscan\fR or the empty string which
  27 indicates that no event has occurred (yet).
  28 .TP
  29 .BI "" z " failback " event
  30 Sets the failback handler. The failback handler is called when an
  31 unrecoverable fatal error occur, for example if the connection is lost.
  32 .TP
  33 .BI "" z " failInfo"
  34 Returns information about the latest fatal error; should be examined
  35 in failback handlers. Two elements are returned:
  36 error number and error string.
  37 .SH CONNECTIONS
  38 The operations that affect connecting to a target.
  39 .TP
  40 .BI "" z " connect [" host "]"
  41 Tries to establish a connection with the \fIhost\fR if specified.
  42 In this case, the default callback is invoked if the connect operation
  43 succeeds; otherwise, the default failback or an error is immediately issued.
  44 If the comstack setting is unknown, the
  45 operation also fails. If the \fIhost\fR is not given, the operation
  46 can be used to detect whether the assocation is connected. In this case
  47 the hostname is returned; otherwise the empty string is returned.
  48 .TP
  49 .BI "" z " disconnect"
  50 Shuts down the connection with the current target. An error is
  51 issued if there is no current connection.
  52 .TP
  53 .BI "" z " comstack [" type "]"
  54 Sets/gets the YAZ comstack. \fItype\fR is either \fBtcpip\fR (the default)
  55 or \fBmosi\fR.
  56 .TP
  57 .BI "" z " protocol [" type "]"
  58 Sets/gets the protocol type.\fItype\fR is either \fBZ39\fR (the default)
  59 or \fBSR\fR.
  60 .SH INIT
  61 The following operations concern initialization.
  62 .TP
  63 .BI "" z " init"
  64 Sends an initialize request.
  65 .TP
  66 .BI "" z " idAuthentication " " openID
  67 .TP
  68 .BI "" z " idAuthentication " " groupID userID password
  69 If one argument is passed the old-style open authentication method is
  70 used in the following initialize request - using an empty string as the
  71 authentication string prevents the (optional) authentication.
  72 If three arguments are passed the new version 3 style name/group/password
  73 scheme is used. The current authentication settings are returned
  74 as either 3 elements (name/group/password scheme), 1 element (open style)
  75 or the empty string (no password used).
  76 .TP
  77 .BI "" z " protocolVersion [" version "]"
  78 Sets/gets the protocol version: 2, 3, etc. Before an initialize-request is
  79 sent the protocol version should be set to the preferred version. After
  80 an initialize response is returned by the target the version holds
  81 the negotiated version.
  82 .TP
  83 .BI "" z " preferredMessageSize [" size "]"
  84 Sets/gets Z39.50/SR preferred-message-size; default is 30000.
  85 .TP
  86 .BI "" z " maxiumumRecordSize [" size "]"
  87 Sets/gets the Z39.50/SR maximum-record-size; default is 30000.
  88 .TP
  89 .BI "" z " implementationId"
  90 Gets the Z39.50/SR implementation-ID.
  91 .TP
  92 .BI "" z " implementationName"
  93 Gets the Z39.50/SR implementation-name.
  94 .TP
  95 .BI "" z " implementationVersion"
  96 Gets the Z39.50/SR implementation-version.
  97 .TP
  98 .BI "" z " options [" option ... "]"
  99 Sets/gets the Z39.50/SR options. These are: \fBsearch\fR, \fBpresent\fR,
 100 \fBdelSet\fR, \fBresourceReport\fR, \fBtriggerResourceCtrl\fR,
 101 \fBresourceCtrl\fR, \fBaccessCtrl\fR, \fBscan\fR, \fBsort\fR,
 102 \fBextendedServices\fR, \fBlevel-1Segmentation\fR, \fBlevel-2Segmentation\fR,
 103 \fBconcurrentOperations\fR and \fBnamedResultSets\fR.
 104 .TP
 105 .BI "" z " targetImplementationName"
 106 Gets the Z39.50/SR implementation-name of the target.
 107 .TP
 108 .BI "" z " targetImplementationId"
 109 Gets the Z39.50/SR implementation-ID of the target.
 110 .TP
 111 .BI "" z " targetImplementationVersion"
 112 Gets the Z39.50/SR implementation-version of the target.
 113 .TP
 114 .BI "" z " initResult"
 115 Gets the initialize-response status as an integer:
 116 0 if connection is rejected by the target; 1 if connection is accepted.
 117 .TP
 118 .BI "" z " userInformationField"
 119 Gets the the user-information-field; this should be inspected when
 120 the connection is rejected by the target (\fBinitResult\fR returns 0).
 121
 122 .SH "SEE ALSO"
 123 .BR ir-set "(n)", " " ir-scan "(n)"