Chapter 6: Box Jobs

Chapter 6: Box Jobs

Box Jobs 

A Box job (or box) is a container of other jobs. You can use it to organize and control
process flow. The box itself performs no actions, although it can trigger other jobs to
run. An important feature of this type of job is that boxes can contain other boxes. You
can use boxes to contain other boxes that contain jobs related by starting conditions or
other criteria. This feature lets you group the jobs and operate on them in a logical
manner.

Box jobs are powerful tools for organizing, managing, and administering large numbers
of jobs that have similar starting conditions or complex logic flows. Knowing how and
when to use boxes is often the result of some experimentation.
For example, assume you want to schedule a group of jobs to start running when a File
Watcher job completes successfully. Instead of making each job dependent on the File
Watcher job, you can create a Box job that is dependent on the File Watcher job,
remove the File Watcher job dependency from the individual jobs, and put all of those
jobs in the box. When the File Watcher job completes successfully, the Box job starts,
which in turn starts all the jobs it contains.

Starting Conditions for Box Jobs 

When no other starting conditions are specified at the job level, a job in a box runs
when the starting conditions for the box are satisfied. When several jobs in a box do not
have job-level starting conditions, they all run in parallel. When any job in a box changes
state, other jobs check if they are eligible to start running.
 Basic Box Concepts

188 User Guide
When the priority attribute is set for jobs in a box, they are processed in order of
priority, highest to lowest.
Note: For more information about the priority attribute, see the Reference Guide.

Jobs in boxes run only once for each box execution. If you specify multiple start times
for a job during one box processing cycle, only the first start time is used. This prevents
jobs in boxes from inadvertently running multiple times.
CA Workload Automation AE starts a job when the current time matches, or is later
than, the specified start time. In addition to explicit starting conditions, jobs in boxes
have the implicit condition that the box job itself is running. This means that jobs in a
box start only if the box job is running. However, if a job in a box starts and the box job
is stopped, the started job runs to completion.

Note: Use caution when putting a job with more than one time-related starting
condition in a box. For example, assume that a job that runs at 15 and 45 minutes past
the hour is put in a box that runs at the start of every hour. The first time the box starts,
the job runs at 15 minutes past the hour. A future start is then issued for 45 minutes
past the hour, by which time the box has completed. As a result, the job will not run
until the box runs again at the start of the next hour. At that time, the job runs as soon
as the box starts because it is past its start time. The job runs, another future start job is
issued for 15 minutes past the hour, the box completes, and the cycle repeats itself.

Basic Box Concepts 
A box is a container of jobs with similar starting conditions (either date and time
conditions or job dependency conditions). Use boxes to group jobs with similar
scheduling parameters, not to group jobs organizationally. For example, you can group
jobs that run daily at 1:00 a.m. in a box and assign them a daily start condition.
However, you should not group a variety of account processing jobs with diverse
starting conditions in the same box.
 Basic Box Concepts

Chapter 6: Box Jobs 189

Default Box Job Behavior
The following default rules apply to boxes:
■ Jobs in a box run only once for each box execution.
■ Jobs in a box start only if the box itself has a status of RUNNING.
■ Boxes are used primarily for jobs with the same starting conditions.
■ A box used to group sequential jobs can contain up to 1,000 jobs.
■ A box remains in RUNNING state until all the jobs it contains have run.
■ A box returns a status of SUCCESS when all the jobs it contains have run and
returned a status of SUCCESS.
■ A box returns a status of FAILURE when all the jobs it contains have run and one or
more of the jobs has returned a status of FAILURE.
■ A box runs until it reaches a status of SUCCESS or FAILURE.
■ Using the sendevent command to change the state of a box to INACTIVE changes
the state of all the jobs it contains to INACTIVE.

More information:
Box Job Attributes and Terminators (see page 192)


Box Job Recommendations
Because all jobs in a box change status when a box starts running, you may want to use
boxes to implement job cycle behavior. However, placing jobs in a box to achieve this
behavior can affect your system adversely because the job status changes put a larger
load on the scheduler when the box starts running.

Do not put jobs in a box solely to run reports on all of them. When you run autorep on a
box, the command generates a report about the box and all the jobs it contains (unless
you use the -L0 option).

