9.5.7 #-adsh_script command (calls an external job definition script file from the job definition script that is running)

Syntax

#-adsh_script job-definition-script-file-name

Description

This command inserts the contents of an external job definition script file at the time the job controller was launched into the currently-running job definition script file. You can call a maximum of 4,095 external job definition script files from a job definition script that is running. An external script that is called is unpacked within the job definition script that contains the calling function. That job definition script is then parsed and executed as a single job definition script.

Arguments

job-definition-script-file-name

Windows: ~<path name>((1 to 247 bytes))

UNIX: ~<path name>((1 to 4,096 bytes))

Specifies the path of the job definition script file that to be deployed. If you specify a relative path, it is interpreted relative to the current directory at the time the job controller was launched.

Return codes

Note:

You cannot use an environment setting parameter to change the return code when the #-adsh_script command terminates normally.

Whether the #-adsh_script command terminates normally or with an error depends on whether the external job definition script file is inserted correctly. It does not depend on whether commands executed within the inserted external job definition script file terminated normally or with errors.

Notes

• This command differs from the standard shell . (dot) command in the following respects.

  • The . (dot) command executes the external script when the job definition script is executed. The #-adsh_script command executes the external script when the job definition script is parsed. You must not change the external script between the time the job definition script is parsed and the time it is executed.

  • The . (dot) command treats any extended script commands in the external script as comments. The #-adsh_script command is able to execute extended script commands contained in the external script.

  • If you execute the #-adsh_script command from an external script executed by another #-adsh_script command, do not call the same external script more than once.

  • The contents of an external script called by the . (dot) command are not output to the script image. The contents of an external script called by the #-adsh_script command are output to the script image.

  • If you specify an external script with a path that is relative to the . (dot) command, it resolves the path with reference to the value of the PATH environment variable. If you specify an external script with a path that is relative to the #-adsh_script command, it is interpreted as a path relative to the current directory when adshexec is started, without reference to the value of the PATH environment variable.

  • There is no limit to the number of times the . (dot) command can be used in a job. The #-adsh_script command can be used no more than 4,095 times in a job.

  • The . (dot) command allows you to specify arguments to the external script. The #-adsh_script command does not allow you to specify arguments to the external script.

• Do not specify a file name that begins 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)

• Normal termination of this command cannot be used to identify the termination status (normal or error) of the job or job step. Refer instead to the execution results of the external script that was called.