IMPORTANT ANNOUNCEMENT

Development and support of Willow is now discontinued. Willow was removed from production at UW on June 30, 1999.

Administering Willow

Section 0: Introduction
Section 1: X Resources
Section 2: Remote Execution of Willow
Section 3: Launching Willow from the Web
Section 4: Database Configuration Files
Section 5: Manual Login Databases
Section 6: Using Help Files
Section 7: Multi-Media Extensions
Section 8: Socketed Drivers
Section 9: Writing Database Drivers

Section 0: Introduction

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.

The third level of customization is to either change the way Willow interacts with the existing databases, or to make the existing database drivers talk to new databases. What you need to know in order to do this is described in the Database Configuration Files section. You may also find Manual Login Databases, Using Help Files and Multi-Media Extensions useful for adding your new database. Specific issues involved in writing a config file entry for a Z39.50 database are discussed on a separate Willow and Z39.50 page.

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.

Section 1: X Resources

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.

Willow*configURL:http://www.washington.edu/willow-config/2.5/db-config/

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.

Menu WillowMenu { 
  "Willow"      f.title
  ""            f.separator
  "Small"       f.exec "willow -xrm \"Willow*size: small\" &"
  "Medium"      f.exec "willow -xrm \"Willow*size: medium\" &"
  "Large"       f.exec "willow -xrm \"Willow*size: large\" &"
  "Extra-Large" f.exec "willow -xrm \"Willow*size: extra-large\" &"
 }

Section 2: Remote Execution of Willow

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.

Section 3: Launching Willow from the Web

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:

 conf_version = 1.1
 dflt_db      = UW-LCAT
 conf_url     = http://www.washington.edu/willow-config/2.5/db-config

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 in willow.X for information on how to suppress this query.

Section 4: Database Configuration Files

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.
conf_url =: This is not used in normal db.conf files -- only abbreviated ones downloaded from the Web. See Launching Willow from the Web for its use.
begin_menu = MN-BIB : UW Bibliographic Databases: 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.

extension_label = Article View

extension_program = some_program

See Multi-Media Extensions for more information on this pair of fields.

basic_mode =

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. Ift_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.

Section 5: Manual Login Databases

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.

Section 6: Using Help Files

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.

Section 7: Multi-Media Extensions

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,

  extension_fields  = ID,SO,II,TI,MF 
  extension_label   = Article View 
  extension_program = /usr/local/bin/uw_xviewer 
  extension_label   = Document Delivery 
  extension_program = /usr/local/bin/uw_doc_deliverer

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.

Section 8: Socketed Drivers

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.

willow-uwbrs stream tcp nowait /usr/local/willow/drivers/uwbrs \
   uwbrs -socketed -class_file /usr/local/willow/class.text

The command line flags available for the drivers are as follows:

-socketed: 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.

Section 9: Writing Database Drivers

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.

Questions and comments about Willow to:
willow@cac.washington.edu