- <screen>
- TITLE "Zen and the Art of Motorcycle Maintenance"
- ROOT
- AUTHOR "Robert Pirsig"
- </screen>
-
- </para>
-
- <para>
- A slightly more complex record would have the author element consist
- of two elements, a surname and a first name:
- </para>
-
- <para>
-
- <screen>
- TITLE "Zen and the Art of Motorcycle Maintenance"
- ROOT
- FIRST-NAME "Robert"
- AUTHOR
- SURNAME "Pirsig"
- </screen>
-
- </para>
-
- <para>
- The root of the record will refer to the record schema that describes
- the structuring of this particular record. The schema defines the
- element tags (TITLE, FIRST-NAME, etc.) that may occur in the record, as
- well as the structuring (SURNAME should appear below AUTHOR, etc.). In
- addition, the schema establishes element set names that are used by
- the client to request a subset of the elements of a given record. The
- schema may also establish rules for converting the record to a
- different schema, by stating, for each element, a mapping to a
- different tag path.
- </para>
-
- <sect2>
- <title>Tagged Elements</title>
-
- <para>
- A data element is characterized by its tag, and its position in the
- structure of the record. For instance, while the tag "telephone
- number" may be used different places in a record, we may need to
- distinguish between these occurrences, both for searching and
- presentation purposes. For instance, while the phone numbers for the
- "customer" and the "service provider" are both
- representatives for the same type of resource (a telephone number), it
- is essential that they be kept separate. The record schema provides
- the structure of the record, and names each data element (defined by
- the sequence of tags - the tag path - by which the element can be
- reached from the root of the record).
- </para>
-
- </sect2>
-
- <sect2>
- <title>Variants</title>
-
- <para>
- The children of a tag node may be either more tag nodes, a data node
- (possibly accompanied by tag nodes),
- or a tree of variant nodes. The children of variant nodes are either
- more variant nodes or a data node (possibly accompanied by more
- variant nodes). Each leaf node, which is normally a
- data node, corresponds to a <emphasis>variant form</emphasis> of the
- tagged element identified by the tag which parents the variant tree.
- The following title element occurs in two different languages:
- </para>
-
- <para>
-
- <screen>
- VARIANT LANG=ENG "War and Peace"
- TITLE
- VARIANT LANG=DAN "Krig og Fred"
- </screen>
-
- </para>
-
- <para>
- Which of the two elements are transmitted to the client by the server
- depends on the specifications provided by the client, if any.
- </para>
-
- <para>
- In practice, each variant node is associated with a triple of class,
- type, value, corresponding to the variant mechanism of Z39.50.
- </para>
-
- </sect2>
-
- <sect2>
- <title>Data Elements</title>
-
- <para>
- Data nodes have no children (they are always leaf nodes in the record
- tree).
- </para>
-
- <note>
- <para>
- Documentation needs extension here about types of nodes - numerical,
- textual, etc., plus the various types of inclusion notes.
- </para>
- </note>
-
- </sect2>
-
- </sect1>
-
- <sect1 id="data-model">
- <title>Configuring Your Data Model</title>
-
- <para>
- The following sections describe the configuration files that govern
- the internal management of data records. The system searches for the files
- in the directories specified by the <emphasis>profilePath</emphasis>
- setting in the <literal>zebra.cfg</literal> file.
- </para>
-
- <sect2>
- <title>The Abstract Syntax</title>
-
- <para>
- The abstract syntax definition (also known as an Abstract Record
- Structure, or ARS) is the focal point of the
- record schema description. For a given schema, the ABS file may state any
- or all of the following:
- </para>
-
- <para>
-
- <itemizedlist>
- <listitem>
-
- <para>
- The object identifier of the Z39.50 schema associated
- with the ARS, so that it can be referred to by the client.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The attribute set (which can possibly be a compound of multiple
- sets) which applies in the profile. This is used when indexing and
- searching the records belonging to the given profile.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The Tag set (again, this can consist of several different sets).
- This is used when reading the records from a file, to recognize the
- different tags, and when transmitting the record to the client -
- mapping the tags to their numerical representation, if they are
- known.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The variant set which is used in the profile. This provides a
- vocabulary for specifying the <emphasis>forms</emphasis> of data that appear inside
- the records.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Element set names, which are a shorthand way for the client to
- ask for a subset of the data elements contained in a record. Element
- set names, in the retrieval module, are mapped to <emphasis>element
- specifications</emphasis>, which contain information equivalent to the
- <emphasis>Espec-1</emphasis> syntax of Z39.50.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Map tables, which may specify mappings to
- <emphasis>other</emphasis> database profiles, if desired.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Possibly, a set of rules describing the mapping of elements to a
- MARC representation.
-
- </para>
- </listitem>
-
- <listitem>
- <para>
- A list of element descriptions (this is the actual ARS of the
- schema, in Z39.50 terms), which lists the ways in which the various
- tags can be used and organized hierarchically.
- </para>
- </listitem>
-
- </itemizedlist>
-
- </para>
-
- <para>
- Several of the entries above simply refer to other files, which
- describe the given objects.
- </para>
-
- </sect2>
-
- <sect2>
- <title>The Configuration Files</title>
-
- <para>
- This section describes the syntax and use of the various tables which
- are used by the retrieval module.
- </para>
-
- <para>
- The number of different file types may appear daunting at first, but
- each type corresponds fairly clearly to a single aspect of the Z39.50
- retrieval facilities. Further, the average database administrator,
- who is simply reusing an existing profile for which tables already
- exist, shouldn't have to worry too much about the contents of these tables.
- </para>
-
- <para>
- Generally, the files are simple ASCII files, which can be maintained
- using any text editor. Blank lines, and lines beginning with a (#) are
- ignored. Any characters on a line followed by a (#) are also ignored.
- All other lines contain <emphasis>directives</emphasis>, which provide
- some setting or value to the system.
- Generally, settings are characterized by a single
- keyword, identifying the setting, followed by a number of parameters.
- Some settings are repeatable (r), while others may occur only once in a
- file. Some settings are optional (o), whicle others again are
- mandatory (m).
- </para>
-
- </sect2>
-
- <sect2>
- <title>The Abstract Syntax (.abs) Files</title>
-
- <para>
- The name of this file type is slightly misleading in Z39.50 terms,
- since, apart from the actual abstract syntax of the profile, it also
- includes most of the other definitions that go into a database
- profile.
- </para>
-
- <para>
- When a record in the canonical, SGML-like format is read from a file
- or from the database, the first tag of the file should reference the
- profile that governs the layout of the record. If the first tag of the
- record is, say, <literal><gils></literal>, the system will look
- for the profile definition in the file <literal>gils.abs</literal>.
- Profile definitions are cached, so they only have to be read once
- during the lifespan of the current process.
- </para>
-
- <para>
- When writing your own input filters, the
- <emphasis>record-begin</emphasis> command
- introduces the profile, and should always be called first thing when
- introducing a new record.
- </para>
-
- <para>
- The file may contain the following directives:
- </para>
-
- <para>
- <variablelist>
-
- <varlistentry>
- <term>name <emphasis>symbolic-name</emphasis></term>
- <listitem>
- <para>
- (m) This provides a shorthand name or
- description for the profile. Mostly useful for diagnostic purposes.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>reference <emphasis>OID-name</emphasis></term>
- <listitem>
- <para>
- (m) The reference name of the OID for the profile.
- The reference names can be found in the <emphasis>util</emphasis>
- module of <emphasis>YAZ</emphasis>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>attset <emphasis>filename</emphasis></term>
- <listitem>
- <para>
- (m) The attribute set that is used for
- indexing and searching records belonging to this profile.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>tagset <emphasis>filename</emphasis></term>
- <listitem>
- <para>
- (o) The tag set (if any) that describe
- that fields of the records.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>varset <emphasis>filename</emphasis></term>
- <listitem>
- <para>
- (o) The variant set used in the profile.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>maptab <emphasis>filename</emphasis></term>
- <listitem>
- <para>
- (o,r) This points to a
- conversion table that might be used if the client asks for the record
- in a different schema from the native one.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>marc <emphasis>filename</emphasis></term>
- <listitem>
- <para>
- (o) Points to a file containing parameters
- for representing the record contents in the ISO2709 syntax. Read the
- description of the MARC representation facility below.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>esetname <emphasis>name filename</emphasis></term>
- <listitem>
- <para>
- (o,r) Associates the
- given element set name with an element selection file. If an (@) is
- given in place of the filename, this corresponds to a null mapping for
- the given element set name.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>any <emphasis>tags</emphasis></term>
- <listitem>
- <para>
- (o) This directive specifies a list of attributes
- which should be appended to the attribute list given for each
- element. The effect is to make every single element in the abstract
- syntax searchable by way of the given attributes. This directive
- provides an efficient way of supporting free-text searching across all
- elements. However, it does increase the size of the index
- significantly. The attributes can be qualified with a structure, as in
- the <emphasis>elm</emphasis> directive below.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>elm <emphasis>path name attributes</emphasis></term>
- <listitem>
- <para>
- (o,r) Adds an element to the abstract record syntax of the schema.
- The <emphasis>path</emphasis> follows the
- syntax which is suggested by the Z39.50 document - that is, a sequence
- of tags separated by slashes (/). Each tag is given as a
- comma-separated pair of tag type and -value surrounded by parenthesis.
- The <emphasis>name</emphasis> is the name of the element, and
- the <emphasis>attributes</emphasis>
- specifies which attributes to use when indexing the element in a
- comma-separated list.
- A ! in place of the attribute name is equivalent to
- specifying an attribute name identical to the element name.
- A - in place of the attribute name
- specifies that no indexing is to take place for the given element.
- The attributes can be qualified with <emphasis>field
- types</emphasis> to specify which
- character set should govern the indexing procedure for that field.
- The same data element may be indexed into several different
- fields, using different character set definitions.
- See the section <xref linkend="field-structure-and-character-sets"/>.
- The default field type is "w" for <emphasis>word</emphasis>.
- </para>
- </listitem></varlistentry>
- </variablelist>
- </para>
-
- <note>
- <para>
- The mechanism for controlling indexing is not adequate for
- complex databases, and will probably be moved into a separate
- configuration table eventually.
- </para>
- </note>
-
- <para>
- The following is an excerpt from the abstract syntax file for the GILS
- profile.
- </para>
-
- <para>
-
- <screen>
- name gils
- reference GILS-schema
- attset gils.att
- tagset gils.tag
- varset var1.var
-
- maptab gils-usmarc.map
-
- # Element set names
-
- esetname VARIANT gils-variant.est # for WAIS-compliance
- esetname B gils-b.est
- esetname G gils-g.est
- esetname F @
-
- elm (1,10) rank -
- elm (1,12) url -
- elm (1,14) localControlNumber Local-number
- elm (1,16) dateOfLastModification Date/time-last-modified
- elm (2,1) title w:!,p:!
- elm (4,1) controlIdentifier Identifier-standard
- elm (2,6) abstract Abstract
- elm (4,51) purpose !
- elm (4,52) originator -
- elm (4,53) accessConstraints !
- elm (4,54) useConstraints !
- elm (4,70) availability -
- elm (4,70)/(4,90) distributor -
- elm (4,70)/(4,90)/(2,7) distributorName !
- elm (4,70)/(4,90)/(2,10 distributorOrganization !
- elm (4,70)/(4,90)/(4,2) distributorStreetAddress !
- elm (4,70)/(4,90)/(4,3) distributorCity !
- </screen>
-
- </para>
-
- </sect2>
-
- <sect2 id="attset-files">
- <title>The Attribute Set (.att) Files</title>
-
- <para>
- This file type describes the <emphasis>Use</emphasis> elements of
- an attribute set.
- It contains the following directives.
- </para>
-
- <para>
- <variablelist>
- <varlistentry>
- <term>name <emphasis>symbolic-name</emphasis></term>
- <listitem>
- <para>
- (m) This provides a shorthand name or
- description for the attribute set.
- Mostly useful for diagnostic purposes.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>reference <emphasis>OID-name</emphasis></term>
- <listitem>
- <para>
- (m) The reference name of the OID for
- the attribute set.
- The reference names can be found in the <emphasis>util</emphasis>
- module of <emphasis>YAZ</emphasis>.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>include <emphasis>filename</emphasis></term>
- <listitem>
- <para>
- (o,r) This directive is used to
- include another attribute set as a part of the current one. This is
- used when a new attribute set is defined as an extension to another
- set. For instance, many new attribute sets are defined as extensions
- to the <emphasis>bib-1</emphasis> set.
- This is an important feature of the retrieval
- system of Z39.50, as it ensures the highest possible level of
- interoperability, as those access points of your database which are
- derived from the external set (say, bib-1) can be used even by clients
- who are unaware of the new set.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>att
- <emphasis>att-value att-name [local-value]</emphasis></term>
- <listitem>
- <para>
- (o,r) This
- repeatable directive introduces a new attribute to the set. The
- attribute value is stored in the index (unless a
- <emphasis>local-value</emphasis> is
- given, in which case this is stored). The name is used to refer to the
- attribute from the <emphasis>abstract syntax</emphasis>.
- </para>
- </listitem></varlistentry>
- </variablelist>
- </para>
-
- <para>
- This is an excerpt from the GILS attribute set definition.
- Notice how the file describing the <emphasis>bib-1</emphasis>
- attribute set is referenced.
- </para>
-
- <para>
-
- <screen>
- name gils
- reference GILS-attset
- include bib1.att
-
- att 2001 distributorName
- att 2002 indextermsControlled
- att 2003 purpose
- att 2004 accessConstraints
- att 2005 useConstraints
- </screen>
-
- </para>
-
- </sect2>
-
- <sect2>
- <title>The Tag Set (.tag) Files</title>
-
- <para>
- This file type defines the tagset of the profile, possibly by
- referencing other tag sets (most tag sets, for instance, will include
- tagsetG and tagsetM from the Z39.50 specification. The file may
- contain the following directives.
- </para>
-
- <para>
- <variablelist>
-
- <varlistentry>
- <term>name <emphasis>symbolic-name</emphasis></term>
- <listitem>
- <para>
- (m) This provides a shorthand name or
- description for the tag set. Mostly useful for diagnostic purposes.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>reference <emphasis>OID-name</emphasis></term>
- <listitem>
- <para>
- (o) The reference name of the OID for the tag set.
- The reference names can be found in the <emphasis>util</emphasis>
- module of <emphasis>YAZ</emphasis>.
- The directive is optional, since not all tag sets
- are registered outside of their schema.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>type <emphasis>integer</emphasis></term>
- <listitem>
- <para>
- (m) The type number of the tagset within the schema
- profile (note: this specification really should belong to the .abs
- file. This will be fixed in a future release).
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>include <emphasis>filename</emphasis></term>
- <listitem>
- <para>
- (o,r) This directive is used
- to include the definitions of other tag sets into the current one.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>tag <emphasis>number names type</emphasis></term>
- <listitem>
- <para>
- (o,r) Introduces a new tag to the set.
- The <emphasis>number</emphasis> is the tag number as used
- in the protocol (there is currently no mechanism for
- specifying string tags at this point, but this would be quick
- work to add).
- The <emphasis>names</emphasis> parameter is a list of names
- by which the tag should be recognized in the input file format.
- The names should be separated by slashes (/).
- The <emphasis>type</emphasis> is th recommended datatype of
- the tag.
- It should be one of the following:
-
- <itemizedlist>
- <listitem>
- <para>
- structured
- </para>
- </listitem>
-
- <listitem>
- <para>
- string
- </para>
- </listitem>
-
- <listitem>
- <para>
- numeric
- </para>
- </listitem>
-
- <listitem>
- <para>
- bool
- </para>
- </listitem>
-
- <listitem>
- <para>
- oid
- </para>
- </listitem>
-
- <listitem>
- <para>
- generalizedtime
- </para>
- </listitem>
-
- <listitem>
- <para>
- intunit
- </para>
- </listitem>
-
- <listitem>
- <para>
- int
- </para>
- </listitem>
-
- <listitem>
- <para>
- octetstring
- </para>
- </listitem>
-
- <listitem>
- <para>
- null
- </para>
- </listitem>
-
- </itemizedlist>
-
- </para>
- </listitem></varlistentry>
- </variablelist>
- </para>
-
- <para>
- The following is an excerpt from the TagsetG definition file.
- </para>
-
- <para>
- <screen>
- name tagsetg
- reference TagsetG
- type 2
-
- tag 1 title string
- tag 2 author string
- tag 3 publicationPlace string
- tag 4 publicationDate string
- tag 5 documentId string
- tag 6 abstract string
- tag 7 name string
- tag 8 date generalizedtime
- tag 9 bodyOfDisplay string
- tag 10 organization string
- </screen>
- </para>
-
- </sect2>
-
- <sect2 id="variant-set">
- <title>The Variant Set (.var) Files</title>
-
- <para>
- The variant set file is a straightforward representation of the
- variant set definitions associated with the protocol. At present, only
- the <emphasis>Variant-1</emphasis> set is known.
- </para>
-
- <para>
- These are the directives allowed in the file.
- </para>
-
- <para>
- <variablelist>
-
- <varlistentry>
- <term>name <emphasis>symbolic-name</emphasis></term>
- <listitem>
- <para>
- (m) This provides a shorthand name or
- description for the variant set. Mostly useful for diagnostic purposes.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>reference <emphasis>OID-name</emphasis></term>
- <listitem>
- <para>
- (o) The reference name of the OID for
- the variant set, if one is required. The reference names can be found
- in the <emphasis>util</emphasis> module of <emphasis>YAZ</emphasis>.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>class <emphasis>integer class-name</emphasis></term>
- <listitem>
- <para>
- (m,r) Introduces a new
- class to the variant set.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>type <emphasis>integer type-name datatype</emphasis></term>
- <listitem>
- <para>
- (m,r) Addes a
- new type to the current class (the one introduced by the most recent
- <emphasis>class</emphasis> directive).
- The type names belong to the same name space as the one used
- in the tag set definition file.
- </para>
- </listitem></varlistentry>
- </variablelist>
- </para>
-
- <para>
- The following is an excerpt from the file describing the variant set
- <emphasis>Variant-1</emphasis>.
- </para>
-
- <para>
-
- <screen>
- name variant-1
- reference Variant-1
-
- class 1 variantId
-
- type 1 variantId octetstring
-
- class 2 body
-
- type 1 iana string
- type 2 z39.50 string
- type 3 other string
- </screen>
-
- </para>
-
- </sect2>
-
- <sect2>
- <title>The Element Set (.est) Files</title>
-
- <para>
- The element set specification files describe a selection of a subset
- of the elements of a database record. The element selection mechanism
- is equivalent to the one supplied by the <emphasis>Espec-1</emphasis>
- syntax of the Z39.50 specification.
- In fact, the internal representation of an element set
- specification is identical to the <emphasis>Espec-1</emphasis> structure,
- and we'll refer you to the description of that structure for most of
- the detailed semantics of the directives below.
- </para>
-
- <note>
- <para>
- Not all of the Espec-1 functionality has been implemented yet.
- The fields that are mentioned below all work as expected, unless
- otherwise is noted.
- </para>
- </note>
-
- <para>
- The directives available in the element set file are as follows:
- </para>
-
- <para>
- <variablelist>
- <varlistentry>
- <term>defaultVariantSetId <emphasis>OID-name</emphasis></term>
- <listitem>
- <para>
- (o) If variants are used in
- the following, this should provide the name of the variantset used
- (it's not currently possible to specify a different set in the
- individual variant request). In almost all cases (certainly all
- profiles known to us), the name
- <literal>Variant-1</literal> should be given here.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>defaultVariantRequest <emphasis>variant-request</emphasis></term>
- <listitem>
- <para>
- (o) This directive
- provides a default variant request for
- use when the individual element requests (see below) do not contain a
- variant request. Variant requests consist of a blank-separated list of
- variant components. A variant compont is a comma-separated,
- parenthesized triple of variant class, type, and value (the two former
- values being represented as integers). The value can currently only be
- entered as a string (this will change to depend on the definition of
- the variant in question). The special value (@) is interpreted as a
- null value, however.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>simpleElement
- <emphasis>path ['variant' variant-request]</emphasis></term>
- <listitem>
- <para>
- (o,r) This corresponds to a simple element request
- in <emphasis>Espec-1</emphasis>.
- The path consists of a sequence of tag-selectors, where each of
- these can consist of either:
- </para>
-
- <para>
- <itemizedlist>
- <listitem>
- <para>
- A simple tag, consisting of a comma-separated type-value pair in
- parenthesis, possibly followed by a colon (:) followed by an
- occurrences-specification (see below). The tag-value can be a number
- or a string. If the first character is an apostrophe ('), this
- forces the value to be interpreted as a string, even if it
- appears to be numerical.
- </para>
- </listitem>
-
- <listitem>
- <para>
- A WildThing, represented as a question mark (?), possibly
- followed by a colon (:) followed by an occurrences
- specification (see below).
- </para>
- </listitem>
-
- <listitem>
- <para>
- A WildPath, represented as an asterisk (*). Note that the last
- element of the path should not be a wildPath (wildpaths don't
- work in this version).
- </para>
- </listitem>
-
- </itemizedlist>
-
- </para>
-
- <para>
- The occurrences-specification can be either the string
- <literal>all</literal>, the string <literal>last</literal>, or
- an explicit value-range. The value-range is represented as
- an integer (the starting point), possibly followed by a
- plus (+) and a second integer (the number of elements, default
- being one).
- </para>
-
- <para>
- The variant-request has the same syntax as the defaultVariantRequest
- above. Note that it may sometimes be useful to give an empty variant
- request, simply to disable the default for a specific set of fields
- (we aren't certain if this is proper <emphasis>Espec-1</emphasis>,
- but it works in this implementation).
- </para>
- </listitem></varlistentry>
- </variablelist>
- </para>
-
- <para>
- The following is an example of an element specification belonging to
- the GILS profile.
- </para>
-
- <para>
-
- <screen>
- simpleelement (1,10)
- simpleelement (1,12)
- simpleelement (2,1)
- simpleelement (1,14)
- simpleelement (4,1)
- simpleelement (4,52)
- </screen>
-
- </para>
-
- </sect2>
-
- <sect2 id="schema-mapping">
- <title>The Schema Mapping (.map) Files</title>
-
- <para>
- Sometimes, the client might want to receive a database record in
- a schema that differs from the native schema of the record. For
- instance, a client might only know how to process WAIS records, while
- the database record is represented in a more specific schema, such as
- GILS. In this module, a mapping of data to one of the MARC formats is
- also thought of as a schema mapping (mapping the elements of the
- record into fields consistent with the given MARC specification, prior
- to actually converting the data to the ISO2709). This use of the
- object identifier for USMARC as a schema identifier represents an
- overloading of the OID which might not be entirely proper. However,
- it represents the dual role of schema and record syntax which
- is assumed by the MARC family in Z39.50.
- </para>
-
- <para>
- <emphasis>NOTE: The schema-mapping functions are so far limited to a
- straightforward mapping of elements. This should be extended with
- mechanisms for conversions of the element contents, and conditional
- mappings of elements based on the record contents.</emphasis>
- </para>
-
- <para>
- These are the directives of the schema mapping file format:
- </para>
-
- <para>
- <variablelist>
-
- <varlistentry>
- <term>targetName <emphasis>name</emphasis></term>
- <listitem>
- <para>
- (m) A symbolic name for the target schema
- of the table. Useful mostly for diagnostic purposes.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>targetRef <emphasis>OID-name</emphasis></term>
- <listitem>
- <para>
- (m) An OID name for the target schema.
- This is used, for instance, by a server receiving a request to present
- a record in a different schema from the native one.
- The name, again, is found in the <emphasis>oid</emphasis>
- module of <emphasis>YAZ</emphasis>.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>map <emphasis>element-name target-path</emphasis></term>
- <listitem>
- <para>
- (o,r) Adds
- an element mapping rule to the table.
- </para>
- </listitem></varlistentry>
- </variablelist>
- </para>
-
- </sect2>
-
- <sect2>
- <title>The MARC (ISO2709) Representation (.mar) Files</title>
-
- <para>
- This file provides rules for representing a record in the ISO2709
- format. The rules pertain mostly to the values of the constant-length
- header of the record.
- </para>
-
- <para>
- <emphasis>NOTE: This will be described better. We're in the process of
- re-evaluating and most likely changing the way that MARC records are
- handled by the system.</emphasis>
- </para>
-
- </sect2>
-
- <sect2 id="field-structure-and-character-sets">
- <title>Field Structure and Character Sets
- </title>
-
- <para>
- In order to provide a flexible approach to national character set
- handling, Zebra allows the administrator to configure the set up the
- system to handle any 8-bit character set — including sets that
- require multi-octet diacritics or other multi-octet characters. The
- definition of a character set includes a specification of the
- permissible values, their sort order (this affects the display in the
- SCAN function), and relationships between upper- and lowercase
- characters. Finally, the definition includes the specification of
- space characters for the set.
- </para>
-
- <para>
- The operator can define different character sets for different fields,
- typical examples being standard text fields, numerical fields, and
- special-purpose fields such as WWW-style linkages (URx).
- </para>
-
- <para>
- The field types, and hence character sets, are associated with data
- elements by the .abs files (see above).
- The file <literal>default.idx</literal>
- provides the association between field type codes (as used in the .abs
- files) and the character map files (with the .chr suffix). The format
- of the .idx file is as follows
- </para>
-
- <para>
- <variablelist>
-
- <varlistentry>
- <term>index <emphasis>field type code</emphasis></term>
- <listitem>
- <para>
- This directive introduces a new search index code.
- The argument is a one-character code to be used in the
- .abs files to select this particular index type. An index, roughly,
- corresponds to a particular structure attribute during search. Refer
- to section <xref linkend="search"/>.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>sort <emphasis>field code type</emphasis></term>
- <listitem>
- <para>
- This directive introduces a
- sort index. The argument is a one-character code to be used in the
- .abs fie to select this particular index type. The corresponding
- use attribute must be used in the sort request to refer to this
- particular sort index. The corresponding character map (see below)
- is used in the sort process.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>completeness <emphasis>boolean</emphasis></term>
- <listitem>
- <para>
- This directive enables or disables complete field indexing.
- The value of the <emphasis>boolean</emphasis> should be 0
- (disable) or 1. If completeness is enabled, the index entry will
- contain the complete contents of the field (up to a limit), with words
- (non-space characters) separated by single space characters
- (normalized to " " on display). When completeness is
- disabled, each word is indexed as a separate entry. Complete subfield
- indexing is most useful for fields which are typically browsed (eg.
- titles, authors, or subjects), or instances where a match on a
- complete subfield is essential (eg. exact title searching). For fields
- where completeness is disabled, the search engine will interpret a
- search containing space characters as a word proximity search.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>charmap <emphasis>filename</emphasis></term>
- <listitem>
- <para>
- This is the filename of the character
- map to be used for this index for field type.
- </para>
- </listitem></varlistentry>
- </variablelist>
- </para>
-
- <para>
- The contents of the character map files are structured as follows:
- </para>
-
- <para>
- <variablelist>
-
- <varlistentry>
- <term>lowercase <emphasis>value-set</emphasis></term>
- <listitem>
- <para>
- This directive introduces the basic value set of the field type.
- The format is an ordered list (without spaces) of the
- characters which may occur in "words" of the given type.
- The order of the entries in the list determines the
- sort order of the index. In addition to single characters, the
- following combinations are legal:
- </para>
-
- <para>
-
- <itemizedlist>
- <listitem>
- <para>
- Backslashes may be used to introduce three-digit octal, or
- two-digit hex representations of single characters
- (preceded by <literal>x</literal>).
- In addition, the combinations
- \\, \\r, \\n, \\t, \\s (space — remember that real
- space-characters may ot occur in the value definition), and
- \\ are recognised, with their usual interpretation.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Curly braces {} may be used to enclose ranges of single
- characters (possibly using the escape convention described in the
- preceding point), eg. {a-z} to entroduce the
- standard range of ASCII characters.
- Note that the interpretation of such a range depends on
- the concrete representation in your local, physical character set.
- </para>
- </listitem>
-
- <listitem>
- <para>
- paranthesises () may be used to enclose multi-byte characters -
- eg. diacritics or special national combinations (eg. Spanish
- "ll"). When found in the input stream (or a search term),
- these characters are viewed and sorted as a single character, with a
- sorting value depending on the position of the group in the value
- statement.
- </para>
- </listitem>
-
- </itemizedlist>
-
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>uppercase <emphasis>value-set</emphasis></term>
- <listitem>
- <para>
- This directive introduces the
- upper-case equivalencis to the value set (if any). The number and
- order of the entries in the list should be the same as in the
- <literal>lowercase</literal> directive.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>space <emphasis>value-set</emphasis></term>
- <listitem>
- <para>
- This directive introduces the character
- which separate words in the input stream. Depending on the
- completeness mode of the field in question, these characters either
- terminate an index entry, or delimit individual "words" in
- the input stream. The order of the elements is not significant —
- otherwise the representation is the same as for the
- <literal>uppercase</literal> and <literal>lowercase</literal>
- directives.
- </para>
- </listitem></varlistentry>
- <varlistentry>
- <term>map <emphasis>value-set</emphasis>
- <emphasis>target</emphasis></term>
- <listitem>
- <para>
- This directive introduces a
- mapping between each of the members of the value-set on the left to
- the character on the right. The character on the right must occur in
- the value set (the <literal>lowercase</literal> directive) of
- the character set, but
- it may be a paranthesis-enclosed multi-octet character. This directive
- may be used to map diacritics to their base characters, or to map
- HTML-style character-representations to their natural form, etc.
- </para>
- </listitem></varlistentry>
- </variablelist>
- </para>
-
- </sect2>
-
- </sect1>
-
- <sect1 id="formats">
- <title>Exchange Formats</title>
-
- <para>
- Converting records from the internal structure to en exchange format
- is largely an automatic process. Currently, the following exchange
- formats are supported:
- </para>
-
- <para>
- <itemizedlist>
- <listitem>
- <para>
- GRS-1. The internal representation is based on GRS-1, so the
- conversion here is straightforward. The system will create
- applied variant and supported variant lists as required, if a record
- contains variant information.
- </para>
- </listitem>
-
- <listitem>
- <para>
- SUTRS. Again, the mapping is fairly straighforward. Indentation
- is used to show the hierarchical structure of the record. All
- "GRS" type records support both the GRS-1 and SUTRS
- representations.
- </para>
- </listitem>
-
- <listitem>
- <para>
- ISO2709-based formats (USMARC, etc.). Only records with a
- two-level structure (corresponding to fields and subfields) can be
- directly mapped to ISO2709. For records with a different structuring
- (eg., GILS), the representation in a structure like USMARC involves a
- schema-mapping (see section <xref linkend="schema-mapping"/>), to an
- "implied" USMARC schema (implied,
- because there is no formal schema which specifies the use of the
- USMARC fields outside of ISO2709). The resultant, two-level record is
- then mapped directly from the internal representation to ISO2709. See
- the GILS schema definition files for a detailed example of this
- approach.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Explain. This representation is only available for records
- belonging to the Explain schema.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Summary. This ASN-1 based structure is only available for records
- belonging to the Summary schema - or schema which provide a mapping
- to this schema (see the description of the schema mapping facility
- above).
- </para>
- </listitem>
-
- <listitem>
- <para>
- SOIF. Support for this syntax is experimental, and is currently
- keyed to a private Index Data OID (1.2.840.10003.5.1000.81.2). All
- abstract syntaxes can be mapped to the SOIF format, although nested
- elements are represented by concatenation of the tag names at each
- level.
- </para>
- </listitem>
-
- </itemizedlist>
-
- </para>
-
- </sect1>
-
-</chapter>