There is also a Printer Friendly version of this page.

Example of a Rexx program running as an applet.

The WarpDoctor Rexx Plug-in does for Rexx what Netscape's inclusion of the JVM and applet tag did for Java: it provides an environment that enables visual type Rexx programs to be downloaded from a web server on demand and run in an area of an HTML page, appearing to be part of the page. By visual Rexx programs we mean programs built to run as Presentation Manager (PM) applications, either with tools such as DrRexx, VX-Rexx and GPF-Rexx, or by using libraries provide PM functions and features the Rexx program such as VRexx2 or Rexx/TK.

The WD Rexx Plug-in however also enables command-line type Rexx programs to be run in an area of the HTML page or in a separate Command Prompt window. Finally, the WD Rexx Plug-in provides the facilities to enable fully automated software installation for WarpIN based installations, and it provides the framework for other non-Rexx applications to function as plug-in applications.

Example of a GPF-Rexx application running as an applet

Why Rexx?

• Rexx is everywhere - from Palm PDA devices to mainframes to Amiga to Microsoft Windows products, Rexx is the interpreted language that runs on almost all operating systems and hardware platforms.
• Rexx is stable - by this I mean both the language specification and the implementation. Rexx is a standardized ANSI language meaning there is a specification for how the language is supposed to work and a governing body that controls the changes made to that specification. In addition the Rexx interpreters on various platforms are very stable and reliable. You can write a Rexx program today and be confident that it will run on any Rexx interpreter 5 years from now. Conversely Rexx programs written almost 10 years ago run perfectly fine today on modern machines and operating systems. Compare this with Java which seems to go through major revisions every year.
• Rexx is fast. Like Java, Rexx programs go through a tokenizing process before they are run by the Rexx interpreter. On OS/2, the tokenized version of the program is stored in extended attributes of the source file so that the tokenizing step can be skipped the second and subsequent times the program is run. Not only do the programs run fast, but Rexx interpreter starts much faster than the Java Virtual Machine; it is not unusual for smaller Rexx programs to finish running in less time than it takes the JVM just to load itself into memory and start up.
• Rexx programs can be very small. On OS/2 so much of the operating system and related parts - like networking, TCP/IP, user management, database access, etc. - are already Rexx enabled and included as part of the standard OS/2 install, that the Rexx programs themselves can be very small because they take advantage of all those "libraries" already installed on the machine. The Rexx program does not have to include any of that function or code because it already is installed. To give an idea of the size difference, the GPF Rexx program that is shown in the figure above, which includes drag and drop capabilities and uses two containers, is less than 60K in size, and it is the largest of all the Rexx demo programs on the plug-in web site. Since the Rexx Plug-in can handle compressed (zipped) Rexx programs, the effective transfer size of the program(s) is even smaller.
• Rexx brings the power of the OS/2 PM API to browser applets. With the libraries and visual Rexx application building tools available on OS/2, Rexx programs can use most or all of the PM API in programs that run in a web page. The disadvantage is that the program is using operating system specific features and is therefore not portable across other platforms. The advantage is that the program is using operating system specific features and is therefore more powerful and familiar to users than an application that uses a generic set of graphical widgets.
• Rexx programs can get to the client system. Which means that the Rexx application can perform real work: they can print, save data to the hard drive, query the client system for information, etc. Java applets are crippled to the extent that is almost impossible for them to do any real work without violating security restrictions which require permission from the user. The procedures needed to enable the Java based application to even ask for that permission are daunting. (Security is implemented by the Rexx Plug-in differently than it is with Java applets. The Rexx program does not need to do anything special in order to get permission from the user; that is handled by the plug-in itself, see the Security section below for details.)

What is a Plug-in?

Netscape published the first plug-in application programming interface (API) which allowed plug-ins to be developed and run by Netscape browsers. Most of the other browser manufacturers followed Netscape's lead and enabled their browsers to load and run plug-ins written to the Netscape API. As an example the WD Rexx Plug-in will run on Netscape (v 4.04 and 4.61), Opera 5.12 and Mozilla based browsers - although Mozilla still has a way to go before they get the bugs out of their plug-in API implementation.

