Chapter 7: Command Jobs

Chapter 7: Command Jobs

Command Jobs :

Command jobs let you run workload on UNIX and Windows client computers. On UNIX,
you can define jobs to run scripts and commands. On Windows, you can define jobs to
run command files and batch files.
Note: To run these jobs, your system requires one of the following:
■ CA WA Agent for UNIX, Linux, or Windows
■ Legacy agent for Unicenter AutoSys Job Management 4.5.1 through r11
 Command Jobs


When you define a Command job, you can specify settings including the following:
Starting Conditions
Defines conditions (for example, date, time, job state, and machine state) that must
be met before a job can start.
Disk Space Criteria
Defines the amount of free space required before a process can start. If the free
space is not available, an alarm is sent and the job is rescheduled.

Job Profile
Specifies a script to be sourced that defines the environment where the command
runs.
Note: On Windows, you can define a job profile using the Job Profiles - CA
Workload Automation AE Administrator window in the Administrator utility.

Environment Variables
Specifies variables that define the local environment where the job runs.

User-defined Exit Codes
Defines exit codes to indicate job success and job failure. By default, an exit code of
0 (zero) indicates job success and any other code indicates job failure. When the job
completes, the exit event (either SUCCESS or FAILURE) and program's exit code are
stored in the database.

Standard I/O Files
Specifies the standard input, output, and error files.
Note: To support chained commands (commands separated by a semicolon) on UNIX,
ensure that the oscomponent.wrapper.exec.force parameter in the agentparm.txt file is
set to false (the default). For more information about supporting chained commands,
see the UNIX Implementation Guide.
 The Directory the Job Runs Under

Chapter 7: Command Jobs 219

The Directory the Job Runs Under
The directory that a Command job runs under is determined by the following settings:
oscomponent.initialworkingdirectory Agent Parameter
Specifies the default initial working directory for all scripts. Options are the
following:
■ SCRIPT—Sets the path to where the script resides.
■ USER—Sets the path to the home directory of the owner of the script.
■ PATH—Sets the path to an absolute path to where the script runs.
If you do not specify a value, the parameter defaults to the path where the running
cybAgent resides.
You can specify the oscomponent.initialworkingdirectory parameter in the agent's
agentparm.txt file.

HOME and PWD Environment Variables (UNIX only)
Overrides the oscomponent.initialworkingdirectory default directory. The directory
depends on the following settings:
■ If you specify a value for PWD (Present Working Directory) in the job definition,
the job runs under the PWD you specified.
■ If you specify a value for HOME in the job definition, but you do not specify a
value for PWD, the job runs under the HOME directory.
■ If you specify values for HOME and PWD in the job definition, the job runs
under the PWD directory.

Determining Which Shell is Used (UNIX)
A shell is a program that provides an environment for users to interact with the system.
Shell programs are files that contain a series of user commands that are grouped, using
logic provided by the shell, to accomplish a task.
Shells can be defined by you, the script’s programmer, your agent administrator, and
your UNIX administrator. When you define a job that runs on UNIX, you may want to
know which shell is used to run the script because different shells have different
facilities and characteristics. Some functions are specific to certain shells and may be
incompatible with other shells.
 Shell Initialization Files (UNIX)

220 User Guide

The shell the CMD job uses is determined by the following settings in the following
order:
1. The shell attribute (if specified in the job definition)
2. The oscomponent.defaultshell parameter in the agentparm.txt file (if not specified
in the shell attribute)
3. The user default shell defined in the user profile (if one exists on the computer)
4. On UNIX, the shell sourced from the /etc/auto.profile script (if one is specified)
5. The shell directive line (first line) of the script (if one is specified)

Notes:
■ If the shell is defined in the first line of the script, you do not need to include the
shell attribute in the job definition. The shell attribute tells the agent which shell
interpreter to use when launching the command. When the command executes a
script that specifies a shell, the script runs from that point forward under the shell
specified in the script.
■ If the oscomponent.checkvalidshell parameter in the agent's agentparm.txt file is
set to true (the default), all shells that are used must be specified using the
oscomponent.validshell parameter. The path defined in the first line of the script or
in the job definition must match the corresponding path in the
oscomponent.validshell parameter. If the shell you want to use is not defined on
the agent, the job fails. For more information about specifying valid shells, see the
oscomponent.checkvalidshell and oscomponent.validshell parameters in the CA
Workload Automation Agent for UNIX, Linux, or Windows Implementation Guide.

Shell Initialization Files (UNIX)
When you log in to the UNIX operating system, the operating system reads a series of
initialization files depending on the shell you use.
 Shell Initialization Files (UNIX)

Chapter 7: Command Jobs 221

C Shell Initialization Files
When you log in to the C shell, it automatically runs a number of files. The first file run is
a system file named /etc/.login, which contains system-wide configuration information
(such as your default path). After these files are run, the C shell reads and runs the
commands from the following files in your home directory:
.cshrc
Establishes variables and operands that are local to a specific shell. Each time you
create a new shell, the C shell reinitializes these variables for the new shell.
The following is a sample .cshrc file:
set noclobber
set ignoreeof
set path = (~/bin $path /usr/games)
alias h history
.login
Contains commands that you want to run once at the beginning of each session. If
the C shell is running as a login shell, it reads and runs the commands in the .login
file in your home directory after login.
The following is a sample .login file:
setenv history 20
setenv MAIL /usr/spool/mail/$user
.logout
Runs when you exit from your login shell.

