PLATINUM

AutoSys
User Guide for UNIX
Version 3.4

Title and Publication Number

PLATINUM Publication Number: ATS-U-342-UG00-01
Printed: December, 1997
Information in this guide is subject to change without notice and does not constitute a
commitment on the part of PLATINUM technology, inc. It is supplied on an as is basis
without any warranty of any kind, either explicit or implied. Information may be changed
or updated in this guide at any time.
Copyright Information
AutoSys is copyright 1993 - 1997 by PLATINUM technology, inc. and its subsidiaries. This
guide is copyright 1993 - 1997 by PLATINUM technology, inc., and its subsidiaries and
may not be reproduced in whole or in part, by any means, without the written permission
of PLATINUM technology, inc. and its subsidiaries.
Names marked or and other company and product names may be trademarks or
registered trademarks of their respective vendors or organizations.
Mailing Address
PLATINUM technology, inc.
1815 South Meyers Road
Oakbrook Terrace, Illinois
60181-5235

Table of Contents
Preface
Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Contacting Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Whats New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Year 2000 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
PLATINUM ProVision Common Services Integration . . . . . . . . . . . . . . . xxii
Reporting using InfoReports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
ServerVision Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
AutoSys/Connect Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Bundled Sybase System 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Security Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Event Processor Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Configuration File Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
Time Zone Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
Set Append or Overwrite Behavior for Standard Files . . . . . . . . . . . . . . xxvi
Hewlett-Packard IT/Operations Support . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
User-configurable Title Bar and Icon Text . . . . . . . . . . . . . . . . . . . . . . . xxvii
Expanded Number of Entries in config.EXTERNAL File . . . . . . . . . . . . xxvii
AutoSys Command Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxix
Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx

1 Introduction to AutoSys
AutoSys Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
Defining Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
System Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4
Event Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5
Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-6

PLATINUM AutoSys User Guide for UNIX

iii

 Table of Contents

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

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-7
AutoSys Database Field Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Job Definition Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
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-12
Job Permissions and Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
AutoSys Superuser Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Edit Superuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Exec Superuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Restricting Access to AutoSys Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Remote Agent Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18

iv

PLATINUM AutoSys User Guide for UNIX

Table of Contents

3 AutoSys Jobs
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3
Job Types and Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3
Basic Job Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-4
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
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-25
Job Dependencies Based on Global Variables . . . . . . . . . . . . . . . . . . . 3-28
Job Run Numbers and Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29
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

PLATINUM AutoSys User Guide for UNIX

 Table of Contents

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-25
Box Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26
Date and Time Attributes and Time Changes . . . . . . . . . . . . . . . . . . . . . . . . 4-27
The Time Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27
AutoSys Behavior During Time Change . . . . . . . . . . . . . . . . . . . . . . . . . 4-29

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-4
Box Job Attributes and Terminators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Attributes in a Box Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Attributes in a Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Time Conditions in a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Force Starting Jobs in a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
How Job Status Changes Affect Box Status . . . . . . . . . . . . . . . . . . . . . . . 5-9
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
Advanced Conditions in Box Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Default Box Success and Box Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Explicit Box Success and Box Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15
Using the Box Terminator Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
Using the Job Terminator Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
Advanced Job Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18

vi

PLATINUM AutoSys User Guide for UNIX

Table of Contents

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-8
Creating a Simple Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Creating a File Watcher Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Creating a Dependent Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
Creating a Box Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18
Changing a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20
Setting Time Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22
Additional Time Setting Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24
Deleting a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25
Deleting a Box Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
Specifying One-Time Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
Setting Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29
Customizing the Job Definition GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
Database Connection Time-out Interval . . . . . . . . . . . . . . . . . . . . . . . . 6-31
Job Definition Title bar Text and Icon Text . . . . . . . . . . . . . . . . . . . . . . 6-31

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-10
Setting Time Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
Additional Time Setting Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12

PLATINUM AutoSys User Guide for UNIX

vii

 Table of Contents

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
Creating a Simple Calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14
Dates Prior to Todays 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-30
Font Selection Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-32
Object Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-33
Date Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-34
Window Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-34

viii

PLATINUM AutoSys User Guide for UNIX

Table of Contents

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-3
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
Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11
Force Starting Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14
Load Balancing Using ServerVision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14
Testing the Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17
ServerVision Monitoring and Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18
Queuing Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18
Queuing and Simple Load Limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19
Queuing with Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20
SubsetsIndividual Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22
Multiple Machine Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-24
User-Defined Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-25

10 The Operator Console

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Alarm Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
InfoReports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Operator Console Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Operator Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PLATINUM AutoSys User Guide for UNIX

10-4
10-4
10-5
10-7
10-7

ix

 Table of Contents

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-14
Resizing Regions of the Job Activity Console . . . . . . . . . . . . . . . . . . . . 10-23
Job Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-23
Specifying a Job by Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24
Specifying Jobs by Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26
Specifying Jobs by Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-27
Sorting the Specified Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28
Setting the Job Selection Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
Changing the Console Clock Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
Alarm Manager Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
Alarm Manager Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31
Alarm List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31
Currently Selected Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-32
Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
Alarm Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-35
Select by Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-36
Select by State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-36
Select by Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-37
Customizing the Operator Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-37
Refresh Time Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-38
Alarm Poll Time Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-38
Changing Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-39
Freeze Frame at Start Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-39
Font Selection Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-40
Label Font Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-40
List Font Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-40
Object Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-41
Job List Column Widths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-44
Operator Console Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-45

PLATINUM AutoSys User Guide for UNIX

Table of Contents

Default Report Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Alarm List Column Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Operator Console Title bar Text and Icon Text . . . . . . . . . . . . . . . . . .
User-Configurable Action Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Console Clock Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10-45
10-45
10-46
10-46
10-49

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
Essential Monitor/Report Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Common Essential AttributesGeneral . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Common Essential AttributesEvents . . . . . . . . . . . . . . . . . . . . . . . . . . 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

PLATINUM AutoSys User Guide for UNIX

xi

 Table of Contents

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-15
AutoSys Database Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16
Event Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16
Database Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18
General Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-19
Daily Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20
DBMaint Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20
Event Server Rollover Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-22
Event Server Crash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-23
Synchronizing the Event Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-23
Improving Database Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-24
Improving Sybase Database Performance . . . . . . . . . . . . . . . . . . . . . . 12-24
Improving Oracle Database Performance . . . . . . . . . . . . . . . . . . . . . . 12-25
Maintaining Bundled Sybase SQL Servers . . . . . . . . . . . . . . . . . . . . . . . . . . 12-27
Sybase Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-27
Sybase Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-28
Default Sybase Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-28
Starting Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-30
Stopping Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-31
Accessing Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-32
Identifying Processes Connected to the Database . . . . . . . . . . . . . . . 12-33
Displaying the Database Date and Time . . . . . . . . . . . . . . . . . . . . . . . 12-34
Bundled Sybase Backup and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . 12-34

13 Configuring AutoSys
AutoSys Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3
Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Configuration File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9
Database Time-out Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10
Cross-Instance Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . 13-11

xii

PLATINUM AutoSys User Guide for UNIX

Table of Contents

Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Event Processor Cascading Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Machines to Check for Running Event Processors . . . . . . . . . . . . . . .
Third Machine for Event Processor Contention . . . . . . . . . . . . . . . . .
Event Processor Log Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Internal Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Event Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Heartbeats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remote Agent Log Files Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SNMP Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenView IT/Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Number of Restart Attempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calculating the Wait Time Between Restarts . . . . . . . . . . . . . . . . . . . .
Method of Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
KILLJOB Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Port Number for Remote Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Z/Team Job Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Instance Wide Append Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling PLATINUM Event Management and Data Exchange . . . . .
Inetd Job Starting Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The auto.profile File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample Default auto.profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remote Agent Database Connection Settings . . . . . . . . . . . . . . . . . .
Modifying Remote Agent Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remote Agent Socket Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running Two AutoSys Versions of Remote Agents . . . . . . . . . . . . . .
Configuring Remote Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring Event Processor Authentication . . . . . . . . . . . . . . . . . . . .
Client-Side Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring ServerVision Monitoring and Reporting . . . . . . . . . . . . . . . .
Library Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
svload Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ServerVision Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . .

PLATINUM AutoSys User Guide for UNIX

13-11
13-12
13-13
13-14
13-15
13-15
13-16
13-17
13-18
13-18
13-21
13-27
13-27
13-28
13-29
13-30
13-31
13-31
13-32
13-33
13-34
13-35
13-36
13-37
13-38
13-38
13-39
13-40
13-41
13-42
13-43
13-43
13-43
13-44

xiii

 Table of Contents

ServerVision Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-44

Monitoring Job Resource Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-45
User-Defined Alarm Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-46

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
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 RunsNo 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 AutoSys with Zeke and AutoSys/Team Agent

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Definition of Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
Job Scheduling for the Enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5
Installing and Configuring for Enterprise Job Scheduling . . . . . . . . . . . . . . . A-6
Install the Basic AutoSys Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Stop the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7
Configure the AutoSys Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7

xiv

PLATINUM AutoSys User Guide for UNIX

Table of Contents

Initializing the Communication Components . . . . . . . . . . . . . . . . . . . . . . . .

License Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Restart the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About the oasis_broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AutoSys and Zeke Cross-Platform Dependencies . . . . . . . . . . . . . . . . . . . .
Job Scheduler Interdependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Notation for Cross-Platform Job Dependencies . . . . . . . . . . . . . . . . . .
Naming Conventions for AutoSys/Zeke Cross-Platform Jobs . . . . . . .
Running AutoSys Jobs on the Team Agent . . . . . . . . . . . . . . . . . . . . . . . . .
Running Jobs on Team Agent Managed Machines . . . . . . . . . . . . . . .
Defining Team Agent Machines to AutoSys . . . . . . . . . . . . . . . . . . . . .
Team Agent Machine in an AutoSys Job Definition . . . . . . . . . . . . . . .
Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logs and Trace Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Zeke and Team Agent Job Statuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unsupported Attributes for Zeke or Team Agent Jobs . . . . . . . . . . . . . . . .
Cross-Platform Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-13
A-14
A-15
A-15
A-16
A-17
A-18
A-19
A-20
A-21
A-22
A-23
A-23
A-23
A-24
A-24
A-26

Index

PLATINUM AutoSys User Guide for UNIX

xv

 Table of Contents

xvi

PLATINUM AutoSys User Guide for UNIX

Preface
Welcome to the world of AutoSys, the scheduling and operations
automation software for distributed computing environments. This
guide describes how to use AutoSys to define and run jobs.
This guide is intended for users who will be responsible for defining jobs
to AutoSys, and monitoring and managing these jobs. It assumes
familiarity with the UNIX operating system, as well as the operating
system on which the jobs will run. It assumes that you have already
installed AutoSys using the AutoSys Installation and Getting Started Guide
for UNIX.

Philosophy

PLATINUM technology, inc., is the leading vendor of open enterprise

systems management (OESM) products, which help organizations
manage all the hardware and software components of the multiplatform,
multi-operating system, multivendor environment called the open
enterprise environment (OEE).
By leveraging its expertise in relational technology, PLATINUM offers
products and services that increase the efficiency of individual computing
systems and databases, as well as the interoperability of these systems
and databases in distributed environments.

PLATINUM AutoSys User Guide for UNIX

xvii

 Preface
Contacting Technical Support

Contacting Technical Support

You can contact us with any questions or problems you have. You will be
directed to an experienced software engineer familiar with PLATINUM
AutoSys.
To send Email to PLATINUM Technical Support, use:
Internet
[email protected]
IBM MAIL Exchange
USRWNPSN
To contact PLATINU M Technical Support, use:
USA or Canada, toll free 800-833-PLAT (7528)
IBM Software Mall
PLATSM4
CompuServe
GO PLATINUM
For product assistance or information, contact:
USA or Canada, toll free 800-442-6861
Illinois
630-620-5000
FAX
630-691-0708 or 630-691-0406
Internet
[email protected]
World Wide Web
http://www.platinum.com
Our Mailing Address is:
PLATINUM technology, inc.
1815 South Meyers Road
Oakbrook Terrace, IL 60181-5235

About This Guide

The PLATINUM AutoSys User Guide for UNIX explains how to define, run,
monitor, manage, and control AutoSys. It has been designed to present
information in a natural order so that basic concepts are discussed prior
to more advanced topics.

xviii

PLATINUM AutoSys User Guide for UNIX

Preface
About This Guide

This guide assumes that the appropriate PLATINUM AutoSys

components have been installed at your site. The instructions for
installing the product are in the AutoSys Installation and Getting Started
Guide for UNIX.
Ch.
No. Chapter Name

Content Description

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.

AutoSys Security

Provides information about

permissions, superusers, and security.

AutoSys Jobs

Describes AutoSys job types and

provides information about basic job
attributes, starting parameters, and job
states.

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.

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.

PLATINUM AutoSys User Guide for UNIX

xix

 Preface
About This Guide

Ch.
No. Chapter Name

xx

Content Description

Defining AutoSys Jobs

Using the GUI

Describes how to use the AutoSys

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.

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.

The Graphical Calendar

Facility

Describes the AutoSys Graphical

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.

Load Balancing and

Queuing Jobs

Describes the use of real and virtual

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.

PLATINUM AutoSys User Guide for UNIX

Preface
About This Guide

Ch.
No. Chapter Name

Content Description

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

Jobs

Describes how to use the GUI or JIL to

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.

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.

Integrating AutoSys with

Zeke and AutoSys/
Team Agent

Explains how to set up and implement

these enterprise-wide scheduling with
AutoSys, Zeke, and Team Agent
components.

Index

Helps you locate information within

this manual.

PLATINUM AutoSys User Guide for UNIX

xxi

 Preface
Whats New

Whats New

PLATINUM AutoSys Version 3.4 offers all the functions available in

Version 3.3, plus the new features in this section.

Year 2000 Support

The AutoSys 3.4.2 GUIs and command-line interfaces now support the
specification and display of four-digit years. If you enter a two-digit year,
AutoSys saves the setting to the database as a four-digit year using a date
window rule. If you enter 79 or less, AutoSys prepends 20, and if you
enter 80 or greater, AutoSys prepends 19. That is, if you enter 79, it
becomes 2079, and if you enter 80, it becomes 1980.

PLATINUM ProVision Common Services Integration

You can enable AutoSys to send events to the PLATINUM Event Manager
and Data Exchange. If enabled, AutoSys will send events for every
AutoSys job to the Event Manger. If you have installed the PLATINUM
ProVision common services, you can view these events with the
PLATINUM Director. Enabling Data Exchange instructs AutoSys to write
job definition and job history information to the POEMS common
services repository.

Reporting using InfoReports

AutoSys bundles an InfoReports Viewer and a number of reports with

details on AutoSys jobs that you can view using the InfoReports GUI.
Access these reports by defining and clicking on one of the
user-configurable action in the Operator Console.
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.

xxii

PLATINUM AutoSys User Guide for UNIX

Preface
Whats New

Job Find
This report allows you to enter a pattern for the job name and report
on all jobs that match the pattern.
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 can also configure the InfoReports Viewer to print the reports.

ServerVision Integration

You can use the ServerVision GUIs to monitor the real-time resource
usage of AutoSys jobs. This integration allows you to view AutoSys jobs
by their job name in the ServerVision GUIs. In addition, AutoSys will
archive job resource usage (CPU utilization, I/O reads and writes, and
average memory usage) to generate reports for capacity planning and
UNIX processes auditing (charge back).
A new load balancing command, svload, can be specified in the machine
attribute of an AutoSys job definition. This enables AutoSys to apply
machine performance metrics monitored by ServerVision to select, at
runtime, the best machine on which to run a job.

AutoSys/Connect Integration

Integration with AutoSys/Connect lets you communicate between many

mainframe legacy scheduling products and AutoSys. You can define an
AutoSys job to conditionally start after a legacy mainframe scheduler job
completes. And you can use AutoSys to schedule a job on the mainframe
through your legacy scheduler. See the PLATINUM AutoSys/Connect User
Guide for details on how to set up and use this feature.

PLATINUM AutoSys User Guide for UNIX

xxiii

 Preface
Whats New

Bundled Sybase System 11

If you purchased AutoSys with a bundled database, you received Sybase

System 11.

Security Enhancements

These are the enhancements to AutoSys security:

You can now enter NT user IDs and passwords from either a UNIX or
an NT machine, using autosys_secure.

The autosys_secure utility now accepts NULL for an NT user

password.

You can now run autosys_secure in command-line mode.

Event Processor Enhancements

These are the enhancements to Event Processor behavior:

xxiv

If you configure AutoSys to run in Dual Server mode, the Event

Processor will not start unless both databases are available.

The Event Processor will shut down if insufficient disk space is

available to write the to the Event Processor log file. A new parameter,
FileSystemThreshold, was added to the AutoSys configuration file.
This parameter specifies the minimum amount of disk space that
must be available, or the Event Processor will issue a warning. The
default setting is 32 kilobytes. If the disk space drops below 8
kilobytes, the Event Processor will shut down.

PLATINUM AutoSys User Guide for UNIX

Preface
Whats New

Configuration File Enhancements

These new parameters were added to the configuration file:

AutoInstWideAppend
FileSystemThreshold
AutoPems

AutoInstWideAppend
This parameter specifies whether to overwrite or append to standard error
and standard output files.

FileSystemThreshold
This parameter specifies the minimum amount of disk space that must be
available, or the Event Processor will issue a warning. If the disk space
drops below 8 kilobytes, the Event Processor will shut down.

AutoPems
This parameter enables AutoSys to communicate with PLATINUM Event
Management and Data Exchange.

Time Zone Setting

Jobs with time-based starting conditions that do not specify a time zone
are scheduled to start based on the time zone under which the Event
Processor runs. This time zone is also used to report event times with the
autorep command.
Before you start the Event Processor, ensure that the TZ environment
variable is set. The Event Processor references this setting to determine
the default time zone.

PLATINUM AutoSys User Guide for UNIX

xxv

 Preface
Whats New

Set Append or Overwrite Behavior for Standard Files

You can now configure AutoSys to either overwrite or append to standard

error and standard output files. You control this behavior for each
AutoSys instance by setting the AutoInstWideAppend parameter in the
AutoSys configuration file.
You can override the instance-wide setting for individual client machines
(Remote Agents) by setting the AutoMachWideAppend variable in the
/etc/auto.profile file. You can also set a behavior for a specific job by
placing special notation as the first character in the standard error or
standard output specification.

Hewlett-Packard IT/Operations Support

This release of AutoSys supports HP IT/Operations Center message,

application, and monitor capabilities. An AutoSys application group has
been provided to support key AutoSys applications from the IT/O user
interface. AutoSys provides its own console GUI which is crucial for
debugging problems that occur with AutoSys. It is recommended that
users of AutoSys monitor IT/O messages to detect when problems have
occurred, and then use the AutoSys console GUI to resolve the details of
the problem. Contact your PLATINUM sales representative for version
compatibility.

xxvi

PLATINUM AutoSys User Guide for UNIX

Preface
Whats New

User-configurable Title Bar and Icon Text

By modifying X resources, you can customize the icon text and title bar
text of the following AutoSys and AutoSys/Xpert GUIs:
AutoSys GUI

X Resources File Name

Calendar Definition

Autocal

AutoSys Operator Console

Autocons

AutoSys Launcher, Monitor/

Browser, and Job Definition

Autosc

AutoSys/Xpert: HostScape,
JobScape, and TimeScape

Xpert

Expanded Number of Entries in config.EXTERNAL File

The config.EXTERNAL file can contain up to 249 entries. You use this file
to implement cross-instance job dependencies within AutoSys, and to
implement cross-platform dependencies for AutoSys Zeke and Team
Agent integration.

AutoSys Command Changes

There are changes to the following AutoSys commands:

archive_events
autobcp
autosyslog
autosys_secure

PLATINUM AutoSys User Guide for UNIX

xxvii

 Preface
Whats New

archive_events
The archive_events command has the following new argument:
-s num_of_days

This option removes ServerVision audit information older than the

specified number of days from the svarchive table. The DBMaint script
automatically archives old data from the svarchive table.