Plug-ins are generally "installed" by placing the DLL file containing the plug-in in a directory the browser recognizes as storing plug-ins. (The WD Rexx Plug-in has a WarpIN install program that will install the plug-in in the correct directory for most browsers.) The browser scans the directory upon start-up to determine which plug-ins are available and what data streams and files the plug-in can handle.

Each plug-in "registers" the types of data streams that it can handle with the browser, and file extensions which identify the type of data. These types are called MIME-Types. On OS/2 the registration happens when the browser starts.

Plug-ins are started in one of three ways:

1. When the browser encounters an EMBED HTML tag in a HTML page. The TYPE parameter of the EMBED tag calls out the MIME-Type the browser uses to identify the plug-in to load and start. This is the most common and most powerful way of starting a plug-in, and the only way to start the WD Rexx plug-in.
2. When the browser is sent a data stream with a MIME-Type that is registered to the plug-in.
3. When the browser is sent a file with an extension that is registered to the plug-in.

The first method, the embed tag method, is the only method the WarpDoctor Rexx plug-in will allow itself to be run in because of the security built into the Rexx plug-in. Therefore it is the only method we will discuss below.

How are Rexx Programs Run?

When the user displays that page the browser reads the page and finds the EMBED tag. The browser then scans the tag for the type parameter in order to ascertain which plug-in needs to be loaded. It reads down its list of registered MIME-Types and loads the plug-in associated with the first match it finds in the list. Once the plug-in DLL is loaded the browser creates an "instance" of the plug-in to handle the EMBED tag and passes all the parameters of the EMBED to that instance of the plug-in.

It is possible for multiple instances of the plug-in to be running at once. This can happen if the user opens the same page in more than one window, or if a single HTML page has multiple EMBED tags on a single page, or if the user opens multiple different pages that all have an EMBED tag that points to our plug-in.

Once the instance is created the browser then retrieves the file or URL specified in the src tag and passes it to the plug-in as a data stream telling the plug-in what MIME-Type the data stream is based on the type parameter of the EMBED tag. (Mozilla based browsers have a bug in that they use the extension of the file specified in the src parameter and ignore the type parameter. The Rexx Plug-in corrects that bug for those browsers.) The Rexx Plug-in uses the MIME-Type to determine what type of Rexx program it is getting and how to execute the program. It then executes the program that is "streamed" to it.

The MIME-Type is the key that tells the Rexx Plug-in the type of Rexx program that is in the data stream. Different types of Rexx programs are run different ways by the plug-in. Some Rexx programs are run in a separate session started by the plug-in; others run as a macro of the plug-in, meaning that the plug-in executes the RexxStart() function and handles input and output through subcommand handlers. Each different type of Rexx program has its own MIME-Type. The MIME-Types recognized by the Rexx Plug-in are shown in the following table:

MIME Type Description x-warpdoctor/cmdrexx Command line Rexx, or Rexx running in an OS/2 Command Prompt window. These types of programs run in a separate session from the plug-in. x-warpdoctor/rexx Rexx program running as a macro of the plug-in. The output is routed to an output window on the HTML page. x-warpdoctor/drrexx DrRexx/DrDialog application, running either in its own window or as an applet. DrRexx applications run in a separate session. x-warpdoctor/gpfrexx GPF Rexx application. The application can run either in its own window or as an applet. GPF applications run in a separate session. x-warpdoctor/vxrexx VX-Rexx running as a macro of the plug-in. The application runs as an applet. x-warpdoctor/vx-rexx VX-Rexx running in a separate session/process. The application can run either in its own window or as an applet. x-warpdoctor/generic Generic Rexx or other application. These always run in a separate session. x-warpdoctor/warpin WarpIN install package file in the *.WPI format. Warpin.exe is run in a separate session from the plug-in. The Rexx Plug-in determines if WarpIN is installed on the client machine before attempting to run WARPIN.EXE, and finds and loads WPIRTL.DLL if necessary.

The EMBED Tag

The example below shows a complete HTML page with an EMBED tag and the parameters needed to run the Rexx program helloWorld1.rex. Each of the parameters is explained below. (The parameters are the name=value sets that appear between the <EMBED and the ending > .)

The type parameter specifies what MIME-Type is associated with this EMBED tag. In this example the MIME-Type specifies a command-line type Rexx program running as a macro of the plug-in.

