Execute shell commands and ARexx macros

AWeb offers a unique and powerful facility to execute Amiga DOS Shell commands and ARexx macros from a page, just by clicking on a hyperlink or by submitting a form. With some effort, you can create complex applications using AWeb as the user interface, starting scripts that dynamically compose new documents that are loaded into AWeb via ARexx, etcetera.

Although this feature can be very useful, it could also be very dangerous. Therefore this feature works only from local pages (with a URL starting with file://localhost/), and only if the Allow Shell commands setting is selected. If you haven't selected this setting, a warning requester is displayed whenever you try to follow such a hyperlink. In this requester you can abandon the command, or allow it to continue.

Simple shell commands

To include a simple command, just add a normal hyperlink in your document that points to a URL of the form

   x-aweb:command/your_DOS_command

If the user clicks on the hyperlink, your_DOS_command is executed. The output of the command is directed to an auto opening console window, unless you specify another output redirection in your command.

Because compatible HTML mode stops the URL at a space, make sure you have escaped all spaces in the command by " " or else the command won't work if the user has selected compatible HTML mode.

Example: <a href="x-aweb:command/dir sys: all">get dir</a> would allow the user to execute the dir sys: all command by a click on the words "get dir".

Note: The DOS command is executed in a separate shell, with a current directory set equal to the current directory of AWeb. You are advised to use only absolute path names in the DOS command, or else the result will depend on which directory happened to be the current directory when you started AWeb. When AWeb is running, you can use the assign name AWebPath: as an absolute reference to the directory where the AWeb executable is located.

ARexx macros

Starting ARexx macros from your page works in a similar way. Just add a normal hyperlink that points to a URL of the form

   x-aweb:rexx/your_ARexx_macro

If the user clicks on the hyperlink, your_ARexx_macro is started with the ARexx port for this window as the default command port.

Parameters

You can use a HTML form or a clickable map to pass parameters to your DOS command or ARexx macro.

Forms

Supply a ACTION="x-aweb:command/your_command" attribute in your <FORM> tag to execute the command if the user submits the form. Similarly, you can include a ACTION="x-aweb:rexx/your_macro" attribute to start the ARexx macro.

METHOD=GET

For forms defined with METHOD=GET (the default), form parameters are converted to Amiga DOS style parameters: the field name will be used as the argument name, and the field value will be used as argument value. The value will be quoted, with the escape, newline and quote characters in the value escaped as required by Amiga DOS.

Note: switch arguments (/S) cannot be passed in this way. You could use a script instead, like the example below.

Parameters for ARexx macros are passed in the same format as for DOS scripts. The argument string will contain the name, an equal sign, and a quoted value for each form parameter. Have a look at the second example below for one possible way of parsing this.

Note that the total length of all arguments passed in this way is limited to about 4000 characters. The excess is truncated. If your form might yield a longer argument set, use METHOD=POST instead.

METHOD=POST

For forms defined with METHOD=POST, a temporary file is created. The command or ARexx script will be called with exactly one argument, the file name. The temporary file contains the message in exactly the same way as it would have been sent to a HTTP server. In short, this means:

Fields are separated by the & character.
Spaces are replaced by + characters.
Most non-alphanumerical characters are replaced by a %XX sequence, where XX is the hexadecimal representation of the character.

It is the responsibility of the command or script to delete the temporary file afterwards.

Note that you should use the default form encoding (ENCTYPE="application/x-www-form-urlencoded", or don't specify the ENCTYPE attribute). The multipart/form-data encoding type is not supported for Shell and ARexx forms.
For file upload fields (<INPUT TYPE=FILE>) the file name is included in the message when using default encoding, not the file contents as it would for multipart/form-data forms. This is probably what you want in your command or script.

Clickable maps

When using a clickable map, the x and y coordinates of the mouse pointer within the image are passed to the command as parameters without keyword.

Load the result back into AWeb

If your script or macro has created an HTML document (or just a plain text file), you can automatically load this file back into AWeb. Use the ARexx OPEN command for this purpose. If you re-use the name of your file for different responses, be sure to add the RELOAD switch to prevent AWeb from showing the previous (cached) document again.

Of course, this will work better from within an ARexx macro than from within a DOS script. In a DOS script, you have no way of determining to which ARexx port you should address the OPEN command.

Another way is to load the resulting document directly into AWeb while you are creating it, without the need to create a temporary file. Look at the description of the CHANOPEN command for details.

Examples

Below are two examples of this feature. Have a look at the source of this page, and at the executed macro first to convince yourself that following the link or submitting the form won't do any harm. Then select Allow Shell commands in the program settings requester and play with this form.

Simple shell command

This example just gets the directory of SYS: and shows it in a separate console window: show dir.

ARexx macro

This example gets the directory contents of a selected drawer.

Back to index.