Korn Shell Initialization Files
The Korn shell supports three startup scripts:
/etc/profile
Contains system-wide startup commands. This file is a login script and runs when
you log in.
 Define a Command Job

222 User Guide

$HOME/.profile
Runs when you log in. Use this login script to set options, set the path, and set and
export variable values.
The following is a sample $HOME/.profile file:
set -o allexport
PATH=.:/bin:/usr/bin:$HOME/bin
CDPATH=.:$HOME:$HOME/games
PS1='! $PWD> '
ENV=$HOME/.kshrc
TIMEOUT=0
set +o allexport
The script named in the Korn shell variable ENV
Runs when you create a Korn shell or run a Korn shell script. Use this file to define
aliases and functions and to set default options and variables that you want to
apply to the Korn shell invocation.

Bourne shell initialization files
When you log in to your system, the Bourne shell looks for the /etc/profile file. This file
contains system-wide startup commands for the Bourne shell. Only the system
administrator can change this file.
After running the commands in the /etc/profile file, the Bourne shell runs the
commands in the $HOME/.profile file. Therefore, you can override the system-wide
commands in the /etc/profile file with commands in the $HOME/.profile file.

Define a Command Job
You can define a Command (CMD) job to run workload on UNIX and Windows client
computers. The job can run a script, execute a UNIX command, or run a Windows
command file.
Note: To run these jobs, your system requires CA WA Agent for UNIX, Linux, or
Windows.
Follow these steps:
1. Insert a job and specify the following attributes in the definition:
job_type: CMD
Specifies that the job type is Command.
Note: For backwards compatibility with previous versions of CA Workload
Automation AE, you can specify job_type: c.
 Define a Command Job

Chapter 7: Command Jobs 223

machine
Specifies the name of the machine on which the job runs.

command
Specifies the command, executable, UNIX shell script, application, or batch file
to run when all the starting conditions are met.

2. (Optional) Specify optional Command attributes:
■ blob_file
■ blob_input
■ chk_files
■ envvars
■ fail_codes
■ heartbeat_interval
■ interactive
■ max_exit_success
■ shell
■ std_err_file
■ std_in_file
■ std_out_file
■ success_codes
■ ulimit
3. (Optional) Specify common attributes that apply to all job types.
The Command job is defined.
 Define a Command Job

224 User Guide

Notes:
■ Attributes that have a default value automatically apply to the job definitions;
therefore, they are optional. For example, jobs with no specified job type are
defined as command jobs by default. Other optional attributes specify information
that is not required but affects how or when a job runs, such as attributes that
specify scheduling conditions.
■ Some optional attributes are common to all job types but others apply to certain
jobs types only. Optional attributes that apply to all job types are known as
common optional attributes. For more information about common optional
attributes and the values that you can specify for them (including their default
values when applicable), see the Reference Guide.
■ For information about required attributes and job type specific optional attributes,
see the procedure topics that provide instructions for defining jobs.
■ This guide provides instructions for defining jobs interactively. You also create job
definitions in script files and then import them using the jil command or use CA
WCC to define them. For more information about the JIL command and JIL syntax,
see the Reference Guide. For more information about using CA WCC to define the
job, see the CA Workload Control Center Workload Scheduling Guide.
■ To support chained commands (commands separated by a semicolon) on UNIX,
ensure that the oscomponent.wrapper.exec.force parameter in the agentparm.txt
file is set to false (the default). For more information about supporting chained
commands, see the UNIX Implementation Guide.

Example: Run a Command on UNIX
This example runs the /bin/touch command on the file named /tmp/test_run.out. The
job runs on the UNIX client computer named unixagent.
insert_job: test_run
job_type: CMD /* This attribute is optional for Command jobs. CMD is the default. */
machine: unixagent
command: /bin/touch /tmp/test_run.out
Example: Run a Command File on Windows
This example runs the c:\bin\test.bat command on the Windows client computer named
winagent. The command is enclosed in quotation marks because the path contains a
colon.
insert_job: test_run
job_type: CMD /* This attribute is optional for Command jobs. CMD is the default. */
machine: winagent
command: "c:\bin\test.bat" Attributes with Default Values

Chapter 7: Command Jobs 225

Attributes with Default Values
Attributes that have a default value automatically apply to the job definition. Therefore,
you do not have to specify those attributes in the definition. Your agent administrator
can define some default values on the agent in the agentparm.txt file.
If you specify the attribute in a job definition, it overrides the default.
The following Command job attributes have default values:
fail_codes
Defines which exit codes indicate job failure.
Default: Any exit code other than 0 (zero) indicates job failure

interactive
(Windows only) Specifies whether to run a Command job in interactive mode or in
batch mode on Windows.
Default: n (The job runs in batch mode.)


max_exit_success
Defines the maximum exit code that the job can exit with and be considered a
success.
Default: 0 (The job interprets only zero as job success.)

owner
Specifies the user ID that the job runs under.
Default: The default owner (the user ID who invokes jil to define the job)

shell
(UNIX only) Specifies the name of the shell used to execute the script or command
file.
Note: Alternatively, you can override the default shell by specifying the shell in the
first line of the script. If a shell is specified in the script and in the job definition, the
job uses the shell specified in the job definition.
Default:
■ oscomponent.defaultshell agent parameter, if specified
■ The user default shell defined in the user profile, if the shell is not specified in
the job definition, script, or oscomponent.defaultshell parameter
 Attributes with Default Values

226 User Guide

std_err_file
Defines the path and file name where you want to redirect all standard error
output.
CA WA Agent Default: The agent's spool directory
(installation_directory/SystemAgent/agent_name/spool)
Legacy Agent Default: /dev/null (UNIX) or NULL (Windows)