Note: Job names can only contain the following characters: a-z, A-Z, 0-9, period (.),
underscore (_), and hyphen (-). You cannot include spaces in a job name.

How a Box Runs
When a box starts running, the status of all the jobs it contains (including subboxes)
changes to ACTIVATED, which means they are eligible to run. Because of this status
change, jobs in boxes do not retain their statuses from previous box cycles.
 Basic Box Concepts

190 User Guide

When a box starts running, the system performs the following actions:
■ Analyzes each job for additional starting conditions.
■ Starts all jobs with no additional starting conditions and without any implied order
or priority.
■ Maintains jobs with additional starting conditions in the ACTIVATED state until
those additional dependencies are met.
■ Maintains the box in the RUNNING state as long as there are jobs in it with
ACTIVATED or RUNNING status.
■ Changes the status of the job directly from ACTIVATED to INACTIVE if its containing
box is terminated before the job starts.
Notes:
■ Jobs in a box cannot start unless the box has a status of RUNNING. However, after a
job starts running, it runs to completion even if the box is stopped.
■ When the box is scheduled to run, the statuses of ON_NOEXEC jobs in the box
change to ACTIVATED. If the box is terminated before the jobs start, the jobs return
to ON_NOEXEC status.
■ When a box that is in ON_NOEXEC status is scheduled to run, the status of the box
changes to RUNNING. Jobs in the box with additional starting conditions remain in
the ACTIVATED state until those additional conditions are met. Once CA Workload
Automation AE bypasses the last scheduled job in the box, the box status returns to
ON_NOEXEC.
■ When a box that is in ON_NOEXEC status is scheduled to run, CA Workload
Automation AE bypasses all scheduled jobs in that box and returns them to the
ON_NOEXEC status regardless of manual status changes to individual jobs issued
after the box has been put in ON_NOEXEC status.

After all the jobs in a box have completed successfully, the box completes with a status
of SUCCESS. The status of the box and the jobs it contains remain unchanged until the
next time the box runs.
If a box changes to TERMINATED state (for example, if a user sends a KILLJOB event), it
stays in TERMINATED state until the next time it is started, regardless of any later state
changes of the jobs it contains.
 Basic Box Concepts

Chapter 6: Box Jobs 191
Example: Simple Box Job
This example shows the behavior of a simple box job.
The following illustration shows a box named simple_box that contains three jobs
(job_a, job_b, and job_c). job_a and job_b have no starting conditions. The starting
condition for job_c is the success of job_b.

When simple_box starts running, the status of all the jobs changes to ACTIVATED.
Because job_a and job_b have no additional starting conditions, they start running.
When job_b completes successfully, job_c starts. When job_c completes successfully,
the box completes with a SUCCESS status.
If job_b fails, job_c does not start but remains in the ACTIVATED state. Because no
contingency conditions have been defined, simple_box continues running, waiting for
the default completion criteria (that all jobs in the box have run) to be met.


More information:
How Job Status Changes Affect Box Status (see page 191)


How Job Status Changes Affect Box Status
If a box that is not running contains a job that changes status because of a
FORCE_STARTJOB or CHANGE_STATUS event, the new job status could change the
status of its containing box. A status change for the box could then trigger the start of
downstream jobs that are dependent on the box.

If a box contained only one job, and the job changed status, the box status would
change as shown in the following table:

Current Box Status New Job Status New Box Status
SUCCESS TERMINATED or FAILURE FAILURE
SUCCESS SUCCESS or ON_NOEXEC Box status does not change Box Job Attributes and Terminators

192 User Guide

Current Box Status New Job Status New Box Status
FAILURE SUCCESS or ON_NOEXEC SUCCESS
FAILURE FAILURE Box status does not change
INACTIVE SUCCESS or ON_NOEXEC SUCCESS
INACTIVE TERMINATED or FAILURE FAILURE
TERMINATED Any change Box status does not change
ON_NOEXEC Any change Box status does not change
If another job is dependent on the status of the box, the status change could trigger the
job to start. If the box status does not change, dependent jobs are not affected.

