adshexec command (executes a batch job)

Format

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

To Page Top

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.

To Page Top

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.3.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 Job Management Partner 1/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 (").

To Page Top

Return codes

To Page Top

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)

To Page Top

Usage 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"'

To Page Top