[Table of Contents | Previous Section | Next Section]

3.2.10 Explain Facility
The Explain facility allows an origin to obtain details of the implementation of a target, including databases available for searching, attribute sets and diagnostic sets used by the target, and schema, record syntax and element specification definitions supported for retrieval. Targets that support the Explain facility:

• provide access (via the Z39.50 Search and Present services) to a database with the name IR-Explain-1 (referred to as the "Explain database");
• support the explain attribute set, exp-1, defined in Appendix 3 ATR (which defines a set of Use attributes and imports bib-1 non-Use attributes); and
• support the Explain syntax, which is defined and registered in Appendix 5 REC.

A record (or result set item representing a record) within the Explain database, is referred to as an "Explain record".

3.2.10.1 Searching the Explain Database
The Explain database appears to the origin as any other database supported by the target. However, certain search terms, corresponding to information categories, are predefined in order to allow a semantic level of interoperability. Terms are searched case-insensitive.

The exp-1 attribute set is used to search the Explain database. Combinations of Use attributes and terms allow searching upon information category; well-defined combinations of Use attributes may be used to allow additional specification by the origin to limit the records to those of immediate interest. Combinations of exp-1 Use attributes to perform a common set of searches are listed in 3.2.10.1.1 and 3.2.10.1.4. Since the Explain database may be searched as any other database using attributes from one or more attribute sets, this list is not exhaustive. However, it is recommended that a target supporting the Explain facility support this list of common searches. As described in 3.2.10.1.2 and 3.2.10.1.3, the HumanStringLanguage, DateAdded, DateChanged, and DateExpires attributes can be used in combination with any of the combinations listed in 3.2.10.1.1 and 3.2.10.1.4.

The exp-1 attribute set consists of a set of Use attributes and imports the non-Use bib-1 attributes. It is recommended that a target supporting the Explain facility support the bib-1 relation attribute 'equal' (see note), position attribute 'any position in field', and structure attribute 'key'.

Note: If the target intends to support searching based on date ranges (e.g. to limit a search to records created before or after a particular date or between two dates), the target should also support one or more of the following relation attributes: 'less than', 'less than or equal', 'greater than', and 'greater or equal'.

Origins should not in general expect that the explain database is searchable using the bib-1 truncation attribute, completeness attribute nor any of the alternative values of the relation, position and structure attributes defined in bib-1. However, targets are free to provide access to the Explain database using those and other alternative attributes and attribute values.

3.2.10.1.1 Searching for Predefined Information Categories. Records corresponding to a particular explain information category are searched by an operand where the term is the name of that category; for example, all records corresponding to TargetInfo are searched using the term "TargetInfo." For each category one or more key elements are defined, and may be provided as search terms (using the appropriate attribute). A search with an operand where the Use attribute = 'ExplainCategory' and the term is a category, and with additional operands corresponding to each key for that category where the value of the Use attribute is the key, should result in (at most) a single record.

The primary mechanism for search and retrieval of information from the Explain database is for the origin to select the records in a category using the Use attribute 'ExplainCategory' and to extract desired information from those records to formulate a subsequent search. For example the origin may search records with ExplainCategory = 'DatabaseInfo,' and retrieve summary information (see 3.2.10.2.2) from those records. Each summary record will include a database name, which serves as a key for a possible subsequent search.

A list and brief description of the Explain information categories (and thus search terms) are given in the table below, as well as the keys for each category. In 3.2.10.3 each category is described in detail.

An origin should adhere to the following rules when searching an Explain database by the predefined information categories.

