W2H: How to run non-GCG applications

---

The W2H interface can be used also for the non-GCG applications. Usually, however, you have to write a wrapper, a shell script which is invoked by W2H and, only after tailoring application command-line parameters, a real application can be called.

This document explains how to add new non-GCG applications into W2H interface and how to write a wrapping shell script. An example of a wrapper with more technical hints is distributed in w2h.example-wrapper.

There are three steps to be done in order to add a new application to W2H:

1. create a configuration file for a given application
2. add its name into the application.menu file, and
3. write a wrapper for starting the application

Creating a configuration file

Each application must have an own configuration file describing all its command-line parameters. The configuration files for GCG programs are distributed with GCG and can serve as templates for your own apps. The format and syntax of these files are the intellectual property of GCG. Two very simple configuration files (for calendar and sort programs) are distributed as examples.

The name of the configuration file consists of an application name and an extension .config. The application name is the one used in a list of application (see about a file application.menu below). Use lowercases for the configuration file name (even if the application name has some uppercases). An example: you would like to call a UNIX program cal. Therefore you add a name Calendar into the application.menu (see below) and you create also a configuration file calendar.config. Note that the application name does not need to be the same as the application which is actually called (here there are cal versus Calendar).

Any newly created configuration file has to be put in a directory specified in $RUNCFG in Cfg.pl. Note that this variable can contain more directories delimited by commas. That means that you do not need to mixed your config files with those distributed by GCG.

Here are few hints how to write your own config file:

You should use a keyword EXTERNAL (the same one introduced in GCG 9) to say that the application is a non-GCG one. But actually for W2H there is only a small difference. W2H is designed so closely to deal with GCG programs that it would be difficult to forget them totally. In reality it means, that W2H starts a GCG session even for a non-GCG program. The main reason for it is that a GCG session is started at the beginning anyway, long before a user decides which application to call.

The main consequence to this behavior is that you cannot use W2H only for non-GCG apps. But it was not the intention of W2H anyway.

The usage of keyword EXTERNAL, however, helps within the wrapper scripts. If EXTERNAL is used W2H does not produce the GCG specific parameters (such as -Default or -Doclines) so your wrapper does not need to take care about them. See also comments in w2h.example-wrapper.

If your application creates an output file which has to be displayed in the output manager (a Result window) use a TEXTFILE keyword. This keyword can have a value representing a file extension used. So if your application creates an HTML document you can put

TEXTFILE html

into your configuration file.

A keyword EXE tells what program has to be invoked. If not used then a name of the configuration file is used (again without the extension .config, of course). In our example, we have calendar.config but we want to start a program cal, so we have to specify EXE cal.

Adding into a list of applications

The names of the new applications must be added into a list of all available apps. For GCG programs, the list is in a file application.menu. Look there for a proper syntax but you do not need to change the original GCG file. The list of all such menu files is specified in Cfg.pl in a variable $APPMENU as a comma separated list.

Remember that the names used in the menu files must be the same (except of case sensitivity) as their configuration files. Of course, without .config extension.

Creating an application wrapper

A wrapper should have a name which a real program name can be deduced from. It is done with help of a variable $NONGCG_WRAPPER in Cfg.pl. For external, non-GCG applications W2H starts a script which name is built from the application name (taken from EXE keyword or from configuration file name) and from the contents of $NONGCG_WRAPPER.

An example: Let's assume that $NONGCG_WRAPPER is set to -wrapper, and calendar.config file contains EXE cal. In such a case W2H starts cal-wrapper. An another example: sort.config does not have any EXE keyword included, so W2H calls sort-wrapper (because the configuration file is called sort.config).

Remember that $NONGCG_WRAPPER is used only for the external apps, i.e. for those having an EXTERNAL keyword in their config files.

Additionally, the wrapper scripts must be found by W2H. Therefore, you must put your wrappers to locations specified in the path defined in $PATH variable in Cfg.pl.

The main task for wrapper scripts is usually to prepare a command line and then to call an application. The GCG programs understand -init=filename construct on their command line. They read their command-line parameters from this filename. W2H creates the init file, and the wrapper has to read it and put all its lines directly on the command line.

There are also some GCG specific parameters (such as -Default). But W2H tries to avoid them when EXTERNAL keyword is used.

Also a common task of a wrapper can be to redirect standard output of the external application (if any) into an output file in order to get it into the output manager window in W2H. See comments in the template w2h.example-wrapper for further explanation.

---