This document is a description of how to customize Willow for use at
your site. There are four levels of customization. First, a user may
want to customize certain aspects of Willow, such as colors, or default
e-mail addresses, etc. That type of customization can be handled
through the Options menu, and/or the X-Resource system. The available
resources are documented in the file willow.X,
and are not described in detail here.

The second level of customization is site-wide behavioral defaults. A
system administrator may wish to pre-set some of the resources
described in willow.X for all of her users. In addition, there are some
resources which are only applicable to site-wide customizations. Those
are described here, in the X Resources
section. Most system administrators will not need to read any further
than this.

For a large user-community, you may decide that it is worthwhile to
take advantage of the X-Window system's remote execution capabilities
to configure Willow to run on central servers and display remotely on
the users' terminals. This is discussed in Remote
Execution of Willow.

Another interesting possibility is to let your users use Netscape or
some other Web-browser to choose from your available Willow databases.
The browser can be configured to launch a Willow process with the
appropriate database configuration at the user's command. This is
discussed in Launching Willow from the Web.

It is also possible to configure Willow so that certain database
drivers are run remotely via network sockets, rather than executed
locally on the same machine as Willow. This is discussed under Socketed Drivers.

The fourth level of customization is to do your own custom programming
and write a new database driver to speak to a database engine which is
not already in Willow's repertoire. See the section Writing
Database Drivers for (sketchy) information on this process.

If you are interested in customization beyond the first two levels, I
strongly suggest that you read the Willow Technical
Report first, since that document explains the overall architecture
and how all the pieces fit together.

Following are the X resources which you are most likely to be
interested in setting on a system-wide basis. You should also take a
look at the file willow.X which describes the X
resources an end-user is most likely to be interested in (colors, size,
save-preferences, etc.).

Note that the user can do some customization herself via Willow's
Options menu. If these settings are saved, they are written to a file
called .willowrc in the user's home directory.

Willow*willowDir: /usr/lib/X11/willow/

The base willow directory. You can use this resource to move the Willow
distribution somewhere other than /usr/lib/X11/willow.
It can also be useful if you want to have more than one version of
Willow running on your system for some reason.

Note that it is simpler to just put the willow distribution wherever
you want it and then use a symbolic link from the default location --
/usr/lib/X11 -- to point to the real location.

This is the URL for a remote directory in which Willow version 2.5 will
be able to find its db.conf and db.info
files (seeDatabase Configuration Files for
details on these files). If you want Willow to read local configuration
files, set these resource to an empty value. Be aware that the Willow
distribution does not come with any database configuration files, so if
you want to use local ones, you should download them
separately from the willow ftp server.

Note that the -cf command-line flag will override the configURL
resource, and force Willow to read a local db.conf
file.

If you are a member of the UW community, but are running Willow from a
machine outside the washington.edu domain, you should set Willow*configURL
to

http://www.washington.edu/willow-config/2.5/db-config.uw/

in order to get a full selection of UW databases. However you will have
to enter a valid UW id and password in order to actually connect to the
UW database from outside washington.edu.

Willow*helpURL:http://www.washington.edu/willow-config/2.5/help/

This is the URL for a remote directory in which Willow version 2.5 can
find its help files. If you want Willow to read local help files, set
this resource to an empty value. Willow will then look in <willowDir>/help
for the files. Be aware that the Willow distribution does not come
with any help files, so if you want to use local ones, you should download them separately from the
willow ftp server.

Willow*httpProgram: www -source

This is the name of a program that Willow can use to retrieve its db.conf
and help files via http. It can be any program that can take a URL as
a single (or final) argument, and return its contents, completely
unmodified, on stdout. If the program name starts with a "/",
it is assumed to be a full path-name, otherwise Willow assumes the
program lives in <willowDir>/drivers.

Note that if Willow*configURL and Willow*helpURL
are both set to empty values, the value of Willow*httpProgram
is ignored, since Willow will be reading the configuration and help
files from local disk.

Willow*databaseConfigDir: db-config

