7. Extended Services

ZOOM offers an interface to a subset of the Z39.50 extended services as well as a few privately defined ones:

To create an extended service operation, a ZOOM_package must be created. The operation is a five step operation. The package is created, package is configured by means of options, the package is sent, result is inspected (by means of options), the package is destroyed.

    ZOOM_package ZOOM_connection_package(ZOOM_connection c,
                                         ZOOM_options options);

    const char *ZOOM_package_option_get(ZOOM_package p,
                                        const char *key);
    void ZOOM_package_option_set(ZOOM_package p, const char *key,
                                 const char *val);
    void ZOOM_package_send(ZOOM_package p, const char *type);

    void ZOOM_package_destroy(ZOOM_package p);
   

The ZOOM_connection_package creates a package for the connection given using the options specified.

Functions ZOOM_package_option_get and ZOOM_package_option_set gets and sets options.

ZOOM_package_send sends the package the via connection specified in ZOOM_connection_package. The type specifies the actual extended service package type to be sent.

Table 3.6. Extended Service Type

TypeDescription
itemorderItem Order
updateRecord Update
createDatabase Create
dropDatabase Drop
commitCommit Operation

Table 3.7. Extended Service Common Options

OptionDescriptionDefault
package-nameExtended Service Request package name. Must be specified as part of a request.none
user-idUser ID of Extended Service Package. Is a request option.none
function Function of package - one of create, delete, modify. Is a request option. create
waitAction Wait action for package. Possible values: wait, waitIfPossible, dontWait or dontReturnPackage. waitIfPossible
targetReference Target Reference. This is part of the response as returned by the server. Read it after a successful operation. none

7.1. Item Order

For Item Order, type must be set to itemorder in ZOOM_package_send.

Table 3.8. Item Order Options

OptionDescriptionDefault
contact-nameILL contact namenone
contact-phoneILL contact phonenone
contact-emailILL contact emailnone
itemorder-setnameName of result set for recorddefault
itemorder-itemPosition for item (record) requested. An integer1

There are two variants of item order: ILL-variant and XML document variant. In order to use the XML variant the setting doc must hold the XML item order document. If that setting is unset, the ILL-variant is used.

Table 3.9. ILL Request Options

Option
protocol-version-num
transaction-id,initial-requester-id,person-or-institution-symbol,person
transaction-id,initial-requester-id,person-or-institution-symbol,institution
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-person
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-institution
transaction-id,transaction-group-qualifier
transaction-id,transaction-qualifier
transaction-id,sub-transaction-qualifier
service-date-time,this,date
service-date-time,this,time
service-date-time,original,date
service-date-time,original,time
requester-id,person-or-institution-symbol,person
requester-id,person-or-institution-symbol,institution
requester-id,name-of-person-or-institution,name-of-person
requester-id,name-of-person-or-institution,name-of-institution
responder-id,person-or-institution-symbol,person
responder-id,person-or-institution-symbol,institution
responder-id,name-of-person-or-institution,name-of-person
responder-id,name-of-person-or-institution,name-of-institution
transaction-type
delivery-address,postal-address,name-of-person-or-institution,name-of-person
delivery-address,postal-address,name-of-person-or-institution,name-of-institution
delivery-address,postal-address,extended-postal-delivery-address
delivery-address,postal-address,street-and-number
delivery-address,postal-address,post-office-box
delivery-address,postal-address,city
delivery-address,postal-address,region
delivery-address,postal-address,country
delivery-address,postal-address,postal-code
delivery-address,electronic-address,telecom-service-identifier
delivery-address,electronic-address,telecom-service-addreess
billing-address,postal-address,name-of-person-or-institution,name-of-person
billing-address,postal-address,name-of-person-or-institution,name-of-institution
billing-address,postal-address,extended-postal-delivery-address
billing-address,postal-address,street-and-number
billing-address,postal-address,post-office-box
billing-address,postal-address,city
billing-address,postal-address,region
billing-address,postal-address,country
billing-address,postal-address,postal-code
billing-address,electronic-address,telecom-service-identifier
billing-address,electronic-address,telecom-service-addreess
ill-service-type
requester-optional-messages,can-send-RECEIVED
requester-optional-messages,can-send-RETURNED
requester-optional-messages,requester-SHIPPED
requester-optional-messages,requester-CHECKED-IN
search-type,level-of-service
search-type,need-before-date
search-type,expiry-date
search-type,expiry-flag
place-on-hold
client-id,client-name
client-id,client-status
client-id,client-identifier
item-id,item-type
item-id,call-number
item-id,author
item-id,title
item-id,sub-title
item-id,sponsoring-body
item-id,place-of-publication
item-id,publisher
item-id,series-title-number
item-id,volume-issue
item-id,edition
item-id,publication-date
item-id,publication-date-of-component
item-id,author-of-article
item-id,title-of-article
item-id,pagination
item-id,ISBN
item-id,ISSN
item-id,additional-no-letters
item-id,verification-reference-source
copyright-complicance
retry-flag
forward-flag
requester-note
forward-note

7.2. Record Update

For Record Update, type must be set to update in ZOOM_package_send.

Table 3.10. Record Update Options

OptionDescriptionDefault
action The update action. One of specialUpdate, recordInsert, recordReplace, recordDelete, elementUpdate. specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)
recordIdOpaqueOpaque Record IDnone
recordIdNumberRecord ID numbernone
recordThe record itselfnone
recordOpaqueSpecifies an opaque record which is encoded as an ASN.1 ANY type with the OID as given by option syntax (see below). Option recordOpaque is an alternative to record - and record option (above) is ignored if recordOpaque is set. This option is only available in YAZ 3.0.35 and later, and is meant to facilitate Updates with servers from OCLC. none
syntaxThe record syntax (transfer syntax). Is a string that is a known record syntax. no syntax
databaseNameDatabase from connection objectDefault
correlationInfo.noteCorrelation Info Note (string)none
correlationInfo.idCorrelation Info ID (integer)none
elementSetNameElement Set for Recordnone
updateVersionRecord Update version which holds one of the values 1, 2 or 3. Each version has a distinct OID: 1.2.840.10003.9.5 (first version) , 1.2.840.10003.9.5.1 (second version) and 1.2.840.10003.9.5.1.1 (third and newest version). 3

7.3. Database Create

For Database Create, type must be set to create in ZOOM_package_send.

Table 3.11. Database Create Options

OptionDescriptionDefault
databaseNameDatabase from connection objectDefault

7.4. Database Drop

For Database Drop, type must be set to drop in ZOOM_package_send.

Table 3.12. Database Drop Options

OptionDescriptionDefault
databaseNameDatabase from connection objectDefault

7.5. Commit Operation

For Commit, type must be set to commit in ZOOM_package_send.

7.6. Protocol behavior

All the extended services are Z39.50-only.

Note

The database create, drop, and commit services are privately defined operations. Refer to esadmin.asn in YAZ for the ASN.1 definitions.