Chapter 4: Working with Jobs

Chapter 4: Working with Jobs

Jobs 
All activity controlled by CA Workload Automation AE is based on jobs. A job is any
single command or executable, UNIX shell script, or Windows batch file. Other objects,
such as monitors, reports, and the Job Status Console, track job progress. A job is the
foundation for the entire operations cycle.
You define jobs to CA Workload Automation AE by creating job definitions. Each job
definition contains attributes that specify the job's properties and behavior. For
example, you can specify conditions that determine when and where a job runs.
 Jobs

You can define jobs using the following methods:
JIL
A scripting language that lets you define and modify assets such as jobs, global
variables, machines, user-defined job types, external instances, and blobs.
CA WCC
A tool that lets you interactively set the attributes that describe when, where, and
how a job should run. The fields in the CA WCC GUI correspond to the JIL
subcommands and attributes. In addition, from the CA WCC GUI, you can define
calendars, global variables, and monitor and manage jobs. CA WCC is supplied with
CA Workload Automation AE.
Both methods set the same attributes and the job definition is always stored in the
database. You can also update and delete existing jobs.
Notes:
■ The scheduler must be running before you start any processes, so you should start
it before performing the tasks described in this chapter.
■ For information about using the CA WCC GUI to define jobs, see the CA WCC
documentation.
■ Before you update or delete an existing job, ensure that the job is not running. To
help avoid losing job definitions in the event of a system failure, we recommend
that you back up your job definitions periodically.



More information:
The jil Command and JIL (Job Information Language)

Job Types
When you create a job definition, you must specify the job type. Job types define the
type of work to be scheduled. For example, you can create a CMD job to run a Windows
command, an FTP job to download a file from a server, or an SAPEM job to monitor for
the triggering of an SAP event. You can also define box jobs, which are containers that
hold other jobs or box jobs. You can define your own job type.
Each job type has required and optional attributes that define the job. The job types
have many common attributes and CA Workload Automation AE treats them all
similarly. The primary differences between them are the actions taken when the jobs
run.
The structure of a job depends on the job type. For example, the following illustration
shows the structure of a Command, File Watcher, and Box job:
 Common Job Attributes


Common Job Attributes
Some JIL attributes are common to all job types. For example, you can define any job to
send an alarm if the job fails or terminates. You can also define starting or restart
conditions for any job.
Required Attributes for All Job Types
The following attributes are required for all job types:
■ job_name
■ machine
Note: By default, the job type is set to CMD. You can specify a different job type using
the job_type attribute.
Optional Attributes for All Job Types
The following attributes are optional for all job types:

■ alarm_if_fail ■ notification_id
■ application ■ notification_msg
■ auto_delete ■ owner (This attribute does not apply
to File Trigger jobs.)
■ auto_hold ■ permission
■ avg_runtime ■ priority
■ box_name ■ resources
■ box_terminator ■ run_calendar
■ condition ■ run_window
■ date_conditions ■ send_notification
■ days_of_week ■ service_desk
■ description ■ start_mins
■ exclude_calendar ■ start_times

■ group

■ svcdesk_attr Job States



■ job_load ■ svcdesk_desc
■ job_type ■ svcdesk_imp
■ max_run_alarm ■ svcdesk_pri
■ min_run_alarm ■ svcdesk_sev
■ must_complete_times ■ term_run_time
■ must_start_times ■ timezone
■ n_retrys


Job States
CA Workload Automation AE tracks the current state, or status, of every job. CA
Workload Automation AE displays job status in the job report that the autorep
command generates and in the CA WCC GUI.
The scheduler records job run information, including job status. The ujo_job_status
table stores job status for the current run, and the ujo_job_runs table stores job status
for previous runs. These tables use numeric codes to represent job status. The numeric
codes are resolved using the ujo_intcodes table. A job can have one of the following
statuses:
ACTIVATED (9)
Indicates that job is contained in a box job with a status of RUNNING but that the
job itself is waiting to start.
FAILURE (5)
Indicates that a job fails to complete successfully. The scheduler issues this alarm
when the alarm_if_fail attribute in a job definition is set to Y and that job fails.

INACTIVE (8)
Indicates that a newly created job has not yet run for the first time.
PEND_MACH (14)
Indicates that the offline status of the machine to which a job is assigned prevents
the job from starting. These jobs can otherwise logically start, so the scheduler
attempts to start them when the offline machine returns to service.
Note: You can use the GlobalPendMach configuration options to control how jobs
in PEND_MACH status start and what happens to new jobs scheduled to currently
offline machines. For more information about the GlobalPendMach parameters on
UNIX, see the Administration Guide. For more information about the Global Pend
Machine fields on Windows, see Online Help.
 Job States


ON_HOLD (11)
Indicates that the job is on hold and cannot run until you take it off hold.
Notes:
■ You can place a job in this status only by sending the JOB_ON_HOLD event.
■ To take a job off hold, send the JOB_OFF_HOLD event.

ON_ICE (7)
Indicates that the job is removed from the job stream but is still defined.
Notes:
■ You can place a job in this status only by sending the JOB_ON_ICE event.
■ To return a job that is on ice to the job stream and resume running it, send the
JOB_OFF_ICE event.

ON_NOEXEC (16)
Indicates that the scheduler bypasses execution of the job.
Notes:
■ You can place a job in this status only by sending the JOB_ON_NOEXEC event.
■ These jobs, and box jobs containing them, evaluate as successfully completed.
Downstream jobs that are dependent on these jobs still run, conditions
permitting.
■ When you instruct the scheduler to bypass the execution of a box job, the
scheduler automatically places all jobs in that box job in ON_NOEXEC status.
■ To resume executing bypassed jobs, send the JOB_OFF_NOEXEC event.


QUE_WAIT (12)
Indicates that a lack of available load units on the machines to which a job is
assigned prevent the job from starting. When the required load units become
available, the job starts.

RESTART (10)
Indicates that the scheduler is attempting to restart a job that failed to start as
scheduled. The scheduler attempts to restart the job at periodic intervals until the
job starts or the maximum number of restart attempts is exceeded.
Note: You can set the maximum number of restart attempts to zero (0). If the
scheduler reaches the maximum number of restart attempts without successfully
starting the job, the job fails. The maximum number of restart attempts depends on
the following global settings:
■ Max Restart Trys (on the Windows Administrator) or MaxRestartTrys (in the
UNIX configuration file)
■ Max Restart Wait (on the Windows Administrator) or MaxRestartWait (in the
UNIX configuration file)
 Job States



RESWAIT (15)
Indicates that the job is waiting for a resource before it can continue running. When
the resource is available, the job starts.

RUNNING (1)
Indicates one of the following situations:
■ The agent is executing the job.
■ The scheduler has instructed the agent to start jobs that are contained in the
box job.
Note: A box job acts as a container for other jobs but performs no action itself. The
agent does not execute box jobs. The scheduler places box jobs in RUNNING status
to send a message to the agent that it can start jobs that are contained in the box
job. These jobs start as soon as they meet the starting conditions that are specified
in the job definitions.

STARTING (3)
Indicates that the scheduler initiated the start job procedure with the agent. This
status does not apply to box jobs.

SUCCESS (4)
Indicates that the job exits with a code equal to or less than the maximum exit code
for success specified in the job definition. A box job enters this status in the
following situations:
■ All jobs that are contained in the box job succeed.
■ The exit condition for the box job evaluates to TRUE.
 Job States


TERMINATED (6)
Indicates that the job ends while it is still in the RUNNING state. The scheduler
issues an alarm when a job is terminated. A job is terminated when one of the
following situations occurs:
■ You send a KILLJOB event.
■ You issue the kill command (UNIX).
■ The job definition specifies that the scheduler should terminate the job under
specific circumstances and those circumstances occur. For example, you can
specify that the scheduler should terminate a job when the box job containing
it fails.
■ The job does not complete within the maximum run time specified in the job
definition
WAIT_REPLY (13)
Indicates that the job cannot continue running without manual intervention. The
scheduler issues an alarm when a job requires a user response to continue running.
Note: The job continues running only when you reply to this alarm by sending the
REPLY_RESPONSE event.
The job state reflects the most recent event processed. A job enters one of the
completed states (such as SUCCESS) when all of the events that are associated with that
job are processed, and the job remains in that state until the job starts again.
Sometimes displays a status that does not reflect reality; for example, the system
displays completed jobs as in the RUNNING state when the scheduler is still processing
events that are associated with that job. You can use the autorep command to view all
the of the events (including unprocessed events) that are associated with a job. For
more information about the autorep command, see the User Guide.
 Job States



Note: The scheduler determines whether or not to start jobs based on a number of
factors. These factors depend on the job type and the state of the job:
■ The scheduler re-evaluates starting conditions for jobs that are in the ON_HOLD
state when you issue the JOB_OFF_HOLD event using the sendevent command. The
scheduler also re-evaluates starting conditions for jobs that are leaving one of the
following queued states:
■ QUE_WAIT
■ RES_WAIT
■ PEND_MACH
The scheduler does not re-evaluate date and time conditions for these jobs if they
meet those conditions while they are on hold or queued. Jobs that meet date and
time conditions while they are on hold or queued start unless they do not meet
other starting conditions. Jobs that did not meet date and time conditions while
they were on hold or queued and still do not meet those conditions do not start.
You can configure CA Workload Automation AE to skip starting condition evaluation
for queued jobs. In this case, the jobs start immediately upon leaving the queue,
even if their starting conditions are no longer satisfied.
■ The scheduler does not start jobs that are in the ON_ICE state when you issue the
JOB_OFF_ICE event using the sendevent command. These jobs start the next time
that their starting conditions recur.
■ The scheduler starts box jobs that are in the ON_NOEXEC state but does not start
jobs of other types that are in this state. The scheduler places these box jobs in
RUNNING status but individual ON_NOEXEC jobs that are contained in the box job
remain in the ON_NOEXEC state. The scheduler automatically generates one
BYPASS event against jobs that are in the ON_NOEXEC state. The BYPASS event is
sent in place of the completion event for box jobs and in place of the RUNNING,
STARTING and completion events for individual jobs. After the scheduler places an
ON_NOEXEC box job in RUNNING status, the scheduler waits for all jobs in the box
job to bypass execution before returning the box job to the ON_NOEXEC state.
■ Box jobs in ON_NOEXEC status start and all of the jobs that are contained in the box
job enter the ACTIVATED state. The scheduler immediately bypasses and marks as
complete the jobs that are contained in the box job unless other conditions apply.
Jobs that are not marked complete by the time the box job completes enter or
remain in the ON_NOEXEC state.
■ All jobs that are contained in a box job enter the ACTIVATED when the box job
starts. Jobs run immediately unless other conditions apply. Jobs contained in a box
job that do not complete by the time that the box job completes enter INACTIVE
status. These jobs do not retain their statuses from previous box job processing
cycles when a new box job cycle begins.

