ANSI/NISO Z39.50-1992                          ISSN: 1041-5653
(Revision of ANSI/NISO Z39.50-1988)

Application Service Definition and Protocol Specification for Open Systems Interconnection

This section defines the Information Retrieval service, which is supported by the Information Retrieval protocol.

3.1 General Characteristics of the Information Retrieval Service

The service definition describes an activity between two applications on different computers: an initiating application, the origin, and a responding application, the target. The target is associated with one or more databases. Communication between origin and target is via an application association. An association is explicitly established by the origin and may be explicitly terminated by either origin or target, or implicitly terminated by a communication failure or other external event.

The roles of origin and target may not be reversed within an association. An association cannot be restarted, thus no status information is retained once an association is released.

The complete application service is composed of the association control service element, which provides association management, and one or more specific application services, such as the Information Retrieval application service. There are three distinct phases during the life of an application association: establishment, information transfer, and termination. The association control service element provides all of the services required during the establishment and termination phases, including the selection of an application context specifying, among other things, the set of service elements which are valid during the information transfer phase. Section 4.2.1.2 specifies those services for association control that are assumed by the Information Retrieval service.

3.2 Facilities of the Information Retrieval Service

There are seven facilities defined by this standard. Each of the Initialization, Search, Retrieval, Result-set-delete, and Access Control facilities consists of a single service. The Accounting/ Resource Control facility consists of three services. The Termination facility consist of two services.

1. Initialization Facility Init Service: Init request by the origin followed by an Init response from the target. The Init service is a confirmed service initiated by the origin.

2. Search Facility Search Service: Search request by the origin followed by a Search response from the target. The Search service is a confirmed service initiated by the origin.

3. Retrieval Facility Present Service: Present request by origin followed by a Present response from the target. The Present service is a confirmed service initiated by the origin.

4. Result-set-delete Facility Delete Service: Delete request by the origin followed by a Delete response from the target. The Delete service is a confirmed service initiated by the origin.
   Note: Between the Init, Search, Present, or Delete request and its respective response, there may occur one or more of the following: Access-control request/response sequence initiated by the target, Trigger-resource-control request by the origin, and Resource-control request (and possibly response) initiated by the target.

5. Access Control Facility Access-control service: Access-control request by the target, following an Init, Search, Present, Delete, or Resource-report request by the origin and followed by an Access-control response from the origin. The Access-Control service is a confirmed service initiated by the target.

6. Accounting/Resource Control Facility The Accounting/ Resource Control facility consists of three services: the Resource-control service, the Trigger-resource-control service, and the Resource-report service.
   • Resource-control Service: Resource-control request by the target, following an Init, Search, Present, or Delete request by the origin and followed (possibly) by a Resource-control response from the origin. The Resource-control service is a conditionally confirmed service, initiated by the target.

   • Trigger-resource-control Service: Trigger-resource-control request by the origin, following an Init, Search, Present, or Delete request by the origin. The Trigger-resource-control service is a non-confirmed service initiated by the origin.

   • Resource-report Service: Resource-report request by the origin, following an Init, Search, Present, Delete, or Resource-report response from the target. The Resource-report service is a confirmed service, initiated by the origin.

   Note: Between the Resource-report request and its response, there may occur one or more Access-control request/response sequences.

7. Termination Facility The Termination Facility allows an origin or target system to initiate abrupt termination of the association, or an origin system to initiate graceful termination.
   • IR-abort Service: IR-abort request by either the origin or the target. The IR-abort service is a non-confirmed service initiated by either the origin or target.

   • IR-release Service: IR-release request by the origin followed by an IR-release response by the target. The IR-Release service is a confirmed service initiated by the origin.

   The IR-abort and IR-release services map directly onto the A-ABORT and A-RELEASE services (respectively) of the association control service element.

3.2.1.1 Init Service

The Init service allows an origin to propose values for initialization parameters. The target system may propose alternative values for some of the parameters. If so, the origin must either accept the alternative values proposed by the target or else terminate communication. See Table 1.

                   Table 1: Parameters of the Init Service

                                   Origin          Target
        Parameter                  Request         Response
   
   Id/authentication               x  (optional)
   ______________________________________________________________________
   Options                         x               x
   ______________________________________________________________________
   Preferred-message size          x               x
   ______________________________________________________________________
   Maximum-record-size             x               x
   ______________________________________________________________________
   Result                                          x
   ______________________________________________________________________
   User-information-field          x (optional)    x (optional)
   ______________________________________________________________________
   Reference-id                    x (optional)    x (if appl.)

The origin and target agree, outside the scope of the standard, whether or not this parameter is to be supplied by the origin, and if so, what the value is. This value is used by the target to determine if the origin is authorized to enter into communication with the target.

3.2.1.1.2 Options

The Init request specifies either "will use" or "will not use," and the Init response specifies "will support" or "will not support" for the following capabilities:

1. search

2. present

3. delete

4. resource-report

5. trigger-resource-control

