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

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

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
					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}
			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 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).

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() 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.

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