Gazebo Configuration File Syntax

Gazebo's configuration file is both elaborate and powerful. Its purpose is not only to express simple parameters such as port number, but also to define the relationships between the query syntaxes of a Gazebo instance's target data sources. An inheritance mechanism within the configuration file makes it possible to define templates which are used to configure groups of similar data sources with a minimum of redundancy.

The configuration file syntax is encoded in XML. The following assumes a basic familiarity with XML and Z39.50.

Contents

1. config Tag

2. param Tags

3. db Tags

3.1 name Attribute

3.2 type Attribute

3.3 param Tags for Databases

3.4 convert Tags for Databases

3.5 syntax Tag for Databases

3.5.1 attr Tag

3.5.1.1 The type Attribute of the attr Tag

3.5.1.2 The value Attribute of the attr Tag

3.5.1.3 The syntax Template

3.5.1.3.1 The {term} Variable

4. Z39.50 Databases

4.1 params for Z39.50

4.2 Z39.50 Object Identifiers (OIDs)

4.2.1 OIDs in the PreferredRecordSyntax PARAM Tag

4.2.2 OIDs in the convert Tag

4.2.3 Z39.50 Query Syntax

4.2.3.1 The Term Segment

4.2.3.2 The Attribute Segment

5. Inheritance Using the class Tag

5.1 The class Tag

5.2 The parent Attribute for class, db, and syntax Tags

5.3 How Inheritance Works

5.3.1 How Inheritance Works for db Tags

5.3.2 How Inheritance Works for syntax Tags

6. An Annotated, Example Configuration File

---

1. config Tag

The config tag is the top most tag in the configuration file. The config tag has no attributes and has the form:

<config>
	<!-- Rest of configuration file here -->
</config>

---

2. param Tags

The param tag is used directly under the config tag to set parameters which apply to the Gazebo service itself, such as port number. It's also used under the db tag to set parameters a database needs in order to connect to a remote data service. The param tag has the form:

<param name="port" value="3737"/>

---

3. db Tags

Databases are defined via the db tag. The db tag takes name and value for attributes. Valid subtags are param, convert, and syntax. The db tag has the form:

<db name="MegaDB" type="Z3950">
	<!-- param, convert, and syntax tags go here -->
</db>

3.1 name Attribute

The name attribute of the db tag is the name of the database we are searching. In the example above, the database is called "MegaDB."

3.2 type Attribute

The type attribute of the db tag specifies the type of database we are searching. Currently, Gazebo supports Z39.50 and OpenText databases, and the only valid values for the type attribute are "Z3950" and "OPENTEXT". The default is "Z3950".

3.3 param Tags for Databases

Parameters which are necessary to allow Gazebo to connect to and search a database are declared using the param tag within the db tag. The param tag has the same form as shown above. For example, to specify the port to use to connect to the database, you'd write:

<db name="DodoDB" type="Z3950">
	<param name="port" value="3737"/>
</db>

3.4 convert Tags for Databases

convert tags instruct Gazebo to perform result record format conversion using an external CGI script. The Gazebo distribution includes such a script for converting USMARC records into HTML. The convert tag takes the attributes from, which specifies the type of the document you are converting from; to, which specifies the type to convert the document to; and url, which specifies the location of the conversion script. For example, to convert from USMARC to text/html, using a script at http://foo.bar.com/cgi-bin/conv.cgi, we'd write:

<convert from="USMARC" to="text/html"
	 url="http://foo.bar.com/cgi-bin/conv.cgi"/>

3.5 syntax Tag for Databases

Each database has a syntax associated with it. The syntax tag holds attributes which, in turn, hold templates for constructing queries the database can recognize. The syntax tag has an optional parent attribute. The syntax tag has the form:

<syntax>
	<!-- Attributes here -->
</syntax>

3.5.1 attr Tag

The attr tag is defined inside of a syntax tag. They can be nested to any depth in a tree-like structure with templates as the leaf nodes of the tree. Attributes are used to specify which template to use to create a node of a database query. The attr tag takes the attributes type and value. type typically identifies a class of searchable fields or search qualifiers, and value typically identifies a member of that class. For instance, if we wanted to describe a set of database fields, we might declare the following set of attributes:

<attr type="field" VALue="name">
        <!-- template goes here -->
</attr>
<attr type="field" value="SSN">
        <!-- template goes here -->
</attr>
<attr type="field" value="Density">
        <!-- template goes here -->
</attr>

If we wanted to declare sub-attributes, such as search qualifiers for the fields, we might declare them as follows:

<attr type="field" value="Name">
        <!-- template goes here -->
        <attr type="qualifier" value="First">
                <!-- template goes here -->
	</attr>
        <attr type="qualifier" value="Last">
                <!-- template goes here -->
	</attr>
</attr>
<attr type="field" value="SSN">
        <!-- template goes here -->
</attr>
<attr type="field" value="Density">
        <attr type="qualifier" value="GramsPerLiter">
                <!-- template goes here -->
	</attr>
        <attr type="qualifier" value="PoundsPerCubicFoot">
                <!-- template goes here -->
	</attr>
</attr>

3.5.1.1 The type Attribute of the attr Tag

The type attribute of the attr tag identifies the type of search Attribute the tag represents. Attributes on the same level (siblings of each other) need not have the same type.

3.5.1.2 The value Attribute of the attr Tag

The value attribute of the attr tag identifies a particular search Attribute of the given type.

3.5.1.3 The syntax Template

Gazebo constructs queries out of templates. The search terms are inserted into the templates to form a query string the database can understand. Templates are stored at the leaf nodes of an attribute tree. For example, an Attribute containing a template for a Z39.50 database which searches on the field representing first names might look like

<attr type="field" value="Name">
	<attr type="qualifier" value="First">
		/t{term}/a1=1016/a5=100/
	</attr>
</attr>

3.5.1.3.1 The {term} Variable

Use the special variable "{term}" to specify where the search term should go in the template. For a search term "Clarence", in the example above the template would be converted to:

/tClarence/a1=1016/a5=100/

---

4. Z39.50 Databases

Z39.50 is an ISO standard network protocol for information retrieval, which is maintained under the stewardship of the the Library of Congress. Gazebo requires several parameters in order to access a Z39.50 service. (See section 4.1).

4.1 params for Z39.50

Several parameters need to be set so that Gazebo can connect to, search on, and retrieve results from a Z39.50 service. These parameters are set with param tags (see above) in the db tag representing the service. The following are the most critical parameters:

Name	Description	Default Value
Host	The hostname of the Z39.50 service (where it's located)	none
Port	The port number used to connect to the Z39.50 service	210
DBName	Names which database to search on the Z39.50 service	none
UserID	The user ID, if needed, to log in to the Z39.50 service	none
Password	The password, if needed, to log in to the Z39.50 service	none
PreferredRecordSyntax	What record syntax to return. This parameter is a Z39.50 Object Identifier (see below). If the service returns plain-text records, this should be set to "1.2.840.10003.5.101". The default is the OID for USMARC records.	1.2.840.10003.5.10
ContentType	The content type of the record you wish returned by default. This determines what conversion service, if any, to use to convert the record to this type from the PreferredRecordSyntax.	text/plain
AttributeSetID	The ID of the attribute set used by the service.	BIB1

The rest of the Z39.50 parameters are relatively unimportant and default values will normally suffice. However it may be necessary to adjust some of them for particular services.

Name	Description	Default Value
Version	The version of the Z39.50 server written as a string of 'y's (one 'y' indicating version 1, and so on)	yyy
ElementSet	Element set name of the kind of records to initially retrieve. Either brief (B) or full (F) records may be returned.	B
MediumSetName	Depending on the size of the result set, different kinds of records (either brief or full) are returned. MediumSetName is which one is returned in the case of a MediumSet.	none
Options	Indicate which options you want the server to perform. Consult ANSI/NISO Z39.50 documentation for information on options available. Options are written as a string of 'y's and 'n's, where 'y' indicates a positive value for the bit and n a negative value.	yy (search and present)
MessageSize	Indicates the preferred message size for records retrieved from the server.	8192
MaximumSize	Indicates the maximum message size for records retrieved from the server.	65536
QueryType	The type of query sent to Gazebo. Gazebo supports type 1, Reverse Polish Notation (RPN), and 101, extended RPN, queries.	1
ReplaceIndicator	If a result set with the same name already exists at the target, the action taken depends on the value of the parameter ReplaceIndicator. If ReplaceIndicator is 1, then after processing the query, the existing result set whose name is specified by the parameter ResultSetName will be deleted and a new result set by that name created. If the value is 0, the search is not processed, an error diagnostic is returned by the target, and the existing result set whose name is specified by the parameter ResultSetName is left unchanged.	1
ResultSetName	This specifies a name to be given to the result set (to be created by the query) so that it may be subsequently referenced	Default
SmallUpperBND	The result set is a small-set if Result-count is not greater than SmallUpperBND. 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).	0
LargeUpperBND	The result set is a large-set if the Result-count is larger than or equal to LargeUpperBND. If the query results in a large-set, no response records are to be returned.	1
MediumPresentNumber	If the query does not result in a small-set or large-set then it is a medium-set, the maximum number of response records to be returned is specified by MediumPresentNumber.	0