In addition, the Init request specifies either "will support" or "will not support," and the Init response specifies "will use" or "will not use" for each of the following capabilities:

1. resource-control

2. access-control

Note: the above two lists of capabilities are subject to expansion in future versions of this protocol.

Search - The origin specifies "will use" for "search" if it intends to submit Search requests. The target indicates that it is willing (or unwilling) to accept and respond to Search requests by specifying "will support" (or "will not support") for "search."

Present - The origin specifies "will use" for "present" if it intends to submit Present requests. The target indicates that it is willing (or unwilling) to accept and respond to Present requests by specifying "will support" (or "will not support") for "present."

Delete - The origin specifies "will use" for "delete" if it intends to submit Delete requests. The target indicates that it is willing (or unwilling) to accept and respond to Delete requests by specifying "will support" (or "will not support") for "delete."

Resource-report - The origin specifies "will use" for "resource-report" if it intends to submit Resource-report requests. The target indicates that it is willing (or unwilling) to accept and respond to Resource-report requests by specifying "will support" (or "will not support") for "Resource-report."

Note: The target indication that it is willing to respond to Resource-report requests does not imply that it will include a resource report in the response.

Trigger-resource-control - The origin specifies "will use" for "trigger-resource-control" if it intends to submit Trigger-resource-control requests (if so, the origin must also indicate that it is prepared to receive and respond to a Resource-control request from the target, by specifying "will support" for "resource-control"). The target indicates that it is willing (or unwilling) to accept Trigger-resource-control requests by specifying "will support" (or "will not support") for "trigger-resource-control."

Notes:

1. The target may indicate unwillingness to accept Trigger-resource-control requests even if it specifies "will use" for "resource-control."

2. An indication by the target of willingness to accept Trigger-resource-control requests does not imply that the target will take any action as a result of a Trigger-resource-control request.

Resource-control - The origin indicates that it is prepared to receive and respond to a Resource-control request from the target by specifying "will support" for "resource-control." Conversely, the origin indicates that it is not prepared to receive a Resource-control request by specifying "will not support." In the latter case, if the target cannot suppress sending a Resource-control request, it should reject the connection by setting Result to "reject," specifying "will use" for "resource-control," and (optionally) supplying a text message in the User-information-field.

Access-control - Likewise, the origin indicates whether or not it is prepared to receive and respond to an Access-control request from the target, by specifying "will support" or "will not support" for "access-control."

Security is invoked at different levels. In addition to user authentication at the outset of an association, security might be invoked to control access to a particular database, record, result-set, or use of a command. It might be used to determine whether an origin is authorized to request a resource report.

If the origin is not capable of receiving an Access-control request, and if security requirements on the target system mandate that security (other than that which might be provided by the parameter Id/authentication) be invoked at the outset of an association, then the target should reject the association by setting the parameter Result to "reject," and specifying "will use" for "access-control." However, if the target invokes security, but not at the association level, then the target may choose to accept the connection. In that case, if the target subsequently receives a command that would precipitate an Access-control request, the target agrees to suppress the request and respond to the command with an error status indicating that a security challenge was required but could not be issued.

3.2.1.1.3 Preferred-message-size and Maximum-record-size

The Init request contains Preferred-message-size and Maximum-record-size, specified in bytes. Maximum-record-size must be greater than or equal to preferred-message-size. The Init response contains both the Preferred-message-size and Maximum-Record-size that the target is going to use.

The target has the option of responding with values different from those requested by the origin (however, Preferred-message-size must be less than or equal to Maximum-record-size), in which case, the origin may abort the connection if those values are not acceptable. The usage of these parameters is specified in section 3.3.

3.2.1.1.4 Result

The target indicates whether or not it accepts the association by specifying a value of "accept" or "reject" respectively in the parameter Result. If "reject" is indicated, the origin is expected to terminate communication.

3.2.1.1.5 User-information-field

This field may be used by either the origin or target for additional information not specified by this standard.

3.2.1.1.6 Reference-id

See section 3.4.

3.2.2 Search Facility

The Search facility enables an origin system to query databases at a target system, and to receive information about the results of the query.

3.2.2.1 Search Service

The Search service allows an origin to send a query to a target. The basic query concept is: "from the specified set of items, identify those with the properties indicated." The set of items identified is called the "result set," and is maintained by the target for subsequent retrieval requests. However, depending on the parameters of the search, one or more items identified by the result set may be immediately returned as part of the search response. The result set is an ordered set; items identified by entries in the result set are referenced by the position of the entry within the result set, beginning with one (1). See Table 2.

                   Table 2: Parameters of the Search Service

                                   Origin          Target
        Parameter                  Request         Response

   Query-type                      x
   ______________________________________________________________________
   Query                           x
   ______________________________________________________________________
   Database-names                  x
   ______________________________________________________________________
   Request-set-name                x
   ______________________________________________________________________
   Replace indicator               x
   ______________________________________________________________________
   Small-set-element-names         x (opt.)
   ______________________________________________________________________
   Medium-set-element-set-names    x (opt.)
   ______________________________________________________________________
   Preferred-record-syntax         x (opt.)
   ______________________________________________________________________
   Small-set-upper-bound           x
   ______________________________________________________________________
   Large-set-lower-bound           x
   ______________________________________________________________________
   Medium-set-present-number       x
   ______________________________________________________________________
   Database/diagnostic-records                     x (if appl.)
   ______________________________________________________________________
   Result-count                                    x
   ______________________________________________________________________
   Number-of-records-returned                      x
   ______________________________________________________________________
   Next-result-set-position                        x
   ______________________________________________________________________
   Search-status                                   x
   ______________________________________________________________________
   Result-set-status                               x (if appl.)
   ______________________________________________________________________
   Present-status                                  x (if appl.)
   ______________________________________________________________________
   Reference-id                    x (opt.)        x (if appl.)

