[Table of Contents | Previous Section | Next Section]

Appendix 8 EXT: Extended Services Defined by this Standard (Normative)

This standard defines and registers the Extended Services listed below, and assigns the following object identifiers:

PersistentResultSet {Z39-50-extendedServices 1}
PersistentQuery {Z39-50-extendedServices 2}
PeriodicQuery Schedule {Z39-50-extendedServices 3}
ItemOrder {Z39-50-extendedServices 4}
DatabaseUpdate {Z39-50-extendedServices 5}
ExportSpecification {Z39-50-extendedServices 6}
ExportInvocation {Z39-50-extendedServices 7}

EXT.1 provides service descriptions, and EXT.2 provides ASN.1 definitions.

EXT.1 Service Definitions
An Extended Service is carried out by an Extended Service (ES) task, which is invoked by an ES operation. The ES Service is described in 3.2.9.1. Execution of the ES Operation results in the creation of a task package, represented by a database record in the ES database. A task package contains parameters, some of which are common to all task packages regardless of package type, and others that are specific to the task type. Among the common parameters, some are supplied by the origin as parameters in the ES request, and others are supplied by the target.

Table A-8-1: Parameters Common to All

Common Task Package Parameter	Origin Supplied	Target Supplied
packageType	x
packageName	x (opt)
userId	x (opt)
retentionTime	x (opt)	x (opt)
permissionsList	x (opt)	x (opt)
description	x (opt)
targetReference		x (opt)
creationDateTime		x (opt)
taskStatus		x
packageDiagnostics		x (opt)

The specific parameters are derived from the ES request parameter Task-specific-parameters. Table A-8-1 provides a summary of common parameters. Their descriptions are included in 3.2.9.1. For parameters listed as both "origin supplied" and "target supplied," when both origin and target supply a value, the target supplied value overrides the origin supplied value.

EXT.1.1 Persistent Result Set Extended Service
The Persistent Result Set Extended Service allows an origin to request that the target create a persistent result from a transient result set belonging to the current Z-association. The Persistent Result Set task has no effect on the transient result set; it remains available for use by the Z-association. The persistent result set is saved for later use, during the current or a different Z-association. It may subsequently be deleted, by deletion of the task package. Note: the origin may thus cause deletion of the persistent result set, by deleting the task package, if the origin user has "delete" permission for that package. A Present (using the ResultSetName element specification), against the Persistent Result Set Parameter Package returns a Parameter Package that contains a target-supplied transient result set name, which may be used during the same Z-association wherever a result set name may be used (e.g. within a query, or in Present, Sort, or Delete request). The parameters of the Persistent Result Set Extended Service are those shown in Table A-8-1 as well as those in Table A-8-2.

Table A-8-2: Specific Parameters for Persistent Result Set

Specific Task Parameter	Origin Supplied	Target Supplied	Task Package Parameter
originSuppliedResultSet	x (if appl)
replaceOrAppend	x (if appl)
targetSuppliedResultSet		x (if appl)	x (if appl)
numberOfRecords		x (opt)	x (opt)

originSuppliedResultSet -- The origin supplies the name of a transient result set belonging to the Z-association. If function is 'create', the target is to create a persistent result set from this transient result set. If function is 'modify' the target is to either replace an existing persistent result set (corresponding to the specified package name) with this result set, or append this result set to an existing persistent result set. This parameter is mandatory when the value of the request parameter function is 'create' or 'modify', and is not included when function is 'delete'.

replaceOrAppend -- This parameter occurs when function is 'modify' (and is valid only when the origin user has "modify-contents" permission). Its value is 'replace' or 'append' meaning that the specified result set is, respectively, to replace, or to be appended to, the existing persistent result set.

targetSuppliedResultSet -- When the origin retrieves the task package, the target supplies the name of a transient result set, which then belongs to the Z-association. The result set is a copy of the persistent result set represented by the package. The target includes this parameter only when the task package is retrieved (i.e. not on an ES response) and does not include the parameter if the element set name on the Present request indicates that the parameter is not to be included.

numberOfRecords -- The target indicates the total number of records in the persistent result set.

EXT.1.2 Persistent Query Extended Service
The Persistent Query Extended Service allows an origin to request that the target save a Z39.50 Query for later reference, during the same or a subsequent Z-association. The parameters of the Persistent Query Extended Service are those shown in Table A-8-1 as well as those in Table A-8-3.

