Step 5: Create a user exit routine (optional)

The TSO Remote Execution server enables you to provide an optional user exit routine. You can use this routine to alter the JOB and EXEC statement parameters. In addition, you can use this routine to provide JES control statements to meet installation-specific requirements, such as updating accounting information before the submission of the TSO batch job.

On entry to the exit, register 1 points to the following parameter list:

Offset

Description

+0

A pointer to an AF_INET or AF_INET6 address structure in the following format:

Offset: Description
+0: Address family AF_INET or AF_INET6 (2 bytes)
+2: Server port (2 bytes)
+4: Client AF_INET or AF_INET6 IP address (4 or 16 bytes)

+4

A pointer to a 1024-byte string terminated by the null character (0x00), which contains the JOB statement parameters. The exit routine can modify this string to meet installation-specific requirements. On entry, the string is set to the following string:

userid,USER=userid,[PASSWORD=passwd,]MSGCLASS=msgclass[,SECLABEL=seclabel]

The userid and passwd values are set to the user ID and password that the client provides, and the msgclass value is the message class of the Remote Execution server cataloged procedure. The PASSWORD parameter is present only when the client provides a password. The server passes the SECLABEL parameter only when the user ID is defined with a security label. The following example shows a modified string:

userid,USER=USER1,PASSWORD=USERXX1,MSGCLASS=E,LINES=999999,NOTIFY=SYSADM

+8

A pointer to a 256-byte string terminated by the null character (0x00), which contains the EXEC statement parameters. The exit routine can modify this string to meet installation-specific requirements. On entry, the string contains the EXEC statement for the procedure that is specified on the TSOPROC parameter of the Remote Execution server, or the default IKJACCNT procedure if the TSOPROC parameter is not specified. The following example shows a modified string:

IKJACCNT,REGION=4K,TIME=300

+12

A pointer to a 256-byte string terminated by the null character (0x00), which the exit can use to provide JES control statements. On entry, the string is set to 0x00. The following example shows a modified string:

/*JOBPARM  SYSAFF=SYS5

Exit return codes:

0
A return code of 0 indicates to the server to continue processing the request.
Nonzero
A nonzero return code indicates to the server to send the job control buffer (offset +4) back to the client and close the connection.

Rules:

Code the exit with the AMODE(31) and RMODE(ANY) attributes to ensure proper addressability of the input parameters.
The exit must terminate all modified strings with the null character (0x00).
If the server is IPv6 enabled and an IPv4 client connects, the IP address is the 4-byte IPv4 address and not the IPv4-mapped IPv6 address.
If the exit provides JES control statements, the server inserts the control statements into the JCL stream following the JOB statement and before the EXEC statement without any parsing. If more than one control statement is present, the exit must ensure proper JCL line separation by including the NL character or CRLF character as necessary.
The server inserts the EXEC parameters into the JCL stream without parsing. If the exit modifies the EXEC parameters, it must ensure proper JCL line separation by including the NL character or CRLF character as necessary.

Guidelines:

For RSH commands without passwords, the PASSWORD parameter is not present.
The userid in the first positional parameter of the JOB statement parameters can be processed by installation-written JES exits.
The modified parameters are submitted as a TSO batch job.

Tip: The exit can have the server reject a connection by setting a nonzero return code. The exit can replace the JOB statement buffer contents with message text to be returned to the client. The first byte of the buffer can be set to 0x00 to reject the connection without sending a message to the client.

The user exit is shipped as a sample in the RXUEXIT member of the SEZAINST data set. For more information about this sample, see the REXEC topic in z/OS Communications Server: IP Configuration Reference.