The parameter Query-type identifies the syntax of the query. As noted above, the basic query concept is "from the specified set of items, identify those with the properties indicated." The "specified set of items" is a collection of one or more databases, specified by the parameter database-names. The "properties indicated" are specified by the parameter Query.

Five types are defined:

- type-0 may be used only when the origin and target have an a priori agreement outside of the standard;

- type-1 is the Reverse Polish Notation (RPN) query specified in section 3.2.2.1.1.1;

- type-2 is the ISO 8777 type query, specified in ISO 8777;

- type-100 is the Z39.58 type query, specified in ANSI Z39.58; and

- type-101 is the proximity query, specified in Appendix G.

This section specifies procedures when Query-type is 1, `RPN-query.' The RPN query has the following structure:

   RPN-query     ::=  argument | 
                      argument+ argument + operator
    argument     ::=  operand | RPN-query
     operand     ::=  attribute-set + term |
                      Result-set-id
    operator     ::=  AND | OR | AND-NOT

   "::="  means "is defined as,"
   "|"    means "or," 
   "+"    means "followed by," and + has precedence over |  
          (i.e., + is evaluated before |).

(1) "RPN-query" is recursively defined; it is either

(a) "operand," or

(b) "argument + argument + operator."

(2) "Operand" is either (a) attribute-set + term, or (b) Result-set-id. In either case it represents a set of database records. For (a) it is the set of database records obtained by evaluating the specified attribute-set and term against the collection of databases specified in the Search request (see Note 3). For (b) it is the set of database records represented by the result set for which Result-set-id was specified as the value of the parameter Result-set-name in a previous Search request.

(3) Different attribute sets will be defined and registered (Appendix C defines and registers attribute-set bib-1). An example of an attribute-set/term combination is `title word'/ `evangeline'; in this case, evaluation of attribute-set/term against a database would result in the identification of all of the records in the database for which the access point `title word' contains the value `evangeline'.

Representation and Evaluation of the Type-1 Query:

At the origin system, the Type-1 query is represented by a tree. Each leaf node contains a simple operand and each non-leaf node contains a complex operand. A simple operand is either a Result-set-id or an Attribute-set+Term. A complex operand is a subtree whose root is an operator and which contains two subtrees: a left-hand operand and a right-hand operand, LO and RO. A complex operand is thus one of the following:

- LO AND RO, representing the intersection of LO and RO;

- LO OR RO, representing the union of LO and RO; or

- LO AND-NOT RO, representing the set of elements in LO that are not in RO.

(a) Attribute-set + Term

(b) Result-set-id

(c) Operator

- if operator is AND, the result is the intersection of the two sets,

- if operator is OR, the result is the union of the two sets,

- if operator is AND-NOT, the result is the set of elements in the first set (i.e., the first of the two sets to have been placed on the stack) which are not in the second set.

When evaluation of the query is complete (i.e. all query-terms have been processed) there will be one item remaining on the stack (otherwise the query is in error) which is the result of the query.

The following examples illustrate query evaluation. In these examples, D represents the collection of databases specified in the Search request, R represents a Result-set-id, and A, B, and C represent attribute-list/term combinations such as "subject = dogs."

1. Query = A
Result: the records in D for which A is true

2. Query = A B C AND OR
Result: the records in D for which both B and C are true, or A is true

3. Query = A B AND C OR
Result: the records in D for which both A and B are true, or C is true

4. Query = R A AND
Result: the records in D for which both (1) A is true, and (2) which are also in result set R

5. Query = R A OR
Result: the records in D for which A is true, together with records in R

The target designates, by agreement outside the scope of the standard, what databases may be specified on a Search request, and also in what combinations they may be specified. For example, a target might specify that databases A, B, and C, may be searched individually, and that A and B may be searched in combination (but not A and C, nor B and C). If an origin requests a combination of databases which is not supported, the search will result in a diagnostic such as "combination of specified databases not supported" (see Appendix D).

3.2.2.1.3 Result-set-name and Replace-indicator

The parameter Result-set-name specifies a name to be given to the result set which will be created by the query so that it may be subsequently referenced within the same association.