autobcp
The autobcp command has two new options which allow you to specify
the source database and the target database. These both default to
autosys. This is the new command syntax:
autobcp source_server target_server dump_file\
autosys_password [source_db_name target_db_name]

autosyslog
The autolog command has been renamed to autosyslog.

autosys_secure
The autosecure command has been renamed to autosys_secure. In
addition, security enhancements (discussed above) were added to
facilitate security administration from both UNIX and Windows NT
platforms.

xxviii

PLATINUM AutoSys User Guide for UNIX

Preface
Conventions

Conventions

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.

alternate
color

(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 documents PLATINUM General

Applications Guide
syntax variables
Monospace

COPY filename

&HIGHLVL.SRCLIB
directories, file names,
command names, computer
code

computer screen text, system Copy file? Y/N

responses, command line
commands
Monospace
bold

what a user types

...enter RUN APP.EXE in the

Application field

<>

the name of a key on the

keyboard

Press <Enter>.

PLATINUM AutoSys User Guide for UNIX

choosing a command from a File  Import  Object

cascading menu

xxix

 Preface
Related Publications

Related Publications

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

xxx

Release Notes: AutoSys version 3.4 for UNIX, 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.

PLATINUM AutoSys User Guide for UNIX

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.
This chapter provides a brief overview of AutoSys, its system architecture,
and features.
AutoSys Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Defining Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

PLATINUM AutoSys User Guide for UNIX

1-1

 Introduction to AutoSys

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

PLATINUM AutoSys User Guide for UNIX

Introduction to AutoSys
AutoSys Jobs

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.

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.

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

PLATINUM AutoSys User Guide for UNIX

1-3

 Introduction to AutoSys
System Components

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

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 platformspecific; 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.
Figure 1-1 illustrates the AutoSys system components in a basic
configuration. In addition, this figure illustrates the communication
paths between the components.

1-4

PLATINUM AutoSys User Guide for UNIX

Introduction to AutoSys
System Components

AutoSys Server
(UNIX or NT)

UNIX Client
Remote Agent

Event Processor
UNIX Job
NT Client
Remote Agent
Event Server
(database)
NT Job

Figure 1-1 AutoSys Components in a Basic Configuration

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.

PLATINUM 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.

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.

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.

1-6

PLATINUM AutoSys User Guide for UNIX

Introduction to AutoSys
System Components

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.

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.

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.
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/*

PLATINUM AutoSys User Guide for UNIX

1-7

 Introduction to AutoSys
System Components

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

Processor

Determines Actions
Initiates Action: Start
job on machine command:rm

/tmp/mystuff/*

Initiates Action: Starts Child

Process
Waits for Exit Code (from Child
Process)
Sends Exit event back to Event
Server

PROCESS
Event Server

PROCESS

WorkStation_2

UNIX Command

Events

Job Definitions

Local Area
Network

Runs UNIX Command:

rm /tmp/mystuff/*
Completes execution and
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.

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

1-8

PLATINUM AutoSys User Guide for UNIX

Introduction to AutoSys
System Components

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 commands 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.
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.

PLATINUM AutoSys User Guide for UNIX

1-9

 Introduction to AutoSys
AutoSys Machines

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

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

PLATINUM AutoSys User Guide for UNIX

Introduction to AutoSys
AutoSys Instance

AutoSys Instance

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

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 jobs 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.

PLATINUM AutoSys User Guide for UNIX

1-11

 Introduction to AutoSys
Alarms

Alarms

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

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

PLATINUM 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

The diagram in Figure 1-3 and the numbered explanations that follow it
illustrate how AutoSys performs its most basic functionstarting 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.

PLATINUM AutoSys User Guide for UNIX

1-13

 Introduction to AutoSys
Basic AutoSys Functionality

Event Processor

AutoSys Client
Event Server
(Database)

agent
connect

4
7

Remote Agent

6
Client Job

Figure 1-3 Basic AutoSys Functionality

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 5

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

PLATINUM 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 jobs 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.

PLATINUM 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

You can extend AutoSys with the AutoSys Zeke/Team Agent Integration
components in order to integrate AutoSys jobs with Zeke and the
AutoSys/Team Agent product from PLATINUMs Altai Development Lab.
Using cross-platform job dependency notation, you can define AutoSys
jobs to conditionally start based on the status of a Zeke job running on a
mainframe, and you can define Zeke jobs to conditionally start based on
the status of an AutoSys job. You can also define AutoSys jobs that will
run on a Team Agent machine, if the Team Agent machine is defined to
AutoSys.
In addition, you can install various AutoSys/Adapters. The applicationspecific 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 PLATINUM sales representative for
information on supported Adapters.
Figure 1-4 illustrates an extended AutoSys configuration that includes the
AutoSys Zeke/Team Agent Integration components and an
AutoSys/Adapter installation on a UNIX client.

1-16

PLATINUM AutoSys User Guide for UNIX

Introduction to AutoSys
Extending AutoSys Functionality

UNIX Client

AutoSys Server
(UNIX or NT)

UNIX Job
Remote Agent

NT Client
Remote Agent

Event Server
(database)
NT Job

AutoSys/Adapter

Event Processor

Mainframe
(MVS)

Application
oasis-broker

Other OS
(e.g., AS/400)

OASIS
Zeke/Team Agent
Communicator

Zeke

Team Agent
MVS Job
Job

Figure 1-4 AutoSys Components in an Extended Configuration

For more information, contact your sales representative.

PLATINUM AutoSys User Guide for UNIX

1-17

 Introduction to AutoSys
Extending AutoSys Functionality

1-18

PLATINUM AutoSys User Guide for UNIX

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 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-7
AutoSys Database Field Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Job Definition Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
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

PLATINUM AutoSys User Guide for UNIX

2-1

 AutoSys Security

AutoSys Permission Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12

Job Permissions and Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14
AutoSys Superuser Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Edit Superuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15
Exec Superuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-16
Restricting Access to AutoSys Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Remote Agent Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-18

2-2

PLATINUM AutoSys User Guide for UNIX

AutoSys Security
Overview

Overview

AutoSys security includes:

System-level security. See System-Level Security on page 2-7.

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.

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.

PLATINUM 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

PLATINUM 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?

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.

PLATINUM 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

PLATINUM AutoSys User Guide for UNIX

AutoSys Security
System-Level Security

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.

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

PLATINUM AutoSys User Guide for UNIX

2-7

 AutoSys Security
System-Level Security

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.

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.

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-8

PLATINUM AutoSys User Guide for UNIX

AutoSys Security
System-Level Security

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 clients Remote Agent to
make the ruserok() UNIX system call to check the client machines
/etc/hosts.equiv and the users .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.
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.

PLATINUM AutoSys User Guide for UNIX

2-9

 AutoSys Security
System-Level Security

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.

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.
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.

2-10

PLATINUM AutoSys User Guide for UNIX

AutoSys Security
AutoSys Job-Level Security

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.

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.

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.
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 owners 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.

PLATINUM AutoSys User Guide for UNIX

2-11

 AutoSys Security
AutoSys Job-Level Security

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-15.

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 jobs 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).

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.

2-12

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

PLATINUM AutoSys User Guide for UNIX

AutoSys Security
AutoSys Job-Level Security

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.
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 owners 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 owners 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).

PLATINUM AutoSys User Guide for UNIX

2-13

 AutoSys Security
AutoSys Job-Level Security

GUI

JIL

Meaning

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).

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.

Job Permissions and Windows NT

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

2-14

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.

PLATINUM AutoSys User Guide for UNIX

AutoSys Security
AutoSys Superuser Privileges

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.

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.

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.

PLATINUM AutoSys User Guide for UNIX

2-15

 AutoSys Security
AutoSys Superuser Privileges

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.
Note Any AutoSys user who knows an existing user ID and password

can change that password or delete that user and password.

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-16

PLATINUM AutoSys User Guide for UNIX

AutoSys Security
Restricting Access to AutoSys Jobs

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.

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

PLATINUM AutoSys User Guide for UNIX

2-17

 AutoSys Security
Restricting Access to AutoSys Jobs

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.

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.

2-18

PLATINUM AutoSys User Guide for UNIX

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-3
Basic Job Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
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
Starting Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
Starting Parameters and Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
Date/Time Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17

PLATINUM AutoSys User Guide for UNIX

3-1

 AutoSys Jobs

Job Dependencies Related to Job Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18

Event Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-22
Event Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-22
Job Dependencies Based on Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-25
Job Dependencies Based on Global Variables . . . . . . . . . . . . . . . . . . . . . . . . .3-28
Job Run Numbers and Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29
Defining Jobs in AutoSys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
AutoSys Graphical User Interface Components . . . . . . . . . . . . . . . . . . . . . . . .3-31

3-2

PLATINUM AutoSys User Guide for UNIX

AutoSys Jobs
Introduction

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.

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.

PLATINUM AutoSys User Guide for UNIX

3-3

 AutoSys Jobs
Job Types and Structure

Job

Basic Job
Information

Definition

Current State

Job
Types

Action

Name
Starting Conditions
Alarms
Restart Conditions

Depends On

Current status
Start time
End time
Exit code

Command
Command to execute
File to source
Machine to run on
Standard output files
Standard input file

Run Command
on Machine

File Watcher
Box

Container

File Name
Minimum File size
Watch Interval

Watch for File

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.

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 jobs starting conditions can be contingent on
the date, time, and the status of any other job.

3-4

PLATINUM AutoSys User Guide for UNIX

AutoSys Jobs
Job Types and Structure

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.
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.

PLATINUM AutoSys User Guide for UNIX

3-5

 AutoSys Jobs
Job Types and Structure

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

PLATINUM 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.

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.

PLATINUM AutoSys User Guide for UNIX

3-7

 AutoSys Jobs
Basic Job Attributes

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.

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

PLATINUM AutoSys User Guide for UNIX

AutoSys Jobs
Basic Job Attributes

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.)

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.)

PLATINUM AutoSys User Guide for UNIX

3-9

 AutoSys Jobs
Job States and Status

Job States and Status

AutoSys keeps track of the current state, or status, of every job. The value
of a jobs 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

PLATINUM 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.

PLATINUM 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 holdnothing
downstream from this job will run.
For details on how on ice affects boxes, see Chapter 5, Box Job Logic.

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

PLATINUM 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 Processor, indicating attempt to start job
on Remote Machine.

Event generated by Remote Agent

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

STARTING

RUNNING

Remote Agent

Inspects Exit Code

of the process.

Event generated by
Remote Agent

SUCCESS - OR - FAILURE

Figure 3-2 State DiagramSimple Jobs

PLATINUM AutoSys User Guide for UNIX

3-13

 AutoSys Jobs
Job States and Status

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 indicating that the box is Running. Nothing
actually RUNS. However, this EVENT
may trigger Jobs within the box to run.

RUNNING

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 DiagramBox 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

PLATINUM 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 jobs 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.

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.

PLATINUM 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.

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

PLATINUM AutoSys User Guide for UNIX

AutoSys Jobs
Starting Parameters

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).

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.

PLATINUM AutoSys User Guide for UNIX

3-17

 AutoSys Jobs
Starting Parameters

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 singlethreaded, 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

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.

3-18

PLATINUM AutoSys User Guide for UNIX

AutoSys Jobs
Starting Parameters

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.
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.

PLATINUM AutoSys User Guide for UNIX

3-19

 AutoSys Jobs
Starting Parameters

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 instances 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.
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.

3-20

PLATINUM AutoSys User Guide for UNIX

AutoSys Jobs
Starting Parameters

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

ACE

One Instance of AutoSys

PRD

config .ACE
config.EXTERNAL

Event
Server

Event
Processor

condition: success(jobB^PRD)
jobE

Event
Server

config.PRD
config.EXTERNAL

Event
Processor

jobB
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.
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.

PLATINUM AutoSys User Guide for UNIX

3-21

 AutoSys Jobs
Starting Parameters

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 instances Event Server can be reached.

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

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.

3-22

PLATINUM AutoSys User Guide for UNIX

AutoSys Jobs
Starting Parameters

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))

PLATINUM 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 jobs 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 arent
running. You would specify the smaller jobs 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

PLATINUM 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.)

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

PLATINUM AutoSys User Guide for UNIX

3-25

 AutoSys Jobs
Starting Parameters

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.

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.

3-26

PLATINUM AutoSys User Guide for UNIX

AutoSys Jobs
Starting Parameters

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

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.

PLATINUM AutoSys User Guide for UNIX

3-27

 AutoSys Jobs
Starting Parameters

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.

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 managers 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.
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.

3-28

PLATINUM AutoSys User Guide for UNIX

AutoSys Jobs
Job Run Numbers and Names

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 jobs
condition statement:
VALUE(manager-ok) = OK
Or
v (manager-ok) = OK

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.

PLATINUM AutoSys User Guide for UNIX

3-29

 AutoSys Jobs
Defining Jobs in AutoSys

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 jobs command. This value is contained in the variable $AUTORUN.
AutoSys also maintains a value for each jobs 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 jobs UNIX
command. The value is contained in the variable $AUTO_JOB_NAME.

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.
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-30

PLATINUM AutoSys User Guide for UNIX

AutoSys Jobs
Defining Jobs in AutoSys

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.
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.

PLATINUM AutoSys User Guide for UNIX

3-31

 AutoSys Jobs
Defining Jobs in AutoSys

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

PLATINUM 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-25
Box Job Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26

PLATINUM AutoSys User Guide for UNIX

4-1

 Job Attributes

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

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

4-2

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Job Attributes and Job Definitions

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
jobs 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.

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.

PLATINUM AutoSys User Guide for UNIX

4-3

 Job Attributes
Job Attributes and Job Definitions

value

Is the setting to be applied to the attribute.

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.

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.

4-4

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Essential Job Attributes

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.

Essential Job Attributes

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).

PLATINUM AutoSys User Guide for UNIX

4-5

 Job Attributes
Essential Job Attributes

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.

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 jobs 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 commands 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
scripteither 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.

4-6

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Essential Job Attributes

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}.
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 sourcedeither 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.

PLATINUM AutoSys User Guide for UNIX

4-7

 Job Attributes
Essential Job Attributes

Command line arguments can be passed using global variables.

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 jobs 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

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Essential Job Attributes

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.

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.

PLATINUM AutoSys User Guide for UNIX

4-9

 Job Attributes
Optional Job Attributes

Optional Job Attributes

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-27.

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

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

4-10

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Optional Job Attributes

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 onvia 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.

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 latearriving file from causing a job to run at an inopportune time. The run

PLATINUM AutoSys User Guide for UNIX

4-11

 Job Attributes
Optional Job Attributes

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.

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 jobs 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).

4-12

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Optional Job Attributes

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.

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.

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.

PLATINUM AutoSys User Guide for UNIX

4-13

 Job Attributes
Optional Job Attributes

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.
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.

4-14

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Optional Job Attributes

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.

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.

PLATINUM AutoSys User Guide for UNIX

4-15

 Job Attributes
Optional Job Attributes

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.
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 time zone under which
the Event Processor is running.

4-16

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Optional Job Attributes

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
boxs 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.
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.

PLATINUM AutoSys User Guide for UNIX

4-17

 Job Attributes
Optional Job Attributes

AutoSyss 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 users 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.
Edit
If edit permissions are enabled for the users 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-18

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Optional Job Attributes

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 jobs 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.
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.

PLATINUM AutoSys User Guide for UNIX

4-19

 Job Attributes
Optional Job Attributes

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 jobs 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 jobs 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_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.

4-20

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Optional Job Attributes

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 jobs 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

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 jobs load, the job will be

PLATINUM AutoSys User Guide for UNIX

4-21

 Job Attributes
Optional Job Attributes

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
machines 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.

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 jobs 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.

4-22

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Optional Job Attributes

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

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

PLATINUM AutoSys User Guide for UNIX

4-23

 Job Attributes
Optional Job Attributes

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 jobs 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.
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,

4-24

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Optional Job Attributes

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.

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 isnt 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.

PLATINUM AutoSys User Guide for UNIX

4-25

 Job Attributes
Optional Job Attributes

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.

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.

4-26

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Date and Time Attributes and Time Changes

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.

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.

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.

PLATINUM AutoSys User Guide for UNIX

4-27

 Job Attributes
Date and Time Attributes and Time Changes

Daylight-saving Time
3:00

1:00

4:00

5: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.
Standard Time
1:00

0:00

1:00

2:00

3:00

4: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-28

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Date and Time Attributes and Time Changes

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

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.

PLATINUM AutoSys User Guide for UNIX

4-29

 Job Attributes
Date and Time Attributes and Time Changes

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.
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

4-30

PLATINUM AutoSys User Guide for UNIX

Job Attributes
Date and Time Attributes and Time Changes

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.

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

PLATINUM AutoSys User Guide for UNIX

4-31

 Job Attributes
Date and Time Attributes and Time Changes

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.
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.

4-32

PLATINUM AutoSys User Guide for UNIX

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 on page 5-10.
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-4
Box Job Attributes and Terminators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Attributes in a Box Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Attributes in a Job Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Time Conditions in a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Force Starting Jobs in a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
How Job Status Changes Affect Box Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
Advanced Conditions in Box Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Default Box Success and Box Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Explicit Box Success and Box Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15

PLATINUM AutoSys User Guide for UNIX

5-1

 Box Job Logic

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

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

5-2

PLATINUM AutoSys User Guide for UNIX

Box Job Logic

Basic Box Concepts

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.

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.

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 on
page 5-13.

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 on
page 5-13.

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 on page 5-6.

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

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

PLATINUM AutoSys User Guide for UNIX

5-3

 Box Job Logic

Basic Box Concepts

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.

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.

5-4

PLATINUM AutoSys User Guide for UNIX

Box Job Logic

Basic Box Concepts

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 on page 5-9.)
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.

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

simple_box

job_b
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.

PLATINUM AutoSys User Guide for UNIX

5-5

 Box Job Logic

Box Job Attributes and Terminators

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.

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.

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 on page 5-15.

5-6

PLATINUM AutoSys User Guide for UNIX

Box Job Logic

Box Job Attributes and Terminators

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 on page 5-16.
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 on page 5-17.

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 conditionthe success of job_a.

PLATINUM AutoSys User Guide for UNIX

5-7

 Box Job Logic

Box Job Attributes and Terminators

bx_stat
3:00 a.m. Daily

job_a
run until succeed
job_report
success(job_a)
Report success of job_a

Figure 5-2 Box Job with Time Conditions

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.

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.

5-8

PLATINUM AutoSys User Guide for UNIX

Box Job Logic

Box Job Attributes and Terminators

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

Watch for file

run_stats
success(job_Fwatch)
box_terminator: y
Run Statistics

report_stats
success(run_stats)

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.
The next section discusses how job status changes influence the status of
the container box.

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.

PLATINUM AutoSys User Guide for UNIX

5-9

 Box Job Logic

Examples

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.
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 userassigned). 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.

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-10

PLATINUM AutoSys User Guide for UNIX

Box Job Logic

Examples

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.

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.

PLATINUM AutoSys User Guide for UNIX

5-11

 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

5-12

PLATINUM AutoSys User Guide for UNIX

Box Job Logic

Examples

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.

PLATINUM AutoSys User Guide for UNIX

5-13

 Box Job Logic

Examples

Job Stream

Job Status

update_accounts

FAILURE

SUCCESS

run_stats
FAILURE

success(update_accounts)

ACTIVATED

SUCCESS

report_stats
success(run_stats)

FAILURE ACTIVATED ACTIVATED

SUCCESS

Box SUCCESS

Box FAILURE Box Still RUNNING

Figure 5-5 Box Success and Failure

5-14

PLATINUM AutoSys User Guide for UNIX

Box Job Logic

Examples

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

Update Files

run_stats
success(update_accounts)

report_stats
success(run_stats)

Run Statistics

Report Statistics

Job Stream

Job Status

do_statistics
FAILURE

update_accounts

SUCCESS

run_stats

FAILURE INACTIVE

SUCCESS

report_stats
FAILURE INACTIVE INACTIVE
SUCCESS

Box

SUCCESS

FAILURE FAILURE FAILURE

Figure 5-6 Success and Failure Conditions

PLATINUM AutoSys User Guide for UNIX

5-15

 Box Job Logic

Examples

Using the Box Terminator Attribute

Job Definitions
daily_accounts
3:00 a.m. Daily
daily_receipts
box_terminator: y

daily_payables
box_terminator: y

Process Receipts

Process Payables

daily_balance
success(daily_reciepts)
AND success(daily_payables)
Calculate Balance

Job Stream
daily_accounts

daily_payables

daily_receipts

SUCCESS

SUCCESS

FAILURE

Box

TERMINATED

FAILURE

SUCCESS

TERMINATED

daily_balance

Figure 5-7 Using box_terminator

5-16

PLATINUM AutoSys User Guide for UNIX

Box Job Logic

Examples

Using the Job Terminator Attribute

Job Definitions
daily_accounts
3:00 a.m. Daily
daily_receipts

daily_payables
job_terminator: y

Process Receipts

Process Payables

daily_balance
success(daily_reciepts)
AND success(daily_payables)
Calculate Balance

Job Stream
daily_accounts

daily_receipts

SUCCESS

Box

daily_payables

TERMINATE

SUCCESS

FAILURE

FAILURE

FAILURE

FAILURE

daily_balance

Figure 5-8 Using job_terminator

PLATINUM AutoSys User Guide for UNIX

5-17

 Box Job Logic

Examples

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

of Month
term_run_time: 90
Watch for File

2:00 a.m. First Day

of Month
success(job_Fwatch)
Re-index, Organize, Purge

3:00 a.m. Daily

success(job_monthly)
Generate Report

Job Stream
Date/Time
Conditions Met

Start

Job Dependency
Condition Met

Date/Time
Conditions Met

File from
Mainframe

job_Fwatch

SUCCESS

Start

job_monthly
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

5-18

PLATINUM AutoSys User Guide for UNIX

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

of Month
term_run_time: 90

2:00 a.m. First Day

of Month
success(job_Fwatch)
Re-index, Organize, Purge

3:00 a.m. Daily

success(job_monthly)

Watch for File

Generate Report

Job Stream
Date/Time

NOT RUN

job_Fwatch

NOT RUN
Date/Time
NOT Conditions Met

job_monthly

NOT Conditions Met

File from
Mainframe

Job Dependency
Condition NOT Met
Event Status in
AutoSys Database =
SUCCESS (from Jan 1)

Job Dependency
Condition Met
Start

job_daily

Date/Time
Conditions Met
SUCCESS

Figure 5-10 Jobs Run the Second of Month

PLATINUM AutoSys User Guide for UNIX

5-19

 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

of Month
term_run_time: 90

2:00 a.m. First Day

of Month
success(job_Fwatch)
Re-index, Organize, Purge

3:00 a.m. Daily

success(job_monthly)

Watch for File

Generate Report

Job Stream
Date/Time
Conditions Met

Start

File from
Mainframe

job_Fwatch

term_run_time: 90
TERMINATED

Job Dependency
Condition NOT Met
NOT RUN

Event Status in
AutoSys Database =
SUCCESS (from Jan 1)

job_monthly

Date/Time
Conditions Met

Job Dependency
Condition Met
Start

job_daily

Date/Time
Conditions Met

Undesirable Result

SUCCESS

Figure 5-11 Incorrect Job Stream Logic

5-20

PLATINUM AutoSys User Guide for UNIX

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

of Month
term_run_time: 90

2:00 a.m. First Day

of Month
success(job_Fwatch)

3:00 a.m. Daily

success(job_monthly)

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
Start

Date/Time
Conditions Met

job_Fwatch

File from

term_run_time: 90
TERMINATED

Mainframe

Condition NOT Met

Job Dependency
Date/Time
Conditions Met

NOT RUN

job_monthly

Event Status in
AutoSys Database =
INACTIVE

Job Dependency
Condition NOT Met
NOT RUN

job_daily

Date/Time
Conditions Met

Desirable Result
Figure 5-12 Changing Job Status

PLATINUM AutoSys User Guide for UNIX

5-21

 Box Job Logic

Examples

Scenario III 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_monthly

job_Fwatch
1:00 a.m.First Day
of Month
box_terminator: y

success(job_Fwatch)
job_terminator: y

Watch for File

Re-index, Organize, Purge

job_daily
3:00 a.m. Daily
success(box_monthly)
Generate Report

box_monthly

Date/Time
Conditions Met

Start
job_Fwatch

File from
Mainframe

SUCCESS
FAILURE
job_monthly

SUCCESS

TERMINATED

Job Dependency
Condition NOT Met
job_daily
NOT RUN
Date/Time
Conditions Met

Job Dependency
Condition Met

Start

job_daily

Date/Time
Conditions Met
SUCCESS

Figure 5-13 Changing Status using Box Jobs

5-22

PLATINUM AutoSys User Guide for UNIX

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-8
Creating a Simple Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Creating a File Watcher Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Creating a Dependent Command Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
Creating a Box Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18
Changing a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20

PLATINUM AutoSys User Guide for UNIX

6-1

 Defining AutoSys Jobs Using the GUI

Setting Time Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22

Additional Time Setting Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-24
Deleting a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25
Deleting a Box Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-26
Specifying One-Time Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
Setting Job Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-29
Customizing the Job Definition GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
Database Connection Time-out Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-31
Job Definition Title bar Text and Icon Text . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-31

6-2

PLATINUM AutoSys User Guide for UNIX

Defining AutoSys Jobs Using the GUI

Starting the GUI

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

GUI Control Panel

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

Ops ConsoleDisplays the Job Activity Console, used to monitor

AutoSys jobs and alarms.

Job DefinitionDisplays the Job Definition dialog, used to define

AutoSys jobs.

CalendarsDisplays the Calendar Definition window, used to define

AutoSys run and exclude calendars.

Monitor/BrowserDisplays the Monitor/Browser dialog, used to

define and run monitors and reports (or browsers).

HostScapeDisplays the AutoSys/Xpert HostScape window, used for

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

PLATINUM AutoSys User Guide for UNIX

6-3

 Defining AutoSys Jobs Using the GUI

Job Definition Dialogs

JobScapeDisplays the AutoSys/Xpert JobScape window, used for

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

TimeScapeDisplays the AutoSys/Xpert TimeScape window, used for

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

ExitExits the GUI.

Note The three AutoSys/Xpert buttons are disabled if you have not

purchased the AutoSys/Xpert product.

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

PLATINUM AutoSys User Guide for UNIX

Defining AutoSys Jobs Using the GUI

Job Definition Dialogs

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

PLATINUM 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:

ClearClears the dialog without affecting the database. Use this

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

DeleteDeletes the currently displayed job from the database.

SaveStores 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 FeaturesDisplays the Job Definition Advanced Features dialog,

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

ExitCloses 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

PLATINUM AutoSys User Guide for UNIX

Defining AutoSys Jobs Using the GUI

Job Definition Dialogs

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:

CalendarsAccesses the Autosys Graphical Calendar facility.

DismissCloses 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.

PLATINUM 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.

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.

6-8

PLATINUM AutoSys User Guide for UNIX

Defining AutoSys Jobs Using the GUI

Job Definition Dialogs

Figure 6-4 Job Definition Advanced Features Dialog

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.

PLATINUM AutoSys User Guide for UNIX

6-9

 Defining AutoSys Jobs Using the GUI

Creating a Simple Command Job

These are the control buttons in this dialog:

DismissCloses the dialog; any entries made in the dialog are

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

Save&DismissCloses the dialog and saves the job, including the

advanced features information to the database.

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, well 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 jobs 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.
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.

6-10

PLATINUM AutoSys User Guide for UNIX

Defining AutoSys Jobs Using the GUI

Creating a Simple Command Job

Note The Owner field for the job defaults to the currently logged on

usernot the user shown in these examples.

Figure 6-5 Job Definition Dialog for Command Job test_run

PLATINUM AutoSys User Guide for UNIX

6-11

 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.

Creating a File Watcher Job

Next, you will create a File Watcher Job. This job will watch for an endof-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.

6-12

PLATINUM AutoSys User Guide for UNIX

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:

PLATINUM AutoSys User Guide for UNIX

6-13

 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 files existence every 60 seconds, and it will
check if the file has grown between checksif 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.

The filled-in dialog should look like the one shown in Figure 6-7.

6-14

PLATINUM AutoSys User Guide for UNIX

Defining AutoSys Jobs Using the GUI

Creating a Dependent Command Job

Figure 6-7 Job Definition Advanced Features Dialog - File Watcher Job

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.

PLATINUM AutoSys User Guide for UNIX

6-15

 Defining AutoSys Jobs Using the GUI

Creating a Dependent Command Job

Using the Job Definition dialog, follow these steps:

1 In the Job Name field, enter the jobs 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 owners home directory.
The filled-in Job Definition dialog should look like the one shown in
Figure 6-8.
Note The jobs 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.

6-16

PLATINUM AutoSys User Guide for UNIX

Defining AutoSys Jobs Using the GUI

Creating a Dependent Command Job

Figure 6-8 Job Definition DialogDependent Command Job

To save the job

 Single-click on the Save button at the top of the Job Definition dialog.

PLATINUM AutoSys User Guide for UNIX

6-17

 Defining AutoSys Jobs Using the GUI

Creating a Box Job

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.

6-18

PLATINUM AutoSys User Guide for UNIX

Defining AutoSys Jobs Using the GUI

Creating a Box Job

Figure 6-9 Job Definition DialogBox Job

PLATINUM AutoSys User Guide for UNIX

6-19

 Defining AutoSys Jobs Using the GUI

Changing a Job

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.

6-20

PLATINUM AutoSys User Guide for UNIX

Defining AutoSys Jobs Using the GUI

Changing a Job

Figure 6-10 Selection List Box

4 Double-click on the desired jobs 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.

PLATINUM AutoSys User Guide for UNIX

6-21

 Defining AutoSys Jobs Using the GUI

Setting Time Dependencies

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.

6-22

PLATINUM AutoSys User Guide for UNIX

Defining AutoSys Jobs Using the GUI

Setting Time Dependencies

Figure 6-11 Date/Time Options DialogTime 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.

PLATINUM AutoSys User Guide for UNIX

6-23

 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.

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.

6-24

PLATINUM AutoSys User Guide for UNIX

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, singleclick the Calendars button, which displays the Graphical Calendar
Facility.

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 jobs 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.

PLATINUM AutoSys User Guide for UNIX

6-25

 Defining AutoSys Jobs Using the GUI

Specifying One-Time Job Overrides

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.

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 reissue 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.

6-26

PLATINUM AutoSys User Guide for UNIX

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 OverRides?

Starting Parameters

Starting Condition

Is Start Date/Time
Dependent?

Execute on Machine

Command to Execute

File To Watch for

Command & File

Watch Information

PLATINUM AutoSys User Guide for UNIX

6-27

 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
Features

Alarms

Minimum Run Time

Maximum Run Time

Time Interval (secs) to

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

Number of Times to
Restart this Job after a
FAILURE

Delete Job hours after

Completion

AutoHold On?

File Watching
Criteria

Misc. Features

6-28

PLATINUM 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

Date/Time
Options

DATE

(all date settings)

Run on Days in
Calendar

Do NOT Run on Days

in Calendar (Exclude)

(all time settings)

Run Window

TIME

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.

PLATINUM AutoSys User Guide for UNIX

6-29

 Defining AutoSys Jobs Using the GUI

Customizing the Job Definition GUI

3 Single-click on the Delete button. This action deletes the job

overrides.

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.

6-30

PLATINUM AutoSys User Guide for UNIX

Defining AutoSys Jobs Using the GUI

Customizing the Job Definition GUI

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.

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.

PLATINUM AutoSys User Guide for UNIX

6-31

 Defining AutoSys Jobs Using the GUI

Customizing the Job Definition GUI

6-32

PLATINUM 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.
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-10
Setting Time Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
Additional Time Setting Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12

PLATINUM 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

PLATINUM AutoSys User Guide for UNIX

Defining Jobs Using JIL

Job Information Language (JIL)

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.

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.

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

PLATINUM AutoSys User Guide for UNIX

7-3

 Defining Jobs Using JIL

Job Information Language (JIL)

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: upperand 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 statements 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

PLATINUM 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 */

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.

PLATINUM AutoSys User Guide for UNIX

7-5

 Defining Jobs Using JIL

Job Information Language (JIL)

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.

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

PLATINUM 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.

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.

PLATINUM AutoSys User Guide for UNIX

7-7

 Defining Jobs Using JIL

Creating a File Watcher Job

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
wont 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

PLATINUM AutoSys User Guide for UNIX

Defining Jobs Using JIL

Creating a Dependent Command Job

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
owners home directory.

Note The jobs 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.

PLATINUM 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.

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.

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.

7-10

PLATINUM AutoSys User Guide for UNIX

Defining Jobs Using JIL

Changing a Job

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, youll have to respecify any of the attributes that need to remain the same. So, in the
example below, youll 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 boxs starting parameters.

PLATINUM AutoSys User Guide for UNIX

7-11

 Defining Jobs Using JIL

Setting Time Dependencies

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

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

PLATINUM 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

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).

