[Table of Contents | Previous Section | Next Section]

3.2.4 Result-set-delete Facility
The Result-set-delete facility consists of a single service, Delete.

Table 5: Parameters of the Delete Service

3.2.4.1 Delete Service
The Delete service enables an origin to request that the target delete specified result sets, or all result sets, created during the Z-association. The target responds by reporting information pertaining to the result of the operation.

list - delete specified result sets (see 3.2.4.1.2), or

bulk-delete - delete all result sets currently on the target created during this Z-association.

3.2.4.1.2 Result-set-list. This parameter occurs if and only if Delete-function is 'list'. It contains a list of result sets (created during this Z-association) to be deleted.

3.2.4.1.3 Delete-operation-status. Delete-operation-status is the status of the delete request. It assumes one of the values 'success' or 'failure-3' through 'failure-9' in the table below.

3.2.4.1.4 Delete-list-statuses. Delete-list-statuses is present in a Delete response if Delete-function in the request was 'list'. Delete-list-statuses contains the same list of result sets as in the Result-set-list parameter of the Delete request, each paired with a status. Possible status values are 'success,' 'failure-1' through 'failure-6,' and 'failure-10'.

Table 6: Delete Statuses

Notes:
1. failure-7 and failure-8 can occur only if Delete-operation is Bulk-delete
2. failure-10 may be used only when version 3 is in force

3.2.4.1.5 Number-not-deleted and Bulk-statuses. These two parameters occur only if Delete-function is Bulk-delete and if Delete-operation-status = 'failure-8'. The parameter Number-not-deleted indicates how many result sets were not deleted, and the parameter Bulk-statuses gives individual statuses for those not deleted.

Note, however, that a target is not obligated to provide statuses for each result set not deleted on a bulk delete. For example, a target may abort a bulk delete when the first failure to delete a result set that is part of the bulk delete fails; in this case only a single status might be included in the parameter Bulk-statuses.

If a bulk delete results in more statuses than can fit into a single Delete-response message, the target may discard those that do not fit.

3.2.4.1.6 Delete-msg. Delete-msg, if present, contains an optional text message.

3.2.4.1.7 Other-information. This parameter may be used by either the origin or target for additional information not specified by the standard. This parameter may be used only when version 3 is in force.

3.2.4.1.8 Reference-id. See 3.4.

3.2.5 Access Control Facility
The Access Control facility consists of a single service, Access-control.

3.2.5.1 Access-control Service
The Access-control service allows a target to challenge an origin. The challenge might pertain to a specific operation or to the Z-association. The Access-control request/response mechanism can be used to support access control challenges or authentication, including password challenges, public key cryptosystems, and algorithmic authentication.

An origin must be prepared to accept and respond to Access-control requests from the target if access control is in effect. A target may issue an Access-control request which is either part of a specific (active) operation, or which pertains to the Z-association.

• If concurrent operations is in effect:
  • If the Access-control request includes a Reference-id: The supplied Reference-id must correspond to an active operation; the Access-control request is part of that operation. The Access-control response must also include that Reference-id.
  • If the Access-control request does not include a Reference-id: The Access-control request and response are not part of any operation, they pertain to the Z-association.
• If serial operations is in effect: The target may issue an Access-control request only when there is an active operation; the Access-control request and subsequent response are part of that operation and must include the Reference-id of the operation (which is assumed 'null' if not present in the initiating request).

The following procedures pertain to access control as it applies to an operation:

1. After sending an initiating request, the origin must be prepared to receive an Access-control request (for that operation), respond with an Access-control response, then later receive another Access-control request, etc., before receiving a terminating response. The target might suspend processing of the operation from the time that it sends the Access-control request until it receives the Access-control response. The challenge does not interrupt any other operation. If the origin response is acceptable to the target, the operation proceeds as if the challenge has never taken place. If the origin fails to respond correctly to the challenge then the target's terminating response to the interrupted operation may indicate that the operation was terminated due to an Access-control failure.
2. If the origin fails to respond correctly to a challenge during an Init operation, the target may reject the Z-association (by setting the Result parameter to 'reject,' and optionally supplying an explanatory message in the User-information-field of the Init response). However, the target need not necessarily reject the Z-association. For example the target might wish to invoke a security challenge during an Init operation to determine whether the origin is authorized to use a capability it has proposed. If the origin fails to respond properly, the target may simply refuse the use of that particular operation (via the Options parameter).
3. During a Search or Present operation, while the target is preparing records for presentation, it might send an Access-control request pertaining to a particular record. If the origin fails to respond correctly to the challenge, the target may simply substitute a surrogate diagnostic: "security challenge failed; record not included."

The following procedures pertain to access control as it applies to the Z-association:

1. If concurrent operations is in effect, following initialization the origin must be prepared at any time during the association, whether or not operations are active, to receive an Access-control request pertaining to the Z-association, to respond with an Access-control response, then later to receive another Access-control request, etc.
2. The target might suspend processing of some or all of the active operations from the time that it sends the Access-control request until it receives the Access-control response. If the origin response is acceptable to the target, the suspended operations proceed as if the challenge had never taken place.
3. If the origin fails to respond correctly to the challenge, the target might decide to terminate one or more operations but to leave open the Z-association. In that case, the target's terminating response to any such operations may indicate that the operation was terminated because of an Access control failure. Alternatively, the target may close the Z-association.

Table 7: Parameters of the Access-control Service

3.2.5.1.1 Security-challenge and Security-challenge-response. Definitions for format and content of the challenge and response are subject to registration; several definitions are defined and registered in Appendix 7 ACC. Alternatively, the contents of these two parameters may be established by prior agreement between a given target/origin pair.

3.2.5.1.2 Other-information. This parameter may be used by either the origin or target for additional information not specified by the standard. This parameter may be used only when version 3 is in force.

3.2.5.1.3 Reference-id. If serial operations is in effect, or if concurrent operations is in effect and the challenge pertains to a particular operation, then the use of Reference-id is governed by section 3.4. If 'concurrent operations' is in effect and the challenge pertains to the Z-association, then the Reference-id is to be omitted from both the request and response.

3.2.6 Accounting/Resource Control Facility
The Accounting/Resource Control facility consists of three services:

1. the Resource-control service, invoked by the target, either as part of an active operation (of any type) or pertaining to the Z-association;
2. the Trigger-resource-control service, invoked by the origin as part of an active operation (of any type except Init), and
3. the Resource-report service, invoked by the origin to initiate a Resource-report operation.

The Resource-control service permits the target to send a Resource-control request, which might include a resource report. The report might notify the origin that either actual or predicted resource consumption will exceed agreed upon limits (or limits built into the target), and request the origin's consent to continue an operation, via the Resource-control response. The target might, for example, inform the origin about the current status of a result set being generated on the target during a Search operation, and indicate information about the progress of the operation.

The Trigger-resource-control service permits the origin to request that the target initiate the Resource-control service, or cancel the operation.

The Resource-report service permits the origin to request that the target send a Resource-report pertaining to a completed operation or to the Z-association.

3.2.6.1 Resource-control Service
An origin must be prepared to accept and respond to Resource-control requests from the target if resource control is in effect. A target may issue a Resource-control request which is either part of a specific (active) operation or which pertains to the Z-association.

• If concurrent operations is in effect:
  • If the Resource-control request includes a Reference-id: The supplied Reference-id must correspond to an active operation; the Resource-control request is part of that operation. The Resource-control response (if any) must also include that Reference-id.
  • If the Resource-control request does not include a Reference-id: The Resource-control request and response are not part of any operation, they pertain to the Z-association.
  If serial operations is in effect: The target may issue a Resource-control request only when there is an active operation; the Resource-control request and (possible) subsequent response are part of that operation and must include the Reference-id of the operation (which is assumed 'null' if not present in the initiating request).