- If a result set with the same name already exists at the target, the action taken depends on the value of the parameter Replace-indicator, as follows:
-- If the value of Replace-indicator is "on," then after processing the query, the existing result set whose name is specified by the parameter Result-set-name will be deleted, and a new result set by that name created. If the search cannot be processed, the content of the result set will be empty.

-- If the value of Replace-indicator is "off," the search is not processed, an error diagnostic is returned by the target, and the existing result set whose name is specified by the parameter Result-set-name is left unchanged.

- If a result set does not exist with the name specified by the parameter Result-set-name, then a result set by that name is created by the target, and the parameter Replace-indicator is ignored. The initial content of the result set is empty. If no records are found by the query, the result set remains empty.

A result set that is created by a Search request (that is, specified by the parameter Result-set-name) may be referenced in a subsequent Present request or as an operand in a subsequent Search request (for example, in a Type-1 query). If a result set named "default" is created, it remains available for reference from the time it is created until the end of the association during which it is created, or until either:

- another "default" result set is created, because the name "default" is specified as Result-set-name in a subsequent Search request, or

- it is unilaterally erased or deleted by the target.

- by a Delete request;

- implicitly, because a result set was specified by the same name in a Search request, and the value of the parameter Replace-indicator was "on";

- unilaterally by the target (at any time); or

- by termination of the association.

An element set name is a primitive name that specifies a particular subset of the elements in a database record that are to compose the response records. The specified subset is made up of components of the abstract-syntax description of the database records and is, therefore, a formal subset of that abstract-syntax-definition. Element set names are specified, along with their definitions, for a given database, by the target, outside of this standard. The target specifies a default element set for each database.

The parameters Small-set-element-set-names and Medium-set-element-set-names describe the preferred composition of the records expected in the search response. If the query results in a small-set (see 3.2.2.1.6), then Small-set-element-set-names pertains. If the query results in a medium-set, then Medium-set-element-set-names pertains.

Each of the two parameters is a set of one or more pairs of a database name and associated element set name. For each database record returned in a Search (or Present) response, if the given database is specified (as a component of one of the pairs comprising the pertaining element set name) then the response record should be composed according to the corresponding element set name. If not, the response record should be composed according to the default element set name for that database. If an element set name is specified which is not valid for the corresponding database, then the Search Response will include a diagnostic, such as "element set name not valid for database," and the value of the parameter Search-Status will be "failure."

Each of the two parameters may alternatively consist of a single element set name (from those defined by the target system), with no database specified. In that case, for each database record returned in a Search (or Present) response:

- if the specified element set name is valid for the given database, the response-record should be composed according to that element set name;

- if the specified element set name is not valid for the given database, the response-record should be composed according to the default element set name for that database.

3.2.2.1.5 Preferred-record-syntax

The parameter Preferred-record-syntax identifies the preferred abstract syntax for the records to be returned, from among the set of abstract syntaxes for records for which presentation contexts are currently established for this application association. If the target cannot supply the information in the requested abstract syntax, it will supply it in one of the other abstract syntaxes from the established set.

3.2.2.1.6 Small-set-upper-bound, Large-set-lower-bound, and Medium-set-present-number

The result set is considered a "small-set," "medium-set," or "large-set," depending on the values of parameters Small-set-upper-bound and Large-set-lower-bound of the Search request, and Result-count of the Search response (see section 3.2.2.1.8). The result set is a small-set if Result-count is not greater than Small-set-upper bound. The result set is a large-set if Result-count is larger than or equal to Large-set-lower-bound. Otherwise, the result set is a medium-set.

If the query results in a small-set, all database records identified by the result set are to be returned to the origin (subject to possible message size constraints). If the query results in a large-set, no database records are to be returned. If the query results in a medium-set, the maximum number of database records to be returned is specified by Medium-set-present-number.

Notes:

(1) The result set may be a medium-set only when Result-count is greater than Small-set-upper bound and less than Large-set-lower-bound, and this can occur only if Large-set-lower-bound is at least 2 greater than Small-set-lower bound; i.e., the result set cannot be a medium-set if Large-set-lower-bound exceeds Small-set-upper-bound by one. For example, if Large-set-lower-bound is 11 and Small-set-upper-bound is 10, the intent is "if 10 or fewer records are found return them all, otherwise do not return any," and medium-set-present-number would not apply.

(2) Small-set-upper-bound may be zero. Large-set-lower-bound must be greater than Small-set-upper-bound.

(3) If the origin does not want any records returned in the response regardless of the value of Result-count, Larger-set-lower-bound should be set to 1 and Small-set-upper-bound to zero.

The target processes the search, creating a result set that identifies a set of database records. It cannot be assumed however that search processing requires physical access to the database records; thus one or more records might not be returnable, but this circumstance might not be recognized until an attempt is made to transfer such a record.

After processing the search, the target attempts to retrieve the first N records identified by the result set, to be included in the Search response (N depends on the search parameters and result-count, as described in 3.2.2.1.6). For each record that cannot be returned, a surrogate diagnostic record is substituted. Thus the parameter Database/diagnostic-records is one of the following:

- N database and/or diagnostic records,

- a number of database and/or diagnostic records, which is less than N because of message size constraints (see 3.3);

- a single non-surrogate diagnostic record indicating that the search cannot be processed, and why it cannot be processed; or

- a single non-surrogate diagnostic record indicating that records cannot be presented, and why not, e.g. "element set name not valid for database."

3.2.2.1.8 Result-count and Number-of-records-returned

The parameter Result-count is the number of records identified by the result set. If the result set is empty, result-count is zero. The parameter Number-of-records-returned is the total number of records (database and diagnostic) returned in the Search response.

3.2.2.1.9 Next-result-set-position

The parameter Next-result-set-position specifies the position within the result set of the next record following those returned (or zero if the last record in the result set is being returned).

3.2.2.1.10 Search-status

The parameter Search-status, returned in the response, assumes one of the following two values:

success - the search completed successfully

failure - the search did not complete successfully

3.2.2.1.11 Result-set-status and Present-status

These are status descriptors necessary to disambiguate certain situations that can occur during search and present operations.

Result-set-status occurs if and only if the value of Search-status is "failure," and its value is one of the following:

subset - Partial, valid results available.

interim - Partial results available, not necessarily valid.

none - No results available (result set is empty).

success - All of the expected database (or surrogate diagnostic) records are available.

partial-1 - Not all of the expected records can be returned because the request was terminated by access-control.

partial-2 - Not all of the expected records can be returned because the request was terminated by maximum message size.

partial-3 - Not all of the expected records can be returned because the request was terminated by resource-control at origin.

partial-4 - Not all of the expected records can be returned because the request was terminated by resource-control at target.

failure - None of the expected database (or surrogate diagnostic) records can be returned. A single diagnostic is returned, which is not a surrogate for a database record.

See section 3.4

3.2.3 Retrieval Facility

The Retrieval facility enables the origin to retrieve a copy of records according to position within a result set maintained by the target.

3.2.3.1 Present Service

The Present service allows the origin system to retrieve records from a specified result set. Records are referenced by relative position within the result set. The origin specifies a range of records to be retrieved and may follow with subsequent requests specifying different ranges. For example, the origin may retrieve records one through five and follow with a request for records four through six. See Table 3.

                   Table 3: Parameters of the Present Service

                                   Origin          Target
        Parameter                  Request         Response

   Number-of-records-requested     x
   ______________________________________________________________________
   Result-set-start-position       x
   ______________________________________________________________________
   Result-set-id                   x
   ______________________________________________________________________
   Element-set-names               x (opt.)
   ______________________________________________________________________
   Preferred-record-syntax         x (opt.)
   ______________________________________________________________________
   Database/diagnostic-records     x (opt.)        x (if appl.)
   ______________________________________________________________________
   Number-of-records-returned                      x
   ______________________________________________________________________
   Next-result-set-position                        x
   ______________________________________________________________________
   Present-status                                  x
   ______________________________________________________________________
   Reference-id                                    x (if appl.)

The origin requests the return of N records beginning at record M, from the result set, where N = Number-of-records-requested and M = Result-set-start-position (and N is not greater than [Result-count - M] + 1).

3.2.3.1.2 Result-set-id

Result-set-id specifies the result set from which records are to be retrieved. It is the result set created by a previous Search request for which the value of the parameter Result-set-name matches the value of Result-set-id.

3.2.3.1.3 Element-set-names

The parameter Element-set-names describes the preferred composition of the records expected in the Present response. See section 3.2.2.1.4.

3.2.3.1.4 Preferred-record-syntax

See section 3.2.2.1.5.

3.2.2.1.5 Database/diagnostic-records

The parameter Database/diagnostic-records returned by the target consists of one of the following:

- N database and/or diagnostic records, where N = Number-of-records-requested,

- a number of database and/or diagnostic records, which is less than N (reason specified by Present-status), or

- a single diagnostic record indicating that the request cannot be processed, and why it cannot be processed.

3.2.3.1.6 Number-of-records-returned and Next-result-set-position

The parameter Number-of-records-returned is the total number of database and diagnostic records returned. Next-result-set-position is the position within the result set of the next record following the last database or surrogate diagnostic record being returned (or zero, if the last database or surrogate diagnostic record in the result set is being returned).

3.2.3.1.7 Present-status

Present-status is mandatory in a Present response and its values are the same as those listed for Present-status in 3.2.2.1.11.

3.2.3.1.8 Reference-id

See section 3.4.

3.2.4 Result-set-delete Facility

The Result-set-delete facility enables an origin to instruct a target system to delete one or more result sets known to the target. The target responds with information pertaining to the result of the operation.

3.2.4.1 The Delete Service

