5.1.11 Specifying external commands

Programs that are not built-in commands in job definition scripts are referred to collectively as external commands. External commands include UNIX-compatible commands, OS-provided commands, and user-created programs. You can execute external commands by specifying their command names in the job definition scripts.

The following show how to specify an external command:

$ path-of-external-command

Organization of this subsection

(1) Executing external commands in Windows
(2) Executing external commands in UNIX
(3) Priority of command execution methods
(4) Priority of child jobs or external commands that have the same name as the function

(1) Executing external commands in Windows

(a) Defining the extensions of external commands

In Windows, you can execute executable files with the extensions .com, .exe, .cmd, and .bat from job definition scripts. If you register these extensions in the PATHEXT shell variable, you can execute such executable files from job definition scripts without having to specify their extensions.

External commands are executed from a job definition script in the order that the extensions are registered in the PATHEXT environment variable. For example, if the value of the PATHEXT environment variable is .COM;.EXE;, and ls.com and ls.exe are stored at the locations indicated by the PATH shell variable, ls.com is executed first.

An example search for an external command is shown below. In this example, the value of the PATHEXT environment variable is .COM;.EXE;.

ls      <-- Because no extension is specified, the extensions .com and .exe are added in this order to locate and execute the corresponding external command.
ls.exe  <-- ls.exe is executed because the extension is specified.

(b) Skipping processes before executing external commands

Before JP1/Advanced Shell executes an external command, it performs the processing explained below on the path and arguments of the external command. If this processing is not needed, execute the external command with the -w option specified in the command command.