If the box contains other jobs in addition to the job that changed status, the status of
the box is evaluated again according to the success or failure conditions assigned to the
box (either the default or user-assigned). Any jobs in the box with a status of INACTIVE
are ignored when the status of the box is being re-evaluated. For example, consider an
INACTIVE box that contains four jobs, all with a status of INACTIVE (this is typical of a
newly created box). If one of the jobs is forced to start and completes successfully, the
status of the box changes to SUCCESS even though none of the other jobs ran.
Note: When a box that is in ON_NOEXEC status is scheduled to run, CA Workload
Automation AE bypasses all scheduled jobs in the box and returns them to ON_NOEXEC
status regardless of manual status changes made to individual jobs in the box after the
box is placed in ON_NOEXEC status.

Box Job Attributes and Terminators
The following sections describe how to use various job attributes to control the behavior
of box jobs and the jobs they contain.
Note: For more information, see the Reference Guide.
 Box Job Attributes and Terminators

Chapter 6: Box Jobs 193

Controlling How CA Workload Automation AE Evaluates the Completion State of a
Box Job
By default, CA Workload Automation AE evaluates the completion state of a box job
when all of the jobs that are contained in that box job complete. You can control how
CA Workload Automation AE evaluates the completion state of box jobs by specifying
the optional box_success and box_failure attributes when you define box jobs.
These attributes define the conditions under which a box job succeeds (enters the
SUCCESS state) and the conditions under which it fails (enters the FAILURE state). You
can define conditions that meet any of the following criteria:
■ Specify that a job that is contained in the box job enters a certain state
CA Workload Automation AE evaluates the overall success or failure of the box job
when the specified job enters the specified state, regardless of the states of other
jobs that are contained in the box job. The condition is not met if the specified job is
not scheduled. In this case, CA Workload Automation AE does not evaluate the
completion state of the box job and it remains in the RUNNING state.
■ Specify that a job that is not contained in the box job enters a certain state
CA Workload Automation AE evaluates the overall success or failure of the box job
when one of the jobs that is contained in the box job completes after the specified
job (which is not contained in the box) enters the specified state.
The condition is not met if all of the jobs that are contained in the box job complete
before the specified job enters the specified state. In this case, CA Workload
Automation AE does not evaluates evaluate the completion state of the box job and
it remains in the RUNNING state.
■ Specify that a job that is defined on an external instance enters a certain state
CA Workload Automation AE evaluates the overall success or failure of the box job
when one of the jobs that is contained in the box completes after the specified
external job enters the specified state. The condition is not met if all of the jobs that
are contained in the box job complete before the specified external job enters the
specified state. In this case, CA Workload Automation AE does not evaluate the box
job and it remains in the RUNNING state.
■ Specify a global variable
CA Workload Automation AE evaluates the overall success or failure of the box job
when one of the jobs that is contained in the box job completes after the global
variable is defined and set to the value that is specified in the condition.
The condition is not met if all of the jobs that are contained in the box job complete
before the global variable is set to the specified value. In this case, CA Workload
Automation AE does not evaluate the completion state of the box job and it
remains in the RUNNING state.
Note: To define a global variable and store it in the database, issue a SET_GLOBAL
event using the sendevent command. For more information about the sendevent
command, see the Reference Guide. Box Job Attributes and Terminators

194 User Guide

Example: Set the Success of a Specific Job in a Box Job as the Success Condition for
that Box Job
This example defines a box job named box_a, sets the success of the job named job_a as
the success condition for box_a, and defines the jobs named job_a, and job_b as jobs
that are contained in box_a.
insert_job: box_a
job_type: b
box_success: success(job_a)
insert_job: job_a
box_name: box_a
command: sleep 15
machine: machine1
insert_job: job_b
box_name: box_a
command: sleep 60
machine: machine1
CA Workload Automation AE evaluates the success of box_a when job_a completes,
regardless of the state of job_b. box_a enters the SUCCESS state when job_a enters the
SUCCESS state.
The success condition is not met when job_a enters a completion state other than
SUCCESS (such as FAILURE or TERMINATED). In this case, CA Workload Automation AE
evaluates the overall failure according to the default behavior (after job_b also
completes) because the job definition does not specify a failure condition. box_a enters
the FAILURE state because the default failure condition for box_a was met when job_a
entered the FAILURE state.
Example: Set the Failure of an External Job as the Failure Condition for a Box Job
This example defines a box job named box_a, sets the failure of the external job named
job_c^ACE as the failure condition for box_a, and defines the jobs named job_a and
job_b as jobs that are contained in box_a.
insert_job: box_a
job_type: b
box_failure: failure(job_c^ACE)
insert_job: job_a
box_name: box_a
command: sleep 60
machine: machine1
insert_job: job_b
box_name: box_a
command: sleep 300
machine: machine1 Box Job Attributes and Terminators

