AutoSys®

User Guide
for UNIX

Version 3.5.1
This documentation and related computer software program (hereinafter referred to as the
"Documentation") is for the end user's informational purposes only and is subject to change
or withdrawal by Computer Associates International, Inc. ("CA") at any time.
This documentation may not be copied, transferred, reproduced, disclosed or duplicated, in
whole or in part, without the prior written consent of CA. This documentation is proprietary
information of CA and protected by the copyright laws of the United States and international
treaties.
Notwithstanding the foregoing, the user may print a reasonable number of copies of this
documentation for its own internal use, provided that all CA copyright notices and legends
are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the
user who are bound by the confidentiality provisions of the license for the software of the user
will have access to such copies.
This right to print copies is limited to the period during which the license for the product
remains in full force and effect. Should the license terminate for any reason, it shall be the
user's responsibility to return to CA the reproduced copies or to certify to CA that same have
been destroyed.
To the extent permitted by applicable law, CA provides this documentation "as is" without
warranty of any kind, including without limitation, any implied warranties of
merchantability, fitness for a particular purpose or noninfringement. In no event will CA be
liable to the end user or any third party for any loss or damage, direct or indirect, from the use
of this documentation, including without limitation, lost profits, business interruption,
goodwill, or lost data, even if CA is expressly advised of such loss or damage.
The use of any product referenced in this documentation and this documentation is governed
by the end user's applicable license agreement.
The manufacturer of this documentation is Computer Associates International, Inc.
Provided with "Restricted Rights" as set forth in 48 C.F.R. Section 12.212, 48 C.F.R. Sections
52.227-19(c)(1) and (2) or DFARS Section 252.227-7013(c)(1)(ii) or applicable successor
provisions.
©1993, 1999, 2001 Computer Associates International, Inc., One Computer Associates Plaza,
Islandia, New York 11749. All rights reserved..
Table of Contents

Preface
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Command Syntax Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
UNIX and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Contacting Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii

1 • Introduction to AutoSys
AutoSys Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
Defining Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
System Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4
Event Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5
Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-6
Remote Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-7
Example Scenario on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-7
Interface Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
AutoSys Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
AutoSys Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
Basic AutoSys Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Extending AutoSys Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16

AutoSys User Guide for UNIX iii ■

■ Table of Contents

2 • AutoSys Security
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Security on Events Sent by Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Security on Events Sent by the Event Processor . . . . . . . . . . . . . . . . . . . 2-5
System-Level Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
AutoSys Database Field Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Job Definition Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Remote Agent Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
AutoSys User and Database Administrator Passwords . . . . . . . . . . . . . 2-10
AutoSys Job-Level Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
AutoSys Job Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
AutoSys User Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
AutoSys Permission Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Job Permissions and Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
AutoSys Superuser Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Edit Superuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Exec Superuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Restricting Access to AutoSys Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Remote Agent Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19

3 • AutoSys Jobs
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Job Types and Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Basic Job Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Command Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Box Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
File Watcher Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
Basic Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Command Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
File Watcher Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Box Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Job States and Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
Example State Diagram - Simple Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
Example State Diagram - Box Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14

■ iv AutoSys User Guide for UNIX

 Table of Contents ■

Starting Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15

Starting Parameters and Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
Date/Time Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
Job Dependencies Related to Job Status . . . . . . . . . . . . . . . . . . . . . . . . 3-18
Event Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
Event Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
Job Dependencies Based on Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . 3-26
Job Dependencies Based on Global Variables . . . . . . . . . . . . . . . . . . . 3-28
Job Run Numbers and Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
Defining Jobs in AutoSys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
AutoSys Graphical User Interface Components . . . . . . . . . . . . . . . . . . 3-31

4 • Job Attributes
Job Attributes and Job Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-3
Using JIL to Create a Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-3
Using the GUI to Create a Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . .4-4
Chapter Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-4
Essential Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-5
Attributes Common to All Job Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-5
Command Jobs Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-6
File Watcher Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-9
Box Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-9
Optional Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
Common Job Starting Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
Common General Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
Command Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
File Watcher Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26
Box Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27
Date and Time Attributes and Time Changes . . . . . . . . . . . . . . . . . . . . . . . 4-28
The Time Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28
AutoSys Behavior During Time Change . . . . . . . . . . . . . . . . . . . . . . . . . 4-29

AutoSys User Guide for UNIX v ■

■ Table of Contents

5 • Box Job Logic

Basic Box Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Default Box Job Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
When You Should Not Use a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
What Happens When a Box Runs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
Box Job Attributes and Terminators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Attributes in a Box Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Attributes in a Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Time Conditions in a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Force Starting Jobs in a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
How Job Status Changes Affect Box Status . . . . . . . . . . . . . . . . . . . . . . 5-10
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Advanced Conditions in Box Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Default Box Success and Box Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14
Explicit Box Success and Box Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
Using the Box Terminator Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
Using the Job Terminator Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
Advanced Job Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19

6 • Defining AutoSys Jobs Using the GUI

Starting the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
GUI Control Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Job Definition Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
The Job Definition Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Date/Time Options Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Job Definition Advanced Features Dialog . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Creating a Simple Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Creating a File Watcher Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13
Creating a Dependent Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Creating a Box Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19
Changing a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21
Setting Time Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23
Additional Time Setting Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25
Deleting a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
Deleting a Box Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27

■ vi AutoSys User Guide for UNIX

 Table of Contents ■

Specifying One-Time Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27

Setting Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
Customizing the Job Definition GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31
Database Connection Time-out Interval . . . . . . . . . . . . . . . . . . . . . . . . 6-32
Job Definition Title Bar Text and Icon Text . . . . . . . . . . . . . . . . . . . . . . 6-32

7 • Defining Jobs Using JIL

Job Information Language (JIL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-3
JIL Syntax Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-3
JIL Sub-commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-5
Submitting Job Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-6
Running JIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-6
Creating a Simple Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-7
Creating a File Watcher Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-8
Creating a Dependent Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-9
Creating a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
Changing a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
Setting Time Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
Additional Time Setting Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
Deleting a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13
Deleting a Box Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14
Specifying One-Time Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14
Setting Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15
Example JIL Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16

8 • The Graphical Calendar Facility

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3
Scheduling Jobs with Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-4
Starting the Calendar Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-5
Calendar Facility Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-5
Calendar Definition Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-6
Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-7
Calendar Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Navigation Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12

AutoSys User Guide for UNIX vii ■

■ Table of Contents

Creating a Simple Calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14

Dates Prior to Today’s Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15
Calendar Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16
Term Calendar Rule Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17
Rule Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18
Examples of Date Selection Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20
Rescheduling Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22
Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24
Term Calendar Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-25
Combining Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27
Printing Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28
Import/Export File Name Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28
Importing Calendar Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28
Exporting Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-30
Customizing the Calendar Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-31
Font Selection Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-32
Object Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-33
Date Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-34
Window Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-34
Print Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-35
Calendar Title bar Text and Icon Text . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-35

9 • Load Balancing and Queuing Jobs

Real Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
Virtual Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
Defining Machines to AutoSys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
Specifying Machine Load (max_load) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5
Specifying Relative Processing Power (factor) . . . . . . . . . . . . . . . . . . . . . 9-6
Using max_load and factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Machine Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Defining a Real Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8
Deleting Real Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Defining a Virtual Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Deleting Virtual Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10

■ viii AutoSys User Guide for UNIX

 Table of Contents ■

Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11

Force Starting Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14
Load Balancing Using ServerVision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15
Testing the Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18
ServerVision Monitoring and Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18
Queuing Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18
Queuing and Simple Load Limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19
Queuing with Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20
Subsets—Individual Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-23
Multiple Machine Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-25
User-Defined Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-26

10 • The Operator Console

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4
Alarm Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4
InfoReports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5
Operator Console Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7
Starting the Operator Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7
Job Activity Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8
Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9
Job List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10
Currently Selected Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11
Starting Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14
Control Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15
Resizing Regions of the Job Activity Console . . . . . . . . . . . . . . . . . . . 10-24
Job Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24
Specifying a Job by Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
Specifying Jobs by Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-27
Specifying Jobs by Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28
Sorting the Specified Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
Setting the Job Selection Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
Changing the Console Clock Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30

AutoSys User Guide for UNIX ix ■

■ Table of Contents

Alarm Manager Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30

Alarm Manager Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-32
Alarm List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-32
Currently Selected Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-34
Alarm Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-36
Select by Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-37
Select by State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-37
Select by Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-38
Customizing the Operator Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-38
Refresh Time Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-39
Alarm Poll Time Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-39
Changing Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-40
Freeze Frame at Start Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-40
Font Selection Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-41
Label Font Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-41
List Font Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-41
Object Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-42
Job List Column Widths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-45
Operator Console Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-46
Default Report Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-46
Alarm List Column Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-46
Operator Console Title bar Text and Icon Text . . . . . . . . . . . . . . . . . . 10-47
User-Configurable Action Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-47
Console Clock Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-50

11 • Monitoring and Reporting Jobs

About Monitors and Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3
Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
Defining Monitors and Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
Using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
Using JIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
Chapter Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6

■ x AutoSys User Guide for UNIX

 Table of Contents ■

Essential Monitor/Report Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7

Common Essential Attributes—General . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Common Essential Attributes—Events . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Essential Report Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10
Optional Monitor/Report Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11
Optional Monitor Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11
Optional Report Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-12
Defining Monitors and Reports using the GUI . . . . . . . . . . . . . . . . . . . . . . 11-12
The Monitor/Browser Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-12
Defining an Example Monitor and Report . . . . . . . . . . . . . . . . . . . . . . 11-15
Defining Monitors and Reports using JIL . . . . . . . . . . . . . . . . . . . . . . . . . . 11-19
Running a Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-21
Customizing the Monitor/Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-22
Database Connection Time-out Interval . . . . . . . . . . . . . . . . . . . . . . . 11-22
Monitor/Browser Title bar Text and Icon Text . . . . . . . . . . . . . . . . . . 11-23

12 • Maintaining AutoSys
Maintaining the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Starting the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Monitoring the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
Stopping the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7
Shadow Event Processor Rollover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8
Running AutoSys in Test Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10
AutoSys Maintenance Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-12
Backing up AutoSys Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13
Restoring AutoSys Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16
AutoSys Database Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16
Event Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17
Database Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18
General Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20
Daily Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20
DBMaint Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-21
Event Server Rollover Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-23
Event Server Crash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-23
Synchronizing the Event Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-24

AutoSys User Guide for UNIX xi ■

■ Table of Contents

Improving Database Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-25

Improving Sybase Database Performance . . . . . . . . . . . . . . . . . . . . . . 12-25
Improving Oracle Database Performance . . . . . . . . . . . . . . . . . . . . . . 12-26
Maintaining Bundled Sybase SQL Servers . . . . . . . . . . . . . . . . . . . . . . . . . . 12-28
Sybase Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-28
Sybase Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-29
Default Sybase Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-29
Starting Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-31
Stopping Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-32
Accessing Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-33
Identifying Processes Connected to the Database . . . . . . . . . . . . . . . 12-34
Displaying the Database Date and Time . . . . . . . . . . . . . . . . . . . . . . . 12-35
Bundled Sybase Backup and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . 12-35

13 • Configuring AutoSys
AutoSys Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Configuration File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10
Database Time-out Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10
Cross-Instance Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . 13-11
Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-12
Event Processor Cascading Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-13
Machines to Check for Running Event Processors . . . . . . . . . . . . . . . 13-14
Third Machine for Event Processor Contention . . . . . . . . . . . . . . . . . . 13-14
Event Processor Log Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15
Internal Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-16
Event Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-17
Sendevent Retries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-18
Heartbeats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-18
Shadow Event Processor Pings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-19
Remote Agent Log Files Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-20
File Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-21
Number of Restart Attempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-23
Calculating the Wait Time Between Restarts . . . . . . . . . . . . . . . . . . . . 13-23
Method of Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-24

■ xii AutoSys User Guide for UNIX

 Table of Contents ■

KILLJOB Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-25

Port Number for Remote Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-26
AutoSysAgentSupport Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-27
Instance Wide Append Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-27
Job Starting Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-28
The auto.profile File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-29
Sample Default auto.profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-30
Remote Agent Database Connection Settings . . . . . . . . . . . . . . . . . . 13-31
Modifying Remote Agent Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-33
Remote Agent Socket Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-33
Running Two AutoSys Versions of Remote Agents . . . . . . . . . . . . . . 13-34
Configuring Remote Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-35
Configuring Event Processor Authentication . . . . . . . . . . . . . . . . . . . . 13-35
Client-Side Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-37
Configuring ServerVision Monitoring and Reporting . . . . . . . . . . . . . . . . 13-38
Library Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-38
svload Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-38
ServerVision Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 13-39
ServerVision Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-40
Monitoring Job Resource Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-40
User-Defined Alarm Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-41

14 • Troubleshooting
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Event Server Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Event Server is Down (Sybase) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Sybase Deadlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Not Enough User Connections (Bundled Sybase) . . . . . . . . . . . . . . . . . 14-7
archive_events Fails (Bundled Sybase) . . . . . . . . . . . . . . . . . . . . . . . . . . 14-9
Event Server Will Not Start (Bundled Sybase) . . . . . . . . . . . . . . . . . . . 14-11
Event Processor Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-11
Event Processor is Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12
Event Processor Will Not Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12

AutoSys User Guide for UNIX xiii ■

■ Table of Contents

Remote Agent Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-13

Remote Agent Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-13
Remote Agent Will Not Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-14
Remote Agent Will Start - Command Will Not Run . . . . . . . . . . . . . . . 14-17
Remote Agent Starts, Command Runs—No RUNNING Event is Sent . 14-20
xql Will Not Start (Sybase Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-23
Remote Agent Not Found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-24
Jobs Run Twice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-25
Job Failure Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-26
Jobs Run Only From the Command Line . . . . . . . . . . . . . . . . . . . . . . . 14-26

A • Integrating with the Mainframe and AutoSys Agents for AS/400

and OpenVMS
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Definition of Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
Job Scheduling for the Enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5
Configuring for Enterprise Job Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Stop the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Configure the AutoSys Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
License Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9
Restart the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
About asbrokerII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
Environment Variables for asbrokerII . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11
AutoSys and AutoSys Connect Cross-Platform Dependencies . . . . . . . . . . A-13
Job Scheduler Interdependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14
Notation for Cross-Platform Job Dependencies . . . . . . . . . . . . . . . . . . . A-15
Naming Conventions for AutoSys Connect Cross-Platform Jobs . . . . . A-16
Running AutoSys Jobs on Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-17
Agent Job Names and User IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-18
Running Jobs on Agent Managed Machines . . . . . . . . . . . . . . . . . . . . . A-18
Defining Agent Machines to AutoSys . . . . . . . . . . . . . . . . . . . . . . . . . . . A-19
AutoSys Agent Machine in an AutoSys Job Definition . . . . . . . . . . . . . A-20
Log and Trace Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-22

■ xiv AutoSys User Guide for UNIX

 Table of Contents ■

AutoSys Connect and AutoSys Agent Job Statuses . . . . . . . . . . . . . . . . . . . A-22

Unsupported Attributes for AutoSys Connect or AutoSys Agent Jobs . . . A-23
Cross-Platform Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-24

B • Troubleshooting CCI
Troubleshooting Tools for Remote CCI Connections . . . . . . . . . . . . . . . . . . .B-2
CCI Command Line Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-4
Reinstalling CCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-9

Index

AutoSys User Guide for UNIX xv ■

Preface
Welcome to the world of AutoSys, the scheduling and operations
automation software for distributed computing environments.

About This Guide 0

The AutoSys User Guide for UNIX explains how to define, run, monitor,
manage, and control AutoSys in UNIX. The chapters of this guide are
organized as follows.

Ch.
No. Chapter Name Content Description

1 Introduction to AutoSys Describes AutoSys and its system

architecture, system components,
events, alarms, and utilities. It also
includes descriptions of basic AutoSys
configurations as well as an overview of
basic functionality.
2 AutoSys Security Provides information about
permissions, superusers, and security.

AutoSys User Guide for UNIX xvii ■

■ Preface
About This Guide

Ch.
No. Chapter Name Content Description

3 AutoSys Jobs Describes AutoSys job types and

provides information about basic job
attributes, starting parameters, and job
states.
4 Job Attributes Describes the various attributes used to
define jobs in AutoSys. It also discusses
essential and optional job attributes,
which govern what a job does and
when and where it will run.
5 Box Job Logic Explains how box jobs work, including
default box behavior and how to
override the default behavior. It also
explains what types of jobs should and
should not be placed in a box. To
illustrate box logic, numerous
examples of box jobs are provided.
6 Defining AutoSys Jobs Describes how to use the AutoSys
Using the GUI Graphical User Interface (GUI), and
how to use the Job Definition dialog to
define a simple command job, a file
watcher job, and a dependent
command job. It describes defining
AutoSys box jobs, as well as changing
and deleting a job. It also explains how
to set time dependencies.
7 Defining Jobs Using JIL Describes how to use the AutoSys Job
Information Language or JIL to define a
simple command job, a file watcher
job, and a dependent command job. It
describes defining AutoSys boxes, as
well as changing and deleting a job.
Also provides an example JIL script.

■ xviii AutoSys User Guide for UNIX

 Preface ■
About This Guide

Ch.
No. Chapter Name Content Description

8 The Graphical Calendar Describes the AutoSys Graphical

Facility Calendar Facility and how to use it to
create, view, and maintain AutoSys
calendars. It also describes how to
access and use the various features of
the Calendar Facility, such as
previewing a calendar before applying
its dates and applying customized rules
to a calendar. Customizing the
Calendar Facility is also covered.
9 Load Balancing and Describes the use of real and virtual
Queuing Jobs machines in the AutoSys environment.
It also provides information about
load balancing jobs across multiple
machines, as well as queueing jobs to
real and virtual machines.
10 The Operator Console Describes the AutoSys Operator
Console and how to monitor and
control job activity in real-time. It also
describes how to access and use the
various features of the Console, such as
reviewing and reporting on any
AutoSys job, as well as using the Alarm
Manager. Customizing the Operator
Console is also covered.
11 Monitoring and Reporting Describes how to use the GUI or JIL to
Jobs define AutoSys monitors and browsers
(reports) using essential and optional
monitor and browser attributes.
12 Maintaining AutoSys Describes basic AutoSys maintenance
and how to maintain a bundled Sybase
database.

AutoSys User Guide for UNIX xix ■

■ Preface
Assumptions

Ch.
No. Chapter Name Content Description

13 Configuring AutoSys Describes the AutoSys configuration

file and how to modify the tunable
parameters in the file to control the
behavior of AutoSys.
14 Troubleshooting Provides useful information about
troubleshooting the primary AutoSys
components.
A Integrating AutoSys with Explains how to set up and implement
the Mainframe and these enterprise-wide scheduling with
AutoSys Agents for AutoSys, AutoSys Connect, and
AS/400 and OpenVMS AutoSys Agent components.
B Introducing CCI Describes how to configure CCI, the
Common Communication Interface,
with AutoSys.

Index Helps you locate information within

this manual.

Assumptions 0

This guide is for users responsible for defining jobs to AutoSys and
monitoring and managing these jobs. It assumes familiarity with the
operating system on which jobs will be run, and it assumes that you have
already installed and are running AutoSys using the procedures described
in the AutoSys Installation and Getting Started Guide for UNIX.

■ xx AutoSys User Guide for UNIX

 Preface ■
Typographical Conventions

Typographical Conventions 0

Some or all of the following conventions appear in this guide:

Symbol or
Type Style Represents Example

Bold a new term ...called a source object.

field names (optional) Click OK.

Magenta (online only) hotlinked ...see Chapter 3, Data

cross-references to other Migration.
sections in this guide; if
you are viewing this guide
online in PDF format, you
can click the cross-
reference to jump directly
to its location

Italic words that are emphasized ...the entry after the current
entry...

the titles of other General Facilities Reference

documents Guide

syntax variables COPY filename

Monospace directories, file names, &HIGHLVL.SRCLIB

command names,
computer code

computer screen text, Copy file? Y/N

system responses,
command line commands
Monospace what a user types ...enter RUN APP.EXE in the
bold Application field

AutoSys User Guide for UNIX xxi ■

■ Preface
Command Syntax Conventions

Symbol or
Type Style Represents Example

} choosing a command from File } Import } Object

a cascading menu
Highlighted used to callout screen text Dataset....
Screen Text Product....
on character- based screen Parmlib...
captures. (When viewed
online, the screen text will
be blue.)

Command Syntax Conventions 0

UNIX and Windows 0

Syntax statements for UNIX and Windows commands are formatted as

follows:
name [option...] [command argument...]

The following is an example:

xxx_stgd -h [-l [level]] [-L file] [-a port] [-d [level]] [-s server]
[-m hostname] [-S status] [action -P|-R -p {-T -H -y}]

■ Options consist of one character and are always preceded by a hyphen

(-).

■ Options with no arguments can be grouped after a single hyphen.

■ [ ]—Brackets surround an option or command argument that is not

required.

■ {}—Curly brackets enclose options or arguments that are

interdependent; everything enclosed must be treated as a unit.

■ |—Denotes OR condition.

■ xxii AutoSys User Guide for UNIX

 Preface ■
Contacting Technical Support

Contacting Technical Support 0

You can contact us with any questions or problems you have. You will be
directed to an experienced software engineer familiar with AutoSys. You
can contact Computer Associates Technical Support at:
http://esupport.ca.com.

Related Publications 0

As you use this AutoSys User Guide for UNIX, you might find it helpful to
have these additional books available for reference:

■ AutoSys and AutoSys/Xpert Release Notes for UNIX, version 3.4.6, which
provides important information about this release. Please read this
before proceeding.

■ AutoSys Installation and Getting Started Guide for UNIX, which describes
the basic AutoSys configurations, how to install AutoSys, including
how to configure AutoSys components, databases, and high
availability features. In addition, this guide describes how to enter
license keys.

■ AutoSys Reference Guide for UNIX, which lists the AutoSys commands
and job, machine, monitor, and report definition parameters. It also
describes system states, database tables and views, and the API.

AutoSys User Guide for UNIX xxiii ■

 1
Introduction to AutoSys
AutoSys is an automated job control system for scheduling, monitoring,
and reporting. These jobs can reside on any AutoSys-configured machine
that is attached to a network.

An AutoSys job is any single command, executable, script, or NT batch

file. Each AutoSys job definition contains a variety of qualifying
attributes, including the conditions specifying when and where a job
should be run.

As with most control systems, there are many ways to correctly define and
implement jobs. It is likely that the way you utilize AutoSys to address
your distributed computing needs will evolve over time. As you become
more familiar with both the features of AutoSys and the characteristics of
your own jobs, you will also refine your use of AutoSys.

However, before you install and use AutoSys, it is important to

understand the basic AutoSys system, its components, and how these
components work together.

AutoSys User Guide for UNIX 1-1 ■

■ Introduction to AutoSys

This chapter provides a brief overview of AutoSys, its system architecture,

and features.
AutoSys Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Defining Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

System Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Event Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Remote Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Example Scenario on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Interface Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10

AutoSys Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10

AutoSys Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11

Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11

Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12

Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12

Basic AutoSys Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13

Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14

Extending AutoSys Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16

■ 1-2 AutoSys User Guide for UNIX

 Introduction to AutoSys ■
AutoSys Jobs

1 AutoSys Jobs
In the AutoSys environment, a job is a single action that can be
performed on a valid AutoSys client machine. On UNIX, this action can
be any single command or shell script, and on NT, this action can be any
single command, executable, or batch file. In addition, job definitions
include a set of qualifying attributes.

For information on defining, running, managing, monitoring, and

reporting on jobs, see the chapters in this guide.

1 Defining Jobs
Using AutoSys utilities, you can define a job by assigning it a name and
specifying the attributes that describe its associated behavior. These
specifications make up the AutoSys job definition. These are the two
methods you can use to create job definitions:

■ Using the AutoSys Graphical User Interface (GUI).

■ Using the AutoSys Job Information Language (JIL) through a

command-line interface.

AutoSys Graphical User Interface

The AutoSys GUI allows you to interactively set the attributes that
describe when, where, and how a job should run. You create job
definitions using the GUI Control Panel and the dialogs you can launch
from it. The fields in the GUIs correspond to the AutoSys JIL
sub-commands and attributes. In addition, from the GUI Control Panel,
you can open applications that allow you to define calendars, monitors,
and reports, and that allow you to monitor and manage AutoSys jobs.

AutoSys User Guide for UNIX 1-3 ■

■ Introduction to AutoSys
System Components

Job Information Language

AutoSys JIL is a specification language, with its own syntax, that is used
to describe when, where, and how a job should run. When you enter the
jil command, you get the jil command prompt, at which you can enter
the job definitions one line at a time using this special language. When
you exit JIL, the job definition is loaded into the AutoSys database.
Alternatively, you can enter the definition as a text file and re-direct the
file to the jil command. In this case, the jil command activates the
language processor, interprets the information in the text file, and loads
this information in the AutoSys database.

System Components 1

The following are the main AutoSys system components:

■ Event Server (AutoSys database)

■ Event Processor

■ Remote Agent

In addition, AutoSys provides utilities to help you define, run, and

maintain AutoSys instances and jobs. The included utilities are platform-
specific; however, all platforms include the AutoSys GUI components
and JIL. Both the GUI and JIL allow you to define, manage, monitor, and
report on jobs.

■ 1-4 AutoSys User Guide for UNIX

 Introduction to AutoSys ■
System Components

Figure 1-1 illustrates the AutoSys system components in a basic

configuration. In addition, this figure illustrates the communication
paths between the components.

AutoSys Server UNIX Client

(UNIX or NT)
Remote Agent

Event Processor
UNIX Job

NT Client

Remote Agent
Event Server
(database)
NT Job

Figure 1-1 • AutoSys Components in a Basic Configuration

1 Event Server
The Event Server or AutoSys database (the RDBMS) is the data repository
for all system information and events as well as all job, monitor, and
report definitions. Event Server refers to the database where all the
AutoSys information, events, and job definitions are stored.

Occasionally, the database is called a dataserver, which actually describes

a server instance. That is, it is either a UNIX or Windows NT process, and
it is associated data space (or raw disk storage), which can include
multiple databases or tablespaces.

Note • The AutoSys database refers to the specific server instance and
the “autosys” database for that instance. Some utilities, such as isql
(Sybase), allow you to specify a particular server and database.

AutoSys User Guide for UNIX 1-5 ■

■ Introduction to AutoSys
System Components

High Availability Option - Dual Event Servers

AutoSys can be configured to run using two databases, or Dual Event
Servers. This feature provides complete redundancy. Therefore, if you
lose one Event Server due to hardware, software, or network problems,
AutoSys operations can continue on the second Event Server without loss
of information or functionality.

For various reasons, database users often run multiple instances of

servers that are unaware of the other servers on the network. When
implementing AutoSys, the database can run stand-alone for AutoSys
only, or it can be shared with other applications.

For more information on using Dual Event Servers, see Dual Event Servers
in Chapter 1, Introduction to AutoSys, of the AutoSys Installation and Getting
Started Guide for UNIX.

1 Event Processor
The Event Processor is the heart of AutoSys; it interprets and processes
all the events it reads from the AutoSys database. Sometimes called the
event_demon, the Event Processor is the program, running either as a
UNIX process or as a Windows NT service, that actually runs AutoSys. It
schedules and starts jobs.

After you start it, the Event Processor continually scans the database for
events to be processed. When it finds one, it checks whether the event
satisfies the starting conditions for any job in the database.

Based on this information, the Event Processor first determines what

actions are to be taken, then instructs the appropriate Remote Agent
process to perform the actions. These actions might be the starting or
stopping of jobs, checking for resources, monitoring existing jobs, or
initiating corrective procedures.

■ 1-6 AutoSys User Guide for UNIX

 Introduction to AutoSys ■
System Components

High Availability Option - Shadow Event Processor

AutoSys lets you set up a second Event Processor, called the Shadow
Event Processor. This second processor should run on a separate
machine to avoid a single point of failure.

The Shadow Event Processor remains in an idle mode, receiving periodic

messages (pings) from the Primary Event Processor. Basically, these
messages indicate that all is well. However, if the Primary Event Processor
fails for some reason, the Shadow Event Processor will take over the
responsibility of interpreting and processing events.

For more information on running a Shadow Event Processor, see Shadow

Event Processor in Chapter 1, Introduction to AutoSys, of the AutoSys
Installation and Getting Started Guide for UNIX.

1 Remote Agent
On a UNIX machine, the Remote Agent is a temporary process started by
the Event Processor to perform a specific task on a remote (client)
machine. On a Windows NT machine, the Remote Agent is a
Windows NT service running on a remote (client) machine that is
directed by the Event Processor to perform specific tasks.

The Remote Agent starts the command specified for a given job, sends
running and completion information about a task to the Event Server,
then exits. If the Remote Agent is unable to transfer the information, it
waits and tries again until it can successfully communicate with the
database.

1 Example Scenario on UNIX

The example scenario in Figure 1-2 and the numbered explanations that
follow it illustrate the interactions between the Event Server, the Event
Processor, and Remote Agents.

AutoSys User Guide for UNIX 1-7 ■

■ Introduction to AutoSys
System Components

In the example, the following UNIX command line is to be run on

“WorkStation_2,” at the start date and time specified in the AutoSys job
definition:
rm /tmp/mystuff/*

Note • Understanding this example will help you answer many

questions that might arise during your experiences with AutoSys.

PROCESS
PROCESS
Remote Agent
Event Processor
•Receives instructions from Event
1 •Determines Actions Processor

•Initiates Action: Start 2 3 •Initiates Action: Starts Child

job on machine com- Process
mand:’
rm /tmp/mystuff/*’ •Waits for Exit Code (from Child
Process)

•Sends Exit event back to Event

Server

5
PROCESS PROCESS
WorkStation_2
Event Server
UNIXCommand
•Events
•Runs UNIX Command:
•Job Definitions 4 rm /tmp/mystuff/*
Local Area •Completes execution and
Network exits with status

Figure 1-2 • Interaction of the Event Server, Event Processor, and Remote Agent

Note • In the example above, the three primary components are

shown running on different machines. Typically, the Event Processor
and the Event Server run on the same machine.

■ 1-8 AutoSys User Guide for UNIX

 Introduction to AutoSys ■
System Components

Explanation
The following numbered steps explain the interactions in the example
scenario:

1 From the AutoSys Event Server, the Event Processor reads a new event,
which is a start job event with a start time condition that has been
met. Then the Event Processor reads the appropriate job definition
from the database and, based on that definition, determines what
action to take. In the example, it runs the rm /tmp/mystuff/*
command on “WorkStation_2”.

2 The Event Processor communicates with the Remote Agent on

“WorkStation_2”. As soon as the Remote Agent receives the
instructions from the Event Processor, the connection between the
two processes is dropped. After the connection is dropped, the job will
run to completion, even if the Event Processor stops running.

3 The Remote Agent performs resource checks, such as ensuring that the
minimum specified number of processes are available, then “forks” a
child process that will actually run the specified command.

4 The command completes and exits, and the Remote Agent captures
the command’s exit code.

5 The Remote Agent communicates the event (exit code, status, etc.)
directly to the Event Server. If the AutoSys database is unavailable for
any reason, the Remote Agent will go into a wait and resend cycle until
it can deliver the message.

Only two AutoSys processes need to be running: the Event Processor and
the Event Server. When these two components are running, AutoSys is
fully operational. The Remote Agent is started on a client machine once
per job. As soon as the job ends and the Remote Agent sends a
completion event to the database, the Remote Agent exits.

AutoSys User Guide for UNIX 1-9 ■

■ Introduction to AutoSys
AutoSys Machines

Note • The Remote Agent is started on the client machine by the Event
Processor talking to the internet daemon (inetd) on the client
machine. For this to happen, inetd must also be running. However,
since UNIX is responsible for starting this daemon, it is not
considered an AutoSys process.

1 Interface Components
To define, monitor, and report on jobs, you can use either the AutoSys
GUI or AutoSys JIL. In addition, the Operator Console and its dialogs
provide a sophisticated method of monitoring AutoSys jobs in real time.
This feature lets you view all jobs that are defined to AutoSys, whether or
not they are currently active. If you purchased AutoSys/Xpert, you can use
the Xpert product to monitor, analyze and forecast (simulate) AutoSys
jobs. For information, see the AutoSys/Xpert User Guide for UNIX.

For information on interface components and defining and monitoring

AutoSys jobs, see the chapters in this guide.

AutoSys Machines 1

From a hardware perspective, the AutoSys architecture is composed of the

following two types of machines attached to a network:

Server Machine

The AutoSys server is the machine on which the Event Processor

and/or the Event Server (database) reside. In a basic configuration,
both the Event Processor and the Event Server reside on the same
machine.

Client Machine

The AutoSys client is the machine on which the Remote Agent

software resides, and where AutoSys jobs are to be run. A Remote
Agent must be installed on the server machine, and it can also be
installed on separate physical client machines.

■ 1-10 AutoSys User Guide for UNIX

 Introduction to AutoSys ■
AutoSys Instance

AutoSys Instance 1

An AutoSys instance is one licensed version of AutoSys software running

as an AutoSys server with one or more clients, on a single machine or on
multiple machines. An AutoSys instance is defined by the instance ID,
which is a capitalized three-letter identifier defined by the AUTOSERV
environment variable. An instance uses its own Event Server and Event
Processor and operates independently of other AutoSys instances.

You might want to install multiple AutoSys instances. For example, you
might want to have one instance for production and another for
development. Multiple instances can run on the same machine, and can
schedule jobs on the same machines without interfering or affecting the
other instances.

Events 1

AutoSys is completely event-driven; that is, for a job to be activated by the

Event Processor, an event must occur on which the job depends. For
example, a prerequisite job has completed running successfully or a
required file has been received.

Events can come from a number of sources, including the following:

■ Jobs changing states, such as starting, finishing successfully, etc.

■ Internal AutoSys verification agents, such as detected errors.

■ Events sent with the sendevent command, sent from the Send Event
dialog, the command line, or user applications.

As each event is processed, the Event Processor scans the database for jobs
that are dependent on that event in some way. If the event satisfies
another job’s starting condition, that job is either started immediately, or
if necessary, queued for the next qualified and available machine. The
completion of one job can cause another job to be started, and in this
way, jobs progress in a controlled sequence.

AutoSys User Guide for UNIX 1-11 ■

■ Introduction to AutoSys
Alarms

Alarms 1

Alarms are special events that notify operations personnel of situations

requiring their attention. Alarms are integral to the automated use of
AutoSys. That is, jobs can be scheduled to run based on a number of
conditions, but some facility is necessary for addressing incidents that
require manual intervention. For example, a set of jobs could be
dependent on the arrival of a file, and the file is long overdue. It is
important that someone investigate the situation, make a decision, and
resolve the problem.

These are some important aspects of alarms:

■ Alarms are informational only. Any action to be taken due to a

problem is initiated by a separate action event.

■ Alarms are system messages about a detected problem.

■ Alarms are sent through the system as an event.

Alarms have special monitoring features to ensure they will be noticed.

For more information about these features, see Chapter 10, The Operator
Console, and Chapter 11, Monitoring and Reporting Jobs.

Utilities 1

To help you define, control, and report on jobs, AutoSys has its own
specification language called Job Information Language, or JIL, for
defining jobs, machines, monitors, and reports. This language is
processed by the jil command, which reads and interprets the JIL
statements that you enter and then performs the appropriate actions,
such as adding a new job definition to the database.

AutoSys also provides a set of commands that run essential utility

programs for defining, controlling, and reporting on jobs. For example,
the autorep command allows you to generate a variety of reports about
job execution, and the sendevent command allows you to manually
control job processing.

■ 1-12 AutoSys User Guide for UNIX

 Introduction to AutoSys ■
Basic AutoSys Functionality

Additional utility programs are provided to assist you in troubleshooting,

running monitors and browsers, and starting and stopping AutoSys and
its components. AutoSys also provides a database maintenance utility
that runs daily by default.

Basic AutoSys Functionality 1

The diagram in Figure 1-3 and the numbered explanations that follow it
illustrate how AutoSys performs its most basic function—starting a job
(i.e., executing a command) on a client machine.

Working through this example will be very helpful for understanding

how AutoSys processes jobs.

Note • In Figure 1-3, the major AutoSys components are shown as

separate entities. Typically, the Event Processor and the AutoSys Event
Server are installed on the same server machine (along with a required
Remote Agent), and other Remote Agents are installed on separate
client machines.

AutoSys User Guide for UNIX 1-13 ■

■ Introduction to AutoSys
Basic AutoSys Functionality

Event Processor

1 2 3 5

AutoSys Client
Event Server agent
(Database) Connect

7
Remote Agent

9 6 8

Client Job

Figure 1-3 • Basic AutoSys Functionality

1 Explanation
1 The Event Processor scans the Event Server for the next event to
process. If no event is ready, the Event Processor scans again in five
seconds.

2 The Event Processor reads from the Event Server that an event is ready.
If the event is a STARTJOB event, the job definition and attributes are
retrieved from the Event Server, including the command and the
pointer (full path name on the client machine) to the profile file to be
used for the job. In addition, for jobs running on Windows NT
machines, the Event Processor retrieves from the database the user
ID(s) and password(s) required to run the job on the client machine.

■ 1-14 AutoSys User Guide for UNIX

 Introduction to AutoSys ■
Basic AutoSys Functionality

3 The Event Processor processes the event. If the event is a STARTJOB,

the Event Processor attempts to establish a connection with the
Remote Agent on the client machine, and passes the job attributes to
the client machine.

The Event Processor sends a CHANGE_STATUS event marking in the

Event Server that the job is in STARTING state.

4 On a UNIX machine, the inetd invokes the Remote Agent. On a

Windows NT machine, the Remote Agent logs onto the machine as
the user defined as the job’s owner, using the user ID(s) and
password(s) passed to it from the Event Processor.

5 The Remote Agent sends an acknowledgment back to the Event

Processor indicating that it has received the job parameters. The socket
connection is terminated. At this point, the Event Processor resumes
scanning the Event Server database, looking for events to process.

6 The Remote Agent starts a process and executes the command in the
job definition.

7 The Remote Agent issues a CHANGE_STATUS event marking in the

Event Server that the job is in RUNNING state.

8 The client job process runs to completion, then returns an exit code to
the Remote Agent and quits.

9 The Remote Agent sends the Event Server a CHANGE_STATUS event

corresponding to the completion status of the job and passes back an
exit code, using the communications facilities of the database.

If the return status is SUCCESS, the Remote Agent deletes the log file
in its temporary file directory (usually tmp) on the client machine (if
so specified in the AutoSys configuration file on UNIX or with the
AutoSys Administrator on Windows NT).

The Remote Agent quits.

AutoSys User Guide for UNIX 1-15 ■

■ Introduction to AutoSys
Extending AutoSys Functionality

The Event Processor, which is scanning the Event Server, sees the process
completion status, determines if there are dependent jobs, and evaluates
the rest of the dependent jobs’ starting conditions. For each job found
whose remaining conditions are satisfied, the Event Processor sends a
STARTJOB command to the Event Server, which it will then process in the
next cycle.

Extending AutoSys Functionality 1

You can extend AutoSys jobs with the AutoSys Connect and AutoSys
Agent integration components. Using cross-platform job dependency
notation, you can define AutoSys jobs to conditionally start based on the
status of an AutoSys Connect job running on a mainframe, and you can
define AutoSys Connect jobs to conditionally start based on the status of
an AutoSys job. You can also define AutoSys jobs that will run on an
AutoSys Agent machine, if the AutoSys Agent machine is defined to
AutoSys.

In addition, you can install various AutoSys/Adapters. The application-

specific Adapters allow you to initiate, control, and report on the status
of jobs related to an application using the sophisticated job scheduling
capabilities of AutoSys. Contact your Computer Associates sales
representative for information on supported Adapters.

■ 1-16 AutoSys User Guide for UNIX

 Introduction to AutoSys ■
Extending AutoSys Functionality

Figure 1-4 illustrates an extended AutoSys configuration that includes the

AutoSys connect and AutoSys Agent integration components and an
AutoSys/Adapter installation on a UNIX client.

AutoSys Server
UNIX Client (UNIX or NT)
NT Client
UNIX Job
Remote Agent
Event Server
(database)
Remote Agent
NTJOB

Event Processor
AutoSys/Adapter

asbrokerII
Application

Other OS Mainframe
(e.g., AS/400) CCI (OS/390)

CCI CCI

AutoSys Agent AutoSys Connectt

AS/400 Job OS/390 Job

Figure 1-4 • AutoSys Components in an Extended Configuration

For more information, contact your sales representative.

AutoSys User Guide for UNIX 1-17 ■

 2
AutoSys Security
This chapter describes AutoSys security. To set up AutoSys correctly, you
should understand the security features that control where and by whom
a job can be edited or executed. If you are installing AutoSys on both
UNIX and NT, you must understand how security is implemented on
both systems.

For information about AutoSys security on Windows NT, see the AutoSys
Security chapter in the AutoSys User Guide for Windows NT.
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Security on Events Sent by Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Security on Events Sent by the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . 2-5

System-Level Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8

AutoSys Database Field Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Job Definition Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Remote Agent Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
AutoSys User and Database Administrator Passwords . . . . . . . . . . . . . . . . . . 2-10

AutoSys User Guide for UNIX 2-1 ■

■ AutoSys Security

AutoSys Job-Level Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

AutoSys Job Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
AutoSys User Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
AutoSys Permission Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13
Job Permissions and Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15

AutoSys Superuser Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15

Edit Superuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Exec Superuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17

Restricting Access to AutoSys Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17

Remote Agent Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19

■ 2-2 AutoSys User Guide for UNIX

 AutoSys Security ■
Overview

2 Overview
AutoSys security includes:

■ System-level security. See System-Level Security on page 2-8.

■ Job-level security. See AutoSys Job-Level Security on page 2-11.

■ Superuser privileges. See AutoSys Superuser Privileges on page 2-15.

■ UNIX and NT file permissions. See Restricting Access to AutoSys Jobs on

page 2-17.

AutoSys security is initiated when either a user sends events that affect the
running of a job or the Event Processor sends events that affect a job.

2 Security on Events Sent by Users

By using the sendevent command or the Send Event dialog, you can send
execute events that affect the running of a job. These are the execute
events that you can send, if you have the appropriate permissions:

STARTJOB FORCE_STARTJOB

KILLJOB DELETEJOB

CHANGE_STATUS CHANGE_PRIORITY

JOB_ON_HOLD JOB_OFF_HOLD

JOB_ON_ICE JOB_OFF_ICE

SEND_SIGNAL

If you start a job by sending an event, the job permissions are checked as
shown in Figure 2-1.

AutoSys User Guide for UNIX 2-3 ■

■ AutoSys Security
Overview

Figure 2-1 • Security when a user starts a job by sending an event

■ 2-4 AutoSys User Guide for UNIX

 AutoSys Security ■
Overview

Figure 2-1 shows how AutoSys checks for the following when a user starts
a job by sending an event:
1 Checks the database to determine if the job definition was tampered
with. If so, the job definition is invalid, and the job is not run.
2 Does the user match the owner as indicated in the job definition?

3 Is the user the Exec Superuser as defined with autosys_secure?

4 Does the user have job execute permissions as indicated in the job
definition?
5 Is there a machine name in the owner value of the job definition? The
Edit Superuser can remove this portion of the owner.
6 Does the machine portion of the user logon match the job owner
machine portion?
7 Does the job have machine permissions as indicated by the job
definition?

2 Security on Events Sent by the Event Processor

In addition to sending execute events on jobs, you can schedule jobs to
start at certain times or under certain conditions. When a job is scheduled
to start automatically, permissions are checked on the Remote Agent
machine on which the job is to run.

The AutoSys Event Processor scans the Event Server for any jobs with
starting conditions that have been met. When the starting conditions for
a job are met, the Event Processor sends a STARTJOB event to the
designated Remote Agent machine.

Figure 2-2 shows the permissions and security checks that occur on a
UNIX machine before a job is allowed to start on the machine.

AutoSys User Guide for UNIX 2-5 ■

■ AutoSys Security
Overview

Figure 2-2 • Security when an Event Processor starts a job on a UNIX client machine

■ 2-6 AutoSys User Guide for UNIX

 AutoSys Security ■
Overview

Note • In the figure, an asterisk indicates checks that are made only if
the specific method of remote authentication is enabled (see Remote
Agent Authentication on page 2-9).

Figure 2-2 shows how AutoSys checks for the following when the Event
Processor sends a STARTJOB event to a Remote Agent machine:

1 Checks the database to determine if the job definition was tampered

with. If so, the job definition is invalid, and the job is not run.

2 Checks the DES encrypted job definition to determine if the Event

Processor can connect to the Remote Agent machine.

3 Does the user who is defined as the job owner (user@machine) have a
logon account on the Remote Agent machine?

4 If user authentication is enabled, is the user a Trusted User (as defined

in the /etc/hosts.equiv and $HOME/.rhosts files)?

5 If Event Processor authentication is enabled, does the requesting

Event Processor have permission to run jobs on this Remote Agent
machine?

Note • The Edit Superuser can enable remote authentication by using

the autosys_secure utility.

AutoSys User Guide for UNIX 2-7 ■

■ AutoSys Security
System-Level Security

2 System-Level Security
The AutoSys security scheme prevents unauthorized access to AutoSys
facilities, which in turn prevents unauthorized access to AutoSys jobs.
The following features handle system security in AutoSys:

■ AutoSys database field verification

■ Job definition encryption

■ Remote Agent authentication

■ AutoSys user and database administrator passwords

Note • On UNIX, the database field and control string encryption

features provide a level of security comparable to the security
provided in the native UNIX environment.

2 AutoSys Database Field Verification

To secure the database, AutoSys not only encrypts some fields specified
in a job definition, but also generates a checksum from fields in the job
definition, and stores the checksum in the AutoSys database. Whenever a
job is accessed, its checksum is regenerated and compared to the one in
the database. If the checksums are different, this indicates that someone
tampered with the job definition in the database, probably by using an
SQL command. In this case, the job is disabled and cannot be executed.

To re-enable a disabled job, the owner or the Edit Superuser must access
the definition and re-save it, by using either the JIL update_job
sub-command or the Job Definition dialog.

■ 2-8 AutoSys User Guide for UNIX

 AutoSys Security ■
System-Level Security

2 Job Definition Encryption

To secure the Remote Agent from unauthorized access, the Event
Processor encrypts the information in a job definition sent over the
socket to the Remote Agent. The Remote Agent then decrypts the job
information and continues to process the job. If the Remote Agent
receives any job information from the Event Processor that it does not
recognize, it issues an error message and will not process the job.

2 Remote Agent Authentication

AutoSys provides two Remote Agent authentication methods:

■ User authentication

■ Event Processor authentication

By default, both user authentication and Event Processor authentication

are disabled. The Edit Superuser must enable them by using the
autosys_secure command.

User Authentication
This remote authentication method uses UNIX ruserok() authentication
to verify that a user has permission to start a job on an AutoSys client
machine. It accomplishes this by telling the client’s Remote Agent to
make the ruserok() UNIX system call to check the client machine’s
/etc/hosts.equiv and the user’s .rhosts file to validate that the
requesting user is registered in that environment. This function call
performs a “local” verification, and it is not related in any way to rshd or
rlogind. To activate this type of remote authentication, use the
autosys_secure command.

AutoSys User Guide for UNIX 2-9 ■

■ AutoSys Security
System-Level Security

The hosts.equiv and/or .rhosts file entries must match the job owner
and machine name field exactly. For example, if the owner is
tarzan@jungle, the hosts.equiv and/or .rhosts file must contain
“jungle.” Similarly, if the owner is [email protected], the
hosts.equiv and/or .rhosts file must contain “jungle.vine.com.” If they
do not match, jobs will fail to run on that machine when ruserok()
remote authentication is in use.

For information on enabling this type of remote authentication, see

autosys_secure in Chapter 1, AutoSys Commands, of the AutoSys Reference
Guide for UNIX.

Event Processor Authentication

When Event Processor authentication is enabled, the Remote Agent
verifies that it has permission to process requests from the requesting
Event Processor before starting each job. It does this by reading the
/etc/.autostuff file on the machine on which the Remote Agent is
running. For information on enabling Event Processor authentication,
see autosys_secure in Chapter 1, AutoSys Commands, of the AutoSys
Reference Guide for UNIX.

Note • Before enabling Event Processor authentication, you must set

up and properly configure the /etc/.autostuff file on every client
machine that will participate in this authentication method, as
described in the Configuring Remote Authentication section of Chapter 13,
Configuring AutoSys.

2 AutoSys User and Database Administrator Passwords

When you install AutoSys and configure your database, an “autosys” user
is added to the database with a password set to “autosys.” The “autosys”
user is the owner of the AutoSys database and can make changes to
AutoSys-specific information in the database. To enhance system
security, we recommend that you change the “autosys” user password
with the autosys_secure command.

■ 2-10 AutoSys User Guide for UNIX

 AutoSys Security ■
AutoSys Job-Level Security

When you install AutoSys with bundled Sybase, the database system
administrator ID is “sa,” and the password is “sysadmin.” To enhance
security, we recommend that you change the system administrator
password by using the xql utility.

You must supply the “autosys” and “sa” user IDs and passwords when
you use several AutoSys utilities. For example, when using the xql utility
to query the database, you must know both the “autosys” user password
and the “sa” system administrator password.

For information on changing the “autosys” user password see

autosys_secure, and for information on changing the “sa” password and
querying the database, see xql in Chapter 1, AutoSys Commands, of the
AutoSys Reference Guide for UNIX.

2 AutoSys Job-Level Security

The AutoSys security scheme provides individuals and groups of users
with edit and execute permissions on a job-by-job basis. For jobs running
on UNIX, AutoSys supports owner, group, and world edit and execute
permissions. For jobs running on NT, AutoSys supports owner and world
edit and execute permissions.

By default, only the user logged on as the owner of a job can edit or
execute a job. The owner can extend permissions to other users and other
machines, as described in the following sections.

2 AutoSys Job Ownership

By default, the owner of an AutoSys job is the user who defines that job
on a particular machine. When a user defines a job on UNIX, the user ID
is retrieved from the UNIX environment and attached to the job in the
form of user@machine. The owner is defined by the owner job attribute.
By default, only the owner can edit and execute the job.

AutoSys User Guide for UNIX 2-11 ■

■ AutoSys Security
AutoSys Job-Level Security

The user@machine combination must have execute permission for any

command specified in a job on the machine where the job command is
to run. The job owner must also have permission to access any device,
resource, etc. that the command needs to access. For this process to work,
the job owner must have the appropriate system permissions.

The owner’s umask “write” permission is used as the default “edit”

permission of the job, and the umask “execute” permission is used as the
default “execute” permission of the job.

If a job is run on an NT client machine, the Edit Superuser must have

entered the valid NT user ID and password for the owner into the AutoSys
database. For more information about the Edit Superuser, see Edit
Superuser on page 2-16.

2 AutoSys User Types

Like UNIX, AutoSys uses the notion of these three types of users for any
job:

■ Owner. The user who created the job.

■ Group. Any user who is in the same primary group as the owner.

■ World. Every user.

AutoSys uses the UNIX user ID (uid) and group ID (gid) of a job’s owner
to control the following:

■ Who can edit, override, or delete a job definition.

■ Who can execute the UNIX command specified in a job.

The owner of a job can allow other users to edit and execute the job by
setting the permissions in the job definition (discussed in the next
section).

■ 2-12 AutoSys User Guide for UNIX

 AutoSys Security ■
AutoSys Job-Level Security

2 AutoSys Permission Types

By default, only the owner has edit and execute permissions on a job, and
all edit and execute permissions are valid only on the machine on which
the job was defined. However, the owner can grant different types of
permissions when defining a job.

Similar to UNIX, AutoSys associates different types of permissions with

each job. Every job has the following permission types:

■ Edit. Users can edit, override, or delete a job definition.

■ Execute. Users can send an execute event that affects the running of a
job by using the sendevent command or the Send Event dialog. For a
list of the execute events that users can send, see Security on Events Sent
by Users on page 2-3.

■ Machine. Users logged onto a machine other than the one on which a
job was created can edit or execute the job.

Note • In order for a job to run on a machine other than the one
on which the job was defined, the owner of that job must have an
account on that machine.

Granting Permissions
The owner of a job cannot override his or her ownership designation;
only the Edit Superuser has the authority to change the owner job
attribute. However, the owner can grant other users edit and execute
permissions for a job by using the GUI or JIL to set the permission job
attribute in the job definition.

AutoSys User Guide for UNIX 2-13 ■

■ AutoSys Security
AutoSys Job-Level Security

The following table shows the permissions that you can set by using JIL
or the Permission toggle buttons on the Job Definitions Advanced
Features dialog.

GUI JIL Meaning

Group Execute gx Users assigned to the job owner’s primary group can
execute the job if logged onto the machine where the job
was created (the machine specified in the owner
attribute, i.e., user@machine).

Group Edit ge Users assigned to the job owner’s primary group can edit
the job if logged onto the machine where the job was
created (the machine specified in the owner attribute, i.e.,
user@machine).

All Hosts Execute mx Users, regardless of the machine logged onto, can
execute the job (otherwise, the user must be logged onto
the machine specified in the owner attribute, i.e.,
user@machine).

All Hosts Edit me Users, regardless of the machine logged onto, can edit
the job (otherwise, the user must be logged onto the
machine specified in the owner attribute, i.e.,
user@machine).

World Execute wx Users can execute the job if logged onto the machine
where the job was created (the machine specified in the
owner attribute, i.e., user@machine).

World Edit we Users can edit the job if logged onto the machine where
the job was created (the machine specified in the owner
attribute, i.e., user@machine).

■ 2-14 AutoSys User Guide for UNIX

 AutoSys Security ■
AutoSys Superuser Privileges

Note • A job and the command it executes will always run as the user
specified in the owner attribute of the job definition. Execute
permissions determine who can execute events against the job, but
not who the job runs as. Even if World Execute permissions are
granted, the job will still run as the user.

2 Job Permissions and Windows NT

If you are defining jobs and running them on different operating systems,
keep the following in mind:

■ When defining a job to run on an NT machine, you can set group

permissions, but they will be ignored. Group permissions will be used
if a job is edited or executed on a UNIX machine.

■ When editing a job from an NT machine, the group edit permission is

ignored. In this case, the user editing the job must be the owner of the
job, or World Edit permissions must be specified for the job.

■ When executing a job from an NT machine, the group execute

permission is ignored. In this case, the user executing the job must be
the owner of the job, or World Execute permissions must be specified
for the job.

2 AutoSys Superuser Privileges

AutoSys recognizes two users with Superuser privileges: the Edit
Superuser and the Exec Superuser. You can define these Superusers by
using the autosys_secure command. For information about defining the
Edit and Exec Superusers, see Chapter 5, Server Installation for Sybase or
Chapter 7, Server Installation for Oracle, in the AutoSys Installation and
Getting Started Guide for UNIX.

AutoSys User Guide for UNIX 2-15 ■

■ AutoSys Security
AutoSys Superuser Privileges

2 Edit Superuser
Only the Edit Superuser has permission to:

■ Edit or delete any job regardless of its owner or its permissions.

■ Change the owner attribute of a job.

■ Change the AutoSys database password, change the remote

authentication method, and add and change NT user IDs and
passwords by using the autosys_secure command.

The Edit Superuser can override user authentication (if enabled) on a

job-by-job basis by changing the owner of the job from the form
user@machine to the form user. User authentication of the job at
execution time is not performed on the client machine. For more
information about changing the job owner, see the owner attribute
section in Chapter 2, JIL/GUI Job Definitions, of the AutoSys Reference Guide
for UNIX.

Note • The purpose of the user@machine form is to prevent users from

running jobs on machines where they do not have the appropriate
permission. For example, root@machine prevents root on any
machine from running root jobs on all machines.

The Edit Superuser must enter valid NT user IDs and passwords into the
AutoSys database. These user IDs and passwords are required for AutoSys
to log onto and run jobs on NT client machines. When a Remote Agent
runs a job on a machine, it logs on as the user defined in the owner
attribute for the job. To do this, the Event Processor retrieves encrypted
versions of the IDs and passwords for the user@host_or_domain and the
user@machine from the Event Server and passes them to the Remote
Agent. For information about entering and changing NT user IDs and
passwords, see autosys_secure in Chapter 1, AutoSys Commands, of the
AutoSys Reference Guide for Windows NT.

■ 2-16 AutoSys User Guide for UNIX

 AutoSys Security ■
Restricting Access to AutoSys Jobs

Note • Any AutoSys user who knows an existing user ID and password
can change that password or delete that user and password.

2 Exec Superuser
Only the Exec Superuser has permission to:

■ Issue commands that affect the running or the state of any AutoSys
job, either using the sendevent command or the Send Event dialog.

■ Stop the Event Processor by issuing the following command:

sendevent -E STOP_DEMON

Note • Exec Superuser privileges are usually granted to the night

operator.

2 Restricting Access to AutoSys Jobs

Using the UNIX chmod command, you can change permissions on many
AutoSys files to control which users can view jobs, execute jobs, edit jobs,
and change calendars.

First, you must ensure that only authorized users can change permissions
on the files and directories in the AutoSys directory structure.

Then, you should determine what level of security you want, for example:

■ Only authorized users can use AutoSys.

Or
■ Any user can view jobs and reports about jobs, such as using autorep
to see the status of a job, but only authorized users can create jobs and
calendars or make changes to them.

AutoSys User Guide for UNIX 2-17 ■

■ AutoSys Security
Restricting Access to AutoSys Jobs

If you want only authorized users to access AutoSys, ensure that only
those users have execute permissions on the files in the AutoSys bin
directory.

If you want all users to view reports about jobs, but only authorized users
to create and edit jobs and calendars, ensure that the following AutoSys
files in the $AUTOSYS/bin directory are executable only by the authorized
users. This will also prevent unauthorized users from making changes to
the AutoSys configuration.

DBMaint clean_files jobscape*

archive_events dbspace sendevent

autocal dbstatistics timescape*

autocal_asc gatekeeper xql

autocons* hostscape* zappls

autotimezone jil zql

Note • An asterisk (*) indicates files that can be executable by all

users as long as sendevent and jil are not executable. This allows
users to use the GUI to view job states, but does not allow them to add
new jobs or calendars or start jobs (even if the job has world execute
permissions).

You should also protect the files in the $AUTOUSER directory from
modification by ensuring that only users authorized to change the
AutoSys configuration have write permission on the files. Read
permission is necessary to source the AutoSys environment files.

■ 2-18 AutoSys User Guide for UNIX

 AutoSys Security ■
Restricting Access to AutoSys Jobs

2 Remote Agent Security

In the auto.profile file for the Remote Agent machine, you can specify
a list of users whose jobs are prohibited from running on that machine.
For information on this, see Client-Side Security in Chapter 13, Configuring
AutoSys.

AutoSys User Guide for UNIX 2-19 ■

 3
AutoSys Jobs
This chapter describes AutoSys jobs and provides information about
their different states and starting parameters.
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Job Types and Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Basic Job Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Command Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Box Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
File Watcher Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7

Basic Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

Command Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
File Watcher Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Box Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

Job States and Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10

Example State Diagram - Simple Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
Example State Diagram - Box Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14

AutoSys User Guide for UNIX 3-1 ■

■ AutoSys Jobs

Starting Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15

Starting Parameters and Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
Date/Time Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
Job Dependencies Related to Job Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
Event Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
Event Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
Job Dependencies Based on Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26
Job Dependencies Based on Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . 3-28

Job Run Numbers and Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30

Defining Jobs in AutoSys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30

AutoSys Graphical User Interface Components . . . . . . . . . . . . . . . . . . . . . . . . 3-31

■ 3-2 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Introduction

3 Introduction
All activity controlled by AutoSys is based on jobs. Other AutoSys objects,
such as Monitors, Browsers (Reports), and the Operator Console, serve to
track job progress. A job is the basic building block upon which the entire
operations cycle is built.

An AutoSys job is any single command or executable, UNIX shell script,

or NT batch file. Each AutoSys job definition contains a variety of
qualifying attributes, including the conditions specifying when and
where a job should be run.

As with most control systems, there are many ways to correctly define and
implement jobs. It is likely that the way you utilize AutoSys to address
your distributed computing needs will evolve over time. As you become
more familiar with both the features of AutoSys and the characteristics of
your own jobs, you will also refine your use of AutoSys.

Note • Before continuing with this chapter, read Chapter 12,

Maintaining AutoSys, for details on starting the AutoSys Event
Processor, which must be running before you start any AutoSys
processes.

AutoSys User Guide for UNIX 3-3 ■

■ AutoSys Jobs
Job Types and Structure

3 Job Types and Structure

Figure 3-1 illustrates the structure of a job. There are three types of jobs:
command, file watcher, and box. These job types have a majority of job
attributes in common, and AutoSys treats them all similarly. The primary
differences between them are the actions that are taken when the job is
run.

Job Depends On
Name
Starting Conditions
Alarms
Basic Job Restart Conditions
Definition
Information
Current status
Start time
End time
Exit code
Current State

Command
Job Container
Command to execute File Watcher
Types File to source Box
Machine to run on File Name
Standard output files Minimum File size
Standard input file Watch Interval

Action Run Command Watch for File

on Machine

Figure 3-1 • Basic Job Information, Job Types, and Actions

As their names imply, command jobs execute commands, box jobs are
containers which hold other jobs (including other boxes), and file
watcher jobs watch for the arrival of a specified file.

■ 3-4 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Job Types and Structure

3 Basic Job Information

In Figure 3-1, the attributes listed inside the Job region comprise what is
called the Basic Job Information, and are common to all jobs regardless
of type. These attributes include the identifier name, the starting
conditions, any specified alarms, the restart conditions, and a variety of
other settings not shown (such as the box, if any, the job is in).

Notice in Figure 3-1 that a job’s starting conditions can be contingent on

the date, time, and the status of any other job.

3 Command Jobs
The command job is commonly thought of (and referred to) as “a job.”
The command can be a shell script, an executable program, a file transfer,
and so forth. When this type of job is run, the result is the execution of a
specified command on a client machine. When all the starting conditions
are met, AutoSys runs this command and captures its exit code upon
completion. The exit event (either SUCCESS or FAILURE) and the exit
code value are stored in the database.

In addition to the primary functionality described above, a command job

has the following supporting features:

Resource Criteria

AutoSys will check that a certain amount of free file space is available
before starting a process. If it is not available, an alarm is sent and the
job is rescheduled to start after a suitable delay.

Profile Script

For each job, you can specify a script to be sourced before the
execution of the command that defines the environment in which the
command is to be run. All commands are run under the Bourne shell
(/bin/sh). Therefore, all statements in the profile must use /bin/sh
syntax.

AutoSys User Guide for UNIX 3-5 ■

■ AutoSys Jobs
Job Types and Structure

I/O Standard Files

For each job, you can specify the standard input, standard output, and
standard error files. To do this, use the JIL std_* commands, or use the
Job Definition Advanced Features dialog.

3 Box Jobs
In the AutoSys environment, the box job (or box) is a container of other
jobs. A box job can be used to organize and control process flow. The box
itself performs no actions, although it can trigger other jobs to run. An
important feature of this type of job is that boxes can be put inside of
other boxes. When this is done, jobs related by like starting conditions
(not by similar application types) can be grouped and operated on in a
logical way.

Note • Box jobs are very powerful tools for organizing, managing,
and administering large numbers of jobs that have similar starting
conditions and/or have complex logic flows. Knowing how and when
to use boxes is often the result of some experimentation

For more information on box jobs, see Chapter 5, Box Job Logic.

Starting Conditions for Box Jobs

If no other starting conditions are specified at the job level, a job within
a box will run as soon as the starting conditions for the box are satisfied.
If several jobs in a box do not have job-level starting conditions, they will
all run in parallel. Each time any job in a box changes state, the other jobs
are checked to see if they are eligible to start running.

If jobs in a box have a priority attribute setting, they will be processed

in order of priority, highest to lowest.

Jobs inside of boxes will be run only once per box execution. If you do
specify multiple start times for a job during one box processing cycle,
only the first start time will be used. This prevents jobs in boxes from
inadvertently running multiple times.

■ 3-6 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Job Types and Structure

AutoSys starts a job if the current time matches, or is later than, the start
time. In addition to explicit starting conditions, jobs inside of boxes have
the following implicit condition: the box job itself is running. This means
that jobs inside of a box will start only if the box job itself is running.
However, if a job inside a box starts and the box job is stopped, the
started job runs to completion.

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

3 File Watcher Jobs

A file watcher job is similar to a command job. However, instead of
starting a user-specified command on a client machine, it starts a process
that monitors for the existence and size of a specific operating system file.
When that file reaches a certain minimum size, and is no longer growing
in size, the file watcher job completes successfully, indicating that the file
has arrived.

Using file watcher jobs provides a means of integrating events which are
external to AutoSys into the processing conditions of AutoSys jobs. For
example, a file needs to be downloaded from a mainframe, and it is
expected to arrive after 2:00 a.m. After it arrives, a batch job is to be run
to process it, possibly even starting a whole sequence of jobs.

You could set up a file watcher job to start at 2:00 a.m. wait for the arrival
of the specified file, then exit. You could also set up the batch job so that
the completion of the file watcher job is its only starting condition.

AutoSys User Guide for UNIX 3-7 ■

■ AutoSys Jobs
Basic Job Attributes

3 Basic Job Attributes

For each of the three AutoSys job types, some job attributes are required.
There are additional optional attributes that you can use for more
advanced job definitions.

Note • The owner attribute is required for all job types, but is
automatically assigned by AutoSys.

3 Command Job Attributes

The basic command job definition has the following required attributes:

Job Name

The unique job identifier by which a job is referenced.

Command

The UNIX shell script, command, or application program to be

executed.

Machine Name

The name of the machine on which the command is to be run.

Starting Conditions

The date/time and/or job dependency conditions necessary for the job
to be run. (Strictly speaking, this is not required, such as in cases
where a job will always be started manually.)

■ 3-8 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Basic Job Attributes

3 File Watcher Job Attributes

The basic file watcher job definition has the following required
attributes:

Job Name

The unique job identifier by which a job is referenced.

File Name to Watch For

The name of the file for which to watch.

Machine Name

The name of the machine on which the command is to be run.

Starting Conditions

The date/time and/or job status conditions necessary for the job to be
run. (Strictly speaking, this is not required, such as in cases where a
job will always be started manually.)

3 Box Job Attributes

The basic box job definition has the following required attributes:

Box Name

The unique job identifier by which the box is referenced. This name is
used by other jobs as the name of their parent box.

Starting Conditions

The date/time and/or job status conditions necessary for the job to be
run. (Strictly speaking, this is not required, such as in cases where a
job will always be started manually.)

AutoSys User Guide for UNIX 3-9 ■

■ AutoSys Jobs
Job States and Status

3 Job States and Status

AutoSys keeps track of the current state, or status, of every job. The value
of a job’s status is used to determine when to start other jobs that are
dependent on the job. The job status is displayed in the job report
generated by the autorep command, and in the job report you can view
in the Job Activity Console.

A job can have one of the following statuses:

INACTIVE

The job has not yet been processed. Either the job has never been run,
or its status was intentionally altered to “turn off” its previous
completion status.

ACTIVATED

The top-level box that this job is in is now in the RUNNING state, but
the job itself has not started yet.

STARTING

The Event Processor has initiated the start job procedure with the
Remote Agent.

RUNNING

The job is running. If the job is a box job, this value simply means that
the jobs within the box might be started (other conditions
permitting). If it is a command or file watcher job, the value means
that the process is actually running on the remote machine.

■ 3-10 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Job States and Status

SUCCESS

The job exited with an exit code equal to or less than the “maximum
exit code for success.” By default, only the exit code “0” is interpreted
as “success.” However, a range of values up to the “maximum exit
code for success” can be reserved for each job to be interpreted as
success. If the job is a box job, this value means that all the jobs within
the box have finished with the status SUCCESS (the default), or the
“Exit Condition for Box Success” evaluated to true. (These exit
conditions are discussed further in later sections.)

FAILURE

The job exited with an exit code greater than the “maximum exit code
for success.” By default, any number greater than zero is interpreted as
“failure.” If the job is a box job, a FAILURE status means either that at
least one job within the box exited with the status FAILURE (the
default), or that the “Exit Condition for Box Failure” evaluated to true.
AutoSys issues an alarm if a job fails.

TERMINATED

The job terminated while in the RUNNING state. A job can be

terminated if a user sends a KILLJOB event or if it was defined to
terminate if the box it is in failed. If the job itself fails, it has a FAILURE
status, not a TERMINATED status. A job might also be terminated if it
has exceeded the maximum run time (term_run_time attribute, if one
was specified for the job), or if it was killed from the command line
via a UNIX kill command. AutoSys issues an alarm if a job is
terminated.

RESTART

The job was unable to start due to hardware or application problems,

and has been scheduled to restart.

QUE_WAIT

The job can logically run (i.e., all the starting conditions have been
met), but there are not enough machine resources available.

AutoSys User Guide for UNIX 3-11 ■

■ AutoSys Jobs
Job States and Status

ON_HOLD

This job is on hold and will not be run until it receives the
JOB_OFF_HOLD event.

ON_ICE

This job is removed from all conditions and logic, but is still defined
to AutoSys. Operationally, this condition is like deactivating the job.
It will remain on ice until it receives the JOB_OFF_ICE event.

The difference between “on hold” and “on ice” is that when an “on
hold” job is taken off hold, if its starting conditions are already
satisfied, it will be scheduled to run, and it will run. On the other
hand, if an “on ice” job is taken “off ice”, it will not start, even if its
starting conditions are already satisfied. This job will not run until its
starting conditions re-occur.

The other major distinction is that jobs downstream from the job that
is “on ice” will run as though the job succeeded. Whereas, all
dependent jobs do not run when a job is on “on hold”—nothing
downstream from this job will run.

For details on how “on ice” affects boxes, see Chapter 5, Box Job Logic.

3 Example State Diagram - Simple Jobs

Figure 3-2 (on page 3-13) depicts the states that simple jobs go through.
In the diagrams, a status is depicted using the following box drawing:

STATE

When a change in job status occurs, it is reported as a CHANGE_STATUS

event, and the Event Processor records it in its log when this status is
processed. For example, when the job “test_job” changes from the
STARTING state to the RUNNING state, the Event Processor log will
contain the following entry:
EVENT: CHANGE_STATUS STATUS: RUNNING JOB: test_job

■ 3-12 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Job States and Status

Figure 3-2 depicts the simplest state transition for a job, in which an
event satisfies the starting conditions for the job.

The job starts, processes, and completes with either a failure or success
exit code.

Event Processor
Event is read by Event Processor EVENT

Find jobs dependent

on this event.

Check Conditions

Event generated by Event Proces-

sor, indicating attempt to start job STARTING
on Remote Machine.

Event generated by Remote Agent

RUNNING Remote Agent
indicating the job has actually been
started and is now running.

Inspects Exit Code

of the process.

Event generated by
Remote Agent SUCCESS - OR - FAILURE

Figure 3-2 • State Diagram—Simple Jobs

AutoSys User Guide for UNIX 3-13 ■

■ AutoSys Jobs
Job States and Status

3 Example State Diagram - Box Jobs

For a job in a box, the job first goes into the ACTIVATED state when the
top-level box it is in goes into the RUNNING state, as shown in
Figure 3-3. After the job starts, the remainder of the scenario is the same
as for simple jobs.

Event Processor
EVENT

Find jobs dependent

on this event.

Check Conditions

Event sent by Event Processor indicat-

ing that the box is “Running.” Nothing
actually RUNS. However, this EVENT
RUNNING
may trigger Jobs within the box to run.

Inspects Exit Status of jobs within it to

determine if box is done, and if so
what the Exit Status is.

SUCCESS - OR - FAILURE

Figure 3-3 • State Diagram—Box Jobs

In the case of a box, the box always goes into the RUNNING state as soon
as all its starting conditions are met. This RUNNING event usually
triggers jobs within the box to also start.

■ 3-14 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Starting Parameters

If the job has a priority associated with it, all its starting conditions have
been met, and there are not enough machine resources available, it goes
into the QUE_WAIT state. Once the resources become available, it goes
into the STARTING state, then runs.

The value of status reflects the AutoSys event processing. Therefore, a job
might have actually completed on a machine and if the Event Processor
has not processed that event yet, AutoSys will still show the job’s status
as RUNNING. By displaying the detail of the job (either in the Job
Activity Console, or in the output of the autorep command), you can see
all the events for a job, including those that have not processed yet.

In addition, the status always reflects the most recent event that was
processed. Therefore, after a job has completed, the status will remain as
it is on completion. If it ended successfully, the status will remain as
SUCCESS until the job is run again.

Note • When a box job starts, all jobs within the box change state to
ACTIVATED before they run. Jobs will then run immediately, unless
other conditions apply. If a box completes before a job is run, the job
is set to INACTIVE at the time of box completion. As a result, jobs do
not retain their statuses from previous box processing cycles once a
new box cycle has begun.

3 Starting Parameters
AutoSys determines whether or not it should start a job based on the
evaluation of the starting conditions (or starting parameters) defined for
the job. These conditions can be one or more of the following:

■ Date and time scheduling parameters are met (it is or has passed the
specified date and time).

■ Starting Conditions specified in the job definition evaluate to true.

■ For jobs in a box, the box must be in the RUNNING state.

■ The current status of the job is not ON_HOLD or ON_ICE.

AutoSys User Guide for UNIX 3-15 ■

■ AutoSys Jobs
Starting Parameters

Every time an event changes any of the above conditions, AutoSys finds
all the jobs that might be affected by this change, and determines
whether or not to start them.

Note • It is very important to keep in mind the above four conditions.

In order for a job to start, all defined starting conditions must be true.

3 Starting Parameters and Boxes

Be aware that for a job in a box to start, the box job must be running.
Placing a job in a box means that the job inherits all the starting
conditions of the box job. It also means that if there are no additional
conditions on the job, it will be started as soon as the box is started. Also,
a job runs only once per box execution.

By default, there is no concept of sequential job processing in a box. For

example, if there are three jobs inside a box, and none of them has any
additional conditions, then when the box is started, all three jobs will be
started.

To implement a sequence within a box, you must specify additional

starting conditions for each job. For example, “Job1” may have no
starting conditions, while “Job2” is dependent on the completion of
“Job1”, and “Job3” is dependent on the completion of “Job2”.

Be aware that if this scenario were implemented and “Job2” were placed
ON_ICE, then “Job1” and “Job3” would start simultaneously as soon as
the box they are in started running. (Jobs that are dependent on a job that
is ON_ICE run as if that starting condition has been satisfied).

■ 3-16 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Starting Parameters

3 Date/Time Dependencies
AutoSys jobs can be automatically scheduled to start at a certain date and
time, based on the information you supply using JIL statements or the
GUI. You define these dependencies by specifying the day(s) or date(s)
and time(s) for time-based job starts. AutoSys then calculates a matrix of
these values and starts jobs at those times. A time range cannot span
more than 24 hours. You can also specify a time zone to apply to your
starting times.

For example, if you define a job to be started on Monday, Wednesday,

and Friday at 8:00 a.m. and 5:00 p.m., it will be started 6 times a week:
Monday at 8:00 a.m. and 5:00 p.m., Wednesday at 8:00 a.m. and 5:00
p.m., and Friday at 8:00 a.m. and 5:00 p.m.

You can specify days of the week or actual dates. However, you cannot
specify both. You can specify days of the week using JIL or the GUI, but
you can only specify actual dates through the use of custom calendars,
which you can define using the Graphical Calendar Facility.

You can specify times as certain times of the day, or hourly, denoted in
minutes past the hour. Again, the two formats are mutually exclusive.
You can specify either form using JIL or the GUI (you do not have to
create custom calendars).

TZ Environment Variable
By default, jobs with time-based starting conditions that do not specify a
time zone are scheduled to start based on the time zone of the TZ
environment variable (the same time zone under which the Event
Processor runs).

Before you start the Event Processor, ensure that the TZ environment
variable is set. The 3.4.4 Event Processor must be started once after you
upgrade your database to insert the value of the TZ environment variable
into the database. Do this before executing jil, autosc, autocons, or
autorep.

AutoSys User Guide for UNIX 3-17 ■

■ AutoSys Jobs
Starting Parameters

Custom Calendars
Using the Graphical Calendar Facility or the autocal_asc utility, you can
define any number of custom calendars, each with a unique name and
containing any number of dates or date/time combinations. You can use
these calendars in one of two ways: as days on which to run the jobs with
which they are associated, or as days on which to not run the jobs with
which they are associated. Calendars exist independently of any jobs that
may be associated with them; they are referenced by jobs through job
definitions.

3 Job Dependencies Related to Job Status

You can start jobs based on the current status of one or more jobs. These
jobs must exist in the AutoSys database. These starting conditions enable
you to program simple or complex prerequisites that must be met in
order to initiate a job.

Starting conditions can be as simple as specifying “JobB” to start when

“JobA” achieves a SUCCESS status, and “JobC” to start when “JobB”
achieves a SUCCESS status. In this way, you can implement a single-
threaded, batch queue-like logic.

Note • If a condition is specified for an undefined job, the condition

will be evaluated as FALSE, and any jobs dependent on this condition
will not run. To check for this type of invalid condition statement, you
can use the chk_cond stored procedure.

The syntax for defining job dependencies is the same whether the job is
being defined using JIL or the GUI. The only difference is the JIL
statement will begin with the JIL condition keyword, while the GUI field
will only contain the language for the dependency itself. The dependency
specification can take one of the following three forms:

■ Based on the current AutoSys status of other jobs

■ 3-18 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Starting Parameters

■ Based on the UNIX exit codes of other jobs

■ Based on AutoSys global variables

This is the syntax for conditions based on AutoSys job status:

status(job_name)

where:

status is one of the following:

success

Indicates that the status condition for job_name is SUCCESS.

failure

Indicates that the status condition for job_name is FAILURE.

done

Indicates that the status condition for job_name is SUCCESS,

FAILURE or TERMINATED.
terminated

Indicates that the status condition for job_name is TERMINATED.

notrunning

Indicates that the status condition for job_name is anything except

RUNNING.

job_name

Is the job on which the new job is dependent.

You can abbreviate the status condition identifiers with the first letter,
using s, f, d, t, and n. You can also abbreviate the dependency
specification exitcode with the letter e and VALUE (of a global variable)
with the letter v. These abbreviations can be upper- or lowercase.

AutoSys User Guide for UNIX 3-19 ■

■ AutoSys Jobs
Starting Parameters

You can control the value of the SUCCESS status by using the “Maximum
Exit Code for Success” attribute, which can be set for a job. If you specify
this attribute, any job that exits with a exit code less than or equal to the
specified value will be treated as a success. A FAILURE status means the
job exited with an exit code higher than this value. The convention (and
the default) for normal job completion is “0”. A TERMINATED status
means the job was killed.

Note • Either uppercase or lowercase can be used to specify a status.

However, the case cannot be mixed in either of the forms described.

Cross-Instance Job Dependencies

Cross-instance job dependencies can be implemented among different
instances of AutoSys.

An AutoSys instance is one licensed version of AutoSys software running

as an AutoSys server, and as an AutoSys server/client, on a single machine
or on multiple machines. It uses its own Event Server and Event Processor
and operates independently of other AutoSys instances.

Multiple instances of AutoSys are not inherently connected, but they can
communicate with each other. You can define jobs to have cross-instance
dependencies, and multiple instances can send events to each other.

For example, multiple instances of AutoSys can send events to each other
by way of a sendevent command line like this:
sendevent -E STARTJOB -J job_name -S autoserv
The job_name argument is a job defined for the instance indicated by the
autoserv argument, which is the instance’s unique, capitalized
three-character identifier.

In addition, jobs can be associated with more than one instance of

AutoSys. For example, a job defined to run on one instance of AutoSys
could have as a starting condition the successful completion of a job
running on a different instance of AutoSys.

■ 3-20 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Starting Parameters

The specification for such a job dependency might look like this:
condition: success(jobA) AND success(jobB^PRD)
The success(jobB^PRD) condition specifies the successful completion of
a job named “jobB” running on a different instance of AutoSys specified
with the three-letter ID of “PRD”. If the dependency specification does
not include a caret (^) and a different instance ID, the current instance
will be used, by default.

Each time a cross-instance dependency is encountered, an

EXTERNAL_DEPENDENCY event is sent from the requesting instance. If
the target instance cannot be reached, an INSTANCE_UNAVAILABLE
alarm is issued.

Figure 3-4 shows two instances of AutoSys, each with a single Event
Server, exchanging cross-instance job dependencies.

One Instance of AutoSys One Instance of AutoSys

ACE PRD
config .ACE config.PRD
Event Event
config.EXTERNAL Server Server config.EXTERNAL

Event Event
Processor Processor

condition: success(jobB^PRD) jobB

jobE condition: success(jobE^ACE)

Figure 3-4 • AutoSys Instances with Cross-Instance Dependencies

Different instances of AutoSys can run from the same executables and can
have the same values for $AUTOSYS and $AUTOUSER, both on the Event
Processor machine and on machines running Remote Agents. However,
they must have a different value for $AUTOSERV.

AutoSys User Guide for UNIX 3-21 ■

■ AutoSys Jobs
Starting Parameters

For information on configuring AutoSys for cross-instance job

dependencies, see the Running Cross-Instance Job Dependencies section in
Chapter 1, Introduction to AutoSys of the AutoSys Installation and Getting
Started Guide for UNIX.

3 Event Processors
When cross-instance dependencies are implemented, different Event
Processors can do the following:

■ Be run on different server machines or on the same server machine.

■ Access the same client machines to start jobs.

■ Send events to other AutoSys instances.

Note • If the Event Server of a target instance is down, the Event

Processor will try to resend an event (or events) every 5 minutes until
the other instance’s Event Server can be reached.

3 Event Servers
Event Servers keep track of the cross-instance job dependencies. Each
time a job definition with a cross-instance job dependency is submitted
to the AutoSys database, the following entries are made:

■ An entry to the ext_job table of the issuing instance. The entries in this
table specify the status of jobs in other instances in which this instance
has an interest.

■ An entry to the req_job table of the receiving instance. The entries in

this table specify the jobs that have been specified as a job dependency
in a job definition on the source AutoSys instance.

In both tables above, jobs are entered using the job name, a caret symbol
(^), and the instance name, as shown below.
jobB^PRD

■ 3-22 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Starting Parameters

The use of multiple database(s) is completely independent of instances

using cross-instance dependencies. You can have multiple instances of
AutoSys, each using Dual Event Servers.

Note • When communicating with Event Servers, Event Processors

can only connect to those instances with “like” Event Servers. That is,
instances with Sybase dataservers can only connect with other
instances having Sybase dataservers. The same holds true for instances
with Oracle databases.

Example Job Dependencies

For a job that runs only if the job named “DB_BACKUP” succeeds, the
job dependency specification would be written as follows:
success(DB_BACKUP)
Or
s(DB_BACKUP)

You can configure more complex conditions by combining a series of

conditions with the AND and/or the OR logical operators. You can enter
these operators in upper- or lowercase, but not in mixed case. In
addition, you can use the symbol | instead of the word “OR,” and the
symbol & instead of the word “AND.” Spaces between conditions and
delimiters are optional.

You can specify more complex conditions by grouping the expressions in

parentheses. The parentheses do not imply any sort of precedence, they
are simply used for grouping. For example, if “JobC” should only be
started when both “JobA” and “JobB” complete successfully or when both
“JobD” and “JobE” complete, regardless of whether they 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))
Or
(s(JobA)&s(JobB))|(d(JobD)&d(JobE))

AutoSys User Guide for UNIX 3-23 ■

■ AutoSys Jobs
Starting Parameters

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 that will
provide alternate actions for error conditions.

For example, if “JobB” fails after processing only partially, you might
want to call a routine titled “Backout” that backs out of the changes that
were made. You would specify the following job dependency in the job
definition for “Backout”:
failure(JobB)
Or
f(JobB)

You use the notrunning operator to keep multiple jobs from running
simultaneously (i.e., running one job is exclusive of any others). For
example, it might be best not to run a database dump (“DB_DUMP”) and
a file backup (“BACKUP”) at the same time. This would cause the hard
disk to be accessed very frequently. However, you might have a smaller
job that can run as long as both of these resource-intensive jobs aren’t
running. You would specify the smaller job’s dependency like this:
notrunning(DB_DUMP) AND notrunning(BACKUP)

Note • If you have jobs that you want to run exclusively, use the
virtual machine and job queueing feature described in Chapter 9, Load
Balancing and Queuing Jobs.

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 last execution of the job, regardless of when it last ran.

However, if you wish 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 you can use to control statuses.

■ 3-24 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Starting Parameters

When a box job is started, all the jobs within the box have their status
changed to ACTIVATED. Therefore, downstream jobs in the box that
depend on the completion of jobs upstream in the same box will use
only the completion statuses from this run of the box. 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 will prevent time-critical jobs from
being affected by invalid information.

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

To change a job status to INACTIVE, use the GUI (Send Event dialog), or
use the sendevent command. Of course, you can create an AutoSys job to
accomplish this as well. If you change the status of a top-level box to
INACTIVE, all the jobs in the box are recursively set to INACTIVE.

Deleting and reinserting the job using JIL will accomplish the same thing.
However, the past reporting history on the job will no longer be
available. (Updating a job using JIL does not change the status of the job.)

AutoSys User Guide for UNIX 3-25 ■

■ AutoSys Jobs
Starting Parameters

3 Job Dependencies Based on Exit Codes

In addition to job status, you can 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. For example, if
a broken communication line results in “JobA” failing with an exit code
of “4”, when this code is encountered, you want the system to execute a
shell script (“JobB”) which redials the line. This is the syntax you would
use to specify this type of job dependency:
exitcode (job_name) operator value
where:
job_name

Is the name of the job upon which the “new” job is dependent.

operator

Is one of the following exitcode comparison operators:

=, != (not equal), <, >, <=, or >=

value

Is any numeric value.

You can abbreviate the dependency specification exitcode with the letter
e (uppercase or lowercase).

For the above example, you would enter the following for the job
dependency specification for the “JobB” redial job:
e (JobA) = 4
You can use any job status or exit codes as part of the specification for
starting conditions. With this latitude, you can program branching paths
that will provide alternative actions for all types of error conditions.

■ 3-26 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Starting Parameters

Using Exit Codes and Batch Files with Jobs Running

on NT
When you are defining jobs that will run batch files on Windows NT, you
should be aware of, and account for, the NT-specific behavior.

NT programs return an exit values that are programmed within the

executable code. This exit value is the last thing returned to NT when the
program terminates.

Generally, a zero 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. You should modify these programs so that they return expected
values. Use these values when specifying exit code dependencies.

AutoSys jobs are created using standard NT process creation techniques.

After the job has been created, the Remote Agent waits for the job to
complete. When the job completes, AutoSys gets the program exit code
from NT and stores it in the AutoSys database for later use.

When launching programs directly from AutoSys, 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 AutoSys to
start *.BAT batch files.

The exit code returned from a batch file is the return code from the last
operation executed from within 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

AutoSys User Guide for UNIX 3-27 ■

■ AutoSys Jobs
Starting Parameters

This example batch file will return a 0 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 executes test. Therefore, this batch file will return a 0
(successful) exit code to Autosys, even if test failed to execute as
intended.

To help handle situations like this, Autosys supplies a program called

FALSE.EXE. This program is located in the AutoSys for NT %AUTOSYS%\bin
directory and takes only one parameter, which is the exit code you want
false to return on completion. You can use false in the above example
batch file, like this:
REM test batch file
test
if errorlevel 1 goto bad
exit
:bad
del test.tmp
false 1

When test fails with errorlevel 1, this batch file will return an exit code
of 1 from false, whether the test.tmp file exists or not.

3 Job Dependencies Based on Global Variables

Job dependencies can also be based on global variables you set using the
Send Event dialog or the sendevent command. When using global
variables in this way, the value of the expression must evaluate to TRUE
for the job dependency to be satisfied. For example, you have a set of jobs
in a box that are only supposed to run on special occasions, such as only
on your manager’s approval. In this case, you would set the global
variable named “manager-ok” to “OK”, and make the top-level box job
dependent on this global variable.

■ 3-28 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Starting Parameters

Global variables are referenced using the following expression:

VALUE(global_name) operator value
where:
VALUE

Can be upper- or lowercase.

global_name

Is the name of the global variable upon which the job is dependent.
operator

Is one of the following: =, != (not equal), <, >, <=, or >=

value

Is any numeric value or text string (no quotes or spaces).

The global_name and the value can each be a maximum of 30 characters.

When using the Job Definition dialog to define a job, enter the above
expression in the Starting Condition field. When using JIL, enter the
above expression in the appropriate JIL script using the condition
attribute.

You can abbreviate the dependency specification VALUE with the letter v
(upper- or lowercase).

In the example cited above, you would enter the following for the job’s
condition statement:
VALUE(manager-ok) = OK
Or
v (manager-ok) = OK

AutoSys User Guide for UNIX 3-29 ■

■ AutoSys Jobs
Job Run Numbers and Names

3 Job Run Numbers and Names

AutoSys employs the notion of 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 that is in a box. This means that all
jobs within 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 within the same run.

If there are restarts of a job, the run number remains the same, and the
ntrys field is incremented. In the standard reports (see the autorep
command in Chapter 1, AutoSys Commands, in the AutoSys Reference Guide
for UNIX), these two values are displayed in the “Run” column as
run_num/ntry.

The value of run_num/ntry is defined in the runtime environment for the

job, and it is accessible to those shell scripts or executables executed as
the job’s command. This value is contained in the variable $AUTORUN.

AutoSys 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 those shell scripts or executables executed as the job’s UNIX
command. The value is contained in the variable $AUTO_JOB_NAME.

3 Defining Jobs in AutoSys

You can define jobs in AutoSys using one of two methods: JIL statements
or the GUI (in the Job Definition dialog). When you use JIL statements,
you can input them interactively to the jil command, or you can store
them in text files, which you can redirect into the jil command.

Alternatively, you can open the GUI by using the autosc command, and
you can enter the job definition by filling in the appropriate fields of the
Job Definition dialog and its associated dialogs.

■ 3-30 AutoSys User Guide for UNIX

 AutoSys Jobs ■
Defining Jobs in AutoSys

You should back up your job definitions periodically, so you can have a
file to restore from in case of system failure. This process is explained in
the Backing up AutoSys Definitions section in Chapter 12, Maintaining
AutoSys.

3 AutoSys Graphical User Interface Components

You can use the AutoSys GUI to interactively define, run, manage,
monitor, and report on jobs. AutoSys provides the following top-level
windows and dialogs, which you can launch from the AutoSys GUI
Control Panel:

Job Definition dialog

Used to define jobs. The Job Definition dialog and its related dialogs
allow you to create, view, edit, and delete job definitions for
command jobs, box jobs, and file watcher jobs.

Graphical Calendar Facility

Used to define calendar definitions. The Graphical Calendar Facility

and its related dialogs allow you to create calendars in order to
simplify job scheduling. It allows you to create custom rules, block
certain dates, setup conflict resolution, build calendars based on
combinations of other calendars, and preview calendar definitions
before assigning them to jobs. Then, you can assign them to certain
job, using the Job Definition dialog.

Operator Console

Used to monitor and manage AutoSys jobs. The Operator Console

consists of the following components: Job Activity Console, Job
Selection dialog, Alarm Manager dialog, and Alarm Selection dialog.
The Job Activity Console allows you to monitor AutoSys jobs, and to
filter the jobs that it displays, you can use the Job Selection dialog. The
Alarm Manager allows you to browse and handle alarms, and to filter
the alarms that it displays, you can use the Alarm Selection dialog.

AutoSys User Guide for UNIX 3-31 ■

■ AutoSys Jobs
Defining Jobs in AutoSys

Monitor/Browser Used to define monitors and reports. The

Monitor/Browser allows you to define filters by which you can screen
AutoSys system information. Monitors provide real-time views of the
system. Browsers (reports) provide historical views of system
information.

Note • You can also access AutoSys/Xpert from the GUI Control
Panel. For information on using AutoSys/Xpert, see the AutoSys/Xpert
User Guide for UNIX.

■ 3-32 AutoSys User Guide for UNIX

 4
Job Attributes
This chapter describes the essential and optional job attributes used to
define jobs in AutoSys. These attributes determine what a job does, as
well as when and where it will run.
Job Attributes and Job Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Using JIL to Create a Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Using the GUI to Create a Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Chapter Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

Essential Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

Attributes Common to All Job Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Command Jobs Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
File Watcher Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
Box Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9

Optional Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10

Common Job Starting Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
Common General Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
Command Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
File Watcher Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26
Box Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27

AutoSys User Guide for UNIX 4-1 ■

■ Job Attributes

Date and Time Attributes and Time Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28

The Time Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28
AutoSys Behavior During Time Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-29

■ 4-2 AutoSys User Guide for UNIX

 Job Attributes ■
Job Attributes and Job Definitions

4 Job Attributes and Job Definitions

You define a new job by assigning it a name and specifying any number
of attributes that describe its intended behavior. This specification of a
job’s behavior is called a job definition. There are two methods of
creating a job definition: using JIL and using the AutoSys GUI. Regardless
of method, the specified set of attributes is the same, and the job
definition is always stored in the database.

Before modifying or deleting an existing job, make sure the job is not
running.

You should back up your job definitions periodically so you can have a
file to restore from in case of system failure. This process is explained in
the Backing up AutoSys Definitions section of Chapter 12, Maintaining
AutoSys.

4 Using JIL to Create a Job Definition

When using JIL to create a job definition, you enter the jil command to
display the jil prompt. At this prompt, you define a job using the
insert_job sub-command followed by any desired attribute:value
statements which specify an action to be performed. You can also use JIL
sub-commands to modify or delete an existing job definition.

Your JIL commands will look like this:

insert_job: job_name
attribute:value
...

where:

job_name is a unique job name.

attribute_keyword is one of the legal JIL attributes.

value is the setting to be applied to the attribute.

AutoSys User Guide for UNIX 4-3 ■

■ Job Attributes
Job Attributes and Job Definitions

4 Using the GUI to Create a Job Definition

When using the AutoSys GUI to create a job definition, issue the autosc
command select the Job Definition button, and set the various attributes
and their values using the text fields and push-buttons in the Job
Definition dialog.

4 Chapter Organization
In this chapter, job attributes are organized into two categories: Essential
and Optional. Essential attributes are those that must be specified in
order for the job definition to be accepted. As the name implies, optional
attributes are not necessarily required for a job definition to be accepted.

For each attribute described in this chapter, we indicate its name, its JIL
attribute keyword, its corresponding GUI object, or GUI Field Name, and
a description of its use, as shown below:

Job Type
job_type Job Type

Attribute description...

JIL Keyword GUI Field Name

In the example above, the “Job Type” attribute, which specifies whether
a job is a command, file watcher, or box, is specified with the JIL keyword
job_type and is identified in the GUI as the field with the name “Job
Type”.

Because Chapter 2, JIL/GUI Job Definitions, of the AutoSys Reference Guide for
UNIX is organized alphabetically by JIL keywords, the keywords in this
chapter can act as “pointers” to more detailed descriptions about a
particular attribute in the reference chapter. The heading on each
reference page contains the same JIL keyword on the left and GUI field
name on the right as in the example above.

■ 4-4 AutoSys User Guide for UNIX

 Job Attributes ■
Essential Job Attributes

4 Essential Job Attributes

4 Attributes Common to All Job Types
The following attributes are common to all job types: command, file
watcher, and box. Although defaults may be available, the attributes in
this section are still essential due to the fact that every job definition must
include them, whether by default or by explicit specification.

Job Name
insert_job Job Name
The job name is used to identify the job to AutoSys, and must be unique
within AutoSys. It can be from 1 to 30 alphanumeric characters, and is
terminated with white space. Embedded blanks and tabs are illegal.
commands, file watchers, and box jobs cannot use the same name.

Job Type
job_type Job Type
The job type specifies the type of job: command (c), file watcher (f), or
box (b).

Job Owner
owner Owner
The job owner specifies whose user ID the command will be run under
on the client machine. This attribute is automatically set to the user who
invoked jil or the GUI to define the job, and cannot be changed except
by the Edit Superuser.

AutoSys User Guide for UNIX 4-5 ■

■ Job Attributes
Essential Job Attributes

4 Command Jobs Attributes

For command jobs, the following attributes must be specified in addition
to those listed in the Attributes Common to All Job Types section (above).

Command
command Command to Execute
The command attribute can be the name of any command, executable,
UNIX shell script or batch file, and its arguments. When issuing
commands that are to be run on a different operating system, you must
use the syntax appropriate to the operating system of the client machine.
The job’s owner must have execute permission for this command on the
client machine. Input and output redirection cannot be part of the
command. Redirection is specified by other job attributes. AutoSys
global variables can be used as part of the command name itself, or as
part of the command’s runtime arguments. To set a global variable, use
the sendevent command, or use the Send Event dialog in the GUI.

This command will be executed in the environment defined in the profile

script—either the AutoSys default /etc/auto.profile, or the one
specified in the job definition (which you can define, and which
preempts the default file). Therefore, if $PATH is assigned in that script,
that path will be searched to find the executable. For more information
on specifying a profile, see Profile on page 4-19.

The full pathname can be specified, in which case, variables exported

from the profile script can be used in the pathname specification. If
variable substitution is used, enclose the variable in curly braces, as in
${DIR}.

■ 4-6 AutoSys User Guide for UNIX

 Job Attributes ■
Essential Job Attributes

These are additional points to keep in mind with regard to the command
attribute:

■ Since AutoSys performs an exec to run the command, multiple

commands separated by a semi-colon are not allowed.

■ Piping and/or redirection of standard input, output, and error files is

not allowed in the command attribute. Shell scripts can be invoked to
execute piped commands and attributes, such as std_in_file used for
standard input, to provide the necessary functionality.

■ You cannot use the background character (&) in the command attribute.
A shell script can be called to provide that functionality.

■ All commands are run under the Bourne shell (/bin/sh). Therefore, all
statements in the profile must use /bin/sh syntax. For example:
Variable=value; export Variable
Do not use this:
export Variable=value or setenv Variable Value
■ If you are running a C-Shell (csh) script, the system will attempt to
source a .cshrc file when it begins interpreting the file. Although this
might be desired, the system will also overwrite any variables defined
in the profile script (the default profile is /etc/auto.profile). If you
do not wish to have the .cshrc file sourced, you must invoke the csh
script with the -f option. For example, this should be the first line of
the script:
#!/bin/csh -f
■ Only one file is sourced—either the default /etc/auto.profile or the
profile file specified in the job definition. Therefore, the entire
environment needed for the command must be defined in the profile
file that will be sourced.

■ Command line arguments can be passed using global variables.

AutoSys User Guide for UNIX 4-7 ■

■ Job Attributes
Essential Job Attributes

Note • If a command is working properly when issued at a shell

prompt, but it fails to run or run properly when specified as a command
attribute, the shell and AutoSys environments are probably different.
If this is the case, ensure that all required command variables are
specified in the AutoSys profile script, either the default one or the
one you have specified.

Machine to Run On
machine Execute on Machine
This attribute specifies the client machine on which the command
should be run. The job’s owner must have permission to access this
machine and to execute the specified command at this machine. The
machine can be a specific real machine (as listed in the /etc/hosts file of
the AutoSys server machine), a set of real machines, or a virtual machine.

Note • If you have implemented the Shadow Event Processor feature,

you should never set the machine attribute to localhost. localhost
implies: “run on the machine on which the Event Processor is currently
running.” The job might run normally on the Primary Event Processor
machine, and yet fail on the Shadow Event Processor machine.

You can also specify the svload program or your own, custom load
balancing program in lieu of a machine name. In this case, the Event
Processor will run the program at runtime to select the machine that is
best suited to run the job.

For more information about virtual machines, and how AutoSys chooses
a machine to run on when you specify multiple machines or a load
balancing program, see Chapter 9, Load Balancing and Queuing Jobs.

■ 4-8 AutoSys User Guide for UNIX

 Job Attributes ■
Essential Job Attributes

4 File Watcher Job Attributes

For file watcher jobs, the following attributes must be specified in
addition to those listed in Attributes Common to All Job Types on page 4-5.

Machine to Run On
machine Execute on Machine
This attribute specifies the client machine on which the File Watcher
should run. For a File Watcher, this attribute must specify a single real
machine, defined in the /etc/hosts file on the AutoSys server machine.

File to Watch For

watch_file File To Watch For
The name of the file to watch for must be a legal file name and must
include the full path to the file. All directories in the path must exist, but
the file itself does not have to exist at the time the job is defined.
Environment variables defined and exported in the profile file (the
specified or default), as well as global variables, can be used in the path.
Wildcards cannot be used in the file name.

When using the GUI, this field only appears when the File Watcher type
has been selected. This attribute is used in combination with the Watch
File Minimum File Size and Watch Interval attributes, to determine when
a file is considered to have arrived.

4 Box Job Attributes

There are no essential attributes for box jobs other than those listed in
Attributes Common to All Job Types on page 4-5.

AutoSys User Guide for UNIX 4-9 ■

■ Job Attributes
Optional Job Attributes

4 Optional Job Attributes

4 Common Job Starting Attributes
The following optional attributes are common to all Job Types:
command, file watcher, and box. These attributes are used to specify
when a job should start, and typically default to “inactive” or NULL if not
specified.

For information on how date and time attributes are affected by the
Spring and Fall time adjustments, see Date and Time Attributes and Time
Changes on page 4-28.

Start Date /Time Dependence

date_conditions Is the Start Date/Time Dependent?
The start date/time dependencies attribute is a toggle, which specifies
whether or not there are date and/or time conditions required for starting
the job. If set to “no,” the remainder of the related date/time attributes
described below will be ignored.

Days of the Week

days_of_week Days of the Week
The days of the week attribute specifies the days on which the job should
be run. You can specify one or more days, or “all” for every day.

Days to Run on - via a Custom Calendar

run_calendar Run on Days in Calendar

■ 4-10 AutoSys User Guide for UNIX

 Job Attributes ■
Optional Job Attributes

The days on which a job should be run can be specified by way of a

custom calendar, rather than through a list of days of the week. Custom
calendars, specified through the AutoSys Graphical Calendar Facility, or
the autocal_asc command, can include any number of dates on which
the job should be run. Each calendar is stored in the database as a
separate object with a unique name, and a calendar can be associated
with one or more jobs, using this attribute or the exclude_calendar
attribute.

Days to NOT Run on—via a Custom Calendar

exclude_calendar Do NOT Run on Days in Calendar
The days on which a job should not be run can be specified by way of a
custom calendar. Custom calendars, specified through the AutoSys
Graphical Calendar Facility, or the autocal_asc command, can include
any number of dates on which the job should not be run. Each calendar
is stored in the database as a separate object with a unique name, and a
calendar can be associated with one or more jobs, using this attribute or
the run_calendar attribute.

Specific Times of Day to Run

start_times Times of Day
This attribute specifies one or more specific times of day when the job
should be started. The job will be started at each specified time of day, on
every day specified in the associated date attributes. This attribute and the
“Specific Times Every Hour to Run” (start_mins) attribute are mutually
exclusive.

AutoSys User Guide for UNIX 4-11 ■

■ Job Attributes
Optional Job Attributes

Time of Day Not to Run

run_window Run Window
This attribute specifies a time range (or time window) during which a job
can be started. When the starting conditions for a job have been met,
AutoSys checks if the current time is within the specified run window.
The job will not start outside of the specified window.

This attribute controls only when the job will start, not when it will stop
running. This attribute is particularly useful when, for example, it is not
known when a watched-for file will arrive, and there are certain times
when jobs dependent on that file should not run. This setting can prevent
a late-arriving file from causing a job to run at an inopportune time. The
run window range cannot span more than 24 hours. jobs that are not in
a box must have starting conditions in addition to the run_window
attribute in order for the job to be automatically started.

Note • You can also block out times of day when you do not want a
job to start by putting the job on hold, then taking it off hold later.
The sendevent command can be used to accomplish this, executed
either from the command line, through the Send Event dialog, or
from within a shell script or batch file in another job.

Specific Times Every Hour to Run

start_mins Every Hour at
One or more specific times per hour when the job should be started can
be specified. Each time is specified in minutes past the hour. The job will
be started at each specified time every hour of the day, on every day
specified in the associated date attributes. This attribute and the “Specific
Times of Day to Run” (start_times) attribute are mutually exclusive.

■ 4-12 AutoSys User Guide for UNIX

 Job Attributes ■
Optional Job Attributes

Job Dependencies (Starting Conditions)

condition Starting Condition
Any number of job dependencies can be specified; however, every
dependency must evaluate to true before the dependent job will be run.
Examples of job dependencies include successful completion of a job,
failure of a job, a job’s exit code, and the value of a global variable.
Various combinations of conditions may also be specified. Job
dependencies can reference jobs residing on different AutoSys instances.

If a condition is specified for an undefined job, the condition will be

evaluated as FALSE, and any jobs dependent on this condition will not
run. To check for this type of invalid condition statement, you can use the
chk_cond stored procedure (see chk_cond (SP) in Chapter 1, AutoSys
Commands, of the AutoSys Reference Guide for UNIX).

Note • You should study the Starting Parameters section of Chapter 3,

AutoSys Jobs, and review the JIL examples provided in Chapter 7,
Defining Jobs Using JIL. This functionality opens up all sorts of
possibilities for controlling jobs, and provides information that will
help you when creating your own job definitions.

4 Common General Attributes

The following optional attributes are common to all job types:
command, file watcher, and box. These attributes are used to specify a
variety of features, and typically default to “inactive” or NULL if not
specified.

Description
description Description
This attribute provides a comment field, used for documentation
purposes only. When entering a description using JIL, you should enclose
the string in double quotes to ensure JIL properly interprets it. The GUI
adds quotes for you automatically.

AutoSys User Guide for UNIX 4-13 ■

■ Job Attributes
Optional Job Attributes

Box Name
box_name Name of the Box this Job is IN
Boxes allow a set of jobs to be manipulated as a group. This feature is
particularly useful for setting starting conditions at the box level, to
“gate” the jobs inside the box, then specifying their starting conditions
relative to each other individually, if necessary. This attribute specifies the
name of the box in which the job is to be placed. The specified box must
already exist before you can place jobs in it.

Minimum Run Time Alarm

min_run_alarm Minimum Run Time
A minimum run time (in minutes) can be specified for a job; the job
should not end in less than the specified time. This may prevent an
inadvertent truncation of the file being processed before it is complete.
If the job does end prior to this time, an alarm is generated to alert
someone to investigate the situation and take corrective action. Alarms
are informational, and they do nothing on their own. A monitor or the
Operator Console must be running and tracking alarms in order for them
to be seen and acted upon in real-time.

Maximum Run Time Alarm

max_run_alarm Maximum Run Time
A maximum runtime can be specified for a job; the job should not take
longer than the specified time to finish. This “reasonability” test may
catch an error, such as the application being stuck in a loop, or the
application waiting for additional data which may never arrive. If the job
runs longer than this time, an alarm is generated to alert someone to
investigate the situation and take corrective action. Alarms are
informational, and they do nothing on their own. A monitor or the
Operator Console must be running and tracking alarms in order for them
to be seen and acted upon in real-time.

■ 4-14 AutoSys User Guide for UNIX

 Job Attributes ■
Optional Job Attributes

The attribute “Terminate this job Mins after starting” (term_run_time)

can be used to automatically terminate a job that has been running for
too long. If term_run_time is not set, the job will continue running until
manually interrupted, or it completes by itself.

Terminate Due to Run Time

term_run_time Terminate this job Mins after starting
A maximum run time (in minutes) can be specified for a job; the job
should not take longer than the specified time to finish. This feature
allows the job to be automatically terminated if it runs longer than the
allotted time.

Send Alarm if the Job Fails

alarm_if_fail Send ALARM if this Job Fails?
This attribute specifies whether or not an alarm should be generated
when the job fails. Failure is defined as the job completing with a
FAILURE or TERMINATED status. (The “Maximum Exit Code for
SUCCESS” attribute determines what codes are interpreted as FAILURE
for a job, and the “Box Failure Condition” attribute determines what
constitutes a box failure.) Alarms are informational, and they do nothing
on their own. A monitor or the Operator Console must be running and
tracking alarms in order for them to be seen and acted upon in real-time.

Terminate the Box if the Job Fails

box_terminator If this Job fails should the Box it is
IN be Terminated?
This attribute specifies whether or not the box containing this job should
be terminated if the job fails or terminates. By using this attribute in
combination with the “Terminate the Job if the Box Fails” attribute, you
can control how nested jobs react when a job fails. This attribute only
applies if the job is being placed in a box.

AutoSys User Guide for UNIX 4-15 ■

■ Job Attributes
Optional Job Attributes

Terminate the Job if the Box Fails

job_terminator If the Box fails should this Job be
Terminated?
This attribute specifies whether or not the job should be terminated if the
box it is in fails or terminates. By using this attribute in combination with
the “Terminate the Box if the Job Fails” attribute, you can control how
nested jobs react when a job fails. This attribute only applies if the job is
being placed in a box.

Number of Times to Restart a Job

n_retrys Number of Times to Restart this Job
after a FAILURE
This attribute specifies how many times, if any, the job should be
restarted after exiting with a FAILURE status. The default is “0”, which
means the job will not be automatically restarted after an application
failure. This attribute applies to application failures (e.g., AutoSys is
unable to find a file or a command, or permissions are not properly set);
it does not apply to system or network failures (e.g., machine
unavailability, the socket connect timed out, the fork in the Remote
Agent failed, or the file system space resource check failed).

The number of restarts after system or network failures is specified using

the MaxRestartTrys parameter in the configuration file.

Time Zone for Job

timezone Time Zone

This attribute allows you to schedule a job based on a chosen time zone.
When this attribute is used, the time settings in the job are based on the
specified time zone. For example, if you define a start time of 01:00 for a
job running on a machine in Denver, and enter SanFrancisco in the Time
Zone field, the job will start at 1:00 a.m. Pacific time, which is 2:00 a.m.
in Denver.

■ 4-16 AutoSys User Guide for UNIX

 Job Attributes ■
Optional Job Attributes

If you specify a time zone that includes a colon, you must quote the time
zone name if you are using JIL. For example:
timezone: "IST-5:30"
If you do not quote a time zone specification that contains a colon, JIL
will interpret the colon as a delimiter, producing unexpected results.

Jobs with time-based starting conditions that do not specify a time zone
will have their start event scheduled based on the TZ environment
variable, which specifies the time zone under which the Event Processor
is running.

Delete Job After Completion

auto_delete Delete Job after completion?
This attribute indicates whether or not the job definition should be
automatically deleted after successful completion. A number of hours
can be specified (including “0” for immediately), or the attribute can be
turned “off” by specifying a negative value (e.g., “-1”), which is the
default. If auto_delete is set to 0, AutoSys will immediately delete job
definitions only if the job completed successfully.

If the job did not complete successfully, AutoSys will keep the job
definition for 7 days before automatically deleting it. This attribute is
useful for letting AutoSys schedule and run a one-time batch job.

Autohold
auto_hold Autohold On?
This feature is only for jobs in a box. When a job is in a box, it inherits the
box’s starting conditions. This means that when a box goes into the
RUNNING state, the box job will start all the jobs within it (unless other
conditions are not satisfied). This is typically the desired behavior;
however, there are occasions when it is not.

AutoSys User Guide for UNIX 4-17 ■

■ Job Attributes
Optional Job Attributes

For example, you might want to place a job in a box, but not start the job
until a non-job (i.e., operating system level) event arrives. By specifying
“yes” to Autohold On, AutoSys automatically changes the job state to
ON_HOLD when the box it is in begins RUNNING. At this point, the job
is in exactly the same state as if it were manually placed on hold. To start
the job, take the job off hold by sending the JOB_OFF_HOLD event via
the Send Event dialog or the sendevent command.

Permissions
permission Permissions
In UNIX, there are three levels of permission by user ID (uid), and within
AutoSys, two levels of job permission.

AutoSys’s permissions are based on the UNIX user ID scheme. This

scheme contains three types: owner, group, and world (or public). The
owner is the user who originally created the job. The group is the primary
group of which the owner is a member, and the world is every user with
a valid logon for the system.

AutoSys also allows designation of an Exec Superuser and an Edit

Superuser, by way of the autosys_secure command. The Edit Superuser
can edit any job definition, change the owner of a job, and change the
permissions assigned to a job; no other user has this authority. The Exec
Superuser can shut down the Event Processor, and can issue sendevent
commands to any job, regardless of its owner.

This is the permissions scheme used in AutoSys:

Execute

If execute permissions are enabled for the user’s group, allows the user
to issue events that affect the running (starting, stopping, etc.) of the
job. Users in primary and secondary groups have this permission.

■ 4-18 AutoSys User Guide for UNIX

 Job Attributes ■
Optional Job Attributes

Edit

If edit permissions are enabled for the user’s group, allows the user to
edit or delete the job definition. Only users in the primary group have
this permission.

The AutoSys permission scheme is based on the same permissions used

in native UNIX environment. AutoSys uses the user ID (uid) and group
ID (gid) specified in the UNIX environment to do the following:

■ Control access to the job definitions themselves.

■ Determine the execution permissions to be used when executing the

actual UNIX command specified in the job.

For more information about setting permissions, see the Overview section
of Chapter 2, AutoSys Security.

4 Command Job Attributes

For command jobs, the following optional attributes can be specified, in
addition to those listed in Attributes Common to All Job Types on page 4-5.
These attributes typically default to “inactive” if not specified.

Profile
profile Job Environment Profile
The profile attribute specifies the file to be sourced by the Bourne shell
before the specified command is executed. The AutoSys Remote Agent
always spawns a process and starts the Bourne shell in that process,
passing it the name of the profile to be sourced. This profile typically
includes definitions and exports of environment variables, which can be
referenced in the job’s command. The primary environment variable in
the profile is the $PATH. If a profile is not specified, the default AutoSys
profile, /etc/auto.profile, is used. If the profile attribute is specified,
that profile is searched for on the machine on which the command is to run.

AutoSys User Guide for UNIX 4-19 ■

■ Job Attributes
Optional Job Attributes

If a command that normally executes when entered at the command line

fails when run as an AutoSys job, it is usually due to the incomplete
specification of the required environment for the command in the
AutoSys profile file.

Note • It is essential that no Korn shell and C-shell statements appear

in profile file, because the Bourne shell that AutoSys runs will not be
able to process them. If you include these types of statements,
unexpected results will occur, often interfering with the proper
redirection of the stdin, stdout, and stderr files.

Redirection of the Standard Input File

std_in_file File to Redirect to Standard Input
The standard input file can be redirected to any file to which the job
owner has read permission on the client machine. The full pathname
must be specified, although variables exported from the default /etc/
auto.profile or job’s profile file, as well as global variables, can be used
in the pathname specification.

The default is /dev/null.

Redirection of the Standard Output File

std_out_file File to Redirect to Standard Output
The standard output file can be redirected to any file on the client
machine to which the job owner has write permission. The full pathname
must be specified, although variables exported from the default /etc/
auto.profile or job’s profile file, as well as global variables, can be used
in the pathname specification. The default is /dev/null.

■ 4-20 AutoSys User Guide for UNIX

 Job Attributes ■
Optional Job Attributes

By default, new information is appended to the file. By placing the

following notation as the first character(s) in the std_out_file
specification, you can specify if the error file should be appended to or
overwritten:

> Overwrite file

>> Append file

This setting overrides the instance-wide setting for the

AutoInstWideAppend parameter in the AutoSys configuration file. It also
overrides the machine-specific setting for the AutoMachWideAppend
parameter in the /etc/auto.profile file.

Note • If you are running jobs across platforms, realize that the Event
Processor of the issuing instance controls the default behavior. If the
issuing instance is NT, the default is to overwrite this file.

Redirection of the Standard Error File

std_err_file File to Redirect to Standard Error
The standard error file can be redirected to any file on the client machine
to which the job owner has write permission. The full pathname must be
specified, although variables exported from the default /etc/
auto.profile or job’s profile file, as well as global variables, can be used
in the pathname specification. The default is /dev/null.

By default, new information is appended to the file. By placing the

following notation as the first character(s) in the std_err_file
specification, you can specify if the error file should be appended to or
overwritten:

> Overwrite file

>> Append file

AutoSys User Guide for UNIX 4-21 ■

■ Job Attributes
Optional Job Attributes

This setting overrides the instance-wide setting for the

AutoInstWideAppend parameter in the AutoSys configuration file. It also
overrides the machine-specific setting for the AutoMachWideAppend
parameter in the /etc/auto.profile file.

Note • If you are running jobs across platforms, realize that the Event
Processor of the issuing instance controls the default behavior. If the
issuing instance is NT, the default is to overwrite this file.

Job Load
job_load Job Load
Machines can be assigned “maximum job loads,” which is a measure of
the CPU load that is desirable for a machine at any given time. Similarly,
jobs can be assigned loads, indicating the relative amount of processing
power they consume. This scheme allows for machine loading to be
controlled, and prevents a machine from being overloaded. If a job is
ready to run on a designated machine, but the current load on that
machine is too large to accept the new job’s load, the job will be
“queued” for that machine, to be run when sufficient resources are
available. For load balancing to function properly, all jobs to be run on
a controlled machine must have job loads specified; otherwise, their
impact on a machine cannot be measured.

Note • If you force a job to start, it will run even if its load exceeds the
machine’s max_load. Also, if job_load is specified for a job and no
priority attribute (described below) is set, AutoSys uses the default
priority of 0, which means ignore the job_load and run the job
immediately.

For information about load balancing on machines, see Chapter 9, Load

Balancing and Queuing Jobs.

■ 4-22 AutoSys User Guide for UNIX

 Job Attributes ■
Optional Job Attributes

Queue Priority
priority Que Priority
The queue priority establishes the relative priority of all jobs queued for
a given machine, with the lower number indicating higher priority. If a
job is ready to run on a designated machine, but the current load on that
machine is too large to accept the new job’s load, the job will be
“queued” for that machine.

priority only influences the starting of jobs that are queued, unless the
jobs are in a box. If jobs in a box have a priority attribute setting, they
will be processed in order of priority, highest to lowest.

Job Overrides
override_job Edit One Time Over-Rides?
You can specify a one-time job override for the next run of a particular job.
An override lets you change the behavior of a job the next time the job
runs.

The following attributes can be modified in a job override:

auto_hold min_run_alarm std_in_file

command n_retrys std_out_file

condition profile term_run_time

date_conditions run_calendar watch_file

days_of_week run_window watch_file_min_size

exclude_calendar start_mins watch_interval

machine start_times

max_run_alarm std_err_file

AutoSys User Guide for UNIX 4-23 ■

■ Job Attributes
Optional Job Attributes

For a description of how to use the GUI to specify job overrides, see
Specifying One-Time Job Overrides in Chapter 6, Defining AutoSys Jobs Using
the GUI.

Maximum Exit Code for Success

max_exit_success Maximum Exit Code for SUCCESS
The maximum exit code for success attribute indicates what exit codes
will be considered by AutoSys as a success. It is used when a command
can exit with more than just a single exit code, indicating either “degrees
of success,” or other conditions that may not indicate a failure. This
attribute lets you define complex branching logic based on specific exit
code values. AutoSys reserves exit codes greater than 120 for internal use,
so do not use exit codes of 120 or greater.

Average Runtimes
avg_runtime (JIL only)
The avg_runtime attribute is used to provide an average runtime (in
minutes) for a job that is newly submitted to the AutoSys database; it
establishes this value in the absence of the job having been run multiple
times. This attribute is used solely to establish an average runtime for the
new job in the avg_job_runs table, which in turn can be used for
projections and simulations in AutoSys/Xpert.

Heartbeat-Interval
heartbeat_interval Heartbeat Interval (mins)
In AutoSys, heartbeats are a means of monitoring a job’s progress. It
automates the common practice of outputting characters, similar to
displaying “progress” asterisks across the screen as a process runs. If a job
does not send a heartbeat within this specified interval, a HEARTBEAT
alarm is generated. The heartbeat interval is specified in minutes.

■ 4-24 AutoSys User Guide for UNIX

 Job Attributes ■
Optional Job Attributes

To send a heartbeat from a C program, you call the routine found in the
following source file:
$AUTOSYS/code/heartbeat.c
To send a heartbeat from a Bourne shell script, execute the code found in
the following file:
$AUTOSYS/code/heartbeat.sh
The Event Processor must be configured to check for heartbeats. To do
this, modify the configuration file, which has the following name:
$AUTOUSER/config.$AUTOSERV

For more information about the AutoSys configuration file, see Sample
Configuration File in Chapter 13, Configuring AutoSys. For information on
sending heartbeats, see Sending Heartbeats in Chapter 7, AutoSys API, of
the AutoSys Reference Guide for UNIX.

Resource Check - File Space

chk_files Resource Check - File System
Space...
This attribute specifies a minimum amount of file space that must be
available on the designated file system(s) for the job to be started. One
or more file systems, specified with full pathnames or directory names,
and their corresponding sizes, can be specified. If multiple file systems
are specified, separate them with a single space. When the Remote Agent
is preparing to start the job on the client machine, it checks whether or
not the required space is available before starting the job. If the
requirements are not met, an alarm is generated and AutoSys
automatically reschedules the job to start again after a delay. It will
perform the same resource check the next time it attempts to start. This
feature is intended to prevent a job that is known to require large
amounts of file space from failing due to a shortage of space during
processing time.

AutoSys User Guide for UNIX 4-25 ■

■ Job Attributes
Optional Job Attributes

4 File Watcher Job Attributes

For file watcher jobs, the following attributes can be specified in addition
to those listed in File Watcher Job Attributes on page 4-9. These attributes
typically default to inactive if not specified.

Watch File Minimum Size

watch_file_min_size Minimum File Size (in Bytes)
The watch file minimum size determines when enough data has been
written to the file to consider it “complete.” This attribute is specified in
bytes. You should specify a reasonable file size to ensure that a nearly
empty file isn’t assumed to be complete. Use caution with this attribute.
If you specify a large file size AutoSys will wait for the file to reach that
size, even if the file has reached a steady state and is no longer growing.

Watch Interval
watch_interval Time Interval (secs) to Determine
Steady State
The watch interval specifies (in seconds) how often the File Watcher
should check the current file size to ascertain whether data is still being
written to the file. The default is every 60 seconds.

Resource Check - File Space

chk_files Resource Check - File System
Space...
This attribute specifies a minimum amount of file space that must be
available on designated file systems for a command job to be started.
One or more file systems, specified with full pathnames or directory
names, and their corresponding sizes can be specified. When the Remote
Agent is preparing to start the job on the client machine, it checks
whether the required space is available before starting the job. If the
requirements are not met, an alarm is generated. File watcher jobs will
still be started.

■ 4-26 AutoSys User Guide for UNIX

 Job Attributes ■
Optional Job Attributes

4 Box Job Attributes

For box jobs, the following optional attributes can be specified, in
addition to those listed in Attributes Common to All Job Types on page 4-5.
These attributes typically default to “inactive” or NULL if not specified.

Box Successful Completion

box_success SUCCESS Conditions
The default condition required for a box to be considered successful is
that every job in the box must have completed with a success condition.
A box can contain complex branching logic, which can take a number of
different paths, all of which constitute a success. In this case, some jobs
in the box may never need to run, but if the default box behavior is
applied, the jobs that had not run would prevent the box from ever
completing.

This attribute can be used to specify what is considered a success, which

could be as simple as the success of a single job, or as complex as
necessary. This attribute is only displayed in the GUI when you select a
box job type.

Box Failure
box_failure FAILURE Condition
The default condition required for a box to complete with a FAILURE
status is that all jobs in the box have completed and one or more jobs in
the box completed with a failure condition. A box can contain complex
branching logic, which may take a number of different paths, one of
which may include recovery from a failed job. In this case, you might
want the box to be considered successful, even though a job within it
failed. This attribute can be used to specify what will be considered as a
failure, which could be as simple as the failure of a single job, or as
complex as necessary. This attribute is only displayed in the GUI when
you select a box job type.

AutoSys User Guide for UNIX 4-27 ■

■ Job Attributes
Date and Time Attributes and Time Changes

4 Date and Time Attributes and Time Changes

Date and Time attributes can be affected by the Spring and Fall time
adjustments. The following sections describe the job run behavior you
should expect, and thus can plan for.

4 The Time Change

During the changes to and from daylight saving time, your operating
system automatically changes the system clock to reflect the switch to
either Standard Time (ST) or Daylight Time (DT).

In the spring, at 2 a.m., the clocks spring forward to 3 a.m. In most of the
United States, this happens on the first Sunday in April. Figure 4-1
illustrates the time change.

Daylight-saving Time

3:00 4:00 5:00

1:00 1:59

Standard Time

Figure 4-1 • Change from ST to DT

When this change occurs, time runs 1:58 ST, 1:59 ST, 3:00 DT, 3:01 DT,
and the 2:00 to 2:59 hour is lost.

In the fall, at 2 a.m., the clocks fall back to 1 a.m. In most of the United
States, this happens on the fourth Sunday in October. Figure 4-2
illustrates the time change.

■ 4-28 AutoSys User Guide for UNIX

 Job Attributes ■
Date and Time Attributes and Time Changes

Standard Time

1:00 2:00 3:00 4:00

0:00 1:00 1:59

Daylight-saving Time

Figure 4-2 • Change from DT to ST

When this change occurs, time runs 1:58 DT, 1:59 DT, 1:00 ST, 1:01 ST,...,
2:00 ST, 2:01 ST, and the 1:00 to 1:59 hour is repeated.

4 AutoSys Behavior During Time Change

Jobs that are time dependent may have their scheduling shifted to adjust
for the time change. Jobs that are not time dependent, but have other
starting conditions, will run as normal.

There are two types of time dependencies within AutoSys: absolute, and
relative. Absolute times are defined to occur at a particular time of day,
for example 9:30 on Thursday, or 12:00 on December 25. Absolute time
dependent job attributes include:
■ days_of_week

■ exclude_calendar

■ run_calendar

■ run_window

■ start_times

AutoSys User Guide for UNIX 4-29 ■

■ Job Attributes
Date and Time Attributes and Time Changes

Relative times are specified with respect to either 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.
Relative time dependent job attributes include:
■ auto_delete

■ max_run_alarm

■ min_run_alarm

■ start_mins

■ term_run_time

■ watch_interval

During the time change, absolute time attributes will behave differently
than relative time attributes, as described below.

Spring Time Change

During the change to daylight saving time in the spring, the “2:00-2:59”
hour is “lost,” therefore AutoSys cannot schedule any jobs during that
non-existent hour.

The AutoSys solution is to schedule jobs with absolute time

dependencies for the missing hour to start within the first minute of the
3:00 DT hour. For example, a job scheduled to run on Sundays at 2:05,
will run at 3:00:05 that day; a job scheduled to run everyday at 2:45 will
run at 3:00:45. Although it might not be possible to start a large number
of jobs within the first minute of the hour, this feature does somewhat
preserve the scheduling order.

If you scheduled a job to run more than once during the missing hour,
for example, 2:05 and 2:25, only the first scheduled job would run. Any
additional start times for the same job in the missing hour will be
ignored.

■ 4-30 AutoSys User Guide for UNIX

 Job Attributes ■
Date and Time Attributes and Time Changes

Relative time dependencies, such as start_mins, will run as you would

expect. For example, a job specified to run at 0, 20, and 40 minutes after
the hour will be scheduled for 1:00 ST, 1:20 ST, 1:40 ST, 3:00 DT, 3:20
DT, and 3:40 DT. Relative interval calculations, such as max_run_alarm,
min_run_alarm, term_run_time, and watch_interval are still calculated in
minutes out from when the job started. For example, if our Sunday at
2:05 job has a term_run_time of 90 minutes, the job will start shortly after
3:00, the term_run_time will be at 4:30.

Therefore, the behavior between two jobs that appear to have the same
times specified, but use start_times versus start_mins, will not be the
same. For example, job “Jrel” has start minutes of 10 and 20 minutes after
the hour, and job “Jabs” has start times of 1:10, 1:20, 2:10, 2:20, 3:10,
and 3:20. “Jrel” will run at 1:10, 1:20, 3:10, and 3:20. “Jabs” will run at
1:10, 1:20, 3:00, 3:10, and 3:20.

Run Windows
Run windows are treated a bit differently. If the specified closing of the
run window falls within the missing hour, its recalculated closing time
will be bumped up an hour, so that the effective duration of the run
window remains the same. For example, a run window of 1:00 - 2:30 will
have the closing time move to 3:30, so that the run window still remains
open for an hour and a half.

If the specified opening of the run window falls within the missing hour,
its opening time is moved to 3:00. The closing time does not get altered,
therefore the run window is foreshortened. For example, a run window
of 2:45 - 3:45 will become 3:00 - 3:45, and the actual run window elapsed
time will be 15 minutes shorter.

If both the specified opening and closing of the run window is within the
missing hour, its opening time is moved to the first minute after 3:00,
and its closing time is pushed forward one hour. Therefore, the resultant
run window may be lengthened. For example, a run window of
2:15 - 2:45 will become 3:00 - 3:45, or 15 minutes longer.

AutoSys User Guide for UNIX 4-31 ■

■ Job Attributes
Date and Time Attributes and Time Changes

Fall Time Change

During the change from daylight saving to standard time in the fall, there
are two “1:00-1:59” hours. Jobs with start_times set between 1:00 and
1:59 will run only in the second, or Standard Time hour. Jobs with
start_mins settings will run in both hours.

For example, a job scheduled to run on Sundays at 1:05, will run only at
the second 1:05. A job scheduled to run every 30 minutes will run at 1:00
DT and 1:30 DT, then again at 1:00 ST and 1:30 ST, and so on (as shown
in Figure 4-3).

Standard Time

1:00 2:00 3:00

start_time attribute
runs in second hour

start_mins attribute runs in both hours

0:00 1:00 1:59

Daylight-saving Time

Figure 4-3 • Scheduling between 1:00 - 1:59, DT to ST

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

Relative interval calculations, such as max_run_alarm, min_run_alarm,

term_run_time, and watch_interval are still calculated in minutes out
from when the job started. For example, if a job is scheduled to run on
Sunday at 0:30, and has a term_run_time of 120 minutes, the job would
normally be terminated at 2:30. On the day of the fall time change, it will
terminate at 1:30 Standard Time, which is 120 minutes after the job
started.

■ 4-32 AutoSys User Guide for UNIX

 Job Attributes ■
Date and Time Attributes and Time Changes

Testing the Fall Time Change

During the fall time change from Daylight Savings time to Standard
Time, your operating system automatically falls back one hour from 2
a.m. to 1 a.m., causing the hour from 1 a.m. to 2 a.m to be repeated.

When testing this time change, you must set the clock to a time before 1
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 within the 1 a.m to 2
a.m. window, the system will assume that the time change has already
occurred and will not reset at 2 a.m.

Run Windows
Run windows are treated a bit differently. If the specified opening of a
run window is before the time change, and its specified closing falls
within the repeated hour, it will close during the daylight saving, or first
hour. For example, a run window of 11:30 - 1:30 will have the closing
time of 1:30 DT, not 1:30 ST, which means that the run window remains
open for its specified two hours. This may be a problem if there are also
associated start times on the job which occur during the repeated hour.
In the example above, if the job 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.

If the specified opening of the run window falls within the repeated hour,
its opening time is moved to the second, Standard Time hour. The closing
time does not get altered, therefore the length of the run window will
remain the same. For example, a run window of 1:45 - 2:45 will become
1:45 ST to 2:45, or the same hour in length.

If both the specified opening and closing of the run window is within the
repeated hour, the run window will be open during the second, Standard
Time hour.

AutoSys User Guide for UNIX 4-33 ■

 5
Box Job Logic
This chapter explains how box jobs work, including default box behavior
and how to override the default behavior. It also explains what types of
jobs should and should not be placed in a box. To illustrate box logic,
several examples of box job definitions and job streams are provided in
Examples.
Basic Box Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Default Box Job Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
When You Should Not Use a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
What Happens When a Box Runs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5

Box Job Attributes and Terminators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

Attributes in a Box Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Attributes in a Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Time Conditions in a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Force Starting Jobs in a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
How Job Status Changes Affect Box Status . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Advanced Conditions in Box Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Default Box Success and Box Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14
Explicit Box Success and Box Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16

AutoSys User Guide for UNIX 5-1 ■

■ Box Job Logic

Using the Box Terminator Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17

Using the Job Terminator Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
Advanced Job Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19

■ 5-2 AutoSys User Guide for UNIX

 Box Job Logic ■
Basic Box Concepts

5 Basic Box Concepts

A box is a container of jobs with like starting conditions (either date/time
conditions or job dependency conditions). Use boxes to group jobs with
like scheduling parameters, not as means of grouping jobs
organizationally. For example, if you have a number of jobs that run
daily at 1:00 a.m., you could put all these jobs in a box and assigning a
daily start condition to the box. However, a variety of account processing
jobs with diverse starting conditions should not be grouped in the same
box.

5 Default Box Job Behavior

Some important rules to remember about boxes are:

■ Jobs run only once per box execution.

■ Jobs in a box will start only if the box itself is running.

■ Boxes should be used primarily for jobs with the same starting
conditions. A box used to group sequential jobs is limited to 1,000
jobs.

■ As long as any job in a box is running, the box remains in RUNNING

state; the box cannot complete until all jobs have run.

■ By default, a box will return a status of SUCCESS only when all the
jobs in the box have run and the status of all the jobs is “success.”

Default SUCCESS is described in Default Box Success and Box Failure.

■ By default, a box will return a status of FAILURE only when all jobs in
the box have run and the status of one or more of the jobs is “failure.”

Default FAILURE is described in Default Box Success and Box Failure.

■ Unless otherwise specified, a box will run indefinitely until it reaches

a status of SUCCESS or FAILURE. For a description of how to override
this behavior, see Box Job Attributes and Terminators.

AutoSys User Guide for UNIX 5-3 ■

■ Box Job Logic
Basic Box Concepts

■ Changing the state of a box to INACTIVE (via the sendevent

command) changes the state of all the jobs in the box to INACTIVE.

5 When You Should Not Use a Box

The fact that all jobs in a box change status when a box starts running has
lead some to use boxes to implement “job cycle” behavior. Be aware that
placing jobs in a box to achieve this end may bring with it undesired
behavior due to the nature of boxes.

Avoid the temptation to put jobs in a box as a short cut for performing
events (such as ON_ICE or ON_HOLD) on a large number of jobs at
once. You will most likely find that the default behavior of boxes inhibits
the expected execution of the jobs you placed in the box.

Likewise, you should not place jobs in a box solely because you want to
run reports on all of them. When you run autorep on a box, you will get
a report on the box and all the jobs in the box (unless you use the -L0
option). In addition, if you use wildcarding when specifying a job name,
you could get duplicate entries in your report. For example, suppose you
have a box named “acnt_box” containing three jobs named “acnt_job1”,
“acnt_job2”, and “daily_rep”. If you specify acnt% as the job name for the
autorep report, the report will have an entry for the box “acnt_box” and
an entry for each job in the box. Then autorep will continue searching for
all job names matching the wildcard characters and, thus, will list
“acnt_job1” and “acnt_job2” a second time.

■ 5-4 AutoSys User Guide for UNIX

 Box Job Logic ■
Basic Box Concepts

5 What Happens When a Box Runs

As soon as a box starts running, all the jobs in the box (including
sub-boxes) change to status ACTIVATED, meaning they are eligible to
run. (Because of this, jobs in boxes do not retain their statuses from
previous box cycles.) Then each job is analyzed for additional starting
conditions. All jobs with no additional starting conditions are started,
without any implied ordering or prioritizing. Jobs with additional
starting conditions remain in the ACTIVATED state until those additional
dependencies have been met. The box remains in the RUNNING state as
long as there are activated or running jobs in the box.

If a box is terminated before a job in it was able to start, the status of that
job will change directly from ACTIVATED to INACTIVE.

Note • Jobs in a box cannot start unless the box is running. However,
once the job starts running, it will continue to run even if the box is
later stopped for some reason.

Once all the jobs in a box have completed successfully, the box completes
with a status of SUCCESS. The status of the box and the jobs in the box
remain unchanged until the next time the box runs. (Some exceptions to
this are explained in How Job Status Changes Affect Box Status.)

If a box changes to TERMINATED state, for example, if a user sends a

KILLJOB event, it will stay in TERMINATED state until the next time it is
started, regardless of any later state changes of jobs within the box.

AutoSys User Guide for UNIX 5-5 ■

■ Box Job Logic
Basic Box Concepts

Simple Box Job

In this example, a box named “simple_box” contains three jobs: “job_a”,
“job_b”, and “job_c”. “job_a” and “job_b” have no starting conditions;
the starting condition for “job_c” is the success of “job_b”.

job_a job_b

simple_box SUCCESS job_b

job_c

Figure 5-1 • Example Box Job

When “simple_box” starts running, all jobs change to state ACTIVATED.

Because “job_a” and “job_b” have no additional starting conditions, they
will start running. After “job_b” completes successfully, “job_c” will start.
When “job_c” completes successfully, the box completes with status of
SUCCESS.

If “job_b” fails, “job_c” will not start; it will remain in ACTIVATED state.
Because no contingency conditions have been defined, “simple_box”
will continue running indefinitely, waiting for the default completion
criteria to be met, namely that all jobs in the box ran.

■ 5-6 AutoSys User Guide for UNIX

 Box Job Logic ■
Box Job Attributes and Terminators

5 Box Job Attributes and Terminators

The following sections describe how to use various job attributes to
control the behavior of box jobs and their contained jobs.

5 Attributes in a Box Job Definition

Two box job attributes override the default success or failure of a box.
They are box_success and box_failure. If included in a box job
definition, they determine what conditions must be met to put the box
in a state of SUCCESS or FAILURE. If you specify conditions for success
of a box you should also specify failure conditions; otherwise the default
failure conditions are applied.

Example of a Non-Default Success Condition

Using the above simple box example, assume you defined the following
success condition for “simple_box”:
box_success: success(job_a)

If “job_a” runs successfully, and “job_b” is still running, “job_c” would

pass from ACTIVATED state directly to INACTIVE state without ever
running because the box it is in would no longer be running.

When overriding default box terminators, be careful that you do not

define conflicting success and failure conditions. For information, see
Figure 5-6.

5 Attributes in a Job Definition

There are two attributes you can add to the definition of a job within a
box to force either the job or the box to stop running. They are
box_terminator and job_terminator.

The box_terminator: y attribute specifies that if the job fails, the box the
job is in should terminate. If you use this attribute, be sure you have
defined conditions for the other jobs in the box in the event that the box
is terminated. For more information, see Figure 5-7.

AutoSys User Guide for UNIX 5-7 ■

■ Box Job Logic
Box Job Attributes and Terminators

The job_terminator: y attribute specifies that if the box the job is in fails,
this job will terminate. If you want every job in a box to terminate upon
box failure, you must add this attribute to every job definition. For more
information, see Figure 5-8.

5 Time Conditions in a Box

Each job in a box will run only once per box execution. Therefore, you
should not define more than one time attribute for any job in a box
because the job will only run the first time. If you want to put a job in a
box, but you also want it to run more than once, you must assign
multiple start time conditions to the box itself, and define no time
conditions for the job.

Remember also that the box must be running before the job can start. Do
not assign a start time for a job in a box if the box will not be running at
that time. If you do, the next time the box starts, the job will start
immediately.

The following example illustrates a scenario that would not work

properly if placed in a box.

“job_a” is defined to run repeatedly until it succeeds. “job_report” has

one starting condition—the success of “job_a”.

bx_stat job_a
3:00 a.m. Daily
run until succeed

job_report
success(job_a)
Report success of job_a

Figure 5-2 • Box Job with Time Conditions

■ 5-8 AutoSys User Guide for UNIX

 Box Job Logic ■
Box Job Attributes and Terminators

At 3:00 a.m., “bx_stat” starts running, which causes “job_a” to start

running. If “job_a” is successful, “job_report” runs and all goes as
expected. However, if “job_a” fails, it will not be able to run again until
the next time the box starts, because jobs run only once per box
execution. “job_report” will still be ACTIVATED waiting for the success
of “job_a”, and the status of the box will be RUNNING. The box will
remain in this state indefinitely.

5 Force Starting Jobs in a Box

The FORCE_STARTJOB command forces a job to start even if its starting
conditions have not been met. The command has the form:
sendevent -E FORCE_STARTJOB -J job_name
You can also execute this by selecting the Force Start Job button in the Job
Activity Console.

If you force start a job in a box, the state of the box influences whether or
not other jobs in the box will run as expected, as shown in the following
example.

bx_report
3:00 a.m. Daily

job_Fwatch run_stats report_stats

success(job_Fwatch) success(run_stats)
box_terminator: y

Watch for file Run Statistics Report Statistics

Figure 5-3 • Example Box Job

In Figure 5-3, if the job “run_stats” fails, the “bx_report” box job will
terminate because “run_stats” has a box_terminator attribute. If you force
start “run_stats”, and it completes successfully, “report_stats” would still
not start because the box it is in is not running.

AutoSys User Guide for UNIX 5-9 ■

■ Box Job Logic
Box Job Attributes and Terminators

The next section discusses how job status changes influence the status of
the container box.

5 How Job Status Changes Affect Box Status

If a box that is not running contains a job that changes status, as a result
of a FORCE_STARTJOB or CHANGE_STATUS event, the new job status
could change the status of its container box. A change of status of the box
could trigger the start of downstream jobs that are dependent on the box.

If a box contained only one job, and the job changed status, the box
status would change as shown in Table 5-1.
Table 5-1 • How Job Status Changes Impact Box Status

Current Box Status New Job Status New Box Status

SUCCESS TERMINATED or FAILURE FAILURE

SUCCESS SUCCESS Box status does not change

FAILURE SUCCESS SUCCESS

FAILURE FAILURE Box status does not change

INACTIVE SUCCESS SUCCESS

INACTIVE TERMINATED or FAILURE FAILURE

TERMINATED any change Box status does not change

If another AutoSys job is dependent on the status of the box, the status
change could trigger the job to start. If the box status does not change,
dependent jobs are not affected.

■ 5-10 AutoSys User Guide for UNIX

 Box Job Logic ■
Examples

If the box contains other jobs in addition to the job that changed status,
the status of the box will be re-evaluated according to the success or
failure conditions assigned to the box (either the default or user-
assigned). Any jobs in the box with a status of INACTIVE are ignored
when the status of the box is being re-evaluated. For example, consider
an INACTIVE box that contains four jobs, all with a status of INACTIVE
(this is typical of a newly created box). If one of the jobs is force started
and completes successfully, the status of the box will change to SUCCESS
even though none of the other jobs ran.

5 Examples
Spend some time studying the examples in this section. They will help
explain the logic of job flow in a box and reduce your chances of creating
unexpected box behavior.

5 Advanced Conditions in Box Jobs

In the following example, conditions are defined to address different
situations where the box might complete with a FAILURE status. The
logic of this job flow is as follows:

■ The box job named “bx_daily_update” has date and time conditions
specified for its starting conditions; it runs every day of the week at
3:00 a.m. This box contains three Command Jobs whose overall
purpose is to update files and generate a report.

■ The Command Job named “job_update” updates a set of files. It is

defined as being inside “bx_daily_update”. It will run as soon as
“bx_daily_update” starts because it has no other starting conditions.
This job has a box_terminator attribute; therefore, if this job fails, the
box containing this job will be terminated.

■ The Command Job named “job_run_stats” runs statistics on the

updated files. It is defined as being inside “bx_daily_update”. It will
run only on the successful completion of the job named
“job_update”. This job has a box_terminator attribute; therefore, if
this job fails, the box containing this job will be terminated.

AutoSys User Guide for UNIX 5-11 ■

■ Box Job Logic
Examples

■ The Command Job named “job_report_stats” reports on the statistics

generated by “job_run_stats”. It is defined as being inside
“bx_daily_update”. It has a job dependency condition specified for its
starting parameter. It will run only on the successful completion of the
job named “job_run_stats”.

■ The Command Job named “job_trigger_msg” has a job dependency

condition specified for its starting parameter. It will run only on the
FAILURE of the box job named “bx_daily_update”. This job will page
an operator in order that the problem be investigated.

Figure 5-4 illustrates this job stream.

■ 5-12 AutoSys User Guide for UNIX

 Box Job Logic ■
Examples

bx_daily_update
3:00 a.m. daily

job_update
box_terminator: y
Update files

SUCCESS job_update FAILURE job_update

job_run_stats
success(job_update)
box_terminator: y
Run statistics

SUCCESS job_run_stats FAILURE job_run_stats

job_report_stats
success(job_run_stats)
Report statistics

SUCCESS job_report_stats FAILURE job_report_stats

SUCCESS bx_daily_update FAILURE bx_daily_update

job_trigger_msg
failure(bx_daily_update)
Page operator

SUCCESS job_trigger_msg

Figure 5-4 • Advanced Box Job Example

AutoSys User Guide for UNIX 5-13 ■

■ Box Job Logic
Examples

5 Default Box Success and Box Failure

The box job “do_statistics” runs every day at 3:00 a.m. It contains three
jobs. “update_accounts” updates files; it has no other starting conditions
so it starts as soon as the box starts running. “run_stats” runs statistics; its
only starting condition is the success of “update_accounts”.
“report_stats” reports statistics; its only starting condition is the success
of “run_stats”. No conditions for success or failure of the box have been
defined, therefore the default conditions are applied. That is, box success
is when all jobs in the box have run and successfully completed; box
failure is when all jobs in the box have run and at least one has failed. The
box will remain in the RUNNING state until all jobs in the box have run.

Figure 5-5 illustrates this job stream logic.

■ 5-14 AutoSys User Guide for UNIX

 Box Job Logic ■
Examples

Job Stream Job Status

update_accounts FAILURE

SUCCESS

run_stats
FAILURE ACTIVATED
success(update_accounts)

SUCCESS

report_stats
FAILURE ACTIVATED ACTIVATED
success(run_stats)

SUCCESS

Box SUCCESS Box FAILURE Box Still RUNNING

Figure 5-5 • Box Success and Failure

AutoSys User Guide for UNIX 5-15 ■

■ Box Job Logic
Examples

5 Explicit Box Success and Box Failure

Job Definitions
do_statistics
3:00 a.m. Daily
box_success: success(update_accounts) AND success(run_stats) AND
success(report_stats)
box_failure: failure(update_accounts) OR failure(run_stats) OR
failure(report_stats)
update_accounts run_stats report_stats
success(update_accounts) success(run_stats)

Update Files Run Statistics Report Statistics

Job Stream Job Status

do_statistics

update_accounts FAILURE

SUCCESS

run_stats FAILURE INACTIVE

SUCCESS

report_stats
FAILURE INACTIVE INACTIVE

SUCCESS

Box SUCCESS FAILURE FAILURE FAILURE

Figure 5-6 • Success and Failure Conditions

■ 5-16 AutoSys User Guide for UNIX

 Box Job Logic ■
Examples

5 Using the Box Terminator Attribute

Job Definitions
daily_accounts
3:00 a.m. Daily
daily_receipts daily_payables daily_balance
box_terminator: y box_terminator: y success(daily_reciepts)
AND success(daily_payables)
Process Receipts Process Payables Calculate Balance

Job Stream
daily_accounts

daily_receipts daily_payables

SUCCESS SUCCESS

FAILURE FAILURE

Box TERMINATED SUCCESS TERMINATED

daily_balance

Figure 5-7 • Using box_terminator

AutoSys User Guide for UNIX 5-17 ■

■ Box Job Logic
Examples

5 Using the Job Terminator Attribute

Job Definitions
daily_accounts
3:00 a.m. Daily
daily_receipts daily_payables daily_balance
job_terminator: y success(daily_reciepts)
AND success(daily_payables)
Process Receipts Process Payables Calculate Balance

Job Stream
daily_accounts

daily_receipts daily_payables TERMINATE

SUCCESS SUCCESS

FAILURE FAILURE

Box FAILURE FAILURE

daily_balance

Figure 5-8 • Using job_terminator

■ 5-18 AutoSys User Guide for UNIX

 Box Job Logic ■
Examples

5 Advanced Job Streams

Scenario on the first of the month

The first time cycle is run (e.g., January 1), statuses behave as expected.

Job Definitions
job_Fwatch job_monthly job_daily
1:00 a.m. First Day 2:00 a.m. First Day 3:00 a.m. Daily
of Month of Month success(job_monthly)
term_run_time: 90 success(job_Fwatch)
Watch for File Re-index, Organize, Purge Generate Report

Job Stream
Date/Time Start File from
job_Fwatch Mainframe
Conditions Met

Job Dependency
Condition Met SUCCESS

Date/Time Start
job_monthly
Conditions Met
Event Status in
AutoSys Database =
SUCCESS SUCCESS

Job Dependency
Condition Met

Start job_daily
Date/Time
Conditions Met

SUCCESS

Figure 5-9 • Jobs Run the First of Month

AutoSys User Guide for UNIX 5-19 ■

■ Box Job Logic
Examples

Scenario on the second of month

On days of the month other than the 1st, “job_Fwatch” and
“job_monthly” do not run. They still have a status of SUCCESS in the
AutoSys database from the previous run on the first of the month. As a
result, “job_daily” will still run.

Job Definitions
job_Fwatch job_monthly job_daily

1:00 a.m.First Day 2:00 a.m. First Day 3:00 a.m. Daily
of Month of Month success(job_monthly)
term_run_time: 90 success(job_Fwatch)
Watch for File Re-index, Organize, Purge Generate Report

Job Stream

Date/Time NOT RUN File from

job_Fwatch Mainframe
NOT Conditions Met

Job Dependency
Condition NOT Met

Event Status in
Date/Time NOT RUN job_monthly AutoSys Database =
NOT Conditions Met SUCCESS (from Jan 1)

Job Dependency
Condition Met

Start job_daily
Date/Time
ConditionsMet

SUCCESS

Figure 5-10 • Jobs Run the Second of Month

■ 5-20 AutoSys User Guide for UNIX

 Box Job Logic ■
Examples

Scenario I on first of the month

On the first of the next month (e.g., February 1), the file from the
mainframe fails to arrive; therefore, “job_monthly” does not run for the
month. However, its event status in the AutoSys database is still
SUCCESS from the previous month, and as a result, “job_daily” runs in
error.

Job Definitions
job_Fwatch job_monthly job_daily

1:00 a.m.First Day 2:00 a.m. First Day 3:00 a.m. Daily
of Month of Month success(job_monthly)
term_run_time: 90 success(job_Fwatch)
Watch for File Re-index, Organize, Purge Generate Report

Job Stream
Date/Time Start File from
job_Fwatch Mainframe
Conditions Met

term_run_time: 90
TERMINATED
Job Dependency
Condition NOT Met
Event Status in
NOT RUN job_monthly AutoSys Database =
Date/Time SUCCESS (from Jan 1)
Conditions Met

Job Dependency
Condition Met

Start job_daily
Date/Time
Conditions Met

Undesirable Result SUCCESS

Figure 5-11 • Incorrect Job Stream Logic

AutoSys User Guide for UNIX 5-21 ■

■ Box Job Logic
Examples

Scenario II on first of the month

To fix statuses that are time-related, you can use a sendevent command
to change them to INACTIVE at the end of their valid time period. You
can create another job to do this automatically.

Job Definitions
job_Fwatch job_monthly job_daily
1:00 a.m.First Day 2:00 a.m. First Day 3:00 a.m. Daily
of Month of Month success(job_monthly)
term_run_time: 90 success(job_Fwatch)
Watch for File Re-index, Organize, Purge Generate Report

At 1:00 a.m. on first day of month, issue a CHANGE_STATUS on “job_monthly”

using GUI Send Event dialog or by issuing the following command:

sendevent -E CHANGE_STATUS -S INACTIVE -J job_monthl

Job Stream

Date/Time Start File from

job_Fwatch
Conditions Met

term_run_time: 90
TERMINATED Mainframe
Condition NOT Met
Event Status in
Job Dependency NOT RUN job_monthly AutoSys Database =
INACTIVE
Date/Time Job Dependency
Conditions Met Condition NOT Met

NOT RUN job_daily

Date/Time
ConditionsMet

Desirable Result
Figure 5-12 • Changing Job Status

■ 5-22 AutoSys User Guide for UNIX

 Box Job Logic ■
Examples

Scenario II I on first of the month

Instead of issuing a sendevent command to change the status of the jobs,
you could put the monthly process in a box, and set box_failure or
box_terminator appropriately.

box_monthly

job_Fwatch job_monthly job_daily

1:00 a.m.First Day 3:00 a.m. Daily
of Month success(job_Fwatch) success(box_monthly)
box_terminator: y job_terminator: y

Watch for File Re-index, Organize, Purge Generate Report

box_monthly

Date/Time Start File from

Conditions Met job_Fwatch Mainframe

SUCCESS
FAILURE

job_monthly

SUCCESS

TERMINATED Job Dependency

Condition Met

Job Dependency
Condition NOT Met
job_daily Start
job_daily
NOT RUN Date/Time
Date/Time ConditionsMet
Conditions Met SUCCESS

Figure 5-13 • Changing Status using Box Jobs

AutoSys User Guide for UNIX 5-23 ■

 6
Defining AutoSys Jobs Using
the GUI
This chapter describes how to define jobs using the AutoSys graphical
user interface or GUI. It also provides information about creating various
types of AutoSys jobs. It discusses changing and deleting a job and how
to set time dependencies.
Starting the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
GUI Control Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

Job Definition Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

The Job Definition Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Date/Time Options Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Job Definition Advanced Features Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9

Creating a Simple Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10

Creating a File Watcher Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13

Creating a Dependent Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17

Creating a Box Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19

Changing a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21

AutoSys User Guide for UNIX 6-1 ■

■ Defining AutoSys Jobs Using the GUI

Setting Time Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23

Additional Time Setting Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-25

Deleting a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26

Deleting a Box Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27

Specifying One-Time Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27

Setting Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-30

Customizing the Job Definition GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31

Database Connection Time-out Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32
Job Definition Title Bar Text and Icon Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32

■ 6-2 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Starting the GUI

6 Starting the GUI

To start the GUI
} Enter the following command at the UNIX prompt:
autosc &
The GUI Control Panel appears, as shown in Figure 6-1.

Figure 6-1 • GUI Control Panel

6 GUI Control Panel

These are the Control Panel buttons and the actions they perform:

■ Ops Console—Displays the Job Activity Console, used to monitor

AutoSys jobs and alarms.

■ Job Definition—Displays the Job Definition dialog, used to define

AutoSys jobs.

■ Calendars—Displays the Calendar Definition window, used to define

AutoSys run and exclude calendars.

■ Monitor/Browser—Displays the Monitor/Browser dialog, used to

define and run monitors and reports (or browsers).

■ HostScape—Displays the AutoSys/Xpert HostScape window, used for

viewing AutoSys machines (and their jobs) in real-time or simulated
mode.

AutoSys User Guide for UNIX 6-3 ■

■ Defining AutoSys Jobs Using the GUI
Job Definition Dialogs

■ JobScape—Displays the AutoSys/Xpert JobScape window, used for

viewing job progressions (and their dependencies) in real-time or
simulated mode.

■ TimeScape—Displays the AutoSys/Xpert TimeScape window, used for

viewing job progressions (across time) in real-time, real-time with
projection, or simulated mode.

■ Exit—Exits the GUI.

Note • The three AutoSys/Xpert buttons are disabled if you have not
purchased the AutoSys/Xpert product.

6 Job Definition Dialogs

AutoSys provides several dialogs that you can use for defining jobs. You
might use up to three, or as few as one dialog, depending on the
complexity of the job. At the top of each dialog box is its title, such as
“Job Definition.” This chapter is organized around these dialogs.

■ 6-4 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Job Definition Dialogs

6 The Job Definition Dialog

The Job Definition dialog contains fields representing all the basic
information you need to define a job. When you single-click on the Job
Definition button in the Control Panel, the Job Definition dialog shown
in Figure 6-2 appears.

Figure 6-2 • Job Definition Dialog

AutoSys User Guide for UNIX 6-5 ■

■ Defining AutoSys Jobs Using the GUI
Job Definition Dialogs

The buttons at the top of the dialog perform the following actions:

■ Clear—Clears the dialog without affecting the database. Use this

button to clear all fields in the dialog (and in memory).

■ Delete—Deletes the currently displayed job from the database.

■ Save—Stores the currently displayed job in the database, either

modifying a pre-existing job, or creating a new one. It also clears the
dialog in preparation for another job definition.

■ Adv Features—Displays the Job Definition Advanced Features dialog,

which is used for all but the simplest of job definitions.

■ Exit—Closes the Job Definition dialog. If Exit is pressed without first

pressing Save, the latest changes will not be saved.

The fields in the Job Definition dialog are context sensitive based on the
type of job being defined. When you select a Job Type, only the fields
appropriate to that type of job are displayed and activated, and the other
fields are disabled.

In this dialog, there is a special field named “Edit One-Time Overrides?”

which is used to specify that certain job attributes be applied for the very
next run of the job. When the Yes radio button in this field is selected,
only those fields that can be used for overrides are active, and the
remaining fields are disabled.

■ 6-6 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Job Definition Dialogs

6 Date/Time Options Dialog

In the Starting Parameters region (middle section) of the Job Definition
dialog, there is a Date/Time Options button. When you single-click on
this button, it displays the Date/Time Options dialog, as shown in
Figure 6-3.

Figure 6-3 • Date/Time Options Dialog

The buttons at the bottom of the dialog perform the following actions:

■ Calendars—Accesses the Autosys Graphical Calendar facility.

■ Dismiss—Closes the Date/Time Options dialog.

In addition to setting specific date and time starting conditions, at this

dialog you can specify (and search for) any run or exclude calendars that
have been defined for the job. To do this, you use one of the provided
Search buttons.

AutoSys User Guide for UNIX 6-7 ■

■ Defining AutoSys Jobs Using the GUI
Job Definition Dialogs

All entries made in the dialog are maintained in memory after you close
the dialog. They are saved only when you select Save at the Job Definition
dialog.

■ 6-8 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Job Definition Dialogs

6 Job Definition Advanced Features Dialog

When you single-click on the Adv Features control button in the Job
Definition dialog, it displays the Job Definition Advanced Features
dialog, as shown in Figure 6-4.

Figure 6-4 • Job Definition Advanced Features Dialog

AutoSys User Guide for UNIX 6-9 ■

■ Defining AutoSys Jobs Using the GUI
Creating a Simple Command Job

The Job Definition Advanced Features dialog has fields for all the
additional features that can be specified for a job. Many of these fields are
organized by job type, and they only pertain to the type of job on which
you are working.

Note • The External Application field is disabled. It is a placeholder

for future functionality.

These are the control buttons in this dialog:

■ Dismiss—Closes the dialog; any entries made in the dialog are

maintained in memory, so that a subsequent Save will save this
information.

■ Save&Dismiss—Closes the dialog and saves the job, including the

advanced features information to the database.

6 Creating a Simple Command Job

The most basic command job requires only a few fields to be entered in
the Job Definition dialog. To demonstrate this, we’ll walk you through
the process of defining a simple job named “test_run” which has no
starting parameters. When manually started, this job will only echo a
message to standard output.

To create the example job

} In the GUI Control Panel, single-click on the Job Definition button.
This action opens the Job Definition dialog.

To define the example job

1 In the Job Name field, enter the job’s name: test_run

2 In the Job Type field, single-click on the Command radio button.

3 In the Execute on Machine field, enter the name of the machine on

which the command will be executed. You should enter your own
valid, licensed client machine name.

■ 6-10 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Creating a Simple Command Job

4 In the Command to Execute field, enter the command to be executed:

/bin/echo "AUTOSYS install test run"

Your entries in the Job Definition dialog should look like those shown in
Figure 6-5.

AutoSys User Guide for UNIX 6-11 ■

■ Defining AutoSys Jobs Using the GUI
Creating a Simple Command Job

Note • The Owner field for the job defaults to the currently logged on
user—not the user shown in these examples.

Figure 6-5 • Job Definition Dialog for Command Job “test_run”

■ 6-12 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Creating a File Watcher Job

To save the example job

} At the top of the Job Definition dialog, single-click on the Save button.
Leave the Job Definition dialog on your screen to use for the next
example.

6 Creating a File Watcher Job

Next, you will create a File Watcher Job. This job will watch for an end-
of-day transaction file called EOD_trans_file. File Watcher jobs do not
actually execute commands themselves; they are used to signal the arrival
of files, and typically set off the execution of a command job.

Using the Job Definition dialog, follow these steps:

1 In the Job Name field, enter this job name: EOD_watch

2 In the Job Type field, single-click on the File Watcher radio button.

3 In the Execute on Machine field, enter the name of the machine on

which the command will be executed. You should enter your own
valid, licensed client machine name.

4 In the File To Watch For field, enter this file name:

/usr/common/EOD_trans_file
Your entries in the Job Definition dialog should look like those shown in
Figure 6-6.

AutoSys User Guide for UNIX 6-13 ■

■ Defining AutoSys Jobs Using the GUI
Creating a File Watcher Job

Figure 6-6 • Job Definition Dialog for File Watcher Job “EOD_watch”

To set the file watching criteria

} Single-click on the Adv Features button at the top of the Job Definition
dialog.
The Job Definition Advanced Features dialog appears.

At the top-center of the dialog are the File Watching Criteria. In this
region of the dialog, enter the following information:

■ 6-14 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Creating a File Watcher Job

1 In the Time Interval (secs) to Determine Steady State field, enter the
time interval: 60

AutoSys will check for the file’s existence every 60 seconds, and it will
check if the file has grown between checks—if it has not changed in
size, this is called a “steady state.”

2 In the Minimum File Size (in BYTES) field, enter the minimum file
size which should be reached before the file can be considered
complete: 50000

The file must have reached this minimum size, and must have reached
a “steady state” before the file watcher job will complete with a
SUCCESS condition.

3 To save the job and dismiss the Job Definition Advanced Features
dialog, single-click on the Save&Dismiss button.

AutoSys User Guide for UNIX 6-15 ■

■ Defining AutoSys Jobs Using the GUI
Creating a File Watcher Job

The filled-in dialog should look like the one shown in Figure 6-7.

Figure 6-7 • Job Definition Advanced Features Dialog - File Watcher Job

■ 6-16 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Creating a Dependent Command Job

6 Creating a Dependent Command Job

Now, you will create a command job that is dependent on the successful
completion of the file watcher job you just created. The only difference
between this command job and the simple command job you created
earlier, is that this one will be dependent on another job.

Using the Job Definition dialog, follow these steps:

1 In the Job Name field, enter the job’s name: EOD_post

2 In the Job Type field, single-click on the Command button.

3 In the Starting Condition field, enter the only starting condition, in

this case the successful completion of the file watcher job:
success(EOD_watch)
4 In the Execute on Machine field, enter the name of the machine on
which the file watcher will run. You should enter your own valid,
licensed client machine name.

5 In the Command to Execute field, enter the command that is to run

when the file watcher completes, like this:
$HOME/post
The environment variable $HOME means that the post executable is
located in the job owner’s home directory.

The filled-in Job Definition dialog should look like the one shown in
Figure 6-8.

Note • The job’s execution environment is determined exclusively by

the profile, which is “sourced” immediately before the job is started.
By default, the file /etc/auto.profile is sourced. This can be
overridden by specifying another profile in the File to Define Job
Environment field in the Job Definition Advanced Features dialog.

For information on the profile job attribute, see Chapter 2, JIL/GUI Job
Definitions in the AutoSys Reference Guide for UNIX.

AutoSys User Guide for UNIX 6-17 ■

■ Defining AutoSys Jobs Using the GUI
Creating a Dependent Command Job

Figure 6-8 • Job Definition Dialog—Dependent Command Job

To save the job

} Single-click on the Save button at the top of the Job Definition dialog.

■ 6-18 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Creating a Box Job

6 Creating a Box Job

Assume that you want to schedule a group of jobs to all start running
once the file watcher completes successfully. Rather than make each job
dependent on the file watcher, you can create a box that is dependent on
the file watcher, and place all of the jobs in the box. (For detailed
information on box jobs, see Chapter 5, Box Job Logic.)

Now you will create a box, then change the job you just created to put it
in the box, and then make it no longer individually dependent on the file
watcher.

In the Job Definition dialog, enter the following information:

1 In the Job Name field, enter the job name: EOD_box

2 In the Job Type field, single-click on the Box button.

When you select the box job type, the lowest section of the Job
Definition dialog changes from “Command & File Watch
Information” to “Box Completion Conditions.”

3 In the Starting Condition field, enter the only starting condition, in

this case the successful completion of the file watcher job:
success(EOD_watch)

To save the job

} Single-click on the Save button at the top of the Job Definition dialog.
The filled-in dialog should look like the one shown in Figure 6-9.

AutoSys User Guide for UNIX 6-19 ■

■ Defining AutoSys Jobs Using the GUI
Creating a Box Job

Figure 6-9 • Job Definition Dialog—Box Job

■ 6-20 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Changing a Job

6 Changing a Job
This exercise will change an existing job. You should make sure a job is
not running before you modify or delete it.

In this exercise, you will place the “EOD_post” job, created previously, in
the newly created box. To load an existing job into the Job Definition
dialog, you can either enter its name explicitly in the Job Name field and
click the Search button, or you can use the Search Facility. For this
exercise, you will use the search facility. You can enter some portion of
the job name, followed by the “%” wildcard character. The “%” character
will match any string of one or more characters in the job name. For
instance, “%box%” will match any job name with the string “box”
anywhere in the name.

To use the search facility

1 In the Job Name field, enter this: EOD%

2 Single-click on the Search button below the Job Name field.

A Selection List Box similar to the one shown in Figure 6-10 appears
containing all the jobs currently defined in the database that start with
the string “EOD”. (The list box shown below may not match yours
exactly, since you can have other jobs defined.)

3 Typing just the % wildcard character will display all the jobs defined
in the database.

AutoSys User Guide for UNIX 6-21 ■

■ Defining AutoSys Jobs Using the GUI
Changing a Job

Figure 6-10 • Selection List Box

4 Double-click on the desired job’s name, in this case, “EOD_post”.

This will automatically dismiss the Selection List Box and display the
requested job in the Job Definition dialog. If the job you wanted was
not in the list, you could click on the Cancel button to dismiss the
Selection List Box without making a selection.

To place the “EOD_post” job in the box

1 In the Name of Box this Job is IN field, enter the box name: EOD_Box

This field also has a search facility, which works the same as the Job
Name search facility, complete with wildcarding using the “%”
character.

2 In the Starting Condition field, delete the string “success

(EOD_watch)”. This starting condition has been assigned to
“EOD_Box”. Now that this job is in a box, it will inherit the starting
condition of the box.

3 Click on the Save button at the top of the dialog to save the changes.

■ 6-22 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Setting Time Dependencies

6 Setting Time Dependencies

The “test_run” job you created at the beginning of the chapter will only
be executed if it is started manually.

To set the job to run on certain days at certain times, such as 10:00
a.m. and 2:00 p.m. on Mondays, Wednesdays, and Fridays
1 In the Job Name field, enter the job name to be modified: test_run

2 Single-click the Search button to display the specified job.

3 In the Starting Parameters region of the Job Definition dialog, locate

the Is the Start Date/Time Dependent? field and single-click on the Yes
button.

4 Single-click on the Date/Time Options button.

5 The Date/Time Options dialog appears, as shown in Figure 6-11.

AutoSys User Guide for UNIX 6-23 ■

■ Defining AutoSys Jobs Using the GUI
Setting Time Dependencies

Figure 6-11 • Date/Time Options Dialog—Time Dependencies

6 In the Date region of the dialog, select the days on which the job is to
run. In this case, single-click on the Monday, Wednesday, and Friday
buttons.

These buttons can be toggled on and off and are not mutually
exclusive.

7 In the Time region of the dialog, select the time(s) when the job is to
be run, in this case, click on the Time(s) of day field, then enter:
10:00, 14:00
Unlike in JIL, the times do not have to be enclosed in quotes when
they are entered in the GUI.

■ 6-24 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Setting Time Dependencies

8 To close the Date/Time Options dialog, single-click on the Dismiss

button.

The information is retained in memory until the job is either saved to

the database or cleared.

To save the new start date/time information for this job in the
database
} Single-click the Save button in the Job Definition dialog.

6 Additional Time Setting Features

You can base the time settings for a job on a specific time zone. To do
this, you enter a valid time zone in the Time Zone field in the Job
Definition Advanced Features dialog. For details on specifying a time
zone in a job definition, see timezone in Chapter 2, JIL/GUI Job Definitions
in the AutoSys Reference Guide for UNIX.

To have a job run at specific minutes past every hour, as opposed to

specific times of day, specify the minutes past every hour in the Every
Hour at field.

If you want to run a job every day, rather than only on specific days, you
single-click on the Every Day button instead of the individual buttons for
each day.

If you want to schedule a job for specific dates, rather than specific days
of the week, you can specify a custom calendar name in the “Run on Days
in Calendar” field. If the custom calendar does not already exist, create it
by single-clicking the Calendars button, which displays the Graphical
Calendar Facility.

Alternatively, you can specify a custom calendar defining days on which

the job must not run. You specify this calendar in the “Do NOT Run on
Days in Calendar (Exclude)” field.

AutoSys User Guide for UNIX 6-25 ■

■ Defining AutoSys Jobs Using the GUI
Deleting a Job

To view the calendars defined in AutoSys, use the Search buttons beneath
each of these fields. These buttons display a list box from which you can
select a pre-defined calendar. To define a calendar “on the fly,” single-
click the Calendars button, which displays the Graphical Calendar
Facility.

6 Deleting a Job
Now you will delete the “test_run” job, which you just modified. You
delete all jobs, regardless of type, in exactly the same way. To delete a job,
you can either enter its name explicitly in the Job Name field, or use the
search facility. In this final exercise, you will use the search facility. You
can enter some portion of the job name, followed by the “%” character,
or just enter the “%” character alone, for a global search.

To delete a job
1 In the Job Name field, enter: %

2 Single-click on the Search button to initiate the search.

A Selection List Box appears, allowing you to select the desired job.

3 Double-click on the desired job’s name, in this case, “test_run”. This

will automatically dismiss the Selection List Box and display the
requested job in the Job Definition dialog.

4 Verify that the “test_job” job is displayed in the Job Definition dialog.

Note • No confirmation dialog appears when you delete a job

using the GUI, so ensure that you are deleting the right job.

5 To delete the job from the database, at the top of the Job Definition
dialog, single-click on the Delete button.

■ 6-26 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Specifying One-Time Job Overrides

6 Deleting a Box Job

When using the GUI to delete a box job, AutoSys will delete the box, and
will recursively delete all jobs within that box.

Using the GUI, there currently is no way to delete just the box itself and
not its contents.

However, with JIL, you can use the delete_job sub-command to delete
the box while leaving its contents intact (see Deleting a Job in Chapter 7,
Defining Jobs Using JIL).

The GUI includes more fields than are discussed in this chapter. All fields
are discussed in detail in Chapter 2, JIL/GUI Job Definitions in the AutoSys
Reference Guide for UNIX.

6 Specifying One-Time Job Overrides

Using the GUI, you can specify a job override for the next run of a
particular job; that is, the next time a job runs, you can change its
behavior. When using the GUI to specify job overrides, you enter new
values into the GUI fields, or enter NULL in a GUI field to turn off a
value.

Job overrides are applied for the next run of the job only. If an AutoSys
RESTART event is generated because of system problems, AutoSys will re-
issue a job override until the job actually runs once, or until the
maximum number of retries limit is met. After this, the override is
discarded.

AutoSys User Guide for UNIX 6-27 ■

■ Defining AutoSys Jobs Using the GUI
Specifying One-Time Job Overrides

Note • The maximum number of job restarts after system or network

failures is specified in the MaxRestartTrys parameter in the AutoSys
configuration file.

One-time job overrides will be applied to jobs restarted due to system

problems, but will not be applied to jobs restarted because of
application failures. System problems include such things as machine
unavailability, media failures, or insufficient disk space. Application
failures include such things as inability to read or write a file,
command not found, exit status greater than the defined maximum
exit status for success, or various syntax errors.

You cannot submit an override if it results in an invalid job definition.

For example, if a job definition has only one starting condition,
start_times, you cannot set the start_times attribute to NULL because
removing the start condition makes the job definition invalid (no start
time could be calculated).

The GUI dialogs, regions, and fields that you can use in a job override
specification (definition) are listed in Table 6-1.

Table 6-1 • Dialogs, Regions, and Fields for Job Overrides

Dialog Region Field

Job Definition Job Definition ■ Edit OneTime Over-

Rides?

Starting Parameters ■ Starting Condition

■ Is Start Date/Time
Dependent?

Command & File ■ Execute on Machine

Watch Information
■ Command to Execute
■ File To Watch for

■ 6-28 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Specifying One-Time Job Overrides

Table 6-1 • Dialogs, Regions, and Fields for Job Overrides (continued)

Dialog Region Field

Advanced Alarms ■ Minimum Run Time

Features
■ Maximum Run Time

File Watching ■ Time Interval (secs) to

Criteria Determine Steady State
■ Minimum File Size (in
BYTES)

Terminators ■ Terminate this job

Mins after starting

Command Information ■ Job Environment

Profile
■ File to Redirect to
Standard Input
■ File to Redirect to
Standard Output
■ File to Redirect
Standard Error
■ External Application

Misc. Features ■ Number of Times to

Restart this Job after a
FAILURE
■ Delete Job hours after
Completion
■ AutoHold On?

AutoSys User Guide for UNIX 6-29 ■

■ Defining AutoSys Jobs Using the GUI
Specifying One-Time Job Overrides

Table 6-1 • Dialogs, Regions, and Fields for Job Overrides (continued)

Dialog Region Field

Date/Time DATE ■ (all date settings)

Options
■ Run on Days in
Calendar
■ Do NOT Run on Days
in Calendar (Exclude)

TIME ■ (all time settings)

■ Run Window

6 Setting Job Overrides

To set job overrides
1 At the Job Definition dialog, enter the name of the desired job and
single-click the Search button.

2 In the Edit OneTime Over-Rides? field, single-click on the Yes button.

Now, the dialog is in job override mode, and only the available fields
for specifying job overrides are active.

3 At the appropriate dialogs and fields, specify the overrides you want.

To save the job overrides

} Single-click on the Save button at the top of the Job Definition dialog.
This action returns you to job definition mode.

To delete the job overrides

1 At the Job Definition dialog, enter the name of the job for which you
want to delete the overrides and single-click the Search button.

2 In the Edit OneTime Over-Rides? field, single-click on the Yes button.

■ 6-30 AutoSys User Guide for UNIX

 Defining AutoSys Jobs Using the GUI ■
Customizing the Job Definition GUI

3 Single-click on the Delete button. This action deletes the job

overrides.

6 Customizing the Job Definition GUI

There is a set of X resources you can use to customize the appearance and
behavior of the Job Definition GUI. In particular, these resources allow
you to control:

■ The time interval after which the Monitor/Browser GUI will drop the
connection to the database.

■ The Monitor/Browse GUI icon text and the Monitor/Browse title bar
text.

Descriptions of the resources which can be customized are given below.

All of these can be set by modifying the X resource file Autosc. The X
resources files reside in the local app-defaults directory, which varies
across platforms. It is usually in /usr/lib/X11/app-defaults or /usr/
openwin/lib/app-defaults. If you are not sure which directory these files
are in, ask your system administrator.

Individual users may have their own copy of the X resources files in their
$HOME directory, which will take precedence over the app-defaults files.

For most operating systems, if you are exporting the display to another
machine you must edit the appropriate files in the app-defaults
directory on the local machine.

For Solaris, you must edit the files in both the /usr/lib/X11/
app-defaults and /usr/openwin/lib/app-defaults directories. The files
in /usr/lib/X11/app-defaults control the resources when you export the
display.

AutoSys User Guide for UNIX 6-31 ■

■ Defining AutoSys Jobs Using the GUI
Customizing the Job Definition GUI

6 Database Connection Time-out Interval

The following resource controls the time interval after which the Job
Definition GUI will drop the connection to the database.
! TimeOut to drop DB connections (in minutes)
*DBDropTime: 400

If DBDropTime is set to 0, the connection is dropped immediately after the

database query has completed. A value greater than or equal to 5 means
that the GUI will automatically drop all database connections if the
database has not been accessed in the last DBDropTime minutes. (Values
of 1 to 4 are invalid). A new database connection will subsequently be
established when required. If DBDropTime is greater than 360, the
connection to the database is maintained until the GUI screens are
exited.

6 Job Definition Title Bar Text and Icon Text

The following resources specify the title bar text and the icon text. By
default the title bar text is “Job Definition” and the icon text is “JobDef”.
Autosc.shellTitleJobDef:
Autosc.iconTitleJobDef:

Note • When changing icon text, be sure the length of the new text
string does not exceed the recommended maximum length for icon
title text for your windowing system. Some window managers can
display long icon text strings, while others will truncate them. Ensure
the text string you specify for your icons displays appropriately. Also,
some window managers allow you to change the size of icons and
icon text font.

■ 6-32 AutoSys User Guide for UNIX

 7
Defining Jobs Using JIL
This chapter describes how to define jobs using the AutoSys Job
Information Language or JIL. It also provides information about creating
various types of AutoSys jobs. It discusses changing and deleting a job,
and how to set time dependencies. An example JIL script is provided.
ob Information Language (JIL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
JIL Syntax Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
JIL Sub-commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Submitting Job Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6
Running JIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6

Creating a Simple Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7

Creating a File Watcher Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8

Creating a Dependent Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9

Creating a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10

Changing a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11

Setting Time Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12

Additional Time Setting Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12

AutoSys User Guide for UNIX 7-1 ■

■ Defining Jobs Using JIL

Deleting a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13

Deleting a Box Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14

Specifying One-Time Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14

Setting Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-15

Example JIL Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16

■ 7-2 AutoSys User Guide for UNIX

 Defining Jobs Using JIL ■
Job Information Language (JIL)

7 Job Information Language (JIL)

Job Information Language JIL) is a scripting language which provides a
way to specify how AutoSys jobs should behave. JIL scripts contain one
or more JIL sub-commands and one or more attribute statements; these
elements constitute a job definition.

Note • In this chapter, all keywords shown in bold fixed font are to be
typed exactly as shown. All words shown in italic are variables that
you specify.

7 JIL Syntax Rules

When writing a JIL script, you must follow the syntax rules listed below.

Rule 1
Each sub-command uses the following form:
sub_command: job_name
where:
sub_command
Is one of the sub-commands listed in Table 7-1.
job_name

Is the user-specified name of the job to be acted upon.

AutoSys User Guide for UNIX 7-3 ■

■ Defining Jobs Using JIL
Job Information Language (JIL)

Rule 2
Each sub-command may be followed by one or more attribute
statements. These statements may occur in any order, and are applied to
the job specified in the preceding sub-command. A subsequent
sub-command begins a new set of attributes for a different job. The
attribute statements have the following form:
attribute_keyword: value

where:
attribute_keyword

Is one of the legal JIL attributes.

value
Is the setting to be applied to the attribute.

Rule 3
Multiple attribute statements can be entered on the same line, but the
lines must be separated by at least one space.

Rule 4
A box must be defined before the jobs can be placed in it.

Rule 5
Legal value settings can include any of the following characters: upper-
and lowercase letters, hyphens, underscores, numbers, colons (if the
colon is escaped with quotes or a preceding backslash), and the special
character “@”.

Rule 6
Any colons used in an attribute statement’s value setting must be
escaped, because JIL parses on the combination of keyword followed by
a colon. For example, to specify the time to start a job, specify 10:00. The
colon may also be escaped with a preceding backslash “\”, as in 10\:00.

■ 7-4 AutoSys User Guide for UNIX

 Defining Jobs Using JIL ■
Job Information Language (JIL)

Rule 7
Comments are indicated using one of the following two methods:

■ An entire line can be commented by placing a pound sign “#” in the

first column.
Or
■ The C programming syntax used for beginning a comment with “/*”
and ending it with “*/” may be used; this allows comments to span
multiple lines. The following is an example:
/* this is a comment */

7 JIL Sub-commands
JIL sub-commands are used to create, modify, override, or delete a job
definition. These sub-commands are listed in Table 7-1.
Table 7-1 • Primary JIL Sub-commands for Defining Jobs

Sub-command Action

insert_job Add a new job to AutoSys.

update_job Edit fields on an existing job.
delete_job Delete an existing job from the AutoSys
database.
delete_box Delete an existing box job, and recursively delete
all the jobs which are contained in the box.
override_job Apply overrides on indicated job attributes for
the next run of this job.

AutoSys User Guide for UNIX 7-5 ■

■ Defining Jobs Using JIL
Job Information Language (JIL)

7 Submitting Job Definitions

As stated earlier, a completed JIL script is called a job definition. This job
definition must be submitted to the AutoSys database before the job it
defines can be run. You can submit a job to the AutoSys database using
one of the following methods:

■ Submit it by redirecting a JIL script file to the jil command, for

example:
jil < my_jil_script
■ Interactively submit it by issuing the jil command and pressing
Return. Then entering JIL statements at the provided jil>> prompts.
To exit interactive mode, enter “exit” at the prompt, or press
<Control+d>.

Both of these methods are analogous to saving a job definition in the

GUI, using the Job Definition dialog

To specify the instance of AutoSys to which definitions are to be sent and

applied, you can use the -S autoserv_instance argument to the jil
command. For single instance AutoSys environments, the command will
default to the only available AutoSys instance.

For the jil command to work properly, the correct AutoSys environment
variables must be assigned. For more information about these variables,
see the AutoSys Installation and Getting Started Guide for UNIX. For more
information about the jil command, see its definition in Chapter 1,
AutoSys Commands in the AutoSys Reference Guide for UNIX.

7 Running JIL
After a job definition has been submitted to the AutoSys database, it will
be started according to the starting parameters specified in its JIL script.
That is, the Event Processor will continually poll the database and when
it determines that the starting parameters have been met, it will run the
job.

■ 7-6 AutoSys User Guide for UNIX

 Defining Jobs Using JIL ■
Creating a Simple Command Job

If a JIL script does not specify any starting parameters for a job, the job
will not be started automatically by the Event Processor; it will start only
if you issue the sendevent command. For example, assume a job named
“test_install” has no starting parameters specified in its JIL script. The
only way to start it would be to issue the following command:
sendevent -E STARTJOB -J test_install

This command tells the Event Processor to start the job named
“test_install”.

For more information about the sendevent command, see its definition
in Chapter 1, AutoSys Commands in the AutoSys Reference Guide for UNIX.

7 Creating a Simple Command Job

To create the most basic Command Job, you only need to specify a few
attributes. For example, the JIL script required to define a simple
Command Job named “test_run” is given below:
insert_job: test_run
job_type: c /*(optional, it is the default) */
machine: tibet
command: /bin/touch /tmp/test_run.out

This JIL script instructs AutoSys:

■ To add a new job named “test_run”.

■ That the new job is a command job.

■ To run the job on the client machine named “tibet”.

■ To execute the UNIX /bin/touch command on the file named /tmp/

test_run.out.

AutoSys User Guide for UNIX 7-7 ■

■ Defining Jobs Using JIL
Creating a File Watcher Job

7 Creating a File Watcher Job

File watcher jobs do not execute commands themselves; they are used to
signal the arrival of files, and typically set off the execution of a command
job. For example, the JIL script required to define a file watcher job
named “EOD_watch” is given below:
insert_job: EOD_watch
job_type: f
machine: tibet
watch_file: /tmp/EOD_trans_file
watch_interval: 60
watch_file_min_size: 50000

This JIL script instructs AutoSys:

■ To add a new job named “EOD_watch”.

■ That the new job will be a file watcher job.

■ To run the job on the client machine named “tibet”.

■ To watch for an end of day transaction file named EOD_trans_file in

the /tmp directory.

■ Check the file every 60 seconds.

■ Determine if the file has reached the minimum file size of 50,000
bytes.

Until the minimum file size of 50,000 bytes has been reached, the file
won’t be considered by AutoSys as “complete.” When the file reaches this
minimum size and does not change between check intervals (60 seconds
in this example) it is considered compslete (also known as “steady
state”). When this occurs, the file watcher job will end with a SUCCESS
condition.

■ 7-8 AutoSys User Guide for UNIX

 Defining Jobs Using JIL ■
Creating a Dependent Command Job

7 Creating a Dependent Command Job

Command jobs can be dependent on the successful completion of other
jobs, such as the file watcher job created in the previous section. The only
difference between a dependent command job and a simple command
job is its dependency on another job.

For example, the JIL script required to define a dependent command job
named “EOD_post” is given below. “EOD_post” will be specified to run
on the same machine as the file watcher job created in the previous
section, since it presumably will need the watched-for file to process.
And, it will be dependent on the success of the file watcher job.
insert_job: EOD_post
job_type: c
machine: tibet
condition: success(EOD_watch)
command: $HOME/post

This JIL script instructs AutoSys:

■ To add a new job named “EOD_post”.

■ That the new job will be a command job.

■ To run the job on the client machine named “tibet”.

■ To run the job only if the file watcher job named “EOD_watch”
completes with a SUCCESS status.

■ To source the /etc/auto.profile file (AutoSys sources this file by

default), and then, to run the job named “post” located in the job
owner’s home directory.

Note • The job’s execution environment is determined exclusively by

the profile, which is sourced immediately before the job is started. By
default, the file /etc/auto.profile, on the client machine, will be
sourced. This can be overridden by specifying another profile by using
the profile attribute.

AutoSys User Guide for UNIX 7-9 ■

■ Defining Jobs Using JIL
Creating a Box

For information on the profile job attribute, see its entry in Chapter 2,
JIL/GUI Job Definitions in the AutoSys Reference Guide for UNIX.

7 Creating a Box
Box jobs are a convenient way to start multiple jobs. When you put jobs
in a box, you only have to start a single job (the box) in order for all the
jobs in the box to start running.

Assume you want to schedule a group of jobs to all start running once the
file watcher completes successfully. Rather than make each job
dependent on the file watcher, you can create a box that is dependent on
the file Watcher, and place all of the jobs in the box.

Now you will create a box, then change the job you just created to put it
in the box, and then make it no longer individually dependent on the file
watcher. The JIL script required to define a box job named “EOD_box” is
given below:
insert_job: EOD_box
job_type: b
condition: success(EOD_watch)

This JIL script instructs AutoSys:

■ To add a new job named “EOD_box”.

■ That the new job will be a box job.

■ To run the job only if the file watcher job named “EOD_watch”
completes with a SUCCESS status.

For information on box jobs, see Chapter 5, Box Job Logic.

■ 7-10 AutoSys User Guide for UNIX

 Defining Jobs Using JIL ■
Changing a Job

7 Changing a Job
To place an existing job in a box, you need to change the “EOD_post”
command job that was created above. You will place the “EOD_post” job
in the newly created box.

You should make sure a job is not running before you modify or delete it.

To change a job, you can either use the update_job sub-command, or you
can delete the job definition, using the delete_job sub-command, then
redefine the job using the insert_job sub-command. The latter scenario
is particularly useful when many non-default attributes have been
specified, and you want to “unset” them rather than “reset” them; in
other words, you want to de-activate them. However, you’ll have to re-
specify any of the attributes that need to remain the same.

So, in the example below, you’ll use the update method. The JIL script
required to change the “EOD-post” job and to put it in the “EOD_box”
is given below:
update_job: EOD_post
condition: NULL
box_name: EOD_box

This JIL script instructs AutoSys:

■ To update the job named “EOD_post”.

■ Remove the starting condition from the job definition, because the
job will inherit the starting condition of the box in which it is placed.

■ Put the job named “EOD_post” in the box named “EOD_box”.

The “EOD_post” command job is now in the “EOD_box” box job, and
has inherited the box’s starting parameters.

AutoSys User Guide for UNIX 7-11 ■

■ Defining Jobs Using JIL
Setting Time Dependencies

7 Setting Time Dependencies

The “test_run” job you specified at the beginning of the chapter has no
starting conditions. Therefore, it will only run if it is started using the
sendevent command. To set the job 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 would modify the job using this 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 AutoSys:

■ To update the job named “test_run”.

■ Activate the conditions based on date.

■ Set the job to run on Mondays, Wednesdays, and Fridays.

■ On each of these three days, start the job at 10:00 a.m. and 2:00 p.m.

The times shown in the script above are quoted, since they contain a
colon. They could also have been escaped by using backslashes, as shown
below:
start_times: 10\:00, 14\:00

7 Additional Time Setting Features

If you wanted the time settings for the job to be based on a specific time
zone, you would use the timezone attribute. If you specify a time zone
that includes a colon, you must quote the time zone name like this:
timezone: "IST-5:30"
If you do not quote a time zone that contains a colon, the colon will be
interpreted as a delimiter, producing unexpected results.

■ 7-12 AutoSys User Guide for UNIX

 Defining Jobs Using JIL ■
Deleting a Job

If you had wanted to run the job every day, rather than only on specific
days, you could have specified the all value, instead of listing the
individual day values. Or, if you had wanted to schedule the job for
specific dates, rather than specific days of the week, you could have
specified a custom calendar. First, you would have had to define the
calendar, using the Graphical Calendar Facility, or the autocal_asc
command. Then, you would specify the calendar name, “weekday_cal”,
using the following JIL statement:
run_calendar: weekday_cal
Alternatively, you could have specified a custom calendar specifying the
days on which the job was not to be run, “holiday_cal”, using the
following JIL statement:
exclude_calendar: holiday_cal

If you wanted the job to run at specific times every hour, as opposed to
specific times of day, the minutes past every hour could have been
specified. For example, to run a job at a quarter after and a quarter before
each hour, use the following JIL statement:
start_mins: 15, 45

7 Deleting a Job
Now you will delete the “test_run” job, which you specified at the
beginning of this chapter. To delete the “test_run” job, enter the
following JIL sub-command:
delete_job: test_run
The delete_job sub-command checks the job_cond table and notifies
you if dependent conditions for the deleted job exist. This functionality
only works when JIL is in job verification mode (which is the default
mode).

AutoSys User Guide for UNIX 7-13 ■

■ Defining Jobs Using JIL
Specifying One-Time Job Overrides

7 Deleting a Box Job

To delete a box, and recursively delete every job in that box
} Use the delete_box sub-command, like this:
delete_box: EOD_box

To delete a box, but leave its contents intact

} Use the delete_job sub-command on the box, like this:
delete_job: EOD_box
Using JIL, there are a number of other attributes which you can configure.
These attributes are described in detail in Chapter 2, JIL/GUI Job
Definitions in the AutoSys Reference Guide for UNIX. This reference chapter
provides complete information on all job attributes specified using JIL.

7 Specifying One-Time Job Overrides

Using JIL, you can specify a job override for the next run of a particular
job. In other words, the next time a job runs, you can change its behavior.
Job overrides are applied only once. If an AutoSys RESTART event is
generated because of system problems, AutoSys will re-issue a job
override until the job actually runs once, or until the maximum number
of retries limit is met. After this, the override is discarded.

Note • The maximum number of job restarts after system or network

failures is specified in the MaxRestartTrys parameter in the AutoSys
configuration file.

■ 7-14 AutoSys User Guide for UNIX

 Defining Jobs Using JIL ■
Specifying One-Time Job Overrides

Note • One-time job overrides will be applied to jobs restarted due to

system problems, but will not be applied to jobs restarted because of
application failures. System problems include such things as machine
unavailability, media failures, or insufficient disk space. Application
failures include such things as inability to read or write a file,
command not found, exit status greater than the defined maximum
exit status for success, or various syntax errors.

The following attributes can be modified in a job override:

auto_hold min_run_alarm std_in_file

command n_retrys std_out_file

condition profile term_run_time

date_conditions run_calendar watch_file

days_of_week run_window watch_file_min_size

exclude_calendar start_mins watch_interval

machine start_times

max_run_alarm std_err_file

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 allow you to set the start_times attribute to NULL because
removing the start condition makes the job definition invalid (no start
time could be calculated).

7 Setting Job Overrides

To set job overrides, you use the override_job sub-command; you only
need to specify those attributes that you want to override. Using this
command, you can also temporarily delete a job attribute.

AutoSys User Guide for UNIX 7-15 ■

■ Defining Jobs Using JIL
Example JIL Script

For example, if you wanted to run a job named “RunData” with no

conditions (where some had been previously specified) and you wanted
to output the results to a different output file, you would enter a JIL script
like this:
override_job: RunData
condition: NULL
std_out_file: /usr/out/run.special

To cancel the job overrides specified in the script above, you would enter
the following JIL script:
override_job: RunData delete

Note • Once you have submitted a JIL script to the AutoSys database,
you cannot view the JIL script and edit a job override. If you want to
change the override values, you must submit another JIL script with
new values, or use the GUI. However, the original override (i.e., the
first over_num) remains stored in the “overjob” table in the AutoSys
database.

7 Example JIL Script

The following is a full example of an AutoSys JIL script. It incorporates
the creation and use of a command job, a file watcher job, and a box job.
This is the processing “scenario”:

■ A file named /download/mainframe/sales.raw is expected to arrive

from the mainframe sometime after 2:00 a.m.

■ When the file arrives, it is processed by the command file named

filter_mainframe_info, and the results are placed in the file named /
download/mainframe/sales.sql.

■ When the above functions are completed, the file named /download/
mainframe/sales.sql (containing SQL statements) is executed.

■ 7-16 AutoSys User Guide for UNIX

 Defining Jobs Using JIL ■
Example JIL Script

# Example of Jobs
insert_job: Nightly_Download
job_type: b
date_conditions: yes
days_of_week: all
start_times: "02:00"
insert_job: Watch_4_file
job_type: f
box_name: Nightly_Download
watch_file: /download/mainframe/sales.raw
machine: gateway
insert_job: filter_data
job_type: c
box_name: Nightly_Download
condition: success(Watch_4_file)
command: filter_mainframe_info
machine: gateway
std_in_file: /download/mainframe/sales.raw
std_out_file: /download/mainframe/sales.sql
std_err_file: /log/filter_mainframe_info.err
insert_job: update_DBMS
job_type: c
box_name: Nightly_Download
condition: success(filter_data)
machine: gateway
command: isql -U mutt -P jeff
std_in_file: /download/mainframe/sales.sql
An example of the output generated by the autorep command for the
above job definition is provided in the Examples section for the autorep
command in Chapter 1, AutoSys Commands of the AutoSys Reference Guide
for UNIX.

AutoSys User Guide for UNIX 7-17 ■

 8
The Graphical Calendar
Facility
This chapter describes the AutoSys Graphical Calendar Facility and how
to use it to create, view, and maintain AutoSys calendars. It also describes
how to preview a calendar before applying its dates and how to apply
custom rules to a calendar.
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3

Scheduling Jobs with Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4

Starting the Calendar Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5

Calendar Facility Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5

Calendar Definition Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6

Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Calendar Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Navigation Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12
Creating a Simple Calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14
Dates Prior to Today’s Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15

Calendar Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16

AutoSys User Guide for UNIX 8-1 ■

■ The Graphical Calendar Facility

Term Calendar Rule Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17

Rule Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18
Examples of Date Selection Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20
Rescheduling Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22
Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24

Term Calendar Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-25

Combining Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27

Printing Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28

Import/Export File Name Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28

Importing Calendar Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28
Exporting Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-30

Customizing the Calendar Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-31

Font Selection Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-32
Object Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-33
Date Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-34
Window Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-34
Print Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-35
Calendar Title bar Text and Icon Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-35

■ 8-2 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Introduction

8 Introduction
An AutoSys calendar is simply a collection of dates grouped as a single
entity. The Calendar Facility lets you define and maintain AutoSys
calendars using a point and click approach on graphical displays of a
conventional calendar. Once these dates are defined in a calendar, you
can use the calendar to schedule jobs. In the job definition, you can
specify that a job start (or not start) on the dates defined in a calendar.
Calendars do not in themselves convey any rules about when a job
should or should not start; this meaning is assigned exclusively through
the job definition.

The Calendar Facility lets you:

■ Define calendars.

■ Apply custom rules to a calendar, such as the “first weekday of every

month,” rather than selecting the individual dates by hand.

■ Block out certain dates, such as holidays, when editing calendars.

■ Select options that will automatically reschedule conflicting dates

when applying a rule. A “conflicted” date is a date that is blocked out
but also meets the qualifications of the rule being applied. A number
of alternatives for rescheduling are provided.

■ Build a new calendar by overlaying multiple, pre-existing calendars,

and allowing you to further customize the new calendar manually.

■ Preview a calendar before applying it to another calendar.

■ Import and export text definitions for calendars.

Note • There is a command-line based calendar editor utility. It is

called autocal_asc.

AutoSys User Guide for UNIX 8-3 ■

■ The Graphical Calendar Facility
Scheduling Jobs with Calendars

8 Scheduling Jobs with Calendars

In the job definition, use one of the following methods to apply a
calendar:

■ With JIL, enter a calendar name in the run_calendar or

exclude_calendar attribute.

■ In the Job Definition Date/Time Options dialog, enter a calendar

name in the Run on Days in Calendar field or the Do NOT Run on
Days in Calendar (Exclude) field.

For example, you could create a calendar called “holidays” containing the
dates of all corporate holidays. For jobs that you want to start on
holidays, you would define this using the attribute:
run_calendar: holidays

For jobs that you do not want to start on holidays, you would define this
using the attribute:
exclude_calendar: holidays

Jobs scheduled with the run_calendar attribute are scheduled to start on

every day specified in the calendar, at the times specified in the calendar
or in the start_times or start_mins attribute. If present in the job
definition, the start_times or start_mins attribute overrides the times
specified in a run calendar. If no start time is specified, jobs scheduled by
a calendar start at midnight, by default.

Note • Times can be assigned to calendars only when using the

command-line calendar definition tool, autocal_asc.

Jobs scheduled with the run_calendar attribute are scheduled on the next
available date from that calendar. Dates previous to the current date are
ignored.

■ 8-4 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Starting the Calendar Facility

Jobs scheduled with the exclude_calendar attribute can make use of

other start conditions in the job definition. In this case, AutoSys evaluates
the start conditions and, if they are true, checks if the date is set in the
exclude_calendar. If it is in the exclude_calendar, the job will not be
started, and its status will be changed to INACTIVE.

For more details on these job attributes, see their reference pages in
Chapter 2, JIL/GUI Job Definitions in the AutoSys Reference Guide for UNIX.

8 Starting the Calendar Facility

To start the Calendar Facility
} Single-click on the Calendars button in the GUI Control Panel.
Or
} Enter the following command at the UNIX prompt:
autocal &
The Calendar Definition window appears, as shown in Figure 8-1.

8 Calendar Facility Screens

The Calendar Facility consists of the following primary screens:

Calendar Definition This window is used to define a calendar and

window specify the dates the calendar should include. It
also provides access to all other calendar
functions and screens.

Calendar Selection This dialog is used to select a pre-defined

dialog calendar to view, modify, or delete.

Term Calendar Rule This dialog is used to specify a rule to apply to the
dialog calendar currently being created or modified.

AutoSys User Guide for UNIX 8-5 ■

■ The Graphical Calendar Facility
Calendar Definition Window

Term Calendar This window is used to preview a pre-existing

Viewer window calendar before applying its dates to the calendar
currently being created or modified. It can also be
used to browse calendars that have already been
defined.

Import/Export File This dialog is used to specify a calendar text file

Name dialog (ASCII format) to import from or export to.

8 Calendar Definition Window

The first screen that displays when the Calendar Facility starts up is the
Calendar Definition window (shown in Figure 8-1).

Figure 8-1 • Calendar Definition Window

■ 8-6 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Calendar Definition Window

The Calendar Definition Window is divided into the following regions:

Menu Bar At the top of the window.

Calendar Display At the center of the window.

Navigation and Legend Controls At the right of the window.

8 Menu Bar
At the top of the Calendar Definition window is the menu bar,
containing four pull-down menus: File, Edit, Tools, and Options.

File Menu
The File menu contains the following options:

New Displays the New Calendar Name dialog for

specifying a name for a new calendar to be created.

Open Displays the Calendar Selection dialog for choosing

an existing calendar to be edited.

Save Saves the calendar currently being edited, using its

current name.

Save As Displays the Save As dialog, asking you for the new
name under which the calendar currently being
edited will be saved.

Delete Displays a verification dialog, asking you to confirm

that you want to delete the calendar currently being
edited.

Rename Displays the New Calendar Name dialog, asking you

to specify a new name for the calendar currently
being edited.

AutoSys User Guide for UNIX 8-7 ■

■ The Graphical Calendar Facility
Calendar Definition Window

Import Displays the Import File Name dialog so you can

select the directory and filename of the text file
containing calendar definitions that you want to
import.

Export Displays the Export File Name dialog so you can

select the directory and name of the file to which you
want to save all the calendars in the database, in text
form.

Print Prints the calendar currently being edited, using the

print command specified in the application defaults
or the print command specified using the Set Print
Command option from the Options menu.

Exit Displays a verification dialog, asking you to confirm

that you want to exit the application. If you have
made changes which have not been saved, you will
be notified and given an opportunity to save your
changes. If you indicate that you want to exit, the
application is exited.

Edit Menu
The Edit menu contains the following options:

Apply Rule Displays the Term Calendar Rule dialog, which

allows you to set multiple dates at once using a
variety of rule options.

Revert Resets the state of all the dates in the current

calendar to those last saved to the AutoSys database.

Clear Resets the state of all the dates in the current

calendar to the Unset state, regardless of their
current states.

■ 8-8 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Calendar Definition Window

Tools Menu
The Tools menu contains the following options:

Term Calendar Displays the Term Calendar Viewer window, which

Viewer allows you to preview various calendars prior to
applying their dates to the calendar currently being
edited.

Job Definition Displays a list of all the jobs which reference the
Reference List calendar currently being edited, either as their “run
calendar” or “exclude calendar.” This list indicates
which jobs will be affected by any changes you make
to the current calendar. The Job Definition List is
shown in Figure 8-2.

Figure 8-2 • Job Definition Reference List

Note • Whenever a calendar is updated, AutoSys recomputes the

starting times for all jobs which use that calendar.

AutoSys User Guide for UNIX 8-9 ■

■ The Graphical Calendar Facility
Calendar Definition Window

Options Menu
The Options menu contains the following options:

Date Range Displays the Date Range pull-down menu, through

which you may specify the date range of the calendar
currently being edited. The default date range is the
prior year through the current year (Current Year).
You may extend that to include additional years, and
these are the options:
■ Thru Next Year
■ Three Calendar Years
■ Four Calendar Years
■ Five Calendar Years
■ Ten Calendar Years
The Date Range option limits how far into the future
you can set dates in the current calendar. You can
increase the date range of a calendar, and you can
decrease it through the previous year.
When you open an existing calendar, either the date
range of the calendar or the current date range,
whichever is greater, becomes the new date range for
the current Calendar Facility session.

Set Print Displays a dialog box prompting you to specify the

Command full path to the print command to be executed when
printing the calendar currently being edited. For
example, the print command might be “/bin/
qprt -Plp3”. The print command could also be set
using the application default settings, as described in
Print Command on page 8-35.

■ 8-10 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Calendar Definition Window

8 Calendar Display
The Calendar Display region of the window displays six months of the
calendar currently being edited. By default at startup, two quarters of the
current year display, one of which contains the current day (indicated by
a box). Using the navigation controls at the right side of the window, you
can advance or move backward through the calendar, one quarter at a
time.

The Calendar Name field at the top left of the Calendar Display region
displays the name of the calendar currently being edited. You can change
this name using the Rename option from the File menu. You cannot edit
the Calendar Name field.

Date States
Each date in the calendar is a selectable button. By using the mouse and
single-clicking, you can set each date to one of the following states:

Unset The date is not set.

Set The date is set.

Blocked The date is ineligible for setting when applying a

rule.

You can cycle through these three states by single-clicking on the mouse
button additional times. The current state of each date is indicated by its
color, as listed in the Color Key area of the Navigation Controls region.

Note • Calendars are stored in the AutoSys database. Only the Set
dates are stored. Dates designated as Blocked are only in effect while
editing a calendar. The Blocked state is only useful while applying
rules. Blocked dates are not saved in the AutoSys database, nor are the
rules.

AutoSys User Guide for UNIX 8-11 ■

■ The Graphical Calendar Facility
Calendar Definition Window

In addition to the three user-selectable states above, there is a fourth,

system-generated state called the “Conflict” state. This state occurs when
both of the following are true:

■ A rule is applied to a calendar.

■ A date that qualifies for setting by the rule has been previously set to
the Blocked state and rescheduling has not occurred. (Rescheduling
may not have occurred if either a reschedule rule has not been
applied, or an applied reschedule rule cannot find a non-conflicting
date to move to.)

For example, you may have marked all holidays as Blocked, one of which
was January 1. Now you want to apply a rule to the first day of each
month, which would conflict with the January 1 Blocked date. If there is
no reschedule rule in effect, such as “move to the next weekday,” or if the
reschedule rule specifies to move backwards, which would end up on a
date in the previous year, a Conflict state would result. In this case, you
must manually correct the situation before attempting to save the
calendar to the database.

For more information about Rescheduling Rules, see Rescheduling Rule on

page 8-22.

8 Navigation Controls
The Navigation Controls region of the window contains controls which
do the following:

■ Let you specify which six months (or two quarters) are to be displayed
in the window.

■ Display additional information relevant to the calendar currently

being edited.

■ 8-12 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Calendar Definition Window

Shift Months Area

The Shift Months area has two push buttons (with up and down arrows)
to advance or move backward through the calendar, one quarter at a
time. You can change the calendar display to any two quarters within the
calendar's date range. (The date range is discussed in Menu Bar on
page 8-7.) When shifting backward, you can move from the current year
into the prior year. Only one prior year is viewable through the Graphical
Calendar Facility (that is, if the current year is 1997, you could shift back
to 1996, but not to 1995).

Note • Rules cannot be applied to dates prior to the current date.

Skip Button Area

To the right of the Shift Months area is a row of push buttons to “skip” to
a particular date whose state has been set. The following buttons are
available:

First Entry Changes focus to the first date in the calendar that
has been set.

Next Entry Changes focus to the next date in the calendar that
has been set relative to the date that currently has the
focus.

Next Conflict Changes focus to the next date in the calendar that
has been set to the Conflict state by the system.

Last Entry Changes focus to the last date in the calendar that
has been set.

Note • The date with the focus is designated with a black box around
the date.

AutoSys User Guide for UNIX 8-13 ■

■ The Graphical Calendar Facility
Calendar Definition Window

When you use the skip buttons, if the focus is changed to a date that is
not currently displayed, the calendar display will shift to bring that date
into view.

Number of Conflicts Area

Below the Shift Months area is the Number of Conflicts area displaying
how many dates with the Conflict state currently exist in the calendar.
This field is updated each time you apply a rule, or manually change a
Conflict date to another state.

Note • You cannot save a calendar containing unresolved conflicts.

Color Key Area

Immediately below the Number of Conflicts area is the Color Key area
which displays the colors that indicate the states of each date. These
colors are user-configurable, as described in Object Color on page 8-33.
The following colors are used by default:

Unset dates Background color of the Graphical Calendar Facility

Set dates Green

Conflict dates Red

Blocked dates Black

8 Creating a Simple Calendar

To create a simple calendar containing all 1998 holidays
1 Choose File } New.

2 In the New Calendar Name dialog, enter: us_hol_98

3 Press Return.

■ 8-14 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Calendar Definition Window

4 In the Calendar Definition window, set the holiday dates by single-

clicking the left mouse button on each date. If the desired dates are not
displayed, use the Shift Months arrows to bring them into view.

5 Choose File } Save. Your calendar will resemble the one shown in
Figure 8-3.

Figure 8-3 • Example Calendar Definition

8 Dates Prior to Today’s Date

Calendars exist to simplify the scheduling of job runs, therefore only
current and future dates are applicable. While the Graphical Calendar
facility allows you to set dates in the past, they will be ignored. Moreover,
when you merge calendars to create a new calendar, any dates prior to
today will be dropped from the new calendar.

AutoSys User Guide for UNIX 8-15 ■

■ The Graphical Calendar Facility
Calendar Selection Dialog

8 Calendar Selection Dialog

The Calendar Selection dialog lets you specify which calendar you want
to open for editing, or which one to use for a rule specification (see Term
Calendar Rule Dialog on page 8-17).

To access the Calendar Selection dialog

} Choose File } Open.
The Calendar Selection dialog appears, as shown in Figure 8-4.

Figure 8-4 • Calendar Selection Dialog

When this dialog appears, it contains a scroll list of all the calendars
currently in the AutoSys database. In the Filter field of this dialog, you
may specify any string, including the “*” wildcard character, to show
only those calendars whose names include the string. The default filter,
“*”, matches all calendar names. For example, to display only those
calendar names starting with the string “us_hol”, such as “us_hol_97”
and “us_hol_98,” you would specify the filter “us_hol*”, then click the
Filter button. The list will display only the matching calendar names.

■ 8-16 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Term Calendar Rule Dialog

You can select any calendar in the list by single-clicking with the mouse.
Click OK to open the calendar and dismiss the dialog. Click the Cancel
button to dismiss the dialog without selecting a calendar.

8 Term Calendar Rule Dialog

The Term Calendar Rule dialog lets you set a state for multiple dates
simultaneously, rather than selecting each date individually.

To access the Term Calendar Rule dialog

} Choose Edit } Apply Rule.
The Term Calendar Rule dialog, shown in Figure 8-5, appears.

Figure 8-5 • Term Calendar Rule Dialog

AutoSys User Guide for UNIX 8-17 ■

■ The Graphical Calendar Facility
Term Calendar Rule Dialog

The Term Calendar Rule dialog is divided into the following three
regions:

Rule Specification The top portion of the dialog.

Rescheduling Rule Center of the dialog.

Control The bottom portion of the dialog.

8 Rule Specification
The Rule Specification region provides a variety of options for specifying
which dates in the currently selected calendar you want to affect, and
what state to set for those dates. This region consists of the following
three areas:

■ Action Area

■ Date Range

■ Date Selection Rule

Action Area
The Action Area lets you apply one of the following states on the selected
dates:

Set Dates Change the state to Set.

Unset Dates Change the state to Unset.

Block Dates Change the state to Blocked. Blocked dates will not
be set during any subsequent rule applications.

Note • These actions are mutually exclusive; only one of these actions
can be selected.

■ 8-18 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Term Calendar Rule Dialog

Date Range Area

In the Date Range area, you specify the date range over which the rule
should apply. By default, the date range of the currently selected calendar
is in effect. However, you can change the date range by selecting an
option from either the All in Year pull-down menu, or by specifying a
date range in the All in Range edit fields. When entering a date range, the
dates must fall within the range set in the Options Date Range pull-down
menu.

Note • Rules are not applied to any date prior to today’s date.

Date Selection Rule Area

The Date Selection Rule area contains the following three sub-areas:

Occurrences Lets you specify the “occurrence of a day” for which

the rule should be applied. Select one or more
options by pressing the corresponding toggle
button.

Day Lets you specify the days of the week to which the
rule should be applied. Select one of the following:
Day (Any), Weekday, or Specific Day(s). If Specific
Day(s) is selected, one or more of the specific days of
the week must be chosen as well.

AutoSys User Guide for UNIX 8-19 ■

■ The Graphical Calendar Facility
Term Calendar Rule Dialog

Period Lets you specify the period during which the rule
should be applied. Only one of the following
options can be chosen: No Period, Monthly,
Quarterly, Every “n” weeks, or the days in a specified
Calendar. The No Period option is used for non-
repeating periods, such as Every/Monday—this
option is generally used with the Every or Every “th”
option in the Occurrences sub-area.
If the Calendar option is selected, only the dates
specified in the indicated calendar will be used when
applying the rule. You can either enter the calendar
name directly, or press the Calendar button to
display the Calendar Selection dialog, from which
you can choose a calendar for the period.

Note • The rules used to set a calendar are not saved after the calendar
has been created and saved.

8 Examples of Date Selection Rules

The following examples illustrate the use of the use of the Date Selection
Rule options. We recommend you experiment with these rules. You can
always revert to the last saved version of a calendar by using the Revert
option from the Edit menu, or you can clear everything using the Clear
option from the Edit menu.

Setting Dates

To set the 3rd Tuesday of every month throughout the entire currently
selected calendar
1 In the Action area, select Set Dates.

2 Keep the default date range, which is the currently selected calendar's
entire range.

■ 8-20 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Term Calendar Rule Dialog

3 In the Occurrences sub-area, select either the Third option or enter 3

in the “th” option.

4 In the Day sub-area, select Tuesday (which automatically selects the

Specific Day(s) option).

5 In the Period sub-area, select Monthly.

6 Click OK or Apply to apply the rule to the calendar you are currently
editing.

Blocking Dates

To block every holiday date and prevent those days from being
scheduled
Follow these steps (assuming the holiday dates already exist in a calendar
named “us_hol_98”).

1 In the Action area, select Block Dates.

2 Keep the default date range, which is the currently selected calendar's
entire range.

3 In the Occurrences sub-area, select Every.

4 In the Day sub-area, select Day (Any).

5 In the Period sub-area, press the Calendar button. When the Calendar
Selection dialog appears, select the calendar named “us_hol_98”, and
click OK. The calendar name will appear in the Calendar field in the
Period sub-area.

6 Click Apply to apply the rule to the calendar you are currently editing.

Following on with the above example, assume that you want to change
the state of the first day of every month to Set.

AutoSys User Guide for UNIX 8-21 ■

■ The Graphical Calendar Facility
Term Calendar Rule Dialog

To change the state of the first day of every month to Set

1 In the Action area, select Set Dates.

2 Keep the default date range, which is the currently selected calendar's
entire range.

3 In the Occurrences sub-area, select First.

4 In the Day sub-area, select Day (Any).

5 In the Period sub-area, select Monthly.

6 Click Apply to apply the rule to whatever calendar you are currently
editing.

When you apply this rule, a Conflict state will be assigned to January 1,
since this date is defined in “us_hol_98,” and was marked as Blocked in
the previous example. To address this you must either “unset” it
manually and, if desired, set another date in its place, or you could
specify a Rescheduling Rule to accommodate this type of conflict.
Rescheduling Rules are described in the next section.

8 Rescheduling Rule
The Rescheduling Rule region lets you control how date conflicts should
be resolved when applying a rule. To specify a rescheduling rule, you
must indicate a “move direction” and the day to which the newly
scheduled Set state should be moved when a conflict occurs. You do this
in the Move Direction and To Day areas.

Note • Conflicts can also occur if a date is Set, then Blocked.

Whenever a conflict occurs, the Set state is moved when rescheduling.

■ 8-22 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Term Calendar Rule Dialog

Move Direction
You can select one of the following Move Direction options:

To Previous Moves the Set state backward in the calendar.

To Following Moves the Set state forward in the calendar.

To Day
In addition to specifying the Move Direction, you must specify one of the
following To Day options:

Any Day Next available date.

Weekday Next available weekday date.

Calendar-based Next available date in the specified calendar. You

must choose either In Calendar or Not In Calendar,
and specify a calendar name, either by entering it
directly, or by pressing the Calendar button, then
selecting a calendar from the Calendar Selection
dialog that appears.

Example
To remedy the conflict situation in the last example from the previous
section (on page 8-22), assume that you want to apply a Rescheduling
Rule that specifies “any day following the date in conflict that is not also
a holiday.”

To apply a Rescheduling Rule that specifies “any day following the

date in conflict that is not also a holiday”
1 In the Action area, select Set Dates.

2 Keep the default date range, which is the currently selected calendar's
entire range.

3 In the Occurrences sub-area, select First.

AutoSys User Guide for UNIX 8-23 ■

■ The Graphical Calendar Facility
Term Calendar Rule Dialog

4 In the Day sub-area, select Day (Any).

5 In the Period sub-area, select Calendar. When the Calendar Selection

dialog appears, select the calendar named “us_hol_98”, and click OK.
The calendar name will appear in the Calendar field.

6 In the Move Direction area, select To Following.

7 In the To Day area, select the Not in Calendar option and enter the
calendar named “us_hol_98”.

8 Click OK or Apply to apply the rule to the calendar you are currently
editing.

Note • Multiple conflict dates can be rescheduled to the same new

date. For example, if you block all weekend dates, then apply a rule to
set every day, with rescheduling to the previous weekday, both the
Saturday and Sunday conflicts will be resolved to the preceding
Friday. If you want separate runs for Saturday and Sunday, turn off the
Rescheduling Rule and resolve the conflicts manually.

Note • If you intend to use a Rescheduling Rule, you should set it up

at the same time you set up the Date Selection Rule, rather than wait
for conflicts to occur.

8 Control
At the bottom of the Term Calendar Rule dialog, there are three buttons:
OK, Apply, and Cancel. The OK button applies the current rule and
dismisses the dialog. The Apply button applies the rule but does not
dismiss the dialog. The Cancel button dismisses the dialog without
applying the rule.

■ 8-24 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Term Calendar Viewer

8 Term Calendar Viewer

The Term Calendar Viewer allows you to preview a calendar before using
it in a rule you are about to apply. You can easily browse any existing
calendars to see which dates they contain.

To access the Term Calendar Viewer

} Choose Tools } Term Calendar Viewer.
The Term Calendar Viewer appears, as shown in Figure 8-6.

Figure 8-6 • Term Calendar Viewer

AutoSys User Guide for UNIX 8-25 ■

■ The Graphical Calendar Facility
Term Calendar Viewer

The Term Calendar Viewer is divided into the following regions:

Calendar Display At the left and center of the window. The dates in
this calendar are read only—they cannot be edited.
You can only edit dates using the Calendar
Definition window.

Navigation At the right of the window.

Controls

Note • Unlike the Calendar Definition window, there is no Next

Conflict button in the Navigation Controls region of this window.
This is because calendars cannot be stored in the database if they
contain conflicts. Also note that Blocked days are not stored in the
database—all dates saved in a calendar are “Set” dates. However,
calendars may be used to block out dates by way of the Term Calendar
Rule dialog.

When the Term Calendar Viewer first appears, it displays six months of
the current year. You must then select a calendar by single-clicking on its
name in the Calendar Selection list in the lower-right corner of the
window. Navigation is exactly the same as in the Calendar Definition
window.

As each calendar is selected, it completely replaces the previously viewed

calendar, and its name is displayed in the Calendar Name field at the top
of the window.

When you are finished viewing calendars, click the Dismiss button to
close the window.

■ 8-26 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Combining Calendars

8 Combining Calendars
Calendars can be combined in a number of ways. For example, you can
create a calendar that includes all the dates that are in either one calendar
or another. Or you can create a calendar that includes all the dates that
are in one calendar but not in another. In fact, you can combine any
number of calendars in these ways.

For example, suppose you have a calendar named “us_hol_98”

containing all United States holidays, and you have a calendar named
“corp_hol_98” containing all your corporation holidays. In this scenario,
you want create a new calendar for all combined holidays called
“all_hol_98.” This new calendar will include all the dates that are in either
of the previously defined calendars. The best way to accomplish this is
described in these steps.

To combine calendars
1 Choose File } New.

2 In the New Calendar Name dialog, enter: all_hol_98

3 Click OK.

4 Choose Edit } Apply Rule.

5 In the Term Calendar Rule dialog, select the Set Dates Action, the
Every Occurrence, and the Day (Any) Day settings.

6 In the Period sub-area, click the Calendar button, then select

“us_hol_98” from the Calendar Selection dialog, and click OK.

7 In the Term Calendar Rule dialog, click Apply.

8 Repeat steps 5 and 6, selecting the calendar “corp_hol_98”.

9 Choose File } Save.

This process of combining calendars can be repeated for any number of

calendars.

AutoSys User Guide for UNIX 8-27 ■

■ The Graphical Calendar Facility
Printing Calendars

Note • When combining calendars, any dates prior to the current date
will be dropped from the new calendar.

8 Printing Calendars
You can print calendars to obtain a hard copy for your files. Before you
attempt to print a calendar, be sure the print command is correctly
specified, either through your X resources file, or by way of the Set Print
Command option from the Options menu. The print command must
include the full path to the print facility to be used, plus all appropriate
arguments. Once this is set, you can open an existing calendar, or create
a new calendar, then select the Print option from the File menu.

8 Import/Export File Name Dialog

You can import calendar text files and you can export calendars to text
files. This is particularly useful for copying calendars from one AutoSys
instance to another. You perform calendar imports and exports using the
Import (and Export) File Name dialog.

8 Importing Calendar Text Files

Calendars contained in ASCII text files can be imported into the AutoSys
database. These text files may contain multiple calendars, each of which
must be delimited with the calendar:calendar_name attribute. A
sample calendar text file is shown below:
calendar: Q1paydays
01/01/1998
01/15/1998
02/01/1998
02/15/1998
03/01/1998
03/15/1998
calendar: Q1holidays
01/01/1998

■ 8-28 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Import/Export File Name Dialog

Comments may be included following a space after the calendar name or

after each date.

If you export a calendar, the output will be in this same format.

To access the Import File Name dialog

} Choose File } Import.
The Import File Name dialog appears, as shown in Figure 8-7.

Figure 8-7 • Import File Name Dialog

At this dialog, you can either enter the full path to the calendar in the
Selection field, or use the Filter field, Directories list, and Files list to
select the file.

AutoSys User Guide for UNIX 8-29 ■

■ The Graphical Calendar Facility
Import/Export File Name Dialog

When using a filter, the Filter field must contain a directory pathname,
which is everything up to the last slash (“/”) followed by the file pattern
containing an asterisk (“*”). For example, to search the directory /home/
my_dir for all file names with the string cal, you would specify: /home/
my_dir/*cal*. Then, click the Filter button, and the Files list will display
all the files containing that string. Then, click on the file you wish to
import, and the full pathname will appear in the Selection field. Finally,
click OK to import the file.

Note • If the text file being imported contains calendars with the same
names as calendars already existing in the database, these calendars
will not be imported. A warning dialog will notify you that a calendar
name is duplicated, and that the import of this calendar will not
occur. Also, after the import has completed, an information dialog
will tell you how many calendars were imported.

8 Exporting Calendars
You can export all the calendars from the AutoSys database to an ASCII
text file. To export, select File } Export. The Export File Name dialog will
display, allowing you to specify a filename for the calendar text file.

Note • When you use the export facility, all the calendars in the
AutoSys database are exported to a single ASCII text file. After the
export has completed, an information dialog will tell you how many
calendars were exported. You cannot export just a single calendar;
however, you can edit the ASCII file after you export all the calendars.

The Export File Name dialog uses the same filtering as described in
Importing Calendar Text Files on page 8-28.

■ 8-30 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Customizing the Calendar Facility

8 Customizing the Calendar Facility

There is a set of X resources that you can use to customize the appearance
and behavior of the Calendar Facility. In particular, these resources allow
you to control:

■ The fonts that are used in the Calendar Definition window as well as
the Calendar Facility dialogs. The choice of fonts will affect the size of
the various windows and dialogs.

■ The colors used to indicate whether dates are Set, Unset, or Blocked.

■ The print command to be executed when you want to print a calendar.

■ The Calendar GUI icon text and the Calendar title bar text.

Descriptions of each of the resources which can be customized are given

below. All of these can be set by modifying the X resource file Autocal.
The X resources files reside in the local app-defaults directory, which
varies across platforms. It is usually in /usr/lib/X11/app-defaults or /
usr/openwin/lib/app-defaults. If you are not sure which directory these
files are in, ask your system administrator.

Individual users may have their own copy of the X resources files in their
$HOME directory, which will take precedence over the app-defaults files.

For most operating systems, if you are exporting the display to another
machine you must edit the appropriate files in the app-defaults
directory on the local machine.

For Solaris, you must edit the files in both the /usr/lib/X11/
app-defaults and /usr/openwin/lib/app-defaults directories. The files
in /usr/lib/X11/app-defaults control the resources when you export the
display.

We have listed the various resource names here as a reference only. For
the default values, see the Autocal file. The provided resource file values
work well for a majority of platforms.

AutoSys User Guide for UNIX 8-31 ■

■ The Graphical Calendar Facility
Customizing the Calendar Facility

8 Font Selection Resources

The following resource specifications control font selection. They are
completely independent of any other font settings.
! main font for all fields not otherwise specified
Autocal*fontList:
! font for dates within each month in Calendar
! Definition window
Autocal*month_form*fontList:
! main font for everything in Calendar Viewer
! except dates
Autocal*calViewForm*fontList
! font for dates in Calendar Viewer
Autocal*calViewform*month_form*fontList
! font for term rule dialog
Autocal*termRuleForm*fontList:

■ 8-32 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Customizing the Calendar Facility

8 Object Color
The following resources affect the colors of the various objects within the
Calendar Facility.

Note • Several of the following colors come in pairs, such as setColor

and setLabelColor. The LabelColor is the color of the numbers that
appear on the date buttons and should be chosen so that they are
easily readable with the color of the button on which they display. For
example, don't specify setColor as blue and setLabelColor also as
blue—the numbers will not be visible on the dates. Select another
color, such as black or white for the label.

! general application background color

Autocal*background:
! color to represent "set" dates
Autocal*setColor:
! color for label (foreground numbers) to represent
! "set" dates
Autocal*setLabelColor:
! color to represent "blocked" dates
Autocal*blockedColor:
! color for label (foreground) to represent
! "blocked" dates
Autocal*blockedLabelColor:
! color to represent "conflict" dates
Autocal*conflictColor:
! color for label (foreground) to represent
! "conflict" dates
Autocal*conflictLabelColor:

AutoSys User Guide for UNIX 8-33 ■

■ The Graphical Calendar Facility
Customizing the Calendar Facility

The following resource sets the color for a grid that appears between the
dates in the Calendar Viewer window, to help differentiate it from the
Calendar Definition window. If you do not want the grid to appear, select
the same color as the background.
Autocal*viewerColor:

8 Date Range
The following resource sets the number of years in the date range of the
calendar, as a default at start up. This can be overridden manually by way
of the Date Range option from the Options menu, or by loading a
calendar that has a larger date range than the default. These are the legal
settings:
! 1 = prior year plus current year,
! 2 = thru next year, 3 = thru third year,
! 4 = thru fourth year, 5 = thru fifth year,
! 10 = thru tenth year
Autocal.dateRange:

8 Window Size
The following resources help keep the size of the window small, and it is
recommend that you do not change their settings.
Autocal*calViewForm*month_form*marginHeight: 0
Autocal*calViewForm*month_form*marginWidth: 0
Autocal*calViewForm*month_form.marginWidth: 2

■ 8-34 AutoSys User Guide for UNIX

 The Graphical Calendar Facility ■
Customizing the Calendar Facility

8 Print Command
The following resource specifies the print command, and its arguments,
which will be executed when you request that a calendar be printed. Be
sure to specify the full pathname of the executable, or it may not be
located and the print will fail.
Autocal.printCommand:

8 Calendar Title bar Text and Icon Text

The following resources specify the title bar text and the icon text. By
default the title bar text is “Calendar Definition” and the icon text is
“CalDef”.
Autocal.shellTitle:
Autocal.iconTitle:

Note • When changing icon text, be sure the length of the new text
string does not exceed the recommended maximum length for icon
title text for your windowing system. Some window managers can
display long icon text strings, while others will truncate them. Ensure
the text string you specify for your icons displays appropriately. Also,
some window managers allow you to change the size of icons and
icon text font.

AutoSys User Guide for UNIX 8-35 ■

 9
Load Balancing and
Queuing Jobs
This chapter describes the use of real and virtual machines in the AutoSys
environment to provide load balancing and queueing functionality. It
provides information about load balancing jobs across multiple
machines, as well as queueing jobs to real and virtual machines.
Real Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3

Virtual Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3

Defining Machines to AutoSys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4

Specifying Machine Load (max_load) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5
Specifying Relative Processing Power (factor) . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Using max_load and factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Machine Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7

Defining a Real Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8

Deleting Real Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9

Defining a Virtual Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9

Deleting Virtual Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10

AutoSys User Guide for UNIX 9-1 ■

■ Load Balancing and Queuing Jobs

Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11

Force Starting Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14

Load Balancing Using ServerVision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15

Testing the Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18

ServerVision Monitoring and Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18

Queuing Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18

Queuing and Simple Load Limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19
Queuing with Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20
Subsets—Individual Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-23
Multiple Machine Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-25

User-Defined Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-26

■ 9-2 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Real Machines

9 Real Machines
In the AutoSys environment, a real machine is any physical CPU that has:

■ Been identified in the appropriate network database (e.g., /etc/

hosts) so that AutoSys can access it.

■ Undergone a client software installation (and is licensed) so that

AutoSys can run jobs on it.

The above two conditions are required for a real machine to run AutoSys
jobs. However, for AutoSys to perform intelligent load balancing and
queuing while executing jobs, it needs to know the relative processing
power of the various real machines. AutoSys provides both load
balancing and queuing by way of the logical construct called virtual
machines.

9 Virtual Machines
A virtual machine is comprised of one or more real machines, in whole
or in part (or a combination of both). All real machines within a virtual
machine must be of the same type, either NT or UNIX. Virtual machines
cannot be a mix of both UNIX and NT machines

By defining virtual machines to AutoSys, and then submitting jobs to run

on those machines, you can specify:

■ Runtime resource policies (or constraints) at a high level.

■ That AutoSys automatically execute those policies in a multi-machine

environment.

AutoSys User Guide for UNIX 9-3 ■

■ Load Balancing and Queuing Jobs
Defining Machines to AutoSys

9 Defining Machines to AutoSys

Define both real and virtual machines to AutoSys by using machine
attribute statements within a JIL script. The following JIL sub-command
defines a real or virtual machine to AutoSys:
insert_machine: machine_name

The following JIL machine attributes are used when defining machines:
type

Specifies a machine type, which can be one of the following:

• r for UNIX real

• v for UNIX virtual

• n for NT (real or virtual)

machine

Specifies a real machine name to be inserted in a virtual machine.

max_load

For real machines only, and used for load balancing.

factor

For real machines only, and used for load balancing.

Real machines only need to be defined to AutoSys if they meet one of the
following criteria:

■ Require a max_load or factor attribute to be set for them. (These

attributes are discussed in the next section.)

■ Are to be included in a virtual machine.

Virtual machines must be defined before you can use them.

■ 9-4 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Defining Machines to AutoSys

Load balancing and queuing can be done only if real and virtual
machines have been defined to AutoSys using these machine attribute
statements. The following two attributes, used when defining real
machines, are key for load balancing and queuing: max_load and factor.

Note • Real and virtual machines can be defined only using JIL. There
is no GUI interface for defining machines.

For more information about the JIL sub-commands and attributes

pertaining to machines, see Chapter 3, JIL Machine Definitions in the
AutoSys Reference Guide for UNIX.

9 Specifying Machine Load (max_load)

The max_load attribute can be defined only for real machines. It describes
how much of a load can be placed on a real machine, and it is specified
with an arbitrary unit called a “load unit”. Any weighting scheme desired
by the user can be used. For example, a load unit with a range of 10-100
would specify that machines with limited processing power are expected
to carry a load of only 10, while machines with ample processing power
can carry a load of 100. There is no direct relationship between the load
unit value and any of the machine’s physical resources. Therefore, you
should develop conventions that are meaningful to you. Zero and
negative numbers cannot be used.

Job Attributes and Load Balancing and Queuing

For load balancing to work, every defined job that will impact the load
on a machine must be assigned a job_load job attribute, which defines
the relative load the job will place on a machine. Thus, a machine’s
current load can be tracked, and overloading of a machine can be
prevented. For example, if the max_load on a machine is “100” and the
job_load for one job is “10”, then that job will use 10 percent of the
machine’s resources.

AutoSys User Guide for UNIX 9-5 ■

■ Load Balancing and Queuing Jobs
Defining Machines to AutoSys

In addition, for job queueing to take place, the priority job attribute
must also be assigned in the job definition. The priority attribute
specifies the relative priority of all jobs queued for a given machine.
Without this attribute set, a job will run immediately on a machine,
and it will not be placed in the queue.

9 Specifying Relative Processing Power (factor)

The factor machine attribute can be defined only for real machines. It is
another arbitrary value that describes the relative processing power of a
machine. This attribute’s value is a real number that can contain a
decimal. It is used to weigh available cycles on one machine against that
of another machine. When AutoSys checks the available cycles on each
machine, it multiplies the percent of free CPU cycles by the factor in
order to determine which machine has more relative processing power
available. Therefore, the factor value is typically a number between 0.0
and 1.0.

9 Using max_load and factor

The max_load attribute is primarily used to limit the loading of a
machine. As long as a job’s load will not cause a machine’s max_load to
be exceeded, the max_load attribute does not influence the decision of on
which machine a job should be run. Conversely, the factor attribute is
primarily intended to be used when deciding between machines for
running a job, if more than one machine is available.

If these attributes are not specified in a real machine definition, they

default to the values shown below:
max_load: none/* no limit */
factor: 1.0

Note • A virtual machine is comprised of real machines. Therefore

you do not specify max_load and factor attributes explicitly in a virtual
machine definition. They are specified in the definitions of the real
machines that make up the virtual machine.

■ 9-6 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Defining Machines to AutoSys

9 Machine Definitions
AutoSys can infer whether a machine being defined is a real or a virtual
machine based solely on the attributes in the definition. Any machine
definition containing a max_load or factor attribute must be a real
machine definition, because only real machines can have these
attributes. Any machine definition containing a list of machine attributes
is a virtual machine definition.

Because of this, you can omit the type attribute when defining a UNIX
machine. For NT, however, the type attribute is required. Compare the
definitions below.

Real UNIX Real NT

insert_machine: toad insert_machine: tiger

max_load: 100 type: n

factor: .8 max_load: 100

factor: .8

Virtual UNIX Virtual NT

insert_machine: pond insert_machine: jungle

machine: toad type: n

machine: frog machine: tiger

machine: monkey

AutoSys User Guide for UNIX 9-7 ■

■ Load Balancing and Queuing Jobs
Defining a Real Machine

To help you understand virtual machines and their capabilities, the

following sections provide a series of examples that demonstrate the
different combinations of real machines that can constitute a virtual
machine. These examples include the JIL statements used to define these
machines.

9 Defining a Real Machine

To define a real machine to AutoSys
1 Assign a machine name, this must be its hostname.

2 Assign a machine type: r for real UNIX or n for NT.

3 Optionally, assign a max_load and a factor attribute value.

Figure 9-1 defines a real UNIX machine named “jaguar” with a max_load
of 100 and a factor of 1.0.

insert_machine: jaguar
type: r
max_load: 100 100 max_load
factor: 1.0 1.0 factor
jaguar

Figure 9-1 • Real UNIX Machine with max_load 100 and factor 1.0

To define a real NT machine named “tiger”, enter the following JIL

statements:
insert_machine: tiger
type: n
max_load: 100
factor: 1.0

■ 9-8 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Defining a Virtual Machine

9 Deleting Real Machines

The following JIL statement deletes the real machine definition for the
machine named “jaguar”:
delete_machine: jaguar

9 Defining a Virtual Machine

To define a virtual machine to AutoSys
1 Assign a machine name.

2 Assign a machine type: v for virtual.

3 Specify the real machines that will make up the virtual machine.

Figure 9-2 defines a virtual machine named “modena”, which is

composed of two real machines named “ferrari” and “lambo”. Because
the real machines do not specify a max_load and factor, they will have
the default values for these attributes: a factor of 1.0 and unlimited load
units.

insert_machine: modena modena

type: v
machine: ferrari
machine: lambo

ferrari lambo
Figure 9-2 • Virtual Machine with Two Real Machine Components

The following JIL statements define two real machines named “fiat” and
“lotus”, and a virtual machine named “capri”, which is composed of the
two real machines. The virtual machine is a superset of the two previously
defined real machines. (Because the real machines are defined first to
AutoSys, the virtual machine will use the max_load and factor attributes
specified for them.)

AutoSys User Guide for UNIX 9-9 ■

■ Load Balancing and Queuing Jobs
Defining a Virtual Machine

insert_machine: fiat
type: r
max_load: 100
factor: 1
insert_machine: lotus
type: r
max_load: 80
factor: .9
insert_machine: capri
type: v
machine: fiat
machine: lotus

The following JIL statements define a virtual machine named “mustang”

which is composed of slices, or subsets, of the real machines named “fiat”
and “lotus”. Even though the real machines have been previously
defined, only the reduced load portion (or slices) will be used in the
virtual machine “mustang”.

insert_machine: mustang
type: v
machine: fiat fiat lotus
max_load: 10
machine: lotus 10 9
max_load: 9

Figure 9-3 • Virtual Machine Comprised of Subsets of Real Machines

9 Deleting Virtual Machines

To delete a real machine component of a virtual machine, you specify the
virtual machine and the desired component. The following JIL
statements delete only the real machine named “lambo” found within
the virtual machine named “modena”:
delete_machine: modena
machine: lambo

■ 9-10 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Load Balancing

If the machine “lambo” had been individually defined outside of the

virtual machine, its individual definition still remains in effect.

To delete the entire virtual machine, you don’t have to specify any of the
component real machines. The real machines are still defined—only the
virtual machine they were in is deleted. The following JIL statement
deletes the virtual machine named “mustang”:
delete_machine: mustang

Because the real machines “fiat” and “lotus” had been individually
defined outside of the virtual machine, their individual definitions
remain in effect.

9 Load Balancing
By specifying a virtual machine or a list of real machines in a job’s
machine attribute, rather than a single real machine, you can implement
simple load balancing. That is, you can cause the work load to be spread
across multiple machines, based on each machine’s capabilities. In
addition to load balancing, this feature is useful way to ensure reliable
job processing. For example, if one of the machines is down, load
balancing will run the job on another machine.

When a job is ready to start, AutoSys will determine which of the

specified machines is best suited to run the job. The following JIL
example shows the job definition statements for such a job:
insert_job: test_load
machine: modena
command: echo "Test Load Balancing"
job_load: 50
priority: 1

Where “modena” is a virtual machine.

Alternatively, you can specify a list of real machines in the job’s machine
attribute, as shown below:
machine: ferrari, lambo

AutoSys User Guide for UNIX 9-11 ■

■ Load Balancing and Queuing Jobs
Load Balancing

If the max_load attribute was not defined for either real machine (as in
our example), or both machines had ample load units available, AutoSys
would choose the machine to run on based solely on available
processing power. To accomplish this, AutoSys does the following:

1 Determines the percentage of CPU cycles available on each real

machine in the specified virtual machine. This is accomplished by one
of the following actions:

• Issuing a remote procedure call (RPC) to the real machine and

requesting rstatd data.

• Running vmstat on the real machine.

2 These methods are specified in the AutoSys configuration file using

the MachineMethod parameter.

Note • rstatd is not currently supported on NCR or Pyramid client

machines.

3 Multiplies it by the machine’s factor value.

4 Chooses the machine with the largest result (i.e., the machine with the
most relative processing cycles available).

In the example machine list above, the factor attribute is not specified
for either machine, and thus the default factor value for each machine is
1.0.

If the machines have equal max_load and factor values, it is equivalent

to defining a job and specifying the following in the machine field:
machine: ferrari, lambo

■ 9-12 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Load Balancing

The advantages of building a virtual machine are that it can be changed,

and the new construct is immediately applied globally. Also, the values
can vary between machines. Even when a set of real machines that have
not been explicitly defined to AutoSys are specified in a job’s machine
attribute, the available CPU cycles are used to determine which machine
will run the job.

In all likelihood, your system configuration will include machines of

varying processing power, so you will need to specify the factor attribute
value for each real machine.

Figure 9-4 illustrates three machines having different capabilities, which

are grouped into a virtual machine.

italia

ferrari alfa_romeo lambo

1.0 0.8 0.3 factors

Figure 9-4 • Load Balancing on a Virtual Machine

The following JIL statements can be used to define this machine:

insert_machine: italia
machine: ferrari
factor: 1
machine: alfa_romeo
factor: .8
machine: lambo
factor: .3

AutoSys User Guide for UNIX 9-13 ■

■ Load Balancing and Queuing Jobs
Load Balancing

To start a job on this virtual machine, simply specify “italia” as the

machine attribute for the job. The Event Processor will perform the
necessary calculations to determine on which machine to run the job,
and reflect these calculations in its output log. The output is similar to
this:
EVENT: STARTJOB JOB: test_mach
Checking Machine usages using RSTATD:<ferrari=78*[1.00]=78>
<alfa_romeo=80*[.80]=64>
<lambo=2*[.30]=06>
[ferrari connected]
EVENT: CHANGE_STATUS STATUS: STARTING JOB:
test_mach

Note that even though the “ferrari” usage was less than “alfa_romeo”,
“ferrari” was picked because of the factors (78 * 1.0 > 80 * 0.8). Thus, the
factors weigh each machine to account for variations in processing
power.

9 Force Starting Jobs

If you force start a job, AutoSys will start the job right away on the
machine specified in the job definition, regardless of the current load on
the machine or the job_load specified for the job. If the job was defined
to run on a virtual machine, or a list of real machines, AutoSys will
determine which machine has the most processing power available and
will run the job on that machine, even if the job_load of the job exceeds
the max_load defined for the machine.

■ 9-14 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Load Balancing Using ServerVision

9 Load Balancing Using ServerVision

AutoSys can use the machine performance metrics monitored by
ServerVision to select, at runtime, the best machine on which to execute
a job. You supply a command that executes a specified algorithm to the
machine job attribute, and this command returns the name of the best
machine (based on the given algorithm).

Before using this feature, ensure the configuration has been completed as
described in Configuring ServerVision Monitoring and Reporting section of
Chapter 13, Configuring AutoSys. For information on ServerVision, see the
SeverVision documentation on the documentation CD.

To apply ServerVision load balancing to an AutoSys job, specify the

following string in the machine job attribute, or to the Machine to Execute
field in the Job Definition screen:
'svload -a alg [-v virt | -l list] -p profile 2> filename'

Note • This string cannot exceed 80 characters.

where:
svload

Is the svload executable.

alg

Is the method to be used by ServerVision to select the best machine.

This algorithm must be defined in the profile file that you reference
with the -p argument. For example, the algorithm you define could
provide one method that would be used for I/O-bound jobs and a
different method that would be used for cpu-bound jobs.
virt

Is a virtual machine that has been defined to AutoSys.

AutoSys User Guide for UNIX 9-15 ■

■ Load Balancing and Queuing Jobs
Load Balancing Using ServerVision

list

Is a comma-separated list of real machines.

profile

Is a file containing basic information and the performance metrics

that apply to each possible algorithm that can be chosen. You can
supply a path and filename for this option.

The profile file for ServerVision load balancing might look like this
example svload.prf file:
[ServervisionConfiguration]
Timeout=12
InstanceType=unix
honda=honda
toyota=toyota
jeep=jeep

[CPU]
cpu_tl,idle,maximum,1

[Memory]
memory,used,minimum,1

[CPUMemory]
cpu_tl,idle,maximum,2
memory,used,minimum,1
where:

[ServervisionConfiguration]

Is a literal that must appear exactly as shown in this example.

Timeout

Is the number of seconds ServerVision should attempt to connect

to a machine. The recommended setting is 12 seconds.

■ 9-16 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Load Balancing Using ServerVision

InstanceType=unix

Indicates the instance type. For this implementation, the value

should be unix. For more information, see your ServerVision
documentation.

honda=honda...

Are examples of names of the real machines defined to AutoSys

with the name of the corresponding ServerVision instance. It is in
the form of machine_name=ServerVision_instance. Typically, the
ServerVision instance will have the machine name also.
[CPU]...[Memory]...[CPUMemory]

These specify examples of names and definitions of the algorithms.

You can create your own definitions, using any name, and you can
have as many definitions in this file as you want. Each algorithm
definition must use the Scan Groups as defined by ServerVision.
The syntax must be a colon separated string with the following
elements, in this order:

Scan Type—Indicates the Scan Type as defined by ServerVision.

Scan Object—Indicates the Scan Object that is associated with the

Scan Type as defined by ServerVision.

maximum or minimum—Indicates the value that is desired, either

the maximum number or the minimum number.

Weight—Indicates the item’s importance in relationship to other

items that make up the algorithm. For example, in the CPUMemory
definition above, the CPU item is indicated as having twice the
weight of the memory item.
2> filename

Specifies to redirect any standard error messages to a file.

For information on ServerVision Scan Types and Objects, see the

ServerVision for UNIX Reference Guide.

AutoSys User Guide for UNIX 9-17 ■

■ Load Balancing and Queuing Jobs
ServerVision Monitoring and Reporting

9 Testing the Algorithms

You can run the following command to test the algorithms you enter in
the svload.prf file:
svload -a alg [-v virt | -l list] -p profile -y
This command prints to the screen the result metrics. You can use this
information when you are creating the profile file and want to test your
algorithm definitions.
WARNING • The -y argument is for testing only. Do not use it when using
this command as the value for the machine job attribute. When testing the
algorithm, do not include the 2> filename argument.

9 ServerVision Monitoring and Reporting

You can also use ServerVision to monitor AutoSys job resource usage in
real time. AutoSys jobs will appear in the ServerVision GUI by job name.
AutoSys can also archive a job’s resource usage use ServerVision to
generate reports for capacity planning and UNIX process auditing (charge
back). This functionality requires that ServerVision integration has been
enabled as described in the Configuring ServerVision Monitoring and
Reporting section in Chapter 13, Configuring AutoSys. For details on
monitoring job resource usage using ServerVision, see Monitoring Job
Resource Usage in Chapter 13.

9 Queuing Jobs
Queuing jobs in AutoSys is a mechanism for ordering jobs that are
unable to be run immediately. You can also issue a “change priority”
event to change the priority of a job in the queue. There is no actual
“queue” entity. Instead, jobs are chosen based on queuing policies.

Queuing policies in AutoSys are established through the use, and

subsequent interaction, of the two job attributes job_load and priority,
and the two machine attributes max_load and factor.

■ 9-18 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Queuing Jobs

The following sections discuss queuing jobs and give examples of how
load balancing and queuing are used to optimize job processing in your
AutoSys environment.

9 Queuing and Simple Load Limiting

If a job has been assigned a job_load value (the load limiting feature),
and a max_load attribute is assigned to every real machine comprising a
virtual machine, AutoSys will first determine whether each machine has
sufficient available load units before running the job. If each real
machine has sufficient load units, AutoSys employs the load balancing
and “factor” algorithms to determine on which machine it should start.
However, if only one of the machines has sufficient load units, the job
will be run on that machine. If no machines have sufficient load units,
the job will be placed “on queue” for both (or all) machines. When one
machine becomes available, the job is run on that machine, and removed
from all other queues.

The words “in the queue” refer to an actual AutoSys QUE_WAIT job
status, and the job will stay in this state until the necessary load units
become available.

When the necessary load units become available, AutoSys again checks
all the job’s starting conditions to ensure it is still okay to run the job. If
any of the starting conditions are no longer true, the following message
is generated:
Job: job_name Starting Conditions are no longer TRUE.
De-Queuing this Job and setting to ACTIVATED.

AutoSys User Guide for UNIX 9-19 ■

■ Load Balancing and Queuing Jobs
Queuing Jobs

Note • In order for any queuing to take place, all jobs must have their
priority attribute set. By default, the priority attribute is set to 0
indicating that the job should not be queued, but be run immediately.
When this is the case, even jobs whose job load would push the
machine over its load limit will be run. However, it is important to
note that even when jobs have a priority of 0, job loads will still be
tracked on each machine. This is done so that jobs that do have
non-zero priorities will still be queued.

Using a previously defined machine named “fiat” with a max_load of

“100”, a simple queuing example would be as follows:
insert_job: jobA
machine: fiat
job_load: 80
priority: 1
insert_job: jobB
machine: fiat
job_load: 90
priority: 1

If “jobA” was running when “jobB” started, “jobB” would be in a

QUE_WAIT state until “jobA” completed and “jobB” could run.

Note • If a job is in the QUE_WAIT state and you want to run it

immediately, do not force start the job. To change the job queue
priority, use the sendevent command with the -E CHANGE_PRIORITY
option.

9 Queuing with Priority

When more than one job is queued, the priority value is considered first
when deciding which job to run next. If there are insufficient load units
(job_load value) available to run the highest priority job, it will remain
in the queue, and lower priority jobs will be considered subsequently.

■ 9-20 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Queuing Jobs

When there is no priority value assigned to a job (default is 0), there is

no queuing and AutoSys starts the job immediately. Therefore, the job
will never go into the QUE_WAIT state. If the job’s priority was set to run
immediately, the job would run regardless of the current load on the
machine. Obviously, this interferes with the load limiting feature, so
when load limiting is in use, the priority attribute should always be set.

In the case where a job has its job_load attribute set, the load value will
be reflected in the total load running on a machine. It is important to
note that if there is no job_load value set for a job, it will not be figured
into the total load units running on a machine.

Note • The constructs of job loads and machine loads are merely
conventions that you set up, and that are enforced by AutoSys. If you
do not indicate for AutoSys what the load of a job is, it will not figure
it into its queuing calculations. This is different from the load
balancing feature, which does inspect the CPU to determine its usage.

Figure 9-5 illustrates a situation where a machine has 80 load units, and
multiple jobs are waiting to start. In this example, “JobB” and “JobC” are
executing while “JobA” and “JobD” are “queued” (in the QUE_WAIT
state), waiting for available load units. The numbers in the figure indicate
the job_load assigned to each job, and the max_load of the machine. The
JIL statements provided below define the machine and the jobs.

EXECUTE
80

JobA JobB
50 50 max_load
JobD JobC
30 30

Figure 9-5 • Schematic of Queuing with Priority

AutoSys User Guide for UNIX 9-21 ■

■ Load Balancing and Queuing Jobs
Queuing Jobs

insert_machine: ferrari
max_load: 80
insert_job: JobA
machine: ferrari
job_load: 50
priority: 60
insert_job: JobB
machine: ferrari
job_load: 50
priority: 50
insert_job: JobC
machine: ferrari
job_load: 30
priority: 80
insert_job: JobD
machine: ferrari
job_load: 30
priority: 70

In the above scenario, “JobB” and “JobC” are already running because
their starting conditions were satisfied first. After “JobB” or “JobC” are
completed, “JobA” or “JobD” will start. Which job will start, “JobA” or
“JobD”, is determined by a combination of the priority and job_load
attributes of each job, and the max_load machine attribute. The resulting
scenario will differ, based on which job finishes first.

If “JobB” finishes first, 50 load units become available, so either “JobA”

or “JobD” could be run. Since “JobA” has a higher priority (lower value
= higher priority), it will run first. However, if “JobC” finishes first, only
30 load units become available, so only “JobD” could be run.

■ 9-22 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Queuing Jobs

9 Subsets—Individual Queues
One variety of virtual machine can be considered a subset of a real
machine. Typically, this type of virtual machine is used to construct an
individual queue on a given machine. One use for this construct might
be to limit the number of jobs, of a certain type, that will run on a
machine at any given time. For example, you have created three different
print jobs, but you want only one job to run on a machine at a time. You
can accomplish this by using a combination of the max_load attribute for
the virtual machine and the job_load attribute for the jobs themselves.

Figure 9-6 depicts a virtual machine functioning as a queue. The JIL

statements to define the queue, called “ferrari_printQ” follow the
graphic. Note that “ferrari” is a real machine.

ferrari_printQ
ferrari

15 80

Figure 9-6 • Virtual Machine used to Construct an Individual Queue

To implement the schema in Figure 9-6, you would first create the virtual
machine named “ferrari_printQ”, like this:
insert_machine: ferrari_printQ
machine: ferrari max_load: 15

AutoSys User Guide for UNIX 9-23 ■

■ Load Balancing and Queuing Jobs
Queuing Jobs

Next, you would define the three print jobs, like this:
insert_job: Print1
machine: ferrari_printQ
job_load: 15
priority: 1
insert_job: Print2
machine: ferrari_printQ
job_load: 15
priority: 1
insert_job: Print3
machine: ferrari_printQ
job_load: 15
priority: 2

Using this definition, only one of the jobs would run on “ferrari” at one
time, since each job requires all of the load units available on the
specified machine.

Load Units and Virtual Machines

It is important to note that the load units associated with a virtual
machine have no interaction with the load units for the real machine. In
the above example, this means that the virtual load of 15 does not
subtract from the load units of 80 for the real machine. Load units are
simply a convention which allows the user to constrict concurrent jobs
running on any one machine.

■ 9-24 AutoSys User Guide for UNIX

 Load Balancing and Queuing Jobs ■
Queuing Jobs

9 Multiple Machine Queues

Virtual machines can also be constructed to allow subsets (or slices) of
real machines to be combined into one virtual machine. A possible need
for this would be if there were two machines that were print servers, on
each of which only one print job was to run at a time. Figure 9-7
illustrates this situation.

ferrari lambo

15 80 15 120

Figure 9-7 • Virtual Machine Comprised of Subsets of Real Machines

To implement the above schema, you would first create the virtual
machine named “printQ”, then you would specify two real machines,
“ferrari” and “lambo” as shown in the following example:
insert_machine: printQ
type: v
machine: ferrari
max_load: 15
machine: lambo
max_load: 15

AutoSys User Guide for UNIX 9-25 ■

■ Load Balancing and Queuing Jobs
User-Defined Load Balancing

As a job is logically ready to start on printQ, AutoSys will determine if

there are enough load units available on either machine. If there are not,
it will place the job in the QUE_WAIT state, and start it when there are
enough load units. If there are enough units on only one machine, it will
start it on that machine. In the case that there are enough available load
units on both machines, AutoSys will determine the usage on each, and
start the job on the machine with the most available CPU resources.

9 User-Defined Load Balancing

As an alternative to using the provided load balancing methods described
in this chapter, you can write your own programs or scripts to determine
which machine to use at runtime. If you specify the name of a program
or script as the machine name in the job’s machine specification, the
Event Processor will execute the script at job runtime, and it will
substitute its output for the machine name. For example, you might
supply the following:
insert_job: run_free
machine: '/usr/local/bin/pick_free_mach'
command: $HOME/rm_stuff

At runtime, the script /usr/local/bin/pick_free_mach is run on the

Event Processor machine. The standard output will be substituted for the
name of the machine, and the job will be run on that machine.

Note • If you specify a user-defined load balancing script in the

machine attribute, you cannot use the priority or job_load job
attributes.

■ 9-26 AutoSys User Guide for UNIX

 10
The Operator Console
This chapter describes how to use the AutoSys Operator Console to
monitor and control job activity in real-time. It also describes the job
selection and reporting features of the console, as well as the Alarm
Manager. Customizing the Operator Console is also covered.
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4
Alarm Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4
InfoReports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5

Operator Console Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7

Starting the Operator Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7

Job Activity Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8

Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9
Job List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10
Currently Selected Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11
Starting Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14
Control Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15
Resizing Regions of the Job Activity Console . . . . . . . . . . . . . . . . . . . . . . . . 10-24

AutoSys User Guide for UNIX 10-1 ■

■ The Operator Console

Job Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-24

Specifying a Job by Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-25
Specifying Jobs by Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-27
Specifying Jobs by Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-28
Sorting the Specified Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-29
Setting the Job Selection Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-30

Changing the Console Clock Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-30

Alarm Manager Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-30

Alarm Manager Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-32
Alarm List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-32
Currently Selected Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-33
Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-34

Alarm Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-36

Select by Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-37
Select by State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-37
Select by Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-38

Customizing the Operator Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-38

Refresh Time Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-39
Alarm Poll Time Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-39
Changing Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-40
Freeze Frame at Start Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-40
Font Selection Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-41
Label Font Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-41
List Font Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-41
Object Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-42
Job List Column Widths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-45
Operator Console Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-46
Default Report Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-46
Alarm List Column Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-46

■ 10-2 AutoSys User Guide for UNIX

 The Operator Console ■

Operator Console Title bar Text and Icon Text . . . . . . . . . . . . . . . . . . . . . . . 10-47

User-Configurable Action Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-47
Console Clock Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-50

AutoSys User Guide for UNIX 10-3 ■

■ The Operator Console
Introduction

10 Introduction
The Operator Console provides a sophisticated method of monitoring
AutoSys jobs in real-time. The Operator Console lets you view any jobs
that are defined to AutoSys, whether they are currently active or not.

Job selection criteria, which you can dynamically change, allows you to
control which jobs you want to view based on various parameters, such
as the current job state, the job name (with wildcarding), and the
machine on which the job runs. You can select any job and view more
detailed information about it, including its starting conditions,
dependent jobs, and autorep reports. You can even invoke the Job
Definition dialog directly from this window and change the job, if the
correct permissions are set.

10 Alarm Manager
In addition to its job monitoring capabilities, the Operator Console
provides an Alarm Manager, which lets you monitor alarms as they are
generated. You can manage alarms by doing the following:

■ Entering responses directly at the Alarm Manager dialog.

■ Setting the alarm’s state to either acknowledged or closed. (If an

alarm’s state is “open” and you simply acknowledge it without closing
it, it will be set to “acknowledged.”)

Alarms and their responses are stored in the AutoSys database, from
which they can be retrieved for viewing, or for adding additional
responses. You can dynamically select which alarms you want to view
based on such criteria as alarm type, alarm state, and the date and time
range in which the alarm was generated.

■ 10-4 AutoSys User Guide for UNIX

 The Operator Console ■
Introduction

10 InfoReports
10

AutoSys provides a number of reports with details on AutoSys jobs which

you can view using the InfoReports GUI (either the one bundled with
AutoSys or your own InfoReports installation). The following types of
reports are available:

■ Job List. This report allows you to select the list of jobs to be reported
on or report on all jobs in the database. It shows almost everything
associated with a job.

■ Job Find. This report allows you to enter a pattern for the job name,
and report on all jobs that match the pattern. This is very similar to the
Job List report.

■ Last Run. This report allows you to enter the job name and get
information regarding the last run of the specified job.

■ Last n Run. This report allows you to enter the job name and get
information on the nth to last run of the job.

You access these reports by clicking on one of the user-configurable

action buttons in the Operator Console. (Enabling these buttons is
described in Accessing InfoReports from the Operator Console.) The buttons
can be configured to open any of the available reports.

Once you have defined these buttons, click one to run the report. When
you do this, the InfoReports Database Login dialog appears. In this
dialog, you enter information in the following fields:

■ In the Source Type drop-down menu, specify which database you are
using, either Sybase or Oracle.

■ In the User field, enter the AutoSys database user name.

■ In the Password field, enter the password for the AutoSys database
user.

■ In the Connection field, enter the Sybase database name (for Sybase)
or the TNS name (for Oracle).

AutoSys User Guide for UNIX 10-5 ■

■ The Operator Console
Introduction

Click OK after you have entered all the required information. The next
dialog to appear will very depending on the type of report to be
displayed. You will be asked to supply information, such as a job name
or a job run number. After processing these dialogs, the requested
information is read from the database and is displayed in an InfoReports
report.

Setting a Scrolling Buffer

To set the number of panels (pages) buffered for the InfoReports Print
Preview, you must modify the InfoReports prorep.prf file in your home
directory ($HOME). In the prorep.prf file, and add the following entry at
the end of the file:
"
[Buffer-Control]
Print-Preview-Panels=50
"

Where 50 is any integer greater than zero. It is the limit on the number
of panels to buffer. The default value is 3.

Refer to your InfoReports documentation for more information on using

InfoReports.

■ 10-6 AutoSys User Guide for UNIX

 The Operator Console ■
Operator Console Screens

10 Operator Console Screens

The Operator Console consists of the following elements:

Job Activity The primary interface to the Operator Console. This

Console console lets you monitor any AutoSys jobs.

Job Selection Used to specify which jobs you want to view.

dialog

Alarm Manager Allows you to browse any alarms which have

dialog occurred, and to acknowledge (and log a response
to) those alarms.

Alarm Selection Used to specify which alarms you want to view.

dialog

10 Starting the Operator Console

If you are reading this chapter for the first time, you should start the
Operator Console before continuing. This way you can follow along with
the descriptions in the following sections using your own system.

To start the Operator Console, use one of the following two methods
} At the UNIX prompt, enter the following command:
autocons &
Or
} At the GUI Control Panel, single-click on the Ops Console button.
The Job Activity Console appears.

AutoSys User Guide for UNIX 10-7 ■

■ The Operator Console
Job Activity Console

10 Job Activity Console

The first screen that displays when the Operator Console starts up is the
Job Activity Console, shown in Figure 10-1.

Figure 10-1 • Job Activity Console

■ 10-8 AutoSys User Guide for UNIX

 The Operator Console ■
Job Activity Console

The Job Activity Console has a menu bar and the following three regions:

■ Job List—Displays a list of all jobs stored in the database, subject to

the job selection criteria currently in effect.

■ Currently Selected Job—Displays more detailed information about

the currently selected job.

■ Control Area—The bottom portion of the Job Activity console is the

Control area. The left side of this area contains buttons that act on the
currently selected job; the middle contains buttons that act on the
console screen; the right side contains the Alarm button, which
displays the Alarm Dialog, and the Exit button to exit the Job Activity
Console.

By default the Job Activity Console starts up in Freeze Frame mode,

which prevents the display from regularly updating and refreshing. To
observe changes as they occur, click on the Freeze Frame button.

10 Menu Bar
At the top of the Job Activity Console is the menu bar, containing three
menus: File, View, and Options.

File menu Contains the Exit option, which functions exactly

like the Exit button in the Control area—it displays
a verification dialog asking you to confirm the exit.
If you confirm, the Job Activity Console is closed. If
the Alarm Manager was open, it will be closed as
well.

View menu Contains the Select Jobs option, which displays the
Job Selection dialog, discussed in Job Selection Dialog
on page 10-24.

AutoSys User Guide for UNIX 10-9 ■

■ The Operator Console
Job Activity Console

Options menu Contains the Console Clock Perspective option. You

have three choices: Server Time, Current Job Time,
or Local Machine Time. This option controls the
time perspective of the display, as discussed in the
Changing the Console Clock Perspective on page 10-30.

10 Job List
The Job List region displays a list of all the jobs that are defined to
AutoSys, subject to the job selection criteria currently in effect.

Each entry in the Job List contains the following information about a
single job:

■ Job name.

■ Description.

■ Current status.

■ Command that is defined for this job, if it is a command job. If it is a

file watcher job, the file to watch for appears in the Command
column. If it is a box job, the Command column is empty.

■ Machine on which the job ran or is currently running.

The entries in the Job List provide a snapshot of the entire system, across
multiple machines.

When you select a job from the list, the highlighted job becomes the
currently selected job, and more detailed information about the job
appears in the Currently Selected Job region.

To select a job
} Single-click on the job in the Job List display.
When you select multiple jobs, you can perform actions on all those jobs
at the same time.

■ 10-10 AutoSys User Guide for UNIX

 The Operator Console ■
Job Activity Console

To select contiguous multiple jobs

} Press and hold the mouse button and drag to select a group of jobs.

To select noncontiguous multiple jobs

} Hold the <Control> key and single-click on each job you want to
select. Holding the <Control> key and single-clicking on a selected job
will deselect that job.

To deselect all the currently-selected jobs

} Single-click anywhere in the job list.

Note • The Job List region has a scroll bar along the right-side for
scrolling through the job list. Using the X resource file, you can
configure the relative sizes of the columns in the Job List, as well as
the length of each field and the spacing between fields.

10 Currently Selected Job

The Currently Selected Job region displays information about the most
recent run (or the current run) of the currently selected job. If you have
selected multiple jobs, the first job you selected will be the currently
selected job. (Freeze Frame must be deselected in order for the
information in this region to update in real time.) In this region, you will
find the following fields:

Currently This field displays the name of the currently selected

Selected Job job.

Console Clock The console clock initially displays the current time
for the machine on which the Operator Console is
running. You can change this display by using the
Options menu (see Changing the Console Clock
Perspective on page 10-30) or by changing the setting
in the resource file (see Console Clock Perspective on
page 10-50).

AutoSys User Guide for UNIX 10-11 ■

■ The Operator Console
Job Activity Console

Description If the job definition includes the description

attribute, the text appears in this field.

Command If the currently selected job is a command job, the

command appears here. If it is a file watcher, the file
it is watching for appears here. If it is a box job, this
field is blank.

Start Time The start time of the current or most recent run of the
job.

End Time The end time of the most recent run of the job. If the
job is currently running, this field will be blank.

Run Time How much time elapsed between the start and end
of the most recent run of the job. If the job is
currently running, this field will be blank.

Status The current status of the job.

Exit Code The exit code from the most recent run of the job.

Next Start If the job has date and time starting conditions, this
field shows when the next run of the job is
scheduled to start.

Machine The name of the machine on which the job ran or is

currently running. If a job is defined to run on a
virtual machine, the name of the real machine
component on which it actually ran will appear
here.

Queue Name If the job is queued to start on a machine, the name

of that machine appears here.

Priority If the job is queued to start on a machine, its priority

in the queue appears here.

Num. of Tries If the job had to be restarted, the number of times it

was started appears here.

■ 10-12 AutoSys User Guide for UNIX

 The Operator Console ■
Job Activity Console

10 Starting Conditions
The Starting Conditions area displays the job’s entire starting condition,
as specified in its job definition, as well as the “atomic” conditions—the
most basic components of an overall condition. This information is very
useful when troubleshooting a job.

For example, in the sample Job Activity Console shown in Figure 10-1 on
page 10-8, the job named “DripCoffee” has a starting condition called:

■ SUCCESS(Grinder) and SUCCESS(BoilWater)

This starting condition is specified in the job’s definition. However, this

starting condition is actually composed of the following two atomic
conditions:

■ SUCCESS(Grinder)

■ SUCCESS(BoilWater)

In the Starting Conditions area, each atomic condition is displayed with

the Current State of the job upon which it is based; in our example,
“Grinder” and “BoilWater,” respectively. Also, a “True/False” flag is
provided that indicates whether or not that atomic starting condition has
been satisfied.

If a job has not run within the time frame it was expected to, you would
select the job from the Job List and check its starting conditions to
quickly determine what “upstream” job might be preventing it from
running.

The atomic condition list is selectable. By single-clicking on any one of

the atomic conditions, the job associated with that condition will
become the currently selected job, and its details will be displayed in the
middle region of the screen. This feature allows you to quickly step
through upstream dependencies, checking out each job along that path.

AutoSys User Guide for UNIX 10-13 ■

■ The Operator Console
Job Activity Console

10 Reports
The Reports area displays a real-time report, and it is also included in the
Currently Selected Job region is. This report presents job run information
in the same format as that produced by the autorep command. You can
choose from the following report types:

Summary A one-line synopsis of the last or current execution

of the job showing the job name, timestamp of the
last start and last end of the job, status, job run
number and number of tries (separated by a slash),
and priority (if the job is in QUE_WAIT status) or
exit code (if the job completed).

Event A detailed report listing all the events and statuses

from the last or current execution of the job. The
illustration on page 10-8 shows an Event Report.

None Does not display a report.

Summary and Event reports will be run automatically each time the
dialog is refreshed. The default refresh interval is every 5 seconds, but the
interval is user-configurable. If the Event report is chosen, you can watch
the real-time progression of a job, observing, as they occur, the arrival of
the various events, such as the job starting, running, completing, and
restarting.

■ 10-14 AutoSys User Guide for UNIX

 The Operator Console ■
Job Activity Console

10 Control Area
The bottom region of the Job Activity Console is the Control area.

Action Buttons
On the left side of this region is a group of push buttons that can be
pressed to initiate certain actions on the currently selected job or jobs. By
pressing the appropriate button, you can issue an event that will:

■ Start a job

■ Kill a job

■ Force a job to start

■ Place a job on hold

■ Take a job off hold

In each of these cases, a dialog box asks you to confirm, after which the
action is taken immediately, without requiring you to perform any
further actions. If you have initiated an action on multiple jobs, the
dialog will display the following:
“Ready to send event event for # jobs”
where:
event
Is the action you chose.
#

Is the number of jobs that are selected.

When you click the Send Event button, the Send Event dialog displays,
and it allows you to send any type of event.

AutoSys User Guide for UNIX 10-15 ■

■ The Operator Console
Job Activity Console

In the last column are buttons that are user configurable. You can
associate any command with these buttons, and specify your own button
labels. This process is explained in User-Configurable Action Buttons on
page 10-47.

Send Event Dialog

The Send Event dialog box provides you the means to do the following:

■ Send any event that can be sent manually in AutoSys.

■ Select the various event parameters you want to specify when sending
the event.

■ Cancel an event that has been scheduled to occur in the future.

Note • The fields of the Send Event dialog correspond to sendevent

command options. For a complete description of these options, see
the sendevent description in Chapter 1, AutoSys Commands, of the
AutoSys Reference Guide for UNIX.

The Send Event dialog is shown in Figure 10-2.

■ 10-16 AutoSys User Guide for UNIX

 The Operator Console ■
Job Activity Console

Figure 10-2 • Send Event Dialog

You specify an event using one of the radio buttons at the top of the
dialog. Just below these buttons is the Job Name field, which by default
contains the name of the currently selected job. You can change this field
if desired.

You can specify when the event is to take effect, either Now (the default),
or at some future time and date. (The current time and date are provided
as examples of the required format.) Use the A.M. and P.M. radio buttons
if you want to specify the time using a 12-hour format. If the time field
contains an hours setting that is less than 13, it is considered a.m., while
any larger value is considered p.m.

The Comment field is a free-form field in which you can enter any text
you want to associate with this event in the database; this field is for
documentation purposes only. For example, if you force a job to start,
you might provide an explanation about why this was necessary.

AutoSys User Guide for UNIX 10-17 ■

■ The Operator Console
Job Activity Console

The AUTOSERV instance field displays the current AutoSys server

identifier; only when events need to be sent to a different AutoSys
instance should this field be changed.

The Global Name and Global Value fields are used when you have
specified a SET_GLOBAL event. Global Name and Global Value can each
be a maximum of 30 characters.

The Signal field is used to specify the signal number if you specified a
SEND_SIGNAL event.

The Queue Priority field is used only when you have specified a
CHANGE_PRIORITY event. This affects the run priority of a job that is in
QUE_WAIT state.

You can only make a selection from the Status pull-down menu if the
Change Status event type (radio button) has been selected. This menu
lets you select a new status for the currently selected job.

Use the Send Priority radio buttons to specify whether the event is to be
sent with normal priority (the default), placing the event in the queue
with all system-generated events, or with high priority, placing it at the
top of the event queue. The latter is normally reserved for emergencies,
such as killing a job.

The Execute button of the dialog executes, or sends, the event. The Cancel
button cancels the event that was about to be sent. When either button is
pressed, the Send Event dialog is dismissed.

■ 10-18 AutoSys User Guide for UNIX

 The Operator Console ■
Job Activity Console

Cancelling a Sent Event

At the Send Event dialog, you can cancel one or more events scheduled
to occur sometime in the future. You can do this in one of two ways: by
cancelling a specific event or by cancelling a specific event type for a
specific scheduled time.

Note • You should use this feature to cancel events that you have sent
from the Send Event dialog. If you want to override a scheduled
starting condition for a job, you should use the one time override job
attribute, either from the Job Definition dialog or from JIL.

To cancel a specific event

1 In the Event Type region, specify an event type by selecting one of the
radio buttons.

Note • You can select multiple jobs in the Job Activity Console
before you open the Send Event dialog. If you do so, the Send Event
dialog will send this cancel event for all of the selected jobs that
meet the Event Type criteria.

2 Select the Cancel Previously Sent Event radio button.

3 In the Job Name field, enter the job name.

4 Single-click on the Execute button. This process cancels all pending

events of the specified Event Type for the selected job(s).

AutoSys User Guide for UNIX 10-19 ■

■ The Operator Console
Job Activity Console

To cancel a specific event by its scheduled time

1 Make sure you have the appropriate job in the Job Name field.

Note • You can select multiple jobs in the Job Activity Console
before you open the Send Event dialog. If you do so, the Send Event
dialog will send this cancel event for all of the selected jobs that
meet the Event Type and Time criteria.

2 In the Event Type region, specify an event type by selecting one of the
radio buttons.

3 Select the Cancel Previously Sent Event radio button.

4 Select the Match on Time radio button.

5 In the Time field (of the Future region), specify the time the event is
scheduled to occur.

6 Single-click the Execute button. This cancels all pending events of the
specified Event Type at the specified Time for the selected job(s).

Notes on Cancelling a Send Event

The Cancel Previously Sent Event feature is designed to be used primarily

on events the that you have sent from the Send Event dialog. If you want
to override a scheduled starting condition for a job, you should use the
one time override job attribute, either from the Job Definition dialog or
from JIL.

If you cancel a future Start Job event for a time-dependent job with no
other starting conditions, the job may never run again without manually
starting it with a Send Event command. For example, “jobA” is scheduled
to run daily at 11:00. “jobA” starts at 11:00 on Monday and completes at
11:30, at which time the next future Start Job event is sent for 11:00
Tuesday. At 9:00 on Tuesday, you cancel the 11:00 Start Job event. The
job not only does not run at 11:00 on Tuesday, but it will not be
scheduled to run again. To restart the job, you can either update its job
definition, or manually issue a Start Job Send Event.

■ 10-20 AutoSys User Guide for UNIX

 The Operator Console ■
Job Activity Console

Control Buttons
In the middle of the Control area, there are several push buttons that
provide you with control functions for the Console screen. The Job
Definition button displays the Job Definition dialog with the currently
selected job already displayed. This allows you to quickly review the job’s
definition, and change it if necessary (and if permissions allow).

The Dependent Jobs button displays the Dependent Jobs dialog that
contains a list of all the jobs directly dependent on the currently selected
job. This allows you to quickly see which jobs will be affected by the
current job; in particular, which jobs will not run until the current job
completes. This is useful if the currently selected job is running late and
you need to determine which other jobs will be affected.

Figure 10-3 shows the Dependent Jobs dialog for the job “BoilWater.” As
with the atomic conditions list, any job in this Dependent Jobs List can
be selected, making it the currently selected job (and dismissing the
dialog).

The Dependent Jobs dialog can be dismissed by pressing the Close

button, or by selecting another job in the Job Activity Console.

Figure 10-3 • Dependent Jobs Dialog Box for the Job “BoilWater”

AutoSys User Guide for UNIX 10-21 ■

■ The Operator Console
Job Activity Console

This feature allows you to arbitrarily follow the chain of job

dependencies far downstream, and to determine which jobs are in some
way dependent on a another job.

The Freeze Frame button freezes the Console display, which otherwise is
regularly updated. By default it is updated every 5 seconds; this refresh
interval is user-configurable. In Freeze Frame mode, all processing
continues normally, but the screen is not refreshed. This feature is useful,
for instance, when you are viewing the Event Report’s output and the
display has scrolled through some of the output. A refresh operation
would reset the report display to the first line of output, forcing you to
scroll back to the area that you were viewing. When the Freeze Frame
button is toggled back off, the Console once again reflects the current
state of the system.

There is a user-configurable X resource that causes the Operator Console

to start in Freeze Frame mode—this is the installation default. For more
information about customizing the Operator Console, see Customizing
the Operator Console on page 10-38.

The three Report buttons let you choose the type of report you want to
view, as described earlier in this section. You can specify a default report
type using the X resources, see Default Report Type on page 10-46.

Job Path (History) Dialog

When you single-click on a job in the atomic conditions list or in the
dependent jobs list (thereby changing which job is the currently selected
one), the Job Path (History) dialog appears. This dialog contains a list of
all the jobs selected since the last time a job was selected directly from the
Job List, in the order in which they were selected.

Assuming that you had single-clicked on the atomic condition for

“BoilWater” while displaying the “DripCoffee” job, the new currently
selected job would be “BoilWater”, and the Job Path (History) dialog
would display with the appropriate entries for both of the jobs you have
traversed since your last selection from the Job List.

Figure 10-4 shows a Job Path (History) dialog box with these entries.

■ 10-22 AutoSys User Guide for UNIX

 The Operator Console ■
Job Activity Console

Figure 10-4 • Job Path (History) Dialog

Using the this dialog, you can quickly return to any previously selected
job by single-clicking on the job’s name.

Alarm Button
The large Alarm button serves both as an indicator that a new alarm has
been detected and as way to display the Alarm Manager dialog. When a
new alarm occurs, the Alarm button changes to the color red. When this
happens, and you press the button, its color returns to green, and the
Alarm Manager dialog is displayed. If the Alarm Manager dialog is
already on the screen, but is obscured by the Job Activity Console,
pressing the Alarm button will bring the Alarm Manager dialog to the top
of the display. The Alarm button can also be used to update the Alarm
Manager dialog, even if Freeze Frame is in effect.

Exit Button
The Exit button is used to close the Job Activity Console, including the
Alarm Manager. When this button is pressed, a verification dialog
displays asking you to confirm the exit.

AutoSys User Guide for UNIX 10-23 ■

■ The Operator Console
Job Selection Dialog

10 Resizing Regions of the Job Activity Console

The resizing handles of the Job Activity Console let you move the
boundary lines between the three regions of the window. You change
these boundaries using the small square handle at the right edge of each
region’s horizontal separators; these separators are blue by default.

To adjust a boundary, you simply click and hold on a resizing handle and
drag it up or down. By doing so, your screen display can be adjusted to
reveal more jobs. For example, you can borrow display space from the
Currently Selected Job region, and even the Control area, to view more
jobs in the Job List. In fact, if the upper handle is pulled all the way down
to the bottom of the Console screen, the entire Job Activity Console can
be used to display the Job List. You can expose the buttons in the Control
area later by pulling the lower handle back up. (You can alter the Job
Activity Console display size using the resizing handles surrounding the
dialog as well.)

10 Job Selection Dialog

The Job Selection dialog provides a way to specify which jobs you want
to view, filtering out all other jobs. You specify the jobs you want to view
by name, job status, and machine on which the job ran (or is currently
running).

To display the Job Selection dialog

} From the Job Activity Console, choose View } Select Jobs.
The Job Selection dialog appears, as shown in Figure 10-5.

■ 10-24 AutoSys User Guide for UNIX

 The Operator Console ■
Job Selection Dialog

Figure 10-5 • Job Selection Dialog

10 Specifying a Job by Name

If you select the All Jobs option, all jobs are selected, ignoring any entries
in the Job Name or Box Name field. However, you can select jobs by
name.

AutoSys User Guide for UNIX 10-25 ■

■ The Operator Console
Job Selection Dialog

When specifying a job name in the Job Name field, you can enter either
the entire name or a partial name with the asterisk ( * ) wildcard
character representing one or more characters. You can use this wildcard
in more than one character position. For example, specifying the job
name “*a*” would match the jobs “Dad”, “Bead”, “Bat”, and so forth.

In a similar fashion, you can specify a box name in the “Box Name” field
to select all jobs in the specified box.

Note • If you use the wildcard character to specify all box names, and
a box has other boxes inside of it, the name of the nested box job will
be listed multiple times in the Job List.

The Box Levels field lets you indicate how many levels of nesting you
want to view for a box job. You can enter any valid positive number.

0 Indicates that only the top-level box specified in the Box

Name field is to be displayed.

1 Indicates that the box specified in the Box Name field and
only the first level nesting of its direct descendents are to
be displayed.

All Indicates that the box specified in the Box Name field and
all of its direct descendents (including nested boxes and
the jobs in those boxes) are to be displayed. This is the
default.

■ 10-26 AutoSys User Guide for UNIX

 The Operator Console ■
Job Selection Dialog

When selecting jobs based on box name, each level of box/job will be
indented two spaces to indicate the nesting. This convention is shown in
the Job List in Figure 10-6.

Figure 10-6 • Job List—Box Job with Nesting

10 Specifying Jobs by Status

From the Job Selection dialog, you can select jobs based on their current
status, such as STARTING, RUNNING, INACTIVE, and so forth. The
default is to display all job statuses. You can select any combination of
the statuses. All Statuses overrides any specific status selections.

AutoSys User Guide for UNIX 10-27 ■

■ The Operator Console
Job Selection Dialog

10 Specifying Jobs by Machine

From the Job Selection dialog, you can select jobs based on the name of
the machine on which it ran (or is currently running). On the right side
of this dialog is a list of all the machines that are referenced in any job or
machine definition, or which have run an AutoSys job. From this list, you
can choose one, several, or All Machines (the default).

Note • Virtual machines will appear in this list, but cannot be used to
select jobs because jobs can run only on real machines.

Selecting Machines

To choose a single machine

} Single-click on that machine.

To choose a range of machines

} Click and hold on the first machine name, drag the cursor to the last
name, then release the mouse button.

To choose additional machines after the initial selection

} Hold down the <Control> key and perform the actions above.

To choose all machines

} Select the All Machines option.

■ 10-28 AutoSys User Guide for UNIX

 The Operator Console ■
Job Selection Dialog

10 Sorting the Specified Jobs

The Job Selection dialog lets you specify the sort order in which the jobs
should be listed. You can choose one of the following sort criteria:

Start Time The starting time for the most recent execution of the
job.

End Time The ending time for the most recent execution of the
job.

Job Name Jobs will be sorted by name in ascending

alphanumeric order.

Job Status Jobs will be sorted by their current status, in

ascending alphabetical order.

Machine Name Jobs will be sorted by the machine on which they

run or have been run, in ascending alphabetical
order.

Unsorted Displays the jobs in the order in which they were

created; that is, the order in which they exist in the
AutoSys database. You should choose this option
when selecting jobs by box name, because their
creation order usually has some significance;
especially as this pertains to the running order of
jobs inside of boxes. If any sorting is done, the
indenting of the various nesting levels has no
meaning, nor is there any indication of which jobs
are in which box.

AutoSys User Guide for UNIX 10-29 ■

■ The Operator Console
Changing the Console Clock Perspective

10 Setting the Job Selection Criteria

To make the job selection criteria take effect
} Click OK, which also dismisses the dialog.
Or
} Click Apply, which does not dismiss the dialog.
Clicking the Cancel button dismisses the Job Selection dialog without
changing the selection criteria.

10 Changing the Console Clock Perspective

The Options menu of the menu bar contains a single option, Console
Clock Perspective. You have three choices: Server Time, Current Job
Time, or Local Machine Time. This option controls the time perspective
of the display.

Note • The Console Clock Perspective does not change the Start Time
and End Time displays in the Currently Selected Job region.

Server Time displays the time based on the time zone of the AutoSys
server machine. Current Job Time displays the time using the time zone
specified in the job definition (the timezone attribute); if no time zone is
set for the job, then the server machine time is used. Local Machine Time
displays the time in the time zone of the machine on which the Operator
Console is running.

10 Alarm Manager Dialog

The Alarm Manager lets you view alarms as they arrive, acknowledge
them, and change their status from Open to Acknowledged or Closed.
This feature provides a useful tracking mechanism for all the alarms
issued on your system.

■ 10-30 AutoSys User Guide for UNIX

 The Operator Console ■
Alarm Manager Dialog

To display the Alarm Manager dialog

} Press the Alarm button in the lower-right corner of the Job Activity
Console.
The Alarm Manager dialog appears, as shown in Figure 10-7.

Figure 10-7 • Alarm Manager Dialog

The Alarm Manager dialog has a menu bar and the following three
regions:

Alarm List At the top of the dialog.

Currently Selected Alarm In the middle of the dialog.

Control At the bottom of the dialog.

AutoSys User Guide for UNIX 10-31 ■

■ The Operator Console
Alarm Manager Dialog

10 Alarm Manager Menu Bar

The Alarm Manager menu bar, at the top of the dialog, contains two
menus: View and Options.

View menu Provides two options: Select Alarms and Reset to

Defaults. The Select Alarms option displays the
Alarm Selection dialog (discussed on page 10-36).
The Reset to Defaults option resets the alarm
selection criteria to their default settings and updates
the Alarm Manager dialog to reflect the new
selection criteria.

Options menu Contains the single selection, Sound On. The

“Sound” feature plays sound clips associated with
alarms whenever a new alarm is generated. This
option is a toggle switch which can be turned on and
off by single-clicking on the option.

10 Alarm List
The Alarm List region of the dialog displays a list of all the alarms that are
currently in the system, and that meet the viewing criteria specified by the
user, which may include closed alarms. The default is to display all Open
and Acknowledged alarms, of any type, regardless of the time they were
generated.

Each entry in the Alarm List contains the following information about a
single alarm:

■ Alarm type.

■ The job for which the alarm was generated.

■ Date and time at which the alarm was generated.

■ The alarm’s current state.

■ Any comment associated with the alarm at the time it was generated.

■ 10-32 AutoSys User Guide for UNIX

 The Operator Console ■
Alarm Manager Dialog

Alarms are displayed in reverse order of occurrence; the newest alarms

appear at the top of the list and older ones appear farther down. An alarm
is made the currently selected alarm by single-clicking on it anywhere on
the line on which it is displayed.

Selecting multiple alarms allows you to perform actions on multiple

alarms at once.

To select multiple alarms

} Press and hold the mouse button and drag to select a group of alarms.
Or
} Hold the <Control> key and single-click on each alarm that you want
to select. Holding the <Control> key and single-clicking on a selected
alarm will deselect the alarm.
Single-clicking anywhere in the alarm list will deselect all currently-
selected alarms.

Note • You can configure the widths of the columns in the Alarm List
using the X resource file, described in the Alarm List Column Width on
page 10-46.

10 Currently Selected Alarm

The Currently Selected Alarm region of the dialog displays the currently
selected alarm, and lets you enter a response in the Response edit box.

The Response edit box accepts multiple lines of text. The entered text is
automatically word-wrapped, with lines breaking at appropriate spaces.
You can use the mouse to edit text. In addition, you can use the arrow
and backspace keys as well as the <Tab> and <Enter> keys.

The User field, beneath the Response edit box, shows the user who
invoked the Alarm Manager. This read-only field shows which user
responded to the alarm field.

AutoSys User Guide for UNIX 10-33 ■

■ The Operator Console
Alarm Manager Dialog

The Alarm State region lets you change the alarm state to Acknowledged
or Closed. Once an alarm is changed from the Open state, you cannot put
it back in the Open state.

10 Control
The third region of the Alarm Manager dialog is the Control region, at the
bottom of the dialog. In this region, there are several buttons used to
control the Alarm Manager. They are:

■ Freeze Frame

■ Select Job

■ New Alarm

Freeze Frame Button

As in the Job Activity Console, the Alarm Manager is automatically
updated at regular intervals. The Freeze Frame button suspends this
automatic refreshing of the screen, keeping the Alarm List static while
you are working on it. The currently selected alarm will remain displayed
until another alarm is selected, even when the dialog is being updated; as
a result, responses can be entered uninterrupted. The Freeze Frame
feature is particularly useful when scrolling through the Alarm List, since
newly arriving alarms are added at the top of the list, and the list scrolls
back to the top each time the display is refreshed.

Select Job Button

The Select Job button causes the job associated with the currently selected
alarm (if there is one) to become the currently selected job on the Job
Activity Console. This is useful when you want to review the details of the
job for which the alarm was generated. In the example in Figure 10-7, the
currently selected alarm is associated with the job “AlarmClock”.
Therefore, pressing the Select Job button in the Alarm Manager will
caused “AlarmClock” to become the currently selected job in the Job
Activity Console. This operation will also update the Job Path (History)
dialog (discussed on page 10-22) in the process.

■ 10-34 AutoSys User Guide for UNIX

 The Operator Console ■
Alarm Manager Dialog

New Alarm Button

The New Alarm button serves the same purpose as the Alarm button on
the Job Activity Console. This button turns red when a new alarm arrives,
which is particularly useful when the Alarm Manager is not refreshing
(when the Freeze Frame feature is in effect).

When you press either the New Alarm button on this dialog, or the Alarm
button on the Job Activity Console, the Alarm List is updated and both
of these buttons are reset to green, even if the Freeze Frame feature is on.

Even when this dialog is refreshing regularly, the New Alarm button can
serve as an indicator that a new alarm has arrived.

When the alarm selection criteria is restrictive enough to filter out the
new alarm, a warning dialog displays when the New Alarm button is
pressed. This dialog offers to reset the selection criteria to the defaults;
this will ensure that any new alarms that are generated will be displayed.
Regardless of whether or not you accept this option, the New Alarm
button’s color will be reset to green.

Registering Responses and Changing Alarm States

To register a response or change the state of an alarm in the AutoSys
database, you must explicitly save the alarm.

To save an alarm to the database

} Click OK. This action dismisses the Alarm Manager.
Or
} Click Apply. This action does not dismiss the Alarm Manager.

To dismiss the Alarm Manager without saving any changes

} Click Cancel.
Typically, you would use the Apply button to register changes, since the
Alarm Manager would probably be running on a continual basis.

AutoSys User Guide for UNIX 10-35 ■

■ The Operator Console
Alarm Selection Dialog

10 Alarm Selection Dialog

The Alarm Selection dialog lets you dynamically control which alarms
are displayed. Alarms can be selected by type of alarm, state of alarm
(Open, Acknowledged, or Closed), and by the date and time of the
alarm’s occurrence.

Note • Alarms that have been archived cannot be displayed.

To display the Alarm Selection dialog

} Select View } Select Alarm at the top of the Alarm Manager dialog. The
Alarm Selection dialog appears, as shown in Figure 10-8

Figure 10-8 • Alarm Selection Dialog (with Default Settings)

■ 10-36 AutoSys User Guide for UNIX

 The Operator Console ■
Alarm Selection Dialog

The Alarm Selection dialog is divided into three regions, described in the
next sections:

■ Select by Type

■ Select by State

■ Select by Time

10 Select by Type
In the Select by Type region of the dialog, a list of all possible alarm types
is displayed. From this list, you can select one, several, or all types of
alarms. The default is All alarm types.

To choose a single alarm from the list

} Single-click on the alarm’s name.

To choose a range of alarms

} Click and hold the mouse button on the first alarm name, drag the
cursor to the last alarm in the range, and release the mouse button.

To choose noncontiguous alarms

} Hold down the <Control> key and single click on the desired alarms.
Hold down the <Control> key and single-click a selected alarm to
deselect the alarm.

To choose all alarm types

} Select the All Types option, which overrides any more-specific
settings.

10 Select by State
You can also select alarms by the state of the alarm. You can select any or
all of the states by toggling on the appropriate buttons, or the All States
toggle. The default is to display all Open and Acknowledged alarms.

AutoSys User Guide for UNIX 10-37 ■

■ The Operator Console
Customizing the Operator Console

10 Select by Time
By default, alarms are shown regardless of the time they were generated.
You can choose to display only alarms that were generated during a
specific date and time window. Fields are provided to specify a From
Date, From Time, To Date, and To Time. You can specify dates without
times. However, you cannot specify times without dates.
The current system date and time are automatically filled in for your
convenience. You use a 24-hour format when specifying times.

To make the alarm selection take effect

} Choose OK. This sets your selections and dismisses the Alarm
Selection dialog.
Or
} Choose Apply. This sets your selections without dismissing the dialog.

To dismiss the dialog without applying the selections

} Choose Cancel.

10 Customizing the Operator Console

You can use a set of X resources to customize the appearance and
behavior of the Operator Console. In particular, these resources allow
you to control:

■ The interval between database reads to refresh the displays.

■ The fonts and colors that are used in the Job Activity window as well
as the Operator Console dialogs.
■ How many characters of certain fields should be displayed.
■ Whether or not the Operator Console starts up in Freeze Frame mode.
■ The Operator Console GUI icon text and the Operator Console title
bar text.
■ User-configurable action buttons.

■ 10-38 AutoSys User Guide for UNIX

 The Operator Console ■
Customizing the Operator Console

Descriptions of each of the resources which can be customized are given

below. All of these can be set by modifying the X resource file Autocons.
The X resources files reside in the local app-defaults directory, which
varies across platforms. It is usually in /usr/lib/X11/app-defaults or
/usr/openwin/lib/app-defaults. If you are not sure which directory
these files are in, ask your system administrator.

Individual users may have their own copy of the X resources files in their
$HOME directory, which will take precedence over the app-defaults files.

For most operating systems, if you are exporting the display to another
machine you must edit the appropriate files in the app-defaults
directory on the local machine.

For Solaris, you must edit the files in both the /usr/lib/X11/
app-defaults and /usr/openwin/lib/app-defaults directories. The files
in /usr/lib/X11/app-defaults control the resources when you export the
display.

We have listed the various resource names here as a reference only. For
the default values, see the Autocons file. The provided resource file values
work well for a majority of platforms.

10 Refresh Time Interval

The following resource controls the time interval after which the
Operator Console will be refreshed (specified in milliseconds).
*refreshTime:

10 Alarm Poll Time Interval

The following resource controls the time interval after which the database
will be searched for the arrival of new alarms, and the Alarm Manager
will be refreshed (specified in milliseconds).
*pollTime:

AutoSys User Guide for UNIX 10-39 ■

■ The Operator Console
Customizing the Operator Console

10 Changing Fonts
The fonts used in the Operator Console fall into the following three
categories:

■ Those you can choose, independent of other fonts.

■ Bold fonts which must correlate with normal fonts.

■ Normal fonts which must correlate with bold fonts.

Several of the lists in the Operator Console present information in

columns, such as the Job List, which displays the job name, command,
etc. In order to maintain the appropriate spacing for these columns, all
characters in each field must be the same width. Therefore, fixed-format
fonts must be specified for all column-oriented lists.

In order for the labels at the top of the columns to align with the columns
themselves, those labels must also use fixed-format fonts, in the same
size and style. We recommend that a bold-faced font be used for the
labels, so that they are consistent with the other, non-list field labels
(unless, of course, you have chosen a non-bold font for everything).

The font chosen for the column data should be a non-bold version of the
same font used in the labels.

Note • The model X resources file provided specifies values that work
well for each of the SunOS and AIX platforms.

10 Freeze Frame at Start Up

The following resource controls whether or not the Operator Console
starts up in Freeze Frame mode, where “1” is true (the default) and “0” is
false:
*FreezeAtStartup: 1

■ 10-40 AutoSys User Guide for UNIX

 The Operator Console ■
Customizing the Operator Console

10 Font Selection Resources

The following resource specifications control font selection. They are
completely independent of any other font settings:
*.fontList:
*XmTextField.fontList:
*XmText.fontList:

10 Label Font Resources

The following label resources should be the same, for consistency across
the application. They should also be fixed and be of the same type as the
list fonts given below, except that those probably shouldn’t be bold.
*jobListForm*jobListLabel.fontList:
*dependHeadLabel*fontList:
*atomicsForm*atomicsLabel.fontList:
*alarmListForm*alarmListLabel*fontList:

10 List Font Resources

The following list resources should be the same, for consistency across
the application. They should also be fixed and be of the same type as the
label fonts above, except that these probably shouldn’t be bold (typically
called “medium”).
*jobListForm*fontList:
*dependList*fontList:
*atomicsForm*fontList:
*alarmListForm*fontList:

AutoSys User Guide for UNIX 10-41 ■

■ The Operator Console
Customizing the Operator Console

The following resources do not necessarily relate to other fonts, but

should match the non-bold font of the list fonts above, for consistency
across the application.
*pathList*fontList:
*alarmCurrentText*fontList:

10 Object Color
The following resources affect the colors of the various objects within the
Operator Console. We recommend that the default colors be used, since
they match those used in the main AutoSys graphical user interface.

Currently Selected Job Name Field

The following resource controls the “currently selected” job name field,
and should be a different color from the rest of the interface, for
emphasis.
*workAreaForm*XmForm*currJobName.background:white

■ 10-42 AutoSys User Guide for UNIX

 The Operator Console ■
Customizing the Operator Console

Background Color of Variable Fields

The following resources control the background color of the variable
fields found in the interface, such as lists and text values, which change
based on user interactions.
*workAreaForm*XmForm*XmText.background:
*workAreaForm*XmForm*XmTextField.background:
*workAreaForm*XmForm*XmList.background:
*workAreaForm*XmForm*XmScrolledList.background:
*workAreaForm*XmForm*XmScrolledText.background:
*workAreaForm*XmPanedWindow*XmForm*
XmScrolledWindow.background:
*XmDialogShell*XmTextField.background:
*XmDialogShell*XmText.background:
*XmDialogShell*XmList.background:
*selection_dialog*XmTextField.background:
*selection_dialog*XmList.background:
*depend_dialog*XmList.background:
*path_dialog*XmList.background:
*alarm_dialog*XmTextField.background:
*alarm_dialog*XmText.background:
*alarm_dialog*XmList.background:

AutoSys User Guide for UNIX 10-43 ■

■ The Operator Console
Customizing the Operator Console

Border Colors
The following resources set the decorative dark blue borders of the
interface:
*workAreaForm.background:
*workAreaForm*XmPanedWindow.background:
*workAreaForm*controlForm*XmSeparator.background:

Primary Interface Color

The following resources set the primary interface color, medium gray:
*workAreaForm*XmForm*background:
*menuBar*background:
*exitDialog*background:
*XmDialogShell*background:
*selection_dialog*background:
*depend_dialog*background:
*path_dialog*background:
*alarm_dialog*background:

Toggle Button Color

The following resource sets the toggle button color used to indicate that
the toggle button is “on”:
*selectColor:

■ 10-44 AutoSys User Guide for UNIX

 The Operator Console ■
Customizing the Operator Console

10 Job List Column Widths

The following resources set the lengths of the various fields (columns) in
the Job List of the Job Activity Console. Specify a number of characters.
(The lines beginning with # are comments.)
#job name:
*nameLength:
#job description:
*descLength:
#job status:
*statusLength:
#command to be executed, according to job
#definition:
*commandLength:
#machine job is (or was) associated with, when it
#runs (or ran):
*machineLength:
#spacing between columns in all lists:
*fieldSpacing:

Atomic Condition Fields

The following resources apply to the atomic conditions in the Job Activity
Console—the fields which describe a starting condition at its most basic
level:
#length of condition (such as “SUCCESS(JOBA)”):
*atomicCondLength:
#length of current state (eg, “SUCCESS”):
*atomicStateLength:
#length of true/false flag - whether the current
#state satisfies the condition:
*atomicTFLength:

AutoSys User Guide for UNIX 10-45 ■

■ The Operator Console
Customizing the Operator Console

10 Operator Console Size

The following two resources force the Console size to be a specified width
and height. Keep in mind that this will override the resizing that occurs
as a function of the chosen font.
*maxAppWidth:
*maxAppHeight:

10 Default Report Type

The following resource specifies the default report type to be run for the
currently selected job, at each Console refresh. Options are: None,
Summary, and Detail.

*reportType:

10 Alarm List Column Width

The following resources determine the widths of the columns in the
Alarm List. Specify a number of characters.
#Length of type of alarm (eg. JOBFAILURE):
*alarmTypeLength:
#Length of name of the job which generated the #alarm:
*alarmJobNameLength:
#Length of mm/dd/[yy]yy hh:mm time stamp of alarm
#occurrence:
*alarmTimeLength:
#Length of alarm state - open, acknowledged, or
#closed:
*alarmStateLength:
#Length of system-generated comment:
*alarmCommentLength:

■ 10-46 AutoSys User Guide for UNIX

 The Operator Console ■
Customizing the Operator Console

10 Operator Console Title bar Text and Icon Text

The following resources specify the title bar text and the icon text. By
default the title bar text is “Job Activity Console” and the icon text is
“JAC”.
Autocons.shellTitle:
Autocons.iconTitle:

Note • When changing icon text, be sure the length of the new text
string does not exceed the recommended maximum length for icon
title text for your windowing system. Some window managers can
display long icon text strings, while others will truncate them. Ensure
the text string you specify for your icons displays appropriately. Also,
some window managers allow you to change the size of icons and
icon text font.

10 User-Configurable Action Buttons

The last column of buttons in the Control area of the Job Activity
Console are user configurable. You may associate any command with
these buttons, and specify your own button labels. The following
resource specifications specify labels and commands for the three
configurable buttons.
Autocons*userButton1Label:
Autocons*userButton1Command:
Autocons*userButton2Label:
Autocons*userButton2Command:
Autocons*userButton3Label:
Autocons*userButton3Command:

By default, these resources are commented out. Be sure to remove the

preceding exclamation point (!) when you edit these specifications.

Button labels can be up to 20 characters, including spaces.

AutoSys User Guide for UNIX 10-47 ■

■ The Operator Console
Customizing the Operator Console

You must specify the full path to the command (environment variables
are not resolved). After the path to the command, environment variables
are allowed. $JOB will take the value of the currently active job. It is
recommended that you run the command in the background by placing
an ampersand (&) at the end of the command. Otherwise, the Operator
Console will pause until the command has completed.

The following example shows how to use this resource to customize

button1 to delete the AutoSys job that is currently selected in the Job
Activity Console, and button2 to run a command called printScreen:
Autocons*userButton1Label: Delete Job
Autocons*userButton1Command: /usr/local/bin/deleteJob $JOB&
Autocons*userButton2Label: SnapShot
Autocons*userButton2Command: /usr/local/bin/printScreen&

Accessing InfoReports from the Operator Console

This section explains how to configure an Operator Console action
button to display reports on AutoSys jobs using InfoReports. The
Autocons X resource file contains the following example InfoReports
button label and command string, which are commented out by default:
!Autocons*userButton1Label:NthfromLastRun

!Autocons*userButton1Command:/autosys/inforeports/xproview -rep/
autosys/inforeports/reports/lastnrun.rep &

To enable the display of reports by clicking on a user-configurable

button, open the Autocons file in a text editor and follow these steps:

1 Remove the comment characters (!) from the beginning of the lines.

2 If desired, change the button label text to any text string of 20

characters or less.

■ 10-48 AutoSys User Guide for UNIX

 The Operator Console ■
Customizing the Operator Console

3 The default example assumes the InfoReports executable file

(xproview) is located in the /autosys/inforeports directory. If
necessary, replace this path with the actual path on your system. If you
have the full InfoReports product installed on your machine, you can
replace this path with the path to your InfoReports installation.

4 The default example assumes the reports (.rep files) are located in the
/autosys/inforeports/reports directory. If necessary, replace this
path with the actual path on your system.

The example command line is configured to display the Last n Run report
(lastnrun.rep). You can change this to display any of the following
reports:

joblist.rep Creates a job list report based on a list of jobs you

select, or on the entire list of jobs in that instance’s
database.

jobfind.rep Creates a job report that includes the jobs that o

match the a pattern for a job name that you enter.

lastrun.rep Creates a last run report on the job that you specify.
The report contains information on the last run of
the job.

lastnrun.rep Creates a last specified run (n) report on the job that
you specify. You can also enter the last, second to
last, or the a number for the last run.

Configuring InfoReports Viewer for Printing

If you want to enable printing of the InfoReports reports, you must first
configure the InfoReports printer. To do this, you run the InfoReports
prfgen.sh script.

1 Change to the $AUTOSYS/install directory.

2 Enter the following command to run the printer configuration script:

./prfgen.sh

AutoSys User Guide for UNIX 10-49 ■

■ The Operator Console
Customizing the Operator Console

3 Provide the information requested to configure an InfoReports

printer.

For details on this script, see your InfoReports documentation.

10 Console Clock Perspective

The following resource specification sets the default console clock
perspective.
! clock perspective (Server|Machine|Job)
Autocons*clockPerspective: Job

Server is the server machine time. Machine is the time zone of the
machine running the Operator Console. Job is the time zone specified in
the job definition (using the timezone attribute). If no time zone is set for
the job, then the server machine time is used.

■ 10-50 AutoSys User Guide for UNIX

 11
Monitoring and Reporting
Jobs
This chapter describes how to define AutoSys monitors and reports using
essential and optional monitor/report attributes. It also explains how to
define monitors and reports using both the GUI and JIL.
About Monitors and Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3
Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4

Defining Monitors and Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4

Using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
Using JIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
Chapter Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6

Essential Monitor/Report Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7

Common Essential Attributes—General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Common Essential Attributes—Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Essential Report Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10

Optional Monitor/Report Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-11

Optional Monitor Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11

AutoSys User Guide for UNIX 11-1 ■

■ Monitoring and Reporting Jobs

Optional Report Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-12

Defining Monitors and Reports using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . .11-12

The Monitor/Browser Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-12
Defining an Example Monitor and Report . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-15

Defining Monitors and Reports using JIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-19

Running a Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-21

Customizing the Monitor/Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-22

Database Connection Time-out Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-22
Monitor/Browser Title bar Text and Icon Text . . . . . . . . . . . . . . . . . . . . . . . .11-23

■ 11-2 AutoSys User Guide for UNIX

 Monitoring and Reporting Jobs ■
About Monitors and Browsers

11 About Monitors and Browsers

Monitors provide you with a real-time view of the system. Reports (or
“Browsers”) provide you the ability to examine historical information
about job executions using a variety of reporting views.

Monitors and reports are simply applications that run against the
AutoSys database. Since all information is in the database, monitors and
reports that retrieve information from the database provide a complete
picture of the state of the entire system. Monitors and reports can run
with any AutoSys database, and Dual Event servers can be in use. Also,
monitors and reports can be run on any AutoSys client machine.

Monitors and reports enable you to filter and screen only the
information you are interested in from of a vast collection of data. That
is, they are tools that can give you information meaningful to you.

Both monitors and reports filter events by the following:

■ Type of event

■ Job or groups of jobs

In addition, reports also filter by time. Monitors do not filter by time

because they provide real-time information.

Note • Monitors can provide a picture of the system’s state in real-

time. If the Event Processor is down, monitors will not provide any
information. On the other hand, reports provide a picture of the
system’s state from a “historical” view, not in real-time.

AutoSys User Guide for UNIX 11-3 ■

■ Monitoring and Reporting Jobs
Defining Monitors and Reports

11 Monitors
Monitors provide a real-time view of the AutoSys system. These are the
two steps necessary to use a monitor:

■ Defining to AutoSys which events to monitor.

■ Actually running the monitor.

A running monitor is an application that polls the database for new

events that meet the selection criteria. Monitors are strictly
informational. They provide an up-to-the-minute window to AutoSys
events as they occur. For box jobs, all job levels can be observed, if
desired.

11 Reports
A report (or browser) is a query run against the database, based on the
selection criteria defined for that report. Its primary function is to enable
you to quickly get very specific information, such as the finish time of the
database backup for the last two weeks or all jobs that have an alarm
associated with them. In addition, all job levels in box jobs can be
reported if desired.

Like monitors, a report definition is stored in the database, enabling

reports to be run at any time, without redefining the criteria to AutoSys.
Reports can only display events that are still in the database. Archived
events are inaccessible and cannot be displayed.

11 Defining Monitors and Reports

There are a number of attributes that are used to define and describe
monitors and reports. Using these attributes, you can specify everything
from the name to be assigned to the new monitor or report, to the events
you are interested in tracking.

■ 11-4 AutoSys User Guide for UNIX

 Monitoring and Reporting Jobs ■
Defining Monitors and Reports

You can specify monitors and reports to AutoSys using either of the
following:

■ Through the Graphical User Interface (GUI).

■ By passing Job Information Language (JIL) statements to the jil

command.

In either case, the monitor or report specification is stored in the

database, and the attributes you specify are virtually the same. You define
a new monitor or report by assigning it a name and specifying any
number of attributes that further define its behavior.

11 Using the GUI

To define a monitor or report using the GUI
1 Issue the autosc command, which displays the AutoSys GUI Control
Panel.

2 In the GUI Control Panel, click Monitor/Browser button, which

displays the Monitor/Browser dialog (as shown in Figure 11-1 on
page 11-13).

3 Set the various attributes and their values using the fields and buttons
in the Monitor/Browser dialog.

11 Using JIL
To define a monitor or report using JIL
} Issue the jil command, and pass it the insert_monbro sub-command
followed by a set of attribute: value pairs.

AutoSys User Guide for UNIX 11-5 ■

■ Monitoring and Reporting Jobs
Defining Monitors and Reports

11 Chapter Organization
In this chapter, monitor and report attributes fit into two categories
(sections): essential and optional. Essential attributes must be specified
in order for a definition to be valid, and optional attributes are not
required.

For each attribute described in this chapter, the following is indicated (as
shown in the diagram below):

■ Its name

■ Its JIL attribute keyword

■ Its corresponding GUI object or “GUI Field Name”

■ A description of its use

Monitor or Report Mode

mode Mode

Attribute description...

JIL Keyword GUI Field Name

In the example above, the Monitor or Report Mode attribute, which

specifies whether a monitor or a report is being defined, is specified
using the JIL keyword mode, and is identified in the GUI as the Mode field.

Note • Since Chapter 18, “JIL/GUI Monitor/Report Definition

Reference,” is organized alphabetically by JIL keywords, the keywords
provided in this chapter can act as “pointers,” indicating where you
can find more details about a particular attribute in the reference
chapter. (The heading on each reference page similarly contains the
JIL keyword on the left and GUI Field Name on the right, as in the
example above.)

■ 11-6 AutoSys User Guide for UNIX

 Monitoring and Reporting Jobs ■
Essential Monitor/Report Attributes

11 Essential Monitor/Report Attributes

11 Common Essential Attributes—General
The following attributes are required for both monitors and reports.
Although defaults might be available, the attributes are still essential in
that every monitor or report must include them, whether by default or by
explicit specification.

Monitor/ Report Name

insert_monbro: monbro_name Name

The monitor or report name is used to identify the monitor or report to

AutoSys, and must be unique within AutoSys. A monitor and report
cannot have the same name, but a monitor or report can have the same
name as a job. A monitor or report name can be from 1-30 alphanumeric
characters; embedded blanks and tabs are illegal.

Mode
mode Mode

The mode attribute indicates whether a monitor or report is being

specified.

11 Common Essential Attributes—Events

The events specification determines which AutoSys events are to be
monitored or reported. Events are any changes in the state of AutoSys
jobs. They can also be AutoSys-generated occurrences, such as alarms. Or,
they can be manually-generated events, such as starting a job, placing a
job on hold, or killing a job.

AutoSys User Guide for UNIX 11-7 ■

■ Monitoring and Reporting Jobs
Essential Monitor/Report Attributes

As described in the next section, monitors and reports can track events by
filtering at several levels. Monitors and reports can also track events based
on selected jobs. The events to be tracked are determined by the
combination of the various event filters and the job filter, which are
specified by using any of the essential attributes.

All Events
all_events ALL EVENTS

The all_events attribute specifies whether any event filtering is in effect.

If it is set to “yes,” the other event filtering attributes are ignored, and all
events, regardless of source, will be reported for the selected jobs. These
events include job status events and alarms.

Note • If you wish to monitor all the events for all jobs, you should
not run a monitor. Instead, you should display the Event Processor log
time in real time, using the following command:
autosyslog -e
Running a monitor adds another connection to the database, and
establishes another process that is continually polling the database.
This process will have a significant impact on system performance.
Moreover, the information logged by the Event Processor contains
much more diagnostic information than that monitor does.

Alarms
alarm Alarms

This attribute specifies whether AutoSys-generated alarms should be

tracked. Alarms can be tracked in addition to job status events (described
below).

■ 11-8 AutoSys User Guide for UNIX

 Monitoring and Reporting Jobs ■
Essential Monitor/Report Attributes

All Job Status Events

all_status ALL Job Status Events

This attribute specifies whether all job status events should be tracked.
Job status events occur whenever a job’s status changes. If this attribute is
set to “yes,” the individual job status events shown below and a few
AutoSys-internal job status events, will be tracked.

Alarms can also be tracked in addition to job status events.

Individual Job Status Events

running Running

success Success

failure Failure

terminated Terminated

starting Starting

restart ReStarting

Job Filter
job_filter Job Filter

The job filter attribute determines which AutoSys jobs are to be

monitored or reported. Monitors and reports can track events based on
selected jobs. The events to be tracked are determined by the
combination of the various event filters and the job filter. The job filter
can be set to one of three settings: track all jobs (no job filtering), track a
single box with the jobs it contains, or track a single job. If either of the
latter two are selected, the name of the job is required.

AutoSys User Guide for UNIX 11-9 ■

■ Monitoring and Reporting Jobs
Essential Monitor/Report Attributes

11 Essential Report Attributes

One of the attributes described below is required when defining reports,
in addition to those essential attributes listed above. Reports allow you
to peruse all the events in the database. The time criteria listed here allow
you to select events that occurred within a particular span of time. They
are mutually exclusive.

Current Run Only

currun Current Run Only

This attribute specifies that only events in the current or most recent
execution of the specified job(s) will be reported. This feature is useful for
getting a sense of what is happening right now. For example, you could
select the job status event “restarting,” turn off job filtering, and set this
attribute to “yes” to see all the jobs that have been automatically restarted
by AutoSys in their current or latest run.

Events After a Certain Date/Time

after_time Events After Date/Time

This attribute specifies that only events occurring after a certain date and
time for the specified job(s) will be reported. This attribute cannot be
used in a monitor definition because monitors only show events as they
occur.

■ 11-10 AutoSys User Guide for UNIX

 Monitoring and Reporting Jobs ■
Optional Monitor/Report Attributes

11 Optional Monitor/Report Attributes

11 Optional Monitor Attributes
The following monitor attributes are optional.

Sound
sound Sound

This attribute specifies whether the sound facility should be used. If the
workstation running the monitor has sound capabilities, AutoSys will
use them to announce the events as they occur. The announced message
is pieced together from pre-recorded sound clips.

Note • It is strongly recommended that you use the sound attribute

for monitoring AutoSys, especially alarms. It frees you from needing
to look through output files to see if there are any problems.

For details on recording sound and a list of machines for which AutoSys
supports sound, see the record_sounds command in Chapter 1, AutoSys
Commands, in the AutoSys Reference Guide for UNIX.

Verification Required for Alarms

alarm_verif Verification Required for Alarms

This attribute specifies whether alarms need to be responded to by

personnel before they will be turned off. This verification feature
prompts the user, in the window running the monitor, for their initials
and a comment. This information is time stamped and recorded in the
database, along with the alarm event. This approach provides an account
of the alarms that were responded to, and when they were responded to.

AutoSys User Guide for UNIX 11-11 ■

■ Monitoring and Reporting Jobs
Defining Monitors and Reports using the GUI

An important feature of this attribute is that if the response is not given

within 20 seconds, the message is repeated. Therefore, if one
momentarily steps out of the room and there is an alarm, it keeps writing
to the window, and playing the sound clip (if specified) until someone
responds.

11 Optional Report Attributes

There are no optional report attributes.

11 Defining Monitors and Reports using the GUI

This section describes the general use of the GUI Monitor/Browser
dialog, which is used for defining monitors and reports.

11 The Monitor/Browser Dialog

The Monitor/Browser dialog contains fields representing all the
information you need to define a monitor or report. When you
single-click the Monitor/Browser button in the GUI Control Panel, the
Monitor/Browser dialog appears, as shown in Figure 11-1.

■ 11-12 AutoSys User Guide for UNIX

 Monitoring and Reporting Jobs ■
Defining Monitors and Reports using the GUI

Figure 11-1 • Monitor/Browser Dialog

AutoSys User Guide for UNIX 11-13 ■

■ Monitoring and Reporting Jobs
Defining Monitors and Reports using the GUI

The buttons at the top of the dialog are the dialog’s control buttons. They
perform the following actions:

Clear Clears the dialog without affecting the database. Use

this button to clear all fields (in the dialog and
memory), before you begin defining a new monitor
or report.

Delete Deletes the currently displayed monitor or report

from the database.

Save Stores the currently displayed monitor or report in

the database, either modifying a pre-existing object,
or creating a new one. It also clears the dialog in
preparation for another monitor or report
definition.

Run MonBro Runs the monitor or report and displays output in

an xterm window.

Exit Closes the Monitor/Browser dialog and displays the

GUI Control Panel. If Exit is pressed without
pressing Save first, the recent changes are not saved.
Exit only exits the dialog.

As indicated above, monitors and reports can be run from the Monitor/
Browser dialog. A monitor must be saved in the database before it can be
run, but reports do not need to be saved before they can be run. When a
monitor or report is run from the dialog, a new terminal window appears
to display the output. To close this window, press <Control+c>.

■ 11-14 AutoSys User Guide for UNIX

 Monitoring and Reporting Jobs ■
Defining Monitors and Reports using the GUI

11 Defining an Example Monitor and Report

In this section, you’ll define one monitor and one report. In the next
section, describing the use of JIL, the examples from this section will be
used to demonstrate the JIL statements you need to create the same
definitions.

Defining a Monitor
First, you will define a monitor with the name “Regular.” This monitor
will monitor all alarms, plus job status events when a job changes state
to running, success, failure, or terminated for the current job run.

To open the Monitor/Browser dialog

} In the GUI Control Panel, single-click on the Monitor/Browser
button, and the Monitor/Browser dialog appears.

To define the example monitor

1 In the Name field, enter the monitor’s name: Regular

2 In the Mode field, single-click on the Monitor button.

3 In the Monitor/Browse these Types of Events region of the dialog,

single-click on the Alarms button.

4 In the Job CHANGE_STATUS Events region, single-click the Running,

Success, Failure, and Terminated buttons.

5 In the Job Selection Criteria region of the dialog, single-click on the

ALL Jobs button.

Your entries in the Monitor/Browser dialog should look like those shown
in Figure 11-2.

AutoSys User Guide for UNIX 11-15 ■

■ Monitoring and Reporting Jobs
Defining Monitors and Reports using the GUI

Figure 11-2 • Monitor/Browser Dialog for Monitor Named Regular

To save the monitor definition in the database

} At the top of the Monitor/Browser dialog, single-click the Save button.

To dismiss the Monitor/Browser dialog

} You can either dismiss the dialog using the Exit button, or you can
leave it open to do the next exercise.

■ 11-16 AutoSys User Guide for UNIX

 Monitoring and Reporting Jobs ■
Defining Monitors and Reports using the GUI

Note • If you want to run the monitor immediately, you must save it
first, then click on the Run MonBro button. When running a monitor
or a report from the GUI, an xterm window is created to display the
monitor or report output.

Defining a Report
Next, you will define a report with the name “Alarm_Rep.” This report
will report all alarms on any job, from December 22, 1997, at 12:00 to
the present.

To define the example report

1 Click the Clear button to clear the dialog and begin a new report.

2 In the Name field, enter the report’s name: Alarm_Rep.

3 In the Mode field, single-click the Browser button.

4 In the Monitor/Browse these Types of Events region of the dialog,

single-click the Alarms button only.

5 In the Job Selection Criteria region of the dialog, single-click the

ALL Jobs button.

6 In the Browser Time Criteria region of the dialog, single-click the No

button next to the words “Current Run Only”, and enter the date and
time in the Events After Date/Time text field as follows (or you can
enter a different, appropriate time):
12/22/1997 12:00
Your entries in the Monitor/Browser dialog should look like those shown
in Figure 11-3.

AutoSys User Guide for UNIX 11-17 ■

■ Monitoring and Reporting Jobs
Defining Monitors and Reports using the GUI

Figure 11-3 • Monitor/Browser Dialog for Report Named Alarm_Rep

To save the report definition in the database

} At the top of the Monitor/Browser dialog, single-click the Save button.

To dismiss the Monitor/Browser dialog

} You can either dismiss the dialog using the Exit button, or you can
leave it open to create other definitions.

■ 11-18 AutoSys User Guide for UNIX

 Monitoring and Reporting Jobs ■
Defining Monitors and Reports using JIL

11 Defining Monitors and Reports using JIL

To define a monitor or report using JIL, use the same syntax as that used
to specify a job. This is the syntax:
sub-command:monbro_name
attribute_keyword:value

where:
monbro_name

Is the monitor or report’s name. It can be from 1-30 alphanumeric

characters and is terminated with white space; embedded blanks and
tabs are illegal.

The only difference between defining monitor/reports and jobs is that

different sub-commands are used. For defining monitor or reports, these
are the JIL sub-commands:
■ insert_monbro

■ update_monbro

■ delete_monbro

The following JIL script creates a monitor that will sound an alarm
whenever a job finishes successfully:
insert_monbro: Job_Success
mode: monitor /* "m" may be specified instead */
sound: yes
success: yes
job_filter: all

Note • The JIL examples in the following sections include the monitor
and report definitions presented in the GUI section above.

AutoSys User Guide for UNIX 11-19 ■

■ Monitoring and Reporting Jobs
Defining Monitors and Reports using JIL

For a list of machines for which AutoSys supports sound, see the
record_sounds command in Chapter 1, AutoSys Commands, in the AutoSys
Reference Guide for UNIX.

Defining Monitors
First, you will define a monitor with the name “Regular.” This monitor
will monitor all alarms, plus job status events when a job changes state
to running, success, failure, and terminated. It sounds an audible alarm
whenever any of the events occur (for a list of machines for which
AutoSys supports sound, see the record_sounds command in Chapter 1,
AutoSys Commands, in the AutoSys Reference Guide for UNIX).

These are the JIL statements for this monitor definition:

/* Monitor for all ALARMS, and
* Job EVENTS: RUNNING,SUCCESS,FAILURE & TERMINATED
*
* Sound is ON!
*/
insert_monbro: Regular
mode: m
sound: y
alarm: y
running: y
success: y
failure: y
terminated: y

The $AUTOSYS/install/data/monbro.jil file contains the example JIL

statements shown above. It also contains the following JIL statements,
which define a sample monitor:
/* Monitor for JUST ALARMS!
* Verification Required is ON so someone must type in a response.
*/
insert_monbro: Alarm
mode: m
sound: y
alarm: y
alarm_verif: y

■ 11-20 AutoSys User Guide for UNIX

 Monitoring and Reporting Jobs ■
Running a Monitor

This set of statements defines a monitor that catches alarms, generates an

audible alarm, and continually repeats the alarm until someone
responds.

Defining a Report
Next, you will define a report with the name “Alarm_Rep.” This report
will report all alarms on any job, from June 1, 1997, at 2:00 a.m., to the
present.
insert_monbro: Alarm_Rep
mode: b
alarm: y
after_time: "06/01/1997 2:00"

Notice that quotes are required in the previous example, because the time
contains a special character, the colon.

Note • Reports can only display events that are still in the database.
Archived events are inaccessible and cannot be displayed.

11 Running a Monitor
To run a monitor
} Enter the name in the Name field of the Monitor/Browser dialog, and
single-click the Run MonBro button.
Or
} Run the monitor by executing the following AutoSys command at the
UNIX command line:
monbro -N monitor_name

AutoSys User Guide for UNIX 11-21 ■

■ Monitoring and Reporting Jobs
Customizing the Monitor/Browser

11 Customizing the Monitor/Browser

There is a set of X resources you can use to customize the appearance and
behavior of the Monitor/Browser GUI. In particular, these resources
allow you to control:

■ The time interval after which the Monitor/Browser GUI will drop the
connection to the database.

■ The Monitor/Browse GUI icon text and the Monitor/Browse title bar
text.

Descriptions of the resources which can be customized are given below.

All of these can be set by modifying the X resource file Autosc. The X
resources files reside in the local app-defaults directory, which varies
across platforms. It is usually in /usr/lib/X11/app-defaults or /usr/
openwin/lib/app-defaults. If you are not sure which directory these files
are in, ask your system administrator.

Individual users may have their own copy of the X resources files in their
$HOME directory, which will take precedence over the app-defaults files.

For most operating systems, if you are exporting the display to another
machine you must edit the appropriate files in the app-defaults
directory on the local machine.

For Solaris, you must edit the files in both the /usr/lib/X11/
app-defaults and /usr/openwin/lib/app-defaults directories. The files
in /usr/lib/X11/app-defaults control the resources when you export the
display.

11 Database Connection Time-out Interval

The following resource controls the time interval after which the
Monitor/Browser GUI will drop the connection to the database:
! TimeOut to drop DB connections (in minutes)
*DBDropTime: 400

■ 11-22 AutoSys User Guide for UNIX

 Monitoring and Reporting Jobs ■
Customizing the Monitor/Browser

If DBDropTime is set to 0, the connection is dropped immediately after the

database query has completed. A value greater than or equal to 5 means
that the GUI will automatically drop all database connections if the
database has not been accessed in the last DBDropTime minutes. (Values
of 1 to 4 are invalid). A new database connection will subsequently be
established when required. If DBDropTime is greater than 360, the
connection to the database is maintained until you exit the GUI screens.

11 Monitor/Browser Title bar Text and Icon Text

The following resources specify the title bar text and the icon text. By
default the title bar text is “Monitor/Browser” and the icon text is
“MonBro”.
Autosc.shellTitleMonBro:
Autosc.iconTitleMonBro:

Note • When changing icon text, be sure the length of the new text
string does not exceed the recommended maximum length for icon
title text for your windowing system. Some window managers can
display long icon text strings, while others will truncate them. Ensure
the text string you specify for your icons displays appropriately. Also,
some window managers allow you to change the size of icons and
icon text font.

AutoSys User Guide for UNIX 11-23 ■

 12
Maintaining AutoSys
This chapter describes the procedures for maintaining AutoSys and the
AutoSys database.
Maintaining the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Starting the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Monitoring the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
Stopping the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7
Shadow Event Processor Rollover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8

Running AutoSys in Test Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-10

AutoSys Maintenance Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-12

Backing up AutoSys Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-13

Restoring AutoSys Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-16

AutoSys Database Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-16

Event Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17
Database Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18

General Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-20

Daily Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20
DBMaint Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-21

AutoSys User Guide for UNIX 12-1 ■

■ Maintaining AutoSys

Event Server Rollover Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-23

Event Server Crash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-23
Synchronizing the Event Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-24

Improving Database Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-25

Improving Sybase Database Performance . . . . . . . . . . . . . . . . . . . . . . . . . . .12-25
Improving Oracle Database Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-26

Maintaining Bundled Sybase SQL Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-28

Sybase Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-28
Sybase Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-29
Default Sybase Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-29
Starting Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-31
Stopping Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-32
Accessing Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-33
Identifying Processes Connected to the Database . . . . . . . . . . . . . . . . . . . . .12-34
Displaying the Database Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-35
Bundled Sybase Backup and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-35

■ 12-2 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining the Event Processor

12 Maintaining the Event Processor

The Event Processor is the engine of AutoSys. When the Event Processor
is not running, you cannot initiate new actions. You can stop the Event
Processor, however, and the actions that have already started will run to
completion.

12 Starting the Event Processor

To start the Event Processor
} On the AutoSys server machine, enter the following command:
eventor
This command performs a number of consistency checks, and then starts
the event_demon program.

You can start the Shadow Event Processor at the same time as the Primary
Event Processor by specifying the -M option followed by the name of the
machine on which you want the Shadow Event Processor to run, like this:
eventor -M machine_name

eventor runs in the background automatically.

WARNING • Do not try to start the Event Processor by invoking the

event_demon binary at the command line. The eventor script is required to
properly check and configure the environment for the Event Processor.

eventor Command
The eventor command performs these tasks:

■ Verifies that no other Event Processor is running on that machine.

AutoSys User Guide for UNIX 12-3 ■

■ Maintaining AutoSys
Maintaining the Event Processor

■ Invokes a restart procedure that looks for any events that are hung in
the “processing” state. Because events are processed one at a time,
there can only be one event hung in the processing state at a time. If
there is an event in this state, it is requeued for processing. Normally,
events will only be in this state if the Event Processor was stopped
while it was processing an event.

Note • If the event being processed was a STARTJOB event, and the
job it started is still alive, it will not be started again. Also, if an
event is in the “processing” state for a long time, this does not
imply that the job associated with that event is in some unusual
state. It could be that the command is lengthy, or is waiting for
machine resources.

■ Invokes the chase command. chase inspects the AutoSys database to

see what AutoSys should be running, then checks each machine to
verify that the appropriate jobs are running. If chase sees any
anomalies, it sends an alarm, and, if the job definitions permit, it
restarts any missing jobs.

The purpose of the chase feature is to verify the state of AutoSys and
detect any problems upon startup.

■ Starts the event_demon. Its output is redirected to the following file:

$AUTOUSER/out/event_demon.$AUTOSERV
When eventor starts, it automatically invokes the following
command:
tail -f $AUTOUSER/out/event_demon.$AUTOSERV
This command displays the output of event_demon to the screen. To
break out of the display, press <Control+c>. This terminates the tail
command only, making the window available—the event_demon
continues to run in the background.

■ 12-4 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining the Event Processor

Note • If you do not want eventor to run the tail command, you
can use the -q option when you start the Event Processor. Several
command line options allow you to start the Event Processor
without some of the checks being performed; however, these
options should be used by an experienced AutoSys administrator
for special circumstances only.

For more information about the eventor command, see its entry in
Chapter 1, AutoSys Commands of the AutoSys Reference Guide for UNIX.

Starting in Global Auto Hold Mode

If you are restarting the Event Processor after a period of downtime, you
can specify the -G option to start the Event Processor in Global Auto Hold
mode. This prevents the system from being overloaded with job starts for
the numerous jobs that were scheduled to run during the downtime.

When the Event Processor is in Global Auto Hold mode, it evaluates all
jobs whose starting conditions have passed and are eligible to run.
Instead of starting the jobs, however, the Event Processor puts the jobs
ON_HOLD. It does this for all types of jobs (box, command, and file
watcher). This allows you to decide which jobs should run and to start
them selectively with the Force Start Job button in the Operator Console,
or with the following command:
sendevent -E FORCE_STARTJOB
This FORCE_STARTJOB event is the only way to start a job put
ON_HOLD with Global Auto Hold; it overrides the Global Auto Hold.

To turn off Global Auto Hold, you must shut down the Event Processor,
and then start it again without the -G option.

You can start both the Primary and Shadow Event Processors with the -G
option.

AutoSys User Guide for UNIX 12-5 ■

■ Maintaining AutoSys
Maintaining the Event Processor

12 Monitoring the Event Processor

The output of the Event Processor (event_demon executable) is written to
the following log file:
$AUTOUSER/out/event_demon.$AUTOSERV
This log file contains a record of all the actions taken by the Event
Processor, including startup and shutdown information.

If the $AUTOUSER directory is NFS mounted, you can view this output from
any machine on the network.

To view the log file

} Type the following UNIX command:
tail -f $AUTOUSER/out/event_demon.$AUTOSERV
Or
} Execute the AutoSys autosyslog utility like this:
autosyslog -e
When you execute this command, the last ten lines of the log file are
displayed, and then all additions to the log are automatically
displayed as they occur.

To terminate the autosyslog process

} Press <Control+c>.

Note • We recommend that you use the autosyslog -e command to

follow the behavior of the Event Processor. It displays the log file,
which generates information on all Event Processor activity.

Event Processor Log File Size

At startup, the Event Processor checks the size of its log file, and if the file
is 250 kilobytes or more, the Event Processor deletes the file.

■ 12-6 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining the Event Processor

The Event Processor log has a file system threshold setting. The Event
Processor shuts down if there is less than 8 kilobytes of disk space
available. However, if the amount of available disk space falls below that
specified by the FileSystemThreshold parameter in the configuration file,
the Event Processor issues warnings in the Event Processor log file.

For information on the FileSystemThreshold parameter, see the Event

Processor Log Disk Space section in Chapter 13, Configuring AutoSys.

12 Stopping the Event Processor

It is safe to stop the Event Processor at any time, if it is stopped properly.
Only the Exec Superuser can stop the Event Processor.

Note • Stopping the Event Processor does not affect jobs that are
already running. They continue to run to completion, at which time
the exit events are sent directly to the AutoSys database. The effect of
stopping the Event Processor is that actions triggered by incoming
events sent from the Remote Agents are not initiated until you start
the Event Processor again.

To stop the Event Processor properly

1 Log onto any AutoSys configured machine as the AutoSys Exec
Superuser.

2 Issue the following command:

sendevent -E STOP_DEMON
This method allows the Event Processor to complete gracefully any
processing it is performing. You can assign a high priority to the
sendevent -E STOP_DEMON command by including the -P 1 argument.

When you issue the sendevent command, the STOP_DEMON event is

sent to the AutoSys database. The Event Processor then reads the
STOP_DEMON event, goes into an orderly shutdown cycle, and exits.
There might be a delay between when you send the STOP_DEMON event
and when the Event Processor reads it and shuts down. If the Event

AutoSys User Guide for UNIX 12-7 ■

■ Maintaining AutoSys
Maintaining the Event Processor

Processor does not shut down immediately, do not send another

STOP_DEMON event, because the event Processor will process that event
the next time it starts, and it will promptly shut down.

For more information about the sendevent command, see sendevent in

Chapter 1, AutoSys Commands, of the AutoSys Reference Guide for UNIX.
WARNING • Do not attempt to stop the Event Processor (the
event_demon process) by using the UNIX kill command. This method
stops the Event Processor no matter what it is doing; it might be in the
middle of processing an event. Also, if you are using Dual Event Servers
and use these methods, the databases can lose synchronization.

12 Shadow Event Processor Rollover

You can configure a Shadow Event Processor to act as a backup Event
Processor. The Shadow Event Processor is normally idle; it listens for the
periodic signals (every 90 seconds) from the Primary Event Processor that
indicate the Primary processor is still functioning.

If the Shadow Event Processor does not receive the signal, it does the
following:

1 Checks the Third Machine for the .dibs file.

2 Does one of the following:

• If it cannot connect to the Third Machine, the Shadow Event

Processor shuts down.
Or
• If it can connect but cannot locate the .dibs file, the Shadow Event
Processor creates the file, attempts to signal the Primary Event
Processor to stop, and takes over processing the events.
Or
• If it can connect and the .dibs file already exists, the Shadow Event
Processor shuts down.

■ 12-8 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining the Event Processor

Similarly, if the Primary Event Processor cannot locate and signal the
Shadow Event Processor, the Primary processor checks the Third
Machine for the .dibs file, and follows the same procedure as the
Shadow Event Processor (as described above).

If the Primary Event Processor and an Event Server are on the same
machine, the Event Processor failure could also mean an Event Server
failure. In this situation, if Dual Event Servers are configured, AutoSys
will roll over to the Shadow Event Processor and to Single Server mode.

AutoSys uses the Third Machine and the existence of the .dibs file to
resolve contentions and to eliminate the case where one processor takes
over because its own network is down. However, the Shadow Event
Processor is not guaranteed to take over in 100% of the cases. For
example, in the case of network problems, AutoSys might not be able to
determine which Event Processor is the “healthy” one, and it will shut
down both processors.

Note • You can specify the Shadow Event Processor and the Third
Machine by modifying the tunable parameters in the AutoSys
configuration file. For information, see Chapter 13, Configuring AutoSys.

Restoring the Primary Event Processor

To restore the Primary and the Shadow Event Processor

1 Stop the Shadow Event Processor by logging on as the AutoSys Exec
Superuser, and issuing the following command:
sendevent -E STOP_DEMON
2 Issue the following command on the Primary Event Processor
machine:
eventor -M shadow_machine
This command starts the Primary and Shadow Event Processors at the
same time.

AutoSys User Guide for UNIX 12-9 ■

■ Maintaining AutoSys
Running AutoSys in Test Mode

Note • If you attempt to start the Primary and Shadow Event

Processors without having a Third Machine specified in the AutoSys
configuration file, the Shadow Event Processor will not start.

12 Running AutoSys in Test Mode

If you want to check your AutoSys configuration, you can run AutoSys in
test mode. This process is helpful for troubleshooting problems. Running
the Event Processor in test mode allows you to test the set up as well as
the execution of logic by the jil command, without having to run the
defined jobs. A simple job is run in place of the defined job.

When running in test mode, you can determine the following:

■ If the Event Processor and the Remote Agents are installed and
configured properly. Running in test mode uses the same mechanisms
of starting jobs and sending events that AutoSys uses in its normal
mode.

■ If the conditional logic for jobs, including nested boxes, is functioning

correctly.

You can run the Event Processor at two levels of test mode. You do this
by setting the $AUTOTESTMODE environment variable before starting the
Event Processor. The levels of test mode are determined by the value of
the $AUTOTESTMODE variable. These are the values, which are discussed in
the following sections:
■ $AUTOTESTMODE = 1

■ $AUTOTESTMODE = 2

Note • The Event Processor cannot run partially in test mode; AutoSys
does not provide a test mode for the database. Therefore, you should
exercise extreme caution when you run in test mode on a live
production system.

■ 12-10 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Running AutoSys in Test Mode

$AUTOTESTMODE = 1
At the first level of test mode, each job that you specify runs with the
following test mode variations:

■ The command /bin/date is executed on the remote machine instead

of the command specified in the job definition.

■ Standard output and standard errors for the command are redirected
to the /tmp/autotest.$AUTO_JOB_NAME file, where $AUTO_JOB_NAME is
the job name as defined to AutoSys.

■ If the job being run in test mode is a file watcher job, it is not disabled;
it runs as it would in real mode.

The following functions are disabled:

■ Minimum and Maximum Run Alarms

■ Sourcing a user-specified .profile file

■ All resource checks

$AUTOTESTMODE = 2
The second level of test mode runs with the same behaviors as the first
level with the addition of the following procedures:

■ Resource checks are performed.

■ A user defined .profile file is sourced.

■ Output from the /bin/date command goes to the user defined

standard output and standard error files, if they are defined;
otherwise, output goes to the file named
/tmp/autotest.$AUTO_JOB_NAME.

AutoSys User Guide for UNIX 12-11 ■

■ Maintaining AutoSys
AutoSys Maintenance Commands

12 AutoSys Maintenance Commands

The maintenance commands described below are located in the
$AUTOSYS/bin directory. You can execute these commands from the UNIX
operating system prompt or as an AutoSys job.

chase
The chase command verifies that the expected jobs are running. It goes
to every machine that should be running a job and verifies that the
following are true:

■ The Remote Agent is running.

■ The job is running.

Errors detected by chase are sent to standard output. The options used
with chase further determine what actions are taken when error
conditions are detected. chase can send alarms to AutoSys to alert you to
the problems it finds (by using the -A option). In addition, it can
automatically restart jobs that are “missing in action” and that are
defined to be restartable (by using the -E option). For more information
about the chase command, see Chapter 1, AutoSys Commands, in the
AutoSys Reference Guide for UNIX.

Note • There is no way for chase to tell if a machine is down;

therefore, it cannot tell if jobs on that machine are running, or if the
network connection to the machine is down. If you run chase with the
-E option, jobs that have already run, or are running on the machine
with the failed network connection might be restarted if the network
connection is re-established.

■ 12-12 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Backing up AutoSys Definitions

clean_files
The clean_files command deletes old Remote Agent log files. It
performs this task by searching the database for all machines that have
had jobs started on them, and then sending a command to the Remote
Agent on that machine to purge all remaining log files from the
machine’s Remote Agent Log directory (specified by AutoRemoteDir in the
AutoSys configuration file). To remove only the log files older than a
specific number of days, use the following command:
clean_files -d days
Where days specifies that files older than this number of days should be
deleted.

For more information about the clean_files command, see Chapter 1,

AutoSys Commands, in the AutoSys Reference Guide for UNIX.

12 Backing up AutoSys Definitions

We recommend that you back up the following AutoSys definitions
periodically to ensure that you have files to restore from in case of a
system failure:

■ calendar definitions

■ job definitions

■ machine definitions

■ monitor and browser definitions

■ global variables

For information about restoring the backed up definitions, see Restoring

AutoSys Definitions on page 12-16.

We also recommend that you keep a copy of your AutoSys license keys in
case you need to reinstall them.

AutoSys User Guide for UNIX 12-13 ■

■ Maintaining AutoSys
Backing up AutoSys Definitions

To back up AutoSys definitions

1 To save your calendar definitions:

a Open a Calendar Definition window.

b Choose File } Export.

The Export File Name dialog is displayed.

c In the Export File Name dialog, select a directory that is outside of

the AutoSys directory structure and select or enter a file name.

d Click OK.

Note • The calendar definitions are saved as text.

2 To save your job definitions, from a UNIX command prompt, execute

the following command:
autorep -J ALL -q > /directory/autosys.jil
Where directory is a directory outside of the AutoSys directory
structure. We recommend that you save to the same directory where
you saved your calendar definitions.

This command saves your job definitions to a file named autosys.jil.

3 To append your machine definitions to the same file that contains

your job definitions, from the UNIX command prompt, execute the
following command:
autorep -M ALL -q >> /directory/autosys.jil
Where directory is the same directory where you saved your job
definitions, a directory outside of the AutoSys directory structure.

■ 12-14 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Backing up AutoSys Definitions

Note • To append definitions to an existing file, you enter >>

instead of >. We recommend that you append your job, machine,
and monitor and browser definitions to the same file. Then you
have only one file to restore following a system failure.

4 To append your monitor and browser definitions to the same file that
contains your job and machine definitions, from the UNIX command
prompt, execute the following command:
monbro -N ALL -q >> /directory/autosys.jil
Where directory is the same directory where you saved your job
definitions, a directory outside of the AutoSys directory structure.

5 To save your global variables to their own file, from the UNIX
command prompt, execute the following command:
autorep -G ALL > /directory/globals.jil
Where directory is a directory outside of the AutoSys directory
structure. We recommend that you save to the same directory where
you saved your other AutoSys definitions.

This command saves your global variables to a file named

globals.jil. This file is simply a record of what you must redefine
following a system failure.

Note • You can create a job that runs periodically to back up your
definitions automatically.

6 To save your license keys, run the gatekeeper command to print your
current license keys to a file.

AutoSys User Guide for UNIX 12-15 ■

■ Maintaining AutoSys
Restoring AutoSys Definitions

12 Restoring AutoSys Definitions

The procedure in this section assumes that you backed up your AutoSys
definitions by following the procedure in Backing up AutoSys Definitions
on page 12-13.

To restore AutoSys definitions

1 To restore your calendar definitions:

a Open a Calendar Definition window.

b Choose File } Import.

The Import File Name dialog is displayed.

c In the Import File Name dialog, select the directory and filename
of the text file that contains your calendar definitions.

d Click OK.

2 To restore your job, machine, and monitor and browser definitions,

from a UNIX command prompt, execute the following command:
jil < /directory/autosys.jil
Where directory is the directory where you saved your definitions.

3 To restore your global variables, reference your backup file and

redefine any global variables.

12 AutoSys Database Overview

All AutoSys information is stored in a relational database known as the
Event Server or AutoSys database. For this database, you can use either a
Sybase or an Oracle database.

An Event Server contains all of the information about a particular

instance of AutoSys. The Event Processor reads from the Event Server to
determine what actions to take. The Remote Agents send starting,
running, and completion information about jobs to the Event Server.

■ 12-16 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
AutoSys Database Overview

Due to the critical nature of the information stored in the database, you
can configure AutoSys to run with Dual Event Servers (two databases).
Dual databases provide redundancy in the event of an Event Server crash.

Note • While AutoSys uses the database solely as an SQL engine, it

does use Sybase Open Client C Library communications protocol and
Oracle SQL*Net V2 to send events around the system.

12 Event Server Overview

An Event Server can be associated with only one instance of AutoSys and
one running Event Processor.

An Event Server contains the following objects:

■ Job definitions

■ Events

■ Monitor and report (browser) definitions

■ Calendar information

■ Machine definitions

For a list of the database tables and views as well as the event and alarm
codes used in the database, see Chapter 6, Database Tables and Codes, in
the AutoSys Reference Guide for UNIX.

Using Dual Event Server Mode

When you configure AutoSys with Dual Event Servers, all of the data is
duplicated on two Event Servers. In Dual Server mode both servers are
peers, and the Event Processor is responsible for keeping the databases
synchronized. The Event Processor continually reads from both
databases as it processes events.

AutoSys User Guide for UNIX 12-17 ■

■ Maintaining AutoSys
AutoSys Database Overview

For information about installing a second Event Server, see the Installing
Dual Event Servers section of Chapter 9, Advanced Configurations, in the
AutoSys Installation and Getting Guide for UNIX.

Database Storage Requirements

The standard sizes for AutoSys databases are 64MB (Sybase) and 100MB
(Oracle). The standard sizes for AutoSys databases are the recommended
sizes. If your job load is large, you should create a larger database. The
size requirements for your database depend on the following:

■ The number of jobs you define.

■ How many of the jobs have dependencies.

■ How often the jobs are run.

■ How often the database is cleaned. (Every time a job runs, it generates
at least three events and an entry in the job_runs table.)

12 Database Architecture
Figure 12-1 shows the layout of databases in an AutoSys environment,
and it will help you understand AutoSys configuration options. It depicts
how AutoSys determines which database to use, and how the three
primary AutoSys components (the Event Processor, the AutoSys
database, and the Remote Agent) interact.

■ 12-18 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
AutoSys Database Overview

One Instance of AutoSys - $AUTOSERV

Read Config file to
Define determine which
Event Jobs database(s) to use.
Server 1

OS FILE:
config.$AUTOSERV

Event
Event Processor
Server 2
Instructs Remote Machine:
Command to execute and
database(s) to send events to.

Remote
Agent

database(s) Processes
Figure 12-1 • Layout of databases and primary component interaction

Figure 12-1 shows one instance of AutoSys that is configured with Dual
Event Servers, which are used only by this one instance. Both the Event
Processor and the Remote Agent ensure that events are written to the
appropriate database(s).

The controlling variable in the architecture is the environment variable

named AUTOSERV. This variable is the instance name that indicates,
among other things, the name of the configuration file to be used. The
configuration file name is determined by expanding the environment
variable in the following way:
$AUTOUSER/config.$AUTOSERV

This configuration file contains information about which database to

use, and in what capacity. All AutoSys commands access this file, unless
they are overridden at the command line with an argument that states an
instance name.

AutoSys User Guide for UNIX 12-19 ■

■ Maintaining AutoSys
General Database Maintenance

For information on configuring AutoSys instances, see Chapter 13,

Configuring AutoSys.

Note • Different instances of AutoSys can start jobs on the same

machine. The Remote Agent receives instructions from the Event
Processor at run time, and the Remote Agent can send events to the
necessary database(s).

12 General Database Maintenance

You can configure AutoSys to maintain itself as it runs. In fact, there are
defaults in place that provide frequent, automatic maintenance. You can
customize the configuration file. In addition to this regularly scheduled
maintenance, you can issue general and AutoSys database maintenance
commands from the command line.

Periodic maintenance is essential to keeping AutoSys working correctly.

Several AutoSys events are generated for each run of each job. If these
events are not “pruned” from the database periodically, the database will
eventually fill up, bringing AutoSys and its jobs to a halt. Therefore, we
recommend that you use the suggested periodic maintenance practices
described in this section.

12 Daily Database Maintenance

Once a day, the Event Processor performs internal database maintenance.
During this time, it does not process any events; it waits for the
maintenance activities to complete before resuming normal operations.
By default, this maintenance cycle starts at 3:30 a.m. If it is necessary to
change the start time, reset it to a time of minimal activity.

The DBMaintTime parameter in the AutoSys configuration file allows you

to specify the time for daily database maintenance. Use a 24-hour format
for the entry. For information on the database maintenance parameter,
see the Configuration File Parameters section in Chapter 13, Configuring
AutoSys.

■ 12-20 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
General Database Maintenance

12 DBMaint Script
By default, AutoSys executes the $AUTOSYS/bin/DBMaint script during its
daily maintenance cycle. This script runs the dbstatistics and
archive_events commands.

DBMaint runs the dbstatistics command to perform the following tasks:

■ Update statistics in the database for optimal performance. For Sybase

database, it updates statistics for the event, job, job_status, and
job_cond tables. For Oracle, it computes statistics for all of the
AutoSys tables.

■ Run the AutoSys dbspace command to check the available space in the
database. If the amount of free space is insufficient, it issues warning
messages and generates a DB_PROBLEM alarm.

Note • If you use an Oracle database, running DBMaint may report

that your database is close to full when this is not the case. This can
occur because DBMaint calculates how much space is not allocated
for extents. The extents may be nearly empty, but DBMaint reports
the whole extent as used space.

■ Calculate and update the average job run statistics in the avg_job_run
table. This information is used by AutoSys/Xpert. When dbstatistics
is run, old data is overwritten with the new data.

DBMaint runs the archive_events command to remove old information

from the various AutoSys database tables. Specifically, archive_events
removes the following:

■ Events and any alarms associated with them from the event table

■ Job run information from the job_runs table.

■ autotrack log information from the audit_info and audit_msg tables

■ ServerVision audit information from the svarchive_tbl table

AutoSys User Guide for UNIX 12-21 ■

■ Maintaining AutoSys
General Database Maintenance

The output from DBMaint, $AUTOUSER/out/DBMaint.out, tells you how

much space is left in your database, so that you can check (and monitor)
if the event tables are filling up. This is a good way to calculate how many
events in a single day can be maintained safely in the database before
they should be archived.

For more information on the dbstatistics and archive_events

commands, see their entries in Chapter 1, AutoSys Commands, of the
AutoSys Reference Guide for UNIX. For a list of the database tables and
views, as well as the event and alarm codes used in the tables, see
Chapter 6, Database Tables and Codes, in the AutoSys Reference Guide for
UNIX.
WARNING • If you are archiving large event tables, your SQL connection
might time out, causing the DBMaint script to core dump. If this occurs,
change the -t argument of the archive_events command to a higher
value.

Modifying the DBMaint Script

You can modify the $AUTOSYS/bin/DBMaint script. For example, you
might want to modify the script to perform database backups also. For
information on backing up bundled Sybase, see Bundled Sybase Backup
and Recovery on page 12-35.

When you modify the script, copy it first, and then add your
enhancements to the copied version. If you modify the script, you should
keep a backup copy of it; then, when you upgrade, you will not lose your
changes. You can use your enhanced script to modify the newly installed
script.

The script name is specified by the DBMaintCmd parameter in the AutoSys

configuration file.

■ 12-22 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Event Server Rollover Recovery

12 Event Server Rollover Recovery

When AutoSys is running in Dual Server mode and detects an
unrecoverable error condition on one of the Event Servers, it will
automatically rollover to Single Server mode.

An unrecoverable error is defined as one of the following:

■ The connection to the database is lost, and, after the configured

number of attempts to remedy this situation have transpired, the
database still remains unconnected.

■ A database has had an unrecoverable error (e.g., corrupt database or

media failure).

Upon Event Server rollover, the Event Processor edits the $AUTOUSER/
config.$AUTOSERV configuration file on only the Event Processor
machine(s). The Event Processor comments out the database that has
been taken off-line and marks the remaining database as being in Single
Server mode. The Event Processor makes these changes so that AutoSys
utilities attempting to access the database will write to or read from only
the running Event Server.

Note • On an Event Server rollover, the configuration file is edited on

the Event Processor machine(s) only; configuration files on client
machines are not modified.

12 Event Server Crash

If one Event Server crashes, AutoSys will automatically roll over to the
“healthy” server and continue running in Single Server mode. After you
recover the crashed server, you can reconfigure AutoSys to run in Dual
Server mode again.

AutoSys User Guide for UNIX 12-23 ■

■ Maintaining AutoSys
Event Server Rollover Recovery

Note • Do not, under any circumstances, restart the down Event

Server and run in Dual Server mode. Before starting the down server,
you must make sure that the two Event Servers are synchronized,
following the instructions in the Synchronizing the Event Servers section
below.

12 Synchronizing the Event Servers

If you have gone into Single Server mode due to problems, and now want
to go back to running Dual Event Servers, you must synchronize the
databases.

Note • Before doing this, you must have already installed and
configured your AutoSys system for Dual Event Servers, as described
in the Installing Dual Event Servers section in Chapter 9, Advanced
Configurations of the AutoSys Installation Guide for UNIX.

To synchronize the databases

1 Log onto a database machine as the AutoSys Exec Superuser.

2 Make sure that no one is executing jil or using the AutoSys GUI
dialogs to change job definitions.

3 Stop the Event Processor by entering the following command:

sendevent -E STOP_DEMON
After the Event Processor is stopped, no additional jobs will be started.

4 Synchronize the databases using the autobcp script. This is described

in detail in the Run the autobcp Script section in Chapter 9, Advanced
Configurations of the AutoSys Installation and Getting Started Guide for
UNIX.

■ 12-24 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Improving Database Performance

5 Edit the $AUTOUSER/config.$AUTOSERV configuration file on the server

machine. In the configuration file, remove the rollover comment from
the EventServer line that defines the sever that went off-line. The
Event Processor commented out this line during the rollover to Single
Server mode.

6 Start the Event Processor, using the eventor command on the AutoSys
Event Processor machine, like this:
eventor
Or, if you are running a Shadow Event Processor, start the Event
Processors like this:
eventor -M shadow_machine
The Event Processor should print a message indicating that it is in
Dual Server mode.

Note • If AutoSys is configured to run in Dual Server mode, the Event

Processor will not start unless both databases are available.

12 Improving Database Performance

This section contains information about improving your database
performance with AutoSys.

12 Improving Sybase Database Performance

These are ways to improve your Sybase database performance:

■ Increase the amount of memory that Sybase can use.

WARNING • Only the database administrator should increase Sybase
memory.

■ Upgrade your processor, memory, and/or hard disks.

AutoSys User Guide for UNIX 12-25 ■

■ Maintaining AutoSys
Improving Database Performance

■ Install the Sybase server and the Event Processor on a dedicated

machine or machines. Do not share machine resources with other
processes.

■ Use the Sybase server for AutoSys only.

■ Tune the kernel for optimal Sybase performance. For information on

how to do this, see your Sybase and operating system documentation.

■ For unbundled Sybase only, put your data on a raw partition. This
improves access time.
WARNING • Only the database administrator should put your data
on a raw partition.

12 Improving Oracle Database Performance

Tuning Oracle to improve its performance with AutoSys is complicated.
The following are some suggestions for the database administrator:

■ Tune the shared pool size. Make changes to the shared pool size by
altering the init.ora value of SHARED_POOL_SIZE.

To determine if you need to increase the shared pool size, enter the
following query in SQL*Plus:
select sum(pins) “Executions”,
sum(reloads) “Cache Misses while Executing”,
((sum(reloads)/sum(pins))*100) “Ratio of Misses”
from v$librarycache;

The Ratio of Misses should be less than 1%. (The Ratio of Misses
number is displayed as a percentage.) If it is higher than 1%, you
should increase the value of SHARED_POOL_SIZE incrementally
until the value of Executions approaches zero.

■ Tune the buffer cache. Make changes to the buffer cache by altering
the init.ora value of DB_BLOCK_BUFFERS.

■ 12-26 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Improving Database Performance

To determine if you need to allocate more memory, enter the

following query as the “sys” user in SQL*Plus:
select name, value
from v$sysstat
where name in
(‘db block gets’, ‘consistent gets’, ‘physical reads’);

Monitor the statistics from the query while AutoSys is running.

Calculate the hit ratio for the buffer cache by using this formula:

hit ratio = 1 - (physical reads/(db block gets + consistent gets))

The closer the hit ratio approaches 1.00, the better your system
performs. If you have free memory and the hit ratio is below .95,
increase the value of DB_BLOCK_BUFFERS. Make sure you have at
least 5% free memory.

■ Maximize disk I/O by separating the data files. If you have disk
contention, place the autodata and autoindexes data files on separate
disk drives, and if possible, different drive controllers.

■ Tune the sort area. A sort area in memory sorts records before they are
written to disk. Increasing the size of the sort area by increasing the
init.ora value of SORT_AREA_SIZE improves sort efficiency.

To determine if sorting is affecting the performance of your system,

monitor the sorting disk activity in your system by entering the
following query in SQL*Plus:
select name, value from v$sysstat
where name in (‘sorts (memory)’, ‘sorts (disk)’);

If disk sorts are greater than 1% of memory sorts, then increase the
value of SORT_AREA_SIZE.

AutoSys User Guide for UNIX 12-27 ■

■ Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

12 Maintaining Bundled Sybase SQL Servers

Because you can purchase AutoSys with a bundled Sybase database, this
section is specific to Sybase Event Server maintenance. It contains
information to help you query the database as well as to perform basic
maintenance procedures on Sybase SQL Server databases.

Note • The following sections are specifically for bundled Sybase

users. If you are using an existing Sybase or Oracle database with
AutoSys, consult your database administrator for details on starting,
stopping, and configuring your database.

12 Sybase Architecture
The Sybase database is based on a client/server architecture, with the
communications between clients and server built into the product. The
server portion is called the Sybase SQL Server. This server is a multi-
threaded, single process that runs on one machine. It listens on a specific
port for a request from a client, fulfills that request, and then returns the
information to the client.

The client communicates with the server using a C library known as Open
Client, or the DB Library. This library handles the communications
between the client application and the Sybase SQL Server as well as
sending requests and parsing results for the use of the application.

This means that all AutoSys commands and processes, including the
Event Processor, the Remote Agent, and monitors, are DB Library
applications that connect to the AutoSys database(s).

Because all AutoSys commands are merely Sybase clients, you can
execute those commands from any machine that has access to the Event
Server and is a licensed AutoSys client.

■ 12-28 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining Bundled Sybase SQL Servers

Note • The DB Library allows a client to maintain multiple

connections to the same server or multiple servers. It is through this
mechanism that the Dual Event Servers are maintained.

12 Sybase Environment
If you are using a Sybase, the following environment variables are used:

DSQUERY Defines the name of the Sybase dataserver.

SYBASE Specifies the complete path to the Sybase software

directory.

The Sybase software directory contains the Sybase configuration file,

which on UNIX is the interfaces file and on Windows NT is the SQL.INI
file. AutoSys uses the Sybase configuration file to look up database
information. It is the means by which the network is navigated to find the
Sybase dataserver.

12 Default Sybase Users

To perform many administrative tasks on your bundled Sybase database,
you use the xql utility, which is an AutoSys-supplied utility that can
access the Sybase dataserver from any properly configured client
machine. In most cases, you must log onto Sybase as “sa” using the
“sysadmin” password, or the appropriate password. You can log onto
Sybase within a command line, or you can log onto Sybase as “sa,” then
operate interactively at the xql prompt.

You do most of the Sybase administration through system-stored

procedures. All system-stored procedures start with the sp_ prefix.

For more information on using xql, see its entry in Chapter 1, AutoSys
Commands of the AutoSys Reference Guide for UNIX.

AutoSys User Guide for UNIX 12-29 ■

■ Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

Database Users
When using the bundled Sybase version of AutoSys, there are two users
defined by default in the AutoSys database: the system administrator and
the AutoSys user. Each of these users has a default user name and
password.

User User Name Default Password

System Administrator sa sysadmin

AutoSys User autosys autosys

For information on changing the “sa” password, see the next section,
Changing the System Administrator Password. For information on changing
the “autosys” password, see autosys_secure in Chapter 1, AutoSys
Commands, of the AutoSys Reference Guide for UNIX.

Changing the System Administrator Password

You can change the system administrator password from its initial value
of “sysadmin” to a new value.

To change the system administrator password

1 Execute the following xql command:

xql -Usa -Psysadmin

The following prompt appears:
xql>>[AUTOSYSDB][master] 1>

Note • If you are not using the default settings, the name of your
dataserver is substituted for AUTOSYSDB.

■ 12-30 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining Bundled Sybase SQL Servers

2 Enter the following command sequence (replacing newPassword with

the new password):
xql>>[AUTOSYSDB][master] 1> sp_password
xql>>[AUTOSYSDB][master] 2> sysadmin, newPassword;
Notice the semi-colon at the end of the command line. It is an end-of-
statement delimiter, replacing the Sybase “go”.

WARNING • After you change the “sa” password, the old password is
unrecoverable. Make sure that the new password is recorded; otherwise,
the entire database will have to be re-installed.

12 Starting Sybase
Starting Sybase involves executing the command that will bring up the
AutoSys database on the machine where AutoSys has been installed. The
following example is for Sybase-bundled versions of AutoSys. If there is
a pre-existing dataserver at your site, consult your local database
administrator about how to start the database.

To start the bundled Sybase

1 As the user who installed AutoSys, log onto the machine where the
dataserver is to run. This is usually done on the machine where
AutoSys has been installed, but not always. If the machine has a
windowing system running, use the console window. (You do this so
all AutoSys database messages will be displayed in that window.)

2 Source the $AUTOUSER/autosys.env file. This sets the $SYBASE

environment variable and the alias start_autodb.

3 Enter one of the following commands:

start_autodb
Or
$SYBASE/install/RUN_AUTOSYSDB
Both of these commands start the server in the background, then
output start-up messages.

AutoSys User Guide for UNIX 12-31 ■

■ Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

Note • The most common problem encountered when starting up

the AutoSys database is the permission assignments on the user
who owns the files that AutoSys uses. If you experience some
difficulty, ensure that you have the proper permissions to execute
the operation. If you do have the necessary permissions and the
database does not start, contact your Technical Support
representative.

4 To verify that the database is up and accessible, enter the following xql
command:
xql -Uautosys -Pautosys -c "select getdate()"
If this command returns the date, then the database is up.

12 Stopping Sybase
You must shut down Sybase before shutting down or rebooting the
machine. Before you shut down Sybase, however, you should shut down
the Event Processor.

To stop Sybase
1 If the Event Processor is running, stop it. To do this, log on as the Exec
Superuser and enter the following command:
sendevent -E STOP_DEMON

Note • If you are not sure whether the Event Processor is running,
do not sent the STOP_DEMON event. If the Event Processor is not
running and you send the event, it will be queued and sent when
the Event Processor is started again. Before you attempt to stop the
Event Processor, ensure that it is running by using the chk_auto_up
command.

2 Stop the Sybase service by entering the following command (the

sa_password is initially installed as “sysadmin”):

xql -Usa -Psa_password -c "shutdown"

■ 12-32 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining Bundled Sybase SQL Servers

This command allows any database processes to complete, and then

shuts the database down. If you must shut down the database
immediately, use this command:
xql -Usa -Psa_password -c "shutdown with no_wait"
For information on changing the “sa” password, see Changing the System
Administrator Password on page 12-30.

12 Accessing Sybase
AutoSys comes with a utility named xql, which resides in the $AUTOSYS/
bin directory. Use this utility for interactive database queries and for
shell-level database access. For a detailed description of how to use xql,
see its entry in Chapter 1, AutoSys Commands, of the AutoSys Reference
Guide for UNIX.

Some examples of using xql in a shell script can be found in the

following scripts:
■ $AUTOSYS/dbobj/create_table

■ $AUTOSYS/bin/chk_auto_up

Note • The xql utility functions only with the Sybase database. If you
use an Oracle database, use sqlplus instead.

AutoSys User Guide for UNIX 12-33 ■

■ Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

12 Identifying Processes Connected to the Database

These are reasons you might want to identify the processes that are
connected to the database:

■ Before you change the “autosys” user password or shut down AutoSys,
you should ensure that no processes are connected to the database.
You can identify the active processes, then shut them down.

■ Many GUI processes connected to the database can slow it down. You
can see how many and what type of processes are connected to the
database, and then ask users to shut down the GUIs they are not
currently using.

To see what processes are connected to the database and their status
} At the xql prompt, enter the following:
xql>>[AUTOSYSDB][master] 1> select program_name, hostname,
xql>>[AUTOSYSDB][master] 2> hostprocess,
xql>>[AUTOSYSDB][master] 3> status from sysprocesses;
The list of processes connected to the database is displayed, like this:
program_name hostname hostprocess status
--------------- ---------- ----------- ------------
xql Joe 14050 running
sleeping
sleeping
sleeping
sleeping
sleeping
event_demon Michelle 13448 recv sleep
jil Erik 12272 recv sleep

status 0, rows affected 8

■ 12-34 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining Bundled Sybase SQL Servers

In the example list of processes, xql is the process running your query to
display the processes, and event_demon is the Event Processor. The
processes without names are internal Sybase processes, which you can
ignore.

The following are the most common processes you will see (there are
others):

autocal event_demon sendevent

autocons hostscape timescape

autosc jil xql

auto_remote jobscape

12 Displaying the Database Date and Time

AutoSys jobs are scheduled and run based on the date and time for the
machine on which the database is running. If your jobs do not run when
you expect them to, you can check the database clock.

To display the database date and time

} At the xql prompt, enter the following:
xql>>[AUTOSYSDB][master] 1> select getdate();

12 Bundled Sybase Backup and Recovery

You must back up the AutoSys database periodically, so that you can
recover it in the event of catastrophic system or media failure. You should
decide on a routine for backing up the AutoSys database so that you will
have no trouble recovering a lost database, using the backup database
dump.

This section describes how to create a backup server and dump the
AutoSys database to a file, which you can then back up to tape.

AutoSys User Guide for UNIX 12-35 ■

■ Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

If you have not yet defined a dump device to Sybase, you must define a
disk or tape dump device, as described in Defining a Disk Dump Device on
page 12-36. Then follow the steps in Dumping the Database on
page 12-40.

Defining a Dump Device

A dump device can be either a disk or a tape.

Defining a Disk Dump Device

To define a disk as a dump device

1 Display the xql prompt, by entering the following command
(assuming that the “sa” password is “sysadmin”):
xql -Usa -Psysadmin
2 At the xql prompt, enter the following:

xql>sp_addumpdevice "disk", dump_device, "pathname", 2;

where:
dump_device
Is an arbitrary name; this name will be used for subsequent
database dumps and loads.
"pathname"
Is the full pathname of the file where the database dump will be
written. Ensure that this file can be created to the appropriate size
for your database, and that it can be mounted on the machine that
hosts the second Event Server.

For example, the following command will define a disk dump device
named “autodump,” and the database will be dumped to a file named
/backup/autodumpdata (for this example to work, the backup directory
must already exist).
xql>sp_addumpdevice "disk", autodump, "/backup/autodumpdata", 2;

■ 12-36 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining Bundled Sybase SQL Servers

Defining a Tape Dump Device

To define a tape device as a dump device

1 Display the xql prompt, by entering the following command
(assuming that the “sa” password is “sysadmin”):
xql -Usa -Psysadmin
2 At the xql prompt, enter the following:

xql>sp_addumpdevice "tape", dump_device, "physical_device", 3,

skip, size;
where:
dump_device
Is an arbitrary name; this name will be used for subsequent
database dumps and loads.
"physical_device"
Is the device name of the actual tape device on your machine.
size
Is the capacity of the tape device (in megabytes).

For example, the following command will define a tape dump device
named “autodumptape,” and the database will be dumped to a tape with
a 40MB capacity loaded in the device named /dev/rmt8.
xql>sp_addumpdevice "tape", autodumptape, "/dev/rmt8", 3, skip, 40;

Sybase Backup Server

If you are using bundled Sybase, you must create and start a backup
server.

AutoSys User Guide for UNIX 12-37 ■

■ Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

Creating a Backup Server

Note • If you are running on Dynix, NCR, Pyramid, SCO UNIX, SCO
UnixWare, or Solaris, skip this section and refer to Creating a Backup
Server Using autotli below.

To create a backup server

1 Edit the $SYBASE/interfaces file

2 Copy the entire entry for AUTOSYSDB to a new entry.

3 In the new entry, change AUTOSYSDB to SYB_BACKUP.

When you are finished, you will have two entries in your interfaces file:
one for AUTOSYSDB and another for SYB_BACKUP. Your SYB_BACKUP entry
should look similar to the following:
SYB_BACKUP
query tcp sun-ether fiji 5335
master tcp sun-ether fiji 5335
console tcp sun-ether fiji 5336
The above example creates a backup server on a host named “fiji,” using
port number 5335. The backup server port can be the same as the port
used by the dataserver.

Note • The format of the interfaces file requires that a single tab (do
not use spaces) precede the first word of every line that follows the
SYB_BACKUP line (which should not have any spaces before it). A single
space is used to delimit each element in an entry line. Incorrect
formatting will prevent communication with the database.

Creating a Backup Server Using autotli

For tli format, instead of editing the interfaces file directly, you run the
autotli command to define the backup server and append the output to
the interfaces file.

■ 12-38 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining Bundled Sybase SQL Servers

To create a backup server using autotli

} Enter the following command:
$AUTOSYS/install/autotli -s SYB_BACKUP -h host -p port >>
$SYBASE/interfaces
where:
SYB_BACKUP
Specifies the name of the backup server.
host
Specifies the host name.
port
Specifies the backup server port. The backup server port can be the
same as the port used by the dataserver, as long as the backup
server and dataserver are on different machines.
>>
Appends the information to the $SYBASE/interfaces file. (Be sure
to use two redirect symbols ( >> ); a single redirect ( > ) symbol will
overwrite the existing file.)

For example, the following command creates the backup server

“SYB_BACKUP” on host “fiji,” using port 5335:
$AUTOSYS/install/autotli -s SYB_BACKUP -h fiji -p 5335 >> $SYBASE/
interfaces

AutoSys User Guide for UNIX 12-39 ■

■ Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

The above command will create the following entry in the $SYBASE/
interfaces file:

# SYB_BACKUP on fiji (192.186.244.21) using tcp

# services: query (5335) master (5335) console (5336)
#
SYB_BACKUP
query tli /dev/tcp \x000214d7c0a8f4150000000000000000
master tli /dev/tcp \x000214d7c0a8f4150000000000000000
console tli /dev/tcp \x000214d8c0a8f4150000000000000000

Starting the Backup Server

To start the backup server

} Enter the following command:
$SYBASE/install/RUN_SYB_BACKUP
If you already defined a dump device to Sybase, continue with the next
section. Otherwise, you must define a disk or tape dump device to
Sybase, as described in Defining a Dump Device on page 12-36.

Dumping the Database

Verify that SYB_BACKUP (the backup server) is running before you dump
the database. If it is not running, start the backup server by entering the
following command:
$SYBASE/install/RUN_SYB_BACKUP

■ 12-40 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining Bundled Sybase SQL Servers

To dump a Sybase database

1 Enter the following xql commands:

xql -Usa -Psysadmin

xql>dump database database_name to dump_device;
where:
database_name
Is the name of the database that contains your AutoSys data. By
convention, this is “autosys.”
dump_device
Is the name of the Sybase dump device that you already defined to
Sybase.

For example, the following writes to a dump device named “autodump”:

xql>dump database autosys to autodump;

Loading the Database

To load the database

1 Sign on to the server that will contain the second Event Server.

2 Enter the following xql command:

xql -Usa -Psysadmin

3 To place the database in single user mode and guarantee that no
transactions can occur while the load is in progress, add the following
database options:
xql>sp_dboption autosys, "no chkpt on recovery", TRUE;
xql>sp_dboption autosys, "dbo use only", TRUE;
xql>sp_dboption autosys, "read only", TRUE;

AutoSys User Guide for UNIX 12-41 ■

■ Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

4 To issue a checkpoint, enter the following:

xql>checkpoint;
5 To load the database backup, enter the following:

xql>load database database_name2 from dump_device;

where:
database_name2
Is the name of the database that contains your AutoSys data. By
convention, this is “autosys.”
dump_device

Is the name for the Sybase dump device that you already defined to
Sybase.

For example, the following will load a disk dump named “autodump”
of the database named “autosys”:
xql>load database autosys from autodump;
6 After the load has succeeded, enter the following to unset the single
user options that you set before executing the load:
xql>sp_dboption autosys, "no chkpt on recovery", FALSE;
xql>sp_dboption autosys, "dbo use only", FALSE;
xql>sp_dboption autosys, "read only", FALSE;
7 To bring the database online, enter the following:

xql>online database autosys;

■ 12-42 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining Bundled Sybase SQL Servers

Recovering a Bundled Sybase Database

To recover a damaged AutoSys database using the backup file

1 Stop the Event Processor.

2 Drop the damaged database.

3 Re-create the database.

4 Reload the database.

5 Restart the Event Processor.

WARNING • You should drop the database and re-create it only in

extreme situations. Before using this process to recover a damaged
database, investigate all other options.

Stopping the Event Processor

To stop the Event Processor

} Log on as the Exec Superuser and issue the following command:
sendevent -E STOP_DEMON
Dropping the Damaged Database
You can drop the damaged AutoSys database by using the drop database
command. Before you drop the damaged database, however, you should
ensure that you have a database dump file to use to restore the database.

To drop the damaged database

1 Enter the following xql command (assuming that the “sa” password
is “sysadmin”):
xql -Usa -Psysadmin
2 At the xql prompt, enter the following:

xql>>[AUTOSYSDB][master] 1> drop database autosys;

If the AutoSys database is so damaged that drop database does not work,
contact your Technical Support representative.

AutoSys User Guide for UNIX 12-43 ■

■ Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

Note • The semicolon at the end of the command line is an

end-of-statement delimiter in xql, replacing the Sybase “go”.

Re-Creating the AutoSys Database

After dropping the damaged database, you must recreate a new AutoSys
database. This new database is used to load the database dump file (e.g.,
the autodump file) that you are recovering. Use the create database
command to create the new AutoSys database.

To re-create the AutoSys database

1 To create the new database, at the xql prompt, enter the following:

xql>>[AUTOSYSDB][master] 1> create database

xql>>[AUTOSYSDB][master] 2> autosys on default
xql>>[AUTOSYSDB][master] 3> = 50;

Note • The above size of 50MB is only an example.

The output generated by this command will look similar to this:

Msg 1805, Level 0, State 1, Line 1 CREATE DATABASE:
allocating 15360 pages on disk ‘default’
2 To change the owner of the new AutoSys database to “autosys,” enter
the following at the xql prompt:
xql>>[AUTOSYSDB][master] 1> use autosys;
xql>>[AUTOSYSDB][autosys] 1> sp_changedbowner
xql>>[AUTOSYSDB][autosys] 2> autosys;
When the procedure has completed successfully, a message similar to
this should be returned:
Database owner changed.

■ 12-44 AutoSys User Guide for UNIX

 Maintaining AutoSys ■
Maintaining Bundled Sybase SQL Servers

Reloading the Database

You are now ready to execute the load database command to restore the
database you originally dumped to autodump.

To reload the database and put it online

} Enter the following at the xql prompt:
xql>>[AUTOSYSDB][master] 1> load database autosys
xql>>[AUTOSYSDB][master] 2> from autodump;
xql>>[AUTOSYSDB][master] 1> online database autosys;
The AutoSys database is now restored and online.

Note • For Sybase System 11, you must put the database online.
Previous versions of Sybase did not require this.

To exit xql
} Enter the following at the xql prompt:
xql>>[AUTOSYSDB][master] 1> exit
Restarting the Event Processor
Then, you can restart the Event Processor. When you complete this
process, AutoSys will be in the state it was in when you dumped the
database to the backup file.

AutoSys User Guide for UNIX 12-45 ■

 13
Configuring AutoSys
The runtime behavior of AutoSys is controlled by the parameters in the
AutoSys configuration file and the environment variables set in the /etc/
auto.profile file. This chapter describes these files.

Note • If you are running AutoSys on Windows NT, the configuration

parameters are set through the AutoSys Administrator. For more
information on the AutoSys Administrator, see the AutoSys User Guide
for Windows NT.

AutoSys Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4

Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4

Configuration File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-10

Database Time-out Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10
Cross-Instance Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11
Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-12
Event Processor Cascading Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-13
Machines to Check for Running Event Processors . . . . . . . . . . . . . . . . . . . . 13-14
Third Machine for Event Processor Contention . . . . . . . . . . . . . . . . . . . . . . . 13-14
Event Processor Log Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15
Internal Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-16

AutoSys User Guide for UNIX 13-1 ■

■ Configuring AutoSys

Event Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-17

Sendevent Retries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-18
Heartbeats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-18
Shadow Event Processor Pings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-19
Remote Agent Log Files Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-20
File Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-21
Number of Restart Attempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-23
Calculating the Wait Time Between Restarts . . . . . . . . . . . . . . . . . . . . . . . . .13-23
Method of Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-24
KILLJOB Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-25
Port Number for Remote Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-26
AutoSysAgentSupport Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-27
Instance Wide Append Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-27
Job Starting Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-28

The auto.profile File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-29

Sample Default auto.profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-30
Remote Agent Database Connection Settings . . . . . . . . . . . . . . . . . . . . . . . .13-31

Modifying Remote Agent Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-33

Remote Agent Socket Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-33
Running Two AutoSys Versions of Remote Agents . . . . . . . . . . . . . . . . . . . .13-34

Configuring Remote Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-35

Configuring Event Processor Authentication . . . . . . . . . . . . . . . . . . . . . . . . . .13-35

Client-Side Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-37

Configuring ServerVision Monitoring and Reporting . . . . . . . . . . . . . . . . . . .13-38

Library Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-38
svload Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-38
ServerVision Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-39

■ 13-2 AutoSys User Guide for UNIX

 Configuring AutoSys ■

ServerVision Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-40

Monitoring Job Resource Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-40

User-Defined Alarm Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-41

AutoSys User Guide for UNIX 13-3 ■

■ Configuring AutoSys
AutoSys Configuration File

13 AutoSys Configuration File

Upon start-up, AutoSys reads the configuration file to determine its
behavior, including which database(s) to connect to and how to react to
certain error conditions. In particular, the Event Processor bases much of
its runtime behavior on the parameters found in this file. If you change
the settings in the configuration file, you must stop and restart the Event
Processor so it can read the new settings.

The configuration file has the following name:

$AUTOUSER/config.$AUTOSERV
The file is instance-specific, and the $AUTOSERV value is the name of the
instance of AutoSys with which the configuration file is associated. The
$AUTOSERV variable must be three uppercase alphabetic characters and
must be unique to each instance of AutoSys.

Note • Events have a unique ID called eoid, which is prefixed by the

first three letters of $AUTOSERV. This ensures an event’s uniqueness and
traceability across multiple instances.

13 Sample Configuration File

A sample configuration file can be found in the file named $AUTOSYS/
install/data/config.ACE. You might want to reference this file as you
read through this chapter. The configuration file has the following
entries:
# Configuration file for AutoSys
#
# Specify the Database(s)
#
EventServer=AUTOSYSDB:autosys
# Sybase database example

■ 13-4 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Sample Configuration File

#EventServer=SYBSERVER2:autosys
# Oracle database example
#EventServer=ORASERVER2
# # # # # # Tunable Parameters # # # # # #
#
# # # # Database Connection Parameters # # #
#
# Database Connection Time Out (in seconds)
DBLibWaitTime=90

# # # Cross Instance DB connection Flag # # #

# If = 0 connect before every EVENT is sent to the
# other Instance and drop after it is sent.
# If > 0 connect the first time an EVENT is sent, and
# maintain the connection forever.
XInstanceDBDropTime=1
#
# Number of times for Event Processor to attempt to
# Reconnect to Event Servers
#
DBEventReconnect=50
#
# USE the following for Dual DataBases
#DBEventReconnect=50,5
#
# # # # # Event Processor Parameters # # # # #

AutoSys User Guide for UNIX 13-5 ■

■ Configuring AutoSys
Sample Configuration File

#
# Event Processor ERRORS
# If there are more than 20 errors in 60 seconds it
# will exit. The MAX value of EDNumErrors is 100.
EDNumErrors=20
EDErrTimeInt=60
#
# Machines for chk_auto_up to inspect to see if an
# Event Processor is running there.
#EDMachines=host1,host2,host3
EDMachines=localhost
#
# For Shadow Event Processor, the Third Machine to
# resolve contention problems between Event
# Processors
#ThirdMachine=a_hostname
#
# Minimum kbytes of space that must be available for
# the EP log file (on the partition or disk). If free
# space falls below this, the EP will issue warnings
# and shut down.
#
FileSystemThreshold=32
# Event Processor’s internal Daily Database
# Maintenance Cycle # #
#
# Daily start-time
DBMaintTime=03:30
# Command to Run to perform Maintenance

■ 13-6 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Sample Configuration File

#
DBMaintCmd=$AUTOSYS/bin/DBMaint
#
# For Dual Server Mode - transfer events timeout
EvtTransferWaitTime=5
#
# Check Heartbeat every 2 minutes
#Check_Heartbeat=2
#
# Output Directory for the Remote Agent
#
# Note: Some OS’s have problems with file locks in /tmp
# If so use some directory other than /tmp.
#
AutoRemoteDir=/tmp
#
# Clean Remote Agent files: 1=Remove files if No
# Problems!
CleanTmpFiles=1
#
# Create Remote Agent Output File for Sourcing the
# Environment
# In UNIX: capture std_out & std_err from sourcing
# /etc/auto.profile
# In NT: output the Environment to the file
#
RemoteProFiles=1

AutoSys User Guide for UNIX 13-7 ■

■ Configuring AutoSys
Sample Configuration File

#
# Host machines to send SNMP traps to. (Specifying
# a machine ENABLES traps)
#SnmpManagerHosts=host1,host2
#
# Snmp community. This is almost always "public"
#SnmpCommunity=public
# Enable sending HP Operations Center messages (opcmsg)
# for AutoSys alarms.
# This defines the message group under which
# messages will be sent.
#OpcMessageGroup=Job
#
# This parameter sets the amount of time that the
# event_demon will wait for the OpCenter message
# to be sent.
#
#OpcWaitTime=4
#
# RESTART configuration stuff
#
# Max number of times to RESTART a job due to system
# errors
MaxRestartTrys=10
#
# Formula for computing the Wait time between
# restart attempts:
# WaitTime = RestartConstant+(Num_of_Trys *
# RestartFactor)

■ 13-8 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Sample Configuration File

# if (WaitTime > MaxRestartWait) then

# WaitTime = MaxRestartWait
#
RestartConstant=10
RestartFactor=5
MaxRestartWait=300
# Preferred method of Load Balancing
# Can be: vmstat | rstatd (default is vmstat)
#MachineMethod=rstatd
#
# List of Signals to Send to a Job for the KILLJOB
# event
KillSignals=2,9
#
# Port number of auto_remote
AutoRemPort=5280
#
# Specify if standard error and standard output
# files should be appended to or overwritten.
# 0 overwrites the file.
# 1 appends the file.
AutoInstWideAppend=1
#

The following sections describe these configuration parameters.

AutoSys User Guide for UNIX 13-9 ■

■ Configuring AutoSys
Configuration File Parameters

13 Configuration File Parameters

You can modify the parameters in the AutoSys configuration file to
control the behavior of AutoSys and optimize your system.

The Event Processor reads the settings in the configuration file on startup
only. Therefore, if you make changes to the file, you must stop and restart
the Event Processor so it can read the new settings.

To stop and restart the Event Processor

1 Stop the Event Processor, using the following command:

sendevent -E STOP_DEMON
2 Restart the Event Processor, like this:

eventor
Or, if you are running AutoSys with a Shadow Event Processor, you
can start both the Primary and the Shadow Event Processors at the
same time, like this:
eventor -M shadow_machine

13 Database Time-out Period

DBLibWaitTime (Sybase Only)
The DBLibWaitTime configuration parameter specifies the amount of time
the Event Processor will wait before breaking the connection with an
Event Server that is in an unknown state. The Event Processor continually
maintains and checks its connections with the database(s), and when an
Event Server goes into an unknown state, the Event Processor will break
the connection after the wait time specified by the DBLibWaitTime
parameter.

The following line in the configuration file sets the timer for 90 seconds:
DBLibWaitTime=90

■ 13-10 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Configuration File Parameters

Typically, the database should never time out. However, if a database

does time out, AutoSys will attempt to reconnect to the database the
number of times specified by the DBEventReconnect parameter. If you see
the database connections timing out often, it probably indicates some
kind of machine or dataserver contention problem.

Note • If you set this value to DBLibWaitTime=0, it means that no

time-out value is to be applied—the connection is continuous.
Because it can cause the Event Processor to hang, this setting is not
recommended.

13 Cross-Instance Database Connections

XInstanceDBDropTime
The XInstanceDBDropTime parameter specifies how an AutoSys instance
will connect with another AutoSys instance if it has a job defined with a
cross-instance job dependency.

If the value of this parameter is equal to zero, the Event Processor will
connect to the other instance before every new event is sent. After the
event has been sent, the connection will be dropped. Use this option for
instances that are using cross-instance job dependencies infrequently.

If the value of this parameter is equal to one, the Event Processor will
connect to the other instance before the first event is sent, and it will
maintain the connection indefinitely. Use this option for instances that
are using cross-instance job dependencies often.

The following line in the configuration file sets the cross-instance

connection to 1, and thus, the Event Processor will maintain the
connection after making the initial connection:
XInstanceDBDropTime=1

AutoSys User Guide for UNIX 13-11 ■

■ Configuring AutoSys
Configuration File Parameters

13 Database Connections
AutoSys can be configured to attempt connect, and reconnect, to
databases a specified number of times. This behavior occurs when the
first attempt to connect to the database is made, and when a database
connection has been lost and there is a reconnect attempt made. This
database connection behavior also sets the rollover criteria for Dual
Server Mode.

DBEventReconnect
The DBEventReconnect parameter controls the number of times an Event
Processor should attempt to connect (or reconnect) to an Event Server
before shutting down, or before rolling over to Single Server Mode. This
parameter is used on start-up and when there is a connection problem
during runtime.

In Single Server Mode, this parameter is set to a simple number, like this:
DBEventReconnect=50
This setting specifies that the Event Processor should attempt a
connection with the Event Server 50 times. If it cannot connect after 50
attempts, it shuts down.

In Dual Server Mode, this parameter contains two values describing the
connection and rollover behaviors, like this:
DBEventReconnect=50,5
This setting specifies that the Event Processor should attempt 5
connections with the Event Servers. If after 5 times it cannot connect, it
should rollover to Single Server Mode, marking the other Event Server as
“down.” Once in Single Server Mode, the Event Processor should attempt
a connection 50 times, and if it is unsuccessful, the Event Processor shuts
down.

■ 13-12 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Configuration File Parameters

Upon startup, the Event Processor attempts to connect to the Event

Servers 5 times. If the Event Processor is unable to connect to both
databases, it assumes there is a connection or configuration problem,
and will gracefully shutdown.

13 Event Processor Cascading Errors

To guard against cascading errors, you can set bounds that will force
AutoSys to automatically shut down the Event Processor if too many
errors occur within a certain period of time. The EDNumErrors and
EDErrTimeInt parameters work together to guard against these cascading
Event Processor errors, which are caused by the Event Processor
automatically re-issuing failed directives.

The primary reason for setting these two parameters to shut the Event
Processor down in this situation is to avoid starting any new processes
while there are serious problems in the system.

EDNumErrors, EDErrTimeInt
The EDNumErrors parameter specifies the maximum number of errors that
can happen within the time specified by the EDErrTimeInt parameter, in
order to determine if AutoSys should shut down the Event Processor. If
the specified Number of Errors occurs within the Error Time Interval,
AutoSys shuts down the Event Processor as a safety measure.

If there are more than EDNumErrors errors within EDErrTimeInt seconds,

AutoSys shuts down the Event Processor. The default settings specify to
shut the processor down if more than 20 errors occur within 60 seconds,
and the entries in the configuration file look like this:
EDNumErrors=20
EDErrTimeInt=60

AutoSys User Guide for UNIX 13-13 ■

■ Configuring AutoSys
Configuration File Parameters

13 Machines to Check for Running Event Processors

EDMachines
The EDMachines parameter specifies a list of valid AutoSys server
machines on the network. AutoSys checks all of the machines on this list
for running Event Processors, both when chk_auto_up is run and when a
new Event Processor is started.

The list should contain all of the machines that could have a started and
running Event Processor on them, so that a new Event Processor cannot
be started on a different machine. Having a complete list of EDMachines
is especially critical when a Shadow Event Processor takeover has
occurred, and your Primary server is configured to automatically restart
the Event Processor.

The entry in the configuration file looks like this:

EDMachines=host1,host2,host3

13 Third Machine for Event Processor Contention

ThirdMachine
When running with a Shadow Event Processor, AutoSys uses a “Third
Machine” to resolve possible contentions between the two Event
Processors, and to ensure that only one of the processors is running at
any given time.

If the Shadow Event Processor does not receive a “ping” from the Primary
Event Processor, or if the Primary Event Processor cannot signal the
Shadow Event Processor, the processor(s) connect to this Third Machine
and create a .dibs file that locks the other processor out. The .dibs file
indicates that the one Event Processor has taken over and the other
should shut down.

■ 13-14 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Configuration File Parameters

The Third Machine must have a Remote Agent installation on it. In

addition, the Third Machine’s hostname must be in the AutoSys
configuration file on both the Primary and Shadow Event Processor
machines. For example, to specify the machine named “ferrari” as the
Third Machine, enter the following line in the configuration files for both
Event Processor machines:
ThirdMachine=ferrari

Note • The Third Machine must have a Remote Agent installed on it,
and it must have a valid client license. In addition, the Third Machine
must be installed on the same type of machine as the Primary and
Shadow Event Processors, either Windows NT or UNIX.

For more information on running AutoSys with a Shadow Event

Processor, see the Shadow Event Processor section in Chapter 1, Introduction
to AutoSys, of the AutoSys Installation and Getting Started Guide for UNIX.

13 Event Processor Log Disk Space

The Event Processor will shut down if there is less than 8 kilobytes of disk
space available to write to the Event Processor log file
(event_demon.$AUTOSERV). If the amount of available disk space falls
below that specified by the FileSystemThreshold parameter, the Event
Processor will issue warnings in the Event Processor log file similar to the
following:
WARNING: The disk partition containing the EP log file is too full!
WARNING: EP will shutdown if partition has less than 8192 bytes
available!

The default FileSystemThreshold setting is 32 kilobytes. Valid settings

must be less than 10 MB and greater than 8192 bytes.

AutoSys User Guide for UNIX 13-15 ■

■ Configuring AutoSys
Configuration File Parameters

If the amount of disk space falls below 8 kilobytes, the Event Processor
will issue an EP_SHUTDOWN alarm and shut down, issuing messages
similar to the following:
ERROR: No disk space left to write Event Processor log

EVENT: STOP_DEMON

The Event STOP_DEMON has just been received. We are going down!

The entry in the configuration file looks like this:

FileSystemThreshold=32

13 Internal Database Maintenance

Once a day, the Event Processor goes into a database maintenance cycle.
During this time, it does not process any events, and it waits for the
maintenance activities to complete before resuming normal operations.

In the configuration file, you can specify the time of day for this
maintenance cycle, and you can specify a maintenance command. The
time you specify should be during a time of minimal activity.

AutoSys provides a database maintenance script called DBMaint to run

during this maintenance cycle. This script does the following:

■ Calculates and updates the average job runs statistics for AutoSys/
Xpert.

■ Updates statistics for the optimizer, checks the available space in the
database, and sends a DB_PROBLEM alarm if the amount of free
space is insufficient.

■ Cleans out old information from the AutoSys database tables using
the archive_events command.

The DBMaint file is installed in the $AUTOSYS/bin directory. It is

recommended that you configure your system to backup the database
during this maintenance cycle.

■ 13-16 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Configuration File Parameters

For more information on using the DBMaint script and backing up a

bundled Sybase database, see the DBMaint Script and Bundled Sybase
Backup and Recovery sections in Chapter 12, Maintaining AutoSys.

DBMaintTime, DBMaintCmd
The following entries in the configuration file instruct the Event
Processor to begin its maintenance cycle at 3:30 a.m. every day, and to
execute the $AUTOSYS/bin/DBMaint script at that time:
DBMaintTime=03:30
DBMaintCmd=$AUTOSYS/bin/DBMaint

13 Event Transfer
When in Dual Server Mode, the Event Processor will copy a missing event
from one Event Server to the other Event Server, after a time-out delay.
This time-out delay is specified by the EvtTransferWaitTime parameter in
the configuration file. The default setting of 5 does not usually need to be
modified.

EvtTransferWaitTime
To set the default behavior of 5 seconds for the time-out, the
configuration file contains the following line:
EvtTransferWaitTime=5

AutoSys User Guide for UNIX 13-17 ■

■ Configuring AutoSys
Configuration File Parameters

13 Sendevent Retries
The following two configuration file parameters control how many times
and how frequently the sendevent command will attempt to send an
event to the Event Server database.

SendeventMaxRetries
Specifies the maximum number of times that the sendevent command
will attempt to send an event to the Event Server database.
To set the number of retry attempts to 10, enter the following line in the
configuration file:
SendeventMaxRetries=10

SendeventRetryInterval
Specifies the interval, in seconds, between attempts to send an event to
the Event Server database. There is no default value.
To set the interval to 15 seconds, enter the following line in the
configuration file:
SendeventRetryInterval=5

13 Heartbeats
Heartbeats offer a method by which the continued progress of an
application can be automatically monitored. That is, you can program
your user applications to send “heartbeats” that can be monitored by
AutoSys. A heartbeat is a signal (SIGUSR2) sent from the application to
the Remote Agent that started the application. That Remote Agent then
sends a HEARTBEAT event to the AutoSys Event Server(s).

The Event Processor will check that the HEARTBEAT event has occurred
within the heartbeat interval specified for the job.

■ 13-18 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Configuration File Parameters

Note • The Event Processor, and not the Remote Agent, checks if there
is a HEARTBEAT between the Remote Agent and the Event Server(s),
and if the HEARTBEAT is absent, there is a problem, and an alarm is
sent. Therefore, the HEARTBEAT option also provides a good
indication of the stability of the network.

Check_Heartbeat
The Check_Heartbeat parameter specifies the interval value (in minutes)
that you want the Event Processor to use when checking for heartbeats. If
there are no applications sending heartbeats, you do not have to set this
parameter. By default, this parameter is commented out in the AutoSys
configuration file.

For example, to instruct the Event Processor to check for missing

heartbeats every two minutes, you would uncomment the following line
in the configuration file:
Check_Heartbeat=2

13 Shadow Event Processor Pings

In high-availability mode, the Shadow Event Processor pings the Primary
Event Processor periodically to ensure that it is still running. The
following parameter determines the ping interval.

ShadowPingDelay
Specifies the interval, in seconds, after a succesful ping of the Shadow
Event Processor before another ping is attempted. The default is 60
seconds.
To set the interval to 30 seconds, enter the following line in the
configuration file:
ShadowPingDelay=30

AutoSys User Guide for UNIX 13-19 ■

■ Configuring AutoSys
Configuration File Parameters

13 Remote Agent Log Files Directory

During its operation, the Remote Agent writes output messages to files in
the directory specified by the AutoRemoteDir parameter. For some
operating systems, the locking of files located on the /tmp file system is
not supported (e.g., on SunOS platforms when /tmp is mounted on
tmpfs). Since AutoSys uses the locks to determine if the Remote Agent is
running, another directory must be specified.

The AutoRemoteDir parameter is passed to the Remote Agent by the Event

Processor when it starts. As a result, the Remote Agent log files directory
must already exist, and be “writable” on every machine running AutoSys.

In a cross-platform environment where a UNIX Event Processor starts a

Windows NT Remote Agent (or vice versa), the path to the log files
directory is translated into the format expected by the recipient platform.
A UNIX Remote Agent will remove the drive letter and colon, if present,
and replace \ characters with / characters. For example, C:\tmp becomes
/tmp. A Windows NT Remote Agent will prepend the system drive letter
and colon if they are not present, and replace all / characters with \
characters. For example, /tmp becomes C:\tmp.

AutoRemoteDir
The following entry in the configuration file specifies that the Remote
Agents should use the /tmp directory for enterprise-wide logging:
AutoRemoteDir=/tmp

■ 13-20 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Configuration File Parameters

13 File Maintenance

CleanTmpFiles
For every job that AutoSys runs, it creates a file in the Remote Agent Log
directory on the machine where the job runs. If CleanTmpFiles is turned
off, these files remain on each machine until they are removed with the
clean_files command.

As an alternative to using the clean_files command, you can set the

value for the CleanTmpFiles variable in the configuration file to be equal
to 1, like this:
CleanTmpFiles=1
Then, upon the successful completion of its tasks, the Remote Agent will
remove the /tmp/auto_rem* file (assuming the default /tmp directory is
specified by the AutoRemoteDir parameter). This is the format of the
Remote Agent log filename, the auto_rem* file that is removed:
auto_rem.joid.run_number.ntry
If the Remote Agent cannot run the job successfully, the files will not be
removed because they are useful to have when diagnosing the run
problem.

Note • To view the Remote Agent output file, use the autosys_log
command on the client machine, like this:
autosys_log -J job_name

Note • Regardless of how you set the CleanTmpFiles parameter, you

should run the clean_files command on a periodic basis to remove
files from unsuccessful Remote Agent processes.

AutoSys User Guide for UNIX 13-21 ■

■ Configuring AutoSys
Configuration File Parameters

RemoteProFiles
When the RemoteProFiles parameter is turned on, it redirects to a file any
stderr and stdout output generated when the /etc/auto.profile file is
sourced. This parameter is “on” by default, and the entry in the
configuration file looks like this:
RemoteProFiles=1

The name of the file to which the profile output is written is based on the
log file name. This is the form of the auto_rem_pro* filename:
auto_rem_pro.joid.run_number.ntry
This output file will contain entries if anything specified in the profile file
failed (e.g., environment variables or definitions were not set). For
example, if the profile file attempts to set an environment variable using
setenv, the Bourne shell that AutoSys runs would not be able to process
this C Shell syntax, and the output file would contain the following line:
setenv: not found

Non-fatal errors when a profile file is sourced are not recorded and will
not appear in the output file.

To view the profile output file, use the autosys_log command on the
client machine, like this:
autosys_log -J job_name -p
This command will display the log file first, appending the profile
output, if there is any. If no profile output file exists, the log file will
display this:
File: profile_output_file Does Not Exist.

Note • If CleanTmpFiles is turned on (set to 1), the output file will be

removed when the job completes successfully, and the profile log
information will not be available. If CleanTmpFiles is turned off, the
file will remain until it is removed with the clean_files command.

■ 13-22 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Configuration File Parameters

13 Number of Restart Attempts

MaxRestartTrys
AutoSys attempts to restart a job if it has problems starting the job due to
system problems, such as machine unavailability, the socket connect
timed out, the Remote Agent was unable to start another process, or the
file system space resource check failed. AutoSys attempts to restart a job
the number of times specified by the MaxRestartTrys parameter.

For example, to set the number of job restarts to 5, include the following
line in the configuration file:
MaxRestartTrys=5

Note • This parameter governs retries that result because of system or

network problems. It is different from the n_retrys job definition
attribute, which controls restarts when a job fails due to application
failure (e.g., AutoSys is unable to find a file or a command, or
permissions are not properly set).

13 Calculating the Wait Time Between Restarts

RestartConstant, RestartFactor, MaxRestartWait

The following formula is used to calculate the amount of time (in
seconds) that AutoSys will wait between each restart of a job:
WaitTime=RestartConstant+(Num_of_Trys*RestartFactor)
if WaitTime > MaxRestartWait,
then WaitTime = MaxRestartWait
where:
WaitTime
Is the calculated interval in seconds to wait before attempting the next
restart of a job.

AutoSys User Guide for UNIX 13-23 ■

■ Configuring AutoSys
Configuration File Parameters

RestartConstant

Is a constant value you specify.

Num_of_Trys
Is the AutoSys counter tracking the number of times the job has
already tried to start.
RestartFactor
Is a factor you specify.
MaxRestartWait

Is the maximum amount of time (in seconds) AutoSys will wait before
it attempts to restart a job.

If the calculated WaitTime is greater than the specified value for

MaxRestartWait, then the resulting WaitTime is set to MaxRestartWait.

For example, the entry in the configuration file might look like this:
RestartConstant=10
RestartFactor=5
MaxRestartWait=300

13 Method of Load Balancing

MachineMethod
This parameter specifies the method AutoSys will use to determine the
percentage of CPU cycles available on a real machine belonging to a
virtual machine. This method is used to achieve load balancing. The
possible choices are rstatd and vmstat. If MachineMethod is not specified,
vmstat is the default setting.

For example, to set the method to rstatd, enter this in the configuration
file:
MachineMethod=rstatd

■ 13-24 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Configuration File Parameters

If rstatd is chosen, you must ensure that this daemon is running on all
client machines.

To ensure that the daemon is running, do the following:

■ Edit the internet daemon configuration file (/etc/inetd.conf) on all

client machines, and un-comment the rstatd entry.

■ Send a SIGHUP signal (kill -1) to reset the running inetd process.

Sometimes, a kill -1 command is not sufficient to reset the inetd. If

rstatd fails, you might have to issue a kill -9 command, then restart
inetd. If necessary, check with your systems administrator.

Note • rstatd is not currently supported on NCR or Pyramid client

machines.

13 KILLJOB Signals

KillSignals
The KillSignals parameter specifies a comma-separated list of signals to
send to a job whenever the KILLJOB event is sent. If the job is running on
a UNIX machine, the parameter specifies a single or comma-delimited
list of UNIX signals to be sent to the job. If a list of signals is specified,
the signals are sent in the order listed, with five second sleeps between
each call.

If the job to be killed is running on a Windows NT machine, this list is

ignored and the job is simply terminated.

To preserve AutoSys backward compatibility, the entry in the

configuration file is:
KillSignals=2,9

AutoSys User Guide for UNIX 13-25 ■

■ Configuring AutoSys
Configuration File Parameters

We recommend that you set this parameter to 15,9. In most cases, this
will lead AutoSys to return a TERMINATED state for a job that was killed.
If it does not, as might happen for some shells on some operating
systems, set the KillSignals parameter to 9.

Note • The KillSignals listed in the configuration file are overridden

when issuing the sendevent command with the -k option.

13 Port Number for Remote Agent

AutoRemPort
The Event Processor communicates to the Remote Agent by way of a TCP/
IP socket connection, and the port number for this socket connection is
specified by the AutoRemPort parameter. The internet services daemon
(inetd) on the client machine uses the port number to point to the name
of the service (found in /etc/services). The service name is located in
the inetd configuration file (/etc/inetd.conf), where it finds the
pathname to the Remote Agent binary.

It is possible to have different versions of AutoSys installed on the same

hardware, where the versions are not cross compatible between the Event
Processor and the Remote Agent. By setting up multiple services and
using different port numbers, you can maintain multiple versions of the
software.

The AutoRemPort number in the configuration file is set at installation

time. If you alter it, you must change both the AutoRemPort number and
the port numbers in all the /etc/services files on all AutoSys client and
all AutoSys server machines.

This is the entry in the configuration file, with the default setting of 5280:
AutoRemPort=5280

■ 13-26 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Configuration File Parameters

Note • If you are using NIS or NIS+, and wish to change AutoRemPort,
you must modify /etc/services on your NIS or NIS+ master and push
it to all client machines, and then do a kill -1 process on the inetd.

13 AutoSysAgentSupport Parameter

AutoSysAgentSupport
The AutoSysAgentSupport parameter specifies whether an AutoSys
instance can dispatch jobs on machines managed by AutoSys Connect or
AutoSys Agent.

If the value of this parameter is equal to zero, then the Event Processor
will not send jobs to AutoSys Connect and AutoSys Agent managed
machines. If the value of this parameter is equal to one, then the Event
Processor will send jobs to these machines.

By default, AutoSys Connect and AutoSys Agent job support is off, and
the entry in the configuration file looks like this:
AutoSysAgentSupport=0

For more information, see Appendix A, Integrating with the Mainframe and
AutoSys Agents for AS/400 and OpenVMS.

13 Instance Wide Append Parameter

AutoInstWideAppendx
The AutoInstWideAppend parameter specifies whether an AutoSys
instance will overwrite or append information to the standard output
and standard error files.

If the value of this parameter is equal to zero, then the files will be
overwritten. If the value of this parameter is equal to one, then new
information will be appended to the files.

AutoSys User Guide for UNIX 13-27 ■

■ Configuring AutoSys
Configuration File Parameters

By default, new information is appended to the files, and the entry in the
configuration file looks like this:
AutoInstWideAppend=1
Each client machine can override the instance-wide setting by using the
AutoMachWideAppendvariable in the /etc/auto.profile file. If specified,
this variable would appear as shown in the following example:
#AUTOENV#AutoMachWideAppend=YES

Note • If you are running jobs across platforms, the Event Processor
of the issuing instance controls the default behavior. For Windows
NT, the default is to overwrite this file.

An individual job definition can override either the instance-wide or the

machine setting by placing the following notation as the first character(s)
in the standard output and standard error files specifications:

> Overwrite file

>> Append file

13 Job Starting Interval

InetdSleepTime
The InetdSleepTime parameter controls how long the inetd waits
between job starts on the same Remote Agent machine. By default, this is
set to 2 seconds, and there is no parameter located in the configuration
file. To reduce the time the inetd waits between job starts on a machine,
you can add the InetdSleepTime parameter to the configuration file and
lower this number, which is specified in seconds.

To lower the default setting, add an entry like this to the configuration
file:
InetdSleepTime=1

■ 13-28 AutoSys User Guide for UNIX

 Configuring AutoSys ■
The auto.profile File

Note • Setting InetdSleepTime too low for your hardware could

adversely affect performance. In addition, you must ensure your
machine has a processor fast enough to handle starting jobs at a faster
interval. Otherwise, there will be frequent socket connection failures,
which will cause numerous job restarts.

13 The auto.profile File

The Remote Agent is a process (called auto_remote) started by the Event
Processor to perform a specific task on a remote (client) machine. The
Remote Agent starts the command specified for a given job, sends
running and completion information about a task to the Event Server,
then exits.

The Remote Agent starts on the client machine as “root”. The Remote
Agent environment is controlled through special descriptors located in
the /etc/auto.profile file, located on the remote (client) machine.

The /etc/auto.profile file serves two purposes for AutoSys:

■ It specifies a number of descriptors that set the environment for the

Remote Agent on the client machine. These descriptors are
environment variables that are preceded by the characters:
#AUTOENV#
■ It specifies default settings for AutoSys jobs that do not have a profile
specified in the job definition. A job profile sets environment
variables for a job immediately before the job is started. This job
attribute is discussed in Chapter 4, Job Attributes.

You may want to view the /etc/auto.profile file in a text editor to

familiarize yourself with the environment settings in this file.

Other settings that can be added to the auto.profile are:

AutoSys User Guide for UNIX 13-29 ■

■ Configuring AutoSys
The auto.profile File

AutoMachWideAppend See Instance Wide Append Parameter on

page 13-27

AUTOSV See ServerVision Environment Variables on

AUTOSV_DIR page 13-39

DENY_USER See Client-Side Security on page 13-37.

13 Sample Default auto.profile

The following example auto.profile file is for an AutoSys with Sybase
installation.
# Set some environmental variables
#
# This must be a Bourne shell script,
# AND the variables exported for your command
# to see them.
# The following lines with $AUTOSYS and $AUTOUSER need to be
#uncommented if either:
# 1) running shadow EP, AND directories are in different locations
# 2) job's command is calling an AutoSys program.
#AUTOSYS=/dev/3.4/SYB ;export AUTOSYS
#AUTOUSER=/dev/3.4/SYB/autouser ;export AUTOUSER
# The following is for the windowing system
DISPLAY=":0.0"
export DISPLAY
LD_LIBRARY_PATH=/usr/openwin/lib:/usr/lib/X11; export
LD_LIBRARY_PATH
# set a PATH so executables can be found
PATH=".:$AUTOSYS/bin:$AUTOSYS/test/bin:/bin:/usr/bin:/usr/local/
bin:/usr/openwin/bin:/usr/bin/X11:/bin:/usr/ucb:/usr/etc"
export PATH
####################################################

■ 13-30 AutoSys User Guide for UNIX

 Configuring AutoSys ■
The auto.profile File

# auto_remote environment variables

# DO NOT REMOVE
#AUTOENV#SYBASE=/usr/vendors/sadb

The Remote Agent looks for the #AUTOENV# descriptors and reads the
variables that follow to set its environment. Do not remove the
#AUTOENV# descriptors from the file. They are required to enable the
Remote Agent to communicate with the AutoSys database.

Note • The #AUTOENV# descriptor is not a comment. Do not remove the

# character from the beginning of the line.

13 Remote Agent Database Connection Settings

Some of the environment variable descriptors in the auto.profile file
define the Event Server(s) to which the Remote Agent should write
events.

Sybase
For Sybase, the descriptor looks like this:
################################################
# auto_remote environment variables
# DO NOT REMOVE
#AUTOENV#SYBASE=/usr/vendors/sadb

The #AUTOENV#SYBASE descriptor defines where the Remote Agent looks

for the Sybase interfaces file, which is specified by the SYBASE
environment variable. If the interfaces file is not present in this
location, the Remote Agent will not be able to write job statuses to the
database.

AutoSys User Guide for UNIX 13-31 ■

■ Configuring AutoSys
The auto.profile File

Note • A common symptom that results from the Remote Agent being
unable to write to the database is that jobs will remain in starting
state.

Oracle
For Oracle, the descriptors look like this:
################################################
# auto_remote environment variables
# DO NOT REMOVE
#AUTOENV#TNS_ADMIN=/etc
#AUTOENV#ORACLE_HOME=/var/opt/oracle

The #AUTOENV#TNS_ADMIN descriptor defines where the Remote Agent

looks for the tnsnames.ora file, if the TNS_ADMIN environment variable is
set. If the TNS_ADMIN variable is not set, the Remote Agent looks in the
default directory, which is operating system specific.

The #AUTOENV#ORACLE_HOME descriptor defines the top-level Oracle

directory, defined by the ORACLE_HOME environment variable.

■ 13-32 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Modifying Remote Agent Settings

13 Modifying Remote Agent Settings

To function correctly, the Remote Agents must have the correct TCP/IP
socket connections, and they must have the appropriate environment set.
The socket connection and environment values are set at installation
time, but you can modify the settings.

13 Remote Agent Socket Connection

The Event Processor communicates with the Remote Agent by way of a
TCP/IP socket connection. The port number for this socket connection is
set in the following two files, and the number must be identical in both
locations:

■ $AUTOUSER/config.$AUTOSERV (AutoSys configuration file)

■ /etc/services

In the AutoSys configuration file, the socket connection is defined by the

AutoRemPort variable, like this:

# Port number of auto_remote

AutoRemPort=5280

In the /etc/services file, the auto_remote entry defines the socket

connection, like this:
auto_remote5280/tcp # AutoSys Version 3.4
The internet services daemon (inetd) on the client machine uses the port
number defined in the AutoSys configuration file to point to the name of
the auto_remote service found in the /etc/services file. The service
name is then located in the internet daemon configuration file (usually /
etc/inetd.conf), where it finds the path to the Remote Agent binary, like
this:
auto_remote stream tcp nowait root \ /usr/vendor/autotree/
auto_remote auto_remote

AutoSys User Guide for UNIX 13-33 ■

■ Configuring AutoSys
Modifying Remote Agent Settings

13 Running Two AutoSys Versions of Remote Agents

If you want to install two different versions of the AutoSys Remote Agent
on the same hardware, it is possible to set up multiple services by using
different port numbers and service names. Each version would point to
its own configuration file.

For example, assume you have one 3.3 Remote Agent using port number
3500. The entry in its AutoSys configuration file (e.g., config.PRD) would
look like this:
AutoRemPort=3500

On the same machine, you could have a 3.4 Remote Agent using port
number 4500. The entry in its AutoSys configuration file (e.g.,
config.DEV) would look like this:

AutoRemPort=4500
If you do this, you must also modify the /etc/services file like this:
auto_remote_333500/tcp # AutoSys Version 3.3
auto_remote_344500/tcp # AutoSys Version 3.4

Then, you would modify the internet daemon configuration file (/etc/
inetd.conf) like this:

auto_remote_33 stream tcp nowait root /usr/vendor/autotree_33/

auto_remote auto_remote
auto_remote_34 stream tcp nowait root /usr/vendor/autotree_34/
auto_remote auto_remote

■ 13-34 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Configuring Remote Authentication

13 Configuring Remote Authentication

You can configure AutoSys to run using the following two methods of
remote authentication:

Unix ruserok() Authentication

When using this method, AutoSys instructs a client’s Remote Agent to

make the UNIX system ruserok() call. This function checks the client
machine’s /etc/hosts.equiv and the user’s .rhosts files to validate
that the requesting user is registered in that environment.

AutoSys Remote Agent Event Processor Authentication

When using this method, a specific Remote Agent can be bound to

one or more Event Processors. In other words, a Remote Agent will
have to verify its permission to process an Event Processor’s requests
before starting each job. The Remote Agent does this by reading the /
etc/.autostuff file on the machine where it is running.

Using the autosys_secure command, the AutoSys Edit Superuser can

enable (or disable) remote authentication. By default, remote
authentication is initially disabled. If you enable Remote Agent Event
Processor Authentication, you must configure AutoSys to support it.

13 Configuring Event Processor Authentication

You can configure Remote Agents to only accept jobs from “trusted”
Event Processors. To configure AutoSys for Remote Agent Event Processor
Authentication, you must do the following:

■ Enable Remote Agent Event Processor Authentication.

■ Create an ASCII file named.autostuff in the /etc directory of every

client machine that will participate in this authentication method.

If both are present, the Remote Agent will only run jobs submitted by
Event Processors listed in the autostuff file.

AutoSys User Guide for UNIX 13-35 ■

■ Configuring AutoSys
Configuring Remote Authentication

The /etc/.autostuff File

The /etc/.autostuff file should have read and write permissions for root
only. Entries in this file must be in the following form:
AUTOSERV:hostname

where:

AUTOSERV Is an AutoSys instance name.

hostname This is the name of the machine on which the Event

Processor is running. This must be a real machine (if
using DNS, this should be a fully qualified name).

The file
should contain an entry for each Event Processor you want
authorized to run jobs on the Remote Agent machine. The entries cannot
contain spaces within the Event Processor specification. You can use
pound signs (#) for comments.

These are example file entries:

PRD:curly #Production Instance
DEV:moe #Development Instance

In this example, PRD is an AutoSys instance name and the Event Processor
for this instance is running on the machine curly. DEV is an AutoSys
instance name and the Event Processor for this instance is running on the
machine moe. These Event Processors are authorized to issue jobs to the
Remote Agent.

■ 13-36 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Client-Side Security

13 Client-Side Security
The AUTOENV environment variable DENY_ACCESS restricts access to the
Remote Agent machine.

In the auto.profile file for the Remote Agent machine, you can specify
a list of users whose jobs are prohibited from running on that machine.
The list is a comma delimited list of user names, with no spaces. The
maximum number of characters is 512. For example:
########################################################
# auto_remote environment variables
# DO NOT REMOVE

#AUTOENV#DENY_ACCESS=root,daemon,admin

In this example, jobs owned by root, daemon, and admin will not be
launched by the Remote Agent.

If a job owned by one of these users is submitted to run on the Remote

Agent, the job fails as if the job's owner did not have a valid account on
the machine. There will be no job restart attempts, regardless of
MaxRestartTrys setting in the AutoSys configuration file. When this
occurs, the following error appears in the Event Processor log, as a
STARTJOBFAIL alarm on the job:
Permission ERROR: Could not SET uid=<uid> on Host: <host>

AutoSys User Guide for UNIX 13-37 ■

■ Configuring AutoSys
Configuring ServerVision Monitoring and Reporting

Configuring ServerVision Monitoring and

13

Reporting
You can use the ServerVision GUIs to monitor the realtime resource
usage of an AutoSys job. This integration allows you to view AutoSys jobs
by their job name in the ServerVision GUIs. In addition, AutoSys can
archive a job’s resource usage to generate reports useful for capacity
planning and UNIX process auditing. This section describes the
configuration tasks necessary to enable this integration.

13 Library Path
A ServerVision library is shipped with this AutoSys release. It is installed
in $AUTOSYS/install/data. You must set your library path as appropriate
for your operating system to point to this library.

13 svload Requirements
To use the svload load balancing executable, the following is required:

1 The ServerVision uvcfgref environment variable must be set in the

environment for the AutoSys Event Processor. This must be set to the
directory that contains the ServerVision instances file.

2 The ServerVision instances file must contain entries for all machines
that you will use with the svload executable. For example, to use a
machine named “mack”, the instances file must contain the
following entry:
[mack]
type=unix
node=mack
3 The ServerVision uvroot environment variable must be set as required
by ServerVision.

4 The ServerVision xuv_net_svc binary must be in your path.

■ 13-38 AutoSys User Guide for UNIX

 Configuring AutoSys ■
Configuring ServerVision Monitoring and Reporting

13 ServerVision Environment Variables

To integrate AutoSys with the monitoring and reporting capabilities of
ServerVision, you must set the AUTOSV and AUTOSV_DIR environment
variables in the /etc/auto.profile file on every client machine for which
you want to enable this functionality.

The entry in the /etc/auto.profile file must be preceded by the

#AUTOENV# delimiters, as shown in the following example:

#AUTOENV#AUTOSV=YesWithArchive
#AUTOENV#AUTOSV_DIR=/tmp

AUTOSV can be set to the following:

YES

Writes AutoSys job information to a file for ServerVision. This enables

a user to view AutoSys jobs from the ServerVision GUI.
YesWithArchive

Writes AutoSys job information to a file for ServerVision and expects

a file in return to place in the archive database table (called
svarchive_tbl). This creates an archive of a job’s resource usage to
generate reports for capacity planning and UNIX process auditing
(charge back).

AUTOSV_DIR must be set to tell AutoSys where to write the files for
ServerVision. This must be a full path name and it must be the same path
that you specify in your ServerVision instance configuration file.

AutoSys User Guide for UNIX 13-39 ■

■ Configuring AutoSys
Configuring ServerVision Monitoring and Reporting

13 ServerVision Configurations
To view AutoSys jobs in the ServerVision GUIs
1 The ServerVision product must already be installed as instructed in the
ServerVision documentation.

2 View the ServerVision configuration file, typically $uvunix/

instance/uv_unix.cfg (where instance is the ServerVision
instance name). In this configuration file, locate the app_* scan types
(scan types are shown in square brackets) and look for the line that
begins with the string “command”, such as:
command exec $uvbin/unix/appd -d /tmp
The directory specified with the -d argument must match the directory
you specify with the AUTOSV_DIR variable in the AutoSys /etc/
auto.profile file.

3 Restart the ServerVision instance. From the XUV GUI, select

Control } Instance } Stop. Then select Control } Instance } Start.

4 Ensure the app_group scan types are on. From the XUV GUI, select
Control } Configure } Scan.

13 Monitoring Job Resource Usage

If you set AUTOSV to YesWithArchive, then AutoSys will write job
information to a file for ServerVision. ServerVision reads this
information and, in turn, generates a file with the following job resource
usage information:

■ CPU utilization

■ I/O reads

■ I/O writes

■ Average memory usage

■ 13-40 AutoSys User Guide for UNIX

 Configuring AutoSys ■
User-Defined Alarm Callbacks

One file is created for each job run. These files are stored in the directory
specified by the AutoRemoteDir parameter in the AutoSys configuration
file. You must run the svarchive utility to process these files and place
the information in the svarchive database table. After the process is
complete, the svarchive utility deletes the files.

Note • You may want to create an AutoSys job to run the svarchive
utility automatically on a regular schedule.

The information in the svarchive database table can be referenced to

generate reports for capacity planning and UNIX process auditing (charge
back).

13 User-Defined Alarm Callbacks

This AutoSys notification mechanism provides a method for
communicating problems to administrators in a manner that is external
to the AutoSys event system. That is, for certain types of AutoSys alarms,
you can configure AutoSys to call user-defined routines that
communicate the problem to specific members of your company. For
example, by using electronic mail or a command line pager utility, your
administrator can be notified as soon as certain AutoSys events occur.

You can configure AutoSys to call user-defined routines for the following
types of system alarms:

DB_ROLLOVER AutoSys has rolled over from Dual Server to Single

Server Mode.

DB_PROBLEM There is a problem with one of the AutoSys

databases.

EP_ROLLOVER The Shadow Event Processor is taking over

processing.

AutoSys User Guide for UNIX 13-41 ■

■ Configuring AutoSys
User-Defined Alarm Callbacks

EP_SHUTDOWN The Event Processor is shutting down. This might be

due to a normal shutdown, or due to an error
condition.

EP_HIGH_AVAIL The Third Machine for resolving contentions

between two Event Processors cannot be reached,
one of the Event Processor is shutting down, or there
are other Event Processor take-over problems.

To specify what executable should be invoked as a user-defined callback

for one of the above alarms, a file named notify.$AUTOSERV must be
created in the $AUTOUSER directory. An example of this file is provided in
the $AUTOSYS/install/data/notify.ACE file, which contains the
following entries:
# Notify for certain CRITICAL ALARMS
#
# Form is: ALARM executable
# We pass in $1 = numeric code
# $2 = Text Message
# Only have 1 space between the ALARM and the executable
#
# The environment is inherited from the Event Processor
# The following is executed: system( <executable>
# $1 $2 & );
#
#DB_ROLLOVER $AUTOUSER/notify_db
#DB_PROBLEM $AUTOUSER/notify_db
#EP_ROLLOVER $AUTOUSER/notify_ep
#EP_SHUTDOWN $AUTOUSER/notify_ep
#EP_HIGH_AVAIL $AUTOUSER/notify_ep

■ 13-42 AutoSys User Guide for UNIX

 Configuring AutoSys ■
User-Defined Alarm Callbacks

Notification Example

To have AutoSys call the program /usr/local/bin/pager when the Event

Processor shuts down
1 Copy the sample notification file to:

$AUTOUSER/notify.$AUTOSERV
2 Change the EP_SHUTDOWN line to this:

EP_SHUTDOWN /usr/local/bin/pager $@
Then, AutoSys will pass pager a numeric code and a text message. The
pager itself must be coded to accept these parameters.

AutoSys User Guide for UNIX 13-43 ■

 14
Troubleshooting
Problems with AutoSys usually involve the interactions between the
major AutoSys components, rather than with the individual components
themselves. This chapter presents a number of common AutoSys
problems, their symptoms, and how to resolve them. It provides very
useful information about troubleshooting the primary AutoSys
components.
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3

Event Server Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3

Event Server is Down (Sybase) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Sybase Deadlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Not Enough User Connections (Bundled Sybase) . . . . . . . . . . . . . . . . . . . . . . 14-7
archive_events Fails (Bundled Sybase) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-9
Event Server Will Not Start (Bundled Sybase) . . . . . . . . . . . . . . . . . . . . . . . . . 14-11

Event Processor Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-11

Event Processor is Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12
Event Processor Will Not Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12

AutoSys User Guide for UNIX 14-1 ■

■ Troubleshooting

Remote Agent Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-13

Remote Agent Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-13
Remote Agent Will Not Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-14
Remote Agent Will Start - Command Will Not Run . . . . . . . . . . . . . . . . . . . .14-17
Remote Agent Starts, Command Runs—No RUNNING Event is Sent . . . . . .14-20
xql Will Not Start (Sybase Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-23
Remote Agent Not Found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-24
Jobs Run Twice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-25

Job Failure Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-26

Jobs Run Only From the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-26

■ 14-2 AutoSys User Guide for UNIX

 Troubleshooting ■
Introduction

14 Introduction
To troubleshoot AutoSys more effectively, it is essential that you
understand the stages in the life of a job, the order in which they occur,
and the roles played by the three major AutoSys components (i.e., Event
Server, Event Processor, and Remote Agent).

When a job is defined, its starting conditions are saved to the Event Server
(database), and the following occurs:

■ When its starting conditions are met, the Event Processor initiates a
Remote Agent on the client machine to execute the job.

■ The Remote Agent runs the job and sends the exit status of the job
back to the Event Server.

■ After the job completes, it is not run again until its starting conditions
are met.

This is the basic cycle for all jobs.

For more information about job processing, see the Basic AutoSys
Functionality section in Chapter 1, Introduction to AutoSys. For information
about troubleshooting CCI, see Appendix B, Troubleshooting CCI in this
guide.

14 Event Server Troubleshooting

14 Event Server is Down (Sybase)

Symptoms
1 When trying to start xql, you get a message like this:

DB-Library error: dbproc NULL

Error in SybInit: dbopen failed

AutoSys User Guide for UNIX 14-3 ■

■ Troubleshooting
Event Server Troubleshooting

2 When running programs like autorep or autosc, you get a messages

like this:
Client ERROR:
Or
Unable to connect: SQL Server is unavailable or does not exist.
3 When you run chk_auto_up, you receive a message similar to this:

Couldn’t connect with Server: AUTOSYSDB:autosys

4 You are unable to insert keys with gatekeeper.

Resolution
This indicates that either the dataserver is down, or the process in
question is unable to access it. To confirm that the dataserver is down, log
onto the server machine and run the chk_auto_up utility. You can also
look at the process table (using the UNIX ps command) for the process
name “dataserver”.

If the database is indeed down, you must restart it. For directions on how
to do this, see Starting Sybase in Chapter 12, Maintaining AutoSys.

If the database is running, the problem could be that you are pointing to
the wrong dataserver. The DSQUERY environment variable points to the
name of the dataserver (typically AUTOSYSDB). If it is not set properly and
you are not specifying a dataserver name to xql (using the -S server
option), then xql will fail.

The AutoSys environment variables point to the configuration file

$AUTOUSER/config.$AUTOSERV. This file contains the name of the Event
Server. Check to make sure that the environment variables and the
configuration file point to the proper location and Event Server.

Enter the following command for the instance ID:

echo $AUTOSERV

■ 14-4 AutoSys User Guide for UNIX

 Troubleshooting ■
Event Server Troubleshooting

The results should look similar to this:

ACE
Enter the following command for the Event Server and database name:
get_server $AUTOSERV
The results should look similar to this:
E AUTOSYSDB autosys

Where:
E
Means that this is an Event Server.
AUTOSYSDB

Is the name of the Event Server.

autosys

Is the name of the database (for Sybase and Microsoft SQL Server).

If the database service is up, and the environment variable is set properly,
then the Sybase interfaces file might not have the proper form, or be in
the proper location. This typically occurs on servers if the environment
has been changed, or, on clients, if the interfaces file has not been
correctly installed.

For more information about the Sybase interfaces file and connecting
to databases, see Chapter 1, Introduction to AutoSys, in the AutoSys
Installation and Getting Started Guide for UNIX.

AutoSys User Guide for UNIX 14-5 ■

■ Troubleshooting
Event Server Troubleshooting

14 Sybase Deadlock

Symptom
A message similar to the following appears in the Event Processor log
when viewed with the autosyslog -e command or in the Sybase error log
($SYBASE/install/errorlog_EventServer):
Your server command (process id #11) was deadlocked with another
process and has been chosen as deadlock victim. Re-run your
command.

Resolution
A deadlock is a Sybase condition that occurs when two users have a lock
on separate objects, and they each want to acquire an additional lock on
the other user’s object. The first user is waiting for the second user to let
go of the lock, but the second user will not let go until the lock on the
first user’s object is freed.

The dataserver detects the situation and chooses the user whose process
has accumulated the least amount of CPU time as the “victim.” The
dataserver rolls back the victim’s transaction, notifies the application
with the above error message, and allows the other user’s processes to
move forward.

sendevent will try to rerun the command until it is successful or until it

reaches the maximum number of tries specified by the -M option.

■ 14-6 AutoSys User Guide for UNIX

 Troubleshooting ■
Event Server Troubleshooting

14 Not Enough User Connections (Bundled Sybase)

Symptoms
Users cannot make connections to the database; they cannot start the
GUI or send events. When you check the Sybase error log ($SYBASE/
install/errorlog_EventServer) you see one or both of the following
errors:
Not enough User Connections (Sybase error 1601)
No Pss structures available for new process

Resolution
These messages occur because there are more users who want to run jobs
simultaneously than there are user connections; there are not enough
connections available to the database. By default, the bundled Sybase
installation of AutoSys has a limit of 25 user connections. You can
increase the number of user connections, but first you must determine
the maximum number of user connections your system can support.

To determine the maximum number of user connections you can set

for your system
1 Log into the database as the “sa.”

2 At the isql or xql prompt, enter:

1> select @@max_connections;

Results similar to the following are displayed:
-------------
253
return status 0, rows affected 1

AutoSys User Guide for UNIX 14-7 ■

■ Troubleshooting
Event Server Troubleshooting

3 Enter:

1> select count(*) from master..sysdevices where cntrltype = 0;

Results similar to the following are displayed:
--------------
3
return status 0, rows affected 1
4 Enter:

1> select count(*) from master..sysdevices where mirrorname is not

NULL;
Results similar to the following are displayed:
--------------
0
return status 0, rows affected 1
5 Enter:

1> select count(*) from master..sysservers where srvname !=

@@servername;
Results similar to the following are displayed:
--------------
1
return status 0, rows affected 1
The maximum number of user connections that you can set is
@@max_connections minus the sum of the results of the last three queries.
In the example results to the above queries, the maximum number of
user connections is 249.

■ 14-8 AutoSys User Guide for UNIX

 Troubleshooting ■
Event Server Troubleshooting

To increase the number of user connections:

1 At the isql or xql prompt, enter the following command to specify
the number of user connections you want:
1> sp_configure “user connections”, number;
Where number is the number of user connections you want.
WARNING • If you set the number of user connections too high, the
database will be unusable. At this point, you might not be able to rerun
sp_configure to lower the number of user connections. To return the
database to working order, you must run buildmaster or recover the
database from backups.

2 Stop and restart the Event Server. Changes will not take effect until
you stop and restart the Event Server.

14 archive_events Fails (Bundled Sybase)

Symptom
When the transaction log is full, archive_events fails. This usually occurs
because archive_events is not run regularly. We highly recommend that
you run archive_events frequently, ideally as part of the daily database
maintenance cycle by using DBMaint or as a regularly scheduled job.

You can usually avoid a full transaction log by having Sybase truncate the
transaction log during regular checkpoints.

To have Sybase truncate the transaction log

1 Log into the database server as the “sa” by entering the following
command (if you changed the “sa” password, use that one instead of
sysadmin):

xql -Usa -Psysadmin

2 To check if the truncate option is set, enter the following commands:

1> sp_helpdb;

AutoSys User Guide for UNIX 14-9 ■

■ Troubleshooting
Event Server Troubleshooting

3 If trunc.log on chkpt is not set, enter one of the following commands

depending on your version of Sybase:
1> sp_dboption autosys, “trunc log on chkpt”, true;
Or
1> sp_dboption autosys, “trunc. log on chkpt.”, true;
4 Enter the following commands:

1> checkpoint;
1> exit

Resolution

To resolve the full transaction log problem

1 Log into the database server as the “sa” by entering the following
command (if you changed the “sa” password, use that one instead of
sysadmin):

xql -Usa -Psysadmin

2 Use the autosys database by entering the following command:

1> use autosys;

3 Dump the transaction log by entering the following command:

1> dump transaction autosys with no_log;

4 If this fails, enter the following commands:

1> set rowcount 1;

1> dump transaction autosys with no_log;
Repeat step 4 and each time increase the rowcount incrementally. To
begin with try doubling the number. If this fails at any time, decrease
the rowcount and try again. When the rowcount is large, log out of the
dataserver.

■ 14-10 AutoSys User Guide for UNIX

 Troubleshooting ■
Event Processor Troubleshooting

5 Log out of the dataserver, and then run archive_events. Begin with a
large number of days and work down until you reach your target
number of days. For example:
archive_events -n 30
archive_events -n 10

14 Event Server Will Not Start (Bundled Sybase)

Symptom
When starting a bundled Sybase Event Server, you get a message similar
to the following:
00: 94/08/18 10:38:37:66 kernel: kcinit:
couldn’t open error log
‘/users/sybase/stdb/install/errorlog_AUTOSYSDB’
(os error 13)

Resolution
You are not the same user who last started Sybase, and do not have
permission to write to the Sybase error log file. Become that user, change
the error log file ($SYBASE/install/errorlog_$DSQUERY) permissions, or
delete the old error log file.

14 Event Processor Troubleshooting

Output from the Event Processor is redirected into the following log file:
$AUTOUSER/out/event_demon.$AUTOSERV

Everything that the Event Processor does, in the order it was done, is in
this file. Network problems are usually reflected in this file as well. This
file is very useful for reconstructing what happened when a problem
occurs.

AutoSys User Guide for UNIX 14-11 ■

■ Troubleshooting
Event Processor Troubleshooting

14 Event Processor is Down

Symptoms
1 Jobs do not start.

2 When chk_auto_up is run, it returns a message similar to this:

Could connect with Server: AUTOSYSDB:autosys

No Event Processor is RUNNING on machine: machine
3 The Event Processor log has not registered a date and time stamp for
a period of time. The Event Processor log should register date and time
stamps every minute.

Resolution
Confirm that the Event Processor is down by performing one of the
following actions:

■ Run the chk_auto_up utility.

■ Perform a tail on the log file and check for date stamps.

■ Look for the event_demon process using ps.

If the Event Processor is indeed down, log on as the Exec Superuser and
run the eventor command to restart it.

14 Event Processor Will Not Start

Symptom
When running the eventor command, you see an error message similar
to the following:
/usr/autotree/autosys/bin/eventor:/usr/autotree/autouser/out/
event_demon.ACE:Cannot create

■ 14-12 AutoSys User Guide for UNIX

 Troubleshooting ■
Remote Agent Troubleshooting

Resolution
You are not the same user who last started the Event Processor. Ether
become that user, or change permissions on the Event Processor output
file, the $AUTOUSER/out/event_demon.$AUTOSERV file.

14 Remote Agent Troubleshooting

14 Remote Agent Verification
If you suspect problems with the Remote Agent, you can use autoping to
verify your suspicions.

autoping
autoping is used to test the connections between the Event Processor and
the Remote Agent. If you use the autoping -M -D client_hostname
command, and it does not return an error, the Remote Agent should start
properly.

The Remote Agent writes RUNNING and completion statuses directly to

the Event Server.

Database Verification
Use autoping to verify the Remote Agent database connection. To check
the database connections on machine, enter this:
autoping -m machine -D
Instead of a single machine, you can type -m ALL to check all machines.

AutoSys User Guide for UNIX 14-13 ■

■ Troubleshooting
Remote Agent Troubleshooting

This command captures the output from the attempted database

connection, displays it, and includes it in the alarm, if one is generated
(use the -A argument to generate an alarm if problems are found).
autoping -m venice -D
AutoPinging Machine [venice] AND checking the
Remote Agent's DB Access.
AutoPing WAS SUCCESSFUL!

14 Remote Agent Will Not Start

The symptoms in this section are similar and result from network
problems.

Symptom
The Event Processor’s $AUTOUSER/out/event_demon.$AUTOSERV log file
contains a message similar to this:
Attempting to connect to AutoSys Remote Agent
Service on socket=5280: Connection Refused
Attempting to connect to ‘inetd’ on
socket=5280: Interrupted system call
The connection to machine: spartacus TIMED OUT.
Either that machine, or the network to it, is
having problems.
ERROR trying to start job: test
Error: Connect to socket FAILED.
Command: sleep 1
Machine: spartacus

Resolution
Either there is a network communication problem, or the client machine
is down. The network or machine problems must be resolved before jobs
can be run on that machine.

■ 14-14 AutoSys User Guide for UNIX

 Troubleshooting ■
Remote Agent Troubleshooting

Symptom
The Event Processor’s $AUTOUSER/out/event_demon.$AUTOSERV log file
contains a message similar to this:
Attempting to connect to AutoSys Remote Agent
Service on socket=5280: Connection Refused
Attempting to connect to ‘inetd’ on
socket=5280: Interrupted system call
Could NOT connect to machine: spartacus The
internet daemon may not be configured properly.
ERROR trying to start job: test
Error: Connect to socket FAILED.
Command: sleep 1
Machine: spartacus

Resolution
There is a problem with the /etc/services file. To locate this problem,
check the following:

1 Check the /etc/services file to see if the following entry is there:

auto_remote 5280/tcp
2 Confirm that the Remote Agent port number, specified with
AutoRemPort in the AutoSys configuration file ($AUTOUSER/
config.$AUTOSERV), is the same number as used in the /etc/services
file.

3 If you are using NIS/NIS+, remake the services and push it out.

This refers to modifying the NIS/NIS+ master machine and

propagating the information to all NIS/NIS+ clients. You should
contact your NIS system administrator for instructions on how to do
this.

AutoSys User Guide for UNIX 14-15 ■

■ Troubleshooting
Remote Agent Troubleshooting

Symptom
In the Event Processor’s $AUTOUSER/out/event_demon.$AUTOSERV log file,
you see a message similar to the following:
[spartacus connected]
*** Remote Agent Process not started. ***
socket read <>, rc=0
ERROR trying to start job: test
Error: Auto Remote process did not start.
Command: sleep 1
Machine: spartacus

Resolution
Check that the internet daemon is properly configured on the client
(Remote Agent) machine. There should be an entry in inetd.conf for
auto_remote. If present, this line points to the Remote Agent’s executable.
Assuming that auto_remote is in the /usr/local/bin directory, and will
be run by the user “root,” the entry should look like this (on one line):
auto_remote stream tcp nowait root/usr/local/bin/auto_remote auto_remote

Note • The auto_remote command must be run as “root,” because it

does a setuid.

For more information about configuring the internet daemon on the

client machine, see the AutoSys Installation and Getting Started Guide for
UNIX.

If the auto_remote entry exists in the inetd.conf file, follow these steps:

1 Make sure that the auto_remote binary (the Remote Agent executable)
exists in the specified directory and has “execute” permission.

■ 14-16 AutoSys User Guide for UNIX

 Troubleshooting ■
Remote Agent Troubleshooting

2 If the inetd.conf file needs to be modified, a SIGHUP (kill -1)

needs to be sent to the inetd process to cause the configuration to be
re-read. To do this, sign on as “root” and execute one of these
commands:
$AUTOSYS/install/touch_inetd
Or
kill -1 pid
where:
pid

Is the process ID of the internet daemon (inetd).

This command forces the internet daemon to re-read its configuration

file, and to reset itself.

Note • On most AIX machines, the kill -1 command fails to reset

the inetd. Instead, you must kill the inetd process using kill -9, and
then restart the inetd manually.

3 Make sure the Remote Agent can write to the AutoRemoteDir directory
(usually /tmp), and that this directory has available space.

14 Remote Agent Will Start - Command Will Not Run

Each time the Remote Agent is started on a machine, it creates the
following log file:
AutoRemoteDir/auto_rem.pid

where:
AutoRemoteDir

Is the Remote Agent log directory specified in the configuration file

(usually specified as the /tmp directory).

AutoSys User Guide for UNIX 14-17 ■

■ Troubleshooting
Remote Agent Troubleshooting

auto_rem.pid

Is the process ID of the Remote Agent.

When the Remote Agent receives its instructions from the Event
Processor, it renames this file in order to give it a unique name. This is
the form of the new filename:
AutoRemoteDir/auto_rem.joid.run_num.ntry

where:
joid

Is the job object ID (the job’s number in the database).

run_num

Is the run job run number.

ntry

Is the number of tries or restarts.

This file contains all the instructions passed to the Remote Agent by the
Event Processor, the results of any resource checks, and a record of all
actions it took. Any problems experienced by the Remote Agent are
reported here, including the inability to send events to the database(s),
which is the most common problem.

To find the most recent instance of the Remote Agent Log for a given job,
you issue the following command on the machine where the job last ran:
autosyslog -J job_name

Note • If the configuration file specifies that the Remote Agent log
files are to be cleaned up at the completion of a job, and the job
completed normally, the file will have been removed. If the job failed
for some reason, the file will not be deleted, regardless of the
configuration file setting. To turn off automatic deletion of the
Remote Agent log files, set the CleanTmpFiles parameter in the
configuration file to 0.

■ 14-18 AutoSys User Guide for UNIX

 Troubleshooting ■
Remote Agent Troubleshooting

For more information about the AutoSys configuration file and the
CleanTmpFiles parameter, see the Configuration File Parameters section of
Chapter 13, Configuring AutoSys.

Symptoms
1 The job is stuck in either the STARTING or RUNNING state as seen in
either the Event Processor log or the output resulting from issuing the
following command:
autorep -J job_name
2 The job has immediately returned as a FAILURE.

Resolution
If you have gotten to this point, the AutoRemoteDir/auto_rem* file should
be present. By looking in this file, you will see how far AutoSys was able
to get. You should check and verify the following items:

1 The correct file is being sourced before running the job command. The
default file is /etc/auto.profile. A job-specific file may be sourced
instead of the default profile.

For more information, see the description of the profile attribute in

Chapter 4, Job Attributes.

2 The $PATH variable is setup properly, and includes the proper location
for all required executables. Variables, such as $PATH, must be exported
for the job to see them.

3 The file system that the job command is on is accessible from this
machine.

4 The permissions are correct on the job command to be executed.

5 The permissions are correct on any standard input/output files

specified for re-direction.

6 The profile is a Bourne shell script. Korn shell and C shell scripts will not
work.

AutoSys User Guide for UNIX 14-19 ■

■ Troubleshooting
Remote Agent Troubleshooting

Note • A valuable debugging technique is to specify a file to be used

for standard output and standard error for the job that will not run. If
there are any shell level command problems, all error messages will
be in that file.

Remote Agent Starts, Command Runs—No RUNNING Event is

14

Sent

Symptoms
1 Job is stuck in STARTING state.

2 This problem is detected either in the Event Processor window (or log)
or in the results of running the autorep command on the job, when
the following event appears, then nothing else, yet the job does run to
completion on the client machine:
CHANGE_STATUS Status: STARTING Job: test_install

Resolution
This is a common problem and is nearly always the result of the Remote
Agent being unable to contact the Event Server. First of all, ensure that
network problems are not preventing communication between the
Remote Agent and the Event Server machines. If this is not the problem,
then check the following database-specific solutions.

With Sybase, this problem usually occurs because the interfaces file is not
set up properly on the machine running the Remote Agent. With Oracle,
this problem usually occurs because the SQL*Net V2 connections are not
set up properly.

The Remote Agent must be able to connect to the Event Server in order to
send the RUNNING, SUCCESS, FAILURE, or TERMINATED status events.

■ 14-20 AutoSys User Guide for UNIX

 Troubleshooting ■
Remote Agent Troubleshooting

To verify the problem, look in the AutoRemoteDir/auto_rem* file for this

job. You can accomplish this by issuing the following command on the
machine where the job is supposed to have run:
autosyslog -J job_name

where job_name is the name of the job in question.

If the Remote Agent cannot send the event back to the database, it will
write a message to that effect, plus some diagnostics, into this file. (The
output from the autosyslog command could provide a helpful DBMS
error number from the connect attempt.)

If you are using Sybase, check the following:

1 Check that the Sybase interfaces file exists and is readable by all
users. The location of the interfaces file is pointed to by an entry in
the
/etc/auto.profile, which looks like this:

#AUTOENV#SYBASE=/usr/home/sybase
2 Check that the Sybase interfaces file has an entry for the dataserver
that contains the AutoSys Event Server.

The format of the Sybase interfaces file requires that:

• Each dataserver name begins at the left margin with no preceding

spaces or tabs.

• Each entry line has a single preceding tab.

Each element in an entry line is separated by a single space.

Incorrect formatting will cause the Remote Agent to be unable to

communicate with the database.

AutoSys User Guide for UNIX 14-21 ■

■ Troubleshooting
Remote Agent Troubleshooting

If you are using Oracle, check for the following:

1 Check that the Oracle TNS names file, tnsnames.ora, exists, is

readable, and contains the correct information for the Event Server. By
default, the TNS names file is in one of the following locations:

• On most systems, it is in /etc/tnsnames.ora

• On some System V systems (e.g., Solaris), it is in

/var/opt/oracle/tnsnames.ora, or in /var/opt/tnsnames.ora

If the tnsnames.ora file is not in one of these locations, you must

define it using the $TNS_ADMIN environment variable. Set the
$TNS_ADMIN variable for the Remote Agent with an entry in /etc/
auto.profile that looks like this:

#AUTOENV#TNS_ADMIN=/usr/home/oracle
/etc/auto.profile must be readable by all users.
2 Check that the Oracle TNS names file has a SQL*Net V2 formatted
entry for the Event Server.

Testing the Setup

To test that everything is set up properly, try to log onto the Event Server
from the client machine, using the xql utility (for Sybase), or using
sqlplus (for Oracle). When you log onto the Event Server, use the
“autosys” user and password.

When testing Sybase using xql, be sure that your user environment is
looking at the same interfaces file as the auto_remote (Remote Agent).
Set SYBASE to the same value that is in /etc/auto.profile.

Note that the auto_remote only attempts to read the interfaces file once.
After a bad interfaces file has been read, correcting it will not allow a
running auto_remote to connect. After you correct the interfaces file,
you will have to kill the auto_remote and restart the job.

■ 14-22 AutoSys User Guide for UNIX

 Troubleshooting ■
Remote Agent Troubleshooting

For Sybase, try to log onto the Event Server from the remote machine
using xql, like this:
xql -U autosys -P autosys -S AUTOSYSDB
When testing Oracle using sqlplus, be sure that your user environment
is looking at the same tnsnames.ora file as the auto_remote (Remote
Agent). Set TNS_ADMIN to the same value that is in /etc/auto.profile.

Note that the auto_remote only attempts to read the tnsnames.ora file
once. After a bad tnsnames.ora file has been read, correcting it will not
allow a running auto_remote to connect. After you correct the
tnsnames.ora file, you will have to kill the auto_remote and restart the
job.

For Oracle, try to log onto the Event Server from the remote machine
using sqlplus with a V2 connect descriptor, like this:
sqlplus autosys/autosys@AUTOSYSDB

14 xql Will Not Start (Sybase Only)

Symptom
From the remote machine, xql returns the following message:
DB-Library error: dbproc NULL
Error in SybInit: dbopen failed

Resolution
Check the following:

1 Determine if the dataserver is started and running, and start it if it is

not running.

AutoSys User Guide for UNIX 14-23 ■

■ Troubleshooting
Remote Agent Troubleshooting

2 Verify that the DSQUERY environment is set to the proper dataserver.

Or
Run xql with the -S and -D options to specify the correct dataserver
and database.

3 If a fully qualified xql statement still fails, then it is a problem with

the interfaces file. For more information about dealing with this file,
see the Resolution section of Remote Agent Starts, Command Runs—No
RUNNING Event is Sent on page 14-20.

14 Remote Agent Not Found

Symptom
When trying to start a job or trying to start the Event Processor with a
Shadow Event Processor, the following message appears in the Event
Processor log when viewed with the autosyslog -e command:
Unknown Host Machine

Resolution
You may receive this message in the following situations:

1 There is a network problem and a connection cannot be made to the

Remote Agent machine.

2 The Remote Agent machine is not in /etc/hosts or DNS.

3 The AutoSys configuration file lists the machine; however, there is a

space after the machine name.

Check /etc/hosts or DNS for the machine name, and add it if necessary.

Check the AutoSys configuration file, $AUTOUSER/config.$AUTOSERV

($AUTOSERV is the name of the AutoSys instance). A space after the
machine name is hard to see. Use an editor, such as vi (with the :set
list option), to edit the configuration file and remove anything after the
name of the machine and before the $ that marks the end of the line.

■ 14-24 AutoSys User Guide for UNIX

 Troubleshooting ■
Remote Agent Troubleshooting

14 Jobs Run Twice

If you receive failed to connect to socket errors during a job run, the
job runs more than once. This is the expected behavior of AutoSys when
this error occurs as explained by this scenario:

1 The server opens a connection to the client to run the job.

2 The Remote Agent on the client starts the job, and then tries to
respond to the server.

3 The server issues a failed to connect to socket error because the

Remote Agent took longer than 30 seconds (the timeout value) to
start the job and respond.

4 The server checks if the job can be restarted, and then restarts the job.
Meanwhile, the job is running and perhaps has completed on the
client.

5 The server opens another connection to the client to run the job a
second time.

6 The Remote Agent starts the job and responds to the server in time.

7 The job runs a second time.

Severe performance problems on the client are the main reason this
occurs. For example, the following might affect performance:

■ Running a full system backup on the client at the same time jobs are
starting might slow down the system so that it cannot respond to the
server.

■ Network problems. If a job’s home directory is on an NFS drive and

there are bandwidth problems, the job might take so long to start that
the socket times out.

AutoSys User Guide for UNIX 14-25 ■

■ Troubleshooting
Job Failure Troubleshooting

Because socket time-out is not a customizable parameter, there is little

you can do to avoid this situation from an AutoSys perspective. However,
you can analyze the performance of the client by asking these questions:

■ Are there too many processes running on the client when you run
jobs?

■ Are you having network problems?

■ Are you using NFS-mounted directories?

■ Do you need more memory or processors on the client?

14 Job Failure Troubleshooting

14 Jobs Run Only From the Command Line

Symptom
Jobs run from the command line, but they fail when run by AutoSys.

Resolution
This problem is nearly always the shell environment where the job runs.
The following are the possible reasons for the problem:

1 The profile in the job definition is not a Bourne shell (sh) type profile.
If this is the case, the profile fails.

2 The default AutoSys profile does not produce the proper environment
for the job to run. The default profile for all AutoSys jobs is /etc/
auto.profile, not the job owner’s logon profile $HOME/.profile. If
the job owner’s profile is not specified in the job definition, it is never
sourced.

To check the difference between the job definition and the user
environment, do the following:

■ 14-26 AutoSys User Guide for UNIX

 Troubleshooting ■
Job Failure Troubleshooting

3 Write the current owner’s environment to a file. Log in as the owner

of the job on the machine where the job will run and enter the
following command:
env >user.env
4 Write the Remote Agent environment to a file by entering the
following JIL command:
insert_job: auto_env
machine: client_hostname
owner: owner
command: env
std_out_file: /tmp/auto.env
std_err_file: /tmp/auto.err
where:

client_hostname

is the hostname of the machine where the problem job runs.

owner

is the owner of the job that will not run.

5 Run the troubleshooting job by entering the following AutoSys

command:
sendevent -E STARTJOB -J auto_env
6 Check the two files for differences by entering the following
command:
diff /tmp/auto.env user.env
This shows you where the AutoSys environment and the user
environment differ. Make the necessary changes in the job definition
and the user profile.

Also, it is useful to define the std_err_file for the job that fails,
because you can check the errors from the shell for a clue about what
is missing.

AutoSys User Guide for UNIX 14-27 ■

 A
Integrating with the
Mainframe and AutoSys
Agents for AS/400 and
OpenVMS
This appendix describes how to integrate AutoSys with the mainframe,
AutoSys Agents for AS/400 and OpenVMS, and Unicenter TNG Workload
Agents for an advanced AutoSys configuration.
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Definition of Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4

Job Scheduling for the Enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5

Configuring for Enterprise Job Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6

Stop the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Configure the AutoSys Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
License Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9

AutoSys User Guide for UNIX A-1 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS

Restart the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-10

About asbrokerII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-10

Environment Variables for asbrokerII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-11

AutoSys and AutoSys Connect Cross-Platform Dependencies . . . . . . . . . . . .A-13

Job Scheduler Interdependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-14
Notation for Cross-Platform Job Dependencies . . . . . . . . . . . . . . . . . . . . . . . .A-15
Naming Conventions for AutoSys Connect Cross-Platform Jobs . . . . . . . . . .A-16

Running AutoSys Jobs on Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-17

Agent Job Names and User IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-18
Running Jobs on Agent Managed Machines . . . . . . . . . . . . . . . . . . . . . . . . . .A-18
Defining Agent Machines to AutoSys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-19
AutoSys Agent Machine in an AutoSys Job Definition . . . . . . . . . . . . . . . . . .A-20

Log and Trace Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-22

AutoSys Connect and AutoSys Agent Job Statuses . . . . . . . . . . . . . . . . . . . . . . .A-22

Unsupported Attributes for AutoSys Connect or AutoSys Agent Jobs . . . .A-23

Cross-Platform Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-24

■ A-2 AutoSys User Guide for UNIX

 Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS ■
Introduction

A Introduction
AutoSys enterprise-wide scheduling lets you integrate AutoSys jobs with
AutoSys Agents for AS/400, OpenVMS, and with various scheduling
products on the mainframe. The following types of integration are
supported:

■ AutoSys jobs can be defined to conditionally start based on the status

of jobs running on OS/390, AS/400, OpenVMS, and any Unicenter
TNG Workload Agent node.

■ AutoSys can schedule jobs on any of those machines as well.

Using cross-platform job dependency notation, AutoSys jobs can be

defined to conditionally start based on the status of a job running on the
included set of agent machines. You can also create AutoSys jobs that will
run on any of the agent machines (if the agent machine is defined to
AutoSys). The term “agent machine” is defined in the next paragraph.

1 Definition of Terms
The following terms are used in this appendix::

AutoSys A job scheduler that runs on UNIX and Windows NT.

AutoSys Connect Software that lets AutoSys communicate with legacy

OS/390 schedulers.

CCI Common Communication Interface.

AutoSys Agent Any remote agent in the set of agents supported by

AutoSys 3.5.1. These are AutoSys, AS/400, AutoSys
Connect, scheduling agents for VMS, and any
Unicenter TNG agent.

Agent Machine(s) Any machine which supports an agent.

AutoSys User Guide for UNIX A-3 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS
Introduction

Unicenter TNG A small set of programs that execute on each target

Workload Agent machine where jobs are processed. The agent
performs the following functions:
■ Receives job requests from one or more managers,
such as Unicenter TNG Workload Server and
AutoSys Server, and initiates the requested
program, script, JCL or other unit of work.
■ Collects status information about job execution
and file creations.
■ Sends status information to the requesting
workload manager.

Cross-instance A dependency between jobs running on different

job dependency instances of AutoSys.

Cross-platform A dependency between jobs running on different

job dependency platforms. For example, an AutoSys job running on a
UNIX or Windows NT machine can be dependent on
a job running on a mainframe.

1 Related Documentation
The information presented in this appendix supplements the following
documents:

■ AutoSys User Guide for UNIX

■ AutoSys Installation and Getting Started Guide for UNIX

■ AutoSys Connect Getting Started

Note • AutoSys can also drive your legacy mainframe scheduler by

way of the AutoSys Connect product. Refer to AutoSys Connect Getting
Started for instructions on how to install and use this product.

■ A-4 AutoSys User Guide for UNIX

 Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS ■
Job Scheduling for the Enterprise

1 Job Scheduling for the Enterprise

AutoSys 3.5.1 lets you schedule or reroute jobs from multiple sources
throughout the enterprise.

1 Prerequisites
Before you can implement enterprise job scheduling, you must install
and configure the basic AutoSys software as instructed in the AutoSys
Installation and Getting Started Guide for UNIX. You must also install and
configure AutoSys Connect or AutoSys Agents, or both, as instructed in
the documentation for these components.

The required software and version levels are listed in the following table:

AutoSys CCI AutoSys Agent

■ AutoSys version ■ Version ■ TCP/IP

3.5.1 for UNIX 16123032000
(minimum) One or more of the
following:
To determine your
■ AutoSys Connect
version of CCI,
enter the following (OS/390)
command: ■ AutoSys Agent for
$CAIGLBL0000/cci/ AS/400 or
bin/ccinet release OpenVMS
■ Unicenter TNG
Workload Agent
(for UNIX versions
such as AIX, HP,
OSF, SCO, DGI,
NCR, etc., and
Windows NT)

AutoSys User Guide for UNIX A-5 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS
Configuring for Enterprise Job Scheduling

The following elements must be present on the AutoSys machine:

asbrokerII An AutoSys process that communicates with

AutoSys Connect or any supported AutoSys Agent.

CCI The Common Communication Interface. See

Appendix A, Introducing CCI in the AutoSys
Installation and Getting Started Guide.

1 Configuring for Enterprise Job Scheduling

After installing and configuring the basic AutoSys software and AutoSys
Connect or AutoSys Agents, or both, you need to configure the AutoSys
machine.

1 Stop the Event Processor

Before you proceed with the configuration and initialization procedures
discussed in the following sections, shut down the Event Processor as
shown below (you must be the AutoSys Exec Superuser to do this):
sendevent -E STOP_DEMON

1 Configure the AutoSys Machine

Set the AutoSysAgentSupport Parameter

To run jobs directly on an AutoSys Agent, enable AutoSys Agent job
support by setting the following parameter in the AutoSys instance
configuration file ($AUTOUSER/config.$AUTOSERV):
AutoSysAgentSupport=1
When this parameter is set to 1, it indicates that an AutoSys instance can
dispatch jobs to an AutoSys Agent.

■ A-6 AutoSys User Guide for UNIX

 Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS ■
Configuring for Enterprise Job Scheduling

Create the config.EXTERNAL File

To enable cross-platform dependencies, create a file named
config.EXTERNAL in the $AUTOUSER directory. In config.EXTERNAL, add an
entry similar to the following for each agent for which cross-platform
dependencies will be exchanged:
INS:AGT=REMOTE_HOST

where:
INS

Is the three-letter uppercase identifier for the AutoSys Connect

instance; for example, CA7. This is the name by which the AutoSys
Connect application will be known to AutoSys.
AGT

Is one of the following:

• CNCT

Represents an AutoSys Connect machine.

• TNG

Represents a Unicenter TNG machine.

REMOTE_HOST

The name of the agent machine.

config.EXTER NAL Examples

The following are examples of the config.EXTERNAL file:
■ FLO:TNG=flower

where:

FLO is a three-character instance name, or INS.

TNG is the agent type, or AGT.

AutoSys User Guide for UNIX A-7 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS
Configuring for Enterprise Job Scheduling

flower is a REMOTE_HOST that is a Unicenter TNG Workload Agent

machine on AS/400, UNIX, VMS, or Windows NT, CA-7, CA-JobTrac,
or CA-Scheduler.
■ FRU:CNCT=fruit

where:

FRU is a three-character instance name, or INS.

CNCT is the agent type, or AGT.

fruit is a REMOTE_HOST that is an AutoSys Connect machine on OS/390.

Note • The config.EXTERNAL file can contain a maximum of 249

entries.

Ensure Consistent Integration Settings

When the Event Processor starts up, it checks the setting of the
AutoSysAgentSupport parameter in the AutoSys configuration file. If the
parameter setting is not set to 1, the Event Processor does not start nor
communicate with asbrokerII. It is important, therefore, to ensure the
settings are consistent. That is, to enable communication with any
AutoSys Agent, the following must be true:

■ AutoSysAgentSupport is set to 1 in the AutoSys configuration file.

■ AutoSys Connect instance(s) are defined in the config.EXTERNAL file

(if you want to communicate with AutoSys Connect).

If you want to disable external dependency communications only, you

must:

■ Comment out AutoSys Connect instances in the config.EXTERNAL file.

If you want to disable both AutoSys Agent and AutoSys Connect

communications, you must do the following:

■ Set AutoSysAgentSupport to 0 in the AutoSys configuration file.

■ A-8 AutoSys User Guide for UNIX

 Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS ■
Configuring for Enterprise Job Scheduling

■ Comment out any AutoSys Connect instances in the config.EXTERNAL

file.

Configure the Communication Components

See Appendix A, Introducing CCI in the AutoSys Installation and Getting
Started Guide for UNIX.

1 License Keys
AutoSys client license keys are required for agent machines in order for
AutoSys to run jobs on those machines.

The client license key is tied to a specific machine. It is generated by the

Computer Associates TLC (Total License Care) group based on the host
name and host id of the client machine.

For agent machines, the host name is the REMOTE_HOST and the host id is
always 0 (zero).

When you supply the above information to the TLC group, they will
provide you with a client key. You install the client key in the AutoSys
database using the gatekeeper command, as shown in the following
example:
gatekeeper <Return>
Utility to Add/Delete or Print KEYs.
Add (A) or Delete (D) or Print (P) ? a
KEY Type: [(c)lient, (s)erver, (t)ime, (x)pert]: c
Hostname: REMOTE_HOST
Hostid: 0
KEY: IIJJKKLLMMNNOOPP
***** New Key ADDED! *****
KEY Type: [(c)lient, (s)erver, (t)ime, (x)pert]:<Return>

AutoSys User Guide for UNIX A-9 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS
About asbrokerII

1 Restart the Event Processor

Now you can start the Event Processor using the eventor command. For
information about starting the Event Processor, see Starting the Event
Processor in Chapter 12, Maintaining AutoSys.

1 About asbrokerII
Communication between AutoSys and AutoSys Connect or an AutoSys
Agent is facilitated by asbrokerII. It is a necessary component for cross-
platform communication. Letting asbrokerII handle that exchange frees
the Event Processor to handle other events.

When the Event Processor is started, it checks if the AutoSysAgentSupport

parameter in the AutoSys configuration file is enabled. If it is, the Event
Processor starts asbrokerII automatically. If the Event Processor is
stopped, or goes down for any reason, asbrokerII will also stop running.
The only way to bring up asbrokerII is to restart the Event Processor.

If the Event Processor and asbrokerII go down while an AutoSys

Connect job finishes, the completion event will be lost. (This does not
happen to an AutoSys Agent job because missed events are resent during
a checkpoint restart at asbrokerII startup.) That information is sent only
once and is not saved. If this happens, the only way to change the status
of the job is to change it manually. (You must have execute permission
on a job in order to change its status.) To change the status of a job, use
the AutoSys sendevent command, as shown in the following example:
sendevent -E CHANGE_STATUS -J job_name -s status
You can also use the Send Event dialog to change the status of a job. This
dialog is accessed from the AutoSys Operator Console.

■ A-10 AutoSys User Guide for UNIX

 Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS ■
About asbrokerII

1 Environment Variables for asbrokerII

You can customize asbrokerII by setting environment variables in the
following:

■ autosys.ksh.hostname, if you use ksh (korn shell)

■ autosys.sh.hostname, if you use sh (bourne shell)

■ autosys.csh.hostname, if you use csh (c shell)

The environment variables are ASBROKERII_INSTANCE,

ASBROKERII_PING_INTERVAL, ASBROKERII_RECV_INTERVAL,
ASBROKERII_TRKARRAY_SIZE, and ASBROKERII_CKP_PATH.

ASBROKERII_INSTANCE
The ASBROKERII_INSTANCE environmental variable allows multiple
instances of asbrokerII program to run on the same machine, if deemed
necessary. Each instance is uniquely identified by a seven character token.

By default, the token is set to ATSBTRK:

ASBROKERII_INSTANCE=ATSBTRK

ASBROKERII_PING_INTERVAL
The ASBROKERII_PING_INTERVAL environmental variable sets the ping
interval of asbrokerII in seconds. asbrokerII pings the Unicenter TNG
Agent and AutoSys Connect machines periodically to check if they are
alive.

By default, the ping interval is set to 60 seconds:

ASBROKERII_PING_INTERVAL=60

AutoSys User Guide for UNIX A-11 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS
About asbrokerII

ASBROKERII_RECV_INTERVAL
The ASBROKERII_RECV_INTERVAL environmental variable sets the
interval, in milliseconds, between checks of the receive queue for job
status coming from the Unicenter TNG Agent and AutoSys Connect
machines.

By default, it is set to 1000 milliseconds:

ASBROKERII_RECV_INTERVAL=1000

ASBROKERII_TRKARRAY_SI ZE
The ASBROKERII_TRKARRAY_SIZE environmental variable sets the
initial number of unique external dependencies handled by asbrokerII.

By default, the initial number of external dependencies is set to 40:

ASBROKERII_TRKARRAY_SIZE=40

ASBROKERII_CKP_PATH
The ASBROKERII_CKP_PATH environmental variable sets the location
of the asbrokerII checkpoint file. The checkpoint file contains the last
timestamp of the last record that is received from a specific agent.

By default, this is set to /tmp:

ASBROKERII_CKP_PATH=/tmp

■ A-12 AutoSys User Guide for UNIX

 Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS ■
AutoSys and AutoSys Connect Cross-Platform Dependencies

AutoSys and AutoSys Connect Cross-Platform

1

Dependencies
AutoSys jobs can have dependencies on jobs managed by the AutoSys
Connect scheduling software running in the OS/390 environment. For
example, an AutoSys job defined to run on a UNIX or NT machine could
have as a starting condition the successful completion of a AutoSys
Connect job running on a mainframe system.

AutoSys UNIX OS/390

REMOTE_HOST: MYMACHIN REMOTE_HOST: CA7
Instance: ACE

Event C
Server CCI CCI O
N
N Job
E
C
T

Event
Processor asbrokerII

*CCI components are listed in Appendix A, Introducing CCI in the

AutoSys Installation and Getting Started Guide.

Figure A-1 • AutoSys and AutoSys Connect (OS/390) cross-platform configuration

AutoSys User Guide for UNIX A-13 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS
AutoSys and AutoSys Connect Cross-Platform Dependencies

In Figure A-1, communication between AutoSys and AutoSys Connect is

handled by asbrokerII and the communication components.

The AutoSys Event Processor communicates with AutoSys Connect

through an AutoSys process called asbrokerII, which communicates
with any supported agent through CCI.

In addition, a file named config.EXTERNAL is present on the machine on

which the AutoSys Event Processor was installed. In this file, the
mainframe has been identified with a three-letter uppercase instance
name, as described in Create the config.EXTERNAL File on page A-7.

1 Job Scheduler Interdependencies

AutoSys jobs can be dependent on the status of AutoSys Connect jobs.
For details on how to implement this with the AutoSys Connect job
scheduler, refer to your AutoSys Connect documentation.

For AutoSys jobs, this type of cross-platform dependency is described

below.

To create job scheduler interdependencies

1 AutoSys sends a request to asbrokerII for the status of a AutoSys
Connect job running on a mainframe.

2 asbrokerII passes the request to AutoSys Connect.

3 AutoSys Connect registers the request.

4 The job runs as scheduled by AutoSys Connect which can run the job
on the mainframe.

5 The completion status of the job is passed to asbrokerII.

6 asbrokerII communicates the status to the AutoSys database.

7 The Event Processor starts the AutoSys job that is dependent on the
completion of the remote job.

■ A-14 AutoSys User Guide for UNIX

 Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS ■
AutoSys and AutoSys Connect Cross-Platform Dependencies

1 Notation for Cross-Platform Job Dependencies

To define a cross-platform job dependency, use the following notation:
JOB_NAME^INS
Where INS is a three-letter uppercase identifier of the instance on which
the job is running.
The caret symbol (^) before the instance name indicates that the job
resides on a different instance of AutoSys.

Note • Job names for cross-platform dependencies must be all

uppercase.

From JIL, you enter this in the condition job attribute, as shown in the
following example:
condition: success(JOB_NAME^INS)
From the AutoSys GUIs, enter this information in the Starting Condition
field of the Job Definition screen. Use the following statuses in the
condition attribute of an AutoSys job definition dependent on a AutoSys
Connect job:
■ success
■ terminated
■ done
■ notrunning

AutoSys User Guide for UNIX A-15 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS
AutoSys and AutoSys Connect Cross-Platform Dependencies

AutoSys and AutoSys Connect Cross-Platform

Dependency Example
Below is an example of an AutoSys job that will start only upon the
successful completion of “JOBA,” an OS/390 scheduler defined job that
runs on a mainframe:
condition: success(JOBA^CA7)

where success(JOBA^CA7) specifies the successful completion of an OS/

390 scheduler defined job named “JOBA” running on a mainframe
specified with the three-letter ID of “CA7.”

Naming Conventions for AutoSys Connect Cross-Platform

1

Jobs
Because of naming limitations in the OS/390 environment, the names of
jobs specified as job dependencies between AutoSys and AutoSys
Connect must follow these guidelines:

■ The first character of a job name must be an uppercase alpha character

or one of the following characters: #, @ $. The remaining characters
in the job name can be any combination of uppercase alphabetic
characters, numbers, or #, @ $ characters.

■ Job names can be no longer than eight characters.

■ All alphabetic characters must be in uppercase.

Note • These limitations do not apply to all AutoSys jobs, only to jobs
that will be referenced to AutoSys Connect.

For more information on cross-instance job dependencies, see the

Cross-Instance Job Dependencies section of Chapter 3, AutoSys Jobs.

■ A-16 AutoSys User Guide for UNIX

 Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS ■
Running AutoSys Jobs on Agents

1 Running AutoSys Jobs on Agents

AutoSys can directly schedule jobs on a machine that is running a
supported agent, assuming the machine running the agent has been
defined to AutoSys. In the following example configuration, the agent is
running on an AS/400 machine. AutoSys and agent integration is
supported on other operating platforms as well.

AutoSys UNIX AS/400

REMOTE_HOST: MYMACHIN REMOTE_HOST = ZASYS400
Instance: ACE

Event CCI CCI Job

Server

Event
Processor asbrokerII AGENT

* CCI components are listed in Appendix A, Introducing CCI in the

AutoSys Installation and Getting Started Guide.

Figure A-2 • AutoSys and agent configuration

In Figure A-2, communication between AutoSys and all agents is handled

by asbrokerII and CCI.

■ The AutoSys Event Processor communicates with an agent through an

AutoSys process called asbrokerII.

■ The communication components running on the AutoSys machine

receive information from the agent and pass it to asbrokerII.

■ An agent (which in this example is running on the AS/400 platform)

is analogous to an AutoSys Remote Agent.

AutoSys User Guide for UNIX A-17 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS
Running AutoSys Jobs on Agents

1 Agent Job Names and User IDs

Agent job names and user IDs have the same naming restrictions as
AutoSys.

Where the operating system allows, agent job names can contain up to
64 alphanumeric characters and agent user IDs can contain up to 30
alphanumeric characters. These job names and user IDs can be both
uppercase and lowercase (when the operating system allows mixed case).
Blank spaces and tabs are illegal characters.

1 Running Jobs on Agent Managed Machines

The process by which AutoSys can run jobs directly on an agent managed
machine is described below.

To run jobs on agent managed machine

1 The Event Processor sends the job information to asbrokerII and the
job changes to STARTING status.

2 asbrokerII passes the information to the agent, which starts the job.

3 The agent passes the information that the job is running (BOJ event)
to CCI on the AutoSys machine which writes it to the proper broker
instance.

4 asbrokerII writes the AutoSys database; the job changes to

RUNNING status.

5 When the job exits, the agent client traps the return code and passes
the information that the job is finished to asbrokerII.

6 asbrokerII writes the AutoSys database; the job changes to a status of

either SUCCESS (if the job exited with a normal end of job code, EOJ)
or FAILURE (if the job exited with an abnormal end of job code,
AEOJ).

■ A-18 AutoSys User Guide for UNIX

 Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS ■
Running AutoSys Jobs on Agents

1 Defining Agent Machines to AutoSys

Before you can run AutoSys jobs on an agent machine, you must first
define the agent machine to AutoSys using the insert_machine sub-
command. This command adds a new machine definition to the AutoSys
database. It is described in detail in Chapter 9, Load Balancing and
Queuing Jobs. This section pertains specifically to defining an agent
machine.

To define an agent machine, use JIL and follow this example:

insert_machine: REMOTE_HOST
type: MACHINE_TYPE

where:
REMOTE_HOST

Is the name of the agent machine.

MACHINE_TYPE

Is one of the following:

• t

Indicates a machine running Unicenter TNG, CA-7, or CA-JobTrac.

• c

Indicates a machine running AutoSys Connect.

If AutoSys Connect is running on the same machine as CA-7,

CA-JobTrac, or any OS/390 scheduling system, the machine type
should be c.

Note • Agent managed machines cannot be part of a virtual machine.

job_load, max_load, and factor attributes are not supported for agent
managed machines.

AutoSys User Guide for UNIX A-19 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS
Running AutoSys Jobs on Agents

For example, to define the machine shown in Figure A-2 on page

page A-17, which has a REMOTE_HOST of “ZASYS400,” you would specify
the following:
insert_machine: ZASYS400
type: t

Job Definition Examples

The following job definition example is for AS/400:
insert_job: as400_a1 job_type: c
command: DLYJOB DLY(15)
machine: usprncax
owner: user1@usprncax
permission: gx,wx
date_conditions: 1
days_of_week: all
start_mins: 30

The following job definition example is for AutoSys Connect:

insert_job: cas1 job_type: c
command: auto_cnct -a A87SOENF -j RYAKEJ01 -c RUN -p SCHEDULE=RYAKE01 -s CAS
machine: A87SOENF
owner: user1@A87SOENF
permission: gx,wx
date_conditions: 1
days_of_week: all
start_mins: 45

1 AutoSys Agent Machine in an AutoSys Job Definition

Once you have defined an AutoSys Agent machine to AutoSys and that
machine is recorded in the Application Registry Table, you can specify
that machine in an AutoSys job definition, using the machine job
attribute. For example:
insert_job: TEAMJOB
owner: bob@sahara
machine: ZASYS400
command: echo “test”

■ A-20 AutoSys User Guide for UNIX

 Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS ■
Running AutoSys Jobs on Agents

The owner identified in the owner attribute of the job definition must
have an account on the target agent machine. The account must match
the owner name exactly in order for the job to run. The owner of the job
definition must be specified as “user@machine.” The AutoSys Edit
Superuser must use the autosys_secure binary to add valid userids and
passwords using option 4 as follows:

1 Start the AutoSys Security Utility:

$ autosys_secure
2 Select option 4 from the menu:

AutoSys Security Utility

Please select an action to perform:
[1] Change AutoSys EDIT and EXEC superusers.
[2] Change AutoSys database password.
[3] Change AutoSys remote authentication method.
[4] Create AutoSys User@Host or Domain password.
[5] Change AutoSys User@Host or Domain password.
[6] Delete AutoSys User@Host or Domain password.
[7] Exit autosys_secure.
> 4
3 Enter the user name, user host or domain, and password information
when prompted:
Enter user name : bob
Enter user Host or Domain : sahara
Enter new password:
Enter new password again:
User Create successful.

AutoSys User Guide for UNIX A-21 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS
Log and Trace Information

1 Log and Trace Information

If AutoSys is unable to start a job on an agent, an entry will be inserted
into the Event Processor log located in the $AUTOUSER/out directory.

AutoSys Connect and AutoSys Agent Job

1

Statuses
The valid statuses that AutoSys can get for AutoSys Connect and AutoSys
Agent managed jobs are:

STARTING

The job has been passed from the Event Processor to asbrokerII.

RUNNING

The job has started and a BOJ (Beginning Of Job) event has been sent
back to asbrokerII.

SUCCESS

The job has ended and an EOJ (End Of Job) event has been passed
back to asbrokerII.

FAILURE

The job has ended and an AEOJ (Abnormal End Of Job) event has
been sent back to asbrokerII.

Any AutoSys Connect or AutoSys Agent managed job without a return

code of zero will be considered TERMINATED.

■ A-22 AutoSys User Guide for UNIX

 Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS ■
Unsupported Attributes for AutoSys Connect or AutoSys Agent Jobs

Unsupported Attributes for AutoSys Connect or

1

AutoSys Agent Jobs

The following AutoSys attributes are not supported for AutoSys Connect
or AutoSys Agent managed jobs. If specified, they will be ignored. The jil
attribute is listed on the left and the corresponding GUI field is shown on
the right.

chk_files Resource Check - File System Space...

heartbeat_interval Heartbeat Interval (mins)

job_load Job Load

job_terminator If the Box fails should this Job be Terminated?

job_type:f Job Type (File Watcher)

n_retrys Number of Times to Restart this Job after a

FAILURE

priority Que Priority

profile Job Environment Profile

std_err_file File to Redirect to Standard Error

std_in_file File to Redirect to Standard Input

std_out_file File to Redirect to Standard Output

term_run_time Terminate this Job Mins after starting

watch_file File To Watch For

watch_file_min_size Minimum File Size (in Bytes)

watch_interval Time Interval (secs) to Determine Steady

State

AutoSys User Guide for UNIX A-23 ■

■ Integrating with the Mainframe and AutoSys Agents for AS/400 and OpenVMS
Cross-Platform Limitations

1 Cross-Platform Limitations
When you running across platforms, keep the following in mind:

■ If you are running a Shadow Event Processor, cross-platform

dependencies will be lost if the Shadow Event Processor takes over.

■ The chase and autoping commands cannot return any information on

AutoSys Connect or AutoSys Agent jobs and machines.

■ Remote Authentication is not supported for AutoSys Connect or

AutoSys Agent jobs.

■ The following events cannot be executed on a AutoSys Connect or

AutoSys Agent job:

• CHANGE_PRIORITY

• SEND_SIGNAL

■ A-24 AutoSys User Guide for UNIX

 B
Troubleshooting CCI
This appendix describes troubleshooting CCI for AutoSys.
Troubleshooting Tools for Remote CCI Connections . . . . . . . . . . . . . . . . . . . . . B-2

CCI Command Line Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4

Reinstalling CCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9

AutoSys User Guide for UNIX B-1 ■

■ Troubleshooting CCI
Troubleshooting Tools for Remote CCI Connections

Troubleshooting Tools for Remote CCI

2

Connections
The following are troubleshooting tools:

netstat
The netstat command allows you to check TCP/IP statistics:

■ netstat –a | grep caic

Shows all connections to the local host involving a port which can be
resolved to caic(ci). The important connections are ESTABLISHED
and LISTEN. If the latter is present, you know that the kernel accepts
connections on behalf of the ccirmtd process. This means that a
remote host attempting to connect to this host should get the TCP/IP
connected state. Established connections are important because we
know that CCI transactions may not transpire between the hosts in
question if a TCP/IP Established connection does not exist.

It is important to understand that netstat output is of the form:

ip-address:port
where the local host listed to the left of the remote host. One side will
always have a port that resolves to caicci and the other side will have
a numeric port. The latter side is that which initiated the connection.

Sometimes netstat –a does not return or may take a long time to

return with very little information. This is usually indicative of name
resolution problems. You can issue:
netstat –an | grep 1721
netstat skips the name resolution and displays information about
connections.

■ B-2 AutoSys User Guide for UNIX

 Troubleshooting CCI ■
Troubleshooting Tools for Remote CCI Connections

■ netstat –i

Shows information about the network interfaces on the local hosts.

You can use the netstat –i command to determine if the host has
more than one network card and determine the hostnames or IP
addresses of these cards. The netstat –i command also provides
valuable statistics about network collisions. A collision occurs when
two hosts simultaneously attempt to send on an ethernet. The
important thing to look for is high ratio of outgoing or incoming
packets to collisions.

Ping
Ping allows you to establish that a remote host can be reached. It is
important to ping by IP address as well as hostname. If you cannot ping
a host, CCI cannot establish a connection to that host.

nslookup
nslookup allows you to be sure that the name of the host to which you
wish to connect, as well as the IP address, is resolvable. If there is a
question as to the integrity of the DNS environment, you can use
nslookup to verify the IP address of the host to which you need to
communicate. You then enter the IP address back into nslookup and
verify that the same hostname is returned. Verify the IP address and
hostname for both hosts.

traceroute
The traceroute command on UNIX and the tracert command on
Windows NT allow you to determine the route taken between two hosts.
If a client cannot ping a host, this command may show where the
network path is failing.

AutoSys User Guide for UNIX B-3 ■

■ Troubleshooting CCI
CCI Command Line Controls

ccinet
ccinet may be used to pass commands to the ccirmtd daemon on UNIX.
On Windows NT, this is the rmtcntrl binary. This may be used as follows:

■ ccinet ping

Can be used to send a special CCI test packet across the CCI
connection. This does not use the native ping command nor does it
operate in quite the same way.

■ ccinet status

Allows you to determine the status of the CCI connections.

■ ccir/ccis/ccic/ccii

Provides you suite of test binaries to test application to application

CCI communication. (ccinet ping tests remote process to remote
process communication)

2 CCI Command Line Controls

Commands may be passed to CCI processes. Executables, therefore, may
gather diagnostic information from these processes.

On UNIX platforms the command binary for the main CCI daemon is:
$CAIGLBL0000/cci/bin/cci

The following verbs are available:

■ cci show

■ cci semashow and cci semaclear X

■ cci shutdown

■ cci debugon and cci debugoff

■ B-4 AutoSys User Guide for UNIX

 Troubleshooting CCI ■
CCI Command Line Controls

cci show
This allows you to view the shared memory segment where CCI stores the
RVT list. This is useful to determine general CCI information, such as:

■ The number of free and active RVTs

■ The key used to create the CCI resources

■ The identifiers for the CCI resources

■ The process ID’s of the CCI daemons

■ The time the shared memory was created

You can also use this command to display information about a specific
receiver, such as:

■ The existence of a specific receiver

■ The number of pending messages for a specific receiver

■ The PID of the process that created the receiver

■ The PID of the process that holds the semaphore for this receiver

■ The last send and receive time

■ The number of sends and receives

cci semashow and cci semaclear X

You can use the semashow command to determine if any of the CCI
semaphores are being held. This is useful information for conditions
when AutoSys is hanging. When a problem exists, the output of the
command will be two or more lines:
CAICCI_I_0003 i[X] sema[YYYY] pid[Z]
CAICCI_S_0046 Command completed successfully

When there is not a problem with the CCI semaphores, only the last line
is returned.

AutoSys User Guide for UNIX B-5 ■

■ Troubleshooting CCI
CCI Command Line Controls

The values listed are:

■ X—The particular semaphore identifier in the CCI semaphore group.

■ YYYY—The semaphore group.

■ Z—The process ID of the process holding the semaphore.

To use this to troubleshoot a hanging condition, execute the command

and note the process ID’s of those processes holding a CCI semaphore. It
is always a good idea to issue ps –ef in conjunction with this command.
If the process holding the semaphore is defunct, the group responsible
for support of this application should be contacted because CCI does not
release resources held by defunct processes.

Next, you issue the following for each held semaphore in the semashow
output:
cci semaclear X

The semaclear command releases the semaphore and may allow AutoSys
to continue normal operations.

cci shutdown
Tells the main daemon to shutdown. The use of this command is not
advised if AutoSys is still running.

cci debugon and cci debugoff

Will turn main daemon tracing on and off.

The binary used to pass commands to the CCI remote daemon is:
$CAIGLBL0000/cci/bin/rmt

■ B-6 AutoSys User Guide for UNIX

 Troubleshooting CCI ■
CCI Command Line Controls

The verbs available are:

■ ccinet show

This command will output data concerning the hosts to which the
remote daemon is or should be connected. It will also output
information about the receivers available on those remote platforms
similar to the RVT information displayed by ‘cci show’. The output
from this command is written to the ccirmtd trace file. Therefore, to
capture this output we prefer that traces have been enabled prior to its
execution. This data is also output to the system console. The output
from this command is usually important for solving all issues
involving remote communication.

■ ccinet debugon and ccinet debugoff

Used to enable or disable remote traces without recycling the remote

daemon.

Trace data is written to:

$CAIGLBL0000/cci/logs/ccirmtd_<pid>.log

■ ccinet status

Will display information concerning the remote hosts to which the

remote daemon is connected or to which it should be connected. This
data is displayed in tabular form on stdout. If you are receiving a "no
receiver online" type error, check this output as it may show that you
are not connected to the host in question.

■ ccinet release

The release of the ccirmtd is displayed to stdout.

Note • The cci 666 command is no longer supported in TNG.

AutoSys User Guide for UNIX B-7 ■

■ Troubleshooting CCI
CCI Command Line Controls

The command gives the release as follows:

xxxyyzzzz
where:

xxx—Is the source code version (for example, 1.137)

yy—Is the genlevel of Unicenter (for example, 21 for TNG 2.1)

zzzz—Is the release of Unicenter (for example, 9708)

■ ccinet disconnect sysid

Causes the local remote to issue a disconnect command to the

specified sysid and close down the connection. This has the effect of
severing the connection between these hosts. Neither side attempts to
reestablish the connection.

■ ccinet reconnect sysid

If hosts are connected, this causes them to disconnect and then

reconnect. If hosts are not connected, the local remote daemon will
attempt to connect to the remote host.

■ ccinet ping sysid

A useful diagnostic tool which causes the local remote daemon to

send a special CCI packet to which the other host responds. This
command allows you to determine if the CCI connection is useful at
the most basic level. Upon successful completion, the roundtrip time
is displayed.

■ ccinet echo sysid message

If successful, the message is displayed on the target systems console.

Another useful tool for determining how well the CCI connection
between two hosts is functioning.

■ B-8 AutoSys User Guide for UNIX

 Troubleshooting CCI ■
Reinstalling CCI

■ ccinet retry sysid N

Will affect the retry time interval as follows:

• Set the retry time interval to N, if N >0

• Set the retry time interval to 2, then double on each successive

failure, if N = -1

• Prevent the local host from attempting to reconnect if N = 0

The commands are passed to the CCI daemon processes using the
message queue facility. Therefore, if there is a problem with these
facilities the commands may not function correctly.

2 Reinstalling CCI
If you need to reinstall CCI, for any reason, reinstall AutoSys. When the
AutoSys installation asks you if you want to install CCI, answer yes.

Note • Before you reinstall CCI, unset CAIGLBL0000. Log in as root at

a UNIX prompt and enter: unset CAIGLBL0000

For more information about CCI installation, see the appendix

“Introducing CCI” in the AutoSys Installation and Getting Started Guide.

AutoSys User Guide for UNIX B-9 ■

Index

Symbols alarm callbacks 13-41

$AUTORUN 3-30 Alarm Manager
$AUTOSYS/bin/chk_auto_up 12-33 about 10-4
$AUTOSYS/code/heartbeat.c 4-25 acknowledging alarms 10-30
$AUTOSYS/code/heartbeat.sh 4-25 Alarm List 10-31
$AUTOSYS/dbobj/create_table 12-33 Alarm Selection dialog 10-36
$AUTOTESTMODE 12-11 Select by State region 10-37
$AUTOUSER/autosys.env 12-31 Select by Time region 10-38
$AUTOUSER/config.$AUTOSERV 13-4 Select by Type region 10-37
$SYBASE 12-31 changing alarm states 10-35
$SYBASE/install/RUN_AUTOSYSDB closing alarms 10-30
12-31 Control Region
/bin/date command 12-11 Freeze Frame button 10-34
/etc/.autostuff file 13-35, 13-36 New Alarm button 10-35
/etc/auto.profile file. See auto.profile file Select Job button 10-34
/etc/services file, Remote Agent port Currently Selected Alarm
number 13-33 acknowledging 10-34
/tmp/autotest.$JobName 12-11 closing 10-33
Response edit box 10-33
A menu bar 10-32
ACTIVATED status 3-10 registering responses 10-35
advanced configuration 13-1 alarm monitor/report attribute 11-8
after_time report attribute 11-10 alarm_if_fail job attribute 4-15

AutoSys User Guide for Windows NT Index -1 ■

■ Index

alarm_verif monitor attribute 11-11 job_name 4-5

alarms job_terminator 4-16
about 1-12 machine 4-8, 4-9
DB_PROBLEM 13-41 max_exit_success 4-24
DB_ROLLOVER 13-41 max_run_alarm 4-14
EP_HIGH_AVAIL 13-42 min_run_alarm 4-14
EP_ROLLOVER 13-41 n_retrys 4-16
EP_SHUTDOWN 13-42 optional
all_events monitor/report attribute 11-8 Box Jobs 4-27
all_status monitor/report attribute 11-9 Command Jobs 4-19
archive data for ServerVision 13-39 File Watcher Jobs 4-26
atomic starting conditions 10-13 non-starting parameters 4-13
attributes starting parameters 4-10
job override_job 4-23
alarm_if_fail 4-15 permission 4-18
auto_delete 4-17 priority 4-23, 9-6
auto_hold 4-17 run_calendar 4-10
avg_runtime 4-24 run_window 4-12
basic 3-8 start_mins 4-12
box_failure 4-27 start_times 4-11
box_name 4-14 std_err_file 4-21
box_success 4-27 std_in_file 4-20
box_terminator 4-15 std_out_file 4-20
chk_files 4-25, 4-26 term_run_time 4-15
command 4-5, 4-6 timezone 4-16
condition 4-13 watch_file 4-9
date_conditions 4-10 watch_file_min_size 4-26
days_of_week 4-10 watch_interval 4-26
description 4-13 job dependencies 3-18
essential machine
all jobs 4-5 factor attribute 9-6
Box Jobs 4-9 max_load 9-5
Command Jobs 4-6 monitor
File Watcher Jobs 4-9 alarm_verif 11-11
exclude_calendar 4-11 sound 11-11
heartbeat_interval 4-24 monitor/report
job_load 4-22 alarm 11-8

■ Index-2 AutoSys User Guide for Windows NT

 Index ■

all_events 11-8 AutoSys

all_status 11-9 components 1-4
essential 11-7 database, defined 1-5
job_filter 11-9 Graphical User Interface, see GUI
mode 11-7 instances, defined 1-11
name 11-7 machines 1-10
report security 2-1
after_time 11-10 AutoSys Agent
currun 11-10 software requirements A-5
starting conditions 3-18 AutoSys Agent support A-1
authentication, remote 13-35 AutoSys Connect and AutoSys Agent
auto.profile file support A-1 to A-24
AutoMachWideAppend variable 13-28 AutoSys/Xpert 4-24, 6-4
AUTOSV variable 13-39 autosys_secure 4-18
AUTOSV_DIR variable 13-39 AutoSysAgentSupport 13-27
DENY_ACCESS 13-37 AutoSysAgentSupport parameter A-6
Remote Agent settings 13-29 autosyslog command 12-6, 14-18
remoteProFiles 13-22 avg_runtime 4-24
auto_delete 4-17
auto_hold 4-17 B
auto_remote. See Remote Agent backups
autocal 8-5 bundled Sybase 12-35
autocons 10-7 calendar definitions 12-14
autohold job attribute 4-17 global variables (using autorep) 12-15
AutoInstWideAppend 13-27 job definitions (using autorep) 12-14
AutoMachWideAppend variable 13-28 machine definitions (using autorep)
autoping 14-13 12-14
AutoRemoteDir 13-20 monitor and browser definitions (using
AutoRemPort 13-26, 13-33 monbro) 12-15
autosc 11-5 batch files and exit codes 3-27
AUTOSERV environment variable 13-4 Box Jobs 3-6, 5-1
autostuff file 13-35, 13-36 basic job definition 3-9
AUTOSV environment variable 13-39 default behavior 5-3
AUTOSV_DIR environment variable diagram 3-14
13-39 examples 5-11
force starting jobs in a box 5-9
guidelines 5-4

AutoSys User Guide for Windows NT Index -3 ■

■ Index

non-default terminators 5-7 exporting definitions to file 12-14

placing job in File menu 8-7
GUI 6-19 importing 8-8, 8-28
JIL 7-11 importing definitions from file 12-16
starting conditions 3-6, 3-16 Job Definition Reference List 8-9
status changes 5-10 merging 8-27
box_failure 4-27 navigation controls 8-12
box_name 4-14 opening 8-7
box_success 4-27 Options menu 8-10
box_terminator 4-15 periods 8-20
browsers print command 8-10
backing up definitions 12-15 printing 8-8, 8-28
defined 11-3 rescheduling rules 8-22
restoring definitions from backup file restoring definitions 12-16
12-16 reverting to last saved 8-8
rule specification 8-18
C saving 8-7
Calendar Selection dialog 8-16 selecting 8-16
calendars 8-1 to 8-35 Set Print command 8-10
applying rules 8-8 setting dates 8-18
backing up definitions 12-14 Term Calendar Rule 8-17
blocked dates 8-11 Term Calendar Viewer 8-9, 8-25
blocking dates 8-18 Tools menu 8-9
Calendar Definition window 8-6 unsetting dates 8-18
clearing 8-8 CCI
color key 8-14 command line controls B-4
combining 8-27 reinstalling B-9
conflicting dates 8-12, 8-14 troubleshooting tools B-2
creating, example 8-14 ccinet B-4
custom 3-18 charge back reporting 9-18
customizing Calendar Facility 8-31 chase command 12-12
date range 8-10, 8-19 check file space 4-25, 4-26
date states 8-11 Check_Heartbeat 13-19
deleting 8-7 chk_auto_up 13-14
Edit menu 8-8 chk_files 4-25
exiting 8-8 clean_files 12-13, 13-21
exporting 8-8, 8-28, 8-30 CleanTmpFiles 13-21

■ Index-4 AutoSys User Guide for Windows NT

 Index ■

client machine 1-10 XInstanceDBDropTime 13-11

command job attribute 4-5, 4-6 configure the AutoSys Machine A-6
Command Jobs 3-5, 3-8 Control Panel, GUI 6-3
command line controls, CCI B-4 cpu, using available cycles to select
components machine to run on 9-12
Event Processor 1-6 crash recovery, database 12-23, 12-43
Event Server 1-5 cross-instance, database connection 13-11
Remote Agent 1-7 Currently Selected Job region 10-11
condition job attribute 4-13 currun report attribute 11-10
conditions, starting 3-18 custom calendars, overview 3-18
config.EXTERNAL, creating the file A-7 customizing
configuration file 13-4 Calendar Facility 8-31
AutoInstWideAppend 13-27 Job Definition 6-31
AutoRemoteDir 13-20 Operator Console 10-38, 11-22
AutoRemPort 13-26
AutoSysAgentSupport 13-27 D
Check_Heartbeat 13-19 database
CleanTmpFiles 13-21 accessing interactively 12-33
DBEventReconnect 13-12 administration 12-29
DBLibWaitTime 13-10 architecture 12-18
DBMaintCmd 13-17 backup, bundled Sybase 12-35
EDErrTimeInt 13-13 changing the “sa” password 12-30
EDMachines 13-14 checking if up 12-32
EDNumErrors 13-13 connection to Job Definition GUI time-
EvtTransferWaitTime 13-17 out interval 6-32
FileSystemThreshold 13-15 connection to Monitor/Browser GUI
InetdSleepTime 13-28 time-out interval 11-22
KillSignals 13-25 connections 13-12
MachineMethod 13-24 crash recovery 12-23
MaxRestartTrys 13-23 defined 12-16
MaxRestartWait 13-23 defining which to use 12-18
RemoteProFiles 13-22 dumping 12-35
RestartConstant 13-23 identifying connected processes 12-34
RestartFactor 13-23 maintenance 13-16
sample 13-4 maintenance script 13-17
ThirdMachine 13-14 maintenance time 12-20
WaitTime 13-23 passwords 2-10

AutoSys User Guide for Windows NT Index -5 ■

■ Index

recovery 12-23, 12-43 dependency, job

reloading 12-45 date/time 3-17
rollover 12-23 exit code 3-26
shutdown 12-32 global variables 3-28
starting 12-31 job status 3-18
stopping 12-32 dependent jobs
stopping service 12-32 creating - GUI 6-17
storage requirements 12-18 creating -JIL 7-9
time-out period 13-10 example 3-23
unrecoverable error 12-23 description job attribute 4-13
verifying connection 14-13 done condition in job definition 3-19
dataserver, defined 1-5 DSQUERY variable 12-29
date dependency 3-17 Dual Event Servers
date range in calendars 8-10, 8-19 crash recovery 12-23
date/time job dependencies 3-17 defined 1-6
Date/Time Options dialog, example 6-7 mode 12-17
date_conditions 4-10 synchronizing Event Servers 12-24
days to run job, setting Dual Server Mode 12-23
GUI 6-23
JIL 7-12 E
days_of_week 4-10 EDErrTimeInt 13-13
DB Library 12-28 edit permissions 2-13
DB_PROBLEM 13-41 Edit Superuser 2-16
DB_ROLLOVER 13-41 EDMachines 13-14
DBDropTime EDNumErrors 13-13
Job Definition GUI 6-32 environment variables
Monitor/Browser GUI 11-23 AUTOSERV 13-4
DBEventReconnect 13-12 DSQUERY 12-29
DBLibWaitTime 13-10 See also profiles
DBMaint script 12-21 SYBASE 12-29
DBMaintCmd 13-17 user-defined 4-7
dbstatistics script 12-21 EP_HIGH_AVAIL 13-42
default owner of job 2-11 EP_ROLLOVER 13-41
delete job EP_SHUTDOWN 13-42
GUI 6-26 errors
JIL 7-13 Event Processor handling 13-13
DENY_ACCESS AUTOENV setting 13-37 Event Processor time interval 13-13

■ Index-6 AutoSys User Guide for Windows NT

 Index ■

essential job attributes 4-5 eventor

Event Processor script 12-3
See also event_demon events
allowable time between errors 13-13 about 1-11
authentication on Remote Agent 13-35 cancelling 10-19
automatic shutdown 13-13 copying between Event Servers 13-17
checking for running 13-14 EvtTransferWaitTime 13-17
defined 1-6 examples
error handling 13-13 calendar rescheduling rule 8-23
heartbeat interval 13-19 calendar, creating 8-14
log individual queues 9-23
minimum disk space 13-15 JIL 7-16
viewing 12-6 job dependencies 3-23
monitoring 12-4, 12-6 load balancing 9-13
restoring 12-9 monitor/report definition 11-15
running in test mode 12-10 multiple machine queues 9-25
shutdown, automatic 13-13 queuing with priority 9-21
starting 12-3, A-10 real machine definition 9-8
stopping 12-7, A-6 reports, defining in JIL 11-21
tail command 12-4 system architecture 1-8
Third Machine 13-14 virtual machine definition 9-9
troubleshooting 14-11 xql scripts 12-33
Event Report, from Operator Console exclude_calendar 4-11
10-14 exclusive condition 3-24
Event Server Exec Superuser 2-17
See also database execute permissions 2-13
See also Dual Event Servers exit codes
defined 1-5 batch files, with 3-27
dual 12-17, 12-18 FALSE.EXE 3-28
recovery 12-23 job dependencies 3-26
rollover 12-23 maximum for success 3-20
synchronizing process 12-24 exitcode 3-26
transferring events 13-17 exporting calendars 8-30, 12-14
troubleshooting 14-3
event_demon 12-3
See also Event Processor

AutoSys User Guide for Windows NT Index -7 ■

■ Index

F Job Definition dialog 6-4, 6-5

factor attribute 9-6 JobScape 6-4
failure condition in job definition 3-19 Monitor/Browser dialog 6-3
FAILURE status 3-11 one-time job overrides 6-27
FALSE.EXE 3-28 Operator Console 6-3
file locking 13-20 starting 6-3
file maintenance 13-21 time dependencies, setting 6-23
File Watcher Jobs 3-7 TimeScape 6-4
basic job definition 3-9 using to create a job definition 4-4
creating 6-13
FileSystemThreshold 13-15 H
filter, monitor/report 11-9 heartbeat_interval 4-24
force starting jobs heartbeats
from Job Activity console 10-15 about 13-18
impact on load balancing 9-14 checking 13-18
code to include 4-25
G interval 4-24
gid 2-12, 4-19 time interval 13-19
global variables high availability
backing up definitions 12-15 Dual Event Servers 1-6
job dependencies 3-28 Shadow Event Processor 1-7
restoring definitions 12-16 HostScape 6-3
setting, in the Send Event dialog 10-18
Graphical Calendar Facility 8-1 to 8-35 I
Calendar Definition window 8-6 Import/Export File Name (calendar)
screens 8-5 dialog 8-28
See also calendars importing calendars 8-28, 12-16
starting 8-5 INACTIVE status 3-10
group ID 2-12, 4-19 inetd
GUI job starting inverval 13-28
Advanced Features dialog 6-9 resetting 13-25
Control Panel 6-3 InetdSleepTime 13-28
Date/Time Options dialog 6-7 InfoReports
defined 1-3 configuring for printing 10-49
defining monitor/reports 11-12 inherit, job’s starting conditions 3-16
HostScape 6-3 instances of AutoSys 1-11

■ Index-8 AutoSys User Guide for Windows NT

 Index ■

J Global Name/Value 10-18

JIL Job Name 10-17
creating a job definition 4-3 Queue Priority 10-18
defined 1-4 Send Priority 10-18
defining jobs 7-3 Signal 10-18
defining monitors/reports 11-19 time of event 10-17
defining report 11-21 starting conditions 10-13
example 7-16 Job Definition dialog 6-4
running 7-6 customizing 6-31
sub-commands 7-5 database connection time-out 6-32
syntax rules 7-3 icon text 6-32
Job Activity Console 10-8 title bar text 6-32
See also Operator Console Job Definition Reference List 8-9
Alarm button 10-23 Job Information Language 1-12
Alarm Manager dialog 10-30 See also JIL
cancelling a sent event 10-19 Job List region 10-10
Control Area 10-15 job overrides, setting 7-14, 7-15
action buttons 10-15 job resource usage 9-18, 13-40
control buttons 10-21 Job Selection dialog 10-24
Dependent Jobs button 10-21 Box Levels field 10-26
Freeze Frame button 10-22 Job Name field 10-26
Job Definition button 10-21 setting job selection criteria 10-30
Report buttons 10-22 sorting specified jobs 10-29
Currently Selected Job region 10-11 specifying jobs
Dependent Jobs dialog 10-21 by machine 10-28
Job List 10-10 by name 10-25
Job Path (History) dialog 10-22 by status 10-27
Job Selection dialog 10-24 job starts, reducing start interval 13-28
menu bar 10-9 job status, as job dependency 3-18
reports 10-14 job_filter monitor/report attribute 11-9
resizing regions 10-24 job_load 4-22
Send Event dialog 10-16 job_name 4-5
AUTOSERV instance 10-18 job_terminator 4-16
Cancel button 10-18 jobs
Change Status 10-18 attributes, basic 3-8
Comment field 10-17 backing up definitions 12-14
Execute button 10-18 basic job information 3-5

AutoSys User Guide for Windows NT Index -9 ■

■ Index

Box Jobs 5-1 exit codes 3-26

creating - GUI 6-19 global variables 3-28
creating - JIL 7-10 job status 3-18
defined 3-6 time
changing - GUI 6-21 GUI 6-23
changing - JIL 7-11 JIL 7-12
Command Jobs edit permissions 2-13
creating - GUI 6-10 execute permssions 2-13
creating - JIL 7-7 exit code 3-26
defined 3-5 File Watcher
creating creating - GUI 6-13
Box Jobs - GUI 6-19 creating - JIL 7-8
Box Jobs - JIL 7-10 defined 3-7
Command Jobs - GUI 6-10 force starting 9-14, 10-15
Command Jobs - JIL 7-7 heartbeats from 4-25
File Watcher Jobs - GUI 6-13 number of restart attempts 13-23
File Watcher Jobs - JIL 7-8 overrides
creating a job definition 4-3 GUI 6-27
custom calendars 3-18 JIL 7-14
cycles of processing 14-3 owner, default 2-11
date/time dependencies permissions on NT 2-15
setting in GUI 6-23 queuing 9-6, 9-18
setting in JIL 7-12 restart tries 13-23
days to run, setting 6-23 restoring definitions from backup file
defined 1-3 12-16
defining environment for 4-7 run number 3-30
defining in AutoSys 3-30 saving definitions to backup file 12-14
definition selection list 6-22
Box 3-9 starting conditions 3-15
Command 3-8 done 3-19
File Watcher 3-9 failure 3-19
deleting notrunning 3-19
GUI 6-26 success 3-19
JIL 7-13 terminated 3-19
dependencies states 3-10
creating with GUI 6-17
creating with JIL 7-9

■ Index-10 AutoSys User Guide for Windows NT

 Index ■

status M
ACTIVATED 3-10 machine
FAILURE 3-11 attribute 4-8, 4-9
INACTIVE 3-10 backing up definitions 12-14
managing 3-24 client 1-10
ON_HOLD 3-12 defining with JIL 9-4
ON_ICE 3-12 deleting
QUE_WAIT 3-11 real machines 9-9
RESTART 3-11 virtual machines 9-10
STARTING 3-10 factor attribute 9-6
SUCCESS 3-11 job runs on 4-8
TERMINATED 3-11 machine attribute 9-4
status codes 3-10 max_load attribute 9-5
time dependencies, setting permissions, edit and execute 2-13
JIL 7-12 priority job attribute 9-6
time/date dependencies 3-17 real 9-3
types 3-4 restoring definitions from backup file
variables for 4-7 12-16
JobScape 6-4 saving definitions to backup file 12-14
server 1-10
K type attribute 9-4
KILLJOB signals 13-25 virtual 9-3
KillSignals 13-25 defining 9-9
deleting 9-10
L MachineMethod 13-24
license keys A-9 maintenance
load balancing 9-11 backing up AutoSys definitions 12-13
example 9-13 calendar definitions 12-14
force starting jobs 9-14 global variables 12-15
job attributes required for 9-5 job definitions 12-14
maximum load on machine 9-5 machine definitions 12-14
method 13-24 monitor and browser definitions
ServerVision 13-38 12-15
user-defined 9-26 chase command 12-12
locking, Remote Agent log file 13-20 clean_files 12-13
commands 12-12
database 13-16

AutoSys User Guide for Windows NT Index -11 ■

■ Index

database time 12-20 N

files 13-21 n_retrys 4-16
restoring AutoSys definitions 12-16 name monitor/report attribute 11-7
managing job status 3-24 netstat B-2
max_exit_success 4-24 NIS, troubleshooting 14-15
max_load machine attribute 9-5 notification, user-defined notification
max_run_alarm 4-14 routines 13-41
maximum exit code for success 3-20 notrunning condition in job definition
maximum system load 9-5 3-19
MaxRestartTrys 13-23 nslookup B-3
MaxRestartWait 13-23 ntrys 3-30
method of load balancing 13-24
min_run_alarm 4-14 O
mode monitor/report attribute 11-7 ON_HOLD 3-12
Monitor/Browser dialog 6-3, 11-12 ON_HOLD vs. ON_ICE 3-12
customizing 11-22 ON_ICE 3-12
database connection time-out 11-22 one-time job overrides 6-27
icon text 11-23 Open Client C Library 12-17
title bar text 11-23 Operator Console 6-3
monitors 11-1 to 11-23 about 10-4
about 11-4 Alarm Manager dialog 10-7
alarm_verif 11-11 Alarm Selection dialog 10-7
backing up definitions 12-15 customizing 10-38
defined 11-3 Alarm List column width 10-46
defining 11-4, 11-15 alarm poll time interval 10-39
GUI 11-12 atomic conditions fields 10-45
JIL 11-19 background color of variable fields
filtering 11-8 10-43
filtering events 11-3 border colors 10-44
job_filter 11-9 changing fonts 10-40
name 11-7 currently selected Job Name field
restoring definitions from backup file 10-42
12-16 Default Report type 10-46
sound 11-11 font selection 10-41
status events 11-9 freeze frame at start up 10-40
multiple machine queues 9-25 icon text 10-47
Job List column widths 10-45

■ Index-12 AutoSys User Guide for Windows NT

 Index ■

label font 10-41 port number for Remote Agent 13-26

list font 10-41 priority job attribute 4-23, 9-6
object color 10-42 profile script 3-5
Operator Console size 10-46 profiles 4-7
primary interface colors 10-44
refresh time interval 10-39, 10-44 Q
title bar text 10-47 QUE_WAIT status 3-11
Job Activity Console 10-7, 10-8 queuing
Job Selection dialog 10-7 and simple load limiting 9-19
See also Job Activity Console as subset of virtual machine 9-23
starting 10-7 jobs 9-18
optional job attributes 4-10 multiple machine 9-25
Oracle policies 9-18
improving database performance 12-26 with priority 9-20, 9-21
SQL*Net V2 12-17
override_job 4-23 R
overrides, job real machines 9-3
GUI 6-27 defining 9-4
JIL 7-14 deleting 9-9
owner, default 2-11 example 9-8
type 9-4
P reconnecting to database 13-12
passwords recovery
autosys user 2-10 database 12-43
database 2-10 Sybase database 12-43
database system administrator 12-30 Remote Agent
permission attribute 4-18 auto_remote service 13-33
permissions 2-3, 4-18 database connectivity 14-20
edit 2-13, 4-19 defined 1-7
execute 2-13, 4-18 Event Processor authentication 2-10
granting 2-13 heartbeat interval 13-19
machine 2-13 log 14-18
types 2-13 modifying settings for 13-33
user 2-11 port number 13-26
using umask 2-12 security 2-19
Windows NT 2-15 security, DENY_ACCESS 13-37
ping B-3 settings 13-33

AutoSys User Guide for Windows NT Index -13 ■

■ Index

socket connection 13-33 Font Selection 8-32

troubleshooting 14-13 icon text 8-35
user authentication 2-9 Object Color 8-33
Remote Agent Event Processor Print Command 8-35
authentication 13-35 title bar text 8-35
Remote Agent log Window Size 8-34
cleanup 13-21 Job Definition 6-31
name assigned 14-18 database connection time-out 6-32
specifying directory for file 13-20 icon text 6-32
Remote Agent settings in auto.profile title bar text 6-32
13-29 Monitor/Browser
remote authentication 13-35 database connection time-out 11-22
configuring 13-35 icon text 11-23
Event Processor 2-10 title bar text 11-23
user 2-9 Operator Console 10-38, 11-22
RemoteProFiles 13-22 alarm list column width 10-46
reports 11-1 to 11-23 alarm poll time interval 10-39
about 11-4 atomic condition fields 10-45
all_events 11-8 border colors 10-44
all_status 11-9 currently selected job name field
defined 11-3 color 10-42
defining 11-4, 11-15 default report type 10-46
GUI 11-12 font selection 10-41
JIL 11-19 freeze frame at start up 10-40
defining - GUI 11-17 icon text 10-47
defining - JIL 11-21 job list column widths 10-45
filtering 11-8 label font 10-41
filtering events 11-3 list font 10-41
job_filter 11-9 Operator Console size 10-46
name 11-7 primary interface color 10-44
Operator Console 10-14 refresh time interval 10-39
status events 11-9 title bar text 10-47
resource check, file space 4-25, 4-26 toggle button color 10-44
resource usage monitoring 13-40 variable fields background color
resources 10-43
Calendar Facility restart attempts, maximum number 13-23
date range 8-34 RESTART status 3-11

■ Index-14 AutoSys User Guide for Windows NT

 Index ■

restart wait time, calculating 13-23 remote authentication 13-35

RestartConstant 13-23 superusers, AutoSys 2-15
RestartFactor 13-23 user permissions 2-11
restoring select getdate 12-32
calendar definitions 12-16 Send Event dialog 10-16
global variables (using autorep) 12-16 AUTOSERV instance 10-18
job definitions (using autorep) 12-16 Cancel button 10-18
machine definitions (using autorep) cancelling an event 10-19
12-16 Change Status 10-18
monitor and browser definitions 12-16 Comment field 10-17
Primary Event Processor 12-9 Execute button 10-18
rollover Global Name/Value 10-18
Event Server 12-23 Job Name 10-17
Shadow Event Processor 12-8 Queue Priority 10-18
rstatd 13-24 Send Priority 10-18
Rule Specification region 8-18 Signal 10-18
Run MonBro button 11-14 time of event 10-17
run number 3-30 sendevent command 2-17
RUN_AUTOSYSDB 12-31 server instance 1-5
run_calendar 4-10 server machine 1-10
run_num/ntry, defined 3-30 ServerVision
run_window 4-12 charge back reporting 9-18
RUNNING status 3-10 integration 13-38
ruserok 2-9, 13-35 job resource usage monitoring 9-18,
13-40
S load balancing 9-15
scripts services file, Remote Agent port number
database maintenance 13-17 13-33
DBMaint 12-21 Shadow Event Processor
start_autodb 12-31 defined 1-7
security 2-1, 2-3 rollover 12-8
DENY_ACCESS Remote Agent setting starting 12-9
13-37 SIGHUP signal 13-25
granting permissions 2-13 signals, UNIX 13-25
permission types 2-13 Single Server Mode 12-23
preventing unauthorized access 2-8 SNMP connections 13-23
Remote Agent 2-19

AutoSys User Guide for Windows NT Index -15 ■

■ Index

socket connection for Remote Agent running 11-9

13-33 starting 11-9
socket time-out 13-23 success 11-9
sound monitor attribute 11-11 terminated 11-9
SQL*Net V2 12-17 processed vs. unprocessed 3-15
standard output/error append parameter using in job dependencies 3-18
13-27 std_err_file 4-21
start interval between jobs 13-28 std_in_file 4-20
start_autodb script 12-31 std_out_file 4-20
start_mins 4-12 STOP_DEMON 12-7, 12-32, 12-43
start_times 4-11 success
starting conditions 3-15, 3-18 condition in job definition 3-19
in Job Activity Console 10-13 maximum exit code 3-20
STARTING status 3-10 SUCCESS status 3-11
STARTJOB 7-6 Summary Report, from Operator Console
states 10-14
job 3-10 superusers 2-15
See also status Edit Superuser, defined 2-16
status Exec Superuser, defined 2-17
job svarchive utility 13-41
ACTIVATED 3-10 svload command 9-15
as job dependency 3-18 svload configuration requirements 13-38
FAILURE 3-11 Sybase
INACTIVE 3-10 accessing interactively 12-33
monitoring and reporting 11-9 architecture 12-28
ON_HOLD 3-12 bundled 12-28
ON_ICE 3-12 defining a dump device 12-36
QUE_WAIT 3-11 disk dump device 12-36
RESTART 3-11 dumping the database 12-40
RUNNING 3-10 loading the database 12-41
STARTING 3-10 tape dump device 12-37
SUCCESS 3-11 communication with 12-28
TERMINATED 3-11 database
tracking changes 11-9 displaying date and time 12-35
monitor/report identifying connected processes
failure 11-9 12-34
restart 11-9 improving performance 12-25

■ Index-16 AutoSys User Guide for Windows NT

 Index ■

DB Library 12-28 time dependencies

DSQUERY variable 12-29 in job definition 4-10
environment 12-29 overview 3-17
environment variable 12-29 setting
interfaces file 12-29 GUI 6-23
server 12-28 JIL 7-12
shutdown command 12-32 TimeScape 6-4
SQL.INI file 12-29 timezone 4-16
starting 12-31 tmpfs, locking problems 13-20
stopping 12-32 traceroute B-3
System 10 backup server 12-37 transferring events between Event Servers
users 12-29 13-17
SYBASE variable 12-29 troubleshooting 14-1
synchronizing Event Servers 12-24 Event Processor 14-11
syntax rules, JIL 7-3 Event Servers 14-3
system administrator, database 12-30 Remote Agent 14-13
system load, maximum 9-5 troubleshooting tools, CCI B-2
ccinet B-4
T netstat B-2
target machine 4-8 nslookup B-3
technical support xxiii ping B-3
Term Calendar Rule dialog 8-17 traceroute B-3
Control region 8-24
Rescheduling Rule region 8-22 U
Term Calendar Viewer 8-9, 8-25 uid 2-12, 4-19
Calendar Display 8-26 user ID 2-12, 4-19
Navigation Controls 8-26 user types
term_run_time 4-15 group 2-12
terminated condition in job definition owner 2-12
3-19 world 2-12
TERMINATED status 3-11 user-defined
test mode alarm callbacks 13-41
output file 12-11 environment variables 4-7
running in 12-10 load balancing 9-26
ThirdMachine 13-14 users, bundled Sybase 12-29
utilities, provided with AutoSys 1-12

AutoSys User Guide for Windows NT Index -17 ■

■ Index

V
variables in a Command Job definition
4-7
virtual machines 9-3
defining 9-4, 9-9
deleting 9-10
example 9-9
type 9-4
using delete_machine 9-4
using insert_machine 9-4
vmstat 13-24

W
WaitTime 13-23
watch_file 4-9
watch_file_min_size 4-26
watch_interval 4-26
Windows NT
job permissions on 2-15

X
X resources, customizing Calendar Facility
8-31
XInstanceDBDropTime 13-11
xql, example scripts 12-33

■ Index-18 AutoSys User Guide for Windows NT