Remote Job Execution command

Issuing the Remote Job Execution command allows HULFT to make an execution request for the jobs of other hosts.

The host that acknowledged the Remote Job Execution Request executes the job that is specified by the host that issued the Request. The job to be executed must be registered in the Job Information in advance. Service name is "HULRJOB".

Program interface

CALL Library name/UTLRJOB PARM(['LIB=Library name'] 'J=jobid' 
   'H=hostname' ['SYNC'] ['W=waittime'] ['{O=[filename]|V8=filename'}] 
   ['G'] ['OUTPUT=filename'] ['EXIT' CL variable name])

Explanation of parameters

LIB=Library name

Library name in which HULFT is installed ("HULFT" by default)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

J=jobid

Job ID to be executed (Mandatory)

Specify a string of alphanumeric characters (and "_" if desired) that is within 50 bytes. This Job ID must be registered in the Job Information of a remote host.

H=hostname

Name of the host to which the job execution request is made (Mandatory)

Specify this parameter as an alphanumeric character string of 68 bytes or less.

SYNC

Synchronous Execution Request (Optional)

Specifying this parameter synchronizes the termination of transfer with the end of job execution by a remote host.

When omitted, the Remote Job Execution Request is handled as asynchronous request.

Specify the parameter of the Synchronous Execution Timeout (W=waittime) when you specify this parameter.

W=waittime

Synchronous Execution Timeout (sec.) (Optional)

Specify the wait time for synchronization with the job execution result received from a remote host. Specify this parameter within the range of "10" to "259200". When it reaches the time specified, the control will return even if the job execution request is still in progress. Note that the request result is not returned to the command, if this happens.

To specify this parameter, you must define the "SYNC" parameter.

When omitted, HULFT applies the value of Job Timeout (JOBWTIMEOUT) specified in the System Environment Settings file.

O=filename

Name of the file to which the results of job execution are output (Optional)

Specify this parameter in the format of Library name/File name(Member name).

If you describe only the tag as in "O=", omitting the filename outputs the results to standard output.

When omitted, HULFT does not output the results of job execution. Besides, HULFT does not output the results if a connection to a remote host failed.

V8=filename

Output format of job execution result (Optional)

Specify this parameter in the format of Library name/File name(Member name).

You cannot omit the parameter value of filename as in "V8=". Type a file name when you specify the "V8=" parameter.

Specifying this parameter outputs individual Job IDs in 50 byte length.

When omitted, HULFT does not output the results of job execution. Besides, HULFT does not output the results if a connection to a remote host failed.

G

Control of error messages that the Remote Job Execution command outputs (Optional)

When omitted, HULFT displays error messages.

OUTPUT=filename

Destination of the error messages that the Remote Job Execution command outputs (Optional)

Specify this parameter in the format of Library name/File name(Member name).

When omitted, error messages are not output.

The number of log records that a log file can retain is unlimited.

EXIT CL variable name

Specifies to receive the error code output by the Remote Job Execution command and specifies the CL variable name to set the error code value (Optional)

The CL variable name must immediately follow the EXIT tag.

HULFT sets an error code to the CL variable only if the command ends unsuccessfully.

When omitted, an error code is not set.

Note

On HULFT for Mainframe, the Synchronous Execution Timeout clocks by minute. Therefore, specify a value of a multiple of 60 for the Synchronous Execution Timeout, when you make a request for the Remote Job Execution to HULFT for Mainframe. When the value is not a multiple of 60, HULFT automatically rounds up the figure to a multiple of 60 to carry out processing.

Command interface

UTLRJOB JOBID( ) HOSTNAME( ) SYNC( ) WAITTIME( ) FORMAT( ) DSPFILE( ) DSPMBR( ) 
   LIBRARY( ) MSG( ) FILE( ) MBR( )

Explanation of parameters

JOBID

Job ID to be executed (Mandatory)

Specify a string of alphanumeric characters (and "_" if desired) that is within 50 bytes. This ID must be registered in the Job Information of the remote host.

HOSTNAME

Name of the host to which the job execution request is made (Mandatory)

Specify this parameter as an alphanumeric character string of 68 bytes or less.

SYNC

Synchronous Execution Request ("*NO" by default)

*NO :: Do not synchronize the termination of transfer with the end of job execution by a remote host.
*YES :: Synchronize the termination of transfer with the end of job execution by a remote host.

Specify the parameter of the Synchronous Execution Timeout (WAITTIME) when you specify "*YES" for this parameter.

WAITTIME

Synchronous Execution Timeout (sec.) (Optional)

