# Xserv Help

Version 2.0.1

Frédéric Boulanger

## Introduction

“Xserv” is an AlphaTcl package which introduces a new way to manage external applications. Each operation that can be done by an application is called a service. For instance, we may have a “viewURL” service, the effect of which is to display the contents of an URL. There may be several implementations of this service: one using “Internet Explorer”, another using “Safari” or yet another using “Netscape”.

Xserv allows packages and modes to declare services and to use them in a uniform way, independent of the implementation used to provide the service.

Xserv interacts with you only for choosing an implementation for a service. If a service is invoked and no implementation has been chosen for it yet, Xserv will display a dialog containing the list of all known implementations of the service. Once an implementation has been chosen, it is remembered until you decide to choose another implementation.

## Xserv and Helper Applications

To set which application to use for different tasks for these parts of AlphaTcl, select the “Config > Global Setup > Helper Applications” command. There are two versions of this dialog; if you cannot find the service you are looking for be sure to click on the “Advanced Options” button for the full set.

Services are grouped into categories. These Categories are defined by the developers when they declare services and should have inspired names… For instance, the “viewURL” service should be found in the “Internet” category.

Note: This dialog shows only the categories, services and implementations that are known to Xserv. If a mode or package declares services but has not been loaded during the current editing session, those services and their implementations probably won't appear in the dialog.

Once you have selected a category, you should see the list of the services in this category. Select the one for which you want to change or set the implementation. You should then see the list of all known implementations of this service. The name of an implementation is generally the name of the application used to provide the service.

If you make an error or choose an implementation which is not the one you expected, you can always go back to this dialog and choose another implementation for the service.

## Using “Old-style Helpers”

If the “Helper Applications“ dialog has a section named “Old-style Helpers“, this means that some AlphaTcl package has not been properly updated to use this Xserv package. If you can't find the service you're looking for, or if for some reason a service is not responding as you expect it to, be sure to inspect this category to see if an “old-style helper“ application preference is being defined. Until AlphaTcl is thoroughly updated, you'll have to live with this limitation.

## Using an application which is not in the list

If you don't see the name of your favorite application in the list of the implementations of a service, it may be that the implementation which uses this application has a weird name, or more probably that no one has told Xserv how to use this application for the service.

If you can write Tcl code and read the programmer's manual of Xserv, you can register your application as an implementation of the service (tell Xserv how to use this application). (Select “Help > More Features Help > Xserv” and look for the “Xserv API” hyperlink.)

However, for simple services, Xserv can learn how to use your application if you know enough about Apple Events or command lines. If the service is simple enough, you will see an button named “New Helper” in the dialog. Choosing this item will open a new dialog allowing you to enter the information needed by Xserv to use your application. From the top pop-up menu of this dialog, you choose whether your application understands Apple Events (like Mac OS applications), or receives arguments from a command line (like Unix programs). If you're having trouble, please send a note to one of the AlphaTcl mailing lists explaining what service is missing and what you would like it to do.

If you are still interested in defining your own implementation for a given service, keep reading.

### Using an Apple Event driven application

For Apple Events applications, you must give the name of the application in the “Application” text field. If you prefer, you can give the creator code of the application between single quote (for instance, 'ttxt' for SimpleText or TextEdit). Then, you must give the class and code of the Apple Event that will be sent to the application. The default is an Apple Event of class aevt and of code odoc, which is the standard Apple Event to ask an application to open a document.

If you want to print a document, you can try aevt and pdoc. To open a URL, the Apple Event has class GURL and code GURL or WWW! and OURL (for Internet Explorer).

The last pop-up menu allows to choose the type of the argument: for an odoc Apple Event, the type is ”file”, which means that the Apple Event will carry a reference to a file on your disk. For a GURL Apple Event, the type should be set to “text” since the URL is just a piece of text.

### Using a command-line program

For command line programs, you must give the name of the program (for instance “gs” for ghostview).

The mode is the way the program will be executed. The default is “InSh” which will execute the program in an interactive window: you will see the output of the program and you will be able to type text if the program needs some input. “Shell” and “Exec” are two non-interactive mode: the program will be executed but you won't see anything until Alpha gets the result and does something with it. In “Exec” mode, the program is executed directly by the operating system, while in “Shell” mode, the program is executed by a shell program (like the one that reads what you type in a terminal).

The last item in the dialog allows you to give the general form of the command line. The default is to use the name of the program (represented by the “<prog>” string), followed by the argument (represented by the “#8220;$params(…)” string, in which the three dots are replaced by the actual name of the argument). For instance, if you want to use the program with the “-verbose” option, and if the argument must be prefixed by “-input=”, you should set the command line to:

         <prog> -verbose -input=$params(...)

where “…” is the name of the argument, as shown in the default value of the field.

When you have entered all the necessary information, click “OK”. This will create and select a new implementation of the service. Such implementations are called “generic implementations” since they use simple and generic mechanisms to interact with an application. Their name is always in the form “generic-<prog>”, where <prog> is the name of the program or application used by the implementation.

### Deleting Generic Implementations

If a generic implementation doesn't work or is no longer needed, it can be deleted. Open the “Config > Global Setup > Helper Applications” dialog, select the service for which you defined the generic implementation, press “Set” and then click on the “Delete” button.