Table A-8-3: Specific Parameters for Persistent Query

Specific Task Parameter	Origin Supplied	Target Supplied	Task Package Parameter
querySpec	x
actualQuery		x	x
databaseNames	x (opt)		x (opt)
additionalSearchInformation	x (opt)		x (opt)

querySpec and ActualQuery -- The origin supplies either the query to be saved or the name of another persistent query to be copied into this package. The target supplies the actualQuery: if the origin has supplied a query, the target uses that query; if the origin supplies a task package name, the target copies the corresponding query.

databaseNames -- The origin optionally supplies a list of databases.

additionalSearchInformation -- See 3.2.2.1.12.

EXT.1.3 Periodic Query Schedule Extended Service
The Periodic Query Schedule Extended Service allows an origin to request that the target establish a Periodic Query Schedule. The origin can also request that the schedule be "activated," either as part of the initial request to create the schedule, or as part of a subsequent request to modify the schedule. The parameters of the Periodic Query Schedule Extended Service are those shown in Table A-8-1 as well as those in Table A-8-4.

activeFlag -- On a Create request, if this flag is set, the Periodic Query Schedule is to be activated immediately upon receipt and validation of its parameters; otherwise the schedule is to be Created but not activated. On a Modify request (which may contain as little as just the ActiveFlag), the origin may activate or deactivate the schedule. In the parameter package, this parameter indicates whether the schedule is active.

querySpec and ActualQuery -- The origin supplies either a query or the name of a Persistent Query Package. (If the origin supplies a query, or if the specified query package does not include a list of databases, then the databaseNames parameter is required.) The target supplies the actualQuery: if the origin has supplied a query, the target uses that query; if the origin supplies a task package name, the target copies the corresponding query.

databaseNames -- The origin may supply a list of databases; the list is required if the origin supplied a query rather than a query package name for querySpec, or if the specified query package does not include a list of databases.

