Hitachi

JP1 Version 12 JP1/Automatic Job Management System 3 Command Reference


jpqjobsub

Organization of this page

Format

jpqjobsub
     [-mh manager-host-name]
     {-q queue-name|-ah agent-host-name}
     [-eu user-name]
     [-jn job-name]
     [-pr execution-priority]
     -sc target-file-name
     [-arg "arguments..."]
     [-w work-path-name]
     [-shl shell-path-name]
     [-res execution-locked-resource-name]
     [-st execution-start-time]
     [-el time-out-period]
     [-si standard-input-file-name]
     [-rs {q|h|d}]
     [-so|-son standard-output-file-name|-soa standard-output-file-name]
     [-se|-sen standard-error-output-file-name| -sea standard-error-output-file-name]
     [-ev environment-variable-file-name]
     [[-env environment-variable-name=value]...]
     [-h]
     [-t transfer-source-file-name[=transfer-destination-file-name]]...
     [-td transfer-source-file-name[=transfer-destination-file-name]]...

Description

The jpqjobsub command registers a submit job. This command can be used to register a PC job, a Unix job, a queue job (a job to be registered in a queue), or a queueless job. This command can also be used to register a submit job with a JP1/NQSEXEC host, a JP1/OJE for VOS3 host, or a AS/400 system. Note that a job to be registered in another system is a queue job, so a queue must be created in the other system before the job is registered.

Destination of registration

Specifiable options

JP1/NQSEXEC host

-mh,-q,-jn,-pr,-sc,-arg,-so#,-se#,-h,-t

JP1/OJE for VOS3 host

-mh,-q,-jn,-sc,-arg,-t

AS/400 system

-mh,-q,-jn,-pr,-sc,-arg,-t

#

This option only takes effect for linkage with JP1/NQSEXEC 06-00 or a later version.

The other options are ignored even if they are specified.

Execution privileges

You must have any of the following JP1 privileges:

Arguments

-mh manager-host-name

Specify the name of the manager host to which you want to register a submit job.

You can specify a character string of 1 to 255 bytes.

By default, the system assumes the local host name.

-q queue-name

If you want to execute a queue job, which is queued and then executed, specify the name of the queue.

You can specify a character string of 1 to 63 bytes. If you want to register a job in another system, specify this option instead of the -ah option.

-ah agent-host-name

If you want to execute a PC or Unix job for which the host where the job will be executed is specified, specify the agent host name.

You can specify a character string of 1 to 255 bytes. You cannot specify this option when you register a job in another system.

-eu user-name

Specify the OS user name. Make sure that the OS user you specify is mapped to the command-execution JP1 user (JP1 user with the same name as the command-execution OS user) on the agent host on which the command is executed.

You can specify a character string of 1 to 63 bytes.

In Windows, if you want to ensure that a submit job is always executed by the local host user, specify the OS user name in the host-name\user-name format.

-jn job-name

Specify the name of the submit job you want to register.

You can specify a character string of 1 to 63 bytes. By default, the system assumes the first 63 bytes of the file name (excluding the path) of the execution file specified with the -sc option.

-pr execution-priority

Specify the execution priority.

You can specify 1 to 5. By default, the system assumes 1.

The following gives the values you can specify, and their meanings.

Value

Priority for UNIX

Priority for Windows

1

nice value + 20

Lower than interactive processing

2

nice value +10

3

nice value

Equal to interactive processing

4

nice value - 10

Higher than interactive processing

5

nice value - 20

For a UNIX host executing jobs, when users do not have superuser privileges, specifying an execution priority of 4 or 5 results in a privilege error at the time of job execution.

Supplementary note

Windows only supports three levels of priority. Specify one of the following three priority classes to start the job process:

  • If the specified value is 1 or 2, the job process is executed when the system is idle (set IDLE_PRIORITY_CLASS as specified in Windows).

  • If the specified value is 3, the job process is executed as a general process (set NORMAL_PRIORITY_CLASS as specified in Windows).

  • If the specified value is 4 or 5, the job process is executed prior to the threads of processes assigned any of the above priority classes (set HIGH_PRIORITY_CLASS as specified in Windows).