• To search for information about the target, use ExplainCategory='TargetInfo'.
• To search for information about a specific database, use ExplainCategory='DatabaseInfo' in combination with the DatabaseName attribute to specify the key of the desired databaseInfo record.
• To search for information about a specific schema, use ExplainCategory='SchemaInfo' in combination with the SchemaOID attribute to specify the desired schema.
• To search for information about a specific tag set, use ExplainCategory='TagSetInfo' in combination with the TagSetOID attribute to specify the desired tag set.
• To search for information about a specific record syntax, use ExplainCategory='RecordSyntaxInfo' in combination with the RecordSyntaxOID attribute to specify the desired record syntax.
• To search for information about a specific attribute set, use ExplainCategory='AttributeSetInfo' in combination with the AttributeSetOID attribute to specify the desired attribute set.
• To search for information about term lists for a database, use ExplainCategory='TermList-Info' in combination with the DatabaseName attribute to specify the desired database.
• To search for information about a specific extended service, use ExplainCategory = 'ExtendedServicesInfo' in combination with the oid for that extended service.
• To search for the attributes and combination of attributes which may be used in searching a database, use ExplainCategory='AttributeDetails' in combination with the DatabaseName attribute to specify the database for which attribute information is desired.
• To search for information about a specific term list, use ExplainCategory = 'TermListDetails' in combination with the name for the term list.
• To search for the element set names defined for a record syntax for a particular database, use ExplainCategory='ElementSetDetails' in combination with the RecordSyntaxOID attribute to specify the desired record syntax and the DatabaseName attribute to specify the desired database.
• To search for the definition of a specific element set name, use ExplainCategory = 'ElementSetDetails' in combination with the ElementSetName attribute to specify the desired element set name. There may be multiple records located since the explain database contains one record for each element set name for each record syntax for each database
• To search for a particular element set name defined for a record syntax, for a particular database, use ExplainCategory = 'ElementSetDetails' in combination with the ElementSetName attribute to specify the desired element set name, the RecordSyntaxOID attribute to specify the desired record syntax and the DatabaseName attribute to specify the desired database.
• To search for the description of the elements of a retrieval record, for a particular record syntax, in a specific schema, for a particular database, use ExplainCategory='RetrievalRecordDetails' in combination with the RecordSyntaxOID attribute to specify the desired record syntax, the SchemaOID attribute to specify the desired schema, and the DatabaseName attribute to specify the desired database.

Table 14: Explain Categories

3.2.10.1.2 Searching for Information in a Particular Language. Elements intended to be presented to the user by the origin are said to consist of "human readable text." Each record includes a language element indicating the language of the human readable text within the record. The explain database might contain several records with identical information, in different languages. To search for records in a certain language, the HumanStringLanguage attribute may be used (in conjunction with the three-character language code as the term; see Z39.53-1994).

For example, to search for a list of databases that have descriptive records in English, the query might be of the form:

(Category = 'DatabaseInfo') AND (HumanStringLanguage = 'eng').

The HumanStringLanguage attribute is intended primarily for use in Version 2. When version 3 is in force, the use of variants is recommended.

3.2.10.1.3 Searching for Information by Control Dates. To search for new records in an Explain database, use the DateAdded attribute; for updated records use the DateChanged attribute, for records based on their date of expiry use the DateExpires attribute. Any of these three may be used in combination with the searches described above.

3.2.10.1.4 Searching for Information Using Content Values. Some of the Explain records are searchable using attributes which take values from elements within the pertinent Explain records. These Use attributes can be used to select subsets of records of specific information category. For instance, the Availability Use attribute can be used to select those database information records for databases which are currently available. The use of these attributes by an origin should conform to the following rules.

• To locate databases currently available, use the ExplainCategory attribute with term 'DatabaseInfo,' in combination with the Availability attribute with term 'yes'.
• To locate the databases provided by a specific supplier, use the ExplainCategory attribute with term 'DatabaseInfo,' in combination with the Supplier attribute with the supplier's name as term.
• To locate databases provided by a specific producer, use the ExplainCategory attribute with term 'DatabaseInfo' in combination with the Producer attribute with the producer's name as term.
• To locate databases that are not proprietary, use the ExplainCategory attribute with term 'DatabaseInfo,' in combination with the Proprietary attribute with term 'no'.
• To locate databases that have no user fee, use the ExplainCategory attribute with term 'DatabaseInfo,' in combination with the UserFee attribute with term 'no'.

3.2.10.2 R etrieval of Explain Records
A Present request for Explain records should specify the Explain syntax as the Preferred-record-syntax. Each explain information category has its own record layout, and all are described in the Explain syntax definition (see Appendix 5 REC.1).

Explain records include key elements which serve to uniquely identify each record. Each Explain category is defined in term of key elements, non-key "brief" elements (see 3.2.10.2.2), "non-brief" elements, and possibly other categories. Key elements are always part of the brief elements.

3.2.10.2.1 Retrieval and Human Readable Text. The Explain database might provide alternative variations of human readable information (however, for language variations; see note below). For example, a text element might be retrievable in ASCII, SGML, or Postscript. To request a particular format, use the variant facilities of Version 3.

Note: For language variation, see 3.2.10.1.2. The Explain database logically includes different records for different languages, and therefore selection based on language occurs during the search.