std_out_file
Defines the path and file name where you want to redirect all standard output.
CA WA Agent Default: The agent's spool directory
(installation_directory/SystemAgent/agent_name/spool)
Legacy Agent Default: /dev/null (UNIX) or NULL (Windows)

success_codes
Defines which exit codes indicate job success.
Default: 0 (The job interprets zero as job success.)
Notes: For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference Guide.

Example: Override the Default Shell Using the shell Attribute
This example overrides the default shell using the shell attribute. The job uses the C
shell run the test1.csh script.
insert_job: unix_job1
job_type: CMD
machine: unixagent
command: /mfg/test1.csh
shell: /bin/csh
Note: This job succeeds only if the user's default shell is csh. To set the default shell,
define the following parameters in the agent's agentparm.txt file:
oscomponent.defaultshell=/bin/csh
oscomponent.defaultshell.force=true Attributes with Default Values

Chapter 7: Command Jobs 227

Example: Override the Default Shell by Specifying the Shell in a Script
This example overrides the default shell with the C shell specified in the following
test1.csh script:
#!/bin/csh -f
if ( $LOGNAME != guest) then
echo "User is not guest"
endif
echo $LOGNAME logon
exit 0
The following job definition runs the test1.csh script:
insert_job: unix_job2
job_type: CMD
machine: unixagent
command: /mfg/test1.csh
owner: guest
The shell attribute is not required in the job definition because the shell is specified in
the first line of the script.

Example: Override the Default Background Mode Using the interactive Attribute
This example runs a Command job in interactive mode on Windows. The job opens the
config.txt file in the Notepad application on the Windows desktop.
insert_job: edit_file
job_type: CMD
machine: winagent
description: "Edit/review a configuration file"
command: notepad.exe "c:\run_info\config.txt"
interactive: y
More information:
Determining Which Shell is Used (UNIX) (see page 219)

 Verify File Space Before a Job Starts

228 User Guide

Verify File Space Before a Job Starts
You can define a Command job to check if one or more UNIX file systems or Windows
drives have the required amount of available space. At run time, the agent checks
whether the required space is available on the machine where the job runs. If the
requirements are met, the job starts. If the requirements are not met, the agent
generates an alarm and the job does not start. The system tries to verify the file space
again and start the job. The number of tries is determined using the n_retrys attribute. If
the n_retrys attribute is not specified in the job definition, the number of tries is
determined by the MaxRestartTrys parameter in the configuration file (UNIX) or the
Max Restart Trys field in the Administrator utility (Windows). If the required space is still
not available after all the restart attempts, the job fails.
By default, jobs do not check the available file space.

Follow these steps:
1. Define a Command job (see page 222).
2. Add the following attribute to the job definition:
chk_files
Specifies the required amount of space on one or more file systems (UNIX) or
drives (Windows) in kilobytes (KB).

3. Run the job.
The file space is verified before the job starts.
Note: For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference Guide.

Example: Verify the Available File Space on UNIX
This example checks whether the file system named roots has 100 KB of available space.
This example also checks whether the file system named auxfs1 has 120 KB of available
space. The specified file space must be available before the job can start.
insert_job: unix_chk
job_type: CMD
machine: unixagent
command: /u1/procrun.sh
chk_files: /roots 100 /auxfs1 120 Pass Positional Arguments in a Command Job

Chapter 7: Command Jobs 229

Example: Verify the Available File Space on Windows
This example checks whether the C: drive has 100 KB of available space and the D: drive
has 120 KB of available space. The specified file space must be available before the job
can start.
insert_job: win_chk
job_type: CMD
machine: winagent
command: "C:\Programs\Payroll\pay.exe"
chk_files: "C: 100 D: 120"
Pass Positional Arguments in a Command Job
When running workload, you might need to pass data between jobs and across
platforms. You can pass positional arguments to a command or script in your job
definition. Positional arguments are variables that can be passed to a program at the
time the program is invoked. The arguments are assigned in the order they are passed.

Follow these steps:
1. Define a Command job (see page 222).
2. Add the following attribute to the job definition:
command: file argument...
file
Specifies the command, executable, UNIX shell script, application, or batch file
to run when all the starting conditions are met.
argument...
Specifies one or more arguments to pass to the command or script at run time.
Note: Separate each argument with a space. You must specify each argument
in the order it is expected in the program.

3. Run the job.
The positional arguments are passed to the program.
Note: For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference Guide.
 Pass Environment Variables in a Command Job

230 User Guide

Example: Pass Positional Arguments to a UNIX Script
This example passes three arguments to a UNIX script. The first argument passed is
"user 1". This argument is enclosed with quotation marks because it contains a space.
The second argument passed is 905-555-1212, and the third argument is 749.
insert_job: cmd_job1
job_type: CMD
machine: unixprod
command: addinfo.sh "user 1" 905-555-1212 749
Example: Pass Positional Arguments to a Windows Program
This example passes two data files to a Windows program. The arguments are enclosed
with quotation marks because they contain spaces.
insert_job: cmd_job2
job_type: CMD
machine: winprod
command: "c:\Programs\Payroll\pay.exe" "C:\Pay Data\salary.dat" "C:\Pay
Data\benefits.dat"
Pass Environment Variables in a Command Job
You can specify environment variables to define the local environment the program
runs in. You can modify existing environment variables or create your own.

Follow these steps:
1. Define a Command job (see page 222).
2. Add the following attribute to the job definition:
envvars
Specifies the environment variables that define the local environment.