More information:
Box Jobs (see page 187)

 Defining Jobs


Defining Jobs
Job definitions specify the work that individual jobs do.
When you define jobs, you can optionally schedule those jobs using the date and time
condition attributes. Scheduling jobs to run on customized schedules requires defining
custom calendars that you can reference in job definitions. Jobs that do not have date
and time conditions specified in their definitions only run when you start them
manually.
To improve workload performance for certain types of jobs, you can define them to run
on a cluster.

Insert a Job Definition
Sometimes the job that you need to run does not have a definition stored in the
database. For example, a new policy requires that you regularly generate a report but
there is no job definition in the database for a job that produces this report. To create
the job definition, use the insert_job subcommand.
Follow these steps:
1. Do one of the following:
■ Issue JIL in interactive mode.
■ Open a JIL script in a text editor.

2. Specify the following definition:
insert_job: job_name
machine: machine_name
job_type: type
required_attribute: value
[attribute: value...]

job_name
Defines a unique name for the job.

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

type
Specifies the type of job you are defining.
 Defining Jobs



required_ attribute: value
Specifies the name of a required JIL attribute and the corresponding value. The
attributes that are required in a job definition depend on the type of job that
you are defining.
optional_attribute: value
(Optional) Specifies that name of an optional JIL attribute and the
corresponding value. The optional attributes that you can specify in a job
definition depend on the type of job that you are defining.

value
Defines the value of the corresponding attribute.

3. Do one of the following:
■ Enter exit if you are using interactive mode.
■ Redirect the script to the jil command if you are using a script.
The data is loaded into the database and the job is defined.
Note: You can also define a job using CA WCC. For more information about using CA
WCC, see the CA WCC Online Help.

Example: Define a Command Job
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
Update a Job Definition
Sometimes you must modify an existing job definition. For example, you must edit the
definition of a reporting job to comply with new reporting requirements. To modify the
definition, use the update_job subcommand.

Follow these steps:
1. Take one of the following actions:
■ Issue JIL in interactive mode.
■ Open a JIL script in a text editor.
 Defining Jobs

90 User Guide

2. Specify the following definition:
update_job: job_name
attribute: value
[attribute: value...]
job_name
Specifies the name of the job you want to update.

attribute
Specifies the name of a JIL attribute that applies to the job type that you are
updating. You can specify one or more attributes.
Note: For more information about specific job types, see the chapter for that
job type. 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.

value
Defines the value of the corresponding attribute.

3. Take one of the following actions:
■ Enter exit if you are using interactive mode.
■ Redirect the script to the jil command if you are using a script.
The data is loaded into the database and the job is updated.
Notes:
■ When you update a job, you cannot update the resources attribute in the existing
job definition if the job has a resource dependency and has held the resource.
■ You can also update a job using CA WCC. For more information about using CA
WCC, see the CA WCC Online Help.

More information:
Issue JIL in Interactive Mode on Windows (see page 33)
Issue JIL in Interactive Mode on UNIX (see page 33)
Issue JIL Using a Script on UNIX (see page 35)
Issue JIL Using a Script on Windows (see page 36)

 Defining Jobs



Defining Jobs to Run on a Cluster
Defining jobs to run on a cluster helps improve workload performance. We recommend
this method for the following types of jobs:
■ Jobs that use shared resources
■ Jobs with high CPU consumption
■ Command jobs that execute client utilities
You can define a job to run on a cluster when you are running CA Workload Automation
AE in a highly-available cluster environment that meets all of the following conditions:
■ The agent is clustered.
■ A machine is defined to represent the cluster.
Note: You can schedule command jobs that execute client utilities to run on a cluster
only when the client is also clustered.
A machine is defined to represent a cluster when the machine definition meets the
following requirements:
■ The machine representing the cluster is a real machine (not a virtual machine or a
machine pool).
■ The node name that is specified for the machine is the same as the host name of
the cluster that the machine represents.
■ The agent name that is specified for the machine is the same as the common agent
name for the agents that are installed on the cluster that the machine represents.
■ The agent port that is specified for the machine is the same as the common agent
port for the agents that are installed on the cluster that the machine represents.
■ The encryption type and key that are specified for the machine are the same as the
encryption type and key that are specified for the agents that are installed on the
cluster that the machine represents.
The cluster manager performs load balancing for jobs that use shared resources or have
high CPU consumption when you define those jobs to run on the cluster. Command jobs
that execute client utilities are more likely to succeed when you define them to run on a
cluster with multiple agents and clients installed on it.
Note: For more information about setting up a clustered agent and a clustered client,
see the UNIX Implementation Guide or the Windows Implementation Guide.
 Delete a Job

92 User Guide

Delete a Job
When you no longer need a job definition, you can delete it from the database.
Follow these steps:
1. Do one of the following:
■ Issue JIL in interactive mode.
■ Open a JIL script in a text editor.
2. Specify the following subcommand:
delete_job: job_name
job_name
Specifies the name of the job you want to delete.
3. Do one of the following:
■ Enter exit if you are using interactive mode.
■ Redirect the script to the jil command if you are using a script.
The delete request is issued. When JIL is in job verification mode (the default), the
delete_job subcommand scans the ujo_job_cond table and notifies you of any
dependent conditions for the deleted job before deleting it.
Note: You can also delete a job using CA WCC. For more information about using CA
WCC, see the CA WCC Online Help.
Example: Delete a Job
This example deletes the test_run job.
delete_job: test_run Running a Job After Using JIL



Running a Job After Using JIL
After you submit a job definition to the database, it runs according to the starting
parameters specified in its JIL script. That is, the scheduler continually polls the
database, and when it verifies that the starting parameters are met it runs the job.
If a JIL script does not specify any starting parameters for a job, the scheduler does not
start the job automatically; the job starts only if you issue the sendevent command.
Note: For more information, see the Reference Guide.
Example: Run a Job with the sendevent Command
This example assumes that a job named test_install has no starting parameters specified
in its JIL script. The only way to start it is to issue the following command:
sendevent -E STARTJOB -J test_install
This command tells the scheduler to start the job named test_install.

Specify the Job Owner
By default, the operating system user who invokes jil to define a job is the owner of that
job. You can change the owner a job by specifying a different user ID in the job
definition.
To change the owner of a job, specify the user ID of a CA Workload Automation AE user
in the owner attribute job definition. CA Workload Automation AE accesses the
associated password from the database.
Important! Jobs that run on other software, such as PeopleSoft and databases, can run
only when the owner specified in the job definition is defined as a user on CA Workload
Automation AE and on the authenticated software. For example, to run an SAP job,
specify an SAP user that is also defined as a CA Workload Automation AE user.
You can use the CA WAAE Security Utility to define users on CA Workload Automation
AE.
 Specify the Job Owner

94 User Guide

To specify the job owner, add the owner attribute to your job definition.
Notes:
■ The owner attribute does not apply to File Trigger jobs.
■ If CA Workload Automation AE is running in native security mode, you can change
the owner value only if you have EDIT superuser permissions.
■ If CA Workload Automation AE is running in external security mode using CA EEM,
you can change the owner value only if you have as-owner authority.
■ CA Workload Automation AE uses the owner value for all job types except for File
Trigger. CA Workload Automation AE does not use the oscomponent.default.user
parameter located in the agent's agentparm.txt file.
■ Other application specific uses of the owner attribute apply to certain job types. For
more information about these job type specific uses, see the documentation on
individual job types in the User Guide.
■ For more information about the owner attribute, see the Reference Guide.

Example: Specify a Job Owner
Suppose that CA Workload Automation AE is running in external security mode and you
have as-owner authority as defined in CA EEM. You can specify the owner attribute in
job definitions. The following job runs under the prod user on the unixagent computer:
insert_job: jobA
job_type: CMD
machine: unixagent
command: /bin/touch /tmp/test_run.out
owner: prod@unixagent Global Variables



Global Variables
You can define global variables using the sendevent command. After you define a global
variable to CA Workload Automation AE you can use the variable as a job dependency.
The job dependency is satisfied only when the value of the expression evaluates to
TRUE.
You can reference a global variable as part of the syntax of any of the following
attributes:
■ command
■ connect_string
■ destination_file
■ ftp_local_name
■ ftp_remote_name
■ i5_library_list
■ i5_name
■ i5_params
■ monitor_cond
■ scp_local_name
■ scp_remote_dir
■ scp_remote_name
■ sp_name
■ sql_command
■ std_err_file
■ std_in_file
■ std_out_file
■ success_criteria
■ tablename
■ text_file_name
■ trigger_cond
■ watch_file
 Global Variables

96 User Guide

Notes:
■ If the length of the attribute value exceeds the limits after the global variable
expansion, the job goes into a RESTART state. The job restarts based on the value
specified in the MaxRestartTrys (on UNIX) or Max Restart Trys (on Windows)
parameter.
■ For the std_in_file, std_out_file, and std_err_file attributes, the length of the
attribute value after the global variable expansion can exceed the limits by four
characters. For the command attribute, the length of the attribute value after the
global variable expansion can be up to 1024 characters.
■ If a global variable is not defined in the database, the scheduler displays a warning
message and continues the execution of the job.
■ For more information about using the sendevent command to define global
variables or about the attributes that support global variable substitution, see the
Reference Guide.
Example: Define a Global Variable
This example sets the global variable "Today" to a value of “12/25/2007":
sendevent -E SET_GLOBAL -G "Today=12/25/2007"
Example: Monitor a File Whose Name is Assigned to a Global Variable on UNIX
This example monitors a file whose name has been assigned to the global variable
file_1.
insert_job: ft_unix2
job_type: FT
machine: unixagt
watch_file: $${file_1} Global Variables