period -- The time period between invocations of the query. The target may override the period specified by the origin. Period may be a number of days, a frequency (e.g. daily, business daily, weekly, monthly), or 'continuous', meaning the search is to be run continuously (or at the target's discretion).

expiration -- The origin may optionally supply a time/date for the target to discontinue execution of this Periodic Query. If the origin does not supply a value, the origin is proposing "no expiration." The target may override the origin supplied value. If the origin supplies a value and the target does not support expiration, the target should reject the ES request.

resultSetPackageName -- The origin may optionally supply the name of an existing Persistent Result Set package. If the origin omits this parameter, the target is to create a persistent result set, unless the parameter exportParameters is included.

resultSetDisposition -- This parameter takes on the value 'createNew', 'replace', or 'append', indicating respectively whether the target is to create a new result set each time the query is invoked, replace the contents of the existing result set, or append any new results to the end of the result set. The value 'createNew' should be used only if the origin and target have an agreement about naming conventions for the resulting package. If the value of the parameter Period is 'continuous' it is recommended that the value of this parameter be 'append'. The value 'append' allows the target to continually extend the result set by appending new records.

alertDestination -- The origin may optionally supply a destination address for Alerts triggered by receipt of new Periodic Query results (e.g, fax number, X.400 address, pager number).

exportParameters -- The origin may optionally supply the name, or actual contents, of an Export Parameter Package to be used with this Periodic Query. It is included only if the origin wants newly posted results to be exported; if so, new results may also be posted to ResultSetName if also specified.

lastQueryTime -- The target indicates the last time this Periodic Query was invoked.

lastResultNumber -- The target indicates the number of new records obtained last time query was invoked.

numberSinceModify -- The target indicates the total number of records obtained via invocation of the Query since the last time this Periodic Query Package was modified.

EXT 1.4 Item Order Extended Service
The Item Order Extended Service allows an origin to submit an item order request to the target. The parameters of the Item Order Extended Service are those shown in Table A-8-1 as well as those in Table A-8-5.

requestedItem -- The origin identifies the requested item, either by: (a) a request whose format is defined externally, and which may be an Interlibrary Loan Request APDU of ISO 10161; or (b) a result set item (name of a transient result set belonging to the current Z-association and an ordinal number of an entry within that result); or (c) both.

itemRequest -- If requestedItem is (a) (e.g. an interlibrary loan request), the target copies it into the task package (although the target might first modify the request). If requestedItem is (b), the target may construct a corresponding item request; if it does not, then the requested item will not be identified within the task package.

supplementalDescription -- The origin may supply additional descriptive information pertaining to the requested item, as a supplement to requestedItem.

contactInformation -- The origin may optionally supply a name, phone number, and electronic mail address of a contact-person.

additionalBillingInfo -- The origin may optionally indicate payment method, credit card information, customer reference, and customer purchase order number.

statusOrErrorReport -- The target supplies a status or error report. The definition of the report is external to this standard, and may be based on the StatusOrErrorReport APDU of the ILL protocol.

auxiliaryStatus -- The target may provide an auxiliary status as a supplement to the status information which might be provided by the statusOrErrorReport.

EXT 1.5 Database Update Extended Service
[Note: for revised version of Database Update Extended Service definition see Update Extended Service ASN.1 Definition -- Revision 1]
The database Update Extended Service allows an origin to request that the target update a database: insert new records, replace or delete existing records, or update elements within records. Note: this service definition does not address concurrency; if multiple users try to update the same record, it may be that only the first request served by the target will update the intended data, and the remaining requests may update a record whose content has changed. The parameters of the databaseUpdate Extended Service are those shown in Table A-8-1 as well as those in Table A-8-6.

action -- The origin indicates recordInsert, recordReplace, recordDelete, or elementUpdate.

databaseName -- The origin indicates the database to which the action pertains.

schema -- The origin indicates the database schema that applies for this update. Note: The action, databaseName, and schema are specified once, and apply to all of the included records.

suppliedRecords -- The origin supplies one or more records. (Along with each the origin may also supply a recordId, supplemental identification, and correlation information; see following three parameters.) For recordInsert or recordReplace, the origin supplies whole records. For recordReplace or recordDelete, each supplied record (or corresponding supplemental identification or recordId) must include sufficient information for the target to identify the database record. For recordDelete, sufficient identifying information should be supplied for each record, but the whole record need not necessarily be supplied. For elementUpdate, the elements within a supplied record are to replace the corresponding elements within the database record, and the remainder of the database record is unaffected. Records must be supplied in a manner that allows the corresponding elements in the database record to be identified (e.g., via tags defined by the schema). For any element within a supplied record, if there is no corresponding element within the database record, if there is more than a single occurrence of the corresponding element, or if the element is not sufficiently identified, the update will not be performed for that record. (For elementUpdate, supplementalId may be used for identification of the record, but not for identification of elements.)

recordIds -- Corresponding to each supplied record the origin may optionally supply a record Id.

supplementalIds -- Corresponding to each supplied record the origin may supply supplemental identification to allow the target to identify the database record, or to identify the correct version of the database record. This may be a timestamp, a version number, or may take some other form, for example, a previous version of the record.

CorrelationInfo -- Corresponding to each supplied record, the origin may include one or both of the following:

• a correlationNote,
• a correlationIdentifier.

The correlationIdentifier may be used to identify the record only within the context of this update task, for correlation purposes only (i.e to correlate a task package record with its corresponding supplied record). It may be used in the task package in lieu of a record id, for a record that might not have an unambiguous record id.

ElementSetName -- The origin indicates an element set name indicating which elements of the updated records are to be included in the task package. If omitted, updated records are not to be included in the task package.

updateStatus -- This parameter occurs in the task package only when taskStatus is 'complete' or 'aborted'. It is one of the following: Success - Update performed successfully. Partial - Update failed for one or more records. Failure - Target rejected execution of the task (one or more non-surrogate diagnostics should be supplied in parameter globalDiagnostics).

globalDiagnostics -- One or more non-surrogate diagnostics, supplied if updateStatus is Failure.

taskPackageRecords -- When taskStatus is 'complete': the task package includes a structure for each supplied record. The structure may include part or all of the updated record (depending on 'elementSetName') or a surrogate diagnostic (when recordStatus, below, is 'failure'), as well as correlationInfo and record status (see next parameter). When taskStatus is 'pending' or 'active': the task package includes the above for each record for which update action is complete. For those records for which action is not complete, the structure includes the correlationInfo and status.

recordStatuses -- Corresponding to each task package record, the task package includes a record status: success - The record was updated successfully. queued - The record is queued for update, or the update is in process (this status may be used in lieu of inProcess, when the target does not wish to distinguish between these two statuses). inProcess - The update for this record is in process. failure - The update for this record failed. A surrogate diagnostic should be supplied in lieu of the record (within the structure corresponding to the record, within the parameter taskPackageRecords).

EXT 1.6 Export Specification Extended Service
The Export Specification Extended Service allows an origin to request that the target establish an export specification. Once established, the export specification may be subsequently invoked (repeatedly) by an Export Invocation Extended Services task; in fact, multiple invocations may be running simultaneously. An Export Specification includes a delivery destination as well as other information that controls the delivery of a unit of information (one or more result set records). The destination might be a printer or some other device. The delivery mechanism could include fax, electronic mail, file transfer, or a target-supported print device. The parameters of the Export Specification Extended Service are those shown in Table A-8-1 as well as those in Table A-8-7.

composition -- This parameter consists of a record syntax, element specification, variants, etc. of the records to be Exported.

exportDestination -- The origin indicates an address or other destination instruction (e.g. e-mail address, printer address, fax number).

EXT 1.7 Export Invocation Extended Service
The Export Invocation Extended Service allows an origin to invoke an export specification. The origin may supply an export specification, or the name of an export specification that has been established by an Export Specification task as described in EXT 1.6. The parameters of the Export Invocation Extended Service are those shown in Table A-8-1 as well as those in Table A-8-8.

exportSpecification -- The origin supplies the packageName, or actual contents, of an export specification.

resultSetId -- The origin supplies the name of a transient result set, from which records are selected for export.

resultSetRecords -- The origin indicates which records are to be exported. This parameter may specify that all records in the result set are to be exported, or it may specify a set of ranges of result set records, in which case the last range may indicate that all records beginning with a specific record are to be exported.

numberOfCopies -- The origin indicates the number of copies requested.

estimatedQuantity and quantitySoFar -- The target optionally indicates the number of pages, message packets, etc., estimated in the information to be exported, and the actual amount exported so far.

estimatedCost and costSoFar -- The target optionally supplies an estimate of the cost to export this information, and the cost accrued so far.

EXT.2 ASN.1 Definitions of Extended Services Parameter Package
Each definition below corresponds to an individual extended service. Each structure occurs within an ES request or as a task package. Correspondingly, each is defined as a CHOICE of 'esRequest' and 'taskPackage'. If the structure occurs within an ES request, it occurs as the parameter taskSpecificParameters.

The structure may occur as a task package either within an ES response (the parameter taskPackage), or in a record retrieved from an ES database, within the parameter taskSpecificParameters within the structure defined by the record syntax ESTaskPackage; see Appendix 5, REC.6. 'esRequest' consists of all service parameters supplied by the origin in the ES request; these are divided into those that are and those that are not to be retained in the task package; 'toKeep' and 'notToKeep'. 'taskPackage' consists of all specific task parameters; which are divided into those supplied by the origin and those supplied by the target, i.e., 'originPart' and 'targetPart'.

Note that 'toKeep' (from 'esRequest') is always the same sub-structure as 'originPart' (from taskPackage), so that structure is shared, in OriginPartToKeep. Each definition may define one or more of OriginPartToKeep, OriginPartNotToKeep, and TargetPart. In EXT.1, in the parameter table in the service definition for a specific ES, for each parameter:

• If the parameter is marked "origin supplied," but is not marked in the right column (i.e. it does not occur in the task parameter package) then that parameter is represented in OriginPartNotToKeep.
• If the parameter is marked "origin supplied," and also marked in the right column, then that parameter is represented in OriginPartToKeep.
• If the parameter is marked "target supplied" (in which case it will always also be marked in the right column), and not also marked "origin supplied" then that parameter is represented in TargetPart.
• If the parameter is marked "origin supplied," and also marked "target supplied" (in which case it will be marked in the right column), then it is a para-meter for which the origin may suggest a value and the target may override that value. In this case the origin suggested value is represented in OriginPartNotToKeep and the target value (which may be the same) is represented in TargetPart.

ESFormat-PersistentResultSet

[Link to ESFormat-PersistentResultSet]

ESFormat-PersistentQuery

[Link to ESFormat-PersistentQuery]

ESFormat-PeriodicQuerySchedule

[Link to ESFormat-PeriodicQuerySchedule]

ESFormat-ItemOrder

[Link to ESFormat-ItemOrder]

ESFormat-Update

[link to ESFormat-Update]

ESFormat-ExportSpecification

[Link to ESFormat-ExportSpecification]

ESFormat-ExportInvocation

[Link to ESFormat-ExportInvocation]