The Resource-control request indicates whether a response is required:

• If so, the origin must issue a Resource-control response. If the Resource-control request was part of an operation: the response is part of the same operation; the target awaits the Resource-control response, and subsequently issues a terminating response after processing of the operation is concluded.
• If not, the origin must not issue a Resourcecontrol response. If the Resource-control request was part of an operation: the target subsequently issues the terminating response, after processing of the operation is concluded.

An origin should be prepared to receive, and (conditionally) respond to, multiple Resource-control requests as part of an operation (while the operation is active), or pertaining to the Z-association.

If the origin responds to a Resource-control request with a Resource-control response saying to terminate an operation, it can expect to receive a terminating response. This response might indicate that the operation was terminated at origin request. However, the response might alternatively indicate that the operation completed, since the operation at the target may continue to execute and subsequently complete before the Resource-control response reaches the target.

Table 8: Parameters of the Resource-control Service

3.2.6.1.1 Resource-report. This parameter may be used to convey information about the current and estimated resource consumption at the server. The format of Resource-report resource-1 and resource-2 are defined in Appendix 6 RSC.

3.2.6.1.2 Partial-results-available. The target indicates the status of the result set via the flag Partial-results-available, whose value is one of the following:

subset - Partial, valid results available.
interim - Partial results available, not necessarily valid.
none - No results available.

This parameter is meaningful only as part of a search operation. If its value is 'subset' or 'interim,' then the target will accept subsequent Present requests against the result set if the origin indicates (via the Continue-flag) that the operation is to be terminated and if the value of the parameter Result-set-wanted is 'on'.

If the value of Partial-results-available is 'none' then the target need not accept subsequent Present requests in the event that the origin indicates (via the Continue-flag) that the operation is to be terminated.

Note that if the Suspended-flag is off, the partial results available situation may change because processing of the Search operation may continue. In all cases, the values of Search-status and Result-set-status in the Search response should be treated as the authoritative information.

3.2.6.1.3 Suspended-flag. This parameter is valid only when the request pertains to an operation. The target indicates whether or not processing of the operation has been suspended pending the Resource-control response. This flag occurs if and only if the value of Response-required is 'yes'.

3.2.6.1.4 Response-required. The target indicates whether or not a response (from the origin) to this request is required.

3.6.2.1.5 Triggered-request-flag. This parameter is valid only when the request pertains to an operation. The target may optionally indicate whether or not this request resulted from a Trigger-resource-control request from the origin.

3.2.6.1.6 Continue-flag. This parameter is valid only when the request pertains to an operation. The origin indicates to the target whether or not to continue processing the operation.

3.2.6.1.7 Result-set-wanted. This flag is valid only:

• during a Search operation,
• when the value of Partial-results-available is 'subset' or 'interim,' and
• when the value of the parameter Continue-flag is 'do not continue'.

If the value of this flag is 'yes,' the target will maintain the (possibly partial) result set for subsequent Present operations. If the value of the flag is 'no,' the target may delete the result set. A result set status of 'none' on the subsequent Search response indicates that the target has discarded the result set. In all cases, the values of Search-status and Result-set-status in the Search response describe the actual decisions made by the target and the way in which the search terminated.

3.2.6.1.8 Other-information This parameter may be used by either the origin or target for additional information, not specified by the standard. This parameter may be used only when version 3 is in force.

3.2.6.1.9 Reference-id See 3.4.

3.2.6.2 Trigger-resource-control Service
An origin may issue Trigger-resource-control requests during an operation (except during an Init operation), as part of that operation. It serves as a signal to the target that the origin wishes the target to:

• simply send Resource-report, i.e., issue a Resource-control request with Response-required 'off';
• invoke full resource control, i.e., issue a Resource-control request with Response-required 'on'; or
• cancel the operation.