The src parameter specifies the URL of the file which contains the Rexx program.

The height and width parameters specify the size, in pixels, of the area set aside on the HTML page for the plug-in's use.

The figure below shows the Rexx program that was specified by the EMBED tag example above.

Rexx Program Running as a Macro of the Plug-in

The HelloWorld1.rex Rexx program shown in the figure above is listed below.

Besides the "standard" HTML parameters of the EMBED tag that control the size and placement of the plug-in on the page, there are addition parameters that are recognized by the Rexx Plug-in that can be used to control the behavior of the plug-in itself. These parameters are shown in the list below.

Standard Parameters

Name Description SRC url URL of Rexx file to execute. This must be specified as a full URL, not a relative URL. This is because the plug-in parses the SRC value in order to fetch other associated files as it needs them. For example src='http://www.warpdoctor.org/plugin_cmdProcessor.res' is correct, src='plugin_cmdProcessor.res' is incorrect. For VX-Rexx and VXRexx programs you specify the macro file, i.e. the file ending in *.VRM, in the SRC parameter. BORDER n Where n = line size in pixels of the border. TYPE mime-type MIME-Type of Rexx file. This must be one of the MIME-Types supported by the plug-in. HIDDEN TRUE | FALSE True = window is hidden. The WarpDoctor Rexx plug-in requires a window in order to function correctly, meaning that this parameter must be set to FALSE, or it must not be specified at all; the default for the parameter when not specified is FALSE. NAME name Name of the plug-in. This enables referring to the plug-in by the supplied name in JavaScript code when using Netscape's LiveConnect to script the plug-in. The WarpDoctor Rexx Plug-in implements a JavaScript to Rexx interface without using LiveConnect, therefore this parameter is meaningless for the Rexx Plug-in. ALIGN LEFT | RIGHT | TOP | BOTTOM Alignment for the applet FRAMEBORDER YES | NO NO = frame has no border HEIGHT n Where n = height of window, in pixels. Passed to the Rexx program as wdMainArgs.winheight WIDTH n Where n = width of window, in pixels.Passed to the Rexx program as wdMainArgs.winwidth VSPACE n Where n = the margin, in pixels, between top and bottom edges of the applet window and surrounding text and images. HSPACE n Where n = the margin, in pixels, between left and right edges of the applet window and surrounding text and images. PALETTE Whether palette is foreground or background to the window. Not used. PLUGINSPAGE URL for auto install instructions. Not used by the Rexx Plug-in.

WD Plug-in Specific - 'reserved' - Parameters