3. Run the job.
The environment variables are passed to the program.
Note: For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference Guide.
 Pass Environment Variables in a Command Job

Chapter 7: Command Jobs 231

Example: Pass Environment Variables to a UNIX Script
This example includes two envvars attributes that pass environment variables to a script
and a third envvars attribute that defines the Present Working Directory (PWD). The
parameter "user 1" is enclosed with quotation marks because it contains a space.
insert_job: unix_job
job_type: CMD
machine: unixprod
command: /home/scripts/pay
envvars: NAME="user 1"
envvars: JOB=PAYROLL
envvars: PWD=/usr/scripts/dailyrun
In this example, the pay script can reference these variables:

Environment Variable Value Passed
NAME user 1
JOB PAYROLL
PWD /usr/scripts/dailyrun
Note: If the parameter oscomponent.loginshell is set to true in the agent's
agentparm.txt file, the agent invokes the user environment while running the script. To
override the value of a shell variable that is already defined in the user login file,
reassign a value to this variable in the script.

Example: Pass Two Environment Variables to a Windows Command File
This example runs the processrun.exe command file on a Windows computer named
winprod. The job uses two local environment variables named PATH and TEMP.
insert_job: cmd_job1
job_type: CMD
machine: winprod
command: "c:\cmds\processrun.exe"
envvars: PATH="c:\windows\system32"
envvars: TEMP="c:\temp"
UNIX Environment Variables
When a Command job runs under a specific user account on UNIX, the agent can pass
the user's environment variables to the script or program. You can also set up a script's
running environment by overriding the environment variables in the job definition. For
example, you can override the HOME environment variable to run the script under a
user’s login directory.
 Pass Environment Variables in a Command Job

232 User Guide

You can pass the following UNIX environment variables in a job definition to override
the variable values:
HOME
Identifies the user's login directory. You can override the HOME value to set up a
user-specific environment by specifying a different login directory in the job
definition.
Example: HOME=/home/guest/bin
Notes:
■ You can set up the script's running environment in the .profile and .login files.
■ You must also set the oscomponent.loginshell parameter to true in the agent's
agentparm.txt file to run the login scripts located in the HOME directory.

PATH
Provides a list of directories that the shell searches when it needs to find a
command. Each directory is separated by a colon. and the shell searches the
directories in the order listed. The PATH variable is the most important
environment variable. You can override the PATH value to set up a user-specific
environment by specifying a different PATH in the job definition.
Note: Overriding the default system path can result in the "command not found"
error.

ENV
Contains the name of the initialization file to run when a new Korn shell starts. You
can override the ENV value to set up a user-specific environment by specifying a
different ENV value in the job definition.
Example: ENV=/home/guest/bin/myenv
Note: The name of the file used to set up the script-running environment must be
.profile. The .profile must be the same file used with the HOME variable.
PWD
Contains the absolute path name of your current directory.
 Define Alternative Error, Input, and Output Sources

Chapter 7: Command Jobs 233

Define Alternative Error, Input, and Output Sources
By default, the standard output and standard error output are redirected to the agent's
spool directory. You can define alternative error, input, and output sources in your job
definition that override these defaults.
Follow these steps:
1. Define a Command job (see page 222).
2. Add one or more of the following attributes to the job definition:
std_err_file
Specifies where you want to redirect the standard error output. The output can
be redirected to a file or a blob.

std_in_file
Specifies where you want to redirect standard input from. The input can be a
file or a blob.

std_out_file
Specifies where you want to redirect the standard output. The output can be
redirected to a file or a blob.

3. Run the job.
The alternative sources are defined.
Note: For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference Guide.

Example: Specify the Standard Input File and Output on UNIX
This example specifies the /tmp/test.in file as the standard input file and /tmp/test.out
as the standard output file .
insert_job: unix_stdin
job_type: CMD
machine: unixagent
command: /usr/common/backup
std_in_file: /tmp/test.in
std_out_file: /tmp/test.out Create a Job Blob

234 User Guide

Create a Job Blob
You can create a job blob that is associated with the Command job you are defining. The
blob can contain the data that you specify in the job definition (input job blob), the job's
output (output job blob), or the job's error messages (error job blob). Input job blobs
are uploaded to the database when the job is defined. Output and error job blobs are
uploaded to the database after the job runs.
Other jobs on different computers can use the input job blobs and output job blobs.
Jobs cannot use error job blobs as input.

Follow these steps:
1. Define a Command job (see page 222).
2. Add one or more of the following attributes to the job definition:
blob_file
Specifies the file containing the data to insert for the blob.

blob_input
Specifies the text to insert for the blob.

std_err_file
Specifies that the job blob contains the job's standard error messages in textual
or binary data format.

std_out_file
Specifies that the job blob contains the job's standard output messages in
textual or binary data format.

3. Run the job.
The job blob is created.
Notes:
■ For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference
Guide.
■ You can also use the insert_blob subcommand to create an input job blob after a
job is defined.
 Create a Job Blob

Chapter 7: Command Jobs 235