If Willow*configURL is set to an empty string, then
this is the local directory in which Willow will look for its database
configuration files. If it starts with a "/" it is assumed to
be a full path name, otherwise it is assumed to be a sub-directory of willowDir.
If Willow*configURL has a value, then configuration
files are read remotely, and databaseConfigDir is
ignored.

Willow*databaseConfigFile: db.conf

This resource tells Willow the name of the initial database
configuration file it should open up. If Willow*configURL
has a value, databaseConfigFile is appended to it in
order to form a complete URL. If configURL is empty, then the value is
appended to <willowDir>/<databaseConfigDir>,
and opened as a local file (but if the value of databaseConfigFile
starts with a '/', then it is assumed to be a complete path name).
Thus by default, Willow's initial db.conf file is

http://www.washington.edu/willow-config/2.5/db-config/db.conf

And if Willow*configURL is empty, the default local
file is

/usr/lib/X11/willow/db-config/db.conf

See the Database Configuration Files section
of this document for more information on db.conf
files. In particular, the difference between db.conf
and db.conf.all is explained there.

Note that the "-cf" command line argument
will override this resource. See the willow man page for more details
on command-line flags.

Willow*databaseInfoFile: db.info

This resource tells Willow the name of the file it should retrieve for
informational blurbs about each of the databases listed in the db.conf
file. Like Willow*databaseConfigFile, its value is
appended to either Willow*configURL or Willow*databaseConfigDir.
See the Database Configuration Files section
of this document for more information on db.conf files

Willow*interfaceMode: normal

There are three modes that the Willow interface can run in: normal, anonymous,
and managed. Normal is used for the
situation where Willow is running on a departmental or personal unix
machine, and all the individual users have personal accounts on that
machine.

If this resource is set to anonymous, Willow comes up
in a mode that is appropriate for anonymous, account-less use. Any
features that require a personal account on the unix machine are
disabled. On the Options menu, "Connection" and
"Print" are removed. Saving of results must be done through
ftp or email, and search strategies can only be saved via ftp. This is
the mode that Willow on the willow.u.washington.edu campus server runs
in. See Remote Execution of Willow for more
information.

Managed mode is used in conjunction with the Session
Manager environment we are running on the walk-up X-Terminals in the UW
libraries. Willow starts completely unmapped, and the Quit button is
gone.

Willow*printCommand : lpr

The default print command used by Willow. For example, you could change
it to lpr -Pprinter1 if you have a printer called
"printer1" which you want people to use. This can be
over-ridden through the options menu on a user by user basis (in normal
mode only).

If printCommand is set to none then printing is
disabled. In normal mode, printing can then be
re-enabled via the options menu.

Willow*printDialog: True

If this resource is set to False, Willow will not pop
up the "Printing..." dialog box after you press the
"Print" button. This can be useful if you have set Willow*printCommand
to be an X program with its own interface that pops up.

Willow*animationDelay : 200

How many milliseconds Willow waits between each frame of animation (the
spinning globe and about-box). If it is set to 0, animation is turned
off.

Willow*browseDelay: 250

How many milliseconds Willow waits after a keystroke in the
list-browser before sending the request to the driver. If another
keystroke comes first, count is reset. This saves wear and tear on the
list-browse server, and actually makes the browser feel more
responsive.

Willow*debug: 0

Setting debug to 1 causes Willow to echo every packet it receives from
the driver, setting to 2 causes it to also echo every packet it sends,
and setting it to 3 causes Willow to start xcodecenter instead of the
driver (to allow codecenter debugging of the driver program). The value
of debug is also passed on to the driver program, via the -debug
parameter, which causes similar echoing on that side.

Setting Up Willow on a Root Menu

You might want to set up a system-menu to start willow in the user's
choice of the four sizes. The following fragment can be used as part of
your system.mwmrc if you are using mwm. See willow.X
for a description of the size resource.

As a huge institution with a very heterogenous collection of X-capable
terminals and workstations, we have found that it makes the most sense
to run Willow on a centrally maintained cluster of machines, which
display the Willow session on the user's terminal. There are several
advantages to this approach. New releases only have to be compiled on a
single architecture, and they do not have to be distributed to a large
number of sites, and virtually all hardware resource requirements are
offloaded to an easily expandable central cluster.

