Submitting REXEC and RSH requests in batch

You usually run REXEC and RSH interactively by entering the command and then receiving the results at your terminal. However, you can also run REXEC and RSH as a batch job. To accomplish this, you must supply the necessary job control language (JCL) and submit it to the job entry subsystem (JES) using the TSO SUBMIT command.

The command format when submitted as a batch job is the same as the command format described in REXEC command—Execute a command on the remote host and receive the results on your local host. You enter the command as a parameter on the EXEC statement. The results of the command executed on the remote host are stored on the local host according to how you define the SYSPRINT DD statement. The data set characteristics should be consistent with the output from the command you are executing at the remote host.

When you invoke the REXEC command, a check is made to see if a data set is allocated to INPUT. If a data set is allocated, any input is read from that data set rather than from your terminal. Similarly, a check is made to see if data set is allocated to OUTPUT. If so, all REXEC output is written to that data set rather than to your terminal.

The REXECD or RSH server does not support output being returned to output DD statements other than SYSTSPRT, SYSPRINT or OUTPUT. Sometimes it is necessary to direct the output from a REXEC or RSH batch request to an OUTPUT DD and to include a SYSPRINT DD with SYSOUT=* specified. This is particularly true if the REXEC or RSH command to be executed contains a slash(/).

There might be times when REXEC and RSH are being executed and the user does not want the output to be directed to the SYSPRINT DD file. If a //OUTPUT DD card is coded, output will be directed to it. This DD statement must be directed to a SYSOUT or a validly defined data set. If multiple REXEC or RSH commands are being executed in one step, then it is recommended that DISP=MOD be coded on the //OUTPUT DD card. This will allow each command execution to be appended to the previous output. If the //OUTPUT DD card specifies a nullfile (ie. DSN=NULLFILE or DD DUMMY), then the //OUTPUT DD statement will not be used. Regardless of which ddname you use for the REXEC or RSH output, a new data set must have the DCB=(...) parameter specified on the DD card. Any data set you use must have a logical record length (LRECL) greater than 0. If the LRECL is equal to 0 then the data set is not used.

When using the REXECD server, the procedure specified in the TSOPROC argument of the startup procedure must have the //SYSTSPRT DD statement appearing before any other output DD specifications in the procedure. For example, if the batch procedure specified was TSOPROC=TESTJOB, the following example would be the correct specification for the batch procedure for REXECD:

//TESTJOB  EXEC PGM=IKJEFT01,REGION=4M,DYNAM=30,REGION=4M
//STEPLIB   DD  DSN=A.LOADLIB,DISP=SHR
//SYSTSPRT  DD SYSOUT=*
//SYSPRINT  DD  SYSOUT=*

Adding a PARM argument to the EXEC JCL DD statement for commands to be submitted to batch might cause unpredictable output, characters to be lost, or output to be presented out of order.

If DDs are dynamically allocated, the order of output returned might be unpredictable. For example, the following TSO/E CLIST were invoked as the remote execution command, using the procedure TESTJOB:

PROC 0
TIME
ALLOC FI(OUT) SYSOUT(*)
OPENFILE OUT OUTPUT
SET &OUT = &STR(THIS; IS THE FIRST LINE)
PUTFILE OUT
SET &OUT = &STR(THIS; IS THE SECOND LINE)
PUTFILE OUT
TIME
SET &OUT = &STR(THIS; IS THE LAST LINE)
PUTFILE OUT
CLOSFILE OUT
FREE  FI(OUT)
EXIT

In this case, the output might be returned as:

THIS IS THE FIRST LINE
THIS IS THE SECOND LINE
THIS IS THE LAST LINE
output from time
output from time

In the following example, the TESTJOB procedure was modified to add the OUT DD statement:

//TESTJOB  EXEC PGM=IKJEFT01,REGION=4M,DYNAM=30,REGION=4M
//STEPLIB   DD  DSN=A.LOADLIB,DISP=SHR
//SYSTSPRT  DD  SYSOUT=*
//SYSPRINT  DD  SYSOUT=*
//OUT       DD  SYSOUT=*