3.2.10.2.2 Retrieving Summary and Descriptive Information. The Explain facility provides for the retrieval of summary, or "brief" information. For example the origin may request summary information about all of the databases supported by a target without retrieving the full databaseInfo records. Within each category's definition, elements are designated as "brief" or "non-brief." Elements designated "brief" are obtained when using the element set name 'B'. Elements designated "non-brief" are obtained (along with brief-elements) when using the element set name 'F'.

The Explain facility also provides for the retrieval of descriptive information, for certain categories, via the element set name 'description' (for details, refer to the ASN.1 definition for the Explain syntax). For example, a Database-info record includes an element which contains a description (in human readable text) of the database; to retrieve only the brief elements and the description element, the element set name 'description' may be used.

Individual categories defined in the Explain syntax may designate other element set names for specific subsets of information within that category.

3.2.10.3 Detailed Descriptions of the Information Categories
This section includes complete descriptions of each information category. In addition to the information enumerated, each record:

• contains information about the record itself, e.g. date of creation and expiration date of the record; and
• includes an element indicating the language of the "human readable text" elements of the record.

These are logical descriptions, which do not reflect the possibility that there might be language variants of a record or syntax variants of a element.

Many of the Explain elements are optional, but are not so indicated in the description below. For specific information, refer to the ASN.1 definition.

3.2.10.3.1 Target-Info. Information about the target. There is one such Explain record in the Explain database.

Brief elements:

• A name for the target (only one), in human readable text.
• Recent news of interest to people using this target, in human readable text.
• An icon used to represent this target (in machine presentable form).
• Whether named results sets are supported.
• Whether multiple databases can be searched in one search request.
• The maximum number of concurrent result sets supported.
• The maximum size (in records) of a result set.
• The maximum number of terms allowed in one search request.
• A timeout interval after which the target will trigger an event if no activity has occurred.
• A "welcome" message from the target to be displayed by the origin.

Non-brief elements:

• Contact information for the organization supporting this target.
• A description of the target, in human readable text.
• A set of nicknames or alternate names by which the target is known.
• Restrictions pertaining to this target, in human readable text.
• A payment address (e.g. business office) for the organization supporting this target.
• Hours of operation.
• A list of supported database combinations.
• Internet address and Port number.
• OSI addresses.
• Languages supported for message strings.
• The following elements, where each object listed is supported for one or more databases. (To determine which are supported for a particular database, retrieve the record for that database.)
  • Which query-types are supported, and details for each supported type.
  • Diagnostic sets supported.
  • Attribute sets supported.
  • Schemas supported.
  • Record syntaxes supported.
  • Resource challenges supported.
  • Access challenges supported.
  • Cost information.
  • Variant sets supported.
  • Element set names supported.
  • Unit systems supported.

3.2.10.3.2 Database-Info Detailed description of a database and database-related restrictions and parameters. There is one such Explain record for each database supported.

Brief elements:

• Full database name (only one).
• Whether this is an Explain database (possibly for a different server).
• A list of short (or alternate) names for the database.
• An icon used to represent this database (in machine presentable form).
• Whether there is charge to access this database.
• Whether this database is currently available for access.
• A human-readable name or title for the database (as opposed to the database name, which is typically a short string not meant to be human-readable, and not variable by language.)

Non-brief elements:

• A list of keywords for the database.
• A description of the database, in human readable text.
• Associated databases: those that the target allows (and possibly encourages) to be searched in combination with this database.
• Sub-databases that make up this conceptual single database.
• Any disclaimers concerning this database, in human readable text.
• News about this database, in human readable text.
• A record count for the database (and whether the count is accurate or an estimate).
• A description of the default order in which records are presented, in human readable text.
• An estimate of the average record size (in bytes).
• A maximum record size (in bytes).
• Hours of operation that this database is available.
• Best time to access this database, in human readable text.
• Time of last update of this database.
• Update cycle/interval for this database.
• Coverage dates of this database, in human readable text.
• Whether this database contains proprietary information.
• A description of copyright issues relating to this database, in human readable text.
• A notice concerning copyright which the target expects the origin to display to the user if possible, in human readable text.
• Description and contact information for the database producer, database supplier, and for how to submit material for inclusion in this database, in human readable text.
• Which query-types are supported for this database, and details for each supported type.
• Diagnostic sets supported for this database.
• Attribute sets supported for this database.
• Schemas defined for this database.
• Record syntaxes supported by this database.
• Resource reports supported for this database.
• Text describing access control for this database, in human readable text.
• Costing information related to this database, in both machine readable format, and in human readable text, for connect, present, and search.
• Variant sets supported for this database.
• Element set names supported for this database, with names and descriptions given in human readable text.
• Unit systems supported for this database.