Example: Create an Input Job Blob at Job Definition Time
This example defines a CMD job that creates and uses an input job blob. When the job is
defined, a blob is created using the text that is specified in the blob_input attribute.
When the job runs, it uses the created blob as input and treats the blob data as textual
data.
insert_job: test_blob
job_type: CMD
command: cat
machine: unixagent
blob_input: <auto_blobt>multi-lined text data for job blob
</auto_blobt>
std_in_file: $$blobt
owner: produser@unixagent
Example: Create an Input Job Blob Using a File at Job Definition Time
This example defines a CMD job that creates and uses an input job blob. When the job is
defined, a blob is created using the textual data contained in the blob_input_file.txt file.
The blob is associated with the job. When the job runs, it uses the created blob as input
and treats the blob data as textual data.
insert_job: test_blob
job_type: CMD
machine: unixagent
command: cat
blob_file: /blob_input_file.txt
std_in_file: $$blobt
owner: produser@unixagent
Example: Create an Error Input Blob
This example captures the standard error output and stores it as a textual format blob
associated with the job.
insert_job: report_job1
job_type: CMD
machine: localhost
command: myapplication
std_err_file: $$blobt Send a User-Defined Exit Code

236 User Guide

Example: Create an Output Blob
This example captures the standard output and stores it as a textual format blob
associated with the job.
insert_job: report_job1
job_type: CMD
machine: localhost
command: myapplication
std_out_file: $$blobt
Send a User-Defined Exit Code
By default, the scheduling manager interprets an exit code of 0 (zero) as job success and
any other number as job failure. However, you can map exit codes other than 0 as job
success and you can map specific codes as job failure.
Follow these steps:
1. Define a Command job (see page 222).
2. Add one or more of the following attributes to the job definition:
fail_codes
Defines which exit codes indicate job failure.
success_codes
Defines which exit codes indicate job success.

3. Run the job.
The user-defined exit code is sent.
Note: For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference Guide.

Example: Define a Range of Exit Codes to Indicate Job Failure
Suppose that you want a job named CMDJOB to run the procjob.exe file. The job is
considered to have failed if the exit code is in the 40-50 range.
insert_job: CMDJOB
job_type: CMD
machine: winagt
command: "c:\temp\procjob.exe"
fail_codes: 40-50 Specify a Command or Script Name Without the Full Path

Chapter 7: Command Jobs 237

Example: Define a Exit Code to Indicate Job Success
This example shows the first and last lines of the payroll.sh script. The script returns the
self-defined exit code 100 to the scheduling manager.
#!/usr/bin/sh
.
.
.
exit 100
The following job definition runs the script. The success_codes attribute defines exit
code 100 as success, indicating successful completion of the script.
insert_job: test_blob
job_type: CMD
machine: unixagent
command: /home/esp/payroll.sh
success_codes: 100
Specify a Command or Script Name Without the Full Path
When defining a Command job, the agent usually requires the full path to the command
or script name you want to run. However, you can specify the command or script name
without the full path if the proper conditions are met.

Follow these steps:
1. Define a Command job (see page 222).
2. Add the following attribute to the job definition:
command
Specifies the command, executable, UNIX shell script, application, or batch file
to run when all the starting conditions are met.

UNIX: To specify a name without the full path, the following conditions must be
met:
■ The agent is running under the root account.
■ The agent is configured to resolve environment variables.
■ The user ID you enter in the owner attribute has the authority to run the
job on the agent. The user default shell is used.
■ The path to the script or command name is set in the PATH system
environment variable for the specified user ID.
 Specify a Command or Script Name Without the Full Path

238 User Guide

Windows: To specify a name without the full path, the following conditions
must be met:
■ The agent is configured to search for paths to command or script files.
■ The script or command file is located in one of the following directories:
 - The directory the agent is installed in
 - WINDOWS\system32 directory on the agent computer
 - WINDOWS\system directory on the agent computer
 - WINDOWS directory on the agent computer
 - Any other directory whose path is set in the system path or user path on
the agent computer

3. Run the job.
The command or script name is specified.

Notes:
■ For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference
Guide.
■ To configure the agent to resolve environment variables, ask your agent
administrator to refer to the information about the oscomponent.lookupcommand
parameter in the CA Workload Automation Agent for UNIX, Linux, or Windows
Implementation Guide.
■ Environment variables are not currently supported in the command attribute for
Command jobs that run on Windows.

Example: Run a Script that is Located in a Path Set in the PATH Variable (UNIX)
This example runs a script named procscript.sh. The job runs under the user ID jsmith,
which has the authority to run the script. The path to procscript.sh is set in the PATH
system environment variable for jsmith on the agent computer and the agent is
configured to search for paths to command and script files.
insert_job: unix_job
job_type: CMD
machine: unixagent
command: procscript.sh
owner: jsmith Specify a Command or Script Name Using an Environment Variable (UNIX)

Chapter 7: Command Jobs 239

Example: Specify a Script Name Without the Full Path (Windows)
This example runs a script named procscript.bat. The path to procscript.bat is set in the
system path on the agent computer and the agent is configured to search for paths to
command and script files.
insert_job: win_job
job_type: CMD
machine: winagent
command: procscript.bat
Specify a Command or Script Name Using an Environment
Variable (UNIX)
When defining a Command job on UNIX, you can specify the command or script name
using an environment variable (for example, $MY_PATH/myscript.sh).
Follow these steps:
1. Define a Command job (see page 222).
2. Add the following attribute to the job definition:
command
Specifies the command, executable, UNIX shell script, application, or batch file
to run when all the starting conditions are met. Include the environment
variable in the name.
Note: To use an environment variable, the following conditions must be met:
■ The agent is running under the root account.
■ The agent is configured to resolve environment variables.
■ The user ID you enter in the owner attribute has the authority to run the
job on the agent computer. The user default shell is used.
■ The environment variable you use, such as $MY_PATH, is set in the
specified user ID's profile file.