The CLIST was also modified, as in the following example (notice that the ALLOC FI(OUT) and the FREE FI(OUT) have been removed):

PROC 0
TIME
OPENFILE OUT OUTPUT
SET &OUT = &STR(THIS; IS THE FIRST LINE)
PUTFILE OUT
SET &OUT = &STR(THIS; IS THE SECOND LINE)
PUTFILE OUT
TIME
SET &OUT = &STR(THIS; IS THE LAST LINE)
PUTFILE OUT
CLOSFILE OUT
EXIT

The output appears as in the following example:

output from time
output from time
THIS IS THE FIRST LINE
THIS IS THE SECOND LINE
THIS IS THE LAST LINE

Be aware that output being returned to the client from DDs other than SYSTSPRT or SYSPRINT might have characters truncated. This behavior has been observed only in the first line of new output files other than SYSTSPRT or SYSPRINT. If you use DDs other than SYSTSPRT or SYSPRINT, you might want to ensure that the first line of the output file contains a blank line, so that no data is lost.

Notes:

You can also use the NETRC data set name described in Using the NETRC data set to specify the user ID and password. You can override the NETRC data set search order by specifying a NETRC DD statement in the batch job. The NETRC DD statement identifies the NETRC data set to be used. You must provide all REXEC command information by using the NETRC data set and the PARM keyword on the EXEC statement.
Submitting a long running command can cause the REXEC program to end abnormally with a 522 system abend code. This can be avoided by specifying TIME=1440 on the EXEC statement of the JCL you submit. Job step timing is suppressed, including the collection of SMF job time accounting information.
If the command to be executed on the remote host contains a slash (/), you must use a preceding slash (/) in the input stream of the NETRC data set or the PARM.
The following example shows invoking the RSH program in batch and executing the command:
```
LS ./bin/temp/*        
//RSHBATCH EXEC PGM=RSH,
//         PARM='/-l userid hostname ls ./bin/temp/*'
```
A condition code of 1 will be set when an REXEC batch request encounters one of the following error conditions:
- The client cannot connect to TCP/IP.
- The host name cannot be resolved.
- The translation table cannot be loaded.
A condition code of 1 will be set when an RSH batch request encounters an error condition in which the client cannot connect to TCP/IP or when the host name cannot be resolved.

The following example shows REXEC JCL Spooling Output to JES:

//REXEC    JOB  USERID,MSGLEVEL=(1,1),NOTIFY=USERID
//STP1     EXEC PGM=REXEC,REGION=512K,
//         PARM='-l userid -p password foreign_host command'
//SYSPRINT DD   SYSOUT=*

Note: The data set containing the JCL cannot have sequence numbers.

The following example shows the use of the userid.NETRC.DATA containing the user ID and password. The output is sent to a permanent data set for later use.

//REXEC    JOB  USERID,MSGLEVEL=(1,1),NOTIFY=USERID
//STP1     EXEC PGM=REXEC,REGION=512K,
//         PARM='foreign_host command'
//SYSPRINT DD   DSN=USERID.REXEC.SYSPRINT,DISP=(NEW,CATLG),
//         UNIT=3380,VOL=SER=MYVOL

Note: When running REXEC in batch, the user ID assigned to the job is used as the user_id in the NETRC data set.

The following example shows the use of the NETRC DD statement in batch. The NETRC DD statement can be used in batch to override the default userid.NETRC.DATA or userid.NETRC files.

//REXEC    JOB  USERID,MSGLEVEL=(1,1),NOTIFY=USERID 
//STP1     EXEC PGM=REXEC,REGION=512K,
//         PARM='foreign_host command'
//SYSPRINT DD   SYSOUT=*
//NETRC    DD   DSN=TST.REXEC.NETRC,DISP=SHR

Note: The user ID and password are retrieved from TST.REXEC.NETRC instead of userid.NETRC.DATA or userid.NETRC.