PLATINUM AutoSys User Guide for UNIX

7-13

 Defining Jobs Using JIL

Specifying One-Time Job Overrides

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.

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

PLATINUM 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).

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. For example,

PLATINUM AutoSys User Guide for UNIX

7-15

 Defining Jobs Using JIL

Example JIL Script

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.

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:

7-16

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.

PLATINUM 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.

PLATINUM AutoSys User Guide for UNIX

7-17

 Defining Jobs Using JIL

Example JIL Script

7-18

PLATINUM AutoSys User Guide for UNIX

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 Todays Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15
Calendar Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16

PLATINUM 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-30
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

PLATINUM AutoSys User Guide for UNIX

The Graphical Calendar Facility

Introduction

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.

PLATINUM AutoSys User Guide for UNIX

8-3

 The Graphical Calendar Facility

Scheduling Jobs with Calendars

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

PLATINUM 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.

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.

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
dialog

This dialog is used to select a pre-defined

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.

PLATINUM AutoSys User Guide for UNIX

8-5

 The Graphical Calendar Facility

Calendar Definition Window

Term Calendar
Viewer window

This window is used to preview a pre-existing

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
Name dialog

This dialog is used to specify a calendar text file

(ASCII format) to import from or export to.

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

PLATINUM 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.

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.

PLATINUM 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:

8-8

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.

PLATINUM AutoSys User Guide for UNIX

The Graphical Calendar Facility

Calendar Definition Window

Tools Menu
The Tools menu contains the following options:
Term Calendar
Viewer

Displays the Term Calendar Viewer window, which

allows you to preview various calendars prior to
applying their dates to the calendar currently being
edited.

Job Definition
Reference List

Displays a list of all the jobs which reference the

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.

PLATINUM 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
Command

8-10

Displays a dialog box prompting you to specify the

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.

PLATINUM AutoSys User Guide for UNIX

The Graphical Calendar Facility

Calendar Definition Window

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.

PLATINUM 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.

Navigation Controls

The Navigation Controls region of the window contains controls which

do the following:

8-12

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.

PLATINUM 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.

PLATINUM 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

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

PLATINUM 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

Dates Prior to Todays 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.

PLATINUM AutoSys User Guide for UNIX

8-15

 The Graphical Calendar Facility

Calendar Selection Dialog

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

PLATINUM 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.

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

PLATINUM 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.

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

PLATINUM 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 todays 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.

PLATINUM 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 nonrepeating periods, such as Every/Mondaythis
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.

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

PLATINUM 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.

PLATINUM 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.

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

PLATINUM 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.

PLATINUM 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.

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

PLATINUM AutoSys User Guide for UNIX

The Graphical Calendar Facility

Term Calendar Viewer

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

PLATINUM 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 onlythey cannot be edited.
You can only edit dates using the Calendar
Definition window.
Navigation
Controls

At the right of the window.

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
databaseall 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

PLATINUM AutoSys User Guide for UNIX

The Graphical Calendar Facility

Combining Calendars

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.

PLATINUM 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.

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.

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.

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

PLATINUM 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.
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:

PLATINUM AutoSys User Guide for UNIX

8-29

 The Graphical Calendar Facility

Customizing the Calendar Facility

/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.

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.

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:

8-30

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.

PLATINUM AutoSys User Guide for UNIX

The Graphical Calendar Facility

Customizing the Calendar Facility

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.

PLATINUM AutoSys User Guide for UNIX

8-31

 The Graphical Calendar Facility

Customizing the Calendar Facility

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

PLATINUM AutoSys User Guide for UNIX

The Graphical Calendar Facility

Customizing the Calendar Facility

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
bluethe 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:

PLATINUM 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:

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:

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

PLATINUM AutoSys User Guide for UNIX

The Graphical Calendar Facility

Customizing the Calendar Facility

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:

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.

PLATINUM AutoSys User Guide for UNIX

8-35

 The Graphical Calendar Facility

Customizing the Calendar Facility

8-36

PLATINUM AutoSys User Guide for UNIX

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-3
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

PLATINUM 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-14
Testing the Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-17
ServerVision Monitoring and Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18
Queuing Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18
Queuing and Simple Load Limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-19
Queuing with Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-20
SubsetsIndividual Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-22
Multiple Machine Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-24
User-Defined Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-25

9-2

PLATINUM AutoSys User Guide for UNIX

Load Balancing and Queuing Jobs

Real Machines

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.

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.

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

PLATINUM AutoSys User Guide for UNIX

9-3

 Load Balancing and Queuing Jobs

Defining Machines to AutoSys

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.

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.

9-4

PLATINUM AutoSys User Guide for UNIX

Load Balancing and Queuing Jobs

Defining Machines to AutoSys

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.

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 machines 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 machines
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
machines resources.
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.

PLATINUM AutoSys User Guide for UNIX

9-5

 Load Balancing and Queuing Jobs

Defining Machines to AutoSys

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 attributes 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.

Using max_load and factor

The max_load attribute is primarily used to limit the loading of a

machine. As long as a jobs load will not cause a machines 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

PLATINUM AutoSys User Guide for UNIX

Load Balancing and Queuing Jobs

Defining Machines to AutoSys

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

PLATINUM 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.

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
factor: 1.0

jaguar
100
1.0

max_load
factor

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

PLATINUM AutoSys User Guide for UNIX

Load Balancing and Queuing Jobs

Defining a Virtual Machine

Deleting Real Machines

The following JIL statement deletes the real machine definition for the
machine named jaguar:
delete_machine: jaguar

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
type: v
machine: ferrari
machine: lambo

modena
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.)

PLATINUM 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
max_load: 10
machine: lotus
max_load: 9

fiat

lotus
10

Figure 9-3 Virtual Machine Comprised of Subsets of Real Machines

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

PLATINUM 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 dont have to specify any of the
component real machines. The real machines are still definedonly 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.

Load Balancing

By specifying a virtual machine or a list of real machines in a jobs

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 machines 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 jobs machine
attribute, as shown below:
machine: ferrari, lambo

PLATINUM 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 machines 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

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

9-12

PLATINUM AutoSys User Guide for UNIX

Load Balancing and Queuing Jobs

Load Balancing

not been explicitly defined to AutoSys are specified in a jobs 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
1.0

alfa_romeo
0.8

lambo
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

PLATINUM AutoSys User Guide for UNIX

9-13

 Load Balancing and Queuing Jobs

Load Balancing Using ServerVision

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.

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.

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).

9-14

PLATINUM AutoSys User Guide for UNIX

Load Balancing and Queuing Jobs

Load Balancing Using ServerVision

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 PLATINUM 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.

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.

PLATINUM AutoSys User Guide for UNIX

9-15

 Load Balancing and Queuing Jobs

Load Balancing Using ServerVision

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.
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.