Name Description CgiUrl url WdPluginCgi.exe is a CGI program on the web server that provides services to the Rexx Plug-in. The plug-in automatically fills in CgiURL on start up by parsing the src parameter. If the value placed in CgiURL by the plug-in is incorrect, either because wdPluginCgi.exe is in a non-standard location or because the plug-in parsed the src parameter incorrectly, you must supply the CgiURL parameter on the EMBED tag with the correct URL for the wdPluginCgi.exe program. CheckForDLLs filename [filename [filename ...]] A list of one or more DLL's to check before running the Rexx program. Multiple file names can be specified in the list by separating each file name by a space. If this parameter is present the plug-in checks that the DLL's in the list exist and can be loaded before attempting to run the Rexx program. If any of the DLL's are missing or cannot be loaded, an error message box is displayed and the instance terminates. This is useful for insuring that the requisite DLL's exist on the client's hard drive before trying to run the program. Note that the plug-in automatically checks for standard required DLL's needed for the various Rexx run-times. You only need to use this parameter if you need non-standard DLL's. CheckForEXEs filename [filename [filename ...]] A list of one or more executable files to check before running the Rexx program. Multiple file names can be specified in the list by separating each file name by a space. If this parameter is present the plug-in checks that the files in the list exist somewhere on the PATH before attempting to run the Rexx program. If any of the files are missing an error message box is displayed and the instance terminates. This is useful for insuring that any requisite executable files exist on the client's hard drive before trying to run the program. Note that the plug-in automatically checks for standard required executable files needed for the various Rexx run-times. You only need to use this parameter if you need non-standard executable files. closeOnExit YES | NO YES = Plug-in closes the Command Prompt window when Rexx program terminates - valid only for x-warpdoctor/cmdrexx. Default=YES. debugPlugin 0 | 1 | 2 | 3 | 4 0 = turn off debug messages, any value > 1 turns on debug messages in plug-in. DebugPlugin=1 means the PmPrintf.DLL is loaded. (PmPrintf.dll is the interface between the PmPrintf.exe output window and the Rexx Plug-in. It must be loaded before any debug messages can be sent to PmPrintf.exe. It is also loaded whenever a PmPrintf command is issued by the Rexx application. eraseOnExit YES | NO YES = Rexx program is erased from the browser cache when terminated. This is useful when making changes to the program since the browser will cache and reuse (usually) the first version downloaded in a session. pluginTitle title text Title that appears in windows and dialog boxes. SavePrompt title If this parameter appears it means that the plug-in will display a file dialog prompting the user to save the streamed file. This is mainly for x-warpdoctor/warpin MIME-Types to allow the user to copy the install file that is downloaded to a known location on their hard drive, thus allowing the user to save the file that is being installed on their machine. Otherwise the file is streamed into the browser's cache and assigned a random name by the browser. ReleaseInstance instanceHandle Releases a plug-in instance (a waiting Rexx program) that has been paused with the WaitOn JS command. This parameter should be used with the MIME-Type of x-warpdoctor/execute. When this parameter is found during plug-in instance start-up the plug-in copies all the embed parameters to equivalent JS_VAR variables for the instanceHandle and then immediately terminates. The waiting Rexx program running in plug-in instanceHandle is then released. That program uses the query JS_VAR... command(s) to retrieve the values. This mechanism allows for passing data between JavaScript and Rexx, or between one Rexx program and another. RexxOutputWindow YES | NO Turns on/off the display of the window that displays Rexx SAY statements and SAYTOWIN commands. The window is ON (YES) by default for MIME-Types of x-warpdoctor/rexx and x-warpdoctor/cmdrexx, and OFF (NO) for all other MIME-Types. StripTrailingBlanks YES | NO YES (the default) causes the plug-in to strip off any trailing blanks from the response to the PULL command for Rexx programs running as a macro - MIME-Type x-warpdoctor/rexx. The default Rexx behavior is to leave trailing blanks, if any were typed, in the value. TimeoutServer milliseconds The amount of time, in milliseconds, to wait for an initial response from the server before declaring an error. This value may need to be adjusted if you are communicating with a very slow or heavily loaded server. The default value is 30,000 - 30 seconds. TimeoutValue milliseconds The amount of time, in milliseconds, to wait for commands and functions to complete before declaring an error. The default value is 10,000 - 10 seconds. workWindowName windowName The name of a window the plug-in is to use for issuing JavaScript commands for various plug-in commands. The default is _blank which means the plug-in will use a new, blank, window. When a JavaScript command is issued by a Rexx program, or any of the other commands (OpenWindow, CloseWindow, etc.) that require JavaScript, the plug-in builds a file containing the JavaScript commands and uses the GetUrl command to get the browser to execute the JavaScript. The plug-in then immediately closes the window. This can cause a window to flash momentarily on the user's screen. The WorkWindowName parameter specifies an already existing window that the plug-in is to use instead of creating a new window. This window can be a very small or obscure window that is not noticeable to the user, thereby avoiding the momentary flashing of the "work window" when it is created and destroyed by the plug-in. If the window named in WorkWindowName does not exist the plug-in will create a new window. ZippedFlag YES | NO YES means the file specified in the SRC parameter is a zipped archive. The plug-in unzips the archive into the TEMP directory and executes the Rexx program extracted from the archive. The name of the Rexx program (without its extension) in the zipped archive must match the name of the zipped file, without its extension.

While all the EMBED tag parameters listed above have special meaning either to the browser or to the Rexx Plug-in, you are not limited to just those parameters. You can create your own additional parameters to use for passing values to the Rexx programs. These "user created parameters" can have any name you want, as long as the name does not conflict with any of the "established" parameters listed above - and the name does not contain any spaces or special characters. Each of user created parameter is passed to the Rexx program in the Rexx stem variable wdEmbed.name where name equals the name of the parameter. So for example, if you modified the EMBED tag from the above example to add two parameters (myParm1 and AnotherUserParm), as shown below

the Rexx stem variable wdEmbed. would hold these values:

Variable Value wdEmbed.myParm1 a special value wdEmbed.anotherUserParm another value wdEmbed.0 2 wdEmbed.name.1 myParm1 wdEmbed.value.1 a special value wdEmbed.name.2 anotherUserParm wdEmbed.value.2 another value

Rexx Plug-in Security

• Don't run any programs unless you know where they come from
• Don't accept any programs (or email, or files) from a site or person that you do not know and trust.

Security for the WarpDoctor Rexx Plug-in is implemented by a list of approved sites with optional prompting before running Rexx programs. The list of approved sites restricts Rexx programs that are run by the Rexx Plug-in to those programs that come from a site in the list. Prompting prevents a Rexx program from running without approval from the user.

The Approved Site list is a list of sites that the user has determined to be "safe" sites - meaning sites that the user will accept Rexx programs from. Sites are added to the list by the user with the Security Configuration Tool (by right-clicking on the list and selecting Add), or by the plug-in when directed to by the user.

Every time a plug-in instance is started the plug-in checks the URL of the Rexx program against the list of approved sites. If the program is from a site that is not in the list, a dialog box is displayed telling the user that the site is not in the list and giving the user the choice of:

• Rejecting the program
• Running the program
• Running the program and adding the site to the Approved Sites list.

If the program is from a site on the Approved Site list, but that site has been flagged as Always Prompt, or the user has checked the Prompt for every Rexx program checkbox, the use will be prompted before the program is run. The user can chose to run the program or reject the program.

Rexx Plug-in Security Configuration Tool

The security system allows the user to accept all Rexx programs from a trusted site, from all sites, or to prompt before running each Rexx program on a site by site, or all Rexx programs from any site. Thus the user has control on how much security to impose and the ability to tailor that security level for each individual site.

Installing the Plug-in

On that page you have a choice of two files to download:

• wdRexxIn.wpi (590K) - which is for those that already have WarpIN installed on their machines.
• wdRexxIn.exe (1MB) - which is for those that do not already have WarpIN installed. This contains enough of the WarpIN files to provide a self-contained install, meaning the install will run without WarpIN existing on the target machine.

Links for both files are FTP links to prevent the file from becoming corrupt during the download. You will need to Shift-click on the link to get the browser to save the file to your local hard drive. Put the file in a temporary directory. Once either file is saved to your hard drive double click on the file to start the install process.

The Rexx Plug-in install archive is made up of three or four parts.

• The executables, which include the Security Configuration Tool and utility programs used by the plug-in. These can be put in any directory you specify.
• A dynamic link module - wdPlugin.dll - which must be installed to a directory on your LIBPATH.
• The DrRexx runtime - DrRexx.exe. This package only appears if DrRexx.exe is not found on the your system, and is installed to the same location as the other executables.
• The plug-in itself - npwrpdoc.dll. This file must be installed to the PLUGINS directory of each browser that needs to run the plug-in.

The parts of the install show up in WarpIN as "packages", with the plug-in part displayed as one or more browser packages, since the plug-in is installed to a browser. The number of browser packages displayed depends on the browsers that are installed on your machine.

Install Screen for the Rexx Plug-in

The install program attempts to find all the browsers installed on your machine. It can find Netscape v 4.04, 4.61, Opera 5.12, IBM Web Browser version 2 and Mozilla starting at version 1.2. The install program cannot find versions of Mozilla below 1.2 or IBM Web Browser before version 2. Each browser found appears as a "package" on the install screen. Each browser "package" copies the npwrpdoc.dll file to the appropriate directory for that browser.

In addition to the packages for each specific browser there is a "User Specified Browser" package which can be used to install the plug-in DLL (npwrpdoc.dll) for a browser not found by the install program. To use this package you have to select the package and specify the PLUGINS directory for that browser in the Install path. For all OS/2 browsers the directory where the plug-in goes is actually called PLUGINS.

When the install completes you will have an entry in OS2.INI that points to the directory where the executable files where installed, and a WarpDoctor folder on your desktop that looks like this.

In addition to installing the Rexx Plug-in itself, you may need to install run-times for different Rexx application environments; the run-time for DrRexx applications is installed as part of the plug-in. For example VX-Rexx applications require the file VROBJ.DLL somewhere on the LIBPATH of the client machine. The Install runtimes page can use be used to install whatever run-times you need. Normally a site administrator would probably include the run-times needed for the types of Rexx programs available at that site in a custom version of the plug-in install package. But since there are demonstration programs for each type of Rexx environment supported by the Rexx Plug-in, this page exists to enable you to run those demonstration programs. You cannot install anything from this page until the plug-in is first installed because this page executes a Rexx program to perform the installs. The program first checks for the existence of the run-time files on your system before downloading the files.

Rexx Run-time Install Page

Writing Rexx Programs for the Plug-in

Since the plug-in is designed to run any Rexx program, Rexx programs that will run in their own window and which do not need to use any of the Rexx Plug-in commands, need do nothing special. The programs should run correctly with no modifications.

On the other hand, Rexx programs that need to be integrated with the plug-in - either because they want to run as an applet in the HTML page or because they want to use the services and features of the plug-in - must have some minor modifications. Integration with the plug-in is achieved through three means:

1. Rexx functions provided by the plug-in for use by the Rexx program.
2. Rexx variables that are used by the plug-in to provide information to the Rexx program and by the Rexx program to control some aspect of the plug-in.
3. "Commands" which the Rexx program "issues" to the plug-in using the plug-in Rexx function wdCommand() .

Rexx Functions

Name Description wdPluginLoad() Registers all the other plug-in Rexx functions. wdParseArgs() Initializes the plug-in environment for the Rexx program and creates the Rexx stem variables wdMainArgs. and wdEmbed. . The function must be called before any other plug-in Rexx function except wdPluginLoad. wdCommand() Sends commands to the plug-in and returns the results of the command. wdPluginUnload() Called at the end of the Rexx program to de-register the plug-in Rexx functions. wdOpenPipe() Opens a "message" pipe to the plug-in for receiving notification of events. A message pipe is used only when a Rexx program needs to receive notification before being terminated, or if the Rexx program needs notification of paint, movement, minimize and maximize events, etc. Normally a "message" pipe is not needed, since the plug-in automatically controls the Rexx application window. wdReadPipe() Waiting until a message is received, then returns with the message. wdClosePipe() Closes the message pipe.

Rexx Variables

Name Description wdMainArgs. Output - contains information about the size and position of the plug-in area/window, the instance handle, pipe handle and the names and the command and message pipes. The variable is created by wdParseArgs() function. wdEmbed. Output - contains the user created parameters from the EMBED tag. A tail variable is created for each user created parameter; the value of the variable equals the value of the parameter. wdPlugin. Input and Output. wdPlugin.errorSwitch is used to control how the plug-in functions handle errors. When set = 0 (the default) any error in the plug-in Rexx functions is returned as an error message in the RESULT. When set = 1 the Rexx functions throw a syntax error instead of returning an error message. The error message is instead put in wdPlugin.errorMessage. This allows you to write programs with a SIGNAL label ON SYNTAX statement instead of checking the return value for each function call for errors.

Commands

• Opening new browser windows.
• Loading HTML pages, or other URLs, into existing or new browser windows.
• Uploading files to a FTP server.
• Downloading files from a web server or an FTP server.
• Getting a URL into a file or a Rexx variable.
• Calling CGI programs on a web server.
• Copying, renaming, moving and deleting files on the client hard drive.
• Executing JavaScript commands and routines.

With these commands, and a CGI program on the web server (which could also be written in Rexx) the Rexx application running in the client browser can be totally integrated with data and applications that exist on the web server, or anywhere else on the network. For example a Rexx application running in a browser could:

1. Retrieve a file from the server containing the latest version numbers of software applications located on the server.
2. Compare the applications on the list to applications installed on the client machine, noting which applications are out of date by version number.
3. Display a screen to the user of the applications needing updates.
4. Retrieve the updated versions from the server based on selection made by the user and install them on the client.

The integration possibilities extend beyond just sending and getting files. With the ability to execute CGI programs on the server and pass variables to those CGI programs, the Rexx application on the client browser can now essentially remotely invoke programs on the server and capture the results or output of those programs on the client.

The plug-in also provides commands and features that allow the Rexx application to interface with JavaScript. The Rexx application can execute JavaScript commands, which means the Rexx program is not limited to the functions provided by the Netscape Plug-in API (and hence the Rexx Plug-in), but can use almost any feature and capability provided by the JavaScript language recognized by the browser.

A summary of the Rexx Plug-in commands is shown in the table below.

Command Description AddToDeleteList Adds a file name to a list of files that are deleted when the plug-in instance terminates. This is the easiest way to insure that temporary files are deleted when the Rexx program terminates without the Rexx program having to capture a termination event. AppendFile Appends the contents of one disk file to another. CloseMessagePipe Closes the plug-in (sever) end of an open message pipe; the plug-in Rexx function wdClosePipe() closes the Rexx (client) end. A message pipe is used by the Rexx program to get notification of plug-in events that are of interest to the program, such as the termination event. CloseWindow Closes an open browser window. CopyFile Copies a disk file to a new name or location on the local hard drive. CopyFileToServer Uploads a file to a remote server using FTP. On Netscape a progress dialog box displayed associated to plug-in window. CreatePage Creates and displays a new HTML page from the text supplied. ExecProg Executes a program on the client machine, returning the program's return code as the result. FileDialog Opens a file dialog box. The file dialog can be specified as either a single or multiple selection dialog. File name(s) selected are returned as the result. FileToURL Converts a fully qualified path and file name into a file type URL. Most of the Rexx Plug-in commands automatically do this conversion. This command is for those instances where the file type URL is needed or the command does not do the conversion automatically. GetFile Gets a file from the web server, transmitting the file as a compressed data stream. GetURL Gets a URL to a specified target. URL can be HTTP, FTP, etc. Target can be a browser window, file or the return value of the command. This command provides a way of displaying HTML in a browser window, or fetching files from a web or FTP server. GotFocus Indicates to the plug-in that the Rexx application has received a mouse click, or otherwise gotten the focus. This is used to help work-around a deficiency in how focus is handled in certain circumstances for Rexx applications running in separate session. JavaScript Executes JavaScript code on the browser. The JavaScript code is passed as a parameter to the command. You can direct the plug-in to create the HTML file containing the JavaScript on the client machine, or on the server. Creating the HTML file on the server allows you to communicate with other HTML files that have been downloaded from the server bypassing a Netscape security restriction that prevents JavaScript that originates from one domain from modifying or reading values of a document that comes from a different domain. Opera does not allow a JavaScript routine to read or modify values in a document from another window regardless of which domain it originated from. Link Establishes a link between the Rexx program and the plug-in, allowing the plug-in to control the Rexx program window, or send messages to the Rexx program. MoveFile Moves a file to a different location on the local hard drive, or renames a file on the local hard drive. OpenURL Opens the URL in a new browser window, optionally specifying window parameters such as size, etc. This command basically combines the OpenWindow and GetUrl commands into one. OpenWindow Opens the a new, empty, browser window. PostUrl Posts data to a URL, i.e. HTTP POST message. The URL is usually a CGI program that processes information included in the post message. This command provides a way of communicating with CGI programs on a web server. PmPrintf Outputs a string to the PmPrintf monitor. Used for debugging Rexx applications running in the plug-in. Query Returns information from plug-in variables, embed parameters, and information provided by the Rexx Plug-in. Reload Reloads the plug-in list in browser, making the browser recognize any newly added plug-ins. SayToWin Outputs text in the Rexx output window. This is used by Rexx programs running a separate window that want to send messages that appear in the Rexx output window. SayPrompt Outputs text in Rexx output window without a line break. Useful in conjunction with the Rexx PULL command to give a better looking prompt. Set Sets or changes the value of plug-in variables and browser/plug-in features. Most of the "reserved" EMBED parameters are also variables that can be set or changed by the Rexx program. TempFileName Creates a temporary file name, that by default is deleted when the plug-in instance terminates. WaitOnJS Causes the Rexx program to wait until it is released by another Rexx program or another plug-in with the ReleaseInstance EMBED parameter This is used when a Rexx program wants to display an HTML page and capture variables from that page.

Applications send commands to the plug-in with the Rexx function wdCommand(). This function sends a command to the plug-in and returns the result of the command to the Rexx program. The example program above shows how a Rexx programs sends commands to the plug-in.

Rexx Program Modifications

For Rexx programs that need to call Rexx Plug-in commands or get the values of EMBED parameters, the program needs to

• Call RxFuncAdd() and wdPluginLoad() to register the Rexx Plug-in functions, as shown below. call RxFuncAdd 'wdPluginLoad', 'wdPlugin', 'wdPluginLoad' call wdPluginLoad This is necessary only for those Rexx applications that run in a separate session; applications that run as a macro of the plug-in have the functions registered automatically. (Applications that run as a macro of the plug-in won't do any damage by registering the functions using wdPluginLoad(), because wdPluginLoad() is smart enough to know if it is being called by a macro program and to behave appropriately.)
• Call wdParseArgs() to convert the EMBED tag parameters into the Rexx variable wdEmbed. and to establish a communication link with the plug-in. GPF Rexx programs have to call this function in a slightly different manner than other Rexx programs.

Visual Rexx applications that run as applets on the HTML page have some design requirements dictated by being applets. The applet appears in the HTML page. It is assigned an area on the page that does not change in size, even when the browser window is re-sized. The applet/application window is controlled by the browser window: when the browser window is minimized the application window is minimize, when the browser window is moved the application window moves, etc. This means that the user interacts with the browser window controls to move, minimize and maximize the window, not application window controls. Finally, the application window should not terminate or close until the browser window closes.

What the application programmer has to do is:

• Remove sizing borders, the title bar, system menu, and the minimize and maximize buttons. Moving, minimizing and maximizing the application is handled through the browser window controls.
• Some applications may need to initially size their main window according to values contained in the Rexx stem variable wdMainArgs.name. However for most Rexx applications the sizing is automatically handled by the plug-in when the application links to the plug-in.
• Link to the plug-in using the link command, for example call wdCommand 'link drrexx' When the application "links" to the plug-in the plug-in takes care of synchronizing the application window to the browser window. The plug-in also removes the entry for the application in the window switch list to prevent the user from terminating the application apart from closing the browser window.
• Make sure the application can be re-sized. The plug-in needs to be able to size the application to the dimensions of the plug-in window area, as specified in the width and height parameters of the EMBED tag. For example, DrRexx applications must use a sizing border or must handle the size event.

Other than what is outlined above, the Rexx program is completely normal.

Packaging the Rexx Program

You then need to move the HTML file to where HTML files are located on your web server, and move the Rexx program file or files to the location pointed to by the SRC tag in your HTML file; usually this will also be in the html directory.

Normally the extension of the Rexx program file will be determined by the type of Rexx program it is:

*.CMD for command line type Rexx programs. *.RES for DrRexx programs. *.VRM and *.VRW for VX-Rexx programs. *.EXE for GPF programs.

You may run into restrictions on what file extensions you can use based on security settings for your web server. The most likely extensions that will cause you problems are *.CMD and *.EXE. For example the WarpDoctor site will not run files with a *.CMD extension.

If you have conflicts with an extension you have two choices:

1. Use an alternate extension. *.REX is an alternate extension for *.CMD for x-warpdoctor/cmdrexx and x-warpdoctor/rexx MIME-Types.
2. Zip the Rexx program file(s) and specify the zipped file as the SRC.

Zipping the file has the added advantage of shortening the download time.

Tools to Help Programming

Command Processor

Command Processor

Rexx Program Tester

Once you are satisfied with how the program executes you can click on the Create HTML button and the application will create HTML files or copy the HTML code to the clipboard for you.

Rexx Program Runner Screen

PmPrintf

The little code snippet and screen shot below shows how it works.

Cross Platform Compatibility

Rexx itself is very compatible between different operating systems and hardware platforms. But the Rexx language does not have any visual components as part of the language specification. In order to build graphical user interface type applications in Rexx you must use a library or application building tool that provides the interface between Rexx and the native graphics system on an operating system. On OS/2 there is a wealth of libraries and tools that are available. On Windows and Unix systems there are not nearly as many. For OS/2 and Windows there is MAID; for OS/2, Windows and Unix there is Rexx/TK.

While the Rexx Plug-in can be ported to different platforms, the Rexx programs that can be run by the plug-in will be limited to the support for Rexx provided by the platform.

Conclusion

Where to get it