[Table of Contents | Previous Section | Next Section]
3.2.1 Initialization
Facility
The Initialization facility consists of the single service, Init.
3.2.1.1 Init Service
The Init service allows the origin to establish a Z-association. In the Init
request, the origin proposes values for initialization parameters. In the Init
response, the target responds with values for the initialization parameters;
those values, which may differ from the origin-proposed values, are in effect
for the Z-association.
If the target responds affirmatively (Result = 'accept'), the Z-association is established. If the origin then does not wish to accept the values in the target response, it may terminate the Z-association, via the Close service (and may subsequently attempt to initialize again). If the target responds negatively, the origin may attempt to initialize again.
Table 1: Parameters of the Init Service
Parameter |
Origin Request |
Target Response |
Version | x | x |
Id/Authentication | x (opt) | x |
Options | x | x |
Preferred-message-size | x | x |
Exceptional-record-size | x | x |
Result | x | |
Implementation-id | x (opt) | x (opt) |
Implementation-name | x (opt) | x (opt) |
Implementation-version | x (opt) | x (opt) |
User-information-field | x (opt) | x (opt) |
Other-information | x (opt) | x (opt) |
Reference-id | x (opt) | x (if appl) |
3.2.1.1.1 Version. Both the origin and target indicate all versions that they support. The highest common version is selected for use, and is said to be 'in force,' for the Z-association. If there are no versions in common, the target should indicate 'reject' for the parameter Result.
Notes:
3.2.1.1.2 Id/authentication. 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, to the value. 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.3 Options. For each of the capabilities listed below, the origin proposes either 'on' or 'off' (meaning 'in effect' or 'not in effect' respectively) and the target responds correspondingly for each. The response determines whether the capability is in effect.
[For a complete list of options see Z39.50 Option Bits]
Note: the above list of capabilities is subject to expansion in future versions of this protocol.
The following rules, describing how these capabilities are to be negotiated, are intended to allow interoperation even when the origin and target have not necessarily implemented the same capabilities.
The Options parameter consists of a string of boolean flags, each corresponding to an individual capability. The origin might set the flag to 'in effect' for a capability unknown to the target. In that case it is recommended that the target set the corresponding flag to 'not in effect' in the response. However, if the origin sets a flag to 'not in effect' and the target sets the corresponding flag to 'in effect,' and if the origin is not aware what capability that flag represents, it is recommended that the origin terminate the Z-association.
Search, present, delete, resource-report, scan, sort, and extended-services -- for each of these operation types, the origin indicates whether it wishes to initiate operations of that type; if so, the target indicates whether it is willing to process an operation of that type. If the origin proposes 'not in effect' for a particular operation type, the target must also specify 'not in effect'.
Notes:
Trigger-resource-control -- The origin may propose to submit Trigger-resource-control requests; if so, the target indicates whether it will accept Trigger-resource-control requests. If the origin proposes 'not in effect,' the target must also specify 'not in effect'.
Notes:
level 1 and level 2 segmentation -- The origin proposes one of the following:
Notes:
The target response indicates which, if either, form of segmentation it intends to perform.
When 'no segmentation' is in effect, the target response to a Present request must consist of a single message (a single "segment", i.e. a Present response only, with no intervening Segment requests), containing an integral number of records. When 'Level 1 segmentation' is in effect the target may respond to a Present request with multiple segments (i.e. a Present response, with possibly one or more intervening Segment requests); each must contain an integral number of records. When 'Level 2 segmentation' is in effect the target may respond to a Present request with multiple segments, and individual records may span segments. Segmentation procedures are detailed in 3.3.
Concurrent-operations -- The origin may propose to initiate concurrent operations; if so, the target indicates whether it will accept concurrent operations. If the origin proposes 'not in effect,' the target must also specify 'not in effect'. If concurrent operations is not in effect, then 'serial operations' is said to be in effect. Concurrent operations may be in effect only when version 3 is in force.
Named-result-sets -- The origin may propose to use named-result sets (i.e. to specify result set names other than "default" as the value of Result-set-name within a Search request); if so, the target specifies whether it will support named-result-sets. If the origin proposes 'not in effect,' the target must also specify 'not in effect'.
Resource-control and access-control -- The origin indicates whether it wishes the target to invoke Resource-control and/or Access-control (i.e. send Resource-control and/or Access-control requests). The target specifies whether it plans to invoke Resource-control and/or Access-control.
Notes:
3.2.1.1.4 Preferred-message-size and Exceptional-record-size. The Init request contains the origin's proposed values of Preferred-message-size and Exceptional-record-size, specified in bytes. The Init response contains the Preferred-message-size and Exceptional-record-size that the target is going to use; these may be different from (and override) the values proposed by the origin. For both the request and response, Preferred-message-size must be less than or equal to Exceptional-record-size.
Exceptional-record-size is meaningful during a Present operation, and only in the special case when a single, exceptionally large record (i.e. larger than preferred-message-size) is requested in the Present request. In this special case, preferred-message-size may be overridden (for the present operation), so that a single record may be presented whose size may be as large as Exceptional-record-size. The fact that a single record is requested is how the origin signals that preferred-message-size may be overridden. Thus Exceptional-record-size must be greater than or equal to preferred-message-size. In the case where they are equal, Exceptional-record-size has no meaning (this is the way to signify that the special case will not apply during the Z-association).
The usage of these parameters is detailed in 3.3.
Note: The parameter Exceptional-record-size has the same meaning as the parameter Maximum-record-size defined in Z39.50-1992. The name of the parameter has been changed, for clarity.
3.2.1.1.5 Result The target indicates whether or not it accepts the Z-association by specifying a value of 'accept' or 'reject' in the parameter Result. (If 'reject' is indicated, the origin may send another Init request.)
3.2.1.1.6 Implementation-id, Implementation-name, and Implementation-version The request or response may optionally include any of these three parameters. They are, respectively, an identifier (unique within the client or server system), descriptive name, and descriptive version, for the origin or target implementation. These three implementation parameters are provided solely for the convenience of implementors, for the purpose of distinguishing implementations.
3.2.1.1.7 User-information-field This parameter may be used by the origin or target for additional information not specified by this standard.
3.2.1.1.8 Other-information This parameter may be used by the origin or target for additional information not specified by the standard. This parameter may be used only if version 3 is in force.
Note: Care should be taken by the origin when using this parameter; the origin cannot ascertain that version 3 is in force before sending the Init request.
3.2.1.1.9 Reference-id See See 3.4.
3.2.2 Search Facility
The Search facility consists of the single service, Search.
3.2.2.1 Search Service
The Search service enables an origin to query databases at a
target system, and to receive information about the results of the query.
The search request allows the origin to request that the target apply a query to a specified set of databases at the target, to identify records with the properties indicated by the query. The target creates a result set, which represents the set of records identified by the query, and the target maintains the result set for subsequent retrieval requests.
Depending on the parameters of the search, one or more records identified by the result set may be immediately retrieved as part of the search response. The result set is an ordered set; a record identified by an entry in the result set is referenced by the position of the entry within the result set (beginning with 1).
Table 2: Parameters of the Search Service
Parameter |
Origin Request |
Target Response |
Query-type | x | |
Query | x | |
Database-names | x | |
Result-set-name | x | |
Replace-indicator | x | |
Small-set-element-set-names | x (opt) | |
Medium-set-element-set-nanes | x (opt) | |
Preferred-record-syntax | x (opt) | |
Small-set-upper-bound | x | |
Large-set-lower-bound | x | |
Medium-set-present-number | x | |
Response-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) | |
Additional-search-information | x (opt) | x (opt) |
Other-information | x (opt) | x (opt) |
Reference-id | x (opt) | x (if appl) |
3.2.2.1.1 Query-type and Query. The parameter Query-type identifies the type of query, i.e the syntax of parameter Query. Six types are defined:
3.2.2.1.2 Database-names. The origin indicates the set of databases to which the Query applies. Notes:
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 (to be created by the query) so that it may be subsequently referenced (within the same Z-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 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 target need not support, in general, the naming of result sets by the origin. However, a target must support at least the result set whose name is "default." If the origin specifies "default" as Result-set-name, then Replace-indicator must be 'on'.
A result set 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 Z-association during which it is created, or until either:
Any result set other than the result set named "default" remains available for reference from the time it is created until it is deleted in one of the following ways:
3.2.2.1.4 Small-set-element-set-names and Medium-set-element-set-names. These parameters 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. These two parameters are described in 3.6.2.
3.2.2.1.5 Preferred-record-syntax. The origin may specify a preferred record syntax for retrieval records. If the target cannot supply a particular record according to the Preferred-record-syntax, it supplies the record according to one of the other abstract syntaxes from the set for which Presentation contexts are currently established for this A-association.
If the target cannot supply the record according to either the requested syntax or a syntax corresponding to an established presentation context, it returns a surrogate diagnostic for that record, unless the established set of presentation contexts is empty; in that case, this standard does not prescribe the target action.
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 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, response records corresponding to 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 response records are to be returned. If the query results in a medium-set, the maximum number of response records to be returned is specified by Medium-set-present-number. Notes:
3.2.2.1.7 Response-records. 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. A particular database record might not be accessible but this circumstance might not be recognized until an attempt is made to access the record for the purpose of forming a retrieval record.
After processing the search, the target attempts to create retrieval records to be included in the Search response, corresponding to the first N database records identified by the result set (N depends on the request parameters and Result-count, as described in 3.2.2.1.6). For each database record for which a retrieval record cannot be included, a surrogate diagnostic record is substituted.
The term response record refers to a retrieval record or a surrogate diagnostic record. The parameter Response-records is one of the following:
The order of occurrence of response records within the parameter Response-records is according to the order in which they are identified by the result set. Each may optionally be accompanied by the name of the database in which the record resides. However, the database name must accompany the first response record being returned, and must accompany any record from a database different from its immediate predecessor.
3.2.2.1.8 Result-count and Number-of-records-returned. The parameter Result-count is the number of database 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 returned in the Search response.
3.2.2.1.9 Next-result-set-position. The parameter Next-result-set-position takes on the value M+1, where M is the position of the result set item which identifies the database record corresponding to the last response record among those returned; or zero if M = Result-count.
3.2.2.1.10 Search-status. The parameter Search-status, returned in the response, assumes one of the following two values:
success - The se arch completed successfully.
failure - The search did not complete successfully.
A value of 'success' does not imply that the expected response records are being returned as part of the response (see Present-status, 3.2.2.1.11). Note also, a value of 'success' does not imply that any database records were located by the search. A value of 'failure' does imply that none of the expected response records is being returned. In the latter case, the target returns one or more non-surrogate diagnostic records (see note) indicating that the search cannot be processed.
Note: If version 2 is in force, the target returns a single non-surrogate diagnostic record. If version 3 is in force, the target returns one or more non-surrogate diagnostic records.
3.2.2.1.11 Result-set-status and Present-status These are status descriptors necessary to distinguish potentially ambiguous 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 result set.
Present-status occurs if and only if the value of Search-status is 'success,' and its value is one of the following:
success - All of the expected response records are available.
partial-1 - Not all of the expected response records can be returned because the request was terminated by access control.
partial-2 - Not all of the expected response records can be returned because they will not fit within the preferred message size.
partial-3 - Not all of the expected response records can be returned because the request was terminated by resource control, at origin request.
partial-4 - Not all of the expected response records can be returned because the request was terminated by resource control, by the target.
failure - None of the expected response records can be returned. One or more non-surrogate diagnostic records is returned (see note in 3.2.2.1.7).
3.2.2.1.12 Additional-search-information. On the response the target may use this parameter to convey information which is a by-product of the search process, including, for example, intermediate result counts, why particular records were returned, or whether a particular attribute was used for searching a database. On the request the origin may use this parameter to indicate the preferred format or content of that information. User Information format SearchResponse-1 is defined in Appendix 8 USR. This parameter may be used only when version 3 is in force.
3.2.2.1.13 Other-information. This parameter may be used by either the origin or target for additional information not specified by the standard. This parameter may be used only when version 3 is in force.
3.2.2.1.14 Reference-id. See See 3.4.
3.2.3 Retrieval Facility
The Retrieval facility consists of two services: Present and Segment.
The origin sends a Present request to request response records according to position within a result set maintained by the target. The target responds by sending a Present response, containing the requested response records. Alternatively, if segmentation is in effect and the requested response records will not fit within the Present response message, the target may segment the response by sending one or more Segment requests before the Present response. The procedures for segmentation are described in 3.3.
The Segment requests (if any) together with the Present response are referred to as the aggregate Present response. Each Segment request as well as the Present response is referred to as a segment of the Present response. If an aggregate Present response consists of a single segment (i.e. only a Present response) it is called a simple Present response.
3.2.3.1 Present Service
The Present service allows the origin to request response records corresponding
to database records represented by a specified result set. Database records
are referenced by relative position within the result set. The origin specifies
a range and may follow with subsequent requests specifying different ranges.Notes:
Table 3: Parameters of the Present Service
Parameter |
Origin Request |
Target Response |
Number-of-records-requested | x | |
Result-set-start-position | x | |
Additional-ranges | x (opt) | |
Result-set-id | x | |
Element-set-names | x (opt) | |
Preferred-record-syntax | x (opt) | |
Comp-spec | x (opt) | |
Max-segment-count | x (opt) | |
Max-segment-size | x (opt) | |
Max-record-size | x (opt) | |
Reponse-records | x (if appl.) | |
Number-of-records-returned | x | |
Next-result-set-position | x | |
Present-status | x | |
Other-information | x (opt) | x (opt) |
Reference-id | x (opt) | x (if appl.) |
3.2.3.1.1 Number-of-records-requested and Result-set-start-position. The origin requests a range of records: N records beginning at record M. M = Result-set-start-position, N = Number-of-records-requested and N is not greater than (Result-count - M) + 1.
3.2.3.1.2 Additional-ranges. The origin may request additional ranges of records by including this parameter, which consists of one or more pairs (M, N) where M and N are as described in 3.2.3.1.1. For the first pair (M, N) M must be greater than or equal the sum of Result-set-start-position and Number-of-records-requested. For any consecutive pairs (M1, N1) and (M2, N2), M1 + N1 must be less than M2. This parameter may occur only when version 3 is in force.
3.2.3.1.3 Result-set-id. The origin indicates the name of a transient result set, created during this Z-association, from which records are to be retrieved.
3.2.3.1.4 Element-set-names. The origin may indicate the desired composition of the retrieved records. See 3.6.2.
3.2.3.1.5 Preferred-record-syntax. See 3.2.2.1.5.
3.2.3.1.6 Comp-spec. This parameter may be included only if the parameter Element-set-names is omitted, and only if version 3 is in force. If included, Comp-spec provides an alternative means of specifying the desired composition of retrieved records. See 3.6.
3.2.3.1.7 Max-segment-count, Max-segment-size, and Max-record-size These three parameters may be used only when version 3 is in force.
Max-segment-count may be included when level-1 or level-2 segmentation is in effect; it specifies the maximum number of segments the target may include in the aggregate Present response. If its value is 1, no segmentation is applied for the operation and Max-record-size should not be included.
Max-segment-size and/or Max-record-size may be included only when level 2 segmentation is in effect. Max-segment-size is the largest allowable segment; if included, it overrides Preferred-message-size (for this Present operation only); if not included it assumes the value of Preferred-message-size. Max-record-size is the largest allowable retrieval record within the aggregate Present response; if included, it must equal or exceed Max-segment-size.
These three parameters are further detailed in 3.3.3.2.
3.2.3.1.8 Response-records. This parameter consists of a sequence of response records, or possibly, if 'level 2 segmentation' is in effect, a final fragment (see 3.3.3) followed by zero or more response records. Alternatively (if the operation included no Segment requests) the parameter consists of one or more non-surrogate diagnostic records indicating that the request cannot be processed, and why not (see note below).
A response record will be returned in the aggregate Present response for each record requested in the request (subject to message size, access-control, and resource-control constraints). Each response record corresponds to a result set entry, and the result set ordinal positions represented by the response records will be ascending and consecutive, unless the request included the parameter Additional-ranges. In this case, the positions will be ascending but may have gaps which will correspond exactly to the gaps in the requested ranges.
Each response record may optionally be accompanied by the name of the database to which it corresponds. However, the database name must accompany the first response record (or starting fragment) within the first segment of the aggregate Present response, and must accompany any response record (or starting fragment of a response record) from a database different from its immediate predecessor within the aggregate Present response.
When the origin has received the aggregate Present response, the result (if all of the segments are re-assembled, and segmented response records re-assembled from their fragments) will be one of the following:
Note: If version 2 is in force, the target returns a single non-surrogate diagnostic record. If version 3 is in force, the target returns one or more non-surrogate diagnostic records.
3.2.3.1.9 Number-of-records-returned and Next-result-set-position The parameter Number-of-records-returned is the total number of records in the aggregate Present response. Next-result-set-position is the value M+1, where M is the position of the result set item corresponding to the last record among those included in the response; or zero if M is the position of the last result set item.
3.2.3.1.10 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. Present-status refers to the aggregate Present response.
3.2.3.1.11 Other-information This parameter may be used by the origin or target for additional information, not specified by the standard. This parameter may be used only if version 3 is in force.
3.2.3.1.12 Reference-id See 3.4.
3.2.3.2 Segment Service
If the records requested by a Present request will not fit in
a single segment, and if segmentation is in effect, the target returns multiple
segments, each of which contains a portion of the records. Each except the last
segment is returned as a Segment request (the last segment is returned as a
Present response). Notes:
Table 4: Parameters of the Delete Service
Parameter | Target Request |
Segment-records | x |
Number-of-records-returned | x |
Other-information | x (optional) |
Reference-id | x (if applicable) |
3.2.3.2.1 Segment-records If level 1 segmentation is in effect, the parameter Segment-records consists of a sequence of response records.
If level 2 segmentation is in effect, the parameter Segment-records may include response records as well as fragments (see 3.3.3). It may be composed of a final fragment (except within the first segment of the aggregate Present response), followed by zero or more response records, followed by a starting fragment. Neither fragment need occur, however if neither occurs there must be at least one response record. (Note that fragments pertain only to retrieval records; a diagnostic record may not be segmented.)
The order of occurrence of a response record or fragment of a retrieval record is according to the order in which the record is identified by the result set. Each response record or starting fragment may optionally be accompanied by the name of the database to which it pertains. However, the database name must accompany the first response record (or starting fragment) within the first segment of the aggregate Present response, and must accompany any response record (or starting fragment of a retrieval record) from a database different from its immediate predecessor within the aggregate Present response.
3.2.3.2.2 Number-of-records-returned This is the total number of response records and starting fragments included within the segment.
3.2.3.2.3 Other-information This parameter may be used by the target for additional information, not specified by the standard.
3.2.3.2.4 Reference-id See 3.4.