4.2 Z39.50 Object Identifiers (OIDs)

From Registry of Z39.50 Object Identifiers:

Z39.50 Object Identifiers (OIDs) take the form: 1.2.840.10003.x.y where "x" enumerates the Z39.50 object classes and "y" enumerates the objects within a class. Consult the Registry of Z39.50 Object Identifiers for a full explaination of object identifiers.

A few of the more common OIDs used with Z39.50 are:

Name	OID
Z39.50	1.2.840.10003
Marc21 (formerly USMARC)	1.2.840.10003.5.10
SUTRS	1.2.840.10003.5.101
BIB1	1.2.840.10003.3.1
HTML	1.2.840.10003.5.109.3

4.2.1 OIDs in the PreferredRecordSyntax param Tag

Specify the OID for the preferred record syntax parameter of a Z39.50 database specification as follows. To specify a USMARC preferred record syntax, use the following param tag:

<param name="PreferredRecordSyntax" value="1.2.840.10003.5.10"/>

4.2.2 OIDs in the convert Tag

Specify the OID you wish to convert from in the convert tag. To specify a conversion from a SUTRS record to a text/html format using the conversion program "sutrs2html.pl" at the site http://www.foo.com/, use the following convert tag:

<convert from="1.2.840.10003.5.101" to="text/html"
	 url="http://www.foo.com/cgi-bin/sutrs2html.pl"/>

4.2.3 Z39.50 Query Template Syntax

Z39.50 query templates are encoded in a simple syntax which allows you to associate terms with Z39.50 attribute combinations. Each query template consists of a sequence of segments delineated with slashes. There are two main kinds of segments: Term segments, and Attribute segments.

4.2.3.1 The Term Segment

Each query segment must contain one Term segment. A term segment consists of the letter "t" followed by a term. Terms can either be hard-coded into the segment, or the "{term}" variable can be used (the latter is the typical case). For example:

/t{term}

4.2.3.2 The Attribute Segment

Each query segment may contain any number of Attribute segments. Attribute segments consist of the letter "a" followed by a Z39.50 attribute specification in the form "j=k" where j is the decimal number of the attribute type and k is the decimal number of the attribute value. For example, the following segment could be used to encode the "Author-name Personal" Use attribute from Z39.50 Attribute Set Bib-1:

/a1=1004

Here's a complete example query template.

/t{term}/a1=1005/a4=103/

---

5. Inheritance Using the CLASS Tag

The configuration file supports an inheritance model which simplifies database declarations. In general, database parameters are constant between several similar databases with only a few parameters changing. With the inheritance model, you need not copy the duplicated parameters but simply inherit those parameters from a CLASS tag.

5.1 The class Tag

The class tag is a generic tag whose contents are inherited through the parent attribute of the class, db, and syntax tags. (Classes can inherit other classes). It can contain any set of tags. The parameters the class tag takes are name, (required) used to give the class an identifying name, and parent, (optional) used to inherit from another class(es) (see section 5.2).

5.2 The parent Attribute for class, db, and syntax Tags

The optional parent attribute for class, db, and syntax tags is a comma separated list of class names from which to inherit. The classes will be inherited from left to right from the class list with later classes overriding declarations from previously inherited classes. For instance, in the following example, the syntax tag will inherit attr tags from OneClass and from AnotherClass, with AnotherClass's attrs possibly overriding the attrs from OneClass:

<syntax parent="OneClass,AnotherClass">
        ...
</syntax>

5.3 How Inheritance Works

Classes which are inherited later in the list override tags from previously inherited classes. Tags which are declared in the inheriting class will override similar inherited tags. An inherited tag will only override a tag if the tag name and attributes match and if it's at the same level as the other tag.

For instance, if several db tags shared the same "host" and "port" params, you could define a class tag which contained those param tags and have the dbs inherit them:

<class name="CertainHost">
        <param name="host" value="my.z3950.host"/>
	<param name="port" value="2210"/>
</class>

...

<db name="Service One" type="Z3950" parent="CertainHost">
        ...
</db>

...

<db name="Service Two" type="Z3950" parent="CertainHost">
        ...
</db>

The effect is as if each db tag contained the param tags contained in the CertainHost class tag.

