Gazelle Configuration File Reference

Contents

1. config Tag

2. param Tags

3. database Tags

3.1 name Attribute

3.2 param Tags for Databases

3.3 The attr Tag

3.4 The template Tag

3.5 The term Tag

4. Inheritance Using the class Tag

4.1 The class Tag

4.2 The parent Attribute for class and database Tags

4.3 How Inheritance Works

4.3.1 How Inheritance Works for database Tags

5. 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>
	<!-- The body of the configuration file goes here -->
</config>

---

2. param Tags

The param tag is used directly under the config tag to set name/value parameter pairs which apply to the Gazelle service itself, such as the port number to listen on. It's also used under the database tag to set parameters Gazelle needs to connect to a target database. The param tag has the form:

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

Predefined Gazelle configuration param names and values:

• port - The IP port number to listen on for connections. The default value is 210.
• type - The mode to run Gazelle. Accepted values are "forking" or "standalone". Default value is "forking".
• debug - Bit flag for logging and debugging. See gazelle documentation for details. Default value is 0 (no debug output).
• debuglog - Name of the debugging log file, if used.
• accesslog - Name of the access log file, if used.
• errorlog - Name of the error log file, if used.

These and any user-specific name/value pairs are passed as a parameter dictionary to the target API target_connect() function.

---

3. database Tags

Databases are defined via the database tag. The database tag takes a name attribute. param, attr, term, and template. The database tag has the form:

<database name="MyDatabase">
	<!-- param, attr, term, and template tags go here -->
	</database>

3.1 name Attribute

The name attribute of the database tag is the name of the database we are searching. In the example above, the database is called "MyDatabase." The value of the name attribute will be matched with an incoming Z39.50 request database name.

3.2 param Tags for Databases

Param tags for databases define name/value pairs of parameters that are specific to the database defined by the enclosing database tag. Possible uses are host, port, username, and password for the target database, or other database-specific options. These name/value pairs are passed as a parameter dictionary to the target API target_search() function.

3.3 attr Tag

Each attr tag corresponds to a possible Z39.50 attribute in an incoming search request. The attr tag takes a type and a value attribute. The type attribute is set to the value of the matching Z39.50 attribute's type, while the value attribute is set to the value of the Z39.50 attribute.

The attr tag has the form:

	<attr type="1" value="101">
		<!-- attr, term, and template tags go here -->
	</attr>

3.4 template Tag

A template tag is used to define a named pattern that can be substituted for in a term tag or within the text of another template tag. The template is invoked within other tags by using the name prepended with a dollar sign ('$').

The template tag has the form:

	<template name="field">
		<!-- text and template references go here -->
	</template>

There are some predefined template names that are used to form complex expressions. These are:

• lhs - The first operand (left-hand side) of a binary boolean operation. This is an implied template, i.e., it need not be defined in the configuartion file.
• rhs - The second operand (right-hand side) of a binary boolean operation. This is an implied template, i.e., it need not be defined in the configuartion file.
• and_expression - defined to describe a boolean AND expression fragment.
• or_expression - defined to describe a boolean OR expression fragment.
• andNot_expression - defined to describe a boolean AND-NOT expression fragment.

Example:

	<template name="and_expression">
		($lhs AND $rhs)
	</template>

	<template name="or_expression">
		($lhs OR $rhs)
	</template>

	<template name="andNot_expression">
		($lhs AND (NOT $rhs))
	</template>

3.5 term Tag

The term tag is used to create an equivalence between a Z39.50 attributeList+Term and a target database term. Therefore, each attr tag or set of nested attr tags must have at least one term tag defined within it.

The term tag has the form:

	<term>
		<!-- Constant strings or template name fields go here -->
	</term>

---

4. Inheritance Using the class Tag

The configuration file supports an inheritance model which simplifies database declarations. This makes it possible for database parameters to be 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.

4.1 The class Tag

The class tag is a generic tag whose contents are inherited through the parent attribute of the class and database 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 4.2).

