WD Plug-in EMBED Parameters

The WarpDoctor Rexx plug-in is started by an EMBED tag in a page of HTML. The embed tag has many parameters that alter the appearance and operation of the Rexx program. For more information about using the EMBED tag and starting Rexx programs see Starting Rexx in the Programming Guide.

Parameters are divided into three categories:

  1. Those that influence how the plug-in is presented on the HTML page. These parameters are officially part of the HTML standard and can be found in any HTML reference manual, along with being listed below. We will call these HTML standard parameters.
  2. Those that alter the behavior of the plug-in. These parameters are specific to the Rexx plug-in and are listed below. All of these type parameters can also be set from the Rexx program with theSet command, unless otherwise noted in the table below. We will call these types of parameters plug-in standard.
  3. Any parameter that is not listed in either of the two tables. You can create any parameter you want and include it as part of the embed tag; that parameter and its value will be passed to the Rexx program. This provides a method for passing arguments to the Rexx program run by the plug-in. These types of parameters are called user defined parameters.

The embed parameters are available to Rexx programs two ways:

  1. The user added parameters are parsed into the Rexx stem variable wdEmbed. by the wdParseArgs() function. The wdEmbed. variable can then be used just like any other Rexx variable.
  2. All parameters can be queried by the Rexx program with the query parmvalue name command.

Note: parameter names are not case sensitive - however when parameters are copied into JSVAR variables by a MIME-Type x-warpdoctor/execute program the JSVAR variable name will be the same as the parameter name, including the case of the name, and JSVAR variable names are case sensitive.

The parameter values must be enclosed by quotes, either single or double quotes, if the value contains a space. Failure to do so will most likely cause the browser to crash when it attempts to run the program/plug-in instance. It is permissible to enclose all parameter values in quotes, even number values.

HTML Standard Parameters

These parameters control how the plug-in is presented on the HTML page.
Name Description
SRC url
URL of Rexx file to execute, or the install file for x-warpdoctor/warpin. 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. The plug-in will fetch the corresponding *.VRW file.

If the file you are specifying has been zipped, you must set the ZippedFlag=1 parameter to inform the plug-in that is must unzip the file. In addition the main part of the zipped file name - the part before the extension - must match the main part of the Rexx source file inside the zipped file. For example: the file drives.res must be zipped to a file named drives.zip or drives.zpp. It is recommended that the extension for zipped files not be .ZIP, but rather *.ZPP. This is because *.ZIP files have special mean to some browsers and using that extension for Rexx Plug-in files may cause problems.

If you specify a file type of URL, you must also specify a CgiURL parameter.

This value is available to Rexx programs with the Query SRC command, and converted to an integer value in the wdMainArgs.rexxRunType Rexx variable.

TYPE mime-type
MIME-Type of Rexx file. This must be one of the MIME-Types supported by the plug-in. The TYPE value tells the browser which plug-in to load for an EMBED tag, and it tells the plug-in which type of Rexx program is being executed.

This value is available to Rexx programs with the Query TYPE command.

HEIGHT n
Where n = height of window, in pixels. This value is available to Rexx programs in the Rexx stem variable wdMainArgs.winHeight and can be queried with the Query WinHeight command.
WIDTH n
Where n = width of window, in pixels. This value is available to Rexx programs in the Rexx stem variable wdMainArgs.winWidth and can be queried with the Query WinWidth command.
BORDER n
Where n = line size in pixels of the border.
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 program. The name is used in the ReleaseInstance name parameter and the ReleaseInstance name, Query instanceHandle name, and SendMessage name commands. Specifying a name allows those commands to find this instance by name, or to release this instance by name. The name is optional.

If you specify a name it must begin with a letter, and contain only letters, numbers, or an underscore, and it must not exceed 32 characters in length. Names greater than 32 characters are truncated to the 32 character limit. In addition the name must be unique for all the instantances that run at a single time. If more than one instance with the same name is running at a time, and you use any of the commands listed above, the first instance found with that name will be used.

ALIGN LEFT | RIGHT | TOP | BOTTOM
Alignment for the applet
FRAMEBORDER YES | NO
NO = frame has no border
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
If the plug-in is not installed this image is centered in the plug-in area.
When the user clicks on the image, the url specified in PluginsPage is loaded. This url should reference installation instructions for the plug-in. The URL used by the WarpDoctor site is http://www.warpdoctor.org/plugin_install.html. When the user has finished installing the plug-in they can reload the page (Ctrl-R) to start the Rexx program called out by the SRC parameter.