Chapter 6: Box Jobs 195

CA Workload Automation AE evaluates the overall failure of box_a when either job_a or
job_b completes. box_a enters the FAILURE state when job_c from the external instance
named ACE enters the FAILURE state before CA Workload Automation AE evaluates
box_a.
The failure condition is not met when one of the following situations occur:
■ Job_c enters a completion state other than SUCCESS (such as FAILURE or
TERMINATED), regardless of the completion state of job_a or job_b.
■ Job_c enters the FAILURE state after both job_a and job_b complete.
In these cases, CA Workload Automation AE evaluates the overall success of box_a
according to the default behavior (after job_a and job_b complete) because the job
definition does not specify a the box_success attribute. box_a enters the SUCCESS state
when job_a and job_b both complete and enter the SUCCESS state. box_a remains in a
RUNNING status when either job_a or job_b enters a state other than success because
the neither the failure condition specified in the box_failure attribute nor the default
success condition were met.
Example: Set the Failure of a Specific Job that is not contained in the Box Job as the
Success Condition for that Box Job
This example defines a box job named box_a, sets the success of a job that is outside of
box_a and is named job_d as the success condition for box_a, and defines the jobs
named job_a and job_b as jobs that are contained in box_a.
insert_job: box_a
job_type: b
box_success: failure(job_d)
insert_job: job_a
box_name: box_a
command: sleep 60
machine: machine1
insert_job: job_b
box_name: box_a
command: sleep 300
machine: machine1
insert_job: job_d
command: sleep 5
machine: machine2
CA Workload Automation AE evaluates the overall success of box_a when either job_a
or job_b completes. box_a enters the SUCCESS state when job_d enters the FAILURE
before the job that triggers the evaluation completes. Box Job Attributes and Terminators

196 User Guide

The success condition is not met when job_d enters a terminal state other than
FAILURE, regardless of whether or not job_a or job_b completes. In this case CA
Workload Automation AE evaluates the overall failure of box_a according to the default
behavior (after job_a and job_b complete) because the job definition does not specify
the box_failure attribute. box_a enters the FAILURE state when the completion state of
either job_a or job_b is not SUCCESS. box_a remains in the RUNNING state when both
job_a and job_b complete and enter the SUCCESS state because the success condition
was not met.
Example: Set a Global Variable as the Failure Condition for a Box Job
This example defines a box job named box_a, sets the global variable named TEST with a
value of ABC as the failure condition for box_a, and defines the jobs named job_a and
job_b as jobs that are contained in box_a.
insert_job: box_a
job_type: b
box_failure: v(TEST) = ABC
insert_job: job_a
box_name: box_a
command: sleep 300
machine: machine
insert_job: job_b
box_name: box_a
command: sleep 600
machine: machine
CA Workload Automation AE evaluates the overall failure of box_a when either job_a or
job_b completes, regardless of the state of the other job that is contained in the box.
box_a enters the FAILURE state when the global variable named TEST evaluates to value
ABC before job_a or job_b completes.
The failure condition is not met when one of the following situations occurs:
■ TEST evaluates to a value other than ABC, regardless of the completion state of
job_a or job_b.
■ TEST evaluates to ABC after both job_a and job_b complete.
In these cases, CA Workload Automation AE evaluates the overall success of box_a
according to default behavior (after job_a and job_b complete) because the job
definition does not specify the box_success attribute. box_a enters the SUCCESS state
when job_a and job_b complete and enter the SUCCESS state. box_a remains in the
RUNNING state when either job_a or job_b enter a completion state other than
SUCCESS because neither the failure condition specified in the box_failure attribute nor
the default success condition were met.
 Box Job Attributes and Terminators

Chapter 6: Box Jobs 197

