XARCHIE(1) 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 avail-
able 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 inter-
face, 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 Pros-
pero, write to info-prospero@isi.edu.
When reporting bugs, problems, suggestions or contribu-
tions, 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 infor-
mation 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
12 Nov 1991 1
XARCHIE(1) XARCHIE(1)
-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 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 sen-
sitive. 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 ser-
vice.
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, select-
ing 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
12 Nov 1991 2
XARCHIE(1) XARCHIE(1)
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 rudimen-
tary. 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.
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 dis-
played 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 out-
put 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. Judi-
cious 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 parame-
ters of your queries to archie. The "Search Mode" and
"Sort Mode" items allow you to change how archie inter-
prets 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, "Ini-
tial 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 men-
tioned above, Archie servers run on machines that must be
shared between other Archie users and even other "real"
12 Nov 1991 3
XARCHIE(1) XARCHIE(1)
users. This item allows you to voluntarily lower the pri-
ority of your request, just like the Unix(tm) nice com-
mand. 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 par-
ticular, 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 inac-
tive 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 Set-
tings panel. However, they do not require that the "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 Direc-
tory" 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. (Actu-
ally, 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 unre-
ported, 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. Further-
more 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
12 Nov 1991 4
XARCHIE(1) XARCHIE(1)
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
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 cor-
responds 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
12 Nov 1991 5
XARCHIE(1) XARCHIE(1)
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 quit-
ting. 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 vari-
able XAPPLRESDIR to the directory containing your private
copy. Alternatively, you can place entries in your .Xde-
faults 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 abbreviations
-e, -s, -c, -r, -es, -ec, or -er, or on the Set-
tings 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 care-
ful to use the nearest possible host. This resource
can be set with the -host option or on the Settings
panel.
12 Nov 1991 6
XARCHIE(1) XARCHIE(1)
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 quit-
ting. 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 Set-
tings panel.
retries
Sets the number of retries, where the timeout dou-
bles every retry. This resource can be set on the
Settings panel.
ftpDir Sets the local destination directory for ftp trans-
fers. 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.
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
12 Nov 1991 7
XARCHIE(1) XARCHIE(1)
hostnames starting at the start of the line, loca-
tion 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 set-
tings 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 cus-
tomized as usual. As mentioned above, even xarchie's wid-
get hierarchy can be specified using resources, thus pro-
viding complete control over widget creation and place-
ment. 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
List hostList
Viewport locView
List locList
Viewport fileView
List fileList
Form stringForm
Label,AsciiText search{Label,Text}
12 Nov 1991 8
XARCHIE(1) XARCHIE(1)
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 con-
densed and does not correspond to the explicit "parent
Class name" format of the hierarchy resources.
To describe these briefly, outerPaned controls the rela-
tive sizes of the three horizontal display areas while
innerPaned allows the browser panels to be resized inde-
pendently. 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 wid-
gets are optional. The quitButton widget invokes the
quit() action (see below) and exits the tool. The query-
Button widget invokes the query() action and sends the
current contents of searchText off to archie . The abort-
Button 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 but-
ton 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, sort-
Button, and niceButton provide menus to set search parame-
ters 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 wid-
get 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}
MenuButton,AsciiText niceLevel{Button,Text}
Label,AsciiText ftpDir{Label,Text}
Label,AsciiText ftpType{Label,Text}
12 Nov 1991 9
XARCHIE(1) XARCHIE(1)
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 doneBut-
ton 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 remain-
ing AsciiText widgets are used to display and edit the
corresponding parameters.
Returning to the main xarchie display, the statusText wid-
get 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 dis-
play information about the current browser selection.
They are all optional; if they are not created the corre-
sponding 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 spec-
ify 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 spec-
ify 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, host-
Button, 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
12 Nov 1991 10
XARCHIE(1) XARCHIE(1)
below) with the appropriate search type as argument. Sim-
ilarly, 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 the niceLevelMenu
invoke the set-nice-level() action. These menus are chil-
dren 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 Con-
firm 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 proce-
dure 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 (query-
Button).
12 Nov 1991 11
XARCHIE(1) XARCHIE(1)
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).
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().
12 Nov 1991 12
XARCHIE(1) XARCHIE(1)
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() 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.
12 Nov 1991 13
XARCHIE(1) XARCHIE(1)
Errors due to incorrect resource specifications cause an
error message on stderr, but do not kill xarchie (usu-
ally).
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 high-
light.
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 (whee-
lan@cs.mcgill.ca).
12 Nov 1991 14