ActiveBatch V6 Reference Manual · ActiveBatch® Reference Manual 6

ActiveBatch® Reference Manual Version 6

The Cross-Platform Enterprise Job Management and Scheduling System

Advanced Systems Concepts, Inc. http://www.advsyscon.com

V6 SP2: January 2008 First Printing V6: April 2007 First Printing V5: January 2005 First Printing V4: September 2002

First Printing V3: January 1999

The information in this document is subject to change without notice and should not be construed as a commitment by Advanced Systems Concepts, Inc. (ASCI). ASCI assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under license, and may only be used or copied in accordance with the terms of such license. The terms and conditions of the license are furnished with the product in both hard copy as well as electronic form.

ASCI logo, ActiveBatch and XLNT are registered trademarks of Advanced Systems Concepts, Inc. ASCI, ActiveBatch logo and XLNT logo are trademarks of Advanced Systems Concepts, Inc. Microsoft, Windows, Windows NT and Systems Management Server are trademarks of Microsoft Corporation. Oracle is a registered trademark of the Oracle Corporation. Intel is a registered trademark of the Intel Corporation. Crystal Reports is a trademark of Business Intelligence. Other marks, as indicated, are owned by their respective companies.

Copyright © 1999-2008, Advanced Systems Concepts, Inc., Parsippany, New Jersey, 07054 All Rights Reserved. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording or by any information storage and retrieval system, without the written permission of Advanced Systems Concepts, Inc.

1

Table of Contents

1 INTRODUCTION ............................................................................................................................................................ 15

1.1 PRODUCT COMPONENTS ............................................................................................................................................. 16

2 ACTIVEBATCH TERMS AND CONCEPTS .............................................................................................................. 17

2.1 ARCHITECTURE ........................................................................................................................................................... 18 2.2 NAMESPACE ................................................................................................................................................................ 19 2.3 OBJECTS ..................................................................................................................................................................... 19

2.3.1 Reference ............................................................................................................................................................ 19 2.3.2 Queue ................................................................................................................................................................. 19 2.3.3 Plan .................................................................................................................................................................... 20 2.3.4 Job ...................................................................................................................................................................... 20 2.3.5 Variables and Properties ................................................................................................................................... 21 2.3.6 Triggers .............................................................................................................................................................. 21

2.3.6.1 Schedule ........................................................................................................................................................................... 21 2.3.6.2 Events .............................................................................................................................................................................. 21

2.3.7 Constraints ......................................................................................................................................................... 22 2.3.7.1 Calendar ........................................................................................................................................................................... 22 2.3.7.2 Job/Plan Instance ............................................................................................................................................................. 22 2.3.7.3 File ................................................................................................................................................................................... 22 2.3.7.4 Time ................................................................................................................................................................................. 22 2.3.7.5 Resource .......................................................................................................................................................................... 22 2.3.7.6 Variable ........................................................................................................................................................................... 22

2.3.8 Alert Object ........................................................................................................................................................ 22 2.3.9 User Account Object .......................................................................................................................................... 22

3 USING ACTIVEBATCH WITH ABATADMIN .......................................................................................................... 25

3.1 ABATADMIN TERMS AND CONCEPTS ........................................................................................................................ 26 3.1.1 Bars, Panes and Views ....................................................................................................................................... 29 3.1.2 Menu Operations ................................................................................................................................................ 30 3.1.3 Object Selection ................................................................................................................................................. 30 3.1.4 ActiveBatch Icons ............................................................................................................................................... 30 3.1.5 ActiveBatch Hot-Keys ........................................................................................................................................ 32

3.1.5.1 Global Keys (applies to all views) ................................................................................................................................... 32 3.1.5.2 Operators/Designers Tree (a.k.a. Navigation) .................................................................................................................. 32 3.1.5.3 Report Lists (Instances / Daily Activity / Browse) .......................................................................................................... 32

3.1.6 ActiveBatch Error Messages .............................................................................................................................. 33 3.1.7 Property Dialogs ................................................................................................................................................ 34

3.2 NAVIGATION ............................................................................................................................................................... 35 3.2.1 Object/View Navigation ..................................................................................................................................... 35

3.2.1.1 Daily Activity .................................................................................................................................................................. 36 3.2.1.2 Gantt Chart ...................................................................................................................................................................... 37 3.2.1.3 Runbook ........................................................................................................................................................................... 38 3.2.1.4 System View .................................................................................................................................................................... 39 3.2.1.5 Queue Counters View ...................................................................................................................................................... 40 3.2.1.6 Instance View .................................................................................................................................................................. 41 3.2.1.7 Design View .................................................................................................................................................................... 42

3.2.2 Administration .................................................................................................................................................... 43 3.2.2.1 Navigation – Administration ............................................................................................................................................ 43 3.2.2.2 ActiveBatch Services ....................................................................................................................................................... 43 3.2.2.3 Active Directory .............................................................................................................................................................. 43 3.2.2.4 High Availability Manager .............................................................................................................................................. 43 3.2.2.5 Policies and Configuration ............................................................................................................................................... 44

3.3 REPORTING FACILITY ................................................................................................................................................. 45 3.4 SLIDER NOTIFICATION ................................................................................................................................................ 46

ActiveBatch® Reference Manual

2

3.5 TOOLS ......................................................................................................................................................................... 47 3.5.1 Refresh and Refresh Pane .................................................................................................................................. 47 3.5.2 WMI Updates ..................................................................................................................................................... 47 3.5.3 Reset ................................................................................................................................................................... 47 3.5.4 Search ................................................................................................................................................................ 47 3.5.5 Options ............................................................................................................................................................... 49

3.5.5.1 Options – General ............................................................................................................................................................ 49 3.5.5.2 Options – Runbook .......................................................................................................................................................... 51 3.5.5.3 Options – Gantt ................................................................................................................................................................ 52 3.5.5.4 Options – System View ................................................................................................................................................... 53 3.5.5.5 Options – Print ................................................................................................................................................................. 54 3.5.5.6 Options – Notification...................................................................................................................................................... 55 3.5.5.7 Options – User Role Panes .............................................................................................................................................. 56

3.6 HELP ........................................................................................................................................................................... 57 3.7 ABATADMIN AND WMI ............................................................................................................................................ 58

4 GETTING STARTED WITH ACTIVEBATCH .......................................................................................................... 59

4.1 STARTING THE ACTIVEBATCH ADMIN APPLICATION .................................................................................................. 59 4.2 LEAVING ACTIVEBATCH ADMIN APPLICATION .......................................................................................................... 60 4.3 JOB SCHEDULER ......................................................................................................................................................... 61

4.3.1 Connecting to a Job Scheduler .......................................................................................................................... 61 4.3.1.1 Basic Connection ............................................................................................................................................................. 61 4.3.1.2 Advanced Connection ...................................................................................................................................................... 62 4.3.1.3 Firewall Connection ......................................................................................................................................................... 63

4.3.2 Disconnecting from a Job Scheduler ................................................................................................................. 64 4.3.3 Job Scheduler Licensing .................................................................................................................................... 64 4.3.4 Find Objects ....................................................................................................................................................... 65

4.3.4.1 Search .............................................................................................................................................................................. 65 4.3.4.2 Object in Tree .................................................................................................................................................................. 65 4.3.4.3 View Property Sheet of Object ........................................................................................................................................ 65

4.3.5 Job Scheduler Properties ................................................................................................................................... 66 4.3.5.1 Variables .......................................................................................................................................................................... 67 4.3.5.2 Alerts ............................................................................................................................................................................... 68 4.3.5.3 Counters ........................................................................................................................................................................... 69 4.3.5.4 Audits .............................................................................................................................................................................. 70 4.3.5.5 History ............................................................................................................................................................................. 71 4.3.5.6 Security ............................................................................................................................................................................ 72

5 DESIGNING THE ACTIVEBATCH SYSTEM ........................................................................................................... 73

5.1 JOB SCHEDULER NAMESPACE ..................................................................................................................................... 73 5.2 COMMON OBJECT PROPERTIES ................................................................................................................................... 74 5.3 QUEUES ...................................................................................................................................................................... 76

5.3.1 Creating an Execution Queue ............................................................................................................................ 76 5.3.1.1 Queue – General .............................................................................................................................................................. 77 5.3.1.2 Queue – Properties ........................................................................................................................................................... 78 5.3.1.3 Execution Queue – Properties .......................................................................................................................................... 79 5.3.1.4 Execution Queue – Characteristics .................................................................................................................................. 81 5.3.1.5 Queue – Alerts ................................................................................................................................................................. 82 5.3.1.6 Queue – Counters............................................................................................................................................................. 84 5.3.1.7 Queue – Audits ................................................................................................................................................................ 85 5.3.1.8 Queue – Security .............................................................................................................................................................. 86 5.3.1.9 Add Security Dialog ........................................................................................................................................................ 88 5.3.1.10 Add User Characteristic (Queue) ..................................................................................................................................... 89

5.3.2 Creating a Generic Queue ................................................................................................................................. 90 5.3.3 Associating/Disassociating a Member Execution Queue ................................................................................... 92 5.3.4 Modifying a Queue ............................................................................................................................................. 92 5.3.5 Built-in Queues .................................................................................................................................................. 93 5.3.6 VariableQueue ................................................................................................................................................... 93

3

5.3.7 OnDemand Queue .............................................................................................................................................. 93 5.4 JOBS AND PLANS ......................................................................................................................................................... 95

5.4.1 What is a Job? .................................................................................................................................................... 95 5.4.2 What is a Plan? .................................................................................................................................................. 95

5.5 PLAN DEFINITION ....................................................................................................................................................... 96 5.5.1 Plan – General ................................................................................................................................................... 96 5.5.2 Plan – Variables................................................................................................................................................. 98 5.5.3 Plan – Triggers/Scheduling ................................................................................................................................ 99 5.5.4 Plan – Triggers/Event ...................................................................................................................................... 101 5.5.5 Plan – Constraints/General ............................................................................................................................. 102 5.5.6 Plan – Constraints/Date-Time ......................................................................................................................... 103 5.5.7 Plan – Execution/General ................................................................................................................................ 104 5.5.8 Plan – Monitoring/Run-Time ........................................................................................................................... 105 5.5.9 Plan – Alerts .................................................................................................................................................... 107 5.5.10 Plan – Completion – Properties ....................................................................................................................... 108 5.5.11 Plan – Completion – Completion Rule ............................................................................................................. 110 5.5.12 Plan – Completion Rule ................................................................................................................................... 111 5.5.13 Plan – Completion – Completion Triggers ...................................................................................................... 112 5.5.14 Plan – Counters ............................................................................................................................................... 113 5.5.15 Plan – Audits .................................................................................................................................................... 114 5.5.16 Plan – History .................................................................................................................................................. 115 5.5.17 Plan – Security ................................................................................................................................................. 116 5.5.18 Plan – Policies ................................................................................................................................................. 118

5.5.18.1 Defaults .......................................................................................................................................................................... 118 5.5.18.2 Auditing ......................................................................................................................................................................... 119

5.5.19 Plans: How Best to Organize your Objects ...................................................................................................... 124 5.5.20 Publishing a Plan ............................................................................................................................................. 127

5.6 JOB DEFINITION ........................................................................................................................................................ 128 5.6.1 Batch Job Security Requirements ..................................................................................................................... 128 5.6.2 Batch Job Files and Run-Time Considerations ................................................................................................ 130 5.6.3 Job Types ......................................................................................................................................................... 132

5.6.3.1 E-Mail ............................................................................................................................................................................ 132 5.6.3.2 FileSystem ..................................................................................................................................................................... 132 5.6.3.3 FTP/SFTP ...................................................................................................................................................................... 132 5.6.3.4 Job Library ..................................................................................................................................................................... 132 5.6.3.5 Process ........................................................................................................................................................................... 132 5.6.3.6 Script .............................................................................................................................................................................. 132

5.6.4 Creating a Job .................................................................................................................................................. 133 5.6.4.1 Job – General ................................................................................................................................................................. 134 5.6.4.2 Job – Job Properties ....................................................................................................................................................... 136

5.6.4.2.1 Process Job Properties .............................................................................................................................................. 136 5.6.4.2.2 E-Mail Job Properties .............................................................................................................................................. 140 5.6.4.2.3 FTP/SFTP Job Properties ......................................................................................................................................... 141 5.6.4.2.4 FileSystem Job Properties ........................................................................................................................................ 142 5.6.4.2.5 Jobs Library Properties ............................................................................................................................................ 144 5.6.4.2.6 Script Job Properties ................................................................................................................................................ 145

5.6.4.3 Job – Generic Queue Properties ..................................................................................................................................... 147 5.6.4.3.1 Job – Machine Characteristics ................................................................................................................................. 148 5.6.4.3.2 Job – User Characteristics ........................................................................................................................................ 150

5.6.4.4 Job – Variables .............................................................................................................................................................. 151 5.6.4.5 Job – Triggers/Scheduling ............................................................................................................................................. 154 5.6.4.6 Job – Triggers/Event ...................................................................................................................................................... 156 5.6.4.7 Job – Constraints/General .............................................................................................................................................. 157 5.6.4.8 Job – Constraints/Date-Time ......................................................................................................................................... 159 5.6.4.9 Job – Execution/General ................................................................................................................................................ 161 5.6.4.10 Job – Execution/User Credentials .................................................................................................................................. 163 5.6.4.11 Job – Execution/Logging ............................................................................................................................................... 165 5.6.4.12 Job – Monitoring/Run-Time .......................................................................................................................................... 167 5.6.4.13 Job – Monitoring/CPU-Time ......................................................................................................................................... 169


4

5.6.4.14 Job – Alerts .................................................................................................................................................................... 171 5.6.4.15 Job – Completion/Properties .......................................................................................................................................... 172 5.6.4.16 Job – Completion/Completion Triggers ......................................................................................................................... 174 5.6.4.17 Job – Counters ............................................................................................................................................................... 175 5.6.4.18 Job – Audits ................................................................................................................................................................... 176 5.6.4.19 Job – History .................................................................................................................................................................. 177 5.6.4.20 Job – Security ................................................................................................................................................................ 178 5.6.4.21 Job – Add Security Dialog ............................................................................................................................................. 180

5.7 JOBS LIBRARY .......................................................................................................................................................... 181 5.7.1 Job Type ........................................................................................................................................................... 181 5.7.2 Job Type Properties ......................................................................................................................................... 183 5.7.3 Job Step ............................................................................................................................................................ 191 5.7.4 Context Variables ............................................................................................................................................. 192

5.8 MODIFYING/VIEWING PLAN AND JOB PROPERTIES ................................................................................................... 193 5.9 PLAN AND JOB INSTANCE ......................................................................................................................................... 194

5.9.1 View Batch Run ................................................................................................................................................ 195 5.9.1.1 List View ....................................................................................................................................................................... 195 5.9.1.2 Gantt View ..................................................................................................................................................................... 196 5.9.1.3 Graphical View .............................................................................................................................................................. 197

5.9.2 Instance ............................................................................................................................................................ 198 5.9.2.1 History ........................................................................................................................................................................... 198 5.9.2.2 Variables ........................................................................................................................................................................ 200 5.9.2.3 Audits ............................................................................................................................................................................ 203 5.9.2.4 Log ................................................................................................................................................................................. 204 5.9.2.5 Properties ....................................................................................................................................................................... 205

5.10 REFERENCE OBJECTS ................................................................................................................................................ 206 5.10.1 Reference – General Properties ....................................................................................................................... 208 5.10.2 Reference – Properties ..................................................................................................................................... 209

5.11 PLAN AND JOB OPERATIONS FOR DESIGNERS ........................................................................................................... 210 5.11.1 Drag and Drop ................................................................................................................................................. 210 5.11.2 Show Dependent Objects .................................................................................................................................. 211 5.11.3 Copy/Paste Object ............................................................................................................................................ 212 5.11.4 Cut/Paste Object .............................................................................................................................................. 212 5.11.5 Delete a Plan or Job ........................................................................................................................................ 212 5.11.6 Hold/ Release a Plan or Job ............................................................................................................................ 213 5.11.7 Export/Import Objects ...................................................................................................................................... 214

5.11.7.1 Export ............................................................................................................................................................................ 214 5.11.7.2 Import ............................................................................................................................................................................ 215

5.11.8 Create Trigger Script ....................................................................................................................................... 215 5.11.9 Take Ownership ............................................................................................................................................... 215 5.11.10 Revision History ............................................................................................................................................... 216

5.12 VARIABLES ............................................................................................................................................................... 218 5.12.1 Definition of Variables ..................................................................................................................................... 218 5.12.2 Use of Variables in Jobs and Plans ................................................................................................................. 218 5.12.3 Active Variable Data Sources .......................................................................................................................... 219 5.12.4 Built-in ActiveBatch Variables ......................................................................................................................... 220 5.12.5 Advanced Variable Usage ................................................................................................................................ 222

5.13 TRIGGERS ................................................................................................................................................................. 223 5.13.1 Schedule Definition .......................................................................................................................................... 223

5.13.1.1 Schedule – General ........................................................................................................................................................ 225 5.13.1.2 Schedule – Time Specification ...................................................................................................................................... 226 5.13.1.3 Schedule – Day Specification/General ........................................................................................................................... 227 5.13.1.4 Schedule – Exact Dates .................................................................................................................................................. 229 5.13.1.5 Schedule – Range Specification ..................................................................................................................................... 230 5.13.1.6 Schedule – Audits .......................................................................................................................................................... 231 5.13.1.7 Schedule – Security ....................................................................................................................................................... 232 5.13.1.8 Copying a Schedule ....................................................................................................................................................... 234 5.13.1.9 Editing a Schedule ......................................................................................................................................................... 234

5

5.13.1.10 Deleting a Schedule ....................................................................................................................................................... 234 5.13.1.11 Associate/Disassociate ................................................................................................................................................... 235

5.13.2 Event Triggers .................................................................................................................................................. 236 5.13.2.1 Event Privileges ............................................................................................................................................................. 239 5.13.2.2 Advanced Event Settings ............................................................................................................................................... 240

5.13.3 Plan/Job Completion Trigger .......................................................................................................................... 241 5.14 CONSTRAINTS ........................................................................................................................................................... 242

5.14.1 Instance Constraint .......................................................................................................................................... 244 5.14.2 File Constraint ................................................................................................................................................. 245 5.14.3 Variable Constraint .......................................................................................................................................... 247 5.14.4 Resource Constraint ......................................................................................................................................... 248 5.14.5 Day/Time Constraint ........................................................................................................................................ 249

5.14.5.1 Exclusion List Constraint ............................................................................................................................................... 249 5.14.5.2 Maximum Dispatch Time .............................................................................................................................................. 250 5.14.5.3 Calendar Constraint ....................................................................................................................................................... 250

5.14.6 Calendars ......................................................................................................................................................... 251 5.14.6.1 Calendar – General ........................................................................................................................................................ 252 5.14.6.2 Calendar – Properties ..................................................................................................................................................... 253 5.14.6.3 Calendar – Audits .......................................................................................................................................................... 254 5.14.6.4 Calendar – Security ........................................................................................................................................................ 255

5.14.7 Resources ......................................................................................................................................................... 256 5.14.7.1 Resource – General ........................................................................................................................................................ 257 5.14.7.2 Resource – Properties .................................................................................................................................................... 258 5.14.7.3 Resource – Audits .......................................................................................................................................................... 259 5.14.7.4 Resource – Security ....................................................................................................................................................... 260

5.15 ALERT OBJECTS ........................................................................................................................................................ 261 5.15.1 Alert Object – General ..................................................................................................................................... 261 5.15.2 Alert Object – Properties ................................................................................................................................. 262 5.15.3 Alert – Audits ................................................................................................................................................... 266 5.15.4 Alert – Security................................................................................................................................................. 267

5.16 USER ACCOUNT NAME OBJECTS .............................................................................................................................. 269 5.16.1 User Account – General ................................................................................................................................... 270 5.16.2 User Account – Properties ............................................................................................................................... 271 5.16.3 User Account – Audits ...................................................................................................................................... 272 5.16.4 User Account – Security ................................................................................................................................... 273 5.16.5 Using a User Account Object ........................................................................................................................... 274

5.17 DESIGN VIEW ........................................................................................................................................................... 275 5.17.1 Find Job (Design View) ................................................................................................................................... 278 5.17.2 Printing (Design View) .................................................................................................................................... 279 5.17.3 Creating a Plan/Job in Design View ................................................................................................................ 280 5.17.4 Adding a Trigger .............................................................................................................................................. 281 5.17.5 Adding a Job Constraint .................................................................................................................................. 284 5.17.6 Modifying Triggers and Constraints ................................................................................................................ 286

5.18 PASSING PARAMETERS AND/OR VARIABLES ............................................................................................................. 288 5.19 JOB CHECKPOINT, RESTART AND PROGRESS INDICATOR .......................................................................................... 289

6 OPERATING THE ACTIVEBATCH SYSTEM ........................................................................................................ 291

6.1 MONITORING ACTIVEBATCH OPERATIONS ............................................................................................................... 291 6.1.1 Filters ............................................................................................................................................................... 291 6.1.2 Daily Activity ................................................................................................................................................... 293 6.1.3 Gantt Chart ...................................................................................................................................................... 294 6.1.4 Properties Window ........................................................................................................................................... 295 6.1.5 Favorites Window ............................................................................................................................................ 296 6.1.6 Runbook ........................................................................................................................................................... 297 6.1.7 System View ..................................................................................................................................................... 298

6.2 MANAGING QUEUES ................................................................................................................................................. 299 6.2.1 Deleting a Queue ............................................................................................................................................. 299


6

6.2.2 Starting and Stopping a Queue ........................................................................................................................ 300 6.2.3 Open and Close a Queue.................................................................................................................................. 302 6.2.4 Flush Instances on a Queue ............................................................................................................................. 303

6.3 MANAGING JOBS AND PLANS .................................................................................................................................... 304 6.3.1 Instance Operations ......................................................................................................................................... 305

6.3.1.1 Change Queue Priority ................................................................................................................................................... 305 6.3.1.2 Constraint (Dependency) Status ..................................................................................................................................... 305 6.3.1.3 Force Run ...................................................................................................................................................................... 306 6.3.1.4 Override Completion Status ........................................................................................................................................... 306 6.3.1.5 Pause and Resume a Plan/Job ........................................................................................................................................ 307 6.3.1.6 Restart Plan/Job Execution ............................................................................................................................................ 307 6.3.1.7 Moving a Job from/to a Queue ...................................................................................................................................... 308

6.3.2 Definition Operations ...................................................................................................................................... 309 6.3.2.1 Test Run ......................................................................................................................................................................... 309 6.3.2.2 Trigger Plan/Job Execution ............................................................................................................................................ 311 6.3.2.3 Copy and Paste a Plan/Job ............................................................................................................................................. 314 6.3.2.4 Cut and Paste a Plan/Job ................................................................................................................................................ 314 6.3.2.5 Browse ........................................................................................................................................................................... 315

6.3.3 Definition and Instance Operations ................................................................................................................. 316 6.3.3.1 Abort/Delete a Plan/Job ................................................................................................................................................. 316 6.3.3.2 Abort Batch .................................................................................................................................................................... 317 6.3.3.3 Hold and Release a Plan/Job .......................................................................................................................................... 317 6.3.3.4 Printing ActiveBatch Objects......................................................................................................................................... 318

6.4 RESOURCE OPERATION ............................................................................................................................................. 319 6.5 SYSTEM VIEW ........................................................................................................................................................... 320

6.5.1 System View Overview ..................................................................................................................................... 320 6.5.2 System View Shapes ......................................................................................................................................... 322 6.5.3 System View Colors .......................................................................................................................................... 323 6.5.4 System View Job/Plan Operations ................................................................................................................... 325 6.5.5 System View Operations ................................................................................................................................... 327

6.5.5.1 Find Job (System View) ................................................................................................................................................. 328 6.5.5.2 Printing (System View).................................................................................................................................................. 329 6.5.5.3 Miscellaneous Operations (System View) ..................................................................................................................... 330

6.6 TROUBLESHOOTING .................................................................................................................................................. 331 6.6.1 Audits ............................................................................................................................................................... 332 6.6.2 Job Output Logging ......................................................................................................................................... 333

6.6.2.1 User Managed Logging.................................................................................................................................................. 333 6.6.2.2 Centrally Managed Logging .......................................................................................................................................... 334

7 REPORTING ................................................................................................................................................................. 335

7.1 REPORTING OVERVIEW ............................................................................................................................................. 335 7.2 CREATING A REPORTING FILE ................................................................................................................................... 337

7.2.1 Column Selection ............................................................................................................................................. 339 7.2.2 Search Column Criteria ................................................................................................................................... 340 7.2.3 Date Specification ............................................................................................................................................ 342 7.2.4 Custom SQL ..................................................................................................................................................... 342

7.3 VERSION 4 REPORTING FILES ................................................................................................................................... 343 7.4 GENERATING A REPORT ............................................................................................................................................ 344

7.4.1 Interactive Report Generation ......................................................................................................................... 345 7.4.2 Non-Interactive Report Generation ................................................................................................................. 347 7.4.3 Third-Party Tools/Report Writers .................................................................................................................... 348

8 DATE ARITHMETIC ................................................................................................................................................... 349

8.1 INTRODUCTION AND SYNTAX ................................................................................................................................... 349 8.1.1 Commands ........................................................................................................................................................ 349 8.1.2 Qualifiers ......................................................................................................................................................... 350

8.2 CUSTOM SCHEDULE SPECIFICATION ......................................................................................................................... 351

7

8.3 VARIABLES AND PROCESS/SCRIPT INPUT PARAMETERS ........................................................................................... 352 8.4 FISCAL CALENDAR AND USER DATE TAGS ............................................................................................................... 352 8.5 DATE ARITHMETIC CALENDAR ADMINISTRATION .................................................................................................... 353

8.5.1 Creating a Date Arithmetic Calendar .............................................................................................................. 353 8.5.2 Assigning Dates to a Date Tag ......................................................................................................................... 355 8.5.3 Managing Date Tags ........................................................................................................................................ 358 8.5.4 Save, Save As and Compile .............................................................................................................................. 358 8.5.5 Import ............................................................................................................................................................... 358 8.5.6 Printable View.................................................................................................................................................. 358

8.6 DATE ARITHMETIC COM FACILITY .......................................................................................................................... 359 8.6.1 Date Arithmetic COM Example ....................................................................................................................... 360

8.7 DATE ARITHMETIC TEST UTILITY ............................................................................................................................. 362 8.8 STAND-ALONE DATE ARITHMETIC SUBSTITUTION UTILITY ...................................................................................... 363

9 USING THE ACTIVEBATCH COMMAND-LINE INTERFACE .......................................................................... 365

9.1 CONVENTIONS .......................................................................................................................................................... 366 9.1.1 Absolute Time ................................................................................................................................................... 366 9.1.2 Delta Time ........................................................................................................................................................ 366 9.1.3 Combination Time ............................................................................................................................................ 368

9.2 ABATAVLMGR ..................................................................................................................................................... 369 9.3 ABATCHKPT .......................................................................................................................................................... 370 9.4 ABATDATESUB .................................................................................................................................................... 371 9.5 ABATDBPWD ........................................................................................................................................................ 372 9.6 ABATEXECSQL ..................................................................................................................................................... 373 9.7 ABATPTY ................................................................................................................................................................... 374 9.8 ABATRPTGEN (DIRECT DATABASE METHOD) ...................................................................................................... 375 9.9 ABATRPTGEN (COM METHOD) ............................................................................................................................ 376 9.10 ABATSET ............................................................................................................................................................... 377 9.11 ABATUPDPWD ...................................................................................................................................................... 378 9.12 ABAT COMMANDS................................................................................................................................................... 379

9.12.1 CLOSE/QUEUE ............................................................................................................................................... 379 9.12.2 DELETE/JOB ................................................................................................................................................... 380 9.12.3 DELETE/QUEUE ............................................................................................................................................ 381 9.12.4 FLUSH/QUEUE ............................................................................................................................................... 382 9.12.5 HOLD ............................................................................................................................................................... 383 9.12.6 INITIALIZE Queue ........................................................................................................................................... 384 9.12.7 MODIFY/JOB .................................................................................................................................................. 386 9.12.8 MODIFY/QUEUE ............................................................................................................................................ 391 9.12.9 OPEN/QUEUE................................................................................................................................................. 393 9.12.10 PAUSE ............................................................................................................................................................. 394 9.12.11 RELEASE ......................................................................................................................................................... 395 9.12.12 REQUEUE ....................................................................................................................................................... 396 9.12.13 RESTART ......................................................................................................................................................... 397 9.12.14 RESUME .......................................................................................................................................................... 398 9.12.15 SET BATCH ..................................................................................................................................................... 399 9.12.16 SHOW JOB ...................................................................................................................................................... 401 9.12.17 SHOW QUEUE ................................................................................................................................................ 403 9.12.18 START/QUEUE ................................................................................................................................................ 405 9.12.19 STOP/QUEUE ................................................................................................................................................. 406 9.12.20 SUBMIT ........................................................................................................................................................... 407 9.12.21 SYNCHRONIZE ............................................................................................................................................... 412 9.12.22 TRIGGER ......................................................................................................................................................... 413

10 ACTIVEBATCH SCRIPTING AND PROGRAMMING .......................................................................................... 415

10.1 ACTIVEBATCH OBJECT TOPOLOGY .......................................................................................................................... 416


8

11 ACTIVEBATCH MESSAGES ..................................................................................................................................... 417

12 INDEX............................................................................................................................................................................. 433

Table of Figures

Figure 1 – ActiveBatch Architecture 18 Figure 2 – ABATAdmin Initial Usage and Connection Dialog 26 Figure 3 – AbatAdmin After Connection 28 Figure 4 – Job Properties Navigation 34 Figure 5 – Daily Activity List 36 Figure 6 – Gantt Chart 37 Figure 7 – Runbook View 38 Figure 8 – System View 39 Figure 9 – Queue Counters View 40 Figure 10 – Instances 41 Figure 11 – Design View 42 Figure 12 – Reporting Facility 45 Figure 13 – Slider Notification 46 Figure 14 – ActiveBatch Search Object Dialog 47 Figure 15 – Search Results 48 Figure 16 – Options (General) 49 Figure 17 – Options (Runbook) 51 Figure 18 – Options (Gantt Chart) 52 Figure 19 – Options (Design/System View) 53 Figure 20 – Options (Print) 54 Figure 21 – Options (Notifications) 55 Figure 22 – Options (User Role Panes) 56 Figure 23 – On-Line Help 57 Figure 24 – ActiveBatch Admin Utility (Initial) 59 Figure 25 – AbatAdmin on the System Tray 60 Figure 26 – Connect Dialog (Basic) 61 Figure 27 – Connect Dialog (Advanced) 62 Figure 28 – Connect through Firewall 63 Figure 29 – Find Object in Tree (by ID) 65 Figure 30 – Job Scheduler Properties 66 Figure 31 – Job Scheduler Variables 67 Figure 32 – Job Scheduler Alerts 68 Figure 33 – Job Scheduler Performance Counters 69 Figure 34 – Job Scheduler Audits 70 Figure 35 – Job Scheduler History 71 Figure 36 – Job Scheduler Security 72 Figure 37 – Queue (General) 77

9

Figure 38 – Queue (Properties) 78 Figure 39 – Execution Queue (Properties) 79 Figure 40 – Execution Queue (Characteristics) 81 Figure 41 – Queue Alerts 82 Figure 42 – Queue Counters 84 Figure 43 – Queue Audits 85 Figure 44 – Queue Security Tab 86 Figure 45 – Add Security Dialog (Queue) 88 Figure 46 – Execution Queue (Add User Characteristic) 89 Figure 47 – New Generic Queue (Properties) 90 Figure 48 – Associating/Disassociating an Execution Queue Dialog 92 Figure 49 – Plan (General) 96 Figure 50 – Plan (Variables) 98 Figure 51 – Plan (Triggers/Scheduling) 99 Figure 52 – Plan (Triggers/Events) 101 Figure 53 – Plan – Constraints/General Dialog 102 Figure 54 – Plan – Constraints/Date-Time Dialog 103 Figure 55 – Plan – Execution/General Dialog 104 Figure 56 – Plan – Monitoring/RunTime 105 Figure 57 – Plan – Alerts 107 Figure 58 – Plan – Completion/Properties 108 Figure 59 – Plan – Completion/Completion Rule 110 Figure 60 – Plan Completion Rule Dialog 111 Figure 61 – Plan – Completion/Completion Triggers 112 Figure 62 – Plan – Counters 113 Figure 63 – Plan Audits 114 Figure 64 – Plan History 115 Figure 65 – Plan Security Dialog 116 Figure 66 – Object Policy Defaults 118 Figure 67 – Plan Auditing 120 Figure 68 – Trigger Operation with Audit 122 Figure 69 – Virtual Root Properties 126 Figure 70 – Adding the BatchLogon Right 129 Figure 71 – Job Definition Navigation 133 Figure 72 – Job – General 134 Figure 73 – Job – Job Properties (Process) 136 Figure 74 – Success Code Rule (Search String Setup) 138 Figure 75 – Job – Job Properties (E-Mail) 140 Figure 76 – Job – Job Properties (FTP) 141 Figure 77 – Job – Job Properties (FileSystem) 142 Figure 78 – File System Operation Dialog 143 Figure 79 – Job – Job Properties (Jobs Library) 144 Figure 80 – Job – Job Properties (Script) 145 Figure 81 – Job – Generic Queue Characteristics 147 Figure 82 – Machine Characteristic Dialog 148 Figure 83 – Select User Characteristics 150


10

Figure 84 – Job – Variables 151 Figure 85 – Variable Properties 152 Figure 86 – Active Variable Data Source Menu 153 Figure 87 – Job – Scheduling 154 Figure 88 – Job – Triggers/Events 156 Figure 89 – Job – Constraint/General Dialog 157 Figure 90 – Job – Constraints/DateTime 159 Figure 91 – Job – Execution/General Dialog 161 Figure 92 – Job – Execution/User Credentials 163 Figure 93 – Job – Execution/Logging 165 Figure 94 – Job – Monitoring/Run-Time 167 Figure 95 – Job – Monitoring/CPU-Time 169 Figure 96 – Job – Alerts 171 Figure 97 – Job – Completion Properties 172 Figure 98 – Job – Completion Triggers 174 Figure 99 – Job – Counters 175 Figure 100 – Job Properties – Audits 176 Figure 101 – Job History 177 Figure 102 – Job Security Dialog 178 Figure 103 – Job Add Security Dialog Box 180 Figure 104 – Job Types Listing (Partial list) 181 Figure 105 – Job Types, Sub-Types and Properties 190 Figure 106 – SQL Block (Job Type) 191 Figure 107 – Modifying a Job 193 Figure 108 – Instance Menu 194 Figure 109 – View Batch Run (List View) 195 Figure 110 – View Batch Run (Gantt) 196 Figure 111 – View Batch Run (Graphical View) 197 Figure 112 – Instance Information 198 Figure 113 – Instance (Job) Variables 200 Figure 114 – MOF Text (File Trigger) 201 Figure 115 – MOF Text (WMI) 202 Figure 116 – Instance (Job) Audits 203 Figure 117 – Instance (Job) Log 204 Figure 118 – Instance (Job) Properties 205 Figure 119 – Reference – General 208 Figure 120 – Reference – Properties 209 Figure 121 – Show Dependent Objects 211 Figure 122 – Queue Dependent Objects 211 Figure 123 – Delete a Template Plan Dialog 212 Figure 124 – Hold/Release a Plan or Job 213 Figure 125 – Export Filter Dialog 214 Figure 126 – Revision History (Initial) 216 Figure 127 – Revision History (Comparison) 217 Figure 128 – Variable – List of Active Sources 219

11

Figure 129 – Schedule List Dialog 223 Figure 130 – Schedule General 225 Figure 131 – Schedule Time Specification 226 Figure 132 – Schedule Day Specification (General) 227 Figure 133 – Schedule Day Specification (Exact Dates) 229 Figure 134 – Schedule Range Specification 230 Figure 135 – Schedule Audits 231 Figure 136 – Schedule Security 232 Figure 137 – Associations Dialog 235 Figure 138 – Event Trigger Dialog 236 Figure 139 – Expected Date/Time (Initial) 238 Figure 140 – Daily Activity (Expected Date/Time Example) 238 Figure 141 – WMI Event Privilege Settings 239 Figure 142 – Event Advanced Settings 240 Figure 143 – Plan/Job Completion Dialog 241 Figure 144 – Constraint Tab Dialog 242 Figure 145 – Adding a Job Constraint Dialog 244 Figure 146 – Adding a File Constraint Dialog 245 Figure 147 – Variable Constraint (Active) 247 Figure 148 – Resource Constraint 248 Figure 149 – Date/Time Constraint Properties 249 Figure 150 – Calendar – General 252 Figure 151 – Defining a Business Calendar 253 Figure 152 – Calendar Audits 254 Figure 153 – Calendar Security 255 Figure 154 – Resource – General 257 Figure 155 – Resource – Properties 258 Figure 156 – Resource Audits 259 Figure 157 – Resource Security 260 Figure 158 – Alert Objects 261 Figure 159 – Managing Job Alert Objects 262 Figure 160 – Job Alert Dialog 263 Figure 161 – Notifications Menu 264 Figure 162 – Alert Object Audits 266 Figure 163 – Alert Object Security 267 Figure 164 – Execution User Credentials 269 Figure 165 – User Account (General) 270 Figure 166 – User Account (Properties) 271 Figure 167 – User Account Audits 272 Figure 168 – User Account Security 273 Figure 169 – Design View (Overview) 275 Figure 170 – Operations 277 Figure 171 – Design View (Find Job) 278 Figure 172 – Design View (Print) 279 Figure 173 – Completion Trigger Dialog 282 Figure 174 – Add Instance Constraint Dialog Box 284


12

Figure 175 – Constraint Tool Tip 286 Figure 176 – Edit a Constraint 287 Figure 177 – Instance Filter Bar 291 Figure 178 – Instance State Selection 291 Figure 179 – Instance Filter Bar (Date and Time) 292 Figure 180 – Daily Activity List 293 Figure 181 – Gantt Chart 294 Figure 182 – Properties Window 295 Figure 183 – Add To Favorites Menu Selection 296 Figure 184 – Favorites Window 296 Figure 185 – Runbook 297 Figure 186 – System View Filter 298 Figure 187 – Delete Queue Confirmation 299 Figure 188 – Stopping/Starting a Queue 300 Figure 189 – Stopping a Queue (Timed) 301 Figure 190 – Opening or Closing a Queue 302 Figure 191 – Restrict Job Submission (Timed) 302 Figure 192 – Flush Instances on a Queue 303 Figure 193 – System View (Job Menu) 304 Figure 194 – Constraint Status 305 Figure 195 – Force Run Menu 306 Figure 196 – Override Completion Status 306 Figure 197 – Pause/Resume a Plan/Job 307 Figure 198 – Requeue Operation 308 Figure 199 – Test Run Plan (Initial) 309 Figure 200 – Test Run Plan (After) 310 Figure 201 – Triggering a Job 311 Figure 202 – Trigger Job Dialog 312 Figure 203 – Browse Plan 315 Figure 204 – Abort an Instance Dialog 316 Figure 205 – Delete a Job Dialog 316 Figure 206 – Hold/Release a Plan/Job 317 Figure 207 – Print Queue Operation 318 Figure 208 – Sample Print Queue 318 Figure 209 – Resource - Evaluate Now 319 Figure 210 – System View (Tool Tip) 321 Figure 211 – System View (Job/Plan Operations) 325 Figure 212 – System View (Active Instance Menu) 326 Figure 213 – System View Operations 327 Figure 214 – System View (Find Job) 328 Figure 215 – System View (Print) 329 Figure 216 – Job Instance History 331 Figure 217 – Reporting Facility 335 Figure 218 – Report Files Dialog 336 Figure 219 – Enter Report Filename 337

13

Figure 220 – Report Filter 338 Figure 221 – Property Column Selection 339 Figure 222 – Selecting/Sorting Columns 340 Figure 223 – Property Search Criteria 340 Figure 224 – Report Date Specification 342 Figure 225 – Converting a Prior Release Report file 343 Figure 226 – Generate Report 345 Figure 227 – Advanced Report Generation 345 Figure 228 – Sample Report 346 Figure 229 – Creating a new Date Arithmetic Calendar 353 Figure 230 – Specifying a Fiscal Year 354 Figure 231 – Date Arithmetic Date Tagging 355 Figure 232 – Create Date Tag 356 Figure 233 – Date Arithmetic Test Utility 362 Figure 234 – ActiveBatch Object Relationship 416


14

Tables

Table 1 – Job Scheduler Alerts 68 Table 2 – Queue States 74 Table 3 – Job States and Sub-States 75 Table 4 – Queue Alerts 83 Table 5 – Queue Security Access 87 Table 6 – Plan Security Access 117 Table 7 – Audit Operations 121 Table 8 – Operating System Batch Job Considerations 130 Table 9 – Environment Variables for Job Steps 131 Table 10 – Date/Time Parameter Format Codes 137 Table 11 – Machine Characteristics 149 Table 12 – Job Security Access 179 Table 13 – Job Types and Supported Platforms 182 Table 14 – Drag and Drop Operations 210 Table 15 – Job Scheduler Built-in Variables 220 Table 16 – Job/Plan Built-in Variables 221 Table 17 – Event Built-in Variables 221 Table 18 – Variable Date/Time Format 222 Table 19 – Schedule Access 233 Table 20 – Constraint Logic Operators 243 Table 21 – Calendar Access 255 Table 22 – Resource Access 260 Table 23 – Plan/Job Alerts 264 Table 24 – Alert Access 268 Table 25 – User Account Security 273 Table 26 – Date Arithmetic Commands 350 Table 27 – Date Arithmetic Qualifiers 350 Table 28 – Format Qualifier 351 Table 29 – Calendar Date Arithmetic Tags 352 Table 30 – ActiveBatch Messages (Alphabetical) 424 Table 31 – ActiveBatch Messages (Numeric) 431

15

1 INTRODUCTION

ActiveBatch® is a distributed Job Scheduling and Management System that allows you to execute tasks in an unattended or background mode. With ActiveBatch you can:

• Define Jobs with pre/post job steps. Job types include: E-Mail, FileSystem, FTP/SFTP/FTPS, Process, Script and Built-in Jobs Library. This means you can utilize proven and reliable ActiveBatch built-in facilities rather than having to write a program or script.

• Define Plans with property classes and variables. Plans give you the ability to create a workspace for your jobs and other ActiveBatch objects. Plans provide a tightly integrated set of policies for related jobs.

• Variables allow for data passing between related jobs and plans. Variables can be constants or active. Active Variables can use a variety of data sources (including SQL Query, Registry, WMI’s WQL, XML files, etc). Variables have hierarchical global or local scope.

• Fiscal and Gregorian Date Arithmetic and substitution supported. ActiveBatch provides four (4) levels of support in which date calculations can be performed for job scheduling and/or job run-time usage.

• Define Jobs with constraints (dependencies). Constraints include: Job Instance, File, Time, Variable and Resource.

• Trigger Plan(s) or Job(s) for execution based on Events. Events include File operations and System Events.

• Trigger Job(s) or Plan(s) for execution based on Date/Time Schedule (including Fiscal Schedules).

• Execute a job on a specific machine or a class of machines.

• Execute a job on a virtual machine in which a specific machine is chosen based on workload or other characteristics.

• Execute a job on different hardware and software platforms.

• Job History can be retrieved individually or within the context of a Plan run (so related job instances can be viewed together).

• Obtain a complete audit trail of the submitted job including a log of the output of the job. Auditing is also extended to the management of ActiveBatch objects. Each time a modification is made to an object an audit is produced as well as a revision id.

• Specify monitoring and alert capability to ensure that jobs run properly and as expected. Alerts can send e-mail (including pager and BlackBerry™ support (client is additional)), trigger events, event log and SNMP. ActiveBatch supports Microsoft’s System Operations/MOM and HP OpenView (including Network Node Manager).


16

1.1 Product Components ActiveBatch consists of three (3) major components:

Client

As you would expect the Client component is the main user interaction point to the ActiveBatch system. ActiveBatch provides three (3) client interfaces depending on the type of user you are and what mode of interaction you require. Most users will execute the ActiveBatch Admin (ABATAdmin) utility. This Windows GUI-based component provides the user with the ability to create and manage job(s). ActiveBatch provides a complete set of command-line utilities so users can script ActiveBatch operations. As ActiveBatch is COM based, a programmatic interface is also available. Object-oriented scripting languages can directly access ActiveBatch’s objects, properties and methods through the various constructs of those languages.

Job Scheduler

The ActiveBatch Job Scheduler is the heart of the job management system. Clients communicate with a Job Scheduler, which is responsible for creating all of the various objects that make up ActiveBatch. As its name implies, the Job Scheduler is the component that keeps track of all jobs and determines when a job is to execute. The Job Scheduler may be limited in terms of the number and type of Execution Agent(s) it can support. Any limitations are noted in the next section on Product Editions.

Execution Agent

Once a job is ready to execute, the Job Scheduler communicates with a machine’s Execution Agent. This is the component that is responsible for actually running the job. The Execution Agent is the cross-platform component of the ActiveBatch system. Each Execution Agent is licensed for use. TCP/IP is used for communications between the Job Scheduler and its Execution Agents.

Note: ActiveBatch is a cross-platform product that supports many releases of Microsoft Windows products. For ease of reference the following conventions apply (unless otherwise noted). When Windows is specified that implies support for Windows 2000 (All Editions), Windows XP and Windows Server 2003 (All Editions) on an Intel 32-bit compatible processor.

17

2 ACTIVEBATCH TERMS AND CONCEPTS

ActiveBatch is a Job Management and Scheduling System. The Batch portion of ActiveBatch refers to the concept of submitting a script or program for non-interactive processing. Simply stated, this means that you don't have to log into Windows or remain logged in for your non-interactive script to execute. When a script or program is submitted to ActiveBatch for processing that script or program is said to become a Batch Job. Batch jobs allow for work to be scheduled and the results of the job to be analyzed. Batch jobs also offer the potential of utilizing your machines during their off-hours when interactive usage is presumably at its lowest.


18

2.1 Architecture

Figure 1 – ActiveBatch Architecture

ActiveBatch is entirely client-server based and all aspects of ActiveBatch can be fully distributed. ActiveBatch consists of three major components: the ActiveBatch UI clients, the ActiveBatch Job Scheduler and the ActiveBatch Execution Agent. All of these components could reside on a single machine or on multiple machines and each component can have multiple instances. The ActiveBatch UI is the user-interface portion of the ActiveBatch system and provides the ability for users to command various aspects of the product. Two (2) UI components are provided. All UI components communicate with one or more selected Job Scheduler(s). The ABATAdmin program is a standard Windows GUI program that provides a windows interface for working with ActiveBatch. The ABAT program is a command-line based user interface that allows

Chapter 2 - ActiveBatch Terms and Concepts

19

access to the product in either an interactive or non-interactive fashion. The ActiveBatch UI clients communicate with the ActiveBatch Job Scheduler component.

2.2 Namespace When you connect to an ActiveBatch Job Scheduler you are actually connecting to a Namespace. A Namespace is where all ActiveBatch objects reside for a given scheduler. Similar to a file system, the ActiveBatch Namespace contains objects that can be end-nodes or containers. A container may contain zero or more other objects including other containers. Continuing with the file system analog, you specify the container name(s) when searching for a specific object. If the context is such where the current container (i.e. current directory) has been set, ActiveBatch will use that context and search that container. The purpose of a Namespace is to catalog objects for later retrieval.

2.3 Objects The ActiveBatch Job Scheduler is responsible for the maintenance and overall operation of the ActiveBatch system and its databases. The Job Scheduler manages several types of objects and all objects are securable. All the objects reside in a Namespace and the namespace resides in a database. Every object must be uniquely labeled, as it exists within the namespace. This doesn’t mean that every object must be uniquely named. Rather you can’t have two objects that have the same name at the same point in the namespace. This is analogous to a file system in which you can have 2 files named the same existing in different folders but not 2 files named the same in the same folder.

Every object has both common and unique properties that pertain to that object. Common properties include the name, label, description, and object-state of the object. An object’s name is what you want the object to be displayed as. While it’s a good idea to uniquely name objects to avoid confusion, ActiveBatch makes no such requirement. An object’s label, however, must be unique within the namespace. An object’s label is typically used when scripting ActiveBatch operations. For example, if you write a script to manipulate ActiveBatch objects it will most likely be the “label” that you reference, not the name. Since the object’s label will be used for namespace retrieval the characters used within the label are subject to stricter content rules. The label can contain alphanumeric (A-Z, a-z, 0-9) and underscore (_) characters. A label must also not begin with a number. ActiveBatch does allow you to search for objects using either the label or the name properties. An object’s state is either enabled or disabled for use.

2.3.1 Reference A Plan or Job object in ActiveBatch can be referenced. For example, let’s say you’ve created a Job “A” under “Plan “Alpha” and you’d like the same job to also be used under a different plan named “Beta”. Rather than copy Job “A” and create an entirely new job (which you can do), you can create a reference to Job “A” under “Plan “Beta”. Creating a reference is analogous, in Windows, to creating a “shortcut”. While the shortcut itself is an object, the shortcut references a file. In ActiveBatch, a reference object references another ActiveBatch object (in this example, a Job). The advantage to referencing an object is that all references actually use the same object. Reference objects do have several properties that are specific to the object. Two (2) properties, in particular, are important and must be mentioned. One, you can individually secure the referenced object. Two, you can disable a reference without disabling the object itself. ActiveBatch provides two levels of enabling and disabling of an object. You can enable/disable an object reference through the Enable/Disable operation. You can globally enable/disable an object (regardless of references) through the object’s Enable property (that’s the object-state property above).

2.3.2 Queue In ActiveBatch a queue represents a non-volatile priority ordered object in which jobs reside waiting for execution. Two types of user-defined queues are available: Execution and Generic. Two other types of system-defined queues are also available: OnDemand and VariableQueue.

An Execution Queue is a named object in which jobs wait for execution for a specific machine. ActiveBatch allows you


20

to create multiple execution queues and associate each execution queue with a given machine. You can also create multiple execution queues for a single machine. When a batch job is ready to execute, the ActiveBatch Execution Agent, residing on the named machine, is responsible for running the job.

A Generic Queue is essentially a “virtual” machine. A Generic Queue represents one or more Execution Queues. This abstraction is very useful in that the actual machine selected to run the job can be determined dynamically versus the static assignment used when submitting a job to a specific Execution Queue. When a job is ready to be executed, characteristics specified with the job are compared to characteristics specified with the Execution Queues. In addition, Generic Queues can employ “scheduling algorithms” to further refine where the job is to be run.

The OnDemand Queue is a special ActiveBatch built-in queue that is neither a Generic or an Execution queue. The purpose of the OnDemand queue is to allow a job author to place a job into the ActiveBatch system and defer where the job is to actually execute until a later time. This provides some very interesting benefits that we will cover in Section 5.3.6.

The VariableQueue is another special ActiveBatch built-in queue that allows a Job Designer to defer the association of job-to-queue to execution time via the built-in variable #queue. This facility means that a job can designate which queue a downstream job will actually execute on at run-time.

2.3.3 Plan A Plan is an object container. A Plan can contain all of the ActiveBatch objects within it. The purpose of a Plan is to provide a workspace where properties can be inherited and where resources and objects can be referenced. An additional benefit of a Plan is to provide isolation between the various objects stored within the Plan and other objects within the ActiveBatch Namespace. A typical use of a Plan would be to store various related job(s) and/or plans. For example, let’s say you wanted to execute 3 jobs serially. You would create a Plan and specify any properties that were to be shared among the 3 jobs. You would then create the 3 jobs linking them in a fashion to cause them to execute serially. Triggering the Plan would then trigger the execution of the 3 jobs within the plan. Since Plans can be triggered, Plan instances are also created allowing you to track the complete history of a particular stream of job execution.

2.3.4 Job A Job represents some type of process that is to be executed in a non-interactive1 manner. Jobs are run under the security context of the submitting user (unless different authentication credentials are provided). ActiveBatch supports many different types of jobs. Each job type is discussed in more detail in Section 5.6.3.

E-Mail This type of job allows the creation and sending of e-mail.

FileSystem This type of job allows you to execute a series of file system operations (n.b. copy, delete, etc) in an operating system independent fashion.

FTP/SFTP This type of job allows you to execute a series of FTP/SFTP commands.

Jobs Library This type of job allows you to invoke existing ActiveBatch logic in order to execute a given feature.

Process This is the typical ActiveBatch job and consists of either a script file or an executable image.

Script This type of job is similar to a Process Job except that the script information is embedded within the job and not referenced through an external script.

The “Process” job type executes an executable image or a script. The script itself can be written using any scripting language installed on the execution machine. The only requirement is that the script extension be registered on the 1 ActiveBatch jobs are executed non-interactively from the point-of-view that the system’s desktop or console need not be logged on. The term “non-interactive” is not meant to imply that an ActiveBatch job cannot query or execute applications that may be interactive in nature.


21

Execution Machine and associated with an actual program or system that is supporting the script. For Unix based systems, the first line of the script typically indicates which command shell is to be used. Jobs are submitted for eventual execution and can be triggered to run in a variety of ways. A trigger is an action that causes a job to begin execution. The most typical trigger is date and time and the most typical date and time trigger is “scheduled” execution. This means that a job is connected to one or more schedules that indicate the day/date and time the job is expected to run. In the ActiveBatch system, jobs are submitted or queued for execution by specifying a named Queue that indirectly indicates the machine the job will execute on. Jobs may also have constraints that prevent a job from executing until one or more conditions have been met. While many job properties depend on the job type you select, many properties are also common to all jobs.

Since Jobs can be executed in a recurring or non-recurring fashion, several new terms must be introduced. A Job Definition is never actually executed but rather describes the job (or plan). An instance is the actual executing job. A single instance job is a non-recurring job. This type of job runs and when it completes it’s essentially done and becomes history. A template job is a recurring (or potentially recurring) job. This type of job runs on either a schedule or is triggered through events or other aspects of the ActiveBatch system. A template job will cause an instance of the job to be created when a trigger is activated (for example, when the scheduled execution time is met). A template job can support one or more instances of the job. Some operations require that you confirm with ActiveBatch whether the operation is intended for the template and/or the instance.

2.3.5 Variables and Properties Variables allow a job designer the ability to pass data from job/plan to job/plan. Variables can be initialized via a constant or a data source. Variables set via a data source are referred to as activeVariables. Variables are established in a hierarchical fashion meaning that jobs can inherit plan variables. Variable substitution is supported almost anywhere a string can be specified. Substitution is performed by enclosing the variable name in curly braces preceded by the dollar sign symbol. For example, ${app_path}test.bat could be an input filename string where “app_path” is defined as “c:\scripts\” in an upper level plan. Variables can also be used as a constraining pre-condition for job execution. You can also designate variables to be exported to the running job by marking it as an “environment variable”.

Plan and Jobs consist of a number of built-in variables that represent the various properties of a Plan or Job. Variables which begin with an at-sign (@) or dollar-sign ($) are ActiveBatch built-in variables. Variable substitution of object properties provides a great deal of run-time customization.

2.3.6 Triggers An action that causes a job to become eligible for execution is called a Trigger. Triggers are arranged as objects as well as operations within ActiveBatch. A job may be started via one or more trigger objects as well as through the job’s Trigger operation. It is important to note that while a job may be triggered for execution, a job will only execute if any/all of the job’s constraints have been met.

2.3.6.1 Schedule

A Schedule represents some recurring date and time trigger. One or more schedules can be associated with a Job or Plan and one or more jobs can share a schedule. Schedules can be public or private. A private schedule can only be associated with one job and when the job’s template is deleted so is the schedule. Schedules can operate on a calendar and/or fiscal date basis.

2.3.6.2 Events

Events are represented as either ActiveBatch or Windows Management Instrumentation (WMI) generated. The event facility enables the triggering of a job without polling for a specific condition to occur. For example, a job can be triggered when a new file is created.


22

2.3.7 Constraints A Constraint is used to filter triggers such that certain actions or properties must be true to allow the Job or Job Plan to actually execute.

2.3.7.1 Calendar

ActiveBatch supports the concept of “Business Dates.” A Business Date is a day when business will be conducted. To determine a business day requires that the Job be assigned to a Calendar. A Calendar contains rules for determining holidays and non-working days. When a Job is assigned to a Calendar, the Calendar “filters” any Schedule triggers and ensures that the job can only execute on a “business day” (the Trigger command/method can override this). The advantage of filtering triggers with a calendar is that the job author need not create special “business” schedules. Also, an administrator can still execute administrative jobs, which are typically scheduled without regard to business days, and use existing schedules. The job, in this case, would run without an assigned calendar. A Calendar is also a securable entity.

2.3.7.2 Job/Plan Instance

A Job/Plan Instance constraint (formerly called a “Job Dependency”) allows you to specify which previous job(s) or plan(s) must have executed before this job can execute.

2.3.7.3 File

A File constraint (formerly called a “File Dependency”) allows you to specify one or more files which must meet certain criteria before this job can execute.

2.3.7.4 Time

A Time constraint allows you to further refine when a job may run (regardless of when the job is triggered).

2.3.7.5 Resource

A Resource constraint allows you to indicate what resource(s) must be present and available (usable) before the job can execute. The resource itself can be static (initialized when the Job Scheduler is started) or dynamic and subject to external change.

2.3.7.6 Variable

A Variable constraint allows you to check external data prior to allowing a job to run. An ActiveBatch variable can be static or dynamic, for example, a variable can be tied to a SQL operation and the results of the operation can be established as a constraint. Variables are typically used to pass information from job to job as part of a Job Plan.

2.3.8 Alert Object An Alert Object represents one or more ActiveBatch alert actions that may be performed. You may assign an alert object to one or more queues, jobs or plans. An Alert object is a securable entity.

2.3.9 User Account Object A User Account object represents a username/password combination that may be used when executing a job. All ActiveBatch jobs require some type of security credentials for execution. The Account object allows you to create a Username/Password reference and then associate that reference to one or more jobs. The advantage of the Account object (like the Alert object) is that a change to the object (for example, a new password) is automatically affects every


23

job assigned to the object. For Windows Server 2003 (or later) systems, ActiveBatch supports Kerberos impersonation. This feature allows ActiveBatch to impersonate a user without the password requirement. This avoids the audit and password change issues when associating a password with an account. The Account object is a securable entity.

25

3 USING ACTIVEBATCH WITH ABATADMIN

The “ActiveBatch User’s Guide” discusses various ActiveBatch terms and concepts using an easy-to-understand case study approach. The case studies begin with simple technical problems and advance to more difficult issues that require more discussion and planning. For first-time or novice users, your ActiveBatch Administrator can setup a sample database for you to use.

This chapter will completely describe all the aspects of the ActiveBatch system in terms of usage. If you have questions concerning installation, as in what product edition to install or what component(s) can be installed please read the ActiveBatch Installation and Administrator’s Guide for more information.


26

3.1 ABATAdmin Terms and Concepts

The ABATAdmin application is the user’s main interface point into ActiveBatch. You can start ABATAdmin by either clicking on its desktop icon or by selecting the program through the ActiveBatch program menu. ActiveBatch begins by displaying a “splash” screen identifying its version and registered owner. ABATAdmin continues the initialization process by connecting to all Job Schedulers you were previously connected to. ABATAdmin follows the general rule that whatever you were looking at on program exit you should be looking at when the program comes up. If this is the first time you’re running the program, AbatAdmin will display a connect dialog using “localhost” for the machine name. This is appropriate only if the Job Scheduler machine is on the same machine as the client. This is likely in an evaluation or proof-of-concept setting. This is unlikely in a production setting.

Figure 2 – ABATAdmin Initial Usage and Connection Dialog

Chapter 3 - Using ActiveBatch with ABATAdmin

27

Clicking the Connect button produces this message.

If the connection was not successful you’ll receive a message box similar to the one here.

In which case the Connect dialog will reappear and ask for a new machine to connect to.

If you attempt to connect to a V5 Job Scheduler you will receive this error. By default, the V6 AbatAdmin GUI can only connect to a V6 Job Scheduler.


28

If the connection was successful, you’ll see the following similar display.

Figure 3 – AbatAdmin After Connection


29

3.1.1 Bars, Panes and Views

Figure 3 shows the initial ABATAdmin screen with a single connected Job Scheduler. Like any Windows GUI program, ABATAdmin has a menu bar. The menu bar consists of the following menus: ActiveBatch, View, Tools and Help. The menu bar is one method for specifying operations (like “Connect” to a Job Scheduler). Beneath the menu bar is the tool bar. The tool bar is a type of shortcut that allows you to quickly select one of the different views that ABATAdmin is capable of displaying. Simply place the cursor over a tool for a quick reminder as to what the tool provides.

The leftmost window beneath the tool bar is the Navigation Pane. This window, through tabs at the bottom, allows you to select the overall navigation you need. ActiveBatch provides two (2) primary types of navigation: Object and View Navigation (selectable through the Navigation tab) and Administration. Object/View Navigation is most appropriate when you want to either navigate the ActiveBatch namespace or you want to retrieve run-time information from one of the ActiveBatch views. Administration is most appropriate for configuration and other administrative aspects of the ActiveBatch system. Users who consider themselves Designers or Operators will most likely use the Object/View Navigation and Administrators will use the Administration tab.

When you select a view (for example, System View or Daily Activity list) the Main Window is activated. The main window is multi-tabbed with the actual view as part of the tab. While you can create multiple views (and tabs), only one view is active and can be in focus. Each tab is listed along the top of the main window. The information presented in the main window is, of course, based on the view that you selected. For example, in the Daily Activity List you would be shown a list of job instances for the specified date. That’s fine but sometimes more information is needed. For example, what if you wanted to see previous instance history for this job or plan. To satisfy instance information, the Instances window is used. This window, by default, appears at the bottom of the screen.

The Properties window (not to be confused with each object’s properties dialog) provides a quick and easy facility for viewing the most important properties of an object without having to issue a Properties operation.

The Favorites window provides an easy way for you to quickly access your most critical plans and jobs. Rather than always using the Navigation Pane, the Favorites window allows you to categorize and save your favorite objects (similar to the Favorites menu operation found on most web browsers). To add a favorite object to the Favorites window, right-click on the object and select Advanced/Add to Favorites (or press Ctrl/D). This operation will display a small dialog box that allows you to name your favorite (the default is the object’s name).

Almost all views and panes support dynamic real-time display. This is great when you want to watch your plans or jobs as they execute and complete. You can disable this feature on a window basis or globally. When you disable this feature, a brief annotation appears indicating that you are no longer looking at live data.

The tab at the very bottom is the Log View window and contains all informational, success and error messages concerning your use of ActiveBatch. A button to the far right of the window allows you to clear the log.

Many of the windows and panes feature a small “pin”. This pin allows you to indicate whether you want the window to always be displayed or to display the window only when you hover your mouse cursor over the tab. You’ll notice that the “Log Viewer” window is displayed through the hover concept. Many of the panes also allow to you to move them to another location, detaching it from the main window.


30

3.1.2 Menu Operations Menu’s are provided to allow you to perform an operation appropriate to the object. You select a menu from either the menu bar, tool bar or by right-clicking on an object. The menu that is shown is always appropriate to the object and in context. For example, if an object is disabled, then a menu operation to enable is provided.

3.1.3 Object Selection AbatAdmin supports the selection of one or more job objects for the purpose of performing a single operation. Left click on a desired object to select it. Depending on the view you’re selection may cause a change in the display within several panes. For example, if you needed to Hold several unrelated jobs you can select each job using the typical Windows select operations (Shift or Ctrl key combination).

3.1.4 ActiveBatch Icons As you look through the various ABATAdmin menus and views you’ve probably noticed many icons. ActiveBatch makes very liberal use of icons and this section describes each icon you will see in the system. ActiveBatch icons do not use color to denote object type. So even on a black and white monitor you will be able to differentiate between a queue and a job. The icons do use color to denote state information (but text is also provided in case you’re color challenged).

Green is considered a “good” state. Red indicates either some type of problem or a user specified operation that acts to inhibit further operations (for example, stopping a queue will result in the queue being colored red). Any object that is disabled will be colored grey. Job and Plan definitions do not observe the red/green convention since a defined plan/job does not actually run. Plan and Job instances, however, do observe the red/green convention (with “purple” indicating that the instance was cancelled or aborted).

represents an execution queue whose state is started. The green color adds to the visual indication of a “good” state.

represents a generic queue (note the multiple machine figures).

represents an execution queue whose state is stopped and closed.

represents a schedule.

represents a calendar.

represents a user account object.

represents a resource object.

represents an alert object.

represents a plan object (with no policy defaults).

represents a plan object (with policy Defaults).

represents a plan object (with Auditing policy).

represents a reference plan.

represents a reference job.


31

represents a “process” type job.

represents an “e-mail” type job.

represents an “FTP/SFTP/FTPS” type job.

represents a “file system” type job.

represents a “script” type job.

represents a “jobs library” type job.


32

3.1.5 ActiveBatch Hot-Keys ABATAdmin supports the use of “hot-keys” for those advanced users who would prefer to use the keyboard for faster product interaction than your mouse. The three (3) sections below describe what hot keys are supported and where.

3.1.5.1 Global Keys (applies to all views)

Key Description F5 Refresh all views in the GUI CTRL + F5 Refresh currently selected view only F4 Connect to a Job Scheduler F11 Toggle Full Screen mode (a.k.a. View->FullScreen) F10 Options (a.k.a. Tools->Options) CTRL + D Favorite/Bookmark selected object in GUI CTRL + F Find/Search for object(s) by Name or Label CTRL + G Find object by ID or Full Path in Tree

3.1.5.2 Operators/Designers Tree (a.k.a. Navigation)

Key Description

CTRL + C

Copy selected object - copies Full Path of selected object to clipboard also

CTRL + X

Cut selected object - copies Full Path of selected object to clipboard also

CTRL + V

Paste Copy/Cut object(s)

DELETE

Delete selected object (a.k.a. RightClick->Delete)

*

Expand all tree nodes under selected object

ENTER

Show Properties of selected object (a.k.a. RightClick->Properties)

F2

Edit Name/Label (based on option "Options->General->Editing Name/Label in Explorer Tree")

3.1.5.3 Report Lists (Instances / Daily Activity / Browse)

Key Description CTRL + C Copy selected object(s) - copies selected text data to clipboard also CTRL + X Cut selected object(s) - copies selected text data to clipboard also CTRL + V Paste Copy/Cut object(s) DELETE Delete selected object (a.k.a. RightClick->Delete) * Expand all tree nodes under selected object CTRL + A Select all rows in report list view CTRL + P Print all rows in report list view CTRL + SHIFT + G Sync to Tree. i.e. Find Template in tree.


33

3.1.6 ActiveBatch Error Messages As you use ActiveBatch you may, from time to time, see an error message box similar to this:

Most of the time we hope the error message sufficiently describes the error condition encountered. In the event it does not you may press the “Online Help” button. If your system has access to the Internet, you will be connected to our web site where more information concerning the specific error you encountered may be available.


34

3.1.7 Property Dialogs

Figure 4 – Job Properties Navigation

Every object has properties and several ActiveBatch objects have a great many properties. To prevent “feature overload”, where an object has so many features that you just can’t find them, we’ve arranged the property dialog as a series of categories that appear on the left side of the dialog. By default, some of the more advanced categories are shown in a collapsed view. For example, for the Plan/Job objects, the “Monitoring” category contains two (2) sub-category displays; one for Run-Time monitoring and one for CPU monitoring. To display these sub-categories, simply click on the main category (in this example, clicking on “Monitoring” first expands the category to show its sub-categories and another click collapses the sub-categories back into the main category. This feature allows us to hide more advanced categories for novice users and avoid unnecessary confusion. A preference option also allows you to control whether certain advanced categories should be collapsed (the default) or expanded.


35

3.2 Navigation The ActiveBatch User Interfaces, particularly AbatAdmin, have been designed to support three (3) types of people who need to use ActiveBatch. Sometimes a single person may assume more than one role. Designers are those individuals who create the various objects that make up an ActiveBatch implementation. Designers create queues, plans and jobs that are expected to implement the business or system requirements that a company may have. Operators are those individuals who are expected to manage the ActiveBatch system and ensure that all plans and jobs operate with successful results. Administrators are those individuals who manage the components and services that make up an ActiveBatch system. By matching functional requirements to an individual’s role, ActiveBatch ensures that the right tools are made available to the right person.

ActiveBatch provides two (2) primary navigation tabs that implement the functionality you need based on what you need to do. The Object/View Navigation satisfies those users who need to navigate the ActiveBatch namespace and/or request run-time information from one of its views. The Administration tab provides access to information that an administrator would need to properly maintain the ActiveBatch system.

3.2.1 Object/View Navigation Object/View Navigation is the primary navigation used by ActiveBatch Designers and Operators. The Object/View Navigation (or Pane) contains all the various objects that have been created on a given Job Scheduler(s). Once you’ve created some objects you’ll notice that ActiveBatch will automatically catalog them under their respective folders.

The Object/View navigation pane allows for easy navigation through ActiveBatch objects. You can select objects and perform various operations. By default, the objects are arranged in their family categories (all queues are listed within the Queue folder, Jobs and Plans are listed together, etc). Clicking on a category produces a listing of all the related objects. For example, clicking on Calendars produces a list displaying common properties of all the calendar objects. Clicking on Plans and Jobs also produces a list of common properties, with Plans displayed using the familiar tree notation for expansion and collapse of contained Plans and Jobs within.

If you click on the Alphabetic icon the objects are arranged in alphabetic order.

You will also note that if you click on an individual Plan or Job object, the Instances pane may be activated. The Instances pane will display the common properties of any active/completed instances for the Plan or Job selected.

Remember that a navigation pane does not replace any other user view(s) present within ActiveBatch but is meant to simplify navigation (or finding objects) requirements when using the ActiveBatch system.


36

3.2.1.1 Daily Activity

The Daily Activity list provides a dynamic real-time display, in list fashion, of what jobs have completed, are executing and will execute on a given day. By default, the current day is displayed. The ability to change the date is also provided. Daily Activity displays all jobs and plans in ascending time fashion (although the display order can be changed by clicking on an information column). Plans are color coded for ease of separation and all completed jobs and plans are color-coded based on whether they succeeded or failed.

Figure 5 – Daily Activity List

You can drill down into a plan by clicking on the plus sign at the start of the plan row. The information displayed provides a snapshot of the critical items that would normally be needed to manage and/or monitor jobs.


37

3.2.1.2 Gantt Chart

In the Gantt chart view, the “time of day” listed at the top and horizontally scrollable. As you scroll horizontally backwards or forwards, the date will change as appropriate. A Calendar control is also available so you can select days other than today. The Jobs themselves are displayed vertically with a graphic rendition of their expected elapsed times. You can perform selected operations on a job by simply right-clicking on the job. All jobs are displayed using a common coding scheme in which color is used to visually identify the states of job instances.

Figure 6 – Gantt Chart


38

3.2.1.3 Runbook

The Runbook provides a dynamic display in which the jobs are listed in a diary fashion by ascending time within a specific date. You can obtain more information about a given job or plan by clicking within the Runbook and obtaining a Runbook list. If the job has completed you can also obtain instance information in the “Runbook Instances” pane.

Figure 7 – Runbook View


39

3.2.1.4 System View

System View is, typically, the real-time graphical dynamic display of Plans and/or Jobs. As these Plans and/or Jobs execute you can see the various shapes representing the objects change color. If multiple instances of the same Plan or Job execute, the Instances pane will display each unique batch run. When System View is launched through the Navigation pane, System View will automatically select the latest instance. You can manually select an instance to view through the Instances pane. When all the instances have completed, an accent stripe appearing on the right side of the shape let’s you know how the latest instance performed.

Note: For V4 customers who may have many objects at the root level you can enable the Filter facility and de-clutter the view by suppressing objects on a queue and/or group basis. This facility is disabled by default. To enable see the “Options\System View” dialog.

Figure 8 – System View


40

3.2.1.5 Queue Counters View

Queue Counters View provides a list of all queues present within the connected Job Scheduler and their respective counters.

Figure 9 – Queue Counters View

The view is list oriented with each queue and its associated counters on a separate row. The queues are shown in color to denote their current state and this view consolidates all queues (regardless of root or plan location) within a single view. This information presented in this view is static, however, a convenient Refresh button has been provided to refresh the counters.


41

3.2.1.6 Instance View

If you launch System View through the Instances pane, the display will only track the selected instance. That is why this view, while very similar to System View, is called Instance View. Only the instance you are interested in tracking is displayed. New instances are not tracked and the color of the shapes always indicates the completion of the job’s instance.

Figure 10 – Instances


42

3.2.1.7 Design View

Selecting Design View allows you to switch to a graphical mode. This view allows you to create and manipulate the various ActiveBatch objects. Design View is where you will create Plans and their Jobs. Jobs and Plans can be linked together such that when one completes another Job is triggered. In Design View, your Jobs and their relationships to other Jobs in the system can be visually seen and graphically managed.

Figure 11 – Design View

Design View, as its name implies, allows you to create and other maintain jobs and perform job operations. System View is very similar Design View with one important exception. Design View displays no information concerning job instances. In Design View, only job definitions are displayed. In System View, a real-time dynamic display of scheduled jobs and their instances (if any) are shown. From System View you can sit back and watch the display change as jobs are run.


43

3.2.2 Administration The Administration tab is meant for the administration of the ActiveBatch system itself. Administration of Plans and Jobs is part of operations. An Administrator is charged with the responsibility for the proper installation of ActiveBatch, its overall maintenance and the security of the various objects that make up the system. Part of that security is the authorization of users to the ActiveBatch system and the establishment of their roles. Another important aspect to security is the use of User Account objects that provide security credentials to the jobs that run. As ActiveBatch is a cross-platform product these credentials are applicable to one or more machines and platforms.

Information on the administration and management of ActiveBatch can be found in the “ActiveBatch Installation and Administrator’s Guide”.

3.2.2.1 Navigation – Administration

The information presented as part of the Navigation pane is what Administrators require.

The Active Directory section allows Administrators to see their published Job Scheduler(s) and Execution Agent(s). Since the software rev levels are also provided this is a very handy way of quickly determining what version and service pack has been applied.

Each connected Job Scheduler will allow you to manage Policies, make ActiveBatch registry changes, manage User Accounts and also manage the ActiveBatch High Availability aspects of the system.

Note: In the Administration Navigation Pane you will only see connected Job Schedulers if you are an ActiveBatch Administrator.

3.2.2.2 ActiveBatch Services

This facility allows you to control the ActiveBatch services across your network. Patterned after the Windows Services applet you can start, stop and otherwise administer the Job Scheduler and/or Execution Agent services.

3.2.2.3 Active Directory

This facility allows you to explore the Active Directory entries (either full Active Directory or ADAM) made by the Job Scheduler and Execution Agent services. By using publishing names and information about the ActiveBatch services on a machine the discovery of ActiveBatch machines is made easier. The Active Directory folder is separated into two sub-folders: Published Job Schedulers and Published Execution Agents. The information displayed consists of the published name, machine name, ActiveBatch version and description. By examining the version information you can quickly determine whether all components have the latest version or ServicePack applied.

3.2.2.4 High Availability Manager

This facility lets you manage the ActiveBatch High Availability features of the product. When enabled, this feature allows active and standby Job Schedulers to participate. If your active Job Scheduler fails, one or more standby Job Schedulers can take over avoiding loss of availability.


44

3.2.2.5 Policies and Configuration

This facility allows you to set object-wide policies and to configure many customizable parameters of the ActiveBatch system.

Note: The Policies section consists of many legacy parameters (please note those that are labeled as “obsolete”). For the most part, this “policies” section has been replaced by “object policies” which are a part of every Plan object. Advanced Systems recommends that you look to the Plan Policies features.


45

3.3 Reporting Facility The Reporting Facility allows you to extract and retrieve information about ActiveBatch jobs. Figure 12 illustrates what a sample report might look like. Chapter 7 provides more detailed information about the creating and scheduling of ActiveBatch reports. Please note that in addition to the built-in ActiveBatch Reporting facility you may also use any Microsoft or third-party product (such as Crystal Reports) to generate your own reports.

Figure 12 – Reporting Facility


46

3.4 Slider Notification Slider Notification is a useful feature when you are specifically interested in certain events and your window may be obscured by other applications you are running. Section 3.5 lets you control which events are to be displayed and when. The slider is raised and lowered from the System Tray area. The slider itself is color-coded. Red typically means that something important has happened. Blue or Green means that some level of successful operation has occurred.

Figure 13 – Slider Notification


47

3.5 Tools The Tools menu option allows you to specify your preferences as well as other useful features.

3.5.1 Refresh and Refresh Pane These options allow you to refresh all panes and windows or the selected pane. Hot keys F5 for refresh and Control/F5 for refresh pane provide quick access.

3.5.2 WMI Updates WMI Updates provide the AbatAdmin GUI program with the ability to display real-time updates. On occasion you may not want to see updates while you are researching a particular view. This option allows you to disable WMI updates. After you confirm the request, AbatAdmin will no longer request WMI updates for ActiveBatch. This option allows you to toggle between enabling and disabling these updates.

3.5.3 Reset With all the various options and preferences that make up ActiveBatch, the GUI allows you to reset a selected portion of the GUII back to the factory default settings or to reset all the panes and options back to their factory default settings. It is important to note that the reset is specific to the GUI and not to the entire ActiveBatch system.

3.5.4 Search ActiveBatch provides a method for searching the various objects you may create. Clicking on the “binoculars” icon in the Toolbar or typing Control/F causes this dialog to appear.

Figure 14 – ActiveBatch Search Object Dialog

The following fields comprise the Search object dialog:

Scheduler to search is a dropdown of your currently connected to Job Schedulers. By default, the Job Scheduler you are currently connected to is displayed.

In the Find what: field you enter data that narrows the search. Data that may be entered includes wildcard characters (*, %).


48

In fields: represents where ActiveBatch should look when comparing the data in the “Find What” field. Two (2) selections are available: Name and Label.

Filter: This is a dropdown of all the ActiveBatch objects. You may narrow the search to specific objects.

The Under field is, by default, filled in with the last Plan or Job Scheduler you selected. Similar to searching files in a folder think of this as the last folder you visited. You can change the scope by clicking on the right most button.

The Recursive (Search within plans) checkbox allows you to continue searching nested plans for the desired object.

When a search is performed, a new search results window appears that provides zero or more objects that met your search criteria. You can then examine the objects found in greater detail.

Figure 15 – Search Results


49

3.5.5 Options The Options sub-menu allows you to specify your GUI preferences. The Options are further sub-categorized by the items on the left-hand portion of the dialog.

3.5.5.1 Options – General

Figure 16 – Options (General)

General Options Description

Connect on Startup This option controls how AbatAdmin connects to the last Job Scheduler you were connected to. By default, AbatAdmin reconnects to those schedulers.

Defer Connections on Startup

This option indicates whether AbatAdmin is to immediately reconnect to any previously connected Job Schedulers or to wait perform the actual connection when you expand a Job Scheduler’s namespace. The default is false (or not to defer). Customers with many connected Job Schedulers may find enabling this option useful.

On Scheduler Communication error

This option controls how AbatAdmin responds to a Job Scheduler disconnect. By default, AbatAdmin automatically attempts to reconnect to the Job Scheduler machine.

Reconnection timeout This option is used in conjunction with an Auto-Reconnect to determine how long to continue attempting to reconnect.


50

General Options Description

Default Text Editor This editor will be used for any large text viewing, for example, as when viewing a log file. Default is Notepad.exe.

Changing tabs forces refresh

If enabled, changing tabs (the tabs along the main window) forcing a refresh of the data.

Minimize to System Tray If enabled, minimizing the GUI will force the GUI icon to appear in the system tray.

Display resolved scheduler name

If enabled, AbatAdmin will use the Job Scheduler name as reported by the Job Scheduler (instead of the specification you entered). The default is false (or disabled).

Display Security Accounts in UPN

If enabled, AbatAdmin will display security information in UPN form (i.e. name@domain) instead of domain\user syntax.

Editing Name/Label in Explorer Tree

Depending on the selection you may or may not be allowed to edit the name or label field by changing the navigation pane tree object.

Display Options Description

Display Mode By default, the object name and not its label are used. Job Authors may find it useful to switch to label mode since that is the best “string” type search.

Display Object Type By default, the object type is not shown in the Navigation views since the objects are categorized within folders. Enabling this checkbox will display the object type (i.e. Plan, Queue, Job, etc).

Time Display By default, all times are shown in the Job Scheduler’s local time zone. This allows you to see what “time” an object will be triggered. You may also select Client (which will show you the times in your time zone) or UTC.

Auto Column Sizing If enabled, AbatAdmin will automatically resize columns based on the displayed data. By default, this option is false (or disabled).

Navigation Options Description

Main View gets updated on

By default, the main view is updated when you double-click on an item. This avoids unnecessary calls to the Job Scheduler when you mean to select an item through right-click. You may also choose to select One-Click.

Instances pane gets updated on

By default, the instances view is updated when you double-click on an item. This avoids unnecessary calls to the Job Scheduler when you mean to select an item through right-click. You may also choose to select One-Click.

Look and Feel Options Description

Theme By default, the Windows XP themes are used. Other themes are possible through selection.

Pane tabs position By default, the tabs are located on the bottom. This option allows you to locate them on the top, bottom, left or right-hand portion of the pane.

Lock panes By default, the panes are unlocked and may be moved to anywhere you desire. You may also select to lock the panes preventing their movement, closure or being undocked.


51

3.5.5.2 Options – Runbook

Figure 17 – Options (Runbook)

This tab allows you to specify preferences when using the Runbook view. The last three items bear some discussion.

Runbook Options Description

Color This selects the background color of the Runbook. You may select other colors. We recommend that you do not select colors such as Green, Red, Purple and Orange since they can conflict with the instance state colors.

Time Interval This option allows you to set the default time interval (minutes) used when displaying the “diary” portion of the Runbook view. You may specify an interval from five (5) to sixty (60) minutes. The initial default is ten (10) minutes.

Auto Scroll This setting will cause the diary portion when viewing the current day to automatically scroll based on time of day. This is very useful when you want to follow along with jobs that are scheduled to run.

Show Time in 24 Hour Format

This setting allows you to see the Runbook time listed, along the left-hand portion, in 24-hour as opposed to AM/PM format.

Combine items greater than

By default, if more than four (4) job/plan(s) are present in a time period they are combined into a single entry. You may change the value with this option.


52

3.5.5.3 Options – Gantt

Figure 18 – Options (Gantt Chart)

This tab controls the manner in which the Gantt Chart displays their objects.

Sort by Name: By default, the Gantt Chart displays jobs in name sorted order. You may prevent that sorting with this option.


53

3.5.5.4 Options – System View

Figure 19 – Options (Design/System View)

Design/System View Options

Description

Show Tooltips This option indicates whether you want to see a tool tip displaying more information on the object.

Show Text on Links This option indicates whether you want text displayed on the links that show constraints (dependencies) and completion triggers.

Color Reset Delay This option indicates the number of seconds AbatAdmin shows the job completion color before returning to the job “template” state color.

Double-click on Plan shows properties

This option is just as it’s described and indicates whether you want the double-click action to drill down into the plan or to show a plan’s properties.

Show Queue and Group Filter Bar

This option enables the filter dropdowns which allow you to de-clutter the view based on queues and/or group names. By default this option is disabled. V4 users, in particular, may find this feature useful until jobs at the root level have been migrated to a plan hierarchy.

Show … Lines These options control whether the specified constraint or alert should be graphically shown.


54

3.5.5.5 Options – Print

Figure 20 – Options (Print)

This tab controls which template is used for printing which object. This advanced option should only be modified by experienced HTML programmers.


55

3.5.5.6 Options – Notification

Figure 21 – Options (Notifications)

This tab controls the Slider Notification feature. Enable Slider Notifications allows you to enable or disable the feature. The Show Only when Minimized checkbox allows you to further limit the notifications to when AbatAdmin is minimized. Window show delay indicates the number of seconds to display the notification. Under Filter you can also refine what events are to be shown in the slider.


56

3.5.5.7 Options – User Role Panes

Figure 22 – Options (User Role Panes)

This tab controls the objects that are to be displayed in each role’s navigation (i.e. Designers, Operators, Administrators). Clicking on the … button causes a checkbox list of all the ActiveBatch objects. Clearing an item means the object will not be shown in that role. The Reset to Factory Defaults provide a simple way to return back to the defaults established by ASCI.


57

3.6 Help The Help menu provides access to the ActiveBatch On-Line Help system. Help also provides access to resources on the Advanced Systems Concepts’ ActiveBatch website.

Figure 23 – On-Line Help


58

3.7 ABATAdmin and WMI

ABATAdmin provides an automatic refresh of ActiveBatch objects through its support of Microsoft’s Windows Management Instrumentation (WMI) facility. The automatic refresh mechanism requires that the Client machine as well as the Job Scheduler machine have WMI installed and started. If WMI is not present or started on either machine, a manual refresh of ActiveBatch data will be necessary to see any changes which have occurred (you can press the F5 key to request a manual refresh). With WMI enabled, all object changes are sent to ABATAdmin as events. Each event is specific to the object that changed. By using WMI instead of some “homegrown” method, the publishing of event data is made available both locally and remote through a facility which can be used by anyone.

ABATAdmin indicates that automatic refresh (AutoRefresh) is available on a Job Scheduler machine through the use of a special icon. The “lightening bolt” indicates that automatic refresh is available. ABATAdmin provides automatic refresh for most views.

59

4 GETTING STARTED WITH ACTIVEBATCH 4.1 Starting the ActiveBatch Admin Application Note: New Users should consider reading the “ActiveBatch User’s Guide”, which provides a quick introduction of the various ActiveBatch objects and provides specific instructions for quickly creating various objects. The User’s Guide is tutorial by design and uses case studies, beginning with creating a simple queue and job and then moving on to more complex problems.

ABATAdmin is a Windows GUI utility that is used to access the user portion of the ActiveBatch system.

To run ABATAdmin double-click on the desktop icon (created during the product’s installation) or search for the ActiveBatch program group and click on “ActiveBatch V6 Admin”. ABATAdmin begins by announcing its startup and then initializes itself for use.

Figure 24 – ActiveBatch Admin Utility (Initial)


60

4.2 Leaving ActiveBatch Admin Application

To leave AbatAdmin click on either the File menu bar and select Exit or click on the stylized in the upper right corner. Depending on your preference you may want to minimize AbatAdmin so it becomes resident on the system tray. This has several advantages:

1. AbatAdmin uses significantly less memory.

2. AbatAdmin starts faster then if you run the process anew.

3. AbatAdmin can alert you to various events when left on the system tray.

This last feature yields quite a few benefits. When Slider Notifications are enabled (Section 3.4), AbatAdmin can alert you when important ActiveBatch events occur (like Job Scheduler failover). A small window will slowly appear indicating which event occurred. After several seconds, the window will slowly drop out of sight.

Figure 25 – AbatAdmin on the System Tray

Chapter 4 - Getting Started with ActiveBatch

61

4.3 Job Scheduler

4.3.1 Connecting to a Job Scheduler With ABATAdmin running you’re ready to connect to a Job Scheduler. The Job Scheduler component is a Windows Service that manages all the ActiveBatch objects. ActiveBatch supports connections to one or more Job Schedulers. As the name implies, this service handles job and machine scheduling. The first thing you need to do is connect to a Job Scheduler.

4.3.1.1 Basic Connection

Figure 26 – Connect Dialog (Basic)

To connect to a Job Scheduler machine, either right click on the “ActiveBatch Neighborhood” icon and select “Connect…” or click on “Job Scheduler/Connect…” using the menu bar. The figure above shows the Connect dialog. The Basic Connect dialog asks for a machine name (or IP address) to connect to. You may enter the machine name by typing it in, or selecting a previously entered machine from the drop down list, or by clicking on the Browse button to display a Network Neighborhood listing of machines. For those machines running Directory Services you can click the Directory button. This retrieves a list of published Job Schedulers and Plans operating within your domain. When you have selected a machine, click on the Connect button to attempt the connection. A successful connection results in a list of that Job Scheduler’s objects presented (and merged) into your current view.


62

4.3.1.2 Advanced Connection

Figure 27 – Connect Dialog (Advanced)

The Basic Connect dialog assumes that your current authentication credentials are sufficient to connect to the named Job Scheduler machine. However, if you are logged onto a Windows machine that is not part of the security domain of the Job Scheduler machine you will need to present your authentication credentials to ActiveBatch so you can be authenticated. To perform an extended authentication check, click the Advanced>> button. This will cause Username and Password fields to be displayed. You should enter a username and password that can be authenticated on the selected Job Scheduler system. This will typically be a domain user account for Windows. As a convenience you can click the checkbox for Remember Password to have ActiveBatch remember your entered username/password for the selected Job Scheduler machine. This saved information will only be used for establishing a connection to a Job Scheduler machine. Once you’ve entered the information you may click the Connect button to allow ActiveBatch to attempt a connection with the authentication credentials you’ve supplied.

As previously discussed, ActiveBatch will also provide auto refresh capability so you can see the active system and how it is changing. The mechanism used is Windows Management Instrumentation (WMI). WMI also performs authentication. Depending on the Client/Job Scheduler machines you are running you may need to change the Impersonation Level and/or Authentication Level as appropriate.


63

4.3.1.3 Firewall Connection

This type of connection is typically used when a firewall is setup between the client and Job Scheduler machines. When a firewall is used, the connection is made to the firewall and a specific port. The firewall then relays the connection to the appropriate internal Job Scheduler machine behind the firewall. The firewall machine can be specified using standard TCP/IP notation (hostname, fully qualified hostname, IP address). The port number is specified by use of a colon (:) and number. For example, hostname:5000 would tell the client to connect to a machine named hostname using port number 5000.

Figure 28 – Connect through Firewall


64

4.3.2 Disconnecting from a Job Scheduler To disconnect from a Job Scheduler right click on the selected Job Scheduler machine icon and select Disconnect. When you successfully disconnect from a Job Scheduler the entire tree of objects that the Job Scheduler represented are removed from all views.

Note: You do not have to be connected to a Job Scheduler for your previously submitted jobs to properly execute.

4.3.3 Job Scheduler Licensing AbatAdmin allows you to execute the AbatLicenseMgr program directly on the specific Job Scheduler machine you’re connected to. For more information concerning this utility read the ActiveBatch Installation and Administrator’s Manual.


65

4.3.4 Find Objects As you can imagine sometimes it may be difficult finding an object among hundreds or thousands of other objects. ActiveBatch provides several operations to help you find an object.

4.3.4.1 Search

Search allows you to find an object based on either the object’s name or label. Wildcards are also supported. A complete description and example of Search can be found in section 3.5.4.

4.3.4.2 Object in Tree

Find Object in Tree is useful when all you know is the object’s ID number. This menu selection displays a simple dialog box asking for the ID. When properly entered the object’s properties are displayed.

Figure 29 – Find Object in Tree (by ID)

When the object is found the object is selected within the Object View Navigation tree.

4.3.4.3 View Property Sheet of Object

This operation is similar to the previously described “Find Object in Tree” but instead of only selecting the object in the Object View Navavigation tree, the object’s properties are also displayed.


66

4.3.5 Job Scheduler Properties Clicking on the Job Scheduler icon and then selecting Properties displays various information about the Job Scheduler machine you’re connected to.

Figure 30 – Job Scheduler Properties

Seven (7) selections are available: Properties (the above figure), Variables, Counters, Alerts, Audits, History and Security. The title of the dialog provides both the IP address of the Job Scheduler machine as well as the user security context used during ActiveBatch logon. The information displayed is retrieved from the Job Scheduler’s machine. The Connected As information reminds you of the current security context associated with this Scheduler, the ActiveBatch Administrator indicates whether you have ActiveBatch Admin access and the WMI Enabled property indicates whether the Job Scheduler machine is using WMI Event handling (necessary for automatic refresh).

Note: The Security selection is discussed in the ActiveBatch Installation and Administrator’s Guide.


67

4.3.5.1 Variables

Previous versions of ActiveBatch displayed a list of the various characteristics (mostly informational) associated with the Job Scheduler. In V6, these characteristics are provided as a series of built-in ActiveBatch variables. The advantage to declaring these characteristics as variables is that you can use them for possible substitution or to customize notification messages. Three (3) buttons are available: Add, Edit and Remove. You must be an ActiveBatch Administrator to access these facilities. The ADD button allows you to add your own “global” variables to the list. Every Plan and Job can retrieve these variables. The variable names you choose must adhere to standard user variable restrictions (in other words you won’t be able to enter a variable with a leading dollar ($) sign or the at-sign (@)). The EDIT button allows you to edit the variables you added. You cannot edit the values of the built-in variables. The REMOVE button allows you to remove or delete an existing variable you added.

Figure 31 – Job Scheduler Variables


68

4.3.5.2 Alerts

The figure below shows a sample Job Scheduler alert.

Figure 32 – Job Scheduler Alerts

This facility allows you to designate one or more alerts (and their actions) based on events governing the Job Scheduler. In particular these events tend to concern the state of the Job Scheduler. The alerts for the Job Scheduler are:

Alert Description

Database Connection Lost Job Scheduler has lost the connection to its database. New jobs will not be started during this period.

Database Connection Resumed Job Scheduler has regained the connection to its database. Normal operations are resumed.

Service Pause Pending Job Scheduler is entering a standby state (for non-cluster failover).

Service Paused Job Scheduler is in standby. (This is a normal state for a standby scheduler).

Service Start Pending Job Scheduler is starting. (This is a transient state).

Service Started Job Scheduler has started. (This is a normal state).

Service Stop Pending Job Scheduler is stopping. (This is a transient state).

Service Stopped Job Scheduler has stopped.

Table 1 – Job Scheduler Alerts


69

4.3.5.3 Counters

The figure below shows a sample of Job Scheduler Performance counters.

Figure 33 – Job Scheduler Performance Counters

The counters in this list box are statically displayed. Clicking on the Refresh button allows you to retrieve updated values. The performance counters are exported so you can track them through various Windows facilities (for example, Microsoft’s Performance Monitoring facility (Perfmon)).


70

4.3.5.4 Audits

The figure below displays audit history concerning the operation of the Job Scheduler itself. Audits typically produced concern the startup and shutdown of the Job Scheduler service.

Figure 34 – Job Scheduler Audits


71

4.3.5.5 History

Figure 35 – Job Scheduler History

This property page shows the number of times the Job Scheduler object has been revised and who/when made the last revision.


72

4.3.5.6 Security

Figure 36 – Job Scheduler Security

This property page allows ActiveBatch Administrators the ability to set Job Scheduler level permissions for authenticated users of ActiveBatch. For more information, please read the “ActiveBatch Installation and Administration” manual.

73

5 DESIGNING THE ACTIVEBATCH SYSTEM

The previous chapter discussed the initial use of AbatAdmin to connect to a Job Scheduler machine. This chapter will discuss the various objects that make up ActiveBatch. As this chapter concerns job authoring and design, make sure that when you run AbatAdmin that you have selected the “Object/View Navigation” tab at the bottom of the Navigation window.

5.1 Job Scheduler Namespace Each Job Scheduler you connect to has its own namespace. The namespace is used for storage and retrieval of ActiveBatch objects. Using a file system analogy, each file is uniquely named depending on the folder it is in. The same is true for ActiveBatch. Just as “C:\” represents the “root” of the “C” drive, when you initially connect to a Job Scheduler you are placed at the root level of the Job Scheduler’s namespace.

The figure to the left shows a connected Job Scheduler with jobs and plans. For example, CaseStudy2 is a plan and its full path is shown as “/CaseStudy2”. If we drill down into CaseStudy2 we see the job objects within that plan (or container).

JobA and JobB, within CaseStudy2, would have a full path of /CaseStudy2/JobA and /CaseStudy2/JobB respectively. Each object is uniquely labeled depending on its position in the namespace. In other words, while you can have two objects labeled JobA you can’t have two objects labeled JobA at the same level within CaseStudy2. When you access objects within the GUI you are always presented with the full path to the object. When you script access to an ActiveBatch object you may elect to use either a full path or just the object’s label. If you specify a full path then no ambiguity exists and the object can be retrieved. However, if you specify only the object label and no path, your current position in the namespace is scanned. If no object is found an error is produced.


74

5.2 Common Object Properties Name, Label, Description and whether the object is enabled are some of the common elements all objects share. As this chapter explains each object, you should give some thought as to how you will name each object. The object’s name and label are two different (yet related) properties. An object’s name does not have to be unique (although you would do well to make it unique to avoid confusion or ambiguity). An object’s label must be unique.

Since every object has common properties those properties have been placed on the “General” category when creating or viewing an object.

Name: The object’s name should be unique to avoid confusion. We recommend that it also be somewhat descriptive so it’s easy to find. The name is limited to sixty-four (64) characters.

Label: Every object must be uniquely labeled within the scope of the namespace. The label is typically the same value as the name; however, uniqueness is always enforced for an object’s label. The label is recorded in the ActiveBatch namespace. The characters that may be used for the label property are restricted to alphanumeric (A-Z, a-z, 0-9) and underscore (_). The label itself must begin with an alpha character. The label is limited to sixty-four (64) characters. The label is typically used only when scripting. All searches are case-insensitive.

Description: This free form property is provided so you can document and describe the object to others.

Enabled: This property determines whether the object itself is enabled for use. ActiveBatch also provides an Enable/Disable method for every object. An additional property named Global Disable is meant to be used with Reference objects and is discussed in that section (Section 5.10).

There are also several read-only properties.

ID: Object ID. This is a unique number that can be used to retrieve any object.

Path: This is the full namespace specification to the object. The object’s label is inserted at the end.

State: The interpreted state depends on the object. For a Queue, the state will indicate whether the Queue has been started, stopped, starting or stopping. Table 2 indicates the Queue states. For a Plan/Job Instance, this property indicates the current status of the instance, for example, waiting for constraint, executing or completed. Table 3 indicates the Plan/Job Instance states.

State Description

Started Queue is started and can dispatch jobs.

Starting Queue is starting, however, jobs cannot be dispatched due to unavailability of active Execution Agent.

Stopped Queue is stopped. Jobs cannot be dispatched.

Table 2 – Queue States

Chapter 5 - Designing the ActiveBatch system

75

State Description

Waiting The job is awaiting execution. Possible sub-states are:

WaitingQueueBusy – the Queue is not available for Job execution at this time. The queue may not be started and/or it has reached its maximum job execution limit.

WaitingConstraint – waiting on one or more constraints (dependencies) to complete. The number of times left to wait are displayed in parenthesis.

WaitingDateTime – waiting for date/time to begin execution (Deferred Trigger).

WaitingActiveInstances – waiting for the active job instance to complete (job tolerates only one active instance) OR waiting for the limit of multiple active instances to complete

WaitingRestart –a disconnection occurred between the Job Scheduler and Execution Agent and the job was not marked as Restart with Failover.

WaitingExecutionAgent – a job with Restart on Reboot is waiting for the Execution Agent/machine to become available.

Preprocessing The job is beginning the execution phase and communicating with an Execution Agent (Dispatch).

Executing The job is currently executing. Possible sub-states are:

Executing – main job step is executing

ExecutingPreStep – pre job step is executing

ExecutingPostStep – post job step is executing

Paused – job is paused on execution machine

Completed The job has completed processing. Possible sub-states are:

Succeeded – job completed successfully

Failed – job completed in failure

Aborted – job was aborted

Held/Disabled The job is held waiting for manual release. A held job is a disabled job.

Table 3 – Job States and Sub-States


76

5.3 Queues This section will describe how to create Queues. Two (2) types of queues can be created: Execution and Generic. At least one Execution queue is required so you can run jobs on the machine represented by that queue. To create a Queue at root level you must have “Create Queue” access permission on the ActiveBatch System (Job Scheduler) object. To create a Queue within a Plan you must have “Create Objects” access permission within the plan.

5.3.1 Creating an Execution Queue To create an Execution Queue either right-click on a Job Scheduler machine icon, right-click on the Queues folder or right click on a Plan and select New… Execution Queue operation. When you’ve completed the Execution Queue selections you must click the OK button to confirm and apply your selections. Click the Cancel button to cancel the New Execution Queue operation. Your new queue will instantly appear (if auto refresh is enabled) and should be ready for operations.


77

5.3.1.1 Queue – General

Figure 37 – Queue (General)

The above figure shows the “General” dialog for queues.

General Definition: These fields describe the common aspects shared by all Queues.

Name: This mandatory field requires the entry of a name for this Queue. Queue names are limited to a maximum of sixty-four (64) characters. While you may enter data in upper or lower case, all comparisons and searches for this field are performed in a “caseless” mode.

Label: This mandatory field uniquely labels the Queue object within the ActiveBatch namespace. Queue labels are limited to a maximum of sixty-four (64) characters. While you may enter data in upper or lower case, all comparisons and searches for this field are performed in a “caseless” mode. This field is used when scripting ActiveBatch objects.

ID: This read-only field indicates the object ID (useful when scripting).

Full Path: This read-only field provides the complete path to the object. The label is used as part of the path.

Description: This optional field allows you to enter data describing the intended use of this Queue.

State: This read-only field indicates the current state of the Queue (see Table 2).

Read Only: This checkbox allows you to prevent anyone from modifying the queue object’s properties.


78

5.3.1.2 Queue – Properties

Figure 38 – Queue (Properties)

The above figure shows the “Properties” pane for all queues.

Auto Close/Stop: The next sets of fields indicate when jobs may be submitted to the Queue or when jobs may be scheduled for execution.

Close from… to…: This “from” and “to” time range indicates when a Queue is closed. Job instances may not be submitted to a closed queue (Job definitions may still be associated with a closed queue). To enable this feature, click the checkbox and then enter a “from” and “to” time range. “from” and “to” times may not be the same.

Stop from… to…: This “from” and “to” time range indicates when a Queue is to be stopped. Jobs are not scheduled for possible execution on a stopped Queue. To enable this feature, click the checkbox and then enter a “from” and “to” time range. “from” and “to” times may not be the same.


79

5.3.1.3 Execution Queue – Properties

Figure 39 – Execution Queue (Properties)

This tab is used to set specific Execution Queue properties.

Machine: This mandatory field indicates the machine that will be used to execute jobs submitted to this Queue. You may enter any valid machine name, IP address or ActiveBatch Execution Agent published name. An ActiveBatch Execution Agent published name is one that has been published via Directory services. The syntax is AD://published-name. The Browse button may be used to select a machine in your Network Neighborhood. The machine entered must be running an ActiveBatch Execution Agent. The Directory button allows you to find all published Execution Agents. By default, the client machine name is used.


80

Executing Job Limit: This field indicates the maximum number of jobs that may simultaneously execute on this Execution Queue. A number from 1 to 32767 may be selected. The default is five (5). This number should be adjusted based on the types of jobs you will be running. Please note that too high a number may have an adverse effect on overall execution machine performance.

Log Job Start/Stop to NT Event log on: This field indicates whether the Job Scheduler should log all job start and stop events to a machine’s NT event log. Clicking the checkbox enables the feature. You may further choose which machine’s event log will be used. Valid selections are: Job Scheduler, Client machine, Execution machine, Custom (a valid machine name) or None. The machine selected must be running Windows.


81

5.3.1.4 Execution Queue – Characteristics

Figure 40 – Execution Queue (Characteristics)

Machine Characteristics: This read-only section indicates the static characteristics of the machine you’ve selected for this Execution Queue. Generic Queues use this information for selecting the most appropriate execution machine for a job. This section will be blank until the Execution Queue is actually created.

User Characteristics: This section lists the current user characteristics associated with this Queue. Generic Queues use this information for selecting the most appropriate execution machine for a job. To add a user characteristic, click the Add button. To edit or remove a user characteristic, select the characteristic from the list and click the Edit or Remove buttons. See Figure 46 – Execution Queue (Add User Characteristic) for specific information on this dialog.


82

5.3.1.5 Queue – Alerts

Figure 41 – Queue Alerts

You can associate alerts with a Queue. The purpose is to potentially alert you or others in the event of a queue status change.


83

The alerts for queues are:

Alert Description

Queue Starting Queue is starting.

Queue Started Queue has started (and is operational).

Queue Stopping Queue is stopping.

Queue Stopped Queue has stopped.

Queue Connected Queue is connected to Execution Agent.

Queue Disconnected Queue is disconnected from Execution Agent.

Queue Closed Queue is closed.

Queue Opened Queue is opened.

Table 4 – Queue Alerts

Using this feature you could generate an e-mail or SNMP trap if a queue was stopped or entered a starting state.


84

5.3.1.6 Queue – Counters

Figure 42 – Queue Counters

ActiveBatch maintains performance counters for all Queue objects. The counters fall into two categories: Operational and Historical counts. Operational counts are those that accurately describe the current state of the queue. Historical counts are those that are accumulated while the product has been actively running. As the counters are statically displayed, clicking the Refresh button allows you to retrieve the latest data. Clicking the Reset Counters button allows you to zero the historical counters.


85

5.3.1.7 Queue – Audits

Figure 43 – Queue Audits

You can examine the audit trail for a queue. The audit trail contains all state changes or modifying operations made to a queue. Opening an audit item (by double-clicking on the item), depending on the nature of the audit, will sometimes reveal additional information concerning the audit. When object level auditing has been enabled, a plus sign will appear that allows you to drill down and obtain more information concerning the audit.


86

5.3.1.8 Queue – Security

Both Execution and Generic Queues share the same Security. This section indicates the security characteristics of the Queue object. The ActiveBatch Administrator may select Queue Policies for an ActiveBatch installation and those policies extend to the security system. Therefore when you create a Queue you may notice that several permissions have already been associated with the object.

To add, edit or remove security access permissions requires the user to have security access to the object.

Figure 44 – Queue Security Tab


87

This section lists all security access permissions using Windows conventions. To edit an existing account name, select the listed account and change the permission using the Type of access: list box. You may select one of the following access permissions:

Access Description

Read Account is allowed to view all properties of the queue

Write Account is allowed to write to the queue

Modify Account is allowed to read/write any properties of the queue (Read + Write)

Delete Account is allowed to delete the queue

Take Ownership Account is allowed to take ownership of the queue

Use Account is allowed to submit jobs to the queue and to create a reference to it

Manage Account is allowed to perform operations on the queue (Enable/Disable or Start/Stop, Open/Close)

Change Permissions

Account is allowed to change permissions (set security) on the queue

Full Control Account may issue all of the operations mentioned above.

Table 5 – Queue Security Access

To add a new account permission, click the Add button and follow the dialog as discussed in Section 5.3.1.9. To remove an existing account name, select the listed account and click the Remove button.

Full Control is a convenient way of granting all access permissions at one time. Any combination of access permissions is allowed. By default, ActiveBatch provides the following access permissions when a queue is created.

Administrators Full Control Authenticated Users Read, Use

The owner of a queue is the user who first creates the Queue. The Queue owner is always implicitly granted “Full Control” access. To change ownership, click the Take Ownership button (remember that in Windows you cannot specify a user to become owner, rather a user “takes” ownership).


88

5.3.1.9 Add Security Dialog

Figure 45 – Add Security Dialog (Queue)

The figure above displays the Security dialog for an ActiveBatch object. The dialog is similar to that of other Windows objects and leverages Active Directory services. The Locations button allows you to select either the Job Scheduler machine or any applicable domain. Clicking the Advanced button allows you to search for specific users and/or groups. Alternatively you may enter object names in the large edit box. Clicking the Check Names button allows you to validate the accounts. Click the OK button to add the selected Account to the object’s security list.


89

5.3.1.10 Add User Characteristic (Queue)

Figure 46 – Execution Queue (Add User Characteristic)

The above figure is displayed when you want to add or edit a user characteristic. User characteristics are uniquely named within a single queue. Typically you will add the same named user characteristic to one or more Execution Queues associated with a Generic Queue. The purpose of user characteristics is to allow a job that has been submitted to a Generic Queue to directly influence which machines should be considered eligible for running a job.

Special reserved user characteristics beginning with the prefix ABAT$ are reserved to Advanced Systems. ABAT$QAFFINITY allows a user to select a preferred execution queue when that queue is a member of a generic queue. This functionality is most appropriate when the generic queue represents a cluster.

Name: Enter a name which will represent this characteristic. The characteristic must be uniquely named only within the same queue.

Description: A description for the user characteristic.

Type: You must select whether the characteristic value is a numeric or string value.

Value: You must enter a value that will be associated with this characteristic.


90

5.3.2 Creating a Generic Queue The concept of Execution Queues is pretty straightforward. Just what is the usefulness of a Generic Queue? A Generic Queue is composed of one or more Execution Queues. An Execution Queue can be a member of one or more Generic Queues. The membership of an Execution Queue to a specific Generic Queue can be as static or dynamic as you wish. This abstraction layer between the Job and the machine that it actually runs on can be very useful. For example, you have a job that could run on one of three machines. If you submitted the job directly to an Execution Queue – that’s it. The job will only execute on that machine. If the machine isn’t available, the job will wait. A Generic Queue is similar to a virtual machine. The actual machine that will be selected can be deferred to the last moment. This means the job can execute on the most appropriate machine available. You can also specify selection criteria as well as match machine/user characteristics of the job to the machine/user characteristics of the Execution Queue. So if you need to run a job on a Pentium of at least 3 Ghz you can. Let’s examine the Generic Queue tabs and learn more about Generic Queues.

As we learned with Execution Queues, five (5) tabs are provided to define a Queue. The General, Properties, Alerts and Security tabs are common to all Queues. Audits and Counters are present once the queue is defined. So let’s concentrate on the Generic Queue Properties tab.

Figure 47 – New Generic Queue (Properties)


91

Figure 47 consists of two (2) lists: Execution Queue and related machine. For a new Generic Queue, this list will be empty. To add members to this Generic Queue, click the Associate button. A new dialog box is displayed listing all available Execution Queues for you to select. Simply select one or more Queues and click the OK button. Those queues will be added to the list. To remove existing members from this Generic Queue, simply select the member(s) and click the Disassociate button.

Scheduling Algorithm: This field indicates what algorithm should be used to dispatch jobs to eligible Execution Queues. An eligible queue is one that meets all requirements for the job and is available for execution at the moment the job is actually dispatched to an Execution Queue. Possible choices are: Sequential, Round Robin and Workload Balancing. Sequential means that the first Execution Queue is used for all job execution dispatches until the Queue has reached its maximum job limit and then the next queue is selected. Round Robin causes jobs to be dispatched to each Queue in turn. Workload Balancing causes ActiveBatch to analyze the run-time aspects of the execution machine and uses the best (least used) execution machine available. CPU and Memory are among the criteria used in workload balancing.

Regardless of Scheduling Algorithm, jobs are kept queued to the generic queue until an eligible execution queue is available to run the job. The job is then re-queued to the execution queue.


92

5.3.3 Associating/Disassociating a Member Execution Queue This operation allows you to associate/disassociate one or more Execution Queue(s) as members to/from a Generic Queue. To associate Execution Queue(s) to a Generic Queue you must select the Generic Queues Properties dialog and click the Associate button.

Figure 48 – Associating/Disassociating an Execution Queue Dialog

The main list shows all available Execution Queues. Next to each Queue is a checkbox. If the box is checked, the Queue is already a member of this Generic Queue. To add members, simply click the checkbox next to each desired Queue. When you’re done, click OK to confirm and apply your selections.

To disassociate existing members, the operations are very similar. Choose Disassociate from the menu selection. Figure 48 will appear however this time, only member Queues are listed with a clicked checkbox next to each one. To perform the disassociation, unclick the checkbox next to each Queue that you no longer want to be a member of this Generic Queue. Click OK to confirm and apply your selections.

To associate/disassociate member Queues, you must have “Manage” access permissions on the Generic Queue object.

5.3.4 Modifying a Queue Right-click on the Queue you want to modify and select Properties. One property you cannot change is the Queue’s type. Modifying a Queue requires that you have “Manage” access permission for the Queue object.


93

5.3.5 Built-in Queues Every ActiveBatch system contains several “built-in” queues. One built-in queue (found under the System plan) is required for ActiveBatch internal job processing. For example, recurring database purges help to maximize ActiveBatch performance and keep data storage requirements down. The second built-in queue is the VariableQueue. Jobs associated with this queue signify that the actual queue they will be submitted to is determined at run-time. The purpose of the VariableQueue is to allow ActiveBatch Administrators the ability to secure this powerful feature by designating those jobs as being members of the VariableQueue. The third built-in queue is the OnDemand queue. The OnDemand queue is used to defer where a job is to actually execute until the last possible moment. ActiveBatch built-in queues cannot be deleted. The objects can be renamed although their namespace label cannot be changed.

5.3.6 VariableQueue The VariableQueue allows a job designer the ability to specify the plan/job associated queue at run-time through a special ActiveBatch variable named #queue. For example, suppose Job1, running on Server1, performs some processing but then needs to tell Job2 (the next job in the stream) to execute on queue “Server2”. While we could use the Trigger facility the downside of that operation is that a new batch run will be created and no variable sharing can occur. Instead the best approach would be for Job1 to set a variable that would tell Job2 what queue to execute on. That’s the purpose of the VariableQueue and the special #queue variable. To enable #queue variable support for a job you must associate the job with the VariableQueue (this also allows ActiveBatch Administrators the ability to restrict this functionality).

With the queue set, we can now create the special #queue variable.

#queue will now be set to server2 (you should specify the full path to the object. If no path is specified, root level is assumed) and that queue will be used as the Submission Queue property for Job2.

5.3.7 OnDemand Queue ActiveBatch provides a special queue named OnDemand. The OnDemand Queue is a special type of Execution Queue that is not associated with a machine. For example, let’s say you wrote a script to start up a Windows service for a machine. If you wanted to execute the job on a specific machine you would submit the job to that machine’s Execution queue. But what if you didn’t know what machine would need to use your script until just before the job is to run? That’s the driving force behind the OnDemand queue. Jobs that are associated with the OnDemand queue enter a special “wait” state. Remember that a job definition (or template) doesn’t actually execute. Instead the instance(s) of the definition execute. Jobs that are associated with the On-Demand queue can’t create instances until a Trigger command is issued. The Advanced Trigger command provides the facility for starting an instance of a job definition and the ability to specify a queue for execution. This means you could submit the script that starts a service and then, later on, issue a Trigger command indicating what queue (machine) the job instance should execute on. The instance would be instantiated on that queue (the job definition would still be associated with the On-Demand queue). This means that you could have the


94

same script run on different queues (machines) at the same time, based “on demand”.

Note: It is important to remember that jobs never execute on the OnDemand queue. You must always trigger such jobs for execution to a different queue.

Security Implications

Since the ability to Trigger an OnDemand job is so powerful in scope, ActiveBatch provides several different access permissions for jobs which are “triggerable”. First, an ActiveBatch job must indicate that it is willing to support the ActiveBatch Trigger command. The “ActiveBatch Event Triggers” property can be found on the Scheduling/Events section of the ABATAdmin Plan/Job dialogues. This property allows you to enable or disable the potential use of this command. Most users will want to enable this feature. Next, you will want to control who can Trigger a job and what Trigger features can be enabled. If you examine Table 12 you’ll notice three (3) Trigger access permissions. Let’s discuss each in more detail.

Trigger Access

This level of access simply means that a named user or group is allowed to start the job. No other aspects of the job can be changed. Trigger level access permission alone makes little sense if you are attempting to trigger an OnDemand job since a major requirement is the ability to specify a queue for the job to execute on.

Trigger with Queue Change Access

This level of access allows a user to both trigger and specify a queue that the job instance should execute on. This access permission is what is typically granted to a user who must trigger a job associated with the OnDemand queue. The user can now both trigger and specify a queue (machine) for execution.

Typically, the author of the job will issue a Trigger command, usually from within another batch job stream that’s been written. This means the same user is issuing a Trigger from another job using the same security context. Since the Trigger command requires access permissions, a very nice benefit can be obtained from letting other users issue a Trigger command. Let’s look at our earlier example on starting a Windows service. Normally starting a service would require Administrator level access and most administrators with good reason won’t just add a user to that group even if, on occasion, there’s justification in doing so. On the other hand, what if you (an administrator) could submit a job to the OnDemand queue and allow a normal user the ability to trigger your job for execution on his machine? That way you wouldn’t have to give him your security credentials (a bad thing) and you wouldn’t have to add him to any Admin groups. That is precisely what Triggering an OnDemand job allows. You simply submit a job with your security credentials to an OnDemand queue and allow (using ActiveBatch security) one or more users to issue a “Trigger with Queue Change” access.

Trigger with Change Parameters Access

This level of access indicates that a user is allowed to trigger a template job and pass a new set of input parameters and/or variables to the job instance.

Trigger with Change Security Credentials

This level of access indicates that a user is allowed to trigger a template job and pass a set of security credentials that are to be used for this specific job instance.

By allowing different access permissions for the Trigger command, a job designer can precisely indicate what can be triggered and where the job can execute.


95

5.4 Jobs and Plans

5.4.1 What is a Job? A Job is, typically, an unattended non-interactive process that executes on a machine through an Execution Queue. While a job is usually non-interactive it need not be so. ActiveBatch supports many types of jobs. This document uses several specific terms to refer to jobs so let’s define them.

A non-recurring Job is a one-time executing job. Since the job will only execute once, a non-recurring job is also the job instance. Two (2) types of non-recurring jobs are supported: Immediate and Deferred. An immediate job is one that runs as soon as it is submitted into the system. A Deferred job is one that runs once sometime in the future.

A Template Job is a potentially recurring job. When a Template Job is triggered for execution, a Job Instance is cloned (or created) from the Template Job. It is the Job Instance that executes, not the Template Job. So a Template Job is really a definition of the job while a Job Instance is the actual running (or completed) job. The vast majority of jobs in ActiveBatch are created as Template Jobs that spawn many Job Instances over its lifetime. Throughout this manual the terms Template Job and Job Definition are synonymous.

5.4.2 What is a Plan? A Plan is an ActiveBatch object similar to a Job except that it’s also a container. Using a file system analogy, a Plan would be a folder. You can place all the other ActiveBatch objects within a Plan including other Plans. Plans provide several features:

• They provide a workspace for you to store related objects. For the most part, this means that you can store other related Jobs, Plans and any other object within a plan. Placing objects within a Plan also provides a form of isolation. For example, if you place a queue or user account object within a plan you eliminate its visibility outside the plan.

• They allow you to avoid name/label conflicts within the ActiveBatch Namespace.

• Plans can be triggered and handled as Jobs.

• New Jobs can inherit Plan policies.

• New Objects can inherit Plan policies.

• Jobs can access Plan(s) variables.

• Plans can be managed as a whole (as opposed to managing each Job within the plan).

Plans can be scheduled or triggered just as Jobs are. Plans can contain variables that can be passed to other related Jobs and Plans.

Note: While many Plans are scheduled and triggered for execution it is important to note that a Plan does not need to be executed (and can be prevented from being executed). Such a plan is called a Plan Folder and provides a policy sandbox into which you can place other plans and objects that are meant to implement a common application. A “policy sandbox” refers to a plan that is meant to only contain policies that new ActiveBatch objects placed into the plan inherit.


96

5.5 Plan Definition Plans are very similar to Jobs and they share most of the various tabs that are described in the Job Definition section of this chapter.

Note: All Plan changes are only applied when the OK button on the Plan Property sheet is clicked. If you haven’t made any changes to the Plan we recommend you click the CANCEL button to avoid unnecessary updates.

5.5.1 Plan – General

Figure 49 – Plan (General)

Figure 49 begins the definition and submission of a new plan. The dialog box is composed of several areas.

Name: This mandatory field represents the name of the Plan (to a maximum of 64 characters). While a plan name is not required to be unique, we highly recommend that you do so to avoid later confusion.

Label: This mandatory field, taken from the plan’s name, is required to be unique and is used to identify the object within the ActiveBatch namespace (maximum 64 characters). The label is typically used for scripting purposes to uniquely retrieve objects within ActiveBatch.

ID: Object ID. This is a unique number that can be used to retrieve this object.


97

Full Path: This read-only field represents the complete namespace path to the object.

Description: This optional field can contain free-form text (to a maximum of 512 characters) describing the nature and conduct of this plan. Clicking on the will cause a mini text editor to appear.

Documentation: This optional field is used to denote a reference to the plan in an operator’s runbook or other documentation concerning the running of the job (to a maximum of 80 characters). Clicking on the will cause a mini text editor to appear.

User Defined: This optional field can be set by the plan’s author as free-form text (to a maximum of 128 characters). If you set this field as a URL (for example, a hot link to runbook information for this plan) you can click the button on the right and launch your web browser with this field as a URL.

Category: This optional field is used to categorize the plan (to a maximum of 64 characters).

Group Name: This field is not used and is obsolete (it is maintained for backward compatibility purposes only). Plans are now used to associate related jobs. The maximum group name length is 64 characters.

State: This read-only field indicates whether the Plan is enabled for use.

Hide in Runbook, Gantt and Daily Activity List: This checkbox indicates whether you would like to hide this plan in the views mentioned. This can be useful when you have a plan that runs very often and would only clutter the usefulness of the other views.

Read Only: This checkbox, when enabled, means the plan’s properties cannot be changed. You must have “Modify” access permission to the Plan’s object to set this feature. To clear the read-only attribute, simply uncheck the box.

Global Disable: This checkbox indicates whether the plan is enabled. If the checkbox is set, the plan is disabled (held).


98

5.5.2 Plan – Variables

Figure 50 – Plan (Variables)

Variables are one of the most important and powerful aspects of ActiveBatch. With variables you can pass data to other related jobs as well as form constraints for proper execution of related jobs.

ActiveBatch variables represent data that can be passed to jobs, plans, programs or used anywhere variable substitution may be used within ActiveBatch. A variable can be exported to a job by enabling it as an environment variable. The figure above displays any variables associated with the plan. The figure shows a simple constant variable named app_path that is being used to specify the location of script files and/or executables that are to be executed in the nested plans and/or jobs with the plan TestDoc.

The checkbox Strict Variable Processing when selected means that all active variables must execute successfully. If even a single variable fails to evaluate, the plan/job will be terminated in failure. For more precise control, on a variable basis, please see the Use property of a variable.


99

5.5.3 Plan – Triggers/Scheduling

Figure 51 – Plan (Triggers/Scheduling)

This selection provides the ability to indicate the day/date and time a plan is to be scheduled.

Enable Date/Time Trigger: This checkbox, when enabled, allows a Plan to be scheduled to date/time and/or time specifications. Two types of date/time triggers may be used: One-Time Run and Recurring.

One Time Run: This section refers to plans that are scheduled using this trigger just once. Two types of one-time run triggers are available.

Immediately: When selected the plan is to be executed immediately.

Deferred until: When selected the plan is to wait until the date and time specified before executing.

Recurring: This section refers to plans that are scheduled on a periodic basis. Two types of recurring triggers are available.

Interval: This trigger, when selected, allows you to enter an interval expressed in days, hours and minutes. This “interval” is added to the starting execution time and forms the next time the job is to be scheduled for execution. For example, let’s say the time is now 11:00am, an interval of 1 day, 1 hour and 0 minutes would result in a next scheduled execution time of tomorrow at 12:00 (noon).

Compute Interval after Completion: This checkbox allows you to have ActiveBatch compute the next time the plan is scheduled to run by adding the interval period when the plan completes rather than


100

when the plan begins to execute. For example: Assuming a ten (10) minute interval and a five (5) minute elapsed execution time, if a plan starts to execute at 12:00 and completes at 12:05 this checkbox will schedule the next occurrence at 12:15 rather than the default of 12:10.

Schedules: This trigger, when selected, allows you to schedule a plan’s execution based on any criteria of date and time specifications. The list box shows any currently associated schedules. The buttons listed down the right side of the box allow you to associate/disassociate existing schedules, create a new schedule that you want to associate or edit a specific schedule. Section 5.12 provides more information concerning Schedules.

Run Last Missed Schedule: This field indicates whether the last “missed” schedule time should be executed. For example, let’s say a Plan was scheduled to run at 17:00 (5pm) today, but the Job Scheduler machine was down. When the Job Scheduler machine is started at 18:00 (6pm) that scheduled execution time would have been missed. With this field enabled, the Job Scheduler will execute the plan based on its last scheduled time.

Note: Only the “last” missed schedule is honored. This is true even if the plan had missed five (5) scheduled times. In other words, the plan is triggered once (not 5 times).

Time Zone to use: This field indicates the time zone to use for determining the time trigger. Possible time zones are: Job Scheduler, Client (Submitter’s machine) or UTC (Universal Time Coordinated or Greenwich Mean Time).


101

5.5.4 Plan – Triggers/Event

Figure 52 – Plan (Triggers/Events)

Event Trigger: This section deals with the creation of system and/or application event triggers. The list box summarizes all the events currently associated with the Job. Three (3) buttons are provided for adding, editing and removing events. The Add button displays the types of events you can add. See Section 5.13.2 for more information on adding, editing and removing Events.

ActiveBatch Event Triggers: When enabled, this checkbox allows use of the ActiveBatch Trigger command. The Trigger command allows authorized users to trigger the execution of a plan via command or automation. The default policy setting for this property is enabled.

Allow Deferred Event Execution: By default, when an event occurs during an “excluded” period (i.e. a period the object is not to execute) the triggering event is ignored. If this property is enabled then the triggering event is obeyed as soon as the exclusion period is over.

Note: Unlike “Run Last Missed Schedule” the above property will cause the plan to run multiple times if multiple events occurred that were missed due to the exclusion period.


102

5.5.5 Plan – Constraints/General

Figure 53 – Plan – Constraints/General Dialog This selection deals with establishing constraints (or dependencies). ActiveBatch supports several different types of constraints. A constraint is a condition that must be satisfied in order for the plan to become eligible to run. ActiveBatch groups constraints into two broad categories: General and Date/Time based. General constraints are separated into four (4) types: File, Job, Variable and Resource. A File constraint indicates whether certain files must or must not be present in order for this plan to execute. A Job constraint indicates whether certain previously executed jobs (or plans) ran successful or at all in order for this plan to execute. A Variable constraint allows you to specify an ActiveBatch active variable and perform a comparison test that, if successful, will meet this constraint condition. A Resource constraint allows you to specify an expected number of “units” this plan will require against a shared Resource object. If the resource has sufficient available units the constraint is met. If not, the constraint fails.

The large window displays all the constraints that have been specified for this plan. Three (3) buttons are provided for you to add, edit or remove constraints.

Constraint Logic: This section indicates how the various listed constraint labels should be checked and in what order. A constraint is only applied if it is listed in the logic box. You can specify arithmetic and Boolean operators to ensure that any constraints match your expectations. See Table 20 for more a complete list of operators.

If constraint logic fails: You’ll also notice several fields that control what actions should be taken if one or more constraints fail. Read Section 5.14 for more information.


103

5.5.6 Plan – Constraints/Date-Time

Figure 54 – Plan – Constraints/Date-Time Dialog

This selection allows you to exclude a triggered plan from executing based on date and/or time.

Exclusion List: This list allows you to exclude a job based on a day, date and/or time specification. For example, you could say “don’t run this job between the hours of 1am and 6am” regardless of a job’s triggers. Three (3) buttons are provided to add, edit or remove an exclusion item from the list.

Calendar: This drop down list contains all the business calendars that have been created on this ActiveBatch system. To associate business date processing with a job, simply specify the name of the calendar you want to use. Leaving the drop down as [None] means that you don’t want special business date processing. The small button to the side allows you to view the selected calendar so you can be certain it’s the one you want. The “New” button allows you to create a calendar. Specifying a calendar means that all triggers will be filtered through the calendar to determine whether the job can be allowed to execute.

If scheduled date falls on a non-business day: This selection allows you to refine your processing if the triggered date happens to fall on a non-business day. By default, you can Skip Run and skip this particular job run. Use Next Business Day means that the conflict will be resolved to the next business date. Use Previous Business Day means that the conflict will be resolved to the prior business day.


104

5.5.7 Plan – Execution/General

Figure 55 – Plan – Execution/General Dialog

This selection specifies the Plan’s execution properties.

Default credentials to use for Variable/Constraints processing: This dropdown and related buttons (Manage and New) allow you to set default credentials when using active Variables and/or Constraints at the Plan level.

If Active: This field indicates what action should be performed if an instance of this Plan is already running.

Skip: If selected, skip execution of this instance. In other words, only one instance can run.

Run Multiple: If selected, run the instance. This means multiple instances of the same plan can be running. The additional value Maximum number of active instances further allows you to indicate the maximum number of simultaneously running instances of the plan. Zero (0) means unlimited. When maximum instances are reached allows you to further refine your processing. You can elect to skip that run or wait a period of time (in seconds) before the run will be skipped.

Wait for: If selected, this instance is to wait, for a specified time (in seconds), before this run is skipped. (While you can specify zero, we recommend you specify an actual value).


105

5.5.8 Plan – Monitoring/Run-Time

Figure 56 – Plan – Monitoring/RunTime

This selection controls the ability for ActiveBatch to proactively monitor a plan’s progress and possibly terminate a plan that is running longer than expected.

Enable: This section, when enabled, allows ActiveBatch to examine the plan’s expected elapsed time and determine whether the job is operating as expected.

Set Initial expected run time: If selected, you enter a days, hours, minutes and seconds time that represents the expected plan’s elapsed run time.

Set Job run against Historical Average: If enabled, ActiveBatch will refine the plan’s initial elapsed time by using the actual run time and average it against previous successful runs. This average will become the new expected run time.

Tolerance: You can specify a tolerance that will modify the initial or average elapsed time (for the purposes of Monitoring). This tolerance can be specified as a Percent or as a Delta Time. Percent means that the over or under time period is created as a percentage of the expected run time. Delta Time is added/subtracted from the expected run time to determine the monitoring period. Three (3) fields make up this property. The Delta Job property allows you to indicate an acceptable under/overrun on elapsed time. You can enter the delta time as either a percentage or as a time specification (days, hours, minutes and seconds).


106

Abort Job if Overrun: If enabled, ActiveBatch will abort the executing job on an overrun condition. An overrun condition occurs when the expected run time plus the tolerance time values (pct or time) are exceeded.

Fail Job if Underrun: If enable, ActiveBatch will change the completion status to a failure if the plan does not run within the low end range of the monitoring period.

Reset Average: Click this button to reset any historical averaging values that ActiveBatch is retaining. This button is available when modifying an existing plan.


107

5.5.9 Plan – Alerts

Figure 57 – Plan – Alerts

This tab is used to associate various plan alerts and their corresponding actions. ActiveBatch allows you to specify alerts by either grouping alerts into an alert object and/or by individually assigning alerts to a specific plan. The benefit to an Alert object is that you can change the contents of the Alert object and by implication have those changes apply to all associated jobs. Individual plan alerts must be changed on a plan-by-plan basis.

Alert Objects: This area lists all Alert objects associated with the plan. Use of the Associate, Disassociate and Manage buttons allow you to otherwise manipulate the objects and their plan associations. See Section 5.15 for more information on creating Alert objects.

Alerts: This area lists all alerts associated with this plan. You may add, edit or remove alerts by clicking the appropriate buttons. See Section 5.15.2 for more information on setting plan alerts.


108

5.5.10 Plan – Completion – Properties

Figure 58 – Plan – Completion/Properties

This selection provides properties that concern the completion phase of a Plan. This includes restart criteria and plan history retention.

Run Once Only: Enabling this checkbox means that the Plan will execute only once.

Failure Restart Options: This section determines when and if ActiveBatch is to restart a Plan. Typically restart concerns the plan’s ability to be automatically restarted in the event of a machine failure (usually the execution machine).

On Failure: This set of radio buttons indicates what should occur if the plan fails. You may choose one of the following:

No Restart: Selecting this radio button (default) means that no special restart action should be performed if the plan fails.

Restart & Failover: This radio button if specified is treated as a Restart since a Plan instance cannot be associated with a queue.


109

Disable Template: Selecting this radio button causes the plan definition to be disabled if the plan instance completes in error.

Restart: Selecting this radio button allows a failed plan instance to be restarted on the same Execution Queue (and machine).

Restart Options:

Wait: If non-zero, the Job Scheduler will wait the specified value (in seconds) before restarting the plan. This is particularly useful if you’ve also selected “On Job Failure” recovery. By delaying the restart whatever resource exhaustion or other temporary condition that occurred may have ended.

Maximum Restarts: The radio buttons allow for an unlimited number of restarts (not recommended from a practical point-of-view) or a specific number of restarts (the acceptable value range is 1 to 999). The maximum number of restarts controls the total number of restarts attempted for this instance.

Reset on Restart: This checkbox determines whether Active Variables, if any, should be re-evaluated when the plan is restarted. If enabled, the variables are re-evaluated.

Job History: This section deals with the period of time that you elect to keep a plan’s instance history.

Delete on Completion when enabled indicates that the plan’s history is to immediately be deleted and removed from the database. This is useful when you are running the same plan many times and the actual plan history would be burdensome or otherwise obscure other more important plan history. Please note that this plan will not appear in any ActiveBatch reports.

Save Job History for: This checkbox, when enabled, indicates how long a completed plan’s history is to be retained within ActiveBatch’s database. If the feature is enabled (highly recommended), a value of 0 indicates that the next scheduled running of DBPurge should delete the plan’s history. The value specified is defined in days and an acceptable range is 0 through 366. If the checkbox is not enabled, the plan’s history will be deleted upon the next scheduled running of the DBPurge facility.


110

5.5.11 Plan – Completion – Completion Rule

Figure 59 – Plan – Completion/Completion Rule

This selection allows you to specify which jobs and/or plans should signify the completion of the plan and what exit status (if any) should be used to make that determination.

Plan Completion Rule: This dropdown provides three (3) rules: All Completed in Success, Last Completed and Custom. All Completed in Success means that all jobs/plans that have actually been run and complete successfully denote plan success. If you have nested jobs/plans that never ran (i.e. “Not Run”) those objects are not considered. Last Completed means that the last job/plan that runs to completion denotes the plan’s status. Custom allows you to specify precisely what nested jobs and/or plans should be considered for determining the plan’s completion status.

Note: Custom where you actually specify each and every job/plan that must complete is the most exact Plan Completion Rule.

When Custom is enabled, three (3) columns are present: Job, Completion Status/Exit Code and Plan Exit Code. Job is the job/plan name that runs within the plan. Completion Status/Exit Code is a specification of a job/plan status. Plan Exit Code indicates which specific plan and/or job should be used to govern the completion determination of this plan. A Yes value indicates that this selected job/plan governs the completion status of the plan.


111

5.5.12 Plan – Completion Rule

Figure 60 – Plan Completion Rule Dialog

If the Plan Completion Rule is set to Custom, the above dialog is used to select the Plan/Jobs and how they must complete for this plan to determine success.

The Job/Plan dropdown provides a selection of the nested plan/jobs.

The Above Job/Plan must complete in status: allows you to indicate how the above job or plan had to complete.


112

5.5.13 Plan – Completion – Completion Triggers

Figure 61 – Plan – Completion/Completion Triggers

This selection allows you to specify which job(s) and/or plan(s) should be triggered when this job completes. You can refine the trigger to simple success or failure; or a series or range of exit codes.

Three (3) buttons are available for you to add, edit or remove Completion Triggers. The display provides two (2) columns: Name (or Label) and Condition. The Name (or Label) identifies the Job (or Plan) that you want to trigger. The Condition identifies the criteria that you want to use when your job completes to determine which triggers are executed.

Read section 5.13.3 for more information on adding a completion trigger.


113

5.5.14 Plan – Counters

Figure 62 – Plan – Counters

The counters above are specific for this plan definition. The Reset Counters button allows you to reset the counters back to zero. The Reset Averages button allows you to reset the averages (elapsed run-tine) back to zero. The Refresh button retrieves the latest set of counters.


114

5.5.15 Plan – Audits

Figure 63 – Plan Audits

This selection allows you to view the audits that are created when the plan is initially defined. Changes made to the plan are audited as well as the creation of any plan instances. Audits covering the plan instances themselves can be found in the individual instances. The dialog provides the ability to filter audits. Audits are a good place to look when a plan runs or doesn’t run when expected because all job state information can be retrieved and examined. Opening an audit item (by double-clicking on the item), depending on the nature of the audit, will sometimes reveal additional information concerning the audit. When object level auditing has been enabled, a plus sign will appear that allows you to drill down and obtain more information concerning the audit.

The Copy to Clipboard button copies the contents of the retrieved audits into a copy buffer that you can later paste into a document or other program.

The Print… button allows you to print the retrieved audits.

The button Revision History… allows you to select one or more audits concerning changes made to an object and perform a difference operation between the selected revised objects.


115

5.5.16 Plan – History

Figure 64 – Plan History

The Plan History tab appears when a plan has already been defined. This tab provides useful information about the execution of this plan. The Plan History dialog box is separated into two areas: Revision and History.

Revision: This area indicates the number of revisions made to this plan and the date/time and user who made the last revision.

History: The properties that follow indicate how the last plan instance fared.


116

5.5.17 Plan – Security

Figure 65 – Plan Security Dialog This tab controls the security attributes associated with this Plan object.

Note: The Owner field has been omitted in the above figure so as not to reveal account/system information at Advanced Systems.

To add, edit or remove security access permissions requires the user to have “Change Permissions” access to the object.

This table lists all security access permissions using Windows conventions. To edit an existing account name, select the listed account and change the permission using the Permissions list box. You may select one of the following access permissions:


117

Access Description

Read Account is allowed to view any properties/variables of the plan (Note: Read implies both Read Properties and Read Variables).

Read Properties Account is allowed to read the properties of the plan.

Read Variables Account is allowed to read the variables of the plan.

Write Account is allowed to write to the plan.

Modify Account is allowed to read/write any properties of the plan (Read + Write).

Delete Account is allowed to delete the plan.

Take Ownership Account is allowed to take ownership of the plan.

Use Account is allowed to use the plan and to create a reference to it.

Manage Account is allowed to perform operations on the plan (Enable/Disable or Hold/Release).

Instance Control Account is allowed to perform operations on the instance (Abort, Pause/Resume, Restart, Force Run, Force Completion Status).

Create Objects Account is allowed to manipulate objects contained in the plan. This includes add, delete and move. The account must also have the necessary corresponding permissions on the underlying object itself.

Change Permissions

Account is allowed to change permissions (set security) on the plan.

Trigger User may trigger plan.

Trigger and Change Parameters

User may trigger plan and specify new or existing ActiveBatch variable(s) that override any specified at the job/plan level.

Trigger and Change Credentials

User may trigger plan and specify new security credentials that override any specified at the job/plan level.


Table 6 – Plan Security Access

To add new access permissions, click the Add button and follow the dialog as discussed in Section 5.6.4.21. To remove an existing account name, select the listed account and click the Remove button. To change existing access permissions, select the account and then select a new Permission Type (either Grant or Deny access) and a new Permission (one of the access permissions listed in the above table.

To propagate new permissions to the objects nested within a plan, enable the Replace Permission Entries… checkbox.

The owner of a plan is the user who first creates the Plan. The owner of a plan is implicitly granted Full Control access permission. To change ownership, click the Take Ownership button and confirm the resulting dialog.


118

5.5.18 Plan – Policies

This selection allows you to specify policies governing all objects that are created as part of this plan. You can specify your own defaults or values for all newly created objects. For example, if you want all jobs/plans to use the same Username Credentials you can accomplish that through a policy.

Plan policies can be broken down into two categories: Defaults and Auditing. Defaults are used to specify the default property and/or security values for new objects that are created as part of the plan. Auditing is used to establish a policy that governs what information is necessary to effectuate a given operation. For example, under ActiveBatch you could establish an audit policy that indicated that a user who wants to trigger a job or plan also specify certain mandatory information before the object can be triggered for execution.

5.5.18.1 Defaults

To enable policy defaults for the objects within a plan, right click on the desired plan and select Policy/Defaults.

Making this selection will cause the following dialog to be displayed.

Figure 66 – Object Policy Defaults

You can set policy defaults for each object above by selecting the object and then click the Set/Edit button to establish a policy for that object.


119

When a policy has been established for the object an icon appears next to the object.

In the above figure, the Job object has a policy default established. To remove an object policy, select the object and then click the Clear button. To remove all object policy defaults, click the Clear All button.

Note: Policy Defaults are applied immediately as performed

5.5.18.2 Auditing

Object level auditing allows companies to impose certain information requirements when an operation is to be performed on an object. That information then becomes a part of the object’s audit trail. To select object level auditing, right click on the desired plan and select Policy/Auditing.

Making this selection will cause the following dialog to be displayed.


120

Figure 67 – Plan Auditing

The left side of the dialog displays various operations that you can specify for additional auditing information requirements. An icon appears next to the operation when an audit has been specified. To clear all audit policies, click the Clear All button.


121

For example, in the above figure the Trigger operation has an audit specified.

Selecting the Trigger operation causes a brief display of the audit information. A required field named “Why” is to be displayed when a Trigger operation is requested.

The following operations are supported for object level auditing.

Operation Description

Add When new objects are created.

Update When an object is updated.

Trigger When a Plan or Job is triggered (specifically using the Trigger operation).

Delete When an object definition is to be deleted.

Template Operations Any operation that is specific to a definition (for example, Disable/Enable).

Instance Operations Any operation that is specific to an instance (for example, Abort, Pause/Resume, Move).

Table 7 – Audit Operations


122

To add an audit, click the Add button. To edit an existing audit, select the audit and click the Edit button. To remove an existing audit, select the audit and click the Remove button.

The dialog above appears for an Add or Edit operation. In this particular example we’re editing the “Why” audit of the Trigger operation. Three (3) fields comprise an audit: Name/Label, Description and Optional/Required.

Name/Label: This field identifies the audit field. The audit must be unique within the audits established for the operation. The name/label must also adhere to the general character set requirements established for naming an object.

Description: This field describes the audit. As you will be asking your user/operator to enter information for the audit, the description should be able to indicate what information you require.

Optional/Required: This field determines whether information must be entered by the user for the operation to be attempted. For a required field, if the information is not specified, the user will receive an error.

When the Trigger operation from the example above is issued the following audit is generated.

Figure 68 – Trigger Operation with Audit

Issuing the Trigger operation produced the above dialog. As the “Why” field is required, the user must enter information. No specific checking of the contents of the information is performed.


123

When the Trigger operation is issued an audit is produced. Look for the plus sign and expand the audit. Notice that in the above audit the “Why” field and the user’s reply are noted.

The main reason behind an audit is to ask for information as to why an operation is being requested (what’s the purpose).


124

5.5.19 Plans: How Best to Organize your Objects As you look through the ActiveBatch manuals and learn about all the various ActiveBatch objects that can be created, a question you will ultimately need to answer is “How do I best organize all the related objects that my business application needs?” This section will help you answer that question using best practices.

Suppose your application consists of three (3) Plans, four (4) execution queues, two (2) user account name objects and one (1) alert object. The three (3) Plans themselves could have contained other plans and/or jobs. One approach would be to create all those objects at “root level”. Root level is defined as the initial Job Scheduler connection level.

Another approach would be to create a Plan Folder. A Plan Folder (or container) is a plan whose sole purpose is to help organize your objects. The plan itself is never expected to actually be executed (in fact it might be critical to ensure that the plan can never be accidentally triggered). Into this Plan Folder you would place all the other objects.

For example, let’s look at CaseStudy15. This plan contains two jobs: JobA and JobB. The jobs themselves execute on a queue named “Server1” and use a user account object named “TrainingAccount”. Both “Server1” and “TrainingAccount” are root level objects. This means that 3 objects (including CaseStudy15) are defined at root level.

Let’s try a different organizational approach. Let’s define “Server1” and “TrainingAccount” so these objects are within the plan “CaseStudy15”.

Now all the objects are within CaseStudy15. This means that when I go to look for the objects used by this plan (or related plans nested within this plan) that operation can be easily performed. Deleting this plan will also delete all the related objects at the same time (which makes cleanup of my system much easier). I can also isolate my objects from the rest of the system. If I disable a user or group “List” access privilege for a plan, no one in that group will be able to see my objects including the execution queue and user account object.

Let’s examine JobA properties and specifically the “Submission Queue” property.

Note the path specification. “Server1” is within “CaseStudy15”. This specification will be the same for JobB and similar for the “TrainingAccount” object.


125

You also gain an additional capability when you organize your objects in this manner. You gain the ability to connect to a plan (or Published Plan). This is known as a “virtual root”. The figures above show the objects as they appear when connected to a Job Scheduler machine. ActiveBatch provides the capability of connecting to a Job Scheduler and a plan directly.

The connect dialog box on the left shows a connection string of “vm2003s-i1/CaseStudy15”. The first part of the connection string is the hostname (“vm2003s-i1”) the path specification is that of our plan “CaseStudy15”.

When we make this connection, look at the navigation tree (on the left) that is produced.

The plan “CaseStudy15” becomes the new root of our navigation tree (hence the term “virtual root” since the “real” root level is the Job Scheduler machine and namespace). JobA and JobB appear within the “Job & Plans” folder and the other objects appear within their respective folders. If we look at the execution properties of JobA and specifically the “Submission Queue” property we see the following:

In this case “/Server1” is relative to our new virtual root “CaseStudy15”. When a user is connected to a virtual root, that user cannot access any objects that are out-of-scope. By “out-of-scope” we mean that the objects are located at the same or higher path level of the connected to plan. As an analogy, consider the SUBST command in Windows. “SUBST D: C:\Test” creates a drive “D” that actually points to “C:\Test”. There is no capability that exists to address objects

at a higher level than C:\TEST (for example, C:\ or C:\ANOTHER-TEST are inaccessible through D:). Consider this example. Suppose I left “Server1” at the original Job Scheduler root level and then connected into the system at “vm2003s-i1\CaseStudy15”. What would the “Submission Queue” property look like then?

The above figure shows what would be displayed. While the original path specification will continue to work, it is inaccessible to the user who has connected at a “non Job Scheduler machine level”.


126

Note that if you use the pull down for access to other queue objects you will see the “inaccessible” object listed as the “Original Selection”. This “Original Selection” concept allows you to restore access to an object that you ordinally would have lacked scope to. By the way, the “Server1” that you see listed is within the CaseStudy15 plan while the “inaccessible” object refers to a Server1 that is located at the original Job Scheduler machine root level.

While visual indications are made when you access the system at a “virtual root” level you can always select the root node of the navigation tree and click on the Properties selection. You will see a subset of the Job Scheduler properties page with one important notation.

Figure 69 – Virtual Root Properties

Note the bold “Virtual Root” property. This property, displayed only for virtual root access, contains the absolute path of the plan you connected to.


127

5.5.20 Publishing a Plan ActiveBatch supports the publishing of a plan so that your users can connect to a plan rather than a Job Scheduler in a simple manner. The ability to publish a plan requires ActiveBatch Administrator access.

The figure above illustrates how you can publish a plan. First, you select the plan and then through Advanced/Publish indicate that you want to publish the plan.

The figure above indicates that the plan “CaseStudy2” is to be published under the name “CaseStudy2”. You may use any Directory Services compatible name.

Note: You do not need to publish a plan to allow direct user connected access. Users must have “List/Connect” access permission to access a plan.


128

5.6 Job Definition A Job is a process that will be executed on a machine, through its assigned Execution Queue, in a reliable and secure manner. An ActiveBatch Job can be one of several types. Usually a Job is executed in an unattended mode in that the desktop itself is not occupied with the task of running the job. In fact, with ActiveBatch, the desktop need not be logged on. Jobs in ActiveBatch can be as simple or as complex as needed to perform the tasks you need to successfully complete.

5.6.1 Batch Job Security Requirements Note: New ActiveBatch Administrators should read this section in its entirety.

Submitting a Job to ActiveBatch requires at least one Execution Queue. The creation of Execution Queues is covered in Section 5.3.1. Before we delve into the actual mechanics of submitting a Job let’s discuss some requirements. All Jobs in ActiveBatch run under a security context. Typically that context will be the submitting user’s username and password. You can specify a different username and password for execution, however, all credentials supplied are authenticated by the execution machine. As ActiveBatch supports different operating systems and platforms, different authentication is used, however, a username and password is common to all systems. Next, for Windows systems, an additional requirement must be met. The user who desires to execute a batch job on a machine must be granted the “Logon as a Batch Job” right. This right must be locally granted to the machine the job will execute on. Most users are participants of some type of domain and so their accounts are typically domain accounts. Please note that the local aspects of the “Logon as a Batch Job” right are important. A typical mistake is to grant this right at the domain level. Once again the right must be granted at the local machine level, specifically on the execution machine. The best approach is to allow the Execution Agent to automatically grant the “Logon as a Batch Job” right to users who you have already authorized as having the ability to execute batch jobs. By default, this facility is enabled as part of the ActiveBatch installation. The Execution Agent registry value “AutoRight” controls this facility (see the ActiveBatch Installation and Administration manual for more details).

If you decide to manually grant this right then you may want to consider creating an ActiveBatch local group. You can then assign the “Logon as a Batch Job” right to that group and then add members to the group. Figure 70 uses the “Local Security Policy” applet of the Administration Services group and illustrates how this would be done. Note that you must click the “Show Advanced User Rights” checkbox to obtain and set the “Log on as a batch job” right. In the example below the group ActiveBatch Users has been created and is now assigned that right on the local computer. You could now add domain members/groups to this local group to complete the required right assignment.

Note: Microsoft Windows Server 2003 machines support Kerberos sign-on through a mechanism called “Protocol Transition”. This allows a user to run a Job under his logon security credentials without having to specify a password. The advantage of this approach is that with no password to specify you don’t have to worry about password expiration, storage, etc.


129

Figure 70 – Adding the BatchLogon Right


130

5.6.2 Batch Job Files and Run-Time Considerations ActiveBatch allows you to run batch jobs across a wide range of heterogeneous platforms. As a result it’s important to note the run-time considerations that an ActiveBatch job may have across different operating systems.

First, lets consider what files may be submitted as batch job scripts. ActiveBatch supports running program images (.EXE) and, on Windows machines, any file may be specified as long as the extension has a known file association. For example, test.bat, test.vbs, test.xcp, etc. If a script file doesn’t have a known file association you can still submit the file by specifying the program that would run the file as the main input job file and the script as its input parameter. For OpenVMS machines you may run a program image (.EXE) or a Command Procedure (.COM). For UNIX machines, you may run a program image (.EXE) or a script file.

Next, depending on the operating system some operational differences may exist between the Interactive and Batch environments. This is particularly true for batch jobs submitted on Windows systems. When you log into a Windows system, the interactive logon process re-establishes any persistent network connections, runs any applications found in the Startup folder and executes a logon script if one exists. For a batch job, Windows does not perform those operations. Some aspects of Windows are inherently shared. For example, if you are logged on at the time you run your batch job your network drive letters will be visible. This may be disconcerting when you then expect those same drive letters to continue to appear even when you are no longer interactively logged in. The best practice is for your batch job to establish any operational environment needs as part of the batch job.

Operating System

Feature Description

Windows Network Connections Network drive letters are not established by Windows for batch jobs. If your batch job needs access to a network share you should either specify a UNC path (best practice) or create the network drive as part of the Batch job.

Login Script Not implicitly executed for Batch jobs.

OpenVMS F$MODE Batch.

Table 8 – Operating System Batch Job Considerations


131

When an ActiveBatch job step runs (pre, main or post) the following environment variables (or logical names) are defined. This allows your program or script access to some aspects of ActiveBatch without having to write a complicated procedure.

Variable Name Description Job Step

ABAT_JOBID The unique job id. All

ABAT_JOBNAME Job Name All

ABAT_JOBSCHED The machine name of the Job Scheduler. All

ABAT_CLIENTMACHINE The submitting user’s machine name All

ABAT_QUEUE The queue name this job is running on. All

ABAT_JOBFILE The file specification of the main job file. All

ABAT_JOBMODE The job’s mode (NORMAL) All

ABAT_CHECKPOINT Checkpoint (YES | NO) Main/Post

ABAT_CHECKPOINTVAL Checkpoint value (if ABAT_CHECKPOINT “Yes”) Main/Post

ABAT_CHECKPOINTTIME Last Checkpoint Date/Time Main/Post

ABAT_JOBEXITSEV Job Exit Severity (SUCCESS | FAILURE) Post

ABAT_JOBEXITCODE Job Exit Code (decimal) Post

ABAT_RESTART Job Restart Mode (YES | NO) All

ABAT_INSTALLPATH ActiveBatch Installation Path All

Table 9 – Environment Variables for Job Steps


132

5.6.3 Job Types ActiveBatch supports several job types to choose from when defining a job. While all jobs have many properties in common, each specific job type also has properties that are unique to that type of job. The Job types below are presented in alphabetical order.

5.6.3.1 E-Mail

The E-Mail job type is used to create and send an e-mail message. The e-mail can be composed of any available data and can make use of any embedded job properties. The composed e-mail can contain attachments. (Windows only).

5.6.3.2 FileSystem

The FileSystem job type is used to create a stream of operating system independent file system operations. For example, if you needed to create a directory and copy some files, this job type would be very useful. While you could script these operations in a simple .BAT file, the purpose of this job type is to perform these operations in an operating system independent fashion without requiring an external script.

5.6.3.3 FTP/SFTP

The FTP/SFTP job type is used to create a stream of FTP commands that are executed on a specific machine. SFTP represents a secure FTP job using public key access through SSH’s security protocol. FTPS represents a secure FTP job using SSL security protocol access.

5.6.3.4 Job Library

The Job Library job type allows you to leverage ActiveBatch logic to quickly implement jobs based on an extensible list of job features. For example, you can zip up a file, execute T-SQL or Oracle code and many other tasks. These tasks can also be combined into a mini-workflow within a single job through a series of job steps.

5.6.3.5 Process

The Process job type is the typical job used under the ActiveBatch system. A Process job consists of either a script file or an executable image that is to be run on an execution machine.

5.6.3.6 Script

This job type is the same as the Process type job except that the script is embedded as part of the job and contains no external file specification. The embedded script job is perfect when you either have a short script to write and don’t want to go to the trouble of locating it on a system or you’re not sure what machines may need this script. Since the script is transmitted to the machine on execution, you never have to worry about whether the script will be found.


133

5.6.4 Creating a Job To create a Job, either right-click on the Job Scheduler object and select New\Job or right-click on a Plan object and select New\Job.

Figure 71 – Job Definition Navigation

The figure above is displayed on the left side portion of a Job Definition. The next sections will detail each category listed. When you have completed all required information, click OK to confirm.

Note: All job changes are only applied when the OK button on the Job Property sheet is clicked. If you haven’t made any changes to the Job we recommend you click on the CANCEL button to avoid unnecessary updates.


134

5.6.4.1 Job – General

Figure 72 – Job – General

Figure 72 begins the definition and submission of a new job. The dialog box is composed of several areas.

Name: This mandatory field represents the name of the Job (to a maximum of 64 characters). While job name is not required to be unique, we highly recommend that you do so to avoid later confusion.

Label: This mandatory field, taken from the job’s name, is required to be unique and is used to identify the job object within the ActiveBatch namespace (maximum 64 characters). The label is typically used for scripting purposes to uniquely retrieve objects within ActiveBatch.

ID: This read-only field contains the object’s unique ID.


Description: This optional field can contain free-form text (to a maximum of 128 characters) describing the nature and conduct of this job.

Documentation: This optional field is used to denote a reference to the job in an operator’s runbook or other documentation concerning the running of the job (to a maximum of 128 characters).


135

User Defined: This optional field can be set by the Job’s Author as free-form text (to a maximum of 128 characters). If you set this field as a URL (for example, a hot link to runbook information for this job) you can click the … button on the right and launch your web browser with this field as a URL.

Category: This optional field is used to categorize the job (to a maximum of 128 characters).

Group Name: This field is not used and is obsolete (it is maintained for backward compatibility purposes only). Plans are used to associate related jobs. The maximum length of a group name is 64 characters.

State: This read-only field indicates whether the Job is enabled for use.

Hide in Runbook, Gantt and Daily Activity List: This checkbox indicates whether you would like to hide this plan in the views mentioned. This can be useful when you have a job that runs very often and would only clutter the usefulness of the other views.

Read Only: This checkbox, when enabled, means the job’s properties cannot be changed. You must have “Modify” access permission to the Plan’s object to set this feature. To clear the read-only attribute, simply uncheck the box.

Global Disable: This checkbox indicates whether the job is enabled. If the checkbox is set, the job is held.


136

5.6.4.2 Job – Job Properties

Figure 73 – Job – Job Properties (Process)

This dialog varies depending on the Job Type you’ve selected. The Job Type field is a drop-down listing the currently supported types: Process, E-Mail, FTP, FileSystem, Script and Jobs Library. The fields displayed are specific to the job type you’ve selected. For example, the Success Code rule is only applicable to some job types but not all.

5.6.4.2.1 Process Job Properties

Filename: This mandatory field represents the main job file (or step) that is to be executed. Unless the Copy script… checkbox is enabled, the file specification must be accessible from the eventual execution machine using this specification. A novice mistake is to specify a local drive and directory on a client machine when a different execution machine will be used to actually run the job. You can specify a UNC path for the job file specification. For frequent or recurring jobs the Job’s file should reside on the execution machine for best performance. Your security context will be used to access the file so please make certain the file is accessible by you. (Variable Substitution supported).

Copy script to execution machine: This checkbox controls whether the file specification is considered local or accessible from the client and should be copied to the Job Scheduler machine and then ultimately to the Execution machine. The file size must be less than the System policy CopyScriptMaxSize.


137

Note: If you modify the contents of a file which has been copied to the Job Scheduler/Execution Machine you must view the Job’s Properties (using AbatAdmin) and then click the OK button. This will cause ActiveBatch to check the dates of Job’s steps (Pre, Post and Main) to determine whether any of those “copied” files are to be updated.

Parameters: This optional field can be used to pass input parameters to the Job. Input parameters can also be specified dynamically via either an abatset or “TRIGGER with Parameters” command. All data specified is passed as a string with any embedded spaces entered. You may perform environment variable substitution using the syntax %var% for Windows systems and $var for UNIX systems. To perform date and time substitution within a parameter list specify one or more of the strings listed below surrounded by pound signs (#).(Variable Substitution supported).

Note: If your input parameter data expects to use the # sign as data, specifying two consecutive pound signs (##) means that one will be actually passed.

%a abbreviated weekday %p AM/PM indicator for 12-hour format (locale)

%A full weekday name %S seconds in decimal (00-59)

%b abbreviated month name %U week of year - decimal; begin Sunday (00-52)

%B full month name %w weekday in decimal (0-6; Sunday is 0)

%c date/time representation (by locale) %W week of year - decimal; begin Monday (00-52)

%d day of month in decimal (01-31) %x date representation for current locale

%H hour in 24-hour format (00-23) %X time representation for current locale

%I hour in 12-hour format (01-12) %y year without century (00-99)

%j day of year in decimal (001-366) %Y year with century in decimal

%m month in decimal (01-12) %z, %Z time-zone abbreviation or name

%M minute in decimal (00-59) %% percent sign

Table 10 – Date/Time Parameter Format Codes

For example: CUST_#%m%d%Y#.dat

might look like this when passed to a job: CUST_08302007.dat

You may insert any formatting characters within the delimited string that you also want to appear. This substitution occurs on the Execution machine. The substitution offered above supports current date and time only. If you need to perform date calculations as well as substitution you should also look at Chapter 8 for more information on Date Arithmetic.


138

Completion Status Rule: This section concerns how a job’s exit status is to be interpreted.

Success Code Rule: This field can contain keywords and numeric (decimal) exit codes all of which are interpreted as success. A range can be specified as “m-n” (for example, 0-5 means zero through 5). Several keywords are also supported: NTMsg, Odd, Even and LZero (negative). NTMsg indicates that an NT Message Code is passed back as an exit status. The upper two (2) bits indicate the severity. XLNT customers can use this type of success code rule. Odd and Even indicate status codes which are either odd or even numbers. OpenVMS uses an odd status as a success indication. Multiple codes can be specified by separating whole positive numbers and ranges with commas (for example: 0,5-10,20). This field offers a simple pull-down control with zero, NTMSG, LZERO, ODD and EVEN as quick selection choices.

Use Search String: Sometimes a program doesn’t pass a reliable exit code. By “reliable” we mean that the exit code may be the same regardless of whether the program worked or not and that the only indication of a program success (or failure) is some data that is written to the batch job’s log file. If that is the case, ActiveBatch supports the scanning of a log file or user-specified file for a string that indicates either success or failure of the job. To enable this feature, check the “Use Search String” checkbox and then click the “Setup” button. You may select whether the string represents success or failure. You may also indicate whether a case sensitive or insensitive comparison should be performed.

Clicking the Setup button produces this dialog:

Figure 74 – Success Code Rule (Search String Setup)

Search for: This field indicates the word or phrase that you want to search for. in file: This radio button allows you to either select the Job’s log file or you can specify another file to be searched. Remember that the file must be accessible from the Execution machine. Case Sensitive Search: By default, the string search is not case sensitive unless you enable this checkbox. Presence of string indicates Job failure: By default, the presence of the string indicates success. If you enable this checkbox, the presence of the string will indicate failure.

Run Job Interactively: If enabled, Windows Execution Agents will run the job on the user’s desktop. Three (3) modes are available: Normal, Maximized and Minimized. Typically, jobs are not run interactively but in background mode.

Note: Running an interactive job on a desktop does pose a security risk since the desktop user will have possible access to interactive job.

Terminate all child processes: Enabling this checkbox means that all processes created by the job are to be terminated when the job completes. For Windows 2000 (and later) systems, the job is created as a Windows Job object


139

and all children can be tracked. For UNIX systems, parent/child processes are part of the operating system. For OpenVMS systems, sub-processes are terminated regardless of the setting of this checkbox and detached processes are never terminated based on this property setting.

Pre/Post Job Steps: The fields in this section allow you to define job steps that are to execute either before and/or after the file specified above. (Variable Substitution supported).

Pre Job Filename: When enabled, the file specification entered will be executed before the main job file. This “pre” step is typically used to establish or confirm the existence of certain objects that the main step would require. For example, the presence of certain files, moving files from one machine to another, etc. The “pre” step, like the main job step, can either be a script file or a program. Unless the Copy script… checkbox is enabled, the file specification must be accessible from the execution machine. You may use the Browse button to lookup the file specification. Table 9 shows the environmental variables (OpenVMS: logical names) that a job step may query (you cannot change any of the values). The Pre job step must exit with a zero exit status to be considered successful.

Copy script to execution machine: This checkbox controls whether the pre job step file specification is considered local or accessible from the client and should be copied to the Job Scheduler machine and then ultimately to the Execution machine. The file size must be less than the System policy CopyScriptMaxSize.

Post Job Filename: When enabled, the file specification entered will always be executed after the main job file. This “post” step is typically used to either clean up any temporary or other files that are no longer necessary and/or move files to other machines. The main job step’s exit status is also provided to the “post” step. The “post” step, like the main job step, can either be a script file or a program. Unless the Copy script… checkbox is enabled, the file specification must be accessible from the execution machine. You may use the Browse button to lookup the file specification. The variables mentioned in Table 9 allow the “post” step to determine how the main job step did and to then perform success or failure processing. The “Restart” indication is also useful in that many jobs may require new copies of various files before the main step executes. With pre and post step processing such determinations no longer need to be made by the main job step. The use of COM Automation to retrieve additional information about the running job may also be used. The Post job step must exit with a zero exit status to be considered successful.

Copy script to execution machine: This checkbox controls whether the post job step file specification is considered local or accessible from the client and should be copied to the Job Scheduler machine and then ultimately to the Execution machine. The file size must be less than the System policy CopyScriptMaxSize.

Failure results in Job Failure: This checkbox controls whether a post job step failure results in marking the entire job in failure regardless of what the main job step actually did. By default, this checkbox is cleared so the results of the post job step don’t interfere with the results of the job.


140

5.6.4.2.2 E-Mail Job Properties

Figure 75 – Job – Job Properties (E-Mail)

This job type allows you to quickly compose an E-Mail message without requiring any programming or scripting. Typically this would be part of an overall job stream where you need to send an E-Mail message. Besides the ability to create an E-Mail, ActiveBatch also provides full variable substitution. This means that you can customize any portion of the E-Mail job at run-time by specifying variables within any of the E-Mail fields below. (All properties support Variable Substitution).

The properties for the E-Mail job type are those you would expect to find as part of any E-Mail.

To: This mandatory field indicates one or more users, using standard E-Mail notation, that this message is to be sent to.

CC: This optional field indicates one or more users, using standard E-Mail notation, that this message is to be sent to as a “carbon copy”.

BCC: This optional field indicates one or more users, using standard E-Mail notation, that this message is to be sent to as a “blind carbon copy”.

Subject: This optional field is the subject of the E-Mail.

Attachments: This optional field allows you to specify zero or more files which are to be sent as an attachment. As all E-Mails are generated on the Job Scheduler machine any files specified must be accessible from that machine. This may necessitate the use of UNC or other shares that the Job Scheduler service will need access to.

Message: This optional field allows you to create the “body” of the E-Mail message. Full variable substitution is available for complete customization of your message.


141

5.6.4.2.3 FTP/SFTP Job Properties

Figure 76 – Job – Job Properties (FTP)

This job type allows you to create an FTP command stream across a heterogeneous set of ActiveBatch supported platforms. The properties for the FTP job allow you to specify a destination server, security credentials and one or more FTP commands. (All properties, except Credentials, support Variable Substitution).

Server: This mandatory field allows you to specify an IP hostname or address in acceptable TCP/IP notation. A Browse button allows you to browse the network and select a machine.

Port #: This optional field allows you to specify a non-standard FTP port number. If omitted the standard FTP port number is used.

Credentials: This mandatory field is used to select a User Account object whose credentials will be used for the FTP session. The dropdown control will display all User Account objects that you have permission to use. Two buttons just to the right allow you to manage User Account objects and/or create a new one.

Protocol: This mandatory field is used to determine the security protocol used for the FTP session. A value of “None” means that standard FTP will be used. SSL2 and SSL3 represent protocols used for FTPS type processing. SSH represents a protocol used for SFTP processing. PCT and TLS are additional security protocols. “Auto” is used with SFTP to attempt to automatically determine the proper security protocol.

Commands: This area allows you to specify your FTP commands. Each command must be listed on its own separate line (with a newline character ending each line). You can cut and paste information through standard Windows hot keys.


142

5.6.4.2.4 FileSystem Job Properties

Figure 77 – Job – Job Properties (FileSystem)

This job type allows you to specify a set of File System operations without regard to the actual platform the job will execute on. This avoids the difference in syntax that many platforms have for simple commands such as Create Directory or Copy file. You can also control whether an error should be ignored or to stop processing.

The figure above provides three (3) columns for every possible file system command. The first column is Operation where each command is listed. Commands are issued in the order they are displayed. Parameters is the data portion of the command and varies depending on the nature of the command itself. All commands expect to use the file system syntax that is supported on the target platform. (Variable Substitution supported). On Failure indicates that should an error occur, whether you want the command stream to continue or stop and fail.

Three (3) buttons are available for you to Add, Edit or Remove a FileSystem operation.


143

Figure 78 – File System Operation Dialog

The above figure illustrates the properties of each FileSystem operation. The dropdown contains a list of supported commands. The Command arguments provides space for entering parameters appropriate to each command. The On Failure… radio buttons allow you to either ignore and continue processing or stop and fail the job.


144

5.6.4.2.5 Jobs Library Properties

The Jobs Library represents a set of built-in functionality in which the job designer can select a job type and obtain the benefit of that job without having to write a script. The Jobs Library also allows the creation of a multi-step job in which one or more job types can be logically constructed.

Figure 79 – Job – Job Properties (Jobs Library)

The Jobs Library does provide the ability to include the other built-in job types (for example, SFTP, E-Mail, Script, etc) as well as many more within the context of a single ActiveBatch job. Please read Section 5.7 for more information on the Jobs Library.

To add a job step click the Add button. To edit or remove an existing job step, click the Edit or Remove button. To change the execution order of a job step, select the desired job step and click Move Up or Move Down as required.


145

5.6.4.2.6 Script Job Properties

Figure 80 – Job – Job Properties (Script)

This type of job is very similar to Process except that the script is actually embedded in the job itself. No external file needs to be specified.

Script Contents: This window provides an editable view of the embedded script. To edit the script using an editor you may press one of the two buttons, located under the script window, which starts one of two editors. The “Edit using Text Editor” allows you to use your favorite text editor to create/modify the script. The “Edit using Extension’s Default Editor” starts up whatever program is associated with editing the script based on the script’s extension. (Variable Substitution supported).

Script Extension: You must specify the script’s underlying extension (i.e. VBS, PL, XCP, etc) that will be used to lookup the associated program that is eventually used to execute the script. The extension must be specified without any periods or other file system notation. (Variable Substitution supported).

Parameters: This optional field can be used to pass input parameters to the Job. Input parameters can also be specified dynamically via either an abatset or “TRIGGER with Parameters” command. All data specified is passed as a string with any embedded spaces entered. You may perform environment variable substitution using the syntax %var% for Windows systems and $var for UNIX systems. To perform date and time substitution within a parameter list specify one or more of the strings listed in Table 10 surrounded by pound signs (#). You may insert any formatting characters within the delimited string that you also want to appear. (Variable Substitution supported).


146

Completion Status: This section concerns how a job’s exit status is to be interpreted.

Success Code Rule: This field can contain keywords and numeric (decimal) exit codes all of which are interpreted as success. A range can be specified as “n-n” (for example, 0-5 means zero through 5). Several keywords are also supported: NTMsg, Odd, Even and LZero (negative). NTMsg indicates that an NT Message Code is passed back as an exit status. The upper two (2) bits indicate the severity. XLNT customers uses this type of success rule. Odd and Even indicate status codes which are either odd or even numbers. OpenVMS uses an odd status as a success indication. Multiple codes can be specified by separating whole positive numbers and ranges with commas (for example: 0,5-10,20). This field offers a simple pull-down control with zero, NTMSG, LZERO, ODD and EVEN as quick selection choices.

Use Search String: Sometimes a program doesn’t pass a reliable exit code. By “reliable” we mean that the exit code may be the same regardless of whether the program worked or not and that the only indication of a program success (or failure) is some data that is written to the batch job’s log file. If that is the case, ActiveBatch supports the scanning of a log file or user-specified file for a string that indicates either success or failure of the job. To enable this feature, check the “Use Search String” checkbox and then click the “Setup” button. You may select whether the string represents success or failure. You may also indicate whether a case-less or case sensitive comparison should be performed.

Run Job Interactively: If enabled, Windows Execution Agents will run the job on the user’s desktop. Three (3) modes are available: Normal, Maximized and Minimized. Typically, jobs are not run interactively but in background mode. Note: Running an interactive job on a desktop does pose a security risk since the desktop user will have possible access to interactive users security credentials.

Terminate all child processes: Enabling this checkbox means that all processes created by the job are to be terminated when the job completes. For Windows 2000 (and later) systems, the job is created as a Windows Job object and all children can be tracked. For UNIX systems, parent/child processes are part of the operating system. For OpenVMS systems, sub-processes are terminated regardless of the setting of this checkbox and detached processes are never terminated.


147

5.6.4.3 Job – Generic Queue Properties

Figure 81 – Job – Generic Queue Characteristics

This selection allows the job author to associate various machine and user characteristics that must match in order for the proper execution queue to be selected. This tab is only applicable when a job is associated with a Generic queue.

User and Machine Characteristics: This list box allows you to associate certain characteristics (machine and/or user) that the execution machine must have in order for the Execution Queue(s) to be considered eligible for job execution. Existing characteristics associated with this job are listed. To add, edit or remove associated machine characteristics, click the Add, Edit or Remove buttons. More information on the resulting dialogs is contained in Section 5.6.4.3.1.

Queue Selection: This field indicates an initial job-to-execution queue selection criteria. Possible choices are: Any and All (default is “Any”). “Any” means that any eligible Execution Queue members may be used to run this Job in accordance with the Generic Queue’s Scheduling Algorithm. “All” means that all eligible Execution Queue(s) members should be used to run this Job. “All” is useful when you need to broadcast an action and have it complied with on a large scale. For example, broadcasting anti-virus updates. When “All” is selected, the “If Job Active” properties are ignored.

Note: If a Job is triggered with “All” enabled, and that Job completion triggers an “Any” job; the “If Job Active” properties are not ignored. This means the triggered job may run once. If the intention is for the “broadcast” job to continue to broadcast all jobs within the stream, all jobs must be set to have “All” enabled.


148

5.6.4.3.1 Job – Machine Characteristics

Figure 82 – Machine Characteristic Dialog

This dialog appears when you want to add or edit a machine characteristic to a Job. Machine characteristics contain static information about the execution machine. The figure above indicates that the job is to run on a machine equal to 2000mhz (2 Gigahertz) in CPU speed. Machine characteristics are used by ActiveBatch when a job is submitted to a Generic Queue and the proper Execution Queue (machine) needs to be selected. This allows the author of a Job to indicate what minimum runtime requirements the job has. Remember that user/machine characteristics are ignored when a job is submitted directly to an Execution Queue.

Name: This field contains a dropdown list of the machine characteristics. The following table provides the machine characteristics that are available (see the Release Notes for any new characteristics that may have been added).

Characteristic Description

CPU (String) CPU Platform Type. (Example: Pentium)

CPUArchitecture (String) CPU Architecture. (Example: x86 or x64)

Memory (Numeric) Physical Memory Size in Mb.

CPUSpeed (Numeric) Processor Speed in Mhz. Note: Not all operating systems expose a chip’s processor speed.

OS (String) Operating System. (Example: Windows NT)

OSVersion (String) Operating System Version. (Example: V4)

OSServicePack (String) Operating System Service Pack. Note: Not all operating system’s use a Service Pack. (Example: 5)

OSBuildNumber (String) Operating System Build Number. Note: Not all operating systems use a build number. (Example: 1381)

OSType (String) Operating System Platform Type. (Example: Workstation)


149

Characteristic Description

ABATVersion (String) ActiveBatch Execution Agent Version. (Example: V5)

NumProcessors (Numeric) Number of processors

FileVersion (String) ActiveBatch version of Execution Agent

Hostname (String) Hostname of Execution Agent

IPAddress (String) IP address of Execution Agent

LicensingPoints (Numeric) Number of points for this Execution Agent

ScriptLanguage (String) Default script language extension

Table 11 – Machine Characteristics

Condition: This field allows you to select a comparison operator to be used when determining whether an Execution Queue meets the machine characteristic requirement. The following operators are available for numeric characteristics only: Equal to, Not Equal to, Less, LessEqual, Greater and GreaterEqual. If the value is a string you may only use the Equal operator.

Value: This field allows you to enter a value that will be used in the above comparison. The data entered must meet the numeric or string value requirements of the machine characteristic chosen. For example, processor speed is numeric only. For string comparison purposes any data entered is matched from left to right until the data given is matched. This means you can enter partial data (for example: “Windows” would match both “Windows 2000” and “Windows 2003”).

Note: Machine Characteristic values vary quite a bit between operating systems and hardware platforms. Please check the Release Notes that accompanies each non-Windows Execution Agent for more specific information.


150

5.6.4.3.2 Job – User Characteristics

Figure 83 – Select User Characteristics

This dialog appears when you want to add or edit a user characteristic to a Job. User characteristics contain free-form data that you determine is important to your Job. User characteristics, like machine characteristics, are used to determine the appropriate Execution Queue. The example above allows the job author to select a machine queue where the characteristic “Region” is the “Northeast”.

Name: This field contains a dropdown list of the user characteristics associated with your Execution Queues (through the Generic Queue).

Description: This field allows you to document your use of the User Characteristic.

Condition: This field allows you to select a comparison operator to be used when determining whether an Execution Queue meets the user characteristic requirement. The following operators are available for numeric characteristics only: Equal to, Not Equal to, Less, LessEqual, Greater and GreaterEqual. When a string value is specified, this field is disabled and the Equal to condition is used.

Value: This field allows you to enter a value that will be used in the above comparison. The data entered must meet the numeric or string value requirements of the user characteristic chosen. For string comparison purposes any data entered is matched, in a case-less fashion, from left to right until the string is exhausted. This means you can enter partial data (for example: “North” would match both “Northeast” and “Northwest”).


151

5.6.4.4 Job – Variables

Figure 84 – Job – Variables

Variables are one of the most important and powerful aspects of ActiveBatch. With variables you can pass data to other related jobs as well as form constraints for proper execution of related jobs. The “Value” field supports Variable Substitution.

ActiveBatch variables represent data that can be passed to jobs, plans, and programs or used anywhere variable substitution may be used within ActiveBatch. A variable can be exported to an executing job by enabling it as an environment variable.

The checkbox Strict Variable Processing when selected means that all active variables must execute successfully. If even a single variable fails, the plan/job will be terminated in failure. For more precise control, on a variable basis, please see the Use property of a variable.


152

Figure 85 – Variable Properties

ActiveBatch variables are further broken down into two (2) groups: Constant and Active. A constant ActiveBatch variable is a variable that contains a hard-coded value. An Active ActiveBatch variable (or simply “active variable”) contains a data source that populates the variable. ActiveBatch supports several data sources. For example, you could issue a SQL SELECT statement to populate an active variable.

Name/Label: This mandatory field provides the name of the variable. You can reference variables in a plan by either using self-referencing or absolute syntax. The general syntax is: ../var-name or /plan-a/var-name. The first syntax is self-referencing because the two dots mean “go up one level” from this point (job). The second syntax is absolute since you explicitly specify the variable’s path. Specifying another plan’s variable(s) in this section is how you would pass data to another job. If the variable doesn’t exist you can expect an error. Section 5.12 contains more information on the use of variables.

Description: This optional field allows you to describe the variable and its usage.

Constant: This radio button indicates that the value for the variable is a constant.


153

Active Variable: This radio button allows you to select a data source for the variable. Depending on the selection you make from the dropdown menu a set of additional properties will appear appropriate to the data source.

Figure 86 – Active Variable Data Source Menu

Properties: The set of properties will vary based on the data source selected. As you click on each property a brief help message is displayed in a small window at the bottom of the display.

Credentials: Depending on the data source you may need to specify security credentials appropriate to its successful operation. When applicable, select a User Account Name object from the dropdown list. Two small buttons allow you to manage or create a new User Account object. If the Credentials are omitted, ActiveBatch will check the plan’s variable credentials property. If that property is omitted (or the job is not executed within a plan), ActiveBatch will use the job’s execution user credential.

Use: This property indicates the criticality of the variable and whether the data source expression must succeed. This property also indicates whether a variable, if undefined, must be requested when a manual Trigger operation is performed. The value Unspecified means the variable is not critical to proper operation and to also not prompt for the variable value if a Trigger is performed. Optional also means the variable is not critical to proper operation but that ActiveBatch should prompt for a value if a Trigger is performed. If a value is not entered, the job/plan will still be triggered. Required indicates that the variable value must be defined and that it is required to be prompted for if a Trigger operation is performed.

Access: You can select whether your variables are public or private. By default, all variables are public and accessible by related Plans and Jobs. If you select Private then only the current object (Plan or Job) can access these variables.

Read Only: This checkbox selects whether the variable is read-only and may not be changed by another plan or job. By default, all variables are read/write.

Secured: This checkbox indicates whether the variable value is secret and should not be displayed (or otherwise allowed to be retrieved). Enabling this checkbox is useful if you decide to use a variable value as a password or to hold other secret or confidential information. A secured variable is a write-only property and can be changed but never retrieved. Once a variable is secured it cannot be unsecured.

Volatile: This checkbox, if enabled, means that the variable must be re-evaluated when a plan/job is executed for whatever reason (including restarts).

Export as Job Environment Variable: This checkbox controls whether the variable and value should be exported to the job instance as an environment variable (for OpenVMS this would be a logical name). By default, a variable is not exported as an environment variable.

Note: Variables declared at the job level can be exported. For other hierarchical variables to be exported they must be re-defined at the job level.


154

5.6.4.5 Job – Triggers/Scheduling

Figure 87 – Job – Scheduling This selection provides the ability to indicate the day/date and time a job (or plan) is to be scheduled.

Date/Time Trigger: This checkbox, when enabled, allows a Job to be scheduled to date and/or time specifications. Two types of date/time triggers may be used: One-Time Run and Recurring.

One Time Run: This section refers to jobs that are scheduled using this trigger just once. Two types of one-time run triggers are available (Note: If selected, ActiveBatch Event Triggers must be disabled).

Immediately: When selected the job is to be executed immediately.

Deferred until: When selected the job is to wait until the date and time specified before executing.

Recurring: This section refers to jobs that are scheduled on a periodic basis. Two types of recurring triggers are available.

Interval: This trigger, when selected, allows you to enter an interval expressed in days, hours and minutes. This “interval” is added to the starting execution time and forms the next time the job is to be scheduled for execution. For example, let’s say the time is now 11:00am, an interval of 1 day, 1 hour and 0 minutes would result in a next scheduled execution time of tomorrow at 12:00 (noon).


155

Compute Interval after Completion: This checkbox allows you to have ActiveBatch compute the next time the job is scheduled to run by adding the interval period when the job completes rather than when the job begins to execute. For example: Assuming a ten (10) minute interval and a five (5) minute elapsed execution time, if a job starts to execute at 12:00 and completes at 12:05 this checkbox will schedule the next occurrence at 12:15 rather than the default of 12:10.

Schedules: This trigger, when selected, allows you to schedule a job’s execution based on any criteria of date and time specifications. The list box shows any currently associated schedules. The buttons listed down the right side of the box allow you to associate/disassociate existing schedules, create a new schedule that you want to associate or edit a specific schedule. Section 5.12 provides much more information concerning Schedules.

Run Last Missed Schedule: This field indicates whether the last “missed” schedule time should be executed. For example, let’s say a Job was scheduled to run at 17:00 (5pm) today, but the Job Scheduler machine was down. When the Job Scheduler machine is started at 18:00 (6pm) that scheduled execution time would have been missed. With this field enabled, the Job Scheduler will execute the job based on its last scheduled time.

Time Zone to use: This field indicates the time zone to use for determining the time trigger. Possible time zones are: Job Scheduler, Client (Submitter’s machine) or UTC (Universal Time Coordinated or Greenwich Mean Time).


156

5.6.4.6 Job – Triggers/Event

Figure 88 – Job – Triggers/Events

Event Trigger: This section deals with the creation of system and/or application event triggers. The list box summarizes all the events currently associated with the Job. Three (3) buttons are provided for adding, editing and removing events. See Section 5.13.2 for more information on adding, editing and removing Events.

ActiveBatch Event Triggers: When enabled, this checkbox allows use of the ActiveBatch Trigger command and other release mechanisms such as Completion Triggers and Alerts. The Trigger command allows authorized users to trigger the execution of a job via command or automation. The default policy setting for this property is enabled.

Note: This property must be disabled if you also select to execute a job on a One Time Run basis.


157

5.6.4.7 Job – Constraints/General

Figure 89 – Job – Constraint/General Dialog This selection deals with establishing constraints (or dependencies). ActiveBatch supports several different types of constraints. A constraint is a condition that must be satisfied in order for the job to become eligible to run. ActiveBatch groups constraints into two broad categories: General and Date/Time based. General constraints are separated into four (4) types: File, Job, Variable and Resource. A File constraint indicates whether certain files must or must not be present in order for this job to execute. A Job constraint indicates whether certain previously executed jobs (or plans) ran successfully or at all in order for this job to execute. A Variable constraint allows you to specify an ActiveBatch active variable and perform a comparison test that, if successful, will meet this constraint condition. A Resource constraint allows you to specify an expected number of “units” this job will require against a shared Resource object. If the resource has sufficient available units the constraint is met; if not, the constraint fails.

The large window displays all the constraints that have been specified for this job. Three (3) buttons are provided for you to add, edit or remove constraints.

Constraint Logic: This section indicates how the various listed constraint labels should be checked and in what order. A constraint is only applied if it is listed in the logic box. You can specify arithmetic and Boolean operators to ensure that any constraints match your expectations. See Table 20 for a more complete list of operators.

Note: If a constraint is removed, you must manually remove that constraint from the Constraint Logic box.


158

If constraint logic fails: You’ll also notice several fields that control what actions should be taken if one or more constraints fail. In the example above the job JobA must complete successfully and the file casestudy2.txt (note the use of the app_path variable for additional flexibility with location) must be present for this dependency to be satisfied. If you look at the bottom of the figure you’ll see an “If constraint logic fails” specification which indicates that we should wait up to 15 minutes to determine whether the constraint failure has resolved itself. Read Section 5.14 for more information on constraints.


159

5.6.4.8 Job – Constraints/Date-Time

Figure 90 – Job – Constraints/DateTime

This selection allows you to exclude a triggered job from executing based on time and/or date.

Exclusion List: This list allows you to exclude a job based on a day, date and/or time specification. For example, you could say “don’t run this job between the hours of 1am and 6am” regardless of a job’s triggers. Three (3) buttons are provided to add, edit or remove an exclusion item from the list.

Dispatch Alert Delay: This value, expressed in minutes, indicates how long a job may wait to begin execution before it is considered “delayed” or “late”. If a delayed/late alert is associated with the job that alert would be signaled. A value of zero (0) indicates that any delay is acceptable and not subject to alert. By default, this value is 5 minutes.

Max Dispatch Time: This set of fields (days, hours and minutes) allows you to indicate the maximum on-queue time a job may wait for dispatching before the job should be canceled and not executed. For example, let’s say a job is queued for execution at 0800 with a 1 hour max dispatch time. At 0900 if the job has not transitioned from a “Pending – Queue Busy” state to another progress state, the job is aborted. This feature is particularly useful for time critical jobs which must execute within a given period of time. By default, a policy value of zeroes means that the job has an unlimited dispatch time.

Calendar: This drop down list contains all the business calendars that have been created on this ActiveBatch system. To associate business date processing with a job, simply specify the name of the calendar you want to use. Leaving the drop down as [None] means that you don’t want special business date processing. The small button to the side allows you to


160

view the selected calendar so you can be certain it’s the one you want. The “New” button allows you to create a calendar. Specifying a calendar means that all triggers will be filtered through the calendar to determine whether the job can be allowed to execute.

If scheduled date falls on a non-business day: This selection allows you to refine your processing if the triggered date happens to fall on a non-business day. By default, you can “skip run” and skip this particular job run. Use Next Business Day means that the conflict will be resolved to the next business date. Use Previous Business Day means that the conflict will be resolved to the prior business day.


161

5.6.4.9 Job – Execution/General

Figure 91 – Job – Execution/General Dialog This selection provides the Job’s execution properties.

Submission Queue: This field contains the Queue that this Job is being submitted to.

Working Directory: This optional field can contain the initial directory associated with the Job when it is executed. The directory specification must be accessible from the execution machine. By default, the user’s TEMP directory specification is used. (Variable Substitution supported).

Queue Priority: This field indicates the priority of the Job within the ActiveBatch system. The priority is used when queuing a job for submission to a named Queue. Values from 1 to 100 are acceptable. The higher the value, the higher the priority. The default for this field is 10.

O/S Priority: This field indicates the Operating System priority that should be assigned to the Job. For Windows, values of Low, BelowNormal, Normal, AboveNormal, High and Realtime are used. For non-Windows systems, a numeric value from 1 to 32 may be used.

Processor Mask: If enabled and the execution machine is multiprocessor capable, the mask is used to indicate which processors this job can use. The processor mask only applies to the main job step. The keyword ALL means all processors


162

should be used (default). To enter a specific processor(s) specify the CPU number as a comma or dashed based entry. For example, 0 means CPU 0 should be assigned. “0,2,5-7” means CPUs 0, 2, 5, 6 and 7 should be used. This property may not be supported by all operating systems so please read the Execution Agent Release Notes for applicability.

Load User Profile: If enabled, Windows Execution Agents will also load the user’s profile as part of logging the job into the system. This is useful only if the job expects to access the Registry specifically for that user (i.e. HKEY_CURRENT_USER). If your job won’t be accessing that registry hive, we recommend that you disable this property.

If Job Active: This field indicates what action should be performed if an instance of this Job is already running.

Skip: If selected, skip execution of this instance. In other words, only one instance can run.

Run Multiple: If selected, run the instance. This means multiple instances of the same job can be running. The additional value Maximum number of active instances further allows you to indicate the maximum number of simultaneously running instances of the job. Zero (0) means unlimited. When maximum instances are reached allows you to further refine your processing. You can elect to skip that run or wait a period of time (in seconds) before the run will be skipped.

Wait for: If selected, this instance is to wait, for a specified time (in seconds), before this run is skipped. (While you can specify zero (to wait forever), we recommend you specify a non-zero value).

Note: This set of properties also indicates the maximum number of instances that can be instantiated within a plan and within a batch run (or if at the root level globally).


163

5.6.4.10 Job – Execution/User Credentials

Figure 92 – Job – Execution/User Credentials

This selection allows you to specify security credentials that will be used when running this job.

User Information: If enabled, this section is where the user must enter authorization credentials for the execution machine where the job is to execute. ActiveBatch provides two (2) approaches for you to specify user security credentials. The recommend approach is to create a Username object if you intend to have multiple jobs run under a single account. The advantage to this approach is that if you need to change the user account password, you will only need to update the corresponding object as opposed to updating every job. The second approach is to assign separate user credentials on an individual job basis.

User Account Object to use

This section allows you to select a user account to associate with this job. The drop down button allows you to select from a list of accounts that you have the rights to use. Two smaller buttons to the right allow you to manage or create a User Account object. ASCI highly recommends using a User Account Object instead of embedding the Username/Password within the job itself.

User Specified (Note: Use of this section is not a “best practice”).

Username: This field contains the username account. By default, your currently connected username (and


164

domain) are used2. If this username is not applicable to the specified execution machine, specify a username that is acceptable. This field is case sensitive only if the execution machine considers the field case sensitive.

Password: This field contains the corresponding password to the above username account. The field is not displayable although a series of asterisks appears as you enter data. This field is case sensitive only if the execution machine considers the field case sensitive. You must enter data into this field unless the No Password Required checkbox is enabled or your password had been previously saved.

Reconfirm Password: This field uses the same attributes as the Password field and is present to reconfirm the unseen password. If a mismatch occurs, you will be immediately notified.

Remember Password: This checkbox allows your authorization credentials to be stored using the same facility as Windows. If this is the first time you have entered your credentials with this checkbox enabled, your security information is saved. On subsequent uses, the clicked checkbox means that ActiveBatch will retrieve and use the saved credentials. If you don’t want to use those saved credentials anymore, simply unclick the checkbox. This will cause the currently saved credentials to be removed and the ones specified will be used.

2 Typically your “connected” username will be your “logged on” username, however, ActiveBatch does allow you to connect to a Job Scheduler with different security credentials.


165

5.6.4.11 Job – Execution/Logging

Figure 93 – Job – Execution/Logging

This selection allows you to enable or disable the logging of “standard out” and/or “standard error”. Clicking on the checkbox enables the possible capture of standard output and/or error. If the checkbox is not enabled, standard output and error are not captured (no files are created).

Centrally Manage Log File: Clicking on the checkbox enables this feature. Centrally managed log files means that ActiveBatch will handle the complete specification of the log and/or error files and the directories they are created in. You can view the log file(s) from the Job History tab as well as determine where the files are located.

Retain for: This field indicates whether you want the centrally managed log file(s) to be retained for a specified period of time. Clicking the checkbox means you want the log file(s) to be retained after the job completes. The period of time is measured in days. The default is one (1) day. A value from 1 to 366 is acceptable. Not enabling this field means you want the log file(s) to be deleted after the job has completed.

Note: The retention period you specify must be less than or equal to the Job’s History Retention period property (see Completion Properties).


166

Log File Name: Clicking on the checkbox means you want the standard output file to be created. This field and centrally managed log files are mutually exclusive. For non-centrally managed files, the file specification entered must be accessible from the execution machine point-of-view. Please note that for recurring jobs, the log file specification will also have the time and date appended to the file spec for uniqueness purposes. (This is to avoid a conflict where multiple instances of the job have executed and would otherwise overwrite the log file). The default varies depending on whether the batch file was copied to the execution system. If the batch file was copied to the execution machine, the log file is created in the job’s working directory with an extension of .LOG. If the batch file was not copied to the execution machine, the log file is created in the same directory as the batch file with an extension of .LOG. (Variable Substitution supported).

Std. Error File: Clicking on the checkbox means that you want the standard error stream to be captured. A file specification must be entered if this checkbox is enabled. If omitted, a batch job’s standard error is directed to the same log file as standard output. (Variable Substitution supported).

Reuse same file: Enabling this button means that the same log file will be used for each job instance execution.

Append to same log file: Normally, when this checkbox is not enabled, a new log file is created and the log file is either unique or reuses the previous log file name (overwrite). Enabling this checkbox allows each job instance to add its log file information to the end of the previous reused log file. This feature is not available for OpenVMS and will be ignored if specified.

Log trailing ActiveBatch statistics: By default, this checkbox is enabled and ActiveBatch inserts a series of various statistics when a job completes. If this checkbox is not enabled, ActiveBatch will not insert any statistics within the job’s log file.

Interpret Exit Code: If enabled, ActiveBatch will attempt to interpret the exit status code as a possible message and provide a description in the Job’s log file. Sometimes the exit code itself is merely an artificial number that the developer uses for a success or failure indication. In this case, the value itself should not be interpreted. This checkbox has no effect on the success or failure interpretation of the exit code.


167

5.6.4.12 Job – Monitoring/Run-Time

Figure 94 – Job – Monitoring/Run-Time

This selection controls the ability for ActiveBatch to proactively monitor a job’s progress and possibly terminate a job that is running longer than expected. The example above shows an expected time of ten (10) minutes with an allowable under/over delta of ten (10) percent.

Enable: This section, when enabled, allows ActiveBatch to examine the job’s expected elapsed time and determine whether the job is operating as expected.

Set Initial expected run time: If selected, you enter days, hours, minutes and seconds time that represents the expected job’s elapsed run time.

Set Job run against Historical Average: If enabled, ActiveBatch will refine the job’s initial elapsed time by using the actual run time and average it against previous successful runs. This average will become the new expected run time.

Tolerance: You can specify a tolerance that will modify the initial or average elapsed time (for the purposes of Monitoring). This tolerance can be specified as a Percent or as a Delta Time. Percent means that the over or under time period is created as a percentage of the expected run time. Delta Time is added/subtracted from the expected run time to determine the monitoring period. Three (3) fields make up this property. The Delta Job property allows you to indicate an acceptable under/overrun on elapsed time. You can enter the delta time as either a percentage or as a time specification (days, hours, minutes and seconds).


168

Abort Job if Overrun: If enabled, ActiveBatch will abort the executing job on an overrun condition. An overrun condition occurs when the expected run time plus the tolerance time values (percent or time) are exceeded.

Fail Job if Underrun: If enabled, ActiveBatch will change the completion status to a failure if the job does not run within the low-end range of the monitoring period.

Reset Average: This button is available when modifying an existing job. Click this button to reset any historical averaging values that ActiveBatch is retaining for this job.


169

5.6.4.13 Job – Monitoring/CPU-Time

Figure 95 – Job – Monitoring/CPU-Time

This selection controls the ability for ActiveBatch to proactively monitor a job’s progress and possibly terminate a job that is using more CPU than expected.

Enable: This section, when enabled, allows ActiveBatch to examine the job’s expected CPU time and determine whether the job is operating as expected.

Set Initial expected CPU time: If selected, you enter a days, hours, minutes and seconds time that represents the expected job’s CPU time.

Set Job run against Historical Average: If enabled, ActiveBatch will refine the job’s initial CPU time by using the actual CPU time and average it against previous successful runs. This average will become the expected CPU time.

Tolerance: You can specify a tolerance that will modify the initial or average CPU time (for the purposes of Monitoring). This tolerance can be specified as a Percent or as a Delta Time. Percent means that the over or under time period is created as a percentage of the expected CPU time. Delta Time is added/subtracted from the expected CPU time to determine the monitoring period. Three (3) fields make up this property. The Delta Job property allows you to indicate an acceptable under/overrun on CPU time. You can enter the delta time as either a percentage or as a time specification (days, hours, minutes and seconds).


170

Abort Job if Overrun: If enabled, ActiveBatch will abort the executing job on an overrun condition. An overrun condition occurs when the expected run time plus the delta time values (percent or time) are exceeded.

Reset Average: This button is available when modifying an existing job. Click this button to reset any historical averaging values that ActiveBatch is retaining for this job.


171

5.6.4.14 Job – Alerts

Figure 96 – Job – Alerts This tab is used to associate various job alerts and their corresponding actions. ActiveBatch allows you to specify alerts by either grouping alerts into an alert object and/or by individually assigning alerts to a specific job. The benefit to an Alert object is that you can change the contents of the Alert object and by implication have those changes apply to all associated jobs. Individual job alerts must be changed on a job-by-job basis.

Alert Objects: This area lists all Alert objects associated with the job. Use of the Associate, Disassociate, Edit and New buttons allow you to otherwise manipulate the objects and their job associations. See Section 5.15 for more information on creating Alert objects.

Alerts: This area lists all alerts associated with this job. You may add, edit or remove alerts by clicking the appropriate buttons. See Section 5.15.2 for more information on setting job alerts.


172

5.6.4.15 Job – Completion/Properties

Figure 97 – Job – Completion Properties This selection provides properties that concern the completion phase of a Job. This includes restart criteria and job history retention.

Run Once Only: Enabling this checkbox means the Job will execute only once.

Failure Restart Options: This section determines when and if ActiveBatch is to restart a Job. Typically restart concerns the job’s ability to be automatically restarted in the event of a machine failure (usually the execution machine).

On Job Failure: This set of radio buttons indicates what should occur if the job fails. This failure does not include machine failure since a separate set of criteria can be specified for that condition. You may choose one of the following:

No Restart: Selecting this radio button (default) means that no special restart action should be performed if the job fails.

Restart & Failover: Selecting this radio button allows a failed job instance to failover back to the original Generic Queue it was submitted to for re-dispatch. This is particularly useful for Microsoft Cluster Server or any fault tolerant cluster systems. Failover is only applicable for Generic Queues. If Failover is specified and a Generic


173

Queue was not used, the job is restarted on the same machine (the same as if Restart had been specified).

Disable Template: Selecting this radio button allows you to disable the Job Definition if the instance fails.

Restart: Selecting this radio button allows a failed job instance to be restarted on the same Execution Queue (and machine).

On Machine Failure: This set of radio buttons indicates what should occur if the job fails as a result of an Execution machine failure. This failure does not include a non-machine failure since a separate set of criteria can be specified for that condition. You may choose one of the following:

No Restart: Selecting this radio button (default) means that no special restart action should be performed if the machine fails.

Restart & Failover: Selecting this radio button allows a failed job instance to failover back to the original Generic Queue it was submitted to for re-dispatch. This is particularly useful for Microsoft Cluster Server or any fault tolerant cluster systems. Failover is only applicable for Generic Queues. If Failover is specified and a Generic Queue was not used, the job is restarted on the same machine (the same as if Restart had been specified). This means that the job instance will wait until the failed machine is active and available.

Disable Template: Selecting this radio button allows you to disable the Job Definition if the instance fails.

Restart: Selecting this radio button allows a failed job instance to be restarted on the same Execution Queue (and machine). This means that the job instance will wait until the failed machine is active and available.

Restart Options:

Wait: If non-zero, the Job Scheduler will wait the specified value (in seconds) before restarting the job. This is particularly useful if you’ve also selected “On Job Failure” recovery. By delaying the restart whatever resource exhaustion or other temporary condition that occurred may have ended.

Maximum Restarts: The radio buttons allow for an unlimited number of restarts (not really recommended from a practical point-of-view) or a specific number of restarts (the acceptable value range is 1 to 999). The maximum number of restarts controls the total number of restarts attempted for this instance.

Reset on Restart: This checkbox determines whether Active Variables, if any, should be re-evaluated when the job is restarted. If enabled, the variables are re-evaluated.

Job History: This section deals with the period of time that you elect to keep a job’s instance history.

Delete on Completion when enabled indicates that the job’s history is to immediately be deleted and removed from the database. This is useful when you are running the same job many times and the actual job history would be burdensome or otherwise obscure other more important job history. Please note that this job will not appear in any ActiveBatch reports.

Save Job History for, when enabled, indicates how long a completed job’s history is to be retained within ActiveBatch’s database. If the feature is enabled (highly recommended), a value of 0 indicates that the next scheduled running of DBPurge should delete the job’s history (and log files). The value specified is defined in days and an acceptable range is 0 through 366. If the checkbox is not enabled, the job’s history will be deleted upon the next scheduled running of the DBPurge facility.


174

5.6.4.16 Job – Completion/Completion Triggers

Figure 98 – Job – Completion Triggers

This selection allows you to specify which job(s) and/or plan(s) should be triggered when this job completes. You can refine the trigger to simple success or failure; or a series or range of exit codes.

Three (3) buttons are available for you to add, edit or remove Completion Triggers. The display provides two (2) columns: Name (or Label) and Condition. The Name (or Label) identifies the Job (or Plan) that you want to trigger. The Condition identifies the criteria that you want to use when your job completes to determine which triggers are executed.

Read section 5.13.3 for more information on adding a completion trigger.


175

5.6.4.17 Job – Counters

Figure 99 – Job – Counters

The counters above are specific for this job definition. The Reset Averages button allows you to reset the average run times (both elapsed and CPU) to zero. The Reset Counters button allows you to reset the counters back to zero. The Refresh button retrieves the latest set of counters.


176

5.6.4.18 Job – Audits

Figure 100 – Job Properties – Audits

This selection allows you to view the audits that are created when a job is initially defined. Changes made to the job are audited as well as the creation of any job instances. Audits covering the job instances themselves can be found in the individual instances. The dialog provides the ability to filter audits. Audits are a good place to look when a job runs or doesn’t run when expected because all job state information can be retrieved and examined. Each audit is contained in a single line in date and time sequence. An icon appears at the beginning of each audit to help visually signal the severity of the audit. The audit trail is read only and cannot be changed by the user.

The Copy to Clipboard button copies the contents of the retrieved audits into a copy buffer so you could later paste the data into a document or other program.


The button Revision History… allows you to select one or more revisions concerning changes made to an object and perform a difference operation between the selected revised objects.


177

5.6.4.19 Job – History

Figure 101 – Job History

The Job History tab appears when a job has already been defined. This tab provides useful information about the execution of this job. The Job History dialog box is separated into two areas: Revision and Job History.

Revision: This area indicates the number of revisions made to this job and the date/time and user who made the last revision.

History: The properties that follow indicate how the last job instance fared.


178

5.6.4.20 Job – Security

Figure 102 – Job Security Dialog This tab controls the security attributes associated with this Job object. The ActiveBatch Administrator may select Job Policies for an ActiveBatch installation and these policies extend to the security system. Therefore when you create a Job you may notice that several permissions have already been associated with the object.

To add, edit or remove security access permissions requires the user to have “Change Permissions” access to the object.

This table lists all security access permissions using Windows conventions. To edit an existing account name, select the listed account and change the permission using the Permissions list box. You may select one of the following access permissions:


179

Access Description

Read Account is allowed to view any properties/variables of the job (Note: Read implies both Read Properties and Read Variables)

Read Properties Account is allowed to read the job’s properties.

Read Variables Account is allowed to read the job’s variables.

Write Account is allowed to write to the job.

Modify Account is allowed to read/write any properties of the job

Delete Account is allowed to delete the job

Take Ownership Account is allowed to take ownership of the job

Use Account is allowed to use the job and to create a reference to it

Manage Account is allowed to perform operations on the Template job (Enable/Disable)

Instance Control Account is allowed to perform operations on the instance (Abort, Pause/Resume, Restart, Force Run, Override Completion Status)

Change Permissions

Account is allowed to change permissions (set security) on the job

Trigger User may trigger job

Trigger and Change Queue

User may trigger job and direct job to execute on a specified queue

Trigger and Change Parameters

User may trigger job and specify new input parameters to job. User may also pass new ActiveBatch variable(s) that override any specified at the job or plan level

Trigger and Change Credentials

User may trigger job and specify new security credentials


Table 12 – Job Security Access

To add a new access permission, click the Add button and follow the dialog as discussed in Section 5.6.4.21. To remove an existing account name, select the listed account and click the Remove button. To change an existing access permission, select the account and then select a new Permission Type (either Grant or Deny access) and a new Permission (one of the access permissions listed in Table 12).

The owner of a job is the user who first creates the Job. The owner of a job is implicitly granted Full Control access permission. To change ownership, click the Take Ownership button and confirm the resulting dialog.


180

5.6.4.21 Job – Add Security Dialog

Figure 103 – Job Add Security Dialog Box

The figure above displays the Security dialog for an ActiveBatch object. The dialog is similar to that of other Windows objects and leverages Active Directory services. The Locations button allows you to select either the Job Scheduler machine or any applicable domain. Clicking the Advanced button allows you to search for specific users and/or groups. Alternatively you may enter object names in the large edit box. Clicking the Check Names button allows you to validate the accounts. Click the OK button to add the selected Account to the object’s security list.


181

5.7 Jobs Library The Jobs Library represents a set of built-in functionality in which the job designer can select a job type and obtain the benefit of that job without having to write a script. In this regard the “Jobs Library” is a type of ActiveBatch job (like “Process” or “Script” jobs). The Jobs Library also allows the creation of a multi-step job in which one or more job types can be logically constructed.

5.7.1 Job Type Job Type represents specific functionality (or a feature) that you want to execute as part of your ActiveBatch job. Job Types are arranged in categories for easy display. For example, the “Net” category reveals network based functionality (i.e. FTP, PING, etc). For example, if you need to SFTP a file to another machine you would select the “Net.FTP” job type. As the Jobs Library is an extensible library of job types this library will grow as new categories and/or job types are added in future servicepacks and/or major releases.

The job types themselves have several forms. One group of job types implement a specific feature, for example, SQLBlock, SFTP, ShellCommand all allow access to specific functionality without having to write a script. A second group of job types provide iteration or looping capability. For example, ForEachRow (database), ForEachFile (files), ForLoop, etc all provide looping of one or more job steps.

Figure 104 – Job Types Listing (Partial list)

The above figure shows a very partial listing of job types within the Jobs Library.


182

Job Type Description Execution Platforms

ActiveBatch ActiveBatch. The job sub-types all employ popular ActiveBatch object methods.

Windows only. ActiveBatch COM client must be installed prior to use.

Database Database. The job sub-types support both Microsoft SQL Server and Oracle family of database products. The GenericSqlBlock also supports any database for which there is an OLE/DB driver.

Windows only. The target database can be located anywhere the database vendor supports.

FileSystem File System. The job sub-types support all file system operations that are found on ActiveBatch supported platforms.

All ActiveBatch supported platforms. OpenVMS archive/unarchive does require prior ZIP (freeware) installation.

FlowControl Flow Control. The job sub-types support all types of iteration processing. Iterations provide the ability to loop through a series of job steps. Iterations can be nested.

All ActiveBatch supported platforms.

General General. The job sub-types support the ability to log an entry into the ActiveBatch job’s log file. “ShellCommand” provides the ability to issue a platform dependent shell command.

All ActiveBatch supported platforms.

Mainframe Job. This job sub-type allows the submission of a file to an IBM z/OS mainframe machine. The file is submitted to execute under the JES job control system.

Windows only. The machine must have .NET 2.0 (or later) Framework installed.

Net Network. The job sub-types support several network based commands.

E-Mail is restricted to Windows platforms. Non-secure FTP is platform independent. Secure FTP is restricted to Windows platforms. Ping is supported by all ActiveBatch platforms.

Service Service. The job sub-types support various Windows-based Service (SCM) commands.

Windows only.

Table 13 – Job Types and Supported Platforms


183

5.7.2 Job Type Properties The table which follows provides specific information on the properties that are required for each Job Type. As you click on each property a brief description appears in the lower portion of the dialog. In the “Description” section, an underlined value represents the property default if not specified.

Job Type Sub-Job Type Properties Description

ActiveBatch CloseQueue JobScheduler Job Scheduler to connect to. This can be a hostname, IP address or published name (using AD:// syntax). Default is local system.

Path Full path specification to the object (for example, /CaseStudy2/Queue1)

UserAccount User Account Name object.

DisableObject JobScheduler Job Scheduler to connect to. This can be a hostname, IP address or published name (using AD:// syntax). Default is local system.



EnableObject JobScheduler Job Scheduler to connect to. This can be a hostname, IP address or published name (using AD:// syntax). Default is local system.



Export JobScheduler Job Scheduler to connect to. This can be a hostname, IP address or published name (using AD:// syntax).


OutputFile Output file specification for XML file that contains the exported objects.

Import JobScheduler Job Scheduler to connect to. This can be a hostname, IP address or published name (using AD:// syntax). Default is local system.


InputFile Input file specification that contains an XML file created by an Export operation.

RestoreOriginalOwner True/False. Restore original owner of the object.

Verbose True/False. This property refers to logging and should only be enabled if an issue exists with the Import operation.


184


ConflictResolution Ignore/CreateCopy/UpdateIfOlder/ForceUpdate. This property controls what Import is to do is an object is already present on the Job Scheduler machine and conflicts with the import object.

OpenQueue JobScheduler Job Scheduler to connect to. This can be a hostname, IP address or published name (using AD:// syntax). Default is local system.



ReportProgress Description Progress Text. This text appears next to the job’s state.

SetVariable VariableName Variable name to set.

VariableValue Value for variable

StartQueue JobScheduler Job Scheduler to connect to. This can be a hostname, IP address or published name (using AD:// syntax). Default is local system.



StopQueue JobScheduler Job Scheduler to connect to. This can be a hostname, IP address or published name (using AD:// syntax). Default is local system.



Trigger JobScheduler Job Scheduler to connect to. This can be a hostname, IP address or published name (using AD:// syntax). Default is local system.



Variables Zero or more variable/value pairs (i.e. variable=value) for the triggered object.

WaitCompletion True/False. Indicates whether the job should wait for the triggered job to complete before continuing.

CrystalReport Report Report File Specification for Crystal Report

Parameters Parameters. One or more parameters in “param1=value1” format. Multiple parameters must be comma separated.


185


ConnectionString Database connection string using Microsoft Universal Data Language syntax.

UserAccount User Account Name object. (Note: The credentials specified are used for Database Authentication. If you are using Windows Integrated security, please leave this property blank).

OutputFormat Select an output format from the dropdown list.

Output File specification for the output file that is to be created (depending on output format chosen).

Database ForEachRow ConnectionString Database connection string using Microsoft Universal Data Language syntax.


CommandText Any valid SQL Select statement.

ContextName The name of a variable that will hold a record from the resulting record-set if the “CommandText” executes properly.

Steps One or more job steps to be executed during the ForEachRow iteration of the record-set.

GenericSQLBlock ConnectionString Database connection string using Microsoft Universal Data Language syntax.


Block Any valid SQL statements that can be properly executed using the connection provider specified in the “ConnectionString”. For T-SQL or PL/SQL code, we suggest using the vendor specific “Block” job types.

Timeout A numeric value, in seconds, that represents the amount of time the job step will wait until a “Timeout Expiration” error occurs. The default is 30 seconds. A value of zero (0) indicates that no timeout expiration will occur and should be used with caution. Note: You may consider using Run-Time Monitoring to prevent a runaway job.

Oracle.SQLBlock DataSource Oracle data source name.


186



Content Any valid PL/SQL statements that can be properly executed.

SQLServer.DTSPackage ServerName SQL Server machine name.


PackageName File path specification for the DTS package.

SQLServer.Job ServerName SQL Server machine name.


JobName Name of the job on the SQL Server Agent.

PollingInterval Time, in seconds, that ActiveBatch is to check on the executing SQL job. The default is 10 seconds.

SQLServer.SQLBlock ServerName SQL Server machine name.


Database Name of the database.

Block Any valid T-SQL statements.

Timeout A numeric value, in seconds, that represents the amount of time the job step will wait until a “Timeout Expiration” error occurs. The default is 30 seconds. A value of zero (0) indicates that no timeout expiration will occur and should be used with caution. Note: You may consider using Run-Time Monitoring to prevent a runaway job.

OutputResults If true, the SQL output will be redirected to the job’s log file. If false, the SQL output will be ignored.

SQLServer.SSISPackage ServerName SQL Server machine name.



187


PackageFileName File path specification for the SSIS package.

Variables Variables to be passed to the SSIS package.

FileSystem Archive Source The path to the file or directory that is be archived (ZIP). Specification may contain wildcard characters. Syntax is operating system dependent.

Destination Full path to the output specification that will form the archive (ZIP file). Syntax is operating system dependent.

IncludeSubFolders True/False. Indicate sub-directories?

PreservePath True/False. Indicate whether the original file path is to be preserved.

CopyFile Source The path to the file or directory that is be the source of the file copy operation. You may use wildcard characters. Syntax is operating system dependent.

Destination The path to the file or directory that is be the destination of the file copy operation. Syntax is operating system dependent.

Overwrite True/False. Should existing files be overwritten in the destination directory?

CopyFolder Source The path to the directory that is be the source of the file copy operation. You may use wildcard characters. Syntax is operating system dependent.

Destination The path to the directory that is be the destination of the file copy operation. Syntax is operating system dependent.

Overwrite True/False. Should existing files be overwritten in the destination directory?

CreateFolder Path The path to the directory that is be created. Syntax is operating system dependent.

DeleteFile FileName The path to the file that is be deleted. You may use wildcard characters. Syntax is operating system dependent.

Force True/False. Indicates whether the file should be deleted even if marked as “read-only”.

DeleteFolder Path The path to the directory that is be deleted. You may use wildcard characters. Syntax is operating system dependent.

Force True/False. Indicates whether the folder (and/or files) should be deleted even if marked as “read-only”.

ForEachFile Folder The path to the directory that is be searched. You


188


may use wildcard characters. Syntax is operating system dependent.

Recursive True/False. Should sub-directories be included in the search?

Filter FilesAndFolders/File/Folders. Indicates the scope of the search when the “pattern” property is applied.

Pattern *.*. The file pattern to be used when searching. You may use wildcard characters. Syntax is operating system dependent.

ContextName The name of a variable that will hold one of the files or directories from the resulting search.

Steps One or more job steps to be executed during the ForEachFile iteration of the resulting search.

MoveFile Source The path to the file or directory that is be the source of the file move operation. You may use wildcard characters. Syntax and operation are operating system dependent. Note: This operation will be performed as a Rename on OpenVMS.

Destination The path to the file or directory that is be the destination of the file move operation. Syntax and operation are operating system dependent.

Unarchive Source The file specification that contains the archive file (ZIP file). Specification may contain wildcard characters. Syntax is operating system dependent.

Destination Path specification into which the archived files will be placed into. Syntax is operating system dependent.

FlowControl ForEachValue List A list of string tokens separated by a “separator” character.

Separator A separator character. Default is comma.

ContextName The name of a variable that will hold one of the string tokens from the list.

Steps One or more job steps to be executed during the ForEachValue iteration.

ForLoop Start Starting value for the loop (integer). Default is 1.

End Ending value for the loop (integer). Default is 10.

Step Step value for the loop (integer). Default is 1.

ContextName The name of a variable that will hold the current iteration (loop) value.

Steps One or more job steps to be executed during the


189


ForLoop iteration.

Wait Duration Sleep duration in seconds (integer). Default is 1.

General Log Text String data written to job’s log file (similar to ECHO).

ShellCommand CommandLine Operating system dependent string that represents a shell command line.

Mainframe Job Job File The full path of the file containing the IBM Job Control Language (JCL) statements that will be submitted to the z/OS mainframe. This file must be accessible from the appropriate ActiveBatch Execution Agent. Note: The seven (7) characters of the JCL JOB statement must be the IBM username. This is required so the FTP interface can find the submitted job. For example: //IBMUSERA JOB … Where “IBMUSER” is the username of the submitted job. The job’s output log file is merged into the standard ActiveBatch log file.

HostAddress The hostname or IP address of the z/OS machine.

UserAccount An ActiveBatch Username Account object that represents the security credentials necessary to access and submit a job to the z/OS machine under JES.

Network Email To Recipient of the e-mail. Multiple destinations may be separated by a comma.

CC CC recipient of the e-mail. Multiple destinations may be separated by a comma.

BCC BCC recipient of the e-mail. Multiple destinations may be separated by a comma.

Attachments Zero or more attachments (if multiple attachments, each one must be comma separated).

Subject Subject line of the e-mail.

Message Message body of the e-mail.

FTP HostName Hostname of the FTP/SFTP/FTPS server.

Port Port number for the operation. Default is 21 (for FTP, secure FTP may vary depending on operation requested).


Script FTP script commands.

Protocol Standard/Auto/SSL3/SSL2/PCT/TLS/SSH. Standard represents standard non-secure FTP. The other


190


options will use (secure) SFTP or FTPS as specified.

IgnoreErrors True/False. Should FTP errors be ignored?

Ping HostName Hostname of the target machine.

Timeout Duration in seconds (integer) that Ping is to wait for a response. Default is 30.

Service PauseService MachineName Hostname of the target machine for the service.

ServiceName Name of the service.

Timeout Duration in seconds (integer) that the Job is to wait for the operation to complete. Default is 30.

ResumeService MachineName Hostname of the target machine for the service.



StartService MachineName Hostname of the target machine for the service.



StopService MachineName Hostname of the target machine for the service.



Figure 105 – Job Types, Sub-Types and Properties


191

5.7.3 Job Step A major part of the design of a “Jobs Library” job is that the Job Types that you select can be arranged and executed in a logical fashion. Each sub-job is actually a step or Job Step in the process. Job steps are executed in sequential order. Move Up and Move Down buttons are available to change a job step’s execution order. Several job types are available to either iterate (or loop through job steps) or perform a logical evaluation (as in an IF statement).

Figure 106 – SQL Block (Job Type)

The above figure displays the initial view of a SQL Block job step. All job steps have common properties as noted under the heading “JobStep”.

Name: The name of the job step (by default, the job type is used as the name). Naming a job step allows easier retrieval of the status of a particular job step.

ErrorAction: This property indicates what should be done if an error occurs. Three (3) options are: Continue (the next job step is executed), FailJob (the ActiveBatch job fails. This is the default), and StopSequence (used during an iteration job type to “break” the loop. If nested, the next inner loop continues, otherwise the job ends with success).

Enabled: This property controls whether this job step is enabled for execution or not. Two (2) selections are: True (enabled) or False (disabled).

The next section contains the properties of the specific job type itself. This varies by the job type you’ve chosen.

For a SQL Block job step the three (3) properties above are required. Server represents the name of the database server. Database represents the name of the database and Block represents the T-SQL code block that is to be executed.

Note: Variable substitution is supported for the properties that make up a job step.


192

Certain job types also support iteration. For example,

This is the initial dialog for the ForEachRow job step. This job allows a series of job types to be performed based on the resulting recordset that is passed back from the operation performed in the CommandText property. As the iteration loops through the recordset, the variable Row (ContextName) is used to hold one (1) row of the recordset. Note the property Steps. If you click on this property you will be able to add one or more job steps for the iteration.

Note the Steps property. Now two (2) steps have been added to the iteration. To drill down and see those two steps require that you click the button.

5.7.4 Context Variables Context variables are created as part of a job step and are specific to the job type. For example, in the above figure the context variable “Row” is used to hold a row of values during a specific iteration. Variable substitution for a context variable uses the following syntax:

$ { %context-variable }

For example, %{row} would potentially allow substitution of the context variable Row. Since Row will hold several values, Row is also a structured variable. For example, if the fields passed back from the Select statement contained; Name, Address, City, State and Zip, you would access each field using this sample syntax: %{row.name}. This would substitute the “Name” field value for this row in the recordset.

For an example on the use of the Jobs Library (and various sub-types) please read the ActiveBatch User’s manual.


193

5.8 Modifying/Viewing Plan and Job Properties To modify a Job you must hold “Modify” access permission to the Job object. To perform the modification right click on the selected Job icon and choose Propertiesr.

Figure 107 – Modifying a Job

You can only modify a Plan/Job definition. An instance cannot be changed.


194

5.9 Plan and Job Instance When you need to view a plan or job instance’s history, click on the plan/job you want instance information on. Instance information is presented in the Instances pane. You can retrieve more detailed information about an instance by selecting Properties.

Figure 108 – Instance Menu

Properties information is discussed in section 5.9.2. Selecting View Batch Run will cause an additional menu selection of List, Gantt or Graphical to be displayed. “List” causes the selected plan or job to be displayed in complete context with any other plans or jobs that were executed as part of the same Batch run. A Batch Run represents all the plans and/or jobs that were executed as part of an initial trigger. “Gantt” causes the selected plan or job to be displayed in a Gantt chart view. Graphical provides a graphic display of the instances as they executed along with their relationships.


195

5.9.1 View Batch Run This selection provides an in-context view of the selected plan or job as part of the overall Batch run. “View Batch Run” provides three (3) modes for viewing a batch run: List, Gantt or Graphical.

5.9.1.1 List View

For example:

Figure 109 – View Batch Run (List View)

Starting on the left, we’ve selected CaseStudy2 and asked for a List view. This produced a list of the instances of this plan for that day (see Instances pane on the bottom). Selecting an instance and issuing a View Batch run produced a new pane with that specific run.

You’ll notice that the plan is bold to show its position in the Batch run.


196

5.9.1.2 Gantt View

Figure 110 – View Batch Run (Gantt)

The above figure shows a Gantt chart representation of the plan and several sub-plans. One of the sub-plans failed after running for approx. 30 minutes. The Gantt chart depicts the elapsed time horizontally and allows a view of plans and/or jobs with their elapsed time with any overlap in processing.


197

5.9.1.3 Graphical View

Figure 111 – View Batch Run (Graphical View)

This selection provides a graphical display of the plans and jobs that actually executed as part of this Batch run. The green boxes indicate that the jobs ran successfully.


198

5.9.2 Instance Just as you can request the properties of a Plan or Job Definition, you can examine the properties that make up a Plan or Job Instance. To avoid confusion, ActiveBatch displays the portions of a Plan or Job that are most likely to change from run to run on separate selections. Figure 108 displays the selection menu.

5.9.2.1 History

Figure 112 – Instance Information

History is the top property selection. This tab provides most of the information you would need concerning the running or completed job. Information is broken down into categories that can be collapsed or expanded as necessary.

General Properties: This list displays current state information.

State: The current state of the instance. The state line is color coded to also visually indicate the state of the instance.

State Details: Additional information concerning the state of the job (if applicable).


199

Queue:

Execution Queue: The name of the execution queue the job ran on.

Original Submission Queue: The name of the original submission queue (for example, a Generic Queue).

Start Properties: This list displays various startup information about the instance.

Begin Execution Time: The date and time the job began execution.

Execution Reason: Why the job began execution.

Execution User: The user under whose security context the job is run.

Batch Run ID: This is the ID associated with a related stream of plans/jobs. For example, if a Plan is triggered for execution, that plan and all nested jobs/plans will have the same Batch Run ID.

Runtime Properties:

Actual Run Time: Actual elapsed time of the job.

Actual CPU Time: Actual CPU time of the job.

Checkpoint Properties:

Checkpoint Restart Enabled: This property indicates whether a checkpoint was taken. If one was, the date and time of the last checkpoint and thirty (30) characters of the checkpoint would be displayed.

Restarts:

Restarted: This property indicates whether a restart was ever performed. If one was, the date and time of the last restart and total number of restarts would also be displayed.

Completion Properties:

End Execution Time: The date and time the job completed execution.

Completion Machine: The name of the last machine that ran the job.

Completion Status: SUCCESS, FAILURE or ABORTED indication for the job.

Exit Code: This field contains the actual job exit code (decimal).

Exit Description: Unless the property “Interpret Exit Code” is disabled, ActiveBatch attempts to interpret the “job return code” as an NT Message Code (so you may need to ignore this field). Read Section 3.5 for information on how to enable or disable this feature.


200

5.9.2.2 Variables

Figure 113 – Instance (Job) Variables

The Variables tab displays all the variables and actual values assigned to each variable for this Plan or Job instance. This avoids guesswork or special tracing to determine what a particular variable was set to. When a variable is displayed with a small plus (+) sign that means that the variable represents a structure. You can expand or collapse the structure by clicking on the plus sign.


201

Show MOF Text button allows you to see the MOF text in a more readable form. MOF stands for Managed Object Format and is used by WMI to fully describe the event that occurred based on the event class that was requested when the event was created.

Figure 114 – MOF Text (File Trigger)

The window above shows the MOF text for a File Trigger event. Three (3) datum are presented. The file specification that actually caused the event is shown, the specific file action (“Created” is shown) and the time stamp (in WMI format) indicates when the event occurred.


202

Figure 115 – MOF Text (WMI)

The window above shows the (partial) MOF text for a WMI event. The complete class instance is shown.


203

5.9.2.3 Audits

Figure 116 – Instance (Job) Audits

The Audits tab displays all the ActiveBatch audits that this instance generated. Audits generated as part of the overall Plan or Job Definition would be found in those objects. This display is among the first to examine when you have a question concerning why a Plan or Job ran (or didn’t run).


204

5.9.2.4 Log

Figure 117 – Instance (Job) Log

The Log tab lets you see the output log of the Job (if enabled). If the log is small enough you can see the information in the window provided (1 megabyte is the maximum size that can be displayed in the window). Otherwise you’ll need to view the log file via the View in Editor button. The log file on a remote machine can only be displayed if it is accessible. ActiveBatch uses two (2) methods for retrieving a log file. First the log file is accessed through an ActiveBatch share that’s created at installation time. If this approach does not work, ActiveBatch will retrieve the file through the Execution Agent on the remote machine.

Log File: This field contains the actual location and log file name used by the job.

The four (4) buttons that are displayed on the left allow you to view the instance log file in several ways. By default, the log file is presented in the view area that dominates the main display. ActiveBatch attempts to access the log file directly through a UNC share, if present. If an error occurs when accessing the file via the UNC share, the destination computer where the log file resides can be placed on a UNC exclusion list. The leftmost button allows you to manipulate this exclusion list. The purpose of the list is to avoid unnecessary delays and to skip trying to access the file directly on future attempts. As you can see in the above example, the string “Log file accessed directly” shows that a UNC attempt at opening the log file succeeded. The second button from the left is the “View in Editor” button. This causes whatever text editor has been set up as your preference (default is Notepad) to be used. The third button from the left allows you to print the log file. Finally, the rightmost button allows you to refresh the log file contents that are displayed. This is particularly useful when the job is still running and producing output.

Note: The “View Log” instance menu operation takes you to this dialog tab quickly.


205

5.9.2.5 Properties

Figure 118 – Instance (Job) Properties

This tab allows you to display the rest of the Plan/Job Instance properties or you can examine the current Plan/Job Definition. While both look similar there is a very important difference. The Plan/Job Instance properties are a snapshot of the Plan/Job Definition taken when the instance was created. The current Plan/Job Definition is what that definition looks like right now which could be different than when the instance was created.


206

5.10 Reference Objects Many times when you’re designing a job stream you need to execute the same job or plan at different points in different streams. Sometimes you simply want to start with an existing plan or job and edit the object to your requirements instead of starting from scratch. ActiveBatch supports both types of actions.

When you need to execute an existing Job or Plan within different job streams you can create a reference to the object. For example, let’s say you’ve already created a job named FTPCustFiles that performs the necessary operations and you need to perform the same thing for a new and different plan. Rather than creating a copy of FTPCustFiles (which you could do) a better approach might be to create a reference to that job. This way if the job is modified, the resulting changes will be seen by both plans. To create a reference to the object (Job), simply select the object and right-click to select the Create Reference operation from the menu.

When you select this operation you should see a window similar to the one below:


207

At this point you indicate where you would like the newly created reference to appear. Typically the reference will be placed within a plan.


208

5.10.1 Reference – General Properties

Figure 119 – Reference – General

As you can see a Reference object does have its own identify apart from the object it’s referencing. In addition, since this referenced object is a Job, the Reference object can have different Triggers, Constraints, Completion Triggers, Alerts and Security as well. Figure 119 shows the General properties of a Reference object.

Name: This mandatory field represents the name of the Reference (to a maximum of 64 characters). While reference name is not required to be unique, we highly recommend that you do so to avoid later confusion.

Label: This mandatory field, taken from the reference’s name, is required to be unique and is used to identify the Reference object within the ActiveBatch namespace (maximum 64 characters). The label is typically used for scripting purposes to uniquely retrieve objects within ActiveBatch.

ID: This read-only field contains the object’s unique ID.


Description: This optional field can contain free-form text (to a maximum of 128 characters) describing the nature and conduct of this reference.

State: This read-only field indicates whether the object is enabled for use.

Read Only: This checkbox, when enabled, means the object’s properties cannot be changed. You must have “Modify” access permission to the object to set this feature. To clear the read-only attribute, simply uncheck the box.


209

5.10.2 Reference – Properties

Figure 120 – Reference – Properties

The main and only property of a Reference object is the reference to the object. As you can see this read-only field is set to the full path of the object that it is referencing (a job named “ActiveVariables” within the plan “TestDoc”). While this field cannot be directly changed, you’ll notice a small button to the right of the field. This button, when clicked, allows you to change your reference (Figure 120 is displayed to allow you to change your selection).

Property pages specific to the reference object are listed in the left-hand side navigation. These properties may be modified as appropriate. Note the “Variables” property page. This allows you to have different variable values (or methods) for the reference job and greatly expands the usefulness of the reference object.

Remember that when you modify a reference you modify all objects referencing the base object (Job/Plan). If you delete a reference only the reference to the existing Job is removed. Of course, when the last reference is deleted, the base object is deleted.


210

5.11 Plan and Job Operations for Designers While all operations are documented under the “Managing…” chapter, there are several operations that designers may need to use. Those operations are documented here as well (with a designer’s slant to the discussion).

5.11.1 Drag and Drop Drag and Drop operations are supported by ActiveBatch and are applicable only for object definitions (specifically instances are not supported). The actual operation performed depends on the source and destination. For example, if you select several Jobs and Plans and then drag and drop the selection to a Plan, the selected objects are moved to the Plan. If you select one or more Jobs and then drag them to a Queue, the Jobs are associated with the Queue. You can perform drag and drop operations using the Navigation views as well as any list-oriented view.

The table below indicates what source objects may be dragged to a destination object. Typically any selected source objects must be of the same type, a major exception to this are Jobs and Plans (called JobPlan in the table). ActiveBatch also supports use of special keys when performing drag and drop operations to modify the drop into another operation. For example, the ALT key performs a Reference operation, the CTRL key performs a Copy operation, the SHIFT key performs a MOVE operation and no key pressed performs the default operation (as per the table below).

Source Queue Schedule Calendar Plan UserAcc Alert Resource Job

Queue xxxA n/a n/a xxMx n/a xxxA n/a xxxA

Schedule n/a n/a n/a xxMA n/a n/a n/a xxxA

Calendar n/a n/a n/a xxMA n/a n/a n/a xxxA

Plan xxMx xxMA xxMA RCMM xxMA xxMA xxMA n/a

UserAcc n/a n/a n/a xxMA n/a n/a n/a xxxA

Alert xxxA n/a n/a xxMA n/a n/a n/a xxxA

Resource n/a n/a n/a xxMA n/a n/a n/a xxxA

Job xxxA xxxA xxxA RCMM xxxA xxxA xxxA n/a

JobRef n/a xxxA xxxA xCMM n/a xxxA xxxA n/a

PlanRef n/a n/a n/a xCMM n/a n/a n/a n/a

JobPlan n/a xxxA xxxA xCMM xxxA xxxA xxxA n/a

Table 14 – Drag and Drop Operations

The first column represents the source object(s) selected. The second through eight columns represent possible destinations (i.e. drop). A value of “n/a” in the table means “not allowed”. Any other value represents a possible operation. Each value shown depicts four (4) possible drag and drop operations. The first position is with the ALT key, the second is with the CTRL key, the third SHIFT key and the fourth is with no keys depressed. The individual values are as follows:

A Associate. Dragged objects are associated with the dropped object.

C Copy. Dragged objects are copied to the dropped object.

R Reference. A reference object is created on the dropped object.

M Move. Dragged objects are moved to the dropped object.

x Not allowed. Operation is not allowed.


211

5.11.2 Show Dependent Objects This operation allows you to view any objects that depend on this one. For example, if you click on a queue, you’ll see every object that depends on the queue.

Figure 121 – Show Dependent Objects

For the above queue Server1, selecting the Show Dependent Objects operation produces this list.

Figure 122 – Queue Dependent Objects

Note that a Generic Queue (GenericQueue) as well as several jobs are associated (or dependent) on this queue. This operation is particularly useful for User Account, Alerts and other objects when determining the overall usefulness of the objects you’ve created.


212

5.11.3 Copy/Paste Object Sometimes you want to create a Plan or Job using most of the information found in an existing Plan or Job. ABATAdmin let’s you do just that.

To copy an object right click on the selected con and choose Copy. You must have Read access to the object.

To paste the copied object, select the Job Scheduler icon or a plan you want the new object to be pasted at and right click to select Paste. The object will be created at that level. If the object’s label value is already present, ActiveBatch will append the word “Copy” to the object as many times as needed until unique.

5.11.4 Cut/Paste Object Sometimes you need to move a Plan or Job from one Plan to another. With Cut and Paste you can select the object and choose Cut. You must have Read and Delete access to the object.

To paste the cut object, select the Job Scheduler icon or a plan you want the object to be pasted to and right click to select Paste. The original object will be pasted at that level.

5.11.5 Delete a Plan or Job The delete operation is applicable to both Plan and Job instances and definitions. Delete implies abort but also means that the object will be removed from the ActiveBatch database. Deletions are permanent and irreversible. Delete requires Delete permission.

If you delete a Plan/Job definition you will be asked to confirm the implicit abort of all of the related instances.

Figure 123 – Delete a Template Plan Dialog

When you delete a plan or job definition, the above confirmation figure is displayed. Click Yes to confirm or No to cancel the operation.


213

5.11.6 Hold/ Release a Plan or Job Sometimes it is useful to hold a job and prevent its execution. ActiveBatch provides this operation through the Hold and Release facility.

Figure 124 – Hold/Release a Plan or Job

Disable (Hold) and Enable (Release) are in-context operations. That means that ABATAdmin will choose the proper operation for you to perform based on the state of the job. If the job is not held, you will be able to hold it. If the job is held you will be able to release it. Hold and Release, while job oriented, do require “Manage” access permission for the Queue that the job is on as well as “Read” access permission on the selected Job object. To hold or release a job either right click on the selected Plan/Job icon and choose Disable/Enable. Note the job must be in a Pending state (so you cannot hold an executing job). Holding a template job causes no new instances to be created while the template is held. You can disable an object instance whose state is “Not Run”.


214

5.11.7 Export/Import Objects ActiveBatch allows you to export an ActiveBatch object to an XML file and also provides the ability to import the object using the same XML file. This mechanism provides several features:

1. A simple method to backup/restore your ActiveBatch system.

2. Versioning control of your ActiveBatch objects (especially when combined with a source control system).

3. The ability to edit an XML file to create variants of ActiveBatch objects.

4. A simple method of transferring completed (and tested) objects from your development system to QA and/or Production ActiveBatch Job Scheduling systems.

You can export or import at any level. For example, exporting objects at the Job Scheduler level means you can save objects recursively. Exporting objects at the Plan level means you can save just the nested objects within that Plan.

5.11.7.1 Export

To export ActiveBatch objects simply right-click on the object or container (Job Scheduler or Plan) and select Export.

Figure 125 – Export Filter Dialog

The figure above allows you to filter which objects you would like to export. When you click the Export… button a file oriented dialog appears asking where you want the export file to be saved.


215

5.11.7.2 Import

To import a previously export set of ActiveBatch objects, right-click on the object or container that you would like the Import to be conducted at and select Import. Import begins by requesting the location of the import file. ActiveBatch V6 allows you to import either a V5 or V6 generated export file.

If the file is V5 based then the V5 dialog to the right will appear.

If the file is V6 based then the V6 dialog below will appear.

As with the V5 import you may enable checkboxes that: (1) Restore the original owner (or use the importing user as the new “Creator Owner”) and (2) Restore the original security that was present at the time of the export (or use the existing security and any defaults in place at the time of import). As a general rule of thumb, you will typically want to select the “Restore” options when importing to the same system you exported from. If you are importing from a previous QA system you will probably not want to elect to restore either the original owner or security settings because they are likely to be different in the new setting (for example, production). Conflict Resolution refers to what Import is to do if an existing object in present in the current system. Your choices are: Ignore (the default), Copy, Update, Force Update. Ignore causes the conflicted object(s) to be ignored and not imported. Copy causes the conflicted object to be newly created with the words “Copy of” inserted as part of the Name/Label of the object. Update causes the conflicted object to be updated with the new properties of the imported object.

5.11.8 Create Trigger Script Create Trigger Script is an operation in which a VBscript is generated that can be used to externally trigger the selected object.

5.11.9 Take Ownership Take Ownership is a security operation in which an authorized user is allowed to become the owner of an object through the action of taking ownership. Normally you would take ownership of an object through the security dialog however if you are denied object access (either explicitly or implicitly) you can’t get to the security dialog through the object properties selection. In this case, you would Take Ownership through this operation.

A user can take ownership of an object by either having the Take Ownership access permission or through the Take Ownership privilege. A user who has such privilege cannot be prevented from taking ownership if the access is explicitly specified.


216

5.11.10 Revision History Revision History allows you to compare revisions of a single object. Revision History is an Advanced menu operation as well as a clickable button on the Audit dialog of many objects.

Figure 126 – Revision History (Initial)

Starting with the top of dialog display, a filter bar is present to allow you to filter revisions to a specific date range. The Refresh button allows you to refresh the display after a filter bar change is made. The View button allows you to retrieve a specific object revision using the normal object property sheets. By default, the latest revision is marked for comparison. This can be changed through the Clear Mark and Mark Selection buttons. With the Auto-Compare on selection checkbox enabled, clicking on another revision level automatically produces a “difference” between the revisions. To manually request a comparison, disable that checkbox, make a selection and then click the Compare button. The buttons on the bottom of the dialog allow you to print or save the revision comparison.


217

Figure 127 – Revision History (Comparison)

The above figure shows a comparison of revisions 7 and 5. As you can see from the differences report, 2 properties were changed between the 2 revisions.

Object Comparer Restrictions

The following modifications will not be picked up as differences between revisions of an object. These restrictions are present within V6 and may be removed or extended in future ActiveBatch releases.

1. Alert object associations.

2. Associating an Execution Queue to a Generic queue.

3. Changing a Resource object to use an ActiveVariable. The change is noted but the specific variable used is not.


218

5.12 Variables The preceding sections have touched on the topic of ActiveBatch Variables. This section will explain this facility in more detail and also provide context for their use.

5.12.1 Definition of Variables The purpose of ActiveBatch variables is to allow: (1) data to be passed from one job to another, (2) variable data substitution within a Plan/Job, (3) to act as a constraint and (4) variable data to be exported to a job as an environment variable. Variables are declared in plans and/or jobs. Variables in a Plan can reference upper level Plans. Variables in a Job can reference upper-level Plans that the job is encapsulated within. A value for a variable can be a constant or from a data source. ActiveBatch supports a wide variety of data sources including SQL Query, WMI Query (WQL), XML, INI file, Registry as well as several others.

Note: Regardless of the data source the most important aspect to a variable is that it can be used to pass data to and from related jobs and plans.

5.12.2 Use of Variables in Jobs and Plans Specifying a variable for substitution is as simple as enclosing the variable in curly braces preceded by a dollar sign ${}. For example, a variable named app_path can be referenced by specifying ${app_path}. ActiveBatch supports variable substitution for most job/plan properties. When you specify a variable, the variable is retrieved by starting at the job level and then popping up each nested plan level until the variable is found or the last plan/job is reached. If a variable cannot be found a null (or empty) string is inserted as the substitution value. You can concatenate variables by simply locating them side by side, for example, ${app_path}${filename}. You can also navigate to another object’s variables. ../ syntax allows you to reference the nested plan that a job may be encapsulated in. For example, ${../app_path} means that you don’t want the job’s app_path declarative value but rather to begin a retrieval one level up. Dash (-) syntax allows you to reference the object that triggered the downstream object (in other words the dash allows you to reference the upstream object’s variables). For example, ${-filename} would reference the filename variable in the upstream job or plan. This syntax can also be used with built-in variables, for example, ${-@LogFileName} would reference the upstream object’s log filename. The syntax ${//var} references the starting plan or job that was triggered to begin the batch. To treat ${ as a literal simply double the substitution sequence (i.e. ${$( would yield a literal ${ ).

Note: You can nest variables by placing a space between variable name sequences. For example,

${ ${month}Password}

Where “month” is Jan, Feb, Mar, etc would yield variable names of JanPassword, FebPassword, etc. The space between the variables is critically important to avoid invoking the literal escape sequence (i.e. ${${ which would yield a literal ${ ).

To establish a new value for a variable simply declare that variable under the “Variables” section of the job. Since a job’s variables only have scope to the current job, you will need to specify the Plan’s variable that you intend to have this job modify. You can specify the Plan’s variable through either implicit access (using self-relative syntax) or explicit access (specifying the plan’s variable through a namespace specification).

To allow a variable to be exported to a running job as an environment variable remember to select the “Export as a Job Environment Variable” checkbox.


219

5.12.3 Active Variable Data Sources The “active” part of an active Variable is that of the data source. ActiveBatch supports many data sources (and the underlying facility is extensible). Active data sources include: SQL Query, WQL Query, INI file, XML file, Registry, Environment variable and built-in ActiveBatch variables. All data sources are read-only. In other words, you can only retrieve information; data cannot be written to the source. All active variables are established under the security context of the User Account Name object associated with the variable. For convenience, you can also inherit the security context of the Plan or Job rather than have to specify separate security for each variable. Some data sources allow additional security to be established apart from any Windows security. For example, a SQL query may need to specify database authentication credentials that are different from those specified with the job. The result of the data source access, if successful, is assigned to the variable. When a single result is produced, that result value is assigned to the variable. When multiple results are produced, ActiveBatch creates a structure within the variable using field names supplied by the data source. Access to the underlying members of a variable, use a notation of variable.field-name. If the access is not successful, a null string is assigned to the variable.

Figure 128 – Variable – List of Active Sources


220

5.12.4 Built-in ActiveBatch Variables ActiveBatch provides a number of built-in variables. Variables prefixed by (or that contain) a dollar sign ($) or an at-sign (@) are exclusively reserved for ActiveBatch use. To maintain upward compatibility, ABAT$ prefixed variables, denote environment variables (you should never define your own variable names using either ABAT$ or the dollar sign character).

The built-in variables that follow describe various ActiveBatch objects. They can be used wherever a variable can be specified although some variables require their use to be limited to their context. For example, you can’t use an AlertNotification variable except within an Alert. The syntax when using these variables is ${@name}. For example, ${@name} would represent the Job name depending on the context.

Name Description

JobScheduler.Name Active Directory Published Name

JobScheduler.Description Active Directory Published Description

JobScheduler.Hostname Hostname

JobScheduler.IpAddress IP Address

JobScheduler.InstallPath Installation Path of ActiveBatch software

JobScheduler.Version Version (6.n.n.n)

Table 15 – Job Scheduler Built-in Variables

Name Description

ID Instance ID

Name Plan/Job Name

Label Object label

Path Object Path

Owner Object Owner

BatchID Batch ID. Batch ID is specific to a group of related executing instances.

ExitCode Exit Code of the Plan/Job, where applicable.

ExitCodeDescription Interpretation of Exit Code (may not be correct if program uses exit codes in non-standard format).

QueueName Name of the Execution Queue

OriginalQueueName Name of original submitted queue.

TemplateID Definition or Template Object ID

LogFileName Full file specification of log file, where applicable.

CreationTime Date/Time object was created.

BeginExecutionTime Starting Execution Date/Time


221

Name Description

EndExecutionTime Ending Execution Date/Time

RestartTime Last Restart Date/Time

RestartCount Number of Restarts

ExecutionMachine Execution Machine name (Jobs only)

ExecutionUser Username that job executed as.

Template.Description Description of Job/Plan Definition

Table 16 – Job/Plan Built-in Variables

Name Description

Trigger Structure Variable. Available when a File Trigger or WMI event has occurred.

Trigger.Type Cause Plan/Job was triggered for execution. One of these (File, Wmi, DateTime, Manual).

Trigger.Username Triggered by

Trigger.Filename File Specification when trigger is “File”.

Trigger.MofText MOF Text of event when trigger is “Wmi”.

Event.DateTime Date and Time the Event occurred.

Event.ID The enumerated event id as published in abatJobAlertType.

Event.Name The corresponding event string (i.e. Succeeded, Failed, etc)

Table 17 – Event Built-in Variables


222

For those variables which have a date/time value an optional format qualifier may also be specified. The syntax is ${var:format} where format is one of the following as noted in Table 18.

Note: All times are Job Scheduler machine local except where specifically noted. Locale format means the Job Scheduler machine’s regional date/time settings as noted.

Format Output Description

<default> 2000-08-17T16:32:42 Sortable ISO

s 2000-08-17T16:32:42 Sortable ISO

S 2000-08-17T16-32-42 Sortable Filename

g 8/17/2000 4:32 PM Short date/time (Locale format, no seconds)

G 8/17/2000 4:32:42 PM Short date/time (Locale format, seconds)

f Thursday, August 17, 2000 4:32 PM Long date/time (Locale format, no seconds)

F Thursday, August 17, 2000 4:32:42 PM Long date/time (Locale format, seconds)

D Thursday, August 17, 2000 Long date (Locale format, no time)

d 8/17/2000 Short date (Locale format)

T 4:32:42 PM Short time (Locale format, seconds)

t 4:32 PM Short time (Locale format, no seconds)

u 2000-08-17T20:32:42 Sortable ISO (UTC) (Using ET as base)

U 2000-08-17T20-32-42 Sortable Filename (UTC) (Using ET as base)

Table 18 – Variable Date/Time Format

For example,

${@CreationTime:S}

would yield the value 2000-08-17T16-32-42. The following VBscript expression would retrieve the 24-hour portion:

split("${timevariable:s}", "T")(1).

5.12.5 Advanced Variable Usage Jobs can change an upper-level variable’s value by declaring that plan’s variable. Variable values can also be set through the abatset utility. This utility allows a job to pass parameters, environment variables and/or ActiveBatch variables to downstream related jobs. When a job/plan instance completes you can examine the variables that job or plan used. You can also hover over the variable as it is used in a job/plan and a “hover text” will appear with the actual value that instance used.


223

5.13 Triggers A Trigger is an action that potentially starts a job (or plan) instance (potentially only because of possible constraints). ActiveBatch supports many types of triggers: Interval, Schedule, Events, Completion Triggers and Alert Triggers.

5.13.1 Schedule Definition Job Schedules form the heart of the date/time trigger. ActiveBatch supports very flexible date/time scheduling. You can schedule both pattern (e.g. every 2 hours) and non-pattern (e.g. 1:31, 2:19) time periods. Schedules can be public or private and schedules, like other ActiveBatch objects, are securable.

Schedules are typically created as a result of submitting a Job, however, because Schedules can be used by multiple jobs, you can manage Schedules at the Job Scheduler level as well.

Figure 129 – Schedule List Dialog

The figure above lists all schedules that are associated with a Job. You will notice several action buttons on the right side. New allows you to create a brand new Schedule. Edit… allows you to edit an existing Schedule and make changes. Associate let’s you associate a schedule with a job from a list of public schedules. Disassociate let’s you disassociate a selected schedule. The last two action buttons won’t appear if you manage schedules from the Job Scheduler object.

Creating a schedule is straightforward in ActiveBatch. You just need to think about what kind of date/time triggers you need for your job(s). When you have completed a Schedule simply click OK to confirm and apply the schedule or Cancel to cancel any changes made. The Schedule is also implicitly associated with the job if the Schedule creation was


224

performed from a Job object.

Schedules can be public or private. Schedules are also securable objects. A Job can have one or more schedules associated as date/time triggers, so don’t think you need to cram every possible date and/or time pattern into one schedule.


225

5.13.1.1 Schedule – General

Figure 130 – Schedule General

This selection allows you to name and describe the Schedule object.

Name: This mandatory field represents the unique name of the Schedule.

Label: This mandatory field represents the object’s label. The label must be unique.

Description: This optional field allows you to fully describe the Schedule.

State: This read-only field indicates whether the Schedule is enabled for use.

Read Only: This checkbox indicates whether the Schedule may be modified. If selected, the Schedule is read only and may be viewed. If not selected, the Schedule may be modified (subject to object security).


226

5.13.1.2 Schedule – Time Specification

Figure 131 – Schedule Time Specification

This selection governs the time portion of a Schedule.

Three (3) radio buttons allow you to select different methods of specifying time.

Hours/Minutes: These two (2) fields allow you to specify hours and/or minutes using a single value, a series and/or a range of values. The two field values produce a union of results. For example, Hours: 6,7 Minutes: 0,15 would produce 6:00, 6:15, 7:00 and 7:15.

Exact Time: Enabling the radio button means you want to enter exact times. Typically you enter these times because they don’t fit a pattern. For example, a job needs to run at 3:14 and 9:52. To enter exact times simply enter a time value in the time control box and then click the << Add button to add the time to a list. Likewise to remove an already entered time, simply select the time from the scrollable list and click the Remove button.

Every: Enabling the radio button means you want to enter an interval time period specified by minutes and bounded by the minute. For example, 10 means a job is to execute every 10 minutes on a nn:10 minute boundary. For example, with a starting hour of 5 the possible execution times would be 5:10, 5:20, 5:30, etc. The legal range is 1-59.


227

5.13.1.3 Schedule – Day Specification/General

Figure 132 – Schedule Day Specification (General)

This selection governs the day/date portion of a Schedule. As you can see there are many ways to specify days/dates with a Schedule.

Calendar Type: This dropdown lists two (2) types of schedules: Calendar and Fiscal. Calendar (not to be confused with the Calendar object) means that dates are expressed through the standard measures of day, weeks, months and years. Fiscal means that fiscal period measurements are to be used. The button View selected days in a calendar graphically depicts the production of selected days/dates in your schedule in a visual manner.

Fiscal Specification: If fiscal type scheduling is specified, these two (2) fields indicate the start date and week-to-quarter breakdown. Base Date is the starting day in the fiscal year and Fiscal Week Breakdown/Quarter allows you to select the type of weeks to quarter period for the fiscal year.

The following radio buttons provide different methods of calculating a date. Remember that you can always create and assign multiple schedules to a single job.

Use Exact Dates Only: This selection allows you to create whatever specific dates you want as a simple list.

Daily: Enabling the radio button means you want to schedule a Job on some type of daily basis. This field allows you to enter a number of days which will be interpreted as “every n days”. For example, 1 means every day, 2 means every


228

other day, etc.

Weekly: Enabling the radio button means you want to schedule a Job on some type of weekly basis. A field and seven (7) checkboxes will appear. The field indicates the frequency as in every n week(s). So 1 means every week, 2 every other week, etc. Clicking on a checkbox means you want the job to run on that day.

Monthly: Enabling the radio button means you want to schedule a Job on some type of monthly basis. Two (2) mutually exclusive fields will appear with a third frequency field.

Day: This field represents a day in the month. A legal range is 1-31 (note that for months ending in less than 31 days, a day greater than the number of days in the month simply means the last day in the month).

The… relative… day: This field contains two controls. The first is a relative schedule whose values are: First, Second, Third, Fourth and Last. The second is days value as in: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Day, Weekday and Weekend. So you can combine the 2 fields such as Second Monday in the month or First Day in the month.

Series Days: This field allows you to specify one or more days (1-31) as a series. You may enter each day separated by a comma (for a list) and/or with a dash as a range of days. The keyword LAST indicates the last legal day of the month.

Of every… month(s): This field represents the frequency of the monthly specification. Legal values are 1-12. So 1 means every month, 2 means every other month, etc.

Quarterly: Enabling the radio button means you want to schedule a Job on a quarterly basis.

Yearly: Enabling the radio button means you want to schedule a Job on some type of yearly basis. Two (2) mutually exclusive fields will appear.

Every: These two (2) controls represent a month and day specification.

The…relative…day…of every month: This field contains three controls. The first is a relative schedule whose values are: First, Second, Third, Fourth and Last. The second is a day value as in Sunday through Saturday and Day, Weekday and Weekend. The third is a frequency expressed in a month (January through December). So: The third Saturday in January or the Last Weekday in December is easily achievable.

Series Months: This field allows you to specify one more months (1-12) as a series. You may enter each month separated by a comma (for a list) and/or with a dash as a range of months.

Series Days: This field allows you to specify one or more days (1-31) as a series. You may enter each day separated by a comma (for a list) and/or with a dash as a range of days. The keyword LAST indicates the last legal day of the month.

Custom: If enabled, you can enter a Date Arithmetic specification (see Section 8.2. for more details). Using Date Arithmetic you can compute a date of your choosing.


229

5.13.1.4 Schedule – Exact Dates

Figure 133 – Schedule Day Specification (Exact Dates)

This selection, if enabled, allows you to specify exact dates. The dates can be in month/day or month/day/year fashion. This selection will only be used if Use Exact Dates has been specified as part of the Day Specification.


230

5.13.1.5 Schedule – Range Specification

Figure 134 – Schedule Range Specification

This section indicates the effective date and time range this Schedule should be considered active.

Start Date: By default the starting date is today’s date and time. You can however specify a different starting date and time.

End Date: You can either indicate that the Schedule is not to have an end date or you can specify an exact ending date and time. Note that even though a schedule may no longer be used for scheduling based on the effective date/time range, the schedule is not removed from the system and can always be modified to become effective once again.


231

5.13.1.6 Schedule – Audits

Figure 135 – Schedule Audits

This section details any changes made to the schedule object.

The controls at the top of the dialog allow you to filter the audits based on a starting/ending date. You can also limit the audits retrieved to a maximum number. The refresh button allows you to retrieve any audits that were generated after this dialog was initially displayed.





232

5.13.1.7 Schedule – Security

Figure 136 – Schedule Security

As with other object security the dialog above lists the existing permissions of any accounts that have specified access to the Schedule. The following table lists the access rights and their descriptions.


233

Access Description

Read User is allowed to read the object.

Write User is allowed to write to the object.

Modify User is allowed to modify the object.

Delete User is allowed to delete the object.

Use Account is allowed to use the object and to create a reference to it.

Take Ownership

User is allowed to take ownership.

Change Permissions

User is allowed to change permissions for the object.

Full Control All of the above access is enabled.

Table 19 – Schedule Access


234

5.13.1.8 Copying a Schedule

To copy a Schedule and make changes to the newly created object, select the Schedule and select the Copy operation. You must have “Read” access permission to the Schedule object.

5.13.1.9 Editing a Schedule

To edit an existing Schedule, select the Schedule and select the Properties operation. You must have “Write” access permission to the Schedule object.

5.13.1.10 Deleting a Schedule

To delete an existing Schedule, select the Schedule and select the Delete operation. A confirmation message box will appear asking you to confirm the deletion. You must have “Delete” access permission to the Schedule object. Note: Deleting a Schedule will automatically disassociate the Schedule from all jobs which are referencing it.


235

5.13.1.11 Associate/Disassociate

To associate an existing Schedule with a Plan or Job, select the Schedule and then select the Associate operation. The Associations dialog is used for objects other than Schedules.

Figure 137 – Associations Dialog

The objects are listed with the checkbox enabled, meaning the object is already associated, or with the checkbox clear, meaning the object may be associated. Objects with a plus sign (+) are plans (and may have schedule objects nested within the plan). To associate an object, mark the checkbox as enabled. To disassociate an object, clear the marked checkbox.


236

5.13.2 Event Triggers ActiveBatch supports the integrated use of Microsoft Windows Management Instrumentation or WMI. WMI provides a common collection point for a diverse set of sources. WMI is Microsoft’s implementation of Web Based Enterprise Management (WBEM). ActiveBatch is both an Event Provider and Event Consumer. First, the ActiveBatch Job Scheduler publishes a list of ActiveBatch events that it provides to WMI. ActiveBatch is also an Event Consumer. This means that ActiveBatch can register for any interested events and is notified by WMI when they occur. This section discusses the consumer aspects of ActiveBatch.

Figure 138 – Event Trigger Dialog

Note: WMI must be installed on the Job Scheduler machine for you to issue WMI Event triggers.


237

ActiveBatch allows job authors to indicate the events that a job may be interested in and can trigger execution of the job when the event occurs. After completing the requested information, click OK to confirm and apply or click Cancel to cancel any addition or changes to the list of event(s).

The dialog box requests that a WMI query be entered. For maximum flexibility, ActiveBatch supports the use of WQL (WMI Query Language, similar in syntax to SQL). Two (2) types of events are supported: System Startup and WMI.

WMI Event. Enter WQL string below: This mandatory field takes a valid WQL statement describing the event you’re interested in. All WQL statements begin with SELECT. You are not restricted in what you can enter however, you should not specify polling intervals that would adversely impact ActiveBatch and/or system performance. The example above shows a WQL query requesting an event be triggered each time a new NT Event Log entry is created (written to the NT Event Log).

Namespace: You must indicate the namespace to connect to. The Namespace specification is: \\machine\namespace, for example, ROOT\CIMV2 is the namespace for the local machine and \\TEST\ROOT\CIMV2 is the namespace for the TEST machine.

Privileges: This button allows you to enable or disable privileges that the selected WMI provider will use to execute your query.

Advanced: This button allows you to enable security credentials which are only required when entering an event query for a remote machine.

System Startup: Clicking this radio button indicates that when the Job Scheduler machine is started the job should now run.

File Trigger: Clicking this radio button indicates that when the named file or a file within the directory has one or more of the specified operations performed, an event trigger should be invoked. Supported file operations through the Filter are: Create, Modified, Deleted and Appeared. By default, the creation operation is enabled. File Event is therefore especially helpful when you want to trigger a job based on the creation of a file. Appeared is useful when a new file may be created in another directory and then later moved to the target directory. Windows IIS server uses this technique when downloading a file. You can specify a specific file or a directory specification. For example, if you want to trigger a Job based upon the reception of a file through FTP, the trigger will occur only after FTP has populated the file. Please note that the “Modified” operation is subject to certain limitations imposed by Windows. In particular file size and date processing may not be timely due to caching considerations. Recursive refers to whether the specified directory should also include any nested sub-directories. If enabled, sub-directories are included. Queue and User may be specified if you wish to monitor directories and/or files on remote non-Windows machines. If neither is specified, ActiveBatch assumes a Windows file specification will be monitored.

Note: All file specifications are evaluated from the Job Scheduler machine’s point-of-view. Note: If using the Delete file operation, please note that some Windows facilities (i.e. DOS/CMD) use the short-form filename for these operations. This means you must also use the short form name for the proper pattern matching.

Note: File Triggers performed on Windows use the Directory Change Notification facility. This facility does have limitations in terms of the number of outstanding directories that may be watched as well as the number of outstanding file triggers at any one time that may be executed. For more information, please read the Knowledge Base articles “File Trigger Session Limitations” and “File Triggers and simultaneous events”. The “File Trigger Session Limitations” article in particular also references the Microsoft article that speaks to various quotas that may need to be increased. This is especially true if you intend to watch or access over 100 file trigger events.

File Triggers performed on a non-Windows system use a built-in polling mechanism to determine directory changes. By default the poll is thirty (30) seconds. Users must ensure that directories to be watched do not contain thousands of file for optimum performance.


238

Expected Date/Times: This facility, when enabled, allows you to associate a date and time with an expected event. By default, an event may occur at any time and no date/time expectations are set. This means views such as the Daily Activity View, the Runbook or Gantt Chart are meaningless for such jobs and plans since no date or time expectations are shown. When you enable this facility you can associate one or more schedule objects that allow you to set expectations as to when the plan/job is expected to run. The Delta field allows further flexibility for setting up an expected time envelope for your plan/job.

Figure 139 – Expected Date/Time (Initial)

To use the facility, enable the Expected Date/Times checkbox (within the Events dialog box. This dialog appears for all event types (WMI, File Trigger and System Startup). Two (2) buttons will become active; Associate (if you have an existing Schedule object) and New. ActiveBatch leverages the Schedule object for its date and time capability. Note: That in this usage the Schedule object will not produce date and time triggers but rather date and time expectations.

The settings above depict a Schedule object named Daily11pm which produces a daily time expectation of 11pm. Combined with the Delta property of one (1) hour this effectively produces an expectation that this plan or job is expected to run each day between the hours of 11pm and midnight (not including the duration of the plan/job itself).

Figure 140 – Daily Activity (Expected Date/Time Example)

The example above shows plan CaseStudy5 with an “expected” (note the (E)) run-time of 11pm.

Trigger Once Only: If enabled, this event is triggered once and then disabled for the life of the job.


239

5.13.2.1 Event Privileges

Figure 141 – WMI Event Privilege Settings

The above figure allows you to select one or more privileges (rights) that you would like to assert for the WMI Provider to properly execute the event query.


240

5.13.2.2 Advanced Event Settings

Advanced: This button allows you to select different authorization and security settings for the WMI query.

Figure 142 – Event Advanced Settings

The above figure allows you to change the Impersonation and/or Authentication levels. Advanced users can select different methods of securely using WMI.

User Account Object to use: This section allows you to select a user account to associate with this event. The drop down button allows you to select from a list of accounts that you have the rights to use. Two smaller buttons to the right allow you to manage or create a User Account object. Advanced Systems highly recommends using a User Account Object instead of embedding the Username/Password within the job itself.

Username/Password: For a local machine (Job Scheduler machine) your logon authentication credentials are used and WMI does not support the specification of different authentication credentials for a “local” machine. For non-Job Scheduler machines you must specify authentication credentials that will be used for WMI Event processing. As with other portions of ActiveBatch, you can indicate that the username and password are to be saved.

Run Job on Event Machine (Generic Queue Only): You can indicate to ActiveBatch that the job queue to select is the machine that actually generated the event. For this feature to work properly the job must be queued to a Generic Queue that contains at least one Execution Queue for the possible event machine. If no valid Execution Queue can be found that matches the event machine the job will not be run.


241

5.13.3 Plan/Job Completion Trigger ActiveBatch provides the ability to trigger execution of a job or plan when a job or plan completes. You can determine which jobs or plans to trigger based on how your job completes. This means you can trigger one set of jobs if your job completes successfully and another set if your job fails.

Figure 143 – Plan/Job Completion Dialog

The dialog above is presented when you want to add a Plan/Job Completion trigger. A single dropdown list containing all eligible active jobs is presented. Only ActiveBatch Trigger enabled jobs are presented for selection. You then indicate the instance completion status that should trigger the plan/job. Success means to trigger the plan/job if the plan/job completed successfully. Failure means to trigger the plan/job if the plan/job didn’t complete successfully. Exit Code(s) means to trigger the plan/job based on one or more exit code specifications. You can specify a single value, a series of values and/or a range of values. Click OK to confirm and apply the selection. Your selection is then added to the list.


242

5.14 Constraints A Constraint (or Dependency) is a specification that must be true before a Job is allowed to execute. A Job triggered to execute will not do so unless all constraints have been met (the “Force Run” operation is provided to force a job to begin execution regardless of constraints). ActiveBatch supports five (5) types of constraints: File, Job, Variable, Resource and Day/Time. Section 5.6.4.7 discussed constraints when creating a new job. This section will expand on the dialog mentioned in that section.

Figure 144 – Constraint Tab Dialog

Figure 144 allows you to add, edit or remove a constraint. The constraints are listed in the order they are defined. Three (3) columns of information are listed. Name, type of constraint and description of the constraint. Three (3) buttons are provided to add, edit or remove a constraint.


243

Constraint Logic: This section indicates how the various listed constraints should be checked and in what order. You can specify comparison, Boolean operators and parenthesis to ensure that any constraints match your expectations. Boolean logic operators, in English or VBScript-style, or arithmetic operators may be used (note: All arithmetic operations are integer based). For example, “and” or && may be specified. A unique label identifies each constraint. In the above example, “JOBA” and “MasterFile” constraints must both be met. See Table 20 more a complete list of operators.

Note: When a constraint is removed you must always ensure that you also remove the associated label referencing that constraint from the Constraint Logic expression. Missing constraints are treated as false.

If constraint logic fails: You’ll also notice several fields that control what actions should be taken if one or more constraints fail. In the example above the job “JOBA” must complete successfully and the file c:\temp\temp.dat must be present, at least 1000 bytes and created within the last five (5) minutes for this dependency to be satisfied. If you look at the bottom of the figure you’ll see a “If constraint logic fails” specification which indicates that we should wait up to 15 minutes to determine whether the constraint failure has resolved itself.

Fail this Job/Plan: This is pretty self-explanatory. ActiveBatch fails the job.

Wait: This indicates that we should wait (the default policy). How long is determined by the next set of paired controls. Check every number units for number interval. Units is one of the following: Hours, Minutes or Seconds (the legal range of the number depends on the unit specified). Interval is one of the following: Days, Hours, Minutes, Seconds, Times or Forever. The default policy is “Check every 2 minutes for 10 minutes”.

Operator Description

+ Addition

- Subtraction

* Multiplication

/ Division

% Modulo

^ Raise to power

&& Logical AND

AND Logical AND

|| Logical OR

OR Logical OR

!= Not Equal

<> Not Equal

NOT, ! NOT or Complement

== Logical Equal

= Equal

>= Greater than or equal

> Greater than

<= Less than or equal

< Less than

Table 20 – Constraint Logic Operators


244

5.14.1 Instance Constraint An Instance constraint is one where a previous plan/job must have executed to completion before this instance can be allowed to execute. The author of the constraint can further indicate whether the instance must have completed successfully or simply completed.

To add an Instance constraint, click the Add…. Job Constraint button. The following dialog appears:

Figure 145 – Adding a Job Constraint Dialog The information requested, in this dialog box, is to determine the job we’re to be dependent on and what the constraint should be.

Label: This mandatory field names the Job Constraint. This label must be unique within the Plan or Job’s usage.

Job: This mandatory field contains a dropdown box listing all known jobs/plans, by name.

Type: This mandatory field indicates whether the specified job must complete successfully (the default) or just complete.

Instance: This field indicates how current the specified job instance must be to consider the job meeting the Type property. Possible choices are: Exact Active, Last Completed or All Instances.

Exact Active means either the currently active instance or the last scheduled instance. This is the default and most precise setting.

Last Completed means the last completed instance as specified by a user provided time period. When this dropdown is selected, the time control labeled “within the last” becomes active and you can set the days and hours/minutes as a time period for ActiveBatch to determine whether a completed instance meets these requirements.

All Instances includes the preceding settings and expands the scope to include any instance of the job that completed. This is the most flexible setting.

Click OK to confirm and add the dependency to the list. Click Cancel to cancel the operation.


245

5.14.2 File Constraint To add a File Constraint, click the Add>File Constraint… button. The following dialog appears:

Figure 146 – Adding a File Constraint Dialog

The information requested in this dialog box is to determine the file that we are to be dependent on.

File Spec: This mandatory field indicates the file that we are dependent on. The file specification must be complete and can represent a local or UNC file specification. You can specify wildcard characters. The characters must be added as per the execution machine’s operating system’s requirements. Please note that local represents the execution machine since all file dependency checks are performed in the job’s security context on the execution machine. This means that you must have security access to the file. (Variable Substitution supported).

Check for File Present/Absent: This radio button indicates whether the file must be present or absent. The default is present.

The following checkboxes allow further refinement of the file dependency check.

If enabled File must be available for exclusive access means that no other process can be accessing the file. If a process is accessing the file, the dependency will fail. An example of when to use this might be expecting a customer to FTP a file into your production system. You don’t want to start the job until the file has completed populating.

If enabled File must be at least n bytes means that the present file must be at least n bytes in size in order to successfully pass the file dependency check. This is particularly useful when a zero (0) byte file should be considered as a file dependency check failure.

If enabled File should have been allows you to perform a date validation on the specified file. You can choose Created, Last Accessed, Last Written dates as well as Before or Within and a relative day/time range. The relative time range can be expressed in days, hours and minutes from the initial file dependency check start time. This option allows you to discriminate between “old” files that just happen to still be present from newer files that should have been created.


246

If enabled the If Wildcard spec… option allows you to further refine wildcard processing by indicating whether ALL files must meet the above checking criteria or simply the first file should result in a dependency check failure. By default, the first file to meet the above criteria will cause the dependency check to succeed.


247

5.14.3 Variable Constraint Variable constraints are added directly to the Constraint Logic property (so you won’t need to add them later on). The variables that form any constraints must already exist. Variable usage within the constraint should not be confused with variable substitution. In other words when you specify variable(s) as a constraint you don’t specify them with the curly brace syntax.

Figure 147 – Variable Constraint (Active)

In the above figure, an active variable constraint is defined. MasterFolderExists checks whether the directory C:\MasterFiles is present. If it is, a Boolean value of True (1) is returned. Otherwise, a Boolean value of False (0) is used.

Assuming the above, our Constraint Logic box might look like this:

A more complicated expression might involve an activeVariable that represents a SQL query looking for a minimum number of rows as a result. If the variable name was “RecordCount” then “RecordCount > 5” would form a constraint as well. That Constraint Logic box might look like this:

JOBA AND MasterFolderExists AND (RecordCount > 5)

Note: Remember that unless a constraint is specified in the Constraint Logic box, that constraint will not be used.


248

5.14.4 Resource Constraint A Resource represents a finite property that is to be shared. For example, the maximum number of simultaneous jobs a particular organization might be run. More dynamic resources might be the amount of free disk space a particular system has and the fixed amount needed by this job. If the required amount of disk isn’t available, this job shouldn’t run. The creation of a Resource is discussed in Section 5.14.7. This section discusses the use of an existing Resource object. ActiveBatch Resources are numeric by definition.

Figure 148 – Resource Constraint

This Resource named “FreeSpaceCDrive” references the dynamic resource corresponding to the amount of free space on drive C: (in Megabyte units). This particular job needs one hundred million bytes of free space on C before being allowed to continue and execute (assuming any other constraints are met). For Constraint Logic purposes, if the Resource constraint is met, the label FreeSpaceCDrive is equated to true, if not, false; 100 (megabytes) is then subtracted from the resource.


249

5.14.5 Day/Time Constraint Day/Time constraints allow you to indicate when a Plan or Job may execute. Three (3) types of day/time constraints are provided: Exclusion, Maximum Dispatch Time and Business Calendar.

The Exclusion List constraint allows you to indicate a day, specific date, and/or one or more time specifications that indicate when the Plan or Job is not allowed to execute. This means that should the Plan or Job be triggered during these days/times the Plan or Job will not execute.

Maximum Dispatch Time refers to the maximum amount of time the Plan or Job may remain on queue, waiting for execution (but not executing) before the Plan or Job Instance should be aborted. This feature is useful when a Plan/Job has been triggered and its execution must occur within a specific time or not at all.

The Business Calendar constraint allows you to indicate that this Plan/Job must adhere to a business calendar and must therefore only execute on business days.

5.14.5.1 Exclusion List Constraint

The Exclusion List as its name implies allows you to specify one or more day and/time specifications that a Plan/Job is not allowed to execute. The list has two (2) properties: Date and Time. The date can be a specific date, a day (Monday…Sunday) or all dates. The time can be a specific time, a series of times and/or time range. With an exclusion list you could indicate that a Job running every 5 minutes not execute at 3:05am. Or, not on Monday’s.

Figure 149 – Date/Time Constraint Properties

The figure above is a dialog box that appears when you want to add or edit a Date/Time Exclusion List item.


250

5.14.5.2 Maximum Dispatch Time

Maximum Dispatch time is used when a plan or job instance has been instantiated (created) and is on queue but has not been dispatched. This property allows you to create an “expiration time” so that in the event the plan/job is not dispatched before the “Maximum Dispatch Time” the instance is cancelled or aborted.

Note: This property is particularly useful when a long running plan or job must begin to execute by a certain time in order to meet service levels or to avoid impacting other aspects of the business.

5.14.5.3 Calendar Constraint

A Calendar constraint is used when the Plan/Job can only execute on business days. The Calendar object, described in the next section, acts as a filter constraining triggers to only operate on business days. Holidays and non-working days (typically weekends) would not be considered as business days. If the Plan/Job is triggered on a non-business date you can indicate one of three (3) options: Run the Plan/Job on the next business day, previous day or not at all.


251

5.14.6 Calendars By default, any trigger will cause a Plan/Job to begin execution (subject to other limitations and constraints). Sometimes, however, it is important to run jobs based on Business days. A Business Day is also known as a “Working Day”. An ActiveBatch Calendar contains the specifications for how to determine a working day. In other words, a Calendar acts as a filter or constraint on when (date) a job may run. ActiveBatch Calendar’s are uniquely named and are used by associating the calendar with a job. If a job doesn’t have a calendar associated with it then the job isn’t provided business day processing.

ActiveBatch allows you to define two (2) types of days to the Job Scheduler by creating a Calendar. They are Holidays, and Non-Working Days (which yields Working Days). A Holiday is defined as a day in which the company is normally open for business but isn’t due to the holiday. A Holiday is therefore not considered a holiday if it falls on a non-working day. A Holiday can be defined in a self-relative manner (like the Last Thursday in November is Thanksgiving Day) or via a fixed date without year (like January 1 is always New Year’s Day) or with a fixed date and year. The first two specifications are used regardless of year while the last is only used for the applicable year. Non-Working Days are specified by day-of-the-week. So the Saturday and Sunday checkboxes would be selected to indicate non-working days.

The sample calendar shows both fixed and relative holiday specifications. While calendars are great for defining holidays you don’t have to. You can just define non-business days without also defining any holidays.


252

5.14.6.1 Calendar – General

Figure 150 – Calendar – General

This selection allows you to name the Calendar as well as describe it.

Name: This field uniquely identifies the Calendar and is specified when defining a job that is to obey business day rules.

Label: This field uniquely identifies the Calendar within the ActiveBatch namespace.

Description: This field provides a description of the Calendar object.

State: This field indicates whether the object is enabled or disabled for use.

Read Only: This field indicates whether the object has been set to Read Only.


253

5.14.6.2 Calendar – Properties

Figure 151 – Defining a Business Calendar

This selection specifies the dates that should be considered non-business and/or holidays.

Non-Business Days: This area allows you to indicate which days are non-working days. Click the checkbox next to each day that is to be considered a non-working day. By default, Saturday and Sunday are non-working days.

Relative Holiday/Name: This area allows you to indicate holidays based on a relative specification rather than a fixed date. For example, Thanksgiving Day in the United States is the “Fourth Thursday in November”. Three (3) controls allow the relative specification for a holiday. The first control contains the following values: First, Second, Third, Fourth and Last. The second control contains the “day” values: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday and Sunday. The last control contains the months of the year. You may also Name the holiday you have entered. Clicking the Add button enters the relative specification in the list box below. To delete an already entered holiday, select the date and click the Delete button.

Fixed Holiday/Name: This area allows you to indicate holidays that are based on a fixed date. For example, Christmas is December 25. You may specify a fixed date holiday using two methods. If the holiday is to occur on the same date each year, click the Every Date radio button and enter the Month and Day of the holiday. If the holiday is to occur on a fixed date for a specific year, click the Fixed Date radio button and enter the month, day and year (localized) of the holiday. You may also Name the holiday you have entered (limited to 20 characters). When you want to add the fixed holiday, click the Add button.


254

5.14.6.3 Calendar – Audits

Figure 152 – Calendar Audits

This section details any changes made to the calendar object.






255

5.14.6.4 Calendar – Security

Figure 153 – Calendar Security

This selection allows you to specify security and access permissions for a Calendar object.

Access Description



Modify User is allowed to modify the object. (Read + Write)



Take Ownership

User is allowed to update the object’s security as well as take ownership.

Change Permissions



Table 21 – Calendar Access


256

5.14.7 Resources A Resource represents a finite property that you typically need to allocate among various plans and jobs. ActiveBatch supports two (2) types of resources: Constant and Active Resources. The types differ only in how they are populated. A constant resource is initialized once and its usage is tracked. An active resource is initialized from a data source (i.e. SQL SELECT statement) and while its usage is tracked the resource may be populated over a time period. For example, you could create a resource named “LICENSED_APPS” with an initial value of 5. That quantity might represent the maximum number of concurrent copies of a particular licensed application that your company was allowed to run. Each Job could request 1 unit from this resource. That means that a maximum of 5 copies could run. The fact that only 5 could run is the constant part of the resource, but what if you needed to track a dynamic resource? A dynamic resource is one that may not be under ActiveBatch’s complete control. For example, what if we needed to create a resource named C_FREESPACE. This resource might be tracking the freespace on drive C. Since programs other than those launched by ActiveBatch allocate space on drive C a constant resource won’t work. In this case, an active resource would be used. Using WMI’s WQL SELECT statement we could get the current freespace on drive C and also periodically reacquire that freespace over a fixed timed interval. Since the resource is being re-examined over a set interval, we only need to track its usage between the repopulation intervals. For example, if C_FREESPACE had an initial value of 100000000 (one hundred million) and JOBA needed 5000000 (five million) of space, the resulting resource would yield a value of 95000000 (ninety-five million). The next time the resource is examined, the value might instead become 1 gig because someone externally deleted some files and freed up some additional space.


257

5.14.7.1 Resource – General

Figure 154 – Resource – General

This selection allows you to name and describe the Resource object.

Name: This field uniquely identifies the Resource.

Label: This field uniquely identifies the Resource within the ActiveBatch namespace.

Description: This field provides a description of the Resource object.


Read Only: This field indicates whether the object is Read Only or can be modified.


258

5.14.7.2 Resource – Properties

Figure 155 – Resource – Properties

This selection allows you to define the Resource. Resources can be based on a constant or an active Variable type populated from a data source.

Expression: If this radio button is selected, the Resource is based on a constant. It will be initially populated and then managed by ActiveBatch.

Active Variable: If this radio button is selected, the Resource is populated from a data source. The Resource can be populated more than once depending on the “Re-evaluation Rule”. The data source specification is identical to that of an Active Variable. Clicking on the dropdown handle produces a tree showing the various categories and Active Variable data sources available.

Credentials: All ActiveVariables are executed under established and explicit security credentials. This dropdown lists the eligible User Account objects that can be used. The two buttons to the right allow you to manage and/or create User Account object(s).

Re-evaluation Rule: A Resource can be re-evaluation or re-populated. If Expires is greater than zero (0) the Resource is re-evaluated every n seconds. If Never (Set once only) is specified the Resource is populated only once.

Note: Normally, a Plan or Job that accesses a Resource releases its units when the instance completes. That is not the case when the Resource is subject to timed re-evaluation. In other words, only those resources that are set to “Never” are subject to the typical subtraction (Job starts) and addition (Job completes) that one would expect with a resource.


259

5.14.7.3 Resource – Audits

Figure 156 – Resource Audits

This section details any changes made to the resource object.






260

5.14.7.4 Resource – Security

Figure 157 – Resource Security

This selection allows you to specify security and access permissions for a Resource object.

Access Description


Write User is allowed to write the object.

Modify User is allowed to modify the object (Read + Write)



Take Ownership User is allowed to take ownership.

Change Permissions User is allowed to change permissions for the object.


Table 22 – Resource Access


261

5.15 Alert Objects A Job, Plan or Queue can have one or more alerts and each alert can have one or more actions. An Alert object is a container or collection of alerts. The advantage of an Alert object is that you can associate the object to one or more event generating objects (like Job, Plan and Queue).

5.15.1 Alert Object – General

Figure 158 – Alert Objects

This selection allows you to name and describe the Alert object.

Name: This field uniquely identifies the Alert object.

Label: This field uniquely identifies the Alert object within the ActiveBatch namespace.

Description: This field provides a description of the Alert object.




262

5.15.2 Alert Object – Properties

Figure 159 – Managing Job Alert Objects

Adding alerts is simple since the dialog shown is the standard alert specification. Once you’ve created or modified your Alert object don’t forget to associate the Alert object with your Plan, Job or Queue.


263

An “Alert” is simply a facility for associating an event with an action. There are currently thirty-six (36) events covering Plan, Job and Queue objects. The action to be specified can be a notification or Plan/Job trigger.

Figure 160 – Job Alert Dialog Enter the information requested and click OK to confirm and add the alert. Click Cancel to cancel the operation.

Alert Type: This mandatory dropdown list contains all the alerts that can be specified for an ActiveBatch job/plan. The following list is used (this table contains only Plan/Job alerts, see Table 4 for Queue alerts):

Alert Description

Job/Plan Begin Execution The job/plan is beginning execution.

Job/Plan Completed The job/plan completed.

Job/Plan Aborted The job/plan was aborted by manual intervention.

Job/Plan Completed in Failure

The job/plan completed in failure.

Job/Plan Completed in Success

The job/plan completed in success.

Job/Plan Pending Execution The job/plan is now pending execution.


264

Alert Description

Job/Plan Released The job/plan is released from a hold.

Job/Plan On Trigger The job/plan has been triggered for execution.

Job/Plan Run Time Overrun The job/plan has exceeded its expected elapsed time.

Job/Plan CPU Time Overrun The job/plan has exceeded its expected CPU time.

Job/Plan Run Time Underrun

The job/plan has underrun its expected elapsed time.

Job/Plan CPU Time Underrun

The job/plan has underrun its expected CPU time.

Job/Plan Restarted The job/plan has been restarted.

Job/Plan Trigger Failure The job/plan failed to start by trigger.

Job/Plan Constraint Failure The job/plan suffered a constraint failure.

Job/Plan Constraint Wait (Delta)

The job/plan suffered a constraint wait. This alert can be set for an interval (delta) time period.

Job Delayed in Starting The job/plan was delayed in starting on-time.

Job/Plan Instance Skipped A job/plan instance was skipped over from executing due to concurrency limitations

Job/Plan Held The job/plan was held from execution.

Job/Plan Failed Logon Error The job/plan failed due to a logon error.

Job/Plan Exceeded Dispatch Time

The job/plan instance was not executed as it exceeded its maximum dispatch time.

Job/Plan Missed Expected Trigger

The job/plan was not instantiated during an expected date/time period. This alert concerns an event plan/job that was expected to execute during a date/time period.

Table 23 – Plan/Job Alerts

Two (2) action categories are possible: Notification or Trigger.

Notification: The first property of each notification allows you to specify whether you want to use the template shown as is or whether you want to customize the message using the template as a guide. Clicking on the Customize field produces a checkbox. Enabling the checkbox turns customization on. You will then be able to edit those fields that were originally part of the template.

Figure 161 – Notifications Menu

E-Mail (SMTP):

General purpose E-Mail. The To field indicates the destination E-Mail recipient. This must be entered as an acceptable E-Mail address. Multiple E-Mail addresses may be separated by a semi colon. A special prefix may also be inserted for special formatting requirements. (Variable Substitution supported).


265

Subject is the subject of the alert. By default, ActiveBatch will display the default subject line for this type of alert. You may follow customization rules for this field.

Message is the body of the message. By default, ActiveBatch will display the default body that will appear for this type of alert. You may follow customization rules for this field.

Attachments is a field indicating the file(s) that are to be sent with this alert message as an attachment.

AlphaPager (SMTP):

AlphaPager E-Mail is limited to 150 characters (all parts of the E-Mail). The To field indicates the destination E-Mail recipient. This must be entered as an acceptable E-Mail address. Multiple E-Mail addresses may be separated by a semi colon. A special prefix may also be inserted for special formatting requirements. (Variable Substitution supported).



BlackBerry (SMTP):

BlackBerry represents the ActiveBatch BlackBerry Wireless Client. If you aren’t using that software, simply select E-Mail to send a BlackBerry a message. The To field indicates the destination E-Mail recipient. This must be entered as an acceptable E-Mail address. Multiple E-Mail addresses may be separated by a semi colon. A special prefix may also be inserted for special formatting requirements. (Variable Substitution supported).



Attachments is a field indicating the file(s) that are to be sent with this alert message as an attachment.

Messenger: (Variable Substitution supported).

Machine: A machine-name (or machine\username) that is acceptable to the Windows Messenger service.

Message: The message to be sent. You may follow customization rules for this field.

Event Log: (Variable Substitution supported).

Location: This dropdown lists the acceptable Windows Event Log machines. One of the following: Job Scheduler machine, Client and Execution Machine or you may indicate a custom location.

Machine: If you entered Custom you would specify the machine in this field.

SNMP: Generate an SNMP trap when this alert occurs. (Variable Substitution supported).

Destination: This field indicates the TCP/IP Hostname or IP address that is the target of the trap. The default of 255.255.255.255 broadcasts the trap to any listening SNMP agents. Multiple trap manager addresses by be specified using a semi-colon.

Trigger: This dropdown lists all Plans and Jobs that can be triggered should this alert occur. Selecting one will cause a Trigger and Change Parameters operation to occur. Two formal parameters are passed to the job: JobID of the job that was the target of the alert and the alert number (see Table 23). Note: You must have “Trigger and Change Parameters” access permission and the job cannot reside on the OnDemand Queue. If the job already has parameters they will be overwritten for this instance.


266

5.15.3 Alert – Audits

Figure 162 – Alert Object Audits

This section details any changes made to the alert object.






267

5.15.4 Alert – Security

Figure 163 – Alert Object Security

This selection allows you to specify security and access permissions for an Alert object.


268

Access Description






Take Ownership


Change Permissions



Table 24 – Alert Access


269

5.16 User Account Name Objects Every ActiveBatch Job runs under the security context of a user account. Just as with Alerts, you have two (2) methods for associating a user account with a Job. You can specify an account for a specific job or you can create a User Account Name Object and associate the object with the Job. The main distinction between the two methods deals with password updating. When you specify an account with the creation of the job you must update the job when the password needs to be changed (perhaps due to security policies at your company). When you create a User Account Name object, you change the object’s password. All jobs that are associated with the object pickup the changed password.

Figure 164 – Execution User Credentials

The above figure shows the two methods. Any existing Username objects that you can select will appear in the drop down list. To create or otherwise manage User Account Name objects, simply click the Manage Accounts button. A list of existing User Account Name objects (if any) will be displayed. To create a new object, click the New button.


270

5.16.1 User Account – General

Figure 165 – User Account (General)

This selection allows you to name and describe the User Account object.

Name: This field uniquely identifies the User Account object.

Label: This field uniquely identifies the User Account within the ActiveBatch namespace.

Description: This field provides a description of the User Account object.




271

5.16.2 User Account – Properties

Figure 166 – User Account (Properties)

The Properties selection allows you to specify username and password credentials that will be used by the Job or other associated object when a security context is needed. The small button to the right allows you to lookup the account using Active Directory. The Authentication Type allows you to specify whether to use standard and/or Kerberos authentication. When a User Account Name object supports both Kerberos and Password authentication, Kerberos is used first and then the Username/Password combination. This ensures that should Kerberos not be supported on the target execution platform your Job will still run successfully.


272

5.16.3 User Account – Audits

Figure 167 – User Account Audits

This section details any changes made to the user account object.



The Print button allows you to print the retrieved audits.


273

5.16.4 User Account – Security

Figure 168 – User Account Security

By default, only the creator/owner of the object is granted access to use the object.

Access Description





Use User is allowed to associate object with a Job

Take Ownership



Table 25 – User Account Security

Note: Please use caution as to which accounts or groups you give Use access to. Use access allows that user or group to run jobs using the account without having to specify a password.


274

5.16.5 Using a User Account Object

The main reason for creating and using a User Account object is that you don’t have to embed a username/password everywhere security credentials are required. As you work with ActiveBatch you’ll see there are many places where security credentials need to be used. A User Account object allows you to secure references to a username/password.

The figure above is taken from the Variables property page. Remember that activeVariables require authentication.

The figure above is taken from the Events property page. When a WMI event notification is requested for a remote machine, authentication is performed.

The figure above is taken from a job’s execution user credentials property page. All ActiveBatch jobs run under the security context of the associated user account.

With all these users of security, having a User Account object simplifies possible maintenance of the underlying OS account. In addition, using a User Account object also abstracts the actual account that’s used. If conditions require the account name to be changed, no changes are required within any of the associated objects. The User Account object alone would change.


275

5.17 Design View Design View is a visual representation of your jobs and their relationships. As the name implies, we expect most authoring of Plans and Jobs to be performed using Design View. With Design View you can create all the various ActiveBatch objects, and visually link them together.

Figure 169 – Design View (Overview)

Before we delve into the specifics of using Design View let’s discuss the pane itself. Besides the current date and time, the top title bar displays the Zoom factor and the number of jobs displayed for one or more Job Scheduler systems. In this case, 3 jobs are displayed for “ASCI62”.

Select Mode: With this checkbox disabled (the default), when you click and drag the mouse to create a box around your Jobs, the Design View zooms in. With this checkbox enabled, the same operation will select all the Job objects within the box.

Auto Layout: As you can imagine simply displaying Job objects could result in a very cluttered display when those objects may or may not be related to other jobs. The Auto Layout facility allows you to choose a layout algorithm that offers the best and most uncluttered display. Four (4) layouts are available: Hierarchical (default) attempts to display jobs that are related near each other. Unrelated Jobs are displayed last. Figure 169 shows the hierarchical layout. Symmetric, Stack and Circular are alternative auto layout modes.

Select Zoom: This list allows you to zoom the display in or out. You can “zoom to fit” in which case the Design View will choose a zoom scale for all objects to be displayed. While preset zoom percentages are available you can click Custom to specify your own zoom scale. Remember that you can also zoom by dragging your mouse to create a box around the Jobs you want to view. In that case, ActiveBatch will adjust the zoom factor for best display of those Jobs.


276

The information that is displayed with the Job is simple. If you “mouse over” the plan or job you can see some additional information.

Design View, as opposed to System View, is not subject to auto refresh, so changes to a Job aren’t displayed until you press the F5 (refresh) key.


277

Figure 170 – Operations

The figure above shows a simple “straight-line” relationship between Jobs “testjob1”, “testjob2” and “testjob3”. Before we discuss what operations we can perform on those objects, observe the menu to the right of the figure. This menu was obtained by right clicking on the “white space” of the display. Several of the operations are common to other views within ActiveBatch. ActiveBatch supports printing this window (as well as Print Preview). This is useful for documentation purposes. You can also integrate this picture into another object (like a Word document) using Save as Image or Copy to Clipboard. The image is saved as a Windows Metafile. When the display contains a great many jobs the Find Job function provides a quick way of locating a specific job. There is a Toggle Full Screen button in the main menu tool bar that allows you to have the Design View display use the full screen.


278

5.17.1 Find Job (Design View)

Figure 171 – Design View (Find Job)

The dialog above will list all jobs which are displayed. You simply double-click on the Job you want to locate in the Design View display. ActiveBatch will blink the located Job “n” times (see Section 3.5 for Options Preferences) in the display. Enabling the Also Zoom to 100% checkbox will change the Zoom factor when the Job is located.


279

5.17.2 Printing (Design View) You can Print (or Print Preview) the Design View by selecting the Print (or Print Preview) operation.

Figure 172 – Design View (Print)

The above figure is displayed for Print and Print Preview operations. You can indicate whether to print the graphical view in portrait or landscape mode, whether to “fit to page” or print using the same view scale and to also, optionally, indicate a “footer” message. When Printing, a standard dialog box will appear asking you to select a printer. In Print Preview mode you will see the first page. You may right click and select the next or previous page. If you double-click you can zoom in for greater detail. To close the Print Preview page, simply right-click on select “Close”.


280

5.17.3 Creating a Plan/Job in Design View To create a Plan/Job with Design View simply right click anywhere in the “white space” of the display and select New Job or New Plan. This will bring up the familiar dialog boxes (and discussed in detail in Section 5.4). Once you added the Plan or Job you’ll see a new Plan or Job object box added to the display. For the purposes of this section, we’ll add a TestJob4 to the other TestJob jobs. TestJob4 will be executed after TestJob3.

The above figure shows what the display now looks like.


281

5.17.4 Adding a Trigger If you look at the Design View tool bar you’ll see three (3) buttons that look like this:

Completion Trigger is the one that currently pressed in and means that any line drawing will represent a completion trigger association. Alert Trigger (the middle button) represents the triggering of a job (or plan) based on a specific ActiveBatch event. Job Completion (the rightmost button) represents an instance constraint relationship (for example, TestJob1 must complete before TestJob2 can execute). For this discussion, “Completion Trigger” must be enabled.

Now I want to create a Completion Trigger between TestJob3 and TestJob4. To perform that I click on TestJob3 (which selects it) and then click on any of the handles that appear on the object (indicating that it is selected). I then drag that handle (and resulting line) to TestJob4 and drop it. The display will look like this:

Notice the line that is drawn. When you release the mouse within TestJob4 the line will momentarily disappear and a dialog box will take its place.


282

Figure 173 – Completion Trigger Dialog

Note the To Job/Plan reference to TestJob4. This removes any doubt about the direction of the trigger. We have a choice as to the condition that we want TestJob4 to be triggered. In this case we want to trigger TestJob4 only when TestJob3 executes successfully. So we select Success and click the OK button.


283

The display now looks like this.

Note the green line/arrow as well as the small “CT” denotes success. The direction of the line and arrow-head further indicate this trigger is from TestJob3 to TestJob4.


284

5.17.5 Adding a Job Constraint Now let’s add a job constraint. Click on the “Job Constraint” button to enable that facility. We want TestJob4 to run only when TestJob3 completes successfully. So we select TestJob4 and drag the handle from TestJob4 to TestJob3. This brings up the following dialog box.

Figure 174 – Add Instance Constraint Dialog Box

The Label field will be used to name the constraint. By default, the “auto label” feature will label this constraint as JC1 through JCn (where “n” is the highest numbered job constraint). In the example above, we’ve manually labeled the constraint as “TestJob3” to avoid confusion. Typically you will use the Job/Plan instance’s name as the label value. The constraint is applicable to TestJob4. TestJob4 should not execute until TestJob3 completes successfully. The defaults settings are appropriate for what we want so we click OK. Now the display looks like this.


285

Note the green line with the small “JC” beneath it. JC stands for Job Completion. The anchor at the end of the dependency indicates what Job the other Job is dependent on.


286

5.17.6 Modifying Triggers and Constraints In the previous sections we created a Job and then a Trigger and Dependency for that job. In this section we’ll learn how to modify or otherwise manage those links.

To modify or delete a link you must select it.

Note that the JC line is selected (you can see the 3 handles). If you wanted to move the line you would simply grab one of the handles and drag the line. To get more information on a link or object, simply place the cursor over the object. You should see a helpful and descriptive tool tip.

Figure 175 – Constraint Tool Tip

The tool tip above describes the constraint we created in the previous sections. The Design View’s use of Tool Tip provides you with a quick way of getting more information without cluttering the display.


287

To edit or remove the link, simply right click on the selected link.

Figure 176 – Edit a Constraint

You can now choose Edit or Remove. The standard dialog boxes will then appear.

Note: Remember that if you remove a constraint you must still ensure to also remove the constraint label from the Constraint Logic box. Missing constraints specified in Constraint Logic are considered failed.


288

5.18 Passing Parameters and/or Variables ActiveBatch provides the ability for a job to pass input parameters and/or variables (and their values) to downstream jobs. A downstream job is one that will be triggered via a Completion Trigger. The ActiveBatch utility responsible for this is called abatset. Abatset is a command-line based utility program that is used by a job, at run-time, to modify plan variables and/or to pass input parameters and/or job variable(s) (and their value(s)) to downstream jobs. For example:

abatset /success /failure /param 123

would pass the value “123” as an input parameter for the next downstream job(s) that the current job will trigger via the Completion Trigger facility. To modify a plan variable you might follow this example:

abatset /env ../plan1=abc

This will modify the plan variable “plan1” and change its value to “abc”. That this is a plan variable is indicated by the ../ syntax. Plan variables are set immediately (any qualifiers are ignored with reference to the variable). To pass the current job parameters and variables to the next downstream jobs you might follow this example:

abatset /current

To pass a job variable, use this syntax:

abatset /success /env test1=abc test2=efg

This example will pass two (2) variables, test1 and test2, to the next downstream jobs. ActiveBatch uses a “Replace or Insert” model. If the variable exists, the new value replaces the existing one. If the variable doesn’t exist, the entire variable and it’s value are added to the downstream jobs.

To avoid operating system ambiguity with regard to embedded spaces, you should follow your operating system recommendations. For example, with Windows you would enclose the entire parameter or variable specification within the set of quotation marks. For example:

abaset /success /env “workdir=c:\program files\asci\activebatch”

This avoids the mistake of ActiveBatch thinking that multiple variables are being passed.

Note: This command can only be issued within an ActiveBatch created job.


289

5.19 Job Checkpoint, Restart and Progress Indicator ActiveBatch provides several features to allow jobs to automatically restart or failover to an available machine. By default, jobs that don’t have restart enabled are considered to have failed when the machine they execute on fails. Two types of job restart are provided (see Section 5.6.4.15): Machine and Process failure recovery. Restart on Reboot is the more typical and simply means that the job is to be restarted when the machine the job was executing on is rebooted and available. Failover Restart is applicable when the job is placed on a Generic Queue and can be re-dispatched to another available machine. Where “Restart on Reboot” means the job must wait until the execution machine is rebooted, “Failover Restart” means the job can be immediately re-dispatched. When a job is restarted, its “pre” step is executed, followed by the “Main” and “Post” steps. Please note that the ABAT_RESTART variable is set to YES to indicate the job is operating under a restart condition (see Table 9 – Environment Variables for Job Steps in Section 5.6.4.9 for more information).

ActiveBatch supports the concept of Checkpointing. A checkpoint represents non-volatile data that is associated with the batch job and saved by ActiveBatch. The last checkpoint value is made available whenever the batch job is restarted. Of course, the actual data and timing of checkpoints are purely up to the batch job itself. To declare a checkpoint you invoke the AbatChkPt program. For most machines the syntax is:

ABATCHKPT “Checkpoint-data”

ABATCHKPT is the name of the checkpoint program and the data you want to checkpoint appears after the command (with an intervening space). The string specified does not have to be quoted unless the data contains embedded spaces. This command can only be issued within an ActiveBatch created job.

To retrieve the checkpoint value, you must check two ActiveBatch environment variables (or logical names), ABAT_RESTART and ABAT_CHECKPOINT. Both must be set to YES for the checkpoint value (ABAT_CHECKPOINTVAL) to be considered safe and available.

You can also specify a progress indicator, separate from a checkpoint that can be used to visually alert an ActiveBatch client user as to the progress of this job. The progress value will be displayed in a portion of the Job State. The Job State is displayed in many views (although the Daily Activity list is best since it dynamically takes real-time updates). Any language (for example, Visual Basic Scripting) that is COM accessible can access this progress indicator through the COM library AbatScripting. Information on this library can be found in the ActiveBatch Developer’s Guide.

291

6 OPERATING THE ACTIVEBATCH SYSTEM This chapter deals with job scheduling operations. Operators are concerned with the monitoring and management of the jobs and plans that make up the ActiveBatch system. Operations should not be confused with Administration. Administration concerns the implementation of ActiveBatch itself.

The first part of this chapter discusses the various monitoring features found under the Operations role tab.

6.1 Monitoring ActiveBatch Operations ActiveBatch objects contain a lot of information. The various views display that information in different ways to satisfy the information requirements of the different people who need to access ActiveBatch.

6.1.1 Filters As you run more and more plans and jobs it’s easy to get “information overload” and not be able to see what you need from the mass of job/plan instances that have been executed. For that reason, ActiveBatch (through AbatAdmin) offers a filter that allows you to determine what instances you may be interested in.

Figure 177 – Instance Filter Bar

The advantage of the filter bar is that you can more precisely target the specific instances you may be interested in. The filtering is done when accessing the database so you get quicker performance as well. The Limit box allows you to indicate how many instances should be retrieved immediately. When the number of instances exceeds the limit, the Page control allows you to move forward or backward through the collection of instance information. The Instance State menu (see … button) allows you to specify the instance state(s) that you’re interested in. For example, if you only wanted to see “successfully completed instances” you would click that checkbox. You can click multiple states.

Figure 178 – Instance State Selection


292

The Ordering dropdown indicates whether you want to see the newest or the oldest listed first.

Figure 179 – Instance Filter Bar (Date and Time)

The next series of filtering information is date/time oriented and must be enabled by clicking on the checkbox. By default, when no date/time filtering is specified – no date/time is considered when retrieving an instance(s). The Date dropdown allows you to specify a specific date for instance retrieval. In the above example the date is set to January 25, 2005. The Day Period dropdown allows you to specify a day or day(s) period (interval) that is used in conjunction with the starting date specified. The period specified may also preclude any additional time based filtering. For example, All Day or 1 Day implies a twenty-four (24) hour period. Specifying Custom activates the time portion of the date/time filter. The Time dropdown allows you to specify a specific time. The Time Period dropdown allows you to specify a time period that is used in conjunction with the time specified.

You’ll notice that the Refresh button is color-coded. A green button means that your filter is active and the data you are looking at has been filtered. An orange color means that you’ve changed the filter and must press the Refresh button to see the new data applied against this filter.

Note: You may notice that when you click on Refresh the button will change to Cancel. This allows you to cancel an instance retrieval if the information you’ve requested is taking longer than desired.

Chapter 6 - Operating the ActiveBatch system

293

6.1.2 Daily Activity This display, found under Daily Activity in the Operations navigation pane, lists all jobs and plans for a specific day. The jobs and plans are listed in alphabetical order by name and represent all jobs/plans that have either run, are currently executing (in some fashion) or are scheduled to execute later in the day. This view is a dynamic real-time display. As jobs run, the display will automatically change to reflect the current state. You can disable this feature if you need to examine the display statically.

Figure 180 – Daily Activity List

The information displayed above is what most operators would need to monitor jobs. Clicking on a column heading changes the sort order. Plans are color coded for easy separation between jobs and plans. Plans are also represented by a tree symbol (plus sign) so you can expand a plan and see its contents.

Each column is further described as follows:

Name The name of the job/plan.

Job ID The unique job/plan instance number.

State Current status of the job/plan. This will be one of the values found in Table 3. A state of “Not Run” means that the plan/job has been scheduled to run but hasn’t as of yet run.

Execution Time Depending on the state of the object, this field for past and present instances reflects the actual execution time. For a future instance this represents the expected execution time. In addition, a letter code indicates the type of forecasted time this instance represents. E=Expected, I=Interval Time and S=Scheduled Time.

Duration Depending on the state of the object, this field for past instances, reflects the actual elapsed time (duration) of the job. If you see a time value in parenthesis, the value represents an under or over elapsed time based on the average run-time (if applicable). For present and future instances, the time value represents the expected (or average) elapsed time.

Queue The name of the queue this job is currently on. “MainQueue” represents a Plan (since that object can contain other objects that will execute on different machine queues).

Exit Code The job/plan’s exit code.

Exit Description The interpreted exit code. (Note: Only ActiveBatch based exit codes are interpreted).

You can perform menu operations on any of the jobs displayed by right clicking on the object.


294

6.1.3 Gantt Chart The Gantt Chart displays jobs based on a start date and day range. By default, jobs are displayed in alphabetical fashion. Each row consists of the job’s name and a color coded bar indicates the start and ending times. The times are listed horizontally so you can scroll in either direction to view all the displayed jobs.

Figure 181 – Gantt Chart

You can use your mouse to grab the time scale and drag it horizontally. In one direction (to the right) the scale will get smaller and the objects will get larger. In the other direction the scale will get larger. The large Left and Right arrows allow you to scroll the time portion of the display horizontally. Clicking on the plus sign of an object expands the object to show you the completed instances. Multiple instances are compressed into a single item appearing on the left side navigation tree. The boxes of the Gantt chart represent the plans and jobs that have either completed, are currently running or will execute in the future. The sizes of the boxes are based on either actual elapsed times or expected elapsed times based on initial run-time or historical average values.


295

6.1.4 Properties Window To see more information on an object you can select it and view it’s properties using the Properties window. For example:

Figure 182 – Properties Window

Provides a quick reference of the important properties of the object.


296

6.1.5 Favorites Window The Favorites Window is similar to that of a Web Browser’s Favorites. Rather than having to navigate the entire tree of ActiveBatch objects you can create a favorite shortcut that represents the object. When you then need to access the object you can quickly find and retrieve it from the Favorites Window.

To add an object as a Favorite use the standard Navigation tree and find the object, then select and right-click the object and select Advanced/Add to Favorites (or Ctrl/D).

Figure 183 – Add To Favorites Menu Selection

When you make this selection you will see this dialog.

You can change the default and enter any name of your choosing. When you click OK the favorite will be added to the Favorites Window.

Figure 184 – Favorites Window

The icons within the window allow you to manage your selection. You can also create a folder to further categorize your selections. Clicking on a Favorite causes the object to be immediately selected in the Navigation Pane.


297

6.1.6 Runbook The Runbook displays jobs in a diary format. When a day is selected, the time is shown vertically (and you can scroll the display) and jobs are arranged in time slots. Time slots can be between 5 and 60 minutes.

Figure 185 – Runbook

As you can see in the above figure, jobs are displayed color-coded based on how they completed, are currently executed or will execute. Jobs are further displayed vertically based on the job’s elapsed time.

As with the Gantt chart, you can click on an item and display its properties using the Properties window.


298

6.1.7 System View To filter objects within the System View, you need to enable the option “Show Queue and Group Filter Bar” in the Options\System View dialog (Note: If a System View is present you will need to exit the view entirely to see the filter bar). Two filters are present: Queues and Groups. When filtering please note that a queue or group selection may only be made if jobs are present at the level of viewing. For example, if your root level consists of only plans, both dropdowns will essentially consist of an “All” type setting.

Figure 186 – System View Filter

To select different queues and/or groups click on the … button that appears to the right of each dropdown. You can select one or more items that can be used to filter the job selections.


299

6.2 Managing Queues Once you’ve created a Queue you’re halfway home to executing a Job. However, while we’re on the subject of Queues let’s complete our discussion by illustrating some types of operations we can perform on Queues.

6.2.1 Deleting a Queue To delete an existing Queue, either right-click to select the Queue icon and choose Delete… or select the Queue icon and choose Queue/Delete… from the menu bar. Deletion of a Queue requires that no jobs of any kind be on queue. ActiveBatch will detect whether there are any jobs on queue and allow you to flush them as part of the deletion process.

Figure 187 – Delete Queue Confirmation The figure above is presented in all cases to ensure you really want to delete the selected queue. Please note that when you delete a Queue, that Queue will also be removed as a member from all Generic Queues it may be associated with. You cannot delete the OnDemand or VariableQueue Queue. Deletion of a Queue requires that you have “Delete” access permission to the Queue object.


300

6.2.2 Starting and Stopping a Queue Stopping a Queue prevents any jobs that are currently on-queue and in a pending state from additional processing. For an Execution Queue this means those jobs will not be allowed to start execution. If a job is already executing, stopping a Queue does not affect the running job. For a Generic Queue, pending jobs are not dispatched to member Execution Queue(s). Stopping a Queue is therefore beneficial when you know a machine will be subjected to some downtime or a reboot. Another advantage to stopping a member Execution Queue is that jobs submitted to a Generic Queue won’t be dispatched to the stopped Queue.

Figure 188 – Stopping/Starting a Queue

To stop a started Queue, right-click on the selected Queue icon and choose Stop.

Starting a Queue is of course the same general actions except that the Start menu operation is chosen. Normally when you start an Execution Queue the execution machine will be up and available. If it isn’t the Queue will enter a “Starting” state and remain in that state until the execution machine becomes available. Jobs are not dispatched to a Queue in a “Starting” state. The Start/Stop operation is an in-context operation. That means ActiveBatch will select the proper operation depending on the current state of the Queue (e.g. if it’s started, you can stop the Queue).


301

Figure 189 – Stopping a Queue (Timed) Remember that you can also automatically stop (and start) a Queue based on the Queue’s properties. The figure above is taken from the Queue General tab. This is especially useful when you know a machine won’t be available during certain hours.

To start or stop a Queue, you must have “Manage” access permission on the Queue object.


302

6.2.3 Open and Close a Queue Stopping and starting a Queue deal with whether jobs are dispatched for execution or left on queue. Opening and closing a Queue deals with whether jobs can be submitted to a Queue by a user. Typically Queues are open to job submissions regardless of whether the Queue can actually support job execution. A “Closed” Queue indicates that jobs will not be accepted for submission. This feature isn’t used very often since most users want to allow job submissions. However to close or open a Queue, you can right-click on the Queue icon and select Open/Close operation. The Open/Close operation is an in-context operation. That means ActiveBatch will select the proper operation depending on the current state of the Queue (i.e. if it’s open, you can close the Queue).

Figure 190 – Opening or Closing a Queue

Remember that you can also automatically schedule open and close operations on a per queue basis as part of the Queue’s properties. Note the Close From field below in Figure 191.

Figure 191 – Restrict Job Submission (Timed)

To open or close a Queue, you must have “Manage” access permission on the Queue object.


303

6.2.4 Flush Instances on a Queue This operation is used to quickly delete all job instances that have been dispatched to a specific Queue. Rather than delete each job instance individually you can simply flush the Queue. When you flush a queue you lose all job history concerning the flushed jobs. Since this operation may result in the deletion of job instances you will receive a confirmation request if jobs are present on queue.

Figure 192 – Flush Instances on a Queue To flush a Queue, you must hold “Manage” access permission on the Queue object.

Note: A flush instances operation will delete all job instances that have been associated with this queue. Prior to V6, the flush operation also deleted all job definitions as well. This is no longer the case when invoked from AbatAdmin. However, you should be very cautious when flushing a queue since no undo operation is provided.


304

6.3 Managing Jobs and Plans The figure below shows the operations you can perform by right clicking on a Plan or Job object.

Figure 193 – System View (Job Menu)

Some Plan/Job Operations are to be executed on Job Definitions (Templates) and some only on Instances. For example, you cannot Trigger a Job Instance but you can Trigger a Job Definition.


305

6.3.1 Instance Operations

6.3.1.1 Change Queue Priority

This operation, valid for job instances that are in a Waiting state, allows you to change a job’s queue priority.

6.3.1.2 Constraint (Dependency) Status

This operation allows you to see which constraints (dependencies) a plan/job instance is actually waiting for. This operation is only valid for a plan/job instance whose status is “Waiting Constraint”.

Figure 194 – Constraint Status

The Constraint Expression box shows the actual constraint logic the plan/job was defined with. Satisifed/Not Satisfied (or True/False) indications are shown in both text and color. Red or a question mark (?) means that the constraint could not be evaluated. This is typically a mistake in entering the variable name. Please note that this status is subject to change and that the constraint expression is a snapshot taken on your request. You may click the Refresh button to retrieve new constraint status information.

Note: You may see two brackets [] with no intervening value. This typically means that the constraint is using Boolean logic and the first portion of the constraint failed so the additional constraints are not evaluated as part of this status operation.


306

6.3.1.3 Force Run

This operation allows you to force a job to execute even though it is waiting on resources or dependencies to become available. For example, a job is waiting on a constraint and you would like to force the job to continue execution despite the lack of satisfactory dependency conditions.

Figure 195 – Force Run Menu

This operation is valid for Plan/Job Instance’s only.

6.3.1.4 Override Completion Status

This operation, for completed Job Instance(s) only, allows you to change the actual completion status of a job. Consider this example: Job A fails and is supposed to trigger several downstream jobs on success. An engineer access the system and fixes the problem by performing those tasks which Job A was supposed to have done. By performing an “Override Completion Status” operation and setting the Job A instance which originally failed to success, any downstream jobs are now triggered automatically.

Figure 196 – Override Completion Status


This operation allows you to set an exit code and/or simply force success. Optionally you can also avoid triggering downstream jobs and/or alert notifications.

Note: If Job A triggered downstream jobs based on a failure status, those jobs would still have been triggered. In other words, this operation does not “undo” the past.


307

6.3.1.5 Pause and Resume a Plan/Job

Where Disable and Enable allow you to prevent/release a Plan/Job from/to executing, Pause and Resume are the counterpart commands you would use to suspend an object that is currently executing.

Figure 197 – Pause/Resume a Plan/Job

Like Disable and Enable, Pause and Resume are in-context operations. You may only Pause an executing object. Pause and Resume require “Manage” access permission for the Queue the job is executing on as well as “Read” access permission on the selected Job object. To pause or resume a job right click on the selected Job icon and choose Pause/Resume. Note you cannot pause a non-executing job.


Operating System Note: The implementation of Pause differs based on O/S platform. For Windows systems, only the primary thread of execution associated with the process is suspended. For multi-threading applications this may not have the desired effect. For non-Windows systems, the job process is suspended.

6.3.1.6 Restart Plan/Job Execution

This operation allows you to restart a failed plan/job instance. The plan/job instance is restarted in its entirety. Restart should not be confused with Trigger. Trigger causes a new plan/job instance to be created. The Restart operation causes an existing instance to begin execution.

If you restart a Plan then all job/plan instances are restarted regardless of their previous execution. If you restart a Job then that job instance will begin execution and any Completion and/or Alert triggers will be honored regardless of the previous job instance state.


308

6.3.1.7 Moving a Job from/to a Queue

Sometimes you need to move a Job from one Queue to another. Moving a Job requires you to hold “Write” access to the selected Job object.

As a designer you can move a job definition from one queue to another by entering Design View for the job you wish to move. Select the destination queue from the designer’s navigation tree and drag the queue and drop it on the desired job. A confirmation dialog will appear. Click OK to move the job to the destination queue or Cancel to cancel the operation.

To move or re-queue job instances(s) that are in a “Waiting” state, select one or more Job(s) and choose Requeue. A list box appears listing all queues. Select one to perform the move operation. This operation will move only instances.

Figure 198 – Requeue Operation


309

6.3.2 Definition Operations

6.3.2.1 Test Run

This operation allows you to validate whether the security credentials of the plan/job will work. The plan/job itself is not executed. This operation is valid only for Plan/Job definitions (Template). When a single job is selected a message box appears indicating the success or failure of the test run. When a plan is selected, the contents of the plan are displayed in a window with a status indication for each nested job or plan’s test run. The entire plan is tested although a Cancel button allows you to abort the test run.

Figure 199 – Test Run Plan (Initial)

If multiple objects were selected you can either manually deselect them or use the convenient Select/Clear All buttons.


310

Figure 200 – Test Run Plan (After)

A real-time display shows each object as it is tested and its result.

Note: Test Run is currently restricted to jobs that are assigned to an Execution Queue. If you issue a Test Run with a job assigned to a Generic Queue the result will be failure even though the job may very well be able to run on any of the member Execution Queues.


311

6.3.2.2 Trigger Plan/Job Execution

ActiveBatch allows the submission of plans/jobs that can execute one or more times based on a variety of date/time or event triggers. The “Trigger” command allows a user or script to generate an ActiveBatch event that starts a job template executing. This trigger allows some interesting uses.

Figure 201 – Triggering a Job

To trigger a plan/job right click on the selected icon and choose Trigger or Trigger (Advanced). The difference between the two Trigger operations is that advanced Trigger will display a dialog box providing more operations you can perform. The simple Trigger operation just triggers the object immediately for execution. Triggering a plan/job requires you to hold at least “Trigger” access permission for the selected object. The object must have ActiveBatch Triggers enabled (see Scheduling/Event tab). A job may be triggered from any ActiveBatch Queue however most trigger jobs are “On Demand” and reside on the OnDemand Queue.

This operation is valid for Plan/Job Definition’s (Template) only.


312

Figure 202 – Trigger Job Dialog

The dialog box above is presented to determine what actions should be taken with the trigger. If the Job resides on the OnDemand Queue you must specify a Generic or Execution Queue for the triggered job to execute on. Please note that the template job is not copied to the Queue you specified; only the instance of the job is created on the Queue. If the Job does not reside on the OnDemand Queue, you may trigger its execution in place (in other words, the job will start execution on the Queue it was submitted to).

Queue to trigger to: You may specify a Queue that is to receive an instance of this Job for execution. For a job that resides on the OnDemand queue you must specify a different queue. “Trigger and Queue” access permission for the selected job is required. This checkbox will not appear for a Plan.

Parameters: This optional field may be entered to provide new input parameters to the newly created instance of the triggered job. Note that the job template is not changed by this operation. Enabling this radio button will activate the “Edit” button allowing you access to the familiar Variable dialog page. You must have “Trigger and Change Parameters” access permission for this Job to enter new parameters.


313

Variables: This optional field may be entered to override any variable values that were specified with the object definition and/or to create new variables (and their values). Note that the object definition is not changed by this operation. You must have “Trigger and Change Parameters” access permission for this object to enter new variables.

Account Information for Execution Machine: You may specify alternate security credentials to be used when triggering this job for execution. By default, any security credentials associated with the job are used. This feature is particularly useful when you have multiple users who need to execute the same job but in their own security context. You can specify the credentials through the familiar username/password fields as well as by specifying a Username object. To trigger and specify new credentials requires you to have “Trigger and Change Credentials” access permissions on the selected Job object.

Ignore Completion/Alert Triggers: If selected, ActiveBatch will ignore any Completion and Alert triggers associated with this plan/job. (Note: In previous versions this was referred to as “Ignore Batch Starts”).

Ignore Alert Notifications: If selected, ActiveBatch will not issue any Alert notifications.

Ignore Dependencies: If selected, you are indicating that ActiveBatch is to avoid dependency checking and treat the selected plan/job as though all dependency checks were successfully performed.

Ignore Calendar: If selected, ActiveBatch will ignore any Calendar restrictions and run the job.

Ignore Exclusion List: If selected, ActiveBatch will ignore any date/time scheduling exclusions.

Defer til: If selected, this useful function allows you to defer the actual trigger to a later date/time. By default, when a Trigger command is issued, the object instance is created immediately.


314

6.3.2.3 Copy and Paste a Plan/Job

This pair of operations is actually performed by the ABATAdmin program as opposed to ActiveBatch itself. Sometimes you want to create a job using most of the information found in another job. ABATAdmin let’s you do just that.

To copy a job right-click on the selected Job icon and choose Copy. This action makes a copy of the Job object.

To paste the copied job, select a Plan or the Jobs & Plans folder and then right click and choose Paste as New Job. The New Job property tab dialog will be displayed allowing you to change any properties concerning your new job. All job properties will be set in the newly pasted job except that your username and security credentials (if any) will be used. If they are not present you will need to enter them. You will also become the owner of the newly created job. Clicking OK confirms the job submission. Clicking Cancel indicates that you want to “undo” the paste operation and not submit the job. The job will, however, remain in the copy buffer. Please note that you must have “Read” access permission to copy the initial Job object.

6.3.2.4 Cut and Paste a Plan/Job

Sometimes you need to move a Plan or Job from one Plan to another. With Cut and Paste you can select the object and choose Cut. You must have Read and Delete access to the object.

To paste the cut object, select the Job Scheduler icon or a plan you want the object to be pasted to and right click to select Paste. The original object will be pasted at that level.


315

6.3.2.5 Browse

The Browse operation is performed on a Plan definition and, when executed, causes a separate window to appear displaying the nested contents of the Plan. Browse is particularly useful when you need to display the contents of several nested plans. Each plan can be displayed in a separate view.

Figure 203 – Browse Plan

In the above example, plan CaseStudy8 contains the embedded jobs and plans.


316

6.3.3 Definition and Instance Operations

6.3.3.1 Abort/Delete a Plan/Job

You may abort a Plan/Job Instance regardless of state. Aborting a plan/job will mark the object as “Completed(Aborted)”. The plan/job will still be visible for query purposes.

Deleting a Plan/Job will cause the object to be removed from the database. So object deletion is a permanent and irreversible operation. By definition, when you delete an object you also delete the object’s instances (if any). Both Abort and Delete require confirmation since both operations are potentially destructive.

To abort a Plan/Job Instance you must have “Manage” access permission on the object. To delete an object you must have “Delete” access permission. To abort an instance right click on the selected object and choose the Abort menu operation.

When you abort an instance, a confirmation dialog appears asking you to confirm the operation. Click OK to confirm or Cancel to cancel the operation.

Figure 204 – Abort an Instance Dialog

When you want to delete an object, a confirmation dialog appears asking you to confirm the operation. Click OK to confirm or Cancel to cancel the operation.

Figure 205 – Delete a Job Dialog

ActiveBatch also supports the Abort and Deletion of an Instance and it’s objects in a single operation. Simply right-click on the object and choose Abort & Delete.

Note: Deletion of an object is an irreversible operation. There is no “un-do”. Please make sure that you really want to delete the selected object.


317

6.3.3.2 Abort Batch

The previous operation allowed you to abort a specific job or plan. Sometimes it is more convenient to abort an entire batch run regardless of which object happens to be executing at the time. To issue an Abort Batch operation, right click on any instance within the desired batch and select Abort Batch.

The following confirmation message will appear to confirm your selection.

Click the Yes button to perform the Abort Batch operation.

Note: You must have Manage level access permission to perform this operation.

6.3.3.3 Hold and Release a Plan/Job

Sometimes it is useful to hold a plan/job and prevent its execution. This capability is also available if the instance has been created but not yet run (for example, the “Not Run” state). ActiveBatch provides this operation through the Hold and Release (Disable/Enable) facility.

Figure 206 – Hold/Release a Plan/Job

Hold and Release are in-context operations. That means that ABATAdmin will choose the proper operation for you to perform based on the state of the job. If the job is not held, you will be able to hold it. If the job is held you will be able to release it. Hold and Release, while job oriented, do require “Manage” access permission for the Queue that the job is on as well as “Read” access permission on the selected Job object. To hold or release a job either right click on the selected Job icon and choose Hold/Release or select the Job icon and choose Job/Hold/Release from the menu bar. Note the job must be in a Pending state (so you cannot hold an executing job). Holding a template job causes no new instances to be created while the template is held.

Note: Do not confuse the Global Disable property with the Enable (Release)/Disable (Hold) operation. Global Disable means that this object and all reference objects are disabled.


318

6.3.3.4 Printing ActiveBatch Objects

AbatAdmin provides the ability to print various ActiveBatch objects in a “holistic” view. For each object look for the “Print” operation.

Figure 207 – Print Queue Operation

The figure above shows how you would print the selected queue “Server1”.

Figure 208 – Sample Print Queue

The figure above shows a portion of the queue’s characteristics. Note that all of the collections (or related sub-objects) that make up the queue are also displayed. The “printout” produced is an HTML file which can be saved via the Save as… button or printed using the Print button. Each object is printed through the use of a template file. This template file consists of standard HTML tags and special syntax allowing any of the queue’s properties to be retrieved and inserted as desired within the printout. All templates are stored within the Templates sub-directory.


319

6.4 Resource Operation A resource object that uses an active variable can be forced to re-evaluate.

Figure 209 – Resource - Evaluate Now

Selecting the “Evaluate Now” operation causes the resource’s active variable data source to be immediately re-evaluated regardless of any timed or lack of timed base settings.


320

6.5 System View System View is a real-time dynamically refreshing display that is capable of showing both relationships and job/plan instance status at the same time. The Design and System View do share many common features. You’ll notice that the title bar and zoom/auto layout features are the same. Where System View diverges from Design View is System View’s ability to dynamically display active jobs as they run. Because System View can display more information you can also control more aspects of ActiveBatch.

6.5.1 System View Overview

The first job ran successfully (you can tell because the box is Green). The middle job (TestJob2) is currently running (you can tell box is Blue and the number 1 in the upper left-hand corner indicates the number of active instances).


321

Figure 210 – System View (Tool Tip)

While a lot of information is displayed within the Job box you can get more information by simply hovering over the box. The tool tip that’s displayed contains much more information in particular about the last active instance (if any). The above figure shows how the last instance for Job “TestJob1” performed.


322

6.5.2 System View Shapes System View and the Design View use various shapes and colors to impart Plan/Job information. System View is dynamic and its use of color and shapes is particularly important.

The Rounded Box shape is used to denote a Job.

The Folder shape is used to denote a Plan.


323

6.5.3 System View Colors System View uses colors to quickly denote a Job’s operational state. The color itself is displayed in a gradient fashion.

Yellow is used to denote a Waiting for Trigger status.

Orange is used to denote a Waiting on Constraint status.

Sea Green is used to denote a Waiting on Queue Busy status.

Cyan is used to denote a PreProcessing status.

Blue is used to denote an Executing status.

Grey is used to denote a Disabled status.


324

Red is used to denote a recently completed but failed job.

Green is used to denote a recently completed successful job.

Purple is used to denote a recently completed but aborted job.

Note: The primary box color stays resident for a small period of time (which is adjustable by you through the Options menu). The side bar color is persistent and indicates how the last Job instance fared. This side bar color stays resident until another Job instance is created.

Completion Triggers and Instance Constraints Completion Triggers are drawn as a solid line. On Success is colored Green. On Failure is colored Red.

Constraints are drawn as a dotted line. On Success is color coded Green. On Completion is colored Blue.


325

6.5.4 System View Job/Plan Operations

Figure 211 – System View (Job/Plan Operations)

By right clicking on the selected Job you can perform various operations. The individual job operations have been covered in other sections of this manual; however, you can multi-select jobs in this view to perform a single operation on many jobs. If the Job has active instances a special form of this menu is available which allows you to control a specific instance. Operations performed on a Plan may affect all the objects within the plan.


326

Figure 212 – System View (Active Instance Menu)

The above figure shows an active instance for JobA. Instance 112364 can be individually controlled based on its state. Notice the grayed out portion titled [Template Operations]. The menu operations below that divider affect the plan/job definition, not the instance. The menu for instance 112364 displays those operations that can be performed on that instance. If JobA were running multiple instances, then a sub-menu operation for each instance would be shown.


327

6.5.5 System View Operations

Figure 213 – System View Operations

The figure above shows a simple “straight-line” relationship between Jobs “testjob1”, “testjob2” and “testjob3”. Before we discuss what operations we can perform on those objects, observe the menu to the right of the figure. This menu was obtained by right clicking on the “white space” of the display. Several of the operations are common to other views within ActiveBatch. For example, Control/F allows you to have the System View display use the full screen. ActiveBatch supports printing this window (as well as Print Preview). This is useful for documentation purposes. You can also integrate this picture into another object (like a Word document) using Save as Image. The image is saved as a Windows Metafile. When the display contains a great many jobs the Find Job function provides a quick way of locating a specific job.


328

6.5.5.1 Find Job (System View)

Figure 214 – System View (Find Job)

The dialog above will list all jobs that are displayed. You simply double-click on the Job you want to locate in the System View display. ActiveBatch will blink the located Job “n” times (see Section 3.5 for Options Preferences) in the display. Enabling the Also Zoom to 100% checkbox will change the Zoom factor when the Job is located.


329

6.5.5.2 Printing (System View)

You can Print (or Print Preview) the System View by selecting the Print (or Print Preview) operation.

Figure 215 – System View (Print)

The above figure is displayed for Print and Print Preview operations. You can indicate whether to print the graphical view in portrait or landscape mode, whether to “fit to page” or print using the same view scale and to also, optionally, indicate a “footer” message (the default is “ActiveBatch”). When Printing, a standard dialog box will appear asking you to select a printer. In Print Preview mode you will see the first page. You may right click and select the next or previous page. If you double-click you can zoom in for greater detail. To close the Print Preview page, simply right-click and select “Close”.


330

6.5.5.3 Miscellaneous Operations (System View)

You can copy the graphical image to a clipboard or save the image as a Windows Metafile.

By default, the System View is displayed along with other windows. To enter Full Screen mode press Ctrl/F.


331

6.6 Troubleshooting ActiveBatch was designed to assist operators and designers track down their batch job problems. The sections that follow discuss some of the features that can be used to determine why ActiveBatch did or didn’t execute a job as well as determining why a job didn’t perform properly.

First, you need to remember the difference between a definition and an instance. An instance is an execution copy of an instance. When something goes wrong you want to check the instance’s history and the copy of the instance properties that were present at the time the instance was cloned.

Figure 216 – Job Instance History

The figure above shows the instance of job CaseStudy1. The History category displays a lot of useful information about the job. As you can see this job was successful.


332

6.6.1 Audits The Job Audit area is the first place to look when a question arises as to ActiveBatch/Job interaction. All exchanges between ActiveBatch and the Job are recorded in this area.

The audit box extract above is for a job instance and tracks the job from submission to end.

The audit box extract above is for a job definition. Audits are produced each time the job is modified as well as each time a job instance fails to execute. Successful job instances are not audited since the Instances pane allows for easy retrieval.


333

6.6.2 Job Output Logging ActiveBatch jobs have great flexibility in the area of logging. Logging in the ActiveBatch context means the capture of a job’s standard output and error streams. These streams (usually found under different names depending on the operating system) are available for every job.

6.6.2.1 User Managed Logging

The example above is the default logging properties for a job named JOB-A. ActiveBatch, by default, uses the same location and filename as the main job step. The extension .LOG is added. When JOB-A is started all data to the standard output and error streams will be directed to “c:\JOB-A.log”. If you don’t like the defaults you can always change the entire file specification. If the job is a template job and is subject to multiple runs then the file specification is used above except that the job-id, date and time are also appended to the filename portion. The intent of this is to make the file specification unique such that other instances of the same job don’t overwrite each other. Clicking the checkbox Std Error File causes the standard error stream to be directed to a separate file that is different than that used for standard output.

If the Reuse same log file checkbox is enabled then the same log file name is used even for recurring job runs (this means that the job-id, date and time are also not added). This feature is useful when you are only interested in the last job instance and don’t want to fill your log file directory up with lots of useless files.

Platform Note: On OpenVMS, the Reuse feature will result in multiple versions of the same log file. This is intended. You can always purge the versions down using the OpenVMS command PURGE.

Logging in this fashion is referred to as User Managed. That is because you are required to manage the files (purge them, etc).


334

6.6.2.2 Centrally Managed Logging

Another choice is for ActiveBatch to manage the log files. After all many users don’t care about the batch job log unless the job fails. By clicking the radio button Centrally Manage Log File you enable this facility. This means that the location and name of the log file is completely left to ActiveBatch. So what do you gain?

Using this feature provides you with two major benefits.

1. If you noticed, enabling this feature also provides you with the ability to indicate the log file retention period. In the example above, ActiveBatch will delete the log file after one (1) day. That’s one less thing you need to do.

2. Your log file can now be viewed from any participating machine without you having to first copy it to your local system. The ability to view a log file can be found on the Job History tab.

Clicking the “View Log File” button (the second from the left) will cause an editor to be started with the job’s log file. By default, Notepad is the editor used. You can change the default editor via the Tools/Options menu.

335

7 REPORTING

7.1 Reporting Overview The ActiveBatch Reporting Facility allows you to generate customized reports concerning the scheduling and execution of ActiveBatch jobs. You can access the Reporting facility through the View\Reporting Facility menu item on the menu bar.

Figure 217 – Reporting Facility

When you click on the Reporting Facility selection you will see a dialog box similar to Figure 218.


336

Figure 218 – Report Files Dialog

This dialog box serves several purposes:

1. A list of existing ActiveBatch Reporting (.ABR) files are displayed.

2. You can create, edit, rename or delete ActiveBatch Reporting files.

3. You can select a Job Scheduler machine and run a desired report.

The top-level drop down list displays one or more entered directories in which you store your ABR files. By default, ActiveBatch stores your files in your “My Documents” folder. You can browse and select other folders by either entering a valid specification or by clicking on the button.

Chapter 7 - Reporting

337

7.2 Creating a Reporting File An ActiveBatch Reporting file is not a report rather it is a template that can later be used to generate a report. To create a new Reporting file click on the New button.

Figure 219 – Enter Report Filename

You are asked to enter a filename that will be used when creating the Reporting file. As the “Note” above explains do not enter an extension or a path specification. Just enter a filename such as SampleReport and then click the OK button.


338

Figure 220 – Report Filter

This dialog allows you to create your Report. You can specify search criteria, what columns (fields/properties) to display and their sorting order.

Let’s divide the Report Filter dialog into several sections for easier discussion.


339

7.2.1 Column Selection This part of the dialog allows you to select one or more Job properties (columns) that you would like to report on. You’ll notice that this section of the display contains three (3) headings: Property Name, Type, and Description. Property Name is self-explanatory. Each property is uniquely named. Each property typically corresponds to a database column found in one of the ActiveBatch database tables. Type indicates whether the property is historical (and therefore may or may not be present) or not. Description describes the property. You select columns for display by selecting a property and then click on the Add to Report button. That will cause the property to move down to the Columns to display in report control.

Figure 221 – Property Column Selection

In Figure 221 several columns have been selected. The columns will display in the order they are listed. To change the ordering select the desired column and use the UP and DOWN arrow buttons on the right side of the control.


340

Figure 222 – Selecting/Sorting Columns

To sort the report into any special sequence, simply select a property in the Columns to display in report and click the button. That will add the property to the sort list. To change the sorting order, use the UP and DOWN arrow buttons that are part of that control. Normally the sorting order for a property is ascending. To change the order, select the property and click the Toggle Sort button. To remove a sorting property, select the property and click the Remove from sort button.

7.2.2 Search Column Criteria Once you’ve selected your columns for display you can add search criteria using two (2) methods. The first is to select a property and then click the Edit Search Criteria… button.

Figure 223 – Property Search Criteria

Figure 223 shows a sample search specification. You can select one from a number of comparison operators followed by the comparison value.

In the figure above, search criteria has been added for the “Name” property (that is to display only job names with


341

“DailyBackup”.

The second approach is to enter SQL syntax into the Additional “Where” clause field. This is useful when you need to perform additional WHERE clause operations that wouldn’t otherwise be supported by the report generator.

This example illustrates pattern matching for the Job Name. When specifying additional “Where” clauses please note that you must ensure that any property in the “Where” clause is also present in the “Columns to display in report”.


342

7.2.3 Date Specification

Figure 224 – Report Date Specification

One of the most important search criteria is the date specification. By that we mean the date or range of dates that the report will encompass. You have three (3) selections to choose from. No Date Range essentially allows you to report on the entire database. Fixed Date allows you to select a range of specific dates and times. Relative Dates allows you to indicate self-relative dates based on when the report is submitted.

You can also select the state of the Instances, for example, Completed, Held, etc. The checkbox allows you to include Plans (by default, only job instances are reported).

7.2.4 Custom SQL

For advanced SQL users you can enter a complete SELECT statement by clicking on the Custom SQL statement field.


343

7.3 Version 4 Reporting Files If you’ve created Report files using Version 4 you may see a screen similar to this. If you click on the report file a prompt will appear asking whether you wish to convert the reporting file to the newer version. This is a simple but irreversible process.

Figure 225 – Converting a Prior Release Report file

Clicking Yes will convert the file for use with this newer version. You will not be able to use the Report file for the older version. Click No to avoid the conversion process (however the file cannot be used under this release).


344

7.4 Generating a Report Once you’ve created a Report file you can generate a report. You have two (2) methods of generating a report within ActiveBatch. One is to use AbatAdmin interactively the other is to use the console app abatrptgen. The later is particularly useful for generating reports within an ActiveBatch job itself.

The ActiveBatch Reporting facility works best when ODBC/OLE-DB is installed and available. You should see excellent report generation performance when using this method. However, there may be some occasions when ODBC/OLE-DB or connection to the ActiveBatch database is not feasible. In this case, ActiveBatch will use its COM model for generating reports. When using the COM model, the following restrictions are present: No direct SQL use is allowed and the generation of the report will be significantly slower as compared to using the direct database access method.

The security credentials used when generating a report varies depending on the database authentication model in use. For Windows authentication, by default, your Windows logon credentials are used when generating an ODBC based report. If your logon credentials fail, ActiveBatch will prompt for new security credentials. For Database authentication, by default, the DB Username is specified and you must supply the password. If Database Authentication fails, you will be prompted to confirm the use of COM (RPC) for report generation. As stated previously, COM is significantly slower than ODBC access.


345

7.4.1 Interactive Report Generation

Figure 226 – Generate Report

To generate a report simply select the ActiveBatch Report file and a connected Job Scheduler system. Then click the Run/View Report button. To obtain a report using different reporting dates, click the Run/View Report (Advanced) button. An additional dialog appears with From and To date and times.

Figure 227 – Advanced Report Generation


346

Figure 228 – Sample Report

The above report was produced using the SanpleReport ABR file. The columns displayed and the overall report are self-explanatory. Note the last 2 items in the report footer. ODBC Connect String can be useful when you need to write your own reports using third party report writers or tools. Likewise SQL Statement shows you the exact SQL SELECT statement that was issued to produce the report.

Reports can be displayed for simple viewing or printed. You can also save generated reports (as HTML files) for later viewing. Users of the ActiveBatch Webserver product can also save these HTML files to a “reporting” location for later viewing by your end-users.


347

7.4.2 Non-Interactive Report Generation In addition to the use of AbatAdmin you can also generate reports non-interactively through the console app AbatRptGen. AbatRptGen supports both the ODBC (preferred) and COM methods for generating reports.

ODBC Method:

AbatRptGen -r ReportFile -o OutputFile -d OdbcConnectString [ -t OutputType ]

ReportFile ActiveBatch Report File (.ABR)

OdbcConnectString ODBC Connect String (see Section 7.4.1 and the comment concerning ODBC Connection String).

OutputFile Report Output file that is generated

OutputType (Optional) Report Output Type (HTML, CSV, XML)

Note: -c ReportFile allows you to convert from an older report file version to the latest version.

For example, to invoke the same report that we produced interactively (in the previous section) the command might be:

Abatrptgen -r “c:\program files\asci\activebatch\reports\SampleReport.abr” -o SampleReport.html

-d “Driver=SQL Server;Server=ENGSERVER1;Database=ASCIABAT”

This convenient command not only generates report files but can also generate a CSV file which can be used to import the report data into a variety of other third-party tools. AbatRptGen can also generate an XML file for simplified parsing and data formatting.

COM Method:

AbatRptGen -r ReportFile -o OutputFile -j JSSMachine [ -u UserName ] [ -p Password ] [ -t OutputType ]

ReportFile ActiveBatch Report File (.ABR)

OutputFile Report Output file that is generated

JSSMachine Job Scheduler machine name (or IP address)

UserName (Optional) Valid Windows Domain\User Account

Password (Optional) Password for above account

OutputType (Optional) Report Output Type (HTML, CSV, XML)

If User Security credentials are omitted then the current logon credentials are used.

Note: The COM method has the following limits:

• No Date Range can be specified.

• No Custom SQL statement or WHERE clause can be specified.

• Job Templates can not be displayed in the report.


348

7.4.3 Third-Party Tools/Report Writers With ActiveBatch’s use of ODBC-compliant databases you are free to use any tool or report writer (such as Business Intelligence’s Crystal Reports) to query the database.

349

8 DATE ARITHMETIC

This chapter discusses the Date Arithmetic facilities of ActiveBatch. Date Arithmetic can be used as part of Job Scheduling and/or to perform date arithmetic calculations within an ActiveBatch script.

8.1 Introduction and Syntax Date Arithmetic is a facility in which dates can be computed through a specification of various date tags. The resulting date itself can be produced in a variety of formats. Date Arithmetic can be used within ActiveBatch in four (4) areas:

1. As part of a Custom date specification in a Schedule.

2. As part of the Parameters field for a Process or Script job.

3. When declaring an Active Variable.

4. With a standalone program, on an execution machine, that can perform Date Arithmetic substitution on an input file and produce a new “substituted” file.

The Date Arithmetic syntax is simple; you start with a left angle bracket (<) followed by a command and zero or more qualifiers ending with a right angle bracket (>). For example, <TODAY> would yield today’s date. The difference between a command and a qualifier is that a command represents a specific date; for example, TODAY or YESTERDAY represents specific dates. A qualifier is used to perform some type of calculation on a date. For example, <TODAY/-DAY> would mean “today minus 1 day”.

What benefits do you get from the Date Arithmetic facility? First, most business applications require the use of dates for generating various reports, aging of database records, etc. The ability to calculate dates, in various formats, can satisfy this requirement. Next, while the Schedule object itself is useful for generating date/time triggers when a pattern is present (i.e. every other Monday, etc) it’s not as easy to use when several non-pattern dates must be entered. This non-pattern date list is easily accomplished with the Date Arithmetic’s calendar facility. You can create a calendar of dates, using the point-and-shoot method and then specify that calendar as part of a Schedule object’s Custom property.

8.1.1 Commands A command yields a specific date and may be used without any qualifiers. The following table displays the commands that are supported by ActiveBatch’s Date Arithmetic facility.

Command Description

TODAY Today’s date

TOMORROW Tomorrow’s date

YESTERDAY Yesterday’s date

BOM Beginning of Month

EOM End of Month

BOW Beginning of Week

EOW End of Week

BOY Beginning of Year

EOY End of Year


350

Command Description

BOQ Beginning of Quarter

EOQ End of Quarter

YEAR Year

MONDAY – SUNDAY Day tags for all seven days

Table 26 – Date Arithmetic Commands

The commands above, unless otherwise specified, assume today’s system date. The system date is the date supplied by the platform operating system. While several of the above commands are self-explanatory, there are several that do require an explanation. By default, BOW is the beginning of the week, which is Monday. EOW is the end of the week, which is Sunday. BOQ is the beginning of the quarter and assumes a calendar year, while EOQ is the end of the quarter (and makes the same assumption). MONDAY through SUNDAY commands use an integral week. For example, if today is October 1st and that date is a Wednesday, the MONDAY tag would be September 29th, TUESDAY would be September 30th and WEDNESDAY would be October 1st, etc.

There is one special command that is missing from the table. DATE is a tag that can be used depending on the context of the operation. DATE represents an ActiveBatch supplied or customer supplied date. We’ll talk more about the DATE command as we progress through this chapter.

8.1.2 Qualifiers Qualifiers perform the actual date arithmetic and computation. Zero or more qualifiers can be specified and the date arithmetic is performed from left to right eventually yielding a date. The date is substituted based on the date format. By default, dates are displayed as ddmmmyy. The following table displays supported qualifiers.

Qualifier Description

/±DAY=n Add or subtract days. If n is omitted, 1 is used.

/±WEEK=n Add or subtract weeks. If n is omitted, 1 is used.

/±MONTH=n Add or subtract month. If n is omitted, 1 is used.

/±QUARTER=n Add or subtract quarters. If n is omitted, 1 is used.

/±YEAR=n Add or subtract years. If n is omitted. 1 is used.

/±MONDAY=n Add or subtract Mondays (you can replace MONDAY with each day). If n is omitted, 1 is used.

/NEXT Move forward 1 unit (unit depends on current context)

/LAST Move backward 1 unit (unit depends on current context)

/SUPPRESS Suppress leading characters

/FORMAT=format-spec Produces date using date specification string.

Table 27 – Date Arithmetic Qualifiers

The qualifiers found in the above table add or subtract to the starting date to produce a new date that is then used in any additional calculations. For example, <BOM/-WEDNESDAY> means the last Wednesday of the previous month. You can also specify a value without a qualifier in which case “days” are assumed. For example, <TODAY/+5> means 5 days from the current date.

Chapter 8 - Date Arithmetic

351

Examples:

<BOY/+MONTH=5/-DAY/-MONDAY> would yield Memorial Day (US holiday).

<BOM/+MONDAY> would yield first Monday in month

<TODAY/+FRIDAY> would yield next Friday

Format Qualifier Description

/FORMAT=ddmmmyy Default date format

/FORMAT=dd Numeric day of month

/FORMAT=ddd Abbreviated day of week (e.g. Mon, Tue, etc)

/FORMAT=dddd Alphabetic day of week (e.g. Monday, Tuesday, etc)

/FORMAT=mm Numeric month number

/FORMAT=mmm Abbreviated alphabetic month (e.g. Jan, Feb, etc)

/FORMAT=mmmm Alphabetic month (e.g. January, February, etc)

/FORMAT=yy Two digit numeric year

/FORMAT=yyyy Four digit numeric year

/FORMAT=jjj Julian day of year (001-365 or 366)

/FORMAT=ww Week of year

/FORMAT=hh Hour (00-23)

/FORMAT=mi Minute (00-59)

/FORMAT=ss Second (00-59)

/FORMAT=cc Fraction of second (00-99)

Table 28 – Format Qualifier

You can also format a date with slashes (/) however the string must be quoted (i.e. /FORMAT=”mm/dd/yyyy”).

8.2 Custom Schedule Specification When Date Arithmetic is used as part of a custom schedule specification you can specify any valid Date Arithmetic tags except /FORMAT.

The Custom portion of a date specification in a Schedule consists of two parts: a calculated date and another calculated date in the event the first date falls on a non-business day. The calculated date is straightforward and consists of one or more Date Arithmetic tags. The second calculated date (if the first falls on a non-business day) supports an additional command: DATE. The command DATE represents the first calculated date. This allows a second date arithmetic specification to start with that date. For example, <DATE/-FRIDAY> means use the previous Friday from that date or <DATE/+TUESDAY> might mean use next Tuesday. You are under no obligation to use the DATE command. You can use any other command and qualifier set of tags.

The example above equates to the last Monday in May.


352

8.3 Variables and Process/Script Input Parameters You can also use Date Arithmetic as part of your input command-line parameters (using the Parameters property). Simply specify the Date Arithmetic tags. When Date Arithmetic is used in this manner there are several other tags that can be specified.

8.4 Fiscal Calendar and User Date Tags The date tags specified in Table 29 allow you to perform date calculations on Gregorian dates. For business date calculations a fiscal date must typically be used. The Date Arithmetic facility allows you to create a calendar in which you can specify fiscal dates for a given year. For example, you can indicate begin and end dates for a month or quarter for a specific fiscal year.

Tag Description

/CALENDAR=file-specification A calendar file. The file specification is an Execution Machine accessible file representing a calendar.

/BOFY /EOFY Fiscal Beginning and End of Year (valid only when /CALENDAR is specified)

/BOFM /EOFM Fiscal Beginning and End of Month (valid only when /CALENDAR is specified)

/BOFQ /EOFQ Fiscal Beginning and End of Quarter (valid only when /CALENDAR is specified)

Table 29 – Calendar Date Arithmetic Tags

The calendar file is created using the Date Arithmetic GUI program (AbatDateAdmin). This program allows you to create a calendar file. A calendar file contains the above fiscal date tags as well as any other “user” date tags you decide to create. Each date tag can have zero or more date values associated with it. Finally, all date values are contained within a single fiscal year. This means that a valid calendar file should have date values for at least one (1) fiscal year. You can store multiple fiscal years within a single calendar file. AbatDateAdmin produces an XML file that in turn can be used to produce a binary image calendar file. The calendar file is used by the Date Arithmetic facility for fiscal date processing. This file can be downloaded onto one or more execution machines. You can generate as many calendar files, as you need.

You can also create your own date arithmetic tags. Naming rules are quite simple. You can’t name your tag so it conflicts with one of the built-in tags mentioned in this chapter. You can identify a date tag as having begin/end context. Using best practices, we recommend adding a B or an E to your date tag. So just as BOM means “beginning of month” you could create a date tag such as BSALES (beginning of sales period) and ESALES (end of sales period). There is no requirement that you create both sets of date tags. The following date tags are reserved for future use and cannot be specified: HOLIDAY, HOLIDAYS, BUSDAY, NONBUSDAY.


353

8.5 Date Arithmetic Calendar Administration AbatDateAdmin is a Windows GUI program that is used to create Date Arithmetic calendar files for fiscal and user specified date tags. Remember that you don’t have to create a calendar file for simple Gregorian calendar date tags (and their values).

When AbatDateAdmin first runs, the following dialog is presented:

This simply allows you to quick way of either creating a new calendar file or opening an existing one.

8.5.1 Creating a Date Arithmetic Calendar To create a new calendar file, run AbatDateAdmin (from the ActiveBatch Program Group menu) and select “File\New”.

Figure 229 – Creating a new Date Arithmetic Calendar

The calendar needs to be named (a simply default name of NewAbatCalendar.xml is provided). You can also specify an optional description. When you initially create a calendar you will also be prompted to create a fiscal year. A fiscal year consists of the year value itself as well as the staring and ending day of the fiscal year.


354

Figure 230 – Specifying a Fiscal Year

As you can see this dialog is divided into three (3) major areas (other than the top field that notes the fiscal year). You need to specify the beginning and ending dates for the fiscal year. By default, Gregorian calendar dates are used. The next second beneath the initial limits of the fiscal year are the Fiscal Quarter limits. The third section denotes each fiscal month.


355

8.5.2 Assigning Dates to a Date Tag Once you’ve created an initial fiscal year you’ll see a window similar to this:

Figure 231 – Date Arithmetic Date Tagging

The calendar is set by default to the beginning month of the fiscal year. A dropdown above the calendar allows you to quickly choose different fiscal years within the calendar. The current month is shown with a Back and Next arrow allowing you to navigate to other fiscal months.


356

Next, you will probably want to create Date Tags to associate business dates for possible date arithmetic use.

You have two (2) methods for adding a Date Tag. You can select Tag\Add Tag from the Menu bar or you can click on the ADD button in the Date Tag area. Either approach will produce the following dialog.

Figure 232 – Create Date Tag

In the above example, we’re creating a tag named “MON_RPT_RUN” which will represent a date each month that we need a certain report run. Click OK to create the Date Tag.

The figure above shows the tag in the date tag list. Next, you can associate dates with that tag. The easiest way of associating date(s) is to simply click on the calendar month and date that’s displayed. Each click adds your selected date. So if I want to add January 7 and 21 to the MON_RPT_RUN tag, I would click on 7 and 21. The date’s list would look like this:


357

To manually enter dates against a date tag, you can use the edit box (next to the ADD button in the dates list) to enter a date..


358

If you made a mistake, press the DELETE button on the keyboard and the last date value will be removed. Alternatively, you can select one or more dates or date tags and then right click to delete them.

Note: A date value can appear on multiple date tags. After all, January 1 could be the start of the fiscal year, month and quarter.

Once a date has been associated with a date tag the date changes color to light blue as a visual clue that the date has been associated.

8.5.3 Managing Date Tags Once you’ve assigned dates to the built-in fiscal date tags you may want to create your own date tags. Remember that a date tag simply refers to one or more dates. To create a date tag, click on the Menu bar under “Edit\User Date Tags”. You’ll see a dialog box that will allow you to name the date tag and specify a description for the tag. To create the tag, click on the Add button. For example, you can create a date tag named PAYROLL that is expected to be the dates when your company pays its employees. That date could be every other Friday except when a month has five weeks. When you specify PAYROLL as in <TODAY/PAYROLL> you mean the next payroll date. Another example might be to create two date tags: BMANURUN and EMANURUN. That means <BMANURUN> would refer to the beginning of the manufacturing run and <EMANURUN> would be the end of the manufacturing run dates. ActiveBatch best practices calls for a beginning type date tag to begin with the prefix B and an ending date tag to use the prefix E. You can create a date tag with no date values. Typically a date tag will have values and B/E prefix date tags would have the same number of date values. If you want to modify the date tag, for example, change its name or description, click on the Edit button and update the desired fields.

If you decide to delete a date tag, you would select the Delete button. You’ll receive a confirmation message box asking you to confirm the deletion.

8.5.4 Save, Save As and Compile Once you’ve created your calendar and applicable fiscal years you need to output the binary calendar file. The Save and Save As operations cause AbatDateAdmin to output an XML file. The XML file can be easily saved or subjected to source control tracking. The Compile operation causes AbatDateAdmin to output a binary calendar file. The binary calendar file is what is actually used by the Date Arithmetic system to perform it’s date calculations, not the XML file. By default, AbatDateAdmin will implicitly create a new binary calendar file whenever the Save or Save As commands are performed (in other words an implicit Compile is performed). This preference can be changed via the Options menu.

Once you create the binary calendar file, it is this file that can be shipped to other execution machines and used by Date Arithmetic utilities local to that platform.

8.5.5 Import This operation allows you to import an existing XML calendar file and use it’s contents.

8.5.6 Printable View This menu option allows you to print your calendar.


359

8.6 Date Arithmetic COM Facility ActiveBatch Date Arithmetic also supports a programmatic COM interface. This allows COM accessible languages the ability to issue Date Arithmetic operations as part of their language. The library AbatComDateSub provides this ability. A single object named DateSub is provided. This object provides three (3) methods: GetDate, GetDateString and Reset.

GetDate – Compute Date Arithmetic Expression and return OLE date.

This method has the following usage syntax requirements:

GetDate (DateExp, [Date], [SimulatedDate]) as OutputDate

Where:

Input

DateExp (string) is a parameter representing a valid Date Arithmetic expression (i.e. <BOM>).

Date (date), if specified, is used to satisfy the <DATE> tag. If omitted, the <DATE> tag uses today’s value.

SimulatedDate (date) is an optional parameter that if specified can be used in place of today’s date. This means that the tag <TODAY> as well as any other tag will use this value for computation purposes. SimulatedDate is therefore useful when you want to see what other dates will generate for the specified tag(s).

Output

OutputDate (date) is the resultant computed date.

GetDateString – Compute Date Arithmetic Expression and return date as a string.

This method has the following usage syntax requirements:

GetDateString (DateExp, [Date], [SimulatedDate]) as OutputDateString

Where:

Input

DateExp (string) is a parameter representing a valid Date Arithmetic expression (i.e. <BOM>).

Date (date), if specified, is used to satisfy the <DATE> tag. If omitted, the <DATE> tag uses today’s value.

SimulatedDate (date) is an optional parameter that if specified can be used in place of today’s date. This means that the tag <TODAY> as well as any other tag will use this value for computation purposes. SimulatedDate is therefore useful when you want to see what other dates will generate for the specified tag(s).

Output

OutputDateString (string) is the resultant computed date.

Note: The only difference between the two (2) methods above is that the output date is either passed back as an OLE Date or a String.

Reset – Clear Memory Calendar Cache.

This method requires no arguments and is used to clear any cached calendar files that you may have specified through previous date expression tags. By default, Date Arithmetic caches any calendar files specified for improved performance. If you modify a calendar you should invoke this method to reset the cache.


360

8.6.1 Date Arithmetic COM Example This sample Vbscript shows how simple it is to use the ActiveBatch Date Arithmetic COM facility. Dates are passed back in Date and String format. Remember that in the Date format the display obeys regional settings.

Option Explicit dim i,datesub, inputtag(18), outputdate, outputdatestr Set datesub =createobject("AbatComDateSub.DateSub") inputtag(1) = "<TODAY> " inputtag(2) = "<TOMORROW> " inputtag(3) = "<YESTERDAY>" inputtag(4) = "<BOM> " inputtag(5) = "<EOM> " inputtag(6) = "<BOW> " inputtag(7) = "<EOW> " inputtag(8) = "<BOY> " inputtag(9) = "<EOY> " inputtag(10) = "<BOQ> " inputtag(11) = "<EOQ> " inputtag(12) = "<MONDAY> " inputtag(13) = "<Tuesday> " inputtag(14) = "<Wednesday>" inputtag(15) = "<Thursday> " inputtag(16) = "<Friday> " inputtag(17) = "<Saturday> " inputtag(18) = "<SUNDAY> " for i = 1 to 18 outputdate = datesub.GetDate(inputtag(i)) outputdatestr = datesub.GetDateString(inputtag(i)) wscript.echo "the inputtag is : " & inputtag(i) wscript.echo vbtab & " the outputdate is: " & outputdate & " ... the outputdateString is: " & outputdatestr next wscript.echo "Done" The output of this script, run on Monday, January 17, 2005, would look like this: Microsoft (R) Windows Script Host Version 5.6 Copyright (C) Microsoft Corporation 1996-2001. All rights reserved. the inputtag is : <TODAY> the outputdate is: 1/17/2005 ... the outputdateString is: 17Jan05 the inputtag is : <TOMORROW> the outputdate is: 1/18/2005 ... the outputdateString is: 18Jan05 the inputtag is : <YESTERDAY> the outputdate is: 1/16/2005 ... the outputdateString is: 16Jan05 the inputtag is : <BOM> the outputdate is: 1/1/2005 ... the outputdateString is: 01Jan05 the inputtag is : <EOM> the outputdate is: 1/31/2005 ... the outputdateString is: 31Jan05 the inputtag is : <BOW> the outputdate is: 1/17/2005 ... the outputdateString is: 17Jan05 the inputtag is : <EOW>


361

the outputdate is: 1/23/2005 ... the outputdateString is: 23Jan05 the inputtag is : <BOY> the outputdate is: 1/1/2005 ... the outputdateString is: 01Jan05 the inputtag is : <EOY> the outputdate is: 12/31/2005 ... the outputdateString is: 31Dec05 the inputtag is : <BOQ> the outputdate is: 1/1/2005 ... the outputdateString is: 01Jan05 the inputtag is : <EOQ> the outputdate is: 3/31/2005 ... the outputdateString is: 31Mar05 the inputtag is : <MONDAY> the outputdate is: 1/17/2005 ... the outputdateString is: 17Jan05 the inputtag is : <Tuesday> the outputdate is: 1/18/2005 ... the outputdateString is: 18Jan05 the inputtag is : <Wednesday> the outputdate is: 1/19/2005 ... the outputdateString is: 19Jan05 the inputtag is : <Thursday> the outputdate is: 1/20/2005 ... the outputdateString is: 20Jan05 the inputtag is : <Friday> the outputdate is: 1/21/2005 ... the outputdateString is: 21Jan05 the inputtag is : <Saturday> the outputdate is: 1/22/2005 ... the outputdateString is: 22Jan05 the inputtag is : <SUNDAY> the outputdate is: 1/23/2005 ... the outputdateString is: 23Jan05 Done The differences between the Date and String formats become obvious. The Date format obeys regional settings when displayed and the String format uses the ActiveBatch default. We could reformat the date using the /FORMAT qualifier as a modifier on the date tags. As you can also see the tags are case-insensitive.


362

8.7 Date Arithmetic Test Utility ABATDATETEST is a stand-alone program that allows you to enter a date arithmetic specification followed by a range of dates that will be considered as “Today” for the purposes of testing the expression. The test utility provides the ability for you to see the results of your date arithmetic expression and ensure that it meets your expectations.

Figure 233 – Date Arithmetic Test Utility

Expression to Test: You enter the date arithmetic tag expression that you would like evaluated. Any other data entered is ignored and will be present in the test output column. This control allows you to see the last “n” occurrences of date tag expressions entered. A Clear List button to the right allows you to clear the currently entered expression.

Interval: This value indicates the number of days to use when testing the expression between the From and To dates. By default, the value is one (1) day. If the value exceeds the total range of possible dates, an error is produced.

From/To Dates: These fields allow you to test your expression across a range of dates. That way you can determine whether the date expression meets your needs. By default, the current full month is selected. To specify a single day, set From and To to the same value.

Table of Results: This table contains two (2) columns. The test date and the resulting output from the expression. A Clear button appears at the bottom left edge of the table. This allows you to manually clear the results table. By default, the results table is cleared for each expression test. Two (2) options are available: Do not clear before each expression… and Do not compact results. A Clear results is also available for manual clearing. By default, if the same result is produced for all given input dates, AbatDateTest will compact the results into a beginning and ending date entry.


363

8.8 Stand-alone Date Arithmetic Substitution Utility You can invoke Date Arithmetic as part of a stand-alone utility named ABATDATESUB. ABATDATESUB is meant to be used on a source file that contains Date Arithmetic tags and produces an output file with the actual computed dates substituted as appropriate.

ABATDATESUB supports all of the Date Arithmetic tags mentioned in Chapter 8. The syntax for the ABATDATESUB utility is:

ABATDATESUB input-file-spec output-file-spec [-d date] [-s simulate-date]

Where:

Input-file-spec is a valid file specification representing an input ASCII file that contains Date Arithmetic tags (if no tags are found the output file will be identical to the source input file).

Output-file-spec is a valid file specification representing an output file that will be created. Any Date Arithmetic tags found in the input-file will be substituted in the output file.

-d date is an optional parameter. If specified, the format must be DDMMMYYYY. This date will be used to populate the DATE tag. Please note that TODAY will always be the system date and that only the DATE tag is populated with this value. If this value is omitted and the DATE tag specified, the system date is used.

-s simulate-date is an optional parameter. If specified, the format must be DDMMMYYYY. This date will be used to represent TODAY in all date tag operations. If omitted, TODAY is populated from the system date. This parameter is useful when you want to test date processing for dates other than the system date.

ABATDATESUB also supports a Date Substitution file. This ASCII file has the following format:

<USER-TAG> <DATE-TAG>

User-Tag is a user created tag (that cannot conflict with an existing Date Arithmetic tag) and when found in a source file will cause the Date-Tag contents to be inserted in its place. For example,

<CHRISTMAS-DAY> <BOY/+MONTH=11/+DAY=24>

means that when the tag <CHRISTMAS-DAY> is found, the resulting Date Arithmetic tags will be used. A Date Substitution file allows you to embed more meaningful and self-descriptive tags for your application. The environment variable ABATDATESUB_ALIAS represents the file specification of the date substitution file.

365

9 USING THE ACTIVEBATCH COMMAND-LINE

INTERFACE

This manual concerns the use of ActiveBatch and the ABATAdmin program. This section describes the set of commands available through the console interface. Console commands are useful in that you can always issue these commands regardless of scripting language capability. The console command interface doesn’t provide access to the entire set of ActiveBatch capability. For programmatic access you are encouraged to read the ActiveBatch Developer’s Guide and the use of Microsoft COM automation with ActiveBatch.

The commands that follow are divided into two categories: Queue and Job. Queue commands create and otherwise manage the batch queue system itself. Job commands are those necessary for submitting a job to a queue for background execution and also for managing those jobs within the batch system.

The commands that follow require the verb ABAT to execute in a CMD console. If you have XLNT (Version 3 or later) installed you don’t need to preface the command. For example:

ABAT SUBMIT job-name /QUEUE=test-queue

This command would be invoked within the CMD console subsystem. If you are using ActiveBatch with XLNT you can invoke the commands below just as you would other XLNT commands. For example, the same command above would be:

$ SUBMIT job-name /QUEUE=test-queue

Note: The /ON qualifier can be used to direct requests to any licensed and active ActiveBatch Job Scheduler. The /ON qualifier also supports the specification of TCP/IP fully qualified hostnames as well as IP addresses.

The command qualifiers (with some minor exceptions) use the Queue and Job Policies to establish defaults.


366

9.1 Conventions Certain commands and qualifiers accept date and time values. You can specify these values in one of the following formats:

9.1.1 Absolute Time An absolute time is a specific date or time of day. The format for an absolute time is as follows:

“[dd-mmm-yyyy][:hh:mm:ss]”

The fields are:

dd Day of month (range from 1 to 31, depending on month) mmm Month (JAN...DEC) yyyy Year hh Hour (range from 0 to 23) mm Minute (range from 0 to 59) ss Second (range from 0 to 59)

The following rules apply to an absolute time:

• You can truncate the date or the time from the right.

• The date must contain at least one hyphen.

• You can omit any of the fields (other than month if a date is specified) as long as you include the punctuation marks that separate the fields.

• A truncated or omitted date field defaults to the corresponding fields for the current date.

• A truncated or omitted time field defaults to zero.

Example:

1-DEC-1997 Midnight, December 1, 1997. 15-DEC-1997:13:00 1:00 PM, December 15, 1997 20-DEC::30 12:30 AM, December 20, 1997 16:30 4:30 PM today

9.1.2 Delta Time A delta time is an offset from the current date and time to a future time. The format of a delta time is:

“+[dddd-][hh:mm:ss]”

The fields are as follows:

dddd Number of days (range from 0 to 9999) hh Hours (range from 0 to 23) mm Minutes (range from 0 to 59) ss Seconds (range from 0 to 59)

Chapter 9 - Using the ActiveBatch Command-Line Interface

367

The following rules apply to a delta time:

• You must specify a plus (+) sign.

• You can truncate a delta time on the right.

• If you specify the number of days, include a hyphen

• You can omit fields within the time as long as you include the punctuation that separates the fields.

• If you omit the time field, the default is zero.

Examples:

“+5-“ 5 days from now “+3” 3 hours from now “+:30” 30 minutes from now


368

9.1.3 Combination Time To combine absolute and delta times, specify an absolute time followed by a delta time.

“[absolute time][+delta time]”

“[absolute time][-delta time]”

The following rules apply:

• Precede the delta time value by a plus sign for future time or a minus sign for past time.

• Enclose the entire specification in quotation marks if a plus or minus sign precedes the delta time value.

• Omit the absolute time value if you want to offset the delta time from the current date and time.

• Remember that the rules for absolute and delta time values still apply.

You can also specify TODAY, TOMORROW or YESTERDAY (the time is always midnight (00:00:00.000)) as well as MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY or SUNDAY (which calculate a forward date to the next day/date, the time is always midnight).

Examples: “+5” 5 hours from now. “-1” Current time minus 1 hour. (Note that the 1 is interpreted as an hour and not a day because it is not followed by a

hyphen.) “-3-“ Current time minus 3 days. (Note the hyphen.) “+:5” 5 minutes from now. “-:5” Current time minus 5 minutes.


369

9.2 ABATAVLMGR This command allows you to control the high-availability features of ActiveBatch’s Job Scheduler system. These features are only available if licensed and enabled.

With abatavlmgr you can designate preference order in terms of active and standby Job Scheduler machines, failover a Job Scheduler manually, stop a Job Scheduler service and also list the active set of Job Scheduler machines.

Format:

ABATAVLMGR command [qualifiers]

Parameters:

command

This required argument specifies the action to be performed. Valid commands are: ABORT, ACTIVE, CONFIG, FAILOVER, LIST, START and STOP.

Qualifiers:

-d connect_str

This qualifier is required for all commands except START and STOP. This qualifier indicates the connection string information or ODBC system DSN to use to access the ActiveBatch database.

-p password

This optional qualifier indicates the password for a –u qualifier. This qualifier may be required if your database access uses database rather than Windows authentication.

-u username

This optional qualifier indicates the username that abatavlmgr should use when accessing the database. This qualifier and –password may be required if your database access requires Database rather than Windows authentication.

Example:

Abatavlmgr list –d abatdemo

This command lists the status of the Job Scheduler failover set for the database accessed through DSN abatdemo.


370

9.3 ABATCHKPT This command allows you to either associate persistent data with a job instance for the purposes of possible restart/checkpoint or you can send progress information as to where a job may currently be executing.

Format:

ABATCHKPT data

Parameters:

data

This mandatory parameter contains the information to either be checkpointed as persistent data or the progress information as to where a job is currently executing.

Example:

Abatchkpt “Test 1 of 15”


371

9.4 ABATDATESUB This command allows you to perform date arithmetic and substitution from a base source file that contains date arithmetic tags and creates an output file with the computed dates in place of the tags.

Format:

ABATDATESUB source-file output-file [date]

Parameters:

Source-file

This mandatory parameter indicates the file specification of the input source file. This file should contain date arithmetic tags (although it is not a requirement).

Output-file

This mandatory parameter indicates the output file specification. This file will contain the computed dates in place of the tags.

Date

When specified, this optional parameter, will be used to load the <DATE> tag. The format of this parameter is DDMMMYYYY. If this parameter is omitted, today’s date is used.

Example:

Abatdatesub c:\template.dat c:\output.dat


372

9.5 ABATDBPWD This command allows you to create, update or remove an encrypted DB Password associated with an ActiveBatch database. During the product installation you were given an opportunity to indicate what type of authentication you supported for access to the ActiveBatch database. For database authentication you needed to specify a user account and a password. This utility command allows you to change the encrypted version of that password. This may be necessary if you have to change the password associated with the user account.

Format:

ABATDBPWD [password]

Parameter:

password

This optional argument specifies the password to be encrypted. If it is omitted, the utility will prompt twice (with echo disabled) for a new password. If you specify a NULL argument (i.e. “”), the password registry item is deleted. This is what you would do if you decided to have an account with no password (i.e. password is blank).

Example:

abatdbpwd password

This command encrypts the word “password” and stores that encrypted form in the ActiveBatch Job Scheduler registry.


373

9.6 ABATEXECSQL This command allows you to execute streams of SQL statements.

Format:

ABATEXECSQL connect-str script.sql [username] [password] [-s]

Parameter:

connect-str

This required parameter provides either a connection string or a data source name (DSN) to use to access the database.

script.sql

This required parameter indicates the file specification containing the SQL statements.

username

This optional argument specifies the username to be used when accessing the database. By default, Windows authentication is assumed and the current logon security credentials are used. If your database uses the native authentication scheme you will want to specify a username and password.

password

This optional argument specifies the password to be used in conjunction with the specified username.

Qualifiers:

-s

This optional qualifier enables silent mode operation. Silent mode disables all message logging (including errors).

Remarks:

While you can specify a DSN, you may see a performance penalty since a new layer (ADO) has been introduced to support the connection-string method of attaching to a database. To avoid this penalty, we recommend that you use the connection-string method instead of a DSN. This causes ADO to use OLE/DB instead of ODBC.

Example:

Abatexecsql “file name=activebatch.udl” c:\test.sql

This command executes a series of SQL statements contained in the file “c:\test.sql”. The Microsoft DataLink file, ActiveBatch.udl, contains the server, database and authentication information necessary to successfully connect to the database. Note: Microsoft Data Link requires that the UDL file be Unicode.

abatexecsql abattest c:\test.sql

This command executes a series of SQL statements contained in the file “c:\test.sql” and applies those commands to the database as denoted by its DSN “abattest”.


374

9.7 abatpty This command, for UNIX-based machines only, allows you to execute a program that requires a tty.

Format:

abatpty [-d driver] [-einv] program-specification [arguments,..]

Parameter:

program-specification

This required parameter specifies the location of the program that is to be executed under the newly created ptty device.

Qualifiers:

–d driver

This optional qualifier indicates what driver is to be used for stdin/stdout.

–e

This optional qualifier indicates noecho for slave pty.

–n

This optional qualifier indicates not interactive

–i

This optional qualifier indicates that EOF is to be ignored on standard input.

–v

This optional qualifier indicates verbose (for abatpty debugging).

Usage and Remarks:

This command is useful when a program requires a tty (or in this case a “ptty”) for proper operation. To use this program with an ActiveBatch job, place “abatpty” in the script filename portion of a Process type job and then place any abatpty qualifiers, your program specification and any arguments in the parameters field of the job. If you’re uncertain as to what abatpty qualifiers are to be used you should typically specify “–i”.

This program was adapted from a UNIX freeware program named “pty”.

Example:

abatpty –i sample

This command executes the program “sample” under a newly created ptty.


375

9.8 ABATRPTGEN (Direct Database Method) This command allows you to generate ActiveBatch reports from pre-existing Report Definition files using ODBC/OLE-DB access (highly recommended).

Format:

ABATRPTGEN -r ReportFile –o OutputFile –d OdbcConnect [ -t OutputType]

Qualifiers:

-c ReportFile

This qualifier may be used to convert Report definition files (.ABR) from a prior version.

-r ReportFile

This required qualifier provides the Report definition file (.ABR) specification.

-o OutputFile

This required qualifier provides the output file specification of the report file itself.

-d OdbcConnect

This required qualifier provides the connection information for ODBC to connect to your selected database. (See Section 7.4.1 and the comment concerning ODBC Connection String)

-t OutputType

This optional qualifier indicates the type of report file produced. By default, HTML is used. You can also specify CSV or XML.

Example:

abatrptgen -r “c:\program files\asci\activebatch\reports\SampleReport.abr” -o SampleReport.html

-d “Driver=SQL Server;Server=ENGSERVER1;Database=ASCIABAT”

This convenient command not only generates report files but can also generate a CSV file which can be used to import the report data into a variety of other third-party tools. AbatRptGen can also generate an XML file for simplified parsing and data formatting.


376

9.9 ABATRPTGEN (COM Method) This command allows you to generate ActiveBatch reports from pre-existing Report Definition files using the COM method. This method is only recommended if you want to generate a report concerning future activity.

Format:

ABATRPTGEN -r ReportFile –o OutputFile –j JSSMachine [-u Username] [p Password] [ -t OutputType]

Qualifiers:

-r ReportFile

This required qualifier provides the Report definition file (.ABR) specification.

-o OutputFile

This required qualifier provides the output file specification of the report file itself.

-j JSSMachine

This required qualifier provides the Job Scheduler machine name (or IP address) for connection through ActiveBatch COM.

-u Username

This optional qualifier allows you to specify an alternative username for COM security purposes when connecting to the Job Scheduler. By default, your logon credentials are used.

-p Password

This optional qualifier (typically used in conjunction with –u above) allows you to specify a password for the username specified with the –u qualifier.

-t OutputType

This optional qualifier indicates the type of report file produced. By default, HTML is used. You can also specify CSV or XML.

Example:

abatrptgen -r “c:\program files\asci\activebatch\reports\SampleReport.abr” -o SampleReport.html

-j ASCI52


377

9.10 ABATSET

This command allows a job to pass parameters and/or variables (and their values) to jobs that will be triggered through the Completion Trigger facility. The Completion Trigger facility (previously known as Batch Start) allows you to establish jobs that are triggered for execution based on whether the job completes successfully or in failure.

Format:

ABATSET [/current] [/success | /failure] [/param parameter-list] [/env var=value,…] [/var var=value,…]

Qualifiers:

/current

If specified, the job’s current parameters and environment variables are passed to the Completion triggered jobs. /param, /env and /var qualifiers are ignored if specified.

/success | /failure

If specified, the respective qualifier indicates which Completion Trigger list should be used for the parameters and/or variables. For example, if /success is specified, then the parameters/variables specified are used for Completion Trigger Success processing. If neither /success or /failure are specified then both Completion Trigger lists are used. Please note that if you need to specify different parameters/variables for both lists you will need to specify two (2) separate abatset commands. In addition, please note that modifications to plan variables are applied immediately and not subject to the success or failure qualifiers.

/param

This optional qualifier indicates the parameters that you would like to pass to the Completion Triggered jobs. Each parameter is delimited by a space. If you need to pass an embedded space then the shell rules for your Operating System apply (for example, “ “, or \”).

/env var=value …

/var var=value …

This optional qualifier indicates the variables and their values that should be passed. “var” indicates the environment variable and “val” indicates the value. If the value contains an embedded space then the shell rules for your Operating System apply. If the environment variable as specified is already a part of the job’s environment variables, then the new value is replaced. If the environment variable isn’t a part of the job’s environment, then both the environment variable and its associated value are inserted. To access an upstream variable (as might exist in a Plan) use ../ (dot, dot, forward slash) syntax. For example, /env ../plan_var=test would access the variable plan_var in the upstream plan.


378

9.11 ABATUPDPWD This command allows you to maintain your stored user accounts on Microsoft Windows systems. Stored user accounts and passwords are those in which the “Save/Remember Password” checkbox has been enabled. This checkbox is presented whenever security credentials are required and allow the convenience of saving a user account and password rather than having to re-enter the data. This is similar to saving passwords when using a web browser. AbatUpdPwd allows you to otherwise maintain (add, replace, delete, list) those stored user accounts. Please note that you can only access these stored accounts that are associated with your current Windows security credentials. In other words, User A cannot access User B’s stored accounts.

Format:

ABATUPDPWD password [user-account] [machine-queue] [/ADD | /REPLACE]

ABATUPDPWD user-account [machine-queue] /DELETE

ABATUPDPWD /DELETEALL

ABATUPDPWD /LIST

Qualifiers:

machine-queue

This parameter further qualifies the user-account parameter since two or more machines may have the same user-account but different passwords (in which case they are really different accounts). If the user-account is a domain account then a domain should be specified in this parameter. If the user-account is specific for a given machine then the machine name should be specified here. Rather than specify a machine you can specify an ActiveBatch queue name that is to provide context in distinguish similar usernames that actually represent different accounts for different machines. Typically the queue would be a generic queue since the machine associated with an execution queue would avoid any username ambiguity.

password

This parameter, if specified, is the password to be associated with a user-account. If omitted, the program will prompt twice, with echo disabled, to confirm the new password.

user-account

This parameter indicates the user-account that is to be stored or deleted. The user account is entered using the same syntax that would be specified and is acceptable on the target machine it is expected to be used on. For Windows machines, domain\user or machine\user is typically specified. For other platforms, the username would be specified.

Example:

Abatupdpwd newpassword sample\user

This command updates the user account (sample\user) with a new password.


379

9.12 ABAT Commands

9.12.1 CLOSE/QUEUE

The CLOSE/QUEUE command prevents further job submission. Format:

CLOSE/QUEUE queue-name

Parameter:

queue-name

This required parameter indicates the specific queue that is to be closed.

Qualifiers: /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports).

Example: CLOSE/QUEUE TESTQUEUE This example closes a queue named TESTQUEUE and prevents further job submission to the queue.


380

9.12.2 DELETE/JOB

The DELETE/JOB command aborts or deletes a specific job or plan, or in the case of a job/plan definition, the definition and its instances can be aborted or deleted. Format:

DELETE/JOB=job-entry-id/qualifiers

Qualifiers:

/INSTANCE This qualifier will abort the executing copy of a scheduled job. A template job will remain eligible for re-execution at a later time. This qualifier is ignored if /PERMANENT is specified. /JOB=job-entry-id This required qualifier indicates the specific job entry via its unique entry identification that is to be aborted/deleted. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports). /PATH=path This qualifier allows you to lookup a specific object using the object’s path (for example, “/Testjob” would refer to the object labeled ‘TestJob’). /PERMANENT This qualifier, if specified, indicates that the job is to be deleted. By default, job(s) are aborted and a job's history can be viewed in the Runbook.

Example: $ DELETE/JOB=5/ON=NTSERVER1 This example aborts a job with the job id of 5 on the Job Scheduler machine NTSERVER1.


381

9.12.3 DELETE/QUEUE

The DELETE/QUEUE command deletes a named queue. Format:

DELETE/QUEUE/qualifiers queue-name

Parameter:

queue-name The name of the queue which is to be deleted. ActiveBatch requires that no jobs be present on the queue (otherwise you should use the /FLUSH qualifier).

Qualifiers: /FLUSH This qualifier indicates that any jobs which are held or pending are to be deleted prior to deleting the queue itself. By default, pending jobs are not deleted. A queue cannot be deleted with pending jobs. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports).

Example: $ DELETE/QUEUE TESTQUEUE /FLUSH This example deletes a queue named TESTQUEUE and the /FLUSH Qualifier deletes any jobs which are held or pending.


382

9.12.4 FLUSH/QUEUE

This command will delete all jobs on a specified queue. Jobs can also be deleted by job state and/or be specifying the user’s username. Format:

FLUSH/QUEUE/qualifiers queue-name Parameter:

queue-name The name of the queue on which the flush operation is to be performed.

Qualifiers: /BY_JOB_STATUS=(ABORTING | EXECUTING | PENDING | TIMED_RELEASE | HOLDING | COMPLETED) This qualifier indicates which jobs by “job state” are to be deleted. By default, all jobs are deleted. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports). /USERNAME=username This qualifier allows the search of jobs to be narrowed to a specific username. By default, the search is not narrowed to a specific user.

Example: $ FLUSH/QUEUE TESTQUEUE This example will delete all jobs that are in the queue named TESTQUEUE.


383

9.12.5 HOLD

This command will hold a job or plan definition. In other words, the state of the object is changed to “Hold” (or Disabled). Format:

HOLD/JOB=job-entry-id/qualifiers Qualifiers:

/JOB=job-entry-id This required qualifier indicates the specific job entry via its unique entry identification is to be set to “Hold” status. Please note that an active executing job cannot have its state changed via this command. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports). /PATH=path This qualifier allows you to lookup a specific job using the object’s path (for example, “/Testjob” would refer to the object labeled ‘TestJob’).

Example: $ HOLD/JOB=5/ON=NTSERVER1 This example will hold a pending or completed job with an entry id of 5 on Job Scheduler machine NTSERVER1.


384

9.12.6 INITIALIZE Queue

This command is used to create or initialize a new queue within the ActiveBatch system. Format:

INITIALIZE/QUEUE/qualifiers queue-name Parameter:

queue-name This required parameter represents a unique name for a batch queue.

Qualifiers: /BASE_PRIORITY=(IDLE | BELOWNORMAL | NORMAL | ABOVENORMAL | HIGH |REALTIME | number) This qualifier represents the operating system scheduling priority assigned to the batch process at job startup. For non-Windows 2000/NT machines, a priority number would be used. /CLOSE This qualifier indicates whether the initial state of the queue should be to allow job submissions. If /CLOSE is specified, job submissions will not be allowed. By default, the initial queue state is OPEN. /CLOSE and /OPEN are mutually exclusive. /CLOSE_TIME=(hh:mm-hh:mm) This qualifier indicates the time of day that the queue is to remain closed. During the remaining portion the queue is open. The time specifier hh:mm represents a 24-hour time. The time range indicates the starting and ending closing time. /DENY=(account:access…,…) This qualifier is used to deny an account access that the account may also obtain through a group. account refers to the WinNT account name (or group) and access refers to one or more of the following keywords: EXECUTIVE, MANAGE and USER. To specify more than one level of access to be denied, separate each access with a colon. Multiple accounts may be specified by delimiting each account/access string with a comma. /DESCRIPTION=”string” This qualifier allows a short description to be assigned and stored with the created queue. /[NO]EVENT_LOG=keyword | \\machine This qualifier indicates whether the Windows 2000/NT Event Log should be used for start and stop batch job messages and, if so, which machine’s event log should be used. Available keywords are: Client, JobScheduler and ExecutionMachine. You may also specify a specific machine by prefacing the machine name with a \\ (2 backslashes) notation. To avoid using the Event Log specify /NOEVENT_LOG. /EXEC_ON=machine-name For an execution queue, this qualifier indicates the machine that submitted jobs are to be executed on. /GENERIC=(ExecQueue1, ExecQueue2,…. ExecQueueN) This qualifier indicates that the queue to be created is a generic queue. A generic queue points to one or more execution queues. The values specified with this qualifier are the actual execution queue names. If this qualifier is omitted, the queue is assumed to be an execution type queue. /GRANT=(account:access,…) This qualifier is used to associate security permissions to the queue that is to be created. By default, the owner and Administrator are given full access to the queue and the all other users are given Submit level access (this default can be changed with the SET BATCH command). To associate different permissions for this queue, you may specify one or more accounts and the level of access each account (or group) may have with this queue. Access is specified using one or more of the following keywords:

FULL Complete access EXECUTIVE Give/Take Ownership MANAGE Ability to issue queue management commands USER Ability to SUBMIT jobs

Each keyword specified must be separated by a colon. Multiple accounts are separated by a comma. /HOLD_ON_ERROR This qualifier is used to establish a default for jobs which are submitted on this queue. When enabled, the job will be automatically placed in a Hold state if the job completes on error. /JOB_LIMIT=number This qualifier, valid for execution queues, indicates the number of simultaneous jobs that may be executed for this execution queue. The valid range is 1 through 10. By default, one is assumed.


385

/JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports). /OPEN This qualifier indicates that the queue is available for job submissions. By default, the /OPEN qualifier is assumed. /PRIORITY=number This qualifier indicates the default queue priority to be used when submitting a job to a queue and a priority is not specified as part of job submission. This qualifier should not be mistaken as the scheduling priority of the job (see /BASE_PRIORITY). The valid range is 1 through 99. The default is 10. /REMOVE=(account,…) This qualifier removes the specified accounts permissions. More than one account may be specified separated by a comma. /SCHEDULING = (SEQUENTIAL | ROUND-ROBIN | BALANCED) This qualifier indicates the scheduling algorithm which will be used for a Generic queue. Sequential means that jobs are submitted to the first Execution Queue listed until that queue is executing its maximum job limit. Round-Robin means that each queue, in turn, is given a job to execute until its job limits are met. Balanced indicates that a workload balancing approach be used which determines the best machine to run on based on CPU, memory and other parameters. /[NO]START This qualifier indicates the initial queue state after becoming initialized. /START (default) indicates that any pending jobs which are eligible to become executable should be started. /NOSTART indicates that the jobs should not be started for execution. Please note that OPEN and CLOSE qualifiers deal with the ability to submit jobs to a queue while START and NOSTART deal with the ability to execute those eligible jobs. /STOP_TIME=(hh:mm-hh:mm) This qualifier indicates the time of day that the queue is to remain stopped. During the remaining portion the queue is started. The time hh:mm represents a 24-hour time. The time range indicates the starting and ending stopped time. /USER_CHAR=(char:datatype:value,…) This qualifier is used to associate user characteristics with an Execution Queue. Char indicates a user characteristic name. This name is free form but cannot contain spaces. Datatype is either String or Numeric. Value is a string or numeric value based on the characteristic datatype. You may specify multiple characteristics by separating each with a comma. /WORKING_FOLDER=device-directory-spec This qualifier indicates the default working directory for jobs submitted to this queue in which a directory has not been specified.

Example: $ INITALIZE/QUEUE TESTQUEUE /DESCRIPTION="A Test Queue" This example creates a queue called TESTQUEUE with a description of "A Test Queue".


386

9.12.7 MODIFY/JOB

This command is used to modify a job’s characteristics on queue. Format:

MODIFY/JOB=job-entry-id/qualifiers Qualifiers:

/[NO]ACTIVEBATCH_EVENT This qualifier indicates whether the job can accept an ActiveBatch TRIGGER command. The default is that a job can accept the command. /[NO]ACCOBJ=user-account-name This qualifier indicates whether a user account name object is being referenced for security (username, password) information. Negating this qualifier indicates the object’s reference is to be removed from this job. User account name objects are highly recommended for security purposes instead of using embedded security credentials within the job. /AFTER=combination-time This qualifier is used to defer a job so that the job will be executed at some future time. The time specified is any valid combination time (including keywords TODAY and TOMORROW). If /AFTER is specified without a combination time specified the keyword TODAY is assumed. By default, job execution is assumed to be immediate. /BASE_PRIORITY=(LOW | BELOWNORMAL | NORMAL | ABOVENORMAL | HIGH | REALTIME | number) This qualifier represents the operating system scheduling priority assigned to the batch job. For Windows 2000/NT machines the keywords above are used. For non-Windows machines, a priority number must be specified. By default, the base priority is taken from the queue’s characteristics. /CALENDAR=calendar-name This qualifier associates a business calendar with the job. This allows a job to be scheduled only on working days. /CATEGORY=”string” This qualifier indicates the user category or other string value that will be kept with the job. /CONTACT=(delivery:target[:time],…) This qualifier is used to denote contact information for those machines/users that are to be notified when a job starts or completes execution. Delivery represents one of two keywords which indicate how the notification is to be occur. MAIL or MESSENGER are valid delivery keywords. Target represents either a machine name, if the delivery is MESSENGER, or a valid e-mail address if the delivery is MAIL. Time indicates either a START or FINISH job time criteria that is used to indicate when the notification is to be sent. If “time” is omitted, then FINISH is assumed. You may specify more than one contact by separating each contact specification with a comma. /DENY=(account:access,…) This qualifier is used to deny an account access that the account may also obtain through a group. account refers to the WinNT account name (or group) and access refers to one or more of the following keywords: READ, WRITE, DELETE, EXECUTE, TAKEOWNERSHIP, TRIGGER, TRIGGERPARAM and TRIGGERQUEUE. To specify more than one level of access to be denied, separate each access with a colon. Multiple accounts may be specified by delimiting each account/access string with a comma.


387

/DESCRIPTION=”string” This qualifier is used to set the pending job’s description specified at job submission time. /DOCUMENTATION=”string” This qualifier is used to associate a documentation reference with the job. /EVERY=(MINUTE=mm,… , HOUR=hh,… , WEEKDAY=ddd,… , DAY=dd,… , MONTH=mm,…) Note: This qualifier while supported is obsolete and has been superceded by the /SCHEDULE qualifier. This qualifier indicates that a rescheduled job entry is to be created. By default, if all keywords are omitted, a job entry is created that will execute at midnight each day. Valid keywords are as follows. Specification of multiple values or multiple keywords is supported through the use of comma delimitation.

MINUTE valid range of 0 through 59. Default is 0. HOUR valid range of 0 through 23. Default is 0. WEEKDAY acceptable values are SUN, MON, TUE, WED, THU, FRI, SAT. DAY valid range of 1 through 31. A day which is specified as greater than the number of days in the

month denotes the last day of the month. Default is every day of a month. MONTH valid range of 1 through 12. Default is every month.

The EVERY and INTERVAL qualifiers are mutually exclusive. When a DAY is specified that exceeds the actual number of days in the month, ActiveBatch will assume that the last day of the month is to be selected. If multiple DAYs are specified which exceed the actual number of days in the month, the job will be scheduled once on the last day of the month. /[NO]FAILURESTART=(job-id,…) This qualifier indicates one or more jobs to trigger if the job completes in failure. One or more job-id’s are entered in a comma delimited format. /NOFAILURESTART removes all failure job triggers. /GRANT=(account:access,…) This qualifier is used to associate security permissions to the job that is to be created. To associate permissions for this job, you may specify one or more accounts and the level of access each account (or group) may have. Access is specified using one or more of the following keywords:

READ Read access WRITE Read and Write access DELETE Delete access TAKEOWNERSHIP Take Ownership TRIGGER Trigger access TRIGGERQUEUE Trigger with Queue change access TRIGGERPARAM Trigger with Parameters change EXECUTIVE Security/Take Ownership FULL Complete access

Each keyword specified must be separated by a colon. Multiple accounts are separated by a comma. /GROUP=name This qualifier indicates the group name for this job. A group name may be used to group related jobs and perform group operations.


388

/[NO]HOLD[=(SUBMIT, ERROR, COMPLETION)] This qualifier is used to set the “Hold” state. The SUBMIT keyword (the default if only /HOLD is specified) indicates the job is to enter a “Hold” state immediately upon a successful submission. The COMPLETED keyword indicates the job is to enter a “Hold” state upon job completion. One or both keywords may be specified. /IFACTIVE=(keyword | WAIT[:time]) This qualifier indicates whether more than one instance of a scheduled job can execute. Possible keywords are: SKIP, MULTIPLE and WAIT. SKIP indicates that the scheduled instance should be skipped if an instance is already executing. MULTIPLE indicates that more than one instance of the job can run. WAIT indicates that the job should wait. You may optionally indicate how long to wait before skipping the job. SKIP is the default. /IMMEDIATE This qualifier when used with the /SCHEDULE qualifier indicates that the job is to run immediately. /INTERVAL=delta-time This qualifier indicates that a rescheduled job entry should be created. A valid delta time can be specified with the exclusion of the TODAY and YESTERDAY keywords. The delta-time specification allows for a self-relative time specification in days, hours, minutes and seconds which are added to the last submission time of the job. EVERY and INTERVAL qualifiers are mutually exclusive. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LABEL=label This qualifier is used to set the job’s object label. The label portion of an object is used to scripting purposes to uniquely identify the object. If this qualifier is omitted, ActiveBatch will create a unique label using a portion of the job’s name. /LOG This qualifier is used to display a message when the operation is successful. /[NO[MANAGE_LOGFILES This qualifier is used to indicate whether ActiveBatch is to centrally manage the job’s log files. If enabled, the location and name of the job’s log files are specified by ActiveBatch (you can programmatically obtain the names). If disabled, you retain the ability to locate and name the log files. /[NO]MAX_RESTARTS=n This qualifier is used to specify the maximum number of restarts the job may undergo. /NOMAX_RESTARTS means an unlimited number and a value specified means the job will be limited to that number of restarts. Please note that this value is applicable until the job completes. /NAME=jobname This qualifier is used to set the name of the submitted job. By default , the job name is set to that of the filename portion of the job file specification.


389

/[NO]NOTIFY[=username] This qualifier is used to indicate that the user submitting the job wants to be notified when the job completes. If a value is set with the NOTIFY qualifier that value is a username specification. By default, NONOTIFY is assumed. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports). /[NO]OUTPUT[=file-specification] This qualifier is used to indicate whether a log file is to be created with the batch job and if so the specification of that log file. /NOOUTPUT means that a log file isn’t to be created. By default, a batch log file is produced in the current directory of the created job. The default batch log file specification is the job-file-specification with a .LOG extension. When /INTERVAL or /EVERY or /SCHEDULE is specified, the following additional information is automatically appended to the output log filename: _mmdddyyyy_hhmmss. This helps keep each individual log file separate and distinct as a batch job is rescheduled. Note: This qualifier is ignored if the /MANAGE_LOGFILES qualifier is specified. /[NO]PARAMETER=(value1,…value8) This qualifier is used to set the input parameters associated with a specific job. Values specified may be strings or numbers. A maximum of eight (8) values may be specified. NOPARAMETER means that no input parameters are to be associated with the job (which is the default). /PASSWORD[=”string”] This qualifier is used to associate a password in conjunction with the current username or a username specified with the /USERNAME qualifier. If specified as a “string” value be sure to enclose the password as a quoted string to prevent the case from being changed. If a password value is not specified, the command will prompt for one (echo is disabled for security purposes). /PATH=path This qualifier allows you to lookup a specific job using the object’s path (for example, “/Testjob” would refer to the object labeled ‘TestJob’). /[NO]POST_STEP=file-specification This qualifier indicates that a post-job step is to be performed. /[NO]PRE_STEP=file-specification This qualifier indicates that a pre-job step is to be performed. The pre-job step is executed prior to the main job file. /PRIORITY=number This qualifier is used to set the queue insertion priority of a job. The valid range is 1 through 99. By default, the queue insertion priority is taken from the queue’s characteristics. /PROCESSORMASK=n This qualifier is used, in a multi-processing system, to denote processor affinity. The value specified should be considered a bit-mask. For example, a value of 3 means bit 0 and 1 and would denote processors zero and one. /QUEUE_SELECTION=ANY | ALL | EVENT This qualifier, appropriate to Generic Queues only, allows you to select whether one eligible execution queue should be used, all eligible machine queues should be used or only the machine that generated the event should be used. /[NO]READ_ONLY This qualifier indicates that the job’s properties should be set to a “read only” state. The default is /NOREAD_ONLY. /REMOVE=(account,…) This qualifier removes the specified accounts permissions. More than one account may be specified separated by a comma. /[NO]RESTART=[WAIT | FAILOVER | TERMINATE] This qualifier is used to set the restartability of an executing job. /RESTART indicates that the job is to be automatically requeued for execution. /NORESTART indicates that the job is to be removed from the queueing system in the event of a system failure. /[NO]RETAIN_HISTORY=days This qualifier is used to indicate the retention period for a completed job. The /NORETAIN_HISTORY means that the job’s history is to be removed when the ActiveBatch Database Purge program runs. A value specified indicates the number of days to save the history information. /[NO]RETAIN_LOGFILES=days This qualifier is used to indicate the retention period of the job’s log files. The /NORETAIN_LOGFILES means that the job’s log files are to be removed when the ActiveBatch Database Purge program runs. A value specified indicates the number of days to save the log files. Please note that this value should not be less than that specified for /RETAIN_HISTORY (otherwise it will be automatically adjusted to the same value).


390

/[NO]REUSE This qualifier may be used to enable or disable the “Reuse Log File” facility. By default, this property is disabled which means that every instance run results in a new log file. Reuse Log file enabled means that a single log file is created (except OpenVMS in which a new version of the log file is created). /[NO]RUNONCE This qualifier is used to specify whether the job is to run once regardless of whether the job is date/time triggered or event triggered. The default is /NORUNONCE. /[NO]SAVE_PASSWORD This qualifier, valid on Windows 2000/NT machines only, indicates that the password specified should be saved. /NOSAVE_PASSWORD indicates that a saved password should be removed and any specified password should not be saved. /[NO]SCHEDULE=(name,…) If specified this qualifier indicates that the named schedules should be associated with this job. The schedules must already exist (if not, you should use the INITIALIZE/SCHEDULE command to create one). /SUCCESSRULE=(n | n-n | ODD | EVEN | LZERO | NTMSG) This qualifier indicates how ActiveBatch interprets the main job step’s exit code. The values specified all indicate that the job completed successfully. You may specify a single value, a range of values and/or a keyword indicating success. /[NO]SUCCESSSTART=(job-id,…) This qualifier indicates one or more jobs to trigger if the job completes successfully. One or more job-id’s are entered in a comma delimited format. /TAKE_OWNERSHIP This qualifier indicates that the current user is requesting ownership of the specified job. The user must have Executive or Full access permission in order to successfully take ownership. /[NO]TERMINATE This qualifier indicates whether children processes should be terminated when the job exits. On Windows NT V4, children processes are identified as having the same parent id (PID). This technique is not precise. On Windows 2000, a job with this qualifier enabled, is created as a job object. OpenVMS and Unix operating systems terminate child or subprocess trees regardless of the setting of this qualifier. By default, /NOTERMINATE is assumed. /TIME_ZONE= CLIENT | JOBSCHED | UTC This qualifier indicates the time zone which should be used by the Job Scheduler to actually schedule time triggers. By default the Job Scheduler’s time zone is used. /USERNAME=username This qualifier is used to set the username that initially submitted the job for execution. Typically when this qualifier is used, the /PASSWORD qualifier is asserted as well. /WORKING_FOLDER=device-directory-spec This qualifier indicates the default working directory for this job.

Example: $ MODIFY/JOB=5/ON=NTSERVER1/HOLD/NORESTART This example will hold a job with an entry id of 5 on queue server machine NTSERVER1 and change the state to ‘Hold” and make the job non-restartable in the event of a system failure.


391

9.12.8 MODIFY/QUEUE

This command is used to change a queue’s characteristics.

Format: MODIFY/QUEUE/qualifiers queue-name

Parameter: queue-name This required parameter represents the name of the batch queue that is to be modified.

Qualifiers: /BASE_PRIORITY=(IDLE | BELOWNORMAL | NORMAL | ABOVENORMAL | HIGH |REALTIME | number) This qualifier represents the operating system scheduling priority assigned to the batch process at job startup. For non-Windows 2000/NT machines, a priority number would be used. By default, NORMAL priority is used. /CLOSE_TIME=(hh:mm-hh:mm) This qualifier indicates the time of day that the queue is to remain closed. During the remaining portion the queue is open. The time specifier hh:mm represents a 24-hour time. The time range indicates the starting and ending closing time. /DENY=(account:access,…) This qualifier is used to deny an account access that the account may also obtain through a group. account refers to the WinNT account name (or group) and access refers to one or more of the following keywords: EXECUTIVE, MANAGE and USER. To specify more than one level of access to be denied, separate each access with a colon. Multiple accounts may be specified by delimiting each account/access string with a comma. /DESCRIPTION=”string” This qualifier allows a short description to be assigned and stored with the created queue. /[NO]EVENT_LOG=keyword | \\machine This qualifier indicates whether the Windows 2000/NT Event Log should be used for start and stop batch job messages and, if so, which machine’s event log should be used. Available keywords are: Client, JobScheduler and ExecutionMachine. You may also specify a specific machine by prefacing the machine name with a \\ (2 backslashes) notation. To avoid using the Event Log specify /NOEVENT_LOG. /EXEC_ON=machine-name For an execution queue, this qualifier indicates the machine that submitted jobs are to be executed on. /GENERIC=(ExecQueue1, ExecQueue2,…. ExecQueueN) This qualifier indicates that the queue to be created is a generic queue. A generic queue points to one or more execution queues. The values specified with this qualifier are the actual execution queue names. If this qualifier is omitted, the queue is assumed to be an execution type queue. /GRANT=(account:access,…) This qualifier is used to associate security permissions to the queue that is to be created. By default, the owner and Administrator are given full access to the queue and the all other users are given Submit level access (this default can be changed with the SET BATCH command). To associate different permissions for this queue, you may specify one or more accounts and the level of access each account (or group) may have with this queue. Access is specified using one or more of the following keywords:


Each keyword specified must be separated by a colon. Multiple accounts are separated by a comma. /JOB_LIMIT=number This qualifier, valid for execution queues, indicates the number of simultaneous jobs that may be executed for this execution queue. The valid range is 1 through 10. By default, one is assumed. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD.


392

/JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports). /PRIORITY=number This qualifier indicates the default queue priority to be used when submitting a job to a queue and a priority is not specified as part of job submission. This qualifier should not be mistaken as the scheduling priority of the job (see /BASE_PRIORITY). The valid range is 1 through 99. The default is 10. /REMOVE=(account,…) This qualifier removes the specified accounts permissions. More than one account may be specified separated by a comma. /SCHEDULING = (SEQUENTIAL | ROUND-ROBIN | BALANCED) This qualifier indicates the scheduling algorithm which will be used for a Generic queue. Sequential means that jobs are submitted to the first Execution Queue listed until that queue is executing its maximum job limit. Round-Robin means that each queue, in turn, is given a job to execute until its job limits are met. Balanced indicates that a workload balancing approach be used which determines the best machine to run on based on CPU, memory and other parameters. /STOP_TIME=(hh:mm-hh:mm) This qualifier indicates the time of day that the queue is to remain stopped. During the remaining portion the queue is started. The time hh:mm represents a 24-hour time. The time range indicates the starting and ending stopped time. /TAKE_OWNERSHIP This qualifier indicates that the current user is requesting ownership of the specified queue. The user must have Executive or Full access permission in order to successfully take ownership. /USER_CHAR=(char:datatype:value,…) This qualifier is used to associate user characteristics with an Execution Queue. Char indicates a user characteristic name. This name is free form but cannot contain spaces. Datatype is either string or numeric. Value is a string or numeric value based on the characteristic datatype. You may specify multiple characteristics by separating each with a comma. /WORKING_FOLDER=device-directory-spec This qualifier indicates the default working directory for jobs submitted to this queue in which a directory has not been specified.

Example: $ MODIFY/QUEUE TESTQUEUE /BASE_PRIORITY=HIGH - /GRANT=EVERYONE:MANAGE - /JOB_LIMIT=5 This example will modify a queue named TESTQUEUE and set the O/S priority to HIGH, grant the Everyone Group Manage permissions, set the job limit to 5.


393

9.12.9 OPEN/QUEUE

The OPEN/QUEUE command allows job submission. Format:

OPEN/QUEUE queue-name Parameter:

queue-name This required parameter indicates the specific queue that is to be opened.


Example: $ OPEN/QUEUE TESTQUEUE This example opens the queue named TESTQUEUE and allows new job submission.


394

9.12.10 PAUSE

This command will pause an executing job instance. Note: On Windows 2000/NT machines, only the primary thread is suspended. For a multi-threaded process this may not necessarily produce the expected results.

Format: PAUSE/JOB=job-entry-id/qualifiers

Qualifiers: /JOB=job-entry-id This required qualifier indicates the specific job entry via its unique entry identification that is to be “Paused”. Please note that this command is only applicable to an executing job. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports).

Example: $ PAUSE/JOB=5/ON=NTSERVER1 This example will pause an executing job with an entry id of 5 on queue server NTSERVER1.


395

9.12.11 RELEASE

This command will release a held job.

Format: RELEASE/JOB=job-entry=id/qualifiers

Qualifiers: /JOB=job-entry-id This required qualifier indicates the specific job entry via its unique entry identification that is currently held and will now be released for possible execution. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports). /PATH=path This qualifier allows you to lookup a specific job using the object’s path (for example, “/Testjob” would refer to the object labeled ‘TestJob’).

Example: $ RELEASE/JOB=5/ON=NTSERVER1 This example will release a held job with an entry id of 5 on queue server machine NTSERVER1.


396

9.12.12 REQUEUE

This command will requeue (or move) a job to another queue.

Format: RELEASE/JOB=job-entry=id/qualifiers

Qualifiers: /JOB=job-entry-id This required qualifier indicates the specific job entry via its unique entry identification that is to be moved to another queue. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports). /PATH=path This qualifier allows you to lookup a specific job using the object’s path (for example, “/Testjob” would refer to the object labeled ‘TestJob’). /QUEUE=new-queue-name This qualifier indicates the destination queue that this job is to be moved to.

Example: $ REQUEUE/JOB=15/QUEUE=MASTER This example will requeue job 15 to queue MASTER.


397

9.12.13 RESTART

This command will restart an existing job or plan instance.

Format: RESTART/qualifiers

Qualifiers: /JOB=job-entry-id This required qualifier indicates the specific object via its unique object identification number. Note: Only an instance (and not a definition) can be restarted. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports).

Example: $ RESTART/JOB=5/ON=NTSERVER1 This command will abort and then restart the job with an entry id of 5 on a machine named NTSERVER1.


398

9.12.14 RESUME

This command will resume a paused job instance.

Format: RESUME/JOB=job-entry-id/qualifiers

Qualifiers: /JOB=job-entry-id This required qualifier indicates the specific object via its unique object identification number. Note: Only an instance (and not a definition) can be resumed. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports).

Example: $ RESUME/JOB=5/ON=NTSERVER1 This example will resume a paused job with an entry id of 5 on Job Scheduler machine NTSERVER1.


399

9.12.15 SET BATCH

This command allows an Administrator to establish defaults for an ActiveBatch user as well as change ActiveBatch Administrator status.

Format: SET BATCH/qualifiers Qualifiers:

/DENY=(account:access…,…) This qualifier is used to deny an account access that the account may also obtain through a group. account refers to the WinNT account name (or group) and access refers to one or more of the following keywords: EXECUTIVE, MANAGE and USER. To specify more than one level of access to be denied, separate each access with a colon. Multiple accounts may be specified by delimiting each account/access string with a comma. /GRANT=(account:access,…) This qualifier is used to associate security permissions to the queue that is to be created. By default, the owner and Administrator are given full access to the queue and the all other users are given Submit level access (this default can be changed with the SET BATCH command). To associate different permissions for this queue, you may specify one or more accounts and the level of access each account (or group) may have with this queue. Access is specified using one or more of the following keywords:


Each keyword specified must be separated by a colon. Multiple accounts are separated by a comma. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports).


400

/[NO]QUEUE=queue-name This qualifier allows you to designate a default Queue to be used when a SUBMIT command is issued. By default, the /QUEUE qualifier is required to be specified with the SUBMIT command. Negating the qualifier causes the default to be removed. /REMOVE=(account,…) This qualifier removes the specified accounts permissions. More than one account may be specified separated by a comma. /[NO]SCHEDULER=machine This qualifier allows you to designate a default Job Scheduler machine to be used when invoking other command-line utilities. By default the local machine is assumed. Negating the qualifier causes the default to be removed.


401

9.12.16 SHOW JOB

This command will display batch jobs based on various search parameters.

Format: SHOW JOB/qualifiers Qualifiers:

/ALL_JOBS By default, only jobs submitted by the owner are eligible for display. This qualifier indicates that all batch jobs, regardless of who submitted the job, are eligible for possible display. /BRIEF This qualifier indicates that only very terse information be displayed for each job. BRIEF is the default. /BY_JOB_STATUS=( DEFERRED | EXECUTING | HELD | PENDING) This qualifier allows you to further refine the search to those jobs in the above specified job states. /EXECUTION_QUEUE This qualifier allows the search for eligible jobs to be further refined to those on execution queues. /FULL This qualifier is used to display complete information on all jobs which are to be displayed. /BRIEF is the default. /GENERIC This qualifier displays jobs that are on a generic queue. EXECUTION_MACHINE and GENERIC qualifiers are mutually exclusive. /JOB=job-entry-id This required qualifier indicates the specific job entry via its unique entry identification is to be set to “Hold” status. Please note that an active executing job cannot have its state changed via this command. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports). /PATH=path This qualifier allows you to lookup a specific job using the object’s path (for example, “/Testjob” would refer to the object labeled ‘TestJob’).


402

/OUTPUT=FileSpecification This qualifier allows the command display to be redirected to a disk file. By default, the output of this command is sent to Standard Out (normally the console window). /USERNAME=username This qualifier allows the search for eligible jobs to be further refined to a specific username. By default, the username of this command is used for job selection. ALL_JOBS and USERNAME are mutually exclusive.

Note: If Job, Name and/or Label are specified the following order of precedence is used: Job, Name and then Label. Example:

$ SHOW JOB /FULL /JOB=6 Job 6 submitted to Queue TESTQUEUE on TEST by XLNTUSER Job Name : TEST2 Status : Retained : CFFD00B5 Priority : 10 File : C:\TESTXCP\TEST2.XCP Command Shell : XLNT Log File : C:\TESTXCP\TEST2.LOG Characteristics : Job Restart disabled, Notification enabled for TEST:XLNTUSER via NT Messenger Service, Log File printing disabled, Log File deleted

This example shows a batch job with an ID of 6 on a machine called TEST and shows all information about that job.


403

9.12.17 SHOW QUEUE

This command will display batch jobs based on various search parameters.

Format: SHOW QUEUE/qualifiers [queue-name]

Parameter: queue-name

This optional parameter represents a specific queue name to display. If omitted, all queues are eligible for display. Qualifiers:

/ALL_JOBS By default, only jobs submitted by the owner are eligible for display. This qualifier indicates that all batch jobs, regardless of who submitted the job, are eligible for possible display. /BRIEF This qualifier indicates that only very terse information be displayed for each job. BRIEF is the default. /EXECUTION_MACHINE=machine-name This qualifier allows the search for eligible jobs to be further refined to those execution queues which are associated with a given machine. /FULL This qualifier is used to display complete information on all jobs which are to be displayed. /BRIEF is the default. /GENERIC This qualifier displays jobs that are on a generic queue. EXECUTION_MACHINE and GENERIC qualifiers are mutually exclusive. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports).


404

/OUTPUT=FileSpecification This qualifier allows the command display to be redirected to a disk file. By default, the output of this command is sent to Standard Out (normally the console window). /USERNAME=username This qualifier allows the search for eligible jobs to be further refined to a specific owner. By default, the username of this command is used for job selection. ALL_JOBS and OWNER are mutually exclusive.

Example: $ SHOW QUEUE TESTQUEUE /FULL Execution Queue TESTQUEUE on TEST, owned by XLNTUSER Status : Started, Opened Job Retention : Failed Jobs Base Priority : NORMAL Queue Priority : 10 Command Shell : XLNT Job Limit : 1 Description: A Test Queue Account Permissions ------- ----------- Administrators Granted: EXECUTIVE, MANAGE, USER SYSTEM Granted: EXECUTIVE, MANAGE, USER Everyone Granted: USER DOMAIN\XLNTUSER Granted: EXECUTIVE, MANAGE, USER Jobs on Queue TESTQUEUE No Jobs on Queue This example shows the queue called TESTQUEUE with complete information on all jobs.


405

9.12.18 START/QUEUE

The START/QUEUE command allows a queue to be started for job execution.

Format: START/QUEUE queue-name

Parameter: queue-name This required parameter indicates the specific queue that is to be started.


Example: $ START/QUEUE TESTQUEUE This example starts the queue named TESTQUEUE for job execution.


406

9.12.19 STOP/QUEUE

The STOP/QUEUE command prevents further job execution on a queue basis and/or aborts a currently executing job.

Format: STOP/QUEUE queue-name

Parameter: queue-name This required parameter indicates the specific queue that is to be stopped.

Qualifiers: /AFTER_EXECUTION This qualifier indicates that the currently executing job should be allowed to complete prior to the queue being stopped. AFTER_EXECUTION is the default. /CLOSE This qualifier indicates that the queue is to be closed for job submission. /IMMEDIATE This qualifier indicates that the currently executing job is to be aborted immediately. By default, the job is allowed to complete (see AFTER_EXECUTION). /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports).

Example: $ STOP/QUEUE TESTQUEUE /IMMEDIATE This example stops the queue named TESTQUEUE immediately rather than waiting for the jobs to execute.


407

9.12.20 SUBMIT

The SUBMIT command is used to submit a job for batch execution.

Format: SUBMIT/qualifiers job-file-specification

Parameter: job-file-specification This required parameter is a file specification which will represent the job. The file specification may be an executable (.EXE) or any file which contains a known file association.

Qualifiers: /[NO]ACTIVEBATCH_EVENT This qualifier indicates whether the job can accept an ActiveBatch TRIGGER command. The default is that a job can accept the command. /[NO]ACCOBJ=user-account-name This qualifier indicates whether a user account name object is being referenced for security (username, password) information. Negating this qualifier indicates the object’s reference is to be removed from this job. User account name objects are highly recommended for security purposes instead of using embedded security credentials within the job. /AFTER=combination-time This qualifier is used to defer a job so that the job will be executed at some future time. The time specified is any valid combination time (including keywords TODAY and TOMORROW). If /AFTER is specified without a combination time specified the keyword TODAY is assumed. By default, job execution is assumed to be immediate. /BASE_PRIORITY=(LOW | BELOWNORMAL | NORMAL | ABOVENORMAL | HIGH | REALTIME | number) This qualifier represents the operating system scheduling priority assigned to the batch job. For Windows 2000/NT machines the keywords above are used. For non-Windows machines, a priority number must be specified. By default, the base priority is taken from the queue’s characteristics. /CALENDAR=calendar-name This qualifier associates a business calendar with the job. This allows a job to be scheduled only on working days. /CATEGORY=”string” This qualifier indicates the user category or other string value that will be kept with the job. /CONTACT=(delivery:target[:time],…) This qualifier is used to denote contact information for those machines/users that are to be notified when a job starts or completes execution. Delivery represents one of two keywords which indicate how the notification is to be occur. MAIL or MESSENGER are valid delivery keywords. Target represents either a machine name, if the delivery is MESSENGER, or a valid e-mail address if the delivery is MAIL. Time indicates either a START or FINISH job time criteria that is used to indicate when the notification is to be sent. If “time” is omitted, then FINISH is assumed. You may specify more than one contact by separating each contact specification with a comma. /COPY=(PRE, POST, MAIN) This qualifier is used to indicate which batch job file steps should be copied to the selected Execution Machine. The keywords PRE, POST and MAIN indicate which batch file steps are to be copied. By default, no batch files are copied. /DENY=(account:access,…) This qualifier is used to deny an account access that the account may also obtain through a group. account refers to the WinNT account name (or group) and access refers to one or more of the following keywords: READ, WRITE, DELETE, EXECUTE, TAKEOWNERSHIP, TRIGGER, TRIGGERPARAM and TRIGGERQUEUE. To specify more than one level of access to be denied, separate each access with a colon. Multiple accounts may be specified by delimiting each account/access string with a comma. /DESCRIPTION=”string” This qualifier is used to set the pending job’s description specified at job submission time. /DOCUMENTATION=”string” This qualifier is used to associate a documentation reference with the job. /EVERY=(MINUTE=mm,… , HOUR=hh,… , WEEKDAY=ddd,… , DAY=dd,… , MONTH=mm,…) Note: This qualifier while supported is obsolete and has been superceded by the /SCHEDULE qualifier. This qualifier indicates that a rescheduled job entry is to be created. By default, if all keywords are omitted, a job entry is created that will execute at


408

midnight each day. Valid keywords are as follows. Specification of multiple values or multiple keywords is supported through the use of comma delimitation.

MINUTE valid range of 0 through 59. Default is 0. HOUR valid range of 0 through 23. Default is 0. WEEKDAY acceptable values are SUN, MON, TUE, WED, THU, FRI, SAT. DAY valid range of 1 through 31. A day which is specified as greater than the number of days in the

month denotes the last day of the month. Default is every day of a month. MONTH valid range of 1 through 12. Default is every month.

The EVERY and INTERVAL qualifiers are mutually exclusive. When a DAY is specified that exceeds the actual number of days in the month, ActiveBatch will assume that the last day of the month is to be selected. If multiple DAYs are specified which exceed the actual number of days in the month, the job will be scheduled once on the last day of the month. /FAILURESTART=(job-id,…) This qualifier indicates one or more jobs to trigger if the job completes in failure. One or more job-id’s are entered in a comma delimited format. /GRANT=(account:access,…) This qualifier is used to associate security permissions to the job that is to be created. To associate permissions for this job, you may specify one or more accounts and the level of access each account (or group) may have. Access is specified using one or more of the following keywords:

READ Read access WRITE Read and Write access DELETE Delete access TAKEOWNERSHIP Take Ownership TRIGGER Trigger access TRIGGERQUEUE Trigger with Queue change access TRIGGERPARAM Trigger with Parameters change EXECUTIVE Security/Take Ownership FULL Complete access

Each keyword specified must be separated by a colon. Multiple accounts are separated by a comma. /GROUP=name This qualifier indicates the group name for this job. A group name may be used to group related jobs and perform group operations. /HOLD[=(SUBMIT, ERROR, COMPLETION)] This qualifier is used to set the initial “Hold” state of a job. If this qualifier is not specified, the job will become eligible for execution based on its position in an execution queue. The SUBMIT keyword (the default if only /HOLD is specified) indicates the job is to enter a “Hold” state immediately upon a successful submission. The ERROR keyword indicates that the job is to enter a “Hold” state if the job completes in error. The COMPLETION keyword indicates the job is to enter a “Hold” state upon job completion (regardless of whether the job was successful or not). One or more keywords may be specified. /IFACTIVE=(keyword | WAIT[:time]) This qualifier indicates whether more than one instance of a scheduled job can execute. Possible keywords are: SKIP, MULTIPLE and WAIT. SKIP indicates that the scheduled instance should be skipped if an instance is already executing. MULTIPLE indicates that more than one instance of the job can run. WAIT indicates that the job should wait. You may optionally indicate how long to wait before skipping the job. SKIP is the default. /IMMEDIATE This qualifier when used with the /SCHEDULE qualifier indicates that the job is to run immediately. /INTERACTIVE=(NORMAL | MAXIMIZED | MINIMIZED) This qualifier indicates that the job is to be executed interactively on the desktop. The keywords NORMAL, MAXIMIZED and MINIMIZED indicate the starting state of the visible window. If the qualifier is specified and the keyword is omitted, NORMAL is assumed.


409

/INTERVAL=delta-time This qualifier indicates that a rescheduled job entry should be created. A valid delta time can be specified with the exclusion of the TODAY and YESTERDAY keywords. The delta-time specification allows for a self-relative time specification in days, hours, minutes and seconds which are added to the last submission time of the job. EVERY and INTERVAL qualifiers are mutually exclusive. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LABEL=label This qualifier is used to set the job’s object label. The label portion of an object is used to scripting purposes to uniquely identify the object. If this qualifier is omitted, ActiveBatch will create a unique label using a portion of the job’s name. /LOG This qualifier is used to display a message when the operation is successful. /[NO[MANAGE_LOGFILES This qualifier is used to indicate whether ActiveBatch is to centrally manage the job’s log files. If enabled, the location and name of the job’s log files are specified by ActiveBatch (you can programmatically obtain the names). If disabled, you retain the ability to locate and name the log files. /[NO]MAX_RESTARTS=n This qualifier is used to specify the maximum number of restarts the job may undergo. /NOMAX_RESTARTS means an unlimited number and a value specified means the job will be limited to that number of restarts. Please note that this value is applicable until the job completes. /NAME=jobname This qualifier is used to set the name of the submitted job. By default , the job name is set to that of the filename portion of the job file specification. /[NO]NOTIFY[=username] This qualifier is used to indicate that the user submitting the job wants to be notified when the job completes. If a value is set with the NOTIFY qualifier that value is a username specification. By default, NONOTIFY is assumed. Note: This qualifier has been made obsolete by the /CONTACT qualifier. The equivalent syntax is /CONTACT=machine-name:MESSENGER:FINISH. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports). /[NO]OUTPUT[=file-specification] This qualifier is used to indicate whether a log file is to be created with the batch job and if so the specification of that log file. /NOOUTPUT means that a log file isn’t to be created. By default, a batch log file is produced in the current directory of the created job. The default batch log file specification is the job-file-specification with a .LOG extension. When /INTERVAL or /EVERY or /SCHEDULE is specified, the following additional information is automatically appended to the output log filename: _mmdddyyyy_hhmmss. This helps keep each individual log file separate and distinct as a batch job is rescheduled. Note: This qualifier is ignored if the /MANAGE_LOGFILES qualifier is specified. /[NO]PARAMETER=(value1,…value8) This qualifier is used to set the input parameters associated with a specific job. Values specified may be strings or numbers. A maximum of eight (8) values may be specified. NOPARAMETER means that no input parameters are to be associated with the job (which is the default). /PASSWORD[=”string”] This qualifier is used to associate a password in conjunction with the current username or a username specified with the /USERNAME qualifier. If specified as a “string” value be sure to enclose the password as a quoted string to prevent the case from being changed. If a password value is not specified, the command will prompt for one (echo is disabled for security purposes). /POST_STEP=file-specification This qualifier indicates that a post-job step is to be performed.


410

/PRE_STEP=file-specification This qualifier indicates that a pre-job step is to be performed. The pre-job step is executed prior to the main job file. /PRIORITY=number This qualifier is used to set the queue insertion priority of a job. The valid range is 1 through 99. By default, the queue insertion priority is taken from the queue’s characteristics. /PROCESSORMASK=n This qualifier is used, in a multi-processing system, to denote processor affinity. The value specified should be considered a bit-mask. For example, a value of 3 means bit 0 and 1 and would denote processors zero and one. /QUEUE=queue-name This qualifier is used to indicate the queue that the job is to be submitted on. This qualifier is required unless a default queue has been established using the SET BATCH command. /QUEUE_SELECTION=ANY | ALL | EVENT This qualifier, appropriate to Generic Queues only, allows you to select whether one eligible execution queue should be used, all eligible machine queues should be used or only the machine that generated the event should be used. /[NO]READ_ONLY This qualifier indicates that the job’s properties should be set to a “read only” state. The default is /NOREAD_ONLY. /REMOVE=(account,…) This qualifier removes the specified accounts permissions. More than one account may be specified separated by a comma. /[NO]RESTART=[WAIT | FAILOVER | TERMINATE] This qualifier is used to set the restartability of an executing job. /RESTART indicates that the job is to be automatically requeued for execution. /NORESTART indicates that the job is to be removed from the queueing system in the event of a system failure. /[NO]RETAIN_HISTORY=days This qualifier is used to indicate the retention period for a completed job. The /NORETAIN_HISTORY means that the job’s history is to be removed when the ActiveBatch Database Purge program runs. A value specified indicates the number of days to save the history information. /[NO]RETAIN_LOGFILES=days This qualifier is used to indicate the retention period of the job’s log files. The /NORETAIN_LOGFILES means that the job’s log files are to be removed when the ActiveBatch Database Purge program runs. A value specified indicates the number of days to save the log files. Please note that this value should not be less than that specified for /RETAIN_HISTORY (otherwise it will be automatically adjusted to the same value). /[NO]REUSE This qualifier may be used to enable or disable the “Reuse Log File” facility. By default, this property is disabled which means that every instance run results in a new log file. Reuse Log file enabled means that a single log file is created (except OpenVMS in which a new version of the log file is created). /[NO]RUNONCE This qualifier is used to specify whether the job is to run once regardless of whether the job is date/time triggered or event triggered. The default is /NORUNONCE. /[NO]SAVE_PASSWORD This qualifier, valid on Windows 2000/NT machines only, indicates that the password specified should be saved. /NOSAVE_PASSWORD indicates that a saved password should be removed and any specified password should not be saved.


411

/SCHEDULE=(name,…) If specified this qualifier indicates that the named schedules should be associated with this job. The schedules must already exist (if not, you should use the INITIALIZE/SCHEDULE command to create one). /SUCCESS_RULE=(n | n-n | ODD | EVEN | LZERO | NTMSG,…) This qualifier indicates how ActiveBatch interprets the main job step’s exit code. The values specified all indicate that the job completed successfully. You may specify a single value, a range of values and/or a keyword indicating success. /SUCCESS_START=(job-id,…) This qualifier indicates one or more jobs to trigger if the job completes successfully. One or more job-id’s are entered in a comma delimited format. /TAKE_OWNERSHIP This qualifier indicates that the current user is requesting ownership of the specified job. The user must have Executive or Full access permission in order to successfully take ownership. /[NO]TERMINATE This qualifier indicates whether children processes should be terminated when the job exits. On Windows NT V4, children processes are identified as having the same parent id (PID). This technique is not precise. On Windows 2000, a job with this qualifier enabled, is created as a job object. OpenVMS and Unix operating systems terminate child or subprocess trees regardless of the setting of this qualifier. By default, /NOTERMINATE is assumed. /TIME_ZONE= CLIENT | JOBSCHED | UTC This qualifier indicates the time zone which should be used by the Job Scheduler to actually schedule time triggers. By default the Job Scheduler’s time zone is used. /USERNAME=username This qualifier is used to set the username that initially submitted the job for execution. Typically when this qualifier is used, the /PASSWORD qualifier is asserted as well. /WORKING_FOLDER=device-directory-spec This qualifier indicates the default working directory for this job.

Example: $ SUBMIT C:\TEST\TEST.XCP /QUEUE=TESTQUEUE –

/NAME=TESTJOB /NOOUTPUT /USERNAME="XLNTUSER" /PASSWORD="12345" This example will submit a batch job with a procedure name of C:\TEST\TEST.XCP, to a queue named TESTQUEUE, with a jobname of "TESTJOB" and will not send the output to a Logfile. It will also submit it under a username of XLNTUSER and a password of 12345.


412

9.12.21 SYNCHRONIZE

The Synchronize command allows the issuer to wait for the completion of an identified and running batch job.

Format: SYNCHRONIZE/qualifiers

Qualifiers: /JOB=entry-identification This qualifier identifies a job through its unique job entry identification number assigned when the job is submitted to a queue. If you specify both /JOB and the job-name parameter, /JOB will be used. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports).

Example:

$ SYNCHRONIZE /JOB=6 This example causes the issuer to wait for the completion of batch job entry id number 6.


413

9.12.22 TRIGGER

The Trigger command allows the issuer to trigger an existing job or plan for immediate execution. You must have “Trigger” access permission to use this command.

Format: TRIGGER/qualifiers

Qualifiers: /IGNORE=(DEPENDENCIES, CALENDAR, EXLCUSION) This qualifier indicates that the job is to ignore certain associated restrictions. The keyword restrictions are: DEPENDENCIES, CALENDAR and EXCLUSION. You may specify one or more qualifiers. By default, all restrictions are enforced. This qualifier is intended to be used when an operator or someone knowledgeable about the job and system intentionally wants to force the job to execute. /JOB=entry-identification This qualifier identifies a job or plan through its unique entry identification number assigned when the job/plan is created. If you specify /JOB, /NAME and/or /PATH, /JOB will be used. /JS_PASSWORD[=password] This qualifier is used in combination with the /JS_USERNAME and, optionally, /JS_SAVEPASSWORD to specify a password to be used with the value of /JS_USERNAME to form an authentication credential to communicate with the Job Scheduler machine. /[NO]JS_SAVEPASSWORD This qualifier indicates that the password specified with /JS_PASSWORD is to be stored for future authentication purposes. You can specify this qualifier only when /JS_PASSWORD is also specified. To delete a stored password specify /NOJS_SAVEPASSWORD. /JS_USERNAME=username This qualifier is used in combination with ./JS_PASSWORD to form an authentication credential used to communicate with the Job Scheduler machine. /LOG This qualifier is used to display a message when the operation is successful. /NAME=job-name This qualifier represents a unique job name that is to be triggered for execution. If /JOB is also specified, this qualifier is ignored. /ON=scheduler-machine-name This qualifier allows the command to be directed to the named Job Scheduler machine. You may specify any valid machine name or IP address (depending on the protocols your machine supports). /PARAMETERS=(param1,…,param8) This qualifier allows you to set input parameters when the job instance is created. You must hold “Trigger with Parameters” job access permissions to specify this qualifier. /PATH=path This qualifier allows you to lookup a specific job using the object’s path (for example, “/Testjob” would refer to the object labeled ‘TestJob’). /QUEUE=queue-name This qualifier is used to explicitly create a job instance on the specified queue. You must hold “Trigger with Queue” job access permission to set this qualifier. /SYNCHRONIZE This qualifier allows you to combine the functions of triggering a job or plan instance and then waiting for the instance to complete (by synchronizing on the newly created instance). /VARIABLES=(var1=value1, …) This qualifier allows you to pass variables and their values to the plan or job that you are about to trigger. If the variable currently exists within the target object, that variable’s value will be replaced. If the variable does not exist a new variable (and it’s value) will be created.

415

10 ACTIVEBATCH SCRIPTING AND PROGRAMMING The ActiveBatch Client sub-system is Microsoft COM based. This means that ActiveBatch is a collection of objects, properties and methods. ActiveBatch allows you to use any object-oriented language (and scripting language) to directly manipulate these objects.

To learn more about the programmatic aspects of ActiveBatch, we invite you to read the “ActiveBatch Developer’s Guide”.


416

10.1 ActiveBatch Object Topology Figure 234 is a drawing that visually describes the different ActiveBatch objects and their relationship.

Figure 234 – ActiveBatch Object Relationship

417

11 ACTIVEBATCH MESSAGES

The following tables list all the pertinent ActiveBatch messages. The message codes follow the Windows 2000/NT convention and contain the severity as part of the message code. In addition, the messages themselves contain a facility code “ABAT”, a severity code (“I”, “W”,”E”) and the message name followed by the text of the message. All ActiveBatch messages are contained in the ABATMSG.DLL file and can be found in the ActiveBatch installation directory.

Please note that the tables do not contain every ActiveBatch message but rather the messages that a user can typically expect to see. The first table lists all the messages in alphabetical order; the second table lists the messages using the numeric value (in hex).

Message Value (hex) Description/Action ABAT-E-ABORTENTRY, Entry has been aborted CFFD00C5 A job has been marked as ‘aborted’. ABAT-E-ALLOCFAIL, Failure to allocate memory CFFD0008 This is an internal error usually indicating that

insufficient hardware or software resources are available to satisfy a memory request.

ABAT-E-ASSOCNOTFND, Failure to determine file association

CFFD015E The Execution Agent was unable to find the job file’s extension to program association. The job was not run.

ABAT-E-AUDPURGEFAIL, Failed to purge Audit ID %1!d!

CFFD01EB This DBPurge message can appear in the NT Application Event Log and indicates that DBPurge was unable to remove old audit messages from a specific job.

ABAT-E-BADPARAM, Bad parameter received CFFD000B This is a general error indicating that a bad parameter was specified. Depending on the context you should specify a legal value or property and try again.

ABAT-E-BATCHSTARTERR, unable to launch Batch Start job

CFFD01CA A job completed and had a Batch Start (Success or Failure) action associated with it. That action could not be performed. Additional information accompanies this message indicating more specifically what the problem was.

ABAT-E-CONNECTFAIL, Failure to connect to Server, %1!s!

CFFD0005 This is a general non-specific error indicating that the client was unable to connect to a server machine. Please check the machine name or IP address and try again.

ABAT-E-COPYFILEERROR, An error occurred while copying the file '%1!s!' to the Job Scheduler because the file cannot be found or there was an error opening/reading the file.

CFFD01A7 This message can occur if the “Copy File” feature is enabled for a Main, Pre or Post file. As the message indicates an error occurred while attempting to copy the file to the Job Scheduler.

ABAT-E-CRELOGFILE, Failure to create log file CFFD015F The Execution Agent was unable to create the batch job’s log file. Typically, the log file specification is not valid or proper OR the main job script file specification is also not valid. Please check the log/script file specification and ensure it can be created from the Execution machine.

ABAT-E-DBPURGEFAIL, An error occurred while running the DBPurge process. Please examine the NT Event Log/DBPurge Log for further details

CFFD01EA Self-explanatory. This error message concerns the running of the DBPurge facility to prune unneeded jobs from the ActiveBatch system.

ABAT-E-DEPENDFAIL, dependency failure CFFD01AE The Batch Job failed because a job dependency could not be satisfied.

ABAT-E-DISCONFAIL, Failure to disconnect from CFFD000E An error occurred disconnecting from a Job Scheduler


418

Message Value (hex) Description/Action server machine. This is typically not something to be overly

concerned about since the error occurs on the disconnect itself.

ABAT-E-DUPLICATE_KEY_VALUE, Duplicate key value

CFFD0070 This error is returned when an attempt has been made to create an object with a duplicate key (2 objects with the same name).

ABAT-E-DUPLICFND, A duplicate license was found. Please ensure that all licenses are valid and unique.

CFFD01D7 This serious error usually indicates some level of license tampering. Please run the ABATLIC program to obtain more information.

ABAT-E-EAGENTADNAMERR, unable to translate Exec Agent Active Directory Name

CFFD0239 An Active Directory published name was provided by a user and could not be translated. Please check the AD name given and try again.

ABAT-E-EMGRCONNECTFAIL, Failure to connect to Execution Queue Manager

CFFD0007 The Job Scheduler was unable to connect to the Execution Agent machine. Please check the machine name or IP address and try again; the machine may not be on the network; the machine may not be running RPC or DCE services.

ABAT-E-EMGRFAIL, Network connection to the execution machine has been lost

CFFD0033 Self-explanatory. Depending on network conditions this problem may resolve itself as the machine is re-discovered.

ABAT-E-EXCCPUTIME, job aborted exceeding expected cpu time

CFFD01C5 The Execution Agent has set this job’s exit status code because of an overrun for CPU time and has aborted the job.

ABAT-E-EXCMAXDISPATCH, job exceeded maximum dispatch time

CFFD0233 This job was terminated because it tried to execute after its established dispatch time.

ABAT-E-EXCRUNTIME, job aborted exceeding expected run time

CFFD01C4 The Execution Agent has set this job’s exit status code because of an overrun for elapsed run time and has aborted the job.

ABAT-E-EXECABORT, job aborted due to Execution Agent failure

CFFD01D1 A job was aborted when an Execution Agent/machine failed. The job was not marked as being restartable.

ABAT-E-FAILURE, Failure in Batch Queue Management System operation

CFFD0002 A non-specific error occurred. The error is typically either internal or transient. Please try the operation again.

ABAT-E-FILESIZEERROR, The file being copied is larger than the system policy allows for

CFFD01A8 The ActiveBatch Administrator has prevented your file from being copied to the Execution Machine through the System policy CopyScriptMax

ABAT-E-FORCERUNERR, unable to Force Run job -- see JSS log for details

CFFD023B A Force Run command was issued and was unable to execute. The JSS log (found in the LOG sub-directory provides additional information).

ABAT-E-GETOWNER, unable to obtain object owner

CFFD01E5 ActiveBatch is unable to retrieve the owner of the object. This error may appear if the domain of the owner’s account is not available.

ABAT-E-HASASSOCIATIONS, object is associated with other items

CFFD0230 The object you want to delete is referred to by other objects. You must either disassociate these object references or enable the forceddelete flag to forcibly de-reference these associations.

ABAT-E-IMPERSONERR, Failure to impersonate client

CFFD00CF This error can be returned if you attempt to connect to a Job Scheduler while the Scheduler is still in the process of starting. Please wait a moment and try again.

ABAT-W-INCONSOS, ActiveBatch Product Edition is inconsistent with Operating System level

8FFD022E The ActiveBatch base product license you’ve previously entered does not allow operation on this Operating system type (for example, Enterprise or Datacenter Server).

Chapter 11 - ActiveBatch Messages

419

Message Value (hex) Description/Action ABAT-E-INITQFAIL, Failure to initialize a queue CFFD000D The operation to initialize a queue failed. The queue

was not created. A more specific error usually accompanies this error.

ABAT-E-INITSD, Failure to initialize ABAT Security Descriptor

CFFD0100 This is an internal error indicating a failure to create a security descriptor the object. This error may be logged to the product’s trace file.

ABAT-E-INSTSKIPPED, instance skipped due to active instance

CFFD01EC This audit message indicates that a job instance could not be executed because the template’s property did not allow multiple concurrent copies of the job to run simultaneously.

ABAT-E-INSTWAITFAIL, active instance wait failed CFFD01ED This audit message indicates that a job instance could not be executed because the “If Job Active… Wait” property was enabled and the timeout period expired.

ABAT-E-INSUFFPRV, Insufficient privilege to perform Batch Queue Management operation

CFFD00FA You attempted to perform a queue or job operation for which you lack sufficient access permissions.

ABAT-E-INVCALCONFIG, An invalid Calendar configuration was made. Please make sure that all the calendar will allow a job to run at least once

CFFD01FF You have attempted to create a job and schedule combination in which the job will never run. For example, scheduling a job on December 25th and then assigning a Calendar with Christmas as a holiday.

ABAT-E-INVHISTPROP, Job save history duration must be greater or equal to the log file retension period

CFFD01C6 Self-explanatory.

ABAT-W-INVJOBTYPE, job type is not valid for specified operation

8FFD0231 The operation attempted is illegal when used against a job’s template. Please verify operation and then issue against job instance.

ABAT-E-INVOPER, An invalid operation was specified

CFFD00DD Either: an invalid context was specified on an enumeration, or an invalid operation was specified based on a job current state. For example, attempting to release a job which isn’t held.

ABAT-E-INVOPNCLSTIME, Invalid queue OPEN time range or CLOSE time range

CFFD0024 The time you entered was not in 24-hour time format. 00:00 through 23:59 is the legal range.

ABAT-E-INVOSPRIORITY, Invalid operating system priority

CFFD0040 An illegal O/S priority value has been specified as part of a job.

ABAT-E-INVOSQPRIORITY, Invalid operating system scheduling priority

CFFD0020 You specified an illegal O/S priority value as the Job default with a queue.

ABAT-E-INVREGVAL, Invalid registry key value, %1!s!

CFFD0009 Data associated with a Registry Key is of an incompatible type. For example, the datatype should be REG_DWORD and the value was found to be REG_SZ; the value itself is not legal.

ABAT-E-INVSTRTSTPTIME, Invalid queue START time range or STOP time range

CFFD0023 The time you entered was not in 24-hour time format. 00:00 through 23:59 is the legal range.

ABAT-E-ITEMALREADYEXISTS, The item being added to the collection already exists

CFFD019D This general error indicates that you are attempting to add an object to a collection and the object already exists. For example, trying to add the same account and access to a security collection.

ABAT-E-JOBABORT, Job aborted during execution CFFD00C9 This is the exit status code of a job that has been aborted.

ABAT-W-JOBHELD, job is held 8FFD0236 You attempted to trigger a job that is held for execution. Release the job first and then retry.

ABAT-E-JOBHISTORYERR, History information for the requested job could not be found

CFFD01A9 This is an internal error indicating that the Job’s History information could not be retrieved.

ABAT-W-JOBNOTWAITING, job is not in a wait state

8FFD0232 You tried to Force Run a job that is not in a wait state


420

Message Value (hex) Description/Action ABAT-E-JOBSCHEDFAIL, Job Scheduler failed to start

CFFD019A This is the exit status code of a Job Scheduler Service which could not be started. Check the trace file or NT Application Event Log for more information.

ABAT-E-JOBSONQUEUE, Jobs exist on queue CFFD00C4 An attempt to delete a queue failed due to jobs currently on queue. You can indicate that a ‘flush’ operation first be performed prior to the actual queue delete.

ABAT-E-JOBUNDERRUN, job has underrun specified time

CFFD0235 A job with monitoring enabled completed execution in much less time than was unexpected. The job is marked as having failed.

ABAT-E-JSSCONNECTFAIL, Failure to connect to Job Scheduler

CFFD0006 The client was unable to connect to the Job Scheduler machine. Please check the machine name or IP address and try again; the machine may not be on the network.

ABAT-E-JSSSTARTUPERR, unable to start Job Scheduler - refer to AbatJss.log for details

CFFD022F The Job Scheduler service cannot be started. Please check the AbatJSS.log file (in the LOG sub-directory) for more information.

ABAT-E-KEY_VALUE_NOT_FOUND, Key not found

CFFD006F This error/warning code indicates that a search for a specific object failed to be found in the database.

ABAT-E-LICENSEXP, license has expired CFFD0161 The evaluation serial number has expired. Please contact ASCI or your distributor for an extension.

ABAT-E-LOCALONLYLIC, This Personal Edition license is only permitted to communicate with a single Execution Agent on the Local Machine.

CFFD01DA When using the Personal Edition license you are restricted to a Workstation/Professional NT system and all connections are local to that system.

ABAT-E-LOGONERR, error logging user onto Execution Machine

CFFD00B5 This error indicates that the user’s username and/or password was not proper for logging the user onto the Execution Machine. Check the username and password (may be case sensitive) for the target system. More specific details may be found in the job’s log file.

ABAT-E-MAXEAGENTLIC, The maximum number of execution agent licenses has been met

CFFD01D3 This licensing error indicates that the maximum number of Execution Agent licenses has been reached. Count each Execution Machine you are attempting to connect to (regardless of whether the machine is active or the queue is started) and then compare against the value reported by the ABATLIC program.

ABAT-E-MSONLYLIC, This Job Scheduler license only permits connections to Microsoft Execution Agents

CFFD01D4 You are attempting to connect to a non-Microsoft Execution Agent and your license only permits you to connect to Microsoft Execution Agents.

ABAT-E-NOBINDINGFND, Binding handle not available or invalid registry %n protocol specified

CFFD000A This is an error indicating that a protocol sequence established in the Registry is not available on this machine. The RPC protocol sequence Registry key should be examined since it contains erroneous transports.

ABAT-E-NOMACHINENAME, No machine name has been specified

CFFD0003 A machine name needs to be specified. This error most typically occurs as a requirement for an execution queue or when connecting to a Job Scheduler machine.

ABAT-E-NOMORE, No more items 8FFD0178 This message code, typically returned as part of a context search, indicates that no more objects are available.

ABAT-E-NOPASSWORD, No password specified CFFD0013 Attempting an advanced connection requires a password; attempting to execute a batch job requires a password (unless Blank Password is enabled). Specify the password and try again. Note: You can let Activebatch remember the password for you.


421

Message Value (hex) Description/Action ABAT-E-NOQUEUENAME, No queue name specified

CFFD0010 No queue name was specified and one was required. Specify a valid queue name and try again.

ABAT-E-NOSUCHQUEUE, specified queue does not exist

CFFD00B0 Self-explanatory.

ABAT-E-NOTCONNECTED, A connection has not been successfully made to a Job Scheduler

CFFD019C You have attempted to perform an operation that requires a current connection to a Job Scheduler machine. Please make the connection and try again.

ABAT-E-NOTGENERIC, This is not a generic queue, unable to associate execution queues

CFFD00F9 Self-explanatory. Check queue properties.

ABAT-W-OBJEXISTS, an object of that name already exists

8FFD0234 You attempted to insert an object with a name that conflicts with an already existing object. The object you insert requires a unique name.

ABAT-E-OPENCMDFILE, Failure to open command procedure

CFFD0160 The Execution Agent was unable to open the batch job’s script file. Please check the main job’s file specification and ensure it can be opened from the Execution machine.

ABAT-E-PROPERTYREADONLY, You cannot modify this job because it is set as Read Only

CFFD01B5 Self-explanatory.

ABAT-E-QUEUEALRDYEXISTS, The queue already exists

CFFD0038 An attempt to create a queue of the same name failed since queue names must be unique.

ABAT-E-QUEUENOTFND, Queue not found CFFD002C The queue name you specified does not exist. Please check the spelling and try again.

ABAT-E-REGOPENERR, Failure to open registry HKEY_LOCAL_MACHINE subkey %1!s!

CFFD001C ActiveBatch was unable to open a Registry Key value in HKEY_LOCAL_MACHINE. While you should check Registry security permissions this error typically means that the ActiveBatch Registry keys have been corrupted or otherwise tampered with. You should try executing a product REPAIR through the ADD/REMOVE Control Panel applet.

ABAT-E-REGVALERR, Failure to obtain registry value %1!s!

CFFD001D ActiveBatch was unable to obtain the specified Registry value-name. Typically this means the ActiveBatch Registry keys and/or value names have been corrupted or otherwise tampered with. You should try executing a product REPAIR through the ADD/REMOVE Control Panel applet.

ABAT-E-REQPROPERTYINV, The required property %1!s! is either absent or invalid

CFFD01A5 Self-explanatory.

ABAT-E-RUNJOBINTERACTIVE, Unable to run the job interactively

CFFD01FC An error occurred while attempting to run this job interactively. The error is most likely due to a lack of desktop permissions.

ABAT-E-SERVERCOMMUNICATIONERROR, There was an error that occurred while communicating with the server

CFFD01A2 The client interface encountered an error while communicating with the Job Scheduler.

ABAT-E-TAKEOWNERFAIL, attempt to take ownership of specified object failed

CFFD01E4 Your attempt to take ownership of this object failed. Verify that you have “Executive” level permission.

ABAT-E-UNEXPEXCEPTCOM, An unexpected exception has occurred in the COM client

CFFD01DF Self-explanatory.

ABAT-E-WRKSTNONLYLIC, The Personal Edition license is only permitted to run on a Workstation Platform

CFFD01F9 Self-explanatory.

ABAT-I-ADDBATCHPRIV, The account under which this job is executing has been adjusted to have the "Logon as Batch" right

4FFD01DD The batch user has been automatically granted the “Logon as a Batch User” right.


422

Message Value (hex) Description/Action ABAT-I-DEPENDSAT, dependency is satisfied 4FFD01AD This audit message indicates that all job dependencies

were met. ABAT-I-EVTTRIGGERED, job triggered by event 4FFD0181 An event occurred which triggered execution of a job. ABAT-I-JOBSTART, job %1!s!(%2!s!) started successfully on queue %3!s!

4FFD00B1 Self-explanatory. This message is displayed by the command-line client.

ABAT-I-JSSUP, The ActiveBatch Job Scheduler Service has started

4FFD0036 Self-explanatory. Typically found in the JSS Trace file or NT Application Event Log indicating the Job Scheduler Service has been started.

ABAT-I-MARKDELETE, job marked for deletion 4FFD01B4 Typically a template job is marked for deletion when one or more active instances are still executing.

ABAT-I-NOWBEM, WBEM services will not be available on this system

4FFD0191 Microsoft’s WMI Services are either not available or have not been started.

ABAT-S-SUCCESS, normal successful completion 0FFD0001 Operation completed normally. No action to be taken. ABAT-W-ACCTLOOKUP, unable to lookup account 8FFD019E ActiveBatch was unable to lookup the specified

accounts SID and validate the account. Check any domain and account name spelling.

ABAT-W-ASSIGNJOBFAIL, unable to assign process to job object

8FFD01B1 The Execution Agent could not create a Windows 2000 Job Object within which to encapsulate the batch job.

ABAT-W-CPYFILERR, error copying file to execution machine

8FFD0184 The Job Scheduler was unable to open the job step(s) script/program file. An additional error code provides more information.

ABAT-W-CREPRCERR, error creating batch process for job %1!s!

8FFD00B6 An error occurred creating the batch job process. More specific details may be found in the job’s log file.

ABAT-W-EXCRESTART, maximum restart value exceeded

8FFD01D2 The job could not be restarted as it has reached its maximum restart count.

ABAT-W-GETSDERR, unable to obtain Security Descriptor

8FFD01B8 ActiveBatch was unable to find the object’s Security Descriptor.

ABAT-W-JOBCANTEXEC, job cannot execute based on Exclusion List/Calendar

8FFD01E9 This audit message appears if a job was scheduled for execution but could not be executed due to an Exclusion List or Calendar conflict.

ABAT-W-JOBNOTEXEC, job not currently executing

8FFD0168 You cannot restart a job that is not currently executing.

ABAT-W-JSSCONNFAIL, failed to connect to Job Scheduler on %1!s!

8FFD00B8 Self-explanatory. Check that the machine’s name or IP address is correct; verify that the machine is up and connected to the proper network; verify the RPCSS or DCE services have been started.

ABAT-W-LOADJOBSFAIL, unable to load job objects dll

8FFD01B3 For Windows 2000 machines, the Execution Agent attempts to load a special DLL which associates Windows Job Objects with ActiveBatch jobs. This warning indicates that Windows 2000 Job Objects will not be used.

ABAT-W-NOCOPY, unable to copy files to execution machine

8FFD0183 Self-explanatory. Please check the job step(s) file specifications. They must be accessible from the client machine.

ABAT-W-NOQUEUESFOUND, no active execution queues found

8FFD0182 This error can occur when a Generic Queue with Round Robin scheduling determines that no active execution queues are available to dispatch a job.

ABAT-W-NOSUCHALERT, no such alert 8FFD017D The specified alert could not be found for update or deletion purposes.

ABAT-W-NOSUCHCALENDAR, specified calendar does not exist

8FFD01E0 Self-explanatory.

ABAT-W-NOSUCHCHAR, no such characteristic 8FFD0177 The machine or user characteristic you specified could


423

Message Value (hex) Description/Action not be found.

ABAT-W-NOSUCHCONTACT, contact information not found

8FFD017A The specified user/machine contact information could not be found for update or deletion purposes.

ABAT-W-NOSUCHJOB, specified job does not exist 8FFD00BB Self-explanatory. The job’s ID did not match any present jobs in the system.

ABAT-W-NOSUCHPOLICY, specified policy does not exist

8FFD0198 The specified policy does not exist. Check the policy name spelling.

ABAT-W-NOTNT, operation requires Windows NT 8FFD00AF The Job Scheduler and Execution Agent services cannot be run on non-Windows 2000/NT systems.

ABAT-W-NOTTEMPLATE, not a template job 8FFD0199 The specified job is not a template. Certain operations can only be performed on a template job, for example, you cannot submit or move a non-template job to the OnDemand queue.

ABAT-W-PROCAFFINITY, unable to set processor affinity

8FFD01BF A processor mask was specified for this job. However, the mask affinity operation could not be performed. The job will still execute. This can be caused if the number of actual processors is less than that specified or an O/S specific restriction on assigning processors to jobs is violated.

ABAT-W-PROPTYLOCKED, property is locked 8FFD018D An attempt to modify a property failed because the property was locked and cannot be changed by an ActiveBatch non-Administrator.

ABAT-W-REQPARMABS, required parameter absent

8FFD017E You didn’t specify a schedule ID or the query event string for a Job.

ABAT-W-RPCEXCEPT, RPC Exception thrown 8FFD01B6 This message, if displayed, would be found in a product trace file.

ABAT-W-SCHEDATTACHED, jobs attached to this schedule

8FFD0167 You cannot delete this schedule since jobs are currently associated. You can disassociate the jobs from this schedule and then delete the schedule.

ABAT-W-TERMJOBFAIL, unable to terminate job object

8FFD01B2 The Execution Agent could not terminate the Windows 2000 Job Object. More information typically follows this error.

ABAT-W-TRIGGERFAIL, failed to trigger/clone job 8FFD0192 A job was triggered was unable to be cloned. An additional message provides more information concerning this condition.

ABAT-W-TRIGGERSDISABLED, ActiveBatch Event Triggers are disabled

8FFD01C3 Unable to issue TRIGGER command as ActiveBatch Triggers are not enabled.

ABAT-W-UNEXPEXCEPT, unexpected exception occurred

8FFD0068 An unexpected exception occurred. Typically this message code is not delivered to user code and is found in the product’s trace file depending on the trace level specified.

ABAT-W-UNKJSS, unknown Job Scheduler 8FFD01A6 The Execution Agent was unable to reconnect back to the Job Scheduler machine.

ABAT-W-WBEMCONN, unable to connect to WBEM

8FFD01C1 The WMI software has either not been installed or started.

ABAT-W-WMIQUERYFAIL, WMI Query request failed

8FFD01C2 ActiveBatch encountered an error issuing the Event Query string to WMI

Database Error: Communications Error CFFD00EC This error usually indicates that insufficient resources have been allocated for the Database server.

Database Error: Record manager inactive CFFD0079 This is an initialization error and indicates that the Database server has not been started. Verify that W32MKDE.EXE exists within the ActiveBatch installation directory.


424

Table 30 – ActiveBatch Messages (Alphabetical)


425

The hexadecimal values below are subject to change and are documented for reference information only.

VALUE (HEX) Message Description/Action

0FFD0001 ABAT-S-SUCCESS, normal successful completion

Operation completed normally. No action to be taken.

4FFD0036 ABAT-I-JSSUP, The ActiveBatch Job Scheduler Service has started

Self-explanatory. Typically found in the JSS Trace file or NT Application Event Log indicating the Job Scheduler Service has been started.

4FFD00B1 ABAT-I-JOBSTART, job %1!s!(%2!s!) started successfully on queue %3!s!

Self-explanatory. This message is displayed by the command-line client.

4FFD0181 ABAT-I-EVTTRIGGERED, job triggered by event An event occurred which triggered execution of a job. 4FFD0191 ABAT-I-NOWBEM, WBEM services will not be

available on this system Microsoft’s WMI Services are either not available or have not been started.

4FFD01AD ABAT-I-DEPENDSAT, dependency is satisfied This audit message indicates that all job dependencies were met.

4FFD01B4 ABAT-I-MARKDELETE, job marked for deletion Typically a template job is marked for deletion when one or more active instances are still executing.

4FFD01DD ABAT-I-ADDBATCHPRIV, The account under which this job is executing has been adjusted to have the "Logon as Batch" right

The batch user has been automatically granted the “Logon as a Batch User” right.

8FFD0068 ABAT-W-UNEXPEXCEPT, unexpected exception occurred

An unexpected exception occurred. Typically this message code is not delivered to user code and is found in the product’s trace file depending on the trace level specified.

8FFD00AF ABAT-W-NOTNT, operation requires Windows NT

The Job Scheduler and Execution Agent services cannot be run on non-Windows 2000/NT systems.

8FFD00B6 ABAT-W-CREPRCERR, error creating batch process for job %1!s!

An error occurred creating the batch job process. More specific details may be found in the job’s log file.

8FFD00B8 ABAT-W-JSSCONNFAIL, failed to connect to Job Scheduler on %1!s!

Self-explanatory. Check that the machine’s name or IP address is correct; verify that the machine is up and connected to the proper network; verify the RPCSS or DCE services have been started.

8FFD00BB ABAT-W-NOSUCHJOB, specified job does not exist

Self-explanatory. The job’s ID did not match any present jobs in the system.

8FFD0167 ABAT-W-SCHEDATTACHED, jobs attached to this schedule

You cannot delete this schedule since jobs are currently associated. You can disassociate the jobs from this schedule and then delete the schedule.

8FFD0168 ABAT-W-JOBNOTEXEC, job not currently executing

You cannot restart a job that is not currently executing.

8FFD0177 ABAT-W-NOSUCHCHAR, no such characteristic The machine or user characteristic you specified could not be found.

8FFD0178 ABAT-E-NOMORE, No more items This message code, typically returned as part of a context search, indicates that no more objects are available.

8FFD017A ABAT-W-NOSUCHCONTACT, contact information not found

The specified user/machine contact information could not be found for update or deletion purposes.

8FFD017D ABAT-W-NOSUCHALERT, no such alert The specified alert could not be found for update or deletion purposes.

8FFD017E ABAT-W-REQPARMABS, required parameter absent

You didn’t specify a schedule ID or the query event string for a Job.

8FFD0182 ABAT-W-NOQUEUESFOUND, no active execution queues found

This error can occur when a Generic Queue with Round Robin scheduling determines that no active execution


426


queues are available to dispatch a job. 8FFD0183 ABAT-W-NOCOPY, unable to copy files to

execution machine Self-explanatory. Please check the job step(s) file specifications. They must be accessible from the client machine.

8FFD0184 ABAT-W-CPYFILERR, error copying file to execution machine

The Job Scheduler was unable to open the job step(s) script/program file. An additional error code provides more information.

8FFD018D ABAT-W-PROPTYLOCKED, property is locked An attempt to modify a property failed because the property was locked and cannot be changed by an ActiveBatch non-Administrator.

8FFD0192 ABAT-W-TRIGGERFAIL, failed to trigger/clone job

A job was triggered was unable to be cloned. An additional message provides more information concerning this condition.

8FFD0198 ABAT-W-NOSUCHPOLICY, specified policy does not exist

The specified policy does not exist. Check the policy name spelling.

8FFD0199 ABAT-W-NOTTEMPLATE, not a template job The specified job is not a template. Certain operations can only be performed on a template job, for example, you cannot submit or move a non-template job to the OnDemand queue.

8FFD019E ABAT-W-ACCTLOOKUP, unable to lookup account

ActiveBatch was unable to lookup the specified accounts SID and validate the account. Check any domain and account name spelling.

8FFD01A6 ABAT-W-UNKJSS, unknown Job Scheduler The Execution Agent was unable to reconnect back to the Job Scheduler machine.

8FFD01B1 ABAT-W-ASSIGNJOBFAIL, unable to assign process to job object

The Execution Agent could not create a Windows 2000 Job Object within which to encapsulate the batch job.

8FFD01B2 ABAT-W-TERMJOBFAIL, unable to terminate job object

The Execution Agent could not terminate the Windows 2000 Job Object. More information typically follows this error.

8FFD01B3 ABAT-W-LOADJOBSFAIL, unable to load job objects dll

For Windows 2000 machines, the Execution Agent attempts to load a special DLL which associates Windows Job Objects with ActiveBatch jobs. This warning indicates that Windows 2000 Job Objects will not be used.

8FFD01B6 ABAT-W-RPCEXCEPT, RPC Exception thrown This message, if displayed, would be found in a product trace file.

8FFD01B8 ABAT-W-GETSDERR, unable to obtain Security Descriptor

ActiveBatch was unable to find the object’s Security Descriptor.

8FFD01BF ABAT-W-PROCAFFINITY, unable to set processor affinity

A processor mask was specified for this job. However, the mask affinity operation could not be performed. The job will still execute. This can be caused if the number of actual processors is less than that specified or an O/S specific restriction on assigning processors to jobs is violated.

8FFD01C1 ABAT-W-WBEMCONN, unable to connect to WBEM

The WMI software has either not been installed or started.

8FFD01C2 ABAT-W-WMIQUERYFAIL, WMI Query request failed

ActiveBatch encountered an error issuing the Event Query string to WMI

8FFD01C3 ABAT-W-TRIGGERSDISABLED, ActiveBatch Event Triggers are disabled

Unable to issue TRIGGER command as ActiveBatch Triggers are not enabled.

8FFD01D2 ABAT-W-EXCRESTART, maximum restart value The job could not be restarted as it has reached its


427


exceeded maximum restart count. 8FFD01E0 ABAT-W-NOSUCHCALENDAR, specified

calendar does not exist Self-explanatory.

8FFD01E9 ABAT-W-JOBCANTEXEC, job cannot execute based on Exclusion List/Calendar

This audit message appears if a job was scheduled for execution but could not be executed due to an Exclusion List or Calendar conflict.

CFFD0002 ABAT-E-FAILURE, Failure in Batch Queue Management System operation

A non-specific error occurred. The error is typically either internal or transient. Please try the operation again.

CFFD0003 ABAT-E-NOMACHINENAME, No machine name has been specified

A machine name needs to be specified. This error most typically occurs as a requirement for an execution queue or when connecting to a Job Scheduler machine.

CFFD0005 ABAT-E-CONNECTFAIL, Failure to connect to Server, %1!s!

This is a general non-specific error indicating that the client was unable to connect to a server machine. Please check the machine name or IP address and try again.

CFFD0006 ABAT-E-JSSCONNECTFAIL, Failure to connect to Job Scheduler

The client was unable to connect to the Job Scheduler machine. Please check the machine name or IP address and try again; the machine may not be on the network.

CFFD0007 ABAT-E-EMGRCONNECTFAIL, Failure to connect to Execution Queue Manager

The Job Scheduler was unable to connect to the Execution Agent machine. Please check the machine name or IP address and try again; the machine may not be on the network; the machine may not be running RPC or DCE services.

CFFD0008 ABAT-E-ALLOCFAIL, Failure to allocate memory This is an internal error usually indicating that insufficient hardware or software resources are available to satisfy a memory request.

CFFD0009 ABAT-E-INVREGVAL, Invalid registry key value, %1!s!

Data associated with a Registry Key is of an incompatible type. For example, the datatype should be REG_DWORD and the value was found to be REG_SZ; the value itself is not legal.

CFFD000A ABAT-E-NOBINDINGFND, Binding handle not available or invalid registry %n protocol specified

This is an error indicating that a protocol sequence established in the Registry is not available on this machine. The RPC protocol sequence Registry key should be examined since it contains erroneous transports.

CFFD000B ABAT-E-BADPARAM, Bad parameter received This is a general error indicating that a bad parameter was specified. Depending on the context you should specify a legal value or property and try again.

CFFD000D ABAT-E-INITQFAIL, Failure to initialize a queue The operation to initialize a queue failed. The queue was not created. A more specific error usually accompanies this error.

CFFD000E ABAT-E-DISCONFAIL, Failure to disconnect from server

An error occurred disconnecting from a Job Scheduler machine. This is typically not something to be overly concerned about since the error occurs on the disconnect itself.

CFFD0010 ABAT-E-NOQUEUENAME, No queue name specified

No queue name was specified and one was required. Specify a valid queue name and try again.

CFFD0013 ABAT-E-NOPASSWORD, No password specified

Attempting an advanced connection requires a password; attempting to execute a batch job requires a password (unless Blank Password is enabled). Specify


428


the password and try again. Note: You can let Activebatch remember the password for you.

CFFD001C ABAT-E-REGOPENERR, Failure to open registry HKEY_LOCAL_MACHINE subkey %1!s!

ActiveBatch was unable to open a Registry Key value in HKEY_LOCAL_MACHINE. While you should check Registry security permissions this error typically means that the ActiveBatch Registry keys have been corrupted or otherwise tampered with. You should try executing a product REPAIR through the ADD/REMOVE Control Panel applet.

CFFD001D ABAT-E-REGVALERR, Failure to obtain registry value %1!s!

ActiveBatch was unable to obtain the specified Registry value-name. Typically this means the ActiveBatch Registry keys and/or value names have been corrupted or otherwise tampered with. You should try executing a product REPAIR through the ADD/REMOVE Control Panel applet.

CFFD0020 ABAT-E-INVOSQPRIORITY, Invalid operating system scheduling priority

You specified an illegal O/S priority value as the Job default with a queue.

CFFD0023 ABAT-E-INVSTRTSTPTIME, Invalid queue START time range or STOP time range

The time you entered was not in 24-hour time format. 00:00 through 23:59 is the legal range.

CFFD0024 ABAT-E-INVOPNCLSTIME, Invalid queue OPEN time range or CLOSE time range

The time you entered was not in 24-hour time format. 00:00 through 23:59 is the legal range.

CFFD002C ABAT-E-QUEUENOTFND, Queue not found The queue name you specified does not exist. Please check the spelling and try again.

CFFD0033 ABAT-E-EMGRFAIL, Network connection to the execution machine has been lost

Self-explanatory. Depending on network conditions this problem may resolve itself as the machine is re-discovered.

CFFD0038 ABAT-E-QUEUEALRDYEXISTS, The queue already exists

An attempt to create a queue of the same name failed since queue names must be unique.

CFFD0040 ABAT-E-INVOSPRIORITY, Invalid operating system priority

An illegal O/S priority value has been specified as part of a job.

CFFD006F ABAT-E-KEY_VALUE_NOT_FOUND, Key not found

This error/warning code indicates that a search for a specific object failed to be found in the database.

CFFD0070 ABAT-E-DUPLICATE_KEY_VALUE, Duplicate key value

This error is returned when an attempt has been made to create an object with a duplicate key (2 objects with the same name).

CFFD0079 Database Error: Record manager inactive This is an initialization error and indicates that the Database server has not been started. Verify that W32MKDE.EXE exists within the ActiveBatch installation directory.

CFFD00B0 ABAT-E-NOSUCHQUEUE, specified queue does not exist

Self-explanatory.

CFFD00B5 ABAT-E-LOGONERR, error logging user onto Execution Machine

This error indicates that the user’s username and/or password was not proper for logging the user onto the Execution Machine. Check the username and password (may be case sensitive) for the target system. More specific details may be found in the job’s log file.

CFFD00C4 ABAT-E-JOBSONQUEUE, Jobs exist on queue An attempt to delete a queue failed due to jobs currently on queue. You can indicate that a ‘flush’ operation first be performed prior to the actual queue delete.

CFFD00C5 ABAT-E-ABORTENTRY, Entry has been aborted A job has been marked as ‘aborted’. CFFD00C9 ABAT-E-JOBABORT, Job aborted during

execution This is the exit status code of a job that has been aborted.


429


CFFD00CF ABAT-E-IMPERSONERR, Failure to impersonate client

This error can be returned if you attempt to connect to a Job Scheduler while the Scheduler is still in the process of starting. Please wait a moment and try again.

CFFD00DD ABAT-E-INVOPER, An invalid operation was specified

Either: an invalid context was specified on an enumeration, or an invalid operation was specified based on a job current state. For example, attempting to release a job which isn’t held.

CFFD00EC Database Error: Communications Error This error usually indicates that insufficient resources have been allocated for the Database server.

CFFD00F9 ABAT-E-NOTGENERIC, This is not a generic queue, unable to associate execution queues

Self-explanatory. Check queue properties.

CFFD00FA ABAT-E-INSUFFPRV, Insufficient privilege to perform Batch Queue Management operation

You attempted to perform a queue or job operation for which you lack sufficient access permissions.

CFFD0100 ABAT-E-INITSD, Failure to initialize ABAT Security Descriptor

This is an internal error indicating a failure to create a security descriptor the object. This error may be logged to the product’s trace file.

CFFD015E ABAT-E-ASSOCNOTFND, Failure to determine file association

The Execution Agent was unable to find the job file’s extension to program association. The job was not run.

CFFD015F ABAT-E-CRELOGFILE, Failure to create log file The Execution Agent was unable to create the batch job’s log file. Typically, the log file specification is not valid or proper OR the main job script file specification is also not valid. Please check the log/script file specification and ensure it can be created from the Execution machine.

CFFD0160 ABAT-E-OPENCMDFILE, Failure to open command procedure

The Execution Agent was unable to open the batch job’s script file. Please check the main job’s file specification and ensure it can be opened from the Execution machine.

CFFD0161 ABAT-E-LICENSEXP, license has expired The evaluation serial number has expired. Please contact ASCI or your distributor for an extension.

CFFD019A ABAT-E-JOBSCHEDFAIL, Job Scheduler failed to start

This is the exit status code of a Job Scheduler Service which could not be started. Check the trace file or NT Application Event Log for more information.

CFFD019C ABAT-E-NOTCONNECTED, A connection has not been successfully made to a Job Scheduler

You have attempted to perform an operation that requires a current connection to a Job Scheduler machine. Please make the connection and try again.

CFFD019D ABAT-E-ITEMALREADYEXISTS, The item being added to the collection already exists

This general error indicates that you are attempting to add an object to a collection and the object already exists. For example, trying to add the same account and access to a security collection.

CFFD01A2 ABAT-E-SERVERCOMMUNICATIONERROR, There was an error that occurred while communicating with the server

The client interface encountered an error while communicating with the Job Scheduler.

CFFD01A5 ABAT-E-REQPROPERTYINV, The required property %1!s! is either absent or invalid

Self-explanatory.

CFFD01A7 ABAT-E-COPYFILEERROR, An error occurred while copying the file '%1!s!' to the Job Scheduler because the file cannot be found or there was an error opening/reading the file.

This message can occur if the “Copy File” feature is enabled for a Main, Pre or Post file. As the message indicates an error occurred while attempting to copy the file to the Job Scheduler.

CFFD01A8 ABAT-E-FILESIZEERROR, The file being copied is larger than the system policy allows for

The ActiveBatch Administrator has prevented your file from being copied to the Execution Machine through the System policy CopyScriptMax


430


CFFD01A9 ABAT-E-JOBHISTORYERR, History information for the requested job could not be found

This is an internal error indicating that the Job’s History information could not be retrieved.

CFFD01AE ABAT-E-DEPENDFAIL, dependency failure The Batch Job failed because a job dependency could not be satisfied.

CFFD01B5 ABAT-E-PROPERTYREADONLY, You cannot modify this job because it is set as Read Only

Self-explanatory.

CFFD01C4 ABAT-E-EXCRUNTIME, job aborted exceeding expected run time

The Execution Agent has set this job’s exit status code because of an overrun for elapsed run time and has aborted the job.

CFFD01C5 ABAT-E-EXCCPUTIME, job aborted exceeding expected cpu time

The Execution Agent has set this job’s exit status code because of an overrun for CPU time and has aborted the job.

CFFD01C6 ABAT-E-INVHISTPROP, Job save history duration must be greater or equal to the log file retension period

Self-explanatory.

CFFD01CA ABAT-E-BATCHSTARTERR, unable to launch Batch Start job

A job completed and had a Batch Start (Success or Failure) action associated with it. That action could not be performed. Additional information accompanies this message indicating more specifically what the problem was.

CFFD01D1 ABAT-E-EXECABORT, job aborted due to Execution Agent failure

A job was aborted when an Execution Agent/machine failed. The job was not marked as being restartable.

CFFD01D3 ABAT-E-MAXEAGENTLIC, The maximum number of execution agent licenses has been met

This licensing error indicates that the maximum number of Execution Agent licenses has been reached. Count each Execution Machine you are attempting to connect to (regardless of whether the machine is active or the queue is started) and then compare against the value reported by the ABATLIC program.

CFFD01D4 ABAT-E-MSONLYLIC, This Job Scheduler license only permits connections to Microsoft Execution Agents

You are attempting to connect to a non-Microsoft Execution Agent and your license only permits you to connect to Microsoft Execution Agents.

CFFD01D7 ABAT-E-DUPLICFND, A duplicate license was found. Please ensure that all licenses are valid and unique.

This serious error usually indicates some level of license tampering. Please run the ABATLIC program to obtain more information.

CFFD01DA ABAT-E-LOCALONLYLIC, This Personal Edition license is only permitted to communicate with a single Execution Agent on the Local Machine.

When using the Personal Edition license you are restricted to a Workstation/Professional NT system and all connections are local to that system.

CFFD01DF ABAT-E-UNEXPEXCEPTCOM, An unexpected exception has occurred in the COM client

Self-explanatory.

CFFD01E4 ABAT-E-TAKEOWNERFAIL, attempt to take ownership of specified object failed

Your attempt to take ownership of this object failed. Verify that you have “Executive” level permission.

CFFD01E5 ABAT-E-GETOWNER, unable to obtain object owner

ActiveBatch is unable to retrieve the owner of the object. This error may appear if the domain of the owner’s account is not available.

CFFD01EA ABAT-E-DBPURGEFAIL, An error occurred while running the DBPurge process. Please examine the NT Event Log/DBPurge Log for further details

Self-explanatory. This error message concerns the running of the DBPurge facility to prune unneeded jobs from the ActiveBatch system.

CFFD01EB ABAT-E-AUDPURGEFAIL, Failed to purge Audit ID %1!d!

This DBPurge message can appear in the NT Application Event Log and indicates that DBPurge was unable to remove old audit messages from a specific job.


431


CFFD01EC ABAT-E-INSTSKIPPED, instance skipped due to active instance

This audit message indicates that a job instance could not be executed because the template’s property did not allow multiple concurrent copies of the job to run simultaneously.

CFFD01ED ABAT-E-INSTWAITFAIL, active instance wait failed

This audit message indicates that a job instance could not be executed because the “If Job Active… Wait” property was enabled and the timeout period expired.

CFFD01F9 ABAT-E-WRKSTNONLYLIC, The Personal Edition license is only permitted to run on a Workstation Platform

Self-explanatory.

CFFD01FC ABAT-E-RUNJOBINTERACTIVE, Unable to run the job interactively

An error occurred while attempting to run this job interactively. The error is most likely due to a lack of desktop permissions.

CFFD01FF ABAT-E-INVCALCONFIG, An invalid Calendar configuration was made. Please make sure that all the calendar will allow a job to run at least once

You have attempted to create a job and schedule combination in which the job will never run. For example, scheduling a job on December 25th and then assigning a Calendar with Christmas as a holiday.

Table 31 – ActiveBatch Messages (Numeric)

433

12 INDEX

A

AbatAdmin Connecting ......................................................................... 61 Exiting ................................................................................ 60 Options ............................................................................... 49 Starting ............................................................................... 59 Tools .................................................................................. 47

ABATLIC ............................................................ 418, 420, 430 Absolute Time ...................................................................... 366 ActiveBatch

Architecture ....................................................................... 18 Error Messages .................................................................. 33 Hot Keys ............................................................................ 32 icons ................................................................................... 30 Introduction ........................................................................ 15 Namespace ......................................................................... 19 Objects ............................................................................... 19 User Types ......................................................................... 35

ActiveBatch Admin ......................................................... 26, 59 ActiveBatch Admin Application . 16, 18, 26, 29, 30, 32, 58, 61,

94, 213, 314, 317, 365 ActiveBatch Administrators ............................................. 128 Alert Objects ........................................................................ 261 Architecture ........................................................................... 18

B

Business Day.................................................. 22, 103, 160, 251

C

Calendar Audits ............................................................................... 254 Properties ......................................................................... 252 Security ............................................................................ 255

Calendars ............................................................................. 251 Client .......................... 16, 58, 80, 100, 155, 265, 384, 391, 415 CLOSE/QUEUE .................................................................. 379 Combination Time ............................................................... 368 Completion Trigger .............................................................. 241 Configuration ......................................................................... 44 Connect ...................................................................... 29, 61, 62

Advanced ........................................................................... 62 Firewall .............................................................................. 63

Constraints ..................................................................... 22, 242 Calendar ..................................................................... 22, 250 Date-Time .......................................................................... 22 Day-Time ......................................................................... 249 File ............................................................................. 22, 245 Instance ............................................................................ 244 Job ...................................................................................... 22

Resource .................................................................... 22, 248 Variable ..................................................................... 22, 247

D

Daily Activity ................................................................ 36, 293 Date Arithmetic ................................................................... 349

Administration ................................................................. 353 COM ................................................................................ 359 Commands ....................................................................... 349 Date Substitution ............................................................. 363 Qualifiers ......................................................................... 350 Test .................................................................................. 362

DBPurge ...................................................... 109, 173, 417, 430 Definition Operations

Copy-Paste ....................................................................... 314 Hold ................................................................................. 317 Release ............................................................................. 317 Test Run ........................................................................... 309 Trigger ............................................................................. 311

DELETE/JOB ...................................................................... 380 DELETE/QUEUE ............................................................... 381 Delta Time ........................................................................... 366 Design View ........................................................................ 275

Find Job ........................................................................... 278 Printing ............................................................................ 279 Using ............................................................................... 280

E

E-Mail Properties ................................................................. 140 Error Messages .................................................... 417, 424, 431 Event Triggers ............................................. 156, 236, 423, 426 Exclusion List ...................................................................... 249 ExecAutoRight .................................................................... 128 Execution Agent . 16, 18, 20, 79, 128, 138, 146, 149, 162, 417,

418, 420, 421, 422, 423, 425, 426, 427, 429, 430 Execution Machine ................ 21, 265, 418, 420, 428, 429, 430 Execution Queue ..... 19, 20, 76, 79, 80, 81, 89, 90, 91, 92, 93,

128, 147, 148, 149, 150, 240, 300, 312, 385, 392, 404, 418, 427

Export .................................................................................. 214

F

Failure Batch Start ............................................................... 156 FileSystem Properties .......................................................... 142 FLUSH/QUEUE .................................................................. 382 FTP Properties ..................................................................... 141

G

Gantt Chart .................................................................... 37, 294 Generic Queue ....................................................................... 20


434

Creating .............................................................................. 90 Scheduling Algorithm ................................................ 91, 147

Graphical View .................................................................... 197

H

HOLD .................................................. 383, 384, 388, 390, 408 Holiday ................................................................................ 251 Hot Keys ................................................................................ 32

I

Import .................................................................................. 215 INITIALIZE Queue ............................................................. 384 Instance ................................................................................ 198

Audits ............................................................................... 203 History ............................................................................. 198 Log ................................................................................... 204 MOF Text ........................................................................ 201 Properties ......................................................................... 205 Variables .......................................................................... 200

Instance Operations .............................................................. 305 Change Queue Priority ..................................................... 305 Constraint Status .............................................................. 305 Force Run ......................................................................... 306 Override Completion Status ............................................. 306 Pause ................................................................................ 307 Restart .............................................................................. 307 Resume ............................................................................ 307

Instance View ........................................................................ 41

J

Job .................................................................................... 20, 95 Alerts ................................................ 107, 156, 171, 263, 264 Audits ............................................................................... 176 Central Manage Log File ......................................... 165, 334

Retention ...................................................................... 165 Constraints ....................................................................... 157 Counters ........................................................................... 175 Date/Time Trigger ........................................................... 154

Immediate .................................................................... 154 Interval ................................................................. 154, 243

Date-Time Constraint ....................................................... 159 Defining ........................................................................... 133 Definition ......................................................................... 128 E-Mail .............................................................................. 132 Environment Variables .................................................... 131 Environmental variables .................................................. 139 File Name ......................................................................... 136 FileSystem ....................................................................... 132 FTP .................................................................................. 132 History ..................................................................... 173, 177

Retention ...................................................................... 173 If Job Active ............................................. 104, 162, 419, 431 Interactive ................................................................ 138, 146 Log File ............................................................................ 334 Log File Name ................................................................. 166

Machine Characteristics................................................... 147 Maximum Restarts ........................................................... 173 Monitor CPU Time .......................................................... 169 Monitor Elapsed Time ............................................. 105, 167 OS Priority ....................................................................... 161 Parameters ............... 94, 137, 145, 265, 312, 387, 408, 413 Process ............................................................................. 132 Processor Mask ................................................................ 161 Queue Priority ................................................................. 161 Queue Selection ............................................................... 147 Restart .............................................................................. 172 Revision ........................................................................... 177 Script ............................................................................... 132 Search string .................................................................... 138 Security ............................................................................ 178 States ................................................................................. 75 Submission Queue ........................................................... 161 Success Code Rule ................................................... 138, 146 Terminate all child processes ................................... 138, 146 Types ............................................................................... 132 Variables .......................................................................... 151 Working Directory ........................................................... 161

Job Scheduler 16, 18, 19, 26, 29, 58, 61, 62, 64, 66, 69, 76, 80, 100, 131, 136, 139, 155, 164, 223, 236, 237, 240, 251, 265, 365, 379, 380, 381, 382, 383, 385, 388, 389, 390, 391, 392, 393, 394, 395, 396, 397, 398, 399, 400, 401, 403, 405, 406, 409, 411, 412, 413, 417, 418, 420, 421, 422, 423, 425, 426, 427, 429, 430 Connecting ......................................................................... 61 Disconnecting .................................................................... 64 Licensing ........................................................................... 64 Properties ........................................................................... 66

Job-Plan Operations Abort ................................................................................ 316 Delete ............................................................................... 316 Printing ............................................................................ 318

L

Log View ............................................................................... 29

M

Machine Characteristics ........................................ 81, 148, 149 MODIFY/JOB ............................................................. 386, 390 MODIFY/QUEUE ....................................................... 391, 392

N

Namespace ............................................................................. 19 Navigation Pane ..................................................................... 29 NTMSG ....................................................... 138, 146, 390, 411

O

Object Description ........................................................................ 74 Enabled .............................................................................. 74 ID ....................................................................................... 74

Index

435

Label .................................................................................. 74 Name .................................................................................. 74 Path .................................................................................... 74 State ................................................................................... 74

Objects ......................................................................... 422, 426 Alert ................................................................................... 22 Job ...................................................................................... 20 Job Object ........................................................ 422, 423, 426 Plan .................................................................................... 20 Queue ................................................................................. 19 Reference ........................................................................... 19 Schedule ............................................................................. 21 User Account ..................................................................... 22

OnDemand ........... 19, 20, 93, 94, 265, 299, 311, 312, 423, 426 OPEN/QUEUE .................................................................... 393 OpenVMS ............................................ 138, 139, 146, 390, 411 Options ................................................................................... 49

P

PAUSE ................................................................................. 394 Plan .................................................................................. 20, 95

ActiveBatch Event Trigger .............................................. 101 Alerts ................................................................................ 107 Completion Properties ..................................................... 108 Completion Rule .............................................................. 110 Completion Triggers ........................................................ 112 Constraints ....................................................................... 102 Counters ........................................................................... 113 Date-Time Interval ............................................................. 99 Date-Time Trigger ............................................................. 99

Deferred ......................................................................... 99 Immediate ...................................................................... 99

Definition ........................................................................... 96 Event Trigger ................................................................... 101 History ............................................................................. 115

Retention ...................................................................... 109 Maximum Restarts ........................................................... 109 Restart .............................................................................. 108 Security ............................................................................ 116 Variables ............................................................................ 98

Plan-Job Operations Abort ................................................................................ 212 Copy-Paste ....................................................................... 212 Delete ............................................................................... 212 Hold ................................................................................. 213 Release ............................................................................. 213 Requeue ........................................................................... 308 Show Dependent Objects ................................................. 211

Policies ................................................................................... 44 Product Editions ..................................................................... 16

Personal .................................................... 420, 421, 430, 431 Properties Window .............................................................. 295

Q

Queue ..................................................................................... 19 Alerts .................................................................................. 83

Audits ................................................................................ 85 Counters ............................................................................. 84 Execution

Creating ......................................................................... 76 Job Execution Limit ........................................................... 80 Operating Times ................................................................ 78 Security .............................................................................. 86 States ................................................................................. 74

Queue Operations Close ................................................................................ 302 Delete ............................................................................... 299 Flush ................................................................................ 303 Open ................................................................................ 302 Start ................................................................................. 300 Stop .................................................................................. 300

Queue Priority ..................................................................... 404 Queue Security ................................................................ 86, 87

R

Reference ............................................................................... 19 Reference object .................................................................. 206

Properties ......................................................................... 208 RELEASE ............................................................ 382, 395, 396 Reporting ....................................................................... 45, 335 REQUEUE .......................................................................... 396 Resource

Audits .............................................................................. 259 Properties ......................................................................... 257 Security ............................................................................ 260

Resource Operations Evaluate ........................................................................... 319

Resources ............................................................................. 256 RESTART ........................................... 131, 289, 389, 397, 410 RESUME ............................................................................. 398 Runbook ........................................................................ 38, 297 Runbook View ................................................................. 37, 51

S

Schedule ................................................ 21, 100, 155, 223, 224 Audits .............................................................................. 231 Copying ........................................................................... 234 Day Specification ............................................................ 227 Delete ............................................................................... 234 Edit .................................................................................. 234 Properties ......................................................................... 225 Security ............................................................................ 232 Time Specification ........................................................... 226

Script Properties .................................................................. 145 serial number ............................................................... 420, 429 SET BATCH ............................................... 384, 391, 399, 410 SHOW JOB ................................................................. 401, 402 SHOW QUEUE ........................................................... 403, 404 Slider Notification ................................................................. 46 SMTP ........................................................................... 264, 265 START/QUEUE .................................................................. 405 STOP/QUEUE ..................................................................... 406


436

SUBMIT .............. 365, 384, 388, 391, 399, 400, 407, 408, 411 Submitting a Job .................................................................. 128 Success Code Rule ....................................................... 138, 146 SYNCHRONIZE ................................................................. 412 System View .................................................................. 39, 320

T

Take Ownership ................................................................... 215 Tools ...................................................................................... 47 TRIGGER ............................ 386, 387, 407, 408, 413, 423, 426 Triggers .................................................................................. 21

Events ................................................................................ 21 Schedule ............................................................................. 21

U

User Account Name ............................................................. 269 Audits ............................................................................... 272 Properties ......................................................................... 270 Security ............................................................................ 273

Use ................................................................................... 274 User Characteristics ....................................................... 81, 150 User Types

Administrators ................................................................... 43 Designers ........................................................................... 35

V

Variables ................................................................................ 21 Active .............................................................................. 219 Built-in ............................................................................. 220 Definition ......................................................................... 218 Use ................................................................................... 218

W

WMI ................ 58, 66, 236, 237, 239, 240, 422, 423, 425, 426

X

XLNT .................................................. 138, 146, 365, 402, 404

ActiveBatch V6 Reference Manual · ActiveBatch® Reference Manual 6

Documents

Transcript of ActiveBatch V6 Reference Manual · ActiveBatch® Reference Manual 6