For UNIX, the default nice value is the nice value of the JP1/AJS3 service that executed jajs_spmd. If no specific value is set for the nice value, 20 is assumed for the nice value.

When the specified value is 1 and the nice value is 20, the priority value is determined as follows:

39 [Figure] 20 (initial value) + 20 (increment)

If the value exceeds the range of the nice value (0 to 39), the maximum value is 39, and the minimum value is 0.

-sc target-file-name

For Windows, specify the name of an executable file on the agent host which will execute the job. For UNIX, specify the name of a script file on the agent host which will execute the job.

You can specify a character string of 1 to 511 bytes. You can use either an absolute or relative path to specify the file name. If you specify a relative path, the system assumes it to be a relative path from the work path for job execution or the path specified by the PATH environment variable. An effective value of the PATH environment variable differs, depending on the operating system of the job-executing host.

For a Windows host

System environment variable

For a UNIX host

PATH environment variable for job-executing OS users

The name of any execution file containing a space character must be enclosed in double quotation marks ("). For example, the aaa bbb name must be specified as follows: "aaa bbb".

In Windows, if you execute a file whose extension is not EXE, COM, CMD, or BAT, and whose file name contains a space character, you must enclose the file name by double quotation marks (") and (\").

For example

jpqjobsub -q q1 -sc "\"C:\PROGRAM FILES\HITACHI\SCRIPT\DATA\EXIT_0.SPT\""

-arg "arguments..."

Set an argument for the target file.

You can specify a character string of 1 to 1,023 bytes.

You can specify multiple arguments separated by at least one space character.

-w work-path-name

Specify the name of the work path (current path) for job execution using an absolute path.

You can specify a character string of 1 to 511 bytes. By default, the system assumes the following directory:

Windows

Work holder for agent process execution that is set in the agent's environmental setting

UNIX

Home directory of the job-executing user

-shl shell-path-name

Specify the full path of a job's startup shell.

You can specify a character string of 1 to 511 bytes.

As the startup shell, specify a shell that can be used to execute the script file in UNIX.

The startup shell specified in this option is used if an execution shell is not specified on the first line of the script file. The execution shell is also used to execute the script file in UNIX as if it were a startup shell. However, the shell specified on the first line of the script file is called the execution shell. If the execution shell is specified on the first line of the script file, the startup shell specified in this option is ignored.

If neither a startup shell nor an execution shell is specified, the login shell for the OS user who executes the command (contents of the /etc/passwd file on the agent host) is used. If a login shell is not defined either, /bin/sh is used.

-res execution-locked-resource-name

To disable concurrent execution of multiple submit jobs, set the same execution-locked resource name for each submit job.

You can specify a character string of 1 to 63 bytes.

For details about execution-locked resources, see 10.4.1(7) Exclusive control when executing submit jobs (execution-locked resource) in the manual JP1/Automatic Job Management System 3 Overview.

-st execution-start-time

Set the local time for the command executing host at which execution of the submit job starts. If you specify a past time, the system assumes that you specify no time at which execution of the submit job starts (the submit job is placed into the waiting or running status immediately after being registered.)

You can specify the date and time in any of the following five formats:

  1. YYYY/MM/DD.hh:mm:ss

    If you register a submit job after the specified time, the system immediately places the submit job into the waiting or running status.

  2. day-of-week.hh:mm:ss

    If you register a submit job after the specified time on the specified day of the week, the system immediately places the submit job into the waiting or running status.

  3. hh:mm:ss

    If you register a submit job after the specified time, the system immediately places the submit job into the waiting or running status.

  4. YYYY/MM/DD

    The system assumes 00:00:00 on the specified day as the time at which execution of the submit job starts. If you submit a job after 00:00:00 on the specified day, the system immediately places the job into the waiting or running status.

  5. n

    The system places the submit job into the waiting or running status n days after the day on which the submit job is registered.

The following describes the meaning of each value:

  • YYYY

    Specify a year. You can specify 1980 to 2038.

  • MM

    Specify a month. You can specify 01 to 12.

  • DD

    Day. You can specify 01 to 31.

  • hh

    Specify hours. You can specify 00 to 23.

  • mm

    Specify minutes. You can specify 00 to 59.

  • ss

    Seconds. You can specify 00 to 59.

  • day-of-week

    You can specify sun, mon, tue, wed, thu, fri or sat.

  • n

    Specify the number of days. You can specify 0 to 366 (days).

-el time-out-period

You can use this option to specify the timeout value used to stop execution of a job if the job is unable to terminate. Specify in minutes a relative time from execution-start-time.

You can specify 1 and 1,440 minutes.

-si standard-input-file-name

Specify the name of the standard input file used for executing the job (the name of the standard input file existing on the agent host on which the job is executed).

You can specify a character string of 1 to 511 bytes. You can use either an absolute or relative path to specify the file name. If you specify a relative path, the system assumes it to be a relative path from the work path for job execution.

-rs {q|h|d}

Specify how the job is to be handled if the manager host cannot receive a job end notification because a problem has occurred on the agent host on which the job is being executed or because the agent process has terminated abnormally. By default, the system holds the job.

  • q

    Makes the job wait to be executed.

  • h

    Holds the job.

  • d

    Kills the job.

-so

Enables you to use the jpqjobget command to acquire job execution data in the standard output file after the execution of the job.

-son standard-output-file-name

To overwrite the standard output file created in the agent host with job information, specify the file name.

You can specify a character string of 1 to 511 bytes. You can use either an absolute or relative path to specify the file name. If you specify a relative path, the system assumes it to be a relative path from the work path for job execution.

For notes for defining the standard output file name, see 7.10.1 Notes on the standard output file and standard error output file in the JP1/Automatic Job Management System 3 System Design (Work Tasks) Guide.

-soa standard-output-file-name

To add job information to the standard output file created in the agent host, specify the file name.

You can specify a character string of 1 to 511 bytes. You can use either an absolute or relative path to specify the file name. If you specify a relative path, the system assumes it to be a relative path from the work path for job execution.

For notes for defining the standard output file name, see 7.10.1 Notes on the standard output file and standard error output file in the JP1/Automatic Job Management System 3 System Design (Work Tasks) Guide.

-se

Enables you to use the jpqjobget command to acquire job execution data in the standard error output file after the execution of the job.

-sen standard-error-output-file-name

To overwrite the standard error output file created in the agent host with error job information, specify the file name.

You can specify a character string of 1 to 511 bytes. You can use either an absolute or relative path to specify the file name. If you specify a relative path, the system assumes it to be a relative path from the work path for job execution.

For notes for defining the standard error output file name, see 7.10.1 Notes on the standard output file and standard error output file in the JP1/Automatic Job Management System 3 System Design (Work Tasks) Guide.

-sea standard-error-output-file-name

To add error job information to the standard error output file created in the agent host, specify the file name.

You can specify a character string of 1 to 511 bytes. You can use either an absolute or relative path to specify the file name. If you specify a relative path, the system assumes it to be a relative path from the work path for job execution.

For notes for defining the standard error output file name, see 7.10.1 Notes on the standard output file and standard error output file in the JP1/Automatic Job Management System 3 System Design (Work Tasks) Guide.

-ev environment-variable-file-name

When you use an environment variable file, specify one existing on the agent host.

You can specify a character string of 1 to 511 bytes. You can use either an absolute or relative path to specify the file name. If you specify a relative path, the system assumes it to be a relative path from the work path for job execution.

For notes on defining environment variables see A. Notes on Defining Environment Variables and an Environment Variable File.

-env environment-variable-name=value

Set an environment variable.

When specifying environment variables, use the following precautions:

You can specify multiple -env options by using one or more space characters to separate each option specification (-env environment-variable-name=value). Note that the total length of the environment-variable-name=value specifications must not exceed 20 KB.

If the same environment variable as set with this option is defined in the environment variable file, the contents set with this option are valid.

  • You can specify multiple environment variables.

    The following shows an example specification of the -env option and how to calculate the total number of bytes:

    Example for specifying the -env option

    -env[Figure]a=1[Figure]-env[Figure]b=2[Figure]-env[Figure]C=3

    Legend:

    [Figure]: One-byte space character

    How to calculate the total number of bytes

    In this example, the total number of bytes (13 bytes) is calculated by adding two bytes to the sum of the number of bytes for the underlined sections.

For notes on defining environment variables see A. Notes on Defining Environment Variables and an Environment Variable File.

-h

Holds a submit job when it is registered.

-t transfer-source-file-name [=transfer-destination-file-name]

If you reference the file related to job execution, specify the name of the file to be transferred. Specify the file name used in the transfer destination if needed. It is required, however, during linkage with JP1/NQSEXEC and JP1/OJE for VOS3.

For transfer-source-file-name, specify a file that exists on the host from which the job is submitted. The transfer source file is transferred to an agent host, JP1/NQSEXEC host, or JP1/OJE for VOS3 host as a file with the name specified for transfer-destination-file-name. If you specify a transfer destination file name, the transfer destination file will not be deleted after the end of job execution.

You can specify a character string of 1 to 511 bytes for the transfer destination file. You can use either an absolute or relative path to specify the file name. If you specify a relative path, the system assumes it to be a relative path from the work path for job execution. If you omit the name of a transfer destination file, the system assumes the $JP1AJS2_JPQTEMPxx$ variable, where the xx part shows the transfer file's number, ranging from 01 to 32. If you specify this variable in the -arg option, there is no need to be concerned about the transfer destination file name when you use the file. After the job is executed, the transfer destination file that has been created temporarily is deleted.

For a UNIX host, you can also specify this variable in the -sc option to execute the job. For a Windows host, you cannot specify this variable in the -sc option. If the variable is specified, it will be impossible to start the job.

You can specify up to 32 options (including the -td option) at the same time.

Also see the explanation for the -td option.

-td transfer-source-file-name [=transfer-destination-file-name]

If you reference the file related to job execution, specify the name of the file to be transferred. (Specify the file name used in the transfer destination if needed.) Unlike the -t option, this option deletes the transfer destination file in the destination host after the end of job execution.

For transfer-source-file-name, specify a file that exists on the host from which the job is submitted. The transfer source file is transferred to an agent host as a file with the name specified for transfer-destination-file-name.

You can specify a character string of 1 to 511 bytes for the transfer destination file. You can use either an absolute or relative path to specify the file name. If you specify a relative path, it becomes a path relative to the work path for job execution. If you omit the name of a transfer destination file, the system assumes the $JP1AJS2_JPQTEMPxx$ variable, where the xx part shows the transfer file's number, ranging from 01 to 32. If you specify this variable in the -arg option, there is no need to be concerned about the file name for the transfer destination when you use the file. After the job is executed, the transfer destination file that has been created temporarily is deleted.

For a UNIX host, you can also specify this variable in the -sc option to execute the job. For a Windows host, you cannot specify this variable in the -sc option. If the variable is specified, it will be impossible to start the job.

You can specify up to 32 options (including the -t option) at the same time.

Notes

  1. Do not specify redirection for a command argument. To output the standard output file, specify the -so, -son, or -soa option. To output the standard error output file, specify the -se, -sen, or -sea option. You cannot acquire job information correctly if you specify redirection with the above options.

  2. When you execute multiple jobs simultaneously on a single agent host, do not specify the same name for the standard output file, standard error output file, and transfer destination file name. Otherwise, the specified file may get corrupted, preventing the job from being executed.

  3. If a file of several megabytes is transferred either during job registration or as the result of job information collection, the transfer may fail or take time.

  4. You can specify only text files for the standard input file, the standard output file, the standard error output file, and transfer files.

  5. JP1/AJS3 converts character codes when a file is transferred from the manager host to the agent host. It also converts character codes when a result file (standard input file, standard output file, or standard error output file) is transferred from the agent host to the manager host. In both cases, the character codes of the JP1/AJS3 service at the transfer destination are converted, rather than the character codes of the user who executed the command.

    As an example, suppose you start the JP1/AJS3 service on a manager host that uses Shift-JIS and start the JP1/AJS3 service on an agent host that uses EUC, and then create a transfer file in Shift-JIS on the manager host. When you transfer the file to the agent host, the file will be created as a EUC file.

    For details about the settings for character encoding in JP1/AJS3, see the description about how to change the character code set in 13.4.1 Setting the language environment in the manual JP1/Automatic Job Management System 3 Configuration Guide.

  6. For details about the characters that can be used in the data contained in the standard input file, standard output file, standard error output file, or in a transfer file, see 2.4.2(7)(a) Available characters in the JP1/Automatic Job Management System 3 System Design (Configuration) Guide.

  7. The following gives the options you can specify for linkage with JP1/NQSEXEC or JP1/OJE for VOS3. The other options are ignored even if they are specified.

    -mh

    -q

    -jn

    -pr (Only with JP1/NQSEXEC linked)

    -sc

    -arg

    -so (Only with JP1/NQSEXEC linked)

    -se (Only with JP1/NQSEXEC linked)

    -h (Only with JP1/NQSEXEC linked)

    -t

Return values

0

Normal end

1

Invalid parameter value

2

An attempt to register a submit job failed due to an internal cause of the host on which a submit was requested.

5

Initialization has failed.

  • The definition of the logical host name or the common definition information contains an error.

6

Memory became insufficient on the host on which a submit was requested.

7

A logical error occurred on the host on which a submit was requested.

8

As the transfer source file or its file path does not exist, you cannot open the file.

9

As you do not have the privilege required to access the transfer source file, you cannot open it.

10

As the transfer source file is used by another process, you cannot open it.

11

You cannot open the transfer source file owing to a cause other than return values 8, 9 and 10.

12

The transfer source file could not be loaded successfully owing to a cause other than return values 8, 9 and 10.

100

The manager host cannot be connected for TCP/IP communication.

  • As TCP/IP is not validly set, the manager host cannot be connected.

  • The manager host name is invalid, or the manager host process stopped.

102

The IP address could not be solved successfully by the manager host name.

200

The manager host does not accept the submit job registered.

  • The manager host is now being started, now being stopped, has stopped, or is running in the reduced-operation mode.

201

You cannot use a specified queue.

  • The specified queue is not found.

202

No response from the manager host

203

The submit job could not be registered successfully due to an internal cause of the manager host.

204

The specified queue is closed.

205

As the number of submit jobs in the specified queue has reached the limit, no more submit jobs can be registered.

206

You do not have the privilege required to submit a job.

219

The manager host is busy.

220

Insufficient manager host memory

221

Invalid user information about JP1/OJE for VOS3

222

A fatal error has occurred.

  • A system call error has occurred.

223

The manager host encountered a logic error.

225

An error occurred after the submit job was registered.

(Registration of the submit job terminated normally. However, because the destination manager host did not return a job number, the result was that hold, cancellation, or other such operations that use the job number could not be performed for the job.)

226

Invalid execution environment

227

Job information having the same ID already exists in the job execution environment database.

228

The transfer destination file could not be created successfully in the manager host.

229

The transfer destination file could not be written successfully in the manager host.

241

Failed to automatically define the agent.