Converts a backslash (\) preceding a double quotation mark (") to \\.
Adds a backslash \ in front of a double quotation mark (").
Encloses in double quotation marks (").

For details about the -w option of the command command, see command command (executes a command) in 9.3 Standard shell commands.

Example:

command -w ."\\prog.exe" "ABC"

(c) Limitations on batch file execution

The following limitations apply to batch file execution:

When there is no argument

If a batch file path contains any of the special characters &, (, ), [, ], {, }, ^, =, ;,!, ', +, ,, `, and ~, specify it in the format <cmd.exe-path> /c <batch-file-path> and then escape the special character in the batch file path by using "'\.
When there are arguments

All the following limitations apply;
- Specify a batch file in the format <cmd.exe-path> /c <batch-file-path> <argument-1> <argument-2> ... <argument-n>.
- If a batch file path contains any of the special characters &, (, ), [, ], {, }, ^, =, ;,!, ', +, ,, `, and ~, use "'\ to escape the special character in the batch file path.
- If an argument contains a space or any of the special characters &, (, ), [, ], {, }, ^, =, ;,!, ', +, ,, `, and ~, use "'\ to escape the space or special character.
- Arguments enclosed in double quotation marks (") are passed to the batch file. The last argument has a double quotation mark (") only at the beginning. To reference arguments from a batch file, use the formats %~1, %~2, ...%~n to automatically remove the double quotation mark (").

To Page Top

(2) Executing external commands in UNIX

You can execute an executable binary file with execution permissions granted from a job definition script.

You can also execute a text file with execution permissions granted from a job definition script by specifying #!executable-program-path at the beginning of the file. In this case, the executable program is executed according to the specification of #!.

To Page Top

(3) Priority of command execution methods

When the job controller executes a file specified in a job definition script, it checks the conditions listed below in the order shown here.

Windows only

If the file satisfies the CHILDJOB_PGM parameter condition, the job controller executes the file as a child job.
If the file satisfies the CHILDJOB_SHEBANG parameter, the job controller executes the file as a child job.
If the file satisfies the default definition for the CHILDJOB_SHEBANG parameter, the job controller executes the file as a child job.
If the file satisfies the CHILDJOB_EXT parameter, the job controller executes the file as a child job.
If the file has the extension exe, bat, cmd, or com, the job controller executes the file as a command.
If none of the above conditions is satisfied, startup of the command fails. However, job execution continues.

UNIX only

If the file satisfies the CHILDJOB_PGM parameter condition, the job controller executes the file as a child job.
If file execution permissions have been granted, the job controller performs the checks beginning with 3. If execution permissions have not been granted, startup of the command fails and the command terminates with an error. However, job execution continues.
If the file satisfies the CHILDJOB_SHEBANG parameter condition, the job controller executes the file as a child job.
If the file satisfies the default definition for the CHILDJOB_SHEBANG parameter, the job controller executes the file as a child job.
If the file satisfies the CHILDJOB_EXT parameter condition, the job controller executes the file as a child job.
If the file is a binary file, the job controller executes the file as a command.
If the file is a text file, the job controller executes the file as a script. If #! is specified, the job controller executes the executable program specified in #!. If #! is not specified, the job controller executes the file with /bin/sh.

The following examples use parameters related to child jobs (test.sh exists and execution permissions have been granted).

Example 1:

Contents of the environment file

#-adsh_conf CHILDJOB_PGM /bin/sh
#-adsh_conf CHILDJOB_SHEBANG /bin/ksh
#-adsh_conf CHILDJOB_EXT sh

Contents of test.sh

#!/bin/ksh
echo JP1AS

Contents of the job definition script

/bin/sh ./test.sh

[Figure] The CHILDJOB_PGM parameter is applied and test.sh is executed as a child job.

Example 2:

Contents of the environment file

#-adsh_conf CHILDJOB_PGM /bin/sh
#-adsh_conf CHILDJOB_SHEBANG /bin/ksh
#-adsh_conf CHILDJOB_EXT sh

Contents of test.sh

#!/bin/ksh
echo JP1AS

Contents of the job definition script

./test.sh

[Figure] The CHILDJOB_SHEBANG parameter is applied and test.sh is executed as a child job.

Example 3:

Contents of the environment file

#-adsh_conf CHILDJOB_PGM /bin/sh
#-adsh_conf CHILDJOB_SHEBANG /bin/ksh
#-adsh_conf CHILDJOB_EXT sh

Contents of test.sh

#!/bin/sh
echo JP1AS

Contents of the job definition script

./test.sh

[Figure] The CHILDJOB_EXT parameter is applied and test.sh is executed as a child job.

Example 4:

Contents of the environment variable

#-adsh_conf CHILDJOB_PGM /bin/sh
#-adsh_conf CHILDJOB_SHEBANG /bin/ksh
#-adsh_conf CHILDJOB_EXT sh

Contents of test.sh

#! /opt/jp1as/bin/adshexec
echo JP1AS

Contents of the job definition script

./test.sh

[Figure] test.sh is executed as a child job because it satisfies the default definition for the CHILDJOB_SHEBANG parameter.

Example 5:

Contents of the environment file

#-adsh_conf CHILDJOB_PGM /bin/sh
#-adsh_conf CHILDJOB_SHEBANG /bin/ksh
#-adsh_conf CHILDJOB_EXT sh

Contents of test.sh

#!/bin/ksh
echo JP1AS

Contents of the job definition script

/bin/ksh ./test.sh

[Figure] Because none of the CHILDJOB_EXT, CHILDJOB_PGM, CHILDJOB_SHEBANG, and CHILDJOB_SHEBANG parameters' default definitions apply, test.sh is executed with /bin/ksh, not as a child job.

Example 6:

Contents of the environment variable

#-adsh_conf CHILDJOB_PGM /opt/jp1as/bin/adshexec
#-adsh_conf CHILDJOB_SHEBANG /bin/ksh
#-adsh_conf CHILDJOB_EXT sh

Contents of test.sh

#!/bin/ksh
echo JP1AS

Contents of the job definition script

/opt/jp1as/bin/adshexec ./test.sh

[Figure] The CHILDJOB_PGM parameter is applied and test.sh is executed as a child job.

Example 7:

Contents of the environment file

#-adsh_conf CHILDJOB_PGM ./test.sh
#-adsh_conf CHILDJOB_SHEBANG /bin/ksh
#-adsh_conf CHILDJOB_EXT sh

Contents of test.sh

#!/bin/ksh
echo JP1AS

Contents of the job definition script

./test.sh

[Figure] According to the order or condition check, the CHILDJOB_PGM parameter is checked. Because the CHILDJOB_PGM parameter definition is satisfied, the corresponding replacement is performed. However, because the file to be executed as a child job is not specified, an execution error results.

To Page Top

(4) Priority of child jobs or external commands that have the same name as the function

The following is the priority of child jobs or external commands that have the same name as the function:

If the function has already been defined in the main script or the function definition file has been loaded by #-adsh_script or a . (dot) command, the function always takes effect.
If the function has the automatic loading attribute and the directory specified in the FPATH shell variable contains a function definition file with the same name as the function, the function takes effect.
If the function does not have the automatic loading attribute but the directory specified in the FPATH shell variable contains a function definition file with the same name as the function, the following conditions are checked in this order:
1. If the directory specified in the FPATH shell variable contains a job definition script with the same name as the function or an external command, the child job or the external command is executed.
2. If the directory specified in the FPATH shell variable does not contain a corresponding job definition script or external command, the function is executed.
If neither the directory specified in the PATH environment variable nor the directory specified in the FPATH shell variable contains a corresponding file, the processing terminates with an error because there is no command to be executed.

To Page Top