[Table of Contents | Previous Section | Next Section]

3.2.9 Extended Services Facility
The Extended Services facility consists of a single service, Extended-services.

3.2.9.1 Extended Services Service
The Extended-Services (ES) service allows an origin to create, modify, or delete a task package at the target. The target maintains task packages in a special database, described in section 3.2.9.2. A task package pertains to an ES task.

An extended service is a task type, related to information retrieval, but not defined as a Z39.50 service. Execution of a task by the target is outside the scope of Z39.50. The extended services defined by this standard are listed in section 3.2.9.1.2. Definitions of those services are included in Appendix 8 EXT.

The origin sends an ES Request to the target requesting execution of a task. The request includes parameters which the target uses to construct the task package. The target checks the request for validity, for consistency with the user's access privileges, and possibly for other target-dependent limitations. The target sends an ES response indicating that the request was accepted or supplying an indication of the reason the request was rejected.

The ES service is a confirmed service, initiated by the origin. The ES operation consists of a request from the origin and a response from the target, possibly with intervening Access-control or Resource-control messages. However, although the request may result in the initiation of a task, the task is not considered part of the Z39.50 ES operation. The target response, which completes the ES operation, does not necessarily signal completion of the task. A task may have a lifetime that exceeds a single Z-association.

Execution of the ES Operation results in the creation of a task package, represented by a database record in the ES database.

For example, when a target creates a task package of type PersistentResultSet, a (persistent) result set is created, represented by the created task package, in the form of a record in the extended services database. When that package is subsequently retrieved by an origin, in either the same or a different Z-association, a copy of that persistent result set is made available to that Z-association, as a Z39.50 result set (i.e. as a transient result set; a result set name, for use during the Z-association, is included within the task package). When an origin deletes the task package, the persistent result set is deleted.

A task package contains parameters, some of which are common to all task packages regardless of package type, and others which are specific to the particular extended service. Among the common parameters (indicated in the table below, listed under "task package parameter" in the right column), some are supplied by the origin as parameters in the ES request, and are used by the target to form the task package; some of those supplied by the origin may be overridden by the target. Others are supplied by the target. The specific parameters are derived from the parameter Task-specific-parameters of the ES request (see Appendix 8 EXT).

Note: The response parameter Task-package below refers to the actual task package, and if it occurs (see 3.2.9.1.13), it includes some or all (depending on the parameter Elements) of the parameters listed under "task package parameter."

Table 13: Parameters of the Extended Services Service

3.2.9.1.1 Function. The origin specifies Create, Delete, or Modify.

If the function is Create, the target is to create a task package, and assign to it the name specified by the parameter Package-name, if supplied.

If the function is Delete or Modify, the target is to delete or modify the task package specified by the parameter Package-name. A target that supports deletion or modification may nonetheless deny the request, for example because the task is already in progress, or the package is in use.

If the function is Delete, the origin requests that if the specified task has not been acted on, it should not be started; if the task is active, the target should either terminate the task or refuse the request.

If the function is Modify, the origin requests that parameter values in the request (as well as those within parameter Task-specific-parameters) replace the corresponding values in the task package. If an optional parameter is omitted, the target does not modify that parameter within the task package (thus to return a parameter to its default value, an origin must explicitly provide the default value).

3.2.9.1.2 Package-type. The Package-type identifies the extended service requested. The extended services defined by this standard (see Appendix 8 EXT) are:

• Save a result set for later use
• Save a Query for later use
• Define a periodic search schedule
• Order an item
• Update a database
• Create an export specification
• Invoke a previously created export specification

3.2.9.1.3 Package-name. The origin may optionally supply a name for the task package to be created. If so, the triple (Package-type, User-id, Package-name) must be unique (i.e. there must be no other task package of that type, for that user with the same name, otherwise the request is in error), and that triple identifies the task package for subsequent reference. Package-name should be included if the origin intends to reference the task package.

3.2.9.1.4 User-id. The User-id identifies the user to be associated with the task package. If not supplied, this parameter may default to the Id of the current user. A target may or may not allow an origin to supply a user id different from its own.

3.2.9.1.5 Retention-time. The origin may optionally specify a retention period (e.g., 2 hours, 3 days, 1 week), which may be overridden by the target. When the retention time has passed, the target may delete the retained task package. A retention time of zero means the task package is not to be retained after the task is completed.

3.2.9.1.6 Permissions. The origin may indicate who may access the task package. If the origin does not supply this parameter, only the creating user may do so. See 3.2.9.3.

3.2.9.1.7 Description. The origin may include a description. It might describe, for example, the result set, for a Persistent Result Set task; or the query, for a Persistent Query task.

3.2.9.1.8 Target-reference. The target may supply a unique identifier for the task package.

3.2.9.1.9 Creation-date-time. The target supplies the date and time that the task package was created.

3.2.9.1.10 Task-status. The target indicates the status of the task. Values are 'pending,' 'active,' 'complete,' and 'aborted'.

3.2.9.1.11 Package-diagnostics. The target may include one or more diagnostics in the task package.

3.2.9.1.12 Task-specific-parameters. These are additional parameters, defined by the specific extended service.

3.2.9.1.13 Wait-action. The origin indicates whether the target should (or may) include the task package in the ES response. This immediate response mechanism may avoid the need for follow-up Search and Present operations, or in general, for making the task package available through the extended services database (see section 3.2.9.2).

This parameter has four possible values:

• wait: the target must perform the task before issuing the ES response (unless the operation aborts; see section 3.2.9.4). If the target is not willing to perform the task before issuing the response it must refuse the request by responding with a status of 'failure' and an appropriate diagnostic. If the target accepts the request, it includes the parameter Task-package in the response.
• wait-if-possible: the origin requests that, if possible, the target perform the task before issuing the ES response and include the task package in the response. If not possible, the target should proceed as though the value were 'do not wait'.
• do-not-wait: The origin does not request that the target attempt to perform the task before issuing the ES response. However, if the target does perform the task before issuing the response, then the response may include the task package.
• do-not-send-task-package: The target may perform the task when it chooses, but is not to include the task package in the response under any circumstance.

3.2.9.1.14 Elements. The origin may optionally include this parameter if Wait-action is other than 'do-not-sent-task-package'. It is an element set name for the task package, in the event that it is returned in the response parameter Task-package.

3.2.9.1.15 Operation-status. This is the status of the ES operation. It is one of the following:

done - The request was accepted, the task is complete and results are included in Task-package.
accepted - The request was accepted and the task is queued for processing, or is in process.
failure - The request was refused. One or more diagnostics are supplied (in parameter Operation-diagnostics).

3.2.9.1.16 Operation-diagnostics. The target may supply additional diagnostic information if Operation-status is 'failure'.

3.2.9.1.17 Task-package. If Operation-status is 'done,' the target includes the task package. The portion of the actual task package included depends on the parameter Elements.

3.2.9.1.18 Other-Information. This parameter may be used by the origin or target for additional information, not specified by the standard.

3.2.9.1.19 Reference-id. See section 3.4.

3.2.9.2 The Extended Services Database
Targets that support the Extended Services facility provide access to a database with the name IR-Extend-1 (referred to as the "extended services database" or "ES database"). Records in the extended services database are task packages constructed from the Request-parameter-package parameter in ES requests (the target may begin execution of the task at any time after it accepts the request, which may be before the task package has been stored in the database). The target may (but need not) retain a task package until the requested task has completed; it may retain the task package until the origin requests that it be deleted. A target may unilaterally delete a task package from the ES Database at any time.

Note: This means, as a practical matter, the target need not actually create a task package for a given task, in particular, when the task is executed immediately. However, it is recommended that a task package exist when the status of the task is pending, active, or aborted.

When the target receives an ES request it may immediately create a task package, with status 'pending,' before completely validating the request. The origin may thus search the database anytime after submitting a request (during the same or a subsequent Z-association), for a r esulting task package. In particular, if an ES operation is aborted (see 3.2.9.4) the origin may be able to determine that the request for that operation was received.

An ES database may be listed in the target Explain database, with a list of extended services the target supports, allowable export destinations, options that an origin may supply for an export task, etc.

An extended services database will appear to the origin as any other database supported by the target (records may be searched and retrieved by the Z39.50 Search and Retrieval facilities; search processing is defined locally by the target; the target may impose access control or exclude records to which the origin is not authorized access). However, certain search terms are predefined in order to allow a semantic level of interoperability. The attribute set used to search the database is defined and registered in Appendix 3 ATR. The task package structures are defined and registered in Appendix 8 EXT.

The ES database may provide the following special element sets (in addition to "F"):

• Identification: includes the creating user's identification, the origin-supplied name of the task package, and possible permissions for other users to access the request. Other identifying information such as time of creation may be included.
• UniqueName: the creating user's identification and the name of the task package.
• Permissions: the contents of the UniqueName element set, and in addition, the granted permissions for the task package. A target might present the full permissions list only to the task package creator, presenting to other users only the permissions applicable to them.
• Status: a short summary of the current status of the request, perhaps including cost and other resource usage.
• Brief: Identification element set plus the most important elements of the Status element set.

3.2.9.3 Owners and Permissions
The creating user of a task package may apply any extended service function to the package, as well as retrieve the full package (via the Retrieval facility) and invoke the package via other extended services. (Invocation occurs, for example, when a Periodic Query task references a saved Query.)

Using the Modify function of the ES request, an origin can change the access permissions of a task package by supplying a new permissions list, which is a sequence of user ids and for each, a sequence of allowed operations, from the following set:

• Delete
• Modify-Contents
• Modify-Permissions
• Present
• Invoke.

As an example of the use of the 'invoke' permission, a target might create a task package, on behalf of a client user, of type PersistentQuery; a persistent query is created, represented by the created task package. The target may subsequently be requested to create a PeriodicQuerySchedule task package, on behalf of a different user, which refers to (i.e. "invokes") that persistent query task package. The target would do so only if that user has 'invoke' privilege for that persistent query. As another example, a target may create an ExportSpecification (package) on behalf of one user, and a different user may subsequently 'invoke' that ExportSpecification by creating an InvokeExportSpecification package, if that user has 'invoke' privilege for the ExportSpecification.

Targets may provide group names for use in permission lists, but a group name would be syntactically the same as a user Id. (The target might report the composition of groups, but the mechanism for doing so is not described by this standard.)

3.2.9.4. Aborted Operations

An origin may receive a response to an ES request only during the Z-association in which it issues the request (as for any other Z39.50 operation). If an ES operation is aborted (explicitly, or because the Z-association is closed or the A-association terminated), the origin will not receive a terminating response. This has no effect on the disposition or processing of the task, regardless of the value of Wait-action that was specified on the request. If an ES operation aborts, Wait-action automatically assumes the value 'do-not-send-task-package'.

If an ES operation is aborted, the origin may search the ES database (possibly in a subsequent Z-association) for information that would otherwise have been returned in the response.