The Delete service enables an origin system to send a Delete request to the target. The origin may request deletion of specified result sets held by the target or all result sets currently on the target created during this association. The target responds by reporting the status of the requested delete operation. See Table 4.

                   Table 4: Parameters of the Delete Service

                                   Origin          Target
        Parameter                  Request         Response

   Delete-operation                x
   ______________________________________________________________________
   Result-set-list                 x (if appl.)
   ______________________________________________________________________
   Delete-operation-status                         x
   ______________________________________________________________________
   Delete-list-statuses                            x (if appl.)
   ______________________________________________________________________
   Number-not-deleted                              x (if appl.)
   ______________________________________________________________________
   Bulk-statuses                                   x (if appl.)
   ______________________________________________________________________
   Delete-msg                                      x (optional)
   ______________________________________________________________________
   Reference-id                    x (optional)    x (if appl.)

The origin specifies one of the following:

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

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

If Delete-operation is "list," then the parameter Result-set-list must be present. It specifies a list of result sets to be deleted, which were created by previous Search requests (in which the value of the parameter Result-set-name matches the value of one of the members of the list). If Delete-operation is "bulk-delete," then the parameter Result-set-list must not be present.

3.2.3.1.3 Delete-operation-status

Delete-operation-status is used by the target to report the status of the delete request. It assumes one of the values "success" or "failure-3" through "failure-9" in Table 5.

                   Table 5: Delete Statuses

      Status     Description

   ______________________________________________________________________
     success     Result set(s) deleted.
   ______________________________________________________________________
   failure-1     Result set did not exist.
   ______________________________________________________________________
   failure-2     Result set previously unilaterally deleted by target.
   ______________________________________________________________________
   failure-3     System problem at target (optional text message may 
                 be included in the Delete-msg parameter).
   ______________________________________________________________________
   failure-4     Access-control failure: the delete request caused the 
                 target system to issue an Access-control request, 
                 which the origin system failed to satisfy, or the 
                 origin could not accept an Access-control request.
   ______________________________________________________________________
   failure-5     Request terminated by origin system through resource 
                   control.
   ______________________________________________________________________
   failure-6     Access terminated by target system due to resource
                 constraints.
   ______________________________________________________________________
   failure-7     Bulk delete of result sets not supported by target.
   ______________________________________________________________________
   failure-8     Not all result sets deleted (on a bulk-delete 
                 request) (see 3.2.4.1.5).
   ______________________________________________________________________
   failure-9     Not all requested result sets deleted (on a list 
                 request).

   Note: failure-7 and failure-8 cab occur only if Delete-operation 
   is Bulk-delete.

Delete-list-statuses is present in a Delete response for a list operation. It contains the same Result-set-id(s) contained in the Result-set-list parameter of the corresponding Delete request. Each result-set-id in the Delete-list-statuses parameter is paired with a status. Possible status values are "success" and "failure-1" through "failure-6" in Table 5.

3.2.4.1.5 Number-not-deleted and Bulk-statuses

These two parameters occur only if Delete-operation 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 system is not obligated to provide statuses for each result set not deleted on a bulk delete. For example, a target system 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 system 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 Reference-id

See section 3.4.

3.2.5 Access Control Facility

The Access control facility allows a target system to challenge an origin system during execution of an Init, Search, Present, Delete, or Resource-report operation. See Table 6.

              Table 6: Parameters of the Access Control Service

                                   Origin          Target
        Parameter                  Request         Response

   ______________________________________________________________________
   Security-challenge              x
   ______________________________________________________________________
   Security-challenge-response                     x
   ______________________________________________________________________
   Reference-id                    x (if appl.)    x (if appl.)

An origin system must be prepared to accept and respond to one or more Access-control requests while an Init, Search, Present, Delete, or Resource-report request is being executed by the target system (unless the parameter Options of the Init request, which initiated the connection, did not include Access-control; see 3.2.1.1.2). For example, after sending a Search request, the origin must be prepared to receive an Access-control request, respond with an Access-control response, then later receive another Access-control request, etc., before receiving a Search response.

