Remote Job Execution API

This API executes the job that is specified by a job ID on a destination host. Since the API works in Language Environment (LE), the CEE.SCEERUN Language Environment library is required. (This is the default name if the library name is defaulted during the installation of the operating system.)

(1) Call Format (COBOL)

CALL 'XRRJOBAP' USING parameter area

Explanation of parameter area

Field	Attribute	Length	Input/Output	Description
Operating Version	Character	6	Input	Specify the version of the parameter area. Specify one of the following: V08L01 V08L02 V08L04 The operation is the same regardless of which you specify.
Reserved	Character	8		Spaces are set.
Job ID	Character	50	Input	Specify the Job ID of the job that is to be executed on the destination host.
Destination Host Name	Character	50	Input	Specify the destination host name.
Synchronization Mode Flag	Character	1	Input	Specify 'S' to return control after the job is executed. If you specify a value other than 'S,' control is returned when issuing of the job execution request is complete.
Job Execution Time-out	Binary	4	Input	Specify the job execution time-out in seconds. Specify a value from '10' to '259200.' If you do not specify a value within this range, the API sets one of the following values: 10 if the specified value is 9 or lower 259200 if the specified value is 259201 or more.
Status Code	Binary	2	Output	The API sets a status code in this field when the API ends.

(2) Status Codes

Status Code	Description
0	The API issued the job execution request successfully.
1	The operating version is not supported.
81	An error occurred during job execution.
83	The specified job ID is not defined on the destination host.
85	A time-out occurred during job execution.
99	Failed to access the Host Information file (HULFT.HOST).
540	A function that cannot be used with the version of HULFT at the communication destination is specified. A string whose length is 9 bytes or more is specified for the Job ID.
9999	An error occurred during the communication processing on the destination host.
Others	The API sets a code that indicates a communication error.

Note

Incorporate the following DD statements into the JCL to be executed:

Example of JCL

//XRFILE   DD DSN=HULFT.FILE,DISP=SHR                                           
//XRHOST   DD DSN=HULFT.HOST,DISP=SHR                                           
//XRSYSIN  DD DSN=HULFT.PARMLIB(HULPRM),DISP=SHR                                
//IPGET    DD DSN=HULFT.HOSTS.LOCAL,DISP=SHR                                    
//*SYSTCPD DD DSN=TCPIVP.TCPPARMS(TCPDATA),DISP=SHR

DD Name	Value	Description
XRFILE	HULFT.FILE	Send and Receive Management File
XRHOST	HULFT.HOST	Host Information File
XRSYSIN	HULFT.PARMLIB(HULPRM)	System Environment Settings File
IPGET	HULFT.HOSTS.LOCAL	IP Management File
SYSTCPD	TCPIVP.TCPPARMS(TCPDATA)	TCPIP.DATA Data Set

(3) Example of Use

Case where you use COBOL

Below is a sample program that executes a remote job, using the Remote Job Execution API (XRRJOBAP).

The sample program has member name 'SMPJOBAP' in HULFT JCL library.

Data to be used

Destination Host Name:	ZOS
The job ID of the record of the Job Information that is registered on the destination host:	JOBID

      * 
      * HULFT REMOTE JOB EXECUTION API SAMPLE 
      * 
       IDENTIFICATION     DIVISION. 
       PROGRAM-ID.         SMPJOBAP. 
       ENVIRONMENT        DIVISION. 
       DATA               DIVISION. 
       WORKING-STORAGE    SECTION. 
      * 
      * XRRJOBAP PARAMETER AREA 
      * 
       01  XRRJOBAP-PARM. 
           02 XRRJOBAP-VER      PIC X(6). 
           02 XRRJOBAP-RESERVE  PIC X(8). 
           02 XRRJOBAP-JOBID    PIC X(50). 
           02 XRRJOBAP-EXHOST   PIC X(50). 
           02 XRRJOBAP-SYNC     PIC X(1). 
           02 XRRJOBAP-TIMEOUT  PIC 9(8)  COMP. 
           02 XRRJOBAP-RTNCD    PIC 9(4)  COMP. 
      *------------------------------------------------* 
       PROCEDURE          DIVISION. 
      * 
      * XRRJOBAP PARAMETER AREA INITIALIZATION 
      * 
           INITIALIZE          XRRJOBAP-PARM. 
      * 
      * REMOTE JOB EXECUTION 
      * 
           MOVE 'V08L04'       TO XRRJOBAP-VER. 
           MOVE SPACE          TO XRRJOBAP-RESERVE. 
           MOVE 'JOBID'        TO XRRJOBAP-JOBID. 
           MOVE 'ZOS'          TO XRRJOBAP-EXHOST. 
           MOVE 'S'            TO XRRJOBAP-SYNC. 
           MOVE 3600           TO XRRJOBAP-TIMEOUT. 
           CALL 'XRRJOBAP' USING XRRJOBAP-PARM. 
      * 
           STOP RUN.