9-16

PLATINUM AutoSys User Guide for UNIX

Load Balancing and Queuing Jobs

Load Balancing Using ServerVision

[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 TypeIndicates the Scan Type as defined by ServerVision.
Scan ObjectIndicates the Scan Object that is associated with the
Scan Type as defined by ServerVision.
maximum or minimumIndicates the value that is desired, either
the maximum number or the minimum number.
WeightIndicates the items 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
PLATINUM ServerVision for UNIX Reference Guide.

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.

PLATINUM AutoSys User Guide for UNIX

9-17

 Load Balancing and Queuing Jobs

ServerVision Monitoring and Reporting

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.

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 jobs 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.

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.
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-18

PLATINUM AutoSys User Guide for UNIX

Load Balancing and Queuing Jobs

Queuing Jobs

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 jobs 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.
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.

PLATINUM AutoSys User Guide for UNIX

9-19

 Load Balancing and Queuing Jobs

Queuing Jobs

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.

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.
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 jobs 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.

9-20

PLATINUM AutoSys User Guide for UNIX

Load Balancing and Queuing Jobs

Queuing Jobs

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.
QUE_WAIT

EXECUTE

JobA

JobB

50

50

JobD

JobC

30

30

80
ferrari

max_load

Figure 9-5 Schematic of Queuing with Priority

PLATINUM 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.

SubsetsIndividual 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

9-22

PLATINUM AutoSys User Guide for UNIX

Load Balancing and Queuing Jobs

Queuing Jobs

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

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

PLATINUM AutoSys User Guide for UNIX

9-23

 Load Balancing and Queuing Jobs

Queuing Jobs

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.

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.
p
ferrari

15

80

lambo

15

120

Figure 9-7 Virtual Machine Comprised of Subsets of Real Machines

9-24

PLATINUM AutoSys User Guide for UNIX

Load Balancing and Queuing Jobs

User-Defined Load Balancing

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

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.

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 jobs 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.

PLATINUM AutoSys User Guide for UNIX

9-25

 Load Balancing and Queuing Jobs

User-Defined Load Balancing

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

PLATINUM 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-14
Resizing Regions of the Job Activity Console . . . . . . . . . . . . . . . . . . . . . . . . 10-23

PLATINUM AutoSys User Guide for UNIX

10-1

 The Operator Console

Job Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-23

Specifying a Job by Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-24
Specifying Jobs by Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-26
Specifying Jobs by Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-27
Sorting the Specified Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-28
Setting the Job Selection Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-29
Changing the Console Clock Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-29
Alarm Manager Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-29
Alarm Manager Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-31
Alarm List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-31
Currently Selected Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-32
Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-33
Alarm Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-35
Select by Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-36
Select by State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-36
Select by Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-37
Customizing the Operator Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-37
Refresh Time Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-38
Alarm Poll Time Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-38
Changing Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-39
Freeze Frame at Start Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-39
Font Selection Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-40
Label Font Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-40
List Font Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-40
Object Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-41
Job List Column Widths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-44
Operator Console Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-45
Default Report Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-45
Alarm List Column Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-45
Operator Console Title bar Text and Icon Text . . . . . . . . . . . . . . . . . . . . . . .10-46

10-2

PLATINUM AutoSys User Guide for UNIX

The Operator Console

User-Configurable Action Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-46

Console Clock Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-49

PLATINUM AutoSys User Guide for UNIX

10-3

 The Operator Console

Introduction

Introduction

10

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.

Alarm Manager

10

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 alarms state to either acknowledged or closed. (If an

alarms 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

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Introduction

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 the Accessing InfoReports from the Operator Console section on
page 10-47.) 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.

PLATINUM AutoSys User Guide for UNIX

10-5

 The Operator Console

Introduction

In the Connection field, enter the Sybase database name (for Sybase)
or the TNS name (for Oracle).

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 the InfoReports documentation on the PLATINUM
documentation CD for information on using InfoReports.

10-6

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Operator Console Screens

Operator Console Screens

10

The Operator Console consists of the following elements:

Job Activity
Console

The primary interface to the Operator Console. This

console lets you monitor any AutoSys jobs.

Job Selection
dialog

Used to specify which jobs you want to view.

Alarm Manager
dialog

Allows you to browse any alarms which have

occurred, and to acknowledge (and log a response
to) those alarms.

Alarm Selection
dialog

Used to specify which alarms you want to view.

Starting the Operator Console

10

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.

PLATINUM AutoSys User Guide for UNIX

10-7

 The Operator Console

Job Activity Console

Job Activity Console

10

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

PLATINUM 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 ListDisplays a list of all jobs stored in the database, subject to

the job selection criteria currently in effect.

Currently Selected JobDisplays more detailed information about

the currently selected job.

Control AreaThe 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.

Menu Bar

10

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 areait 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-23.

PLATINUM 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-29.

Job List

10

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

PLATINUM 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.

Currently Selected Job

10

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
Selected Job

This field displays the name of the currently selected

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-29) or by changing the setting
in the resource file (see Console Clock Perspective on
page 10-49).

PLATINUM AutoSys User Guide for UNIX

10-11

 The Operator Console

Job Activity Console

10-12

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.

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Job Activity Console

Starting Conditions

10

The Starting Conditions area displays the jobs entire starting condition,
as specified in its job definition, as well as the atomic conditionsthe
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 jobs 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.

PLATINUM AutoSys User Guide for UNIX

10-13

 The Operator Console

Job Activity Console

Reports

10

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.

Control Area

10

The bottom region of the Job Activity Console is the Control area.

10-14

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Job Activity Console

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.
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-46.

PLATINUM AutoSys User Guide for UNIX

10-15

 The Operator Console

Job Activity Console

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.

Figure 10-2 Send Event Dialog

10-16

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Job Activity Console

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.
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.

PLATINUM AutoSys User Guide for UNIX

10-17

 The Operator Console

Job Activity Console

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.

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).

10-18

PLATINUM AutoSys User Guide for UNIX

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.

PLATINUM AutoSys User Guide for UNIX

10-19

 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 jobs
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

10-20

PLATINUM AutoSys User Guide for UNIX

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 Reports 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 modethis is the installation default. For more
information about customizing the Operator Console, see Customizing
the Operator Console on page 10-37.
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-45.

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.

PLATINUM AutoSys User Guide for UNIX

10-21

 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 jobs 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.

10-22

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Job Selection Dialog

Resizing Regions of the Job Activity Console

10

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
regions 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.)

Job Selection Dialog

10

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.

PLATINUM AutoSys User Guide for UNIX

10-23

 The Operator Console

Job Selection Dialog

Figure 10-5 Job Selection Dialog

Specifying a Job by Name

10

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.

10-24

PLATINUM AutoSys User Guide for UNIX

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.

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.

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.

PLATINUM AutoSys User Guide for UNIX

10-25

 The Operator Console

Job Selection Dialog

Figure 10-6 Job ListBox Job with Nesting

Specifying Jobs by Status

10

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.

10-26

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Job Selection Dialog

Specifying Jobs by Machine

10

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.

PLATINUM AutoSys User Guide for UNIX

10-27

 The Operator Console

Job Selection Dialog

Sorting the Specified Jobs

10

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:

10-28

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.

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Changing the Console Clock Perspective

Setting the Job Selection Criteria

10

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.

Changing the Console Clock Perspective

10

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.

Alarm Manager Dialog

10

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.

PLATINUM AutoSys User Guide for UNIX

10-29

 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:

10-30

Alarm List

At the top of the dialog.

Currently Selected Alarm

In the middle of the dialog.

Control

At the bottom of the dialog.

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Alarm Manager Dialog

Alarm Manager Menu Bar

10

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-35).
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.

Alarm List

10

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 alarms current state.

Any comment associated with the alarm at the time it was generated.

PLATINUM AutoSys User Guide for UNIX

10-31

 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 currentlyselected 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-45.

Currently Selected Alarm

10

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.

10-32

PLATINUM AutoSys User Guide for UNIX

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.

Control

10

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-21) in the process.

PLATINUM AutoSys User Guide for UNIX

10-33

 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
buttons 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.

10-34

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Alarm Selection Dialog

Alarm Selection Dialog

10

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
alarms 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)

PLATINUM AutoSys User Guide for UNIX

10-35

 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

Select by Type

10

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 alarms 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.

Select by State

10

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.

10-36

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Customizing the Operator Console

Select by Time

10

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.

Customizing the Operator Console

10

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.

PLATINUM AutoSys User Guide for UNIX

10-37

 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.

Refresh Time Interval

10

The following resource controls the time interval after which the
Operator Console will be refreshed (specified in milliseconds).
*refreshTime:

Alarm Poll Time Interval

10

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:

10-38

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Customizing the Operator Console

Changing Fonts

10

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.

Freeze Frame at Start Up

10

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

PLATINUM AutoSys User Guide for UNIX

10-39

 The Operator Console

Customizing the Operator Console

Font Selection Resources

10

The following resource specifications control font selection. They are

completely independent of any other font settings:
*.fontList:
*XmTextField.fontList:
*XmText.fontList:

Label Font Resources

10

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 shouldnt be bold.
*jobListForm*jobListLabel.fontList:
*dependHeadLabel*fontList:
*atomicsForm*atomicsLabel.fontList:
*alarmListForm*alarmListLabel*fontList:

List Font Resources

10

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 shouldnt be bold (typically
called medium).
*jobListForm*fontList:
*dependList*fontList:
*atomicsForm*fontList:
*alarmListForm*fontList:

10-40

PLATINUM AutoSys User Guide for UNIX

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:

Object Color

10

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

PLATINUM AutoSys User Guide for UNIX

10-41

 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:

10-42

PLATINUM AutoSys User Guide for UNIX

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:

PLATINUM AutoSys User Guide for UNIX

10-43

 The Operator Console

Customizing the Operator Console

Job List Column Widths

10

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
Consolethe 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:

10-44

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Customizing the Operator Console

Operator Console Size

10

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:

Default Report Type

10

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:

Alarm List Column Width

10

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:

PLATINUM AutoSys User Guide for UNIX

10-45

 The Operator Console

Customizing the Operator Console

Operator Console Title bar Text and Icon Text

10

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.

User-Configurable Action Buttons

10

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.

10-46

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Customizing the Operator Console

Button labels can be up to 20 characters, including spaces.

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.

PLATINUM AutoSys User Guide for UNIX

10-47

 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 instances
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

10-48

PLATINUM AutoSys User Guide for UNIX

The Operator Console

Customizing the Operator Console

3 Provide the information requested to configure an InfoReports

printer.
For details on this script, see the PLATINUM InfoReports Installation and
Configuration Guide on the PLATINUM documentation CD.

Console Clock Perspective

10

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.

PLATINUM AutoSys User Guide for UNIX

10-49

 The Operator Console

Customizing the Operator Console

10-50

PLATINUM 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 AttributesGeneral . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Common Essential AttributesEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Essential Report Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10

PLATINUM AutoSys User Guide for UNIX

11-1

 Monitoring and Reporting Jobs

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

11-2

PLATINUM AutoSys User Guide for UNIX

Monitoring and Reporting Jobs

About Monitors and Browsers

About Monitors and Browsers

11

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 systems state in realtime. If the Event Processor is down, monitors will not provide any
information. On the other hand, reports provide a picture of the
systems state from a historical view, not in real-time.

PLATINUM AutoSys User Guide for UNIX

11-3

 Monitoring and Reporting Jobs

Defining Monitors and Reports

Monitors

11

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.

Reports

11

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.

Defining Monitors and Reports

11

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

PLATINUM 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.

Using the GUI

11

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.

Using JIL

11

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.

PLATINUM AutoSys User Guide for UNIX

11-5

 Monitoring and Reporting Jobs

Defining Monitors and Reports

Chapter Organization

11

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

PLATINUM AutoSys User Guide for UNIX

Monitoring and Reporting Jobs

Essential Monitor/Report Attributes

Essential Monitor/Report Attributes

11

Common Essential AttributesGeneral

11

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.

Common Essential AttributesEvents

11

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.

PLATINUM 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

PLATINUM 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 jobs 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.

PLATINUM AutoSys User Guide for UNIX

11-9

 Monitoring and Reporting Jobs

Essential Monitor/Report Attributes

Essential Report Attributes

11

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

PLATINUM AutoSys User Guide for UNIX

Monitoring and Reporting Jobs

Optional Monitor/Report Attributes

Optional Monitor/Report Attributes

11

Optional Monitor Attributes

11

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.

PLATINUM 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.

Optional Report Attributes

11

There are no optional report attributes.

Defining Monitors and Reports using the GUI

11

This section describes the general use of the GUI Monitor/Browser

dialog, which is used for defining monitors and reports.

The Monitor/Browser Dialog

11

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

PLATINUM AutoSys User Guide for UNIX

Monitoring and Reporting Jobs

Defining Monitors and Reports using the GUI

Figure 11-1 Monitor/Browser Dialog

PLATINUM 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 dialogs 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

PLATINUM AutoSys User Guide for UNIX

Monitoring and Reporting Jobs

Defining Monitors and Reports using the GUI

Defining an Example Monitor and Report

11

In this section, youll 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 monitors 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.

PLATINUM 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

PLATINUM 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 reports 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.

PLATINUM 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

PLATINUM AutoSys User Guide for UNIX

Monitoring and Reporting Jobs

Defining Monitors and Reports using JIL

Defining Monitors and Reports using JIL

11

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 reports 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.

PLATINUM 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

PLATINUM 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.

Running a Monitor

11

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

PLATINUM AutoSys User Guide for UNIX

11-21

 Monitoring and Reporting Jobs

Customizing the Monitor/Browser

Customizing the Monitor/Browser

11

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.

Database Connection Time-out Interval

11

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

PLATINUM 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.

Monitor/Browser Title bar Text and Icon Text

11

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.

PLATINUM AutoSys User Guide for UNIX

11-23

 Monitoring and Reporting Jobs

Customizing the Monitor/Browser

11-24

PLATINUM AutoSys User Guide for UNIX

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-15
AutoSys Database Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-16
Event Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16
Database Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18
General Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-19
Daily Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20
DBMaint Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20

PLATINUM AutoSys User Guide for UNIX

12-1

 Maintaining AutoSys

Event Server Rollover Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-22

Event Server Crash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-23
Synchronizing the Event Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-23
Improving Database Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-24
Improving Sybase Database Performance . . . . . . . . . . . . . . . . . . . . . . . . . . .12-24
Improving Oracle Database Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-25
Maintaining Bundled Sybase SQL Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-27
Sybase Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-27
Sybase Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-28
Default Sybase Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-28
Starting Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-30
Stopping Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-31
Accessing Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-32
Identifying Processes Connected to the Database . . . . . . . . . . . . . . . . . . . . .12-33
Displaying the Database Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-34
Bundled Sybase Backup and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-34

12-2

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
Maintaining the Event Processor

Maintaining the Event Processor

12

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.

Starting the Event Processor

12

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.

PLATINUM 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 availablethe event_demon
continues to run in the background.

12-4

PLATINUM 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.

PLATINUM AutoSys User Guide for UNIX

12-5

 Maintaining AutoSys
Maintaining the Event Processor

Monitoring the Event Processor

12

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

PLATINUM 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.

Stopping the Event Processor

12

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

PLATINUM 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.

Shadow Event Processor Rollover

12

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

PLATINUM 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.

PLATINUM 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.

Running AutoSys in Test Mode

12

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

PLATINUM 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

PLATINUM AutoSys User Guide for UNIX

12-11

 Maintaining AutoSys
AutoSys Maintenance Commands

AutoSys Maintenance Commands

12

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.

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

12-12

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
Backing up AutoSys Definitions

machines 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.

Backing up AutoSys Definitions

12

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-15.
We also recommend that you keep a copy of your AutoSys license keys in
case you need to reinstall them.
To back up AutoSys definitions
1 To save your calendar definitions:
a Open a Calendar Definition window.
b Choose File  Export.

PLATINUM AutoSys User Guide for UNIX

12-13

 Maintaining AutoSys
Backing up AutoSys Definitions

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.
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

12-14

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
Restoring AutoSys Definitions

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.

Restoring AutoSys Definitions

12

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.

PLATINUM AutoSys User Guide for UNIX

12-15

 Maintaining AutoSys
AutoSys Database Overview

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.

AutoSys Database Overview

12

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.
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.

Event Server Overview

12

An Event Server can be associated with only one instance of AutoSys and
one running Event Processor.

12-16

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
AutoSys Database Overview

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.
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.

PLATINUM AutoSys User Guide for UNIX

12-17

 Maintaining AutoSys
AutoSys Database Overview

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.)

Database Architecture

12

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.
One Instance of AutoSys - $AUTOSERV

Event
Server 1

Define
Jobs

Read Config file to

determine which
database(s) to use.

OS FILE:
config.$AUTOSERV
Event
Server 2

Event
Processor
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).

12-18

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
General Database Maintenance

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.
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).

General Database Maintenance

12

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.

PLATINUM AutoSys User Guide for UNIX

12-19

 Maintaining AutoSys
General Database Maintenance

Daily Database Maintenance

12

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.

DBMaint Script

12

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.

12-20

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
General Database Maintenance

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

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-34.

PLATINUM AutoSys User Guide for UNIX

12-21

 Maintaining AutoSys
Event Server Rollover Recovery

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.

Event Server Rollover Recovery

12

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-22

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
Event Server Rollover Recovery

Event Server Crash

12

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.
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.

Synchronizing the Event Servers

12

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.

PLATINUM AutoSys User Guide for UNIX

12-23

 Maintaining AutoSys
Improving Database Performance

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.
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.

Improving Database Performance

12

This section contains information about improving your database

performance with AutoSys.

Improving Sybase Database Performance

12

These are ways to improve your Sybase database performance:

12-24

Increase the amount of memory that Sybase can use.

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
Improving Database Performance

WARNING Only the database administrator should increase Sybase

memory.

Upgrade your processor, memory, and/or hard disks.

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.

Improving Oracle Database Performance

12

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.

PLATINUM AutoSys User Guide for UNIX

12-25

 Maintaining AutoSys
Improving Database Performance

Tune the buffer cache. Make changes to the buffer cache by altering
the init.ora value of DB_BLOCK_BUFFERS.
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.

12-26

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

Maintaining Bundled Sybase SQL Servers

12

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.

Sybase Architecture

12

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 multithreaded, 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.

PLATINUM AutoSys User Guide for UNIX

12-27

 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.

Sybase Environment

12

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.

Default Sybase Users

12

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.

12-28

PLATINUM AutoSys User Guide for UNIX

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

sa

sysadmin

autosys

autosys

System Administrator
AutoSys User

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.

PLATINUM AutoSys User Guide for UNIX

12-29

 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-ofstatement 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.

Starting Sybase

12

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

12-30

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

Both of these commands start the server in the background, then

output start-up messages.
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.

Stopping Sybase

12

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.

PLATINUM AutoSys User Guide for UNIX

12-31

 Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

2 Stop the Sybase service by entering the following command (the

sa_password is initially installed as sysadmin):
xql -Usa -Psa_password -c "shutdown"

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-29.

Accessing Sybase

12

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.

12-32

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

Identifying Processes Connected to the Database

12

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

event_demon
jil

Michelle
Erik

13448
12272

running
sleeping
sleeping
sleeping
sleeping
sleeping
recv sleep
recv sleep

status 0, rows affected 8

PLATINUM AutoSys User Guide for UNIX

12-33

 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

Displaying the Database Date and Time

12

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();

Bundled Sybase Backup and Recovery

12

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.

12-34

PLATINUM AutoSys User Guide for UNIX

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-35. Then follow the steps in Dumping the Database on
page 12-39.

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;

PLATINUM AutoSys User Guide for UNIX

12-35

 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.

12-36

PLATINUM AutoSys User Guide for UNIX

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.

PLATINUM AutoSys User Guide for UNIX

12-37

 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

12-38

PLATINUM AutoSys User Guide for UNIX

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-35.

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

To dump a Sybase database

