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|tcpipComstack type.
protocol Z39|SRProtocol type - ANSI/NISO Z39.50 or ISO SR.
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:
0ok
1connect failed
2connection closed
3connection closed
4failed to decode incoming APDU
5unknown 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.
implementationIdImplementation-id of origin system. This setting is read-only.
implementationVersionImplementation-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: ISO/SR target DANBIB and TCP/Z39.50 target Data Research, will be defined as:
set targetList { {danbib mosi SR 0103/find2.denet.dk:4500}
{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.