3. Run the job.
The command or script name is specified.
 Run a Script Under a Specific User Account (UNIX)

240 User Guide

Notes:
■ For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference
Guide.
■ To configure the agent to resolve environment variables, ask your agent
administrator to refer to the information about the oscomponent.lookupcommand
parameter in the CA Workload Automation Agent for UNIX, Linux, or Windows
Implementation Guide.

Example: Run a Script that is Located in a Path Set in a User Environment Variable
In this example, an agent named unixagent runs a script named myscript.sh. The job
runs under the user ID jsmith, which has the authority to run the script. The path to
myscript.sh is set in the user environment variable $MY_PATH, which is defined in the
profile file for jsmith. The agent is configured to search for paths to command and script
files.
insert_job: unix_job
job_type: CMD
machine: unixagent
command: $MY_PATH/myscript.sh
owner: jsmith
Run a Script Under a Specific User Account (UNIX)
You can define a Command job to run a UNIX command or script under a specific user's
account.

Follow these steps:
1. On the client computer where you want to run the job, do one of the following:
■ Start the agent as root.
■ Start the agent as a user other than root.
Note: This user account must have permissions to access the resources that the
job requires. If the job is defined to run under a different user (owner), the user
account the agent is started under must have permissions to switch to that
user. Otherwise, the job fails.
 Run a Script Under a Specific User Account (UNIX)

Chapter 7: Command Jobs 241

2. Define a Command job (see page 222).
3. Add the following attribute to the job definition:
owner
Specifies the user ID that the job runs under.
Default: The default owner (the user ID who invokes jil to define the job)
Note: The user ID must have the permissions to access the required directories
and run the commands and scripts located on the agent computer.

4. Run the job.
The script runs under the specified user.

Notes:
■ If the shell is specified in the first line of the script and its path matches the path
defined in the oscomponent.validshell parameter, you do not have to specify the
shell attribute in the job definition to define the shell that you want the agent to
use. For example, you can run a script using the environment defined in a specific
user's account.
■ For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference
Guide.

Example: Run a Script Under a Specific User Account
In this example, if the first line of the script is #!/bin/ksh and the path /bin/ksh is
defined using the oscomponent.validshell parameter, you can use the owner attribute
to run the script under a specific user account, as follows:
insert_job: unix_job
job_type: CMD
machine: unixagent
command: /home/guest/bin/cmd1.ksh
owner: guest
In this example, the agent runs the cmd1.ksh Korn script using the environment defined
in either the $HOME/.login file or the
$HOME/.profile file, depending on which login shell is defined for user guest:
■ If csh is defined, the $HOME/.login file is used.
■ If ksh is defined, the $HOME/.profile file is used.
 Modify Resource Limits (UNIX)

242 User Guide

The login shell for user guest does not have to be the Korn shell. For example, the agent
can pick up the following environment variables for user guest:
HOME=/home/guest
LOGNAME=guest
USER=guest
SHELL=/usr/bin/csh
PWD=/home/guest
In this example, user guest has specified the login shell as the C shell. The agent,
therefore, runs the cmd1.ksh script using the environment defined in the $HOME/.login
file.

Modify Resource Limits (UNIX)
When you define a Command job to run UNIX workload, you can set the job to modify
resource limits on the agent computer for a given job. For example, you can define a job
that modifies the maximum core file size and CPU times on the UNIX computer.

Follow these steps:
1. Define a Command job (see page 222).
2. Add the following attribute to the job definition:
ulimit
Specifies one or more resource types and their soft and hard limits. Specify the
attribute as follows:
ulimit: resource_type="soft_value,hard_value"
 [,resource_type="soft_value,hard_value"...]
3. Run the job.
The resource limits on the UNIX computer are modified.

Notes:
■ If the job runs under a non-root user ID, the hard limit will not be modified if the
value in the job definition is greater than the hard limit on the UNIX computer.
■ For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference
Guide.
 Customize the Run-time Environment for a Korn Shell Script (UNIX)

Chapter 7: Command Jobs 243

Example: Modify Multiple Resource Limits
This example runs the procrun.sh script on the unixagent computer. The job modifies
the following resource limits on the UNIX computer:
■ The core file size limit is 100 KB (soft limit). The size can be increased to 200 KB
(hard limit).
■ The stack size limit is 250 KB (soft limit). The size can be increased to 300 KB (hard
limit).
■ The CPU time can be up to 4000 seconds.
■ The process virtual size limit is 3332 KB (soft limit). The size can be increased to an
unlimited value.
insert_job: cmd_job
job_type: CMD
machine: unixagent
command: /u1/procrun.sh
ulimit: c=”100,200”, s=”250,300”, t=”4000, unlimited”, m=”3332, unlimited”
Note: The resource limits are modified for the current job definition only. When you run
another job, the default values will be used.

Customize the Run-time Environment for a Korn Shell Script
(UNIX)
When you define a Command job to run a Korn shell script under a user's account, you
can customize the job's run-time environment. The agent runs the job using the
specified user's login environment and the run-time environment you specify.

Follow these steps:
1. Define a Command job (see page 222).
2. Ensure that the oscomponent.loginshell parameter in the agent's agentparm.txt file
is set to true.
3. Add the following attributes to the job definition:
envvars: HOME=/directory_name
envvars: ENV=/directory_name/myenv
4. Run the job.
The run-time environment for the Korn shell script is customized. Before running
the Korn script, the agent runs the /directory_name/.profile file and the
/directory_name/myenv file.
Note: For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference Guide.
 Customize the Run-time Environment for a Bourne Shell Script (UNIX)