Once the origin has responded, the operation proceeds as if the challenge has never taken place. If the origin system fails to respond correctly to the challenge during a Search, Present, Delete, or Resource-report request, then the respective response may indicate that the operation was terminated due to an Access-control failure. (Note: 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.") If the origin system fails to respond correctly to the challenge during an Init request, the target may set the Result parameter to "reject" and may (optionally) supply such an indication in the User-information-field of the Init response.

The Access-control request/response mechanism can be used to support password challenges, public key cryptosystems, algorithmic authentication, etc. The specific content of the Access-control request and response parameters are outside the scope of this standard.

3.2.5.1.1 Security-challenge and Security-challenge-response

The contents of these two parameters are outside the scope of this standard and must be established by prior agreement between a given target/origin system pair.

3.2.5.1.2 Reference-id

See section 3.4.

3.2.6 Accounting/Resource Control Facility

The Accounting/Resource Control facility consists of the Resource-control service (initiated by the target during a Search, Present, or Delete operation), the Trigger-resource-control service (initiated by the origin during a Search, Present, or Delete operation), and the Resource-report service (initiated by the origin when no operation is pending).

The Resource-control service permits the target system to send a Resource-report, notifying the origin system when either actual or predicted resource consumption will exceed agreed upon limits (or limits built into the target system), and to obtain the origin system's consent to continue the operation. In addition, the target system can inform the origin system about the current status of a result set being generated on the target in response to a Search request, and indicate information about the status of the current request to the origin.

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

When no operation is pending, the Resource-report service permits the origin system to request that the target send a Resource-report.

3.2.6.1 Resource-control Service

A target system may issue a Resource-control request following receipt of an Init, Search, Present, or Delete request, prior to issuing the corresponding Init, Search, Present, or Delete response.

The target indicates whether a response to the request is required:

- If the target indicates that a response is required, the origin system must issue a Resource-control response. The target awaits the Resource-control response, and subsequently issues the Init, Search, Present, or Delete response, after processing of the operation is concluded.

- If the target indicates that a response is not required, the origin system must not issue a Resource-control response, and the target subsequently issues the Init, Search, Present, or Delete response, after processing of the operation is concluded.

If the origin responds to a Resource-control request with a Resource-control response saying to terminate the operation, it can expect to receive an Init, Search, Present, or Delete response. This response might indicate that the operation was terminated at origin request. However, the response might alternately indicate that the operation completed, since the operation at the target system may continue to execute and subsequently complete before the Resource-control response reaches the target system. See Table 7.

3.2.6.1.1 Resource-report

Resource-report may be used to convey information about the current and estimated resource consumption at the target system. The format of Resource-report bib-1 is defined in Appendix F.

         Table 7: Parameters of the Resource Control Service

                                   Origin          Target
        Parameter                  Request         Response
   ______________________________________________________________________
   Resource-report                 x (opt.)
   ______________________________________________________________________
   Partial-results-available       x (if appl.)
   ______________________________________________________________________
   Suspended-flag                  x (if appl.)
   ______________________________________________________________________
   Response-required               x
   ______________________________________________________________________
   Triggered-request-flag          x (opt.)
   ______________________________________________________________________
   Continue-flag                                   x
   ______________________________________________________________________
   Result-set-wanted                               x (if appl.)
   ______________________________________________________________________
   Reference-id                   x (if appl.)     x (if appl.)

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.

If the value of Partial-results-available is "none" then the target need not accept subsequent Present requests in the event that the request is terminated by the Resource-control response.

Note that if Suspended-flag is off, the partial results available situation may change since processing continues on the search. 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

The target system indicates whether or not processing of the command 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 system indicates whether or not a response (from the origin) to this request is required.

3.2.6.1.5 Triggered-request-flag

The target system 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

The origin indicates to the target whether or not to continue processing.

3.2.6.1.7 Result-set-wanted

This flag is meaningful only:

- during a Search request,

- when the value of Partial-results-available is "subset" or "interim," and

- when the value of the parameter Continue-flag is "do not continue."

3.2.6.1.8 Reference-id

See section 3.4.

3.2.6.2 Trigger-resource-control Service

An origin system may issue a Trigger-resource-control request following an Init, Search, Present, or Delete request, prior to receipt of the corresponding response. The request serves as a signal to the target system that the origin wishes the target to:

(a) simply send a Resource-report -- i.e. issue a Resource-control request with Response-required "off";

(b) invoke full resource control -- i.e. issue a Resource-control request with Response-required "on"; or

(c) cancel the current Init, Search, Present, or Delete operation.

If the origin issues a Trigger-resource-control request saying to cancel the command, and if the target honors the request, the origin can expect to receive an Init, Search, Present, or Delete response indicating that the request was terminated at origin request.

Although an origin system may issue a Trigger-resource-control request only prior to receipt of an Init, Search, Present, or Delete response, the target might issue such a response before it receives the Trigger-resource-control request. 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, 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.) See Table 8.

     Table 8: Parameters of the Trigger Resource Control Service

                                      Origin
        Parameter                     Request

   Requested-operation                x
   ______________________________________________________________________
   Preferred-resource-report-format   x (if applicable)
   ______________________________________________________________________
   Result-set-wanted                  x (if applicable)
   ______________________________________________________________________
   Reference-id                       x (if applicable)

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 current Init, Search, Present, or Delete operation.

This parameter is meaningful only when the value of the parameter Requested-operation is "resource-control" or "resource-report." It identifies a resource report format that the origin prefers.

3.2.6.2.3 Result-set-wanted

This flag is meaningful only during a Search request and when the value of the parameter Requested-operation is "cancel." If the value of the flag is "on," the origin requests that the target maintain the (possibly partial) result set for subsequent Present requests. See section 3.2.6.1.7.

3.2.6.2.4 Reference-id

See section 3.4.

3.2.6.3 Resource-report Service

The origin may issue a Resource-report request following receipt of an Init, Search, Present, or Delete response from the target. The target responds with a Resource-report response.

