8.3.7 adshexec command (executes a batch job)
Syntax
- To run normally
-
adshexec [-v] [-c] [-m {EXTENDED|SIMPLE|MINIMUM}] [-t [-f] [-o asc-file-path-name]] [-h logical-host-name] [-s {SPOOL|PARENT}] [-x] {-r command-line|job-definition-script-file-path-name} [run-time-parameters]
- To start in the debugger mode (UNIX only)
-
adshexec -d [-v] [-c] [-m {EXTENDED|SIMPLE|MINIMUM}] [-t [-f] [-o asc-file-path-name]] [-h logical-host-name] [-x] job-definition-script-file-path-name
Description
This command launches the job controller to execute the batch job in the job definition script file specified in an argument. You can also execute commands that would be specified in a job definition script file by directly specifying those commands in the -r option.
The command's arguments are specified before the values to be passed to the job definition script's positional parameters.
Arguments
- -d (UNIX only)
Specifies that the job controller is to be started in the debugger mode. This option can be used in a UNIX environment. In the debugger mode, coverage information is collected in memory and continues to be collected each time the run command is executed. The coverage information stored in memory can be displayed by the info coverage command.
If the -t option is not specified, the coverage information collected in memory is discarded when you terminate the debugger with the quit command.
Job definition script operation information is not collected when the -d option is specified.
- -v
Specifies that version information is to be displayed; no batch job is executed.
- -c
Specifies that the job definition script file's syntax is to be checked.
Only syntax checking is performed; no batch job is executed.
- -m {EXTENDED|SIMPLE|MINIMUM}
Specifies how to output the standard output and the standard error output of the job that is to be started. For details about the output modes, see 3.4.4 Suppressing output of information and warning messages to job execution logs.
EXTENDED
Use the expansion output mode.
SIMPLE
Use the simple output mode.
MINIMUM
Use the minimum output mode.
If this option is omitted, the specifications of the OUTPUT_MODE_ROOT and OUTPUT_MODE_CHILD parameters take effect.
This option applies only to the job that is started with the adshexec command and is not inherited by jobs that are started from that job. For a job that is started separately, specify the -m option again in the adshexec command that you use to start the job.
If the root job is run in the simple output mode or the minimum output mode, the standard output is not redirected to a spool file even when the -s option is specified or SPOOL is specified in the OUTPUT_STDOUT environment setting parameter.
If you use the -r option, also specify -m SIMPLE or -m MINIMUM to avoid job execution logs from being mixed together with the output results.
- -t
Specifies that coverage information is to be collected while the batch job executes and the collected coverage information is to be output to an asc file when the command terminates.
If the -t option is not specified when the debugger mode is started in UNIX, the coverage information is collected in memory only (however, it can be displayed with the debugger's info coverage command). When you terminate the debugger with the quit command, the collected coverage information is discarded.
- -f
Specifies that if coverage information has already been collected, the existing asc file is to be overwritten when differences are detected between the job definition script file to be executed and the backup information. The -f option can be specified only when the -t option is also specified.
- When this option is specified
If coverage information has already been collected and differences are detected between the job definition script file to be executed and the backup information, the backup information is discarded and new coverage information is collected.
If no coverage information has been collected, the newly collected coverage information is output to an asc file.
- When this option is not specified
If coverage information has already been collected and differences are detected between the job definition script file to be executed and the backup information, a command error occurs and the job definition script file is not executed. The asc file is not updated.
- -o asc-file-path-name
Windows: ~<path name>((1 to 229 bytes))
UNIX: ~<path name>((1 to 1,005 bytes))
Specifies the path name for the asc file to be used for collection of coverage information, when you want to use a different file from the existing asc file. The -o option can be specified only when the -t option is also specified.
Omitting this option is equivalent to specifying the asc file in the current directory when the adshexec command is executed. The following shows the format of an asc file name:
name-of-job-definition-script-without-extension_user-name.asc
In the example below, the adshexec command is executed under the following conditions:
Current directory when the adshexec command is executed: /home/user1/test
User name: user1
Name of job definition script: script1.ash
The name of the asc file when the -o option is omitted is as follows:
/home/user1/test/script1_user1.asc
- -h logical-host-name ~<logical host name>((1 to 255 bytes))
Specifies the name of the logical host to be used for execution on a logical host. In Windows, the length of the logical host name must not exceed 196 bytes, and it is recommended that it not exceed 63 bytes. If you specify a name that exceeds 63 bytes, the command might not function correctly.
If an empty string is specified for logical-host-name, the value specified in the JP1_HOSTNAME environment variable is assumed. If the JP1_HOSTNAME environment variable is not set, the KNAX0220-E message is output and the command terminates. For details about the JP1_HOSTNAME environment variable, see the JP1/Base User's Guide.
Do not specify this option when running on the physical host.
- -s {SPOOL|PARENT}
Specifies the destination for the standard output from the root job. child jobs assume that PARENT was specified in this option.
If this option is omitted, the root job assumes the value specified in the OUTPUT_STDOUT parameter. If the root job is run in the simple output mode or the minimum output mode, the standard output is not redirected to a spool file, regardless of this option.
SPOOL
Output the standard output from the root job to a file on the spool.
PARENT
Output the standard output from the root job to the destination inherited from the parent process when the process starts. Assuming the destination is not later redirected in the parent process, output goes to the same destination as for the parent process.
- -x
Enables the xtrace shell option.
You can disable the xtrace shell option by executing set +x or set +o xtrace in the job definition script.
- -r command-line
Specifies what is to be executed from the command line. In command-line, you can specify any commands that can be specified in a job definition script, such as standard shell commands and UNIX-compatible commands. Make sure that the command-line specification does not exceed the maximum length permitted for a line of a job definition script (8,191 bytes).
If this option is specified together with the -v option, the -v option takes effect.
- In UNIX:
This argument cannot be specified together with the -c, -d, or -t option. An error results if this argument is specified together with any of these options.
- In Windows:
This argument cannot be specified together with the -c or -t option. An error results if this argument is specified together with either of these options.
For details, see 3.2.4 Specifying what is to be executed by a job from the command line.
- job-definition-script-file-path-name
Windows: ~<path name>((1 to 247 bytes))
UNIX: ~<path name>((1 to 1,023 bytes))
Specifies the path name of the job definition script file that is to be run.
- run-time-parameters ~<any character string>((1 to 1,022 bytes))
Specifies values to be stored in the positional parameters of the job definition script. If a run-time parameter includes a space, you must enclose that string in double quotation marks (").
Return codes
Trigger |
Return code |
|
---|---|---|
-c option specified |
-c option not specified |
|
Normal execution of the exit command or of the return command from an outside function |
Return code specified in the command |
-- |
Normal execution of an external command by specifying it in the argument to the exec command |
Return code of the external command specified in the argument |
-- |
Normal execution of the job definition script through the end of the job definition script file |
Return code of the most recently executed standard shell command or extended script command |
-- |
No errors in the job controller in the debugger mode |
0 |
-- |
No syntax errors in the job definition script file or initialization script file |
The job definition script is executed, with the following return code:
|
0 |
Syntax error in the job definition script file |
1 or the value set in the ADSH_JOBRC_FATAL environment variable |
1 or the value set in the ADSH_JOBRC_FATAL environment variable |
Syntax error in the initialization script file |
1 or the value set in the ADSH_JOBRC_FATAL environment variable |
-- |
An error in the job controller, except for an error in executing the job definition script, such as an error in reading an environment file |
1 or the value set in the ADSH_JOBRC_FATAL environment variable |
1 or the value set in the ADSH_JOBRC_FATAL environment variable |
The initialization script file does not exist. Alternatively, the permission required for the job controller to execute the initialization script file is not assigned to the initialization script file. |
1 or the value set in the ADSH_JOBRC_FATAL environment variable |
-- |
Executed the forced termination of JP1/AJS.# [Only for UNIX] |
143 |
143 |
The job controller process receives a signal and terminates (UNIX only). |
128 + signal number |
128 + signal number |
The job controller process is forcibly terminated from outside, for example from JP1/AJS or the Windows Task Manager (Windows only). |
Return code specified by the program that forcibly terminated the job controller |
Return code specified by the program that forcibly terminated the job controller |
Failure to start the job controller for a reason attributable to the OS (Windows only) |
1 to 3 |
1 to 3 |
A parsing error occurred in the ADSH_JOBRC_FATAL environment variable. |
255 |
255 |
An invalid value is specified for the ADSH_LINK_SUPPORT environment variable (only for Windows) |
255 |
255 |
- Legend:
--: Does not apply because the job definition script is not executed.
- #:
-
If you define a job with the "command statement" of UNIX job, the return code of the job that can be referenced by JP1/AJS becomes -1.
Notes
If the same option is specified more than once, the last specification takes effect.
When -v and -c are specified together with any other options, they are handled in descending order of priority. The priority order is -v, then -c, and then the other options. Lower priority options are ignored.
Example
The -d option is ignored, only -v takes effect.
$ adshexec -v -d MyShell.ash
Collecting coverage information without specifying the -o option can result in duplication of asc file names. This duplication occurs in the situations listed below. To avoid duplicate asc file names, change the name of the job definition script file or the name of the asc file.
You collect coverage information from multiple job definition scripts whose file names differ only in their extensions
Example: sc.1 and sc.2
You collect coverage information from multiple job definition scripts with the same name but in different directories
Example: /dir1/sc1 and /dir2/sc1
Do not specify file names that begin with . (dot).
Do not use a reserved device name (such as CON, AUX, and NUL) as a file name. (Windows only)
Do not use an NTFS stream as a file name. (Windows only)
You cannot specify run-time parameters when the -d option is specified. Specify the run-time parameters in an argument of the run command.
Access permissions for asc files are set as follows:
The owner (creator) of a file is granted r (read) and w (write) access permissions regardless of the umask settings. Group and general access permissions are set according to the umask settings at the time the command is invoked. (UNIX only)
In principle, execution users are granted Full Control access permissions over their own asc files. However, actual file access permissions are affected by permission inheritance in Windows (inheritance of permissions from higher-level directories). Similarly, access permissions for other users obey Windows permissions inheritance (inheritance of permissions from higher-level directories). (Windows only)
File descriptors are closed without being inherited by adshexec commands that are generated as child processes. For example, an error results if the job definition script of a child process attempts to perform I/O using a file descriptor opened by a parent process without first reopening it. Standard output and standard error output do not need to be reopened. (Windows only)
Examples
Start the job controller in the syntax checking mode.
adshexec -c /home/user/shell/JOB.ash
Start the job controller in the debugger mode.
adshexec -d /home/user/shell/JOB.ash
Display version information for the job controller without executing a batch job.
adshexec -v
Specify run-time parameters to be passed to the positional parameters of the job definition script and start the job controller.
adshexec /home/user/shell/JOB.ash parm1 parm2
Collect coverage information.
adshexec -t /home/user/shell/JOB.ash
If the contents of the job definition script file have been modified, discard the coverage information collected so far and collect new coverage information.
adshexec -t -f /home/user/shell/JOB.ash
Collect coverage information and store it in /home/user/JOB.asc.
adshexec -t -o /home/user/JOB.asc /home/user/shell/JOB.ash
Enable the xtrace shell option and start the job controller.
adshexec -x /home/user/shell/JOB.ash
Start the job controller with a command specified in command-line in the -r option that is to be executed in the job.
adshexec -r "ls *"
Start the job controller with a positional parameter that is referenced in command-line in the -r option specified in the runtime parameters.
This example specifies a command in the job definition script file. command-line must be enclosed in single quotation marks (') because it specifies a positional parameter.
adshexec -r 'cat $1 | grep $2' file.txt abc
Start the job controller with a command that handles file paths specified in command-line in the -r option.
This example specifies a command in the job definition script file.
adshexec -r 'cat "C:\\Documents and Settings\\user001\\file.txt"'