244 User Guide

Customize the Run-time Environment for a Bourne Shell Script
(UNIX)
When you define a Command job to run a Bourne shell script under a user's account,
you can customize the job's run-time environment. The agent runs the job using the
specified user's login environment and the run-time environment you specify.
Follow these steps:
1. Define a Command job (see page 222).
2. Ensure that the oscomponent.loginshell parameter in the agent's agentparm.txt file
is set to true.
3. Define a specific environment for the Korn shell.

4. Ask your agent administrator to configure the agent to run the Bourne shell script
using the Korn shell
5. Run the job.
The run-time environment for the Bourne shell script is customized.
Notes:
■ The ENV variable only works for the Korn shell. The Korn shell is a superset of the
Bourne shell. Anything that runs under the Bourne shell runs without modification
under the Korn shell.
■ For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference
Guide.

Example: Customize the Run-time Environment for a Bourne Shell Script
This example runs the cmd1.sh Bourne shell script. Before running the script, the agent
runs the following:
■ The login file for user guest
■ The /esp/myenv file
insert_job: cmd_job
job_type: CMD
machine: unixagent
command: /home/bin/cmd1.sh
shell: /bin/ksh
owner: guest
envvars: ENV=/esp/myenv Customize the Run-time Environment for a C Shell Script (UNIX)

Chapter 7: Command Jobs 245

Customize the Run-time Environment for a C Shell Script
(UNIX)
When you define a Command job to run a C shell script under a user's account, you can
customize the job's run-time environment. The agent runs the job using the specified
user's login environment and the run-time environment you specify.

Follow these steps:
1. Define a Command job (see page 222).
2. Ensure that the oscomponent.loginshell parameter in the agent's agentparm.txt file
is set to true.
3. Set the environment in a .login file.

4. Add the following attribute to the job definition:
envvars: HOME=login_file
login_file
Specifies the path to the .login file.

5. Run the job.
The run-time environment for the C shell script is customized.
Note: For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference Guide.

Example: Customize the Run-time Environment for a C Shell Script
In this example, the agent picks up the environment for user root and runs the
/home/bin/.login file before running the cmd1.csh C shell script. The agent is running as
root. Note that the login shell for root is not the C shell.
insert_job: cmd_job
job_type: CMD
machine: unixagent
command: /home/guest/bin/cmd1.csh
envvars: HOME=/home/bin/ Define a Command Job to Run a Perl Script (UNIX)

246 User Guide

Define a Command Job to Run a Perl Script (UNIX)
You can define a Command job to run a Perl script on UNIX.
Follow these steps:
1. Ask your agent administrator to add the path of the Perl interpreter to the
oscomponent.validshell parameter in the agent's agentparm.txt file, as shown in
the following example:
oscomponent.validshell=/usr/bin/sh,/bin/csh,/bin/ksh,/usr/local/bin/perl,/usr
/local/bin/bash
Note: If the oscomponent.checkvalidshell parameter is set to false, you do not need
to perform the first step.
2. Define a Command job (see page 222).

3. Add the command attribute to the job definition using the following syntax:
command: /usr/script
script
Specifies the path to the script you want to run.
Example: cmd1.pl

4. Do one of the following:
■ Specify the path to the Perl interpreter in the first line of the script, as shown in
the following example:
Perl Script cmd1.pl
 #!/usr/local/bin/perl
 print " $0 @ARGV\n";
 while (( $var, $value) = each %ENV) {
 print "$var = $value\n";
 }
 $live=$ENV{pick};
 print " user variable pick = $live\n";
■ Specify the path to the Perl interpreter in the job definition, using the shell
attribute, as shown in the following example:
insert_job: perl_job
job_type: CMD
machine: unixagent
command: /bin/cmd1.pl Hello world
shell: /usr/local/bin/perl
owner: guest Run the Windows Command Interpreter (Windows)

Chapter 7: Command Jobs 247

5. Run the job.
The job runs the Perl script.
Note: For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference Guide.

Run the Windows Command Interpreter (Windows)
You can schedule a job to run a command, a batch script, program executable using the
Windows command interpreter (cmd.exe).
Follow these steps:
1. Verify the following parameters are set in the agent's agentparm.txt file:
oscomponent.lookupcommand=true
oscomponent.cmdprefix.force=true
2. Define a Command job (see page 222).

3. Add the command attribute to the job definition using the following syntax:
command: command argument...
command
Specifies the cmd.exe command to run.
Examples: copy, dir, echo
argument...
Specifies one or more arguments to pass to the cmd.exe command.
Note: Separate each argument with a space. You must specify each argument
in the order it is expected in the program.
4. Run the job.
The job runs the specified cmd.exe command.
 Run the Windows Command Interpreter (Windows)

248 User Guide

Notes:
■ If the agent parameters specified in Step 1 are not set to true, you must explicitly
invoke the command interpreter in the command attribute, as follows:
command: "path\cmd.exe /C command argument..."
path
Specifies the path to cmd.exe. The path to cmd.exe depends on your Windows
operating system version. For example, on Windows NT, the path is
C:\WINNT\system32\cmd.exe.
■ For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference
Guide.