Note: The Resource-report service is a confirmed service and as such differs from the Trigger-resource-control service, which is non-confirmed. The origin may invoke the Resource-report service only in the "open" state, that is, following the conclusion of an operation (Init, Search, Present, Delete, or Resource-report) and prior to initiation of a subsequent operation. Therefore a Resource-report request from the origin requires a response from the target. (If the response were not determinable, then the origin would not be certain when to initiate a subsequent operation. In contrast, when the origin issues a Trigger-resource-control request, it awaits an action from the target--either a Resource-control request or an operation response--and therefore the lack of a deterministic response does not present sequencing problems.) However, although the target is obliged to send a Resource-report response, the target is not obliged to include a resource-report in the Resource-report response. See Table 9.

3.2.6.3.1 Preferred-resource-report-format

Identifies a resource report format that the origin prefers.

3.2.6.3.2 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 - Access terminated by target due to resource constraints.

failure-3 - Access-control failure.

failure-4 - Unspecified failure.

See 3.2.6.1.1.

3.2.6.3.4 Reference-id

See section 3.4.

              Table 9: Parameters of the Resource Report Service

                                      Origin          Target
        Parameter                     Request         Response

   Preferred-resource-report-format   x (opt.)
   ______________________________________________________________________
   Resource-report-status                             x
   ______________________________________________________________________
   Resource-report                                    x (opt.)
   ______________________________________________________________________
   Reference-id                       x (opt.)        x (if appl.)

3.2.7 The Termination Facility

The Termination Facility allows either:

1. an origin or target to initiate abrupt termination of the association via the IR-abort service element, or

2. an origin to initiate graceful termination via the IR-release service.

3.2.7.1 IR-abort Service

Either the origin or target may at any time either send or receive an IR-abort request, and consider the application association terminated.

3.2.7.2 IR-release Service

The origin may invoke an IR-release request following receipt of an Init, Search, Present, Delete, or Resource-report response. It should then await receipt of an IR-Release response, and then consider the association terminated. Alternately, it might receive an IR-abort request from the target, in which case it should consider the application association terminated.

The target may receive an IR-release request after sending an Init, Search, Present, Delete, or Resource-report response. It should then send an IR-release response, and consider the association terminated.

3.3 Message Size Limitations

For both the Search and Present services, it is possible that the target will not be able to return the number of database records requested because of message size limitations. In that case, the target is responsible for packing as many records as possible into the response message. (Note: A response message always contains an integral number of records; a record never spans response messages.)

Illustration

Assume that the target is attempting to transmit records in result set positions 1 through 10 (in this section, the term "record" means "database or surrogate diagnostic record," unless "diagnostic record" or "database record" is specified). Assume further that:

- records in position 1 through 6 fit in the response message, such that the sum of the sizes of the records (not including any protocol control information) does not exceed Preferred-message-size; but,

- the database record in position 7 will not fit in the message along with records in position 1 through 6 without the resulting sum of the record sizes exceeding Preferred-message-size. The size of the database record in position 7:

(a) does not exceed Preferred-message-size, or

(b) exceeds Preferred-message-size, but does not exceed Maximum-record-size, or

(c) exceeds Maximum-record-size.

In case (b) or (c) if the diagnostic record will not fit along with the records in position 1 through 6, the target returns the records in position 1 through 6. (Preferred-message-size must always be large enough to contain any diagnostic record; thus a subsequent Present request beginning with the record in position 7 will retrieve the diagnostic.) Otherwise, the target inserts the diagnostic record and proceeds to attempt to fit records in positions 8 through 10 into the response message.

Exception

If a Present request specifies a single record (i.e. Number-of-records-requested equals 1) then if the size of that record exceeds Preferred-message-size, but does not exceed Maximum-record-size, the target will return that single database record in the Present response. Note that this exception applies only to a Present request and not to a Search request.

Thus in case (b), the origin may subsequently request the database record in position 7, by issuing a Present request in which that record is the only record requested.

Note that the purpose of this distinction between Preferred-message-size and Maximum-record-size is to allow the transfer of normal length records to proceed in a routine fashion, with convenient buffer sizes, but to also provide for the transfer of an occasional exceptionally large database record without requiring the origin to continually allocate and hold local buffer space for worst-case records. Note also that this intended purpose is defeated if the origin routinely requests a single record.

3.4 Reference-id

The parameter Reference-id is optional in an Init, Search, Present, Delete, and Resource-report request. If supplied,

- it must be echoed by the target in the respective response;

- it must be echoed in both the request and response of any intermediate Access-control or Resource-control request/response sequences; and

- it must be echoed by the origin in any intermediate Trigger-resource-control request.

The service does not assume any relationship between the Reference-id used in an Init, Search, Present, Delete, or Resource-report request and the Reference-id used in any other Init, Search, Present, Delete, or Resource-report request.

The purpose of this parameter is to facilitate the grouping of events by the origin system. This standard does not specify its contents. Reference-ids are always assigned by the origin and have meaning only within the origin system. Since there are no semantics attributed to this parameter, it has no implied datatype and can only be described as transparent binary data. It is therefore described as ASN.1 type OCTETSTRING.