1 Enter the following xql commands:
xql -Usa -Psysadmin
xql>dump database database_name to dump_device;

PLATINUM AutoSys User Guide for UNIX

12-39

 Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

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;
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;

12-40

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

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;

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.

PLATINUM AutoSys User Guide for UNIX

12-41

 Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

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.
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.

12-42

PLATINUM AutoSys User Guide for UNIX

Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

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.

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.

PLATINUM AutoSys User Guide for UNIX

12-43

 Maintaining AutoSys
Maintaining Bundled Sybase SQL Servers

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.

12-44

PLATINUM AutoSys User Guide for UNIX

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-3
Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Configuration File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9
Database Time-out Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10
Cross-Instance Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11
Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11
Event Processor Cascading Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-12
Machines to Check for Running Event Processors . . . . . . . . . . . . . . . . . . . . 13-13
Third Machine for Event Processor Contention . . . . . . . . . . . . . . . . . . . . . . . 13-14
Event Processor Log Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15
Internal Database Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15

PLATINUM AutoSys User Guide for UNIX

13-1

 Configuring AutoSys

Event Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-16

Heartbeats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-17
Remote Agent Log Files Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-18
File Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-18
SNMP Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-21
HP OpenView IT/Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-27
Number of Restart Attempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-27
Calculating the Wait Time Between Restarts . . . . . . . . . . . . . . . . . . . . . . . . .13-28
Method of Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-29
KILLJOB Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-30
Port Number for Remote Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-31
Z/Team Job Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-31
Instance Wide Append Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-32
Enabling PLATINUM Event Management and Data Exchange . . . . . . . . . . .13-33
Inetd Job Starting Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-34
The auto.profile File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-35
Sample Default auto.profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-36
Remote Agent Database Connection Settings . . . . . . . . . . . . . . . . . . . . . . . .13-37
Modifying Remote Agent Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-38
Remote Agent Socket Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-38
Running Two AutoSys Versions of Remote Agents . . . . . . . . . . . . . . . . . . . .13-39
Configuring Remote Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-40
Configuring Event Processor Authentication . . . . . . . . . . . . . . . . . . . . . . . . . .13-41
Client-Side Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-42
Configuring ServerVision Monitoring and Reporting . . . . . . . . . . . . . . . . . . .13-43
Library Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-43
svload Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-43
ServerVision Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-44
ServerVision Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-44
Monitoring Job Resource Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-45
User-Defined Alarm Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-46

13-2

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
AutoSys Configuration File

AutoSys Configuration File

13

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 events uniqueness and

traceability across multiple instances.

PLATINUM AutoSys User Guide for UNIX

13-3

 Configuring AutoSys
Sample Configuration File

Sample Configuration File

13

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
#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.

13-4

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Sample Configuration File

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 # # # # #
#
# 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

PLATINUM AutoSys User Guide for UNIX

13-5

 Configuring AutoSys
Sample Configuration File

#
#
#
#
#
#

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 Processors internal Daily Database
# Maintenance Cycle # #
#
# Daily start-time
DBMaintTime=03:30
# Command to Run to perform Maintenance
#
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 OSs have problems with file locks in /tmp
# If so use some directory other than /tmp.
#

13-6

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Sample Configuration File

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
#
# 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.

PLATINUM AutoSys User Guide for UNIX

13-7

 Configuring AutoSys
Sample Configuration File

#
#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)
#

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

13-8

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

# Port number of auto_remote

AutoRemPort=5280
#
# Allow AutoSys jobs to be dispatched on Z/Team
# managed machines.
#

0 for no support for Z/Team machine.

1 to allow jobs on Z/Team machines.

ZTeamJobSupport=0
#
# Specify if standard error and standard output
# files should be appended to or overwritten.
# 0 overwrites the file.
# 1 appends the file.
AutoInstWideAppend=1
#
# Enable PLATINUM Event Management and Data Exchange
# 0 does not send events to PEMS and DEX.
# 1 send events to PEMS and DEX.
#
#AutoPems=1

The following sections describe these configuration parameters.

Configuration File Parameters

13

You can modify the parameters in the AutoSys configuration file to

control the behavior of AutoSys and optimize your system.

PLATINUM AutoSys User Guide for UNIX

13-9

 Configuring AutoSys
Configuration File Parameters

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

Database Time-out Period

13

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

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.

13-10

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

Note If you set this value to DBLibWaitTime=0, it means that no

time-out value is to be appliedthe connection is continuous.

Because it can cause the Event Processor to hang, this setting is not
recommended.

Cross-Instance Database Connections

13

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

Database Connections

13

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.

PLATINUM AutoSys User Guide for UNIX

13-11

 Configuring AutoSys
Configuration File Parameters

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.
Similarly, upon start-up, the Event Processor attempts to connect to an
Event Servers 5 times, and if unsuccessful, it will immediately rollover to
Single Server Mode, using the Event Server that is still functioning.

Event Processor Cascading Errors

13

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.

13-12

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

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

Machines to Check for Running Event Processors

13

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

PLATINUM AutoSys User Guide for UNIX

13-13

 Configuring AutoSys
Configuration File Parameters

Third Machine for Event Processor Contention

13

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.
The Third Machine must have a Remote Agent installation on it. In
addition, the Third Machines 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 are installed on, either 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-14

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

Event Processor Log Disk Space

13

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.
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

Internal Database Maintenance

13

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.

PLATINUM AutoSys User Guide for UNIX

13-15

 Configuring AutoSys
Configuration File Parameters

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.
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

Event Transfer

13

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.

13-16

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

EvtTransferWaitTime
To set the default behavior of 5 seconds for the time-out, the
configuration file contains the following line:
EvtTransferWaitTime=5

Heartbeats

13

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.
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

PLATINUM AutoSys User Guide for UNIX

13-17

 Configuring AutoSys
Configuration File Parameters

Remote Agent Log Files Directory

13

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 an
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.
An 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

File Maintenance

13

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.

13-18

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

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.

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

PLATINUM AutoSys User Guide for UNIX

13-19

 Configuring AutoSys
Configuration File Parameters

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-20

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

SNMP Connections

13

AutoSys can be integrated with Hewlett-Packards Network Node

Manager software, versions 4.10 or higher. This enables OpenView users
to do the following:

Monitor all alarms generated by AutoSys.

Monitor all UNIX signals received by the AutoSys Event Processor.

Specify that certain commands be issued when an AutoSys alarm or

signal is received by OpenView.

AutoSys sends alarms and signals to OpenView using the Simple

Network Management Protocol (or SNMP), and AutoSys posts its alarms
and signals using the SNMP trap mechanism.
Note Whenever the AutoSys Event Processor receives a UNIX signal,
it posts an SNMP event to OpenView. This can be particularly useful if
a signal has been sent to AutoSys that will shutdown the Event
Processor. The signal will be posted to OpenView before the Event
Processor shuts down.

To integrate AutoSys with OpenView, both of the following parameters

must be configured for AutoSys alarms to be detected by OpenView.

SnmpManagerHosts
The SnmpManagerHosts parameter specifies the machines to which
AutoSys will send SNMP traps. It contains a list of machines on the
network that are running SNMP managers, such as HPs OpenView or
IBMs NetView, and to which you want to send SNMP traps (i.e., post
SNMP events). By entering the name of a machine with this parameter,
you enable this functionality.
The entry in the AutoSys configuration file would look like this:
SnmpManagerHosts=host1,host2

PLATINUM AutoSys User Guide for UNIX

13-21

 Configuring AutoSys
Configuration File Parameters

SnmpCommunity
The SnmpCommunity parameter specifies the SNMP community associated
with all SNMP traps sent by AutoSys. This parameter is effectively a
password that can be used to filter SNMP traps by SNMP managers, such
as HPs OpenView. This value is almost always public, and thus, the entry
in the AutoSys configuration file usually looks like this:
SnmpCommunity=public

Configuring OpenView
To integrate OpenView with AutoSys
1 Install the AutoSys Tools option in the OpenView Misc menu, which

is described in Installing the AutoSys Tools Option, below.

2 Install the PLATINUM (AutoSys) Management Information Block (or

MIB), which is described in Installing the PLATINUM MIB on

page 13-23.
3 Modify the OpenView trapd.conf file, which is described in Modifying

the trapd.conf File on page 13-24.

Installing the AutoSys Tools Option

Install the AutoSys Tools option in the OpenView Misc menu by
installing the autosys menu registration file, located in the following
directory:
$AUTOSYS/snmp

Modify the autosys file to indicate to OpenView the location of the

autocons (Operator Console) and autosc (AutoSys GUI) executables.
When you do this, both the Autocons and Autosc options will become
available under the OpenView Misc menu  AutoSys Tools option.

13-22

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

In the autosys file, you must replace AUTOSYSBIN with the actual install
location of the AutoSys binaries. For example, if OpenView and AutoSys
are installed on the same machine, and AutoSys is located in the
/usr/vendors/autosys directory, you would locate the following lines:
Command "AUTOSYSBIN/autocons";
Command "AUTOSYSBIN/autosc";

And replace them with the following lines:

Command "/usr/vendors/autosys/bin/autocons";
Command "/usr/vendors/autosys/bin/autosc";

After you modify the file, copy it to the directory specified below.
For OpenView Operations Center 2.x:
/usr/OV/registration/$LANG
$LANG specifies the language with which OpenView Operations Center
2.x was installed, and this is usually english.

For IT/Operations Center 3.x or higher:

/etc/opt/OV/share/registration/$LANG
Note In OpenView, the default language is C for Common. If there
is not an english directory, the autosys menu registration file should
be copied to the C directory.

Installing the PLATINUM MIB

For IT/Operations Center 3.x or higher, the auto_opc_install script
installs the platinum.my file into the proper directory. Load the
/var/opt/OV/share/snmp_mibs/Vendor/Platinum/platinum.my file by
choosing OpenView root window  Options  Load/Unload
MIBs:SNMP.
For OpenView Operations Center 2.x, follow the steps below to copy it
to the proper location.

PLATINUM AutoSys User Guide for UNIX

13-23

 Configuring AutoSys
Configuration File Parameters

To install the PLATINUM (AutoSys) MIB

1 Locate the platinum.my file in the following directory:
$AUTOSYS/snmp
2 Copy the platinum.my file to the directory specified below.
/usr/OV/snmp_mibs/$LANG
$LANG specifies the language with which OpenView was installed; this
is usually english.
3 Load the /usr/OV/snmp_mibs/$LANG/platinum.my file by choosing:

OpenView root window  Options  Load/Unload MIBs:SNMP.

Modifying the trapd.conf File

The trapd.conf file is used to configure the traps that the HP Network
Node Manager will recognize. This file can be modified using OpenView
main window  Options  Event Configuration. Use caution when
modifying this file.
Note You may want to use xnmevents to load the trap.conf file.

The trapd.conf file is located in the directory specified below:

OpenView Operations Center 2.x:
/usr/OV/conf/$LANG
$LANG specifies the language with which OpenView Operations Center
2.x was installed; this is usually english.

IT/Operations Center 3.x or higher:

/etc/opt/OV/share/conf/C/

13-24

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

Supplied with your AutoSys release are two trapd.conf fragments that
you can merge into the existing trapd.conf file to configure all AutoSys
traps. These fragments are located in the trapd.auto1 and trapd.auto2
files in the following directory:
$AUTOSYS/snmp

The trapd.auto1 file contains the enterprise definitions. These

definitions should be placed near the beginning of the existing
trapd.conf file in the enterprises section. The section should look
similar to this:
#
#enterprises:
#
OpenView {.1.3.6.1.4.1.11.2.17.1}
hp {.1.3.6.1.4.1.11}

The trapd.auto2 file contains the AutoSys trap definitions. These

definitions should be placed at the end of the existing trapd.conf file.
Note If the above fragments are not installed properly, AutoSys

alarms will not be detected by OpenView.

Triggering Commands with AutoSys Alarm Events

Once AutoSys has been integrated with OpenView, you can configure
OpenView to trigger commands as a function of receiving specific events
from AutoSys.
To configure an AutoSys job_failure alarm to run a script that pages
someone once it is received by OpenView
1 Select OpenView main window  Options  Event Configuration:

SNMP.
This opens the Event Configuration window.

PLATINUM AutoSys User Guide for UNIX

13-25

 Configuring AutoSys
Configuration File Parameters

2 Single-click on the entry that has the Enterprise Name called

AutoSys.
The Event Identification list box displays all AutoSys alarm names.
3 Select the event named AS_JobFailure and single-click the Modify

button.
The Modify Event window appears.
4 At the bottom of the Modify Event window, in the Command for

Automatic Action text box, enter the name of the script you want
executed whenever this alarm event is received by OpenView. Then,
click OK.

13-26

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

HP OpenView IT/Operations

13

Two configuration parameters are needed to configure AutoSys with

Hewlett-Packard OpenView IT/Operations (IT/O). These two parameters
are OpcMessageGroup and OpcWaitTime.
Note For more information on these parameters, see Appendix C,
AutoSys Integration with OpenView IT/Operations in the AutoSys
Installation and Getting Started Guide for UNIX.

OpcMessageGroup
This parameter enables IT/O message generation and defines the IT/O
Message Group name under which messages should be posted.
The parameter appears in the configuration file like this:
#OpcMessageGroup=Job

OpcWaitTime
The OpcWaitTime parameter specifies the number of seconds the Event
Processor will wait for an IT/O status message to be sent to the IT/O
Message Agent. This option only applies to configurations that have
enabled IT/O support via the OpcMessageGroup parameter.
The parameter appears in the configuration file like this:
#OpcWaitTime=4

Number of Restart Attempts

13

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.

PLATINUM AutoSys User Guide for UNIX

13-27

 Configuring AutoSys
Configuration File Parameters

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).

Calculating the Wait Time Between Restarts

13

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.
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.

13-28

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

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

Method of Load Balancing

13

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

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.

PLATINUM AutoSys User Guide for UNIX

13-29

 Configuring AutoSys
Configuration File Parameters

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.

KILLJOB Signals

13

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

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-30

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

Port Number for Remote Agent

13

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
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.

Z/Team Job Parameter

13

ZTeamJobSupport
The ZTeamJobSupport parameter specifies whether an AutoSys instance
can dispatch jobs on machines managed by Zeke or Team Agent.

PLATINUM AutoSys User Guide for UNIX

13-31

 Configuring AutoSys
Configuration File Parameters

If the value of this parameter is equal to zero, then the Event Processor
will not send jobs to Zeke and Team 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, Zeke and Team Agent job support is off, and the entry in the
configuration file looks like this:
ZTeamJobSupport=0

For more information, see Appendix A, Integrating AutoSys with Zeke and
AutoSys/Team Agent.

Instance Wide Append Parameter

13

AutoInstWideAppend
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.
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 NT, the
default is to overwrite this file.

13-32

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuration File Parameters

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

Enabling PLATINUM Event Management and Data Exchange

13

AutoPems
You can enable AutoSys to send events to the PLATINUM Event Manager
and Data Exchange, assuming you already have the Event Manager and
Data Exchange are properly installed. The Event Manager makes
available, via subscription, the entire range of events and messages
supported by each PLATINUM application. The Event Manager can be
used to automate enterprise communication and integration.
If enabled, AutoSys will send events for every AutoSys job to the Event
Manager. Events include alarms and job status changes (job start, job
running, job complete, and completion status). If you have installed the
PLATINUM ProVision product, you can view these events with the
ProVision output browser.
Enabling Event Management integration also enables integration with
ProVision Data Exchange. This instructs AutoSys to write job definition
and job history information to the ProVision repository.
Refer to your ProVision documentation for information on the Event
Manager, Data Exchage, and the output browser.
The AutoPems parameter specifies if AutoSys should send events to the
ProVision Event Manager and Data Exchange. The entry in the
configuration file looks like this:
#AutoPems=1

PLATINUM AutoSys User Guide for UNIX

13-33

 Configuring AutoSys
Configuration File Parameters

AutoPems can be set to the following:

1
Sends AutoSys events to the PLATINUM Event Manager. This enables
a user to view AutoSys jobs from the ProVision output browser.
0
Does not send AutoSys events to the ProVision Event Manager.
By default, events are not sent. You must remove the comment character
from the beginning of this line to enable this integration.

Inetd Job Starting Interval

13

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
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-34

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
The auto.profile File

The auto.profile File

13

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:
AutoMachWideAppend See Instance Wide Append Parameter on

page 13-32
AUTOSV
AUTOSV_DIR

See ServerVision Environment Variables on

page 13-44

DENY_USER

See Client-Side Security on page 13-42.

PLATINUM AutoSys User Guide for UNIX

13-35

 Configuring AutoSys
The auto.profile File

Sample Default auto.profile

13

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
####################################################
# 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.

13-36

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
The auto.profile File

Note The #AUTOENV# descriptor is not a comment. Do not remove the

# character from the beginning of the line.

Remote Agent Database Connection Settings

13

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.
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.

PLATINUM AutoSys User Guide for UNIX

13-37

 Configuring AutoSys
Modifying Remote Agent Settings

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.

Modifying Remote Agent Settings

13

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.

Remote Agent Socket Connection

13

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

13-38

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Modifying Remote Agent Settings

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

Running Two AutoSys Versions of Remote Agents

13

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

PLATINUM AutoSys User Guide for UNIX

13-39

 Configuring AutoSys
Configuring Remote Authentication

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

Configuring Remote Authentication

13

You can configure AutoSys to run using the following two methods of
remote authentication:
Unix ruserok() Authentication
When using this method, AutoSys instructs a clients Remote Agent to
make the UNIX system ruserok() call. This function checks the client
machines /etc/hosts.equiv and the users .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 Processors 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-40

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuring Remote Authentication

Configuring Event Processor Authentication

13

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.

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
DEV:moe

PLATINUM AutoSys User Guide for UNIX

#Production Instance
#Development Instance

13-41

 Configuring AutoSys
Client-Side Security

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.

Client-Side Security

13

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>

13-42

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuring ServerVision Monitoring and Reporting

Configuring ServerVision Monitoring and

Reporting

13

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 jobs resource usage to generate reports useful for capacity
planning and UNIX process auditing. This section describes the
configuration tasks necessary to enable this integration.

Library Path

13

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.

svload Requirements

13

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.

PLATINUM AutoSys User Guide for UNIX

13-43

 Configuring AutoSys
Configuring ServerVision Monitoring and Reporting

ServerVision Environment Variables

13

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 jobs 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.

ServerVision Configurations

13

To view AutoSys jobs in the ServerVision GUIs

1 The ServerVision product must already be installed as instructed in the

ServerVision documentation.

13-44

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
Configuring ServerVision Monitoring and Reporting

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.

Monitoring Job Resource Usage

13

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

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.

PLATINUM AutoSys User Guide for UNIX

13-45

 Configuring AutoSys
User-Defined Alarm Callbacks

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).

User-Defined Alarm Callbacks

13

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:

13-46

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.

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.

PLATINUM AutoSys User Guide for UNIX

Configuring AutoSys
User-Defined Alarm Callbacks

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

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

PLATINUM AutoSys User Guide for UNIX

13-47

 Configuring AutoSys
User-Defined Alarm Callbacks

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.

13-48

PLATINUM AutoSys User Guide for UNIX

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
Remote Agent Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-13
Remote Agent Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-13
Remote Agent Will Not Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-14

PLATINUM AutoSys User Guide for UNIX

14-1

 Troubleshooting

Remote Agent Will Start - Command Will Not Run . . . . . . . . . . . . . . . . . . . .14-17

Remote Agent Starts, Command RunsNo 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

PLATINUM AutoSys User Guide for UNIX

Troubleshooting
Introduction

Introduction

14

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.

Event Server Troubleshooting

Event Server is Down (Sybase)

14

14

Symptoms
1 When trying to start xql, you get a message like this:
DB-Library error: dbproc NULL
Error in SybInit: dbopen failed

PLATINUM 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:
Couldnt 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

PLATINUM 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.