Example: Specify a File Name with a Global Variable on UNIX
This example redirects the job's standard error file output to a file whose path contains
the global variable named Today. You can use the sendevent command to set the value
of a global variable to today’s date.
insert_job: unix_glob_var
job_type: CMD
machine: unixagent
command: /usr/common/backup
std_err_file: /tmp/$${Today}.err
Example: Specify a File Name with a Global Variable on Windows
This example redirects the job's standard error file output to a file whose path contains
the global variable named Today. You can use the sendevent command to set the value
of a global variable to today’s date.
insert_job: win_globalvar
job_type: CMD
machine: winagent
command: “C:\COMMON\Backup”
std_err_file: "C:\tmp\$$Today.err"
More Information:
Job Dependencies Based on Global Variables (see page 108)

 Alerts

98 User Guide

Alerts
You can define the following job types to monitor a condition continuously:
■ CPU Monitoring (OMCPU)
■ Database Monitor (DBMON)
■ Database Trigger (DBTRIG)
■ Disk Monitoring (OMD)
■ File Trigger (FT)
■ Text File Reading and Monitoring (OMTF)
■ Windows Event Log Monitoring (OMEL)
■ Windows Services monitoring (OMS)
Each time the specified condition occurs, an ALERT event is written to the scheduler log
file (event_demon.$AUTOSERV on UNIX and event_demon.%AUTOSERV% on Windows).
An alert helps you track and report each time that a monitored condition occurs.
Note: An alert is only generated for triggers that occur during continuous monitoring.
Alerts are not generated for non-continuous monitoring (NOW and WAIT).

To stop a continuous monitor, you must complete the job manually by issuing the
following command:
sendevent –E KILLJOB –J job_name
For non-continuous monitors the proper event order will be reflected as:
1. STARTING
2. RUNNING
3. SUCCESS

For a continuous monitor the event order will be reflected as:
1. STARTING
2. RUNNING
3. ALERT
4. ALERT
5. ALERT...
6. KILLJOB
7. TERMINATED
8. JOBFAILURE (ALARM)
 Alerts



You can view the text of alerts using the following methods:
■ View the scheduler log file
■ Issue the following command:
autorep –J job_name –d
■ CA WCC
Note: You cannot manually send the ALERT event using the sendevent command.

Example: Trigger Alerts When Monitoring CPU Usage Continuously
This example continuously monitors used CPU on the unixagent computer. When the
job runs, it goes into a RUNNING status. When the job detects that the used CPU is
within 70 and 100 percent, an ALERT event is raised (an alert is written to the scheduler
log file). The available, used CPU and load averages will be reported as part of the ALERT
event and the status message is reported with the RUNNING event. Subsequently, each
time the job detects that the use CPU meets the monitored condition, an alert is
triggered. The job only ends when it is complete manually.
insert_job: cpu_monitoring_used
job_type: OMCPU
machine: unixagent
lower_boundary: 70
cpu_usage: USED
inside_range: TRUE
monitor_mode: CONTINUOUS
In contrast, the following example monitors used CPU in WAIT monitor mode. When the
job runs, it goes into a RUNNING status. When the job detects that the used CPU is
within 70 and 100 percent, the job completes. No alert is triggered. The available, used
CPU and load averages are reported on the SUCCESS event.
insert_job: cpu_monitoring_used_wait
job_type: OMCPU
machine: unixagent
lower_boundary: 70
cpu_usage: USED
inside_range: TRUE
monitor_mode: WAIT Starting Conditions

100 User Guide

Starting Conditions
CA Workload Automation AE verifies whether it should start a job by evaluating the
starting conditions defined for the job. All defined starting conditions must be true for a
job to start.
CA Workload Automation AE starts all jobs that meet their starting conditions, unless
one of the following conditions apply:
You place the job on hold or on ice. If you put a job on hold or on ice, the job does not
start until you take it off hold or off ice.
Notes:
■ To put a job on hold or on ice, issue the JOB_ON_HOLD or JOB_ON_ICE event using
the sendevent command. To take a job off hold or off ice, issue the JOB_OFF_HOLD
or JOB_OFF_ICE event.
■ You can also instruct the scheduler to bypass execution of a job by issuing the
JOB_ON_NOEXEC event.
■ Jobs in the ON_NOEXEC state start immediately when they meet their starting
conditions. The scheduler simulates running these jobs, but the agent does not
execute commands associated with the jobs. Jobs in this state immediately return
an evaluation of successfully completed on the Scheduler machine. When you issue
the JOB_OFF_NOEXEC event against a job in the ON_NOEXEC state, the agent
resumes executing commands associated with that job the next time the job runs.
■ External conditions prevent the job from running. Depending on the reason, CA
Workload Automation AE places the job in one of the following queued states:
– When an offline machine prevents the job from running, the job enters
PEND_MACH status.
– When held resources prevent the job from running, the job enters RES_WAIT
status.
– When unavailable load units prevent the job from running, the job enters
QUE_WAIT status.
When a job leaves a queued state, the scheduler determines whether to start the job by
re-evaluating starting conditions for that job unless you configure CA Workload
Automation AE to skip starting condition evaluation for queued jobs. If a job that is
contained in a box fails its starting condition checks when leaving the queue, the
scheduler places that job in the ACTIVATED state. If a job that is not contained in a box
fails its starting condition checks when leaving the queue, the scheduler places that job
in the INACTIVE state. If the job meets its starting conditions, or if you configure the
system to skip starting condition evaluation for queued jobs, the job starts.
When you take a job off hold, the scheduler re-evaluates starting conditions for that job.
When you take a job off ice, the scheduler does not restart the job until its starting
conditions recur, even if those conditions were met while the job was on ice. Starting Conditions



When you instruct the scheduler to bypass execution of a job, the scheduler starts the
job when it meets its starting conditions. The scheduler simulates running these jobs,
but the agent does not execute commands associated with the jobs. Bypassed jobs
evaluate as successfully completed on the scheduler machine. When you issue the
JOB_OFF_NOEXEC event, the agent executes commands associated with the specified
job the next time the job starts. Changing the executable status of a job does not affect
evaluation of starting conditions.
Notes:
■ When you take jobs off hold or when jobs leave a queued state, the scheduler does
not re-evaluate date and time conditions. Jobs that meet their date and time
conditions while they are in a queued state or on hold start as soon as they leave
the queue or are taken off hold unless other starting conditions apply and are not
satisfied.
■ If you configure CA Workload Automation AE to skip starting condition evaluation
for queued jobs, those jobs start immediately upon leaving a queued state.
■ For more information about configuring CA Workload Automation AE to skip
starting condition evaluation for queued jobs, see the Administration Guide or the
Online Help.
■ For more information about the sendevent command, see the Reference Guide.
When you put a job on ice or instruct the scheduler to bypass execution of the job, it
affects starting conditions of downstream dependent jobs. How CA Workload
Automation AE evaluates the downstream dependent jobs depends on the condition of
the job that you bypass or put on ice.
Suppose that you put JobA in ON_NOEXEC status. When CA Workload Automation AE
bypasses JobA, downstream jobs dependent upon JobA are evaluated when starting
conditions of JobA are met, based on the condition of JobA, as follows:

Condition Evaluates to
success (JobA) TRUE
failure (JobA) FALSE
terminated (JobA) FALSE
done (JobA) TRUE
notrunning (JobA) TRUE
exitcode TRUE, if the expression evaluates to true with an
exit code of 0
FALSE, if the expression evaluates to false with an
exit code of 0 Starting Conditions

102 User Guide

Suppose that you put JobA in ON_ICE status. The downstream jobs dependent upon
JobA are immediately evaluated based on the condition of JobA, as follows:

Condition Evaluates to
success (JobA) TRUE
failure (JobA) FALSE
terminated (JobA) FALSE
done (JobA) TRUE
notrunning (JobA) TRUE
exitcode FALSE

Date and Time Dependencies
You can use JIL statements to schedule CA Workload Automation AE jobs to start at a
specific date and time. CA Workload Automation AE then calculates a matrix of specified
day, date, and time values and starts jobs accordingly. A time range cannot span more
than 24 hours.
You can specify days of the week or actual dates, but you cannot specify both. For
example, you can define a job to start on Monday, Wednesday, and Friday at 8:00 a.m.
or on the 15th and the 30th of the month at 8:00 a.m. but not on Monday the 15th at
8:00 a.m.
You can specify days of the week using JIL, but you can only specify actual dates using
custom calendars. You can also specify a time zone to apply to your starting times, and
you can define a job to start at one specific time of day or hourly, denoted in minutes
past the hour.

TZ Environment Variable
Valid on UNIX
By default, jobs with time-based starting conditions that do not specify a time zone have
their start event scheduled based on the time zone under which the database runs.
Before you start the scheduler or application server, ensure that the TZ environment
variable is set. The scheduler or application server references this setting to determine
the default time zone. After you upgrade your database, you must start the scheduler to
insert a time zone offset value (calculated from the value of the TZ environment
variable) into the database. Do this before executing jil or autorep.
Important! Ensure that the database is running in the same time zone that the
scheduler starts up with.
 Starting Conditions



Job Dependencies Based on Job Status
You can define starting conditions to start jobs based on the current status of one or
more jobs that exist in the database. In this way you can program simple or complex
prerequisites for starting a job.
For example, you can implement a single-threaded, batch queue-like set of job
dependencies so that JobB starts when JobA achieves a SUCCESS status and JobC starts
when JobB achieves a SUCCESS status.