3.2.10.3.3 Schema-Info. Descriptive information about a database schema. There is one Explain record for each schema supported by the target. Note: this is not specific to a database.

Brief elements:

• The object identifier of the schema definition.
• The name of this schema.:

Non-brief elements

• A description of this schema, in human readable text.
• TagSets used by this schema, and for each, a designated tagType.
• The abstract record structure defined by this schema.

3.2.10.3.4 Tag-Set-Info. Descriptive information about a given tagSet. There is one such Explain record for each supported tagSet.

Brief elements:

• The object identifier for the tagSet.
• The name of this tagSet.

Non-brief elements:

• A description of this tagSet, in human readable text.
• For each element defined in the tagSet:
  • The name of the element.
  • Nicknames for the element.
  • The tag assigned to the element.
  • A description of the element.
  • Its datatype.

3.2.10.3.5 Record-Syntax-Info Descriptive information about a record syntax. There is one Explain record for each abstract record syntax supported by the target. Note: this is not specific to a database.

Brief elements:

• The object identifier of the abstract record syntax.
• A name by which this syntax is known.

Non-brief elements:

• Transfer syntaxes supported for this abstract syntax (object identifiers).
• A description of this abstract record syntax, in human readable text.
• An ASN.1 module describing the syntax.
• The record structure defined by this syntax.

3.2.10.3.6 Attribute-Set-Info Descriptive information about an attribute set. There is one record for each supported attribute set.

Brief elements:

• The attribute set Id (object identifier) for this attribute set.
• Its name.

Non-brief elements:

• For each attribute type, its name, description, and integer value of the type, and a list of attributes. For each attribute:
  • Its name.
  • Description.
  • Its value.
  • Names of equivalent attributes. Equivalences are derived from the attribute set definition (not from the targets behavior).
  Description of the attribute set.

3.2.10.3.7 TermList-Info Descriptive information about term-lists. There is one Explain record for each database.

Brief elements:

• Full database name (one only).
• Summary information about each term-list associated with this database (for each term-list described, there is a TermList-details record):
  • Name of the term-list. Must be unique for the database. This is the name to be used to search for the TermList-details record for this term list.
  • Its title. For users to see; need not be unique.
  • An indication of how expensive it is to search, using the associated attributes. The target indicates one of the following:
  • The attribute (combination) associated with this list will do fast searches. Note: To obtain the attribute combination, retrieve the associated TermList-details record.
  • The attribute (combination) will work as expected. So there is probably an index for the attribute (combination) or some similar mechanism.
  • Can use the attribute (combination), but it might not provide satisfactory results. Probably there is no index, or post- processing of records is required.
  • Cannot search with this attribute (combination) alone.
  • Whether the term-list may be scanned.
  • A list of names of alternative, broader term-lists.
  • A list of names of alternative, narrower term-lists.

(No non-brief elements.)

3.2.10.3.8 Extended-Services-Info Descriptive information about an extended service. There is one Explain record for each extended service supported.

Brief elements:

• The object identifier of the extended service.
• A name by which this extended service is known.
• Boolean flags, indicating:
  • Whether it is a private extended service.
  • Whether restrictions apply.
  • Whether a fee applies.
  • Whether the service is available.
  • Whether retention is supported.
• What level of wait-action is supported.

Non-brief elements:

• A description, in human readable text.
• Explain elements specific to this extended service (defined within the specific extended service definition).
• An ASN.1 module for the Explain definition.

3.2.10.3.9 Attribute-Details Information for each attribute. There is one Explain record for each supported database.

Brief elements:

• Name of the database to which this attribute information applies.

Non-brief elements:

• For each attribute set supported for the database, the object identifier of the attribute set, and for each attribute within the set:
  • The attribute type.
  • A default value which applies if the attribute is omitted, and a description of default behavior in human readable form.
  • For each value of the attribute:
  • The attribute value.
  • A description of that value in human readable text.
  • Sub-attributes (for Use attributes): a list of alternative values that allow access to the same aspect of the record, but in greater detail.
  • Super-attributes (for Use attributes): a list of alternative values that allow access to the same aspect of the record at a coarser level.
  • Whether the value is only "partially supported": i.e. the value is accepted but may not provide expected results.
