Unicenter AutoSys Job Management for Windows and UNIX

Reference Guide 4.0

This documentation and related computer software program (hereinafter referred to as the “Documentation”) is for the end user’s informational purposes only and is subject to change or withdrawal by Computer Associates International, Inc. (“CA”) at any time.

This documentation may not be copied, transferred, reproduced, disclosed or duplicated, in whole or in part, without the prior written consent of CA. This documentation is proprietary information of CA and protected by the copyright laws of the United States and international treaties.

Notwithstanding the foregoing, licensed users may print a reasonable number of copies of this documentation for their own internal use, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the confidentiality provisions of the license for the software are permitted to have access to such copies.

This right to print copies is limited to the period during which the license for the product remains in full force and effect. Should the license terminate for any reason, it shall be the user’s responsibility to return to CA the reproduced copies or to certify to CA that same have been destroyed.

To the extent permitted by applicable law, CA provides this documentation “as is” without warranty of any kind, including without limitation, any implied warranties of merchantability, fitness for a particular purpose or noninfringement. In no event will CA be liable to the end user or any third party for any loss or damage, direct or indirect, from the use of this documentation, including without limitation, lost profits, business interruption, goodwill, or lost data, even if CA is expressly advised of such loss or damage.

The use of any product referenced in this documentation and this documentation is governed by the end user’s applicable license agreement.

The manufacturer of this documentation is Computer Associates International, Inc.

Provided with “Restricted Rights” as set forth in 48 C.F.R. Section 12.212, 48 C.F.R. Sections 52.227-19(c)(1) and (2) or DFARS Section 252.227-7013(c)(1)(ii) or applicable successor provisions.

2002 Computer Associates International, Inc. (CA)

All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

Contents

Chapter 1: Preface Assumptions ................................................................................. 1–1

Notational Conventions ................................................................... 1–2 Related Publications .......................................................................... 1–3

Chapter 2: AutoSys Commands Functional Listing of AutoSys Commands....................................................... 2–2 archive_events ............................................................................... 2–3

Function ................................................................................. 2–3 Syntax ................................................................................... 2–3 Description............................................................................... 2–3 Options .................................................................................. 2–4 Examples................................................................................. 2–6

autocal....................................................................................... 2–7 Function ................................................................................. 2–7 Syntax ................................................................................... 2–7 Description............................................................................... 2–7 Example ................................................................................. 2–8

autocal_asc................................................................................... 2–9 Function ................................................................................. 2–9 Syntax ................................................................................... 2–9 Description............................................................................... 2–9 Example ................................................................................ 2–10

autocons .................................................................................... 2–12 Function ................................................................................ 2–12 Syntax .................................................................................. 2–12

Contents iii

Description ............................................................................. 2–12 Example ................................................................................ 2–13

autoflags ................................................................................... 2–14 Function................................................................................ 2–14 Syntax.................................................................................. 2–14 Description ............................................................................. 2–14 Options................................................................................. 2–14 Example ................................................................................ 2–15

autoping ................................................................................... 2–16 Function................................................................................ 2–16 Syntax.................................................................................. 2–16 Description ............................................................................. 2–16 Options................................................................................. 2–17 Example ................................................................................ 2–18

autorep..................................................................................... 2–19 Function................................................................................ 2–19 Syntax.................................................................................. 2–19 Description ............................................................................. 2–19 Job Run Summary ....................................................................... 2–19 Job Run Detail........................................................................... 2–19 Machine Definition and Status In the Database ............................................. 2–20 Job Override Information................................................................. 2–20 Columns In the autorep Report ........................................................... 2–20 Status Abbreviations..................................................................... 2–21 Event State Abbreviations ................................................................ 2–22 Options................................................................................. 2–23 Examples ............................................................................... 2–26

autosc ...................................................................................... 2–30 Function................................................................................ 2–30 Syntax.................................................................................. 2–30 Description ............................................................................. 2–30 Example ................................................................................ 2–30

autostatus .................................................................................. 2–31 Function................................................................................ 2–31 Syntax.................................................................................. 2–31

iv Reference Guide

Description.............................................................................. 2–31 Options ................................................................................. 2–31 Examples................................................................................ 2–32

autosyslog .................................................................................. 2–35 Function ................................................................................ 2–35 Syntax .................................................................................. 2–35 Description.............................................................................. 2–35 Remote Agent log ........................................................................ 2–35 Event Processor Log...................................................................... 2–36 Options ................................................................................. 2–36 Examples................................................................................ 2–37

autosys_secure .............................................................................. 2–38 Function ................................................................................ 2–38 Syntax .................................................................................. 2–38 Description.............................................................................. 2–38

Edit Superuser and Exec Superuser .................................................... 2–38 AutoSys Database Password .......................................................... 2–39 Remote Authentication Method........................................................ 2–39 Windows User Passwords............................................................. 2–40

Running autosys_secure .................................................................. 2–40 Running autosys_secure in Interactive Mode............................................ 2–40 Running autosys_secure from the Command Line ....................................... 2–41 Edit and Exec Superusers ............................................................. 2–42 AutoSys Database Password .......................................................... 2–42 Remote Authentication Methods....................................................... 2–43 Remote Agent User Authentication Only ............................................... 2–43 UNIX ruserok Authentication Only .................................................... 2–44 Windows Remote Agent User Authentication ........................................... 2–44 AutoSys Event Processor Authentication Only .......................................... 2–45 Both Remote Agent User and Event Processor Authentication ............................ 2–45 Both UNIX and AutoSys Authentication Methods ....................................... 2–46 Creating AutoSys user@host_or_domain Passwords ..................................... 2–46 Changing AutoSys user@host_or_domain Passwords.................................... 2–46 Deleting AutoSys user@host_or_domain Passwords ..................................... 2–47

Options ................................................................................. 2–47

Contents v

Example ................................................................................ 2–48 Autotimezone............................................................................... 2–49

Function................................................................................ 2–49 Syntax.................................................................................. 2–49 Description ............................................................................. 2–49 TZ Variable Syntax ...................................................................... 2–51 Options................................................................................. 2–53 Examples ............................................................................... 2–53

autotrack ................................................................................... 2–54 Function................................................................................ 2–54 Syntax.................................................................................. 2–54 Description ............................................................................. 2–54 Options................................................................................. 2–56 Examples ............................................................................... 2–59

chase....................................................................................... 2–61 Function................................................................................ 2–61 Syntax.................................................................................. 2–61 Description ............................................................................. 2–61

Running chase Automatically ......................................................... 2–63 Options................................................................................. 2–64 Example ................................................................................ 2–64

chk_auto_up................................................................................ 2–65 Function................................................................................ 2–65 Syntax.................................................................................. 2–65 Description ............................................................................. 2–65 Options................................................................................. 2–66 Return Codes ........................................................................... 2–66 Example ................................................................................ 2–67

chk_cond (SP)............................................................................... 2–68 Function................................................................................ 2–68 Syntax.................................................................................. 2–68 Description ............................................................................. 2–68 Options................................................................................. 2–68 Example ................................................................................ 2–69

clean_files .................................................................................. 2–70

vi Reference Guide

Function ................................................................................ 2–70 Syntax .................................................................................. 2–70 Description.............................................................................. 2–70 Options ................................................................................. 2–71 Example ................................................................................ 2–71

cron2jil ..................................................................................... 2–72 Function ................................................................................ 2–72 Syntax .................................................................................. 2–72 Description.............................................................................. 2–72 Options ................................................................................. 2–73 Example ................................................................................ 2–73

dbstatistics .................................................................................. 2–74 Function ................................................................................ 2–74 Syntax .................................................................................. 2–74 Description.............................................................................. 2–74

eventor ..................................................................................... 2–76 Function ................................................................................ 2–76 Syntax .................................................................................. 2–76 Description.............................................................................. 2–76

Log Files ............................................................................ 2–77 Options ................................................................................. 2–77 Examples................................................................................ 2–79

gatekeeper .................................................................................. 2–80 Function ................................................................................ 2–80 Syntax .................................................................................. 2–80 Description.............................................................................. 2–80 Example ................................................................................ 2–81

jil........................................................................................... 2–82 Function ................................................................................ 2–82 Syntax .................................................................................. 2–82 Description.............................................................................. 2–82 Options ................................................................................. 2–85 Examples................................................................................ 2–86

job_depends................................................................................. 2–87 Function ................................................................................ 2–87

Contents vii

Syntax.................................................................................. 2–87 Description ............................................................................. 2–87 Options................................................................................. 2–87 Example ................................................................................ 2–90

monbro .................................................................................... 2–94 Function................................................................................ 2–94 Syntax.................................................................................. 2–94 Description ............................................................................. 2–94 Options................................................................................. 2–95 Examples ............................................................................... 2–96

record_sounds .............................................................................. 2–97 Function................................................................................ 2–97 Syntax.................................................................................. 2–97 Description ............................................................................. 2–97

To Record Sounds: ................................................................... 2–98 Example ................................................................................ 2–98

sendevent .................................................................................. 2–99 Function................................................................................ 2–99 Syntax.................................................................................. 2–99 Description ............................................................................. 2–99 Options................................................................................ 2–100 Examples .............................................................................. 2–108

sendevent (SP) ............................................................................. 2–111 Function............................................................................... 2–111 Syntax................................................................................. 2–111 Description ............................................................................ 2–111 Options................................................................................ 2–112 Examples .............................................................................. 2–113

viii Reference Guide

xql ........................................................................................ 2–114 Function ............................................................................... 2–114 Syntax ................................................................................. 2–114 Description............................................................................. 2–114

Batch Mode......................................................................... 2–115 Interactive Mode .................................................................... 2–115

Options ................................................................................ 2–116 Examples............................................................................... 2–119

Chapter 3: JIL/GUI Definitions JIL Sub-commands............................................................................ 3–2 Job Attributes ................................................................................ 3–3 alarm_if_fail.................................................................................. 3–4

GUI Path ................................................................................. 3–4 JIL Syntax ................................................................................ 3–4 Description............................................................................... 3–4 Where Applicable......................................................................... 3–4 Values ................................................................................... 3–5 Example ................................................................................. 3–5

auto_delete................................................................................... 3–6 GUI Path ................................................................................. 3–6 JIL Syntax ................................................................................ 3–6 Description............................................................................... 3–6 Where Applicable......................................................................... 3–6 Values ................................................................................... 3–7 Example ................................................................................. 3–7

auto_hold .................................................................................... 3–8 GUI Path ................................................................................. 3–8 JIL Syntax ................................................................................ 3–8 Description............................................................................... 3–8 Where Applicable......................................................................... 3–8 Values ................................................................................... 3–9 Example ................................................................................. 3–9

avg_runtime (JIL only) ....................................................................... 3–10

Contents ix

JIL Syntax............................................................................... 3–10 Description ............................................................................. 3–10 Where Applicable ....................................................................... 3–10 Values.................................................................................. 3–10 Example ................................................................................ 3–11

box_failure ................................................................................. 3–12 GUI Path ............................................................................... 3–12 JIL Syntax............................................................................... 3–12 Description ............................................................................. 3–12 Where Applicable ....................................................................... 3–12 Values.................................................................................. 3–13 Examples ............................................................................... 3–13

box_name .................................................................................. 3–14 GUI Path ............................................................................... 3–14 JIL Syntax............................................................................... 3–14 Description ............................................................................. 3–14 Where Applicable ....................................................................... 3–14 Values.................................................................................. 3–15 Example ................................................................................ 3–15

box_success................................................................................. 3–16 GUI Path ............................................................................... 3–16 JIL Syntax............................................................................... 3–16 Description ............................................................................. 3–16 Where Applicable ....................................................................... 3–17 Values.................................................................................. 3–17 Examples ............................................................................... 3–17

box_terminator.............................................................................. 3–18 GUI Path ............................................................................... 3–18 JIL Syntax............................................................................... 3–18 Description ............................................................................. 3–18 Where Applicable ....................................................................... 3–18 Values.................................................................................. 3–19 Example ................................................................................ 3–19

chk_files.................................................................................... 3–20 GUI Path ............................................................................... 3–20

x Reference Guide

JIL Syntax ............................................................................... 3–20 Description.............................................................................. 3–20 Where Applicable........................................................................ 3–21 Values .................................................................................. 3–22 Example ................................................................................ 3–23

command ................................................................................... 3–24 GUI Path ................................................................................ 3–24 JIL Syntax ............................................................................... 3–24 Description.............................................................................. 3–24 Where Applicable........................................................................ 3–27 Values .................................................................................. 3–28 Examples................................................................................ 3–28

condition ................................................................................... 3–30 GUI Path ................................................................................ 3–30 JIL Syntax ............................................................................... 3–30 Description.............................................................................. 3–30

Job Status Dependencies .............................................................. 3–31 Cross-Instance Job Dependencies ...................................................... 3–33 Exit Code Dependencies .............................................................. 3–34 Global Variable Dependencies ......................................................... 3–35

Where Applicable........................................................................ 3–36 Values .................................................................................. 3–36 Examples................................................................................ 3–36

date_conditions.............................................................................. 3–38 GUI Path ................................................................................ 3–38 JIL Syntax ............................................................................... 3–38 Description.............................................................................. 3–38 Where Applicable........................................................................ 3–38 Values .................................................................................. 3–39 Example ................................................................................ 3–39

days_of_week ............................................................................... 3–40 GUI Path ................................................................................ 3–40 JIL Syntax ............................................................................... 3–40 Description.............................................................................. 3–40 Where Applicable........................................................................ 3–40

Contents xi

Values.................................................................................. 3–41 Examples ............................................................................... 3–41

delete_box.................................................................................. 3–42 Function................................................................................ 3–42 GUI Path ............................................................................... 3–42 Description ............................................................................. 3–42 Values.................................................................................. 3–42 Example ................................................................................ 3–42

delete_job .................................................................................. 3–43 Function................................................................................ 3–43 GUI Path ............................................................................... 3–43 JIL Syntax............................................................................... 3–43 Description ............................................................................. 3–43 Values.................................................................................. 3–43 Example ................................................................................ 3–44

description ................................................................................. 3–45 GUI Path ............................................................................... 3–45 JIL Syntax............................................................................... 3–45 Description ............................................................................. 3–45 Where Applicable ....................................................................... 3–45 Values.................................................................................. 3–45 Example ................................................................................ 3–46

exclude_calendar............................................................................ 3–47 GUI Path ............................................................................... 3–47 JIL Syntax............................................................................... 3–47 Description ............................................................................. 3–47 Where Applicable ....................................................................... 3–47 Values.................................................................................. 3–48 Example ................................................................................ 3–48

heartbeat_interval ........................................................................... 3–49 GUI Path ............................................................................... 3–49 JIL Syntax............................................................................... 3–49 Description ............................................................................. 3–49 Where Applicable ....................................................................... 3–50 Values.................................................................................. 3–50

xii Reference Guide

Example ................................................................................ 3–50 insert_job ................................................................................... 3–51

Function ................................................................................ 3–51 GUI Path ................................................................................ 3–51 JIL Syntax ............................................................................... 3–51 Description.............................................................................. 3–52 Values .................................................................................. 3–52 Examples................................................................................ 3–53

job_load .................................................................................... 3–54 GUI Path ................................................................................ 3–54 JIL Syntax ............................................................................... 3–54 Description.............................................................................. 3–54 Where Applicable........................................................................ 3–55 Values .................................................................................. 3–55 Example ................................................................................ 3–55

job_name (GUI only) ......................................................................... 3–56 GUI Path ................................................................................ 3–56 JIL Syntax ............................................................................... 3–56 Description.............................................................................. 3–56 Where Applicable........................................................................ 3–56 Values .................................................................................. 3–56

job_terminator............................................................................... 3–57 GUI Path ................................................................................ 3–57 JIL Syntax ............................................................................... 3–57 Description.............................................................................. 3–57 Where Applicable........................................................................ 3–58 Values .................................................................................. 3–58 Example ................................................................................ 3–58

job_type .................................................................................... 3–59 GUI Path ................................................................................ 3–59 JIL Syntax ............................................................................... 3–59 Description.............................................................................. 3–59 Where Applicable........................................................................ 3–59 Values .................................................................................. 3–60 Example ................................................................................ 3–60

Contents xiii

machine .................................................................................... 3–61 GUI Path ............................................................................... 3–61 JIL Syntax............................................................................... 3–61 Description ............................................................................. 3–61 Where Applicable ....................................................................... 3–62 Values.................................................................................. 3–63 Examples ............................................................................... 3–63

max_exit_success............................................................................ 3–64 GUI Path ............................................................................... 3–64 JIL Syntax............................................................................... 3–64 Description ............................................................................. 3–64 Where Applicable ....................................................................... 3–64 Values.................................................................................. 3–64 Example ................................................................................ 3–65

max_run_alarm ............................................................................. 3–66 GUI Path ............................................................................... 3–66 JIL Syntax............................................................................... 3–66 Description ............................................................................. 3–66 Where Applicable ....................................................................... 3–67 Values.................................................................................. 3–67 Example ................................................................................ 3–67

min_run_alarm ............................................................................. 3–68 GUI Path ............................................................................... 3–68 JIL Syntax............................................................................... 3–68 Description ............................................................................. 3–68 Where Applicable ....................................................................... 3–68 Values.................................................................................. 3–69 Example ................................................................................ 3–69

n_retrys .................................................................................... 3–70 GUI Path ............................................................................... 3–70 JIL Syntax............................................................................... 3–70 Description ............................................................................. 3–70 Where Applicable ....................................................................... 3–71 Values.................................................................................. 3–71 Example ................................................................................ 3–72

xiv Reference Guide

override_job................................................................................. 3–73 GUI Path ................................................................................ 3–73 Function ................................................................................ 3–73 JIL Syntax ............................................................................... 3–73 Description.............................................................................. 3–73 Values .................................................................................. 3–75 Examples................................................................................ 3–75

owner ...................................................................................... 3–76 GUI Path ................................................................................ 3–76 JIL Syntax ............................................................................... 3–76 Description.............................................................................. 3–76 Where Applicable........................................................................ 3–78 Values .................................................................................. 3–78 Example ................................................................................ 3–80

permission .................................................................................. 3–81 GUI Path ................................................................................ 3–81 JIL Syntax ............................................................................... 3–81 Description.............................................................................. 3–81

User Types .......................................................................... 3–82 Permission Types .................................................................... 3–82 User and Permission Types............................................................ 3–83

Where Applicable........................................................................ 3–84 Values .................................................................................. 3–84 Job Permissions and Windows ............................................................ 3–85 Example ................................................................................ 3–85

priority ..................................................................................... 3–86 GUI Path ................................................................................ 3–86 JIL Syntax ............................................................................... 3–86 Description.............................................................................. 3–86 Where Applicable........................................................................ 3–87 Values .................................................................................. 3–87 Examples................................................................................ 3–88

profile ...................................................................................... 3–89 GUI Path ................................................................................ 3–89 JIL Syntax ............................................................................... 3–89

Contents xv

Description ............................................................................. 3–89 Where Applicable ....................................................................... 3–91 Values.................................................................................. 3–92 Examples ............................................................................... 3–92

run_calendar................................................................................ 3–93 GUI Path ............................................................................... 3–93 JIL Syntax............................................................................... 3–93 Description ............................................................................. 3–93 Where Applicable ....................................................................... 3–93 Values.................................................................................. 3–94 Example ................................................................................ 3–94

run_window................................................................................ 3–95 GUI Path ............................................................................... 3–95 JIL Syntax............................................................................... 3–95 Description ............................................................................. 3–95

Run Windows in Boxes............................................................... 3–95 Where Applicable ....................................................................... 3–96 Values.................................................................................. 3–96 Example ................................................................................ 3–97

start_mins .................................................................................. 3–98 GUI Path ............................................................................... 3–98 JIL Syntax............................................................................... 3–98 Description ............................................................................. 3–98 Where Applicable ....................................................................... 3–98 Values.................................................................................. 3–98 Example ................................................................................ 3–99

start_times................................................................................. 3–100 GUI Path .............................................................................. 3–100 JIL Syntax.............................................................................. 3–100 Description ............................................................................ 3–100 Where Applicable ...................................................................... 3–100 Values................................................................................. 3–101 Example ............................................................................... 3–101

std_err_file ................................................................................ 3–102 GUI Path .............................................................................. 3–102

xvi Reference Guide

JIL Syntax .............................................................................. 3–102 Description............................................................................. 3–102 Where Applicable....................................................................... 3–103 Values ................................................................................. 3–103 Examples............................................................................... 3–104

std_in_file.................................................................................. 3–106 GUI Path ............................................................................... 3–106 JIL Syntax .............................................................................. 3–106 Description............................................................................. 3–106 Where Applicable....................................................................... 3–106 Values ................................................................................. 3–106 Examples............................................................................... 3–107

std_out_file ................................................................................ 3–108 GUI Path ............................................................................... 3–108 JIL Syntax .............................................................................. 3–108 Description............................................................................. 3–108 Where Applicable....................................................................... 3–109 Values ................................................................................. 3–109 Examples............................................................................... 3–110

term_run_time ............................................................................. 3–111 GUI Path ............................................................................... 3–111 JIL Syntax .............................................................................. 3–111 Description............................................................................. 3–111 Where Applicable....................................................................... 3–111 Values ................................................................................. 3–112 Example ............................................................................... 3–112

timezone................................................................................... 3–113 GUI Path ............................................................................... 3–113 JIL Syntax .............................................................................. 3–113 Description............................................................................. 3–113 Where Applicable....................................................................... 3–113 Values ................................................................................. 3–114 Example ............................................................................... 3–116

update_job ................................................................................. 3–117 Function ............................................................................... 3–117

Contents xvii

GUI Path .............................................................................. 3–117 JIL Syntax.............................................................................. 3–117 Description ............................................................................ 3–117 Values................................................................................. 3–117 Example ............................................................................... 3–118

watch_file ................................................................................. 3–119 GUI Path .............................................................................. 3–119 JIL Syntax.............................................................................. 3–119 Description ............................................................................ 3–119 Where Applicable ...................................................................... 3–120 Values................................................................................. 3–120 Examples .............................................................................. 3–121

watch_file_min_size ........................................................................ 3–122 GUI Path .............................................................................. 3–122 JIL Syntax.............................................................................. 3–122 Description ............................................................................ 3–122 Where Applicable ...................................................................... 3–122 Values................................................................................. 3–123 Example ............................................................................... 3–123

watch_interval ............................................................................. 3–124 GUI Path .............................................................................. 3–124 JIL Syntax.............................................................................. 3–124 Description ............................................................................ 3–124 Where Applicable ...................................................................... 3–124 Values................................................................................. 3–125 Example ............................................................................... 3–125

Chapter 4: JIL Machine Definitions JIL Sub-commands ............................................................................4–1 Machine Attributes ............................................................................4–1 delete_machine ...............................................................................4–2

Function..................................................................................4–2 JIL Syntax.................................................................................4–2 Description ...............................................................................4–2

xviii Reference Guide

Values ................................................................................... 4–2 Examples................................................................................. 4–3

factor ........................................................................................ 4–4 JIL Syntax ................................................................................ 4–4 Description............................................................................... 4–4 Where Applicable......................................................................... 4–4 Values ................................................................................... 4–4 Examples................................................................................. 4–5

insert_machine ............................................................................... 4–6 Function ................................................................................. 4–6 JIL Syntax ................................................................................ 4–6 Description............................................................................... 4–6 Values ................................................................................... 4–8 Examples................................................................................. 4–8

machine .................................................................................... 4–12 JIL Syntax ............................................................................... 4–12 Description.............................................................................. 4–12 Where Applicable........................................................................ 4–12 Values .................................................................................. 4–12 Examples................................................................................ 4–13

max_load ................................................................................... 4–15 JIL Syntax ............................................................................... 4–15 Description.............................................................................. 4–15 Where Applicable........................................................................ 4–16 Values .................................................................................. 4–16 Examples................................................................................ 4–16

type ........................................................................................ 4–17 JIL Syntax ............................................................................... 4–17 Description.............................................................................. 4–17 Where Applicable........................................................................ 4–17 Values .................................................................................. 4–17

Contents xix

Chapter 5: JIL/GUI Monitor/Report Definitions JIL Sub-commands ............................................................................5–1 Monitor and Report Attributes .................................................................5–1 after_time ....................................................................................5–2

GUI Path .................................................................................5–2 JIL Syntax.................................................................................5–2 Description ...............................................................................5–2 Where Applicable .........................................................................5–2 Values....................................................................................5–3 Example ..................................................................................5–3

alarm ........................................................................................5–4 GUI Path .................................................................................5–4 JIL Syntax.................................................................................5–4 Description ...............................................................................5–4 Where Applicable .........................................................................5–4 Values....................................................................................5–4 Example ..................................................................................5–5

alarm_verif ...................................................................................5–6 GUI Path .................................................................................5–6 JIL Syntax.................................................................................5–6 Description ...............................................................................5–6 Where Applicable .........................................................................5–6 Values....................................................................................5–6 Example ..................................................................................5–7

all_events.....................................................................................5–8 GUI Path .................................................................................5–8 JIL Syntax.................................................................................5–8 Description ...............................................................................5–8 Where Applicable .........................................................................5–9 Values....................................................................................5–9 Example ..................................................................................5–9

all_status ................................................................................... 5–10 GUI Path ............................................................................... 5–10 JIL Syntax............................................................................... 5–10 Description ............................................................................. 5–10

xx Reference Guide

Where Applicable........................................................................ 5–10 Values .................................................................................. 5–11 Example ................................................................................ 5–11

currun ...................................................................................... 5–12 GUI Path ................................................................................ 5–12 JIL Syntax ............................................................................... 5–12 Description.............................................................................. 5–12 Where Applicable........................................................................ 5–13 Values .................................................................................. 5–13 Example ................................................................................ 5–13

delete_monbro .............................................................................. 5–14 GUI Path ................................................................................ 5–14 Function ................................................................................ 5–14 JIL Syntax ............................................................................... 5–14 Description.............................................................................. 5–14 Values .................................................................................. 5–14 Example ................................................................................ 5–14

failure ...................................................................................... 5–15 GUI Path ................................................................................ 5–15 JIL Syntax ............................................................................... 5–15 Description.............................................................................. 5–15 Where Applicable........................................................................ 5–15 Values .................................................................................. 5–15 Example ................................................................................ 5–16

insert_monbro............................................................................... 5–17 Function ................................................................................ 5–17 JIL Syntax ............................................................................... 5–17 Description.............................................................................. 5–17 Values .................................................................................. 5–18 Examples................................................................................ 5–19

job_filter .................................................................................... 5–20 GUI Path ................................................................................ 5–20 JIL Syntax ............................................................................... 5–20 Description.............................................................................. 5–20 Where Applicable........................................................................ 5–20

Contents xxi

Values.................................................................................. 5–21 Example ................................................................................ 5–21

job_name ................................................................................... 5–22 GUI Path ............................................................................... 5–22 JIL Syntax............................................................................... 5–22 Description ............................................................................. 5–22 Where Applicable ....................................................................... 5–22 Values.................................................................................. 5–22 Example ................................................................................ 5–23

mode....................................................................................... 5–24 GUI Path ............................................................................... 5–24 JIL Syntax............................................................................... 5–24 Description ............................................................................. 5–24 Where Applicable ....................................................................... 5–24 Values.................................................................................. 5–24 Example ................................................................................ 5–25

monbro_name (GUI only) .................................................................... 5–26 GUI Path ............................................................................... 5–26 JIL Syntax............................................................................... 5–26 Description ............................................................................. 5–26 Where Applicable ....................................................................... 5–26 Values.................................................................................. 5–27

restart ...................................................................................... 5–28 GUI Path ............................................................................... 5–28 JIL Syntax............................................................................... 5–28 Description ............................................................................. 5–28 Where Applicable ....................................................................... 5–28 Values.................................................................................. 5–28 Example ................................................................................ 5–29

running .................................................................................... 5–30 GUI Path ............................................................................... 5–30 JIL Syntax............................................................................... 5–30 Description ............................................................................. 5–30 Where Applicable ....................................................................... 5–30 Values.................................................................................. 5–30

xxii Reference Guide

Example ................................................................................ 5–31 sound ...................................................................................... 5–32

GUI Path ................................................................................ 5–32 JIL Syntax ............................................................................... 5–32 Description.............................................................................. 5–32 Where Applicable........................................................................ 5–32 Values .................................................................................. 5–33 Example ................................................................................ 5–33

starting ..................................................................................... 5–34 GUI Path ................................................................................ 5–34 JIL Syntax ............................................................................... 5–34 Description.............................................................................. 5–34 Where Applicable........................................................................ 5–34 Values .................................................................................. 5–34 Example ................................................................................ 5–35

success...................................................................................... 5–36 GUI Path ................................................................................ 5–36 JIL Syntax ............................................................................... 5–36 Description.............................................................................. 5–36 Where Applicable........................................................................ 5–36 Values .................................................................................. 5–36 Example ................................................................................ 5–37

terminated .................................................................................. 5–38 GUI Path ................................................................................ 5–38 JIL Syntax ............................................................................... 5–38 Description.............................................................................. 5–38 Where Applicable........................................................................ 5–38 Values .................................................................................. 5–38 Example ................................................................................ 5–39

Contents xxiii

update_monbro ............................................................................. 5–40 GUI Path ............................................................................... 5–40 Function................................................................................ 5–40 JIL Syntax............................................................................... 5–40 Description ............................................................................. 5–40 Values.................................................................................. 5–40 Example ................................................................................ 5–41

Appendix A: System States Events....................................................................................... A–1

ALARM (106) ............................................................................ A–1 CHANGE_PRIORITY (120)................................................................ A–1 CHANGE_STATUS (101).................................................................. A–2 CHECK_HEARTBEAT (116)............................................................... A–2 CHK_BOX_TERM (118) ................................................................... A–2 CHK_MAX_ALARM (114) ................................................................ A–2 CHK_RUN_WINDOW (122)............................................................... A–2 COMMENT (117)......................................................................... A–2 DELETEJOB (119) ........................................................................ A–2 EXTERNAL_DEPENDENCY (127) ......................................................... A–3 FORCE_STARTJOB (108).................................................................. A–3 HEARTBEAT (115) ....................................................................... A–3 JOB_ON_ICE (110) ....................................................................... A–3 JOB_OFF_ICE (111) ....................................................................... A–3 JOB_ON_HOLD (112)..................................................................... A–3 JOB_OFF_HOLD (113) .................................................................... A–4 KILLJOB (105)............................................................................ A–4 REFRESH_BROKER (129) ................................................................. A–4 RESEND_EXTERNAL_STATUS (128) ...................................................... A–5 SET_GLOBAL (125)....................................................................... A–5 SEND_SIGNAL(126)...................................................................... A–5 STARTJOB (107).......................................................................... A–5 STOP_DEMON (109) ..................................................................... A–5

Status ....................................................................................... A–6

xxiv Reference Guide

ACTIVATED (9) ......................................................................... A–6 FAILURE (5)............................................................................. A–6 INACTIVE (8) ........................................................................... A–6 ON_HOLD (11) .......................................................................... A–6 ON_ICE (7).............................................................................. A–6 QUE_WAIT (12) ......................................................................... A–7 RESTART (10) ........................................................................... A–7 RUNNING (1) ........................................................................... A–7 STARTING (3) ........................................................................... A–7 SUCCESS (4) ............................................................................ A–7 TERMINATED (6) ....................................................................... A–7

Alarms ..................................................................................... A–8 ALREADY_RUNNING (528).............................................................. A–8 AUTO_PING (526) ....................................................................... A–8 CHASE (514) ............................................................................ A–8 DATABASE_COMM (516) ................................................................ A–8 DB_PROBLEM (523) ..................................................................... A–8 DB_ROLLOVER (519) .................................................................... A–8 DUPLICATE_EVENT (524) ............................................................... A–9 EP_HIGH_AVAIL (522) .................................................................. A–9 EP_ROLLOVER (520)..................................................................... A–9 EP_SHUTDOWN (521) ................................................................... A–9 EVENT_HDLR_ERROR (507) ............................................................. A–9 EVENT_QUE_ERROR (508)............................................................... A–9 EXTERN_DEPS_ERROR (529)............................................................. A–9 FORKFAIL (501) ........................................................................ A–10 INSTANCE_UNAVAILABLE (525) ....................................................... A–10 JOBFAILURE (503) ...................................................................... A–10 JOBNOT_ONICEHOLD (509) ............................................................ A–10 MAX_RETRYS (505)..................................................................... A–11 MAXRUNALARM (510) ................................................................. A–11 MINRUNALARM (502) ................................................................. A–11 MISSING_HEARTBEAT (513)............................................................ A–11 MULTIPLE_EP_SHUTDOWN (530) ...................................................... A–11 RESOURCE (512) ....................................................................... A–12

Contents xxv

STARTJOBFAIL (506) .................................................................... A–12 VERSION_MISMATCH (518)............................................................. A–12

AutoSys Exit Codes ......................................................................... A–13

Appendix B: Database Tables and Codes AutoSys Tables and Views .................................................................... B–1

alarmode ................................................................................ B–2 alarm.................................................................................... B–2 audit_info ............................................................................... B–2 audit_msg ............................................................................... B–2 avg_job_runs............................................................................. B–2 calendar ................................................................................. B–2 chase .................................................................................... B–3 cred ..................................................................................... B–3 event .................................................................................... B–3 event0 ................................................................................... B–3 event2 ................................................................................... B–3 eventvu.................................................................................. B–4 ext_job .................................................................................. B–4 glob ..................................................................................... B–4 intcodes ................................................................................. B–4 job ...................................................................................... B–4 job2 ..................................................................................... B–4 job_cond................................................................................. B–5 job_runs ................................................................................. B–5 job_status................................................................................ B–5 jobst..................................................................................... B–5 keymaster ............................................................................... B–5 last_Eoid_counter ........................................................................ B–5 machine ................................................................................. B–6 monbro.................................................................................. B–6 msg_ack ................................................................................. B–6 next_oid ................................................................................. B–6 next_run_num ........................................................................... B–6

xxvi Reference Guide

overjob...................................................................................B–6 req_job...................................................................................B–6 restart....................................................................................B–7 svarchive_tbl .............................................................................B–7 svarchive_vw.............................................................................B–7 timezones ................................................................................B–7 wait_que .................................................................................B–7

AutoSys Database Numeric Codes .............................................................B–8 Event Codes ..............................................................................B–8

Event Status Codes ...........................................................................B–9 Event que_status Codes ......................................................................B–10 Alarm Codes ................................................................................B–10 Alarm State Codes ...........................................................................B–12

Appendix C: AutoSys API Accessing Events from the Database ............................................................C–2

get_auto_event ( ) .........................................................................C–4 Name ................................................................................C–4 Prototype.............................................................................C–4 Synopsis..............................................................................C–4 Description ...........................................................................C–4 Sample ...............................................................................C–5

Return Values ............................................................................C–5 Sending Heartbeats ...........................................................................C–6

autoheartbeat ( ) ..........................................................................C–7 Name ................................................................................C–7 Prototype.............................................................................C–7 Synopsis..............................................................................C–7

Description...............................................................................C–7 Return Values ............................................................................C–7

Contents xxvii

Chapter

1 Preface

The Unicenter AutoSys Job Management for Windows and UNIX Reference Guide is intended for system administrators and operations personnel who will be responsible for defining jobs to AutoSys, and monitoring and managing these jobs. It lists the AutoSys system states and commands, and it lists job, machine, monitor, and report definition parameters.

This document covers the reference material for AutoSys, the scheduling and operations automation software for distributed computing environments.

Assumptions

This guide assumes familiarity with AutoSys and UNIX or Windows, and the operating system on which jobs will be scheduled, and it assumes that you have already installed AutoSys using the Unicenter AutoSys Job Management for Windows Installation Guide, or the Unicenter AutoSys Job Management for UNIX Installation Guide.

Preface 1–1

Assumptions

Notational Conventions

The majority of the information provided in this guide applies generically to both the Windows and UNIX platforms. However, when information is specific to one of these, the appropriate platform identifier, as shown below, accompanies it.

This image is associated with information that is specific only to the Microsoft Windows operating system.

Unless otherwise noted, the term Windows refers to any Microsoft Windows operating system supported by Unicenter.

This image is associated with information that is specific only to UNIX platforms.

The small shaded box ( ) designates the end of the platform-specific information.

In this guide, the term Windows refers to Microsoft Windows operating systems Windows NT, Windows 2000, and Windows XP Professional. Unless specifically designated, Windows refers to any Microsoft Windows operating system supported by AutoSys.

1–2 Reference Guide

Related Publications

Related Publications As you use the Unicenter AutoSys Job Management for Windows and UNIX Reference Guide, you may find it helpful to have these additional books available for reference:

■ Unicenter AutoSys Job Management Release Summary, which provides important information about this version.

■ Unicenter AutoSys Job Management Upgrade for Windows Guide, which describes how to upgrade to the current version of AutoSys.

■ Unicenter AutoSys Job Management Upgrade for UNIX Guide, which describes how to upgrade to the current version of AutoSys.

■ Unicenter AutoSys Job Management for Windows Installation Guide, which describes the basic AutoSys configurations, how to install AutoSys, including how to configure AutoSys components, databases, and high-availability features, as well as entering license keys.

■ Unicenter AutoSys Job Management for UNIX Installation Guide, which describes the basic AutoSys configurations, how to install AutoSys, including how to configure AutoSys components, databases, and high-availability features, as well as entering license keys

■ Unicenter AutoSys Job Management for Windows User Guide, which describes how to define, run, monitor and report on jobs. In addition it describes how to run and manage AutoSys, and covers AutoSys security and the AutoSys Administrator.

■ Unicenter AutoSys Job Management for UNIX User Guide, which describes how to define, run, monitor and report on jobs. In addition it describes how to run and manage AutoSys, and covers AutoSys security and the AutoSys Administrator.

Preface 1–3

Chapter

2 AutoSys Commands

This chapter provides a task oriented list of AutoSys commands followed by an alphabetical listing of all the commands used to control, configure, and report on AutoSys jobs.

You can execute AutoSys commands in an AutoSys Instance Command Prompt window, using options and arguments to specify exactly what you want them to do. You can also embed many of these commands within batch files.

WARNING! You must use the AutoSys Instance Command Prompt, located in the AutoSys program group, to execute AutoSys commands. This Command Prompt presets all of the AutoSys environment variables for that instance. Commands will fail to run if executed from an MS-DOS Command Prompt.

Note: When issuing commands that will execute on a different operating system, for example: Windows to UNIX, you must use the syntax appropriate to the operating system on which the job will run.

You can execute AutoSys commands at the UNIX operating system prompt, using options and arguments to specify exactly what you want them to do. You can also embed many of these commands within shell scripts. After you are familiar with the commands in this chapter, you can create aliases for those commands you will use frequently, such as the sendevent command that is used for starting jobs.

Note: The command reference found in this chapter is also available online, by way of the UNIX man command. For example, to access the reference page for the sendevent command, enter:

man sendevent

If this does not display the proper man page, it is because the MANPATH environment variable is not set correctly. This variable is usually set in the $AUTOUSER/autosys.* files used for setting up the environment for AutoSys (* = .csh.host name, .sh.host name, or ksh.host name).

AutoSys Commands 2–1

Functional Listing of AutoSys Commands

Functional Listing of AutoSys Commands

This section lists which AutoSys commands to use for specific tasks. All commands are for both Windows and UNIX, unless otherwise specified.

Task Command

Accessing Sybase xql

Checking System Status autoflags

autoping

autosyslog

chase

chk_auto_up

Converting cron to JIL (UNIX Only) cron2jil

Defining AutoSys Jobs or Machines jil

Defining Calendars autocal

autocal_asc

Installing and Managing License Keys gatekeeper

Maintaining Databases archive_events

clean_files

dbstatistics

Managing Security autosys_secure

Monitoring Jobs autocons

Recording Sounds (UNIX Only) record_sounds

Reporting Job Dependencies and Conditions

job_depends

Reporting Job Status autorep

autostatus

monbro

Starting AutoSys (UNIX Only) eventor

Stopping AutoSys sendevent

2–2 Reference Guide

archive_events

archive_events

Function

Removes old information from the AutoSys database. archive_events will optionally copy the information to an archive directory before deletion.

Syntax

archive_events {-n num_of_days | -j num_of_days | -l num_of_days | -s num_of_days } [-A] [-d directory_name] [-B batch_size] [-D data server:database | -D TNSname] [-t timeout_in_secs]

Note: -s and –t are UNIX commands only.

Description

archive_events removes data from various AutoSys database tables that are older than the specified number of days. You use this command to prevent the AutoSys database from becoming full. If the -A option is used, the data is archived before it is deleted. It is copied into a default directory unless you specify a different directory with -d option. The –n option removes events and any alarms associated with them from the event table. The -j option removes information from the job_runs table. Because data from both the event and the job_runs tables is used to generate reports with autorep, we recommend that you always archive the same number of days of information from both tables. The -l option removes autotrack information from the audit_info and audit_msg tables.

The -s option removes ServerVision audit information from the svarchive_tbl table.

In Dual-Server mode, the data is archived from both servers at the same time.

If information from these tables is not regularly purged from the database, the database can fill up rather quickly, stopping all AutoSys processing. We highly recommend that you run archive_events during the database maintenance cycle. The DBMaint script, which runs daily by default, will do this for you. Data that has been archived with archive_events is no longer accessible for reports (with autorep) or for simulations with AutoSys/Xpert.

AutoSys Commands 2–3

archive_events

Options

-n num_of_days Indicates that records older that the num_of_days should be deleted from the event table. The num_of_days value indicates the number of days of information that should be left in the database. If a row in the table is as old or older than this value, it will be deleted.

-j num_of_days Indicates that the information older than the num_of_days should be deleted from the job_runs table. The num_of_days value indicates the number of days of information that should be left in the database. If a row in the table is as old or older than this value, it will be deleted.

-1num_of_days Indicates that the autotrack information older than the num_of_days should be deleted from the audit_msg tables. The num_of_days value indicates the number of days of information that should be left in the database. If a row in the table is as old or older than this value, it will be deleted.

-s num_of_days

Indicates that the job resource usage information older than the num_of_days should be deleted from the svarchive_tbl table. The num_of_days value indicates the number of days of information that should be left in the database. If a row in the table is as old or older than this value, it will be deleted.

-A Indicates that information is to be copied to an archive file before being deleted; otherwise, the information is discarded.

For events, archive_events generates a file name for the file in which events are stored. This file is:

archive_events.%AUTOSERV%.MM.DD.YYYY

For job_runs, archive_events generates a file name for the file in which the job_runs information is stored. This file is:

archive_job_runs.%AUTOSERV%.MM.DD.YYYY

For autotrack tables, archive_events generates a file name for the file in which the job_runs information is stored. This file is:

archive_audit.%AUTOSERV%.MM.DD.YYYY

where:

MM.DD.YYYY Is the date on which the archive_events command was run.

2–4 Reference Guide

archive_events

For events, archive_events generates a file name for the file in which events are stored. This file is:

archive_events.$AUTOSERV.MM.DD.YYYY

For job_runs, archive_events generates a file name for the file in which the job_runs information is stored. This file is:

archive_job_runs.$AUTOSERV.MM.DD.YYYY

For autotrack tables, archive_events generates a file name for the file in which the job_runs information is stored. This file is:

archive_audit.$AUTOSERV.MM.DD.YYYY

where:

MM.DD.YYYY Is the date on which the archive_events command was run.

WARNING! If you run the archive_events command more than once a day, this file will be overwrit n in that 24-hour period. te

-d directory_name Indicates a user-specified directory in which the archived data should be stored. If this option is omitted, data is archived to the default directory named $AUTOUSER/archive for UNIX or to %AUTOUSER%\archive for Windows.

-B batch_size Specifies the batch size—the number of events to be archived at a time.

For Sybase or Microsoft SQL Server, the default number of events to archive at one time is 100, which should be used unless the database is dangerously full and the transaction log is likely to become full if 100 events are moved at once. Each transaction (in this case the deletion of a Single-Event) is recorded in the database’s transaction file, which shares file space with the actual data. If the data space is almost full, you might want to remove only a few events at a time. The maximum value is 500.

-D data_server:database

Indicates the name of the Sybase data server, and the specific database within it, from which events are to be archived.

-D TNSname Indicates the TNS alias name of the Oracle data server from which events are to be archived.

AutoSys Commands 2–5

archive_events

-t timeout_in_secs

Specifies the number of seconds to wait before timing out your SQL connection.

This Value is used only by Sybase (Oracle silently ignores it.) When archiving large event tables, set timeout_in_secs to a large number to prevent your SQL connection from timing out. If the default setting of 300 seconds is insufficient, increase the setting in 300-second increments. If timeout_in_secs is larger than the DBLibWaitTime configuration parameter value (in the configuration file,) archive_events will use the new time-out for the current session only. If –t is not specified, archive_events defaults to 300 seconds, regardless of the Database Wait Time setting.

Examples

1. To copy all events in the events table older than 5 days to the default archive file, and delete it from the database, enter:

archive_events -A -n 5

2. To copy all job_runs statistics older than 5 days to a specified archive directory, and delete them from the database, enter:

archive_events -A -d \my_archive -j 5

2–6 Reference Guide

autocal

autocal

Function

This starts the CalendarEditor.

This starts the Graphical Calendar Facility.

Syntax

autocal

Description

The autocal command is used to start up the Calendar Editor to define and maintain AutoSys calendars. The autocal command is used to start up the AutoSys Graphical Calendar to define and maintain AutoSys calendars. You can also start the facility by clicking on Calendar Editor from the AutoSys GUI Control Panel, or from the Date/Time tab in the Job Editor

The autocal command is used to start up the AutoSys Graphical Calendar Facility to define and maintain AutoSys calendars. The autocal command is used to start up the AutoSys Graphical Calendar to define and maintain AutoSys calendars. You can also start the facility by clicking on Calendar from the AutoSys GUI Control Panel, or from Date/Time Options in the Job Definition dialog.

Calendars are lists of dates that you can use to schedule the days on which jobs should, or should not, run. This facility lets you define calendars using a point and click approach on different screens that display a real-world calendar.

The Calendar Editor and Calendar Facility allows you to do the following:

■ Apply various 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.

■ When applying a rule, select options that will automatically reschedule conflicting dates—dates which are blocked out but also meet the qualifications of the rule being applied. A number of alternatives for rescheduling are also provided.

AutoSys Commands 2–7

autocal

■ Build a new calendar by overlaying multiple, preexisting calendars, as well as letting you perform additional modifications to the new calendar manually.

■ Preview a calendar before applying it to another calendar.

Calendars created using the Calendar Feature are actually a collection of dates, which can be referenced in a job definition. Use one of the following methods to apply a calendar:

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

■ With JIL, enter a calendar name in the run_calendar or exclude_calendar attribute.

For more information, see the chapter “Calendar Editor,” in the Unicenter AutoSys Job Management for Windows User Guide, or the chapter “The Graphical Calendar Facility,” in the Unicenter AutoSys Job Management for UNIX User Guide.

Example

To start the Graphical Calendar, enter:

Autocal

To start the Graphical Calendar Facility, enter:

autocal &

2–8 Reference Guide

autocal_asc

autocal_asc

Function

Adds, deletes, and prints custom calendar definitions.

Syntax

autocal_asc

Description

autocal_asc provides a text-based, command line mechanism for creating, deleting, and printing custom calendars, which may be used to specify the days on which to start jobs, or days on which a job should not be started, for example: holidays. Each calendar has a unique name and a list of days.

Once created, calendars can be referenced in a job definition. Use one of the following methods to apply a calendar:

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

■ With JIL, enter a calendar name in the run_calendar or exclude_calendar attribute.

Whenever a calendar is updated, AutoSys refigures the starting times for all jobs, which use that calendar.

For more information, see the chapter “Calendar Editor,” in the Unicenter AutoSys Job Management for Windows User Guide, or the chapter “The Graphical Calendar Facility,” in the Unicenter AutoSys Job Management for UNIX User Guide.

AutoSys Commands 2–9

autocal_asc

Example

To start autocal_asc to begin by entering calendar information, follow these steps:

1. Enter the following command:

autocal_asc

The following messages appear:

Utility to Add/Delete or Print entries in Calendar Calendar Name:

2. At this point you can enter the name of an existing calendar you want to edit, or the name of a new calendar.

After entering the name, the following message appears:

Add (A) or Delete (D) or Print (P)?

3. If you want to add a date to the calendar, enter: A

The following prompt appears:

Date (MM/DD/[YY]YY [HH:MM]):

Note: If you enter D to delete, the same prompt appears, and you can enter the date and time you want to delete from the calendar definition. If you enter P to print, the screen displays a summary of the specified calendar.

2–10 Reference Guide

autocal_asc

4. Using the following format, enter the date and, optionally, the time:

MM/DD/[YY]YY [HH:MM]

where:

MM Is the month.

DD Is the day.

[YY]YY Is the year.

HH Is the hours, in 24-hour format.

MM Is the minutes.

This prompt is repeated as long as dates are entered in response to the prompt.

Note: If you enter a two-digit year, AutoSys saves the setting to the database as a four-digit year. If you enter 79 or less, AutoSys prepends 20, and, if you enter 80 or greater, AutoSys prepends 19.

5. Complete the additions, click Enter without specifying a date.

This action will also exit the autocal_asc utility.

AutoSys Commands 2–11

autocons

autocons

Function

Starts the Scheduler Console.

Starts the AutoSys Operator Console.

Syntax

autocons

Description

The autocons command starts up the AutoSys Operator Console in UNIX, or the Scheduler Console in Windows for monitoring AutoSys jobs in real-time. You can also start the Console by single-clicking on the Ops Console button in the AutoSys GUI Control Panel.

The Consoles allow you to specify job selection criteria, which can be dynamically changed, to control, which jobs you want to view. This criteria includes 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 invoke the job definition automatically, allowing you to change the job, if the correct permissions are set.

The Operator Console and the Scheduler Console provides an Alarm Manager, which allows the monitoring of alarms as they are generated. In the Alarm Manager, you can do the following:

■ Enter responses to alarms.

■ Set the alarm’s state—either acknowledged or closed.

For more information, see the chapter “Scheduler Console,” in the Unicenter AutoSys Job Management for Windows User Guide, or the chapter “The Operator Console,” in the Unicenter AutoSys Job Management for UNIX User Guide.

2–12 Reference Guide

autocons

Example

To start the Operator Console, enter:

autocons

To start the Operator Console, enter:

autocons &

AutoSys Commands 2–13

autoflags

autoflags

Function

Prints information about AutoSys and the system configuration.

Syntax

autoflags [-a | -i | -o | -d | -v | -r | -h | -n]

Description

The autoflags command prints out the AutoSys version and release number, the database being used, and the operating system. You also use autoflags to determine the proper host name and host id for AutoSys license key generation.

Options

-a Displays all autoflags information to standard output.

-i Displays the AutoSys tape ID number to standard output.

-o Displays the operating system to standard output.

-d Displays the database type to standard output, either SYB for Sybase or ORA for Oracle.

-v Displays the AutoSys version number to standard output.

-r Displays the AutoSys release number to standard output.

-h Displays the host id to standard output to standard output.

-n Displays the host name to standard output to standard output.

2–14 Reference Guide

autoflags

Example

To view all AutoSys and system configuration information, enter:

autoflags -a

The following is an example of the information that would be displayed to standard output by issuing the command:

5 Windows_NT SYB 3.4 0 0 venice

3 AIX SYB 3.4 0 c0a9e38d venice

AutoSys Commands 2–15

autoping

autoping

Function

Verifies that the various AutoSys communication facilities are correctly configured and functioning.

Syntax

autoping -m {machine|ALL} [-A] [-D]

Description

autoping verifies that the server and client machines are properly configured and are communicating successfully. It also checks and verifies that the Remote Agent and the Remote Agent’s database connection are functioning correctly. If you are running Dual-Event Servers, it checks both database connections. If requested, it generates an alarm when problems are detected.

Since these client/server communication facilities are critical to AutoSys functioning, autoping provides valuable information for troubleshooting, and should always be used early in that process.

When autoping is executed, the server (the machine from which autoping is issued) establishes a connection with the client machine and waits for the Remote Agent to respond. If successful, the following message will be displayed on standard output at the server:

AutoPinging Machine[machine] AutoPing WAS SUCCESSFUL!

If there is a problem with the configuration, a message indicating that the remote machine has not responded (or that there is a more serious problem, such as a socket read error) will be displayed.

If the -D argument is used, autoping attempts to connect to the database and displays the resultant output to the screen. It includes the output in the alarm, if one was generated with the -A argument. If you are running Dual-Event Servers, both databases are checked. You can issue autoping from any machine on which the autoping executable resides. The target can be any Remote Agent machine.

2–16 Reference Guide

autoping

When autoping is executed, the server (the machine from which autoping is issued) establishes a connection with the client machine, which starts a Remote Agent on that machine, and the server waits for the Remote Agent to respond. If successful, the following message will be displayed on standard output at the server:

AutoPinging Machine[machine] AutoPing WAS SUCCESSFUL!

If there is a problem with the configuration, a message indicating that the remote machine has not responded or that there is a more serious problem, such as a socket read error will be displayed. Most of the time, these problems have to do with the improper installation of the Remote Agent with regard to the configuration of the internet demon inetd.

If the -D argument is used, autoping attempts to connect to the database and displays the resultant output to the screen. It includes the output in the alarm, if one was generated with the -A argument. If you are running Dual-Event Servers, both databases are checked. You can issue autoping from any machine on which the autoping executable resides. The target can be any Remote Agent machine.

Options

-M machine|ALL In order to use the -m ALL option, you must first define machines to the database using the insert_machine command. If you do not define the machines, autoping will display the following message:

Could not get list of machines from Database

-M

The name of the machine to be verified. This must be a real machine, and must be accessible through TCP/IP network protocol on the machine from which the command is issued. ALL checks all machines.

-M

The name of the machine to be verified. This must be a real machine, and must be listed in the /etc/hosts file on the machine from which the command is issued. ALL checks all machines.

-A Send an alarm if problems are detected.

-D Check the database connections on the specified machines

AutoSys Commands 2–17

autoping

Example

To check whether the machine “venice” is properly configured for AutoSys, and that its Remote Agent can function properly, enter:

autoping -m venice

If successful, the following will display:

AutoPinging Machine [venice] AutoPing WAS SUCCESSFUL!

To check all machines and verify their database access, enter:

autoping -m ALL -D

If successful, the following will display:

AutoPinging Machine [venice] AND checking the Remote Agent's DB Access. AutoPing WAS SUCCESSFUL!

AutoPinging Machine [rome] AND checking the Remote Agent's DB Access. AutoPing WAS SUCCESSFUL!

2–18 Reference Guide

autorep

autorep

Function

Reports information about a job, jobs within boxes, machines, and machine status. Also reports information about job overrides and global variables.

Syntax

autorep {-J job_name | -M machine_name | -G global_name} [-s | -d | -q | -o over_num] [-r run_num][-L print_level] [-t] [-D data_server:database | -D TNSname]

Description

autorep lists a variety of information about jobs, machines, and global variables currently defined in the AutoSys database. You can use it to list a summary of all currently defined jobs, or to display current machine load information. autorep serves as a problem tracking tool by listing all relevant event information for the last run of any given job, or a specified job run. You can also use it to extract job definitions in JIL script format and save them to an output file for later re-loading into AutoSys, as a means of backing up job definitions.

autorep retrieves data from the AutoSys database to formulate the reports. Any data that has been archived with archive_events will not appear in the reports.

When listing nested jobs, subordinate jobs are indented to illustrate the hierarchy. The following sections describe the types of autorep reports.

Job Run Summary

When a summary is requested, autorep prints the current status, if the job is still running, or the status for a previous run. The summary report reflects the last status posted to the AutoSys database.

Job Run Detail

When detail is requested, autorep prints all events for the job that are recorded in the event table in the AutoSys database. If the job is running, it posts events for the current run. If the job is not running, it posts events for the most recent run, or, if requested, a previous run.

AutoSys Commands 2–19

autorep

Machine Definition and Status In the Database

For all machines defined to AutoSys, you can use autorep to examine the current load and the defined maximum load and factor.

Job Override Information

autorep can print information for a specified override, based on job name and override number. In addition to the overridden job definition fields, it also displays user, time and run information.

Columns In the autorep Report

The columns in an autorep report vary with the type of report requested. The following table describes the columns.

Job Name Name of Job

Last Start Date and time of the most recent start of the job.

Last End Date and time of the most recent completion of the job.

ST The completion status of the most recent run of the job, or, if the job is still running, the current status.

Note: The completion status is shown in an abbreviated format.

Run Job run number and number of tries, separated by a slash ( / ).

Pri/Xit Priority/Exit code. If the job is in QUE_WAIT status, this column shows the priority in the queue; if the job completed, this column shows the exit code.

Status/[Event] Status for the current run of the job.

2–20 Reference Guide

autorep

Job Name Name of Job

Time Time-stamp when the change status event was generated by the Event Processor or Remote Agent.

Ntry Number of restart attempts for the listed event.

ES Processing state of the status (event).

Note: The completion status is shown in an abbreviated format.

Process Time Time-stamp when the change status event was processed by the Event Processor (the effective state change).

Machine Name of the machine the job was run on or is running on.

Status Abbreviations

The following table lists the abbreviations used in the ST (status) column of the autorep report, and gives the status for each abbreviation.

Abbreviation Status (Event)

AC ACTIVATED

FA FAILURE

IN INACTIVE

OH ON_HOLD

OI ON_ICE

QU QUE_WAIT

RE RESTART

AutoSys Commands 2–21

autorep

Abbreviation Status (Event)

RU RUNNING

ST STARTING

SU SUCCESS

TE TERMINATED

Event State Abbreviations

The following table lists the abbreviations used in the ES (event state) column of the autorep report, and gives the status for each abbreviation.

Abbreviation Event state

ER Error

PD Processed

PG Processing

UP Unprocessed

US Unsent

2–22 Reference Guide

autorep

Options

-J job_name Indicates that a Job Report is desired. job_name specifies the name of the job on which to report. Any valid AutoSys job name may be specified. To report on all jobs, specify ALL. The percent (%) character may be used in the job name as a wildcard (For example: %box% will select all jobs containing the string “box”).

Note: The underscore (_) character may also be used as a wildcard to match exactly one character. However, this can lead to some unexpected results when the job name itself contains an underscore “_” character. For example, specifying the job name “mon_%” will select all jobs beginning with the string “mon”, such as mon_box, monet, and so on.

The SQL ESCAPE option is not supported for wildcards in AutoSys.

-M machine_name Indicates that a Machine Report is desired, which lists the machine’s Max Load, Current Load, and Factor. machine_name specifies the machine on which to report. This may be a virtual machine, a real machine, or ALL for all machines; the machine must be defined to AutoSys.

-G global_name Indicates that a global variable report is desired, listing the variable name, value, and last modification date. global_name specifies the name of a global variable that has been set using the sendevent command or the Send Event dialog. In the specification, you can use ALL or wildcard characters.

-s Indicates that a Summary Report is desired. This is the default.

For a Job Report, the following information is provided: Start date/ time, End date/time, Current Status, Run Number, and Priority. You can request a report on a specific job run with the -r option. If the –r option is omitted, the most current job run is used.

For a Machine Report, the following information will be provided for each specified machine: Machine Name, Max Load, Current Load, and Factor.

For a Global Variable Report, this option is ignored.

AutoSys Commands 2–23

autorep

-d Indicates a Detail Report is desired.

For a Job Report, all events from the last run of the requested job will be listed. For each event, the following data is provided: Status, Date/ Time, Try Number, Event State (whether the event has been processed by the Event Processor yet), Process Date/Time, and the Machine on which the job was run. Also specifies if a job was run with an override and lists the override number.

For a Machine Report, the following information will be provided for each specified machine: Machine Name, Maximum Load, Current Load, and Factor. In addition, for any jobs currently running on the specified machines, the following information will be provided: Job Name, Machine, Status, Load, and Priority.

For a Global Variable Report, this option is ignored.

-q Indicates a Query Report is desired, providing the current job or machine definition, in JIL format, as it exists in the AutoSys database.

For a Global Variable Report, this option is ignored.

-o over_num Indicates an Override Report is desired, providing the overrides for the specified override number (over_num) and job_name. If the most current override is desired, the value of over_num should be zero. The job attributes and their associated overrides are displayed to standard output. You must supply a job name (-J job_name) with this option.

-r run_num Indicates a report is desired for a specific job run (run_num). This option can only be used with the -s and -d options. If this option is omitted, or run_num is zero, the most current job run is reported. A minus sign (-) can be used before the run_num value to indicate a relative counter for a past job run, relative to the current run number. For example, the option -r -2 would generate a report for the job run two runs back.

-t Requests that the time zone, if one is specified in the job definition, appear in the report. If requested, the time zone will appear in parentheses beneath the job name and the Time column of the report will be based on the specified time zone.

2–24 Reference Guide

autorep

-L print_level (Job reports only.) Indicates the number of levels of nesting for boxes for which the specified information should be listed. For example, a level of 2 means list the information for the specified job (a box) as well as two levels of jobs within that box.

This value may be any valid numeric value; to list the outermost box alone, specify “0.” The default is to list all levels within the box.

-D data_server: database

Indicates the name of the Sybase or Microsoft SQL Server data server, and the specific database within it, to be searched for the specified information. Normally, autorep consults the AutoSys Administrator (which are read from the Windows Registry) to determine which database to connect to. This option enables autorep to report on any AutoSys Event Server on the network.

-D data_server: database

Indicates the name of the Sybase data server, and the specific database within it, to be searched for the specified information. Normally, autorep consults the AutoSys configuration file ($AUTOUSER/ config.$AUTOSERV) to determine which database to connect to. This option enables autorep to report on any AutoSys Event Server on the network.

-D TNSname Indicates the TNS alias name of the Oracle data server to be searched for the specified information. Normally, autorep consults the AutoSys configuration file ($AUTOUSER/config.$AUTOSERV) on UNIX, or the Windows NT Registry, to determine which database to connect to. This option enables autorep to report on any AutoSys Event Server on the network.

AutoSys Commands 2–25

autorep

Examples

1. The following summary report is for a run of the Nightly_Download example. This is the command that requests the report:

autorep -J Nightly_Download Job Name Last Start Last End ST RunPri/Xit ________________ _____________________________________ _________ Nightly_Download 11/10/1997 17:0011/10/1997 17:52SU 101/1 Watch_4_file 11/10/1997 17:0011/10/1997 17:13SU 101/1 filter_data 11/10/1997 17:13 11/10/1997 17:24SU 101/1 update_DBMS 11/10/1997 17:24 11/10/1997 17:52SU 101/1

2. The following is the detail report that shows each event and status for each job. This is the command that requests this report:

autorep -J Nightly_Download -d Job Name Last Start Last End ST Run Pri/Xit ________________ ____________________________________________________ Nightly_Download 11/10/1997 17:00 11/10/1997 17:52SU 101/1 Status/[Event] Time Ntry ES ProcessTime Machine -------------- ------------------------------------------------------- RUNNING 11/10/1997 17:00:12 1 PD 11/10/1997 17:00:17 SUCCESS 11/10/1997 17:52:31 1 PD 11/10/1997 17:52:32 Watch_4_file 11/10/1997 17:00 11/10/1997 17:13 SU 101/1 Status/[Event] Time Ntry ES ProcessTime Machine -------------- ------------------------------------------------------- STARTING 11/10/1997 17:00:13 1 PD 11/10/1997 17:00:19 RUNNING 11/10/1997 17:00:19 1 PD 11/10/1997 17:00:29 gateway SUCCESS 11/10/1997 17:13:22 1 PD 11/10/1997 17:13:31 filter_data 11/10/1997 17:13 11/10/1997 17:24 SU 101/1 Status/[Event] Time Ntry ES ProcessTime Machine -------------- ------------------------------------------------------- STARTING 11/10/1997 17:13:32 1 PD 11/10/1997 17:13:34 gateway RUNNING 11/10/1997 17:13:38 1 PD 11/10/1997 17:13:45 gateway SUCCESS 11/10/1997 17:24:23 1 PD 11/10/1997 17:24:30 update_DBMS 11/10/1997 17:24 11/10/1997 17:52 SU 101/1 Status/[Event] Time Ntry ES ProcessTime Machine -------------- ------------------------------------------------------- STARTING 11/10/1997 17:24:16 1 PD 11/10/1997 17:24:22 gateway RUNNING 11/10/1997 17:24:20 1 PD 11/10/1997 17:24:29 gateway SUCCESS 11/10/1997 17:52:23 1 PD 11/10/1997 17:52:31

In the above example report, Nightly_Download is a box job. Therefore it does not enter the “Starting” state, but goes directly to the “Running” state. Box jobs do not list an associated machine, because the jobs in boxes may execute on different machines.

2–26 Reference Guide

autorep

3. The following is an example of a detailed report for one run back. This is the command that requests this report:

autorep -J RunData -d -r -1 Job Name Last Start Last End ST Run Pri/Xit _____________ ________________________________________________________ RunData 08/15/1997 12:14 08/15/1997 12:15 FA 2565/11 Status/[Event] Time Ntry ES ProcessTime Machine -------------- ----------------------------------------------------- STARTING 08/15/1997 12:14:56 1 PD 08/15/1997 12:15:00 venice RUNNING 08/15/1997 12:14:58 1 PD 08/15/1997 12:15:05 venice FAILURE 08/15/1997 12:15:00 1 PD 08/15/1997 12:15:05 [*** ALARM ***] JOBFAILURE 08/15/1997 12:15:04 1 PD 08/15/1997 12:15:10 venice [STARTJOB] 08/15/1997 12:15:38 0 PD 08/15/1997 12:15:46

4. The following example lists all machines defined on the data server. This is the command that request this report:

autorep -M ALL Machine Name Max Load Current LoadFactor O/S _______________ ________ __________________ _____ london 100 0 1.00 Unix berlin 90 0 0.90 NT v_italy.rome 0 0 0.00 Unix v_italy.venice 0 0 0.00 Unix v_france.paris 100 0 1.00 NT v_france.cannes 75 0 1.00 NT

5. The following is an override report, showing the current one-time job override in effect for the job. This is the command that requests this report:

autorep -J RunData -o 0 /* -------------------- over -------------------- */ override_job: RunData /* Over-Ride #2 Set by User: roger@venice on [07/28/1997 16:13:59] */ /* Over-Ride CURRENTLY IN EFFECT.*/ command: /bin/rundata2

6. The following is an override report, showing the first one-time job override for the job. This is the command that requests this report:

autorep -J RunData -o 1 /* -------------------- over -------------------- */ override_job: RunData /* Over-Ride #1 Set by User: roger@venice on [07/25/1997 18:23:45] */ /* Was RUN on run_num=175, Started on: 07/25 18:24:01 */ command: /bin/rundata1

7. To list the value of a specific variable, specify the variable using the –G option, as shown in the following example:

autorep -G DAY

The output from this command would look similar to the following:

Wednesday

AutoSys Commands 2–27

autorep

8. To list the value of all global variables that have been set, enter:

autorep -G ALL

The output from this command would look similar to the following:

Global Name Value Last Changed ------------ ------------ ------------------- DAY Wednesday 11/12/1997 12:18:27 AUDIT_DIR /usr/audit11/12 /1997 12:41:00 DINNER_TIME 18:30 11/12/1997 12:40:00 MAX_VAL 2048 11/12/1997 12:30:24

9. To list a summary report on the top two levels of boxes in the job named “Box3”, enter:

autorep -J Box3 -s -L 2

10. To include the time zone specification in a detailed report for the last run of the job named “MyJob”, enter:

autorep -J MyJob -d -t

When you use the -t option, the time reported in the Time column is translated to the time zone specified in the job definition. The time reported in the ProcessTime column is not affected by the -t option. It shows the time the event processor processed the events (server time).

The output from this command would look similar to:

Job Name Last Start Last End ST Run Pri/Xit _____________________________ _________________ _______ _____ _______ MyJob 12/10/1997 17:30 12/10/1997 17:30 SU 102/1 (Chicago) Status/[Event] Time Ntry ES ProcessTime Machine ----------------------------------------------------------------------------- STARTING 12/10/1997 17:30:05 1 PD 12/10/1997 16:30:13 localhost RUNNING 12/10/1997 17:30:08 1 PD 12/10/1997 16:30:13 localhost SUCCESS 12/10/1997 17:30:10 1 PD 12/10/1997 16:30:13 [STARTJOB] 12/10/1997 17:30:00 0 UP <Event was Scheduled based on Job Definition.>

2–28 Reference Guide

autorep

11. You can use the autorep command to extract job definitions in JIL script format and direct the output to a file. The following example shows how to save all job definitions to a file.

autorep -J ALL -q > dump_file

The output of this command is formatted exactly as a JIL job definition script, like the following:

insert_job: test_job job_type: c command: sleep 60 machine: juno #owner: jerry@jupiter permission: gx,ge,wx alarm_if_fail: 1

Note: The owner field of each job definition is commented out unless the Edit Superuser ran the autorep command to generate this report. Only the Edit Superuser can change the owner field.

You can save this file as a backup of job definitions, or you can use a text editor to quickly edit the job definitions. To re-load the job definitions into the AutoSys database, using the following jil command:

jil < dump_file

AutoSys Commands 2–29

autosc

autosc

Function

Starts the AutoSys Graphical User Interface (or GUI) and displays the GUI Control Panel.

Syntax

autosc

Description

The autosc starts up the AutoSys graphical user interface. This is equivalent to opening the AutoSys Graphical Interface from the AutoSys program group. From the GUI Control Panel, you can open applications and dialogs to define jobs, monitors, reports (browsers), and custom run or exclude calendars, as well as access the Scheduler Console. If AutoSys/ Xpert has been installed and activated with keys, you can display any of the AutoSys/Xpert interface windows from the GUI Control Panel. These windows include HostScape, JobScape, or TimeScape.

The autosc starts up the AutoSys graphical user interface. From the GUI Control Panel, you can open applications and dialogs to define jobs, monitors, reports (browsers), and custom run or exclude calendars, as well as access the Operator Console. If AutoSys/Xpert has been installed and activated with keys, you can display any of the AutoSys/Xpert interface windows from the GUI Control Panel. These windows include HostScape, JobScape, or TimeScape.

For more information, see the Unicenter AutoSys Job Management for Windows User Guide, or the Unicenter AutoSys Job Management for UNIX User Guide.

Example

To start the AutoSys Graphical User Interface, enter:

Autosc

To start the AutoSys Graphical User Interface, enter:

autosc &

2–30 Reference Guide

autostatus

autostatus

Function

Reports the current status of a specific job, or the value of an AutoSys global variable.

Syntax

autostatus {-J job_name | -G global_name} [-S autoserv_instance]

Description

autostatus writes the current status of the specified job or the current value of a global variable to standard output. This facility is especially useful in two circumstances:

■ When an application needs to know the status of another job.

■ When complex starting conditions are required that are beyond the scope of the starting conditions that can be easily specified in the job definition.

As an example of the latter situation, a job may need to be started when two out of a set of three jobs have completed successfully. This situation could be encoded by way of the starting conditions, but the conditions would be very cumbersome to define. Instead, you could use autostatus in a shell script to check the status of these jobs, and perform the appropriate action. A detailed description of this is given in the Examples section, following.

Options

-J job_name Specifies the name of the job whose status needs to be determined. The current status is returned to standard output.

-G global_name Specifies the name of a global variable that has been set using the sendevent command or the Send Event dialog. The value of the global variable is returned to standard output.

-S autoserv_instance Specifies the three-character code of the AutoSys instance to be queried. The UNIX default is the value of $AUTOSERV from the current environment. Or, in Windows the default is the value of %AUTOSERV%.

AutoSys Commands 2–31

autostatus

Examples

1. To check the current status of the job named “test_install” in the current instance of AutoSys, enter:

autostatus -J test_install

A one-word response to this command displays on standard output, such as the following:

SUCCESS

2. This example shows how to use autostatus in place of a cumbersome condition statement. Assume a job named “New_Stats” is dependent on the jobs named “Account_Run”, “Corp_Run”, and “End_Run.” “New_Stats” is to be run when all three of these jobs have run, at least two jobs have completed successfully, and it is not the 13th day of the month. These conditions are too complex to be specified as “New_Stats” starting condition, so autostatus should be used in a shell script to specify these conditions. To implement this, you would perform the following steps:

a. Create a job named “New_Stats_Starter” with the following job definition:

# # JIL for New_Stats_Starter # insert_job: New_Stats_Starter job_type: command machine: mombo command: new_stats_starter condition: done(Account_Run) and done(Corp_Run) and done(End_Run)

2–32 Reference Guide

autostatus

b. To create a batch file with the name “New_Stats.bat” to run for the job named “New_Stats_Starter”. This batch file will determine if the job “New_Stats” should be started. It communicates its decision back to AutoSys by exiting with a “0” (SUCCESS) or nonzero (FAILURE) exit code. The job named “New_Stats” bases its starting condition on that exit code.

@REM ECHO OFF @REM Program to determine when to start New_Stats @REM @REM Check for 13th of month, if it is, exit with 2 @echo | more | date > testdate.out @findstr /c:"/13/" testdate.out @if errorlevel 1 goto not13 @if errorlevel 0 echo 13th of the month @del testdate.out @autostatus -J %1 > test1.dat @findstr SUCCESS test1.dat @if errorlevel 1 goto nosuccess @if errorlevel 0 goto sayok :nosuccess @del test1.dat @REM false is supplied in %AUTOSYS%\bin @false 1 @goto exit: :sayok @del test1.dat @goto exit :not13 @del testdate.out @REM false is supplied in %AUTOSYS%\bin @false 2 :exit

Note: Reference jobs running on other instances of AutoSys, the $AUTOSERV for that instance needs to be supplied in the call to autostatus.

AutoSys Commands 2–33

autostatus

b. To create a Bourne shell script with the name “new_status_starter” to run for the job named “New_Stats_Starter”. This script will determine if the job “New_Stats” should be started. It communicates its decision back to AutoSys by exiting with a “0” (SUCCESS) or non-zero (FAILURE) exit code. The job named “New_Stats” bases its starting condition on that exit code.

#!/bin/sh # # Program to determine when to start New_Stats # Check for 13th of month - if it is, exit # with 2 if [ ‘date +%d‘ -eq 13 ] then exit 2 fi # Add up the Number of SUCCESS endings SUCCESS=0 for JobName in Account_Run Corp_Run End_Run do if [ ‘autostatus -J $JobName‘ = "SUCCESS" ] then SUCCESS=‘expr $SUCCESS + 1‘ fi done if [ $SUCCESS -gt 1 ] then exit 0 else exit 1 fi

Note: Reference jobs running on other instances of AutoSys, the $AUTOSERV for that instance needs to be supplied in the call to autostatus.

c. Create the job named “New_Stats” and specify that it should start when the above job completes successfully. Use the following starting condition as its job definition:

condition: success(New_Stats_Starter)

3. To check the value of a global variable named “Today,” enter:

autostatus -G Today

2–34 Reference Guide

autosyslog

autosyslog

Function

Displays the Event processor and Remote Agent log files.

Syntax

autosyslog [-e | -J job_name] [-p]

Description

autosyslog is used to view either the event processor log file or the Remote Agent log file for the specified job. Both the Remote Agent and Event Processor write diagnostic messages to their respective logs, as part of their normal operations and in response to detected error conditions.

autosyslog provides useful troubleshooting information because the event processor logs all events it processes and provides a detailed trace of its activities. If AutoSys appears to be behaving abnormally, these logs are the first places you should look.

Using autosyslog to view the event processor log is the same as issuing the following command:

tail -f $AUTOUSER/out/event_demon.$AUTOSERV

The last ten lines of the event processor log file are displayed when the autosyslog command is issued. The log file is updated continually as processing occurs. To terminate the display of the log, click Ctrl+C in the display window.

Remote Agent log

The autosyslog utility can be a useful diagnostic tool when jobs fail. This command, when provided with the name of a job, displays the log of the job’s most recent run. Although the Remote Agent’s log file is automatically deleted by default after a successful job run, the log file will not be deleted at job completion if the job ended with a FAILURE status.

AutoSys Commands 2–35

autosyslog

Event Processor Log

The event processor log contains a timestamped history of each event that occurs. Viewing this log is an alternative to monitoring “all jobs” and “all events.”

Options

-e Indicates that the event processor log is to be monitored. When in this mode, in order to terminate the command, you must press Ctrl+C.

To view the event processor log, you must execute this command on the machine that is running the Event processor, or on a machine that can access the same %AUTOUSER% file system. Also, the %AUTOUSER% and %AUTOSERV% environment variables must be set the same as it was when the event processor was run.

To view the event processor log, you must execute this command on the machine that is running the Event processor, or on a machine that can access the same $AUTOUSER file system. Also, the $AUTOUSER and $AUTOSERV environment variables must be set the same as it was when the event processor was run.

-J job_name Indicates that the Remote Agent log for the specified job_name is to be viewed. You must issue this command on the machine where job_name ran. Otherwise, the following message will display:

*** No remote agent files found for job_name job_name***

Note: View the Remote Agent log, you must execute this command from the machine on which the specified job ran last.

-P The -p option must be used with the -J job_name option.

Note: If the CleanTmpFiles parameter in the AutoSys configuration file is “on,” AutoSys removes the Remote Agent log file upon successful completion of the job. Therefore, if this parameter is set to “on,” the autosyslog command will not able to display the log contents of jobs that completed successfully—these log files will not exist.

2–36 Reference Guide

autosyslog

Examples

1. To view the event processor log, enter this on the command line of the system where the event processor is running, or where it ran last:

autosyslog –e

You can enter this command on any machine that can access the same file system for example %AUTOUSER% as the event processor.

You can enter this command on any machine that can access the same file system for example $AUTOUSER as the event processor.

2. To view the Remote Agent log of the last run of the “test_install” job, you would issue the following command on the command line of the machine where the “test_install” job ran:

autosyslog –J test_install

To view the output file with profile information, enter:

autosyslog –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 profile output section will be empty, for example:

OutPut from File: auto_rem_pro.491.216.1

AutoSys Commands 2–37

autosys_secure

autosys_secure

Function

Maintains the AutoSys Edit and Exec superuser ownerships, remote authentication methods and AutoSys database password. Also maintains Windows user Ids and passwords, which are required for AutoSys jobs to run on Windows client machines.

Syntax

autosys_secure

or:

autosys_secure [-q] {-a | -c | -d} –u user@host_or_domain [-o old_password] –p password

Description

You use the autosys_secure command to specify the AutoSys Edit Superuser and Exec Superuser, the AutoSys database password, remote authentication method, and Windows user Ids and passwords.

Edit Superuser and Exec Superuser

Two AutoSys users have administrator privileges: the Edit Superuser and the Exec Superuser.

The Edit Superuser is the only user with permission to:

■ Edit or delete any AutoSys job, regardless of who owns it and what permissions are set for it.

■ Change the owner of an AutoSys job.

■ Change the AutoSys database password, remote authentication method, and Windows user passwords.

2–38 Reference Guide

autosys_secure

The Exec Superuser is the only user with permission to:

■ Issue start or kill any AutoSys job, regardless of the execution permissions on the specified job. This user can affect how jobs run, typically by issuing the sendevent command.

■ Shut down the Event processor (by sending the STOP_DEMON event).

AutoSys Database Password

The AutoSys database password is used by the AutoSys Event processor, GUIs, and command-line utilities to securely access the AutoSys database (Event Server). By default, this password is stored in the AutoSys database as autosys, but you can change it using autosys_secure.

Every Event Server in an AutoSys instance must have the same AutoSys database password. If you are running in Dual-Server mode, autosys_secure changes the password on both Event Servers.

Note: If you have rolled over to Single-Server mode, do not change the password until you have established Dual Server mode again.

Remote Authentication Method

Remote authentication methods are used to verify one or both of the following:

■ A user has permission to start a job on an AutoSys client machine.

■ An event processor has permission to start a job on an AutoSys client machine.

The remote authentication methods are stored in the AutoSys database and are referenced when an AutoSys client initializes.

AutoSys Commands 2–39

autosys_secure

Windows User Passwords

Windows user Ids and passwords must be entered into the AutoSys database in order for jobs to run on Window client machines. When a Remote Agent runs a job on a machine, it logs on and impersonates the user who owns the job. To enable the Remote Agent do this, the event processor passes both the job information and an encrypted version of the job owner’s password from the AutoSys database to the Remote Agent. The AutoSys Edit Superuser must enter these passwords, and the Edit Superuser can do this from one machine using autosys_secure, either interactively or from the command line. After the Ids and passwords are entered, any user that knows an existing user ID and password can change the password or delete that user ID and password.

Note: Entering passwords using autosys_secure is not related to Windows user account administration.

Running autosys_secure

Before using autosys_secure to change the AutoSys database password or the remote authentication method, you must shut down all AutoSys processes that access the database for example, Event processor, GUIs, and Remote Agent. Also ensure no AutoSys jobs are running.

Running autosys_secure in Interactive Mode

When the Edit Superuser invokes autosys_secure, this menu displays:

AutoSys Security Utility.

Select an action to perform:

[1] Change AutoSys EDIT and EXEC superusers. [2] Change AutoSys database password. [3] Change AutoSys remote authentication method. [4] Create AutoSys User@Host or Domain password. [5] Change AutoSys User@Host or Domain password. [6] Delete AutoSys User@Host or Domain password. [7] Exit autosys_secure.

2–40 Reference Guide

autosys_secure

When a user other than the AutoSys Edit Superuser invokes autosys_secure, the following menu displays: AutoSys Security Utility. Only the AutoSys EDIT superuser has access to all options!

Please select an action to perform:

Options 1 thru 4 for superusers only [5] Change AutoSys User@Host or Domain password. [6] Delete AutoSys User@Host or Domain password. [7] Exit autosys_secure.

Any user that knows an existing user ID and password combination can change the password or delete the user from the AutoSys database.

Running autosys_secure from the Command Line

You can run autosys_secure from the command line to enter, change, or delete Windows user Ids and passwords. This option allows you to write interactive programs or batch files to enter or modify large numbers of user Ids and passwords, if necessary. To do this, you can use Windows Batch or Perl (Perl is shipped with AutoSys for Windows ).

You can run autosys_secure from the command line to enter, change, or delete Windows user Ids and passwords. This option allows you to write interactive programs, scripts, or batch files to enter or modify large numbers of user Ids and passwords, if necessary. To do this, you can use any scripting language, such as Windows Batch or Perl (Perl is shipped with AutoSys for Windows ).

Print the usage statement for the command-line options to the screen, enter this command:

autosys_secure –h

This is the autosys_secure command-line syntax:

autosys_secure [-q] {-a | -c | -d} –u user@host_or_domain [-o old_password] –p password

AutoSys Commands 2–41

autosys_secure

Edit and Exec Superusers

The first time option [1] in the autosys_secure menu is chosen after AutoSys is installed, you are prompted for the names of the users who should be assigned the Edit Superuser and Exec Superuser privileges. Both these privileges can be assigned to the same user. These users must be valid users on the host or domain that you are logged onto.

After the initial assignments, only the Edit Superuser can change these assignments. Option [1] displays the current settings and allows the Edit Superuser to accept the same users by clicking Enter, or change the users by entering a new specification.

AutoSys Database Password

Option [2] in the autosys_secure menu displays a prompt at which you can change the AutoSys database password. This option changes the database password for the “autosys” user. By default, the password is “autosys.”

Only the AutoSys Edit Superuser can change the AutoSys database password. The password must be between 6 and 20 characters in length. It can contain uppercase and lowercase alpha characters, numbers, and punctuation marks; it cannot contain single or double quotes, spaces, or control characters.

Note: For Bundled Sybase users only, the “sa” system administrator user password is “sysadmin” by default. To change the password for the “sa” user, use the xql utility.

2–42 Reference Guide

autosys_secure

Remote Authentication Methods

Only the AutoSys Edit Superuser can change the remote authentication method. When option [3] in the autosys_secure menu is chosen, the following menu displays.

Current remote authentication method: No remote authentication. Please select a remote authentication method: [1] No remote authentication. [2] Remote agent user authentication only. [3] AutoSys event processor authentication only. [4] Both remote agent user and AutoSys Event processor authentication [2]&[3]).

Current remote authentication method: No remote authentication. Please select a remote authentication method: [1] No remote authentication. [2] Unix ruserok authentication only. [3] AutoSys event processor authentication only. [4] Both Unix and AutoSys authentication methods [2]&[3]).

No Remote Authentication

When this option is selected, the remote authentication feature is disabled.

Remote Agent User Authentication Only

When this option is selected, Remote Agent user authentication will be performed. The method of authentication depends on whether the client machine is an Windows or a UNIX machine.

Note: The Edit Superuser can override this type of remote authentication by changing the ownership of a job from the form user@host_or_domain to the form user. As a result, remote authentication on the job on the target machine at execution time is not performed.

AutoSys Commands 2–43

autosys_secure

UNIX ruserok Authentication Only

When this option is selected, remote authentication will be accomplished by telling a client’s Remote Agent to make the UNIX system call named ruserok(). This function checks both the client machine’s /etc/hosts.equiv and the user’s .rhosts files 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. On Windows, Remote Agent user authentication is enabled using the Security settings in the AutoSys Administrator.

Note: The Edit Superuser can override this type of remote authentication by changing the ownership of a job from the form user@machine to the form user. As a result, remote authentication on the job on the target machine at execution time is not performed.

Windows Remote Agent User Authentication

Remote Agent user authentication is enabled on a Windows machine, the Remote Agent on that machine consults the Security settings from the AutoSys Administrator under certain circumstances to verify that the job’s owner is registered on the client machine. The two security entries, Trusted Hosts and Trusted Users, are used to accomplish this task. The Trusted Hosts list specifies host or domain names. All users on all hosts specified in the Trusted Hosts list are assumed to be trusted and are allowed to run jobs on the client machine. Only the AutoSys Edit Superuser can change this list, using the AutoSys Administrator Security screen. This list should be changed with great care since it is a very powerful key that grants access to all users on a given host. The Trusted Users lists are owned and administered by individual users from the AutoSys Administrator Security screen on their specific client machines. Trusted Users differ from Trusted Hosts in that every individual user on a client machine or domain has their own personal Trusted Users list. Users can grant access to foreign users to run jobs under their current, logged-on user accounts. The Trusted Users list entries are in the user@host_or_domain format. All users listed in the Trusted Users field are allowed to run jobs on that client machine.

2–44 Reference Guide

autosys_secure

AutoSys Event Processor Authentication Only

When this option is selected, remote authentication will be accomplished by binding a specific Remote Agent to one or more event processors. This means a Remote Agent must verify that it has permission to process an event processor’s requests before starting each job. On UNIX, the event processor reads the /etc/.autostuff file on the machine on which the Remote Agent is running. On Windows, the event processor checks the list of Authorized Event Processor host names in the Remote Agent screen of the AutoSys Administrator on the machine on which the Remote Agent is running.

Notes:

Before activating Event Processor authentication, you must have already specified the authorized Event Processor host names in the Remote Agent Administration screen of the AutoSys Administrator.

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

Both Remote Agent User and Event Processor Authentication

When this option is selected, both the Remote Agent user and the AutoSys Event Processor authentication methods will be used. If this option is enabled, both methods of authentication must succeed for the job to run.

AutoSys Commands 2–45

autosys_secure

Both UNIX and AutoSys Authentication Methods

When this option is selected, both the UNIX ruserok() and the AutoSys Event Processor authentication methods will be used. If this option is enabled, both methods of authentication must succeed for the job to run.

Creating AutoSys user@host_or_domain Passwords

Option [4] in the autosys_secure menu lets you enter a user name, a host or domain name, and a password for a user. Autosys_secure accepts a NULL password. A message appears to confirm the user was created. No validation is done to verify the password is correct (but the process does verify that the password can be encrypted and decrypted correctly). You must enter Windows user Ids and passwords for all users that will be job “owners” (users that will be specified by the owner job attribute). If the Windows user ID and password combination is not valid, the Remote Agent will issue an error when it attempts to run a job as that user, because it will not be able to log on when the job is to be run. Windows user names can be from 1 to 20 characters in length and can contain all characters except the following:

3. [ ] + : ; “ < > . , ? / \ |

Windows passwords can be a maximum of 14 characters in length. Passwords are case-sensitive and may contain any character except a space. NULL passwords are accepted. To enter a NULL password, click the Enter key when autosys_secure prompts for the password.

Changing AutoSys user@host_or_domain Passwords

When option [5] in the autosys_secure menu is chosen, a prompt appears asking you to enter a user name and a host or domain name. Then you are prompted to enter the existing password and the new password. A message appears to confirm the password was changed for the specified user. Any user that knows the existing user ID and password can change the password in the AutoSys database.

2–46 Reference Guide

autosys_secure

Deleting AutoSys user@host_or_domain Passwords

when option [6] in the autosys_secure menu is chosen, a prompt appears asking you to enter a user name, a host or domain name, and the current password. A message appears to confirm the user/password entry was deleted from the AutoSys database. Any user that knows the existing user ID and password can delete the user ID and password from the AutoSys database.

Options

-h Displays help. Use this option to get help on the autosys_secure command-line options.

-q Specifies to run in quiet mode and not print any messages to the screen. When run in quiet mode, autosys_secure will not print any error messages. You can, however, check the return code to see if there were any run errors. To check the return code, enter a command similar to the following:

-q echo %ERRORLEVEL%

If autosys_secure is successful, the return value is 0; and if it is unsuccessful, the value is 1.

-q csh echo $status sh or ksh echo $?

If autosys_secure is successful, the return value is 0; and if it is unsuccessful, the value is 1.

-a Specifies to add a user ID and password. You must also supply the –u and –p options.

-c Specifies to change an existing user password. You must also supply the –u, -o, and –p options.

-d Specifies to delete an existing user password. You must also supply the –u and -o options.

-u user@host_or_domain

Specifies the Windows user whose password you are entering. Windows user names can be from 1 to 20 characters in length and can contain all characters except the following:

* [ ] + : ; “ < > . , ? / \ |

AutoSys Commands 2–47

autosys_secure

-o old_password Specifies the password for an existing user. If you are changing a password or deleting a user ID and password, you must supply this option. If the password is NULL, enter NULL.

-p password Specifies the password for the user@host_or_domain that you want entered in the AutoSys database. If you are adding a user or changing a password, you must supply this option. Windows passwords can be a maximum of 14 characters in length. Passwords are case-sensitive and can contain any character except a space. NULL passwords are accepted. To specify a NULL password, enter NULL.

Example

To start autosys_secure in interactive mode, enter:

autosys_secure

The autosys_secure options display.

2–48 Reference Guide

Autotimezone

Autotimezone

Function

Allows additions, deletions, and queries to the time zones table.

Syntax

autotimezone [-a entry_name value] [-c entry_name value] [-t timezone_name] [-d entry_name] [-q entry_name | sql_pattern] [-l]

Description

autotimezone lets you query the timezones table, and add and delete timezones table entries. The timezones table contains entries that you can specify in a job definition using the timezone attribute. The timezones table maps cities and common aliases to valid POSIX TZ environment variables. The table contains entries for all the common time zones that are recognized by most operating systems, as well as many cities in the world.

The AutoSys timezones table has three entry “Types,” Zone, Alias, and City, as shown in the following excerpt from the timezones table:

Entry Type Zone ---------------------- ------ ---------------- US/Pacific Zone PST8PDT US/Samoa Alias Pacific/Samoa UTC Alias GMT+0 Vancouver City Canada/Pacific

All “Alias” and “City” Types are eventually resolved to “Zone” Types. The “Zone” Types resolved to TZ Variables (in the Zone column) that correspond to those recognized by the operating system for the machine on which the Event Server is running. TZ variable syntax is compatible with Windows NT TZ variables, but has been extended to allow full control over the day and time that daylight saving time changes occur. If the time zone specification in a job definition is not a TZ variable, the timezones table will be read multiple times until it resolves to a TZ variable. For example, assume a job definition included the attribute timezone:Berlin. Berlin would be resolved to Europe/Berlin the first time the table is read. The second time the table was read, Europe/Berlin would be resolved to MET, which is a TZ variable. If a time zone is not resolved within five lookups, it is considered invalid and the job specifying the time zone will fail.

AutoSys Commands 2–49

Autotimezone

The AutoSys timezones table is complete and accurate and should not need modification. However, the syntax of TZ variables is provided in the next section if you want to add or modify entries in the timezones table.

Important! If you change the timezones table, be sure you do not change or delete entries that are used by pre-existing STARTJOB and other events that were scheduled using the old timezones table.

All “Alias” and “City” Types are eventually resolved to “Zone” Types. The “Zone” Types resolved to TZ Variables (in the Zone column) that correspond to those recognized by the operating system for the machine on which the Event Server is running. For details on the format of the TZ variable, refer to your system time, timezone, or environ man page.

When processing a job definition that includes a time zone, AutoSys first tries to resolve the specified time zone using the zones known to the operating system. If it is not found there, AutoSys looks up the zone in the timezones table. If the time zone specification is not a TZ Variable for example a “Zone” Type, the timezones table will be read multiple times until it resolves to a TZ Variable. For example, assume a job definition included the attribute timezone:Berlin. Berlin would be resolved to Europe/Berlin the first time the table was read. The second time the table was read, Europe/Berlin would be resolved to METS-1METD, which is a TZ Variable. If a time zone is not resolved within five lookups, it is considered invalid and the job specifying the time zone will fail.

Important! If you change the timezones table, make sure you do not change or delete entries that are used by pre-existing STARTJOB and other events that were scheduled using the old timezones table.

2–50 Reference Guide

Autotimezone

TZ Variable Syntax

This is the format of the TZ variable:

std offset [dst [offset] [,start [/time] ,end [/time] ]]

There should be no spaces between any of the components of the TZ variable. Valid values for the TZ variable components are defined following:

std and dst An abbreviation of three or more characters representing standard and daylight saving time for the time zone. Std is required and dst is optional. If dst is not specified, is it assumed that the time zone does not observe daylight saving time.

Offset Indicates the amount of time to be added to the local time to arrive at GMT. If dst is specified but does not have an offset specification, it is assumed that daylight saving time is one hour ahead of standard time.

The format of offset is:

[-|+]hh[:mm[:ss]]

hh is required and is a 1 or 2 digit number representing hours. Mm and ss are optional and refer to minutes and seconds, respectively. If specified, mm and ss must be between 0 and 59. If a + or no prefix is present, the value is assumed to be a time zone west of GMT. A – prefix indicates the value is a time zone east of GMT.

AutoSys Commands 2–51

Autotimezone

Start and end Indicate when to change to and from daylight saving time, respectively. The format is one of the following three types:

Jn

The Julian day n (1 <= n <= 365). Leap days are ignored, meaning December 31 is always day 365 and February 29 cannot be specified.

N

The zero-based Julian day n (0 <= n <= 365). Leap days are counted.

Mm.n.d

Specifies that the time change occurs on the nth occurrence of a particular day of a specific month (for example, the first Sunday in April). January is month 1, and Sunday is day 0. When n is 5, it means the last occurrence of that day in month m. Valid value ranges are:

1 <= m <= 12 0 <= n <= 5 0 <= d <= 6

If start and end are omitted, United States daylight saving time defaults are assumed. That is, start is the first Sunday in April and end is the last Sunday in October.

Time Specifies the time of day that the change to daylight saving or standard time occurs. The format is:

hh[:mm[:ss]]

hh is a 1 or 2 digit number representing hours, and is required. Mm and ss are optional and refer to minutes and seconds, respectively. If specified, mm and ss must be between 0 and 59. If time is not specified, the default is 02:00:00 (2:00 a.m.).

2–52 Reference Guide

Autotimezone

Options

-a entry_name value Adds an Alias entry to the timezones table. An Alias entry associates a name with a time zone. For example, you could alias “US/Mountain” to “MST.” Entry_name is a string between 1 and 50 characters; and can include upper- or lowercase letters, digits, slash ( / ), hyphen (— ), and underscore ( _ ). Value must correspond to a time zone recognized by the operating system. Use spaces to separate the entry_name and the value.

-c entry_name value Adds a City entry to the timezones table. A City entry is a type of Alias that maps a city to a time zone. Entries added to the table through the –c argument will display as type “City” in a listing of the timezones table. See the –a argument, above, for a description of entry_name and value.

-t timezone_name Adds a time zone entry to the timezones table. A Zone entry must be of the format of a valid POSIX standard timezone (TZ) environment variable.

-d entry_name Deletes an entry from the timezones table.

-q entry_name | sql_pattern

Queries the timezones table for the setting of a specific alias, city, or zone. Queries are case insensitive, and you can use the wildcard character, percent ( % ) or the SQL underscore

-l Lists all entries in the timezones table.

Examples

1. The following command adds a city named “San-Jose” to the timezones table:

autotimezone –c San-Jose US/Pacific

2. The following command deletes the city named “San-Jose” from the timezones table:

autotimezone –d San-Jose

3. The following command queries the timezones table for all entries beginning with the letter “d”:

autotimezone –q d%

The output from this command would be similar to the following:

AutoSys Commands 2–53

Entry Type Zone Dallas City US/Central Denver City US/Mountain Detroit City US/Central

autotrack

autotrack

Function

Tracks and reports changes to the AutoSys database.

Syntax

autotrack [-D data_server:database | -D TNSname] [-u 0|1|2] [-l] [-h|H] [-v] [-F “from_time”] [-T “to_time”] [-U user_name] [-m machine] [-J job_name] [-t A|B|C|J|M|O|S|T]

Description

autotrack tracks changes to the AutoSys database for example: job definition changes, sendevent calls, and job overrides and writes this information to the database. When you query for this information, autotrack prints a report to the screen, or you can redirect the output to a file. Autotrack can track changes to job definitions, both from JIL or the GUIs. Changes made directly to the database through SQL commands cannot be tracked.

autotrack tracks changes to the AutoSys database for example: job definition changes, sendevent calls, and job overrides and writes this information to the database. When you query for this information, autotrack prints a report to the screen, or you can use standard UNIX file redirection to save the output to a file. Autotrack can track changes to job definitions, both from JIL or the GUIs. Changes made directly to the database through SQL commands cannot be tracked.

This facility is especially useful for:

■ Sites desiring careful monitoring of the job definition environment.

■ Sites where multiple users have permission to edit job definitions or send AutoSys events.

Start tracking, use the autotrack –u command to set the tracking level to 1 or 2, depending on the amount of detail you want tracked. By default, autotrack is set to level 0 (no tracking). Autotrack –l lists the current tracking level.

Note: Only the AutoSys Exec or Edit Superuser can change the tracking level.

2–54 Reference Guide

autotrack

Use the autotrack command with one or more query options (-J, -U, -m, -F, -T, and –t) to request reporting on a specific job, user, machine, time window, or event type. Typing autotrack with no arguments retrieves information on all events, but omits the detail.

Type autotrack –h or autotrack –H to display the usage summary.

Autotrack output is stored in two tables: audit_info and audit_msg. By default, these tables reside in the same database (or tablespace) as all other AutoSys tables. You might want to relocate these tables to another database (or tablespace) to insulate event processing from an auditing table overflow. If you frequently unload all your jobs from the database and reload, you should turn off autotrack temporarily to prevent the database from growing unnecessarily large.

For example:

autotrack –u 0 jil –V none < whole_thing.jil autotrack –u 1

Running archive_events will help prevent the database from filling up with autotrack output. The archive_events –l num_of_days command archives information from the audit_info and audit_msg tables older than the specified number of days.

AutoSys Commands 2–55

autotrack

Options

-D data_server: database

Indicates the name of the Sybase or Microsoft SQL Server data server, and the specific database within it, to be searched for the specified information. Normally, autotrack consults the environment variables and the AutoSys Administrator configuration settings to determine to which database to connect. This option enables autotrack to report on any AutoSys Event Server on the network.

Indicates the name of the Sybase data server, and the specific database within it, to be searched for the specified information. Normally, autotrack consults the environment variables and the AutoSys configuration file to determine to which database to connect. This option enables autotrack to report on any AutoSys Event Server on the network.

-D TNSname Indicates the TNS alias name of the Oracle data server to be searched for the specified information. Normally, autotrack consults the environment variables and the AutoSys Administrator configuration settings to determine to which database to connect. This option enables autotrack to report on any AutoSys Event Server on the network.

Indicates the TNS alias name of the Oracle data server to be searched for the specified information. Normally, autotrack consults the environment variables and the AutoSys configuration file to determine to which database to connect. This option enables autotrack to report on any AutoSys Event Server on the network.

2–56 Reference Guide

autotrack

-u tracking_level Updates the level of detail that autotrack writes to the database, using Level 0, 1, or 2.

Level 0

The default setting, and it indicates no tracking.

Level 1

Tracks job, calendar, monitor, browser, and machine definition changes; job overrides; and autosys_secure, autotrack, and sendevent calls. It condenses each tracked event to a one-line summary.

Level 2

Tracks the same information as Level 1, but also writes the entire job definition for overrides and job definition changes. Level 2 is very database intensive and will significantly impair jil performance.

-l Displays the currently set tracking level (0, 1, or 2).

-h|H Displays the autotrack usage summary.

-v Verbose reporting.

-F "from_time" Reports changes or events that occurred from this date and time forward; the format is “MM/DD/[YY]YY HH:MM.”

If you enter a two-digit year, AutoSys saves the setting to the database as a four-digit year. If you enter 79 or less, AutoSys prepends 20, and, if you enter 80 or greater, AutoSys prepends 19.

-T "to_time" Reports changes or events that occurred up to this date and time; the format is “MM/DD/[YY]YY HH:MM.”

If you enter a two-digit year, AutoSys saves the setting to the database as a four-digit year. If you enter 79 or less, AutoSys prepends 20, and, if you enter 80 or greater, AutoSys prepends 19.

-U user_name Reports changes or events initiated by the specified user.

AutoSys Commands 2–57

-m machine_name Reports changes or events initiated from the specified machine.

autotrack

-J job_name Reports on the specified job. The percent (%) character may be used in the job name as a wildcard.

Note: The underscore (_) may also be used as a wildcard to match exactly one character. However, this can lead to some unexpected results when the job name itself contains a (_) character. For example, specifying the job name “mon_%” will select all jobs beginning with the string “mon”, such as mon_box, monet, and so on. The SQL ESCAPE option is not supported for wildcards in AutoSys.

-t autotrack_type Reports on a specific event; an event can be one of the following types:

Event Type Event

A Calls generated by the autosys_secure command.

B Monbro definition changes generated by jil or the GUI.

C Calendar definition changes generated by the autocal_asc command or the Graphical Calendar Facility.

J Job definition changes, sendevent-J (or the Send Event dialog sent from the Operator Console), or overrides to a specific job generated by jil or the GUI.

M Machine definition changes generated by jil.

O Override definition changes generated by jil or the GUI.

S Calls generated by the sendevent command evoked through jil or the GUI.

T Calls generated by the autotrack command, for example; changes to the tracking level.

2–58 Reference Guide

autotrack

Examples

The amount of detail written to the database (and, thus, available to query against) is determined by the autotrack tracking level. Level 2 tracking provides much more detail than does Level 1, as shown in examples 1 and 2.

1. The following query requests verbose reporting about a job named “NightlyReport.”

autotrack -J NightlyReport -v

If the autotrack tracking level had been set to 1, the output of this request would resemble that shown following.

jane@taurus 11/21 10:04:54 job definition change :::::::::::::::::::::::::::::::::::::::::::::::: jane@taurus 11/21 10:05:49 job definition change command: date :::::::::::::::::::::::::::::::::::::::::::::::: jane@taurus 11/21 10:06:29 sendevent issued

If the tracking level had been set to 2, autotrack would have written much more detail to the database. Thus, the same query

autotrack -J NightlyReport -v

would produce a report that includes the entire job definition with changes indicated by an asterisk.

2. The following query requests non-verbose reporting about the job “NightlyReport”:

autotrack -J NightlyReport

A query without verbose reporting omits all indented detail; only the first three lines for each event appears, as shown in the following:

jane@taurus 11/21 10:04:54 job definition change :::::::::::::::::::::::::::::::::::::::::::: jane@taurus 11/21 10:05:49 job definition change :::::::::::::::::::::::::::::::::::::::::::: jane@taurus 11/21 10:06:29 sendevent issued

3. View all the changes that occurred to the job “NightlyReport” after 1 a.m. on

AutoSys Commands 2–59

November 12, 1997, enter:

autotrack -F "11/12/1997 01:00" -J NightlyReport

autotrack

4. View all changes made by user “sue” over the weekend of November 16 and 17, 1997, enter:

autotrack -U sue -F "11/16/1997 01:00" -T "11/17/1997 23:59"

5. View all autosys_secure changes that occurred from the machine “gemini,” enter:

autotrack -t A -m gemini

The output from this command would resemble the following:

jane@gemini 11/05 19:08:12 autosys_secure change EDIT Super-User: jane EXEC Super-User: jane password: **************

2–60 Reference Guide

chase

chase

Function

Verifies that the jobs that the AutoSys database indicates are running, are running. This process also checks the associated Remote Agents.

Syntax

chase [-A] [-E]

Description

chase determines from the AutoSys database, which jobs are in the STARTING or RUNNING state, and on which machine. For each client machine, chase passes to a Remote Agent a list of jobs that are supposed to be running there and instructs the Remote Agent to verify that the processes actually are running. For Command jobs running on a UNIX machine, the Remote Agent also checks for the pid of the UNIX process.

Chase also verifies that the Remote Agent is running. When the event processor service is started, chase is automatically invoked. Since chase uses the same mechanism as the event processor to communicate with the Remote Agent machines, it gives an accurate picture of the system’s state of health.

When verifying that the Remote Agent is running, chase checks that the Remote Agent has a lock on the Remote Agent log file. (This is more reliable than checking the Remote Agent’s process ID.)

Note: If you have disabled file locking on the client machine, chase will not be able to verify if a Remote Agent is running. Therefore, ensure that the directory specified by the AutoRemoteDir parameter in the AutoSys configuration file is on a file system that has file locking enabled.

When the event processor is started (by way of the eventor command), chase is automatically invoked. Since chase uses the same mechanism as the event processor to communicate with the Remote Agent machines, it gives an accurate picture of the system’s state of health.

Note: The event processor does not have to be running while chase is run, but the database must be available.

AutoSys Commands 2–61

chase

Errors detected by chase are sent to standard output. Optional arguments used with chase further determine what actions to take when error conditions are detected. The -A option sends an alarm to AutoSys to alert the user that problems were found. If the -E option is specified, chase will force a FAILURE of any job that is supposed to be running but is not. This will trigger an automatic restart of the job if the n_retrys attribute has been defined. The Event processor must be running for chase to automatically restart jobs.

Notes: If chase cannot connect to a Remote Agent machine, it cannot determine if the reason is due to a network failure or the machine being down. As a result, to prevent jobs from being restarted when in fact they may have run already, chase will not change the status of jobs in this case, even if chase is run with the -E option.

If jobs are stuck in the STARTING state, chase will not automatically restart them. Instead, it will write a message to standard output that manual intervention may be required. Jobs stuck in the STARTING state should not be automatically restarted—it is possible, due to network problems, that the job may be running or have run, and its state not yet communicated to the database. The actual status of these jobs should be verified before they are restarted and their status is changed.

2–62 Reference Guide

chase

Running chase Automatically

It is a good idea to run chase automatically at regular intervals to track down any problems on the network. For example, if a machine becomes unreachable while it is running a job, chase will detect that the machine is down and send an alarm. If a user or operator has a monitor running, they will also be alerted to the problem.

Run chase automatically, we suggest that you use AutoSys to run it as a job. The %AUTOSYS%\data\chase.jil file contains AutoSys JIL statements to run chase every 10 minutes on the machine running the Event processor (“charley,” in the example following). You can change the specific parameters in this script to suit your own environment, then submit it to the jil command.

The following are examples of JIL statements for automatically running chase.

# chase function # insert_job: chase machine: charley command: %AUTOSYS%\bin\chase -A -E date_conditions: yes days_of_week: all start_mins: 05,15,25,35,45,55 max_run_alarm: 5 # change if many jobs are running term_run_time: 10 # ditto # These output files can be changedstd_out_file: %AUTOUSER%\out\chase.out std_err_file: %AUTOUSER%\out\chase.err

Run the chase process automatically, you can use AutoSys to run it as a job. The $AUTOSYS/data/chase.jil file contains the JIL statements that will instruct AutoSys to run chase every 10 minutes on the machine running the event processor (“charley,” in the example following). You can change the specific parameters in this script to suit your own environment, then submit it to the jil command.

The following are examples of JIL statements for automatically running chase.

# chase function # insert_job: chase machine: charley command: $AUTOSYS/bin/chase -A -E date_conditions: yes days_of_week: all start_mins: 05,15,25,35,45,55 max_run_alarm: 5 # change if many jobs are running term_run_time: 10 # ditto # These output files can be changed std_out_file: $AUTOUSER/out/chase.out std_err_file: $AUTOUSER/out/chase.err

AutoSys Commands 2–63

chase

Options

-A Indicates that if chase detects any inconsistencies, for example; jobs that should be running, but are not, it sends alarms to the AutoSys RDBMSs.

-E Indicates that if a job and the job’s Remote Agent are not running on the client machine, but the database indicates they should be, chase puts the job in FAILURE status, triggering the job to be restarted if the job definition includes the n_retrys attribute.

Note: If chase is run without any options, AutoSys performs all chase activities and writes the results to standard output. No alarms or job restart events are sent.

Example

If a job is running longer than expected and you suspect it may have abnormally ended (but still shows as “running”), you should run chase. To verify that the job is running, receive an alarm if there is an inconsistency, and restart the job if necessary, enter:

chase -A –E

2–64 Reference Guide

chk_auto_up

chk_auto_up

Function

Inspects the environment variables and AutoSys Administrator settings in the Windows Registry, then determines if the AutoSys database (Event Server) and event processor are running.

Inspects the environment variables and configuration files, then determines if the AutoSys database (Event Server) and event processor are running.

Syntax

chk_auto_up [-Q]

Description

chk_auto_up determines if the Event Server (database) and the event processor are running. This facility is essential for locating the cause of problems, such as jobs not being started at the scheduled time. The Event Server and the event processor must both be running for job to start.

chk_auto_up uses the AutoSys product environment variables to locate the AutoSys instance configuration as defined in the AutoSys Administrator, and uses the information to determine the data server and database names. If chk_auto_up completes successfully, this indicates that those environment variables and the AutoSys configuration are set up correctly. If events are not being processed, or jobs are not running, this is the first utility you should run.

chk_auto_up uses the AutoSys product environment variables to locate the AutoSys configuration file $AUTOUSER/config.$AUTOSERV, and uses the configuration file to determine the data server and database names. If chk_auto_up completes successfully, this indicates that those environment variables and the AutoSys configuration file are set up correctly. If events are not being processed, or jobs are not running, this is the first utility you should run.

AutoSys Commands 2–65

chk_auto_up

If a Shadow Event processor is running in addition to the primary event processor, or if Dual-Event Servers are being run, chk_auto_up will report on the state of these objects as well.

For more information see the chapter “AutoSys Administrator,” in the Unicenter AutoSys Job Management for Windows User Guide, or the chapter “Configuring AutoSys,” in the Unicenter AutoSys Job Management for UNIX User Guide.

chk_auto_up will look for event processors both on the current machine and on machines in the Network Machine List, which is specified on the AutoSys Administrator event processor screen.

chk_auto_up will look for event processors both on the current machine and on machines in the EDMachines list, which is located in the AutoSys configuration file $AUTOUSER/config.$AUTOSERV.

Options

-Q Indicates that the command should output just the exit code without any descriptive message. This makes the command useful for inclusion in shell scripts. In this case, the return code is sufficient to indicate the status.

Return Codes

One of the return codes listed following is returned by chk_auto_up. If you omit the -Q option, a descriptive message also will be displayed.

Return Code Optional Message

0 Event Processor not running; No Event Server.

1 Event Processor not running; Event Server up.

2 Event Processor not running; Primary and Dual-Event Servers up.

10 Event Processor up; Event Server name invalid, probably because the Event Server (EventServer parameter in the AutoSys configuration file) was correct when the event processor was started, but was corrupted before you ran:

chk_auto_up.

2–66 Reference Guide

chk_auto_up

Return Code Optional Message

11 Event Processor up; Event Server up.

12 Event Processor up; Primary and Dual-Event Servers up.

20 Shadow Event Processor up; Event Server name invalid (see return code 10).

21 Shadow Event Processor up; Primary Event Processor not running; Event Server up.

22 Shadow Event Processor up; Primary Event Processor not running; Primary and Dual-Event Servers up

30 Primary and Shadow Event Processors up; Event Server name invalid (see return code 10).

31 Primary and Shadow Event Processors up; Event Server up.

32 Primary and Shadow Event Processors up; Primary and Dual-Event Servers up.

50 Event Processor “not running” because could not connect to machine in the EDMachines list in the AutoSys configuration file; No Event Server.

51 Event Processor “not running” (see return code 50); Event Server up.

52 Event Processor “not running” (see return code 50); Primary and Dual-Event Servers up.

60 Event Processor “not running” because no machines listed in the EDMachines list in the AutoSys configuration file; No Event Server.

61 Event Processor “not running” (see return code 60); Event Server up.

62 Event Processor “not running” (see return code 60); Primary and Dual-Event Servers up.

99 One of the following can cause this message to appear:

■ One or more of the following environment variables is not set or is set incorrectly: AUTOSYS, AUTOSERV, AUTOUSER.

■ You issued the chk_auto_up command with invalid arguments.

Example

To check that the database and Event Processor are up and to view the results on

AutoSys Commands 2–67

your monitor, enter:

chk_auto_up

chk_cond (SP)

chk_cond (SP)

AutoSys Stored Procedure.

Function

Prints diagnostics if a job has starting conditions based on another job that does not exist.

Syntax

chk_cond job_name

Description

The chk_cond (SP) prints a report containing diagnostics about a job having starting conditions that are based on another job that does not exist.

Note: chk_cond is called every time a job is inserted or updated. If there is a missing job, chk_cond prints out a warning message.

chk_cond is supported for Sybase and Microsoft SQL Server databases only.

chk_cond is supported for Sybase databases only.

Options

job_name Specifies the name of the job against which diagnostics should be run. If job_name is not specified, the stored procedure will be run against all jobs.

2–68 Reference Guide

chk_cond (SP)

Example

A job named “jobA” has the following conditions specified:

condition: success(jobB) and success(jobC)

But, “jobC” does not exist.

To print out diagnostics for all jobs in a Sybase data server, enter:

1> chk_cond 2> go

The following would be displayed to standard output:

Job Missing_Condition_Job --------- -------------------------------- jobA jobC

Note: You can also use the chk_cond stored procedure with a Microsoft SQL Server database, using the ISQL/w graphical query interface.

AutoSys Commands 2–69

clean_files

clean_files

Function

Removes Remote Agent log files from the various machines.

Syntax

clean_files -d days

Description

The clean_files command deletes old Remote Agent log files. It performs this task by searching the database for all machines which have had jobs started on them, then sending a command to the Remote Agent on that machine to purge all remaining log files from the machine’s Remote Agent Log directory (specified during the installation process or in the Local Agent Logging Directory field of the AutoSys Administrator Remote Agent screen).

Remote Agent log files are deleted automatically only if the job completed normally, and if the Clean Temporary Files box is checked on in the AutoSys Administrator Event Processor screen.

Remote Agent logs for failed jobs are not deleted, and these files can take up valuable disk space. Therefore, we recommend that you run the clean_files command daily, as part of the daily Database Maintenance cycle, which you can set up in the AutoSys Administrator Event Processor screen.

The clean_files command deletes old Remote Agent log files. It performs this task by searching the database for all machines which have had jobs started on them, then sending a command to the Remote Agent on that machine to purge all remaining log files from the machine’s Remote Agent Log directory (specified by AutoRemoteDir in the AutoSys configuration file).

Remote Agent log files are deleted automatically only if the job completed normally, and if the CleanTmpFiles parameter in the AutoSys configuration file specifies that the log files be deleted at the end of each job.

2–70 Reference Guide

clean_files

Remote Agent logs for failed jobs are not deleted, and these files can take up valuable disk space. Therefore, we recommend that you run the clean_files command daily, as part of the daily DBMaint cycle.

Note: If you are experiencing problems running jobs successfully, the Remote Agent log files are very useful diagnostic tools. In this case, you should not run clean_files, or remove the Remote Agent log files using any other method, until the problem has been diagnosed and resolved.

Options

-d days Specifies that log files older than the number of days will be removed.

Note: This option is only effective on NTFS file systems. On other file systems, which do not store file time stamps (For example: FAT), all Remote Agent log files are removed.

Example

To start clean_files and delete all Remote Agent log files older than 1 day, enter:

clean_files -d 1

AutoSys Commands 2–71

cron2jil

cron2jil

Function

Translates UNIX crontab files into AutoSys JIL format.

Syntax

cron2jil -f crontab_file [-d output_directory] [-i include_file] [-m machine] [-p prefix]

Description

The cron2jil command converts each line in a UNIX crontab file to a corresponding JIL script (*.jil file) and, if necessary, a run calendar file (*.cal file). The cron2jil command cannot comprehensively address all job processing requirements. It should be used as a first step in converting from cron to the AutoSys environment. The second step requires editing the newly created JIL and calendar files to ensure the desired job processing.

When cron2jil reads a crontab file, it assigns job names by combining the basename of the job’s command and the line number of the file. For example, the following crontab entries would result in the job names “cp_1” and “mail_2” respectively.

>>0,59 0,23 * * 0,6 /bin/cp /etc/passwd /etc/passwd.bak >>0,59 * * * 0,6 /usr/ucb/mail root@support1 < /tmp/errorLog

After translation, cron commands involving pipes and I/O redirection perform just as they did in the cron environment. If run calendars are created, cron2jil only generates calendars with a one year duration. After conversion, pipe and I/O redirections might not take full advantage of the fault tolerance mechanisms of AutoSys. For example, the exit code of a failed command in a pipe might not result in the failure of the complete command expression. Because of this behavior, translated JIL scripts should be edited and pipes should be split into separate jobs with the appropriate conditions and job control. With this approach, problems can be detected and reported at the point of failure.

2–72 Reference Guide

cron2jil

Cron2jil does not generate JIL files for jobs that are defined in crontab to start every minute; for example with an asterisk (*) specified in the first field of the cron listing. In the AutoSys environment, this is a special case and should be remedied by using a starting condition for the job that is the successful completion of the job itself.

Note: Once any *.jil or *.cal files are generated, you must submit these files to the AutoSys database using the jil and the autocal_asc commands, respectively.

Options

-f crontab_file Specifies the name of the crontab formatted file.

-d output_directory Specifies the directory to which the *.jil and *.cal files should be written. The default is the current working directory.

-i include_file Specifies the name of a file containing JIL statements that are to be included in every generated *.jil file. This file must be created before the conversion, and it can contain any default JIL statements.

-m machine Specifies the name of the machine on which the translation should occur. If no machine is specified, the default is “localhost.”

-p prefix Specifies a prefix that should be inserted before each job’s name. For example, if a prefix of “AUTO” is specified, the jobs cited in the example above would have the following names: “AUTOcp_1” and “AUTOmail_2.”

Example

To translate a crontab file with the name “daily,” enter:

cron2jil -f daily

AutoSys Commands 2–73

dbstatistics

dbstatistics

Function

Generates statistics in the data servers to maintain an optimal performance environment for AutoSys.

Syntax

dbstatistics

Description

dbstatistics performs the following tasks:

■ It update statistics in the database for optimal performance by invoking the Sybase Transact-SQL command update statistics. For Sybase and Microsoft SQL Server databases, it updates the statistics for the event, job, job_status, and job_cond tables. For Oracle, it computes statistics for all of the AutoSys tables.

■ It update statistics in the database for optimal performance by invoking the Sybase Transact-SQL command update statistics. For Sybase databases, it updates the statistics for the event, job, job_status, and job_cond tables. For Oracle, it computes statistics for all of the AutoSys tables.

■ For Sybase only: dbstatistics recompiles stored procedures in the event, job, and job_status tables by invoking the Sybase Transact-SQL command sp_recompile.

2–74 Reference Guide

dbstatistics

■ dbstatistics runs the AutoSys dbspace command to check the available space in the database. dbspace prints a summary of the free space versus the used space in the database. If the amount of free space is insufficient, dbspace 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 allocated for extents not the number of bytes that are in use. The extents may be nearly empty, but DBMaint reports the whole extent as used space.

■ dbstatistics calculates and updates the average job run statistics in the avg_job_run table. The old data is overwritten with the new data. The update statistics command returns either a 0 or 1; 0 indicates success and 1 indicates failure. The average job run statistics are used by AutoSys/Xpert.

AutoSys Commands 2–75

eventor

eventor

Function

Starts the Event Processors.

Syntax

eventor [-f] [-n] [-q][-G] [-M shadow_machine]

Description

Use the eventor command to bring up the event processor (and, optionally, the Shadow Event Processor), also referred to as the “event demon.” eventor runs in the background, by default. It first makes sure that another Event processor of the same instance is not running on the same machine as this instance of AutoSys (as determined by the $AUTOSERV variable), unless two event processors are specified in the configuration file.

It then runs chase, which inspects the database to determine which jobs are supposed to be running, and then checks each machine to verify that the jobs are there. If problems are detected, chase sends alarms or failure events, depending on the options specified, for any missing jobs. If the missing jobs can be restarted, they are automatically restarted.

The eventor -M command brings up the Primary and the Shadow Event Processor (which takes over if the Primary Event Processor machine fails).

If the event processor has been down for a long period of downtime, you can start it in Global AutoHold mode by specifying the -G option. This prevents the system from being flooded at once with numerous jobs, which were scheduled to run during the downtime.

For more information see the section “High-Availability Option: Shadow Event Processor,” in the chapter “Introduction to AutoSys,” in the Unicenter AutoSys Job Management for UNIX User Guide.

2–76 Reference Guide

eventor

Log Files

Eventor writes log information to the file named $AUTOUSER/out/ event_demon.$AUTOSERV. The output from the chase command is written to this same log file.

By default, eventor executes the tail -f command against the log file. This tail is useful for monitoring the execution of the event processor, particularly when there are problems with its startup. For example, if the machine from which eventor is issued does not have a valid AutoSys license, the event processor will not start. The only indication that this condition exists is a message output by the Event Processor in its log file. To exit the tail command, use Ctrl+C in the window displaying the event processor log.

The Shadow Event Processor writes log information to the $AUTOUSER/ out/event_demon_shadow.$AUTOSERV file.

-f Specifies that the event processor should run in the foreground, and all of its output should be sent to the display from which the command was issued.

Options

Note: The -f option is not recommended for production use. The default behavior is to run the Event processor in the background, with all output going to the $AUTOUSER/out/event_demon.$AUTOSERV file.

-n Specifies that eventor is not to run the chase command on startup. The default behavior is to run the chase -A -E command. The chase command inspects the database to find out what jobs are supposed to be running, then it checks each machine to verify that the jobs are there. If there are any problems, chase sends alarms, changes the missing jobs’ states to FAILURE, and, if conditions permit, causes the missing jobs to be restarted.

All chase output is redirected to the following file:

$AUTOUSER/out/event_demon.$AUTOSERV

-q Specifies that eventor should run in quiet mode, meaning that after the event processor has been started, eventor should not execute the tail -f command on the event_demon log file.

AutoSys Commands 2–77

eventor

-G Starts up the event processor in Global AutoHold mode. Global AutoHold is useful if you are restarting the event processor after a period of downtime. This prevents the system from being flooded at once with numerous jobs that were scheduled to run during the downtime. When in Global AutoHold mode, the event processor evaluates all jobs whose starting conditions have passed and are eligible to run. But instead of starting the jobs, the event processor puts the jobs ON_HOLD. This gives you the opportunity to decide which jobs should run by selectively starting them with the Force Start Job button in the Operator Console, or with the sendevent -E FORCE_STARTJOB command.

When Global AutoHold is on, the following message appears after every timestamp:

-------------< Date: 12/12 20:22:00 >--------------- ******* Global AutoHold IS ON ! *******

If Global AutoHold is on, you cannot take a job OFF_HOLD through the Operator Console or the sendevent command. The only way to start a job when Global AutoHold is on is with the FORCE_STARTJOB event. When sent, this event will override the AutoHold mode.

If you start a Shadow Event Processor with the -G flag, the Shadow Event Processor will also be in Global AutoHold mode.

Turn off Global AutoHold, you must shut down the event processor, then start it up again without the -G flag.

-M shadow_machine Specifies that a Shadow Event Processor should be started.

No Options Set This is the recommended way to bring up the event processor. All restart checks are performed, alarms are sent, and output is recorded in the log file.

Note: Do not attempt 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.

2–78 Reference Guide

eventor

Examples

1. To start the Event Processor under normal circumstances, enter:

eventor

2. To start the Event Processor on the local machine, and a Shadow Event Processor on the machine named “jupiter,” enter:

eventor -M jupiter

AutoSys Commands 2–79

gatekeeper

gatekeeper

Function

Maintains license keys.

Syntax

Gatekeeper

Description

gatekeeper is an interactive utility you can use to maintain AutoSys license keys located in the AutoSys database. The following types of keys are used in AutoSys:

■ Single Time Key

Time Keys are assigned for software evaluations, and will indicate an expiration date. For purchased licenses, the expiration date is

“*Infinity*”.

Note: When entering a temporary license key, you must enter a four-digit year.

■ Server Key

Required for each server (that is, machine running an Event processor). You will be asked for the host name and ID of the server machine where the Event Processor will run, and the key will be generated for you by Computer Associates Technical Support.

■ Client Key

Required for each client (that is, machine running any AutoSys software, from the Remote Agent which runs jobs under AutoSys control, to the utilities, such as jil). You will be asked for the host name and host ID of the client machine, and the key will be generated for you by Computer Associates Technical Support. Frequently, the AutoSys server machine is also a client; if it is, it will need a client license as well as a server license key. Each client must have a key registered individually.

For more information see the chapter “License Management,” in the Unicenter AutoSys Job Management for UNIX User Guide.

2–80 Reference Guide

gatekeeper

Xpert Keys are assigned to separately enable the AutoSys/Xpert product.

Example

To start the license utility, enter:

Gatekeeper

AutoSys Commands 2–81

jil

jil

Function

Runs the Job Information Language (JIL) processor to add, update, and delete AutoSys jobs, machines, monitors, and reports. Also used to insert one-time job override definitions.

Syntax

jil [-q] [-S autoserv_instance] [-V none | job | batch]

Description

The jil executable is the language processor for the AutoSys Job Information Language (JIL). Using JIL (the language itself), you can define and update jobs, monitors, reports, and machines. The jil command can be used in one of two ways:

■ Automatically submit job definitions to the AutoSys database. You do this by redirecting a JIL script file to the jil command.

■ Interactively submit job definitions to the AutoSys database. You do this by issuing the jil command only and entering JIL statements at the provided jil>> prompts. To exit interactive mode, enter “exit” at the prompt, or click Ctrl+D.

A JIL file contains a sub-command such as insert_job and a set of attributes for that job, in a specific format. The complete syntax rules are defined following. The JIL sub-commands listed in the following table are used to create, update, delete, or override a job definition.

Sub-command Action

insert_job Add a new job to AutoSys.

update_job Edit fields on an existing job.

delete_job Delete this job from AutoSys.

2–82 Reference Guide

jil

Sub-command Action

delete_box Delete this box job, and recursively delete all the jobs contained in the box.

override_job Insert overrides on indicated job attributes for the next run of this job.

The JIL syntax rules are following:

Rule 1

Each sub-command uses the following form:

sub_command: job_name

where:

sub_command Is one of the sub-commands listed in the previous table.

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 are of the form:

attribute_keyword: value

where:

attribute_keyword Is one of the legal JIL attributes.

value Is the setting to be applied to the attribute.

Rule 3

Multiple attribute statements can be entered on the same line; however, they must be separated by at least one space.

Rule 4

A box that contains jobs must be defined before the jobs can be placed in it.

AutoSys Commands 2–83

jil

Rule 5

Legal value settings can include any of the following characters: upper and lowercase letters, numbers, colons (if the colon is escaped), and the “at” symbol(@).

Rule 6

Any colons used in an attribute statement’s value setting must be escaped, since 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.

Note: When specifying drive letters in commands, the colon ( : ) must be escaped. These examples are valid: "C:\tmp" and C\:\tmp. This example is not valid: C:\tmp.

Rule 7

Comments are indicated using one of two methods.

■ An entire line can be commented by placing a pound sign (#) in the first column.

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

One of the primary advantages of using JIL is the ability to use the UNIX tools that are available for file manipulation that create and control AutoSys job definitions. For example, you run the following command on every workstation:

rm /tmp/stuff/*

Then, it would be far simpler to create a “generic” JIL template (text file), and copy it for each machine, changing only the machine attribute of the job. In fact, you could iteratively copy the template to a temporary file, replacing the machine name, and redirecting the temporary file into jil.

2–84 Reference Guide

jil

Options

-q Specifies that jil should be run in “quiet” mode and that it should only output error messages. This is useful when entering a large number of jobs, so that errors can be easily seen. The default is to also output status messages, indicating the success or failure of the JIL subcommands. This information is very useful and should typically be allowed to print out.

-S autoserv _instance

Specifies the three-character AutoSys instance name, for example; ACE, (and therefore the RDBMS) to which to apply the definitions. If not specified, jil will use the value of the environment variable named %AUTOSERV%.

Specifies the three-character AutoSys instance name, for example; ACE, (and therefore the RDBMS) to which to apply the definitions. If not specified, jil will use the value of the environment variable named $AUTOSERV.

-V none | job | batch Specifies whether or not the JIL processor should verify that jobs specified in the job dependency condition for the job actually exist in the AutoSys database. By default, the JIL processor always performs this operation on a job-by-job basis, when jobs are submitted to the database. You can use this option to bypass this behavior by using the none or batch arguments. The none option does not perform any job dependency verification. The batch option checks the database after the JIL file has been entirely processed. The job option checks the database on a job-by-job basis; this is the same as not using the –V option.

WARNING! The portion of a condition statement that includes job dependencies on undefined jobs will evaluate to FALSE for all conditions except not running. For example, if “jobA” has the condition success(jobB) and success(jobC), and “jobC” is not defined in the database, the condition will evaluat to FALSE. If “jobA” depends on not running(jobC), the condition will evaluate to TRUE.

e

When you use this option, the jobs specified in job dependencies that do not exist in the AutoSys database are reported to standard output. The display will look something similar to the following:

________________________________________________________ Insert/Updating Job: JobA *** WARNING: The Following Jobs are referenced in the *** Conditions for this Job, YET are not defined! 1) JobC Database Change WAS Successful! ________________________________________________________

AutoSys Commands 2–85

jil

Examples

1. To redirect a text file named “job1” containing JIL statements into jil, enter:

jil < job1

2. To redirect a text file named “job1” containing JIL statements into jil and prohibit the JIL processor from verifying the existence of specified jobs in its job dependencies, enter:

jil < job1 -V none

2–86 Reference Guide

job_depends

job_depends

Function

Reports information about the dependencies and conditions of a job.

Syntax

job_depends [-c | -d | -t] [-J job_name] [-F from_date/time][-T to_date/time] [-L print_level] [-D data_server:database | -D TNSname]

Description

job_depends provides detailed reports about the dependencies and conditions of a job. This command can be used to determine the current state of a job, its job dependencies, and (for boxes) nested hierarchies as specified in the job definition, and a report of what jobs will run during a given period of time.

Options

-c

Current Condition Status. Prints out the current state of a job and the names of any jobs that are dependent on this job. The information from this option is similar to that displayed in the Job Dependencies dialog, which you can open from the Scheduler Console.

Current Condition Status. Prints out the current state of a job and the names of any jobs that are dependent on this job. The output of this option is similar to that displayed in the Starting Conditions area of the Job Activity Console.

-d Dependencies Only. Prints out the starting conditions for a job; no indication of the current status of the job is provided. For box jobs, jobs inside the box are shown hierarchically. The -L option controls how many levels of nesting are displayed.

AutoSys Commands 2–87

job_depends

-t Time Dependencies. Prints out the starting conditions for a job; however, the top level of jobs (or boxes) that are reported are limited to those that will start within the time period specified by the job or box’s date conditions. In the event that a box will satisfy those date conditions, all of the jobs within it will also be printed. The level of nesting displayed can be controlled with the -L option.

job_depends -t does not calculate all complex job dependencies when reporting on the jobs and boxes that are scheduled to run. For example, “JobB” may have a date condition and be dependent on “JobA.” The date conditions for “JobB” may be met for a given day, while those for “JobA” are not. As a result, “JobA” won’t run, and neither will “JobB.” However, “JobB” will appear on the report produced by job_depends. For this reason, the starting conditions are also printed; for example next to “JobB” would be the condition:

success(JobA).

-J job_name Indicates the job on which to report, where job_name is the name of the target job. To report on all jobs, enter the word ALL for the job_name. Wildcards are also supported, using the percent symbol (%). For example, to print all jobs that have ‘Backup’ in their job name, enter:

%Backup%

Note: The underscore (_) character may also be used as a wildcard to match exactly one character. However, this can lead to some unexpected results when the job name itself contains a (_) character. For example, specifying the job name “mon_%” will select all jobs beginning with the string “mon,” such as mon_box, monet, and so on.

The SQL ESCAPE option is not supported for wildcards in AutoSys.

-F "from_date/time" Indicates the report start date and time, where from_date/time is the date and time of the first job in the report. This option is used with the -T option only. The format is MM/DD/[YY]YY HH:MM.

If you enter a two-digit year, AutoSys saves the setting to the database as a four-digit year. If you enter 79 or less, AutoSys prepends 20, and, if you enter 80 or greater, AutoSys prepends 19.

2–88 Reference Guide

job_depends

-T "to_date/time” Indicates the report end date and time, where o_date/time is the date and time of the last job in the report. This option is used with the -F option only. The format is MM/DD/[YY]YY HH:MM. If this option is not specified, job_depends will search without limitation into the future.

t

If you enter a two-digit year, AutoSys saves the setting to the database as a four-digit year. If you enter 79 or less, AutoSys prepends 20, and, if you enter 80 or greater, AutoSys prepends 19.

-L print_level Indicates the print level for the report, where print_level is any valid numeric value specifying the number of levels of nesting to display for a box job. This option is used with the -d and -t options only.

For example, a print_level of 2 indicates that information for the specified box job and two levels of jobs within that box, should be shown. If you want to report on the outer most box alone, specify “0.” The default is to list all levels within the box.

-D data_server: database

Indicates the name of the Sybase data server, and the specific database within it, to be searched for the specified information. Normally, job_depends consults the environment variables and the AutoSys configuration file to determine to which database to connect. This option enables job_depends to report on any AutoSys Event Server on the network.

Indicates the name of the Sybase or Microsoft SQL Server data server, and the specific database within it, to be searched for the specified information. Normally, job_depends consults the environment variables and the AutoSys Administrator configuration settings to determine to which database to connect. This option enables job_depends to report on any AutoSys Event Server on the network.

AutoSys Commands 2–89

job_depends

-D TNSname

Indicates the TNS alias name of the Oracle data server to be searched for the specified information. Normally, job_depends consults the environment variables and the AutoSys Administrator configuration settings to determine to which database to connect. This option enables job_depends to report on any AutoSys Event Server on the network.

Indicates the TNS alias name of the Oracle data server to be searched for the specified information. Normally, job_depends consults the environment variables and the AutoSys configuration file to determine to which database to connect. This option enables job_depends to report on any AutoSys Event Server on the network.

Example

1. To display a report on the current condition status of a job named “jobX,” you would issue the following command:

job_depends -c -J jobX

You would see a report similar to the following displayed to standard output:

________________________________________________________________ Start Dependent Job Name Status Date Cond? Cond? Jobs? -------- ------ ---------- ------ --------- jobX INACTIVE No No Yes Dependent Job Name ------------------- jobY ________________________________________________________________

This report shows that “jobX” has no date or starting conditions, but another job, “jobY” is dependent on it.

2–90 Reference Guide

job_depends

2. To display a report on the current condition status of a job named “jobA,” which does have starting conditions and dependencies, you would issue the following command:

job_depends -c -J jobA

You would see a report similar to the following displayed to standard output:

________________________________________________________________ Start Dependent Job Name Status Date Cond? Cond? Jobs? -------- ------ ---------- ------ --------- JobA INACTIVE MetYe s No Condition: done(jobB) and success(jobC) and success(jobD) and success(jobE) and success(jobF) and success(jobG) and success(jobH) and success(jobI) Atomic Condition Current Status T/F ---------------- -------------- --- DONE(jobB) INACTIVE F SUCCESS(jobC) INACTIVE F SUCCESS(jobD) INACTIVE F SUCCESS(jobE) RUNNING F SUCCESS(jobF) INACTIVE F SUCCESS(jobG) INACTIVE F SUCCESS(jobH) SUCCESS T SUCCESS(jobI) INACTIVE F ________________________________________________________________

This report shows that even though the date conditions have been met for “jobA,” it is in the INACTIVE state because its starting conditions have not been met. An “F” next to an atomic condition indicates that the atomic condition has not been satisfied (F = False, T = True).

AutoSys Commands 2–91

job_depends

3. To display a report on the box job named “job_bxA” showing all the nested levels of jobs and boxes within this job, you would enter the following command:

job_depends -d -J job_bxA

You would see a report similar to the following displayed to standard output:

________________________________________________________________ Job Dependency Report Job Name Date Cond? Atomic Start Conditions _____________________ _________________________________ job_bxA Yes d(job1) s(job2) job3 job_bxB ------- ------- job_bxC ------- ------- job4 ------- ------- job5 ------- ------- job6 ------- ------- job7 ------- ------- job8 ------- s(job6) s(job7) ________________________________________________________________

In this report, all the nested jobs and boxes within “job_bxA” are shown. If a job has a date condition or any atomic starting conditions, these are indicated. Starting conditions are abbreviated as follows: s = SUCCESS, f = FAILURE, d = DONE, t = TERMINATED, and n = NOTRUNNING.

2–92 Reference Guide

job_depends

4. To display a report on jobs that are scheduled to run on New Years day, you would enter the following command:

job_depends -t -J ALL -F "01/01/1998 00:00" -T "01/02/1998 00:00"

The -F (from date/time) and -T (to date/time) options allow you to specify the date and time for the beginning and end of the report. You would see a report similar to the following displayed to standard output:

________________________________________________________________ Job Forecast Report From: 01/01/1998 00:00:00 To: 01/02/1998 00:00:00

Job Name NextStart Atomic Start Conditions _________________________________________________________ job1 01/01/191 12:05 ------- job_bxA ------- d(job1) job2 job_bxB ------- ------- job_bxC ------- ------- job3 ------- ------- job4 ------- ------- job5 ------- ------- job6 ------- ------- job7 ------- s(job5) s(job6)

job8 01/01/1998 02:00 ------- job_bxD ------- d(job8) job_bxE ------- ------- job9 ------- ------- job10 ------- -------

job11 ------- ------- job12 ------- ------- job13 ------- ------- job14 ------- s(job11) s(job12) s(job13)

job15 01/02/1998 04:00 ------- job_bxF ------- d(job15) job_bxG ------- ------- job16 ------- ------- job17 ------- -------

job18 ------- ------- job19 ------- ------- job20 ------- s(job18) s(job19) ________________________________________________________________

AutoSys Commands 2–93

monbro

monbro

Function

Runs a monitor or report (browser) previously registered in the database.

Syntax

monbro -N name [-P poll_frequency] [-D data_server:database| -D TNSname] [-q]

Description

monbro runs a monitor or report (browser) that has already been defined, either using either jil or the Monitor/Browser Editor.

Output from monbro goes to standard output. If a monitor is configured with sound on, it will use the sound capabilities of the machine on which it is running.

The definition of the monitor or report to be run must reside on the database for the instance you are accessing. monbro can connect to any that your AutoSys instance is configured to use. By default, it will inspect the environment variables %AUTOSYS%, %AUTOUSER% and %AUTOSERV% to determine which database to connect to. This default can be overridden by using the -D option.

When you define a monitor using the Monitor/Browser Editor, you define the instance to which it should connect in the New Monitor/ Browser dialog, which you open from the New option on the File menu.

For more information see the Unicenter AutoSys Job Management for Windows User Guide, or the Unicenter AutoSys Job Management for UNIX User Guide.

2–94 Reference Guide

monbro

monbro runs a monitor or report (browser) that has already been defined, either using either jil or the GUI.

Output from monbro goes to standard output. If a monitor is configured with sound on, it will use the sound capabilities of the machine on which it is running. The sound clips must be pre-recorded, and the machine running monbro must be able to access the $AUTOUSER/sounds directory.

The definition of the monitor or report to be run must reside on the database for the instance you are accessing. monbro can connect to any that your AutoSys instance is configured to use. By default, it will inspect the environment variables $AUTOSYS, $AUTOUSER and $AUTOSERV to determine which database to connect to. This default can be overridden by using the -D option.

Options

-N name Specifies the name of the monitor or report (browser) to be run. The percent (%) character may be used in the name as a wildcard; or you can type ALL for all.

-P poll_frequency Applies to monitors only, and indicates the time interval (in seconds) to sleep between polls of the database. The default is 10 seconds.

-D data_server :database

Specifies the name of the Sybase or Microsoft SQL Server data server, and the specific database within it, from which to retrieve events and the monitor or report definition. The default behavior is to inspect the AutoSys environment variables and AutoSys Administrator configuration settings to determine which data server and database to use.

Specifies the name of the Sybase data server, and the specific database within it, from which to retrieve events and the monitor or report definition. The default behavior is to inspect the AutoSys environment variables and configuration file to determine which data server and database to use.

AutoSys Commands 2–95

monbro

-D TNSname

Specifies the TNS alias name of the Oracle database from which to retrieve events and the monitor or report definition. The default behavior is to inspect the AutoSys environment variables and AutoSys Administrator configuration settings to determine which database instance to use.

Specifies the TNS alias name of the Oracle database from which to retrieve events and the monitor or report definition. The default behavior is to inspect the AutoSys environment variables and configuration file to determine which database instance to use.

-q Specifies that you want to display monbro definitions in JIL format.

Examples

To run a monitor called “mon1” which is defined in the default database, enter:

monbro -N mon1

Sample output with the -q option:

monbro -N mon1 -q insert_monbro: xxx mode: m all_events: Y job_filter: a sound: N alarm_verif: N insert_monbro: xxx2 mode: b all_events: N alarm: Y all_status: N running: N success: Y failure: Y terminated: N starting: N restart: N job_filter: b job_name: box currun: N after_time: "11/11/1997 12:12"

2–96 Reference Guide

record_sounds

record_sounds

Function

Records sounds to be played back by monitors.

Syntax

record_sounds AutoSys_password

Description

This utility records sounds for playback in monitors. It stores the sounds in files located in the $AUTOUSER/sounds directory.

It assumes that the workstation you are on is equipped for sound, has a microphone plugged in, and is set up correctly.

As of this printing, the sound facility is supported on Solaris, and SGI platforms.

Record_sounds is an interactive tool that will record sounds for jobs (the Job Names) or System Phrases (for example; RUNNING or SUCCESS). The recordings for all System Phrases come with AutoSys. However, we recommend that the person who records the Job Names should also re-record the System Phrases.

Record_sounds inspects the AutoSys database to get lists of Job Names and System Phrases. You will be prompted for each sound to record.

Sounds are stored in various files in the $AUTOUSER/sounds directory. The file name for these files is constructed using the Job Name or the System Phrase name. For example, the sound file for the job “DB_Backup” is stored in the $AUTOUSER/sounds/DB_Backup file, and the MINRUNALARM System Message is stored in the $AUTOUSER/sounds/MINRUNALARM file.

If you have a favorite pre-recorded sound you want to use, you can simply copy it into the proper file. record_sounds gets lists of jobs names and system phrases from the AutoSys database. The sound clips themselves are stored in files in the $AUTOUSER/sounds directory. When you run the command, you are prompted to decide which sounds you will record.

AutoSys Commands 2–97

record_sounds

To Record Sounds:

1. Choose whether to record job names, system phrases, or one sound only. If you choose one sound, you must supply the file name. If you choose to record job names or system phrases, you are prompted by the following message:

Record only those sounds that are missing? y/n

If you answer y, you will then be prompted to record those sounds that are not already in the $AUTOUSER/sounds directory. Selecting this option is useful for maintaining a complete set of sounds when new jobs are added.

If you answer n, you will be prompted to record all of the sounds until you finish or exit.

2. At each prompt, you are asked to click Enter to start recording, then speak or play a sound into the microphone, and click Enter to end the recording.

3. To exit the record sounds utility, click Ctrl+C at any time.

Sounds are stored in files in the $AUTOUSER/sounds directory. The file name is the job or system phrase name. For example, the sound file for the job “DB_Backup” is stored in $AUTOUSER/sounds/DB_Backup, while the message for MINRUNALARM is stored in the $AUTOUSER/sounds/MINRUNALARM file. If you have a favorite pre-recorded sound that you want to use, simply copy it into the appropriate file.

Example

When recording sounds, be sure the workstation you are on is equipped for sound, has a microphone plugged in, and is set up correctly, then, enter:

record_sounds

2–98 Reference Guide

sendevent

sendevent

Function

Sends events to AutoSys for a variety of purposes, including starting or stopping AutoSys jobs, stopping the Event processor, and putting a job on hold. This command is also used to set AutoSys global variables or cancel a scheduled event.

Syntax

sendevent -E event [-S autoserv_instance] [-A alarm] [-J job_name] [-s status] [-C comment] [-P priority] [-M max_send_trys] [-q job_queue_priority] [-T "time_of_event"] [-G "global_name=value"] [-k signal_numbers] [-u]

Description

Issuing the sendevent command is the only method of externally sending an event to AutoSys for such purposes as starting a job or stopping the event processor. You can also use sendevent to communicate with any instance of AutoSys, provided the machine on which it is executing can connect with the databases associated with that instance of AutoSys.

The event that is sent is written to the database, which the event processor is continually polling. The event processor reads and processes the event.

The Send Event Tool can also be used to send an event. You access this tool, from Scheduler Console and Alarm Manager.

The Send Event dialog can be used to send an event. You access this dialog by clicking Send Event in the Job Activity Console.

Note: To issue a sendevent on a job, you must have execute permission on that job. Only alarms, comments, and set global can be sent without regard to permissions.

AutoSys Commands 2–99

sendevent

Options

-E event Specifies the event to be sent. This option is required. Any one of the following events may be specified:

STARTJOB

Start the job specified in -J job_name if the starting conditions are satisfied. A STARTJOB event ignores time and date conditions, but it does consider other start conditions, such as dependencies on other jobs. This command cannot be used on jobs in boxes. Jobs in boxes inherit the starting conditions of the box they are in; as a result, they will be started when that box is started.

KILLJOB

Kill the job specified in -J job_name. The action depends on one of the following job types:

■ Command Jobs

If the AutoSys job is running on a UNIX, this kills the process that is currently running and all the processes that it has spawned; for example: the process group. It will not kill orphan processes. It sends a signal to the process, waits five seconds, then sends a second signal, if the process is still there. The default kill signals to be sent are specified in the Kill Signals field in the AutoSys Administrator Event Processor screen. This enables the application programmer to program commands that will react intelligently to the KILLJOB event. For UNIX processes, specific signals can be specified, or default signals can be overridden using the -k option.

Windows does not support the concept of process groups. If the job that was launched was a *.exe, KILLJOB will kill the process specified in the command definition. If the job being run is not a *.exe (for example, *.bat, *.cmd, or *.com), AutoSys uses CMD.EXE to launch the job, and KILLJOB will kill only the CMD.EXE process. The Job Status will be set according to the return code of the killed CMD.EXE process. This status can be any one of the following: SUCCESS, FAILURE, or TERMINATED. Any processes that were launched by user applications or batch (*.bat) files will not be killed.

Note: Work around this KILLJOB limitation, you can use the SEND_SIGNAL event. Your application must watch for a specified semaphore signal and react accordingly, and you can use the SEND_SIGNAL event to implement this behavior.

2–100 Reference Guide

sendevent

Kills the process that is currently running and all the processes that it has spawned; for example; the process group. It will not kill orphan processes. It sends a signal to the process, waits five seconds, then sends a second signal, if the process is still there. The default kill signals to be sent are specified in the AutoSys configuration file with the KillSignals parameter, and typically the signals are SIGINT and SIGKILL. This enables the application programmer to program commands that will react intelligently to the KILLJOB event. For UNIX processes, specific signals can be specified, or default signals can be overridden using the -k option.

■ Box Jobs

Changes the status to TERMINATED. No more jobs within the box will be started. Jobs that are already running will continue to run to completion.

■ File Watcher Jobs

Kills the file watcher job and changes the status to TERMINATED.

DELETEJOB

Delete the job specified in -J job_name from the database. If the job is a box, deletes the box and all the jobs in the box.

FORCE_STARTJOB

Start the job specified in -J job_name, regardless of whether the starting conditions are satisfied. Because multiple instances of the same job could be started using this command, we recommend you use the FORCE_STARTJOB event only in extreme situations.

Do not force start a job in QUE_WAIT state because jobs in QUE_WAIT state are already “started” and are waiting for machine resources to become available to run. If you want a job in QUE_WAIT to start running immediately, change the job queue priority to 0 (using the CHANGE_PRIORITY event).

If a job fails inside a box and you fix the problem manually, use FORCE_STARTJOB to rerun the job.

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

AutoSys Commands 2–101

sendevent

JOB_ON_ICE

Puts the job specified in -J job_name “on ice.” When a job is placed on ice, it effects downstream jobs dependent upon that job. For example, the starting conditions for jobs downstream from “JobA,” which has been put “on ice,” will evaluate as shown in the following table:

If the condition is this: It will evaluate this:

success (JobA) TRUE

failure (JobA) FALSE

terminated (JobA) FALSE

done (JobA) TRUE

notrunning (JobA) TRUE

exitcode FALSE

Note: If a job’s status is RUNNING or STARTING, AutoSys will not allow the job to be put “On Ice.”

JOB_OFF_ICE

Takes the job specified in -J job_name “Off Ice.” Jobs that are taken “Off Ice” will not start until the next time their starting conditions are met.

JOB_ON_HOLD

Puts the job specified in -J job_name “On Hold.” When a job is “On Hold”, it will not be started, and downstream dependent jobs will not run. A box cannot successfully complete if a job within it is ON_HOLD. If the job is already STARTING or RUNNING, you cannot put it ON_HOLD.

JOB_OFF_HOLD

Takes the job specified in -J job_name “Off Hold.” If the starting conditions are met, the job will be started.

2–102 Reference Guide

sendevent

CHANGE_STATUS

Forces a change in the status of the job specified in -J job_name. Ordinarily this should not be used, since AutoSys manages job state changes internally. If this option is selected, the -s status option must also be selected.

When you send a CHANGE_STATUS event, you are changing the status of the job in the database; this event does not affect the current running of the job. That is, if you change the status to running, the status is changed in the database but the job is not run. You will have to change the status to a termination state before the job can be run again.

STOP_DEMON

Stops the event processor service (event demon). This is the only way to stop the event processor. This command does not stop the AutoSys database.

Stops the event processor (event demon). This is the only way to stop the event processor. This command does not stop the AutoSys database.

CHANGE_PRIORITY

Changes the Job Queue Priority of the job specified in -J job_name to the priority specified by the -q priority arguments. Queue priority is the relative priority of all jobs in the queue. The lower the number, the higher the priority; zero means to run the job right away. If the job has not been started, priority is changed for the next run only. If the job has been started, and is in a queue, priority is changed immediately.

COMMENT

Attaches a message to the event, for informational purposes only. When used with the -J job_name option, the message is attached to the specified job for a given job run. When used with the -c option, sendevent will write a comment directly to the Event processor Log.

ALARM

Sends an alarm. Generally alarms are generated internally; however, using this event, users and programmers can send alarms to alert operators.

AutoSys Commands 2–103

sendevent

SET_GLOBAL

Sets an AutoSys global variable. This event is sent with a high priority so the Event Processor will process the variable before it is referenced by any jobs at runtime. The -G ”global_name=value” option must be used with this event.

SEND_SIGNAL

Sends a signal to a running AutoSys job. For processes running on UNIX systems, you must use the -k signal_numbers and -J job_name options with this event. For processes running on Windows, you must use the -k signal_name and -J job_name options with this event.

On Windows NT, you can use the SEND_SIGNAL event to signal a specific named semaphore. Then, you can program your application to watch for and react to that semaphore signal.

-S autoserv _instance

Specifies the three-character AutoSys instance, for example; ACE, to which the event should be sent. If not specified, sendevent will use the value of the environment variable named %AUTOSERV%.

Specifies the three-character AutoSys instance, for example; ACE, to which the event should be sent. If not specified, sendevent will use the value of the environment variable named $AUTOSERV.

-A alarm Specifies the name of the alarm to be sent. This option is only used when the specified event is ALARM; it is required when using this event.

-J job_name Specifies the name of the job to which the specified event should be sent. This option is required for all events except STOP_DEMON, COMMENT, ALARM, or SET_GLOBAL

2–104 Reference Guide

sendevent

-s status Specifies the status to which the job specified in -J job_name should be changed. This option is used only when the specified event is CHANGE_STATUS, which requires this option.

These are the valid statuses: RUNNING, STARTING, SUCCESS, FAILURE, INACTIVE, and TERMINATED.

Note: Changing the status to RUNNING does not cause the job to run. It only changes the status of the job in the database. Changing the status of a box to INACTIVE will cause all the jobs in the box to be changed also to INACTIVE.

-C comment Specifies a textual comment that is to be attached to this event for, documentation purposes only. The text string can be up to 255 characters, entered as a single line. If the text string contains spaces, the entire string must be enclosed in double quotes.

For example, this option can be used to document why a KILLJOB event was sent, in which case it is attached to the KILLJOB event and is viewable in an autorep report. Or, it may be a stand-alone comment (when issued with the COMMENT event), in which case it can be used to post a note to the event log.

For example, this option might be used to indicate a condition, which was noticed by the operator, and is “viewable” by using the autosyslog utility.

-P priority Specifies the priority to be assigned to the event being sent. The value may be from 1 to 1000, with 1 being the highest priority and 1000 the lowest. The default value is 10. Assign a high priority if the event must be processed immediately (for example, when attempting to place a job which is about to be started on hold).

-M max_send_trys Specifies the maximum number of times sendevent will attempt to send the event to the database. Any number of attempts may be specified. If all the specified send attempts resulted in failure, sendevent will exit with an exit code of “1.” The default is 0, meaning sendevent will try indefinitely.

-q job_queue_priority Specifies the new queue priority to be assigned to the job. This option is only used, and is required, with the CHANGE_PRIORITY event. The priority must be a numeric value from 0 to 99, with higher numbers indicating a lower priority. A value of 0 signifies to start the job immediately.

AutoSys Commands 2–105

sendevent

-T "time_of_event" Specifies the date and time when the event should be processed. The format is MM/DD/[YY]YY hh:mm, where hh denotes hours and must be from 0 to 23. Double quotes are required as part of the specification. This is used to schedule an event in the future. The default is to process the event immediately.

If you enter a two-digit year, AutoSys writes the setting to the database as a four-digit year. If you enter 79 or less, AutoSys prepends 20, and, if you enter 80 or greater, AutoSys prepends 19.

-G "global_name=value"

Specifies the name and value of a global variable when a SET_GLOBAL event is sent. The global_name and the value can each be a maximum of 30 characters (leading and trailing spaces in the value are ignored). Once a global variable is set, it can be referenced by jobs at runtime using the syntax by the indicated job attributes in the following table.

Job Attribute Global Variable Syntax

condition VALUE global_name operator “value”

command $$global_name or $${global_name}

watch_file $$global_name or $${global_name}

std_*_file $$global_name or $${global_name}

Delete a global variable from the database, set it with a value of DELETE, like:

sendevent -E SET_GLOBAL -G "global_name=DELETE"

Notes:

Global variables are stored in the AutoSys database, they are not set in the AutoSys environment. Therefore, they cannot be referenced in the job’s profile.

Global variables are stored in the AutoSys database, they are not set in the AutoSys environment. Therefore, they cannot be referenced in the default (etc/auto.profile) or the job’s defined AutoSys profile.

2–106 Reference Guide

sendevent

-k signal_numbers or signal_name

For processes running on UNIX, this argument specifies the signal number. This option is only used with the SEND_SIGNAL or KILLJOB event. This argument is required for the SEND_SIGNAL event. For KILLJOB events this option overrides any KillSignals specified in the AutoSys configuration file. The signal_numb rs value can contain a comma delimited list of signals to send to the process. In this case, the Remote Agent will send the first signal, sleep for five seconds, then send the next signal, and so forth. To send a signal to an entire process group, place a minus sign (-) before the appropriate signal_numb rs values.

e

e

For processes running on Windows, this argument is used only with the SEND_SIGNAL event, and it specifies the name of the semaphore that the application is watching.

Windows does not support the concept of process groups, and thus the KILLJOB event functions differently on Windows. Any processes that were launched by user applications or batch (*.bat) files will not be killed; only the CMD.EXE process will be killed. To work around this limitation, you can use modify your programs to watch for an AutoSys signal from an AutoSys job running on a Windows machine, and you can implement this using the SEND_SIGNAL event.

-u Cancels the event specified in the -E event option. This option can be used only for unprocessed events that are scheduled to be processed in the future. If no time is specified with the -T option, all events satisfying the indicated criteria (options) will be canceled. If multiple future events exist, the -T option can be used to specify a specific event for cancellation.

Canceled events are not deleted from the database. Their status is changed, for example: que_status=4, which prevents them from being processed.

AutoSys Commands 2–107

sendevent

Examples

1. To start a job named “test_install” that has no starting conditions (and therefore must be started manually), enter:

sendevent -J test_install -E STARTJOB

2. To force a job to start named “wait_job,” which is waiting on the completion of another job, and explain the reasons for your action, enter:

sendevent -J wait_job -E FORCE_STARTJOB -C "tired of waiting,forced it"

3. To change the status of a job called “ready_to_run” to ON_HOLD to prevent its execution, and to assign the sendevent command a high priority so it will be sent immediately, enter:

sendevent -J ready_to_run -E JOB_ON_HOLD -P 1

When you want the above job to run, enter:

sendevent -J ready_to_run -E JOB_OFF_HOLD

4. To prevent a job called “lock_out” from running between the hours of 11:00 a.m. and 2:00 p.m., a pair of sendevent commands could be used to place it on hold during that time. (These same sendevent commands could be placed in a job that is run daily to perpetuate this condition on a regular basis.)

Put the job on hold at 11:00 a.m., enter:

sendevent -J lock_out -E JOB_ON_HOLD -T "11/08/1997 11:00"

To take the job off hold at 2:00 p.m., enter:

sendevent -J lock_out -E JOB_OFF_HOLD -T "11/08/1997 14:00"

5. To write a comment into the Event processor log file, enter:

sendevent -E COMMENT -C "have not received EOD files - an hour late again"

6. To stop the Event processor at 2:30 a.m. on November 9, 1997 (it is always a good idea to attach a comment to this event), enter:

sendevent -E STOP_DEMON -T "11/09/1997 02:30" -C "stopped for upgrade"

7. To change a job called “resource_hog” to a lower priority (it is currently at 1 and is not yet running), and to only issue the sendevent command five times, rather than letting it try indefinitely, enter:

sendevent -J resource_hog -E CHANGE_PRIORITY -q 10 -M 5

The above command will change the job queue priority only for the next run of the job.

8. To kill a job named “wrong_job” which is running on another AutoSys instance called “PRD,” enter:

sendevent -J wrong_job -E KILLJOB -S PRD

2–108 Reference Guide

sendevent

9. To set a global variable named “today” having a value of “12/25/ 1997,” enter:

sendevent -E SET_GLOBAL -G "today=12/25/1997"

10. To delete the global variable named “today,” enter:

sendevent -E SET_GLOBAL -G "today=DELETE"

11. To cancel all unprocessed JOB_OFF_HOLD events for a job named “RunData,” enter:

sendevent -E JOB_OFF_HOLD -J RunData –u

11. To send the Unix signal number 1 to a job named “RunData,” enter:

sendevent -E SEND_SIGNAL -J RunData -k 1

12. When running a job on Windows, you can program your application to watch for a signal from AutoSys. More than one job can be programmed to watch for the same signal. The following code example uses a thread to create and then block on a semaphore named MyFirstSignal. This semaphore can then be signaled using the sendevent SEND_SIGNAL command. Then, as shown in the example program, the watchsem job watches for a signal on both the MyFirstSignal and MySecondSignal semaphores. A second application, such as a child process of the original job (application), could also watch and react to these signals. To signal the jobs, use this sendevent command from an AutoSys Instance Command Prompt window:

sendevent -E SEND_SIGNAL -J watchsem -K MyFirstSignal

This is the example program, which you can compile using cl watchsem.c:

#include <windows.h> /*Prototypes*/ void WatchForAutosysSignal(char *SignalName); DWORD WINAPI WatchAutosysSignalThread(LPVOID Parm); void main(void) { printf("This is your application running.\n"); printf("Call the WatchForAutosysSignal function\ with a name of a semaphore.\n"); WatchForAutosysSignal("MyFirstSignal"); printf("You can set up multiple watches if you choose.\n"); WatchForAutosysSignal("MySecondSignal"); printf("Go on about your application."); Sleep(-1); } void WatchForAutosysSignal(char *SignalName) {

AutoSys Commands 2–109

sendevent

HANDLE ThisThread; DWORD tid; char *SignalCopy; /* Use this to pass in the signal name without referencing any */ /* global values */ SignalCopy=_strdup(SignalName); ThisThread=CreateThread(NULL,0,WatchAutosysSignalThread, (LPVOID)SignalCopy,0,&tid); if (ThisThread==NULL) { free(SignalCopy); printf("Failed to CreateThread for WatchAutosysSignalThread\ error %ld.\n",GetLastError()); return; } printf("Created thread for WatchAutosysSignalThread.\n"); if (!CloseHandle(ThisThread)) /*Drop the handle*/ printf("Failed to Close the thread handle error\ %ld.\n",GetLastError()); return; } DWORD WINAPI WatchAutosysSignalThread(LPVOID Parm) { HANDLE ThisSem; DWORD dwrc; char *SignalName; SignalName=(char *)Parm; printf("Beginning to wait for %s.\n",SignalName); /* Autosys will Open the event semaphore and then call*/ /* PulseEvent to signal the semaphore and reset it to */ /* unsignaled. This way you can watch for the signal */ /* multiple times. If more than one application is waiting */ /* for the signal, make sure to create it with the */ /* ManualReset value set to TRUE. */ ThisSem=CreateEvent(NULL,TRUE,FALSE,SignalName); if (ThisSem==NULL) { printf("Failed to create semaphore %s with error\ %ld.\n",SignalName,GetLastError()); return(0); } dwrc=WaitForSingleObject(ThisSem,INFINITE); if (dwrc!=WAIT_OBJECT_0) { printf("WaitForSingleObject for %s failed with %ld and\ %ld.\n",SignalName,dwrc,GetLastError()); CloseHandle(ThisSem); return(0); } printf("Received signal on %s.\n",SignalName);

printf("You may react to the signal in any way you choose.\n"); CloseHandle(ThisSem);

exit(0); /* In this case just kill the application */ }

12. To cancel all unprocessed JOB_OFF_HOLD events for a job named “RunData,” enter:

sendevent -E JOB_OFF_HOLD -J RunData –u

2–110 Reference Guide

sendevent (SP)

sendevent (SP)

AutoSys Stored Procedure

Function

Issues a sendevent command directly to the data server.

Syntax

sendevent ’event’, ’job_name’, ’status’, ’alarm’, ’time_of_event’, ’comment’

Description

The sendevent (SP) is a call made directly to the data server to execute a sendevent command. To execute the procedure, you must be logged on to the data server, and you must enter the command statement using the syntax required by the target database. All options (fields) must be entered, even if they contain no information.

This stored procedure only can be sent to the data server you are currently logged on to. If you are running Dual-Event Servers, the event processor will copy the event to the second Event Server before it is processed. If you are using non-UNIX applications that can access the data server, they can also issue this stored procedure.

Note: Since this procedure is done directly from the database, other database actions can call this interface. For example, updates to tables can be configured to generate the sendevent (SP) through “triggers” to initiate a job.

Important! Using sendevent (SP) bypasses the AutoSys security feature for Execute permissions on jobs.

AutoSys Commands 2–111

sendevent (SP)

Options

event Specifies the event to be sent; for example: STARTJOB

job_name Specifies the name of the job to which the specified event should be sent. If the event is SET_GLOBAL, specify global_name=value instead of job_name.

status Use this option only when the specified event is CHANGE_STATUS; in this case, this option is required. status specifies the status to which the job specified in job_name should be changed.

alarm Use this option only when the specified event is ALARM; in this case, this option is required. alarm specifies the name of the alarm to be sent.

time_of_event Specifies the date and time when the event should be posted. The format is the same date and time format that is currently being used for the Event Server to which the command is issued. If a null is input, the current date and time is used.

comment Specifies a textual comment (up to 255 characters) to be attached to this event.

2–112 Reference Guide

sendevent (SP)

Examples

1. To immediately start a job named “test_job” on a Sybase data server that you are currently logged onto, enter:

1> sendevent ’STARTJOB’,’test_job’,’’,’’,’’,’’ 2> go

Note: You can also use the sendevent stored procedure with a Microsoft SQL Server database, using the ISQL/w graphical query interface.

2. If you are currently logged onto an Oracle data server and want to change the status of a job named “test_job” to INACTIVE on December 25, 1997, with a textual comment, enter:

SQL> declare 2 rc int; 3 begin 4 rc := sendevent (’CHANGE_STATUS’,’test_job’, ’INACTIVE’,’’, ’12:00:00 12/25/1997’, ’Reset for today’); 5 end; 6 /

3. To set a global variable named “Today” on a Sybase data server that you are currently logged onto, enter:

1> sendevent ’SET_GLOBAL’,’Today=12/12/1997’,’’, 2> ’’,’’,’’ 3> go

AutoSys Commands 2–113

xql

xql

Function

Provides direct access to the Sybase data server, allowing the user to query the database itself.

Syntax

xql -U user_name -P password [-S server] [-D database] [-c "command_string" | -f input_file] [-d delimiter] [-l] [-T timeout_interval]

Description

Xql is the AutoSys-supplied utility that accesses the Sybase data server from any properly configured client. It can be used as an interactive interface to the data server (like isql), as a command issued in an AutoSys Instance Command Prompt window, or in a batch file (batch mode) to send requests to the server and output results.

Xql also serves as a useful tool for determining whether or not the AutoSys database is accessible at all, given the current configuration and state of the environment variables. Often, when AutoSys problems arise, these variables are not set correctly, or the AutoSys or Sybase configuration files are not set up properly. xql can be used to detect that situation; as a result, xql should not be overlooked as a troubleshooting tool.

Xql is the AutoSys-supplied utility that accesses the Sybase data server from any properly configured client. It can be used as an interactive interface to the data server (like isql), as a command issued at the UNIX command line, or in a shell script (batch mode) to send requests to the server and output results.

Xql also serves as a useful tool for determining whether or not the AutoSys database is accessible at all, given the current configuration and state of the environment variables. Often, when AutoSys problems arise, these variables are not set correctly, or the AutoSys or Sybase configuration files are not set up properly. xql can be used to detect that situation; as a result, xql should not be overlooked as a troubleshooting tool.

2–114 Reference Guide

xql

Batch Mode

To execute xql in batch mode and have the results sent to standard output, you specify either the -c option, the -f option, or redirect standard input into xql. The -c option will read its SQL input from the command_string argument and the -f option will read its SQL input from the file specified in input_file. Batch mode is particularly useful for embedding SQL statements inside of batch files. (An example is given following.) When using the -c option, you must enter “go” to mark the end of the SQL statement.

To execute xql in batch mode and have the results sent to standard output, you specify either the -c option, the -f option, or redirect standard input into xql. The -c option will read its SQL input from the command_string argument and the -f option will read its SQL input from the file specified in input_file. Batch mode is particularly useful for embedding SQL statements inside of shell scripts. (An example script is given following.) When using the -c option, you must enter “go” to mark the end of the SQL statement.

Interactive Mode

To execute xql interactively, you omit the -c and -f options; as a result, the standard output will not be redirected into xql. The xql prompt looks like the following:

xql>>[AutoSysDB][autosys] 1>

The second token in the prompt (AUTOSYSDB in this example) displays the name of the data server to which you are connected. The third token is the name of the database that you are currently in. At this prompt, xql is waiting for input, in the form of Transact SQL—Sybase’s extended SQL language. The SQL can extend across multiple lines. To execute the SQL, you enter a semi-colon (;) at the end of the SQL statements, or enter “go” on a new line.

Help is available in interactive mode by typing “help” at the xql command prompt.

There is a history feature, which allows you to reuse past commands stored in the buffer. Also, an editing feature, which uses emacs or vi, is available to edit the buffer before sending it to the Server. To exit xql, you enter exit at the prompt and press Enter or Ctrl+D.

AutoSys Commands 2–115

xql

Notes:

XQL is provided only for use with the Sybase database. If you are using Oracle, you can use Oracle’s SQL*Plus command language interface. If you are using a Microsoft SQL Server, you can use the ISQL/w graphical query interface.

XQL is provided only for use with the Sybase database. If you are using Oracle, you can use Oracle’s sqlplus.

Options

-U user_name Specifies the name of the Sybase user to log in as, and can be any valid Sybase user. This is typically “autosys” for the AutoSys user, or “sa” for the system administrator.

-P password Specifies the Sybase password for the specified user_name. By default, the “autosys” user’s password is “autosys” and, for bundled Sybase, the “sa” password is “sysadmin.” You can change both of these passwords, and you should for security reasons. The password must not be null.

-S server

Specifies the name of the Sybase data server to be accessed. The default value is taken from the environment variable %DSQUERY%. If no server is specified, and %DSQUERY% is not defined, xql will terminate. For the database bundled with AutoSys, this value is normally AUTOSYSDB.

Specifies the name of the Sybase data server to be accessed. The default value is taken from the environment variable $DSQUERY. If no server is specified, and $DSQUERY is not defined, xql will terminate. For the database bundled with AutoSys, this value is normally AUTOSYSDB.

2–116 Reference Guide

xql

-D database

Specifies the specific Sybase database to be accessed. For the database bundled with AutoSys, this value is normally “autosys.” If no database is specified, it is taken from the environment variable %DSDB%, if defined. If this variable is not defined, the default database for the identified user is taken from the user table in the master database. For the user “sa,” this is typically “master”; for “autosys,” it is normally “autosys”.

Specifies the specific Sybase database to be accessed. For the database bundled with AutoSys, this value is normally “autosys.” If no database is specified, it is taken from the environment variable $DSDB, if defined. If this variable is not defined, the default database for the identified user is taken from the user table in the master database. For the user “sa”, this is typically “master”; for “autosys,” it is normally “autosys.”

-c "command_string" Specifies an SQL statement to be passed to Sybase and executed in “batch,” rather than interactive mode. The SQL statement must be wrapped in double quotes. Multiple lines of input, as well as multiple Sybase commands, can be entered in a single call. xql will send this command to the data server, then send the results to standard output. This option is particularly useful for embedding SQL commands in batch files.

In this non-interactive mode, column names, for example; field names are not output unless the -l option is also specified.

-f input_file Specifies a text file containing SQL statements to be passed to Sybase, to be executed in batch, rather than interactive mode. xql will send this file of commands to the data server, then send the results to standard output. In this non-interactive mode, column names, for example; field names are not output unless the -l option is also specified.

AutoSys Commands 2–117

xql

-d delimiter

Specifies the delimiter to be used for output, which is written to standard output. The default delimiter is the pipe symbol (|), which is placed between all output fields. This option is useful for creating a flat file of data that uses delimiters for processing at a later time. The delimiter is not restricted to a single character, and can even be a string of characters with special characters. Be sure not to use a character that your shell could mistakenly interpret, especially the asterisk symbol (*).

-l Specifies that a long listing is desired, meaning that the output should be displayed as one column name, for example; field name with its corresponding value per line. The default in non-interactive mode (using the -c or -f options) is to output the selected “records” one per line, with multiple fields of a single record appearing on the same line. No field names are output in the non-interactive “short” mode. This option has no effect in interactive mode.

-T timeout_interval Specifies a period of time after which xql will terminate the session if no activity has occurred. The interval is specified in minutes; any number may be specified. To specify that xql should never terminate the session, enter “0.” The default is 15 minutes.

Specifies the delimiter to be used for output, which is written to standard output. The default delimiter is the pipe symbol (|), which is placed between all output fields. This option is useful for creating a flat file of data that uses delimiters for processing at a later time. The delimiter is not restricted to a single character, and can even be a string of characters with special characters. Be sure not to use a character that your batch file could mistakenly interpret, especially the asterisk symbol (*).

2–118 Reference Guide

xql

Examples

The following examples assume that the Sybase account and password are “autosys” and “autosys” respectively. The examples also assume that the data server defaults to AUTOSYSDB, and the database defaults to “autosys.”

1. To select the job ID and job name (the field names are assigned by AutoSys) from the job table in the default data server and database, enter this (using the “autosys” user and the “autosys”, or the appropriate, password):

xql -Uautosys -Pautosys

Then, at the xql prompt, enter:

xql>>[AUTOSYSDB][autosys] 1> select joid, xql>>[AUTOSYSDB][autosys] 2> job_name xql>>[AUTOSYSDB][autosys] 3> from job;

Assuming that there are only three jobs, this will be the output:

joid job_name -------- -----------------------------

To exit the interactive session, enter:

101|tester

3. To use the percent sign (%) as the delimiter and specify a filename named “test.sql” containing the same select statement as shown previously, enter:

101%tester

101 tester 106 test1 107 domail.tibet

xql>>[AUTOSYSDB][autosys] 1> exit

2. To obtain the same information as above by way of the “batch” mode and entering the SQL statement at the command line, enter:

xql -Uautosys -Pautosys -c "select joid, job_name from job go"

Note the “go” at the end of the command line—a semi-colon will not be accepted.

The output, with the default delimiter, would appear as follows:

106|test1 107|domail.tibet

xql -Uautosys -Pautosys -f test.sql -d %

The output would appear as follows:

106%test1 107%domail.tibet

AutoSys Commands 2–119

xql

4. To request the “long listing” of the same query, enter:

xql -Uautosys -Pautosys -l -f test.sql

The output would appear as follows:

joid 101

job_name test1

5. To interactively query a data server called “PRODSERV” and a database called “production,” and to specify no timeout, enter:

job_name tester joid 106

joid 107 job_name domail.tibet

xql -Uautosys -Pautosys -S PRODSERV -D production -T 0

6. To multiple SQL statements can be entered at the command line as follows (do not forget the closing quote and that each escape character (\) must be immediately followed by the newline character):

xql -Uautosys -Pautosys -c "select count(*) \ from job go \ select joid, job_name \ from job go"

7. By invoking xql with the -c or -f option, or by redirecting input into it, xql will execute the command or file of commands, and write its results to standard output, then exit. This use is most common in batch files where data from the database is needed. Suppose that you want to store the number of jobs defined in the “autosys” database in a batch file. To accomplish this, enter the following in the batch file:

@REM Get the number of jobs in AutoSysDb @REM

@REM @xql -Uautosys -Pautosys -S%DSQUERY% -DAutoSysDb -c"select count (*) from job"

7. By invoking xql with the -c or -f option, or by redirecting input into it, xql will execute the command or file of commands, and write its results to standard output, then exit. This use is most common in shell scripts where data from the database is needed. Suppose that you want to store the number of jobs defined in the “autosys” database in a Bourne shell script. To accomplish this, enter the following in the script:

# Get the number of Jobs in AutoSys

#!/bin/sh # # Example program

num_jobs=`xql -Uautosys -Pautosys -c "select count(*) from job”`

2–120 Reference Guide

xql

if [ $numjobs -gt 100 ]

fi

then echo "Lots of Jobs in AutoSys"

The following screen will be display:

* !1: Sends query 1 from hist. to SYBASE xql cmd buffer. *

* vi : Invokes Vi editor, with current or last query. *

* clear : Clears the screen. *

*******************************************************************

8. To obtain help in interactive mode, type “help” at the xql prompt as shown following:

xql>>[AUTOSYSDB][autosys] 1> help

******************** xql interactive mode help********************* * ! : Displays the history of xql queries. *

* !5 11: Sends queries 5-11 from hist. to SYBASE xql cmd buffer. * * !? : Shows what is in the SQL command buffer. * * go or ;: Signals the SYBASE to execute the last query again.* * emacs : Invokes emacs editor, with current or last query. *

* lpron : Results of queries will be sent to printer. * * lproff : Stops sending the Results to printer. *

* exit/quit: Exits the xql program. * * help : Displays help for xql Usage in Interactive mode. *

AutoSys Commands 2–121

Chapter

3 JIL/GUI Definitions

JIL Sub-commands

JIL sub-commands are used to establish if you are creating, updating, or deleting a job. When using the AutoSys GUI, the same instructions are conveyed by entering values in various fields, or by pressing different buttons in the GUI’s dialog boxes.

JIL sub-commands are used to establish if you are creating, updating, or deleting a job. When using the AutoSys Job Editor, the same instructions are conveyed by opening the window, and by entering values or selecting buttons in the various fields on the various tabs.

JIL/GUI Definitions 3–2

Job Attributes

Job Attributes

AutoSys job attributes are used to specify everything from the name of a new job to the specific exit conditions, which must be “successful” in order for the job to be considered completed. Job attributes can be defined using JIL statements, which are input to the jil command, or they can be defined using the AutoSys Graphical User Interface (GUI), Job Editor. Regardless of method, the attributes are virtually the same.

AutoSys job attributes are used to specify everything from the name of a new job to the specific exit conditions, which must be “successful” in order for the job to be considered completed. Job attributes can be defined using JIL statements, which are input to the jil command, or they can be defined using the AutoSys Graphical User Interface (GUI). Regardless of method, the attributes are virtually the same.

Note: When issuing commands that will execute on a different operating system, (for example: Windows to UNIX or UNIX to Windows,) you must use the syntax appropriate to the operating system of the client machine.

JIL/GUI Definitions 3–3

alarm_if_fail

alarm_if_fail

JIL Attribute

GUI Path

Job Definition, Adv Features Send, ALARM if this Job Fails?

Job Editor, Alarms/Terminators tab, Send Alarm if this job fails.

JIL Syntax

alarm_if_fail: toggle

Description

Indicates whether an alarm should be posted to the Event processor if the job fails or is terminated. The alarm is informational only. A defined monitor, the Alarm Sentry, or the Alarm Manager needs to be running to view the alarm as it occurs, and an operator must take the appropriate steps to address the situation.

Where Applicable

Command job definition

File watcher job definition

Box job definition

3–4 Reference Guide

alarm_if_fail

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the Yes or No radio button; to change your selection, click the other button.

GUI: Select the check box for Yes, and deselect it for No.

The default value is 1, for yes.

Example

Set the job currently being created or updated to post an alarm if it fails or is terminated, enter:

alarm_if_fail: y

JIL/GUI Definitions 3–5

auto_delete

auto_delete

JIL Attribute

GUI Path

Job Editor, Misc tab, Delete Job after completion n Hours

Job Definition, Adv Features, Delete Job after Completion?

JIL Syntax

auto_delete: value

Where Applicable

Description

Indicates whether the job should be automatically deleted after completion. This attribute is useful for using AutoSys to schedule and run a one-time batch job. The number of Hours after the job’s completion, at which time the job should be deleted, can be specified (including “0” for immediately). If it is a box job, the box and all the jobs in the box will be deleted.

If auto_delete is set to 0, AutoSys will immediately delete job definitions only if the job completes successfully. If the job does not complete successfully, AutoSys will keep the job definition for seven days before automatically deleting it.

Command job definition

File watcher job definition

Box job definition

3–6 Reference Guide

auto_delete

Values

JIL: value can be any number of hours; 0 indicates immediate deletion, while -1 indicates that the job should not be deleted.

GUI: Select the check box, and enter the number of Hours, which can be any number of hours; 0 indicates immediate deletion. The keyword auto_delete is omitted.

GUI: Enter the value, which can be any number of hours; 0 indicates immediate deletion. The keyword auto_delete is omitted.

The default is to not delete the job automatically.

Example

Set the job to be automatically deleted 5 hours after completion, enter:

auto_delete: 5

JIL/GUI Definitions 3–7

auto_hold

auto_hold

Job Attribute

GUI Path

Job Editor, Misc tab, AutoHold on for jobs in boxes.

Job Definition, Adv Features, AutoHold On?

JIL Syntax

auto_hold: toggle

Description

This feature is only for jobs that are in a box. When a job is in a box, it inherits the starting conditions of the box. 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).

By specifying “yes” to AutoHold On, AutoSys automatically changes the job state to ON_HOLD when the box it is in begins RUNNING. To start the job, take the job off hold by sending the JOB_OFF_HOLD event. This is done with the AutoSys sendevent command.

Where Applicable

Command job definition, if the job is in a box

File watcher job definition, if the job is in a box

Box job definition, if the job is in a box

3–8 Reference Guide

auto_hold

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate Yes, and deselect it to indicate No.

GUI: Select the Yes or No radio button; to change your selection, click the other button.

To set the job to be automatically placed on hold, enter:

The default value is 0 for no.

Example

auto_hold: y

JIL/GUI Definitions 3–9

avg_runtime (JIL only)

avg_runtime (JIL only)

Job Attribute

JIL Syntax

avg_runtime: value

Description

Indicates an average runtime (in minutes) for a job that is newly submitted to the AutoSys database; it establishes this value in the absence of the job having been run multiple times. This attribute is used solely to establish an average runtime for the new job in the avg_job_runs table.

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

Note: When the DBMaint script executes, it recalculates the average runtime for each job in the database. If a new job has been submitted with the avg_runtime attribute and has not been run yet, its average runtime will be changed to 0.

Where Applicable

Command job definition

File watcher job definition

Box job definition

Values

JIL: value can be any number of minutes, to include decimal numbers.

3–10 Reference Guide

avg_runtime (JIL only)

Example

To set the average runtime for a new job to be five minutes, enter:

avg_runtime: 5

JIL/GUI Definitions 3–11

box_failure

box_failure

Job Attribute

GUI Path

Job Editor: for box job, Failure Conditions

Job Definition: Box Completion Conditions, FAILURE Condition

JIL Syntax

box_failure: conditions

Description

Specifies the conditions to be interpreted as a box failure. The Box Completion Conditions appears in the Job Definition dialog only when you select a box job, and when you are opening an existing box job definition. The default condition for a box to be considered as having failed is that any job in the box completed with a failure condition. A box can contain complex branching logic, which can take a number of different paths, one of which can include recovery from a failed job. In this case, you might not want the box to be considered a failure, even though a job inside of it failed.

Specifies the conditions to be interpreted as a box failure. The Success and Failure Conditions appear in the Job Editor only when you select a box job when opening a new definition, and when you are opening an existing box job definition. The default condition for a box to be considered as having failed is that any job in the box completed with a failure condition. A box can contain complex branching logic, which can take a number of different paths, one of which can include recovery from a failed job. In this case, you might not want the box to be considered a failure, even though a job inside of it failed.

Where Applicable

Box job definition

3–12 Reference Guide

box_failure

Values

JIL: conditions can specify any of the dependencies described in the “Starting Parameters” section of the Unicenter AutoSys Job Management for Windows User Guide and the Unicenter AutoSys Job Management for UNIX User Guide.

GUI: Enter the conditions, which can be any of the dependencies described in the “Starting Parameters” section of the Unicenter AutoSys Job Management for Windows User Guide and the Unicenter AutoSys Job Management for UNIX User Guide. The keyword box_failure is omitted.

The conditions can be up to 255 characters.

The default Failure Condition is that all the jobs in the box have run and at least one failed.

Examples

1. Set the status of the box currently being created or updated to FAILURE if “JobA” fails or “JobB” fails, but ignoring if “JobC” fails, enter:

box_failure: failure(JobA) AND failure(JobB) AND failure(JobC)

box_failure: failure(JobA) OR failure(JobB)

2. Set the status of the box currently being created or updated to FAILURE only if all three jobs fail, enter:

Note: In JIL, multiple lines of input up to 255 characters can be specified without any continuation characters.

JIL/GUI Definitions 3–13

box_name

box_name

Job Attribute

GUI Path

Job Editor _ Box

Job Definition, Name of the Box this Job is IN

JIL Syntax

box_name: name

Indicates the name of the box in which this job is to be placed. Boxes allow for 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 specify their starting conditions relative to each other individually, if necessary. The specified box must already exist.

File watcher job definition

Description

Where Applicable

Command job definition

Box job definition

3–14 Reference Guide

box_name

Values

JIL: name can be any string of up to 30 alphanumeric characters, plus the underscore character ( _ ).

GUI: Enter or Search for the Box name, which can be any string of up to 30 alphanumeric characters, plus the underscore character ( _ ). The box_name keyword is omitted. The entered name, the box job, must already exist.

GUI: Enter the name, which can be any string of up to 30 alphanumeric characters, plus the underscore character ( _ ). The box_name keyword is omitted. The entered name, the box job, must already exist.

There is no default box name.

box_name: Box1

Example

To specify the job currently being created or updated should be put in the box named “Box1”, enter:

JIL/GUI Definitions 3–15

box_success

box_success

Job Attribute

GUI Path

Job Definition: Box Completion Conditions, SUCCESS Condition

Job Editor: Box Completion Conditions, Success Condition

JIL Syntax

box_success: conditions

Description

Specifies the conditions to be interpreted as a box success. The Success and Failure Conditions appear in the Job Editor only when you select a box job type when opening a new definition, or when you are opening an existing box job definition.

Specifies the conditions to be interpreted as a box success. The Box Completion Conditions appears in the Job Definition dialog only when you select a box job type, or when you are opening an existing box job definition.

The default condition for a box to be considered successful is that every job in the box completed with a success condition. A box can contain complex branching logic, which can take a number of different paths, all of which constitute success. In this case, some jobs in the box may never need to be run, but if the default box behavior is applied, the jobs that had not run would keep 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.

For more information, see the section “Starting Parameters,” in the chapter “AutoSys Jobs,” in the Unicenter AutoSys Job Management for Windows User Guide, or the section “Starting Parameters,” in the chapter “AutoSys Jobs,” in the Unicenter AutoSys Job Management for UNIX User Guide.

3–16 Reference Guide

box_success

Where Applicable

Box job definition

GUI: Enter the Success Conditions, which can be any of the dependencies described in the “Starting Parameters” section in the Unicenter AutoSys Job Management for Windows User Guide and the Unicenter AutoSys Job Management for UNIX User Guide. The keyword box_success is omitted.

Note: In JIL, multiple lines of input + up to 255 characters can be specified without any continuation characters.

Values

JIL: conditions can specify any of the dependencies described in the “Starting Parameters” section in the Unicenter AutoSys Job Management for Windows User Guide and the Unicenter AutoSys Job Management for UNIX User Guide.

The condition can be up to 255 characters.

The default success condition is that all the jobs in the box ran and all completed successfully.

Examples

1. Set the status of the box currently being created or updated to SUCCESS only when “JobA” succeeds or “JobB” succeeds, but ignoring the status of “JobC,” enter:

box_success: success(JobA) OR success(JobB)

2. Set the status of the box currently being created or updated to SUCCESS only if all three jobs succeed, and they are the only jobs in the box, enter nothing. This is the default behavior of box jobs.

3. Set the status of the box currently being created or updated to SUCCESS only if jobs “JobA” and “JobB” succeed, and “JobC” completes, regardless of its status, enter:

box_success: success(JobA) AND success(JobB) AND done(JobC)

JIL/GUI Definitions 3–17

box_terminator

box_terminator

Job Attribute

GUI Path

Job Editor, Alarms/Terminators tab, If this job fails, terminate the box it is in

Job Definition, Adv Features, If this Job Fails should the Box be Terminated?

JIL Syntax

box_terminator: toggle

Description

This attribute specifies whether the box containing this job should be terminated if the job fails or terminates. By using this attribute in combination with the If the box fails, terminate this box setting, you can control how nested jobs react when a job fails. This attribute can only be specified if the job being defined is being placed in a box.

Where Applicable

Command job definition, if the job is in a box

File watcher job definition, if the job is in a box

Box job definition, if the job is in a box

3–18 Reference Guide

box_terminator

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate Yes, or deselect it to indicate No.

GUI: Click the Yes or No radio button; to change your selection, click the other button.

The default setting is 0 for no.

Example

Specify that if the job currently being created or updated fails, the box it is in should be terminated, enter:

box_terminator: y

JIL/GUI Definitions 3–19

chk_files

chk_files

Job Attribute

GUI Path

Job Editor, Resource/Profile tab, Resource Check - File System Space...

Job Definition, Adv Features, Resource Check - File System Space...

JIL Syntax

chk_files: drive size [drive size]...

chk_files: file_system_name size [file_system_name size]...

Description

This resource check specifies the minimum amount of file space that must be available on designated drives for the job to be started. One or more drives, specified with the corresponding drive letter, and their corresponding sizes, can be specified. Only drives are checked; directories, if specified, are ignored. If multiple drivers 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 the required space is available before starting the job.

If the requirements are not met, an alarm is generated. If the job is a command job, the job will not be started; after a logarithmic-back off type delay, another attempt will be made to check the file system space and start the job. If the job is a file watcher job, it will be started regardless of the lack of available space.

In the case of a file watcher definition, the drive should identify the drive on which the file is expected to arrive, as specified in the “File to Watch” attribute, and the minimum file size should be the same as the “Minimum File Size” attribute.

3–20 Reference Guide

chk_files

This resource check specifies the minimum amount of file space that must be available on designated file systems for the job to be started. One or more file systems, specified with full path names or directory names, and their corresponding sizes, can be specified. If multiple file systems are specified, separate them with a single space. When the Remote Agent is preparing to start the job on the client machine, it checks whether the required space is available before starting the job.

If the requirements are not met, an alarm is generated. If the job is a command job, the job will not be started; after a logarithmic-backoff type delay, another attempt will be made to check the file system space and start the job. If the job is a file watcher job, it will be started regardless of the lack of available space.

In the case of a file watcher definition, the file_system_name should identify the location where the file is expected to arrive, as specified in the “File to Watch” attribute, and the minimum file size should be the same as the “Minimum File Size” attribute.

Where Applicable

Command job definition

File watcher job definition

JIL/GUI Definitions 3–21

chk_files

Values

drive The drive on which the file space will be needed, and environment variables defined in the job’s profile can be used in the path name.

size

Many drive size pairs can be specified, separated by a space.

The default is to not check the file space available.

Is the file space needed (in KB).

The value can be up to 255 characters.

JIL: Enter one or more pairs of drive size.

GUI: Enter one or more file size pairs. The keyword chk_files is omitted.

file_system_

name

The full path name of the file system where the file space will be needed, and environment variables exported in the profile can be used in the path name.

size

Many file_system_name size pairs can be specified, separated by a space.

GUI: Enter one or more file_system_name size pairs. The keyword chk_files is omitted.

Is the file space needed (in KB).

The value can be up to 255 characters.

JIL: Enter one or more pairs of file_system_name size.

The default is to not check the file space available.

3–22 Reference Guide

chk_files

Example

To specify that the job currently being created or updated should have 100 KB of space available on the C: drive and 120 KB of space available on the D: drive, enter:

chk_files: "C: 100 D: 120"

To specify that the job currently being created or updated should have 100 KB of space available on the file system named “rootfs” and 120 KB of space available on the file system named “auxfs1”, enter (using the full path name):

chk_files: /rootfs 100 /auxfs1 120

JIL/GUI Definitions 3–23

command

command

Job Attribute

GUI Path

Job Editor, Basic tab, Command

Job Definition, Command To Execute

JIL Syntax

command: command_name command_runtime_args

Description

The command attribute can be the name of any command, executable, UNIX script, or batch file, and its arguments. Input and output redirection is provided by other job attributes and cannot be part of a command. AutoSys global variables can be used as part of the command name itself, or as part of the command’s runtime arguments. (Use the sendevent command, or the Send Event Tool, to set a global variable.)

Note: When issuing commands that will execute on a different operating system, for example: Windows to UNIX, you must use the syntax appropriate to the operating system of the client machine.

If the command resides on a file system that supports Windows security mechanisms (for example: NTFS), then the job’s owner must have read and execute permission on that command. (By extension, all resources and files referenced by the command’s execution must also be accessible to the job’s owner.)

Environment variables for the command to be executed are defined by a profile, either the default profile or the profile specified in the job definition.

3–24 Reference Guide

command

If you want to use an AutoSys command in the Command field or for the command attribute, you must use the following syntax (when you use this syntax, the AutoSys-specific variables are set correctly):

Instance

"command_line"

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

■ Although system environment variables will be automatically set into the command’s environment, user environment variables will not be. All other required environment variables must be defined in the job’s profile, either the default one or a user-defined one specified by the job’s profile attribute (which you can also set in the Job Editor, using the Job Environment Profile field on the Resource/Profile tab).

When specifying drive letters in commands, the colon (:) must be escaped. That is, "C:\tmp" and C\:\tmp are valid; and C:\tmp is not.

initautosys -i Instance -r "command_line"

where:

Specifies the instance name.

Specifies the full command line. This command line must be in quotes.

■ By default, Windows jobs are started in the foreground to allow Windows applications to interact with the desktop. To launch a job in the background, enter an ampersand (&) as the first character in the job command attribute.

■ Redirection of standard input, output, and error files is not allowed. Job attributes, such as std_in_file for standard input, can be used to provide the necessary functionality.

■ Command-line arguments can be passed using global variables.

Note: If a command works properly when issued at an MS-DOS Command Prompt, but it fails to run or run properly when specified as a command attribute, the necessary user-defined environment variables and the variables defined in the job profile are probably different. If this is the case, make sure that all required user environment variables are defined in the job profile, either the default one or a user-defined one specified by the job’s profile attribute. You can do this using the Profiles Manager, which is in the AutoSys program group.

JIL/GUI Definitions 3–25

command

The command attribute can be the name of a command, shell script, or application program that is to be run on the client machine (when all necessary conditions are met). 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. In addition, the job’s owner must have execute permission for this command on the client machine. AutoSys global variables can be used as part of the command name itself, or as part of the command’s runtime arguments. (To set a global variable, use the sendevent command or the Send Event dialog in the GUI.)

The full path name can be specified, in which case, variables exported from the profile script can be used in the path name specification. If variable substitution is used, enclose the variable in curly braces, like the following:

■ Since AutoSys performs an “exec” to run the command, you cannot separate multiple commands with semi-colons.

This command will be executed in the environment defined in the profile script—either the AutoSys default /etc/auto.profile, or the one specified in the job definition (which overrides the default profile).

Therefore, if $PATH is assigned in that script, that path will be searched to find the executable.

${PATH}

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

■ Piping or redirection of standard input, output, and error files are not allowed. 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 ampersand (&) in the command attribute. You can call a shell script to provide that functionality.

3–26 Reference Guide

command

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

Variable=value; export Variable

■ Only one file is sourced—either the default /etc/auto.profile or the profile file specified in the job definition. Therefore, the entire environment needed for the command must be defined in the profile file that will be sourced.

#!/bin/csh -f

■ All commands are run under the Bourne shell (/bin/sh). Therefore, all statements in the profile must use /bin/sh syntax, like:

WARNING! Do not use this syntax: export Variable=value or setenv Variable Value

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

Where Applicable

Command job definition

JIL/GUI Definitions 3–27

command

Values

command_ name

The Windows command can be the name of any command, batch file, or an application program that is to be run on the client machine when all the necessary conditions are met.

the command_name can be the name of any command, shell script, or application program executable.

command_runtime_args

Any runtime arguments.

$$global_name

Examples

The command name and any runtime arguments can be up to 255 characters long. Global variables can be referenced anywhere in the command_name or in its command_runtime_args. Global variables are referenced using one of the following expressions:

or:

$${global_name}.

JIL: Enter the command_name and any command_runtime_args.

GUI: Enter the command_name and any command_runtime_args. The keyword command is omitted.

There is no default command_name. The command, batch file, or executable does not need to exist at job definition time. It must however exist at runtime.

1. Specify that the NTGETDATE command is to be executed, enter:

command: NTGETDATE

NTGETDATE is supplied in %AUTOSYS%\bin.

2. Specify that SLEEP is to be launched in the background, enter:

command: &SLEEP 30

3–28 Reference Guide

command

3. Specify that a batch file named “Backup.bat” in the directory named C:\COMMON is to be executed, you would enter:

command: Backup

5. Remove all files from the \tmp subdirectory under the directory specified in the “MY_BACKUPS” global variable, you could enter:

command: "C:\COMMON\Backup"

Or, if C:\COMMON is included in the runtime environment, either through the system environment variables or a job profile, you would enter:

4. Specify that a batch file named “Backup.bat” in the directory named C:\COMMON is to be past today’s date (that has been set as the global variable named “RunDate”), you might enter:

command: "C:\COMMON\Backup" -D $$RunDate

command: del $$MY_BACKUPS\tmp\*.*

1. Specify that the UNIX date command is to be executed, enter:

command: /bin/date

command: /usr/common/Backup

4. Specify that the “Backup” script in the /usr/common directory is to be past today’s date (that has been set as the global variable named “RunDate”), you enter:

command: rm $${MY_BACKUPS}/tmp/*

2. If the /bin directory is included in the search path, either in the /etc/ auto.profile or in the user-defined profile, the UNIX date command can be specified to execute by entering:

command: date

3. Specify that the “Backup” script in the /usr/common directory is to be executed, enter:

or:

If the /usr/common directory is included in the runtime environment path of the job being defined, enter instead:

command: Backup

command: /usr/common/Backup -D $$RunDate

5. Remove all files from the /tmp subdirectory under the directory specified in the “MY_BACKUPS” global variable, you could enter:

JIL/GUI Definitions 3–29

condition

condition

Job Attribute

GUI Path

Job Editor, Basic tab, Dependencies

Job Definition, Starting Condition

JIL Syntax

condition: [(]condition[)][{AND | OR }[(] condition [)]]...

Description

When using the condition attribute, any number of job dependencies can be specified. All dependencies must evaluate to “true” before the dependent job will be run. Starting conditions can be one or more of the following types of dependencies:

■ Status of a job (For example: success(DB_BACKUP))

■ Job status across-instances (For example: success(jobB^PRD))

■ Exit code of a job (For example: exitcode (my_job)=4)

■ Global variables (For example: VALUE(TODAY)=Friday)

Jobs can conditionally start based on the status of another job running on a different AutoSys instance.

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.

These conditions are described in the sections that follow.

3–30 Reference Guide

condition

Job Status Dependencies

Starting conditions can be as simple as specifying “JobB” to start based on the SUCCESS status of “JobA,” and “JobC” to start when “JobB” returns a SUCCESS status. In this way, a single-threaded, batch queue like logic can be implemented.

The syntax for defining job dependencies is the same regardless of whether the job is being defined using JIL or the Job Editor; the only difference is that the JIL statement will begin with the condition keyword, while the Job Editor Dependencies field will only contain the language for the dependency itself. The dependency specification can take one of three forms: one based on the current AutoSys status of other jobs, and one based on the exit codes of other jobs, and one based on AutoSys global variables.

The syntax for defining job dependencies is the same regardless of whether the job is being defined using JIL or the GUI; the only difference is that the JIL statement will begin with the condition keyword, while the GUI field will only contain the language for the dependency itself. The dependency specification can take one of three forms: one based on the current AutoSys status of other jobs, and one based on the UNIX exit codes of other jobs, and one based on AutoSys global variables.

JIL/GUI Definitions 3–31

condition

This is the syntax, based on AutoSys status:

status(job_name)

where:

status Is one of the following:

success—The job_name’s status is SUCCESS.

failure—The job_name’s status is FAILURE.

done—The job_name’s status is SUCCESS, FAILURE, or TERMINATED.

terminated—The job_name’s status is TERMINATED

notrunning—The job_name’s status is anything except RUNNING.

job_name Is the job on which the job you are defining is dependent.

Note: If you issue a KILLJOB event for a job which is not a *.exe (for example, *.bat, *.cmd, or *.com), KILLJOB will kill only the AutoSys initiated CMD.EXE process. The Job Status will be set according to the return code of the killed CMD.EXE process. This status can be any one of the following: SUCCESS, FAILURE, or TERMINATED.

Note: Either uppercase or lowercase characters can be used to specify conditions; however, mixed case is not allowed.

These statuses are internal AutoSys settings, so their actual values do not need to be known. The value of the SUCCESS status can be controlled by the user by way of the Maximum Exit Code for SUCCESS field, on the Command Info tab, which can be set for a specific job. If that attribute is specified, any job that exits with an exit code less than or equal to the specified “Maximum Exit Code for Success” (max_exit_success attribute) value will be treated as a success. FAILURE means the job exited with an exit code higher than this value. The default for normal job completion is “0.” All other status settings are internally defined only. TERMINATED means the job was actually killed.

You may abbreviate the status condition identifiers with the first letter: s, f, d, t, and n. These abbreviations can be upper or lowercase.

3–32 Reference Guide

condition

You can configure more complex conditions by combining a series of conditions with the OR or the AND logical operators. You may use the pipe symbol (|) instead of the word “OR,” and the ampersand symbol (&) instead of the word “AND.” Spaces between conditions and delimiters are optional. You can specify even more complex conditions by grouping the expressions in parentheses. The parentheses do not imply any sort of precedence; they are simply used for grouping.

As in the previous list, any job status can be used as part of the specification for starting conditions. With this latitude, you can program branching paths to be taken that will provide alternate actions for error conditions. The notrunning operator is used to keep jobs from running at the same time as other jobs; that is, running one is exclusive of the other.

Cross-Instance Job Dependencies

Specify a cross-instance job dependency, enter the job name followed by a caret (^) and the name of the other instance, as in the following example:

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

Note: In JIL, multiple lines of input up to 255 characters can be specified without any continuation characters.

JIL/GUI Definitions 3–33

condition

Exit Code Dependencies

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, you can specify that when this code occurs, you want the system to execute a batch file (“JobB”), which redials the line.

In addition to job status, you can base job dependencies on UNIX 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, you can specify that when this code occurs, you want the system to execute a shell script (“JobB”), which redials the line.

This is the syntax you would use to specify this type of job dependency:

exitcode (job_name) operator value

where:

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

operator Is one of the following exit code comparison operators:

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

value Is any numeric value.

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

3–34 Reference Guide

condition

Global Variable Dependencies

Job dependencies can also be based on global variables you set using the sendevent command or the Send Event dialog. When using global variables this way, the value of the variable must evaluate to TRUE for the job dependency to be satisfied. Global variables are referenced using the following expression:

condition: VALUE(global_name) operator value

where:

global_name Is the name of the global variable already set in the database.

operator Is one of the following (spaces around the operator are optional):

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

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

You can also abbreviate the dependency specification VALUE (of a global variable) with the letter v (uppercase or lowercase).

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

You can use any job status, exit code, or global variable as part of the specification for starting conditions. With this latitude, you can program branching paths to provide alternative actions for all types of error conditions.

For example, the conditions for jobs downstream from “JobA,” which has been put “on ice” (with JOB_ON_ICE), as shown in the following table.

If the condition is: It will evaluate this:

SUCCESS (JobA) TRUE

failure (JobA) FALSE

terminate (JobA) FALSE

done (JobA) TRUE

notrunning (JobA) TRUE

exitcode (JobA) FALSE

JIL/GUI Definitions 3–35

condition

Where Applicable

Command job definition

File watcher job definition

Box job definition

Values

JIL: conditions can specify any combination of the dependencies described previously.

GUI: Enter the Dependencies, which can specify any combination of the starting conditions described previously. The keyword condition is omitted.

GUI: Enter the conditions, which can specify any combination of the starting conditions described previously. The keyword condition is omitted.

The condition can be up to 255 characters. There is no default.

Examples

2. If “JobC” should be started only when both “JobA” and “JobB” complete successfully or when both “JobD” and “JobE” complete, regardless of whether they failed, succeeded, or terminated, specify the following dependency in the job definition for “JobC”:

1. This is the job dependency specification for a job, which is to run if the job named “DB_BACKUP” succeeds:

condition: success(DB_BACKUP)

condition: (success(JobA) AND success(JobB)) OR (done(JobD) AND done(JobE))

3. If “JobB” fails part of the way through processing, you might want to call a routine named “Backout” that will back out of the changes. To do this, specify the following job dependency in the job definition for “Backout”:

condition: failure(JobB)

3–36 Reference Guide

condition

4. One use of the notrunning operator could be to avoid a database dump (“DB_DUMP”) and a file backup (“BACKUP”) at the same time, which would cause the hard disk to be accessed very frequently. However, you may have a smaller job that can run as long as both of these resource-intensive jobs are not running. You would specify the smaller job’s dependency like this:

condition: notrunning(DB_DUMP) AND notrunning(BACKUP)

5. This is the job dependency specification for the re-dial job for which the prerequisite job exited with an exit code of 4:

condition: exitcode (JobA) = 4

6. The job dependency specification for a job, which is to run, only if the global variable named “OK_TO_RUN” is greater than 2 would be entered as follows:

condition: VALUE(OK_TO_RUN)>2

7. The job dependency specification for a job, which is to run only if the job named “BACKUP” completes with a SUCCESS and the global variable named “TODAY” has a value of Friday, would be entered as follows:

condition: success(BACKUP) AND VALUE(TODAY)=Friday

Note: In multiple conditions (that is, if “JobC” is dependent on SUCCESS of “JobA” and SUCCESS of “JobB”), “JobC” will run whenever both “JobA” and “JobB” have succeeded, no matter when the first SUCCESS event occurred. For example, if you want to run a daily processing cycle, and “JobA” finished yesterday but did not run today, and “JobB” succeeded today, this is not the desired behavior. The recommended method is to group these jobs in a box.

8. The job dependency specification for a job, which is to run, only if the job named “DB_BACKUP” residing on another AutoSys instance named “PRD” succeeds, would be entered as follows:

condition: success(DB_BACKUP^PRD)

JIL/GUI Definitions 3–37

date_conditions

date_conditions

Job Attribute

GUI Path

Job Editor, Date/Time tab, Date/Time Conditions

Job Definition, Is the Start Date/Time Dependent?

JIL Syntax

date_conditions: toggle

Description

This attribute specifies whether or not there are date or time conditions for starting this job. If it is set to “no,” the remainder of the date/time related attributes will be ignored. If set to “yes,” the date can be specified using the days_of_week attribute, or the specific dates can be specified by associating this job with a custom calendar, created using the Graphical Calendar facility or the autocal_asc command. Starting times can also be specified using the start_times attribute to request specific times per day, or using the start_mins attribute to request specific times per hour. (See each of these attribute’s reference pages for further details.)

Where Applicable

Command job definition

File watcher job definition

Box job definition

3–38 Reference Guide

date_conditions

Values

JIL: toggle can be a y or 1 for yes; or n or 0 for no.

GUI: Select the Date/Time check box for Yes, or deselect it for No.

GUI: Click the Yes or No radio button; to change your selection, click the other button.

The default value is 0 for no. If the default is used, all other date/time dependencies are set to off, or disabled.

Example

To specify that starting date and time conditions are to be in effect, enter:

date_conditions: y

JIL/GUI Definitions 3–39

days_of_week

days_of_week

Job Attribute

GUI Path

Job Editor, Date/Time tab, Run Days

Job Definition, Date/Time Options, Date

JIL Syntax

days_of_week: {day [,day]... | all}

Description

Indicates the days of the week when the job will be run. One or more days can be selected, or all days can be selected. This attribute and the run_calendar attribute are mutually exclusive. AutoSys will schedule the job to run on every day of the week specified by this attribute, at the times specified in the start_times or start_mins attribute, one of which must be specified if this attribute is used.

Where Applicable

Command job definition

File watcher job definition

Box job definition

3–40 Reference Guide

days_of_week

Values

JIL: day can be any of the following:

■ mo (Monday)

■ tu (Tuesday)

■ fr (Friday)

■ we (Wednesday)

■ th (Thursday)

■ sa (Saturday)

■ su (Sunday)

■ all can be specified for every day of the week.

Note: The day specifications must be in lowercase.

GUI: select the Run Days radio button, then select one or more of the Monday through Sunday toggle buttons by single-clicking them, or click the All button, to select all days. If days have been selected and you decide you want to use a calendar instead, click the Run Days radio button to deselect it.

GUI: select one or more of the Monday through Sunday toggle buttons by single-clicking on them, or select the Every Day toggle button. If days have been selected and you decide you want to use a calendar instead, deselect the days toggle buttons to avoid an error.

If start times are specified for a job and no dates or days have been specified using other GUI fields, the definition is invalid.

The default is that no days will be set.

Examples

1. Specify that the job should be run only on weekdays, enter:

days_of_week: mo, tu, we, th, fr

2. Specify that the job should be run every day of the week, enter:

days_of_week: all

JIL/GUI Definitions 3–41

delete_box

delete_box

JIL Sub-command

Function

Deletes a box, and all the jobs in it, from the AutoSys database.

GUI Path

Job Editor, File menu, Delete option

Job Definition, Job Name, Delete

Description

The delete_box sub-command deletes the specified box and all the jobs in that box. Jobs in the box, and the box itself that are already scheduled to run will still be deleted and will not be run.

Values

box_name Must be a box currently defined in the AutoSys database. There is no default.

Example

To delete a box named “Box1” and all jobs inside it, you would specify the following sub-command in the JIL script:

delete_box: Box1

3–42 Reference Guide

delete_job

delete_job

JIL Sub-command

Function

Deletes a job from the AutoSys database.

GUI Path

Job Editor, File menu, Delete option

Job Definition, Job Name, Delete

JIL Syntax

delete_job: job_name

Description

The delete_job sub-command deletes the specified job from the AutoSys database. Even if the job is already scheduled to run, it will not be run. delete_job 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 setting. If the specified job is a box, the box will be deleted. The jobs in the box will have their box reference removed and will become stand-alone jobs.

If a box name is specified in the GUI, a delete_box on the box and all the jobs inside of it will be performed. If a box name is specified with JIL using delete_job, only the box is deleted, the contained jobs are not deleted.

Values

job_name Must be a job or box currently defined in the AutoSys database. There is no default.

JIL/GUI Definitions 3–43

delete_job

Example

To delete a job called “Job1,” you would specify the following sub-command in the JIL script:

delete_job: Job1

3–44 Reference Guide

description

description

Job Attribute

GUI Path

Job Editor, Basic tab, Description

Job Definition, Description

JIL Syntax

description: text

Description

Specifies a description for the job; for documentation purposes only.

Where Applicable

Command job definition

File watcher job definition

Box job definition

Values

JIL: text can be any string of alphanumeric characters, up to 255 characters. Spaces can be included. You should enclose the string in double quotes to ensure JIL properly interprets it.

GUI: enter the text description, which can be any string of alphanumeric characters, up to 255 characters. Spaces can be included. The keyword description is omitted. You do not have to enclose the string in quotes; the GUI does this for you automatically when the job definition is saved.

There is no default.

JIL/GUI Definitions 3–45

description

Example

To specify that the job is an incremental daily backup of the database, enter:

description: "incremental daily backup of the database"

3–46 Reference Guide

exclude_calendar

exclude_calendar

Job Attribute

GUI Path

Job Editor, Date/Time tab, Exclude Calendar

Job Definition, Date/Time Options, Do NOT Run on Days in Calendar

JIL Syntax

exclude_calendar: calendar_name

Description

Indicates the name of the custom calendar to be used for determining the days of the week on which this job will not run. The calendar must have been previously created using Graphical Calendar facility (or autocal_asc).

If an exclude_calendar is specified as the only date_condition and the job has other implicit or explicit start conditions, the Event processor will inspect the calendar before starting the job. If the current date is on the calendar, the job will not be started and its status will be changed to INACTIVE. If the job’s status changes to INACTIVE and it’s in a box job, the box will complete if all other conditions are satisfied. Also, if the job is a box job itself and its status is changed to INACTIVE, all the jobs in the box will be changed to INACTIVE.

Where Applicable

Command job definition

File watcher job definition

Box job definition

JIL/GUI Definitions 3–47

exclude_calendar

Values

JIL: calendar_name must be the name of a custom calendar that has already been created.

GUI: Select the defined calendar from the Exclude Calendar pop-up list.

GUI: Enter the name of a custom calendar that has already been created. The keyword exclude_calendar is omitted.

The default is that no exclude calendar will be used.

Example

To specify that the job can be run on any day except those days specified in the “holiday” calendar, which you have previously defined, enter:

exclude_calendar: holiday

3–48 Reference Guide

heartbeat_interval

heartbeat_interval

Job Attribute

GUI Path

Job Editor, Command Info tab, Heartbeat interval (mins)

Job Definition, Adv Features, Heartbeat Interval (mins)

JIL Syntax

heartbeat_interval: mins

Description

Specifies the frequency (in minutes) at which this job’s command is expected to issue a heartbeat. Heartbeats are the way AutoSys monitors a job’s actual progress. It automates the common practice of outputting characters, such as displaying asterisks, which are echoed across the screen as a process runs in order to reflect its continued progress. The Remote Agent that starts the job will listen for these regular heartbeats. If the job does not send a heartbeat within this specified interval, a HEARTBEAT alarm is generated.

To send a heartbeat from a C program, call the routine found in the following file:

%AutoSys%\code\testheart.c

You must configure the Event processor to check for heartbeats, and you can do so using the AutoSys Administrator Event processor screen.

To send a heartbeat from a C program, call the routine found in the following 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

JIL/GUI Definitions 3–49

heartbeat_interval

You must configure the Event processor to check for heartbeats, and you can do so in the AutoSys configuration file ($AUTOUSER/ config.$AUTOSERV).

For more information, see the section “Sending Heartbeats,” in the chapter “AutoSys Administrator,” in the Unicenter AutoSys Job Management for Windows User Guide, or the Unicenter AutoSys Job Management for UNIX User Guide.

Where Applicable

Command job definition

Values

JIL: mins specifies the number of minutes; any reasonable number is acceptable.

GUI: Enter the minutes to specify the number of minutes between heartbeats, which the job should send; any reasonable number is acceptable. The keyword heartbeat_interval is omitted.

GUI: Enter mins to specify the number of minutes between heartbeats, which the job should send; any reasonable number is acceptable. The keyword heartbeat_interval is omitted.

The default is “0,” indicating that heartbeats will not be listened for.

Example

To set the heartbeat to be expected every 2 minutes, modify your program to call the heartbeat routine every 2 minutes or less by entering the following:

heartbeat_interval: 2

3–50 Reference Guide

insert_job

insert_job

JIL Sub-command

Function

Creates a new job of one of the following types: command job, box job, or file watcher job.

GUI Path

Job Editor, File menu, Save or Save As option (based on the Job Type and Job Name entered in the New Job dialog)

Job Definition , Job Name, Job Attribute Specification, Save

JIL Syntax

insert_job: job_name

JIL/GUI Definitions 3–51

insert_job

Description

The insert_job sub-command adds a new command, box, or file watcher job definition to the AutoSys database. The insert_job: job_name command is followed by a list of attribute:value statements, which are listed individually in this chapter. There are a set of job attributes that are required for each job type.

For command jobs, the following attribute values are required:

■ insert_job: job_name

■ command: value

■ machine: value

For box jobs, the following attributes are required:

■ insert_job: job_name

■ job_type: value

For file watcher jobs, the following attributes are required:

■ insert_job: job_name

■ job_type: value

■ machine: value

■ watch_file: value

Values

job_name The unique job identifier used throughout AutoSys. It can be from 1 to 30 alphanumeric characters, and is terminated with white space. Embedded blanks and tabs are illegal. There is no default.

3–52 Reference Guide

insert_job

Examples

1. The following example creates a command job, specifying only the essential job attributes. The job is called “time_stamp,” is to run on the real machine “tibet,” and simply executes the time_stamp.bat batch file. To create this definition, enter the following sub-command and job attributes in the JIL script:

insert_job: time_stamp machine: tibet command: time_stamp.bat

The job_type attribute is optional when defining a command job. To specify a command job, enter:

job_type: c

2. The following example creates a Box, specifying only the essential job attributes. The box is called “end_of_day”. To create this definition, enter the following sub-command and job attribute in the JIL script:

insert_job: end_of_day job_type: b

3. The following example creates a file watcher job, specifying only the essential job attributes. The file watcher is called “EOD_batch_watch”, is to run on the real machine “tibet”, and is to watch for a file named C:\myapps\EOD_batch.bat. To create this definition, enter the following sub-command and job attributes in the JIL script:

insert_job: EOD_batch_watch job_type: f machine: tibet watch_file: "C:\myapps\EOD_batch.bat"

JIL/GUI Definitions 3–53

job_load

job_load

Job Attribute

GUI Path

Job Editor, Command Info, Job Load

Job Definition, Adv Features, Job Load

JIL Syntax

job_load: load_units

Description

Specifies the relative amount of processing power the job will consume. The range of possible settings is arbitrary and user-defined. Machines can be assigned “maximum job loads,” a measure of CPU load that is desirable to place on 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 to prevent a machine from being overloaded.

If a job is ready to run on a designated machine, but the current load on that machine is too large to accept the new job’s load, the job will be queued for that machine, to be run later when sufficient resources are available. However, for this scheme to function properly, all jobs to be run on a controlled machine must have job loads specified; otherwise, a job could be started on a machine without the machine showing the additional load.

3–54 Reference Guide

job_load

The default priority of a job is 0, which means that the job should run immediately and ignore any available load units. Therefore, whenever you set a job_load for a job, you should also set a priority of 1 or higher for the job_load to take effect.

Note: You cannot use the priority or job_load attribute if you specify a user-defined load balancing script in the machine attribute.

For more information, see the chapter “Load Balancing and Queuing Jobs,” in the Unicenter AutoSys Job Management for Windows User Guide, or the chapter “Load Balancing and Queuing Jobs,” in the Unicenter AutoSys Job Management for UNIX User Guide.

Where Applicable

Command job definition

Values

JIL: load_units specifies the relative load of the job, and can be any arbitrary value within the user-defined range of possible values (which are also arbitrary).

GUI: Enter the load units, which specify the relative load of the job. This number can be any arbitrary value within the range of possible values the user has defined (which are also arbitrary).

GUI: Enter load_units, which specifies the relative load of the job. This number can be any arbitrary value within the range of possible values the user has defined (which are also arbitrary).

The default is that no load is assigned.

Example

To set the job load for a job that typically uses 10% of the CPU, with a range of possible load values from 1-100, enter:

job_load: 10

JIL/GUI Definitions 3–55

job_name (GUI only)

job_name (GUI only)

Job Attribute

GUI Path

Job Editor, Open, New, Save, and Save As dialogs, Job Name

Job Definition, Job Name

JIL Syntax

None.

Description

Specifies the name of the job using the GUI. When JIL is used, this attribute is included with the JIL sub-command; for example insert_job: job_name. This attribute must be unique within a single instance of AutoSys, since it is the primary identifier of the job. The name cannot be changed once the job has been defined.

Where Applicable

Command job definition—using GUI only

File watcher job definition—using GUI only

Box job definition—using GUI only

Values

In the Job Editor dialogs, enter the job name. The job name can be up to 30 alphanumeric characters, including the underscore character ( _ ).

There is no default; this field is always required.

3–56 Reference Guide

job_terminator

job_terminator

Job Attribute

GUI Path

Job Editor, Alarms/Terminators, If the box fails, terminate the job

Job Definition, Adv Features, If the Box Fails should this job be Terminated?

JIL Syntax

job_terminator: toggle

Description

This attribute specifies whether the job should be terminated if the box it is in fails or terminates. By using this attribute in combination with the If this job fail, terminate the box setting, you can control how nested jobs react when a job fails. This attribute only applies if the job is being placed in a box. The job is terminated with a KILLJOB event.

Note: Windows does not support the concept of process groups. If the job that was launched was a *.exe, KILLJOB will kill the process specified in the command definition. If the job being run is not a *.exe (for example, *.bat, *.cmd, or *.com), AutoSys uses CMD.EXE to launch the job; KILLJOB will kill only the CMD.EXE process. The Job Status will be set according to the return code of the killed CMD.EXE process. This status can be any one of the following: SUCCESS, FAILURE, or TERMINATED. Any processes that were launched by user applications or batch (*.bat) files will not be killed.

This attribute specifies whether 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. The job is terminated with a KILLJOB event.

For more information, on sending KILLJOB see the section “Sendevent,” in the chapter “AutoSys Commands,” in this guide.

JIL/GUI Definitions 3–57

job_terminator

Where Applicable

Command job definition, if the job is in a box

File watcher job definition, if the job is in a box

Box job definition, if the job is in a box

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate yes, or deselect it to indicate no.

GUI: Click the Yes or No radio button; to change your selection, click the other button.

The default value is 0, for No.

Example

To specify that if the box containing the job currently being created or updated fails, the job should be terminated, enter:

job_terminator: y

3–58 Reference Guide

job_type

job_type

Job Attribute

GUI Path

Job Editor, File menu New option, which opens the New Job dialog, Job Type

Job Definition, Job Type

JIL Syntax

job_type: type

Description

Specifies whether the job is a command job, file watcher job, or box job.

Where Applicable

Command job definition

File watcher job definition

Box job definition

JIL/GUI Definitions 3–59

job_type

Values

JIL: type can be any one of the following:

c (command)

f (file watcher)

b (box)

GUI: In the New Job dialog, select Command, Box, or File Watcher from the Job Type pop-up list.

GUI: Click the appropriate Box, Command, or File Watcher radio button; to change your selection, click a different button.

The default value is c, specifying a command job.

Example

To set the job currently being created or updated to be a box job, enter:

job_type: b

3–60 Reference Guide

machine

machine

Job Attribute

GUI Path

Job Editor, Basic tab, Machine

Job Definition, Execute on Machine

JIL Syntax

machine: {machine_name [, machine_name]...| ‘machine_chooser_batch_file‘}

machine: {machine_name [, machine_name]...| ‘machine_chooser_script‘}

Description

Specifies the client machine where the job will be run, under the control of the Remote Agent. The owner of the job must have permission to access this machine as well as permission to execute the specified command on this machine. The machine can be a specific real machine, a set of real machines, or a virtual machine. Real machines must be accessible over the network using the TCP/IP protocol. Specifying the machine “localhost” tells AutoSys to run the job on the machine where the Event processor is currently running

Alternatively, you can specify a program that the event processor will execute at runtime to determine which machine will be used. This program can be a program or batch file that you write yourself. The event processor runs this program and writes the name of the machine to its log file; this output will be substituted as the name of the machine. The fully qualified program or batch file name must be enclosed in back quotes.

Note: If you specify a load balancing program or batch file that you wrote yourself, you cannot use the priority or job_load attribute.

JIL/GUI Definitions 3–61

machine

Specifies the client machine where the job will be run, under the control of the Remote Agent. The owner of the job must have permission to access this machine as well as permission to execute the specified command on this machine. The machine can be a specific real machine, as listed in the /etc/hosts file on the AutoSys server machine, a set of real machines, or a virtual machine. Specifying the machine “localhost” tells AutoSys to run the job on the machine where the event processor is currently running.

Alternatively, you can specify a program that the event processor will execute at runtime to determine which machine will be used. This program can be the svload program provided by AutoSys or it can be a program or script that you write yourself. The event processor runs this program and writes the name of the machine to standard output; this output will be substituted as the name of the machine. The fully-qualified program or script name must be enclosed in back quotes.

Note: If you specify the svload program or a load balancing program or script that you wrote yourself, you cannot use the priority or job_load attribute.

WARNING! If you have implemented the Shadow Event Processor feature, you should never set the machine attribute to local host. local host implies: “run on the machine on which the event processor is currently running.” The job may run normally on the Primary Event Processor machine, and yet fail on the Shadow Event processor machine.

For more information, see the chapter “Load Balancing and Queuing Jobs,” in the Unicenter AutoSys Job Management for Windows User Guide, or the Unicenter AutoSys Job Management for UNIX User Guide.

Where Applicable

Command job definition

File watcher job definition

Note: For a file watcher, you must specify one real machine.

3–62 Reference Guide

machine

Values

JIL: machine_name can be any real machine, virtual machine, or set of real machines. The name can be up to 80 characters.

GUI: Select a defined machine from the Machine pop-up list, or Add a machine by clicking the Add button and entering a name in the New Machine Name dialog. The new name can be up to 80 characters.

GUI: Enter the machine_name, which can be any real machine, virtual machine, or set of real machines. The name can be up to 80 characters. Omit the keyword machine.

There is no default; this attribute must always be explicitly specified.

Examples

1. Specify that the job be executed on either of the machines named “tibet” or “socrates,” enter:

machine: tibet, socrates

2. Run the batch file C:\MYSTUFF\MYCHOSER.BAT at job runtime to determine which machine to use, you would enter:

machine: ‘C\:\MYSTUFF\MYCHOSER.BAT’

Note: When specifying drive letters in commands, the colon ( : ) must be escaped, For example: C\:\tmp or "C:\tmp".

2. Run the svload program at runtime to determine which machine to use, enter:

machine: 'svload -a alg [-v virt | -l list] -p profile'

3. Run the script /usr/local/bin/my-machine-chooser at job runtime to determine which machine to use, enter:

machine: '/usr/local/bin/my-machine-chooser'

JIL/GUI Definitions 3–63

max_exit_success

max_exit_success

Job Attribute

GUI Path

Job Editor, Command Info tab, Maximum Exit Code for SUCCESS

Job Definition, Adv Features, Maximum Exit Code for SUCCESS

JIL Syntax

max_exit_success: exit_code

Description

Specifies the maximum exit code with which the job can exit and still be considered a success by AutoSys. An exit code equal to or less than this value will be considered a success. This attribute is used when a command can exit with more than one exit code, indicating either “degrees of success” or other conditions that cannot indicate a failure. It is useful when defining complex branching logic based on real time processing.

Where Applicable

Command job definition

Values

JIL: exit_code can be any integer.

GUI: Enter the maximum exit code, which can be any integer.

The default is “0,” which is the normal exit code for Windows executables.

GUI: Enter the exit_code, which can be any integer representing a UNIX exit code. Omit the keyword max_exit_success.

The default is “0,” which is the normal exit code for UNIX executables.

3–64 Reference Guide

max_exit_success

Example

To set the job to be considered successful when exiting with any exit code of “2” or less, enter:

max_exit_success: 2

JIL/GUI Definitions 3–65

max_run_alarm

max_run_alarm

Job Attribute

GUI Path

Job Editor, Alarms/Terminators, Maximum Runtime

Job Definition, Adv Features, Maximum Runtime

JIL Syntax

max_run_alarm: mins

Description

Specifies the maximum runtime (in minutes) that a job should require to finish normally. This “reasonability” test can catch an error, such as the application stuck in a loop or waiting on a system event that never occurs. If the job runs longer than this time, an alarm is generated. Alarms are informational only. You must have a monitor, the Alarm Sentry, or the Alarm Manager running to track alarms in real time.

Specifies the maximum run time (in minutes) that a job should require to finish normally. This “reasonability” test can catch an error, such as the application stuck in a loop or waiting on a system event that never occurs. If the job runs longer than this time, an alarm is generated. Alarms are informational only. You must have a monitor or the Alarm Manager running to track alarms in real time.

In particular, we recommend that you include a max_run_alarm attribute for file watcher jobs to keep them from running indefinitely; this, for example, would address situations such as a communication link being down and preventing the arrival of a file.

3–66 Reference Guide

max_run_alarm

Where Applicable

Command job definition

File watcher job definition

Box job definition

Values

JIL: mins can be any integer; it represents the maximum number of minutes the job should ever require to finish normally.

GUI: Enter the number of Minutes, which can be any integer; it represents the maximum number of minutes the job should ever require to finish normally.

GUI: Enter the mins, which can be any integer; it represents the maximum number of minutes the job should ever require to finish normally. Omit the keyword max_run_alarm.

The default is to not set a maximum at all.

Example

To set the job to be considered as running too long if it runs for more than an hour and a half, enter:

max_run_alarm: 90

JIL/GUI Definitions 3–67

min_run_alarm

min_run_alarm

Job Attribute

GUI Path

Job Editor, Alarm/Terminators, Minimum Runtime

Job Definition, Adv Features, Minimum Run Time

JIL Syntax

min_run_alarm: mins

Description

Specifies the minimum runtime (in minutes) that a job should require to finish normally. This “reasonability” test can catch an error, such as the input file being truncated due to an error. If the job runs in less than this time, an alarm is generated. Alarms are informational only. You must have a monitor, the Alarm Sentry, or the Alarm Manager running to track alarms in real time.

Specifies the minimum runtime (in minutes) that a job should require to finish normally. This “reasonability” test can catch an error, such as the input file being truncated due to an error. If the job runs in less than this time, an alarm is generated. Alarms are informational only. You must have a monitor or the Alarm Manager running to track alarms in realtime.

Where Applicable

Command job definition

File watcher job definition

Box job definition

3–68 Reference Guide

min_run_alarm

Values

JIL: mins can be any integer; it represents the minimum number of minutes the job should ever require to finish normally.

GUI: Enter the number of Minutes, which can be any integer; it represents the minimum number of minutes the job should ever require to finish normally.

GUI: Enter the mins, which can be any integer; it represents the minimum number of minutes the job should ever require to finish normally. Omit the keyword min_run_alarm.

The default is no set minimum.

Example

To set the job to be considered as completing too quickly if it runs for less than an hour and a half, enter:

min_run_alarm: 90

JIL/GUI Definitions 3–69

n_retrys

n_retrys

Job Attribute

GUI Path

Job Editor, Misc tab, Number of Times to Restart this Job after a Failure

Job Definition, Adv Features, Number of Times to Restart this Job after a FAILURE

JIL Syntax

n_retrys: attempts

Description

Specifies how many times, if any, the job should be restarted after exiting with a FAILURE status. If a job is TERMINATED, it will not restart. This attribute applies to application failures, for example: 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, for example: machine unavailability, the socket-connect timed out, the fork in the Remote Agent failed, or the file system space resource check failed. Job restarts after system or network failures are controlled by the setting in the Max Restart Try’s field on the AutoSys Administrator Event processor screen.

Note: The delay between restarts is determined by the settings in the Restart Constant and Restart Factor fields on the AutoSys Administrator Event processor screen, and the delay is capped by the setting in the Max Restart Wait field.

3–70 Reference Guide

n_retrys

Specifies how many times, if any, the job should be restarted after exiting with a FAILURE status. If a job is TERMINATED, it will not restart. This attribute applies to application failures, for example: 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, for example machine unavailability, the socket-connect timed out, the fork in the Remote Agent failed, or the file system space resource check failed. Job restarts after system or network failures are controlled by the MaxRestartTrys parameter in the AutoSys configuration file.

Note: The delay between restarts is determined by the RestartConstant and RestartFactor parameters in the AutoSys configuration file, and the delay is capped by the MaxRestartWait parameter.

Where Applicable

Command job definition

File watcher job definition

Box job definition

Values

JIL: attempts can be any integer between 1 and 20.

GUI: Enter number of attempts, which can be any integer between 1 and 20.

GUI: Enter attempts, which can be any integer between 1 and 20. Omit the keyword n_retrys.

The default is 0, indicating the job will not be restarted.

JIL/GUI Definitions 3–71

n_retrys

Example

To set the job to be automatically restarted up to five times after an application failure (not system or network related), enter:

n_retrys: 5

This means that the job would start as scheduled, and, if it fails, it would restart up to five additional times for a total of six attempts.

3–72 Reference Guide

override_job

override_job

JIL Sub-command

GUI Path

Job Editor, Basic tab or File menu, Add One Time Override (or Add or Delete Override)

Job Definition, Edit OneTime Over-Rides

Function

Specifies a job override for the next run of a job.

JIL Syntax

override_job: {job_name | job_name delete} attribute_keyword: {value | NULL}

Description

The override_job sub-command specifies that a one-time override be applied to a particular job, for the indicated attributes. If an AutoSys RESTART event is generated because of system problems, AutoSys will reissue the 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 Max Restart Try’s field on the AutoSys Administrator Event processor screen.

Note: The maximum number of job restarts after system or network failures is specified in the MaxRestartTrys parameter in the AutoSys configuration file.

JIL/GUI Definitions 3–73

override_job

These are the job attributes you can use for 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 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).

All job override information is kept in a table named “overjob” in the AutoSys database. The override has a value of over_num assigned to it when you save the job definition, and is kept in the job_status table until runtime. You reference this over_num value when you want to know what overrides were applied after a job run.

For example, when applying a job override, the event processor will specify the override it is using, as shown following:

Job: JOB_NAME is using Over-Ride #14

Note: You cannot edit a job override that has been specified using JIL. If you specify an override for a job and one already exists, the new override replaces the original one. However, the original overrides for example, their over_num are still maintained in the overjob table in the AutoSys database.

3–74 Reference Guide

override_job

Values

job_name Must be a job or box currently defined in the AutoSys database. There is no default.

delete Used to cancel a previously specified job override.

NULL Used to delete or negate any currently existing value for the indicated attribute_keyword.

Examples

1. To specify a one-time job override for the job named “job1” to change the standard output file, enter the following sub-command and attribute in the JIL script:

override_job: job1 std_out_file: C:\OUTPUT\SpecialRun.out

2. To specify a one-time job override for the job named “jobA” to delete its job dependency condition and change the standard output file, enter the following sub-command and attributes in the JIL script:

override_job: jobA std_out_file: C:\OUTPUT\SpecialRun.out

3. To cancel the job overrides specified in Example 2 previously shown, enter the following sub-command in the JIL script:

override_job: jobA delete

1. To specify a one-time job override for the job named “job1” to change the standard output file, enter the following sub-command and attribute in the JIL script:

override_job: job1 std_out_file: /usr/out/run.special

2. To specify a one-time job override for the job named “jobA” to delete its job dependency condition and change the standard output file, enter the following sub-command and attributes in the JIL script:

override_job: jobA std_out_file: /usr/out/run.special

3. To cancel the job overrides specified in Example 2 previously shown, enter the following sub-command in the JIL script:

override_job: jobA delete

JIL/GUI Definitions 3–75

owner

owner

Job Attribute

GUI Path

Job Editor, Basic tab, Owner

Job Definition, Owner

JIL Syntax

owner: {user@host_or_domain | user}

Description

Specifies the owner of the job. This attribute is automatically set to the user who invoked jil or the GUI Control Panel to define the job. You can determine the job owner by looking at the Owner field on the Job Editor Basic tab, or by issuing the following command at an AutoSys Instance Command Prompt:

autorep -J job_name -q

The owner, by default, is specified in the user@host_or_domain format. The host_or_domain portion reflects the local host or local domain that the user was logged on to when defining the job. It can be either a “local” domain host name or a Windows “network” domain.

The owner cannot change this ownership designation. Only the Edit Superuser can change the owner attribute. However, when defining the job the owner can grant other users edit or execute permission on that job.

To run a job, the Remote Agent logs on to the machine first as the owner (user@host_or_domain), then, if that does not work, the Remote Agent attempts to log on to the machine as the user specified by the owner attribute at the host specified by the machine attribute (user@host).

3–76 Reference Guide

owner

For either of these log on attempts to work, the Windows user IDs and passwords must be entered into the database. In addition, if Remote Agent User Authentication is enabled, it is performed on the second (user@host) log on attempt. In this case, the proper Trusted Hosts or Trusted Users permissions are also required.

In order for jobs to run on the Primary Domain Controller in a Windows domain, the job owner must be of the form user@domain, user@host will not work. On Windows, you cannot log on to the domain controller machine; you must log on to the domain when using the domain controller machine.

For Command jobs, the command runs as the logged-on user.

Notes:

After the user is logged on to a machine, that user must also have all the necessary Windows permissions to access the command to be run, as well as any resources needed to run the command.

IF you change your Computer Name on the Identification tab of the Windows Control Panel Network dialog, you should also change the Host Name on the DNS tab of the TCP/IP Protocol dialog to the same name. AutoSys uses the Host Name as the host portion of the owner and ignores the Computer Name. This could be confusing if you know you changed your computer name, but the owner is displayed with the “old” name.

For more information, see the chapter “Autosys Commands,” in this guide.

Specifies the owner of the job. The owner is the user who invoked jil or the GUI Control Panel to define the job. This user will own all jobs defined during the session, and will have edit permission on the jobs. The UNIX command specified in that job will be run under the user ID of the owner. When a command is started on the Remote Agent, the uid of the process is changed to the owner of the job.

The default owner is defined as user@machine. Therefore, only the specific user on the specific machine can edit the job. In order for the job to run, this user@machine combination must have execute permission on the UNIX command specified in the job, on the client machine for the job.

JIL/GUI Definitions 3–77

owner

The owner cannot change this ownership designation. Only the Edit Superuser can change the owner of a job. However, the owner can grant other users edit permission, as well as execute permission, on the job. Execute permission controls which users can issue sendevent commands on the job, such as STARTJOB or KILLJOB. However, it does not affect under whose permissions the job’s command is executed.

If remote authentication has been activated using the autosys_secure Command, the user’s permission on the Remote Agent is checked at job runtime. This is done by having the Remote Agent make the ruserok() system call. This function checks the Remote Agent’s /etc/hosts.equiv and the user’s .rhosts files to validate that the requesting user is registered in that environment. This is a “local” verification; it is not related in any way to rshd or rlogind, which rely on the configuration of the Remote Agent’s / etc/services and /etc/inetd.conf files.

Note: If the rshd and rlogind are disabled on a client, but the /etc/ hosts.equiv and the .rhosts files are configured correctly, users will not be able to rlogin or rsh to the client machine, but they will be able to run AutoSys jobs on it.

Where Applicable

Command job definition

File watcher job definition

Box job definition

Values

The default setting for user@host_or_domain is the user who initiated jil or the GUI Control Panel to define the job at the host_or_domain that user was logged on to. Only the Edit Superuser can modify this attribute.

JIL: user@host_or_domain can be any valid user with an account on the specified host or domain, which must be a real, not a virtual machine. The user must have an account on all machines where the job can be run, and the user must have a valid password for that account in the AutoSys database.

3–78 Reference Guide

owner

GUI: Enter user@host_or_domain, which can be any valid user with an account on the specified machine, which must be a real, not a virtual machine. The user must have an account on all machines where the job can be run, and the user must have a valid password for that account in the AutoSys database.

The Edit Superuser can change the owner of an individual job by using the update_job JIL sub-command, or by using the AutoSys Job Editor screens. To change a large number of jobs, the Edit Superuser can invoke the autorep command to dump multiple JIL job definitions to an output file, change the owner, and re load the changed job definitions using the jil command. The following example shows how to save all job definitions to a file:

autorep -J ALL -q > dump_file

The output of this command is formatted exactly as a JIL job definition script, like:

insert_job: test_job job_type: c command: sleep 60 machine: juno owner: jerry@jupiter permission: wx alarm_if_fail: 1

The owner field of each job definition is usually commented out, unless the Edit Superuser runs the autorep command to generate the report. This is because only the Edit Superuser can change the owner field. After generating this report, the Edit Superuser can use a text editor to change the owner field and re load the job definitions into the AutoSys database using the jil command, as follows:

jil < dump_file

The default setting for user@machine is the user who initiated jil or the GUI Control Panel to define the job at the machine that user was logged on to. Only the Edit Superuser can modify this attribute.

JIL: user@machine can be any valid user with an account on the specified machine, which must be a real, not a virtual machine. The user must have an account on all machines where the job can be run.

GUI: Enter user@machine, which can be any valid user with an account on the specified machine, which must be a real, not a virtual machine. The user must have an account on all machines where the job can be run. Omit the keyword owner.

JIL/GUI Definitions 3–79

owner

The Edit Superuser can change the owner of an individual job by using the update_job JIL sub-command, or by using the AutoSys Job Definition screens. To change a large number of jobs, the Edit Superuser can invoke the autorep command to dump multiple JIL job definitions to an output file, change the owner, and re load the changed job definitions using the jil command. The following example shows how to save all job definitions to a file:

autorep -J ALL -q > dump_file

The output of this command is formatted exactly as a JIL job definition script, like:

insert_job: test_job job_type: c command: sleep 60 machine: juno owner: jerry@jupiter permission: gx,ge,wx alarm_if_fail: 1

The owner field of each job definition is usually commented out, unless the Edit Superuser runs the autorep command to generate the report. This is because only the Edit Superuser can change the owner field. After generating this report, the Edit Superuser can use a text editor to change the owner field and re load the job definitions into the AutoSys database using the jil command, as follows:

jil < dump_file

Example

For the Edit Superuser to change the owner such that “chris” on any machine in the network can edit the job, and the job’s command will run with the permissions of “chris,” enter:

owner: chris

3–80 Reference Guide

permission

permission

Job Attribute

GUI Path

Job Editor, Misc tab, Permissions area

Job Definition, Adv Features, Permissions

JIL Syntax

permission: permission [, permission]

Description

The AutoSys permission scheme provides users with edit and execute permissions on a per job basis. By default, only a job’s owner has edit and execute permission on a job.

The AutoSys permission scheme is based on the same permissions used in native UNIX. It uses the user ID (uid), and group ID (gid) from the UNIX environment to control who can edit job definitions and who can execute the actual command specified in the job. (If you are defining jobs that are to run on different operating systems, use the permissions applicable to the operating system of the client machine.)

JIL/GUI Definitions 3–81

permission

User Types

The following types of users are supported for any job:

■ Owner—The user who created the job.

■ World—Any user.

Note: For Windows, the UNIX group permission attribute is not supported.

The default owner is the user who initiated jil or the GUI Control Panel to define the job. The owner will always have both edit and execute permission for the job on the machine on which it was defined. permission attributes can extend edit and execute capability to other users and other machines.

AutoSys uses the concept of three levels of users for any job. These levels are:

■ Owner—The user who created the job.

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

■ World—Every user.

Permission Types

The following levels of permissions are supported:

■ Edit—The user can edit, override, or delete the job definition itself.

■ Exec—The user can affect the running of the job, typically by issuing a sendevent command. Events that affect the running of a job are:

■ STARTJOB

■ FORCE_STARTJOB

■ KILLJOB

■ CHANGE_STATUS

■ JOB_ON_HOLD, JOB_OFF_HOLD

■ JOB_ON_ICE, JOB_OFF_ICE

■ Machine—By default, all edit and execute permissions are valid only on the machine on which the job was defined. Permission attributes can extend this permission to other machines.

3–82 Reference Guide

permission

In UNIX, there are multiple levels of permissions associated with a job. Every job has the following levels of permissions:

■ Edit—The user can edit, override, or delete the job definition itself.

■ Execute—The user can affect the running of the job, typically by issuing a sendevent command. These are the events users can execute:

■ STARTJOB

■ FORCE_STARTJOB

■ KILLJOB

■ DELETEJOB

■ CHANGE_STATUS

■ OB_ON_HOLD, JOB_OFF_HOLD

■ OB_ON_ICE, JOB_OFF_ICE

■ SEND_SIGNAL

The default owner is the user who initiated jil or the GUI to define the job. The job owner has edit permission on the job, and the UNIX command specified in the job is run under that user ID.

When a command is started on the machine specified in the job definition, the uid of the process is changed to that of the owner of the job. This is done with the

setuid(uid) system call.

User and Permission Types

When a job is first created, the user ID is retrieved from the environment and attached to the job. Then, the current value of the owner’s umask is used to supply default permissions to the job. The 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.

JIL/GUI Definitions 3–83

permission

Where Applicable

Command job definition

File watcher job definition

Box job definition

Values

When a job is first created, the user ID is retrieved from the environment and attached to the job. Then the current value of the owner’s umask is used to supply default permissions to the job. The 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.

JIL: These are the possible values for the permission attribute:

gx (UNIX only) Group Execute

ge (UNIX only) Group Edit

mx Execute by any authorized users, regardless of the machine they are on (otherwise they must be logged on to the machine specified in the owner field, for example, user@host_or_domain).

me Edit by any authorized users, regardless of the machine they are on (otherwise they must be logged on to the machine specified in the owner field, for example, user@host_or_domain).

wx World Execute

we World Edit

The order of occurrence is not important.

GUI: Select the desired permissions by clicking the appropriate Permissions check boxes. By default, the permissions apply only if the user is logged on to the machine on which the job was created.

3–84 Reference Guide

permission

GUI: Select the desired permissions by clicking the appropriate Permissions toggle buttons. The All Hosts buttons indicate whether or not the permission should be granted regardless of the machine the user is on. By default, the group and world permissions are based on the user’s umask setting.

By default, machine permissions are turned off.

The owner of the job always has full edit and execute permissions.

Job Permissions and Windows

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

■ When defining a job to run on a Windows machine, you can set group permissions, but they will be ignored. Group permissions will be used if a job is edited or executed on a UNIX machine.

■ When editing a job from a Windows 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 a Windows 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.

Example

To set the job to be executed by any authorized user regardless of the machine they are on, you would enter:

permission: mx

To set the job to allow anyone to execute it, but to allow only members of your group to edit it, enter:

permission: ge, wx

JIL/GUI Definitions 3–85

priority

priority

Job Attribute

GUI Path

Job Editor, Command Info tab, Que priority

Job Definition, Adv Features, Que Priority

JIL Syntax

priority: priority_level

Description

Specifies the queue priority of the job. Machines can be assigned “maximum job loads,” a measure of CPU load desired to place on a machine at any given time. Each job is assigned a load as well. If a job is ready to run and designated to run on that machine, but the current load on that machine is too large to accept the new job’s load, the job will be “queued” for that machine.

The queue priority establishes the relative priority of all jobs queued for a given machine, the lower number indicating a higher priority. Scenarios can arise where a CPU-intensive, high priority job cannot get enough resources on the machine to run because smaller, lower-priority jobs continually grab the small amounts of resource available. The priority “banding” scheme provides a solution. Priorities have an associated implied “band;” 1-99 is band “0,” 100-199 is band “1”, and so forth. A band of higher priority jobs (for example; band 0) completely blocks a band of lower priority jobs, for example: band 1, until all of the high priority jobs have been run. Thus, the higher priority jobs (although demanding) will not be delayed unnecessarily.

3–86 Reference Guide

priority

Although boxes cannot be queued, they can be assigned priorities. This permits boxes within other boxes to be run according to their priority, rather than the order in which they were defined, which is the default.

Note: You cannot use the priority or job_load attribute if you specify a user-defined load balancing script in the machine attribute.

For more information, see the chapter “Load Balancing and Queuing Jobs,” in the Unicenter AutoSys Job Management for Windows User Guide.

Where Applicable

Command job definition

Box job definition

Values

priority_level can be any integer 0 or larger. priority_level 0 indicates that the job should always be run immediately, regardless of the current machine load. The lower the priority_level number, the higher the priority; therefore, 1 is the highest possible queued priority.

The default is 0, indicating the job will not be queued at all; instead it will run immediately, regardless of the current machine load.

Note: If a job_load is specified for a job, but its priority is allowed to default to 0, then the current load on the machine will be ignored, and the job will run immediately.

JIL: Enter the priority keyword and priority_level number, which can be any number that is 0 or larger.

GUI: Enter the priority level number, which can be any number that is 0 or larger.

JIL/GUI Definitions 3–87

priority

GUI: Enter the priority_level number, which can be any number that is 0 or larger. Omit the keyword priority.

Examples

1. Set the job to always run, regardless of the current load on the client machine, accept the default, which is 0.

2. Set the job to run with the highest priority, while not overriding the machine load control mechanism, enter:

priority: 1

3. Set the job to run in the background when the machine load is low, enter:

priority: 100

3–88 Reference Guide

profile

profile

Job Attribute

GUI Path

Job Editor, Resource/Profile tab, Job Environment Profile

Job Definition, Adv Features, Job Environment Profile

JIL Syntax

profile: profile_name

profile: pathname

Description

Specifies an AutoSys job profile that defines environment variables to be set before the specified command is executed. If the profile attribute is not specified, the profile named “default” is used; AutoSys “sources” the default profile before running jobs that do not have a profile explicitly assigned to them. On Windows, the default profile is initially empty. You can leave the default profile empty, or you can define the environment variables that you want it to contain.

You can define the default and other job profiles using the Profiles Manager, to specify the profile for a job, you can supply the name of a profile that is located on the job’s client machine, or you can supply a path name that includes the machine on which the profile resides, using the form:

\\computer_name\profile_name

JIL/GUI Definitions 3–89

profile

For more information, see the section “Basic Job Attributes,” in the chapter “AutoSys Jobs,” in the Unicenter AutoSys Job Management for Windows User Guide.

System environment variables are the only other variables defined for the command’s execution. Therefore, non-system environment variables must be defined in either the default or a user-defined job profile. System environment variables are set before profile variables. Therefore, you can use references to system environment variables in job profiles.

Notes:

■ If a command normally runs at the MS-DOS Command Prompt (or from the AutoSys Instance Command Prompt window), but fails to run properly from AutoSys, the most likely cause of failure is a difference between the Windows user-defined environment variables and the environment specified in the job’s profile.

■ Either the specified profile or the default profile will be used; not both. Therefore, if there are environment variables in the default profile that your command needs, for example: the path to an AutoSys command, make sure to set them in your specified job profile.

Specifies the profile that is to be sourced by the Bourne shell before the specified command is executed. If a profile attribute is specified, that profile is searched for on the machine on which the command is to run. 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 the definitions and exports of environment variables, which can be referenced in the job’s command (especially if the command is a shell script).

It is very important that Korn shell and C shell statements are not included in the profile file, since the Bourne shell that AutoSys runs will not be able to process them. The results will be, at best, unexpected. In particular, redirection of the stdin, stdout, and stderr files will most likely fail.

The primary environment variable in the profile is the path. If a profile is not specified, the default AutoSys profile, /etc/auto.profile, will be used.

3–90 Reference Guide

profile

The only environment variable that absolutely must be set in the profile is the $PATH variable, since it is used to locate the command specified in the job. For Korn shell users, we recommend that any other environment variables required to be set are either explicitly set in the shell script that is specified as the command to be run, or that additional shell scripts be sourced in your main shell script.

If you want the set permissions for stdout and stderr to -rw-r--r--, you must set umask 022 in /etc/auto.profile, or, if you are using the profile attribute, set it in the specified profile file. If you do not set this, the stdout and stderr files will have world write permissions.

Notes: ■ If a command normally runs at the shell prompt, but fails to run properly

from AutoSys, the most likely cause of failure is a difference between the shell environment and the environment specified in the profile file.

■ Either the specified profile file, or if not specified, the default /etc/auto.profile file is sourced, not both. Therefore, if there are environment variables in /etc/auto.profile that your command needs to use for example: the path to AutoSys binaries like autostatus, make sure to include them in your specified profile file.

Where Applicable

Command job definition

File watcher job definition

JIL/GUI Definitions 3–91

profile

Values

profile_name

A job environment profile defined using the Profiles Manager, located in the AutoSys program group. If the profile attribute is omitted, the profile named “default” is used.

JIL: Enter the name of the profile containing the environment variables to be set.

GUI: Enter the name of the profile containing the environment variables to be set. When entering the job profile, you can specify both the machine name and profile name, which allows you to run the job on one machine while using a Job Profile defined on another machine.

pathname

The full path name of the profile file to be sourced in order to establish the job’s runtime environment. Variable substitution cannot be used.

The full pathname cannot exceed 80 characters.

The default is to source the AutoSys-supplied profile named /etc/ auto.profile.

JIL: Enter the profile keyword and the full path name of the file to be sourced.

GUI: Enter the full path name of the file to be sourced. Omit the keyword profile.

Examples

To set the environment from a profile named “eng” (which was previously defined in the Profiles Manager, located in the AutoSys program group), enter:

profile: eng

Set the environment from a profile named “eng” that was defined on the machine “dev,” which is different from the machine on which the job will run, enter the machine name and the profile name, like:

profile: \\dev\eng

To set the user’s profile called my_profile in their home directory called /usr/home, enter:

profile: /usr/home/my_profile

3–92 Reference Guide

run_calendar

run_calendar

Job Attribute

GUI Path

Job Editor, Date/Time tab, Run Calendar

Job Definition, Date/Time Options, Run on Days in Calendar

JIL Syntax

run_calendar: calendar_name

Description

Indicates the name of the custom calendar to be used when determining the days of the week on which a job will run. This attribute is useful for complex date specification, such as running a job on the last business day of the month. The custom calendar will list the dates and the times when the job is to be run. The calendar must have been previously created using the Graphical Calendar Facility or the autocal_asc command. This attribute and the days_of_week attribute are mutually exclusive.

AutoSys will schedule the job to run on every day specified in this calendar, at the times specified in the calendar (default calendar time is midnight), or at the times specified in the start_times or start_mins attribute. The start_times and start_mins attributes override any times set in a calendar.

Where Applicable

Command job definition

File watcher job definition

Box job definition

JIL/GUI Definitions 3–93

run_calendar

Values

JIL: calendar_name must be the name of a custom calendar that has already been created.

GUI: Check the Date/Time Conditions check box, select the Run Calendar radio button, and then select a defined calendar from the Run Calendar pop-up list. To create or modify a Calendar, click the Edit Calendar button, which opens the Calendar Editor.

GUI: Enter the name of a custom calendar that has been previously created. The keyword run_calendar is omitted. If you have entered a calendar name, then decide to specify the dates or days using other fields in the dialog, clear this field to avoid an error.

The default is that no run calendar will be used.

Example

To specify that the job should be run on the last business day of the month, as specified in the previously created custom calendar named “last_business”, enter:

run_calendar: last_business

3–94 Reference Guide

run_window

run_window

Job Attribute

GUI Path

Job Editor, Date/Time tab, Run Window

Job Definition, Date/Time Options, Run Window

JIL Syntax

run_window: "time-time"

Description

Indicates the time span during which the job will be allowed to start. If this attribute is specified, then when the job is eligible to run (based on its starting conditions) AutoSys will check if the current time falls within the specified run window. If it does, the job will start. If it does not, the following calculations are used to determine whether or not to run the job. The end of the last run window and the beginning of the next run window are determined. If the current time is closer to the beginning of the next run window, the job will be scheduled to start when the next run window starts. If the current time is closer to the end of the last run window, the job does not start and its status is changed to INACTIVE.

run_window is not in itself a starting condition. It is an additional control over when the job will be allowed to start, once the starting conditions have been satisfied. The time range in a run window cannot span more than 24 hours.

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

Run Windows in Boxes

If the job is in a box, the job is changed to ACTIVATED state when the box starts running. However, if the current time is not in the specified run window, the job is changed to INACTIVE state.

JIL/GUI Definitions 3–95

run_window

If a run_window is specified as the only date_condition, the Event processor will calculate the time since the run_window closed and the time until the run_window opens again.

■ If the current time is closer to the end of the run_window than the next opening of the run_window, the status of the job is changed to INACTIVE. If the job is in a box, the box can still run to completion.

■ If the current time is closer to the start of the next run_window, a future STARTJOB event is issued for the next opening of the run_window.

The above calculations and actions are done so that a box can run to completion when the run_window for a job inside the box has just closed. For example, “jobA”, “jobB”, and “jobC” are in “box1” and “jobA” has a run_window of 02:00 to 04:00. If “boxA” starts at 04:05, “jobB” and “jobC” can run and “jobA” will become INACTIVE, so that the box can complete that day. If “box1” instead starts at 16:05, “jobA” will have a STARTJOB event set for 02:00 the next day, and the box will continue running until the job starts the next day.

Where Applicable

Command job definition

File watcher job definition

Box job definition

Values

JIL: time-time must be entered in quotes, using the format "hh:mm-hh:mm" where the hh specifies hours, in 24-hour format, and the mm specifies minutes.

GUI: Enter the time range, using the format hh:mm-hh:mm where the hh specifies hours, in 24-hour format, and the mm specifies minutes.

The default is that no run window will be used.

The range can overlap midnight as long as it is not more than 24 hours, as in the following example.

3–96 Reference Guide

run_window

Example

To specify that the job should be allowed to start only between 11:00 p.m. and 2:00 a.m., regardless of other conditions, enter:

run_window: "23:00-02:00"

JIL/GUI Definitions 3–97

start_mins

start_mins

Job Attribute

GUI Path

Job Editor, Date/Time tab, Minutes after Each Hour

Job Definition, Date/Time Options, Every Hour at

JIL Syntax

start_mins: mins [, mins]...

Description

Indicates the number of minutes past the hour, every hour, on the specified days or dates, when the job will be started. The days or dates must be specified using one of the following attributes: days_of_week or run_calendar. This attribute overrides any times set in a run calendar. The start_mins attribute and the start_times attribute are mutually exclusive.

Where Applicable

Command job definition

File watcher job definition

Values

Box job definition

JIL: mins must be a number 0–59, representing the number of minutes past each hour when the job will be run. The total number of characters must not exceed 255. Multiple lines can be used without specifying a continuation character.

3–98 Reference Guide

start_mins

GUI: Enter a number, 0–59, representing the number of minutes past each hour when the job will be run. The total number of characters must not exceed 255. You can also enter a number in the Every n Minutes field, then click Apply, this puts the appropriate intervals in the Minutes after Each Hour field.

GUI: Enter a number, 0–59, representing the number of minutes past each hour when the job will be run. The total number of characters must not exceed 255. The keyword start_mins is omitted.

The default is that no start time in minutes will be set.

Example

To specify that the job be run at a quarter past and a quarter before each hour, enter:

start_mins: 15, 45

JIL/GUI Definitions 3–99

start_times

start_times

Job Attribute

GUI Path

Job Editor, Date/Time tab, Times of Day

Job Definition, Date/Time Options, Times of Day

JIL Syntax

start_times: "time [, time]..."

Description

Indicates the times of day, in 24-hour format, on the specified days or dates, when the job will be started. The days or dates must be specified using one of the following attributes: days_of_week or run_calendar. This attribute overrides any times set in a run calendar. The start_times attribute and the start_mins attribute are mutually exclusive.

Where Applicable

Command job definition

File watcher job definition

Box job definition

3–100 Reference Guide

start_times

Values

JIL: time must be specified using the format “hh:mm” where the hh specifies hours, in 24-hour format, and the mm specifies minutes.

Be sure to include the quotes, or an error will result. The total number of characters must not exceed 255. Multiple lines can be used without specifying a continuation character.

GUI: Enter the time using the format hh:mm where the hh specifies hours, in 24-hour format, and the mm specifies minutes. You can enter a comma separated list of times.

The total number of characters must not exceed 255.

The default is that no start time will be set. This is an error if days or dates are specified for this job, and no time has been specified in the other field.

Example

To specify that the job be run at 10:00 a.m. and 2:00 p.m. on every specified day or date, enter:

start_times: "10:00, 14:00"

JIL/GUI Definitions 3–101

std_err_file

std_err_file

Job Attribute

GUI Path

Job Editor, Command Info, File to redirect to standard error

Job Definition, Adv Features, File to Redirect to Standard Error

JIL Syntax

std_err_file: pathname

Description

Specifies the file to which the standard error file’s output should be redirected. Any file for which the job owner has write permission on the client machine can be specified as the standard error file.

By default, the file will be overwritten with new information. By placing the following notation as the first characters 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 Append stdout/ stderr field on the AutoSys Administrator Event processor screen.

It also overrides the machine-specific setting for the AutoMachWideAppend environment variable that you can set on the Administrator System Information screen.

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.

3–102 Reference Guide

std_err_file

If you are running jobs across platforms, the Event processor of the issuing instance controls the default behavior. For UNIX, the default is to append this file, and for Windows the default is to overwrite this file.

Where Applicable

Command job definition

Values

pathname

The path name to which all error output is to be redirected. The full path name must be specified, although variables exported from the job profile or from the AutoSys global variables can be used in the path name specification. If a full path name is not specified, the job owner’s home directory is assumed. If variable substitution is used, we recommended that the variable be enclosed in curly braces, such as in “${PATH}” for variables referenced in the job profile. The expression $${global_name} should be used for AutoSys global variables. The pathname must not exceed 80 characters.

The path name to which all error output is to be redirected. The full path name must be specified, although variables exported from the profile script or from the AutoSys global variables can be used in the path name specification. If variable substitution is used, we recommended that the variable be enclosed in curly braces, such as in “${PATH}” for variables referenced in the profile file. The expression $${global_name} should be used for AutoSys global variables. The pathname must not exceed 80 characters.

When using JIL, if you are including a drive letter with the path name, it must be escaped; for example "C:\tmp" and C\:\tmp are valid; C:\tmp is not. When using the Job Editor, do not use quotes.

The default is to redirect standard error file output to NULL.

The default is to redirect standard error file output to /dev/null.

JIL: Enter the std_err_file keyword and the full path name for the standard error file.

GUI: Enter the full path name for the standard error file. Omit the keyword std_err_file.

JIL/GUI Definitions 3–103

std_err_file

Examples

1. To set the job, enter:

std_err_file: "C:\tmp\TEST.ERR"

2. Append new information to the error file, enter:

std_err_file: ">>C:\tmp\TEST.ERR"

3. Set the file “C:\tmp\TodaysDate.err” to receive standard error file output for the job, you would set a global variable named “Today” (using the sendevent command or the Send Event Tool) to be today’s date, then enter:

std_err_file: "C:\tmp\$$Today.err"

4. You can create a unique identifier by appending the process id to the file name, using %AUTOPID% as shown in the following example:

std_err_file: "C:\tmp\my_file.%AUTOPID%"

1. To set the file /tmp/test.err to receive standard error file output for the job, enter:

std_err_file: /tmp/test.err

2. Append new information to the error file, enter:

std_err_file: >>/tmp/test.err

3. Set the file /tmp/today’s_date.err to receive standard error file output for the job, set a global variable named “Today” (using sendevent or the Send Event dialog) to be today’s date, then enter:

std_err_file: /tmp/$${Today}.err

4. You can create a unique identifier by appending the process id to the file name, using $$ as shown in the following example:

std_err_file: /tmp/my_file.$$

If you want to imbed the process id in the middle of the file name, you must follow the $$ with a dot, slash, or space (otherwise AutoSys will try to interpret the string following the $$ as a global variable). Therefore, the following examples are valid:

std_err_file: /tmp/my_file.$$.err std_err_file: /tmp/my_file.$${}err

3–104 Reference Guide

std_err_file

Note: In the final example above, the curly braces must be used to separate the $$ from the string err. Otherwise, AutoSys would try to interpret err as a global variable. If unable to find global variable err, AutoSys would drop that part of the file name, creating a file named my_file. (because $$err would be null).

JIL/GUI Definitions 3–105

std_in_file

std_in_file

Job Attribute

GUI Path

Job Editor, Command Info, File to redirect to standard input

Job Definition, Adv Features, File to Redirect to Standard Input

JIL Syntax

std_in_file: pathname

Description

Specifies the file to which the standard input file for the job should be redirected. Any file for which the job owner has read permission on the client machine can be specified as the standard input file.

Where Applicable

Command job definition

Values

pathname

The path name to which all standard input is to be redirected. The full path name must be specified, although variables exported from the job profile or from the AutoSys global variables can be used in the path name specification. If a full path name is not specified, the job owner’s home directory is assumed. If variable substitution is used, the variable should be enclosed in curly braces, such as in “${PATH}” for variables referenced in the job profile. The expression $${global_name} should be used for AutoSys global variables. The pathname must not exceed 80 characters.

When using JIL, if you are including a drive letter with the path name, it must be escaped for example "C:\tmp" and C\:\tmp are valid; C:\tmp is not. When using the Job Editor, do not use quotes.

3–106 Reference Guide

std_in_file

The path name to which all standard input is to be redirected. The full path name must be specified, although variables exported from the profile script or from the AutoSys global variables can be used in the path name specification. If variable substitution is used, the variable should be enclosed in curly braces, such as in “${PATH}” for variables referenced in the profile file. The expression $${global_name} should be used for AutoSys global variables. The pathname must not exceed 80 characters.

The default is to not redirect standard input.

JIL: Enter the std_in_file keyword and the full path name of the standard input file.

GUI: Enter the full path name for the standard input file. Omit the keyword std_in_file.

GUI: Enter the full path name for the standard input file. Omit the keyword std_in_file.

Examples

1. Set the file named "C:\tmp\TEST.IN" to be read as the standard input file, enter:

std_in_file: "C:\tmp\TEST.IN"

2. Set the file named “C:\tmp\TodaysDate.in” to be read as the standard input file, you would set a global variable named “Today” (using the sendevent command or the Send Event Tool) to be today’s date, then enter:

std_in_file: "C:\tmp\$$Today.in"

1. Set the file named /tmp/test.in to be read as the standard input file, enter:

std_in_file: /tmp/test.in

2. Set the file named /tmp/today’s_date.in to be read as the standard input file, set a global variable named “Today” (using sendevent or the Send Event dialog) to be today’s date, then enter:

std_in_file: /tmp/$${Today}.in

JIL/GUI Definitions 3–107

std_out_file

std_out_file

Job Attribute

GUI Path

Job Editor, Command Info, File to redirect standard output

Job Definition, Adv Features, File to Redirect to Standard Output

JIL Syntax

std_out_file: pathname

Description

Specifies the file to which the standard output file should be redirected. Any file for which the job owner has write permission on the client machine can be specified as the standard out file. By default, the file will be overwritten with new information. By placing the following notation as the first characters 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 Append stdout/ stderr field on the AutoSys Administrator Event processor screen. It also overrides the machine-specific setting for the AutoMachWideAppend environment variable that you can set on the Administrator System Information screen.

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.

If you are running jobs across platforms, the event processor of the issuing instance controls the default behavior. For UNIX, the default is to append this file, and for Windows the default is to overwrite this file.

3–108 Reference Guide

std_out_file

Where Applicable

Command job definition

Values

pathname

The path name to which all standard output is to be redirected. The full path name must be specified, although variables exported from the job profile or from the AutoSys global variables can be used in the path name specification. If a full path name is not specified, the job owner’s home directory is assumed. If variable substitution is used, the variable should be enclosed in curly braces, such as in “${PATH}” for variables referenced in the job profile. The expression $${global_name} should be used for AutoSys global variables. The pathname must not exceed 80 characters.

When using JIL, if you are including a drive letter with the path name, it must be escaped for example "C:\tmp" and C\:\tmp are valid; C:\tmp is not. When using the Job Editor, do not use quotes.

pathname

The path name to which all standard output is to be redirected. The full path name must be specified, although variables exported from the profile script or from the AutoSys global variables can be used in the path name specification. If variable substitution is used, the variable should be enclosed in curly braces, such as in “${PATH}” for variables referenced in the profile file. The expression $${global_name} should be used for AutoSys global variables. The pathname must not exceed 80 characters.

The default is to redirect standard output to NULL.

JIL: Enter the std_out_file keyword and the path name of the standard out file.

GUI: Enter the full path and name for the standard out file. Omit the keyword std_out_file.

GUI: Enter the full path name for the standard out file. Omit the keyword std_out_file.

JIL/GUI Definitions 3–109

std_out_file

Examples

1. Set the file named "C:\tmp\TEST.OUT" to receive standard output for the job, enter:

std_out_file: "C:\tmp\TEST.OUT"

2. Append new information to the output file, enter:

std_err_file: ">>C:\tmp\TEST.OUT"

3. Set the file named “C:\tmp\TodaysDate.out” to receive standard output for the job, you would set a global variable named “Today” (using the sendevent command or the Send Event Tool) to be today’s date, then enter:

std_err_file: "C:\tmp\$${Today}.out"

1. Set the file named /tmp/test.out to receive standard output for the job, enter:

std_out_file: /tmp/test.out

2. Append new information to the output file, enter:

std_err_file: >>/tmp/test.out

3. Set the file named /tmp/today’s_date.out to receive standard output for the job, set a global variable named “Today” (using sendevent or the Send Event dialog) to be today’s date, then enter:

std_out_file: /tmp/$${Today}.out

4. You can create a unique identifier by appending the process id to the file name, using $$ as shown in the following example:

std_out_file: /tmp/my_file.$$

If you want to imbed the process id in the middle of the file name, you must follow the $$ with a dot, slash, or space (otherwise AutoSys will try to interpret the string following the $$ as a global variable). Therefore, the following examples are valid:

std_out_file: /tmp/my_file.$$.mary std_out_file: /tmp/my_file.$${}mary

Note: In the example shown here, the curly braces must be used to separate the $$ from the string “mary.” Otherwise AutoSys would try to interpret mary as a global variable. If unable to find global variable mary, AutoSys would drop that part of the file name, creating a file named my_file. (because $$mary would be null).

3–110 Reference Guide

term_run_time

term_run_time

Job Attribute

GUI Path

Job Editor, Alarms/Terminators, Terminate this job n mins after starting

Job Definition, Adv Features, Terminate this Job Mins after starting

JIL Syntax

term_run_time: mins

Description

Specifies the maximum runtime (in minutes) that a job should require to finish normally. If the job runs longer than this time, it will be automatically terminated by AutoSys.

Note: Windows does not support the concept of process groups. If the job that was launched was a *.exe, KILLJOB will kill the process specified in the command definition. If the job being run is not a *.exe, for example: *.bat, *.cmd, or *.com, AutoSys uses CMD.EXE to launch the job; KILLJOB will kill only the CMD.EXE process. The Job Status will be set according to the return code of the killed CMD.EXE process. This status can be any one of the following: SUCCESS, FAILURE, or TERMINATED. Any processes that were launched by user applications or batch (*.bat) files will not be killed.

Where Applicable

Command job definition

File watcher job definition

Box job definition

JIL/GUI Definitions 3–111

term_run_time

Values

JIL: mins can be any integer; it represents the maximum number of minutes the job should ever require to finish normally.

GUI: Enter the number of minutes, which can be any integer; it represents the maximum number of minutes the job should ever require to finish normally. Omit the keyword term_run_time.

GUI: Enter the mins, which can be any integer; it represents the maximum number of minutes the job should ever require to finish normally. Omit the keyword term_run_time.

The default is “0,” indicating the job should allowed to run forever.

Example

To set the job to be automatically terminated if it runs longer than 90 minutes, enter:

term_run_time: 90

3–112 Reference Guide

timezone

timezone

Job Attribute

GUI Path

Job Editor, Date/Time tab, Time Zone

Job Definition, Adv Features, Time Zone

JIL Syntax

timezone: zone

Description

Allows you to schedule a job based on a chosen time zone. When the timezone attribute is specified in a job definition, the time settings in that job are based on the zone time zone. For example, if you define a start time of 01:00 for a job running on a machine in Denver, and set timezone to San Francisco (which is in the Pacific time zone, one hour earlier than Denver), the job will start at 2:00 a.m. in Denver.

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.

For more information, see the chapter “AutoSys Commands,” in this guide.

Where Applicable

Command job definition

File watcher job definition

Box job definition

JIL/GUI Definitions 3–113

timezone

Values

zone

A case-insensitive string of characters corresponding to an entry in the AutoSys timezones table. The timezones table contains entries for all the cities and time zones supported by Windows NT, as well as many additional cities throughout the world.

Windows time zones are located in the Date/Time applet in the Control Panel. The majority of entries in the Time Zone pull-down menu of the Date/Time applet are cities, any one of which can be specified by the timezone attribute.

For example, if you want a job to run in the time zone Windows NT refers to as “Bogota, Lima,” you could specify either “Bogota” or “Lima.” Omit spaces and periods when specifying this attribute; for example, use “MountainTime” instead of “Mountain Time,” and “SolomonIs” instead of “Solomon Is.”

Entry Type Zone

AbuDhabi City Arabian-Z

Adelaide City Australia/Adelaide

Africa Zone SAT-2

Africa/Cairo Alias Egypt

Africa/Cape_Verde Zone AAT1

Africa/Casablanca Zone WET+0

Africa/Harare Alias Africa-Z

Africa/Johannesburg Zone SAST-2

Africa/Monrovia Zone WAT+0

AKST9AKDT Zone AKST9AKDT

3–114 Reference Guide

timezone

Entry Type Zone

Alaska Alias US/Alaska

Almaty City Asia/Almaty

ASKT9AKDT

America/Atka Zone HAST10HADT

America/Bogota Zone EST5

America/Buenos_Aries Zone EST3

America/Caracas Zone AST4

America/Fort_Wayne Zone EST5

America/Anchorage Zone

Note: Some regions may change to daylight saving time at different days and times than the time zone in which the AutoSys server machine is running. Any jobs scheduled to start in such a time zone will run one hour earlier (or later) until the time zone in the job definition and the time zone where the server is running are both in the same time scheme (either daylight saving time or standard time).

Either a time zone recognized by the operating system or a case-insensitive string of characters corresponding to an entry in the timezones table. The timezones table contains entries for all the common time zones maintained by the operating system, as well as many cities in the United States. Entries in the timezones table are strings between 1 and 50 characters; these characters can be uppercase or lowercase letters, decimal digits, slash ( / ), hyphen ( — ), and underscore ( _ ). AutoSys interprets the string and matches it to a time zone value on your platform. If the string is not found there, AutoSys searches for it in the timezones table. The table might be read multiple times to resolve a zone value. If the zone value is not resolved after five attempts, the job will fail. It is best to use a time zone value that is available from your operating system to ensure that AutoSys is using the same values as other applications running on that platform.

JIL/GUI Definitions 3–115

timezone

This is a sample of the timezone table (to display all the entries in the table, use the autotimezone -l command):

Entry Type TZ Variable

Auckland City NZ

Bahamas Alias EST5EDT

Bangkok City GMT-7

Beijing City CST-8CDT

Berlin City METS-1METD

Bogota City EST5

Bombay City IST

Note: Some regions may change to daylight saving time at different days and times than the time zone in which the AutoSys server machine is running. Any jobs scheduled to start in such a time zone will run one hour earlier (or later) until the time zone in the job definition and the time zone where the server is running are both in the same time scheme (either daylight saving time or standard time).

Example

To set the time zone for a job definition to Chicago time, enter:

timezone: Chicago

To set the time zone for a job definition to Pacific time, enter:

timezone: US/Pacific

If you specify a time zone that includes a colon, you must quote the time zone name if you are using JIL, like:

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. However, if you are using the Job Editor, you do not need to escape the time zone specification.

3–116 Reference Guide

update_job

update_job

JIL Sub-command

Function

Updates an existing job of one of the following types: command job, box job, or file watcher job.

GUI Path

Job Editor, File menu, Save option

Job Definition, Job Name, Enter New or Modify Existing Attributes, Save

JIL Syntax

update_job: job_name

Description

The update_job sub-command updates an existing command, box, or file watcher job definition in the AutoSys database. The update_job statement is followed by a list of attribute:value statements, which are listed individually in this chapter.

Any attributes in the existing definition that are not explicitly replaced by specifying the attribute in the update_job input will retain their original settings. If many attributes need to be “unset,” it would be more efficient to delete and re-insert the new or updated job definitions.

Values

job_name The unique job identifier used to define the original job to AutoSys. There is no default value.

JIL/GUI Definitions 3–117

update_job

Example

To change a preexisting command job called “time_stamp” to run on the real machine “paris”, rather than on the originally specified machine, enter the following sub-command and job attribute in the JIL script:

update_job: time_stamp machine: paris

3–118 Reference Guide

watch_file

watch_file

Job Attribute

GUI Path

Job Editor: for File Watcher Job, Basic tab, File to watch

Job Definition, Adv Features, File to Watch For

JIL Syntax

watch_file: pathname

Description

Specifies the full path name of the file for which this file watcher job should watch. System environment variables, AutoSys job profile environment variables, and AutoSys global variables can be used in the path name specification.

Specifies the file for which this file watcher job should watch. The name of the file to watch for must be a legal UNIX file name, and it must identify the full path name of the file. Variables exported from the profile script or AutoSys global variables can be used in the path name specification.

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.” AutoSys does not actually consider a file complete until the minimum file size is reached, and the watch interval has detected a “steady state” for example: the file size has not changed between checked intervals.

In those cases where the user has control over the application generating the file, we recommend that the following “fail-safe” scenario be used. Since the generating application could crash, or a communication link could be interrupted after having written the minimum size file, AutoSys would evaluate that the file was complete, when it actually would not be complete.

JIL/GUI Definitions 3–119

watch_file

To circumvent this situation, we recommend that a separate, zero-length file be created by the generating application when it’s finished writing the data file. The application would delete this file on its next run. The file watcher would actually be set to watch for the appearance of this “completion indicator” file.

Where Applicable

File watcher job definition

Values

pathname

The full path name of the file for which to watch. Variables exported from the job profile can be used in the path name specification. If variable substitution is used, we recommend that the variable be enclosed in curly braces, such as in “${PATH}” for variables referenced in the job profile. The expression $${global_name} should be used for AutoSys global variables. The pathname must not exceed 80 characters.

When using JIL, if you are including a drive letter with the path name, it must be escaped (for example "C:\tmp" and C\:\tmp are valid; C:\tmp is not). When using the Job Editor, do not use quotes.

GUI: Enter the full pathname and name of the file for which to watch.

pathname

The full path name of the file for which to watch. Variables exported from the profile script can be used in the path name specification. If variable substitution is used, we recommend that the variable be enclosed in curly braces, such as in “${PATH}” for variables referenced in the profile file. The expression $${global_name} should be used for AutoSys global variables. The pathname must not exceed 80 characters.

There is no default; a pathname is always required for a file watcher.

JIL: Enter the watch_file keyword and the full path name of the file for which to watch.

GUI: Enter the full pathname and name of the file for which to watch. Omit the keyword watch_file.

3–120 Reference Guide

watch_file

Examples

1. Set the file watcher to watch for a file named “C:\tmp\BATCH.IN,” enter:

watch_file: "C:\tmp\BATCH.IN"

2. Set the file watcher to watch for a file whose name has been assigned to a global variable named “file_1,” enter:

watch_file: $${file_1}

1. Set the file watcher to watch for a file named /tmp/batch.input, enter:

watch_file: /tmp/batch.input

2. Set the file watcher to watch for a file whose name has been assigned to a global variable named “file_1,” enter:

watch_file: $${file_1}

JIL/GUI Definitions 3–121

watch_file_min_size

watch_file_min_size

Job Attribute

GUI Path

Job Editor: for File Watcher Job, Basic tab, Minimum file size (in bytes)

Job Definition, Adv Features, Minimum File Size (in Bytes)

JIL Syntax

watch_file_min_size: bytes

Description

Specifies the watch file minimum size (in bytes), which determines when enough data has been written to the file to consider it complete. AutoSys does not consider a file complete until both the minimum file size is reached, and the watch interval has detected a “steady state” for example: the file size has not changed between checked intervals. A reasonable file size should be specified in order to ensure that a nearly empty file does not appear to be complete, while a size that is smaller than usual does not prevent the file from being considered complete.

In those cases where the user has control over the application generating the file, we recommend that the following “fail-safe” scenario be used. Since the generating application could crash, or a communication link could be interrupted after having written the minimum size file, AutoSys would think the file was complete, when it actually wouldn’t be.

To circumvent this situation, we recommend that a separate, zero-length file be created by the generating application when it is finished writing the data file. The application would delete this file on its next run. The file watcher would actually be set to watch for the appearance of this “completion indicator” file.

Where Applicable

File watcher job definition

3–122 Reference Guide

watch_file_min_size

Values

JIL: bytes can be any integer; it represents the minimum number of bytes in the file before it is considered complete.

GUI: Enter the size in bytes, which can be any integer. This number represents the minimum number of bytes in the file before it is considered complete.

GUI: Enter the bytes, which can be any integer. This number represents the minimum number of bytes in the file before it is considered complete. Omit the keyword watch_file_min_size.

The default is “0,” meaning the mere presence of the file is enough to consider the file complete.

Example

To set the file to be considered complete when it reaches 10 KB bytes (assuming the file has reached “steady state” as well), enter:

watch_file_min_size: 10000

JIL/GUI Definitions 3–123

watch_interval

watch_interval

Job Attribute

GUI Path

Job Editor: for File Watcher Job, Basic tab, Time Interval (secs) to determine steady state

Job Definition, Adv Features, Time Interval (secs) to Determine Steady State

JIL Syntax

watch_interval: seconds

Description

Specifies the interval (in seconds) at which the file watcher job will check for the existence and size of the watched-for file. A “steady state” is said to have been reached when the file hasn’t grown during the specified time interval. When the “steady state” has been reached and the file is at least as large as the minimum file size specified in watch_file_min_size, the file is considered complete. A reasonable interval should be specified to ensure that the file does not appear to be at “steady state” when it really is not.

In those cases where the user has control over the application generating the file, we recommend that the following “fail-safe” scenario be used. Since the generating application could crash, or a communication link could be interrupted after having written the minimum size file, AutoSys would think the file was complete, when it actually would not be.

To circumvent this situation, we recommend that a separate, zero-length file be created by the generating application when it is finished writing the data file. The application would delete this file on its next run. The file watcher would actually be set to watch for the appearance of this “completion indicator” file.

Where Applicable

File watcher job definition

3–124 Reference Guide

watch_interval

Values

JIL: seconds can be any integer; it represents the time interval between checks of the file existence and file size.

GUI: Enter the number of seconds, which represents the time interval between checks of the file existence and file size.

GUI: Enter the seconds, which can be any integer; it represents the time interval between checks of the file existence and file size. Omit the keyword watch_interval.

The default interval is 60.

Example

To set the file to be checked for a steady state every two minutes, enter:

watch_interval: 120

JIL/GUI Definitions 3–125

Chapter

4 JIL Machine Definitions

This chapter provides an alphabetical listing of all the JIL sub-commands and machine attributes used to define and describe real and virtual machines.

JIL Sub-commands

Certain JIL sub-commands are used to define the machines upon which AutoSys operates.

Machine Attributes

There are several attributes, which are used to define and describe AutoSys machines. Machine attributes are defined using JIL statements, which are input to the jil command.

Note: AutoSys machines can only be defined and described using JIL statements.

JIL Machine Definitions 4–1

delete_machine

delete_machine

JIL Sub-command

Function

Deletes a real or virtual machine from the AutoSys database.

JIL Syntax

delete_machine: machine_name

Description

The delete_machine sub-command deletes the specified machine from the AutoSys database. To delete a component (real) machine from a virtual machine, while leaving the virtual machine defined, you specify the machine attribute immediately after the command, as in the example given following. To delete an entire virtual machine, you use delete_machine without the machine attribute.

If a real machine was defined separately, for example: (not as part of a virtual machine,) delete_machine will delete it from the virtual machine; however, the real machine definition will still exist.

Values

machine_name Must be a real or virtual machine currently defined in the AutoSys database. There is no default.

4–2 Reference Guide

delete_machine

Examples

1. To delete a real machine named “socrates,” you would issue the following JIL sub-command:

delete_machine: socrates

2. To delete a component (real) machine named “socrates” from a virtual machine called “ferrari,” while leaving “ferrari” defined, you would issue the following JIL sub-command and attribute:

delete_machine: ferrari machine: socrates

3. To delete the entire virtual machine named “ferrari,” you would issue the following JIL sub-command:

delete_machine: ferrari

Note: Example 3 shown previously deletes only the virtual machine “ferrari.” It does not however delete any real component machines that were defined separately.

JIL Machine Definitions 4–3

factor

factor

Machine Attribute

JIL Syntax

factor: real_number

Description

Indicates the factor to be multiplied by a real machine’s available CPU cycles in order to determine the “relative available CPU cycles.” The real_numb r value is used to determine on which machine a job should be run, when more than one real machine or a virtual is specified with the job’s machine attribute. factor is an indication of a machine’s relative processing power. For example, a small machine can be assigned a value of “0.2,” while a powerful machine can be assigned a value of “1.0.” These values are arbitrary; any range can be used.

e

Real Machine definition

real_number

Where Applicable

Values

Any real number within a user-selected range of values. The examples following show the ranges as 0.0-1.0; however, any reasonable convention can be chosen. The default value is 1.0.

4–4 Reference Guide

factor

Examples

1. Set the factor for a very high-performance real machine, when a scale of 0.0-1.0 is in use, you would enter:

machine: ferrari

factor: .3

:<ferrari=78*[1.00]=78> <alfa_romeo=80*[.80]=64>

factor: 1.0

2. Set the factor for a relatively low-performance real machine, when a scale of 0.0-1.0 is in use, you would enter something similar to the following:

factor: 0.4

3. Assume the following virtual machine has been defined:

insert_machine: italia

factor: 1 machine: alfa_romeo factor: .8 machine: fiat

If a job that is ready to start has the virtual machine “italia” specified in its machine attribute, the Event Processor would perform the necessary calculations to determine which machine on which to run the job, and reflect these calculations in its output log as shown following:

EVENT: STARTJOB JOB: test_mach Checking Machine usages using RSTATD

<fiat=2*[.30]=0.6> [ferrari connected] EVENT: CHANGE_STATUS STATUS: STARTING JOB: test_mach

Note: Checking Machine usages in the previous example, is replaced by NT Performance Method, on NT machines.

The factors weigh each machine to account for variations in processing power. In this example, even though the usage for “ferrari” (or raw available CPU) was less than that of “alfa_romeo,” “ferrari” was still chosen because of the following factor calculation:

( 78 * 1.0 > 80 * 0.8 )

That is, “ferrari” had more relative CPU cycles available. If max_load attributes had been specified for the real machines shown previously, the following scenario would occur.

When a job is to be started on the virtual machine, AutoSys would first determine which of its component real machines had sufficient load units to run the job. If more than one did, AutoSys would query each machine for its available CPU cycles, multiply it by that machine’s factor, and choose the machine with the largest value.

JIL Machine Definitions 4–5

insert_machine

insert_machine

JIL Syntax

■ NSM

The machine type can be specified as either r for real, v for virtual, n for Windows, t for NSM or a Universal Job Management Agent, and c for AutoSys Connect. The component real machines in a virtual machine definition must be all of the same type, for example, all UNIX machines or all Windows machines (not a mix).

JIL Sub-command

Function

Defines a new real or virtual machine.

insert_machine: machine_name

Description

The insert_machine sub-command adds a new machine definition to the AutoSys database for one of the following:

■ Real machine

■ Virtual machine

■ Universal Job Management Agent

■ AutoSys Connect

If the machine being defined is a virtual machine, the insert_machine sub-command is followed by one or more machine attributes that specify real machines.

Note: AutoSys Agent managed machines cannot be part of a virtual machine.

4–6 Reference Guide

insert_machine

A real machine specification can also include a max_load attribute to specify how many load units are allowed on that machine simultaneously, and a factor attribute to specify the relative processing capacity of the machine. Both of these attributes are assigned from an arbitrary, user-defined range of values. max_load is used in combination with the job_load attribute of jobs to limit the load placed on a machine at any one time. When overloading would otherwise occur, jobs are placed “on queue” to run later, at a time when load units become available again.

When more than one machine is specified with the job’s machine attribute, AutoSys must choose on which machine to run the job. In the simplest case, this is done by querying each machine’s available CPU cycles and multiplying it by the factor attribute to calculate the “relative available CPU cycles.” The machine with the largest value will run the job.

A virtual machine specification is comprised of real machines, which are defined using the machine attribute.

Any machine accessible through the TCP/IP protocol can be specified in the machine attribute of a job; it need not be explicitly defined using the insert_machine command. However, any undefined machine will have a default factor of “1.0” and no max_load, meaning that there will be no limit on the job load assigned to it.

Any machine defined in the /etc/hosts file on the machine running the Event Processor can be specified in the machine attribute of a job; it need not be explicitly defined using the insert_machine command. However, any undefined machine will have a default factor of “1.0” and no max_load, meaning that there will be no limit on the job load assigned to it.

For more information, see the Unicenter AutoSys Job Management for Windows User Guide, and the Unicenter AutoSys Job Management for UNIX user Guide.

JIL Machine Definitions 4–7

insert_machine

Values

machine_name The unique name of the machine to be defined. It can be from 1-30 alphanumeric characters, and is terminated with white space; embedded blanks and tabs are illegal.

The default type is UNIX (n or v), if no type is specified.

Examples

1. Define a real UNIX machine named “socrates,” you would specify the following JIL sub-command:

insert_machine: socrates type: r

2. Define a Windows machine named “plato,” you would specify the following JIL sub-command:

insert_machine: aristotle

factor: 1.5

machine: tibet

type: n

insert_machine: plato type: n

3. Define a real UNIX machine named “aristotle” with a factor of 1.5 and capable of handling up to 100 load units, you would specify the following JIL sub-command and attributes:

type: r max_load: 100

4. Define a virtual UNIX machine named “virtual_a” to include two real UNIX machines, named “socrates” and “tibet,” without specifying factors or loads, you would specify the following JIL sub-command and attributes:

insert_machine: virtual_a type: v machine: socrates

5. Define a virtual Windows machine named “virtual_b” to include two Windows machines, named “france” and “italy,” without specifying factors or loads, you would specify the following JIL sub-command and attributes:

insert_machine: virtual_b

machine: france machine: italy

4–8 Reference Guide

insert_machine

Note: In the previously shown definitions of virtual machines, the real machines have no max_load and factor attributes. If the real machines were not previously defined individually, they will be considered identical in terms of factor and load limits. As a result, a job specifying the virtual machine name will be scheduled on whichever of these real machines has the rawest CPU percentage available. Also, if the real machines are defined again outside of a virtual machine, the stand-alone real machine can have different values for max_load and factor. In this case, a job specifying the virtual machine versus a job specifying the stand-alone real machines will be handled differently.

type: v

When a job is to be started on the virtual machine, AutoSys will first determine which of its component real machines has sufficient available load units to run the job. If both do, AutoSys queries each machine for its available CPU cycles, multiplies it by that machine’s factor, and chooses the machine with the largest value.

insert_machine: tibet

type: v

6. Define a virtual UNIX machine named “virtual_c,” to include two real UNIX machines named “ferrari” with a factor of 5.0 and a max_load of 400, and “vw” with a factor of .2 and a max_load of 15, you would specify the following JIL sub-command and attributes:

insert_machine: virtual_c

machine: ferrari max_load: 400 factor: 5.0 machine: vw max_load: 15 factor: .2

Note: In example 6, the two real machines, when specified in a job definition by way of the virtual machine, vary considerably in capacity from a scheduling point of view. However, when these machines are explicitly specified by name in a job definition, the factor and max_load attributes defined here have no bearing; they only have these values when specified by the virtual machine name.

7. First define two real UNIX machines individually named “socrates” and “tibet,” then define a virtual machine named “VIRTUAL_D” to include these real machines, you would specify the following JIL subcommand and attributes:

insert_machine: socrates type: r max_load: 100 factor: 1.0

type: r max_load: 200 factor 1.0 insert_machine: VIRTUAL_D

machine: socrates machine: tibet

JIL Machine Definitions 4–9

insert_machine

8. First define two Windows machines individually named “elm” and “maple”, then define a virtual machine named “trees” to include these real machines, you would specify the following JIL sub-command and attributes:

max_load: 100 factor: 1.0

insert_machine: elm type: n max_load: 100 factor: 1.0 insert_machine: maple type: n max_load: 200 factor 1.0 insert_machine: trees type: n machine: elm max_load: 50 factor: .1 machine: maple

Note: In example 8, the max load and factor units for both the real machines are different in the virtual machine.

1. Define a real machine named “socrates,” you would specify the following JIL sub-command:

insert_machine: socrates type: r

2. Define a real machine named “aristotle” with a factor of 1.5 and capable of handling up to 100 load units, you would specify the following JIL sub-command and attributes:

max_load: 100

insert_machine: virtual_a

Note: In the previously shown definitions of virtual machines, the real machines have no max_load and factor attributes. If the real machines were not previously defined individually, they will be considered identical in terms of factor and load limits. As a result, a job specifying the virtual machine name will be scheduled on whichever of these real machines has the rawest CPU percentage available. Also, if the real machines are defined again outside of a virtual machine, the stand-alone real machine can have different values for max_load and factor. In this case, a job specifying the virtual machine versus a job specifying the stand-alone real machines will be handled differently.

insert_machine: aristotle type: r

factor: 1.5

3. Define a virtual machine named “virtual_a” to include two real machines, named “socrates” and “tibet,” without specifying factors or loads, you would specify the following JIL sub-command and attributes:

type: v machine: socrates machine: tibet

4–10 Reference Guide

insert_machine

4. Define a virtual machine named “virtual_b,” to include two real machines named “ferrari” with a factor of 5.0 and a max_load of 400, and “vw” with a factor of .2 and a max_load of 15, you would specify the following JIL sub-command and attributes:

insert_machine: virtual_b type: v

5. First define two real machines individually named “socrates” and “tibet,” then define a virtual machine named “virtual_d” to include these real machines, you would specify the following JIL subcommand and attributes:

machine: tibet

Note: In example 5, the max load and factor units for both the real machines are different in the virtual machine.

machine: ferrari max_load: 400 factor: 5.0 machine: vw max_load: 15 factor: .2

When a job is to be started on the virtual machine, AutoSys will first determine which of its component real machines has sufficient available load units to run the job. If both do, AutoSys queries each machine for its available CPU cycles, multiplies it by that machine’s factor, and chooses the machine with the largest value.

Note: In example 4, the two real machines, when specified in a job definition by way of the virtual machine, vary considerably in capacity from a scheduling point of view. However, when these machines are explicitly specified by name in a job definition, the factor and max_load attributes defined here have no bearing; they only have these values when specified by the virtual machine name.

insert_machine: socrates type: r max_load: 100 factor: 1.0 insert_machine: tibet type: r max_load: 200 factor 1.0 insert_machine: virtual_d type: v machine: socrates

JIL Machine Definitions 4–11

machine

machine

Machine Attribute

JIL Syntax

machine: machine_name

Description

Specifies a real machine to be included in the virtual machine defined in the insert_machine sub-command.

Note: This machine attribute differs from the machine attribute used in the job definition sub-commands; in the job definitions, this attribute assigns the job to one or more real or virtual machines. However, in a machine definition, it makes a real machine a component of a virtual machine.

The machine type is assumed to be Windows if the virtual machine is type n; it is assumed to be UNIX if the virtual machine is type v. The machine type is assumed to be UNIX if no type is specified.

Where Applicable

The unique name of the real machine to be placed in the virtual machine definition. It can be from 1-30 alphanumeric characters, and is terminated with white space; embedded blanks and tabs are illegal. There is no default.

Machine definition

Values

machine_name

4–12 Reference Guide

machine

Examples

1. Define a virtual machine named “virtual_a,” to include two real UNIX machines named “socrates” and “tibet,” without specifying factors or loads, you would specify the following JIL sub-command and attributes:

insert_machine: virtual_a

Note: In example 1, the two real machines do not have their max_load and factor attributes set. If these two real machines were not previously defined, they will be considered identical in terms of factor and load limits. As a result, a new job that specifies the virtual machine name will be scheduled on the real machine with the rawest CPU percentage available. If these machines are defined again outside of a virtual machine, the stand-alone real machine can have different values for max_load and factor. In this case, a job specifying the virtual machine versus a job specifying the stand-alone real machines will be handled differently.

machine: ferrari max_load: 400 factor: 5.0

machine: socrates machine: tibet

2. Define a virtual machine named “virtual_b,” to include two real Windows machines named “ferrari,” with a factor of 5.0 and a max_load of 400, and “vw” with a factor of .2 and a max_load of 15, you would specify the following JIL sub-command and attributes:

insert_machine: virtual_b type: n

machine: vw max_load: 15 factor: .2

Note: In example 2, these two real machines, when specified using the virtual machine in a job, are considered to vary considerably in capacity from a scheduling point of view. However, when these machines are explicitly specified by their real names in a job definition, the factor and max_load defined here have no bearing; they only have these values when specified by the virtual machine name.

JIL Machine Definitions 4–13

machine

1. Define a virtual machine named “virtual_a,” to include two real machines named “socrates” and “tibet,” without specifying factors or loads, you would specify the following JIL sub-command and attributes:

insert_machine: virtual_a machine: socrates machine: tibet

Note: In example 1, the two real machines do not have their max_load and factor attributes set. If these two real machines were not previously defined, they will be considered identical in terms of factor and load limits. As a result, a new job that specifies the virtual machine name will be scheduled on the real machine with the rawest CPU percentage available. If these machines are defined again outside of a virtual machine, the stand-alone real machine can have different values for max_load and factor. In this case, a job specifying the virtual machine versus a job specifying the stand-alone real machines will be handled differently.

2. Define a virtual machine named “virtual_b,” to include two real machines named “ferrari,” with a factor of 5.0 and a max_load of 400, and “vw” with a factor of .2 and a max_load of 15, you would specify the following JIL sub-command and attributes:

insert_machine: virtual_b machine: ferrari max_load: 400 factor: 5.0 machine: vw max_load: 15 factor: .2

Note: In example 2, these two real machines, when specified using the virtual machine in a job, are considered to vary considerably in capacity from a scheduling point of view. However, when these machines are explicitly specified by their real names in a job definition, the factor and max_load defined here have no bearing; they only have these values when specified by the virtual machine name.

4–14 Reference Guide

max_load

max_load

Note: If job_load is not set, a job will run without checking for load units. If a priority is not set, the priority will default to 0 and the job_load will be ignored.

If more than one machine was set in the job’s machine attribute, the other machines will be checked for available load units. If none of the machines presently has the necessary load units available, the job will be “queued” on all of the specified machines, and will run on the first one with the necessary load units available (due to the completion of another job).

Machine Attribute

JIL Syntax

max_load: load_units

Description

Indicates the maximum load (in load units), which a machine can reasonably handle. Load units are arbitrary values, the range of which is user-defined; the examples following use 1-100, for simplicity.

A max_load is assigned to each machine, indicating its relative processing capacity. For example, a small machine can handle 10 load units, while a powerful machine can handle 100. Likewise, jobs are assigned loads using the job_load attribute, which indicates how much relative processing power they require. When a job’s starting conditions are satisfied, resulting in the job being ready to run, a machine for it to run on needs to be chosen. If the job has the job_load attribute set, the potential machines are checked to determine whether they have enough load units available at the time. If not enough units are available, the job will not be run on that machine.

Note: The job_load attribute has nothing to do with the priority, or ordering, of jobs in a queue. In addition, the job_load attribute controls what machine the job will be run on only when it exceeds the max_load of a machine, thus eliminating that machine.

For more information, see the chapter “JIL/GUI Job Definitions,” in the Unicenter AutoSys Job Management for Windows User Guide, and the Unicenter AutoSys Job Management for UNIX user Guide.

JIL Machine Definitions 4–15

max_load

Where Applicable

Real Machine definition

Values

load_units Any real number within a user-selected range of values. The examples following show the ranges as 1–100, but any reasonable convention can be chosen. Zero and negative numbers cannot be used. There is no default; therefore, if no max_load value is set, the load on the machine will not be limited in any way.

Examples

1. Set the max_load for a very high-performance real machine, when a scale of 1–100 is in use, enter:

max_load: 100

2. Set the max_load for a relatively low-performance real machine, when a scale of 1–100 is in use, you would enter something similar to the following:

max_load: 20

4–16 Reference Guide

type

type

Machine Attribute

JIL Syntax

type: {r | v | n | t | c }

Description

Specifies the type of machine being defined. r specifies a real UNIX machine; v specifies a virtual UNIX machine; n specifies a Windows machine (real or virtual); t specifies a NSM or a Universal Job Management Agent machine, and C specifies AutoSys Connect.

Where Applicable

Machine definition

Values

r, v, or n, t, or c.

JIL Machine Definitions 4–17

Chapter

JIL/GUI Monitor/Report Definitions5

This chapter provides an alphabetical listing of all the JIL sub-commands used to monitor and generate reports on AutoSys jobs and all the JIL and Graphical User Interface (GUI) entered attributes for monitoring and generating reports on AutoSys jobs.

JIL Sub-commands

Certain JIL sub-commands can be used for monitoring and generating reports on AutoSys jobs. When using the AutoSys Monitor/Browser Editor, the same thing is accomplished by using the corresponding fields and buttons in the various dialogs.

Monitor and Report Attributes

There are a number of attributes, which are used to define and describe AutoSys monitors and reports (browsers). Monitor and report attributes can be defined using JIL statements, or they can be defined using the Monitor/Browser Editor. Regardless of method, the attributes are virtually the same.

JIL/GUI Monitor/Report Definitions 5–1

after_time

after_time

Report Attribute

GUI Path

Monitor/Browser Editor: for Browser, Events After Date/Time

Monitor/Browser, Events After Date/Time

JIL Syntax

after_time: date_time

Description

Specifies the date and time for the start of the reporting period, which the report being defined should cover. Only events that occurred after this date and time will be reported on.

Where Applicable

Report definition

5–2 Reference Guide

after_time

Values

JIL: date_time must be specified using the format MM/DD/[YY]YY hh:mm where MM is the month, DD is the day, [YY]YY is the year, hh is the hour in 24-hour format, and mm is the minutes.

You must include the quotes, or an error will result due to the colon in the time.

GUI: Enter the date and time, using the format MM/DD/[YY]YY hh:mm where MM is the month, DD is the day, [YY]YY is the year, hh is the hour in 24-hour format, and mm is the minutes.

You can omit the quotes, since colons are not reserved characters when entered using the Monitor/Browser Editor. The keyword after_time is omitted.

GUI: Enter the date_time, using the format MM/DD/[YY]YY hh:mm where MM is the month, DD is the day, [YY]YY is the year, hh is the hour in 24-hour format, and mm is the minutes.

The default, if the currun attribute is set to “no” is 12:00 midnight on the specified day. If the date is omitted, it defaults to the current day. If the currun attribute is set to “yes,” the after_time attribute is ignored.

Report on all events after 2:00 p.m. on October 1, 1997, enter:

Note: If you enter a two-digit year, AutoSys saves the setting to the database as a four-digit year. If you enter 79 or less, AutoSys prepends 20, and, if you enter 80 or greater, AutoSys prepends 19.

Example

after_time: "10/01/1997 14:00"

JIL/GUI Monitor/Report Definitions 5–3

alarm

alarm

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, Alarms

Monitor/Browser, Alarms

JIL Syntax

alarm: toggle

Where Applicable

Description

Specifies whether alarms should be tracked in the monitor or report being defined. Alarms can be tracked at the same time as other events. If the all_events attribute is specified, all alarms will be tracked, regardless of the alarm attribute’s setting.

Monitor definition

Report definition

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate yes; to change your selection, deselect the check box. The default value is 0 for no.

GUI: Click the button in to indicate yes; to change your selection, click the button again to indicate no. The default value is 0 for no.

5–4 Reference Guide

alarm

Example

Set the monitor or report to track alarms, enter:

alarm: y

JIL/GUI Monitor/Report Definitions 5–5

alarm_verif

alarm_verif

Monitor Attribute

GUI Path

Monitor/Browser Editor: for Monitor, Alarm Verification Required

Monitor/Browser, Verification Required for Alarms

JIL Syntax

alarm_verif: toggle

Description

Specifies whether alarms should continue to notify the operations staff until there is a response. When the monitor is running, the 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. It provides an accounting of the events that were responded to, and when that occurred.

If a response is not given within 20 seconds, the sound clip is repeated. Therefore, if someone momentarily steps out of the room and an alarm occurs, the monitor keeps playing the sound clip (if specified) until someone responds.

Values

Where Applicable

Monitor definition

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate yes; to change your selection, deselect the check box.

5–6 Reference Guide

alarm_verif

GUI: Click the button to indicate yes; to change your selection, click the button again to indicate no.

The default value is 0 for no.

Example

Set the monitor to require operator verification of alarms, enter:

alarm_verif: y

JIL/GUI Monitor/Report Definitions 5–7

all_events

all_events

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, All Events

Monitor/Browser, ALL EVENTS

JIL Syntax

all_events: toggle

Description

Note: If you wish to monitor all events for all jobs, you should display the event processor log time in real time, using the following command instead of running a monitor:

Specifies whether all events should be tracked for the monitor or report being defined. This 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. This includes job status events, alarms, and manually generated events, such as starting a job.

If set to “no,” the other event selection attributes, including the alarm attribute, are used to select the events to be tracked.

autosyslog -e

Note: You should do this because running a monitor adds another connection to the database and establishes another process, which is continually polling the database. This will have a significant impact on system performance. Furthermore, the information logged by the event processor contains more diagnostic information than a monitor does.

5–8 Reference Guide

all_events

Where Applicable

Monitor definition

Report definition

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate yes; to change your selection, deselect the check box.

GUI: Click the button to indicate yes; to change your selection, click the button again to indicate no.

The default value is 0 for no.

Example

Set the monitor or report to track all events, whether they are AutoSys- or manually-generated job status changes, enter:

all_events: y

JIL/GUI Monitor/Report Definitions 5–9

all_status

all_status

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, All Change Status Events

Monitor/Browser, ALL Job Status Event

JIL Syntax

all_status: toggle

Description

Specifies whether all job status events should be tracked by the monitor or report being defined. Job status events occur whenever a job’s status changes. If this attribute is set to “yes,” all of the individual job status events, which have their own attributes, as well as a few AutoSys-internal job status events, will be tracked.

Report definition

Alarms can be tracked in addition to job status events. If the all_events attribute is set to “yes,” the all_status attribute is ignored.

Where Applicable

Monitor definition

5–10 Reference Guide

all_status

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate yes; to change your selection, deselect the check box.

GUI: Click the button to indicate yes; to change your selection, click the button again to indicate no.

The default value is 0 for no.

Example

Set the monitor or report to track all job status events, enter:

all_status: y

JIL/GUI Monitor/Report Definitions 5–11

currun

currun

Report Attribute

GUI Path

Monitor/Browser Editor: for Browser, Current Run Only

Monitor/Browser, Current Run Only

JIL Syntax

currun: toggle

Description

Specifies whether only the events in the current or most recent execution of the specified jobs will be reported. (Jobs are specified using the job_name attribute, or in the Job Selection Criteria area of the Monitor/ Browser Editor.)

Using this attribute is useful for getting a sense of what is happening currently. For example, you could select the job status restart event using the Restart checkbox in the Monitor/Browser Editor, or you could specify the restart attribute with JIL. Then, you would turn off Job Filtering, by selecting all jobs, and set the currun attribute to yes to see all of the jobs that have been automatically restarted by AutoSys in their current or latest run.

Specifies whether only the events in the current or most recent execution of the specified jobs will be reported. (Jobs are specified using the job_name attribute, or in the Job Name field of the GUI, in combination with the job_filter attribute or the Job Filter field in the GUI.)

Using this attribute is useful for getting a sense of what is happening currently. For example, you could select the job status restart event using the Restart checkbox in the GUI, or you could specify the restart attribute with JIL. Then, you would turn off Job Filtering, by selecting all jobs, and set the currun attribute to yes to see all of the jobs that have been automatically restarted by AutoSys in their current or latest run.

If this attribute is set to no, the after_time attribute must be specified.

5–12 Reference Guide

currun

Where Applicable

JIL: toggle can be y or 1 for yes; or n or 0 for no.

Report definition

Values

GUI: Toggle the button off to indicate no; to change your selection, click the button again to indicate yes.

GUI: Deselect the Current Run Only check box to indicate no; select the check box to indicate yes.

The default value is 1 for yes.

Example

Set the monitor or report to report only on events in the current or most recent run of the specified jobs, enter:

currun: y

JIL/GUI Monitor/Report Definitions 5–13

delete_monbro

delete_monbro

JIL Sub-command

GUI Path

Monitor/Browser Editor, File menu, Delete

Monitor/Browser, Delete

Function

Deletes a monitor or report (browser) from the AutoSys database.

The delete_monbro sub-command deletes the specified monitor or report (browser) from the AutoSys database.

Must be a monitor or report currently defined in the AutoSys database.

Example

JIL Syntax

delete_monbro: monbro_name

Description

Values

monbro_name

There is no default.

Delete the monitor called “track_alarm,” specify the following JIL sub-command:

delete_monbro: track_alarm

5–14 Reference Guide

failure

failure

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, Job Change Status Events: Failure

Monitor/Browser, Failure

JIL Syntax

failure: toggle

Where Applicable

Values

Description

Specifies whether the job status event generated when a job changes to the failure state should be tracked by the monitor or report being defined. If either of the all_events or all_status attributes are set to “yes,” the failure attribute is ignored. Alarms can be tracked in addition to job status events.

Monitor definition

Report definition

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate yes; to change your selection, deselect the check box.

GUI: Click the button to indicate yes; to change your selection, click the button again to indicate no.

The default value is 0 for no.

JIL/GUI Monitor/Report Definitions 5–15

failure

Example

Set the monitor or report to track jobs changing to the failure state, enter:

failure: y

5–16 Reference Guide

insert_monbro

insert_monbro

JIL Sub-command

JIL Syntax

insert_monbro: monbro_name

In order to use a monitor or report, it must first be defined, then it must be run; defining it alone has no effect. In order to define a monitor or report, several attributes must also be specified. These attributes are discussed individually in this chapter.

■ mode attribute—For monitor or report

■ SUCCESS

Function

Defines a new monitor or report (browser).

Description

The insert_monbro sub-command defines a new monitor or report (browser). Monitors are used to monitor events within AutoSys and to watch for specific occurrences, such as alarms. Reports are used to filter and report on events within AutoSys.

For all monitors and reports, the following specifications are required:

■ Monitor or report name

■ Event selection—This can be one or a combination of the following status events or alarms:

■ RUNNING

■ FAILURE

JIL/GUI Monitor/Report Definitions 5–17

insert_monbro

■ TERMINATED

■ STARTING

■ ALL_EVENTS (selects all events)

■ job_name attribute—Is required if a single box or job is to be selected.

Values

■ RESTART

■ ALL_STATUS (selects all statuses)

■ alarm attribute

In addition, the following specifications can be required for the following reasons:

■ For all reports, the time criteria may also need to be specified. For example, the currun attribute, which specifies that the current or latest run of each job is to be considered, will be used by default if no other selection is made.

For more information, see the chapter “Monitoring and Reporting Jobs,” in the Unicenter AutoSys Job Management for Windows User Guide, and the Unicenter AutoSys Job Management for UNIX User Guide.

monbro_name The unique name of the monitor or report to be defined. It can be from 1-30 alphanumeric characters and is terminated with white space; embedded blanks and tabs are illegal. There is no default.

5–18 Reference Guide

insert_monbro

Examples

job_filter: a /* the default */

insert_monbro: alarm_monitor

1. Define a report named “success_report” that will browse all jobs for success in the “current” or most recent execution of the job, specify the following JIL sub-command and attributes:

insert_monbro: success_report mode: b /* "browser" can also be specified */ success: y

currun: y /* the default */

2. Define a monitor named “alarm_monitor” that will watch for alarms on all jobs and sound an audible alarm, specify the following JIL sub-command and attributes:

mode: m /* "monitor" can also be specified */ alarm: y job_filter: a /* the default */ sound: y

JIL/GUI Monitor/Report Definitions 5–19

job_filter

job_filter

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, Job Selection Criteria: Job Filter

Monitor/Browser, Job Filter

JIL Syntax

Specifies which jobs are to be monitored or reported on, for the monitor or report being defined. 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 filtering), track a single box with the jobs it contains, or track a single job.

job_filter: type

Description

If either of the latter two settings are selected, the name of the job to be tracked is required. This name can be specified using the job_name attribute or the Job Name field in the GUI.

If either of the latter two settings are selected, the name of the job to be tracked is required. This name can be specified using the job_name attribute or the Job Name field in the Monitor/Browser Editor Save or Save As dialogs.

Where Applicable

Monitor definition

Report definition

5–20 Reference Guide

job_filter

Values

JIL: type can be any one of the following:

a

Box with its jobs.

Single job.

All jobs (no filtering).

b

j

GUI: Select one of the following radio buttons: All Jobs, Jobs in Box named, or Single Job named. To change your selection, select a different radio button.

GUI: Select one of the following radio buttons: ALL Jobs, Box with Its Jobs, or Single Job. To change your selection, select a different radio button.

The default is a (ALL Jobs).

Example

Set the monitor or report to only track events in the box specified in the job_name attribute, enter:

job_filter: b

JIL/GUI Monitor/Report Definitions 5–21

job_name

job_name

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, Job Filter name field

Monitor/Browser, Job Name

JIL Syntax

job_name: name

Description

Specifies the box or job for which events are to be monitored or reported on, for the monitor or report being defined. The events to be tracked are determined by the combination of the various event filters, the job filter, and the job name. The job_name attribute is required if the job_filter attribute is set to a single job or to a box and its jobs; otherwise, it is ignored.

Where Applicable

Monitor definition

Report definition

Values

JIL: name must be an existing job.

GUI: Enter the name of an existing job.

There is no default.

5–22 Reference Guide

job_name

Example

Set the monitor or report to only track events in the box called “EOD_Box”, enter:

job_name: EOD_Box

JIL/GUI Monitor/Report Definitions 5–23

mode

mode

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, Monitor or Browser

Monitor/Browser, Mode

JIL Syntax

mode: type

Description

Specifies whether a monitor or report (browser) is to be defined.

Where Applicable

Monitor definition

Report definition

Values

JIL: type can be one of the following:

m or monitor for a monitor

b or browser for a report (browser)

GUI: Select either Monitor or Browser from the pop-up list.

In the Monitor/Browser Editor, the default setting is Monitor, and in JIL there is no default.

5–24 Reference Guide

mode

GUI: Click the appropriate Monitor or Browser radio button; to change your selection, click the other button.

There is no default.

Example

Set the definition to apply to a report, enter:

mode: b

JIL/GUI Monitor/Report Definitions 5–25

monbro_name (GUI only)

monbro_name (GUI only)

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, File menu, Save or Save As dialog: Name

Monitor/Browser, Name

JIL Syntax

None.

Description

Specifies the name of the monitor or report being defined, by way of the Monitor/Browser Editor. When JIL is used, this attribute is included with the JIL sub-command, for example: insert_monbro: monbro_name. This attribute must be unique for monitors and reports within an instance of AutoSys, since it is the primary identifier of the monitor or report. The name cannot be changed once the monitor or report has been defined, although the monitor or report can be deleted and re-defined.

Specifies the name of the monitor or report being defined, by way of the GUI. When JIL is used, this attribute is included with the JIL sub-command, for example: insert_monbro: monbro_name. This attribute must be unique for monitors and reports within an instance of AutoSys, since it is the primary identifier of the monitor or report. The name cannot be changed once the monitor or report has been defined, although the monitor or report can be deleted and redefined.

Where Applicable

Monitor or Report definitions, using the Monitor/Browser Editor only.

Monitor or Report definitions, using the GUI only.

5–26 Reference Guide

monbro_name (GUI only)

Values

GUI: Enter the new monitor or report name in the Save or Save As dialog. The name can be up to 30 alphanumeric characters, including the underscore (_) character. Embedded blanks and tabs are illegal.

GUI: Enter the monitor or report name. The name can be up to 30 alphanumeric characters, including the underscore (_) character. Embedded blanks and tabs are illegal.

There is no default setting; this field is always required.

JIL/GUI Monitor/Report Definitions 5–27

restart

restart

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, Job Change Status Events: Restart

Monitor/Browser, ReStart

JIL Syntax

restart: toggle

Description

Monitor definition

Specifies whether the job status event generated when a job changes to the restart state should be tracked by the monitor or report being defined. If either of the all_events or all_status attributes are set to “yes,” the restart attribute is ignored. Alarms can be tracked in addition to job status events.

Where Applicable

Report definition

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Click the button into indicate yes; to change your selection, click the button again to indicate no.

GUI: Select the check box to indicate yes; to change your selection, deselect the check box.

The default value is 0 for no.

5–28 Reference Guide

restart

Example

Set the monitor or report to track jobs changing to the restart state, enter:

restart: y

JIL/GUI Monitor/Report Definitions 5–29

running

running

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, Job Change Status Events: Running

Monitor/Browser, Running

JIL Syntax

running: toggle

Description

Where Applicable

Specifies whether the job status event generated when a job changes to the running state should be tracked by the monitor or report being defined.

If either of the all_events or all_status attributes are set to “yes,” the running attribute is ignored. Alarms can be tracked in addition to job status events.

Monitor definition

Report definition

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate yes; to change your selection, deselect the check box.

GUI: Click the button into indicate yes; to change your selection, click the button again to indicate no.

The default value is 0 for no.

5–30 Reference Guide

running

Example

Set the monitor or report to track jobs changing to the running state, enter:

running: y

JIL/GUI Monitor/Report Definitions 5–31

sound

sound

Monitor Attribute

GUI Path

Monitor/Browser Editor: for Monitor, Sound

Monitor/Browser, Sound

JIL Syntax

sound: toggle

Description

Specifies whether the appropriate sound clip for the specified events should be played when a tracked event is seen by the monitor being defined.

If the workstation running the monitor has sound capabilities, AutoSys will use them to announce the events as they occur. If there is no sound capability, this attribute is ignored. The announced message is pieced together from pre-recorded sound clips.

Note: You should use sound for monitoring AutoSys, especially alarms. It frees you from needing to examine output files to see if there are any problems. Some users have plugged their machine into the P.A. system, or other external amplifiers.

For more information, see the chapter “AutoSys Administrator,” in the Unicenter AutoSys Job Management for Windows User Guide, or the chapter “AutoSys Commands,” in this guide.

Where Applicable

Monitor definition

5–32 Reference Guide

sound

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate yes; to change your selection, deselect the check box.

GUI: Click the button into indicate yes; to change your selection, click the button again to indicate no.

The default value is 0 for no.

Example

Set the monitor to play the appropriate sound clip for a specified event, enter:

sound: y

JIL/GUI Monitor/Report Definitions 5–33

starting

starting

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, Job Change Status Events: Starting

Monitor/Browser, Starting

JIL Syntax

starting: toggle

Description

Specifies whether the job status event generated when a job changes to the starting state should be tracked by the monitor or report being defined.

If either of the all_events or all_status attributes are set to “yes,” the starting attribute is ignored. Alarms can be tracked in addition to job status events.

Where Applicable

Monitor definition

Report definition

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate yes; to change your selection, deselect the check box.

GUI: Click the button to indicate yes; to change your selection, click the button again to indicate no.

The default value is 0 for no.

5–34 Reference Guide

starting

Example

Set the monitor or report to track jobs changing to the starting state, enter:

starting: y

JIL/GUI Monitor/Report Definitions 5–35

success

success

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, Job Change Status Event: Success

Monitor/Browser, Success

JIL Syntax

success: toggle

Description

Specifies whether the job status event generated when a job changes to the success state should be tracked by the monitor or report being defined.

If either of the all_events or all_status attributes are set to “yes,” the success attribute is ignored. Alarms can be tracked in addition to job status events.

Where Applicable

Monitor definition

Report definition

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate yes; to change your selection, deselect the check box.

GUI: Click the button to indicate yes; to change your selection, click the button again to indicate no.

The default value is 0 for no.

5–36 Reference Guide

success

Example

Set the monitor or report to track jobs changing to the success state, enter:

success: y

JIL/GUI Monitor/Report Definitions 5–37

terminated

terminated

Monitor/Report Attribute

GUI Path

Monitor/Browser Editor, Job Change Status Events: Terminated

Monitor/Browser, Terminated

JIL Syntax

terminated: toggle

Description

Specifies whether the job status event generated when a job changes to the terminated state should be tracked by the monitor or report being defined.

If either of the all_events or all_status attributes are set to “yes,” the terminated attribute is ignored. Alarms can be tracked in addition to job status events.

Where Applicable

Monitor definition

Report definition

Values

JIL: toggle can be y or 1 for yes; or n or 0 for no.

GUI: Select the check box to indicate yes; to change your selection, deselect the check box.

GUI: Click the button to indicate yes; to change your selection, click the button again to indicate no.

The default value is 0 for no.

5–38 Reference Guide

terminated

Example

Set the monitor or report to track jobs changing to the terminated state, enter:

terminated: y

JIL/GUI Monitor/Report Definitions 5–39

update_monbro

update_monbro

JIL Sub-command

GUI Path

Monitor/Browser Editor, File menu, Save

Monitor/Browser, Save

Function

Updates an existing monitor or report (browser).

JIL Syntax

update_monbro: monbro_name

Description

The update_monbro sub-command updates an existing monitor or report (browser). Monitors are used to monitor events within AutoSys and to watch for specific occurrences, such as alarms. Reports are used to filter and report on events within AutoSys.

Any attributes in the existing definition which are not explicitly replaced by specifying the attribute in the update_monbro input will retain their original settings. If many attributes need to be “unset,” use the alternative method of deleting and redefining the monitor or report definition, because it would be more efficient.

For more information, see the chapter “Monitoring and Reporting Jobs,” in the Unicenter AutoSys Job Management for Windows User Guide, and the Unicenter AutoSys Job Management for UNIX User Guide.

Values

monbro_name The unique name of the monitor or report to be modified. There is no default.

5–40 Reference Guide

update_monbro

Example

Change a monitor called “alarm_monitor” so that it will indicate all terminations, in addition to the already-specified alarms, specify the following JIL sub-command and attribute:

update_monbro: alarm_monitor terminated: y

JIL/GUI Monitor/Report Definitions 5–41

Appendix

A System States

Events The following is the list of events that AutoSys processes. Some of these events are generated internally by AutoSys, while some only occur when sent manually using the sendevent command. In effect, manual events are runtime commands for the event processor. In the listing following, each event’s internal code assignment is provided next to the event in parenthesis. This code number is used for viewing the event in the database event table.

For more information, see the chapter “AutoSys Commands,” in this guide.

ALARM (106)

An alarm is an informational event only; it invokes no action on its own. The type of alarm is further qualified by the value of the alarm, described later in this appendix. An alarm is generally an internal event, but an alarm can also be sent manually if an application wants to alert an operator.

CHANGE_PRIORITY (120)

Changes the priority of a job. If the job is in the QUE_WAIT state, it changes it immediately, and possibly starts the job. If the job is not yet in the QUE_WAIT state, it changes the priority for the next run of the job only. A permanent change of priority can be done by editing the job definition.

System States A–1

Events

CHANGE_STATUS (101)

Changes the value of the status for a specific job. When the event processor processes this event, it initiates any actions that are dependent upon this status of this job. The values of status are listed later in this appendix.

CHECK_HEARTBEAT (116)

Instructs the event processor to check all jobs that have specified a heartbeat interval to see if any are missing. If so, a MISSING_HEARTBEAT alarm will be sent. If the event processor is configured to do so, it will perform this check automatically.

CHK_BOX_TERM (118)

This is an internally generated event that instructs the event processor to check if a box job has run for more than its Maximum Run Time (max_run_time) value.

CHK_MAX_ALARM (114)

This is an internally generated event, instructing the event processor to check if a job has run for more than its Maximum Run Time value.

CHK_RUN_WINDOW (122)

This is a future event set to run at the end of a job’s run window, to see if the job has run or not.

COMMENT (117)

For information purposes only. This event can be associated with a job and as a result, is displayed on AutoSys reports (autorep). It is a method for generating comments at runtime and have them be associated with a specific run of a job.

DELETEJOB (119)

Tells AutoSys to delete this job. If the job is a box, it deletes everything within the box.

A–2 Reference Guide

Events

EXTERNAL_DEPENDENCY (127)

Sent from an issuing AutoSys instance to a different, receiving AutoSys instance to signal that a cross-instance dependency has been dispatched.

FORCE_STARTJOB (108)

Event to start a job, regardless of any conditions on this job. This event is never generated by AutoSys, and should be used only in the event of system problems. Using this event, it is possible to start the same job twice, and as a result, have two instances of the job running at the same time. For this reason, we recommend that this command be used only with extreme caution.

HEARTBEAT (115)

The event sent from the Remote Agent posting a heartbeat for a given job. This event is internally generated.

JOB_ON_ICE (110)

Event that instructs the event processor to place a job ON_ICE. If the job is in the STARTING or RUNNING state, it will not place the job ON_ICE. This event is manually generated.

JOB_OFF_ICE (111)

Event that instructs the event processor to take a job OFF_ICE. If the job is in a RUNNING box, it will attempt to start it, conditions permitting. This event is manually generated.

JOB_ON_HOLD (112)

Event that instructs the event processor to place a job ON_HOLD. If the job is in the STARTING or RUNNING state, it will not place the job ON_HOLD. This event is manually generated.

System States A–3

Events

JOB_OFF_HOLD (113)

Event to take the job OFF_HOLD. The starting of the job will continue as it was before it was placed ON_HOLD. This is the method for taking a job OFF_HOLD when using the AutoHold feature.

KILLJOB (105)

Instructs the event processor to kill a specific job. If the specified job is a box, it will change the box status to TERMINATED, and, if so configured, kill the jobs within it. This event is manually generated.

Notes:

The KillSignals parameter of the KILLJOB event specifies a comma-separated list of signals to send to a job whenever a KILLJOB event is sent. If the job to be killed is running on a Windows machine, this list is ignored and the job is simply terminated.

Windows does not support the concept of process groups. If the job that was launched was a *.exe, KILLJOB will kill the process specified in the command definition. If the job being run is not a *.exe, for example, *.bat, *.cmd, or *.com, AutoSys uses CMD.EXE to launch the job; KILLJOB will kill only the CMD.EXE process. The Job Status will be set according to the return code of the killed CMD.EXE process. This status can be any one of the following: SUCCESS, FAILURE, or TERMINATED. Any processes that were launched by user applications or batch (*.bat) files will not be killed.

For more information, see the chapter “AutoSys Commands,” in this guide.

REFRESH_BROKER (129)

This is an internally generated event by the Event Processor when the AutoSys Broker starts up. It triggers all external dependencies to be sent by the event processor to the AutoSys Broker.

A–4 Reference Guide

Events

RESEND_EXTERNAL_STATUS (128)

This event is sent when a CHANGE_STATUS event is sent to another instance and the receiving instance is unavailable. When this happens, the receiving Event Processor will reschedule the event and try to send it five minutes later; an INSTANCE_UNAVAILABLE alarm is also generated.

SET_GLOBAL (125)

Sets an AutoSys global variable. This event is sent with a high priority so that the event processor will process the variable before it is referenced by any jobs at runtime.

SEND_SIGNAL(126)

Sends a Unix signal to a running AutoSys job.

STARTJOB (107)

Event to start a job, if and only if the starting conditions are satisfied, and if it is not already running. This is the recommended way to start a job manually.

STOP_DEMON (109)

Manually generated event telling the event processor to shut down. This is used to halt the event demon.

System States A–5

Status

Status

Every job has a status, or current state, associated with it; these are described in this section. AutoSys moves jobs through these states as it processes the events. Also provided are the internal codes for status, for use when accessing the job_status table in the database.

ACTIVATED (9)

Top-level box that this job is in is now in the RUNNING state. This status does not have an event associated with it. It is an internal state only.

FAILURE (5)

For command jobs, the command exited with an exit code greater than the maximum success value specified for this job. If a box, it means that the failure conditions for the box evaluated to true.

INACTIVE (8)

Job is inactive; it has no status, by(or in) itself. For example, a newly created job, which has not run yet is inactive.

ON_HOLD (11)

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

ON_ICE (7)

Job is removed from all conditions and logic, but is still defined to AutoSys. Operationally, it is like deactivating the job.

A–6 Reference Guide

Status

QUE_WAIT (12)

The job can logically start, has a nonzero priority, and the machines on which it can start do not have enough available load units. When the required load units become available, AutoSys will start the job. To remove a job from QUE_WAIT, use:

sendevent -E CHANGE_PRIORITY -J job_name -q 0

RESTART (10)

Job was unable to start due to hardware or application problems, and has been scheduled to restart.

RUNNING (1)

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

STARTING (3)

Event Processor has initiated the start procedure with the Remote Agent. The job is in the process of “coming up.” This status is only for command and file watcher jobs, not box jobs.

SUCCESS (4)

Job exited and is considered by AutoSys to be successful, as determined by the exit code for a command job, and the success conditions for a box job.

TERMINATED (6)

Job was terminated.

System States A–7

Alarms

Alarms

The following is a list of the alarms that may be generated by AutoSys.

ALREADY_RUNNING (528)

An attempt was made to start a job that was already running. The Remote Agent did not start the job.

AUTO_PING (526)

The autoping -M -A command cannot connect to a client machine. The name of the machine is listed.

CHASE (514)

The chase command has found a problem with a job that is supposedly running. The job and the problem are listed.

DATABASE_COMM (516)

The Remote Agent had trouble sending an event to the database. The job probably ran successfully. Inspect the Remote Agent Log file to determine what happened.

DB_PROBLEM (523)

There is a problem with one of the AutoSys databases, such as a lack of free space. This alarm can trigger a user-specified notification procedure.

DB_ROLLOVER (519)

AutoSys has rolled over from Dual-Server to Single-Server Mode. This alarm can trigger a user-specified notification procedure.

A–8 Reference Guide

Alarms

DUPLICATE_EVENT (524)

Duplicate events have been received in the Event Server. Typically, this means that two event processors are up and running, although duplicate events can also be caused by Event Server configuration errors.

EP_HIGH_AVAIL (522)

Can mean that the Third Machine for resolving contentions between two event processors cannot be reached, that the event processor is shutting down, or that there are other event processor take over problems. This alarm can trigger a user-specified notification procedure.

EP_ROLLOVER (520)

The Shadow event processor is taking over processing. This alarm can trigger a user-specified notification procedure.

EP_SHUTDOWN (521)

The event processor is shutting down. This may be due to a normal shutdown (SEND_EVENT triggered by sendevent -E STOP_DEMON), or due to an error condition. This alarm can trigger a user-specified notification procedure.

EVENT_HDLR_ERROR (507)

The event processor had an error while processing an event. The job associated with that event should be inspected to see if manual intervention is required.

EVENT_QUE_ERROR (508)

An event was not able to be marked as processed. This is usually due to a problem with the Event Server. Contact Computer Associates Technical Support.

EXTERN_DEPS_ERROR (529)

The AutoSys Broker is unable to send external dependencies to the remote node. The alarm text message identifies the falling remote node.

System States A–9

Alarms

FORKFAIL (501)

The Remote Agent was unable to start the user command because it was unable to get a process slot on the UNIX machine. When this happens, AutoSys will automatically attempt a RESTART. This alarm can occur only when a job is running on a UNIX machine.

INSTANCE_UNAVAILABLE (525)

When different AutoSys instances communicate with each other, this alarm is generated when the Event Server of the receiving AutoSys instance cannot be reached. The Event Server is probably down.

JOBFAILURE (503)

A job has failed or was terminated. Its status is now FAILURE or TERMINATED.

JOBNOT_ONICEHOLD (509)

To place a job ON_HOLD or ON_ICE, a JOB_ON_HOLD or JOB_ON_ICE event is sent. If the job cannot be placed ON_HOLD or ON_ICE (for example, if it is already running), this alarm is sent to alert the user that this event could not be performed.

A–10 Reference Guide

Alarms

MAX_RETRYS (505)

AutoSys will continue attempting to restart a job if there are system problems, or if the job is configured for application restarts (n_retrys). There is a limit to how many times it will attempt a restart, as defined in the AutoSys Administrator (using the Max Restart Trys setting). When that limit has been reached, this alarm is sent to alert operators that AutoSys has given up trying to start it. When the problem is fixed, the job must be started manually.

AutoSys will continue attempting to restart a job if there are system problems, or if the job is configured for application restarts (n_retrys). There is a limit to how many times it will attempt a restart, as defined in the configuration file (using MaxRestartTrys). When that limit has been reached, this alarm is sent to alert operators that AutoSys has given up trying to start it. When the problem is fixed, the job must be started manually.

MAXRUNALARM (510)

The job has been running for a time greater than that defined in the Maximum Run time alarm (max_run_alarm) field in the Job Editor for that job. The job may continue to run; this event generates a warning alarm.

MINRUNALARM (502)

The job has completed running in less time than that defined in the Minimum Run time alarm (min_run_alarm) field Job Editor for that job.

MISSING_HEARTBEAT (513)

A job has not sent a HEARTBEAT within the interval specified for that job. The operator should inspect the job to see why.

MULTIPLE_EP_SHUTDOWN (530)

An event processor is shutting down when the AutoSys 4.0 is configured to run multiple event processors. This may be due to an error condition, or and abnormal exit.

System States A–11

Alarms

RESOURCE (512)

A resource, such as file space, needed for this job was not available. Specific information about the problem is in the comment associated with this alarm. If AutoSys encounters a resource problem, it will attempt to restart the job after a suitable delay.

STARTJOBFAIL (506)

AutoSys was unable to start the job. This is generally due to communication problems with the remote machine. AutoSys will attempt to restart the job.

VERSION_MISMATCH (518)

Generated by the Remote Agent when the calling routine, for example: Event Processor, chase, clean_files, autoping, and so forth, is at a different version number than the Remote Agent. Inspect the Remote Agent Log file for the exact version mismatch. The proper Remote Agent version should be installed.

A–12 Reference Guide

AutoSys Exit Codes

AutoSys Exit Codes

When you use the autosyslog -J command to display the Remote Agent log file for a specified job, you may see an entry containing one of the following exit codes. If the exit code contains two numbers in parentheses, for example: (0 1), the first number is the UNIX signal, and the second number is the exit code. If a job is killed or terminated, the exit code remains at zero, which is what it was set to when the job started.

Exit Codes Meaning

15 (15 0) The job was terminated by a UNIX kill –15

101 (0 101) A CHANGE_STATUS was done on the job, for example: possibly the job was changed to a TERMINATED or FAILURE status.

121 (0 121) Cannot open std_in_file. File doesn't exist or is inaccessible; check permissions.

122 (0 122) Cannot open std_out_file. Output directory doesn't exist or is inaccessible; check permissions; check that the file system is not full.

123 (0 123) Cannot open std_err_file. Output directory doesn't exist or is inaccessible; check permissions; check that the file system is not full.

127 (0 127) Directory that contains the executable not in the command search PATH.

System States A–13

AutoSys Exit Codes

Exit Codes Meaning

256 (0 1) Unable to execute the command.

There are many possible causes:

■ The command or file to be executed does not exist.

■ The file to be executed is not executable. Check permissions.

■ The file to be executed is in a directory that is not accessible:

1. Check permissions (ls -ld).

2. If the directory is NFS-mounted, verify that the mount exists.

If a Job Environment File is being used, the PATH variable may be incorrect:

1. The file to be executed may not be in a directory that is specified in PATH.

2. The PATH command may use an undefined variable (which would translate as blank space, and thus the PATH command would terminate before all the directories are defined to it).

3. The job environment file may use non-Bourne shell commands, for example: "alias," and the expected settings (or aliases) may not exist.

■ Wrong command options, for example: date –JASD can generate this return code.

A–14 Reference Guide

AutoSys Exit Codes

Exit Codes Meaning

512 (0 2) Wrong command options, for example: awk 'junk.’

-655 SYSTEM_ERROR STARTJOB failures because auto_remote will not start.

-656 NO_EXIT_CODE exit_code field in database is initialized to this.

-657 PROCESS_MIA Set by a chase-generated FAILURE event, for example: chase cannot find the process.

System States A–15

Appendix

B Database Tables and Codes

This chapter lists the database tables and views, and it lists the event and alarm codes used in these tables.

AutoSys Tables and Views

Because AutoSys uses a relational database, you can query the database to supply custom reports and information. All of the DDL (Data Definition Language) for the database is in the following directory:

%AUTOSYS%\DBOBJ\STEP3

View definitions are in the following directory:

%AUTOSYS%\DBOBJ\STEP4

Because AutoSys uses a relational database, you can query the database to supply custom reports and information. All of the DDL (Data Definition Language) for the database is in the following directory:

$AUTOSYS/dbobj

The table definitions are in file named table_name.tbl, and the view definitions are in the view_name.view file.

The tables and views are described in the following sections.

WARNING! Changing information in AutoSys tables by using SQL commands may cause your system to fail.

Database Tables and Codes B–1

AutoSys Tables and Views

alarmode

This table stores configuration information, such as autotrack level and remote authentication level, used by the event processor.

WARNING! Do not change this table or you may crash the AutoSys installation.

alarm

This table stores all the alarms. Each alarm has a unique eoid (event object ID), which is the reference to the event that created the alarm.

audit_info

This table stores most of the autotrack utility information. You can archive this table by using the -l option with the archive_events command. The audit_msg table contains additional information.

audit_msg

This table stores additional autotrack utility information. You can archive this table by using the -l option with the archive_events command. The audit_info and audit_msg tables combined contain all of the autotrack utility information.

avg_job_runs

Each job has a row in this table, with the field named joid (job object ID) being the unique key. Each row of the table contains a job’s calculated average runtime, based on the data in the job_runs table. In addition, each row contains a field named num_runs, which indicates how many runs were used to calculate the average runtime.

calendar

The calendar table contains a list of the dates for each calendar. Multiple calendars may be defined, and they are referenced by unique names.

B–2 Reference Guide

AutoSys Tables and Views

chase

This table stores chase utility information. Information remains in the chase table only temporarily.

cred

This table stores in encrypted format the Windows user passwords entered through the autosys_secure utility.

WARNING! You can change the information in this table only by using AutoSys utilities. If you use SQL commands to make any changes, jobs may fail.

event

Each AutoSys event is a row in the event table. When an event is processed, it is moved through the different processing states by changing the field que_status. Each event has an identifier called its eoid, which is unique across all instances of AutoSys. This ensures that events can never be lost, confused, or overwritten when you run multiple instances of AutoSys. This table can be archived using the -n option with the archive_events command.

WARNING! You can change the information in this table only by using AutoSys utilities. If you use SQL commands to make any changes, your jobs and events will not run.

event0

This table stores unprocessed events for the event processor. Each unprocessed event has a unique eoid. The information remains in the event0 table temporarily.

event2

This table stores duplicate events, which each have a unique eoid. Under normal conditions the event2 table is empty.

Database Tables and Codes B–3

AutoSys Tables and Views

eventvu

This view of the event table presents the information in that table in a more readable form. Most notably, all the events, alarms, and statuses are displayed in an easily interpreted textual format.

ext_job

This table stores the status of external job dependencies. If jobs on one instance of AutoSys have dependencies on jobs that run on another instance of AutoSys, this table specifies the status of the referenced jobs that are running on the other AutoSys instance.

glob

Each global variable is a row in the glob table, with the field named glo_name being the unique key.

intcodes

This table stores all the numeric codes—alarm, event, and status codes—used in the other tables. These other tables reference the intcodes table.

job

Each job is a row in the job table, with the field named joid (job object ID) being the unique key. Most of the parameters for all the job definitions are contained in this table. The job2 table contains the remaining parameters.

WARNING! You can change the information in this table only by using AutoSys utilities. If you use SQL commands to make any changes, your jobs and events will not run.

job2

This table is an extension of the job table. The parameters for the job definitions that are not in the job table are contained in this table. The job and job2 tables

B–4 Reference Guide

combined contain all of the parameters for all of the job definitions.

AutoSys Tables and Views

job_cond

Each atomic condition for a job is a row in this table.

job_runs

Each job run is a row in this table, with the fields named joid (job object ID), run_num (run number), and ntry (number of tries to run the job) being the unique keys. Each row of the table contains a job’s start time, end time, runtime (in seconds), completion status, and exit code. The Event Processor updates this table. The table can be archived using the archive_events command with the -j option.

job_status

The current run information for every job is stored in this table. It is also identified by the key field named joid. Information such as the current status, run number, last start time, last end time, and exit code are also in this table.

jobst

This view contains the information from both the job and job_status tables.

keymaster

This table stores all of the license keys and the information associated with them.

WARNING! Do not use SQL commands to change information in this table or AutoSys will not run, and do not use SQL commands to delete license keys from this table, unless instructed to do so by Computer Associates Technical Support.

last_Eoid_counter

This table stores the number of the last event; the last Eoid used by the event processor.

Database Tables and Codes B–5

AutoSys Tables and Views

machine

This table stores the machine definitions entered through JIL by using the insert_machine command.

monbro

Each monitor or report (browser) definition is a row in this table. All monitors and reports are contained in this table.

msg_ack

This table is used when the Verification Required for Alarms feature is set for a monitor. This table contains the alarm ID that is responded to (eoid), who responded to the alarm, what time it was first reported, what time it was acknowledged, and a short comment from the operator.

next_oid

This table stores all of the oid (other ID) counters except the eoid used by the event processor (stored in the last_Eoid_counter table).

next_run_num

This table stores the next run number counter.

overjob

This table stores the attributes for job overrides and the run number for which the overrides were applied. The indices to this table are joid and over_num, where joid is the unique job ID and over_num is the number of the override for that job. The value of over_num is assigned at the time an override is defined, and it is stored in the job_status table until runtime.

req_job

B–6 Reference Guide

This table stores the jobs on one instance of AutoSys that are referenced in the starting dependencies of jobs running on another instance of AutoSys.

AutoSys Tables and Views

restart

This table stores jobs that are in RESTART state. The information remains in the restart table temporarily.

svarchive_tbl

This table stores CPU utilization, I/O read, I/O write, and average memory usage information on a per-job-run basis. This information is gathered by ServerVision and can be referenced to generate reports for capacity planning and process auditing (charge back). ServerVision requires this table.

svarchive_vw

This view of the svarchive_tbl table hides the structure of the information in that table because the definition of the svarchive_tbl will change. ServerVision requires this table.

timezones

This table stores time zone information. If you create your own time zones with the autotimezone utility, that information is also stored in the timezones table.

wait_que

This table stores information about jobs in the QUE_WAIT state. The information remains in the wait_que table temporarily.

Database Tables and Codes B–7

AutoSys Database Numeric Codes

AutoSys Database Numeric Codes

AutoSys events and alarms have unique numeric codes that the database tables use to represent each event and alarm. The following sections list the numeric codes and the associated event or alarm.

Event Codes

Event codes are used in the event table. The following table contains the numeric codes and associated event types.

For descriptions of the events, see the appendix “System States,” in this guide.

Numeric Code Event Type

101 CHANGE_STATUS

103 CHK_N_START

105 KILLJOB

106 ALARM

107 STARTJOB

108 FORCE_STARTJOB

109 STOP_DEMON

110 JOB_ON_ICE

111 JOB_OFF_ICE

112 JOB_ON_HOLD

113 JOB_OFF_HOLD

114 CHK_MAX_ALARM

115 HEARTBEAT

116 CHECK_HEARTBEAT

117 COMMENT

B–8 Reference Guide

118 CHK_BOX_TERM

Event Status Codes

Numeric Code Event Type

119 DELETEJOB

120 CHANGE_PRIORITY

121 QUE_RECOVERY

122 CHK_RUN_WINDOW

125 SET_GLOBAL

126 SEND_SIGNAL

127 EXTERNAL_DEPENDENCY

128 RESEND_EXTERNAL_STATUS

129 REFRESH_BROKER

Event Status Codes

Event status codes are used in the chase, event, job_runs, job_status, and restart tables. The following table contains the numeric codes and associated event status types.

For descriptions of the events, see the appendix “System States,” in this guide.

Numeric Codes Event Status

1 RUNNING

3 STARTING

4 SUCCESS

5 FAILURE

6 TERMINATED

7 ON_ICE

8 INACTIVE

9 ACTIVATED

Database Tables and Codes B–9

10 RESTART

Event que_status Codes

Numeric Codes Event Status

11 ON_HOLD

12 QUE_WAIT

Event que_status Codes

Event que_status codes are used in the event table. The following table contains the numeric codes and associated event que_status types.

0 unprocessed

1 processing

2 processed

3 processed w/errors

4 unsent event

Alarm Codes

Alarm codes are used in the alarm and event tables. The following table contains the numeric codes and associated alarm types.

Numeric Code Associated Alarm

501 FORKFAIL

502 MINRUNALARM

503 JOBFAILURE

505 MAX_RETRYS

506 STARTJOBFAIL

B–10 Reference Guide

507 EVENT_HDLR_ERROR

508 EVENT_QUE_ERROR

Alarm Codes

Numeric Code Associated Alarm

509 JOBNOT_ONICEHOLD

510 MAXRUNALARM

512 RESOURCE

513 MISSING_HEARTBEAT

514 CHASE

516 DATABASE_COMM

518 VERSION_MISMATCH

519 DB_ROLLOVER

520 EP_ROLLOVER

521 EP_SHUTDOWN

522 EP_HIGH_AVAIL

523 DB_PROBLEM

524 DUPLICATE_EVENT

525 INSTANCE_UNAVAILABLE

526 AUTO_PING

528 (UNIX only) ALREADY_RUNNING

529 EXTER_DEPS_ERROR

For descriptions of the alarms, see the appendix “System States,” in this guide.

Database Tables and Codes B–11

Alarm State Codes

Alarm State Codes

Alarm state codes are used in the alarm table. The following table contains the numeric codes and associated alarm state types.

Numeric Code Alarm State

43 open

44 acknowledged

45 closed

B–12 Reference Guide

Appendix

C AutoSys API

AutoSys provides a C Programming Language API that enables you to integrate events and alarms into your processing environment. This API is comprised of two functions: get_auto_event, which gives you direct programmatic access to all events in the system and autoheartbeat, which generates heartbeats. With autoheartbeat, you can modify a program to run under AutoSys control that will send “heartbeats” to indicate the program is still running. This enables AutoSys to monitor the execution of the program and notify you if the application becomes inactive.

This chapter describes how to integrate AutoSys events and alarms into the user’s processing environment by way of the AutoSys application program API.

AutoSys API C–1

Accessing Events from the Database

Accessing Events from the Database

All the files you need to access events in the database, including an example file, are located in the %AUTOSYS%\code directory.

These are the files:

■ autosys_api.h

■ libauto.a

■ test_api

■ autosys_api.lib

■ testheart.c

■ testheart.mak (Makefile (vc++))

■ test_api.c

■ test_api.mak (Makefile (vc++))

All the files you need to access events in the database, including an example file, are located in the $AUTOSYS/code directory.

These are the files:

■ autosys_api.h

■ libauto.a

■ test_api

■ test_api.c

■ test_api.m (makefile)

■ heartbeat.c

■ heartbeat.sh

The AutoSys API reads the event information directly from the AutoSys database. As a result, if the event processor is lost due to hardware problems, the events will still be available to the API. Furthermore, you can control the API so that it will attempt to reconnect to the database if the database is unavailable.

C–2 Reference Guide

Accessing Events from the Database

This is the prototype for the call to get an AutoSys event:

get_auto_event()

This is the syntax for the call to get an AutoSys event:

get_auto_event()

AutoSys API C–3

Accessing Events from the Database

get_auto_event ( )

Name

get_auto_event API to get AutoSys events.

Prototype

int get_auto_event(struct event_api *, int);

Synopsis

#include <autosys_api.h> int get_auto_event(event, polling_freq) struct event_api *event; int polling_freq;

Description

get_auto_event() loads the structure pointed to by * with the full event entry. The events are returned in the order in which they are posted to the database. Events can be reported to the API before they are processed by the event processor.

The event_api structure is defined in the header file autosys_api.h, like:

struct event_api { oid joid; char roid[EOIDLEN+1]; char job_name[NAMELEN+1]; char box_name[NAMELEN+1]; char eventtxt[NAMELEN+1]; char statustxt[NAMELEN+1]; char alarmtxt[NAMELEN+1]; char event_time[DATETIMELEN+1]; int exit_code; int run_num; int ntry; char machine[NAMELEN+1]; char comment[256]; };

C–4 Reference Guide

Accessing Events from the Database

Sample get_auto_event(&event, POLL_FREQ)

If a field is not used for a given event, it will be defined as a NULLterminated string. The only field guaranteed to be present is eventtxt.

The value POLL_FREQ instructs the API how often to inspect the database for a new event.

After finding an event, get_auto_event() returns to the calling program.

Return Values

Get_auto_event() returns 0 if it got an event, DB_DEAD if the database dropped the connection or is unavailable, and -1 if it failed. The ability to reconnect to the database is controlled by the calling program. get_auto_event() will itself attempt to reconnect one time if an existing connection is dropped. If it is unable to establish a connection, it will return with DB_DEAD.

Example programs in %AUTOSYS%\code\test_api.c

Get_auto_event() returns 0 if it got an event, DB_DEAD if the database dropped the connection or is unavailable, and -1 if it failed. The ability to reconnect to the database is controlled by the calling program. get_auto_event() will itself attempt to reconnect one time if an existing connection is dropped. If it is unable to establish a connection, it will return with DB_DEAD.

Example programs in $AUTOSYS/code/test_api.c

AutoSys API C–5

Sending Heartbeats

Sending Heartbeats

A function call can be embedded in an application program that executes under AutoSys control to periodically send a message to the Event processor signaling that the application is still processing normally. If the Event processor does not receive a message within the time interval specified in the HeartBeat Interval field on the AutoSys Administrator Event Processor screen, an error condition is detected, and then the condition can be handled appropriately. This is the function, which is located in the autosys_api.h file:

autoheartbeat()

A function call can be embedded in an application program that executes under AutoSys control to periodically send a message to the event processor signaling that the application is still processing normally. If the event processor does not receive a message within the time interval specified in the AutoSys configuration file, an error condition is detected, and then the condition can be handled appropriately. This is the function, which is located in the AUTOSYS/code/heartbeat.c file:

autoheartbeat()

C–6 Reference Guide

Sending Heartbeats

autoheartbeat ( )

Name

autoheartbeat API to send heartbeats to the event processor.

Prototype

int autoheartbeat(void)

Synopsis

int autoheartbeat()

Description

autoheartbeat() sets an event for the Remote Agent, which sends it on to the event processor.

autoheartbeat() sends a signal (SIGUSR2) to the Remote Agent, which sends it on to the event processor.

For more information, see the chapter “AutoSys Administrator,” in the Unicenter AutoSys Job Management for Windows User Guide, or the chapter “Configuring AutoSys,” in the Unicenter AutoSys Job Management for UNIX User Guide.

Return Values

autoheartbeat() returns 1 if it was able to send the signal successfully, 0 if not.

For example programs, see:

%AUTOSYS%\code\testheart.c file

autoheartbeat() returns 1 if it was able to send the signal successfully, 0 if not. Alternatively, a heartbeat can be issued from a Bourne shell script by executing the script contained in the following file:

$AUTOSYS/code/heartbeat.sh

AutoSys API C–7

Index

A

Accessing Events from the Database, C-2

Alarm Codes, B-10

Alarm State Codes, B-12

alarm_if_fail, 3-4

Alarms, A-8

Alarms ALREADY_RUNNING (528), A-8 AUTO_PING (526), A-8 CHASE (514), A-8 DATABASE_COMM (516), A-8 DB_PROBLEM (523), A-8 DB_ROLLOVER (519), A-8 DUPLICATE_EVENT (524), A-9 EP_HIGH_AVAIL (522), A-9 EP_ROLLOVER (520), A-9 EP_SHUTDOWN (521), A-9 EVENT_HDLR_ERROR (507), A-9 EVENT_QUE_ERROR (508), A-9 EXTERN_DEPS_ERROR (529), A-9 FORKFAIL (501), A-10 INSTANCE_UNAVAILABLE (525), A-10 JOBFAILURE (503), A-10 JOBNOT_ONICEHOLD (509), A-10 MAX_RETRYS (505), A-11 MAXRUNALARM (510), A-11 MINRUNALARM (502), A-11

MISSING_HEARTBEAT (513), A-11 MULTIPLE_EP_SHUTDOWN (530), A-11 RESOURCE (512), A-12 STARTJOBFAIL (506), A-12 VERSION_MISMATCH (518), A-12

archive_events, 2-3

Assumptions, 1-1

auto_delete, 3-6

auto_hold, 3-8

autocal, 2-7

autocal_asc, 2-9

autocons, 2-12

autoflags, 2-14

autoping, 2-16

autorep, 2-19

autosc, 2-30

autostatus, 2-31

AutoSys Database Numeric Codes, B-8 Database Numeric Codes

Event Codes, B-8 Exit Codes, A-13 Functional Listing of Commands, 2-2 Tables and Views, B-1 Tables and Views

alamode, B-2 alarm, B-2 audit_info, B-2

Index–1

audit_msg, B-2 avg_job_runs, B-2 calendar, B-2 chase, B-3 cred, B-3 event, B-3 event0, B-3 event2, B-3 eventvu, B-4 ext_job, B-4 glob, B-4 intcodes, B-4 job, B-4 job_cond, B-5 job_runs, B-5 job_status, B-5 job2, B-4 jobst, B-5 keymaster, B-5 last_Eoid_counter, B-5 machine, B-6 monbro, B-6 msg_ack, B-6 next_oid, B-6 next_run_num, B-6 overjob, B-6 req_job, B-6 restart, B-7 svarchive_tbl, B-7 svarchive_vw, B-7 timezones, B-7 wait_que, B-7

autosys_secure, 2-38

autosyslog, 2-35

autotimezone, 2-49

autotrack, 2-54

avg_runtime, 3-10

B

box_failure, 3-12

box_name, 3-14

box_success, 3-16

box_terminator, 3-18

C

chase, 2-61

chk_auto_up, 2-65

chk_cond (SP), 2-68

chk_files, 3-20

clean_files, 2-70

command, 3-24

condition, 3-30

cron2jil, 2-72

D

date_conditions, 3-38

days_of_week, 3-40

dbstatistics, 2-74

delete_box, 3-42

delete_job, 3-43

delete_machine, 4-2

description, 3-45

Documentation notational conventions, 1-2

E

Event REFRESH_BROKER (129), A-4

Event que_status Codes, B-10

Index–2 User Guide

Event Status Codes, B-9

eventor, 2-76

Events, A-1

Events ALARM(106), A-1 CHANGE_PRIORITY (120), A-1 CHANGE_STATUS (101), A-2 CHECK_HEARTBEAT (116), A-2 CHK_BOX_TERM (118), A-2 CHK_MAX_ALARM (114), A-2 CHK_RUN_WINDOW (122), A-2 COMMENT (117), A-2 DELETEJOB (119), A-2 EXTERNAL_DEPENDENCY (127), A-3 FORCE_STARTJOB (108), A-3 HEARTBEAT (115), A-3 JOB_OFF_HOLD (113), A-4 JOB_OFF_ICE (111), A-3 JOB_ON_HOLD (112), A-3 JOB_ON_ICE (110), A-3 KILLJOB (105), A-4 RESEND_EXTERNAL_STATUS (128), A-5 SEND_SIGNAL (126), A-5 SET_GLOBAL (125), A-5 STARTJOB (107), A-5 STOP_DEMON (109), A-5

exclude_calendar, 3-47

F

factor, 4-4

G

gatekeeper, 2-80

Gui monbro_name, 5-26

GUI job_name, 3-56

H

heartbeat_interval, 3-49

I

insert_job, 3-51

insert_machine, 4-6

J

jil, 2-82

JIL avg_runtime, 3-10 Machine Attributes, 4-1 Sub Commands, 3-2 Sub-commands, 4-1

Job Attributes, 3-3

job_depends, 2-87

job_name, 3-56

job_terminator, 3-57

job_type, 3-59

L

load_job, 3-54

M

machine, 3-61, 4-12

max_exit_success, 3-64

max_load, 4-15

max_run_alarm, 3-66

Index–3

min_run_alarm, 3-68

monbro, 2-94

Monitor/Report Attributes, 5-1 Attributes

after-time, 5-2 alarm, 5-4 alarm_verif, 5-6 all_events, 5-8 all_status, 5-10 currun, 5-12 delete_monbro, 5-14 failure, 5-15 insert_monbro, 5-17 job_filter, 5-20 job_name, 5-22 mode, 5-24 monbro_name, 5-26 restart, 5-28 running, 5-30 sound, 5-32 starting, 5-34 success, 5-36 terminated, 5-38 update_monbro, 5-40

JIL Sub-commands, 5-1

N

n_retrys, 3-70

O

override_job, 3-73

owner, 3-76

P

permission, 3-81

priority, 3-86

profile, 3-89

R

record_sounds, 2-97

Related Publications, 1-3

run_calendar, 3-93

run_window, 3-95

S

sendevent, 2-99

sendevent (SP), 2-111

Sending Heartbeats, C-6

start_mins, 3-98

start_times, 3-100

Status, A-6

Status ACTIVATED (9), A-6 FAILURE (5), A-6 INACTIVE(8), A-6 ON_HOLD (11), A-6 ON_ICE (7), A-6 QUE_WAIT (12), A-7 RESTART (10), A-7 RUNNING (1), A-7 STARTING (3), A-7 SUCCESS (4), A-7 TERMINATED (6), A-7

std_err_file, 3-102

std_in_file, 3-106

Index–4 User Guide

std_out_file, 3-108

T

term_run_time, 3-111

timezone, 3-113

type, 4-17

U

update_job, 3-117

W

watch_file, 3-119

watch_file_min_size, 3-122

watch_interval, 3-124

X

xql, 2-114

Index–5