You can configure more complex conditions by combining a series of conditions with the
AND and OR logical operators. You can use the pipe symbol (|) instead of the word OR
and the ampersand symbol (&) instead of the word AND. Spaces between conditions
and delimiters are optional. You can specify even more complex conditions by grouping
the expressions in parentheses, which force precedence. The equation is evaluated from
left to right.
For example, in the following set of starting conditions, either both A and B must be
successful or both D and E must be successful for the statement to evaluate as TRUE:
(success(JobA) and success(JobB)) or (success(JobD) AND success(Job E))
Note: If you specify a condition for an undefined job, the condition evaluates as FALSE,
and any jobs dependent on this condition do not run. You can use the job_depends
command to check for this type of invalid condition statement.
The syntax for defining job dependencies is the same whether the job is being defined
using JIL or the CA WCC GUI, except that the JIL statement begins with the JIL condition
keyword.
 Starting Conditions

104 User Guide

The following is the syntax for conditions based on job status:
status(job_name)
status
Indicates the status as one of the following:
success
Indicates that the status condition for job_name is SUCCESS, ON_ICE or
ON_NOEXEC. You can abbreviate this value to s.
failure
Indicates that the status condition for job_name is FAILURE. You can abbreviate
this value to f.
done
Indicates that the status condition for job_name is SUCCESS, FAILURE,
TERMINATED, ON_ICE or ON_NOEXEC. You can abbreviate this value to d.
terminated
Indicates that the status condition for job_name is TERMINATED. You can
abbreviate this value to t.
notrunning
Indicates that the status condition for job_name is anything except RUNNING
or STARTING. You can abbreviate this value to n.

job_name
Identifies the job on which the new job is dependent.
You can also abbreviate the dependency specification EXIT CODE to e and VALUE (of a
global variable) to v.
You can use the max_exit_success (maximum exit code for success) attribute set for a
job to control the value of the SUCCESS status. If you specify this attribute, any job that
exits with an exit code less than or equal to the specified value is treated as a success. A
FAILURE status means the job exited with an exit code higher than this value. The
default exit code for normal job completion is 0. A TERMINATED status means the job
was killed.
Note: You can use either uppercase or lowercase letters to specify a status. However,
you cannot use mixed case.
 Starting Conditions



Example: Job Dependencies
For a job that runs only when the job named DB_BACKUP succeeds, you would specify
the job dependency as follows:
success(DB_BACKUP)
If JobC should only start when both JobA and JobB complete successfully or when both
JobD and JobE complete (regardless of whether JobD and JobE failed, succeeded, or
terminated), you would specify the following dependency in the job definition for JobC:
(success(JobA) AND success(JobB)) OR (done(JobD) AND done(JobE))
As indicated in this example, you can use any job status as part of the specification for a
specific job's starting conditions. With this latitude, you can program branching paths
that must be taken and provide alternate actions for error conditions.
For example, if JobB fails after partially processing, you might want to call a routine
called Backout that reverses the changes that were made. You would specify the
following job dependency in the job definition for Backout:
failure(JobB)
You can use the notrunning operator to keep multiple jobs from running simultaneously.
For example, assume you do not want to run a database dump (DB_DUMP) and a file
backup (BACKUP) at the same time because such processing would adversely impact
performance. However, you might have a smaller job that can run as long as both of
these resource-intensive jobs are not running. You would specify the smaller job's
dependency as follows:
notrunning(DB_DUMP) AND notrunning(BACKUP)
Managing Job Status
Starting conditions that are based on job status use the current (or most recent)
completion status of the job. The current completion status is defined by the job run,
regardless of when that run occurred.
However, if you want to enforce the concept of time-based processing cycles, where the
completion status of a job for some previous time period should not affect the
processing of this time cycle, there are several options available.

When a box job starts, the status of all the jobs in the box changes to ACTIVATED.
Therefore, subsequent jobs in the box that depend on the completion of jobs performed
earlier in the same box only use the completion statuses from this box run. Placing the
jobs in one processing cycle inside a top-level box and setting the box to start at the
beginning of the processing cycle prevents time-critical jobs from being affected by
invalid information.
 Starting Conditions

106 User Guide

When a job is first entered into the database, and before it runs for the first time, its
status is set to INACTIVE. By changing the status of jobs that have completed but whose
completion status should no longer be used in dependent job conditions to INACTIVE,
the completion status from the last run is no longer the current status and it is not used.

Use the sendevent command to change a job status to INACTIVE. Alternatively, you
could create a CA Workload Automation AE job to accomplish this. If you change the
status of a top-level box to INACTIVE, all the jobs in the box also change to INACTIVE.
Deleting and reinserting the job using JIL accomplishes the same thing. However, the
past reporting history on the job is no longer available. Updating a job using JIL does not
change the status of the job.

Job Dependencies Based on Exit Codes
You can use the following syntax to base job dependencies on exit codes that indicate
completed tasks. In this way, you can implement even more specific branching logic for
recovering from job failures.
This method of defining job dependencies has the following format:
exitcode (job_name) operator value
job_name
Defines the name of the job upon which the new job depends.

operator
Specifies one of the following exit code comparison operators:
=
Equal to.
!=
Not equal to.
<
Less than.
>
Greater than.
<=
Less than or equal to.
>=
Greater than or equal to.
 Starting Conditions



value
Defines the numeric exit code value on which to base the dependency.
For example, if a broken communication line results in JobA failing with an exit code of
4, and you want the system to run a script (JobB) that redials the line when this code is
encountered, you would enter the following for the job dependency specification for
the JobB redial job:
exitcode (JobA) = 4
You can use any job status or exit codes as part of the specification for starting
conditions. You can abbreviate the dependency specification exitcode with the letter e
(uppercase or lowercase).

Exit Codes and Batch Files in Jobs Running on Windows
When you define jobs to run batch files on Windows, you should be aware of and
account for Windows-specific behavior.
Windows programs return any exit values that are programmed in the executable code.
This exit value is the last thing returned to Windows when the program terminates.

Generally, a zero (0) exit code indicates success, while a non-zero exit code indicates an
error. The expected error values should be documented with each individual program,
but some programs can return unexpected exit codes. Modify these programs so that
they return expected values, and use these values when specifying exit code
dependencies.

Jobs are created using standard Windows process creation techniques. After the job is
created, the agent waits for the job to complete. When the job completes, CA Workload
Automation AE gets the program exit code from Windows and stores it in the database
for later use.

When launching programs directly, the exit codes are returned and put in the database.
However, there are some exit code behaviors that you must take into consideration
when using a job to start *.BAT batch files.
 Starting Conditions

108 User Guide

The exit code returned from a batch file is the return code from the last operation
executed in that particular batch file. Consider the following example:
REM test batch file
test
if errorlevel 1 goto bad
goto good
:bad
del test.tmp
:good
exit
This sample batch file returns a 0 exit code when the test program exits with a 1 exit
code as long as test.tmp exists. If test.tmp does not exist, the return code is from the del
line and not from the line that runs the test. Therefore, this batch file returns a 0
(successful) exit code, even if test failed to execute as intended.

To help handle situations like this, CA Workload Automation AE supplies a program
called FALSE.EXE. This program resides in the Windows %AUTOSYS/bin directory and
takes only one parameter, which is the exit code you want FALSE.EXE to return on
completion. You can use FALSE.EXE as follows:
REM test batch file
test
if errorlevel 1 goto bad
exit
:bad
del test.tmp
false 1
When test fails with error level 1, this batch file returns an exit code of 1 from
FALSE.EXE, whether the test.tmp file exists or not.

Job Dependencies Based on Global Variables
You can base job dependencies on global variables set using the sendevent command.
When using global variables in this way, the job dependency is satisfied only when the
value of the expression evaluates to TRUE.
This method of defining job dependencies has the following format:
VALUE(global_name) operator value Starting Conditions



global_name
Defines the name of the global variable upon which the job depends.
Limits: This value can be up to 64 characters in length. The following characters are
valid: a-z, A-Z, 0-9, period (.), underscore (_), and hyphen (-). You can include spaces
in a global variable name.
operator
Specifies one of the following exit code comparison operators:
=
Equal to.
!=
Not equal to.

<
Less than.
>
Greater than.

<=
Less than or equal to.
>=
Greater than or equal to.

value
Defines the numeric or text value of the global variable on which to base the
dependency.
Limits: This value can be up to 100 characters in length and cannot contain
quotation marks or spaces. The following characters are valid: a-z, A-Z, 0-9, period
(.), underscore (_), and hyphen (-).
Note: When using JIL, use the condition attribute to enter the above expression in the
appropriate JIL script.

For example, assume that a set of jobs in a box should only run with a manager's
approval. In this case, use the following syntax to set the global variable named
manager-ok to OK, and make the top-level box job dependent on this global variable:
VALUE(manager-ok) = OK
You can abbreviate the dependency specification VALUE with the letter v (uppercase or
lowercase).
 Starting Conditions and Boxes

110 User Guide

Starting Conditions and Boxes
When you put a job in a box, it inherits all of the starting conditions of the box.
Therefore, all starting conditions defined for the box must be met and the box must
enter the RUNNING state before the job can run. If there are no additional conditions on
the job, it starts as soon as the box starts. A job runs only once for each box execution.
By default, there is no sequential job processing in a box. For example, if three jobs are
in a box, all three jobs start when the box starts if they have no additional conditions.
To implement a processing sequence for jobs in a box, you must specify additional
starting conditions for each job. For example, you could specify that Job1 has no starting
conditions, Job2 depends on the completion of Job1, and Job3 depends on the
completion of Job2.
Note: Jobs that depend on a job that is ON_ICE status run immediately as if the starting
condition of the ON_ICE has instantly been satisfied. Jobs that depend on a job that is in
ON_NOEXEC status only run when the starting condition of the ON_NOEXEC job has
been satisfied. In this scenario:
■ If Job2 enters the ON_ICE status, Job1 and Job3 start simultaneously when the box
they are in starts running.
■ If Job2 enters the ON_NOEXEC status, CA Workload Automation AE bypasses Job2
and starts Job3 after Job1 completes.
■ If Job2 is in the ON_ICE state, the box completes successfully after Job1 and Job3
complete.
■ If Job2 is in ON_NOEXEC status, the box completes successfully after CA Workload
Automation AE bypasses Job2 and Job1 and Job3 complete.