The target is not obliged to take any specific action upon receipt of a Trigger-resource-control request. For the purpose of procedure description, there is no response to the request; if the target wishes to issue a Resource-control request it does so unilaterally. (If the origin issues a Trigger-resource-control request and subsequently receives a Resource-control request as part of the same operation, the origin cannot necessarily determine whether the latter resulted from the Trigger-resource-control request. However, the target may include Triggered-request-flag in the Resource-control-request to so indicate.)

If the origin issues a Trigger-resource-control request saying to cancel the operation, and if the target honors the request, the origin can expect to receive a terminating response indicating that the operation was terminated at origin request.

Although an origin may issue a Trigger-resource-control request as part of an active operation, the target might receive the request after the operation terminates. In that case, the target will ignore the Trigger-resource-control request. Furthermore, the target might receive a Trigger-resource-control request after issuing a Resource-control request for the same operation, while awaiting a Resource-control response. In that case, again, the target should ignore the Trigger-resource-control request. (Note that in general, the target may ignore any Trigger-resource-control request.)

Table 9: Parameters of Trigger-resource-control Service

3.2.6.2.1 Requested-action. The origin indicates one of the following:

resource-report - Issue a Resource-control request and set Response-required to 'off'.
resource-control - Issue a Resource-control request and set Response-required to 'on'.
cancel - Terminate the operation.

3.2.6.2.2 Preferred-Resource-report-format. The origin may indicate a resource report format that it prefers.

3.2.6.2.3 Result-set-wanted. This flag is meaningful only for a Search operation, and when the requested action is 'cancel'. If the value of the flag is 'yes,' the origin requests that the target maintain the (possibly partial) result set for subsequent Present operations. See 3.2.6.1.7.

3.2.6.2.4 Other-information. This parameter may be used by the origin for additional information, not specified by the standard. This parameter may be used only when version 3 is in force.

3.2.6.2.5 Reference-id. See 3.4.

3.2.6.3 Resource-report Service
The Resource-report service allows an origin to request a Resource-report, pertaining to a specified, completed operation, or to the entire Z-association.

Note: The Resource-report service differs from the Trigger-resource-control service, in this respect: Trigger-resource-control is a non-confirmed service; there is a request, but no response. The request is part of, but does not initiate, an operation; it requests a report pertaining to that active operation. Resource-report, in contrast, is a confirmed service; there is a request and a response (the target is obliged to respond, although the target is not obliged to include a resource report in the response). The request and response initiate and terminate an operation respectively; the request identifies a particular completed operation and solicits a report pertaining to that operation (or it may solicit a report pertaining to the entire Z-association).

Table 10: Parameters of the Resource-report Service

3.2.6.3.1 Preferred-resource-report-format The origin may indicate a resource report format that it prefers.

3.2.6.3.2 Op-id This parameter may be supplied by the origin to identify a completed operation for which the origin requests a resource report. This parameter may be used only when version 3 is in force.

• If Op-id is present, it consists of a Reference-id, and refers to the most recently completed operation that used that Reference-id. Notes:
  1. When an operation terminates, if the origin anticipates that it will subsequently issue a Resource-report request pertaining to that operation, it is the origin's responsibility to ensure that the Reference-id is not re-used before doing so.
  2. The origin may (but need not) use the same reference-id for the Resource-report operation as that specified in Op-id, and if so, Op-id will nevertheless pertain to a completed operation only. However, it is recommended that the origin not specify a value of Op-id equal to any reference-id being used by any active operation other than this Resource-report operation. If the origin does so, the target may (but need not) consider the request in error (see failure-6 of Resource-report-status).
  3. If the origin wants resource information about an active operation, it should not use the Resource-report service, but instead use the Trigger-resource-control service, as part of that operation. If the operation terminates before the target receives the Trigger-resource-control request, the origin will receive a terminating response and may then subsequently issue a Resource-report request pertaining to that (completed) operation.
• If Op-id is not present, the origin requests a resource report pertaining to the Z-association.

3.2.6.3.3 Resource-report-status. The target supplies one of following status values:

success - A resource report is included (and in the preferred format, if the parameter Preferred-resource-report-format was included in the request).
partial - A resource report is included, but not in the preferred format (applies only if the parameter Preferred-resource-report-format was included in the request).
failure-1 - Target unable to supply resource report.
failure-2 - Operation terminated by target due to resource constraints.
failure-3 - Access-control failure.
failure-4 - Unspecified failure.
failure-5 - There is no known operation with specified id.
failure-6 - There is an active operation with specified id.
Note: Failure-5 and failure-6 apply only when version 3 is in force.

3.2.6.3.4 Resource-report. See 3.2.6.1.1.

3.2.6.3.5 Other-information. This parameter may be used by either the origin or target for additional information, not specified by the standard. This parameter may be used only when version 3 is in force.

3.2.6.3.6 Reference-id See 3.4.

3.2.7 Sort Facility
The Sort facility consists of a single service, Sort.

[Note: This definition is amended by Z39.50-1995 Amendment 1: Add Result Count Parameter to Sort Response.]

3.2.7.1 Sort Service
The Sort service allows an origin to request that the target sort a result set (or merge multiple result sets and then sort). The origin specifies a sequence of sort elements. The result set is to be ordered according to the specified sequence, and subsequent positional requests against the result set will be construed by the target to apply to the result set as so ordered.

Table 11: Parameters of the Sort Service

3.2.7.1.1 Input-result-sets. This parameter is the name of a result set to be sorted, or the names of result sets to be merged and the result sorted.

3.2.7.1.2 Sorted-result-set. This parameter is the name of the sorted result set. It may be the name of an existing result set (including one of the names included in Input-result-set); if so, then if the sort is processed, the existing result set is deleted, and a new result set by that name is created; its content is the sorted results. If Sorted-result-set is not the name of an existing result set and if the sort is processed, a result set by the specified name is created by the target, whose content is the sorted results; the content of the Input-result-sets is left unchanged. In any case, if the sort is not processed, the final content of Sorted-result-set is indicated by the parameter Result-set-status.

3.2.7.1.3 Sort-sequence. The parameter Sort-sequence comprises the elements that are to be used for sorting, together with the direction of the sort (ascending or descending), case sensitivity (if applicable), and target action if an element is missing from a record in the result set to be sorted. Each of the sort elements is a set of attributes, a sort-field-designator, or an element specification, that the target has designated (see note below) for use as a sort key.

Note: The target designates this information either via the Explain facility, or through some mechanism outside of the standard.

3.2.7.1.4 Sort-status. The parameter Sort-status, returned by the target, assumes one of the following values:

success - The sort was performed successfully.
partial-1 - The sort was performed but the target encountered records with missing values in one or more sort elements.
failure - The sort was not performed. The target supplies one or more diagnostics in the parameter Diagnostics.

3.2.7.1.5 Result-set-status. The target supplies this parameter if and only if the value of Sort-status is 'failure'. It refers to the contents of Sorted-result-set, and its value is one of the following:
empty - The result set is empty.
interim - Partial results available, not necessarily valid.
unchanged - The content of the result set is unchanged (applies only if Sorted-result-set is one of the input result sets).
none - Result set not created (applies only if Sorted-result-set is not one of the input result sets).

3.2.7.1.6 Diagnostics. The target includes this parameter if the value of Sort-status is 'failure'. It includes one or more diagnostic records.

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

3.2.7.1.8 Reference-id. See 3.4.

3.2.8 Browse Facility
The Browse facility consists of a single service, Scan.

3.2.8.1 Scan Service
The Scan service is used to scan an ordered term-list (subject terms, names, titles, etc.). The ordering of the term-list is target defined. The origin specifies a term-list to scan and a starting term (implicitly, by specifying an attribute/term combination and a database-id), the size of the scanning steps, and the desired number of entries and position of the starting term in the response.

Table 12: Parameters of the Scan Service

3.2.8.1.1 Database-names. The parameter Database-names identifies a set of databases to which the term-list (specified by Term-list-and-start-point) pertains.