Attributes in a Job Definition
You can use the following attributes in the job definition of a job in a box to force either
the job or the box to stop running:
box_terminator: y
Specifies that if the job completes with a FAILURE or TERMINATED status, the box
terminates. Define additional conditions for the other jobs in the box in case the
box is terminated.

job_terminator: y
Specifies that if the job's containing box completes with a FAILURE or TERMINATED
status, the job terminates. You must add this attribute to each job definition that
you want to terminate upon box failure.
Notes:
■ If a job defined with the job_terminator attribute is in ON_NOEXEC status, the job
does not terminate when the box fails.
■ If a job defined with the box_terminator attribute is in ON_NOEXEC status, then CA
Workload Automation AE bypasses the job and the job's containing box does not
terminate.

More information:
Job Flow with Box Terminator Attribute (see page 204)
Job Flow with Job Terminator Attribute (see page 203)


Time Conditions in a Box
Each job in a box runs only once each time the box runs. Therefore, do not define more
than one time attribute for any job in a box because the job only runs the first time. If
you want to put a job in a box, but you also want it to run more than once, you must
define multiple start time conditions for the box itself, and define no time conditions for
the job.
Note: The box must be running before the job can start. Do not assign a start time for a
job in a box if the box will not be running at that time. If you do, the next time the box
starts, the job starts immediately.
 Box Job Attributes and Terminators

198 User Guide

Example: Define Time Conditions for a Box Job
The following illustration shows a scenario with time conditions in a box:

In the illustration, job_a is defined to run repeatedly until it succeeds; job_report has
one starting condition, the success of job_a.

At 3:00 a.m., bx_stat starts running, which causes job_a to start running. If job_a is
successful, job_report runs and also succeeds.
If job_a fails, it will not be able to run again until the next time the box starts because
jobs run only once per box execution. In this situation, the following occurs:
■ Job job_report is still ACTIVATED while it waits for the success of job_a, and the
status of the box is RUNNING.
■ Because job_a is defined as a box terminator, the box then enters into a
TERMINATED state.
■ This change also terminates job job_report because its job_terminator attribute is
set to y.
■ Box bx_stat is now in a state that permits it to run again at 3:00 a.m. the following
day.
If job_a was not defined as a box terminator, the box remains in RUNNING state
indefinitely.

Force Jobs in a Box to Start
You can use the sendevent command to send a FORCE_STARTJOB event to force a job to
start, even if its starting conditions have not been met.
You can also execute the FORCE_STARTJOB command by selecting the Force Start Job
button in the Job Activity Console, which is part of the CA WCC GUI.
 Box Job Flow Examples

Chapter 6: Box Jobs 199

Example: Force a Job in a Box to Start
This example defines a sendevent command that sends a FORCE_STARTJOB event to
force a job in a box to run. You could use the following command to force the job
run_stats to start:
sendevent -E FORCE_STARTJOB -J run_stats
In the following illustration, the box job bx_report contains three jobs (job_Fwatch,
run_stats, and report_stats). If the job run_stats fails, the bx_report box job terminates
because run_stats has a box_terminator attribute. If you force start run_stats, and it
completes successfully, report_stats would still not start because the box it is in is not
running.

Box Job Flow Examples
This section contains examples to help explain the flow of box jobs and the jobs they
contain. These scenarios will help provide a clearer understanding of box job flow
concepts.

Default Box Success and Box Failure
This scenario describes the default job flow for box job success and failure.
The box job do_statistics runs every day at 3:00 a.m. It contains three jobs:
update_accounts
Updates files. This job starts when do_statistics starts running. It has no other
starting conditions.

run_stats
Runs statistics. This job starts when update_accounts completes successfully. It has
no other starting conditions.
 Box Job Flow Examples

200 User Guide
report_stats
Reports statistics. This job starts when run_stats completes successfully. It has no
other starting conditions.

No conditions for success or failure have been defined for do_statistics; therefore the
default conditions are applied. The box job completes successfully when all the jobs it
contains have run and completed successfully. The box job fails when all jobs in the box
have run and at least one has failed. The box job remains in the RUNNING state until all
the jobs it contains have run.

The following illustration shows this job flow:
box_name “do_statistics"
 Box Job Flow Examples

Chapter 6: Box Jobs 201