More Information:
Global Variables (see page 95)

 Controlling Jobs in PEND_MACH Status



Controlling Jobs in PEND_MACH Status
The scheduler puts a machine in the offline state if it is unable to contact the agent to
run a job. You can manually put a machine in the offline state by issuing the sendevent
command to send a MACH_OFFLINE event. Jobs that are scheduled to start on offline
machines are placed in PEND_MACH status by default.
When an offline machine returns to service, the scheduler immediately starts all jobs in
PEND_MACH status on that machine. Starting too many jobs in PEND_MACH status on
the machine at a time places a heavy demand for resources on both the scheduler and
agent computers. This may introduce performance problems that affect all scheduled
workload.
You can use the GlobalPendMachInterval, GlobalPendMachStatus, or
GlobalPendMachDelay parameters (on UNIX) or the Global Pend Mach Interval, Global
Pend Mach Status, or Global Pend Mach Delay fields (on Windows) to:
■ Control the starting of jobs in PEND_MACH status when an offline machine returns
to service.
■ Control the status of jobs that are scheduled on a machine that is currently offline.
Notes:
■ The values specified in the GlobalPendMachInterval, GlobalPendMachStatus, or
GlobalPendMachDelay parameters (on UNIX) or the Global Pend Mach Interval,
Global Pend Mach Status, or Global Pend Mach Delay fields (on Windows) are
applied at the global level and not at the machine level or job level. That is, these
values apply to all machines that return to service and have jobs in PEND_MACH
status that are scheduled to start on them.
■ If the scheduler changes the status of a job from PEND_MACH to any other valid
status because of the GlobalPendMachStatus parameter (on UNIX) or the Global
Pend Mach Status field (on Windows) setting or a manual CHANGE_STATUS event,
the job is not run when the machine returns to service. Only jobs in PEND_MACH
status are eligible to start on the machine that returns to service.
 Controlling Jobs in PEND_MACH Status

112 User Guide

Controlling the Starting of Jobs in PEND_MACH Status
You can control the starting of jobs in PEND_MACH status in the following ways:
■ By defining the time interval (in seconds) that the scheduler waits before starting
jobs in PEND_MACH status when an offline machine returns to service.
■ By defining the burst value. The burst value defines the number of jobs in
PEND_MACH status that the scheduler starts after waiting for the specified interval.
The scheduler starts the specified number of jobs, waits for the specified interval, starts
the specified number of jobs, waits for the specified interval, and so on. This process
repeats until all jobs in PEND_MACH status for that machine are started. On UNIX, you
can configure this setting using the GlobalPendMachInterval parameter in the
configuration file. On Windows, you can configure this setting using the Global Pend
Mach Interval field on the Scheduler window of CA Workload Automation AE
Administrator (autosysadmin).
When an offline machine returns to service, the scheduler updates the status of all jobs
scheduled for that machine from PEND_MACH to ACTIVATED unless the jobs fail their
starting condition checks. If a job fails its starting condition checks, the scheduler
updates its status to INACTIVE, unless it is in a box. All jobs contained in boxes are
placed in the ACTIVATED state, even if they fail their starting condition checks.
Note: You can configure CA Workload Automation AE to skip re-evaluation of starting
conditions for queued jobs. If you use this configuration option, the scheduler
immediately updates jobs in the PEND_MACH state to ACTIVATED when the required
machine returns to service. For more information about this configuration option, see
the Administration Guide or the Online Help.
If the ACTIVATED jobs meet their starting conditions or if CA Workload Automation AE is
configured to skip starting condition evaluation for queued jobs, the scheduler verifies
the following before starting the jobs:
■ Manual changes to the status of the job—If you send a manual CHANGE_STATUS
event for a job and the status of the job is updated, the scheduler detects the status
change and does not run the job on the machine. A message is written in the
scheduler log and the scheduler proceeds with the next job start.
■ Issuing a FORCE_STARTJOB event—If you issue a FORCE_STARTJOB event for a job,
the scheduler detects the status change and does not run the job on the machine. A
message is written in the scheduler log and the scheduler proceeds with the next
job start.
 Controlling Jobs in PEND_MACH Status



■ Reevaluation of the scheduled machine—The scheduler runs a job on a different
machine (any machine other than the machine that was used to bring the job out of
the PEND_MACH status) during the following situations:
– If a job is defined to run on a virtual machine and one or more component
machines in the virtual machine return to service, the scheduler determines
the best machine for the job from one of the component machines in the
virtual machine. The same applies for jobs that are defined to run against a
comma-separated list of machines. When one or more machines in the
comma-separated list of machines return to service, the scheduler determines
the best machine for the job from one of the machines in the list.
– If a job is initially defined against a single machine and you define a one-time
override against the machine attribute while the job is in PEND_MACH status
and the initial single machine returns to service, the scheduler starts the job on
the machine specified by the override. If the scheduler cannot contact the
machine specified by the override, it puts the job in PEND_MACH status until
the machine specified by the override becomes available.

– If a job is initially defined against a virtual machine and you define a one-time
override against the machine attribute while the job is in PEND_MACH status
and one or more component machines in the initial virtual machine return to
service, the scheduler starts the job on the machine specified by the override. If
the scheduler cannot contact the machine specified by the override, it puts the
job in PEND_MACH status until the machine specified by the override becomes
available.

– If a job is initially defined against a comma-separated list of machines and you
define a one-time override against the machine attribute while the job is in
PEND_MACH status, the scheduler behaves as follows:
– If you define a one-time override to a single machine while the job is in
PEND_MACH status, the scheduler starts the job when the overridden
single machine returns to service.
– If you define a one-time override to a virtual machine while the job is in
PEND_MACH status, the scheduler starts the job when one or more
component machines in the overridden virtual machine return to service.
The scheduler determines the best machine for the job from one of the
component machines in the overridden virtual machine.
 Controlling Jobs in PEND_MACH Status

114 User Guide

– If you define a one-time override to a different list of machines while the
job is in PEND_MACH status, the scheduler starts the job when one or
more machines in the overridden list return to service. The scheduler
determines the best machine for the job from one of the machines in the
overridden list.
If the scheduler cannot contact the machine specified by the override, it puts
the job in PEND_MACH status until the machine specified by the override
becomes available.
Note: Overriding the machine attribute of a job in PEND_MACH status does not
cause the scheduler to start the job. The job remains in PEND_MACH status
regardless of the status of the machine specified by the override. The scheduler
only evaluates jobs in PEND_MACH status when it processes the
MACH_ONLINE events.
■ Online machine status—If the scheduler loses contact with the machine, the
machine is put in offline state and all remaining jobs are put back in PEND_MACH
status.

Notes:
■ If you set the interval to 0 (the default value), the scheduler starts all jobs in
PEND_MACH status with no delay between job starts and the burst value is ignored.

■ The order in which the jobs are started depends on the job priority and amount of
time the job has been in PEND_MACH status. For example, if JOB1, JOB2, and JOB3
have the same priority and they enter the PEND_MACH status at 08:00:00 a.m.,
08:00:01a.m., and 08:00:02 a.m. respectively, the order in which they are started is
JOB1, JOB2, and JOB3. Once the scheduler determines the starting order of jobs
that are coming out of the PEND_MACH status, you cannot modify the starting
order by using the sendevent command to send the CHANGE_PRIORITY event. If
you send the CHANGE_PRIORITY event, the job priority changes do not apply to the
run of the job exiting in PEND_MACH status. The job priority changes apply to the
next run of the job.

■ If jobs enter PEND_MACH status at the same time and have the same priority, their
starting order is not guaranteed. If the job priority is set to 0, it overrides the
duration the job has been in PEND_MACH status and starts immediately.
■ For more information about the GlobalPendMachInterval parameter and
controlling the starting of jobs in PEND_MACH status on UNIX, see the
Administration Guide. For more information about the Global Pend Machine
Interval field and controlling the starting of jobs in PEND_MACH status on Windows,
see the Online Help.
 Controlling Jobs in PEND_MACH Status



Controlling the Status of Jobs Scheduled on an Offline Machine
You can control the status of jobs that are scheduled on a machine that is currently
offline in the following ways:
■ By defining the completion status that the scheduler assigns to jobs that are
scheduled on an offline machine. On UNIX, you can configure this setting using the
GlobalPendMachStatus parameter in the configuration file. On Windows, you can
configure this setting using the Global Pend Mach Status field on the Scheduler
window of CA Workload Automation AE Administrator (autosysadmin). The jobs
temporarily remain in PEND_MACH status before the scheduler assigns the status
specified in the GlobalPendMachStatus parameter (on UNIX) or the Global Pend
Mach Status field (on Windows).
Note: If the scheduler changes the status of a job from PEND_MACH to any other
valid status because of the GlobalPendMachStatus parameter (on UNIX) or the
Global Pend Mach Status field (on Windows) setting or a manual CHANGE_STATUS
event, the job is not run when the machine returns to service. Only jobs in
PEND_MACH status are eligible to start on the machine that returns to service.
■ By defining the time interval (in seconds) that the scheduler waits before updating
the status of the job to the status specified in the GlobalPendMachStatus
parameter (on UNIX) or the Global Pend Mach Status field (on Windows). On UNIX,
you can configure this setting using the GlobalPendMachDelay parameter in the
configuration file. On Windows, you can configure this setting using the Global Pend
Mach Delay field on the Scheduler window of CA Workload Automation AE
Administrator (autosysadmin).
Note: If you use the default value, the scheduler immediately sends a
CHANGE_STATUS event to update the status of jobs in PEND_MACH status to the
status specified in the GlobalPendMachStatus parameter (on UNIX) or the Global
Pend Mach Status field (on Windows). If you specify a value other than the default,
jobs remain in PEND_MACH status until the delay interval expires, and are then
assigned the status specified in the GlobalPendMachStatus parameter (on UNIX) or
the Global Pend Mach Status field (on Windows). If the machine returns to service
within the delay interval, the scheduler does not set the status of the job to the
status specified in the GlobalPendMachStatus parameter (on UNIX) or the Global
Pend Mach Status field (on Windows). Since the job is in PEND_MACH status when
the machine returns to service, the scheduler reschedules it to run on the online
machine based on the interval specified in the GlobalPendMachInterval parameter
(on UNIX) or the Global Pend Mach Interval field (on Windows).
Note: For more information about the GlobalPendMachStatus and
GlobalPendMachDelay parameters and controlling the status of jobs that are scheduled
on an offline machine on UNIX, see the Administration Guide. For more information
about the Global Pend Machine Status and Global Pend Machine Delay fields and
controlling the status of jobs that are scheduled on an offline machine on Windows, see
the Online Help.
 Job Run Numbers and Names

