Configuring REXX parameters for custom exit functionality
When a user requests an unlock, setup, or reset through the product, the product calls the corresponding REXX routine defined by the parameter. If the parameter is already defined, it sends a return code and an optional response message to the product, which the product then analyzes to decide whether to process the user request.
You can enable REXX processing either locally or remotely, but you cannot combine them. The parameters and variables defined for local and remote REXX routines, which are defined in the following tables, are the same:
Parameter | Description |
|---|---|
REXXReset memberName | Defines the REXX member used for the reset exit |
REXXUnlock memberName | Defines the REXX member used for the unlock exit |
REXXSetup memberName | Defines the REXX member used for the setup exit |
Variable | Description |
|---|---|
EC_Sysplex | Stores the sysplex ID |
EC_Sysid | Stores the LPAR ID |
EC_AppTrace | Acts as a flag if AppTrace is ON This variable is not applicable to remote REXX processing. |
EC_RexxTrace | Acts as a flag if REXXTrace is ON This variable is not applicable to remote REXX processing. |
EC_Userid | Stores the user ID from the current SSPR request |
EC_Pass | Stores the password from the current SSPR request This variable is not applicable to the REXXUnlock parameter. (SPE2301) You can also use this variable to set and amend a password within a REXX member. |
EC_Resp | Stores the response text (maximum limit is 512 characters) This variable is not applicable to remote REXX processing. |
As an administrator, you can configure the custom exit functionality by using either of the following methods:
Local REXX processing
In this simple setup, which offers the most basic REXX functionality, REXX runs in the same TSO address space as SSPR.
The following table lists the functions that are used for local REXX processing:
Function | Description |
|---|---|
ecentry() | Initializes the SSPR variables Include this function at the beginning of the REXX code. |
ecreturn() | Sends a response back to the product, and allows the product to display an error message |
When you run a REXX routine on a local address space, the product parses the return code from REXX (returned using the EXIT or RETURN statements) to determine whether to approve a user request. The return code 0 indicates success and the return code 8 indicates failure. You can choose to return an error message along with the return code.
A sample code for local REXX processing follows:
/* Get args */
rc = ecentry()
/* Check for DB2 users */
if left(EC_Userid, 3) == 'DB2' then do
EC_Resp = 'Access Rejected - DB2 Users are not permitted to use SSPR'
SAY DATE('U') TIME() ': Access Rejected for 'EC_Userid
rc = ecreturn()
exit 8
end
/* Override password for all CICS users */
if left(EC_Userid, 3) == 'CIC' then do
SAY DATE('U') TIME() ': Processing CICS user 'EC_Userid
EC_Pass = 'CIC'right(EC_Userid, 3)
end
/* All clear */
EC_Resp = ''
rc = ecreturn()
exit 0
Remote REXX processing
In this method, the REXX routines occur on a remote TSO address space, which is different from the address space in which the product runs. Remote REXX processing provides the following advantages:
- You can run all REXX processes under a separate STC user ID.
- You can use functions that are unavailable for single address space configurations. For example, you can use Db2 commands by using the rxsubcom() command.
The following table lists the functions that are used for remote REXX processing:
Function | Description |
|---|---|
rssvars() | Initializes the variables received from the product |
rssresp() | Sends a response to the server You can use this function to send a return code to the product and a response to the product UI. The syntax to send a return code is rc = rssresp('EC_Return <n>'). |
When you run a REXX routine on a remote address space, you must use the rssresp() function to send the return code from the REXX to the product. The product then parses the return code to determine whether to approve a user request. The return code 0 indicates success and the return code 8 indicates failure. You can use the rssresp() function again to return an error message.
A sample code for remote REXX processing follows:
/* Get args */
rc = rssvars()
/* Check for DB2 users */
if left(EC_Userid, 3) == 'DB2' then do
rc = rssresp('Access Rejected - DB2 Users are not permitted to use SSPR')
SAY DATE('U') TIME() ': Access Rejected for 'EC_Userid
rc = rssresp('EC_Return 8')
exit 0
end
/* Override password for all CICS users */
if left(EC_Userid, 3) == 'CIC' then do
SAY DATE('U') TIME() ': Processing CICS user 'EC_Userid
EC_Pass = 'CIC'right(EC_Userid, 3)
rc = rssresp('EC_Pass 'EC_Pass)
end
/* All clear */
rc = rssresp('EC_Return 0')
exit 0