This approach only works well when the application can effectively be
run anonymously, i.e. if the user does not have to have a personal
account on the server machine. As discussed in X
Resources, Willow can be run with Willow*interfaceMode:anonymous,
which turns off everything that requires access to a personal account
on the machine Willow actually runs on. All result-saving etc. can be
done via e-mail or ftp, and the user can set any personal
customizations via .Xdefaults. Following is a brief
overview of how the UW installation works.

UW Users can request an anonymous willow on their X displays via a standard script, at the heart of which is an
rsh command like this:

rsh willow.u -l willow <mydisplayname>:0

We have also added a demo account that can be started in a similar
fashion, and is accessible by anyone on the internet:

rsh willow.u.washington.edu -l demo <mydisplayname>:0

On most campus machines /usr/local/bin/willow is the
script which executes the above rsh command. Most users never know
Willow is being run on a remote machine.

Design Overview:

Note that instead of a typical rsh 'command string' after the -l
<accountname>, we have users supply their display
name. This is because the specified account always runs only one
predefined command script. This helps make the servers more secure.

The DNS name willow.u is randomly assigned to 1 of
several Dec 5000's. Currently, the pool has two such machines. More can
be added as load increases, or machines can be removed from the willow.u
alias if they develop hardware problems. This allows hardware changes
to be somewhat transparent to the user community.

We use dedicated hosts so system problems are isolated and so the
machines can be tuned for just running Willow.

We use the public domain tcpwrapper software on the
servers to restrict IP connections and to provide info about where
connections are from. This allows us to make sure only UW based systems
can access the system. Note that the demo account has much less
stringent requirements than the willow account.

We wanted the flexibility of a script to control the login process but
we didn't want a script to be the account's shell (again for security
reasons). Hence, we wrote a small C program which is used as the
account's shell. This shell binary simply invokes our startup script
and passes all the rsh arguments to the script. We only currently use 1
argument -- the display to send willow to.

The startup script does a few basic checks before starting the
requested program. It logs who/when/where the connection was from, and
also logs to which display the output will connect to. If a connection
is rejected due to IP checking or a malformed display name was
specified, the script outputs a message and dies. If the script decides
it is ok to start the process, the willow process is exec'ed on the
requested display.

Feel free to contact us
for more information, and/or source code and scripts used in this
process.

Willow is designed to be compatible with the World Wide Web and any
standard browser. The situation is analogous to the way image files
work in Mosaic. With those, you click on a hypertext link which causes
a file with a .gif extension to be downloaded. Mosaic
knows that when it has a gif file, it should start the
"xv" program to view it. Similarly, you can pick
a WWW hypertext link which causes a file containing a single db.conf
entry to be downloaded (with the extension .dbcf), and if
you have configured your Web browser properly, it will know to start a
Willow to "view" that file.

The mime type for .dbcf file is "application/x-willow".
At the client end you need to adjust your mailcap file so your browser
knows what to do with a file of type x-willow, so add the line:

application/x-willow; willow -cf %s

The "-cf" flag tells Willow to read a particular file as its db.conf,
rather than the one specified by X resources.

If you offer your own .dbcf files via a www server, you
need to tell your server that files with the .dbcf extension should be
sent out as type x-willow. To do so (at least for NCSA's httpd
server) add the following line to srm.conf:

AddType application/x-willow dbcf

Alternatively, you can add the following line to the .dbcf files
themselves. This forces the file to be interpreted as the correct mime
type, and the line is stripped out by the browser before it is passed
on to Willow.

Content-type: application/x-willow\n\n

See Database Configuration Files for more
information on creating a a db.conf file. When creating a configuration
file for downloading from a Web page, it is best to use an abbreviated
indirect file, which contains the following fields only:

The conf_version lets Willow check that it is of the
correct version, the dflt_db tag lets Willow know which
database to start, and the conf_url lets Willow know where
the real database configuration file is. When Willow sees a
configuration file of this form, it immediately opens the complete db.conf
file located at the conf_url, then starts whichever
database is specified by the dflt_db tag. This allows
Willow to present a complete selection of databases to the user, rather
than just a single one.