Earlier versions (builds) of the Opera browser do not recognize the PluginsPage parameter, although build 31 (beta 4) does recognize PluginsPage. To support all builds of Opera v 5.12 you need to use JavaScript to determine if the plug-in is installed. If the plug-in is not installed you can also use JavaScript to load the same URL you specify in the PluginsPage. The WarpDoctor site has a JavaScript function called checkPlugin(), available in the file http://www.warpdoctor.org/plugin_install.js which you can reference in your HTML files. This checks for the plug-in and calls the URL http://www.warpdoctor.org/plugin_install.html if the plug-in is not installed. You can use this for Opera browsers.

The example below shows an HTML page that uses both the PluginsPage parameter and JavaScript detection of the plug-in, so that it will function correctly with Netscape, Mozilla and Opera browsers. 

<html>
<script language="JavaScript" src="http://www.warpdoctor.org/plugin_install.js"></script>
<script>checkPlugin();</script>
<head>
<BODY bgcolor="white">
<br>
<h3>VX-Rexx Calculator</h3>
<embed
 type='x-warpdoctor/vxrexx'
 height=350
 width=450
 src='http://www.warpdoctor.org/calc.zpp'
 title='Calculator Sample Program'
 pluginspage='http://www.warpdoctor.org/plugin_install.html'
 zippedFlag=1
  >
</embed>
</body>
<html>

Plug-in Standard Parameters

These parameters have special meaning to the plug-in, as described in the table below.