4.2 The parent Attribute for class and database Tags

The optional parent attribute for class and database 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 database tag will inherit attr tags from OneClass and from AnotherClass, with AnotherClass's attrs possibly overriding the attrs from OneClass:

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

4.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 database tags shared the same "host" and "port" params, you could define a class tag which contained those param tags and have the database's inherit them:

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

		...

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

			...

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

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

4.3.1 How Inheritance Works for database Tags

The database tag can inherit param and attr tags from a class.

The database 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 database 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.

---

5. Example Configuration File

<config>

<param name="port" value="2663"/>
<param name="type" value="forking"/>
<param name="debug" value="true"/>
<param name="debugLog" value="debug.log"/>
<param name="accessLog" value="access.log"/>
<param name="errorLog" value="error.log"/>

<!-- the following should be database-specific params -->
	<param name="pghost" value="hatteras.ncsa.uiuc.edu"/>
	<param name="pgport" value="5432"/>
	<param name="pguser" value="guest"/>
	<!param name="pgpassword" value="foobar"/>
	<param name="pgdbname" value="competition"/>
	<!param name="pgoptions" value="etc. etc."/>

<database name="zaphod">
	<!-- miscellaneous non-expression parameters (SQL-specific) -->

	<!--
		Mapping of z39.50 terms and operators to target expressions.
		Currently, each attr or nested attr combination must have a
		"term" tag (or there must be a global-scope "term" tag) that
		defines how to build a term (the z39.50 attributePlusTerm) of
		an expression.
		Each attribute may also optionally have a "template" tag which
		defines how it is translated.  The "template" tag is not optional
		if the "attr" hierarchy has no "term" tag definition, i.e., there
		must be some way to translate each attribute into a term.
	-->
	<attr type="1" value="1">
		<template name="field">entrant.name</template>
		<attr type="2" value="3">
			<term>$field = '$value'</term>
		</attr>
		<attr type="2" value="101">
			<template name="relop"> ~~ </template>
			<term>$field $relop '$value'</term>
		</attr>
	</attr>
	<attr type="1" value="2">
		<template name="field">entrant.city</template>
		<term>$field $relop '$value'</term>
	</attr>
	<attr type="1" value="3">
		<term>entrant.state = '$value'</term>
	</attr>
	<attr type="1" value="4">
		<term>$field $relop '$value'</term>
		<template name="field">club.clubname</template>
	</attr>
	<attr type="1" value="5">
		<template name="field">entry.place</template>
	</attr>
	<attr type="1" value="6">
		<template name="field">entry.score</template>
	</attr>
	<attr type="1" value="7">
		<template name="field">category.categoryname</template>
		<term>$field $relop '$value'</term>
	</attr>

	<attr type="2" value="1">
		<template name="relop"> &lt; </template>
	</attr>
	<attr type="2" value="2">
		<template name="relop"> &lt;= </template>
	</attr>
	<attr type="2" value="3">
		<template name="relop"> = </template>
	</attr>
	<attr type="2" value="4">
		<template name="relop"> &gt;= </template>
	</attr>
	<attr type="2" value="5">
		<template name="relop"> &gt; </template>
	</attr>
	<attr type="2" value="6">
		<template name="relop"> &lt;&gt; </template>
	</attr>
	<attr type="2" value="101">
		<template name="relop"> ~~ </template>
	</attr>

	<term>$field $relop $value</term>

	<template name="and_expression">
		($lhs AND $rhs) 
	</template>

	<template name="or_expression">
		($lhs OR $rhs) 
	</template>

	<template name="andNot_expression">
		($lhs AND NOT $rhs) 
	</template>

	<template name="query">
		select category.categoryname,entry.place,entrant.name,
			club.clubname,entrant.city,entrant.state
		from entry,entrant,club,category
		where entry.entrantid = entrant.entrantid
			and entrant.clubid = club.clubid
			and entry.categoryname = category.categoryname
			and $expression
		order by category.category,entry.place;
	</template>

</database>
</config>