If there is a Willow already running on your screen when you launch a
Willow from the Web, the first Willow will ask you whether you want to
do a database change, or actually start the second Willow. See Willow*confirmWebChange
inwillow.X for information on how to
suppress this query.

The database configuration files tell Willow which databases are
available, and how to present them. By default the initial file is
called db.conf and is retrieved via http from the remote
directory specified by the Willow*configURL X-resource. If
you want to change the way Willow interacts with an already-configured
database, or have one of the already-existing drivers talk to a new
database, you must make a new db.conf entry for it.
Database configuration files do not come with the Willow distribution,
but may be downloaded
separately from the same ftp site. There is also a file called db.info
(by default) which contains informational blurbs about each available
database, for display to the user before choosing a particular one.

You can set up your database configuration either as one large file
(usually called db.conf.all) which gets read in at
start-up, or a single small file (db.conf) which contains
just enough information for Willow to build a Databases selection
interface, plus a single additional file for each database. The small
files will not get read in until the user actually selects the database
from the menu. The name of the small files are the same as the value of
their db_tag field (see below), and they should be in the same
directory as the db.conf file.

Supplementary information about configuring the Z39.50 driver can be
found in Willow and Z39.50.

Following is a field by field description of db.conf.
Blank lines, and lines starting with a '#' or '!' are ignored. Most
fields require an equal sign followed by a value, but some do not. For
them, just having the field appear is equivalent to setting its value
to true. If the field is not there, then the value is false.

Before the individual database descriptions is an optional section for
configuring Willow's hierarchical Database interface. There are four
fields available. If a menu configuration section does not appear,
Willow will automatically create a single-level Database selector, with
all the databases that appear in the db.conf file.

conf_version = 1.1

This tag must be the first non-comment item in a db.conf
or db.conf.all file (it is not needed in the database
sub-files). The expected value for Willow version 2.5 is
"1.1" (the configuration file format version number is not
the same as the Willow program version number, since the file format
does not necessarily change with every Willow release).

dflt_db = UW-LCAT

If a dflt_db field appears, then Willow will
automatically launch the specified database. The value must be a db_tag
which appears further along in the db.conf file. This
tag must appear immediately after the conf_version tag. Normally this
tag is only used in conjunction with launching Willow from a Web
browser (see Launching Willow from the Web).
Note that the -db command line option takes precedence
over the dflt_db tag in the db.conf file.

The begin_menu field indicates that a new sub-menu
should be started at this point. The value consists of two parts, a
menu tag and a label. The label is used for the button which triggers
the sub-menu (either in the interactive database picker or the pulldown
Databases menu). The tag is used to associate an informational blurb
from the db.info file with this menu section (See
below for more information about the db.info file).

Each top-level menu section will get its own page in the interactive
database picker. If Willow is configured to use the pulldown Databases
menu instead, then only the first top-level menu section will be used.

end_menu

Marks the end of a menu. Every begin_menu must have a corresponding
end_menu.

item = UW-LCAT : UW Libraries Catalog

The item field is used to indicate a database entry for the current
sub-menu. The label must correspond to a db_tag field
(see below) for a described database. If a database matching this tag
is not found in the current configuration file, Willow will assume that
a sub-file exists, with a file-name identical to the tag. For this
example, when the user selects "UW Libraries Catalog" from
the Databases menu, Willow will try to open a db.conf
file named "UW-LCAT". The same tag value can exist in more
than one place in your menu hierachy.

Following the tag is an optional colon, and a full name for the
database. If this name appears, it will be used for display to the user
on the Databases menu. In a db.conf.all file, the
display names can be taken from the db_name field in the database
description, but in db.conf file with just a menu
description that information is not available at the time the menu is
built.

separator

This is only meaningful if a Databases pulldown menu is being created,
it is ignored for the interactive database picker. It indicates that a
separator line should be drawn in the current position in the menu
structure. Note that Willow always creates a separator at the top of
the root Database menu, right after the built-in "No Database
(Disconnect)" item.

