7. Extended Services
Prev | Chapter 3. ZOOM | Next

## 7. Extended Services

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

- Z39.50 Item Order (ILL). See Section 7.1, “Item Order”.

- Record Update. This allows a client to insert, modify or delete records. See Section 7.2, “Record Update”.

- Database Create. This a non-standard feature. Allows a client to create a database. See Section 7.3, “Database Create”.

- Database Drop. This a non-standard feature. Allows a client to delete/drop a database. See Section 7.4, “Database Drop”.

- Commit operation. This a non-standard feature. Allows a client to commit operations. See Section 7.5, “Commit Operation”.

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

Type | Description
--- | ---
itemorder | Item Order
update | Record Update
create | Database Create
drop | Database Drop
commit | Commit Operation

Table 3.7. Extended Service Common Options

Option | Description | Default
--- | --- | ---
package-name | Extended Service Request package name. Must be specified as part of a request. | none
user-id | User 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`
operationStatus | Read after response. One of: done, accepted or failure. Inspect with `ZOOM_pacakage_option_get`. | none
targetReference | Target Reference. This is part of the response as returned by the target. Read it after a successful operation. Inspect with `ZOOM_pacakage_option_get`. | none
taskStatus | Read after response: One of: pending, active, complete, aborted. | none
esError | Read after response: is set to diagnostic code for response. | none
esAddinfo | Read after response: is set to additional info for response. | none

### 7.1. Item Order

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

Table 3.8. Item Order Options

Option | Description | Default
--- | --- | ---
contact-name | ILL contact name | none
contact-phone | ILL contact phone | none
contact-email | ILL contact email | none
itemorder-setname | Name of result set for record | default
itemorder-item | Position for item (record) requested. An integer | 1

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

Option | Description | Default
--- | --- | ---
action | The update action. One of `specialUpdate`, `recordInsert`, `recordReplace`, `recordDelete`, `elementUpdate`. | `specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)`
recordIdOpaque | Opaque Record ID | none
recordIdNumber | Record ID number | none
recordIdString | Record ID string | none
record | The record itself | none
recordOpaque | Specifies 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
syntax | The record syntax (transfer syntax). Is a string that is a known record syntax. | no syntax
databaseName | Database from connection object | Default
correlationInfo.note | Correlation Info Note (string) | none
correlationInfo.id | Correlation Info ID (integer) | none
elementSetName | Element Set for Record | none
updateVersion | Record 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

Option | Description | Default
--- | --- | ---
databaseName | Database from connection object | Default

### 7.4. Database Drop

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

Table 3.12. Database Drop Options

Option | Description | Default
--- | --- | ---
databaseName | Database from connection object | Default

### 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.

Prev | Up | Next
6. Scan | Home | 8. Options