3.2.8.1.2 Term-list-and-start-point. The origin supplies an attribute list and term. The attribute list contains attributes indicating which term-list to scan. The term, as qualified by those attributes, indicates where scanning begins; this will be a presumed entry in the term-list. If there is no matching entry, the first entry with higher value is to be the starting point.

As an example, to scan a list of personal names: the attribute list might consist of a single attribute whose type is 'use' and whose value is 'personal name'; the term would specify a personal name; the database-id would identify one or more databases to which the list of personal names pertains.

3.2.8.1.3 Step-size. The origin may specify the desired number of entries in the term-list between two adjacent entries in the response. A value of zero means "do not skip any entries." If the target cannot support the requested step size, it sets Scan-status to 'failure' and includes a non-surrogate diagnostic such as "only step size of zero supported" or "requested step size not supported." If the origin omits this parameter, the step size is selected by the target, and the target includes the selected step size in the response.

3.2.8.1.4 Number-of-entries. The origin indicates the proposed number of entries to be returned. The target indicates the actual number of entries returned. If the actual number is less than the proposed number, the reason is indicated in Scan-status.

3.2.8.1.5 Position-in-response. The origin may optionally indicate the preferred position, within the returned entries, of the specified starting point value. A value of 1 refers to the first of the returned entries. A value of 0 means that the returned entries should begin with the term immediately following the starting point term. A value of Number-of-entries + 1 means that the origin requests terms immediately preceding the starting point term.

The target may indicate the actual position of the chosen starting point within the returned entries. Example: If the values of the request parameters Number-of-entries and Position-in-response are 10 and 3 respectively, then the origin requests two terms immediately preceding the starting point value, followed by the starting point value, followed by the immediately-following seven terms.

Note: If response parameter Position-in-response is less than the value proposed in the request, the origin may conclude that there were fewer terms than expected in the low end of the term-list. However, if Position-in-response is the same value in the response as proposed in the request, but Number-of-entries in the response is less than the value proposed in the request, the origin may not conclude that there were fewer terms than expected at the high end of the term-list, unless Scan-status is Partial-5. The reason that fewer terms than expected are returned is indicated in the Scan-status.

3.2.8.1.6 Scan-status. The target indicates the result of the operation. The defined values are:

success - The response contains the number of entries (term-list-entries or surrogate diagnostics) requested.
partial-1 - Not all of the expected entries can be returned because the operation was terminated by access-control.
partial-2 - Not all of the expected entries will fit in the response message.
partial-3 - Not all of the expected entries can be returned because the operation was terminated by resource-control, at origin request.
partial-4 - Not all of the expected entries can be returned because the operation was terminated by resource-control, by target.
partial-5 - Not all of the expected entries can be returned because the term-list contains fewer entries (from either the low end, high end, or both ends of the term-list) than the number of terms requested.
failure - None of the expected entries can be returned. One or more non-surrogate diagnostics is returned.

3.2.8.1.7 Entries. The parameter Entries returned by the target consists of one of the following:

• N entries, where each entry is a term-list-entry or surrogate diagnostic, where N = Number-of-entries in the request.
• A number of entries which is less than N, and may be zero (reason specified by Scan-status).

And may also include:

• One or more non-surrogate diagnostic records (possibly indicating that the operation cannot be processed, and why it cannot).

Each term-list-entry includes a term (occurring in one of the databases specified in the parameter Database-names), and optionally the following:

• A display term (when the actual term is not considered by the target to be suitable for display).
• A list of suggested attributes for use in subsequent Scan requests (useful for scanning multiple indices, e.g. author and title, at the same time).
• A suggested alternative term.
• Occurrence-information: this might include a count of records in which the term occurs. It may also list counts for specific attributes, possibly further broken down by database. Alternatively, a term-list-entry might list databases in which the term occurs, and for associated attributes, but no counts.
• Other information: additional information concerning the entry.

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

3.2.8.1.9 Reference-id. See 3.4.