Following the menu section comes a series of database descriptions.

db_tag = UW-LCAT

The first field of a database description must be db_tag. It is a
unique identifier for the current database. It is for internal use by
Willow. If database sub-files are being used, db_tag
must be identical to the name of the file the database description
appears in.

The db_tag is also passed into the help subsystem for displaying
database-specific help. See Using Help Files
for more information.

Advanced users will need to know db_tag for use with
the defaultDatabaseChoice, userInfo, and customFields
X resources. See the file willow.X for
information on those. The value of the tag is displayed for users under
"About this Database..." in the Willow "File" menu.

db_group = UW

Databases can optionally be put together into groups. This is used
mainly for databases that require a manual login. If you enter a
user-id and password for one database, if you attempt to connect to
another one in the same group, that user-id and password will be put in
the dialog box as the default.

UW databases require an id and password if you use the UW-only
configuration files from outside the washington.edu domain. See the
section on Willow*configURL for more information on
using UW configuration files outside of UW.

The value of db_group can also be used in place of the db_tag, when
specifying the Willow*customFields or Willow*userInfo
X resources. See willow.X for details on
those.

db_name = UW Libraries Catalog

This is the display name of the database. It appears in the Databases
menu and in the "Connected" box. Note that if a name is
specified in the menu structure, it has priority over the value of the db_name
field (so this field can actually be left out).

driver = uwbrs

Name of driver program to be executed to connect to this database. If
the value is just a simple program name, then that program must exist
in <willow directory>/drivers. Willow will
launch that program locally, and communicate with it via a Unix pipe.

If the value of this field is of the form <program>:<host>:<port>,
i.e.

driver = uwbrs:cac.washington.edu:4321

Then Willow will contact the specified machine and port, and
communicate with the driver program remotely over a network socket. See Socketed Drivers for more information.

db_int_name = LCAT

This is the database name as known to the host database system. It is
not displayed to the user at all.

title_fields = ME:19,SD:60,YR:4

Specification of database-fields to use in the title-line display of
the summary window. The value of this field is passed directly to the
driver, so its format could vary. For the UW-BRS driver, the syntax is
two-character field abbreviation, followed by colon and width in
characters, with no blanks between fields.

summary_fields = ME,DT,PI,SH,MH,OH,HO,OR,PR

Specification of database-fields to use in the summary text display
area of the summary window. The value of this field is passed directly
to the driver, so its format could vary. For the UW-BRS driver, the
syntax is a comma-separated list of two-character field abbreviations,
with no blanks between fields.

extension_fields = UI,LH,IT

Specification of database-fields to use for external extension
programs. The value of this field is passed directly to the driver, so
its format could vary. For the UW-BRS driver, the syntax is a
comma-separated list of two-character field abbreviations, with no
blanks between fields. See the Multi-Media
Extensions section of this document for a description of how
extensions work.

Note that the fields listed here for UW Catalog are not used in a true
extension, but extension_fields gives us a handy way of specifying
fields that are used internally by the driver, in this case for
circulation-status queries.

If this field appears, regardless of value, display this database in
"Basic Searching" mode when it first comes up. Individual
users can override this by setting the noBasicMode
resource (see willow.X).

no_info =

If this field appears, regardless of value, do not display the database
info screen when it comes back from the driver.

env_name = class

env_val = uw

env_name = app_pool

env_val = willow_secure

The env_name/env_val fields allow you to send an
arbitrary list of name/value string pairs to the database driver. An
env_name must be immediately followed by its env_val.
These particular name/value pairs are used by the UW license manager
for granting a login ticket. See Manual Login
Databases for information about the ManualLogin env_name.
A LicenseHost env_val is also available if you have
your own copy of the UW license
manager running.

no_adv_mode =

If this field appears, regardless of value, then this database will be
accessible only in Basic Mode. I.e. there will be no
"Go To Advanced Searching" button.

