ANSI/NISO Z39.50-1992 ISSN: 1041-5653 (Revision of ANSI/NISO Z39.50-1988)
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 184.108.40.206 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.
220.127.116.11 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.)18.104.22.168.1 Id/authenmtication
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.
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:
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:
Note: the above two lists of capabilities are subject to expansion in future versions of this protocol.
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."
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.
22.214.171.124.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.
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.
This field may be used by either the origin or target for additional information not specified by this standard.
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.
126.96.36.199 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.)188.8.131.52.1 Query-type and Query
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-1 is the Reverse Polish Notation (RPN) query specified in section 184.108.40.206.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-NOTWhere
"::=" means "is defined as," "|" means "or," "+" means "followed by," and + has precedence over | (i.e., + is evaluated before |).Notes:
(1) "RPN-query" is recursively defined; it is either
(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 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.
- 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."
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).
220.127.116.11.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 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.
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:
- it is unilaterally erased or deleted by the target.
- 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 18.104.22.168.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 not valid for the given database, the response-record should be composed according to the default element set name for that database.
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.
22.214.171.124.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 126.96.36.199.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.
(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 188.8.131.52.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:
- 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."
184.108.40.206.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.
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).
The parameter Search-status, returned in the response, assumes one of the following two values:
failure - the search did not complete successfully
220.127.116.11.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:
interim - Partial results available, not necessarily valid.
none - No results available (result set is empty).
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.
18.104.22.168 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.)22.214.171.124.1 Number-of-records-requested and Result-set-start-position
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).
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.
The parameter Element-set-names describes the preferred composition of the records expected in the Present response. See section 126.96.36.199.4.
See section 188.8.131.52.5.
The parameter Database/diagnostic-records returned by the target consists of one of the following:
- 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.
184.108.40.206.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).
Present-status is mandatory in a Present response and its values are the same as those listed for Present-status in 220.127.116.11.11.
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.
18.104.22.168 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.)22.214.171.124.1 Delete-operation
The origin specifies one of the following:
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.
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 Description126.96.36.199.4 Delete-list-statuses
______________________________________________________________________ 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 188.8.131.52.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.
184.108.40.206.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.
Delete-msg, if present, contains an optional text message.
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.)220.127.116.11 Access-control Service
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 18.104.22.168.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.
22.214.171.124.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.
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.
126.96.36.199 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 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.
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.)188.8.131.52.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:
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.
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."
The target system indicates whether or not a response (from the origin) to this request is required.
The target system may optionally indicate whether or not this request resulted from a Trigger-resource-control request from the origin.
The origin indicates to the target whether or not to continue processing.
This flag is meaningful only:
- when the value of Partial-results-available is "subset" or "interim," and
- when the value of the parameter Continue-flag is "do not continue."
See section 3.4.
184.108.40.206 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:
(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)220.127.116.11.1 Requested-operation
The origin indicates one of the following:
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.
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 18.104.22.168.7.
See section 3.4.
22.214.171.124 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.
Identifies a resource report format that the origin prefers.
The target supplies one of following status values:
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 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:
126.96.36.199 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.
188.8.131.52 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.)
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:
- 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:
(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.
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.
The parameter Reference-id is optional in an Init, Search, Present, Delete, and Resource-report request. If supplied,
- 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.