Explicit Box Success and Box Failure
This scenario provides an example job flow in which specific conditions are defined for
the success or failure of a box job.
The box job do_statistics runs every day at 3:00 a.m. It contains three jobs:
update_accounts
Updates files. This job starts when do_statistics starts running. It has no other
starting conditions.

run_stats
Runs statistics. This job starts when update_accounts completes successfully. It has
no other starting conditions.

report_stats
Reports statistics. This job starts when run_stats completes successfully. It has no
other starting conditions.

The following conditions define the criteria for success or failure of the box job
do_statistics:
■ The box job can complete successfully only when all of the jobs it contains have
completed successfully.
■ The box job fails if any of the jobs it contains fails.
 Box Job Flow Examples

202 User Guide

The following illustration shows the job definitions and the job flow:
 Box Job Flow Examples

Chapter 6: Box Jobs 203

Job Flow with Job Terminator Attribute
This scenario provides an example job flow in which the job_terminator attribute is
defined for a job in a box job.
The box job daily_accounts runs every day at 3:00 a.m. It contains two jobs:
daily_receipts
Processes receipts. This job runs when daily_accounts starts because it has no other
starting conditions.

daily_payables
Processes payables. This job runs when daily_accounts starts because it has no
other starting conditions. Because daily_payables includes a job_terminator
attribute, daily_account is terminated if this job fails.

A third job, daily_balance, is not contained in daily_accounts and runs only if both
daily_receipts and daily_payables complete successfully.

Because daily_accounts can only complete successfully if both of the jobs it contains
complete successfully, the failure of daily_receipts causes daily_accounts to fail. This in
turn triggers the job_terminator attribute in daily_payables, which terminates the job if
the box that contains it fails.
 Box Job Flow Examples

204 User Guide

The following illustration shows the job definitions and the job flow:

Job Flow with Box Terminator Attribute
This scenario provides an example job flow in which the box_terminator attribute is
defined for jobs in a box job.
The box job daily_accounts runs every day at 3:00 a.m. It contains two jobs:
daily_receipts
Processes receipts. This job runs when daily_accounts starts because it has no other
starting conditions. Because daily_receipts includes a box_terminator attribute,
daily_accounts will be terminated if this job fails.

daily_payables
Processes payables. This job runs when daily_accounts starts because it has no
other starting conditions. Because daily_payables includes a box_terminator
attribute, daily_accounts will be terminated if this job fails.
 Advanced Job Flows

Chapter 6: Box Jobs 205

A third job, daily_balance, is not contained in daily_accounts and will run only if both
daily_receipts and daily_payables complete successfully.

The following illustration shows the job definitions and the job flow:

Advanced Job Flows
This section contains examples to help explain the flow of box jobs and the jobs they
contain in advanced situations. These scenarios help provide a clearer understanding of
advanced job flow concepts.
 Advanced Job Flows

206 User Guide

Job Flow with Time Conditions Running on the First of the Month
This scenario is an example of a job flow that begins on the first of every month.

The job flow consists of three jobs:
job_Fwatch
Waits for a specific file to be created by some mainframe process. This job runs at
1:00 a.m. on the first of every month and waits for 90 minutes before giving up.

job_monthly
Re-indexes, organizes, and purges its records based on the file created by the
mainframe. This job runs at 2:00 a.m. on the first of the month only when
job_Fwatch completes successfully.

job_daily
Generates a report. This job runs daily at 3:00 a.m. when job_monthly completes
successfully.
 Advanced Job Flows

Chapter 6: Box Jobs 207

The failure of job_Fwatch causes job_monthly to skip its scheduled run because
job_monthly can only complete successfully if job_Fwatch completes successfully. Job
job_daily only runs if job_monthly completes successfully. By the same logic, job_daily
always runs if job_monthly was able to successfully run at least once.
Note: The first time the cycle is run (for example, January 1), statuses behave as
expected.

Job Flow with Time Conditions Running on the Second of the Month
This scenario builds upon the previous scenario and takes place on the following day.

On days of the month other than the first, job_Fwatch and job_monthly do not run.
They still have a status of SUCCESS in the database from the previous run on the first
day of the month. As a result, job_daily still runs.
 Advanced Job Flows

208 User Guide

