REXX functions

The RSSTSO address space can be used by BMC AMI Resident Security Server (RSS) products to drive BMC or user-developed REXX procedures inside a secured and isolated batch TSO environment.

In addition to all the normal built-in and TSO specific REXX functions, RSS supplies some additional REXX functions:

Function	Purpose
RSSINIT	Function to initialize/verify REXX is running under RSS.
RSSRESP	Function to return response messages to the calling application.
RSSAUDIT	Function to write messages to the RSS Audit Log.
RSSALIAS	Function to perform an alias lookup based on the Alias Table defined in the RSS configuration.
RSSEMAIL	Function to send an email via RSS.
RSSREXEC	Function to request execution of a command on a remote RSS system.

Use of RSS REXX procedures is always 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

The RSSINIT function can be used to verify that the REXX procedure is running under RSS:

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:

rssresp('message text')

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:

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:

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 set up the email profile before sending the email. Multiple emails can be sent with the same profile using multiple 'send' operations:

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.
Operation	Arguments
TO	value1: Email address of recipient value2: Name of recipient (optional)
CC	value1: Email address of cc: recipient value2: Name of cc: recipient (optional)
FROM	value1: Email address of sender value2: Name of sender(optional)
SUBJECT	value1: Email Subject
SEND	value1: The text of email to be sent or STEM variable (ending in a '.') to send a multiple line email. When a STEM variable is specified, the stem.0 entry must contain a valid counter of stem array elements.

An email is sent for each 'SEND' operation with any email attributes set in the previous rssemail() calls.

RSSREXX function

The RSSREXEC function can be used to queue commands to an 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.

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 the RSS REXX function:

/* REXX */

/**************************************/
/* 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.)