116 User Guide

Job Run Numbers and Names
CA Workload Automation AE uses run numbers for jobs. The run number is a unique
integer associated with every run of a job.
Consecutive run numbers are assigned every time a top-level job starts. A top-level job
is a job that is not contained in a box, and these run numbers are inherited by every job
in a box. This means that all jobs in a top-level box have the same run number as the
number used for the run of the box. This design permits runs of nested jobs to be
associated together in the same run.

If a job restarts, the run number remains the same and the ntrys field is incremented. In
the standard reports (autorep command), these two values are displayed in the run
column as run_num/ntry.

The run_num/ntry value is defined in the run-time environment for the job, and is
accessible to shell scripts or executables run as the job's command. This value is
contained in the variable $AUTORUN.

CA Workload Automation AE also maintains a value for each job's name, which is
defined in the runtime environment for the job.
As with $AUTORUN, this value is accessible to shell scripts or executables run as the
job's UNIX command. The value is contained in the variable $AUTO_JOB_NAME.

On Windows, the environment variables are %AUTORUN% and %AUTO_JOB_NAME%.

How Time Dependencies Are Set
If you do not define starting conditions for a job, it only runs when you issue a
sendevent command for it. You can set time dependencies for a job so that it runs
automatically on specific days and at specific times.
Note: For more information, see the Reference Guide.
Example: Set Time Dependencies for a Job
This example shows how to use the date_conditions, days_of_week, and start_times
attributes to set time dependencies for a job.
 How Time Dependencies Are Set



To set the existing job test_run to run automatically on certain days at a certain time
(such as 10:00 a.m. and 2:00 p.m. on Mondays, Wednesdays, and Fridays), you could
modify the job using the following JIL script:
update_job: test_run
date_conditions: y
days_of_week: mo, we, fr
start_times: "10:00, 14:00"
This JIL script instructs CA Workload Automation AE to do the following:
■ Update the job named test_run.
■ Activate the conditions based on date.
■ Set the job to run on Mondays, Wednesdays, and Fridays.
■ Start the job at 10:00 a.m. and 2:00 p.m. on each of the specified days.

The times shown in the sample script are surrounded by quotation marks because they
contain a colon. You can also use a backslash (\) as an escape character for the colon, as
the following example shows:
start_times: 10\:00, 14\:00
Note: If a job runs daily at the same time (for example, 12:00) and you edit the job
definition and save it at 11:59, the job will not run until the next day at 12:00.

When you save a start time job definition to the database within one minute of the
specified start time, the start time is placed in the future (that is, tomorrow). However,
if the start time is two minutes or more from the save time, the job runs at the next
occurrence of the specified start time (that is, today).

Example: Base Time Settings on a Specific Time Zone
Use the timezone attribute to base the time settings for a job on a specific time zone. If
you specify a time zone that includes a colon, you must surround the time zone name
with quotation marks, as in the following example:
timezone: "IST-5:30"
Example: Run a Job Every Day
To run the job every day, instead of only on specific days, specify the all value instead of
listing the individual day values. For example:
days_of_week: all Dependent Jobs

118 User Guide

Example: Schedule a Job to Run on Specific Dates
To schedule the job for specific dates, instead of specific days of the week, specify a
custom calendar. Use the autocal_asc command to define the calendar, and then use
the run_calendar attribute to specify the calendar name (for example, weekday_cal) in
the job definition. For example:
run_calendar: weekday_cal
Example: Exclude a Job from Running on Specific Dates
To specify a custom calendar that defines the days on which the job should not run, use
the autocal_asc command to define the calendar, and use the exclude_calendar
attribute to specify the calendar name (for example, holiday_cal) in the job definition.
For example:
exclude_calendar: holiday_cal
Example: Schedule a Job to Run at Specific Times Every Hour
To run the job at specific times every hour instead of at specific times of the day, use the
start_mins attribute to specify the minutes past every hour that the job should run. For
example, to run a job at 15 minutes after and 15 minutes before each hour, add the
following statement to the job definition:
start_mins: 15, 45
Dependent Jobs
Jobs can be dependent on the successful completion of other jobs. The only difference
between a dependent job and a simple job is its dependency on another job. To define
job dependencies, specify the condition attribute in the job definition.
CA Workload Automation AE lets you specify a time limit in the condition attribute that
applies in job dependency evaluations. The job's execution environment is verified
exclusively by the profile, which is sourced immediately before the job starts. On UNIX,
by default the /etc/auto.profile file on the client computer is sourced. On Windows, the
variables set by the installer in the agent’s profile directory are sourced or set. You can
use the profile attribute to override the default profile.
Note: For more information about the condition attribute, see the Reference Guide.
 Dependent Jobs



Example: Create a Dependent Command Job
This example shows a JIL script that defines a dependent command job named
EOD_post. EOD_post depends on the successful completion of the File Watcher job
named EOD_watch.
insert_job: EOD_post
job_type: cmd
machine: prod
condition: success(EOD_watch)
command: $HOME/POST
This JIL script instructs CA Workload Automation AE to do the following:
■ Add a new job named EOD_post.
■ Define the job as a command job.
■ Run the job on the client computer named prod.
■ Run the job only if the file watcher job named EOD_watch completes with a
SUCCESS status.
■ Source the /etc/auto.profile file (CA Workload Automation AE sources this file by
default), and run the job named POST located in the job owner's home directory.

More information:
Job Profiles (see page 127)

 Dependent Jobs

120 User Guide

Look-Back Conditions
CA Workload Automation AE supports look-back conditions. You can use look-back
conditions to base dependencies for a job on the last run of another job. The last run is
defined by the ending time of the last successful run of a job. If the job has run with the
specified result, the condition or predecessor is satisfied and the job starts. If not, the
condition is not satisfied and the job for which the look-back condition is defined does
not start.
To specify a look-back dependency, enter the job name followed by a comma (,) then
HH (hours), period (.) and MM (minutes).
Example: Specifying Look-Back Conditions
This example shows a job definition with look-back conditions.
In the following job definition, the command job test_sample_04 can only start if all of
the following conditions are met:
■ The last run of test_sample_01 completed successfully during the last 12 hours.
■ The last run of test_sample_02 completed with a FAILURE status during the last 24
hours.
■ The last run of test_sample_03 completed successfully at any time.
insert_job: test_sample_04
machine: localhost
command: sleep 10
condition: success(test_sample_01,12.00) AND failure(test_sample_02,24.00) AND
success(test_sample_03) Specifying One-Time Job Overrides



Specifying One-Time Job Overrides
You can use the override_job subcommand to specify an override that changes the
behavior of a specific job during its next run. Job overrides are applied only once. If a
RESTART event is generated because of system problems, CA Workload Automation AE
reissues a job override until the job actually runs once, or until the maximum number of
retries limit is met. After this, CA Workload Automation AE discards the override.
You can modify the following attributes in a job override:
■ auto_hold
■ command
■ condition
■ date_conditions
■ days_of_week
■ exclude_calendar
■ machine
■ max_run_alarm
■ min_run_alarm
■ n_retrys
■ profile
■ run_calendar
■ run_window
■ start_mins
■ start_times
■ std_err_file
■ std_in_file
■ std_out_file
■ term_run_time
■ watch_file
■ watch_file_min_size
■ watch_interval
 Specifying One-Time Job Overrides

122 User Guide

JIL will not accept an override if it results in an invalid job definition. For example, if a
job definition has only one starting condition, start_times, JIL will not let you set the
start_times attribute to NULL because removing the start condition makes the job
definition invalid (no start time could be calculated).
One-time job overrides are applied to jobs restarted due to system problems, but are
not applied to jobs restarted because of application failures.
System problems include the following:
■ Machine unavailability
■ Media failures
■ Insufficient disk space
Application failures include the following:
■ Inability to read or write a file
■ Command not found
■ Exit status greater than the defined maximum exit status for success
■ Various syntax errors
Notes:
■ Overriding the machine attribute of a job in PEND_MACH status does not cause the
scheduler to start the job. The job remains in PEND_MACH status regardless of the
status of the machine specified by the override. The scheduler only evaluates jobs
in PEND_MACH status when it processes the MACH_ONLINE events.
■ CA Workload Automation AE does not execute overridden jobs in ON_NOEXEC
status. If you issue a one-time override for a job in this status or put a job in this
status after overriding, the override remains in effect until you issue the
JOB_OFF_NOEXEC event.
 Date and Time Attributes and Time Changes



How Job Overrides Are Set
To set job overrides, use the override_job subcommand to specify the job and attributes
to override. You can also temporarily delete a job attribute in this manner.
Example: Define a One-time Override for a Job
This example shows how to define a one-time job override. The following script runs the
job RunData with no conditions (where some had been previously specified) and
outputs the results to a different output file:
UNIX:
override_job: RunData
condition: NULL
std_out_file: "tmp\SpecialRun.out"
Windows:
override_job: RunData
condition: NULL
std_out_file: "C:\tmp\SpecialRun.out"
Example: Cancel a Job Override Before it Runs
This example shows how to cancel a job override before it runs. To cancel overrides for
a job, enter the override_job subcommand followed by the job name and the delete
parameter. For example:
override_job: RunData delete
Note: After you submit a JIL script to the database, you cannot view the script or edit an
override. To change the override values, you must submit another JIL script with new
values or use the CA WCC Quick Edit. However, the original override remains stored in
the ujo_overjob table in the database.

