Next Previous Contents

4. Associations

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.

4.1 Connect

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 list

Tcl script called when the connection is established.

failback list

Fatal 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 IrTcl system shuts down the connection. 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.

4.2 Init

If the connect operation succeeds the init action should be used. The init related settings are:

preferredMessageSize integer

Preferred-message-size. Default value is 30000.

maximumRecordSize integer

Maximum-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 string

Implementation-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 list

Options 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 integer

Protocol version: 2, 3, etc. Default is 2.

referenceId string

Reference-id of init operation. If string is empty no reference-id is used.

initResponse list

Init-response Tcl script.

callback list

General response Tcl script. Only used if initResponse is not specified.

The init-response handler should inspect some of the settings shown below:

initResult returns boolean

Init response status. True if init operation was successful; false otherwise.

preferredMessageSize returns integer

Preferred-message-size after negotiation.

maximumRecordSize returns integer

Maximum-record-size after negotiation.

targetImplementationName returns string

Implementation-name of target system.

targetImplementationId returns string

Implementation-id of target system.

targetImplementationVersion returns string

Implementation-version of target system.

options returns list

Options after negotiation. The list contains the options that are set.

protocolVersion returns integer

Protocol version: 2, 3, etc after negotiation.

userInformationField returns string

User information field.

referenceId returns string

Reference-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

4.3 Disconnect

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.


Next Previous Contents