Alpha Services

Name:	Xserv
Version:	2.2
Last update:	2019-02-18 17:52:14

Introduction

Xserv is an AlphaTcl package which introduces a new way to manage external applications. Each operation that can be performed 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 Firefox, another using Safari or yet another using Internet Explorer.
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 for the service. Once an implementation has been chosen, it is remembered until you decide to choose another one.
For Alpha developers, more information about the xserv API can be found in the Xserv Guide.

Xserv and Helper Applications

To set which application to use for different tasks for these parts of AlphaTcl, select the Alpha ↣ 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: the Helper Applications dialog displays only the categories, services and implementations that are known to Xserv at the moment it is invoked. If a mode or package declares services but has not been loaded yet 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 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 (that is to say tell Xserv how to use this application). For more information, see the Xserv Guide.
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 a button named New Helper in the Helper Applications 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 usually do), or expects arguments from a command line (like Unix programs do). If you're having trouble, please send a note to one of Alpha's 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 driven 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 class aevt and code 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 modes: 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 $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 Alpha ↣ Global Setup ↣ Helper Applications dialog, select the service for which you defined the generic implementation, press Set and then click on the Delete button.

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.

License and Disclaimer

Original Author: Frédéric Boulanger.
Copyright (c) 2002-2019, Frédéric Boulanger and contributors.
Contributors: Joachim Kock, Bernard Desgraupes.
All rights reserved.
The xserv package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Frédéric Boulanger nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL FRÉDÉRIC BOULANGER OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.