5.3.1 How Inheritance Works for db Tags

The db tag can inherit param, syntax, and convert tags from a class.

5.3.2 How Inheritance Works for syntax Tags

The syntax tag has attr tags for subtags. attr tags can be nested within other attr tags to an arbitrary level forming a tree-like structure. When inheriting from a class, the syntax tag will merge the two attribute trees into one. Attributes at the same level in the tree which have the same type and value will override previously inherited attributes.

---

6. An Annotated, Example Configuration File

<config>

<!--
  Gateway Parameters:

	Name - The name of the gateway is "Gazebo Test Gateway".
	Port - The Gateway will accept connections on port 3737.
  -->
<param name="Name" value="Gazebo Test Gateway"/>
<param name="Port" value="3737"/>

<!--
  	Declare a class of converters for converting from a USMARC record
	to a text/html format. Note: This class does not inherit from
	another class.
  -->
<class name="convert.usmarc2html">
	<!--
		from - 1.2.840.10003.5.10 (USMARC's OID)
		to   - text/html (MIME type for HTML)
		url  - http://www.foo.bar.edu/cgi-bin/usmarc2html
			(Location of conversion CGI program)
	  -->
	<convert from="1.2.840.10003.5.10"
	         to="text/html"
		 url="http://www.foo.bar.edu/cgi-bin/usmarc2html"/>
</class>

<!--
	Declare a class which specifies the preferred syntax for a Z39.50
	database declaration. This class inherits the conversion routine
	"convert.usmarc2html".
  -->
<class name="z3950.prs.USMARC" parent="convert.usmarc2html">
	<!--
		Preferred record syntax keyword/value pair for a Z39.50
		database. "1.2.840.10003.5.10" indicates a preferred
		syntax of USMARC.
	  -->
        <param name="PreferredRecordSyntax" value="1.2.840.10003.5.10"/>
</class>

<!--
	Declare a bevy of generic Z39.50 parameters.
  -->
<class name="z3950">
	<!--
		Port number for the Z39.50 server.
	  -->
	<param name="Port" value="210"/>

	<!--
		The desired composition of the retrieved records is set
		to B (Brief).
	  -->
	<param name="ElementSet" value="B"/>

	<!--
		Set the Version parameter to 3 (yyy == 3).
	  -->
	<param name="Version" value="yyy"/>

	<!--
		Set the Options parameter to search and present (yy).
	  -->
	<param name="Options" value="yy"/>

	<!--
		The attribute set the Z39.50 database uses.
		"1.2.840.10003.3.1" indicates a BIB1 attribute set.
	  -->
	<param name="AttributeSetID" value="1.2.840.10003.3.1"/>

	<!--
		The preferred message size for records retrieved from the
		server.
	  -->
	<param name="MessageSize" value="8192"/>

	<!--
		The maximum message size for records retrieved from the
		server.
	  -->
	<param name="MaximumSize" value="65536"/>

	<!--
		The maximum number of response records to be returned if
		the result set is a medium-set.
	  -->
	<param name="MediumPresentNumber" value="0"/>

	<!--
		Set the type of the query to 1.
	  -->
	<param name="QueryType" value="1"/>

	<!--
		Replace the result set with a new result set.
	  -->
	<param name="ReplaceIndicator" value="1"/>

	<!--
		Name of the result set.
	  -->
	<param name="ResultSetName" value="Default"/>
</class>

<!--
	Declare a class of generic Z39.50 syntax attributes.
  -->
<class name="z3950.generic.syntax">
	<attr name="Field" value="Anything">
		/t{term}/a1=1016/a5=100/
	</attr>
	<attr name="Field" value="Title">
		/t{term}/a1=4/a5=100/
	</attr>
	<attr name="Field" value="Subject">
		/t{term}/a1=21/a5=100/
	</attr>
</class>

<!--
	Declare a database named Z3950_Foo of type Z3950 which inherits
	values from the z3950 and z3950.prs.USMARC classes.
  -->
<db name="Z3950_Foo" type="Z3950" parent="z3950,z3950.prs.USMARC">
        <param name="DBName" value="PREMEDLINE"/>

	<!--
		The SYNTAX tag inherits the attributes from the
		z3950.generic.syntax class but overrides the
		Field/Subject attribute in the class to reflect this
		specific database.
	  -->
        <syntax PARENT="z3950.generic.syntax">
                <attr name="Field" value="Subject">
                        /t{term}/a1=4/a5=100/
                </attr>
        </syntax>
</db>

</CONFIG>