Using REXX functions
In addition to all the normal built-in and TSO-specific REXX functions, RSS supplies some additional REXX functions:
Function | Purpose |
|---|---|
Function to initialise/verify Rexx is running under RSS. | |
Function to return response messages to the calling application. | |
Function to write messages to the RSS Audit Log. | |
Function to perform an alias lookup based on the Alias Table defined in the RSS configuration. | |
Function to send an email via RSS. | |
Function to request execution of a command on a remote RSS system. |
You use RSS REXX procedures from a specific RSS application. The application controls the REXX procedures driven and how any response messages are further processed.
Where REXX is driven from the Tools facility for testing as described earlier in this manual, the Tools driver is effectively the application and any response messages are returned to the browser window.
RSSINIT function
Use the RSSINIT function to verify that the REXX procedure is running under RSS:
Syntax | Description |
|---|---|
rssinit('reference') | The reference parameter is optional. If specified, any audit log records written from REXX will be tagged with this reference. The reference can be up to 15 characters. |
RSSRESP function
The RSSRESP function can be called multiple times to return one or more messages to the calling application:
Syntax | Description |
|---|---|
rssresp('messageText') | The message text supplied to the function in the first positional parameter is returned to the calling application. |
RSSAUDIT function
The RSSAUDIT function can be called multiple times to write one or more messages to the RSS Audit Log:
Syntax | Description |
|---|---|
rssaudit('audit log text') | The Audit Log message text supplied to the function in the first positional parameter is written to the RSS Audit Log. All messages from a single REXX procedure execution are written as a block in a single Audit Log record. |
RSSALIAS function
The RSSALIAS function is used to convert a generic name to a specific name. The name translations are defined in the AliasTable configuration in RSS:
Syntax | Description |
|---|---|
specificName = rssalias(genericName) | The generic name supplied to the function in the first positional parameter is used as a lookup in the RSS Alias Table. If the name is defined, the specific name from the table is returned. If the name is not defined, the generic name is returned. |
RSSEMAIL function
The RSSEMAIL function is used to send emails from RSS REXX.
Defaults for email settings are defined in the EmailProfile parameters in the RSS configuration. The RSSEMAIL function allows the majority of these defaults to be overridden.
Multiple rssemail() function calls may be required to setup the email profile prior to sending the email. Multiple emails can be sent with the same profile using multiple 'send' operations:
Syntax | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
rssemail(operation, value1|STEM., value2) | The first positional parameter defines the email operation to be performed. Where an email should be sent to multiple recipients, the rssemail() function should be called multiple times with the TO or CC operands.
|
An email is sent for each SEND operation with any email attributes set in previous rssemail() calls.
RSSREXEC function
The RSSREXEC function can be used to queue commands to a RSSTSO address space running in a remote environment, such as an LPAR in another sysplex. Any TSO or REXX command supported by RSSTSO can be routed.
It should be noted that the remote execution of the command is not guaranteed. If the remote system is unavailable, the command will not be sent.
Syntax | Description |
|---|---|
rssrexec(systemName, command|STEM) | The system name in the first positional parameter must match a name defined in the servers table in the RSS configuration. The command string in the second positional parameter must be a valid TSO or REXX command string. If the second positional parameter is a stem variable (ending in a ‘.’) all commands in the stem array will be sent. The stem.0 entry must contain a valid counter of stem array elements. |
Example function calls
The following code excerpt gives simple samples of RSS REXX function use:
/**************************************/
/* Sample rssinit() */
/**************************************/
rc = rssinit('TestRexx')
if rc <> 0 then exit 4
/**************************************/
/* Sample rssresp() */
/**************************************/
rc = rssresp('Request completed OK')
/**************************************/
/* Sample rssaudit() */
/**************************************/
rc = rssaudit('Audit Log Record Line 1')
rc = rssaudit('Audit Log Record Line 2')
/**************************************/
/* Sample rssalias() */
/**************************************/
sysid = rssalias('Production')
/**************************************/
/* Sample rssemail() */
/**************************************/
rc = rssemail('TO','support@abcbank.com',"support")
rc = rssemail('CC','manager@abcbank.com',"My Manager")
rc = rssemail('SUBJECT','Alert from Rexx')
email.0 = 3
email.1 = 'This is an automatic email'
email.2 = alerttext
email.3 = 'Please call 0800 123 4567'
rc = rssemail('SEND', email.)
/**************************************/
/* Sample rssrexec() */
/**************************************/
cmd.0 = 3
cmd.1 = 'myrexx parm1 parm2'
cmd.2 = 'LISTA'
cmd.3 = 'rexx4 parm1 parm2'
rc = rssrexec('Production', cmd.)