Following the above fields, which apply to an entire database, come the
specifications for the search fields. Do not get confused by the
overload on the word "field" here. These are fields in the db.conf
file which are used to describe the searchable fields that exist in
the database Willow is going to talk to.

Willow knows about two types of fields. First are text fields. These
appear in a vertical column on the left-hand side of the Search window
(in advanced searching mode), and each has a corresponding text-area
for the user to enter a value. Each text-field name is actually a
pop-up menu which contains all the available fields. The second type
are limit fields. These appear at the bottom of the Search window, and
the user can simply turn them on and off with a check-box.

First come the descriptions of all the text fields. To describe a text
field requires two db.conf fields, but there are several
additional optional fields as well.

t_field_name = Title

The value of t_field_name is the string that actually
appears on the Search window next to the type-in box. This field is
required.

t_field_cmd = .TI.

The value of t_field_cmd is passed to the driver along
with whatever the user has put into the text box. In the case of the UW
BRS driver this is normally a two-character field abbreviation wrapped
in periods. However it can be any value whatsoever, as long as the
driver will know what to do with it. This field is required.

dflt_at = 1

dflt_at = 2

This field indicates in which, if any, of the six available text field
positions this field should be displayed. Use multiple lines with dflt_at
if the field should be shown more than once. If there is no dflt_at
for this text_field then it will only be accessible to the user if she
pops-up one of the field/menus and changes the field value. If you use
fewer than all six dflt_ats, the extra search fields
will not appear on the Willow search screen.

list_name = Exact Titles

Which, if any, browse-list(s) should be associated with this text
field. If there are multiple lists, then have multiple list_name lines.

basic_field =

If this field appears, regardless of value, then this text field should
be shown in basic searching mode. If basic_mode was not set above, then
this field is ignored.

basic_only =

If this field appears, regardless of value, then this text field should
be shown only in basic searching mode, not in advanced.

is_limit =

If this field appears, regardless of value, then this text field is
actually searched as a limit field. This is probably only relevant for
the BRS database driver.

t_range_type = YEAR

Text fields can also be used for numeric/date searching. If
t_range_type is set, then instead of the text-typein area
next to the field name, there will be buttons to allow the user to pick
a range. There are four possible values, DAY, MONTH, YEAR,
and NUMERIC, which correspond to the type of dialog
that will be presented to the user.

t_year_range = 1989-1994

This field is only applicable if t_range_type is set.
If so, and t_year_range is not set, then the user will
have to type in the years she wants manually. If it is set, then the
indicated range will be available on a pop-up menu. If the upper year
is left out, then the current year (according to your system clock)
will be used.

After specifications for the text fields come the specifications for
the limit fields. No more than four limit fields can be specified per
database. There are only two db.conf fields applicable to
limit fields.

l_field_name = English Only

This is the label that should be displayed next to the on/off check
box.

l_field_cmd = LG = ENG

This is a string that gets passed verbatim to the driver if the limit
is turned on by the user.

Willow and its drivers can be configured to prompt the the user for
login information for secure databases. However Willow knows nothing
about the concept of user-ids and passwords.

Instead, there is a general purpose mechanism for the driver to ask
questions directly to the user. The driver passes the text of the
question to Willow, and Willow displays it to the user in a dialog,
then sends the response back to the driver. The question can require a
response of yes/no, typed-in text, or masked text (where Willow
displays asterisks instead of the characters the user enters).

The driver supplies an identifying tag for each question, such as
"Password" or "UserID", or whatever. Willow
remembers the last response the user made for each question for each
database. If the question is asked again during a session, Willow will
enter the user's previous response as a default. Thus for manual-login
databases you don't have to keep re-entering the same user-id and
password. Databases sharing the same db_group tag will
share cached responses (see Database Configuration
Files for more information on the db_group tag). If
the user selects Save from the Options menu the responses are recorded
in the .willowrc file (along with the other options the
user has set). Responses are not recorded on disk for
masked-text queries (to avoid storing passwords in plain-text files).

There is also a resource Willow*userInfo which lets the
user predefine default answers in her .Xdefaults. See willow.X for more information on this resource.