Example: Run a Windows Operating System Command
This example lists the contents of the c:\temp directory. The
oscomponent.lookupcommand and oscomponent.cmdprefix.force parameters in the
agentparm.txt file are set to true, so the path to the command interpreter
(path\cmd.exe /c) is automatically prefixed to the command before running the process
insert_job: cmd_job
job_type: CMD
machine: winprod
command: dir "c:\temp\"
Example: Explicitly Invoke the Command Interpreter
This example uses cmd.exe to copy a file to another location. The
oscomponent.lookupcommand and oscomponent.cmdprefix.force parameters in the
agentparm.txt file are not set to true, so the path to the command interpreter must be
explicitly invoked in the command attribute.
insert_job: cmd_job
job_type: CMD
machine: winprod
command: "C:\Windows\system32\cmd.exe /C copy C:\env.txt C:\test\env.txt" Access Network Resources (Windows)

Chapter 7: Command Jobs 249

Access Network Resources (Windows)
When your agent runs as a Windows service, you can schedule Windows workload that
accesses network resources. For example, you can specify UNC names and share names
in your job definition.
Usually, when running a Windows program as a service, you are restricted to how you
can access data on remote computers. For example, to access data on a remote
computer as a specified user ID, you must run the Windows service with that user ID.
With the agent, however, those restrictions do not apply. Instead of running the agent
service with a specific user ID, you can specify the user ID with the owner attribute in
your job definition. To use the owner attribute, your agent must run as a Windows
service under the local system account (the default configuration).

Follow these steps:
1. Verify with your agent administrator that the agent is running as a Windows service
under the local system account.
2. Ask your scheduling manager administrator to define a user ID and password on the
scheduling manager that has access to the file on the remote Windows system.
3. Define a Command job (see page 222).

4. Add the following attributes to the job definition:
command
Specifies a command, executable, application, or batch file to run when all the
starting conditions are met.

Notes:
■ You can specify UNC (Universal Naming Convention) names. A UNC name
is the name of a file or other resource that begins with two backslashes
(\\), indicating that it exists on a remote computer.
■ You can specify share names. A share name is an alias for the path the
resource exists in.
■ You can specify the share names C$ and ADMIN$ if the agent service logs
on to a remote Windows server as a user with administrative authority.
The agent can then access remote resources that are not marked as
shared.

owner
Specifies the Windows user ID and the domain the user ID belongs to.
Default: The default owner (the user ID who invokes jil to define the job)

5. Run the job.
The job accesses the specified Windows network resources.
 Access Network Resources (Windows)

250 User Guide

Notes:
■ For more information about JIL job types and other job definition attributes, the
values that you can specify for those attributes, and JIL syntax, see the Reference
Guide.
■ Before accessing network resources with your agent, verify that you are complying
with the terms of your agent license agreement. In most situations, you are
permitted to access data on remote computers; however, scripts or executable files
run by an agent should use the CPU and memory of the computer where the agent
resides.

■ Although not recommended, your agent administrator can run the agent as a
Windows service under a local user account (the This Account option). When you
run the service under a local user account, when the service starts, it runs using the
security context of the specified user account. If the user account and password are
valid, the service process has access to network resources.

■ When you access a remote computer from an agent on Windows, the user ID
defined in the owner attribute or in the This Account option is a domain user. If the
local and remote servers are standalone servers, you must have the same user IDs
and passwords defined on both servers.

■ For more information on configuring and running the agent as a Windows service,
see the CA Workload Automation Agent for UNIX, Linux, or Windows
Implementation Guide.

Example: Run a Command on a Remote Server
In this example, the path c:\WINNT\Profiles\Visitor\Desktop\ has the share name
MyDesktop. The command notify.cmd is in that path on the CYBNT server. JDOE is a
user ID in the CYBDOM domain and has access to the notify.cmd command. JDOE's
password is defined on the scheduling manager.
insert_job: exe_job1
job_type: CMD
machine: NT20
command: \\CYBNT\MyDesktop\notify.cmd
owner: CYBDOM\JDOE
Example: Run an Executable in Public Folder on a Remote Server
This example runs calc.exe on the CYBNT server. CYBUSER is a user ID in the CYBDOM
domain. CYBUSER is defined on the scheduling manager and has access permission to
the public folder.
insert_job: exe_job2
job_type: CMD
machine: NT30
command: \\CYBNT\public\calc.exe
owner: CYBDOM\CYBUSER Access Network Resources (Windows)

Chapter 7: Command Jobs 251

Example: Access a Remote Resource Using the C$ Share Name
In this example, drive C is accessed by an administrator over the network through an
agent. The agent is running under the System Account option. The agent runs the test
application in the c:\working directory on the server CYBNT. The directory c:\working is
not a shared resource. The user admin1 is a valid user on both the local and remote
computers and belongs to the Administrators group. admin1 is also in the CYBDOM
domain.
insert_job: exe_job3
job_type: CMD
machine: NT30
command: \\CYBNT\C$\working\test
owner: CYBDOM\admin1
Specifying a Password for a User ID (Windows)
You can define a Command job to access Windows network resources by specifying the
user ID and the domain name the user ID belongs to using the owner attribute. The
resources are accessed under the specified user ID.
Note: To use the owner attribute in a Command job that runs on Windows, your agent
must run as a Windows service under the local system account.

If the user ID requires a password, your administrator must define the password on the
scheduling manager. For security reasons, you do not define the password in the job
definition. Your administrator must define and store the password in the CA Workload
Automation AE database using the autosys_secure command.

When you specify a user ID that requires a password in a job definition, the scheduling
manager sends the agent the user ID and password pair (the password is encrypted).
The scheduling manager searches the repository for an entry matching the specified
owner. The results from the search, the encrypted password or null, are provided to the
agent to run the job.

The following job types require a user password:
■ Database
■ FTP
■ PeopleSoft
■ SAP
■ Command (for Windows)