PLATINUM AutoSys User Guide for UNIX

14-5

 Troubleshooting
Event Server Troubleshooting

Sybase Deadlock

14

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 users 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 users 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 victims transaction, notifies the application
with the above error message, and allows the other users 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

PLATINUM AutoSys User Guide for UNIX

Troubleshooting
Event Server Troubleshooting

Not Enough User Connections (Bundled Sybase)

14

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

PLATINUM 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

PLATINUM 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.

archive_events Fails (Bundled Sybase)

14

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;

PLATINUM 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

PLATINUM 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

Event Server Will Not Start (Bundled Sybase)

14

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:
couldnt 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.

Event Processor Troubleshooting

14

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.

PLATINUM AutoSys User Guide for UNIX

14-11

 Troubleshooting
Event Processor Troubleshooting

Event Processor is Down

14

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.

Event Processor Will Not Start

14

Symptom
When running the eventor command, you see an error message similar
to the following:
/usr/autotree/autosys/bin/eventor:/usr/autotree/autouser/out/eve
nt_demon.ACE:Cannot create

14-12

PLATINUM 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.

Remote Agent Troubleshooting

14

Remote Agent Verification

14

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.

PLATINUM 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!

Remote Agent Will Not Start

14

The symptoms in this section are similar and result from network
problems.

Symptom
The Event Processors $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

PLATINUM AutoSys User Guide for UNIX

Troubleshooting
Remote Agent Troubleshooting

Symptom
The Event Processors $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.

PLATINUM AutoSys User Guide for UNIX

14-15

 Troubleshooting
Remote Agent Troubleshooting

Symptom
In the Event Processors $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 Agents 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

PLATINUM 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.

Remote Agent Will Start - Command Will Not Run

14

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).

PLATINUM 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 jobs 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

PLATINUM 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.

PLATINUM 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 RunsNo RUNNING Event is

Sent

14

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

PLATINUM 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.

PLATINUM 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

PLATINUM 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

xql Will Not Start (Sybase Only)

14

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.

PLATINUM 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 RunsNo
RUNNING Event is Sent on page 14-20.

Remote Agent Not Found

14

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

PLATINUM AutoSys User Guide for UNIX

Troubleshooting
Remote Agent Troubleshooting

Jobs Run Twice

14

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 jobs 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.

PLATINUM 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?

Job Failure Troubleshooting

14

Jobs Run Only From the Command Line

14

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 owners logon profile
$HOME/.profile. If the job owners 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

PLATINUM AutoSys User Guide for UNIX

Troubleshooting
Job Failure Troubleshooting

3 Write the current owners 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.

PLATINUM AutoSys User Guide for UNIX

14-27

 Troubleshooting
Job Failure Troubleshooting

14-28

PLATINUM AutoSys User Guide for UNIX

A
Integrating AutoSys with
Zeke and
AutoSys/Team Agent
This appendix describes how to integrate AutoSys with Zeke and
AutoSys/Team Agent components for an advanced AutoSys
configuration.
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Definition of Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
Job Scheduling for the Enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5
Installing and Configuring for Enterprise Job Scheduling . . . . . . . . . . . . . . . . . A-6
Install the Basic AutoSys Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Stop the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7
Configure the AutoSys Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7
Initializing the Communication Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
License Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14
Restart the Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-15

PLATINUM AutoSys User Guide for UNIX

A-1

 Integrating AutoSys with Zeke and AutoSys/Team Agent

About the oasis_broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-15

AutoSys and Zeke Cross-Platform Dependencies . . . . . . . . . . . . . . . . . . . . . . . .A-16
Job Scheduler Interdependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-17
Notation for Cross-Platform Job Dependencies . . . . . . . . . . . . . . . . . . . . . . . .A-18
Naming Conventions for AutoSys/Zeke Cross-Platform Jobs . . . . . . . . . . . . .A-19
Running AutoSys Jobs on the Team Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-20
Running Jobs on Team Agent Managed Machines . . . . . . . . . . . . . . . . . . . . .A-21
Defining Team Agent Machines to AutoSys . . . . . . . . . . . . . . . . . . . . . . . . . . .A-22
Team Agent Machine in an AutoSys Job Definition . . . . . . . . . . . . . . . . . . . . .A-23
Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-23
Logs and Trace Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-23
Zeke and Team Agent Job Statuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-24
Unsupported Attributes for Zeke or Team Agent Jobs . . . . . . . . . . . . . . . . . . .A-24
Cross-Platform Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-26

A-2

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

Introduction

Introduction

AutoSys enterprise-wide scheduling lets you integrate AutoSys jobs with

Zeke and the AutoSys/Team Agent. The following types of integration are
supported:

AutoSys jobs can be defined to conditionally start based on the status

of a Zeke job.

AutoSys can schedule jobs to run on a Team Agent machine.

Using cross-platform job dependency notation, AutoSys jobs can be

defined to conditionally start based on the status of a Zeke job running
on a mainframe. You can also create AutoSys jobs that will run on a Team
Agent machine (if the Team Agent machine is defined to AutoSys).

Definition of Terms

The following terms are used in this appendix:

AutoSys

A job scheduler that runs on UNIX and NT.

Zeke

A mainframe scheduler that runs on MVS and VSE

environments.

Team Agent

Team Agent is similar in function to an AutoSys

client machine (Remote Agent). Jobs from Zeke or
AutoSys can directly schedule cross-platform jobs on
a machine that is running Team Agent. AutoSys
supports Zeke and Team Agent integration on a
subset of the operating platforms on which Team
Agent runs, as specified in the AutoSys release notes.
The term Team Agent is used as an abbreviation for
the AutoSys/Team Agent product.

PLATINUM AutoSys User Guide for UNIX

A-3

 Integrating AutoSys with Zeke and AutoSys/Team Agent

Introduction

Cross-instance
job dependency

A dependency between jobs running on different

instances of AutoSys.

Cross-platform
job dependency

A dependency between jobs running on different

platforms. For example, an AutoSys job running on
a UNIX or NT machine can be dependent on a Zeke
job running on a mainframe.

Related Documentation

The information presented in this appendix supplements the following

documents:

PLATINUM AutoSys User Guide for UNIX

PLATINUM AutoSys Installation and Getting Started Guide for UNIX

PLATINUM AutoSys/Team Agent for UNIX Reference Guide (PLATINUM

AutoAction Reference Guide)

PLATINUM Zeke Product Reference Guide

PLATINUM Zeke Users Guide

Note AutoSys can also drive your legacy mainframe scheduler by

way of the AutoSys/Connect product. Refer to the AutoSys/Connect
User Guide for instructions on how to install and use this product.

A-4

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

Job Scheduling for the Enterprise

Job Scheduling for the Enterprise

PLATINUM AutoSys with Zeke and Team Agent let you schedule or
reroute jobs from multiple sources throughout the enterprise. To
accomplish this, the following elements must be present on the AutoSys
machine:
oasis_broker

An AutoSys process that communicates with Zeke or

Team Agent.

communication
components

A collection of executables used to route

information from Zeke or Team Agent back to the
AutoSys Event Processor. These executables are
listed in the Configure the Communication
Components on page A-11.

In addition, to utilize cross-platform job dependencies with a Zeke

machine, the following must be present on your Zeke machine:
OASIS

Open Architecture System Integration Solution

(OASIS) is a network interface between the Zeke
software and TCP/IP transport mechanisms. It
provides cross-platform communication between
Zeke and AutoSys.

The next section explains how to install and configure these components.
To learn how to implement enterprise job scheduling, see AutoSys and
Zeke Cross-Platform Dependencies on page A-16 and Running AutoSys Jobs
on the Team Agent on page A-20.

PLATINUM AutoSys User Guide for UNIX

A-5

 Integrating AutoSys with Zeke and AutoSys/Team Agent

Installing and Configuring for Enterprise Job Scheduling

Installing and Configuring for Enterprise Job

Scheduling

Before you can install and configure the components that must be
present to implement enterprise job scheduling, you must have installed
the Zeke and Team Agent components as instructed by your Zeke and
Team Agent installation documentation, and the AutoSys software as
instructed in the AutoSys Installation and Getting Started Guide for UNIX.
The required software and version levels are listed in the following table:
AutoSys

AutoSys version 3.4

for UNIX

Zeke

Team Agent

OASIS version 1.1

or later

ACF/VTAM level
V3R4M0

Zeke version 4.2

PTF193 or later

TCP/IP

AutoSys/Team
Agent version 1.2

Note AutoSys does not support Zeke or Team Agent licensing and
security, or the Team Agent GUIs, as implemented in Team Agent
version 1.2.

Install the Basic AutoSys Release

If it is not already installed, install the basic AutoSys product as described

in the AutoSys Installation and Getting Started Guide for UNIX.

A-6

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

Installing and Configuring for Enterprise Job Scheduling

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

Configure the AutoSys Machine

In addition to the basic AutoSys installation, the following procedures

must be performed on the AutoSys machine (that is, the machine on
which the AutoSys Event Processor was installed).

Edit the zteam.conf File

Edit the zteam.conf file in the directory $AUTOSYS/config. The zteam.conf
file must contain the following entries:
netregid:

NETREGID

defprotocol:

tcp

network:

na

node:

na

ipoasislog:

AUTOSYS/log/ipoasis.log

allowsujobs:

no

autosys_communications:AutoSys-OASIS.INS

where:
NETREGID (also called data group name)

Is a user-defined uppercase alphanumeric identifier from 1 to 8

characters.

PLATINUM AutoSys User Guide for UNIX

A-7

 Integrating AutoSys with Zeke and AutoSys/Team Agent

Installing and Configuring for Enterprise Job Scheduling

AUTOSYS

Is the value of the $AUTOSYS environment variable (for example:

/usr/autosys). This must be the full path, NOT the string $AUTOSYS.
INS

Is the three-letter uppercase ID (for example, ACE) for the AutoSys

instance that will communicate with the Zeke scheduling software.
Note If you are using an existing installation of Team Agent for
UNIX, edit the zteam.conf file in the ZTEAM directory and add the
following line to the end of the file:
Autosys_communications: AutoSys-OASIS.INS
where: INS is the three-letter uppercase ID (for example, ACE) for the

AutoSys instance that will communicate with Zeke.

Set the ZTEAMDIR Environment Variable

In the UNIX environment file (.profile or .cshrc) for the user who will
be starting AutoSys (that is, the user who will execute the eventor
command), define a new environment variable named ZTEAMDIR. This
variable must be set to the value you set for the AUTOSYS environment
variable. For example:
setenv ZTEAMDIR $AUTOSYS

Alternatively, you can set ZTEAMDIR from the command line at the time
you want to run Team Agent jobs or exchange job dependencies between
AutoSys and Zeke. Also, you can set this variable when you execute the
eventor command by using the -Z $ZTEAMDIR argument.
Note If you are using an existing installation of Team Agent for
UNIX, set the ZTEAMDIR environment variable to the value set during
the Team Agent installation. For example:
setenv ZTEAMDIR /usr/zteam

A-8

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

Installing and Configuring for Enterprise Job Scheduling

Set the ZTeamJobSupport Parameter

To run jobs directly on a Team Agent, enable Team Agent job support by
setting the following parameter in the AutoSys instance configuration file
($AUTOUSER/config.$AUTOSERV):
ZTeamJobSupport=1

When this parameter is set to 1, it indicates that an AutoSys instance can

dispatch jobs on a Team Agent.

Create the config.EXTERNAL File

To enable cross-platform dependencies with Zeke, create a file named
config.EXTERNAL in the $AUTOUSER directory. In config.EXTERNAL, add an
entry similar to the following for each Zeke scheduling system for which
cross-platform dependencies will be exchanged:
INS:ZEKE=OASIShost

where:
INS

Is the three-letter uppercase identifier for the Zeke instance; for

example, ZEK. This is the name by which the Zeke application will be
known to AutoSys.
ZEKE

Is a constant.
OASIShost

Is the OASIS network registration identifier (NETREGID) for the Zeke

scheduling system. This identifier can be up to eight uppercase
alpha/numeric characters.
For example:
ZEK:ZEKE=TESTZEKE

PLATINUM AutoSys User Guide for UNIX

A-9

 Integrating AutoSys with Zeke and AutoSys/Team Agent

Installing and Configuring for Enterprise Job Scheduling

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
ZTeamJobSupport parameter in the AutoSys configuration file. If the
parameter setting is inconsistent with the other integration settings, the
Event Processor will detect this disparity and shut down. Therefore it is
important to ensure the settings are consistent. That is, to enable
communication with Zeke and Team Agent, the following must be true:
ZTeamJobSupport is

set to 1 in the AutoSys configuration file.

ZTEAMDIR environment

variable is defined.

Zeke instance(s) are defined in the config.EXTERNAL file (if you want
to communicate with Zeke).

If you want to disable only Zeke communication, you must:

Comment out any Zeke instances in the config.EXTERNAL file.

If you want to disable both Team Agent and Zeke communication, you
must do the following:

A-10

Set ZTeamJobSupport to 0 in the AutoSys configuration file.

Unset the ZTEAMDIR environment variable.

Comment out any Zeke instances in the config.EXTERNAL file.

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

Installing and Configuring for Enterprise Job Scheduling

Configure the Communication Components

The following communication components are bundled with this release
and are installed on the machine on which the AutoSys Event Processor
was installed.
ipoasis

zappls

zping

ztrace

zglobals

zclients

Note If you prefer to use the Altai Development Lab supplied Team
Agent commands instead of those provided with this AutoSys release,
you should install them in an appropriate location other than the
AutoSys installation directories. However, we recommend that you
install the AutoSys provided communication components to ensure
proper communication between AutoSys and Zeke and Team Agent.

Refer to the PLATINUM AutoSys/Team Agent for UNIX Reference Guide for
details on the usage of these commands.
If you are using an existing installation of Team Agent for UNIX (from the
Altai Development Lab), you do not need to perform the following
configuration stepsthis will already be done. Otherwise, you must
configure the communication components as described in the following
steps.
To configure the communication components
1 Add entries to the /etc/services file following the example below:
zteamclnt

7701/tcp

zclnt

zteamsrvr

7702/tcp

zsrvr

oasisbroker

7998/tcp

oasibrkr

PLATINUM AutoSys User Guide for UNIX

A-11

 Integrating AutoSys with Zeke and AutoSys/Team Agent

Installing and Configuring for Enterprise Job Scheduling

These entries specify:

The Team Agent client port number. This port number can be any

number that is not already in use. We recommend you use a

number higher than 1024.
The Team Agent server port number. The server port number must

be the same on ALL machines running Team Agent. This port

number can be any number that is not already in use. We
recommend you use a number higher than 1024. This number
should match the entry in the OASIS initialization parameters.
The Oasis Broker port number.
2 Set up the Team Agent server service by adding the following entry to
the internet servers database file (/etc/inetd.conf) this must be a

single entry:
zteamsrvr stream tcp nowait root /usr/autosys/bin/ipoasis \
ipoasis -z /usr/autosys

This assumes that /usr/autosys is the full path defined for both the
$ZTEAMDIR and the $AUTOSYS environment variables.
3 To force the internet services daemon (inetd) to read in the changes
to the configuration file, determine the process ID of the inetd and

send it a hang up signal (SIGHUP).

For System V, use the following commands:
% ps -ef | grep inetd
% kill -1 pid

Where pid is the inetd process ID.

Or
For BSD, use the following commands:
% ps -aux | grep inetd
% kill -1 pid

A-12

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

Initializing the Communication Components

Where pid is the inetd process ID.

Note For AIX, use kill -9 pid, and then restart the inetd.

Initializing the Communication Components

The communication components on the AutoSys machine (the machine

on which the AutoSys Event Processor was installed) must be registered
in the Application Registry Table. The zappls command allows you to
monitor or browse the current list of applications registered with the
local Team Agent system.
Note We recommend that you always stop the AutoSys Event
Processor before running the zappls -i command.

To initialize the communication components

1 To clear all applications from the Application Registry Table and

restore the local Team Agent product to the local system, execute the
following command:
$AUTOSYS/bin/zappls -i
2 Register the adjacent Team Agent or Zeke by executing the following

command:
$AUTOSYS/bin/zping -p tcp -t ADDRESS

Where ADDRESS is the Zeke mainframes TCP/IP address or the UNIX

or NT hostname.
3 Confirm that the NETREGID (or Team Agent Application) that you want

to register is recorded in the Application Registry Table by executing

the following command:
$AUTOSYS/bin/zappls

PLATINUM AutoSys User Guide for UNIX

A-13

 Integrating AutoSys with Zeke and AutoSys/Team Agent

Initializing the Communication Components

This displays the Application Registry Table, as shown in Figure A-1

Application | Prod | Last Activity | In | Out
===================================================================
PLATHPUX ZTEM

Thu June 05 12:08:20 1997 0 0

Figure A-1 Example Application Registry Table display

License Keys

AutoSys client license keys are required for Team 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
Customer Service department at the AutoSystems Development Lab
based on the host name and host id of the client machine.
For Team Agent machines, the host name is the NETREGID and the host id
is always 0 (zero).
When you supply the above information to the Customer Service
department, 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: NETREGID
Hostid: 0
KEY: IIJJKKLLMMNNOOPP
***** New Key ADDED! *****
KEY Type: [(c)lient, (s)erver, (t)ime, (x)pert]:<Return>

A-14

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

About the oasis_broker

Restart the Event Processor

Now you can start the Event Processor using the eventor command.

About the oasis_broker

Communication between AutoSys and Zeke or a Team Agent is facilitated

by the oasis_broker. It is a necessary component for cross-platform
communication because contacting and passing information to Zeke or
a Team Agent could take several minutes. Letting the oasis_broker
handle that exchange frees the Event Processor to handle other events.
The Event Processor inserts entries into the ext_job and req_job tables in
the AutoSys database for completion events communicated to it by the
oasis_broker.
When the Event Processor is started, it checks if the ZTeamJobSupport
parameter in the AutoSys configuration file is enabled and if the ZTEAMDIR
variable is set. If they are, the Event Processor starts the oasis_broker
automatically. If the Event Processor is stopped, or goes down for any
reason, the oasis_broker will also stop running. The only way to bring
up the oasis_broker is to restart the Event Processor.
If the Event Processor and the oasis_broker go down while a Team Agent
or Zeke job finishes, the completion event will be lost. 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.

PLATINUM AutoSys User Guide for UNIX

A-15

 Integrating AutoSys with Zeke and AutoSys/Team Agent

AutoSys and Zeke Cross-Platform Dependencies

AutoSys and Zeke Cross-Platform

Dependencies

AutoSys jobs can have dependencies on jobs managed by PLATINUMs

Zeke scheduling software running in the MVS and VSE environments. 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 Zeke job
running on a mainframe system.
AutoSys UNIX or NT
NETREGID: MYMACHIN
Instance: ACE

Event
Server

MVS
NETREGID: MVSZEKE

Communication
Components *

O
A

Z
E

Event
Processor

Job

S
oasis_broker

Team Agent
(Remote)

* Communication components are listed in Configure the

Communication Components on page A-11.
Figure A-2 AutoSys and Zeke (MVS) cross-platform configuration

A-16

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

AutoSys and Zeke Cross-Platform Dependencies

In Figure A-2, communication between AutoSys and Zeke is handled by

the oasis_broker and the communication components.

The AutoSys Event Processor communicates with Zeke through an

AutoSys process called the oasis_broker, which communicates with
Zeke through the OASIS network interface.

OASIS routes Zeke job information back to AutoSys via the

communication components.

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-9.

Job Scheduler Interdependencies

AutoSys jobs can be dependent on the status of Zeke jobs and Zeke jobs
can be dependent on the status of AutoSys jobs. For details on how to
implement this with the Zeke job scheduler, refer to your Zeke
documentation.
For AutoSys jobs, this type of cross-platform dependency is described
below.
To create job scheduler interdependencies
1 AutoSys sends a request to the oasis_broker for the status of a Zeke