Specify the wait time for synchronization with the job execution result received from a remote host. Specify this parameter within the range of "000010" to "259200". When you set "0" for this parameter, HULFT waits for the result infinitely.

To specify this parameter, you must define the "SYNC(*YES)" parameter.

When omitted, HULFT applies the value of Job Timeout (JOBWTIMEOUT) specified in the System Environment Settings file.

FORMAT

Output format of job execution result (*V7 by default)

*V7 :: Output the results in V7 format.
*V8 :: Output the results in V8 format.

DSPFILE

Name of the file to which the results of job execution request are output (Optional)

Specify this parameter in the format of Library name/File name.

Specify these names as an alphanumeric character string of 10 bytes or less starting with an alphabet, respectively.

When omitted, HULFT does not output the results of job execution.

DSPMBR

Member name of the file to which the results of job execution are output ("*FILE" by default)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

LIBRARY

Library name in which HULFT is installed ("HULFT" by default)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

MSG

Control of error messages ("*YES" by default)

*NO :: Suppress error messages.
*YES :: Show error messages.

FILE

Name of the library and the file to which error messages are output (Optional)

Specify this parameter in the format of Library name/File name.

Specify these names as an alphanumeric character string of 10 bytes or less starting with an alphabet, respectively.

When omitted, error messages are not output. The number of log records that a log file can retain is unlimited.

MBR

Member name of the file to which error messages are output ("*FILE" by default)

Specify this parameter as an alphanumeric character string of 10 bytes or less starting with an alphabet.

Note

Example of output on the requesting side of a Remote Job Execution request

Output example of the result from the remote job execution request (When V8 format is not specified)

JOBID=JOB02    DATE=12292017 STIME=212629 ETIME=212631 RC=00000-000000000 HOST=AS400

Output example of the result from the remote job execution request (When V8 format is specified)

JOBID=JOB02                                              DATE=12292017 STIME=212955 ETIME=212956 RC=00000-000000000 HOST=AS400

JOBID: Job ID (8 bytes or 50 bytes)

= Remarks =
When V8 format is not specified, HULFT outputs the ID as an 8-byte string.

When V8 format is specified, HULFT outputs the ID as a 50-byte string.
DATE: Date on which the host started requesting (MMDDYYYY)

= Remarks =
The date format varies depending on a value of the Date Format (DATEFMT) that is specified in the System Environment Settings

For details, refer to the following:

HULFT10 for IBMi Administration Manual : Global Settings
STIME: Time at which the host started requesting (HHMMSS)
ETIME: Time at which the host ended requesting (HHMMSS)
RC: Status code (5 bytes) - Detail code (9 bytes)
HOST: Name of the host that acknowledged the Remote Job Execution Request (68 bytes)

= Remarks =

The values shown below are set to the Status code:

Where the host that acknowledged a request is HULFT for IBMi:

Detail code in the Request Acknowledge Log

0 :: Successful end
Other than 0 :: Unsuccessful end

Refer to the following:

HULFT10 for IBMi Error Codes and Messages : Status codes for observe program

Where the host that acknowledged a request is other than HULFT for IBMi:

Refer to the following of HULFT that acknowledged a request:

HULFT10 for Windows Operation Manual : Remote Job Execution command

HULFT10 for Linux/AIX Operation Manual : Remote Job Execution command

HULFT10 for zOS Operation Manual : Remote Job Execution

Example of output on the requested side of a Remote Job Execution request

Output example of the result from an acknowledgment of the remote job execution request (When V8 format is not specified)

JOBID=JOB02    HOST=AS400                                                                DATE=12292017 STIME=21:29:56 ETIME=21:29:56 RC=00000-000000000

Output example of the result from an acknowledgment of the remote job execution request (When V8 format is specified)

JOBID=JOB02                               HOST=AS400 
                DATE=12292017 STIME=19:08:51 ETIME=19:09:01 RC=00000-000000000

JOBID: Job ID (8 bytes or 50 bytes)

= Remarks =
When V8 format is not specified, HULFT outputs the ID as an 8-byte string.

When V8 format is specified, HULFT outputs the ID as a 50-byte string.
HOST: Name of the host that issued the Remote Job Execution Request (68 bytes)
DATE: Date on which the host started requesting (MMDDYYYY)

= Remarks =
The date format varies depending on a value of the Date Format (DATEFMT) that is specified in the System Environment Settings. For details, refer to the following:

HULFT10 for IBMi Administration Manual : Global Settings
STIME: Time at which the host started requesting (HH:MM:SS)
ETIME: Time at which the host ended requesting (HH:MM:SS)
RC: Status code (5 bytes) - Detail code (9 bytes)