• A list of all attributes combinations supported for the database.

3.2.10.3.10 Term-list-Details Descriptive information for a term-list. There is one record for each term-list listed by TermList-info records.

Brief elements:

• Name of the term-list.

Non-brief elements:

• A description.
• Attribute combination corresponding to this list. If list may be scanned, this is the attribute combination to be used by scan.
• Maximum step-size supported.
• Collating sequence (e.g. ASCII, EBCDIC) in human-readable text.
• Order (ascending or descending).
• Estimated number of terms.
• A list of sample terms (not guaranteed to be valid; optimally would represent a uniformly distributed sampling of the list).

3.2.10.3.11 Element-Set-Details. Descriptive information about an element set. There is one Explain record for each element set for each record syntax for each database.

Brief elements:

• The database to which this record pertains.
• The element set name for the element set described by this record.
• The record syntax to which this record pertains.
• The schema for which this element set is defined.

Non-brief elements:

• A description, in human readable text, of the element set.
• For each element in the element set, the information provided for each element by the Retrieval-Record-Details category.

3.2.10.3.12 Retrieval-Record-Details. Descriptive information about the elements of a retrieval record. Note that the elements are relative to a database schema. There is one such Explain record for each database for each schema for each record syntax.

Brief elements:

• The database, schema, and record syntax to which this Explain record pertains.

Non-brief elements (for each element described by the syntax):

• The name of the element.
• The tag of the element, if any.
• A list of schema elements that comprise this element within the record syntax.
• The maximum size of the element.
• The minimum size of the element.
• The average size of the element.
• The size of the element, if fixed length.
• Whether or not the element is repeatable.
• Whether or not the element is required.
• A description of the element, in human readable text.
• A description of its contents, in human readable text.
• Charging/billing issues related to this element, in human readable text.
• Restrictions (e.g. copyright, proprietary) pertaining to use and access to this element, in human readable text.
• Alternate names for this element.
• Generic names for this element text (e.g. a "geographicSubject" element might also be under the generic name "subject").
• Attribute combinations corresponding to this element.

3.2.10.3.13 Sort-Details. Description of the sorting capabilities supported by the target. There is one record for each database.

Brief elements:

• Database to which this sort description pertains.

Non-brief elements:

• For each sort key:
  • A description.
  • If the key is a record element, a specification of the element.
  • If the key is an attribute combination, a specification of that combination.
  • The type of key: character, numeric, structured.
  • Whether the key is case-sensitive.

3.2.10.3.14 Processing-Info. Instructions, representing how the target believes the data should be processed by the origin for presentation to the user. Instructions are defined externally. For a given database and processing context (access, search, retrieval, record-presentation, and record-handling) for which the target offers processing information, there may be more than one set of instructions; these are distinguished by name. Each set of instructions may be available in more than one abstract syntax; these are distinguished by object identifier. Thus an Explain record of this type is distinguished by database, processing context, name, and object identifier.

Brief elements:

• Full name of the database to which this record pertains.
• The context for which this processing information is pertinent.
• A name for this processing information.
• An object identifier, for the abstract syntax of the externally defined instructions.

Non-brief elements:

• A description of the instructions, in human readable form.
• The machine processable instructions, externally defined (whose abstract syntax is identified by the object identifier referenced above).

3.2.10.3.15 Variant-set-info. Descriptive information about a variant set definition supported by the target; classes, types, and values supported for a particular variant set. Support of a particular variant set definition does not imply that the definition is supported for any specific database or element.

Brief elements:

• The object identifier of the variant set definition.
• Its name.

Non-brief elements:

• A list of supported classes, including name and description; and for each, a list of supported types, including name and description; and for each, a list of supported values.

3.2.10.3.16 Unit-info Descriptive information about a unit system definition supported by the target.

Brief elements:

• The name of the unit system.

Non-brief elements:

• A description.
• A list of unit types, including name and description, and for each, a list of units, including name and description.

3.2.10.3.17 Category-list A list of the Explain categories supported by the target. There is one such record for the Explain database. It consists of the information below, for each supported category.

Brief elements:

• The search term used in conjunction with Use attribute of ExplainCategory to search for records of this category.

Note: the following need occur only if the target is supporting a category not defined in this standard.

• The original search term. (This is for information categories where the target is supporting a revision of the original definition of a category.)
• A description.
• An ASN.1 definition of the record for this category.