Date and Time Attributes and Time Changes
Your operating system might automatically change the system clock to reflect the switch
to either standard time (ST) or daylight time (DT), and the scheduling of time-dependent
CA Workload Automation AE jobs might shift to adjust for the time change. Jobs that are
not time-dependent run as appropriate.
There are two types of time dependencies: absolute and relative.
 Date and Time Attributes and Time Changes

124 User Guide

Jobs with absolute time dependencies are defined to run at a specific time of the day
(for example, 9:30 on Thursday or 12:00 on December 25). The following attributes
define absolute time dependencies:
■ days_of_week
■ exclude_calendar
■ must_start_times
■ must_complete_times
■ run_calendar
■ run_window
■ start_times

Relative time dependencies are based either on the current time or relative to the start
of the hour (for example, start a job at 10 and 20 minutes after the hour, or terminate a
job after it has run for 90 minutes). The following attributes define relative time
dependencies:
■ auto_delete
■ max_run_alarm
■ min_run_alarm
■ must_start_times
■ must_complete_times
■ start_mins
■ term_run_time
■ watch_interval
During the time change, absolute time attributes behave differently than relative time
attributes.

Daylight Time Changes
Because the clock loses an hour during the change from standard time to daylight time
in the spring, CA Workload Automation AE cannot schedule any jobs using
time-dependent attributes during that time.
The solution is to schedule jobs with absolute time dependencies for the missing hour to
start during the first minute of the next hour. In this case, because the time change
automatically occurs at 2:00 a.m., a job scheduled to run on Sundays at 2:05 runs at
3:00:05 that day; a job scheduled to run every day at 2:45 runs at 3:00:45. Although it
might not be possible to start a large number of jobs during the first minute of the hour,
this feature does preserve the scheduling order.
 Date and Time Attributes and Time Changes



If you schedule a job to run more than once during the missing hour (for example, at
2:05 and 2:25), only the first scheduled job run occurs. Additional start times for the
same job in the missing hour are ignored.
Jobs with relative time dependencies run as expected. For example, a job specified to
run at 0, 20, and 40 minutes after the hour is scheduled for 1:00 ST, 1:20 ST, 1:40 ST,
3:00 DT, 3:20 DT, and 3:40 DT.

Run windows are treated differently. When the specified end of the run window falls
during the missing hour, CA Workload Automation AE recalculates its end time, so that
the effective duration of the run window remains the same. For example, the product
recalculates a run window of 1:00 - 2:30 so that the window ends at 3:30 and the run
window still remains open for 90 minutes.

When the run window’s specified start time falls during the missing hour, CA Workload
Automation AE moves the start time to 3:00. The end time does not change, so the run
window is shortened. For example, a run window of 2:45 - 3:45 becomes 3:00 - 3:45,
shortening the run window by 15 minutes.

When the run window’s start and end time both fall during the missing hour, CA
Workload Automation AE moves the start time to the first minute after 3:00 and the
end time to one hour later. Therefore, the resulting run window might be lengthened.
For example, a run window of 2:15 - 2:45 becomes 3:00 - 3:45, or 15 minutes longer.
 Date and Time Attributes and Time Changes

126 User Guide

Standard Time Changes
Because the clock gains one hour during the change from daylight time to standard time
in autumn, there are two 1:00-1:59 hours. CA Workload Automation AE only runs jobs
for which the start_time attribute is set to between 1:00 and 1:59 during the second
(standard time) hour. Jobs for which the start_mins attribute is set run in both hours.
For example, a job scheduled to run on Sundays at 1:05 runs only at the second 1:05. A
job scheduled to run every 30 minutes runs at 1:00 DT and 1:30 DT, then again at 1:00
ST and 1:30 ST, and so on, as the following illustration shows:

Jobs that are not time-based but have other dependencies still run during the first hour.

Jobs with relative time dependencies run as expected. For example, if a job is scheduled
to run on Sunday at 0:30 and its term_run_time attribute is set to 120 minutes, the job
would normally terminate at 2:30. On the day of the autumn time change, the job
terminates at 1:30 standard time, which is 120 minutes after the job started.

When testing how the change from daylight time to standard time affects your jobs, you
must set the system clock to a time before 1:00 a.m. and allow the entire hour to pass
before you can observe the time change. If you manually set the time to a period during
the 1:00 a.m. to 2:00 a.m. window, the system assumes that the time change has
already occurred and does not reset at 2:00 a.m.

Run windows are treated differently. When the specified start of a run window is before
the time change and its specified end occurs during the repeated hour, the run window
closes during the daylight time period (the first hour). For example, a run window of
11:30 - 1:30 ends at 1:30 DT, not 1:30 ST (that is, the run window remains open for its
specified two hours, not for three hours). A problem might occur if there are also
associated start times for the job that occur during the repeated hour. If the job in our
example also had a start time of 1:15, the start time would be calculated for 1:15 ST and
the job would not run on the day of the time change.
 Job Profiles


When the specified opening of the run window falls during the repeated hour, CA
Workload Automation AE moves its start time to the second, standard time hour. The
end time does not change, so the length of the run window remains the same. For
example, a run window of 1:45 - 2:45 becomes 1:45 ST - 2:45 ST.
When both the specified start and end of the run window occur during the repeated
hour, the run window opens during the second, standard time hour.

Job Profiles
A job profile defines the non-system environment variables for a job. When you define a
job, you can assign a job profile to it. Only one profile can be sourced for a job.
Job profiles apply to the following job types:
■ Command jobs
■ File Watcher (FW) jobs that are submitted to the legacy agent

On UNIX, job profiles are shell scripts that typically include the definitions and exports of
environment variables. The command that the job runs can reference these variables.
You can store job profiles on UNIX in any directory. Job profiles on UNIX are always
sourced using the job owner's default shell, which is set for the user in the etc/passwd
file. Therefore, when you create a job profile, you must use the syntax of the owner's
default shell. For example, if the owner's default shell is the Korn shell, you must use
Korn syntax in the profile script.

On Windows, you create job profiles using the Job Profiles window in the CA Workload
Automation AE Administrator utility. These profiles contain variable=value pairs that
define the environment variables. The profiles are stored in the
SystemAgent\agent_name\profiles directory of the CA Workload Automation AE
computer. If you move a job profile to another location, you must specify the full path
when you assign the profile to a job. The agent uses the variable=value pairs in the job
profile to set the environment variables.

Environment Variables
System environment variables are automatically set in the environment of a job.
However, user environment variables are not automatically set. You must define all
other required environment variables using one or both of the following methods:
■ envvars attribute in the job definition
■ Job profile
 Job Profiles

128 User Guide

If a job profile is assigned to a job, the agent sources the profile before running the job.
When the agent reads the profile, the environment variables in the profile are
expanded. For example, if Path is a variable in the profile, the following occurs:
■ Any environment variables specified in the value of Path are expanded.
■ That path is used to search for the command.
■ The new value for the %Path% variable is set before running the command.

If you want to specify the full path name, you can use variables set from the job profile
in the path name specification.
The agent reads profile variables in alphabetical order. Therefore, if you plan to expand
variables in the profile itself, you must define the variables so that they are in the
appropriate order when read alphabetically.

Notes:
■ On the agent, you can define environment variables that apply to all jobs at a global
agent level, scheduling manager level, or user level. For example, suppose that you
want to set an environment variable for all jobs that run on an agent under a
specific user (owner). Instead of defining that variable in every job definition using
the envvars attribute or in a job profile, you can define the variable on the agent
using the oscomponent.environment.variable_user_userid parameter. For more
information about setting environment variables on the agent, see the CA Workload
Automation Agent for UNIX, Linux, or Windows Implementation Guide.
■ For more information about the envvars and profile JIL attributes, see the Reference
Guide.
 Job Profiles



How the Environment for a Job is Sourced
System environment variables are automatically set in the environment for a job. When
the job is submitted, the agent processes the following additional information to source
the environment, in the following order:
1. Variables set during the CA Workload Automation AE installation.
■ On UNIX the auto.profile file is automatically created during CA Workload
Automation AE installation and contains variable definitions such as
AUTOUSER. This file is located on the CA Workload Automation AE computer.
■ On Windows variables are set by the installer in the agent’s profile directory.
The WAAE.txt file contains a set of variables for the product, and an
<instance_name>.txt file contains a set of variables for each instance. Typically,
these files contain the %AUTOROOT%, %AUTOSYS%, %AUTOUSER%, and
%PATH% variables.
2. Environment variables defined using the envvars attribute in the job definition (if
specified)
3. The job profile defined using the profile attribute (if specified)
Note: The environment variables are set before the job profile variables. Therefore, you
can reference system environment variables in job profiles. However, if a variable is set
more than once, the last value read is used.

Create a Job Profile
You can create a job profile to define the non-system environment variables that must
be set for a Command job or for a File Watcher (FW) job that is submitted to a legacy
agent.
To create a job profile, do one of the following:
■ On UNIX, create a shell script file that contains the environment variables you want
to source.
You must use the syntax for the default shell of the job owner. You can store this
script in any directory.
■ On Windows, use the Job Profiles window in the CA Workload Automation AE
Administrator utility.
The job profile is stored in the SystemAgent\agent_name\profiles directory of the
CA Workload Automation AE computer.
Note: For more information about creating, viewing, and deleting job profiles on
Windows, see the Online Help.
 Job Profiles

130 User Guide

Assign a Job Profile to a Job
You can assign a job profile to a job to source the non-system environments that must
be set before the job can run.
Follow these steps:
1. Do one of the following:
■ Define a Command job (see page 222).
■ Define a File Watcher job on the legacy agent. (see page 297)
2. Add the following attribute to the job definition:
profile: path_name
Specifies a profile that defines the non-system environment variables for the
job.
Notes:
■ On UNIX, specify the name of the profile script. Alternatively, you can
specify path/profile_name.
■ On Windows, specify the name of the profile that you created in the
Administrator utility. Alternatively, you can specify path\profile_name.
■ You can specify both the computer name and the profile name, which lets
you run the job on one computer while using a job profile defined on
another computer. For example, you can specify the following path on
Windows: \\machine_name\share_name\profile_name.txt