Job Flow with Time Conditions Running on the First of the Following Month
This scenario builds upon the previous scenario and takes place on the first day of the
following month.
On the first day of the next month (for example, February 1), the file from the
mainframe fails to arrive in the 90 minute wait time; therefore, job_Fwatch
self-terminates. As a result, job_monthly misses its run for the month. However,
because its event status in the database is still SUCCESS from the previous month,
job_daily is able to run every day this month. When job_daily runs, it uses the previous
month's data leading to invalid reports for the month.

 Advanced Job Flows

Chapter 6: Box Jobs 209

Resetting a Job Flow with Time Conditions Through INACTIVE Status Change
This scenario builds upon the previous scenario and takes place on the last day of the
month.
To fix time-related statuses, you can use a sendevent command to change them to
INACTIVE at the end of their valid interval. You can create another job to do this
automatically.

Changing the status of job_monthly to INACTIVE at the end of every month allows
job_daily to run only in the months that job_monthly completes successfully. In the
following example, when job_Fwatch fails, job_monthly will not run, job_daily will not
run because its status has been reset to INACTIVE.

 Advanced Job Flows

210 User Guide

Resetting a Job Flow with Time Conditions Through Box Job
This scenario builds upon the previous scenarios and takes place on the first day of the
month.
Instead of issuing a sendevent command to change the status of the jobs, you can put
the monthly process in a box, and set the box_failure or box_terminator attribute
appropriately.

The job flow now consists of a box called box_monthly that runs at 1:00 a.m. on the first
day of every month with the following jobs:
job_Fwatch
Waits for a specific file to be created by some mainframe process. This job runs at
1:00am on the first of every month and waits for 90 minutes before giving up.
job_monthly
Re-indexes, organizes, and purges its records based on the file created by the
mainframe. This job runs at 2:00 a.m. on the first of the month only when
job_Fwatch completes successfully.
A third job, job_daily, is not contained in box_monthly and runs only if job_Fwatch and
job_monthly complete successfully.
 Advanced Job Flows

Chapter 6: Box Jobs 211

The failure of job_Fwatch causes box_monthly to terminate because box_monthly can
only complete successfully if both of the jobs it contains complete successfully. This in
turn triggers the job_terminator attribute in job_monthly, which terminates the job if
the box that contains it fails.
 How a Box Job Is Created

212 User Guide

How a Box Job Is Created
Box jobs are a convenient way to start multiple jobs. When you put jobs in a box, you
only have to start a single job (the box) for all the jobs in the box to start running.
Assume you want to schedule a group of jobs to start running when a file watcher job
completes successfully. Instead of making each job dependent on the file watcher job,
you can create a box job that is dependent on the file watcher job, remove the file
watcher job dependency from the individual jobs, and put all of those jobs in the box.
When the file watcher job completes successfully, the box job starts, which in turn starts
all of the jobs it contains.
Note: For more information, see the Reference Guide.

Example: Creating a Box Job
This example shows how to define a box job named EOD_box that depends on the
success of a file watcher job to run:
insert_job: EOD_box
job_type: box
condition: success(EOD_watch)
This JIL script instructs CA Workload Automation AE to do the following:
■ Add a new job named EOD_box.
■ Define the job as a box job.
■ Run the job only if the file watcher job named EOD_watch completes with a
SUCCESS status.

Box Job Attributes
The following attributes are required for all box job definitions:
box_name
Defines the name used to identify the job to CA Workload Automation AE. This
name is used by other jobs as the name of their parent box.

job_type: BOX
Specifies that the job type is box.
Note: If you omit this attribute, the job type defaults to cmd (Command job).
 How Job Groupings Are Created

Chapter 6: Box Jobs 213

condition
Defines the dependency conditions that must be met for the job to run.
Note: The condition attribute is not always required, for example when a job is
always started manually.

How Job Groupings Are Created
Box jobs provide one method of grouping jobs, but are typically used when all the jobs
in the box share the same starting condition. CA Workload Automation AE provides the
group and application attributes so you can logically group sets of jobs and boxes with
unrelated starting conditions or dependencies. By specifying both group and application
attributes in a job definition, you can make the job belong to both a group logical set
and an application logical set.

