The WarpDoctor Rexx Plug-in supplies a number of Rexx functions for communicating with the plug-in. Each of those functions are listed below.
The behavior of the functions can be modified by the Rexx variable
wdPlugin.errorSwitch
If the variable is not present, or if it is set to 0 (zero) then the functions return errors
as part of the normal Rexx return value. When wdPlugin.errorSwitch = 1 any errors
encountered by any functions will result in a Rexx syntax error. You can pick up this syntax error
using the Rexx signal on syntax statement.
Loads (registers) all the Rexx plug-in functions. This should be called at the top of the Rexx program, for programs that run in a separate session. It does not hurt for this function to also be called from programs that run as a macro of the plug-in.
Initializes the plug-in environment for the Rexx program, and creates the Rexx stem variables wdEmbed. and wdMainArgs.
rc = wdParseArgs( [argumentString] )
argumentString = the string to parse. If the argumentString is not supplied as a argument to wdParseArgs() it will retrieve the argumentString from the Rexx variable pool, which is the default and desired behavior.
This function must be called before all other Rexx plug-in functions except for wdPluginLoad(). The function must be called on the main thread of the Rexx program if the Rexx program is multi-threaded.
The normal behavior when calling wdParseArgs() is to not pass any arguments to the function. wdParseArgs() will obtain the information it needs from the argument string passed to the Rexx program by the plug-in when the plug-in started the program.
GPF Rexx programs handle arguments passed to the
program differently than other Rexx programs, therefor when calling
wdParseArgs() from a GPF Rexx program you must supply the argument
string passed to the GPF Rexx program by the plug-in as the first (and
only) argument to wdParseArgs(). GPF Rexx programs obtain the
start-up argument string with the GPF function
queryArgs(varName), where varName is the
name of a Rexx stem variable. The tail .2 contains the argument
string, which is what needs to be passed to wdParseArgs(), as shown in
the example below.
Sends commands to the plug-in and returns results from the command.
rc = wdCommand( command [ parameter1] [ parameter2] ... )or
rc = wdCommand( command [ ,parameter1] [ ,parameter2] ... )
The command and any arguments are space delimited when passed as a single argument to wdCommand(). Optionally you can pass the command and each argument as separate arguments (separated by commas) to wdCommand(). The function will successfully handle either method of invocation.
The maximum size of a command plus any arguments is 64K. The maximum size of any return value is also 64K; any return value that exceeds that size will be truncated to 64K.
Exposes the Rexx stem variables wdMainArgs. and wdEmbed. to a Rexx routine in a separate file.
call wdExposeArgs plugin_environment
plugin_environment is obtained from wdMainArgs.environment
Each source file containing Rexx code has its own variable pool that is isolated from all other Rexx variable pools. This means that when a Rexx program calls a routine located in another file, the Rexx variables in the main program are not visible to the routine. And the Rexx variables in the routine are not visible to the main program.
Since the Rexx Plug-in stores its "environment" in the Rexx variable pool, it needs to copy that environment to a new variable pool before any plug-in features can be used from in the Rexx code associated with that variable pool.
The wdExposeArgs() function "sets up" the plug-in environment in a new variable pool. When it is called the environment value from wdMainArgs.environment is passed as the (only) argument. The wdExposeArgs() function builds the Rexx variables and values it needs for the plug-in environment from the argument passed to it.
Opens the client end of message pipe
rc = wdOpenPipe(pipeNname, handleVariableName)
pipeName is the name of the pipe to open. For a message pipe you must use the name in the wdMainArgs.msgpipename variable on the main thread.
handleVariableName The name of the Rexx variable to store the pipe handle. This variable will be filled in by the function.
This function opens the client end a named pipe, or message pipe.
This function, along with the wdReadPipe() are provided to read messages sent from the plug-in, or to any other named pipe. When communicating with the plug-in's message pipe you must
When this function returns the pipe will be open and the pipe handle will be set in the variable specified in the handleVariableName argument. You must pass that variable name to the wdReadPipe() funciton to read from the pipe.
Normally the
link type of pipeMessage is not used, hence the pipe functions are not needed.
The pipe is only needed when the other types of links do not work for your application, or
you need some specific event notification that is not happening through the normal event mechanisms
of your application. Examples of this might be a Command Prompt Rexx program that wants to shut-down
when the plug-in instance window is closed, or any VX-Rexx application with multiple windows
since VX-Rexx doesn't respond to the WM_QUIT window message.
Note: The wdCommand() function talks to the plug-in using a named pipe when the Rexx program is running in a separate session. The communications with the pipe are all handled automatically. Although you can see the name used for that pipe in the wdMainArgs.private.cmdPipeName variable you should not attempt to open, read or close the pipe manually.
When using the link type of pipe the Rexx code that reads from the pipe
needs to be on a separate thread from the main Rexx program. This is because messages can come
down the pipe at any time from the plug-in.
rc = wdOpenPipe(wdMainArgs.private.msgPipeName,'pipehandle')
if (word(rc,1) = '#') then do
say rc
exit
end
Reads an open named pipe.
returnVar = wdReadPipe(pipeHandle )
pipeHandle is the handle of a pipe from the wdOpenPipe() command.
The pipe must be opened with the wdOpenPipe() function before it can be read. The function will wait until a message is available in the pipe before returning.
rc = wdOpenPipe('\PIPE\1293412\WDPLUGIN\MESSAGE','pipehandle')
if (word(rc,1) = '#') then do
say rc
exit
end
do forever
retvalue = wdReadPipe(pipeHandle)
if retvalue = 'X') then leave
end
Closes an open message pipe.
wdClosePipe(pipeHandle
This closes an open pipe. Normally a message pipe does not need to be closed by the Rexx program, it will be closed by the plug-in automatically when the instance terminates.
Deregisters all the plug-in Rexx functions.
wdPluginUnload( functionName [, functionName ] )
Where functionName is the name of the function to deregister. You can use ALL in place of a function name to deregister all the Rexx Plug-in functions.
The plug-in Rexx functions are automatically registered and deregistered for Rexx programs running as macros of the plug-in.
You should not deregister functions unless you are sure that no other programs are running in the plug-in. The only way to know that is to query the number of instances (query instances).
call wdPluginUnload