Name Description
AutoCloseWindow YES | url | [#seconds#] text String

This parameter instructs the plug-in to close the current browser window, replace the current page with a URL, or replace the current page with a text string, when the session running the Rexx program terminates. This only applies to Rexx programs running in a separate session.

YES means close the current window when the Rexx program terminates. This should not be used when the current window is the main (only) browser window. Example:

autoCloseWindow="YES"

url means replace the current page with the url when the Rexx program terminates. Example:

autoCloseWindow="http://www.warpdoctor.org/newPage.html"

text string means replace the current page with the text string when the Rexx program terminates. If the optional #seconds# is included at the beginning of the text string the window, after displaying the text is automatically closed after the number of seconds. Example:

autoCloseWindow="Done with Program" autoCloseWindow="#10#Done with Program"

Default is blank - meaning the window and page are not closed or replaced when the program terminates.

This parameter cannot be set from the Rexx program, it can only be specified in the EMBED tag.

This parameter is available to Rexx programs with the Query ParmValue autoclosewindow command.

BGColor colorName | color hex value
Sets the background color of the Rexx output window, or if the output window is turned off the color of the rectangle in the plug-in area. The color can be set by specifying a color "name" or by specifying a RGB value in hexadecimal. Any value specified that does not match one of the color names is assumed to be a hexadecimal value. The hexadecimal values can be prefixed with a pound sign (#) which is how hex values are specified in HTML tags, or with a 0x prefix. The color names recognized are: BLACK, BLUE, GREEN, CYAN, RED, LIGHTRED, DARKRED, PINK, YELLOW, WHITE, DARKGRAY, and PALEGRAY. Please note that in many cases these color names do not produce the same color in the output window as it does in the bgcolor parameter of the <BODY> HTML tag. To match colors in the output window with the HTML document use hexadecimal values.

This value is available to Rexx programs with the Query BGColor command and can be changed from a Rexx program with the Set BGColor command.

CgiUrl url
Full URL to the wdPluginCgi.exe CGI program on the web server. The CgiURL value is set automatically by the plug-in. This parameter only needs to be used when
  1. You are specifying a file type of URL in SRC
  2. The CGI programs are located in a nonstandard location on the server
  3. When the plug-in incorrectly ascertains the URL of the wdPluginCgi.exe program.

This value is available to Rexx programs with the Query CGIURL command and can be set from a Rexx program with the Set CGIURL command.

CheckForDLLs filename [filename [filename ...]]
A list of one or more DLLs 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 DLLs in the list exist and can be loaded before attempting to run the Rexx program. If any of the DLLs are missing or cannot be loaded an error message box is displayed and the instance terminates. This is useful for insuring that the requisite DLLs exist on the client's hard drive before trying to run the program. Note that the plug-in automatically checks for standard required DLLs needed for the various Rexx runtimes. You only need to use this parameter if you need nonstandard DLLs. The standard DLLs are listed for each MIME-Type in the MIME-Types chapter.

This parameter cannot be be set with the plug-in Set command.

This parameter is available to Rexx programs with the Query ParmValue checkForDLLs command.

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 runtimes, see MIME-Types for which executable files are "standard". You only need to use this parameter if you need nonstandard executable files.

This parameter cannot be be set with the plug-in Set command.

This parameter is available to Rexx programs with the Query ParmValue checkForEXEs command.

CloseOnExit YES | NO
YES = Plug-in closes the Command Prompt window when Rexx program terminates (valid only for Cmd Rexx) Default=YES. (query by name)

Default = YES

This value is available to Rexx programs with the Query CloseOnExit command, and can be set from Rexx programs with the Set CloseOnExit command.

DebugPlugin 0 | 1 | 2 | 3 | 4
0 = turn off debug messages. Any value > 1 turns on debug messages in plug-in. A value of 1 loads the PmPrintf.dll. This parameter can be set and queried by Rexx programs, with the Query debugPlugin and Set debugPlugin commands.

Default = 0

EnableIPC YES | NO
YES = Other programs can query and set this program's JSVAR variables and query this programs instance start-up arguments. The default = YES. Setting this parameter to NO will prevent other programs from setting and reading variables in this instance.

Default = YES This parameter can be set and queried by Rexx programs, with the Query enableIPC and Set enableIPC commands.

EraseOnExit YES | NO
YES means the file specified in the SRC parameter is erased when the plug-in instance is destroyed. If that file is a VX-Rexx *.VRM file then the corresponding *.VRW file is also erased. If the file specified is a zipped archive file then archive file is erased but not the contents extracted from the archive file. (The program file extracted from the zipped archive is automatically erased by the plug-in when the instance terminates, but any other files in the archive are not automatically erased.)

Default = NO This parameter can be set and queried by Rexx programs, with the Query eraseOnExit and Set eraseOnExit commands.

ExitMessage message
This parameter sends the message to the instance specified in the ReleaseInstance parameter when the instance terminates. The SendMessage parameter can also be specified when using this parameter, if you want to send a message when the instance first starts, i.e. when the page containing the instance loads in the browser.

This parameter provides a simple way to notify another instance when a page being displayed by the browser is destroyed. Since there is no other "hook" available for a plug-in program to use to find out when a page is destroyed, you can use this parameter in an EMBED tag that you place on the page you want to monitor.

See ReleaseInstance for restrictions and details.

This parameter cannot be be set with the plug-in Set command and cannot be queried with the Query ParmValue savePrompt command.

FGColor colorName | color hex value
Sets the foreground or text color of the Rexx output window. The color can be set by specifying a color "name" or by specifying a RGB value in hexadecimal. Any value specified that does not match one of the color names is assumed to be a hexadecimal value. The hexadecimal values can be prefixed with a pound sign (#) which is how hex values are specified in HTML tags, or with a 0x prefix. The color names recognized are: BLACK, BLUE, GREEN, CYAN, RED, LIGHTRED, DARKRED, PINK, YELLOW, WHITE, DARKGRAY, and PALEGRAY. Please note that in many cases these color names do not produce the same color in the output window as it does in the bgcolor parameter of the BODY HTML tag. To match colors in the output window with the HTML document use hexadecimal values.

This parameter can be set and queried by Rexx programs, with the Query FGColor and Set FGColor commands.

GenericArgsFlag 0 | 1 | 2 | 3
Determines how arguments are passed to the program started by the plug-in, when type=x-warpdoctor/generic

0 = Default. User defined parameters of the EMBEDtag are passed as name = value . If there are no user defined parameters then no arguments are passed to the program.

1 = User defined parameters of the EMBEDtag are passed as value . If there are no user defined parameters then no arguments are passed to the program. 1 is the same as 0 except only the values are passed.

2 = Parameters are passed to the program in the same manner as when running one of the Rexx MIME-Types. This allows a Rexx applications such as VX-Rexx and DrRexx to be packaged as an executable file and run by the plug-in. It may also provide for running Rexx applications not specifically supported by the plug-in such as MAID or VisPro-Rexx. When running a Rexx application as an executable file the TYPE parameter must be set to x-warpdoctor/generic and GenericArgsFlag=2. The settings needed for the plug-in "environment" are passed in one argument as an encoded string that is decoded in the Rexx program by the wdParseArgs() function.

3 = Is used for non-Rexx programs that run in the plug-in and want to communicate with the plug-in. The arguments passed to the program are: 

pipeName  x-desktop  y-desktop  width  height   x-window  y-window
where
pipeName Is the name of the "command" named pipe, the pipe used by the plug-in Rexx function wdCommand() for communicating with the plug-in
x-desktop The lower left position of the plug-in window relative to the desktop, in pixels.
y-desktop The lower left position of the plug-in window relative to the desktop, in pixels.
width The width of the plug-in window in pixels.
height The height of the plug-in window in pixels.
x-window The lower left position of the plug-in window relative to the browser window containing the page that has the plug-in instance, in pixels.
y-window The lower left position of the plug-in window relative to the browser window containing the page that has the plug-in instance, in pixels.
The program uses the x-desktop, y-desktop, height and width arguments to size its window to fit the plug-in area/window. The program uses the pipeName argument to open the client end of a named pipe to send commands to the plug-in.

This parameter cannot be be set with the plug-in Set command, but can be queried with the Query ParmValue genericArgsFlag command.

MakeNameSame YES | NO
YES forces the name of the downloaded Rexx program, or WarpIN install file, to be the same as the name of the file on the sever, i.e. the name in the SRC parameter. NO means the downloaded file name is a random name.

Default = NO for all programs except x-warpdoctor/warpin, which has a default of YES.

This parameter cannot be be set with the plug-in Set command, but can be queried with the Query ParmValue makeNameSame command.

PluginTitle title text
Title that appears in windows and dialog boxes.

Default = WarpDoctor Rexx Plug-in

This parameter can be set and queried by Rexx programs, with the Query pluginTitle and Set pluginTitle commands.

PullAsPrompt 0 | 1 | 2 | YES | NO
1 or 2 = display the prompt dialog box for getting user input instead of the normal PULL processing. 2 outputs the last SAY statement as the title for the prompt dialog, 1 uses the default title (INPUT).
0 = solicit input from use through the Rexx output window (the MLE).
YES is equivalent to 1, NO is equivalent to 0. This parameter only affects Rexx programs running as MIME-Type x-warpdoctor/rexx. See the Prompt command for more information about the prompt dialog and prompting.

Default = NO

This parameter can be set and queried by Rexx programs, with the Query pullAsPrompt and Set pullAsPrompt commands.

ReleaseInstance instanceHandle | name
where
instanceHandle is the handle for the instance to be released
name is the name of the for the instance to be released.

This parameter is used for two purposes

  1. Sending a message to Rexx program running in another instance,
  2. Releasing a plug-in instance (a waiting Rexx program) that has been paused with the WaitOnJS command.

Either of the two actions specified above can happen, but not both. Meaning that when using the ReleaseInstance parameter you can either send messsage(s) to another program running in a difference instance, or you can set JSVAR variables in a program running in another instance, but you cannot do both.

This parameter must be used with the MIME-Type of x-warpdoctor/execute and cannot have a SRC parameter specified.

What happens to the instance when this parameter is used depends on whether the sendMessage/ExitMessage parameter have also been specified. If either the sendMessage or ExitMessage parameter is also specified then

  1. The plug-in sends the message specified in the SendMessage parameter to the instance specified in the ReleaseInstance.
  2. If an ExitMessage has also been specified the instance waits until it is terminated. When terminated the instance sends the message specified in the ExitMessage parameter.
  3. If no ExitMessage parameter has been specified then the instance terminates

If neither a SendMessage nor an ExitMessage has been specified then on instance startup the plug-in:

  1. Deletes (drops) all pre-existing JSVar variables in the instanceHandle.
  2. Copies all the user defined EMBED parameters to equivalent JSVar variables for the instanceHandle
  3. Releases the waiting Rexx program running in the instanceHandle plug-in instance.
  4. Terminates the x-warpdoctor/execute instance.

The Rexx program in instanceHandle, then uses the Query JSVar command to retrieve the values of the JSVar variables set by the x-warpdoctor/execute program.

This parameter cannot be be set with the plug-in Set command. However there is a ReleaseInstance plug-in command which is intended for Rexx programs release other running Rexx programs.

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.

This parameter cannot be be set with the plug-in Set command, but can be queried with the Query rexxOutputWindow command.

Default = YES for x-warpdoctor/rexx, x-warpdoctor/cmdrexx, NO for all other MIME-Types

RunExclusive YES | urlList
Prevents two instances of the same program from running at the same time, or other programs from running while this program is running. A value or YES prevents two copies of this program from running at the same time. If a urlList is entered all the programs in the urlList are prevented from running while this program is running. The urlList can contain one or more entries separated by a space. If the entry is not a fully qualified URL then the SiteURL is prefixed to the entry to make it a fully qualified entry. Examples: RunExclusive=YES RunExclusive='http:\\www.warpdoctor.org\calcprog.zpp http:\\www.warpdoctor.org\drives.res' RunExclusive='calcprog.zpp drives.res'

In the examples above the second line and the third line are equivalent if the SRC program is running from the site http:\\www.warpdoctor.org. There is a maximum number of 64 entries at a time in the exclusive list.

Note: the URL you enter into the RunExlusive list is the URL for the Rexx program, not the URL of the HTML page containing the EMBED tag that starts the program.

Entries can be added to the RunExclusive list by the Rexx program while it is running with the Set RunExclusive command. Entries can also be dropped from the list with the Drop RunExclusive command.

Default = blank (NO)

SavePrompt title
If this parameter is present, a Save As type file dialog is presented to the user after the SRC file is downloaded but before the program is executed. The title text appears in the title-bar of the file dialog. Although this parameter can be used with any MIME-Type it is intended for use with the x-warpdoctor/warpin MIME-Type to allow the user to save the WarpIN archive file to some known name and location on his hard drive before running the installation. This allows the user to keep a copy of the and run the install in one step. Without the file dialog prompt the download file is placed in the browser's cache and deleted when the cache is cleaned, or when the instance is terminated if the EraseOnExit parameter is set.

This parameter cannot be be set with the plug-in Set command but can be queried with the Query ParmValue savePrompt command.

Default = NO

SendMessage message
This parameter sends the message to the instance specified in the ReleaseInstance parameter. The message is sent when the instance starts. If an exitMessage is also specified then the instance passively waits until it is terminated. If no exitMessage is specified the instance terminates immediately after sending the message .

See ReleaseInstance for restrictions and details.

This parameter cannot be be set with the plug-in Set command and cannot be queried with the Query ParmValue savePrompt command.

ShutDownDelay milliseconds
The number of milliseconds the plug-in waits when destroying an instance before terminating the session a Rexx program is running in. This only pertains to Rexx programs that run in a separate session. The default is 0 unless the program issues the link messagepipe command; then the default becomes 250 (1/4 second). If a Rexx program has a number of resources that need to be freed and which take some time to free, it should adjust the value to give itself enough time to free the resources. The maximum time allowed is 15,000 - 15 seconds.

This parameter can be set and queried by Rexx programs, with the Query shutDownDelay and Set shutDownDelay commands.

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.

Default = YES

This parameter can be set and queried by Rexx programs, with the Query stripTrailingBlanks and Set stripTrailingBlanks commands.

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.

Default = 30,000 - 30 seconds.

This parameter can be set and queried by Rexx programs, with the Query timeOutServer and Set timeOutServer commands.

TimeoutValue milliseconds
The amount of time, in milliseconds, to wait for commands and functions to complete before declaring an error.

Default = 10,000 - 10 seconds.

This parameter can be set and queried by Rexx programs, with the Query timeOutValue and Set timeOutValue commands.

Title title text
The title is useful in two situations:
  1. When the user's security setting causes the plug-in to prompt the user for permission to run the program. The title text appears in the prompt dialog box to help identify the program that is being requested to run.
  2. When cooperating Rexx programs are running, each in its own plug-in instance, the title provides a way for the programs to "find each other" so that they can communicate. A Rexx program must use an instance handle to communicate with another Rexx program running in the plug-in. The instance handle is not known until run time. A Rexx program can use the title to find the instance handle of another program by querying the titles for all the running instances until it finds the title for the program it is looking for.

Please note that the Title is different from the PluginTitle. The PluginTitle identifies the plug-in to the user. The default value for the pluginTitle is WarpDoctor Rexx Plug-in. The Title identifies the Rexx program to the user.

The Title cannot be set in a Rexx program but it can be queried with the Query title command.

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. If you specify the name of a window and that window does not exist it will be created when needed.

The WorkWindowName parameter provides a means for you to hide the window(s) used by the plug-in when it issues JavaScript commands. You do this by creating a window that is sized so small the user cannot see what happens in the window, and passing the name of that window to the WorkWindowName parameter.

This parameter can be set from a Rexx program, and queried with the Query workWindowName commands. on WorkWindowName.

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 that matches the name of the zipped file. See Compressing Rexx Sources for more information.

This parameter cannot be be set with the plug-in Set command, but can be queried with the Query parmvalue zippedflag command.

Default = NO

User Defined Parameters

The user or programmer can create addition parameters not listed in the tables above which are called User Defined Parameters. All parameters of the EMBED tag are passed to the Rexx program. User defined parameters, meaning parameters not listed in the tables above, are also parsed into the Rexx stem variable wdEmbed. when the Rexx plug-in environment is initialized by the Rexx program.

The value for any single parameter you create cannot exceed 4096 characters, and the total size of all the parameters you create, both names and values, cannot exceed 64K.