job running on a mainframe.

2 The oasis_broker passes the request to the MVS OASIS.
3 The MVS OASIS informs Zeke of the request. Zeke registers the

request.
4 The job runs as scheduled by the Zeke job scheduler. Zeke can run the

job on the mainframe or remotely through a Team Agent.

5 The completion status of the job is passed to the MVS OASIS by the

jobs parent (Zeke or the remote Team Agent).

PLATINUM AutoSys User Guide for UNIX

A-17

 Integrating AutoSys with Zeke and AutoSys/Team Agent

AutoSys and Zeke Cross-Platform Dependencies

6 The MVS OASIS sends the status of the job to the communication

component on the AutoSys machine.

7 The communication component sends the status to the oasis_broker.
8 The oasis_broker communicates the status to the Event Processor.
9 The Event Processor starts the AutoSys job that is dependent on the

completion of the Zeke job.

Notation for Cross-Platform Job Dependencies

To define a cross-platform job dependency, you 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.
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, you enter this information in the Starting
Condition field of the Job Definition screen. You can use the following
statuses in the condition attribute of an AutoSys job definition
dependent on a Zeke job:

A-18

success

terminated

done

notrunning

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

AutoSys and Zeke Cross-Platform Dependencies

AutoSys and Zeke Cross-Platform Dependency

Example
Below is an example of an AutoSys job that will start only upon the
successful completion of jobA which is a Zeke job that runs on a
mainframe:
condition: success(jobA^ZEK)

where: success(jobA^ZEK) specifies the successful completion of a Zeke

job named jobA running on a mainframe specified with the three-letter
ID of ZEK.

Naming Conventions for AutoSys/Zeke Cross-Platform Jobs

Because of naming limitations in the MVS, VSE, and AS/400

environments, the names of jobs specified as job dependencies between
AutoSys and Zeke 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 Zeke.

For more information on cross-instance job dependencies, see the CrossInstance Job Dependencies section of Chapter 3, AutoSys Jobs.

PLATINUM AutoSys User Guide for UNIX

A-19

 Integrating AutoSys with Zeke and AutoSys/Team Agent

Running AutoSys Jobs on the Team Agent

Running AutoSys Jobs on the Team Agent

AutoSys can directly schedule jobs on a machine that is running the Team
Agent, assuming the machine running the Team Agent has been defined
to AutoSys. In the following example configuration, the Team Agent is
running on an AS/400 machine. The AutoSys and Team Agent
integration is supported on other operating platforms as well.
AutoSys UNIX or NT
NETREGID: MYMACHIN
Instance: ACE

AS/400
NETREGID = ZASYS400
Communication
Components *

Event
Server

Event
Processor

oasis_broker

T
E
A
M
A
G
E
N
T

Job

* Communication components are listed in the Configure the

Communication Components on page A-11.
Figure A-3 AutoSys and Team Agent configuration

In Figure A-3, communication between AutoSys and the Team Agent is

handled by the oasis_broker and the communication components.

A-20

The AutoSys Event Processor communicates with the Team Agent

through an AutoSys process called the oasis_broker.

The communication components running on the AutoSys machine

receive information from the Team Agent and pass it to the
oasis_broker.

Team Agent (which in this example is running on the AS/400

platform) is analogous to an AutoSys Remote Agent.

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

Running AutoSys Jobs on the Team Agent

Running Jobs on Team Agent Managed Machines

The process by which AutoSys can run jobs directly on a Team Agent
managed machine is described below.
To run jobs on Team Agent managed machine
1 The Event Processor sends the job information to the oasis_broker

and the job changes to STARTING status.

2 The oasis_broker passes the information to the Team Agent, which

starts the job.

3 The Team Agent passes the information that the job is running (BOJ

event) to the communication component on the AutoSys machine.

4 The communication component on the AutoSys machine informs the
oasis_broker of the change.
5 The oasis_broker informs the Event Processor; the job changes to

RUNNING status.
6 When the job exits, the Team Agent client traps the return code and

passes the information that the job is finished to the communication

component on the AutoSys machine.
7 The communication component on the AutoSys machine informs the
oasis_broker of the change.
8 The oasis_broker informs the Event Processor; the job changes to a

status of either SUCCESS (if the job exited with a normal end of job
code, EOJ) or TERMINATED (if the job exited with an abnormal end
of job code, AEOJ).

PLATINUM AutoSys User Guide for UNIX

A-21

 Integrating AutoSys with Zeke and AutoSys/Team Agent

Running AutoSys Jobs on the Team Agent

Defining Team Agent Machines to AutoSys

Before you can run AutoSys jobs on a Team Agent machine, you must
first define the Team 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 a Team Agent
machine.
To define a Team Agent machine, follow this example:
insert_machine: NETREGID
type: z

where:
NETREGID

Is the Team Agents NETREGID, which must be recorded in the

Application Registry Table.
type: z

Indicates that the machine type is a Team Agent.

Note Team Agent managed machines cannot be part of a virtual
machine. job_load, max_load, and factor attributes are not supported

for Team Agent managed machines.

For example, to define the machine shown in Figure A-3 on page
page A-20, which has a NETREGID of ZASYS400, you would specify the
following:
insert_machine: ZASYS400
type: z

A-22

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

Database Tables

Team Agent Machine in an AutoSys Job Definition

Once you have defined a Team 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

The owner identified in the owner attribute of the job definition must
have an account on the target Team Agent machine. The account must
match the owner name exactly in order for the job to run. If the owner is
specified as user@machine), everything after the @ is ignored. (If
necessary, the AutoSys Edit Superuser can change the owner of a job.)

Database Tables

To implement cross-platform functionality, two new AutoSys tables were

created: ext_job and req_job. These tables contain job status events for
jobs that are shared between instances.

Logs and Trace Information

If AutoSys is unable to start a job on a Team Agent, an entry will be

inserted into the error log located in the $AUTOSYS/log directory with a
file name of the current date.
OASIS trace information is kept in $AUTOSYS/log. The amount of
information written to this file is controlled by the zglobals command
(see the zglobals man page). To obtain OASIS trace information, you
can execute the ztrace command, for example:
ztrace oasis_broker.in

PLATINUM AutoSys User Guide for UNIX

A-23

 Integrating AutoSys with Zeke and AutoSys/Team Agent

Zeke and Team Agent Job Statuses

Zeke and Team Agent Job Statuses

The valid statuses that AutoSys can get for Zeke and Team Agent managed
jobs are:
STARTING
The job has been passed from the Event Processor to the
oasis_broker.

RUNNING
The job has started and a BOJ (Beginning Of Job) event has been sent
back to the oasis_broker.
SUCCESS
The job has ended and an EOJ (End Of Job) event has been passed
back to the oasis_broker.
TERMINATED
The job has ended and an AEOJ (Abnormal End Of Job) event has
been sent back to the oasis_broker.
Any Zeke or Team Agent managed job without a return code of zero will
be considered TERMINATED.

Unsupported Attributes for Zeke or Team

Agent Jobs

The following AutoSys attributes are not supported for Zeke or Team
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.

A-24

chk_files

Resource Check - File System Space...

heartbeat_interval

Heartbeat Interval (mins)

PLATINUM AutoSys User Guide for UNIX

Integrating AutoSys with Zeke and AutoSys/Team Agent

Unsupported Attributes for Zeke or Team Agent Jobs

job_load

Job Load

job_terminator

If the Box fails should this Job be Terminated?

job_type:f

Job Type (File Watcher)

max_exit_success

Maximum Exit Code for SUCCESS

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

PLATINUM AutoSys User Guide for UNIX

A-25

 Integrating AutoSys with Zeke and AutoSys/Team Agent

Cross-Platform Limitations

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

Zeke or Team Agent jobs and machines.

Remote Authentication is not supported for Zeke or Team Agent jobs.

The following events cannot be executed on a Zeke or Team Agent job:

KILLJOB
CHANGE_PRIORITY
SEND_SIGNAL

A-26

PLATINUM AutoSys User Guide for UNIX

Index
Symbols
$AUTORUN 3-30
$AUTOSYS/bin/chk_auto_up 12-32
$AUTOSYS/code/heartbeat.c 4-24
$AUTOSYS/code/heartbeat.sh 4-24
$AUTOSYS/dbobj/create_table 12-32
$AUTOTESTMODE 12-11
$AUTOUSER/autosys.env 12-30
$AUTOUSER/config.$AUTOSERV 13-3
$SYBASE 12-30
$SYBASE/install/RUN_AUTOSYSDB
12-30
/bin/date command 12-11
/etc/.autostuff file 13-40, 13-41
/etc/auto.profile file. See auto.profile file
/etc/services file, Remote Agent port
number 13-39
/tmp/autotest.$JobName 12-11

A
ACTIVATED status 3-10
advanced configuration 13-1 to 13-26
after_time report attribute 11-10

PLATINUM AutoSys User Guide for UNIX

alarm callbacks 13-46

Alarm Manager
about 10-4
acknowledging alarms 10-29
Alarm List 10-30
Alarm Selection dialog 10-35
Select by State region 10-36
Select by Time region 10-37
Select by Type region 10-36
changing alarm states 10-34
closing alarms 10-29
Control Region
Freeze Frame button 10-33
New Alarm button 10-34
Select Job button 10-33
Currently Selected Alarm
acknowledging 10-33
closing 10-32
Response edit box 10-32
menu bar 10-31
registering responses 10-34
alarm monitor/report attribute 11-8
alarm_if_fail job attribute 4-15

Index-1

 Index

alarm_verif monitor attribute 11-11

alarms
about 1-12
DB_PROBLEM 13-46
DB_ROLLOVER 13-46
EP_HIGH_AVAIL 13-46
EP_ROLLOVER 13-46
EP_SHUTDOWN 13-46
all_events monitor/report attribute 11-8
all_status monitor/report attribute 11-9
archive data for ServerVision 13-44
atomic starting conditions 10-13
attributes
job
alarm_if_fail 4-15
auto_delete 4-17
auto_hold 4-17
avg_runtime 4-23
basic 3-8
box_failure 4-27
box_name 4-13
box_success 4-26
box_terminator 4-15
chk_files 4-24, 4-26
command 4-5, 4-6
condition 4-12
date_conditions 4-10
days_of_week 4-10
description 4-13
essential
all jobs 4-5
Box Jobs 4-9
Command Jobs 4-6
File Watcher Jobs 4-9
exclude_calendar 4-11
heartbeat_interval 4-24
job_load 4-21

Index-2

job_name 4-5
job_terminator 4-15
machine 4-8, 4-9
max_exit_success 4-23
max_run_alarm 4-14
min_run_alarm 4-14
n_retrys 4-16
optional
Box Jobs 4-26
Command Jobs 4-19
File Watcher Jobs 4-25
non-starting parameters 4-13
starting parameters 4-10
override_job 4-22
permission 4-17
priority 4-22, 9-5
run_calendar 4-10
run_window 4-11
start_mins 4-12
start_times 4-11
std_err_file 4-21
std_in_file 4-20
std_out_file 4-20
term_run_time 4-14
timezone 4-16
watch_file 4-9
watch_file_min_size 4-25
watch_interval 4-25
job dependencies 3-18
machine
factor attribute 9-6
max_load 9-5
monitor
alarm_verif 11-11
sound 11-11

PLATINUM AutoSys User Guide for UNIX

Index

monitor/report
alarm 11-8
all_events 11-8
all_status 11-9
essential 11-7
job_filter 11-9
mode 11-7
name 11-7
report
after_time 11-10
currun 11-10
starting conditions 3-18
authentication, remote 13-40
auto.profile file
AutoMachWideAppend variable 13-32
AUTOSV variable 13-44
AUTOSV_DIR variable 13-44
DENY_ACCESS 13-42
Remote Agent settings 13-35
remoteProFiles 13-19
auto_delete 4-17
auto_hold 4-17
auto_remote. See Remote Agent
autocal 8-5
autocons 10-7
autohold job attribute 4-17
AutoInstWideAppend 13-32
AutoMachWideAppend variable 13-32
AutoPems 13-33
autoping 14-13
AutoRemoteDir 13-18
AutoRemPort 13-31, 13-39
autosc 11-5
AUTOSERV environment variable 13-3
autostuff file 13-40, 13-41
AUTOSV environment variable 13-44

PLATINUM AutoSys User Guide for UNIX

AUTOSV_DIR environment variable

13-44
AutoSys
components 1-4
database, defined 1-5
Graphical User Interface, see GUI
instances, defined 1-11
machines 1-10
security 2-1
AutoSys/Team Agent support 13-31
AutoSys/Xpert 4-24, 6-4
autosys_secure 4-18
autosyslog command 12-6, 14-18
avg_runtime 4-23

B
backups
bundled Sybase 12-34
calendar definitions 12-13
global variables (using autorep) 12-15
job definitions (using autorep) 12-14
machine definitions (using autorep)
12-14
monitor and browser definitions (using
monbro) 12-14
batch files and exit codes 3-26
Box Jobs 3-6, 5-1
basic job definition 3-9
default behavior 5-3
diagram 3-14
examples 5-10
force starting jobs in a box 5-8
guidelines 5-4
non-default terminators 5-6

Index-3

 Index

placing job in
GUI 6-18
JIL 7-10
starting conditions 3-6, 3-16
status changes 5-9
box_failure 4-27
box_name 4-13
box_success 4-26
box_terminator 4-15
browsers
backing up definitions 12-14
defined 11-3
restoring definitions from backup file
12-16

C
Calendar Selection dialog 8-16
calendars 8-1 to 8-35
applying rules 8-8
backing up definitions 12-13
blocked dates 8-11
blocking dates 8-18
Calendar Definition window 8-6
clearing 8-8
color key 8-14
combining 8-27
conflicting dates 8-12, 8-14
creating, example 8-14
custom 3-17
customizing Calendar Facility 8-30
date range 8-10, 8-19
date states 8-11
deleting 8-7
Edit menu 8-8
exiting 8-8
exporting 8-8, 8-28, 8-30
exporting definitions to file 12-13

Index-4

File menu 8-7

importing 8-8, 8-28
importing definitions from file 12-15
Job Definition Reference List 8-9
merging 8-27
navigation controls 8-12
opening 8-7
Options menu 8-10
periods 8-20
print command 8-10
printing 8-8, 8-28
rescheduling rules 8-22
restoring definitions 12-15
reverting to last saved 8-8
rule specification 8-18
saving 8-7
selecting 8-16
Set Print command 8-10
setting dates 8-18
Term Calendar Rule 8-17
Term Calendar Viewer 8-9, 8-25
Tools menu 8-9
unsetting dates 8-18
charge back reporting 9-18
chase command 12-12
check file space 4-24, 4-26
Check_Heartbeat 13-17
chk_auto_up 13-13
chk_files 4-24
clean_files 12-12, 13-19
CleanTmpFiles 13-18
client machine 1-10
command job attribute 4-5, 4-6
Command Jobs 3-5, 3-8

PLATINUM AutoSys User Guide for UNIX

Index

components
Event Processor 1-6
Event Server 1-5
Remote Agent 1-7
condition job attribute 4-12
conditions, starting 3-18
configuration file 13-4
AutoInstWideAppend 13-32
AutoPems 13-33
AutoRemoteDir 13-18
AutoRemPort 13-31
Check_Heartbeat 13-17
CleanTmpFiles 13-18
DBEventReconnect 13-12
DBLibWaitTime 13-10
DBMaintCmd 13-16
EDErrTimeInt 13-13
EDMachines 13-13
EDNumErrors 13-13
EvtTransferWaitTime 13-17
FileSystemThreshold 13-15
InetdSleepTime 13-34
KillSignals 13-30
MachineMethod 13-29
MaxRestartTrys 13-27
MaxRestartWait 13-28
OpcMessageGroup 13-27
OpcWaitTime 13-27
RemoteProFiles 13-19
RestartConstant 13-28
RestartFactor 13-28
sample 13-4
SnmpCommunity 13-22
SnmpManagerHosts 13-21
ThirdMachine 13-14
WaitTime 13-28
XInstanceDBDropTime 13-11

PLATINUM AutoSys User Guide for UNIX

ZTeamJobSupport 13-31
configuration, AutoSys 13-1 to 13-26
Control Panel, GUI 6-3
conventions, typographical xxix
cpu, using available cycles to select
machine to run on 9-12
crash recovery, database 12-23, 12-41
cross-instance, database connection 13-11
Currently Selected Job region 10-11
currun report attribute 11-10
custom calendars, overview 3-17
customizing
Calendar Facility 8-30
Job Definition 6-30
Operator Console 10-37, 11-22

D
data exchange (ProVision) 13-33
database
accessing interactively 12-32
administration 12-28
architecture 12-18
backup, bundled Sybase 12-34
changing the sa password 12-29
checking if up 12-31
connection to Job Definition GUI timeout interval 6-31
connection to Monitor/Browser GUI
time-out interval 11-22
connections 13-11
crash recovery 12-23
defined 12-16
defining which to use 12-18
dumping 12-34
identifying connected processes 12-33
maintenance 13-15
maintenance script 13-16

Index-5

 Index

database (contd.)
maintenance time 12-20
passwords 2-10
recovery 12-22, 12-41
reloading 12-43
rollover 12-22
shutdown 12-31
starting 12-30
stopping 12-31
stopping service 12-31
storage requirements 12-17
time-out period 13-10
unrecoverable error 12-22
verifying connection 14-13
dataserver, defined 1-5
date dependency 3-17
date range in calendars 8-10, 8-19
date/time job dependencies 3-17
Date/Time Options dialog, example 6-7
date_conditions 4-10
days to run job, setting
GUI 6-22
JIL 7-12
days_of_week 4-10
DB Library 12-27
DB_PROBLEM 13-46
DB_ROLLOVER 13-46
DBDropTime
Job Definition GUI 6-31
Monitor/Browser GUI 11-23
DBEventReconnect 13-12
DBLibWaitTime 13-10
DBMaint script 12-20
DBMaintCmd 13-16
dbstatistics script 12-20
default owner of job 2-11

Index-6

delete job
GUI 6-25
JIL 7-13
DENY_ACCESS AUTOENV setting 13-42
dependency, job
date/time 3-17
exit code 3-25
global variables 3-28
job status 3-18
dependent jobs
creating - GUI 6-15
creating -JIL 7-9
example 3-23
description job attribute 4-13
done condition in job definition 3-19
DSQUERY variable 12-28
Dual Event Servers
crash recovery 12-23
defined 1-6
mode 12-16
synchronizing Event Servers 12-23
Dual Server Mode 12-22

E
EDErrTimeInt 13-13
edit permissions 2-12
Edit Superuser 2-15
EDMachines 13-13
EDNumErrors 13-13
environment variables
AUTOSERV 13-3
DSQUERY 12-28
See also profiles
SYBASE 12-28
user-defined 4-7
EP_HIGH_AVAIL 13-46
EP_ROLLOVER 13-46

PLATINUM AutoSys User Guide for UNIX

Index

EP_SHUTDOWN 13-46
errors
Event Processor handling 13-13
Event Processor time interval 13-13
essential job attributes 4-5
event management (ProVision) 13-33
Event Processor
See also event_demon
allowable time between errors 13-13
authentication on Remote Agent 13-41
automatic shutdown 13-12, 13-13
checking for running 13-13
defined 1-6
error handling 13-13
heartbeat interval 13-17
log
minimum disk space 13-15
viewing 12-6
monitoring 12-4, 12-6
restoring 12-9
running in test mode 12-10
shutdown, automatic 13-12
starting 12-3
stopping 12-7
tail command 12-4
Third Machine 13-14
troubleshooting 14-11
Event Report, from Operator Console
10-14
Event Server
See also database
See also Dual Event Servers
defined 1-5
dual 12-16, 12-18
recovery 12-22
rollover 12-22
synchronizing process 12-23

PLATINUM AutoSys User Guide for UNIX

