XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
NAME
xarchie - X11 browser interface to archie
SYNOPSIS
xarchie [X Toolkit options] [-search type | -cers] [-sort type | -t]
[-host host] [-maxHits num] [-offset num] [-nice lev | -N lev]
[-debug num | -D num] [-expert ] [-help | -?]
DESCRIPTION
Xarchie is an X11 browser interface to the Archie network information
service using the Prospero virtual filesystem protocol. Archie provides
information about files available for ftp anywhere on the Internet;
xarchie displays this information using an easy-to-use, point-and-click
interface. Xarchie is designed (like most X applications) to be highly
customizable. Almost all details of the interface, including display
appearance and command interface, can be customized using X resources.
Users should be aware that the xarchie client accesses a server that is
shared with users on other hosts. As such, submitting long or large
numbers of queries during peak periods not only increases the time that
they have to wait for a response, but it increases the time that others
have to wait too. Please read about the -nice option, the niceLevel
resource, and the "Nice Level" button on the Settings panel before making
large queries. Also, you should use the closest possible host to save
long-distance network traffic.
If you have any questions about Archie itself, write to archie-
l@cs.mcgill.ca. If you have questions about Prospero, write to info-
prospero@isi.edu.
When reporting bugs, problems, suggestions or contributions, please be
sure to send them to the right place. Issues dealing with the X interface
should be sent to George Ferguson (ferguson@cs.rochester.edu). Brendan
Kehoe (brendan@cs.widener.edu) is charge of the archie clients and the
network stuff underlying xarchie, Cliff Neuman (bcn@isi.edu) is in charge
of Prospero, and Alan Emtage (bajan@cs.mcgill.edu) and the others are in
charge of the Archie service itself.
USAGE
This section describes how to use xarchie in its default configuration.
Subsequent sections provide all the information needed to customize it to
your liking.
Command and Status Area
Xarchie's display is divided into three horizontal areas. The top pane is
a control panel. The "Quit" button exits xarchie after prompting for
confirmation (but see the -expert option, below, or use Shift while
clicking), the "Query" button sends your search term (see below) to
Archie, the "Abort" button allows to you to abort a long-running query,
and the "Settings" button pops up a panel from which you can change
various parameters of your queries. The buttons labelled "Search Type",
"Sort Type", and "Nice Level" allow you to modify aspects of your search
10/89 Page 1
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
without using the Settings panel. Their use is described below under "The
Settings Panel". The area labelled "Status" is updated to reflect the
progress of your query when one is progress. The "Save" and "Ftp"
buttons are described below under "Retrieving Files".
Querying
You enter your "search term" (the string or expression you want to search
for) in the appropriately labelled text item in the bottom pane. These
text items provide emacs-like editing controls (see the Athena widgets
manual for a complete description). Hitting Return in the text item or
clicking on the top pane button labelled "Query" will send your request
to archie. Entries matching your search term will be displayed in middle
pane of xarchie's display, which functions as a host-location-file
browser.
If you find that your query is taking too long, you can abort it by
clicking on the "Abort" button when it is sensitive. Your query will be
aborted as soon as possible. You should note that while aborting a query
will allow you to enter a new query, it does not currently remove the
query from the server's queue. Thus aborting queries does not reduce the
load on the server -- just the opposite probably. Use with discretion,
like the rest of the service.
The Browser
The left-hand pane of the browser contains the names of hosts that have a
file matching your search term. Clicking on a hostname will highlight it
and cause the middle browser pane to be filled with a list of locations
on that host where files matching your search term can be found. The
selected hostname will also be displayed in the item labelled "Host" in
the bottom pane of the xarchie display. Similarly, selecting a location
from the middle browser pane will cause the right browser pane to be
filled with a list of the files available from the selected host in the
selected location, and the location will be displayed in the bottom pane
item labelled "Location". Finally, selecting a file from the right
browser pane causes its name, size, permission modes and last-
modification date to be displayed in the correspondingly-labelled bottom
pane items. Clicking on a selected item will unselect it and will clear
any "lesser" panes and information items.
Note that if a browser pane has only one item, then that item will be
automatically selected and its "lesser" panes and information items
filled in. This saves time and effort in the common case where there is
only one host, location, or file that matches.
Retrieving Files
The button labelled "Ftp" in the top xarchie pane lets you retrieve the
file currently selected in the browser by anonymous ftp. This service is
presently quite rudimentary. You must have selected a host, location, and
file in the browser, and the selection must not be a directory. The
destination directory and mode of the file transfer can be set on the
Settings panel, described below. This functionality will be improved in
the near future.
Page 2 10/89
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
To allow you to save the results of a query for later use, the button
labelled "Save" in the top pane causes xarchie to write a file containing
the information currently displayed in the browser. Clicking on this
button prompts for the filename to save to, then writes the file. When
clicked on with "Shift" held down, it uses the current search term with
".lst" appended. The format of the output file is controlled by the
saveFormatOneLine resource, and the operation is actually performed by
the save-to-file() action. Both of these are described below. Judicious
use of "Save" will obviously help reduce the load on the Archie servers.
The Settings Panel
The panel popped up by clicking on the "Settings" button in the top
xarchie pane allows you to change the parameters of your queries to
archie. The "Search Mode" and "Sort Mode" items allow you to change how
archie interprets your search term and how xarchie sorts the results,
respectively. Holding down a mouse button while the mouse cursor is in
the item displays a menu from which you can choose the desired search or
sort type. The label to the right of the item is updated to reflect the
choice. The item labelled "Host" similarly provides a menu of known
Archie hosts. You should choose one appropriate to your site. In addition
however, you can enter an arbitrary hostname in the Text item next to the
"Host" item. The other items on the Settings panel are Text items that
allow you to edit their values. "Host" is what machine to contact with
the query, "Max Hits" is the limit on the number of successful matches
that will be returned, "Initial Timeout" is the length of the first
timeout interval in seconds, and "Retries" is the number of times to
retry the query if it times out, doubling the timeout each retry.
The "Nice Level" item deserves special mention. As mentioned above,
Archie servers run on machines that must be shared between other Archie
users and even other "real" users. This item allows you to voluntarily
lower the priority of your request, just like the Unix(tm) nice command.
The menu provides some recommended values and you can enter arbitrary
values in the text item. If you are searching with a large number of
matches requested, please increase your nice level. Note that, like
nice(1), nicing a job does not mean your job won't affect others. In
particular, once your job begins it is not pre-empted, thus you should
still avoid long jobs during peak periods. You should especially avoid
queries for items of only personal interest (you know what we mean)
during these periods.
Clicking on the "Apply" button will apply the settings on the panel to
xarchie. Clicking on "Default" will reset the settings to the values
they had when xarchie started (but note that you will still have to apply
them to have them take effect). Clicking on "Done" closes the Settings
panel. A popup confirmer will appear if you did not apply your changes,
allowing you to discard the changes or go back and apply them. Note that
the "Apply" button is inactive until a change is made.
The menus available from the "Search Type", "Sort Type", and "Nice Level"
buttons on the xarchie top pane have effects corresponding to those of
the buttons on the Settings panel. However, they do not require that the
10/89 Page 3
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
"Apply" button be clicked on to take effect, and do not affect the
behaviour of the "Done" button confirmer.
The functions of the items labelled "Local Ftp Directory" and "Ftp
Transfer Type" affect how files are retrieved, as described in the
previous section. The "Local Ftp Directory" item specifies the directory
on the local machine that you wish the retrieved file to end up in. The
"Ftp Transfer Type" item allows you to specify whether the file should be
retrieved in "ascii" or "binary" mode. (Actually, you can enter whatever
you want there, but I doubt that many other values are meaningful). Note
that since ftp support is so rudimentary, errors resulting from incorrect
values in these items will probably go unreported, except that you won't
get the file.
OPTIONS
The following non-widget resources can be set from the command-line or in
a resource file. As usual, when given on the command line they can be
abbreviated to their shortest unique prefix, often the first letter.
Furthermore xarchie accepts all the standard X Toolkit options (see
X(1)).
-search type
Sets the search mode for archie queries. The type can be one of
exact, substr, subcase, regexp, exactSubstr, exactSubcase, or
exactRegexp. The exact mode is fastest and returns files exactly
matching your search term. The substr and subcase modes return
substring and case-sensitive substring matches respectively (ie.,
substr means case-insensitive). The regexp mode allows you to
specify a regular expression to select files. The exact* forms of
these last three try an exact match first and then fall back on the
more costly search type if the exact match fails. The default
search mode is exact. This option corresponds to the searchType
resource.
-e Equivalent to "-search exact".
-s Equivalent to "-search substr".
-c Equivalent to "-search subcase".
-r Equivalent to "-search regexp".
-es Equivalent to "-search exactSubstr".
-ec Equivalent to "-search exactSsubcase".
-er Equivalent to "-search exactRegexp".
-sort type
Sets the sort mode for displaying archie responses. The type can be
one of default (sort by host and file name) or invdate, meaning
"sort inverted by date". This option corresponds to the sortType
Page 4 10/89
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
resource.
-t Equivalent to "-sort invdate".
-host host
Sets the host to which archie queries will be sent. Please be
careful to use the nearest possible host. The default is
"archie.mcgill.ca". This option corresponds to the archieHost
resource.
-maxHits num
Sets the maximum number of matches allowed per query. This option
corresponds to the maxHits resource.
-offset num
Sets the offset of the Prospero query. This option corresponds to
the offset resource.
-nice level or -N level
Sets the query niceness level. Higher numbers are nicer, up to a
maximum niceness of 32765. The default niceness is 0. This option
corresponds to the niceLevel resource.
-debug level or -D level
Sets the Prospero debugging level. Higher numbers mean more verbose
messages. For this option to have any effect, xarchie must have
been compiled with the -DDEBUG flag. This option corresponds to the
debugLevel resource.
-expert
Tells xarchie not to confirm operations like quitting. This option
corresponds to the expert resource.
-help or -?
Prints the usage message summarizing xarchie options.
CUSTOMIZING XARCHIE
Xarchie has a default set of resources built in. If you wish to customize
the tool, take a copy of the default application defaults file (see FILES
below) and modify it. Then, before invoking xarchie, set the environment
variable XAPPLRESDIR to the directory containing your private copy.
Alternatively, you can place entries in your .Xdefaults file or provide
them with the -xrm toolkit option.
Non-Widget Resources
Most of the following resources can also be set using the command-line
options described in the previous section.
searchType
Sets the search mode for archie queries. This can be one of exact,
substr, subcase, or regexp. The default search mode is exact.
This resource can be set with the -search option, or its
10/89 Page 5
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
abbreviations -e, -s, -c, -r, -es, -ec, or -er, or on the Settings
panel.
sortType
Sets the sort mode for displaying archie responses. This can be one
of default or invdate, meaning "sort inverted by date". This
resource can be set with the -sort option, or its abbreviation -t,
or on the Settings panel
archieHost
Sets the host to which archie queries will be sent. The default is
"archie.mcgill.ca". Please be careful to use the nearest possible
host. This resource can be set with the -host option or on the
Settings panel.
maxHits
Sets the maximum number of matches allowed per query. The default
is 99. This resource can be set with the -maxHits option or on the
Settings panel.
offset
Sets the Prospero offset. The default is 0. This resource can be
set with the -offset option or on the Settings panel.
niceLevel
Sets the query niceness level. Higher numbers are nicer, up to a
maximum niceness of 32765. The default is 0. This resource can be
set with the -nice option or on the Settings panel.
debugLevel
Sets the Prospero debugging level. Higher numbers mean more verbose
messages. For this option to have any effect, xarchie must have
been compiled with the -DDEBUG flag. This resource can be set with
the -debug or -D options.
expert
Tells xarchie not to confirm operations like quitting. This
resource can be set with the -expert option.
timeout
Sets the initial timeout value, in seconds. The default is 4. This
resource can be set on the Settings panel.
retries
Sets the number of retries, where the timeout doubles every retry.
This resource can be set on the Settings panel.
ftpDir
Sets the local destination directory for ftp transfers. The ftp()
action will use the "lcd" command to switch this directory before
retrieving the file. This resource can be set on the Settings
panel.
Page 6 10/89
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
ftpType
Sets the transfer type for ftp transfers. The ftp() action will use
the "type" command to set the transfer type before retrieving the
file. This resource can be set on the Settings panel.
saveFormatOneLine
If True, then the file written by the save-to-file() action will
have one line per entry, in the format
mode size date host:location/file
If False (the default), then the file format has hostnames starting
at the start of the line, location names indented one tab, and file
entries indented two tabs, all on separate lines. Hostnames and
locations are only printed once. The latter is more readable, the
former may be more useful if the output is to be used by a program.
widgets
Specifies the widget hierarchy, as described below. This should be
a whitespace-separated list of
parent Class name
triples. Certain widgets must be created; xarchie will fail with an
error message if they are not. These are described in the next
section.
menus Due to problems with some versions of X, widgets of class EzMenu
must be created separately from the others. Thus any entries that
would normally go in the widgets resource with class EzMenu must
instead be listed here. The format is the same as for the widgets
resource.
settingsWidgets
Specifies the widget hierarchy for the popup settings pane. These
widgets are not created until they are needed. The format is the
same as for the widgets resource.
Widget Hierarchy
Xarchie uses standard Athena widgets that can be customized as usual. As
mentioned above, even xarchie's widget hierarchy can be specified using
resources, thus providing complete control over widget creation and
placement. The default widget hierarchy, given by the widgets resource,
is as follows:
TopLevelShell Xarchie
Paned outerPaned
Form buttonForm
Command quitButton,queryButton
Command abortButton
Command saveButton,ftpButton
Command searchButton,sortButton
Command niceButton,settingButton
Label,AsciiText status{Label,Text}
Paned innerPaned
Viewport hostView
10/89 Page 7
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
List hostList
Viewport locView
List locList
Viewport fileView
List fileList
Form stringForm
Label,AsciiText search{Label,Text}
Label,AsciiText host{Label,Text}
Label,AsciiText location{Label,Text}
Label,AsciiText file{Label,Text}
Label,AsciiText size{Label,Text}
Label,AsciiText mode{Label,Text}
Label,AsciiText date{Label,Text}
Note that this description of the widget hierarchy is condensed and does
not correspond to the explicit "parent Class name" format of the
hierarchy resources.
To describe these briefly, outerPaned controls the relative sizes of the
three horizontal display areas while innerPaned allows the browser panels
to be resized independently. Each browser panel consists of a Viewport to
allow it to scroll and a List to display the entries. The three List
widgets must be created with those names.
The default widget hierarchy creates several buttons across the top of
the top xarchie pane. All of these widgets are optional. The quitButton
widget invokes the quit() action (see below) and exits the tool. The
queryButton widget invokes the query() action and sends the current
contents of searchText off to archie . The abortButton invokes the
abort() action to interrupt the current query. (Note that xarchie looks
for a widget with this name to sensitize and desensitize, so if you want
the button be active only during queries, be sure to create it with this
name.) The saveButton widget invokes the save-to-file() action which
writes the currently displayed results to a file. Without "Shift", it
prompts for the filename. With "Shift" it uses the current search term
with ".lst" appended. The ftpButton invokes the ftp() action to fetch
the selected file. The searchButton, sortButton, and niceButton provide
menus to set search parameters without using the Settings panel. These
specification of these menus is described below under "EzMenus". The
settingsButton widget invokes the settings() action to pop up the
Settings panel. This panel uses the following widget hierarchy, given by
the settingsWidget resource:
TopLevelShell settingsShell
Form settingsForm
Command doneButton,applyButton,defaultButton
MenuButton,Label search{Button,Label}
MenuButton,Label sort{Button,Label}
MenuButton,AsciiText host{Button,Text}
Label,AsciiText maxHits{Label,Text}
Label,AsciiText timeout{Label,Text}
Label,AsciiText retries{Label,Text}
Page 8 10/89
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
MenuButton,AsciiText niceLevel{Button,Text}
Label,AsciiText ftpDir{Label,Text}
Label,AsciiText ftpType{Label,Text}
All the widgets on the Settings panel are optional. If they are not
created then the corresponding parameters will obviously not be visible
or changeable. The doneButton invokes the done-settings() action, the
applyButton invokes apply-settings(), and the defaultButton invokes
default-settings(). While these Command widgets are optional, you will
need some way of invoking apply-settings() if you want your changes to
take effect. The actions are described below. The MenuButton widgets
pop up menus described below under "EzMenus". The remaining AsciiText
widgets are used to display and edit the corresponding parameters.
Returning to the main xarchie display, the statusText widget is updated
during queries to show the progress (or lack thereof) of the query. If
this widget is not created, status updates will not be done. In the
bottom pane, the searchText widget is used to enter the search term, and
by default it binds Return to the query() action to send the query to
archie. It must be created. Finally, all the other AsciiText items in
the stringForm are used to display information about the current browser
selection. They are all optional; if they are not created the
corresponding information will not be displayed. In the future perhaps
these will be used for input also, to restrict searches or indicate other
actions.
EzMenus
The MenuButton widgets on both the main xarchie display and on the
Settings panel use the EzMenu package to specify their menus in resource
files. The format of these resources is, for example:
Xarchie*sortMenu.label: Sort Mode
Xarchie*sortMenu.menu:\
(line) \
(item "Default" (action "set-sort-type(default)")) \
(item "Invdate" (action "set-sort-type(invdate)"))
The label of the menu is given by the label resource and the menu
specification by the menu resource. Each menu entry is described by a
parenthesized expression. In this example, the first expression
specifies an unselectable line, like an SmeLineObject. The other
expressions specify items with their labels and the action procedure to
invoke when the item is selected. Entries are separated by whitespace.
Action procedures are described in the next section.
On the settings panel, the searchButton, sortButton, hostButton, and
niceLevelButton widgets each pop up menus that allow the searchType,
sortType, archieHost and niceLevel, respectively, to be changed. When
selected, each item in the searchMenu invokes the set-search-type()
action (see below) with the appropriate search type as argument.
Similarly, the items in the sortMenu invoke the set-sort-type() action,
the items in the hostMenu invoke the set-host() action, and the items in
10/89 Page 9
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
the niceLevelMenu invoke the set-nice-level() action. These menus are
children of their respective MenuButtons.
On the main xarchie top pane, the corresponding buttons pop up menus that
invoke the "-now" forms of these actions (see below), thereby removing
the need to "Apply" the changes.
Finally, three types of popup windows can appear. An Alert box signals an
error and blocks until clicked in, a Confirm box allows the user to make
a Yes/No decision, and a Dialog box allows the user to enter a string.
These have widget hierarchies:
TransientShell alertShell
Dialog alertDialog
Command okButton
TransientShell confirmShell
Dialog confirmDialog
Command yesButton,noButton
TransientShell dialogShell
Dialog dialogDialog
Command okButton,cancelButton
respectively.
Translation Actions
The following action procedures are registered for xarchie and can be
bound to widget events using the translations resource (see the Xt
manual, Appendix C). The actions of the browser widgets are hard-coded
since they are so essential to correct behaviour. They can however be
bound to different events using the notify() action (that is, you could
notify on some other event than mouse clicks).
quit()
Exit xarchie. Prompts for confirmation unless either an argument
is passed to the action procedure or the expert resource is True.
By default this is called without arguments by clicking on the
"Quit" button (quitButton), and is called with an argument to force
exit if Shift-"Quit" is used.
query()
Send the current contents of the "Search Term" text widget
(searchText) to xarchie. By default this is performed by clicking
on the "Query" button (queryButton).
abort()
Aborts the current query at the soonest possible time. Has no
effect is a query is not currently being processed. By default,
this is performed by clicking on the "Abort" button (abortButton).
Page 10 10/89
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
save-to-file()
Writes a file containing the information displayed in the browser.
With no arguments, this action prompts for the filename to write
to. With one argument, the argument is passed to sprintf(3)
together with the current search term to form the filename. By
default, the "Save" button invokes save-to-file() to prompt for the
filename and Shift-"Save" invokes save-to-file("%s.lst").
ftp() Attempts to fetch the currently selected file by anonymous ftp. It
is currently an error if a file is not selected, and the selected
file must not refer to a directory. By default this is performed
by clicking on the "Ftp" button (ftpButton).
settings()
Pops up the Settings panel, and resets its values to those
currently in effect. Raises the Settings panel is it is already
popped up. By default this is performed by clicking on the
"Settings" button (settingsButton).
apply-settings()
Sets the current settings from the values on the Settings panel.
default-settings()
Resets the values on the Settings panel to the default settings,
but does not affect the current settings until the apply-settings()
action is invoked.
done-settings()
Pops down the Settings panel. If there are changes that have not be
applied, then a popup confirm box allows the user to discard the
settings or go back and apply them.
set-search-type()
This action sets the searchType as indicated on the Settings panel,
but does not affect the current settings until the apply-settings()
action is invoked.
set-search-type-now()
Sets the searchType immediately without waiting for
apply-settings().
set-sort-type()
This action sets the sortType as indicated on the Settings panel,
but does not affect the current settings until the apply-settings()
action is invoked.
set-sort-type-now()
Sets the sortType immediately without waiting for apply-settings().
set-host()
This action sets the archieHost as indicated on the Settings panel,
but does not affect the current settings until the apply-settings()
10/89 Page 11
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
action is invoked.
set-host-now()
Sets the archieHost immediately without waiting for
apply-settings().
set-nice-level()
This action sets the niceLevel as indicated on the Settings panel,
but does not affect the current settings until the apply-settings()
action is invoked.
set-nice-level-now()
Sets the niceLevel immediately without waiting for
apply-settings().
alert-ok()
confirm-yes()
confirm-no()
dialog-ok()
dialog-cancel()
These actions are registered for use with the Alert, Confirm, and Dialog
popups. Registering them for widgets that are not popups will at best
have no effect. These actions are invoked by default by the buttons on
the popups. As well, by default pressing Return in a Dialog popup's
"value" sub-widget (where the value is entered) invokes dialog-ok().
ENVIRONMENT
XAPPLRESDIR - Directory containing xarchie resource file
FILES
$XAPPLRESDIR/Xarchie - default xarchie resource file
DIAGNOSTICS
Xarchie indicates X errors using the ever-popular default X error handler
that prints a message and dies, possibly leaving a large core dump
somewhere.
Errors due to incorrect resource specifications cause an error message on
stderr, but do not kill xarchie (usually).
Errors due to incorrect user commands or problems with the connection to
archie result in a popup alert box being displayed. Clicking on the
indicated button in the alert box will make it go away and allow you to
continue.
BUGS
The current searchType, sortType, etc., are not indicated in the menus.
This is because the specification is so flexible that it's hard to figure
out which item to highlight.
Page 12 10/89
XARCHIE(1) UNIX System V(12 Nov 1991) XARCHIE(1)
The current ftp service is primitive. In particular, xarchie will not
signal an error if the file is not found, since the ftp sub-process
itself did not signal an error upon termination. Rather, a message will
appear on stderr. This should improve as we redo the ftp services.
SEE ALSO
X(1), archie(1), ftp(1).
AUTHOR
George Ferguson, University of Rochester,
(ferguson@cs.rochester.edu)
Original standalone archie program by Brendan Kehoe,
(brendan@cs.widener.edu).
Original Prospero archie program by Clifford Neuman,
(bcn@isi.edu).
The archie service was conceived of and implemented by Alan Emtage
(bajan@cs.mcgill.ca), Peter Deutsch (peterd@expresso.cc.mcgill.ca), and
Bill Heelan (wheelan@cs.mcgill.ca).
10/89 Page 13