Note: For more information, see the Reference Guide.
Example: Associate Jobs with Groups and Applications
This example shows how you can associate jobs with specific groups and applications to
control processing.
Assume you want to create a set of jobs that run a suite of applications called
EmployeePay that is used to manage employee salaries. The Accounting and Human
Resources groups each have their own jobs defined to use the EmployeePay
applications. The following JIL script defines two jobs (HR_payroll and
ACCT_salaryreport):
insert_job: HR_payroll
job_type: cmd
...
group: HumanResources
application: EmployeePay
insert_job: ACCT_salaryreport
job_type: cmd
...
group: Accounting
application: EmployeePay How an Existing Job Is Put in a Box

214 User Guide

This JIL script instructs CA Workload Automation AE to do the following:
■ Add two new command jobs (HR_payroll and ACCT_salaryreport).
■ Associate job HR_payroll with the HumanResources group and the EmployeePay
application.
■ Associate job ACCT_salaryreport with the Accounting group and the EmployeePay
application.
To run a job associated with the EmployeePay application, enter the following:
sendevent -e STARTJOB -I EmployeePay
To run a job associated with the Accounting group, enter the following:
sendevent -e STARTJOB -B Accounting
To run a job associated with both the EmployeePay application and Accounting group
(intersection of both sets), enter the following:
sendevent -e STARTJOB -I EmployeePay -B Accounting
How an Existing Job Is Put in a Box
To place an existing job in a box, verify that the job is not running, and do either of the
following:
■ Use the update_job subcommand to change the current job definition.
■ Use the delete_job subcommand to delete the current job definition, and use the
insert_job subcommand to redefine the job.
This method is useful when the job definition contains many non-default attributes
that you want to deactivate instead of resetting them. However, if you delete and
redefine the job, you must redefine any non-default attributes you want to keep
from the previous definition.
Note: For more information, see the Reference Guide.
 Delete a Box Job

Chapter 6: Box Jobs 215

Example: Put an Existing Job in a Box
This example shows how to update the definition of an existing job to include it in a box.
The following JIL script uses the update_job subcommand to change the EOD_post job
to put it in the EOD_box job:
update_job: EOD_post
box_name: EOD_box
This JIL script instructs CA Workload Automation AE to do the following:
■ Update the job named EOD_post.
■ Put the job named EOD_post in the box named EOD_box.

Delete a Box Job
To delete a box and every job it contains, enter the delete_box subcommand followed
by the name of the box job to delete. For example, to delete the box EOD_box and
every job in it, you would enter the following:
delete_box: EOD_box
To delete a box without deleting the jobs it contains, enter the delete_job command
followed by the name of the box job to delete. The jobs in the box become stand-alone
jobs. For example, to delete the box EOD_box without deleting the jobs in it, you would
enter the following:
delete_job: EOD_box

Chapter 7: Command Jobs 217

Chapter 7: Command Jobs

This section contains the following topics:
Command Jobs (see page 217)
The Directory the Job Runs Under (see page 219)
Determining Which Shell is Used (UNIX) (see page 219)
Shell Initialization Files (UNIX) (see page 220)
Define a Command Job (see page 222)
Attributes with Default Values (see page 225)
Verify File Space Before a Job Starts (see page 228)
Pass Positional Arguments in a Command Job (see page 229)
Pass Environment Variables in a Command Job (see page 230)
Define Alternative Error, Input, and Output Sources (see page 233)
Create a Job Blob (see page 234)
Send a User-Defined Exit Code (see page 236)
Specify a Command or Script Name Without the Full Path (see page 237)
Specify a Command or Script Name Using an Environment Variable (UNIX) (see page
239)
Run a Script Under a Specific User Account (UNIX) (see page 240)
Modify Resource Limits (UNIX) (see page 242)
Customize the Run-time Environment for a Korn Shell Script (UNIX) (see page 243)
Customize the Run-time Environment for a Bourne Shell Script (UNIX) (see page 244)
Customize the Run-time Environment for a C Shell Script (UNIX) (see page 245)
Define a Command Job to Run a Perl Script (UNIX) (see page 246)
Run the Windows Command Interpreter (Windows) (see page 247)
Access Network Resources (Windows) (see page 249)

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

218 User Guide

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)