To cause the uwbrs and z3950 drivers to ask for a user-id and password,
use the db.conf env_name ManualLogin. I.e.

env_name = ManualLogin
env_val = Yes

It does not actually matter what appears as the env_val to
go with ManualLogin. See Database
Configuration Files for more information on the db.conf
file. Note that for the z3950 driver it is possible to just hard-code
the user-id and password into the db.conf file by using
the auth_id env_name. See Willow and
Z39.50 for more information.

Willow uses a custom-designed hierarchical help browser which displays
bitmap image files. Willow can display generic or database-specific
help. If you add new databases you may want to create your own custom
help screens to document the subtleties of searching them.

See X Resources for information on where help
are actually located (i.e. either on the local file system or a remote
Web server). The files with a .txt extension are the help
control files. Basically these files list the help topics that will be
shown to the user and the names of the bitmap files that correspond to
each topic. They can also point to other txt files, this
allows a topic to expand into a sub-menu.

A different root-level txt file is read in depending on
which Help button the user presses on Willow. Pressing help on the
Search window reads in search.txt. Pressing help on the
Search window in Basic Searching mode reads in basic.txt,
while summary.txt and full-record.txt
correspond to the help buttons on the Summary and Full-Record windows.

The first character on a line in txt file determines what the help
system will do with it. You may want to look at help/search.txt
for examples of how these contructs are used:

#

Denotes a comment. The line is ignored.

!

Starts a new help topic. The rest of line is displayed to the user in
the menu portion of the help window.

$

Means a directive, as follows:

$ help filename

Calls subtopic file 'filename', i.e. read in a new .txt file.

$ picture filename

Includes bitmap file 'filename' to correspond to previous topic line.
See below for more information on bitmap files.

$ if symbol

Tests if 'symbol' is defined in the symbol list passed in from Willow.
Currently Willow passes in two symbols -- the value of the db_tag
field from db.conf of the currently connected
database, and a string representation of the size that Willow is
currently running -- small, medium, large, or extra-large. See willow.X for more information on how
Willow determines its size. It is also possible to test multiple
symbols separated by a '|' symbol.

$ ifnot symbol

Tests if 'symbol' is not defined in the symbol
list.

$ else

$ else if symbol

Companions to the $ if construct.

$ endif

Terminates an $ if construct.

The bitmap files live in the sub-directories of help. CROS
and CROS-s contain the regular and small sized bitmap
files for cross-database help, i.e. screens that all databases share. GENERIC
is the general purpose help which is used when there is no database
specific help available. The rest of the directories correspond to the
names of the available databases.

The bitmap files start out as standard xbm files, then they are
converted to a more compact binary format (using the xbmtobin program
found in willow/tools/xbmtobin). As discussed in willow/README,
these help screens are then compressed using the Free Software
Foundation's gzip file compression program (hence the .gz
extension). The gzip package is available via ftp from MIT. Willow can use gunzip
to uncompress them on the fly, or, you can pre-gunzip
them all if you want save CPU but use extra disk space. Note that help
files retrieved remotely via http are always assumed to be in
compressed form.

The original xbm files can be created by any number of tools. At UW, we
create the master help documents in FrameMaker, then use xgrab
to capture xbm images of the pages. Contact us if you would like more
information about the tools we have developed to make this process a
little less painful than it sounds.

The current plan is for this help system to eventually be scrapped in
favor of an HTML-based one.

Willow has the capability to work with multi-media extension programs.
This interface is still under development, and no databases which use
it are currently offered to the public. However it is available for you
to use if you wish.

The basic idea is that you can use Willow to feed certain data-fields
of your retrieved records to an arbitrary list of external programs.
For example:

As part of Elsevier Publication's TULIP project, UW Willow users will
soon be able to view bitmap images of the actual pages from the journal
articles they find in a Materials Science bibliographic database.

Even though Willow currently only handles standard ASCII text in a
single font, UW Library Catalog users will soon (?) be able to use an
external program to view bibliographic records in the proper language
for Chinese, Japanese, or Korean holdings.