transferring events 13-16

troubleshooting 14-3
event_demon 12-3
See also Event Processor
eventor
script 12-3
events
about 1-11
cancelling 10-18
copying between Event Servers 13-17
EvtTransferWaitTime 13-17
examples
calendar rescheduling rule 8-23
calendar, creating 8-14
individual queues 9-22
JIL 7-16
job dependencies 3-23
load balancing 9-13
monitor/report definition 11-15
multiple machine queues 9-25
queuing with priority 9-21
real machine definition 9-8
reports, defining in JIL 11-21
system architecture 1-8
virtual machine definition 9-9
xql scripts 12-32
exclude_calendar 4-11
exclusive condition 3-24
Exec Superuser 2-16
execute permissions 2-13
exit codes
batch files, with 3-26
FALSE.EXE 3-28
job dependencies 3-25
maximum for success 3-19
exitcode 3-25
exporting calendars 8-30, 12-13

Index-7

 Index

F
factor attribute 9-6
failure condition in job definition 3-19
FAILURE status 3-11
FALSE.EXE 3-28
file locking 13-18
file maintenance 13-18
File Watcher Jobs 3-7
basic job definition 3-9
creating 6-12
FileSystemThreshold 13-15
filter, monitor/report 11-9
force starting jobs
from Job Activity console 10-15
impact on load balancing 9-14

G
gid 2-12, 4-18
global variables
backing up definitions 12-15
job dependencies 3-28
restoring definitions 12-16
setting, in the Send Event dialog 10-17
Graphical Calendar Facility 8-1 to 8-35
Calendar Definition window 8-6
screens 8-5
See also calendars
starting 8-5
group ID 2-12, 4-18
GUI
Advanced Features dialog 6-8
Control Panel 6-3
Date/Time Options dialog 6-7
defined 1-3
defining monitor/reports 11-12
HostScape 6-3
Job Definition dialog 6-4, 6-5

Index-8

JobScape 6-4
Monitor/Browser dialog 6-3
one-time job overrides 6-26
Operator Console 6-3
starting 6-3
time dependencies, setting 6-22
TimeScape 6-4
using to create a job definition 4-4

H
heartbeat_interval 4-24
heartbeats
about 13-17
checking 13-17
code to include 4-24
interval 4-24
time interval 13-17
high availability
Dual Event Servers 1-6
Shadow Event Processor 1-6
HostScape 6-3
HP OpenView IT/Operations settings
13-27
HP OpenView settings 13-22

I
Import/Export File Name (calendar)
dialog 8-28
importing calendars 8-28, 12-15
INACTIVE status 3-10
inetd
job starting inverval 13-34
resetting 13-29
InetdSleepTime 13-34
InfoReports 10-5
accessing from Operator Console 10-47
configuring for printing 10-48

PLATINUM AutoSys User Guide for UNIX

Index

inherit, jobs starting conditions 3-16

instances of AutoSys 1-11
IT/Operations settings 13-27

J
JIL
creating a job definition 4-3
defined 1-3
defining jobs 7-3
defining monitors/reports 11-19
defining report 11-21
example 7-16
running 7-6
sub-commands 7-5
syntax rules 7-3
Job Activity Console 10-8
See also Operator Console
starting conditions 10-13
Alarm button 10-22
Alarm Manager dialog 10-29
cancelling a sent event 10-18
Control Area 10-14
action buttons 10-15
control buttons 10-20
Dependent Jobs button 10-20
Freeze Frame button 10-21
Job Definition button 10-20
Report buttons 10-21
Currently Selected Job region 10-11
Dependent Jobs dialog 10-20
InfoReports viewing 10-5
Job List 10-10
Job Path (History) dialog 10-21
Job Selection dialog 10-23
menu bar 10-9
reports 10-14
resizing regions 10-23

PLATINUM AutoSys User Guide for UNIX

Send Event dialog 10-16

AUTOSERV instance 10-17
Cancel button 10-18
Change Status 10-17
Comment field 10-17
Execute button 10-18
Global Name/Value 10-17
Job Name 10-17
Queue Priority 10-17
Send Priority 10-18
Signal 10-17
time of event 10-17
Job Definition dialog 6-4
customizing 6-30
database connection time-out 6-31
icon text 6-31
title bar text 6-31
Job Definition Reference List 8-9
Job Information Language 1-12
See also JIL
Job List region 10-10
job overrides, setting 7-14, 7-15
job resource usage 9-18, 13-45
Job Selection dialog 10-23
Box Levels field 10-25
Job Name field 10-25
setting job selection criteria 10-29
sorting specified jobs 10-28
specifying jobs
by machine 10-27
by name 10-24
by status 10-26
job starts, reducing start interval 13-34
job status, as job dependency 3-18
job_filter monitor/report attribute 11-9
job_load 4-21
job_name 4-5

Index-9

 Index

job_terminator 4-15
jobs
attributes, basic 3-8
backing up definitions 12-14
basic job information 3-4
Box Jobs 5-1
creating - GUI 6-18
creating - JIL 7-10
defined 3-6
changing - GUI 6-20
changing - JIL 7-10
Command Jobs
creating - GUI 6-10
creating - JIL 7-7
defined 3-5
creating
Box Jobs - GUI 6-18
Box Jobs - JIL 7-10
Command Jobs - GUI 6-10
Command Jobs - JIL 7-7
File Watcher Jobs - GUI 6-12
File Watcher Jobs - JIL 7-8
creating a job definition 4-3
custom calendars 3-17
cycles of processing 14-3
date/time dependencies
setting in GUI 6-22
setting in JIL 7-12
days to run, setting 6-22
defined 1-3
defining environment for 4-7
defining in AutoSys 3-30
definition
Box 3-9
Command 3-8
File Watcher 3-9

Index-10

deleting
GUI 6-25
JIL 7-13
dependencies
creating with GUI 6-15
creating with JIL 7-9
exit codes 3-25
global variables 3-28
job status 3-18
time
GUI 6-22
JIL 7-12
edit permissions 2-12
execute permssions 2-13
exit code 3-25
File Watcher
creating - GUI 6-12
creating - JIL 7-8
defined 3-7
force starting 9-14, 10-15
heartbeats from 4-24
number of restart attempts 13-27
overrides
GUI 6-26
JIL 7-14
owner, default 2-11
permissions on NT 2-14
queuing 9-5, 9-18
restart tries 13-27
restoring definitions from backup file
12-16
run number 3-29
saving definitions to backup file 12-14
selection list 6-21

PLATINUM AutoSys User Guide for UNIX

Index

jobs (contd.)
starting conditions 3-15
done 3-19
failure 3-19
notrunning 3-19
success 3-18
terminated 3-19
states 3-10
status
ACTIVATED 3-10
FAILURE 3-11
INACTIVE 3-10
managing 3-24
ON_HOLD 3-12
ON_ICE 3-12
QUE_WAIT 3-11
RESTART 3-11
STARTING 3-10
SUCCESS 3-11
TERMINATED 3-11
status codes 3-10
time dependencies, setting
JIL 7-12
time/date dependencies 3-17
types 3-3
variables for 4-7
JobScape 6-4

K
KILLJOB signals 13-30
KillSignals 13-30

L
load balancing 9-11
example 9-13
force starting jobs 9-14
job attributes required for 9-5

PLATINUM AutoSys User Guide for UNIX

maximum load on machine 9-5

method 13-29
ServerVision 13-43
user-defined 9-25
locking, Remote Agent log file 13-18

M
machine
attribute 4-8, 4-9
backing up definitions 12-14
client 1-10
defining with JIL 9-3
deleting
real machines 9-9
virtual machines 9-10
factor attribute 9-6
job runs on 4-8
machine attribute 9-4
max_load attribute 9-5
permissions, edit and execute 2-13
priority job attribute 9-5
real 9-3
restoring definitions from backup file
12-16
saving definitions to backup file 12-14
server 1-10
type attribute 9-4
virtual 9-3
defining 9-9
deleting 9-10
MachineMethod 13-29
maintenance
backing up AutoSys definitions 12-13
calendar definitions 12-13
global variables 12-15
job definitions 12-14
machine definitions 12-14

Index-11

 Index

maintenance (contd.)
backing up AutoSys definitions (contd.)
monitor and browser definitions
12-14
chase command 12-12
clean_files 12-12
commands 12-12
database 13-15
database time 12-20
files 13-18
restoring AutoSys definitions 12-15
managing job status 3-24
max_exit_success 4-23
max_load machine attribute 9-5
max_run_alarm 4-14
maximum exit code for success 3-19
maximum system load 9-5
MaxRestartTrys 13-27
MaxRestartWait 13-28
method of load balancing 13-29
min_run_alarm 4-14
mode monitor/report attribute 11-7
Monitor/Browser dialog 6-3, 11-12
customizing 11-22
database connection time-out 11-22
icon text 11-23
title bar text 11-23
monitors 11-1 to 11-23
about 11-4
alarm_verif 11-11
backing up definitions 12-14
defined 11-3
defining 11-4, 11-15
GUI 11-12
JIL 11-19
filtering 11-8
filtering events 11-3

Index-12

job_filter 11-9
name 11-7
restoring definitions from backup file
12-16
sound 11-11
status events 11-9
multiple machine queues 9-24

N
n_retrys 4-16
name monitor/report attribute 11-7
NIS, troubleshooting 14-15
notification, user-defined notification
routines 13-46
notrunning condition in job definition
3-19
ntrys 3-29

O
ON_HOLD 3-12
ON_HOLD vs. ON_ICE 3-12
ON_ICE 3-12
one-time job overrides 6-26
OpcMessageGroup 13-27
OpcWaitTime 13-27
Open Client C Library 12-16
OpenView
configuring for SNMP 13-22
OpenView, configuring for SNMP 13-22
Operator Console 6-3
about 10-4
Alarm Manager dialog 10-7
Alarm Selection dialog 10-7
customizing 10-37
Alarm List column width 10-45
alarm poll time interval 10-38
atomic conditions fields 10-44

PLATINUM AutoSys User Guide for UNIX

Index

Operator Console (contd.)

customizing (contd.)
background color of variable fields
10-42
border colors 10-43
changing fonts 10-39
currently selected Job Name field
10-41
Default Report type 10-45
font selection 10-40
freeze frame at start up 10-39
icon text 10-46
Job List column widths 10-44
label font 10-40
list font 10-40
object color 10-41
Operator Console size 10-45
primary interface colors 10-43
refresh time interval 10-38, 10-43
title bar text 10-46
Job Activity Console 10-7, 10-8
Job Selection dialog 10-7
See also Job Activity Console
starting 10-7
optional job attributes 4-10
Oracle
improving database performance 12-25
SQL*Net V2 12-16
override_job 4-22
overrides, job
GUI 6-26
JIL 7-14
owner, default 2-11

PLATINUM AutoSys User Guide for UNIX

P
passwords
autosys user 2-10
database 2-10
database system administrator 12-29
permission attribute 4-17
permissions 2-3, 4-17
edit 2-12, 4-18
execute 2-13, 4-18
granting 2-13
machine 2-13
types 2-12
user 2-11
using umask 2-11
Windows NT 2-14
platinum.my file 13-24
port number for Remote Agent 13-31
priority job attribute 4-22, 9-5
profile script 3-5
profiles 4-7
ProVision
data exchange 13-33
event management 13-33

Q
QUE_WAIT status 3-11
queuing
and simple load limiting 9-19
as subset of virtual machine 9-22
jobs 9-18
multiple machine 9-24, 9-25
policies 9-18
with priority 9-20, 9-21

Index-13

 Index

R
real machines 9-3
defining 9-3
deleting 9-9
example 9-8
type 9-4
reconnecting to database 13-11
recovery
database 12-41
Sybase database 12-41
Remote Agent
auto_remote service 13-39
database connectivity 14-20
defined 1-7
Event Processor authentication 2-10
heartbeat interval 13-17
log 14-18
modifying settings for 13-38
port number 13-31
security 2-18
security, DENY_ACCESS 13-42
settings 13-38
socket connection 13-38
troubleshooting 14-13
user authentication 2-9
Remote Agent Event Processor
authentication 13-41
Remote Agent log
cleanup 13-18
name assigned 14-18
specifying directory for file 13-18
Remote Agent settings in auto.profile
13-35
remote authentication 13-41
configuring 13-40
Event Processor 2-10
user 2-9

Index-14

RemoteProFiles 13-19
reports 11-1 to 11-23
about 11-4
all_events 11-8
all_status 11-9
defined 11-3
defining 11-4, 11-15
GUI 11-12
JIL 11-19
defining - GUI 11-17
defining - JIL 11-21
filtering 11-8
filtering events 11-3
InfoReports 10-5
job_filter 11-9
name 11-7
Operator Console 10-14
status events 11-9
resource check, file space 4-24, 4-26
resource usage monitoring 13-45
resources
Calendar Facility
date range 8-34
Font Selection 8-32
icon text 8-35
Object Color 8-33
Print Command 8-35
title bar text 8-35
Window Size 8-34
Job Definition 6-30
database connection time-out 6-31
icon text 6-31
title bar text 6-31
Monitor/Browser
database connection time-out 11-22
icon text 11-23
title bar text 11-23

PLATINUM AutoSys User Guide for UNIX

Index

resources (contd.)
Operator Console 10-37, 11-22
alarm list column width 10-45
alarm poll time interval 10-38
atomic condition fields 10-44
border colors 10-43
currently selected job name field
color 10-41
default report type 10-45
font selection 10-40
freeze frame at start up 10-39
icon text 10-46
job list column widths 10-44
label font 10-40
list font 10-40
Operator Console size 10-45
primary interface color 10-43
refresh time interval 10-38
title bar text 10-46
toggle button color 10-43
variable fields background color
10-42
restart attempts, maximum number 13-27
RESTART status 3-11
restart wait time, calculating 13-28
RestartConstant 13-28
RestartFactor 13-28
restoring
calendar definitions 12-15
global variables (using autorep) 12-16
job definitions (using autorep) 12-16
machine definitions (using autorep)
12-16
monitor and browser definitions 12-16
Primary Event Processor 12-9

PLATINUM AutoSys User Guide for UNIX

rollover
Event Server 12-22
Shadow Event Processor 12-8
rstatd 13-29
Rule Specification region 8-18
Run MonBro button 11-14
run number 3-29
RUN_AUTOSYSDB 12-30
run_calendar 4-10
run_num/ntry, defined 3-30
run_window 4-11
RUNNING status 3-10
ruserok 2-9, 13-40

S
scripts
database maintenance 13-16
DBMaint 12-20
start_autodb 12-30
security 2-1, 2-3
DENY_ACCESS Remote Agent setting
13-42
granting permissions 2-13
permission types 2-12
preventing unauthorized access 2-7
Remote Agent 2-18
remote authentication 13-40
superusers, AutoSys 2-15
user permissions 2-11
select getdate 12-31
Send Event dialog 10-16
AUTOSERV instance 10-17
Cancel button 10-18
cancelling an event 10-18
Change Status 10-17
Comment field 10-17
Execute button 10-18

Index-15

 Index

Send Event dialog (contd.)

Global Name/Value 10-17
Job Name 10-17
Queue Priority 10-17
Send Priority 10-18
Signal 10-17
time of event 10-17
sendevent command 2-16
server instance 1-5
server machine 1-10
ServerVision
charge back reporting 9-18
integration 13-43
job resource usage monitoring 9-18,
13-45
load balancing 9-14
services file, Remote Agent port number
13-39
Shadow Event Processor
defined 1-6
rollover 12-8
starting 12-9
SIGHUP signal 13-29
signals, UNIX 13-30
Simple Network Management Protocol
(SNMP) 13-21
Single Server Mode 12-22
SNMP 13-21
SNMP connections 13-21
SnmpCommunity 13-22
SnmpManagerHosts 13-21
socket connection for Remote Agent
13-38
socket connection, for Remote Agent
13-39
socket time-out 13-27
sound monitor attribute 11-11

Index-16

SQL*Net V2 12-16
standard output/error append parameter
13-32
start interval between jobs 13-34
start_autodb script 12-30
start_mins 4-12
start_times 4-11
starting conditions 3-15, 3-18
in Job Activity Console 10-13
STARTING status 3-10
STARTJOB 7-6
states
job 3-10
See also status
status
job
ACTIVATED 3-10
as job dependency 3-18
FAILURE 3-11
INACTIVE 3-10
monitoring and reporting 11-9
ON_HOLD 3-12
ON_ICE 3-12
QUE_WAIT 3-11
RESTART 3-11
RUNNING 3-10
STARTING 3-10
SUCCESS 3-11
TERMINATED 3-11
tracking changes 11-9
monitor/report
failure 11-9
restart 11-9
running 11-9
starting 11-9
success 11-9
terminated 11-9

PLATINUM AutoSys User Guide for UNIX

Index

status (contd.)
processed vs. unprocessed 3-15
using in job dependencies 3-18
std_err_file 4-21
std_in_file 4-20
std_out_file 4-20
STOP_DEMON 12-7, 12-31, 12-42
success
condition in job definition 3-18
maximum exit code 3-19
SUCCESS status 3-11
Summary Report, from Operator Console
10-14
superusers 2-15
Edit Superuser, defined 2-15
Exec Superuser, defined 2-16
svarchive utility 13-45
svload command 9-15
svload configuration requirements 13-43
Sybase
accessing interactively 12-32
architecture 12-27
bundled 12-27
defining a dump device 12-35
disk dump device 12-35
dumping the database 12-39
loading the database 12-40
tape dump device 12-36
communication with 12-27
database
displaying date and time 12-34
identifying connected processes
12-33
improving performance 12-24
DB Library 12-27
DSQUERY variable 12-28
environment 12-28

PLATINUM AutoSys User Guide for UNIX

environment variable 12-28

interfaces file 12-28
server 12-27
shutdown command 12-32
SQL.INI file 12-28
starting 12-30
stopping 12-31
System 10 backup server 12-36
users 12-28
SYBASE variable 12-28
synchronizing Event Servers 12-23
syntax rules, JIL 7-3
system administrator, database 12-29
system load, maximum 9-5

T
target machine 4-8
Team Agent support 13-31, A-1
Term Calendar Rule dialog 8-17
Control region 8-24
Rescheduling Rule region 8-22
Term Calendar Viewer 8-9, 8-25
Calendar Display 8-26
Navigation Controls 8-26
term_run_time 4-14
terminated condition in job definition
3-19
TERMINATED status 3-11
test mode
output file 12-11
running in 12-10
ThirdMachine 13-14
time dependencies
in job definition 4-10
overview 3-17

Index-17

 Index

time dependencies (contd.)

setting
GUI 6-22
JIL 7-12
TimeScape 6-4
timezone 4-16
tmpfs, locking problems 13-18
transferring events between Event Servers
13-16
trapd.conf file 13-24
troubleshooting 14-1
Event Processor 14-11
Event Servers 14-3
Remote Agent 14-13
typographical conventions xxix

U
uid 2-12, 4-18
user ID 2-12, 4-18
user types
group 2-12
owner 2-12
world 2-12
user-defined
alarm callbacks 13-46
environment variables 4-7
load balancing 9-25
users, bundled Sybase 12-28
utilities, provided with AutoSys 1-12

type 9-4
using delete_machine 9-3
using insert_machine 9-3
vmstat 13-29

W
WaitTime 13-28
watch_file 4-9
watch_file_min_size 4-25
watch_interval 4-25
Windows NT
job permissions on 2-14

X
X resources, customizing Calendar Facility
8-30
XInstanceDBDropTime 13-11
xql, example scripts 12-32

Z
Zeke and AutoSys/Team Agent support
A-1 to A-26
Zeke support 13-31
ZTeamJobSupport 13-31

V
variables in a Command Job definition
4-7
virtual machines 9-3
defining 9-3, 9-9
deleting 9-10
example 9-9

Index-18

PLATINUM AutoSys User Guide for UNIX