The ir object describes an association with a target.
This section covers the connect-init-disconnect actions provided
by the ir object.
An ir object is created by the ir
command and the
created object enters a 'not connected' state, because it isn't
connected to a target yet.
A connection is established by the connect
action which is
immediately followed by a hostname. A number of settings affect the
connect
action. Obviously, these settings should be set
before connecting. The settings are:
comstack
mosi|tcpip
Comstack type. Note that mosi
is no longer supported by YAZ.
protocol
Z39|SR
Protocol type - ANSI/NISO Z39.50 or ISO SR. Note, that SR is no longer supported by YAZ.
callback
listTcl script called when the connection is established.
failback
listFatal error Tcl script. Called on protocol errors or if target closes connection.
If the connect is unsuccessful either the connect action itself will return an error code or the failback handler is invoked.
In general, the failback
handler is invoked when serious
unrecoverable errors occur when communicating with the target.
In this case the failback
handler might inspect the failInfo
setting to determine the cause of the failure; it returns
two elements. The first is an error integer; the second is an
english representation of the error. The error codes and
the corresponding messages are:
0
ok
1
connect failed
2
connection closed
3
connection closed
4
failed to decode incoming APDU
5
unknown APDU
Note: in case 3 the connection was closed during read a read operation whereas in case 4 it was closed during a write operation.
If the connect operation succeeds the init
action should be used.
The init related settings are:
preferredMessageSize
integerPreferred-message-size. Default value is 30000.
maximumRecordSize
integerMaximum-record-size. Default value is 30000.
idAuthentication
string ...Id-authentication. There are three forms. If any empty is given, the Id-authentication is not used. If one non-empty string is given, the 'open' authentication is used. If three strings are specified, the version 'id-pass' authentication (version 3 only) is used in which case the first string is groupId; the second string is userId and the third string is password.
implementationName
stringImplementation-name of origin system.
implementationId
Implementation-id of origin system. This setting is read-only.
implementationVersion
Implementation-version of origin system. This settings is read-only.
options
listOptions to be negotiated in the init service. The list contains
the options that are set. Possible values are search
,
present
, delSet
, resourceReport
,
triggerResourceCtrl
, resourceCtrl
,
accessCtrl
, scan
, sort
,
extendedServices
, level-1Segmentation
,
level-2Segmentation
, concurrentOperations
and
namedResultSets
. Currently the default options are:
search
, present
, scan
and
namedResultSets
. The options
setting is set to its default
value when an ir object is created and when a disconnect
action is performed.
protocolVersion
integerProtocol version: 2, 3, etc. Default is 2.
referenceId
stringReference-id of init operation. If string is empty no reference-id is used.
initResponse
listInit-response Tcl script.
callback
listGeneral response Tcl script. Only used if initResponse
is not specified.
The init-response handler should inspect some of the settings shown below:
initResult
returns booleanInit response status. True if init operation was successful; false otherwise.
preferredMessageSize
returns integerPreferred-message-size after negotiation.
maximumRecordSize
returns integerMaximum-record-size after negotiation.
targetImplementationName
returns stringImplementation-name of target system.
targetImplementationId
returns stringImplementation-id of target system.
targetImplementationVersion
returns stringImplementation-version of target system.
options
returns listOptions after negotiation. The list contains the options that are set.
protocolVersion
returns integerProtocol version: 2, 3, etc after negotiation.
userInformationField
returns stringUser information field.
referenceId
returns stringReference-id of init response.
Example
Consider a client with the ability to access multiple targets.
We define a list of targets that we wish to connect to. Each item in the list describes the target parameters with the following four components: association-name, comstack-type, protocol-type and a hostname.
The list for the two targets: Library of Congress and Z39.50 target Data Research, will be defined as:
set targetList { {loc tcpip Z39 z3950.loc.gov:7090}
{drs tcpip Z39 dranet.dra.com} }
The Tcl code below defines, connect and initialize the
targets in targetList
:
foreach target $targetList {
set assoc [lindex $target 0]
ir $assoc
$assoc comstack [lindex $target 1]
$assoc protocol [lindex $target 2]
$assoc failback [list fail-response $assoc]
$assoc callback [list connect-response $assoc]
$assoc connect [lindex $target 3]
}
proc connect-response {assoc} {
$assoc callback [list init-response $assoc]
$assoc init
}
proc fail-response {assoc} {
puts "$assoc closed connection or protocol error"
}
proc init-response {assoc} {
if {[$assoc initResult]} {
puts "$assoc initialized ok"
} else {
puts "$assoc didn't initialize"
}
}
target
is bound to each item in the list of targets.
The assoc
is set to the ir object name.
Then, the comstack, protocol and failback are set for the assoc
object.
The ir object name is argument to the fail-response
and
connect-response
routines.
Note the use of the Tcl list
command which
is necessary here because the argument contains variables
(assoc
) that should be substituted before the handler is defined.
After the connect operation, the init-response
handler
is defined in much the same way as the failback handler.
And, finally, an init request is executed.
End of example
To terminate the connection the disconnect
action should be used.
This action has no parameters.
Another connection may be established by a new connect
action on
the same ir object.