Eventually UW Willow users will be able to use an external forms editor
to request library staff to actually xerox and campus-mail the text of
interesting articles after the user finds the citation in one of our
bibliographic databases. Forms will also be available on-line for
inter-library loans of books the UW does not have.

Other possibilities include using external programs to give the user
sound samples, images, animations, etc. associated with retrieved
records.

To use an external extension program, you use the extension_fields,
extension_label, and extension_program fields in
the db.conf file (as discussed above).
For example,

If any extension_label fields exists for a given database,
then the "Retrieve Full" button on the Summary window becomes
a pull-down menu, labeled "Retrieve ->". The first item on
the menu does the normal Willow full-record retrieval. For each extension_label,
an additional menu-item is created. When one of those items is
selected, the corresponding extension_program is executed.
Then for each title currently selected in the Summary window, the
program is fed, through its stdin, the values of the
database fields listed in extension_fields.

As discussed in the Willow Technical Report,
Willow and its database driver generally run on the same machine, and
communicate via a Unix pipe. However it is also possible for the Willow
and the driver program to run on different machines, and communicate
via a network socket. This capability was developed to facilitate the
porting of Willow to non-Unix platforms. That way the Willow interface
can be ported to the MS-Windows for example, but the driver programs
can continue to run on a Unix host, and do not need to be ported. Also,
this architecture would allow somebody to write a customized database
driver, and let outside users get at their data without having to
download and install a new driver.

Whether Willow execs a local driver or connects over a socket is
controlled by the db.conf file (see Database
Configuration Files). If the name of the driver is followed by a
":<host-name>:<port>" then it is a
socket connection.

Socketed drivers are designed to be launched by inetd. If you are
interested in configuring some socketed drivers yourself, see the man
pages for "inetd", "inetd.conf",
and "services" for general information. In your /etc/services
you will need an entry along the following lines for each driver type
you want to offer. This establishes a mapping between a port number and
a named service.

willow-uwbrs 1234/tcp # willow uwbrs driver

Then in inetd.conf, you will need a line like this, to
establish a mapping between the named service and an actual program to
execute, with arguments. Note that this should actually be a single
long line.

This tells the driver that it is running under a socket instead of a
pipe.

-debug <n>

If n is greater than 0, some debugging information is printed out as
the driver runs.

-outfile <file>

Tells the driver to log echo and debug information to a named file
rather than stdout/stderr. This is the only way to see output from a
socketed driver.

-cfg_path <path>

Tells the driver what directory to look for auxiliary files in. This is
only used by the z3950 driver. This path can actually be a URL.

-http_prog <prog>

Tells the driver the name of a program that can be used to retrieve
configuration files remotely via http. This is currently only used by
the z3950 driver.

-class_file <file>

Tells the driver the name of the class file used for determining where
a client connection is coming from. This is used at the UW to make sure
people from outside the UW do not gain access to our UW-only databases
by "laundering" a connection through a socketed driver. See getclass.c
in the uwbrs source for more details.

One major caveat here -- at least under Ultrix, in your inetd.conf
file you are only allowed to specify five arguments to the program you
are starting, and the first must be the program's own name. If you need
more than five arguments, you will probably want to start the driver
via a one-line shell script, then just put that script name in your inetd.conf.

As discussed in the Willow Technical Report, a
database driver is the program that translates back and forth between
the Willow user interface and a particular host database system. Right
now, there are exactly two database drivers in existence -- one which
speaks the standard Z39.50 database access protocol, and one which
speaks to the BRS search engine, as installed and customized at the UW.
It is our hope that Z39.50 will really take off, and more and more
database vendors will offer compatibility with this standard. If the
database you would like Willow to talk to does speak Z39.50, then you
merely need to set-up a db.conf entry and use the existing
driver.

However, if your database does not speak Z39.50, and the prospects for
making it do so do not look good, then you can write your own custom
driver program to allow Willow to speak to it. Since we do not know if
many people are going to be interested in doing this, we have not yet
expended a great deal of effort to make this process as easy as it
could be. If you do want to do it, you should start by looking at the
uwbrs source code. Figure out as much as you can by yourself, then
contact us for more help as needed.