3. Run the job.
The job profile is assigned to Command or File Watcher job.
Notes:
■ Job profiles are instance-specific. You cannot assign a profile defined in one CA
Workload Automation AE instance to a job defined in another.
■ For more information about the profile attribute, see the Reference Guide. You can
also use CA WCC to assign a profile to one or more jobs.
 Must Start Times and Must Complete Times



Convert Job Profiles to the New Format (Windows Only)
In Unicenter AutoSys JM 4.5.1 and r11 on Windows, job profile information was stored
in the Windows registry. To upgrade to r11.3, Release 11.3.5, or Release 11.3.6, the job
profile information in the registry must be converted to a file format that is compatible
with the new CA Workload Automation Agent for Windows. When you upgrade CA
Workload Automation AE, the upgrade process automatically converts the job profiles.
You can also issue the autoprofm command to manually convert profiles.
Follow these steps:
1. Click Start, Programs, CA, Workload Automation AE, Command Prompt
(instance_name).
The CA Workload Automation AE command prompt opens. The command prompt
presets all the environment variables for the instance.

2. Enter the following command:
autoprofm -P directory [-N agent_name] [-x] [-?]
The job profiles in the Windows registry are converted to the new format and
stored in text files. The new files are stored in the directory specified by the -P
option.
When a job is submitted in r11.3, Release 11.3.5, or Release 11.3.6, the agent refers
to the converted profile specified in the profile attribute and sources the
environment variables.
Note: For more information about the autoprofm command, see the Reference Guide.

Must Start Times and Must Complete Times
You can define the time that a job must start or complete by. If the job does not start by
its must start time or complete by its must complete time, an alert is issued. Defining
must start times and must complete times is helpful when you want to be notified that a
job has not started or completed on time. For example, a must start alarm can alert you
to investigate whether the job's starting conditions have not been satisfied or whether
the job is stuck in the STARTING state.
You can specify more than one must start time or must complete time for a job. If the
job has multiple start times, you must specify the same number of must start times or
must complete times. For example, if the job runs at three different times during the
day, you must specify three must start times, corresponding to each run of the job.
 Must Start Times and Must Complete Times

132 User Guide

To define must start times, add the must_start_times attribute to your job definition.
To define must complete times, add the must_complete_times attribute to your job
definition.
You can specify both must_start_times and must_complete_times attributes in the
same job definition.

After the job is defined, you can issue the autorep -q command to display the must start
times and the must complete times. You can issue the autorep -d command to view the
alarms generated. You can also view the scheduler log file (event_demon.$AUTOSERV
on UNIX and event_demon.%AUTOSERV% on Windows) to see which alarms were
issued.
Note: For more information about the syntax for the must_start_times and
must_complete_times attributes, see the Reference Guide.

How Must Start Times and Must Complete Times Work
When you define a job with the must_start_times or must_complete_times attribute,
the job definition and corresponding events are added to the database. The scheduler
checks the events to determine whether to issue alarms.
CA Workload Automation AE uses the following process to track the must start and
must complete times:
■ The job is inserted in the event table in the database.
■ If the job definition includes the must_start_times attribute, a CHK_START event
corresponding to the next must start time is inserted in the event table.
■ If the job definition includes the must_complete_times attribute, the
CHK_COMPLETE event corresponding to the next must complete time is inserted in
the event table.

■ The scheduler checks the CHK_START event to see whether the job has started
successfully.
■ If the job has not started, a MUST_START_ALARM is issued. An alert is written to
the scheduler log file to indicate that the CHK_START criteria has not been satisfied.
■ The scheduler checks the CHK_COMPLETE event to see whether the job has
completed successfully. The scheduler checks for the SUCCESS, FAILURE, or
TERMINATED events.
 Must Start Times and Must Complete Times



■ If the job has not completed, a MUST_COMPLETE_ALARM is issued. An alert is
written to the scheduler log file to indicate that the CHK_COMPLETE criteria has not
been satisfied.
■ After the job completes, the scheduler calculates the next must start time and must
complete time for the job and inserts the following events in the event table:
– A new STARTJOB event
– A new CHK_START event for the next must start time
– A new CHK_COMPLETE event for the next must complete time

Examples: Specifying Must Start Times and Must Complete Times
The following examples are jobs that have must start times and must complete times
defined:
Example: Specify Absolute Must Start and Must Complete Times
This example defines a job to run every day at 10:00 a.m., 11:00 a.m., and 12:00 p.m.
The job must start by 10:02 a.m., 11:02 a.m., and 12:02 p.m. respectively. The job must
complete by 10:08 a.m., 11:08 a.m., and 12:08 p.m. respectively. Otherwise, an alarm is
issued for each missed start or complete time.
insert_job: test_must_start_complete
command: /opt/StartTransactions.sh
machine: localhost
date_conditions: y
days_of_week: all
start_times: "10:00, 11:00, 12:00"
must_start_times: "10:02, 11:02, 12:02"
must_complete_times: "10:08, 11:08, 12:08"
Note: The number of must start times and must complete times must match the
number of start times. Otherwise, the job cannot be defined. For example, the job
cannot be defined if it has one start time and two must start and complete times, as
follows:
start_times: "10:00"
must_start_times: "10:02, 12:02"
must_complete_times: "10:08, 12:08" Must Start Times and Must Complete Times

134 User Guide

Example: Specify Absolute Must Start and Must Complete Times on the Next Day
This example defines a job to run every day at 12:00 a.m. Suppose that you want each
job run to start by 10:10 a.m. the next day and end by 10:12 a.m. the next day. You must
specify 34:10 in the must_start_times attribute and 34:12 in the must_complete_times
attribute.
insert_job: job3
command: echo "hello"
machine: localhost
date_conditions: y
days_of_week: all
start_times: "12:00"
must_start_times: "34:10"
must_complete_times: "34:12"
The must start time is calculated as follows:
must start time + 24 hours
= 10:10 + 24 hours
= 34:10
The must complete time is calculated as follows:
must complete time + 24 hours
= 10:12 + 24 hours
= 34:12
If a job run does not start by the must start time, a MUST_START_ALARM is issued to
notify you that the job has not started on time. If a job run does not complete by the
must complete time, a MUST_COMPLETE_ALARM is issued to notify you that the job has
not completed on time.

Example: Specify Relative Must Start and Must Complete Times
This example defines a job to run every day at 10:00 a.m., 11:00 a.m., and 12:00 p.m.
Each job run must start within 3 minutes after each start time (10:03 a.m., 11:03 a.m.,
and 12:03 p.m.). Each job run must complete within 8 minutes after each start time
(10:08 a.m., 11:08 a.m., and 12:08 p.m.). Otherwise, an alarm is issued for each missed
start or complete time.
insert_job: test_must_start_complete
job_type: CMD
machine: localhost
command: /opt/StartTransactions.sh
date_conditions: y
days_of_week: all
start_times: "10:00, 11:00, 12:00"
must_start_times: +3
must_complete_times: +8 Delete Obsolete Job Versions



Example: Specify Relative Must Start and Must Complete Times With start_mins
This example defines a job to run every day at 10 minute intervals every hour (for
example, 2:00 p.m., 2:10 p.m., 2:20 p.m., and so on). Each job run must start within 2
minutes after the specified start times and complete within 7 minutes after the
specified start times. Otherwise, an alarm is issued for each missed start or complete
time. For instance, the 2:10 p.m. job run must start by 2:12 p.m. and must complete by
2:17 p.m.

insert_job: test_must_start_complete
job_type: CMD
machine: localhost
command: /opt/StartTransactions.sh
date_conditions: y
days_of_week: all
start_mins: 10, 20, 30, 40, 50, 00
must_start_times: +2
must_complete_times: +7
Delete Obsolete Job Versions
When you update or delete a job definition, previous versions of the definitions are
stored in the database. To prevent the database from being overloaded with job
versions, you can delete obsolete job versions. Job versions are obsolete when the job is
inactive and the database no longer refers to it.
Note: We recommend that you issue the archive_events command before issuing the
archive_jobs command. We also recommend that you run archive_jobs as part of your
usual database maintenance.
Follow these steps:
1. Do one of the following:
■ On UNIX, run the shell that is sourced to use CA Workload Automation AE.
The UNIX operating system prompt is displayed.
■ On Windows, click Start, Programs, CA, Workload Automation AE, Command
Prompt (instance_name).
The CA Workload Automation AE command prompt opens. The command
prompt presets all the environment variables for the instance.

2. Enter the following command:
archive_jobs -j number_of_days [-d "directory_name"] [-A] [-x] [-?]
The obsolete job versions are deleted.
Note: For more information about the archive_jobs command, see the Reference Guide.
 Restricting the Runtime Behavior of Jobs

136 User Guide

Example: Delete Obsolete Job Versions
■ This example deletes obsolete job versions older than 7 days:
archive_jobs -j 7
■ This example deletes obsolete job versions older than 7 days and creates the
archive flat file in the $AUTOUSER/archive file (the default):
archive_jobs -j 7 -A
■ This example deletes obsolete job versions older than 7 days and creates the
archive flat file in the /tmp/archive directory:
archive_jobs -j 7 -A -d "/tmp/archive"
Restricting the Runtime Behavior of Jobs
You can define the following environment variables on CA Workload Automation AE to
restrict the runtime behavior of a job:
RESTRICT_FORCE_STARTJOB=1
Restricts a user from running multiple instances of a job while the job is in a
RUNNING state.

RESTRICT_DELETE_JOB=1
Restricts a user from deleting a job when the job is in ACTIVATED, RUNNING, or
STARTING states.

RESTRICT_DELETE_DEPENDENT_JOB=1
Restricts a user from deleting a job if the job has dependencies.