For a complete subcommand handler description, see the Open Object Rexx: Programming Guide.
The RXSUBCOM command registers, drops, and queries Rexx subcommand handlers. A Rexx procedure or script file can use RXSUBCOM to register dynamic-link library subcommand handlers. Once the subcommand handler is registered, a Rexx program can send commands to the subcommand handler with the Rexx ADDRESS instruction. For example, Rexx Dialog Manager programs use RXSUBCOM to register the ISPCIR subcommand handler.
"RXSUBCOM REGISTER ISPCIR ISPCIR ISPCIR" Address ispcir
See ADDRESS for details of the ADDRESS instruction.
RXSUBCOM REGISTER registers a dynamic-link library subcommand handler. This command makes a command environment available to Rexx.
>-RXSUBCOM--REGISTER--envname--dllname--procname--------------><
Parameters:
The subcommand handler name. The Rexx ADDRESS instruction uses envname to send commands to the subcommand handler.
The name of the dynamic-link library file containing the subcommand handler routine.
The name of the dynamic-link library procedure within dllname that Rexx calls as a subcommand handler.
Return codes:
The command environment has been registered.
A duplicate registration has occurred. An envname subcommand handler in a different dynamic-link library has already been registered. Both the new subcommand handler and the existing subcommand handler can be used.
The registration has failed. Subcommand handler envname in library dllname is already registered.
RXSUBCOM was unable to obtain the memory necessary to register the subcommand handler.
A parameter is missing or incorrectly specified.
RXSUBCOM DROP deregisters a subcommand handler.
>>-RXSUBCOM--DROP--envname--+---------+------------------------><
+-dllname-+Parameters:
The name of the subcommand handler.
The name of the dynamic-link file containing the subcommand handler routine.
Return codes:
The subcommand handler was successfully deregistered.
The subcommand handler does not exist.
The environment was registered by a different process as RXSUBCOM_NONDROP.
A parameter is missing or specified incorrectly.
RXSUBCOM QUERY checks the existence of a subcommand handler. The query result is returned.
>>-RXSUBCOM--QUERY--envname--+---------+-----------------------><
+-dllname-+Parameters:
The name of the subcommand handler.
The name of the dynamic-link file containing the subcommand handler routine.
Return codes:
The subcommand handler is registered.
The subcommand handler is not registered.
A parameter is missing or specified incorrectly.
RXSUBCOM LOAD loads a subcommand handler dynamic-link library.
>>-RXSUBCOM--LOAD--envname--+---------+------------------------><
+-dllname-+Parameters:
The name of the subcommand handler.
The name of the dynamic-link file containing the subcommand handler routine.
Return codes:
The dynamic-link library was located and loaded successfully.
The dynamic-link library was not located or could not be loaded.
A parameter is missing or incorrectly specified.
>>-RXQUEUE--+-----------+--+--------+--------------------------><
+-queuename-+ +-/FIFO--+
+-/LIFO--+
+-/CLEAR-+The RXQUEUE filter usually operates on the default queue named SESSION. However, if an environment variable named RXQUEUE exists, the RXQUEUE value is used for the queue name.
For a full description of Rexx queue services for applications programming, see External Data Queue.
Parameters:
stacks items from STDIN last in, first out (LIFO) on a Rexx queue.
queues items from STDIN first in, first out (FIFO) on a Rexx queue.
removes all lines from a Rexx queue.
RXQUEUE takes output lines from another program and places them on a Rexx queue. A Rexx procedure can use RXQUEUE to capture operating system command and program output for processing. RXQUEUE can direct output to any Rexx queue, either FIFO (first in, first out) or LIFO (last in, first out).
RXQUEUE uses the environment variable RXQUEUE for the default queue name. When RXQUEUE does not have a value, RXQUEUE uses SESSION for the queue name.
The following example obtains the Windows version number with RXQUEUE:
/* Sample program to show simple use of RXQUEUE */ /* Find out the Windows version number, using the */ /* VER command. VER produces two lines of */ /* output; one blank line, and one line with the*/ /* format "The Windows Version is n.nn" */ "VER |RXQUEUE" /* Put the data on the Queue */ pull . /* Get and discard the blank line */ Pull . "VERSION" number "]" /* The bracket is required for Windows 95, not for Windows NT */ Say "We are running on Windows Version" number
Note that the syntax of the version string that is returned by Windows can vary, so the parsing syntax for retrieving the version number may be different.
The following example processes output from the DIR command:
/* Sample program to show how to use the RXQUEUE filter */
/* This program filters the output from a DIR command, */
/* ignoring small files. It displays a list of the */
/* large files, and the total of the sizes of the large */
/* files. */
size_limit = 10000 /* The dividing line */
/* between large and small*/
size_total = 0 /* Sum of large file sizes*/
NUMERIC DIGITS 12 /* Set up to handle very */
/* large numbers */
/* Create a new queue so that this program cannot */
/* interfere with data placed on the queue by another */
/* program. */
queue_name = rxqueue("Create")
Call rxqueue "Set", queue_name
"DIR /N | RXQUEUE" queue_name
/* DIR output starts with five header lines */
Do 5
Pull . /* discard header line */
End
/* Now all the lines are file or directory lines, */
/* except for one at the end. */
Do queued() - 1 /* loop for lines we want */
Parse Pull . . size . name ./* get one name and size */
/* If the size field says "<DIR>", we ignore this */
/* line. */
If size <> "<DIR>" Then
/* Now check size, and display */
If size > size_limit Then Do
Say format(size,12) name
size_total = size_total + size
End
End
Say "The total size of those files is" size_total
/* Now we are done with the queue. We delete it, which */
/* discards the line remaining in it. */
Call rxqueue "DELETE", queue_name