This chapter lists the plug-in commands recognized by the Rexx Plug-in. All commands are issued using the wdCommand() Rexx function. Many of the commands take arguments. The arguments can be specified in wdCommand() by separating each argument with a comma, or by stringing the arguments together into one string, each argument separated by a space. The three examples below all show acceptable ways of calling wdCommand().
call wdCommand command , arg1, arg2 call wdCommand command||arg1, arg2 call wdCommand command||arg1||arg2
If your Rexx program is multithreaded commands can be issued from any thread in the Rexx program. However each thread must have the plug-in Rexx "environment" created in that thread, see wdExposeArgs() for details.
Every command returns a value. Unless otherwise noted, if the first character of the
return return value is # a failure or error has occurred.
Adds a file name to a list of files that are delete when the plug-in instance terminates.
addToDeleteList fileName
filename is the file to be added to the list
Adding a file name to the list will insure that the file is deleted when the plug-in instance is terminated. The file does not have to exist when it is added to the list, or when the plug-in instance terminates.
Appends the contents of one file to another
appendFile targetFile, sourceFile
sourceFile is the file you want to copy.
targetFile is the file you want to append to.
AppendFile appends the contents of the sourceFile to the target file, if the file exists. If the target file does not exist it is created. the CopyFile command for replacing a existing file with the source file.
rc = wdCommand('appendfile c:\os2\dll\wdPlugin.dll e:\temp\wdPlugin.dll')
Closes a browser window
CloseWindow [windowName]
windowName is the name of the window that is to be closed. Window names are case sensitive. If a window name is not specified the window containing the current plug-in instance will be closed, which will terminate the plug-in instance and the program that it is running.
You can only close windows that have been created with a name, or your own window. If the named window you specify is not open when you call CloseWindow, the window will be opened briefly before it is closed. See the OpenWindow command for information about window names.
This command uses a work window to perform its task. See the WorkWindowName parameter for information about work windows.
Copies a file to a new name or location.
copyFile targetFile, sourceFile [, OVERWRITE]
sourceFile is the file you want to copy.
targetFile is the new name to give to the file.
The OVERWRITE parameter means that if the targetFile already existed it would be overwritten. If the OVERWRITE parameter is not specified and the target file already exists, an error is returned.
The copy completely replaces any existing target file, if the target file exists, Use the AppendFile command for appending one file to another.
Copies or uploads a file to a FTP server.
Syntax
CopyFileToServer [ SYNC | ASYNC ,] url , filename
SYNC means do not return from command until the file is uploaded. This the default. SYNC can also be specified as WAIT
ASYNC means the command returns immediately after starting the upload, but before the upload is complete. If you specify ASYNC you will have no way of knowing if the file transfer completed successfully without checking for the file on the FTP server. ASYNC can also be specified as NOWAIT.
url is the URL of an FTP server that will accept the file. If the URL contains spaces it must be encoded using the EncodeURL command.
filename is the fully qualified name of the local file you want to copy to the FTP server.
This command only works with Netscape. It does not work with Opera, Mozilla, or any of the IBM Web Browsers; none of those browsers implement the FTP upload correctly. If you want to upload from your Rexx program while running in Opera, Mozilla or IBM Web Browser you must use the Rexx FTP package. An example program is shown in the Examples below.
The URL can include a user name and password in the URL. The syntax is
ftp://userName:password@IPAddressfor example
ftp://dgclark:whoaNelle@192.168.32.100where dgclark is the user name and whoaNelle is the password.
fileName is the fully qualified file name to be uploaded.
The file will have the same name on the FTP server as it has on the local hard drive. If you want to upload the file and specify a different name on the server you can:
You can use the TempFileName command to create a name that should be unique on the FTP server. The name can be created so that it includes your IP address as it appears to the web server, well as some random characters in the name.
The original file remains on the local hard drive after the upload is complete. Use the MoveFileToServer command to remove the local file after the upload is complete.
/* upload a file */
call wdParseArgs
fileName = 'f:\temp\a.cmd'
rc = wdCommand('movefiletoserver ftp://uploadUser:uploadPassword@www.hometown.org',fileName)
say 'rc: ' rc
exit
/* rexx ftp upload */
call wdParseArgs
rc = rxFuncAdd('FTPLoadFuncs','rxFtp','FtpLoadFuncs')
say 'register Funcs rc: ' rc
rc = FtpLoadFuncs()
say 'LoadFuncs rc: ' rc
rc = ftpsetuser('www.hometown.org','uploadUser','uploadPassword');
say 'set user rc: ' rc
rc = ftpput("f:\temp\a.cmd",a.cmd,"BINARY");
say 'ftp put rc: ' rc '
say 'ftperrorno: ' ftperrno
say 'rc: ' rc
exit
Creates and displays a new HTML page from the text you supply. The text is bracketed with the <:html>:<:body>: and <:/body><:/html> tags
createPage target, autoclose, text
target is one of the following
| _blank | The page is opened in a new, blank window |
| _self | The page is opened in the same window the plug-in occupies. If this refers to the window containing the instance that issued the command, the instance will be destroyed - something you probably don't want to do. |
| _parent | The page is opened the immediate FRAMESET parent of the current window. If the plug-in instance document has no parent the default is _self |
| _top | The page is displayed in the top window of chain of nested windows. |
| name | The page is displayed in the named window, replacing whatever is currently being displayed in that window. See OpenWindow for opening named windows. |
Autoclose is an integer value indicating the number of seconds the window should remain open before automatically closing. Zero means the window will not automatically close.
text is text displayed in the window, including HTML tags if you wish.
CreatePage creates an HTML page and displays it in an already open browser window. If you want to display the page in a new window use OpenWindow to open a new "named" window and then use that name as the target to CreatePage.
The text you supply is bracketed with the <html><body> and </body></html> tags, meaning those are generated for you automatically by this command.
This command uses a work window to perform its task. See the WorkWindowName parameter for information about work windows.
Deletes a local file.
deleteFile fileName
fileName is the name of the file to delete.
This command deletes a local file from the client's system. You can also accomplish the same thing in most Rexx programs using the statement
'delete fileName'The difference are:
Drops one or all JSVar variables, or one or all entries in the RunExclusive list for this plug-in instance.
drop JSVAR name | ALL
drop RUNEXCLUSIVE url | ALL
JSVAR name drops the single variable name. Names are case sensitive.
JSVAR ALL drops all the JSVar variables.
RUNEXCLUSIVE url drops the url entry in the RunExclusive list added by this program. If the URL is not fully qualified it will be prefixed with the SiteURL to make a fully qualified URL. URL entries are not case sensitive.
RUNEXCLUSIVE ALL drops or deletes all the entries in the list for this plug-in instance.
This command drops or deletes JSVar variables and entries in the RunExclusive list.
JSVar variables are
variables managed by the Rexx Plug-in. There can be a maximum of 64
variables. Each variable can store any value of any length.
JSVar variables are created by the Set
JSVar command, or by a plug-in instance running a MIME-Type of
x-warpdoctor/execute which copies EMBED parameters
into JSVar variables.
The RunExclusive list is a list of programs that are not allowed to run. Entries are put into the list by the RunExclusive embed parameter and by the Set RunExclusive command. Entries are deleted from the list by the DROP command, and all entries added by a plug-in instance are automatically deleted when the instance terminates.
If is possible for two different Rexx programs to list the same url in their RunExlusive parameters. When that happens the program listed will not be allowed to run after its entry is "dropped", until all entries for the program are deleted from the list, i.e. until both Rexx programs drop the entry from the list or terminate.
Drops a file name from the delete list
dropFromDeleteList index
This command deletes the file and drops the entry in the delete list - the list of files that will be deleted when the plug-in instance terminates. The entry is indentified by the index number returned when the entry was added to the delete list with AddToDeleteList. If the file exists it is deleted before being removed from the list. If the file does not exist, no error is returned.
Encodes a URL
encodeUrl url
url is the url or fully qualified path and file name to encode.
This command encodes a URL so that any non-printable characters outside of the lower 128 ASCII characters are encodes. It also converts a fully qualified file name into a file type URL.
A URL must be encode before being passed as an argument when the URL contains spaces.
URLs containing a percent sign (%) are not encoded. Those must be manually encoded by you.
The commands GetURL and OpenURL automatically encode the URL so EncodeURL is not needed when using the GetURL or OpenURL commands unless the URL contains a space. Then is must be encoded before being passed as an argument to those commands. a file for those commands, unless the file name contains a space.
The file name must be fully qualified with the drive and full path included.
Executes a program, returning the program's return code as the result.
execprog SYNC | ASYNC , programName , [parameters ]
SYNC = command does not return until program is finished executing.
ASYN = command returns immediately after starting program.
programName is the name of the program to run. The program name must include the extension. See remarks.
parameters are any optional parameters to be passed to the program.
The program must either be fully qualified or the program must reside on the PATH.
If the program name is not fully qualified the path is searched for the program before executing.
The extension of the program must be specified as part of the program name, e.g. gzip.exe is ok, while
gzip will return an error for program not found.
The return from this command is the return code from the program that is executed. In order for the return value to be meaningful to you, you must be aware of the return codes that can be returned by the program you are executing. Most programs return 0 to indicate a successful execution, and some other value to indicate an error.
Opens a file dialog, returns the selected file(s) or directory.
fileDialog flags [,okButtonText ,fileSpec ,title ]
fileSpec is the filter to use for selecting which files appear in the file list part of the dialog box.
flags You can specify more than one flag. Flags are specified by the first character of the flag name only, meaning for example O for OPEN, E for ENABLEFILELB, etc.
| Name | Description |
|---|---|
| OPEN | The file dialog is a OPEN file dialog |
| SAVEAS | The file dialog is a SAVEAS file dialog |
| MULTIPLESEL | Multiple files may be selected. Default is a single select |
| ENABLEFILELB | Enables the file list part of the dialog box when the file dialog is a SAVEAS type. This allows the user to select a pre-existing file name from the list. The file list is disabled by default for SAVEAS types of dialogs. |
| VOLINFO | If this flag is set, the dialog will preload the volume information for the drives and will preset the current default directory for each drive. The default behavior is for the volume label to be blank and the initial directory will be the root directory for each drive. |
| DESKTOP | Specifies that the desktop is to be parent for the file dialog. This is the default. When the desktop is the parent the file dialog is centered on the desktop when it is opened. |
| PLUGIN | Specifies that the plug-in window is to be the parent of the file dialog. When the file dialog opens it is centered over, and sized to fit the plug-in window. |
okButtonText is the text that appears on the OK button, the button that accepts the input from the dialog box. Any spaces the text must be changed to a plus sign (+), for example: SAVE AS should be SAVE+AS
fileSpec is the name of a file that is to appear in the file dialog box, or a file filter. The simple file name can be replaced with a string filter, such as *.DAT. When the dialog is invoked, all drive and path information is stripped from the entry and moved to the corresponding fields in the dialog. When a file name is specified, the Files list box is scrolled to the matching file name. When there is no exact match, the closest match is used. When a string filter is specified, the dialog is initially refreshed using the results of this filter. After the dialog is initially shown, the string filter remains in the file name field until a file is selected, or the user overtypes the value.
title The title for the dialog box.
This command presents a standard operating system file dialog box. The number of files that can be selected is determined by the FLAGS you specify: a FLAG of M for MULTIPLESEL enables more than one file to be selected. If M is not specified as a flag, which is the default, only one file can be selected.
The fileSpec parameter can be used to select the initial drive that is displayed in the file dialog box, along with specifying a filter to restrict the names of the files displayed. For example a fileSpec of
If the dialog box can be displayed, the return consists of 4 strings
| String | Description |
|---|---|
| 1 | Button pressed. 1 = OK, 2 = CANCEL |
| 2 | Number of files selected |
| 3 | Separate character |
| 4 | File name(s) |
If you specified a MULTLIPLESEL type of file dialog, where the user can select more than one file, the file names are returned in an encoded string, with each file name separated by the separater character (string 3 in the return string).
The file names always start at character position 10, so you can use
This produces the output shown below
Returns the value of a cookie.
getCookie cookieName
cookieName is the name of the cookie to retrieve. Cookie names are case sensitive.
Returns the value of the cookie name specified in the commands. Only cookies set in (HOST) domain are visible.
Use the SetCookie command to
create or update a cookie from Rexx. Use the
document.cookie() JavaScript method to set a cookie
within a JavaScript program.
Gets a file from the web server.
getfile url, target
url is an HTTP URL. FTP URLs will not work.
target is the path/name the file is to have on the client machine.
This command retrieves files from a web server, based on the path and name of the file on the server. The web server compresses the file and sends it as a compressed data stream which is decompressed by the browser before the command returns. The file is transferred using HTTP.
GetFile will reliably download binary information where GetURL will not when using HTTP to transfer the file.
call RxFuncAdd 'SysBootDrive', 'REXXUTIL', 'SysBootDrive'
rc = wdCommand('getfile http:\\www.warpdoctor.org\files\vrobj.dll '||sysBootDrive()||"\os2\dll\VROBJ.DLL")
Gets a URL to the target specified.
getUrl url [,target] [, NOWAIT | fileName]
url is the URL you want to get. If the URL contains spaces it must be encoded with the EncodeURL command.
Target is one of the following
| _blank | The URL is opened in a new, blank window |
| _self | The URL is opened in the same window the plug-in occupies. If this refers to the window containing the instance that issued the command, the instance will be destroyed - something you probably don't want to do. |
| _parent | The URL is opened to the immediate FRAMESET parent of the current window. If the plug-in instance document has no parent the default is _self |
| _top | The URL is displayed in the top window of chain of nested windows. |
| _file | The URL is to be downloaded to a file. |
| _result | The URL is returned in the RESULT Rexx variable, i.e. the return result from the
wdCommand(). The maximum size that can be returned as a result is 64k. If
the URL is larger than that it will be truncated to the first 64K.
|
| name | The page is displayed in the named window, replacing whatever is currently being displayed in that window. See OpenWindow for opening named windows. |
NOWAIT means control returns immediately to the Rexx program before the URL is actually received on the client machine. If you specify NOWAIT you have no way of knowing whether the URL was successfully gotten on not.
fileName is the name you want to use for the file when you have specified _file as the target. If you do not specify a filename one is generated for you automatically and the file is placed in the browser cache.
This command "gets" a URL and returns it to the target specified. The URL can be
any type including HTTP , FTP, news, mailto, or gopher.
The target must match the type of URL, for example _file is not appropriate for mailto
type URLs.
The
default target is new blank window. If you want to send the URL to an existing window use
the OpenWindow command first to open the window, then use
the name supplied on the OpenWindow command as the target in the GetUrl command.
When you use _file as a target with an FTP type URL this command can be used to download files from an FTP server. If you specify an HTTP URL and _file as the target the URL is downloaded to a file. Note that binary files downloaded as HTTP URLs do not download reliably: the file sometimes is corrupted by the download.
When downloading to a file the status or progress messages displayed is depended on the type of browser being used.
If you want to get the results from executing a CGI program on the server, use PostUrl.
Even though the GetURL command is synchronous unless the NOWAIT argument is specified, browsers are usually heavily multithreaded and the browser window might not be finished initializing itself when the command returns. If the next Rexx statement after GetURL does something with the window, such as issuing a JavaScript command against that window, you should pause the Rexx program for a second or two after the GetURL to give the window a chance to finish initialization. You can use the SysSleep() function from the RexxUtil package the comes with Rexx to pause a Rexx program.
Example
This above example gets the file sample.zip from the download directory relative to the directory connected to when connecting to the FTP server 192.168.32.100. The user ID dgclark and password raininspain are included as part of the FTP URL.
The above example displays the xhome.html page in a new window - the default target.
The above example returns the contents of the file xhome.html in the Rexx variable fileString.
Indicates to the plug-in that the Rexx application window has received a focus message.
Syntax
GotFocus
This helps cure the behavior where the browser window containing the plug-in/Rexx GUI application is partly obscured by another window, and the user clicks on the Rexx GUI application and it does not rise to the top of the window stack (the window z-order). Normally the expectation is that by clicking on the Rexx GUI application it will rise to the top of the windows, i.e. it will rise above the window that was partly obscuring it. Note that if the user clicks directly on the browser window everything works fine; it is only when the user clicks on the Rexx GUI application within the browser window that the problem occurs.
Linked Rexx GUI applications that run in a separate session do not share the PMwindow procedure used by the plug-in and the browser - because they are running in a separate session. Therefor when the Rexx application window receives a focus message the plug-in needs to be notified. When the plug-in receives the GotFocus command it causes the browser window containing the plug-in to get focus, which moves the Rexx application to the top of the window stack. The unfortunate side-effect of this is that the browser window gets the focus and so the user must click once again in the Rexx window to put the focus where he wants it.
call wdCommand 'gotfocus'
Executes JavaScript commands or code.
Syntax
javascript LOCAL | HOST | url , code
| LOCAL | means the JavaScript code will be executed from the local hard drive, |
| HOST | means that the JavaScript code will be executed from the server, as defined by the CgiURL variable. If the CgiURL variable points to the wrong host or is not present, you must specify a URL, |
| url | is a full URL of the wdPluginCGI.exe program that will execute the JavaScript code.
The URL must contain the wdPluginCgi.exe program, e.g. http://mydomain/cgi-bin/wdPlugincgi.exe
|
code can equal one or more lines of JavaScript code. Multiple lines of JavaScript code must be separated by semicolons.
The maximum size of a JavaScript command string is 1024 characters for Mozilla and Netscape browsers. This is a browser limitation, the plug-in will handle strings of up to 64K in size.
The JavaScript command is not fully synchronous, the command returns when the window is opened, but the JavaScript code execution may not be complete.
JavaScript is segregated into domains for security reasons. JavaScript code running on one domain cannot communicate (set variables, execute functions, etc.) with JavaScript code running in another domain. On some browsers like Opera, the security restriction is even tighter: JavaScript executing in one window cannot communicate with JavaScript executing in another window even if both windows come from the same domain. The executionLocation argument allows you to specify which domain the JavaScript code you supply to the JavaScript command will execute in. Since cookies are also segregated into domains the same restriction applies: JavaScript executing in one domain will not see cookies set in another domain. You can however, use cookies to pass values between JavaScript programs running in two different windows on the same domain, which provides a workaround for the Opera restrictions.
In order to set JavaScript or HTML variables, or to execute a JavaScript function
you must know the name of the window
that contains the variables or the JavaScript function. The easiest way to know the window name
is to open the page with the OpenURL or OpenWindow
and specify a window name. Then you need to create a JavaScript object for that window, using the JavaScript
window.open() method, passing in the name of the window you want to the reference to.
For example, if you want to execute a JavaScript function
doThis() contained on the page SomeFunction.html you would:
This first line opens the page SomeFunction.html assigning the name fred
to the window containing the page. The second line creates a JS object, here named xx, that
points to the window, and uses that object to get to the
doThis() function.
Establishes a link between the Rexx application and the plug-in.
Syntax
Link linkType [,handle]
linkType is one of the following
| linkType | Description |
|---|---|
| DRREXX | Links DrRexx applications |
| GPF | Links GPF Rexx applications |
| MessagePipe | "Links" the Rexx application to the plug-in using a "message" named pipe. The plug-in sends messages through the pipe to the Rexx application informing the application of significant window/GUI type events. The application uses the wdOpenPipe() and wdReadPipe() to read the messages sent by the plug-in. Usually this needs to be done on a secondary thread since the messages can come at any time. It is the Rexx application's responsibility to respond appropriately to those messages. |
| VXREXX handle | Links VX-Rexx applications running either as macros or in a separate session. The handle must be supplied as a base 10 ASCII value. | VX-REXX handle | Same as VXREXX |
| WindowMessage | The plug-in sends PM window messages to the Rexx GUI window to simulate parent-child relationship. This is used when DRREXX, VXREXX, VX-REXX, or GPF will not work, e.g when the Rexx GUI app has multiple windows open at the time it issues the LINK command, or when the plug-in cannot correctly determine the window handle. |
| FindHandle | The plug-in searches all desktop windows for a window with the same PID number as the PID assigned to the program when started by the plug-in. This link method is intended for non-Rexx "generic" type executable programs. |
| Handle handle | Establishes a link based on the handle of the main window passed as the argument. The handle must be a ASCII value in base 10. This link method is intended for non-Rexx "generic" type executable programs. |
The Link command
or
The DRREXX, GPF, VXREXX, VX-REXX, FINDHANDLE and HANDLE linkTypes are mutually exclusive and link the application as an applet to the plug-in. The MESSAGEPIPE linkType starts the plug-in side of the message pipe and can be used regardless of whether the application is or is not already linked to the plug-in as an applet.
If the Rexx application or program is not running as an applet, meaning that it is not appearing in the plug-in window on the page, then it does not need to link to the plug-in.
Linking the Rexx application to the plug-in as an applet allows the plug-in to control the application's main window so that it remains synchronized to the plug-in area on the HTML page. When linked as an applet, the plug-in minimizes the Rexx application window when the browser window is minimized, moves the Rexx application window when the browser window is moved, etc.
The linkType MESSAGEPIPE can use used in combination with any other linkType. The MESSAGEPIPE linkType argument starts the message pipe on the plug-in side. The Rexx program must then open the message pipe on its end with the wdOpenPipe() function. After opening the message pipe the Rexx program reads the messages from the message pipe in a loop, using the wdReadPipe() function. When a message pipe is opened the plug-in sends "messages" to the Rexx application for "events" that happen to the plug-in and the plug-in area/window. These messages allow the Rexx application to synchronize itself to the plug-in area, if it has not also linked to the plug-in using one of the other linkTypes, and they give the Rexx application notice of when it is about to be terminated by the plug-in. The "message" consists of a single letter, plus parameters. The parameters for most of the messages are the location of the lower left corner of the plug-in area/window relative to the desktop. The parameters are separated from the message by a space.
The message pipe can also be used for communication between Rexx programs running in different plug-in instances. The user defined message is the single letter Z followed by an option parameter. A Rexx program sends a user defined message to another Rexx program with with SendMessage command. The message can be any text string up to 250 characters, and appears as the parameter of the user defined message.
| Message | Description |
|---|---|
| H x y | Hide window |
| M x y | Move window |
| P x y | Paint |
| R x y | Mouse move (rodent) |
| S x y | Show |
| X | Terminate application. The plug-in instance is being destroyed |
| Z | User defined message |
Sends a mail message
Syntax
MailTo address ,message
address is the e-mail address of the recipient.
message is the text for the body of the message.
This command sends an email message using the the browser's setting for the outgoing server and originator. The browser must support email. Currently this does not work on Opera 5.12 and any Mozilla based browsers up to and including v 1.2 or IBM browser version 2.0: Opera does not support email, and the Mozilla/IBM browsers have a bug in their implementation of the command.
The subject of the message is always NULL
rc = wdCommand('mailto auntRuth@aol.com Howdy aunt Ruth - how's going?')
MessageBox displays a message box, the same function as RxMessageBox in RexxUtil functions, except the MessageBox command can be used by Rexx programs running in a Command Prompt window where the RxMessageBox() function cannot.
Syntax
MessageBox buttons[+icon+default+mobility+mobility] , messageText
| Buttons | |
|---|---|
| OK | Message box contains an OK push button. |
| OKCANCEL | Message box contains both OK and CANCEL push buttons. |
| CANCEL | Message box contains a CANCEL push button. |
| ENTER | Message box contains an ENTER push button. |
| ENTERCANCEL | Message box contains both ENTER and CANCEL push buttons. |
| RETRYCANCEL | Message box contains both RETRY and CANCEL push buttons. |
| ABORTRETRYIGNORE | Message box contains ABORT, RETRY, and IGNORE push buttons. |
| YESNO | Message box contains both YES and NO push buttons. |
| YESNOCANCEL | Message box contains YES, NO, and CANCEL push buttons. |
|
| |
| Icon | |
| ERROR | Message box contains a small red circle with a red line across it. |
| ICONASTERISK | Message box contains an information (i) icon. |
| ICONEXCLAMATION | Message box contains an exclamation point (!) icon. |
| ICONHAND | Message box contains a small red circle with a red line across it. |
| ICONQUESTION | Message box contains a question mark (?) icon. |
| INFORMATION | Message box contains an information (i) icon. |
| NOICON | Message box is not to contain an icon. |
| QUERY | Message box contains a question mark (?) icon. |
| WARNING | Message box contains an exclamation point (!) icon. |
|
| |
| Default | |
| DEFBUTTON1 | The first button is the default selection. This is the default case, if none of MB_DEFBUTTON1, MB_DEFBUTTON2, and MB_DEFBUTTON3 is specified. |
| DEFBUTTON2 | The second button is the default selection. |
| DEFBUTTON3 | The third button is the default selection. |
|
| |
| Modality | |
| APPLMODAL | Message box is application modal. This is the default case. Its owner is disabled; therefore, do not specify the owner as the parent if this option is used. |
| SYSTEMMODAL | Message box is system modal. |
|
| |
| Mobility | |
| MOVEABLE | Message box is moveable. |
| Button pressed | Return value |
|---|---|
| ENTER | 1 |
| OK | 2 |
| YES | 3 |
| CANCEL | 4 |
| NO | 5 |
| IGNORE | 6 |
| RETRY | 7 |
| ABORT | 8 |
| ERROR | 0 |
The button flag and message text argument are required. The icon, default, modality and mobility flags are optional. All the flags are combined with a plus sign
The message box is displayed with a title bar and a system menu, which shows only the Move, Close, and Task Manager choices, which can be selected either by use of the pointing device or by accelerator keys.
If the user selects Close, the message box is removed and the return value = 4, whether or not a cancel button existed within the message box.
rc = wdCommand('messageBox OK+ERROR This is a sample message')
Moves a file to a new location on the client machine, or renames a file.
moveFile newName, oldName
moveFile destination, sourceFile
newName is the name you want the file to have,
oldName is the name of the existing file.
- or -
destination is where you want the file to be moved,
sourceFile is the file that you want to move.
MoveFile works on local files only, i.e. files on the client system.
You can rename a file with MoveFile by specifying new name with the same location as the source file.
Moves the file from the client machine to the FTP server specified.
Syntax
MoveFileToServer [ SYNC | ASYNC ,] url , filename
SYNC means do not return from command until the file is uploaded. This the default. SYNC can also be specified as WAIT
ASYNC means the command returns immediately after starting the upload, but before the upload is complete. If you specify ASYNC you will have no way of knowing if the file transfer completed successfully without checking for the file on the FTP server. ASYNC can also be specified as NOWAIT.
url is the URL of an FTP server that will accept the file. If the URL contains spaces it must be encoded using the EncodeURL command.
filename is the fully qualified name of the local file you want to copy to the FTP server.
This command only works with Netscape. It does not work with Opera, Mozilla, or any of the IBM Web Browsers; none of those browsers implement the FTP upload correctly. If you want to upload from your Rexx program while running in Opera, Mozilla or IBM Web Browser you must use the Rexx FTP package. An example program is shown in the Examples below.
The URL can include a user name and password in the URL. The syntax is
ftp://userName:password@IPAddressfor example
ftp://dgclark:whoaNelle@192.168.32.100where dgclark is the user name and whoaNelle is the password.
fileName is the fully qualified file name to be uploaded.
The file will have the same name on the FTP server as it has on the local hard drive. If you want to upload the file and specify a different name on the server you can:
You can use the TempFileName command to create a name that should be unique on the FTP server. The name can be created so that it includes your IP address as it appears to the web server, well as some random characters in the name.
The original file is deleted from the local hard drive after the upload is complete. Use the MoveFileToServer command to retain the local file after the upload is complete.
/* upload a file */
call wdParseArgs
fileName = 'f:\temp\a.cmd'
rc = wdCommand('movefiletoserver ftp://uploadUser:uploadPassword@www.hometown.org',fileName)
say 'rc: ' rc
exit
/* rexx ftp upload */
call wdParseArgs
rc = rxFuncAdd('FTPLoadFuncs','rxFtp','FtpLoadFuncs')
say 'register Funcs rc: ' rc
rc = FtpLoadFuncs()
say 'LoadFuncs rc: ' rc
rc = ftpsetuser('www.hometown.org','uploadUser','uploadPassword');
say 'set user rc: ' rc
rc = ftpput("f:\temp\a.cmd",a.cmd,"BINARY");
say 'ftp put rc: ' rc '
say 'ftperrorno: ' ftperrno
say 'rc: ' rc
exit
Opens a window with the specified URL.
openURL url, name [,windowParms] [, NOWAIT]
url The URL that is to be opened in the window. If the URL contains spaces it must be encoded; you can use the EncodeURL command if needed to encode the URL.
name The name to assign to the window. Names must be 32 characters or less, contain no spaces, and consist of letters, numbers and the underscore.
windowParms can be one of the following
| Parameter | Description |
|---|---|
| dependent | Create the new window as dependent on the current window. When the current window closes its dependent windows close. |
| directory | creates the standard browser directory buttons, such as What's New and What's Cool |
| innerHeight | Height of the inner part of the window in pixels |
| innerWidth | Width of the inner part of the window in pixels |
| location | Window will have the location entry field at the top of the window |
| menubar | Window will have the menu bar. |
| outerHeight | Vertical dimensions of the window in pixels. Includes any frame that might exist. |
| outerWidth | Horizontal dimensions of the window in pixels. Includes any frame that might exist. |
| personalbar | Creates the personal bar which displays the buttons from the user's Personal Toolbar bookmark folder |
| resizable | Allows the window to be resized. |
| screenX | Left side of window relative to the desktop |
| screenY | Top of the window relative to the desktop |
| scrollbars | Scrollbars are displayed |
| toolbar | Creates standard browser toolbar. |
| width | width of the window in pixels |
The NOWAIT parameter specifies that the command is to return as soon as possible, not waiting for a response, or possible error message, from the browser.
This command opens a browser window assigning the name you specify to the window. If a window of that name is already open this is the equivalent of GetUrl with a target = windowName. If the window does not already exist it will be created using the window parameters specified. If the window already exists the window parameters are ignored.
After the window is open you can then refer to this window by name when specifying a target for the GetURL, PostURL, etc. commands.
If the no windowparms are specified then a standard window is opened. If any windowParms are specified then all parameters are considered to be turned off and must be explicitly turned on in the windowParms. Multiple windowParms are concatenated together with commas, as shown in the examples below. There can be no spaces between any values in the window parameters.
In order to specify the NOWAIT parameter you must specify window parameters. If you want to open a default window and do not want to specify window parameters use the keyword DEFAULT in place of the window parameters.
This command uses a work window to perform its task. See the WorkWindowName parameter for information about work windows.
rc = wdCommand('openurl http://www.warpdoctor.org/plugindoc_commands.html helpForCommands outerheight=600,outerwidth=400,scrollbars,toolbar,resizable')
rc = wdCommand('openurl http://www.warpdoctor.org/plugindoc_commands.html DEFAULT NOWAIT')
rc = wdCommand('openurl http://www.warpdoctor.org/plugindoc_commands.html')
Opens a new, empty, browser window.
openWindow name [windowParms]
name The name to assign to the window. Names must be 32 characters or less, contain no spaces, and consist of letters, numbers and the underscore.
windowParms can be one of the following
| Parameter | Description |
|---|---|
| dependent | Create the new window as dependent on the current window. When the current window closes its dependent windows close. |
| directory | creates the standard browser directory buttons, such as What's New and What's Cool |
| innerHeight | Height of the inner part of the window in pixels |
| innerWidth | Width of the inner part of the window in pixels |
| location | Window will have the location entry field at the top of the window |
| menubar | Window will have the menu bar. |
| outerHeight | Vertical dimensions of the window in pixels. Includes any frame that might exist. |
| outerWidth | Horizontal dimensions of the window in pixels. Includes any frame that might exist. |
| personalbar | Creates the personal bar which displays the buttons from the user's Personal Toolbar bookmark folder |
| resizable | Allows the window to be resized. |
| screenX | Left side of window relative to the desktop |
| screenY | Top of the window relative to the desktop |
| scrollbars | Scrollbars are displayed |
| toolbar | Creates standard browser toolbar. |
| width | width of the window in pixels |
Examples
This command opens a new browser window assigning the name you specify to the window. You can then refer to this window by name when specifying a target for the GetURL, PostURL, etc. commands.
If the no windowParms are specified then a standard window is opened. If any windowParms are specified then all parameters are considered to be turned off and must be explicitly turned on in the windowParms. Multiple windowParms are concatenated together with commas, as shown in the examples below.
The wdCommand() returns when processing this command immediately after sending the command to the plug-in API to open the work window (which in turns opens the browser window). The new browser window may not actually be open by the time this function returns. If you intend to write to the browser window immediately after issuing the OpenWindow command you may need to delay the write to the window using the SysDosSleep() function for 1/2 to 1 second, depending on the speed of the client machine.
This command uses a work window to perform its task. See the WorkWindowName parameter for information about work windows.
Posts a message to another instance running in the plug-in
PostMsg instanceHandle messageString
where instanceHandle is the instance the message is to be sent to.
messageString is the string that is to appear in the
PmPrintf viewer
This command can be used to send notification of "events" between Rexx programs running in different instances in the plug-in. The message is sent to the Message Pipe of the instance specified. If that instance has not created and connected a message pipe then an error is returned.
The message can be any string upto 252 characters. The message is prefixed by the character U and a single space separates the U from the message string. For example the message HELLO THERE comes across the pipe as U HELLO THERE
The "message" sent in the example above is R765.
Sends a text string to the PmPrintf viewer; useful for debugging Rexx programs.
PmPrintf textString
where textString is the string that is to appear in the PmPrintf viewer
This command is intended to facilitate debugging of Rexx programs that run in the plug-in by the authors of those Rexx programs. The PmPrintf commands should be removed from the program before it is "released" for general use on a web site.
The PmPrintf viewer (PmPrintf.exe) and DLL (PmPrintf.DLL) must both reside
on the client machine running the Rexx program that contains the PmPrintf command(s). The viewer should be
started and running before the Rexx program executes, and the DLL must reside on the LIBPATH in order to
be found.
If the Rexx program starts running before the viewer is running you will hear a musical tone to indicate that you are losing your output.
If the PmPrintf.DLL file cannot be loaded or found
by the plug-in you will get an error message dialog box and the Rexx program will terminate.
The DLL is loaded by the plug-in when any plug-in instance needs to produce output and stays loaded
until all the plug-in DLL is unloaded; on Netscape and Mozilla this is when all the plug-in instances are
destroyed, on Opera this is when the browser is shut down.
The PmPrintf viewer and DLL are included in the standard installation package for the Rexx Plug-in from the WarpDoctor site.
The above Rexx program produces the output shown below
Posts data to a URL, the data being in the form of name=value sets. This is the same function as supplied by the HTML FORM tag, and is a way of sending information to and executing CGI programs.
The PostUrl command has four forms, each of which takes a different first argument. The command has to be issued multiple times in order to complete the post. You start with a PostURL URL ... and finish with a PostURL POST. You can intermix PostUrl commands with other commands - the PostUrl parameters you enter are saved until you send the PostURL POST command to finish the sequence. Sending the PostURL URL ... command will also clear out all the parameters from any previous PostURL commands issued.
PostURL URL ,url
url is the fully qualified URL of the CGI program to execute. WAIT - the default instructs the POST subcommand to not return control to the Rexx program until the post command completes and the CGI program sends its results. If the URL contains any spaces or non-printable characters it must be encoded before being passes as an argument. You can use the EncodeURL command to encode simple URLs, but if your URL is an "ISINDEX" type URL the command will not encode the URL the way you want.
PostURL TARGET ,target [, name]
Optional target of the post = [_blank | _self |_parent | _top | _result | _file | _window].
name is required for _window and is optional for _file.
PostUrl VAR , name = value
Optional - establishes a variable of name and value for the post operation. The name is not case sensitive.
PostUrl POST [, WAIT | NOWAIT]
Completes and executes post command WAIT - the default instructs the POST subcommand to not return control to the Rexx program until the post command completes and the CGI program sends its results. NOWAIT returns control to the Rexx program immediately after issuing the POST subcommand. NOWAIT cannot be used for targets of _file or _result.
Target can be
| Target | Description |
|---|---|
| _blank | The output of the CGI program is opened in a new, blank window |
| _self | The output of the CGI program is opened in the same window the plug-in occupies, which will destroy the plug-in instance running the program. |
| _parent | The output of the CGI program is opened the immediate FRAMESET parent of the current window. If the plug-in instance document has no parent the default is _self |
| _top | The output of the CGI program is displayed in the top window of chain of nested windows. |
| _file | The output of the CGI program is to be downloaded to a file. You can optionally supply the name of the file following the _file parameter. If you do not supply a name the output from the post operation goes to a randomly generated file name. The name of the file is returned as the return value of the command. |
| _window | The output of the CGI program is displayed in a named window, replacing whatever is currently being displayed in that window. You must supply the name of the window following the _window parameter. See OpenWindow for opening named windows. |
| _result | The output of the CGI program is sent as the return value of the PostURL Post command. This is a handy way of getting values returned from a CGI program directly into Rexx variables. The maximum amount of data that can be returned as a result is 64K. Any amount in excess of that will be truncated. |
fileName the fileName for the URL if _file was specified as the target,
0 for success if _file was not the target.
The POSTURL URL command deletes any existing post variables (created with the POSTURL VAR command) and resets the target to the default value. It is not an error to issue multiple POSTURL URL commands without issuing a POSTURL POST subcommand; the effect will be to erase the target and var subcommands and start a new POSTURL command.
The POSTURL URL command must be issued before any other type of POSTURL command. The POSTURL POST command completes the POSTURL procedure and executes the CGI program. The POSTURL VAR and POSTURL TARGET can be issued in any sequence.
If a name is not specified for _file in the POSTURL TARGET subcommand a random name is generated and returned in the return value of the post subcommand.
Each command, except for POSTURL POST, immediately returns control to the Rexx program, with a return string of 0 to indicate success or # Error - message to indicate an error. The POSTURL POST subcommand does not return control to the Rexx program until the CGI program finishes unless the NOWAIT argument is specified. The NOWAIT argument is valid only for window type targets, it is ignored for targets of _file and _result.
The post HTTP message is not sent to the web server until the POSTURL POST subcommand is issued. If the URL is invalid it will not be known until the POSTURL POST subcommand is issued.
POSTURL VAR can be issued multiple times to create multiple variables for a single post procedure. The maximum number of variables that can be created for a single post is 64. If POSTURL VARname=value is issued multiple times with the same name but different values the last name=value set is the one that is saved - meaning each new value for the same name overwrites the previous value. Values can hold numbers or strings of any size. Once a variable has been created it cannot be deleted until the post procedure is complete or a new POSTURL URL is issued - which deletes all the variables. The variable name cannot contain spaces.
Example
This example opens a new window named fred that is sized 250 pixels by 300 pixels, and then sends the variables action=99 and message='Hello World' to the CGI program WDPLUGINCGI.EXE at 192.168.32.102. Any output from the CGI program is directed to the window "fred".
Displays a dialog box with a entry text control for getting input from the user. The dialog box is modal to the plug-in window.
Prompt [,title]
where title is the title that appears in the title bar of the prompt dialog box. If no title is specified the title is Input. The title is limited to 256 characters.
# Error - message is returned for errors, or
inputValue - the value typed in the dialog
box.
If the
user types # Error...
in the prompt box it is converted to
## Error in the return value.
The prompt dialog box is mainly intended for non-visual Rexx
programs that are running as a macro of the plug-in (
x-warpdoctor/rexx), although it can be also be used with
other types of Rexx programs, including Command Prompt, i.e.
(x-warpdoctor/cmdrexx). When used with Command Prompt
type programs
be aware that the prompt dialog box is centered over the plug-in
window, not the Command Prompt window, and when the prompt dialog is
displayed the plug-in window will rise to the top of the window
z-order.
For x-warpdoctor/rexx type Rexx programs the prompt
dialog can also be automatically called when the Rexx PULL command is
issued in the program by setting the EMBED parameter
PullAsPrompt=YES
, or setting the plug-in variable
PullAsPrompt=YES from the Rexx program
at run-time.
The above Rexx program produces the output shown below
The first prompt dialog is show below.
The second prompt dialog is show below.
Returns information from the plug-in, or returns the value of plug-in variables.
For YES/NO or TRUE/FALSE variables the return value is always 1 or 0: 1 = YES or TRUE, 0 = NO or FALSE.
The variable name is not case sensitive, except for JSVar variables, which are case sensitive.
query variable
Variable is one of the following
| Variable | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Agent | Returns browser agent info, i.e. information about the browser.
For Netscape this is similar to the JavaScript method
navigator.userAgent(). For Opera
this function always returns the value
Mozilla/4.76 (IBM OS/2, Odin build 532; U) Opera 5.12 [en]regardless of the browser identity set in the preferences, where the JavaScript method navigator.userAgent() will return different values depending on the browser
identity setting. See also BrowserType.
Example | ||||||||||||||||||
| API | Returns version of the Netscape plug-in API for this browser.
Example
| ||||||||||||||||||
| AutoCloseWindow | Returns 0 | YES | url | textString | #n #textString
0 = no autoCloseWIndow parameter has been specified. YES = Plug-in instance is terminated when the session running the Rexx program/application is terminated. This applies only to Rexx programs run in a separate session. url = the plug-in instance is terminated when the session running the Rexx program is terminated, and the url specified is loaded in the window in place of the plug-in instance. textString or
Example
| ||||||||||||||||||
| BGColor | Returns hex value
Returns the hexadecimal value of the current background color of the Rexx output window, or of the rectangle if the output window is turned off. To use this value in the BGCOLOR parameter of the HTML BODY tag
you need to prefix the value with a pound sign (#), as shown below.
Example | ||||||||||||||||||
| BrowserType | Returns n,
where n is a numeric "type" of browser according to the "company" making the browser. Netscape = 1 - 9, Opera = 10-29, Mozilla = 30-49, IBM Web Server = 50-60. Each individual version is a number within the range of browserTypes. This allows for a easy way of doing conditional branching depending on who produced the browser. See also Agent.
Example | ||||||||||||||||||
| CgiURL | Returns url
Where url is the CGI program which provides back-end services to the plug-in. This is normally set automatically by the plug-in from the SRC parameter of the EMBED tag that started the instance. It can also be set by specifying the CGIURL parameter of the EMBED
A plug-in instance is not
allowed to run unless CGIURL is set.
Example | ||||||||||||||||||
| CloseOnExit | Returns n
1 = the Command Prompt window is closed at end of Rexx program - valid only for x-warpdoctor/cmdrexx type programs 0 = the Command Prompt window is not closed when the Rexx program terminates.
Example | ||||||||||||||||||
| CurrentDir | Returns drive:/directory
The current drive and directory for the Rexx program execution.
Example | ||||||||||||||||||
| DebugPlugin | Returns current setting for the debugPlugin variable. Settings
are:
Example | ||||||||||||||||||
| DLL | name
Determines whether name DLL can be loaded. On OS/2 the DLL specified in name is loaded into memory using the OS/2 function DosLoadModule(). If you want to search for the DLL without loading it into memory use the Query File command. The name can be the name of the DLL module with the .DLL extension, or it can be the fully qualified path of a DLL - with the .DLL extension. If the DLL cannot be found, or it cannot be loaded, an error message is returned with the DosLoadModule() return code. If the DLL can be loaded the full path and name of the DLL is returned. Once the DLL is loaded into memory it stays loaded until the browser is shut down. Example | ||||||||||||||||||
| Domain | Returns domain
The domain part of the SiteURL, i.e. the part of the URL for the current site that is between the http:// and the first forward slash. For example if the SiteURL was http://www.greatSite.org/rexxstuff the domain would be http://www.greatSite.org Example | ||||||||||||||||||
| EnableIPC | Returns n
Returns 1 if this instance allows other instances or programs to query and set the JSVAR variables, and to query the arguments. Returns 0 if other programs are not allowed to query or set JSVAR variables or the instance arguments. The default is 1. Example
| ||||||||||||||||||
| EraseOnExit | Returns n
Returns 1 if the Rexx program file, specified in SRC is deleted on destruction of plug-in instance. Returns 0 if the file(s) is not deleted. Example | ||||||||||||||||||
| FGColor | Returns hex value
Returns the hexadecimal value of the current foreground color /text color of the Rexx output window. Example | ||||||||||||||||||
| File | Checks whether file exists, or if the file can be written to, or read, or
searches a path for a file.
Syntax:
query file EXISTS | READ | WRITE | READWRITE | envVar , filename The first argument is
If an error is returned, the return value is
Examples | ||||||||||||||||||
| GotFocusCount | Returns number
Returns the number of times that the plug-in has been notified of a focus change since the last time the plug-in attempted to update the application window it is controlling. Example
| ||||||||||||||||||
| GzipName | Returns x:\path\gzip.exe
Returns the fully qualified path and name of the gzip compress/decompress utility. This is normally installed in the WarpDoctor install directory. The plug-in searches for gzip.exe in the install directory, and if it doesn't find gzip.exe there it searches the PATH. The value returned in the first location where gzip.exe is found. Example
| ||||||||||||||||||
| InstallDir | Returns drive:directory
Returns the drive and path where the WarpDoctor Rexx Plug-in files are installed This value comes from the WarpDoctor_Plugin, key=Path entry in the OS2.INI profile. Example
| ||||||||||||||||||
| InstanceHandle | Returns the instance handle for the name/title/src value specified.
Syntax query instanceHandle [NAME | TITLE | SRC , string ] If NAME, or TITLE is specified all the currently running instances are searched for a name, title that matches the string and that instanceHandle is returned. If no instances have a name or title that matches the string an error is returned. The string for name and title title is case sensitive. If SRC is specified all the currently running instances are searched for a src that matches the string. The string for src is a fully qualified URL; if the URL in string is not fully qualified the SiteURL of the current instance is prefixed to the value to make it fully qualified. Note that instance handles are returned only for those instances where EnableIPC=YES. The instance handle is used in the
ReleaseInstance
parameter of the
Examples Returns
| ||||||||||||||||||
| InstanceHandles | Returns handle handle ...
Returns a space delimited list of the instance handles of all the currently running instances. You can use the Rexx WORD() function, or the Rexx PARSE statement to process the instance handle list that is returned. Note that an instance can be terminated at any time, so the list that is returned is a "snapshot" of the instance that were running at the time of the command. Example
| ||||||||||||||||||
| InstanceJSVar | Returns the value of the JSVar variable in the instance specified
Syntax
Returns the value of JSVAR variable name from instance specified by
instanceHandle or instanceName.
If a name is specified
all the current running instances are searched for a
name that matches the
instanceName to determine the instance.
If the name JSVAR variable does not exist in the instance specified
an error will be returned.
Note that the names are case sensitive.
The instance which you are querying
JSVars must have the variable EnableIPC=1, otherwise
querying is not allowed for that instance.
Example
| ||||||||||||||||||
| InstanceJSVars | Returns name name ...
Syntax
Returns the names, blank delimited, of all the JSVar variables from
the instance specified in
instanceHandle or instanceName.
If a name is specified
all the current running instances are searched for a
name that matches the
instanceName to determine the instance.
If no JSVar variables exist in the instance specified
an error will be returned.
The JSVar names are case sensitive.
The instance which you are querying
JSVars must have the variable EnableIPC=1, otherwise
querying is not allowed for that instance.
The JSVar names returned existed in the instance at the time the query was run.
Since JSVar variables can be dropped by a program at any time, there is no guarantee
that a variable will exist after the query returns.
Example
| ||||||||||||||||||
| InstanceName | Returns instanceHandle
Returns the name for the instanceHandle. If no name exists for that instance an error is returned. Example | ||||||||||||||||||
| Instances |
Returns the number of instances currently running in the plug-in. There will always
be at least one instance running - the one making the request.
Example | ||||||||||||||||||
| InstanceTitle | instanceHandle
Returns the title for the instanceHandle. If no title exists for that instance an error is returned. Example | ||||||||||||||||||
| IPAddress | Returns ipaddress
Returns the IP address of user at the web server. This may be different than the user's local IP address if the user is going through a proxy server that masks IP addresses. Example | ||||||||||||||||||
| JSVar name | returns value in the JSVar name.
Syntax
The name is the name or number of the variable to return a value from. The name is not case sensitive. If the name variable does not exist an error will be returned. JSVAR variables are created when a program with the MIME-Type of
x-warpdoctor/execute
runs that has a
ReleaseInstance parameter with a instanceHandle = to this instance.
The plug-in creates a JSVAR variable in the instanceHandle
for each user created parameter of the A Rexx program can also create its own JSVar variables with Set JSVAR command. This provides a way to transfer values from a secondary thread running in a multithreaded Rexx program, or from Rexx routines contained in separate source files. Finally, a Rexx program can create JSVar variables in another instance with the Set instanceJSVar command, which provides a mechanism for transferring values between cooperating Rexx programs running in different instances, Example | ||||||||||||||||||
| JSVar_Name variableNumber | returns name of the variableNumber JSVAR variable.
Syntax
The number is the number of the variable to return the name of. If the variable does not exist an error will be returned. Example | ||||||||||||||||||
| JSVars | returns name name ...
Returns the names of all the JSVAR variables in a single string. Each name is blank-delimited. If no JSVAR variables exist an error is returned. Note that the names are case sensitive. Example | ||||||||||||||||||
| MimeType | Returns mimeType
Returns a textual MIME-Type, i.e. the value specified in the TYPE parameter. The Rexx variable wdMainArgs.rexxRunType is a numerical value for the MIME-Type. Example | MozillaWait | Returns milliseconds
The number of milliseconds to delay before returning from certain commands when running in a Mozilla based browser. A millisecond value of -1 means the feature is disabled. See here for more details. Example
| ||||||||||||||||
| MsgShutdownDelay | Returns milliseconds
The number of milliseconds the plug-in waits after sending the *SHUTDOWN* message through the message pipe, before continuing the shutdown process. You can use this parameter to allow an application time to finish its termination sequence before the application or process is terminated by the plug-in. You can change this value with the set msgShutdownDelay command.
| NoCloseWorkWindow | Returns n
Returns the current setting of the NoCloseWorkWindow variable. A setting of 1 means that work windows are not closed and the temporary file executed in the window is not immediately deleted. This is useful for debugging purposes, when you want to see the JavaScript code that is executed in the window. The default setting is 0. Example
| ||||||||||||||||
| NumOfParms | Returns n
Returns the number of EMBED parameters from the
tag that started the program
Example | ||||||||||||||||||
| ParmName n | Return name
Syntax
Returns the name of a parameter, where n = the parameter number
Example
| ||||||||||||||||||
| ParmValue n | Return value
Syntax
where n = the parameter number (ordinal) or the name of a parameter,
or name is the name of the parameter.
Parameter names are not case sensitive.
| ||||||||||||||||||
| PluginTitle | Returns string
Returns the Title for that appears in dialog boxes and window titles. The PluginTitle is the title of the plug-in; the title is the title of the Rexx program running in the plug-in. Example
| ||||||||||||||||||
| Posx | Returns x
Returns lower left corner coordinate relative to browser window
| ||||||||||||||||||
| Posy | Returns y
Returns lower left corner coordinate relative to browser window
| ||||||||||||||||||
| PullAsPrompt | Returns 0,1 or 2.
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).
This value is ignored for
programs that run in a separate session.
| ||||||||||||||||||
| RunExclusive | Returns url url ...
Syntax
Returns a blank delimited list of all the entries in the RunExclusive list added by the current program. If the ALL argument is specified the return list contains all the entries in the RunExclusive list.
| ||||||||||||||||||
| RexxOutputWindow | Returns n
Returns 1 if the output window is displayed, or 0 if the output window is not displayed. If the output window is not displayed the plug-in area/window is filled by a rectangle. The color of the rectangle is controlled by the BGColor setting.
| ||||||||||||||||||
| SRC | Returns url
File or URL specified in the SRC embed parameter.
| ||||||||||||||||||
| ScreenSize | Returns x y
Returns the x and y dimensions of the screen, in pixels. The value is returned as X Y with a space separating the X from the Y.
| ||||||||||||||||||
| ShutdownDelay | Returns 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). You can change this value with the set shutdowndelay command.
| ||||||||||||||||||
| SiteURL | Returns url
The URL of the site parsed from the SRC EMBED tag parameter. The SiteURL includes everything from the beginning of
the SRC string up to (but excluding) the last forward slash.
| ||||||||||||||||||
| StripTrailingBlanks | Returns 1 or 0
1 = trailing blanks are stripped from the PULL result when the user types input in the output window. The default is 1 or YES.
| ||||||||||||||||||
| TempDir | Current location where temporary files are created. If the Rexx program was
zipped this is the location the program was unzipped to, and where the
program is running from.
| ||||||||||||||||||
| TimeOutServer | Returns n
Returns the number of milliseconds the plug-in waits for a response from the server before declaring an error.
| ||||||||||||||||||
| TimeOutValue | Returns n
Returns the number of milliseconds the plug-in waits for a response from itself before declaring an error.
| ||||||||||||||||||
| Type | mimeType
Returns the value specified in the TYPE parameter of the EMBED tag. This is the same command as MimeType.
| ||||||||||||||||||
| Title | title
Returns the value specified in the Title parameter of the EMBED tag.
| ||||||||||||||||||
| Version | Returns version
Returns version the WD plug-in Example | ||||||||||||||||||
| WinLocation | Returns x y
Returns lower left corner coordinates, both x and y, relative to desktop. The X and Y corrdinates are separated by a space. Example | ||||||||||||||||||
| WinPos | Returns x y
Returns lower left corner coordinates, both x and y, relative to desktop, and the width and height. All corrdinates are separated by a space. Example | ||||||||||||||||||
| WinX | Returns x
Returns lower left corner coordinate relative to desktop Example | ||||||||||||||||||
| WinY | Returns y
Returns lower left corner coordinate relative to desktop Example
| ||||||||||||||||||
| WinHeight | Returns n
Returns height in pixels of the plug-in window . Example | ||||||||||||||||||
| WinWidth | Returns n
Returns width in pixels of the plug-in window . | ||||||||||||||||||
| WorkWindowName | Returns name
Returns the name of the window used by the plug-in to execute JavaScript functions. See Set WorkWindowName for details.
|
Releases a waiting Rexx program in another plug-in instance that have been suspended with the WaitOnJS command.
ReleaseInstance instanceHandle | name
Where instanceHandle is the handle of another currently running
(but suspended) plug-in instance.
name is the
name of an instance to release.
Names are case sensitive.
The ReleaseInstance command releases a Rexx program that has been suspended with the WaitOnJS command in another plug-in instance. If the instance that is being released is not enabled for for interprocess communications (EnableIPC=1) an error will be returned.
You can obtain a list of the instance handles for all the currently running instances with the query instanceHandles command.
Reloads the plug-in list in browser, making the browser recognize any newly added plug-ins.
reload
Syntax
YES = reload pages that contain plug-ins
Outputs text in Rexx output MLE window WITHOUT a line break. The SAY command always adds and carriage return to text that is output. This command outputs text without the carriage return making for a better prompt when using the Rexx PULL command
SayPrompt message
Example
call wdCommand 'sayprompt Enter the destination directory: ' pull destDir
Outputs text in the Rexx output MLE window.
saytowin text
text will be output in the Rexx MLE output window.
Sends a text based "message" to another plug-in instance Rexx program.
SendMessage instanceHandle | instanceName [ , message ]
instanceHandle or instanceName is the instance to which the message is sent.
message is the text to be sent. Maximum size of message text is 4096 characters.
This provides a way of sending a short message to another Rexx program running in a different plug-in instance. The Rexx program that is the target of the message must have a message pipe open or the command will return an error. The target Rexx program/instance must also have enabled IPC ( EnableIPC=1 ).
You specify the target program or plug-in instance by supplying the instance handle of the
target instance, or by specifying the name of
the instance. You can also send a message to yourself by specifying THIS as the instanceName.
Sets or changes the value of plug-in variables.
None of the variable names, except for JSVar variables , are case sensitive;
JSVar variables are designed to hold variables from JavaScript and are
are case sensitive to match the behavior of JavaScript variables. The
variables are
Set
Syntax
set name = value
| Variable Name | Description |
|---|---|
| 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 assummed 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. All four examples below set the same color value.
|
| CgiURL | url
URL of the CGI program which provides back-end services to the plug-in. This is set automatically by the plug-in, but you can override the setting if you know that it is incorrect. The program name is wdplugincgi.exe. Example
|
| CloseOnExit | YES | NO
YES = close Command Prompt window when Rexx program is finished, NO = Leave the window open when the Rexx program terminates. The default = NO. This setting only applies to Rexx programs run in a Command Prompt window. Example |
| DebugPlugin | n
where n is an integer from 0 to 4: 2 - 4 turn on debugging output, 1 = loads PmPrintf.DLL but produces no output. For debugging output higher numbers generate more verbose messages. Default value = 0. Setting DebugPlugin to a non-zero value turns on debugging messages from the plug-in. In order to turn on debugging messages you must have PmPrintf.DLL on your LIBPATH and PmPrintf.exe to view the messages. |
| EnableIPC | YES | NO
YES (or 1) means that other programs and instances are allowed to query and set the JSVar variables, and to query the arguments. NO (or 0) = other programs are not allowed to query or set JSVar variables or the instance arguments. The default = YES.
|
| EraseOnExit | YES | NO
YES = erase Rexx program file(s) on destruction of plug-in instance, NO = Do not erase Rexx program file(s) on exit. Default value = NO. This is useful if you don't want anyone to see the contents of the Rexx program, or if you are developing or debugging a Rexx program. Since the browser caches the Rexx program that is downloaded you will not see changes you have made to the program until you clear the browser's cache or you restart the browser. Conversly if you are not debugging the program you want EraseOnExit=NO (which is the default) so that browser will cache the Rexx program, thereby avoiding downloading the program again when running it a second time.
|
| 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.
|
| InstanceJSVar | instanceHandle |instanceName , name = value
Sets the JSVar variable name to the value. The name is case sensitive. To set a JSVar to a blank (zero length string) value do not specify a value, for example The value is stripped of leading and trailing blanks. If you need leading or trailing blanks in the value put quotes around the value. A maximum of 64 JSVar variables can exist in a plug-in instance.
|
| JSVar | name = value
Sets the JSVar variable name to the value. The name is case sensitive. To set a JSVar to a blank (zero length string) value do not specify a value, for example The value is stripped of leading and trailing blanks. If you need leading or trailing blanks in the value put quotes around the value. A maximum of 64 JSVar variables can exist in a plug-in instance. To remove a variable use the Drop JSVAR command. To remove all JSVar variables use the Drop ALL command.
|
| MozillaWait | NO | milliseconds
A value of NO turns off the MozillaWait feature. Any value other than NO (or FALSE or -1) is considered to be milliseconds and sets the MozillaWait to that millisecond value. All Mozilla based browsers, upto and including version 1.2b, have a
bug in their implementation of the plug-in API. The browser is
supposed to notify the plug-in when commands
CopyFileToServer,
MoveFileToServer, and
PostURL
with a target other than
|
| MsgShutdownDelay | milliseconds
The number of milliseconds the plug-in waits after sending the *SHUTDOWN* message through the message pipe, before continuing the shutdown process. Using this parameter allows you to give an application time to finish its termination sequence before the plug-in terminates the application or process. This parameter is different from the ShutDownDelay in two ways:
This setting is ignored is a message pipe is not running. The maximum time allowed is 15,000 - 15 seconds.
| NoCloseWorkWindow | 1 | 0
1 means that work windows are not closed and the temporary file executed in the window is not immediately deleted. This is useful for debugging purposes, when you want to see the JavaScript code that is executed in the window. The default setting is 0.
|
| PluginTitle | title text
Sets text for dialog box and window titles.
|
| 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. See Prompt for more information about the prompt dialog and prompting.
|
| RunExclusive | YES | urlList
Adds an entry to the RunExclusive List. YES adds the currently running program to the list, urlList adds the URLs in the list (blank delimited) to the list. If the entry is not a fully qualified URL then the SiteURL is prefixed to the entry to make it a fully qualified entry. The
RunExclusive list prevents two instances of the same program from
running at the same time, or it prevents other programs from running
while this program is running. All the entries in the list are
prevented from running as long as they are in the list. The entries
added by a program, either with this command or by specifying a value
for the Note: the URL entered into the RunExlusive list must be the URL
for
the Rexx program, not the URL of the HTML page containing the
|
| 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.
|
| StripTrailingBlanks | YES | NO
YES = strip trailing blanks on Rexx PULL values when running Rexx as a macro. Default value = YES. Stripping trailing blanks makes it easier to compare values entered by the user.
|
| StatusLine | message text
Sets text that appears in the status line at the bottom of the browser window. The status line will retain the text message only until the next message appears, which can come from multiple sources.
|
| TempDir | path
Sets the path where temporary files are created, overriding the automatic setting. When the plug-in starts it automatically sets TempDir to the value in the TMP variable, if it exists, or the TEMP variable if it exists and TMP is null, or to the plug-in install directory (where the security configuration file is stored) if both TMP and TEMP are null. When you change the value of TEMPDIR any cookies created under the old value will not be visible to Javascript code running locally; Javascript code running from a domain will not be effected. |
| TimeOutServer | milliseconds
Sets the number of milliseconds to wait for a response after issuing a command to the web/FTP server before declaring an error. This is not the time for the server to complete the command, but just for the server to acknowledge the command. The default setting is 30 seconds. |
| TimeOutValue | milliseconds
Sets the number of milliseconds to wait for a response after issuing performing a function in the plug-in. This pertains to plug-in commands that run on a separate thread or are awaiting response from the browser. The default setting is 10 seconds. |
| WorkWindowName | _blank | name
Default = _blank. Sets the name of the window used by the plug-in to execute JavaScript functions. Some of the commands provided by the plug-in ( CloseWindow, CreatePage, JavaScript, OpenURL, OpenWindow ) are executed by opening a browser window, executing JavaScript in that window, and then closing the browser window. This causes a momentary flash on the screen as the window |