tivoli workload scheduler reference...

Tivoli® Workload SchedulerReference GuideVersion 8.1 SH19-4556-00

Tivoli Workload Scheduler Reference Guide, Version 8.1

Copyright Notice

© Copyright IBM Corporation 1993, 2001. All rights reserved. May only be used pursuant to a Tivoli Systems Software LicenseAgreement, an IBM Software License Agreement, or Addendum for Tivoli Products to IBM Customer or License Agreement. Nopart of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computerlanguage, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without priorwritten permission of IBM Corporation. IBM Corporation grants you limited permission to make hardcopy or other reproductions ofany machine-readable documentation for your own use, provided that each such reproduction shall carry the IBM Corporationcopyright notice. No other rights under copyright are granted without prior written permission of IBM Corporation. The document isnot intended for production and is furnished “as is” without warranty of any kind. All warranties on this document are herebydisclaimed, including the warranties of merchantability and fitness for a particular purpose.

U.S. Government Users Restricted Rights—Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBMCorporation.

Trademarks

IBM, Tivoli, the Tivoli logo, AIX, AS/400, and NetView are trademarks or registered trademarks of International Business MachinesCorporation or Tivoli Systems Inc. in the United States, other countries, or both.

Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in theUnited States and other countries.

Other company, product, and service names may be trademarks or service marks of others.Notices

References in this publication to Tivoli Systems or IBM products, programs, or services do not imply that they will be available inall countries in which Tivoli Systems or IBM operates. Any reference to these products, programs, or services is not intended toimply that only Tivoli Systems or IBM products, programs, or services can be used. Subject to valid intellectual property or otherlegally protectable right of Tivoli Systems or IBM, any functionally equivalent product, program, or service can be used instead ofthe referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, exceptthose expressly designated by Tivoli Systems or IBM, are the responsibility of the user. Tivoli Systems or IBM may have patents orpending patent applications covering subject matter in this document. The furnishing of this document does not give you any licenseto these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive,Armonk, New York 10504-1785, U.S.A.

ISO 9001 Certification

This product was developed using an ISO 9001 certified quality system.

Certification has been awarded by Bureau Veritas Quality International (BVQI) (Certification No. BVQI - 92086 / A).

BVQI is a world leader in quality certification and is currently recognized by more than 20 accreditation bodies.

Contents

Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWho Should Read This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

What This Guide Contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Tivoli Workload Scheduler Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Accessing Publications Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Ordering Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Providing Feedback about Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Contacting Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Conventions Used in This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Typeface Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Operating System-dependent Variables and Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Chapter 1. The Production Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Automating the Production Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Customizing the Final Job Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Adding the final Job Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Starting a Production Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Production Processing Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

The schedulr Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

The compiler Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

The stageman Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

The logman Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

The wmaeutil Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Managing the Production Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Choosing the Workload Scheduler Start of Day . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Changing the Start of Day . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Creating a Plan for Future or Past Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Using Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 2. Composer Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Managing Scheduling Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Workstation Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Workstation Class Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Domain Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Job Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

User Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

iiiTivoli Workload Scheduler Reference Guide

Calendar Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Parameter Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Prompt Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Resource Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

The Composer Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Running Composer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Command Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

continue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

display, list, print. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

new. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

validate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

System Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 3. Scheduling Language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Syntax for Job Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Case Sensitivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Keyword Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

at . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

carryforward . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

confirmed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

end . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

every. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

except . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

follows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

freedays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

iv Version 8.1

||

in order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

job statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

needs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

opens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

until . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Chapter 4. Conman Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Running Conman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Control Characters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Executing System Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

User Prompting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Terminal Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Offline Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Selecting the Conman Command Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Wildcard Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Delimiters and Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

List of Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Selecting Jobs in Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Selecting Job Streams in Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Command Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Conman Command Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

adddep job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

adddep sched. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

altpass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

altpri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

cancel job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

cancel sched . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

vTivoli Workload Scheduler Reference Guide

||

console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

continue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

deldep job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

deldep sched . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

fence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

kill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

limit cpu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

limit sched . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

listsym . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

recall. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

release job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

release sched . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

rerun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

setsym. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

showcpus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

showdomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

showfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

showjobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

showprompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

showresources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

showschedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

shutdown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

start. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

stop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

submit docommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

submit file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

submit job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

submit sched . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

switchmgr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

System Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

tellop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

unlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

vi Version 8.1

version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Chapter 5. Utility Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Command Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

at | batch Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

caxtract Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

cpuinfo Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

datecalc Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

dbexpand Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

delete Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

evtsize Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

jbxtract Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

jobinfo Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

jobstdl Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

maestro Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

makecal Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

morestdl Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

parms Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

paxtract Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

prxtract Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

r11xtr Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

release Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

rextract Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

rmstdlist Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

showexec Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

StartUp Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

version Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

wmaeutil Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

xrxtrct Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Unsupported Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Chapter 6. Report Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Report Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Command Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

rep1 - rep4b Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

rep7 Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

rep8 Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

rep11 Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

reptr Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

xref Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

viiTivoli Workload Scheduler Reference Guide

Chapter 7. Extended Agent Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235What are Extended Agents? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Workstation Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Access Method Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Method Command Line Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Method Response Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Method Options File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Method Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Launch Job (LJ) Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Manage Job (MJ) Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Check File (CF) Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Get Status (GS) Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

The cpuinfo Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Job Standard List Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Method Not Executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Console Manager Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Composer and Compiler Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Jobman Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Chapter 8. Network Agent Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Configuring a Network Agent Workstation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Network Agent Command Line Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Options File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Internetwork Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Creating an Internetwork Dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Internetwork Dependencies and Conman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Chapter 9. Integration with Other Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Integration with NetView. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

General Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Installing the Integration Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Setting Up. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Objects, Symbols, and Submaps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Menu Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Tivoli Workload Scheduler/NetView Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Tivoli Workload Scheduler/NetView Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Tivoli Workload Scheduler/NetView Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . 267

viii Version 8.1

||

||

||

||

||

||

||

||

||

Unison Software MIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Tivoli Workload Scheduler/NetView Program Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Integration with Tivoli Business Systems Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

General Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Using the Key Flag Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Installing the Common Listener Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Customizing the Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Starting and Stopping the Common Listener Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Workload Scheduler/Tivoli Business Systems Manager Events . . . . . . . . . . . . . . . . . . . . . . . . 279

Appendix A. Maintaining Tivoli Workload Scheduler . . . . . . . . . . . . . . . . . . . 281Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Defragmenting Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Backing Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Maintaining the File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

File Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Temporary Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Appendix B. Time Zone Names and Descriptions. . . . . . . . . . . . . . . . . . . . . . . 285

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

ixTivoli Workload Scheduler Reference Guide

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

x Version 8.1

Preface

Tivoli Workload Scheduler simplifies systems management across distributed environmentsby integrating systems management functions. Workload Scheduler plans, automates, andcontrols the processing of your enterprise’s entire production workload. The Tivoli WorkloadScheduler Reference Guide provides detailed information about the command line interface,scheduling language, and utility commands for Tivoli Workload Scheduler.

Who Should Read This GuideThis guide is intended for adminstrators and advanced users of Tivoli Workload Scheduler.

What This Guide ContainsThis guide contains the following sections:

¶ Chapter 1, “The Production Cycle” on page 1

Describes the procedures and commands used in the Workload Scheduler productioncycle.

¶ Chapter 2, “Composer Reference” on page 17

Describes the composer command line interface. This is used to create schedulingobjects in the Workload Scheduler database.

¶ Chapter 3, “Scheduling Language” on page 59

Describes the scheduling language used to define jobs and job streams in the WorkloadScheduler database.

¶ Chapter 4, “Conman Reference” on page 89

Describes the conman command line interface. This is used to monitor and manage jobexecution during the production day.

¶ Chapter 5, “Utility Commands” on page 179

Describes the Tivoli Workload Scheduler utility commands. These commands are used tomanage the Workload Scheduler environment.

¶ Chapter 6, “Report Commands” on page 225

Describes how to print different types of report in Workload Scheduler.

¶ Chapter 7, “Extended Agent Reference” on page 235

Provides a programmers’ reference for creating extended agents.

¶ Chapter 8, “Network Agent Reference” on page 245

Describes how to create and use a network agent workstation.

¶ Chapter 9, “Integration with Other Products” on page 253

Describes how Workload Scheduler works with NetView® and Tivoli Business SystemsManager.

¶ Appendix A, “Maintaining Tivoli Workload Scheduler” on page 281

Discusses how to keep Workload Scheduler running with optimal performance.

¶ Appendix B, “Time Zone Names and Descriptions” on page 285

Lists the time zones supported by Workload Scheduler.

xiTivoli Workload Scheduler Reference Guide

Publications

This section lists publications in the Tivoli Workload Scheduler library and any other relateddocuments. It also describes how to access Tivoli publications online, how to order Tivolipublications, and how to make comments on Tivoli publications.

Tivoli Workload Scheduler LibraryThe following documents are available in the Tivoli Workload Scheduler library:

Table 1. List of Publications for Tivoli Workload SchedulerTask Publication Order number

Installing a Workload Schedulernetwork

Tivoli Workload Scheduler Planningand Installation

SH19-4555

Using the command line interface,scheduling language, and utilitycommands

Tivoli Workload Scheduler ReferenceGuide

SH19-4556

Installing and configuring limitedfault-tolerant agents on AS/400®

Tivoli Workload Scheduler LimitedFault-Tolerant Agent for AS/400 User’sGuide

SH19-4558

Setting up and using the Plusmodule

Tivoli Workload Scheduler Plus ModuleUser’s Guide

SH19-4562

Interpreting messages Tivoli Workload Scheduler ErrorMessages

SH19-4557

Using the Java™-based graphicaluser interface

Tivoli Workload Scheduler JobScheduling Console User’s Guide

SH19-4552

Accessing Publications OnlineYou can access many Tivoli publications online using the Tivoli Information Center, whichis available on the Tivoli Customer Support Web site:

http://www.tivoli.com/support/documents/

These publications are available in PDF or HTML format, or both. Translated documents arealso available for some products.

Ordering PublicationsYou can order many Tivoli publications online at the following Web site:

http://www.ibm.com/shop/publications/order

You can also order by telephone by calling one of these numbers:

¶ In the United States: 800-879-2755

¶ In Canada: 800-426-4968

¶ In other countries, for a list of telephone numbers, see the following Web site:

http://www.tivoli.com/inside/store/lit_order.html

xii Version 8.1

http://www.tivoli.com/support/documents/

http://www.ibm.com/shop/publications/order

http://www.tivoli.com/inside/store/lit_order.html

Providing Feedback about PublicationsWe are very interested in hearing about your experience with Tivoli products anddocumentation, and we welcome your suggestions for improvements. If you have commentsor suggestions about our products and documentation, contact us in one of the followingways:

¶ Send an e-mail to [email protected].

¶ Complete our customer feedback survey at the following Web site:

http://www.tivoli.com/support/survey/

Contacting Customer SupportIf you have a problem with any Tivoli product, you can contact Tivoli Customer Support.See the Tivoli Customer Support Handbook at the following Web site:

http://www.tivoli.com/support/handbook/

The handbook provides information about how to contact Tivoli Customer Support,depending on the severity of your problem, and the following information:

¶ Registration and eligibility

¶ Telephone numbers and e-mail addresses, depending on the country you are in

¶ What information you should gather before contacting support

Conventions Used in This GuideThis book uses several conventions for special terms and actions, operatingsystem-dependent commands and paths, and margin graphics.

Typeface ConventionsThe following typeface conventions are used in this book:

Bold Lowercase and mixed-case commands, command options, and flags thatappear within text appear like this, in bold type.

Graphical user interface elements (except for titles of windows and dialogs)and names of keys also appear like this, in bold type.

Italic Variables, values you must provide, new terms, and words and phrases thatare emphasized appear like this, in italic type.

Monospace Commands, command options, and flags that appear on a separate line, codeexamples, output, and message text appear like this, in monospace type.

Names of files and directories, text strings you must type, when they appearwithin text, names of Java methods and classes, and HTML and XML tagsalso appear like this, in monospace type.

Operating System-dependent Variables and PathsThis book uses the UNIX® convention for specifying environment variables and fordirectory notation.

xiiiTivoli Workload Scheduler Reference Guide

http://www.tivoli.com/support/survey/

http://www.tivoli.com/support/handbook/

When using the Microsoft® Windows® command line, replace $variable with %variable%for environment variables and replace each forward slash (/) with a backslash (\) in directorypaths.

Note: If you are using the bash shell on a Windows system, you can use the UNIXconventions.

xiv Version 8.1

The Production Cycle

The Tivoli Workload Scheduler processing day begins at the time defined by the start globaloption, which is set, by default. to 6:00 a.m. To turn over a new day, pre-production set upis performed for the upcoming day, and post-production logging and reporting is performedfor the day just ended. This chapter describes the procedures and commands you use toperform these tasks. For information about the start options, refer to the Tivoli WorkloadScheduler Planning and Installation Guide.

Automating the Production CyclePre-production and post-production processing can be automated fully by adding theTivoli-supplied final job stream, or a user-supplied equivalent, to the scheduler database,together with other job streams. A copy of the Tivoli-supplied job stream is in theTWShome/config/Sfinal directory. A copy of the job script is in the TWShome/Jnextdaydirectory. You might find it useful to print copies to help you understand the turnoverprocess.

The final job stream is placed in production every day, and results in running a job namedJnextday prior to the start of a new day. The job performs the following tasks:

1. Execute the schedulr command to select job streams for the new day’s production plan.For more information, see 3.

2. Execute the compiler command to compile the production plan. For more information,see “The compiler Command” on page 5.

3. Execute the reptr command to print pre-production reports. For more information, see“reptr Command” on page 231.

4. Stop the scheduler.

5. Execute the stageman command to carry forward uncompleted job streams, log the oldproduction plan, and install the new plan. For more information, see “The stagemanCommand” on page 7.

6. Run the wmdeutil.sh command to stop all mapper servers so that they all open a newsymphony. For more information, see “The wmaeutil Command” on page 12.

7. Start the scheduler for the new day.

8. Execute the reptr command to print post-production reports for the previous day. Formore information, see “reptr Command” on page 231.

9. Execute the logman command to log job statistics for the previous day. For moreinformation, see “The logman Command” on page 10.

1

1Tivoli Workload Scheduler Reference Guide

1.T

he

Pro

du

ction

Cycle

In the Tivoli Workload Scheduler manual set, the terms final and Jnextday are used whenreferring to both the Tivoli-supplied versions, and any user-supplied equivalents.

Customizing the Final Job StreamBefore using the final job stream, it can be modified to meet your needs, or you can createa different job stream to use in its place.

When creating your own job stream, model it after the one supplied by Tivoli. If you chooseto do so, consider the following:

¶ If you choose to change the way stageman generates log file names, remember thatreptr and logman must use the same names.

¶ If you would like to print the pre-production reports in advance of a new day, you cansplit the Jnextday job into two jobs. The first job will execute schedulr, compiler andreptr. The second job will stop the scheduler, execute stageman, start the scheduler, andexecute reptr and logman. The first job can then be scheduled to run at any time priorto the end of day, while the second job is scheduled to run just prior to the end of day.

Adding the final Job StreamIf you performed the quick start procedure in the Tivoli Workload Scheduler InstallationGuide, the final job stream is already added to the database. If not, follow these steps to addthe final job stream, or a user-supplied equivalent.

1. Log in as the maestro user on the master domain manager.

2. At a command prompt, execute the following command on UNIX:composer “add Sfinal”

or the following command on Windows NT®:composer “add Sfinal”

To add your own job stream, use its name in place of Sfinal.

Starting a Production CycleIf it has not been started before follow these steps:

1. Log in as the maestro user on the master domain manager.

2. At a command prompt, execute the Jnextday job by entering the following command:Jnextday

This will perform pre-production processing and start the scheduler production processes.

Production Processing CommandsThe pre and post-production processing commands executed by the Jnextday job aredescribed on the pages that follow.

2 Version 8.1

The schedulr Command

The schedulr command selects job streams for a specific date from the database filemastsked, and copies them to a new production schedule file named prodsked.

You must have build access to the scheduler database files.

Synopsisschedulr -v|-u

schedulr [-date date|-autodate] [-scheds {in-file|-}] [-prodsked {out-file|-}]

Arguments-u Display the command version and exit.

-v Display command usage information and exit.

-date Select job streams for a specific date. The date is entered as mm/dd/[yy]yy.

-autodateSelect job streams for the current system date.

-schedsIn addition to those selected by -date or -autodate, if any, select the job streamsnamed in in-file. The names must appear in the file as [workstation#]jobstream, withone name per line. If a dash is entered instead of a file name, schedulr prompts forjob stream names at stdin.

-prodskedDirect schedulr output to out-file. If a dash is entered instead of a file name, theoutput is directed to stdout. If the argument is omitted, the output is written to a filenamed prodsked.

DescriptionIf -autodate, and -date are omitted, schedulr prompts for a date. If you respond to theprompt by pressing Return, job streams are selected only from the in-file.

ExamplesSelect job streams for today’s date, plus the job streams named in the file myskeds:schedulr -autodate -scheds myskeds

Select job streams for February 15, 1999, do not prompt for extra job stream names, andwrite the output to the file myprodsked:schedulr -date 2/15/90 -prodsked myprodsked

Select job streams for February 15, 1999, and prompt for extra job streams:schedulr -date 2/15/1999 -scheds -

Prompt for the production date, and extra job streams (note that “schedule” is the same as“job stream”):schedulrEnter schedule date: 4/14/99Enter a list of extra schedules


1.T

he

Pro

du

ction

Cycle

Schedule name: site1#sked2Schedule name: <Return><list of job streams selected>End of Program

4 Version 8.1

The compiler Command

The compiler command compiles the production schedule file, and creates an interimproduction plan file.

Synopsiscompiler -v|-u

compiler [-date date] [-input in-file] [-output out-file]



-date The production date to be recorded in the interim production plan file. The date isentered as mm/dd/[yy]yy.

-input The name of the file containing the production schedule. If this option is omitted,the default name is prodsked.

-outputDirect compiler output to out-file. If the argument is omitted, the output is written toa file named Symnew.

DescriptionIf you omit the -date argument, Symnew is given the same date as that recorded in theproduction schedule file created by schedulr. If there is no date in production schedule file,the current system date is used. The date in Symnew is the date that the scheduler willbegin executing the production plan. The ability to enter a different date can be used to setup processing for past or future dates.

Missing Object MessagesThe following messages are produced by compiler to indicate missing scheduling objects.The messages are normally found in the standard list file for the Jnextday job.job. 5 ... Undefined parameter in "schedule"; not replaced.

A parameter called for in a job stream does not exist in the scheduler database. Nosubstitution occurs and the parameter string itself is used.102 ... Job name is not found in database. Added a dummy job in FAIL state.

A job named in a job stream does not exist in the scheduler database. A dummy job of thesame name is placed in the production schedule with a priority of zero and a state of FAIL.103 ... Prompt name not found. Added prompt name in Symphony.

A prompt named in a job stream does not exist in the scheduler database. A dummy promptcontaining the following text is used instead: Prompt name was not found in database. Thisis dummy text. Do you want to continue (Y/N).104 ... Resource name for cpu name not found in database. Added resource name with 0 units.

A resource named in a job stream does not exist in the scheduler database. A dummyresource with zero available units is used instead:106 ... Cpu name does not exist in cpu database. Ignoring schedule name.


1.T

he

Pro

du

ction

Cycle

A job stream is defined to run on a cpu that does not exist. The job stream is ignored andnot placed in the production schedule.

ExamplesCompile prodsked into Symnew:compiler

Compile prodsked into Symnew, and enter a production date of May 15, 1999:compiler -date 5/15/99

Compile the file mysked into a file named mysym:compiler -input mysked -output mysym

6 Version 8.1

The stageman Command

The stageman command carries forward uncompleted job streams, logs the old productionplan, and installs the new production plan. The new production plan file is namedSymphony. A copy of Symphony, named Sinfonia, is also created. Sinfonia is sent todomain managers and agents as part of the initialization process for the new day.

You must have build access to the Symphony file.

Synopsisstageman -v|-u

stageman [-carryforward {yes|no|all}] [-log log-file|-nolog] [symnew]



-carryforwardDefine the type of carry forward as follows:

no Do not carry forward any job streams.

yes Carry forward only those uncompleted job streams that are Carry Forwardenabled.

all Ignore Carry Forward enabling in job streams, and carry forward alluncompleted job streams.

-log Log the old production plan, and give the log file this name. See “Log File Names”on page 8 for more information.

-nolog Do not log the old production plan.

symnewThe name of the interim production plan file created by compiler. If omitted, thefile Symnew is used.

DescriptionIf you omit -carryforward, the default for carry forward is determined by the carryforwardglobal option.

On UNIX only, stageman also determines which executable files can be deleted for jobssubmitted with the at and batch commands. These are jobs that were not carried forward.The files are actually deleted when the scheduler starts up for the new day.

If scheduler processes are still running and accessing the Symphony file, stageman displaysthe message:Unable to get exclusive access to Symphony.Shutdown batchman and mailman.

To continue, stop the scheduler and rerun stageman. If stageman aborts for any reason, youmust rerun both compiler and stageman.


1.T

he

Pro

du

ction

Cycle

Users accessing the plan through the CLI during the time Symphony is being switched aresent the message:Current Symphony file is old. Switching to new Symphony.Schedule mm/dd/yy (nnnn) on cpu, Symphony switched.

Some user commands executed during the switch may not execute properly because thetarget jobs or job streams were not carried forward.

Log File NamesProduction plan log files are stored in the TWShome/schedlog directory. The default namingconvention used by stageman, when the -log and -nolog arguments are omitted, is asfollows:TWShome/schedlog/Myyyymmddhhtt

where yyyymmddhhtt is the year, month, day, hour, and minute the log file was created.

The above naming convention is coded in the Jnextday script supplied by Tivoli. If youwish, you can change the naming convention when you automate the production cycle. Formore information see “Automating the Production Cycle” on page 1.

Note: Be sure to monitor the disc space in the schedlog directory and remove older logfiles on a regular basis.

Job Streams Carried ForwardThe carry forward option remains enabled on job streams that are carried forward, so theymay be carried forward again. If an unsuccessful job stream is carried forward and itcontinues to terminate in a state other than SUCC, it may be carried forward indefinitelyunless its Until time expires or it is cancelled.

Carried forward job streams maintain their original production date internally. Any jobwithin these job streams that utilizes datecalc will use this production date when using the″scheddate″ keyword.

For carry forward to work properly in a network, the master domain manager’s productionplan file, Symphony, must be updated with the latest job stream status from its agents andsubordinate domain managers. This can be accomplished by entering the following at acommand prompt on the master domain manager prior to executing stageman:conman "link @"

Job Stream NamesJob streams that are carried forward are renamed as follows. If the global option expandedversion is set to no the new name is:

CFyjjjnn

where y is the last digit of the year, jjj is the Julian date, and nn is a sequence number(00-99, AA-ZZ).

If the global option expanded version is set to yes the new name is:

CFyjjjnnxxxxxxxxx

8 Version 8.1

|||

where y is the last digit of the year, jjj is the Julian date, nn is a sequence number (00-99,AA-ZZ), and xxxxxxxxx is a random alpha string.

For information about the global option expanded version, see the chapter explaining globaloptions in the Tivoli Workload Scheduler Planning and Installation Guide.

Carry Forward PromptsTo retain continuity when carrying job streams forward, stageman creates special prompts inthe new production plan to account for disconnected Follows dependencies. These promptsare issued after the new processing day begins, when the scheduler checks to see if the jobor job stream is ready to launch, and are replied to as standard prompts. The following is anexample of a Carry Forward prompt:INACT 12 (SYS1#CF9123AA) follows SYS1#SKED3 satisfied?

This prompt indicates that a job stream from the previous day was carried forward asCF9123AA, and that it follows a job stream named sked3 which was not carried forward.The state of the prompt– INACT in this case– defines the state of the corresponding Followsdependency. The possible states are:

INACTThe prompt has not been issued and the dependency is not satisfied.

ASKEDThe prompt has been issued, and is awaiting a reply. The dependency is notsatisfied.

NO Either a ″no″ reply was received, or it was determined before Carry Forwardoccurred that the followed job stream (sked3) had not completed successfully. Thedependency is not satisfied.

YES Either a ″yes″ reply was received, or it was determined before Carry Forwardoccurred that the followed job stream (sked3) had completed successfully. Thedependency is satisfied.

ExamplesCarry forward all uncompleted job streams (regardless of the status of the Carry Forwardoption), log the old Symphony file, and create the new Symphony file:DATE=vdatecalc today pic YYYYMMDDHHTTvstageman -carryforward all -log schedlog/M$DATE

Carry forward uncompleted job streams as defined by the carryforward Global Option, donot log the old Symphony file, and create a new production control file named mysym:stageman -nolog mysym


1.T

he

Pro

du

ction

Cycle

The logman Command

The logman command log job statistics from a production plan log file.

Synopsislogman -v|-u

logman [-smooth percent] [-minmax {elapsed|cpu}] log-file



-smoothUse a weighting factor that favors the most recent job run when calculating thenormal (average) run time for a job. This is expressed as a percentage. For example,-smooth 40 will apply a weighting factor of 40% to the most recent job run, and60% to the existing average. The default is zero.

-minmaxDefine how the minimum and maximum job run times are logged and reported.

elapsedBase the minimum and maximum run times on elapsed time.

cpu Base the minimum and maximum run times on cpu time.

log-fileThe name of the production plan file or log file from which job statistics areextracted.

DescriptionJobs that have already been logged, cannot be logged again. Attempting to do so generates a0 jobs logged error message.

Elapsed Time Compared to CPU TimeElapsed time, expressed in minutes, is greatly affected by system activity. It includes boththe amount of time a job made use of the CPU and the intervals the job had to wait forother processes to release the CPU. In periods of high system activity, for example, a jobmay have a long elapsed time, and yet use no more CPU time than in periods of low systemactivity. On the other hand, CPU time, expressed in seconds, is a measure of the actual timea job made use of the CPU, and does not include the intervals when the job was waiting.

If you run logman with the -minmax elapsed argument, the maximum and minimum runtimes and dates are based solely on a job’s elapsed time. The values are updated only if thelatest job run has an elapsed time greater than the existing maximum, or less than theexisting minimum. The CPU times, in this case, will not necessarily indicate their maximumand minimum extremes.

If you run logman with the -minmax CPU argument, the maximum and minimum run timesand dates are based solely on a job’s CPU time. The values are updated only if the latest jobrun has a CPU time greater than the existing maximum, or less than the existing minimum.The elapsed times, in this case, will not necessarily indicate their maximum and minimumextremes.

10 Version 8.1

If you run logman without the -minmax argument, the elapsed time and CPU time valuesare updated independently to indicate their maximum and minimum extremes, but the rundates correspond only to the elapsed time values. No record is kept, in this case, of the rundates for maximum and minimum CPU times.

ExamplesLog job statistics from the log file M199903170935:logman schedlog/M199903170935

Log job statistics from the log file M$DATE based on elapsed time, giving the most recentjob runs a weight of 40% when calculating normal (average) run times:logman -smooth 40 -minmax elapsed schedlog/M$DATE

The $DATE variable contains the date and time stamp used by stageman to create the logfile name. See “The stageman Command” on page 7 for more information.


1.T

he

Pro

du

ction

Cycle

The wmaeutil Command

Used to stop the connector server for the plan, database, and engine. The makesec commandwill not run successfully on Windows NT until the connectors are stopped.

Note: If you recreate a plan file manually (not using Jnextday), you must stop theconnectors by running the wmaeutil command and then refresh the views in the JobScheduling Console to view the new production day. Otherwise, the views in the JobScheduling Console will remain on the prior production day.

Synopsiswmaeutil instance_name [-stop DB | PL | EG | *] [-version DB | PL | EG | *] [-dbinfoDB | PL | *] [-sethome] [-gethome] [ALL -stop]

Argumentsinstance_name

The name of the scheduler instance. This refers to the instance name you enteredduring installation of the scheduler engine, and the installation of the connector.

-stop DB | PL | EG | *This option can be used to shut down specified connector server. The (*) asteriskcan be used to shut down all three connector server.

-version DB | PL | EG | *This option is used to obtain the version number of the connector server for theplan, database, engine and installed on the system. The (*) asterisk can be used toobtain versions for all three connector server at once.

-dbinfo DB | PL | *This option is used to find out if the scheduler database and plan to which thisconnector is linked is expanded or unexpanded. The (*) asterisk can be used toobtain versions for both database and plan.

-sethomeThis option is used to set MaestroHomeDir attribute of the scheduler objects(Engine, Database, and Plan) in Tivoli’s object database. This attribute value linksconnectors for the specified object instance to the core scheduler product. It takesthe fully qualified name of the scheduler home directory as an argument. Also thepathname string should be enclosed in quotes to prevent any shell interpretation.

-gethomeThis option does not require any arguments and it prints the value ofMaestroHomeDir attribute for the Engine, Database, and Plan object instances as setin the object database.

ALL -stopThis option stops the connector servers for all scheduler connector instancesconnected to the current scheduler installation, that is, it stops the connector serversfor all instances whose MaestroHomeDir attribute matches the home directory of thescheduler current installation.

12 Version 8.1

Usage Notes

Set Environment VariablesBefore wmaeutil can be run successfully, you must execute following file in order to setframework environment.

On Windows NT:c: \> %SystemRoot%\system32\drivers\etc\Tivoli\setup_env.cmd

For UNIX:$. /etc/Tivoli/setup_env.sh

You can update your UNIX profile to run this file, in order to avoid having to run thecommand manually.

Makesec ConsiderationsThe wmaeutil command must be run before running the makesec command. The makeseccommand will not run successfully on Windows NT until the connectors are stopped. Youshould also stop the connectors when using the makesec command on UNIX.

Workload Scheduler Instance NameIf you are not sure of the instance name that was entered at installation, perform thefollowing steps:

1. Source the Tivoli environment variables:. /etc/Tivoli/setup_env.sh (for UNIX)

C:\winnt\system32\drivers\etc\Tivoli\setup_env.cmd (for NT)

2. Run the wlookup command to get the scheduler instance name:wlookup -ar MaestroEngine

maestro2 1697429415.1.596#Maestro::Engine#

where maestro2 is the scheduler instance name.

ExamplesStop the connectors for the database, plan, and engine for an instance called maestro:wmaeutil maestro -stop *

Stop the connectors for the database for an instance called tws:wmaeutil tws -stop DB

Stop the connector versions for the database, plan and engine for an instance calledmaestro2:wmaeutil maestro2 -version *

Managing the Production EnvironmentThis section provides information on changing the start of day for Workload Scheduler andcreating a plan to process future or past days processing.

Choosing the Workload Scheduler Start of DayThere are three common options for the start of the production day.

¶ early morning


1.T

he

Pro

du

ction

Cycle

¶ late afternoon

¶ midnight

These are a few of the scheduling implications:

Start and Deadline Times

Start times (at keyword) specified are always in relationship to the scheduler production daystart time. You may need to add “+ 1 day” to job streams whose jobs process acrossproduction days. Also be certain that the deadline (until keyword) time comes after the starttime.

On keyword

Production and calendar days may not be the same. If your production day starts at 06:00a.m. (the default setting), 05:59 a.m. will be the last minute of the production day. A JobStream defined to run ON MONDAY at 05:30 will be selected on Monday and will run onthe calendar day Tuesday at 5:30 a.m.

Carryforward keyword

Placing the start of day near midnight to correspond with the calendar day will tend toproduce a large number of carried forward Job Streams. This may increase the complexity ofmanaging the data center.

Changing the Start of DayThe start of day for Workload Scheduler is when the final Job Stream is run and thescheduler processes are stopped and restarted. To specify the start of day for the scheduler:

1. Modify the start option in the globalopts file. This is the start time of the processingday in 24 hour format: hhmm (0000-2359). The default start time is 6:00 A.M.

2. Modify the start time (at keyword) of the final job stream to run one minute before theend of day.

Creating a Plan for Future or Past DatesYou can create a plan that executes processing normally scheduled for a future or past dayof processing. This procedure effectively recreates any specified day of processing. You mayneed to use this procedure if you lost a day of processing due to an emergency.

1. Unlink and stop all workstations in your scheduler network. This stops all processing inthe network.

2. Run the schedulr command with the date option to create a prodsked file:schedulr -date ddmmyyyy

With the date option you can specify to create a plan based on a future or past day ofprocessing.

3. Run the compiler command to create a Symnew file:compiler (-date ddmmyyyy)

14 Version 8.1

You can use the date option with the compiler to specify today’s date or the date of theday you are trying to recreate. This option may necessary if you have job streams thatcontain date sensitive input parameters. The scheddate parameter is keyed off the datespecified with the compiler command.

4. Run console manager to stop scheduler processes:conman stop @!@

5. Run stageman to create the new Symphony file:stageman

6. Run console manager to start scheduler processes:conman start

Using ReportsUse reports to help you manage the production cycle. For more information, see “ReportCommands” on page 225 and “reptr Command” on page 231.


1.T

he

Pro

du

ction

Cycle

16 Version 8.1

Composer Reference

The Composer program is used to manage scheduling objects in the Workload Schedulerdatabase. Scheduling objects are workstations, workstation classes, domains, jobs, jobstreams, resources, prompts, calendars, and parameters. This chapter describes the Composercommand syntax and the syntax used to define scheduling objects.

Managing Scheduling ObjectsScheduling objects are managed with the Composer program and are stored in the schedulerdatabase. To add a new object, you enter its definition in an edit file, which is checked forcorrect syntax before it is added to the database.

You can access the database entries for job streams, jobs, users, workstations, domains, andworkstation classes and manage them individually. For example, to modify an existing jobdefinition, the definition is copied from the database into an edit file, you modify the editfile, the edit file is checked for correct syntax, and the modified definition is copied backinto the database, replacing the existing definition.

You manage the database entries for calendars, parameters, prompts, and resources ascomplete lists. For example, to modify an existing resource, the entire resource list is copiedfrom the database into an edit file, you modify the edit file, the edit file is checked forcorrect syntax, and the new list is copied back into the database, replacing the existingresource list.

2


2.C

om

po

serR

eference

Workstation Definitions

A workstation is a scheduling object that runs jobs. You can include multiple workstationdefinitions in the same text file, along with workstation class definitions and domaindefinitions.

Synopsis#[ comment]cpuname wkstation [description ″text″]os os-typenode hostname [tcpaddr port][timezone|tz tzname][domain domainname][for maestro [host host-wkstation [access method]]

[type fta | s-agent | x-agent][ignore][autolink on | off][fullstatus on | off][resolvedep on | off][server serverid]]

end

[cpuname ...]

[cpuclass ...]

[domain ...]

Arguments# comment

Specifies to treat everything from the pound sign to the end of the line as acomment.

cpuname wkstationSpecifies the name of the workstation. The name must start with a letter, and cancontain alphanumeric characters, dashes and underscores. For non-expandeddatabases, it can contain up to eight characters. For expanded databases, it cancontain up to 16 characters.

Note: Workstation names must be unique, and cannot be the same as workstationclass and domain names.

description “text”Provides a description of the workstation. Your text must be enclosed in doublequotes.

os os-typeSpecifies the operating system of the workstation. Valid include MPEV, MPIX,UNIX, WNT, and OTHER.

node hostnameSpecifies the host name or the IP address of the workstation. Fully-qualified domainnames are accepted.

18 Version 8.1

tcpaddr portSpecifies the TCP port number that the scheduler uses for communications on theworkstation. The default is 31111.

timezone|tz tznameSpecifies the time zone of the workstation. See “Time Zone Names andDescriptions” on page 285 for valid time zone names. To ensure the accuracy ofscheduling times, this time zone must be the same as the computer’s operatingsystem time zone.

domain domainnameSpecifies the name of the scheduler domain of the workstation. The default forfault-tolerant and standard agents is the master domain, usually namedMASTERDM. The default for a domain manager is the domain in which it isdefined as the manager. The default for an extended agent is the domain of its hostworkstation.

host host-wkstationSpecifies the name of the agent’s host workstation. This is required for extendedagents. The host is the workstation with which the extended agent communicates andwhere its access method resides. Note that the host cannot be another extendedagent.

access methodSpecifies an access method for extended and network agents. This must be the nameof a file that resides in the TWShome/methods directory on the agent’s hostworkstation.

type Specifies the type of workstation. Enter one of the following:

fta Fault-tolerant agent, including domain managers and backup domainmanagers.

s-agentStandard agent.

x-agentExtended agent.

ignore Specifies that the scheduler will ignore this workstation definition.

autolinkSpecifies whether to open the link between workstations at startup. For fault-tolerantand standard agents, enter on to have the domain manager open the link to the agentwhen the domain manager is started. For the domain manager, enter on to have itsagents open links to the domain manager when they are started.

Autolink is useful primarily during the startup sequence at the beginning of eachday. At that time, a new production plan is created and compiled on the masterdomain manager, and all workstations are stopped and restarted. For each agent withautolink turned on, the domain manager automatically sends a copy of the newproduction plan and starts the agent. If autolink is also turned on for the domainmanager, the agent, in turn, opens a link back to the domain manager. If the value ofautolink is off for an agent, it is initialized when you execute a Conman linkcommand on the agent’s domain manager or the master domain manager.

fullstatusSpecifies whether the agent is updated with full or partial status. This is for


2.C

om

po

serR

eference

fault-tolerant agents only. Enter on to have the agent operate in Full Status mode. Inthis mode, the agent is updated about the status of jobs and job streams running onall other workstations in its domain but not in subordinate domains.

If the value of fullstatus is off, the agent is informed only about the status of jobsand job streams on other workstations that affect its own jobs and job streams. Thiscan improve performance by reducing network activity.

To keep an agent’s production plan at the same level of detail as its domainmanager, set fullstatus and resolvedep to on. Always set these modes on for backupdomain managers.

resolvedepSpecifies whether an agent will track all dependencies or only its own. This is forfault-tolerant agents only. Enter on to have the agent operate in Resolve AllDependencies mode. In this mode, the agent tracks dependencies for all jobs andjob streams, including those running on other workstations. Note that the value offullstatus must also be on so that the agent is informed about activity on otherworkstations. If the value of resolvedep is off, the agent tracks dependencies for itsown jobs and job streams only. This reduces processing overhead.

To keep an agent’s production plan at the same level of detail as its domainmanager, set fullstatus and resolvedep to on. Always set these modes on for backupdomain managers.

server serveridSpecifies a Mailman server on the domain manager to handle communications withthe agent. This is for fault-tolerant and standard agents only. Do not use this optionfor domain managers. Using servers can reduce the time required to initialize agentsand improve the timeliness of messages.

The ID is a single letter or a number (A-Z and 0-9). The IDs are unique to eachdomain manager, so you can use the same IDs in other domains without conflict. Ifmore than 36 server IDs are required in a domain, consider dividing it into two ormore domains.

If a server ID is not specified, communications with the agent are handled by themain Mailman process on the domain manager.

When it starts up, the domain manager creates a separate server for each uniqueserver ID. If the same ID is used for multiple agents, a single server is created tohandle their communications. As a guide, extra servers should be defined to preventa single server from handling more than eight agents.

ExamplesThe following creates a master domain manager named hdq-1, and a fault-tolerant agentnamed hdq-2 in the master domain. Note that a domain argument is optional in thisexample, because the master domain defaults to masterdm.cpuname hdq-1 description “Headquarters master DM”

os unixtz pstnode sultan.unison.comdomain masterdmfor maestro type fta

autolink onfullstatus onresolvedep on

end

20 Version 8.1

|||

cpuname hdq-2os wnttz pstnode opera.unison.comdomain masterdmfor maestro type fta

autolink onend

The following example creates a domain named distr-a with a domain manager nameddistr-a1 and a standard agent named distr-a2:domain distr-a

manager distr-a1parent masterdm

end

cpuname distr-a1 description “District A domain mgr”os wnttz estnode pewter.unison.comdomain distr-afor maestro type fta

autolink onfullstatus onresolvedep on

end

cpuname distr-a2os wntnode quatro.unison.comtz estdomain distr-afor maestro type s-agent

host distr-a1end


2.C

om

po

serR

eference

Workstation Class Definitions

A workstation class is a group of workstations for which common job streams can bewritten. You can include multiple workstation class definitions in the same text file, alongwith workstation definitions and domain definitions.

Synopsis# commentcpuclass wkstationclass

members {wkstation | @} [...]end

[cpuname ...]

[cpuclass ...]

[domain ...]

Arguments# comment


cpuclass wkstationclassSpecifies the name of the workstation class. The name must start with a letter, andcan contain alphanumeric characters, dashes and underscores. For non-expandeddatabases, it can contain up to eight characters. For expanded databases, it cancontain up to 16 characters.

Note: You cannot use the same names for workstations, workstation classes, anddomains.

members wkstationSpecifies a list of workstation names, separated by spaces, that are members of theclass. The at sign (@) wildcard character includes all workstations.

ExamplesThe following defines a workstation class named backup:cpuclass backup

membersmainsite1site2

end

The following defines a workstation class named allcpus that contains every workstation:cpuclass allcpus

members@

end

22 Version 8.1

Domain Definitions

A domain is a group of workstations consisting of one or more agents and a domainmanager. The domain manager acts as the management hub for the agents in the domain.You can include multiple domain definitions in the same text file, along with workstationdefinitions and workstation class definitions.

Synopsis# commentdomain domainname[description “text”]

manager wkstation[parent domainname]

end

[cpuname ...]

[cpuclass ...]

[domain ...]

Arguments# comment

Treat all from the pound sign to the end of the line as a comment.

domain domainnameThe name of the domain. It must start with a letter, and can contain alphanumericcharacters, dashes, and underscores. For non-expanded databases, it can contain upto eight characters. For expanded databases, up to 16 characters. You cannot use thesame names for workstations, workstation classes, and domains.

description “text”Provides a description of the domain. Your text must be enclosed in double quotes.

manager wkstationSpecifies the name of the workstation that is the domain manager. The domainmanager must be a fault-tolerant agent with fullstatus and resolvedep set to on.

parent domainnameThe name of the parent domain to which the domain manager is linked. The defaultis the master domain, which does not require a domain definition. The masterdomain is defined by the global options master and master domain.

ExamplesThe following defines a domain named east, with the master domain as its parent, and twosubordinate domains named northeast and southeast:domain east description “The Eastern domain”

manager cyclopsenddomain northeast description “The Northeastern domain”

manager boxcar parent eastenddomain southeast description “The Southeastern domain”

manager sedan parent eastend


2.C

om

po

serR

eference

Job Definitions

A job is an executable file, program, or command that is scheduled and launched byWorkload Scheduler. You can write job definitions in edit files and then add them to thescheduler database with the Composer program. You can include multiple job definitions ina single edit file. Note that you specify job dependencies when you write job streams. Thescheduling language used to write job streams also permits you to add and modify jobdefinitions.

Synopsis$jobs[wkstation#]jobname

[description “text”]{scriptname | jobfilename} filename | docommand “command”streamlogon username[interactive][recovery

{stop | continue | rerun}[{recoveryjob | after} [wkstation#]jobname][{recoveryprompt | abendprompt} “text”] ]

[ [wkstation#]jobname... ]

Argumentswkstation#

Specifies the name of the workstation or workstation class on which the job runs.The default is the workstation on which Composer is running. The pound sign (#) isa required delimiter. If you specify a workstation class, it must match theworkstation class of any job stream in which the job is included.

jobnameSpecifies the name of the job. The name must start with a letter, and can containalphanumeric characters, dashes and underscores. For non-expanded databases, it cancontain up to eight characters. For expanded databases, it can contain up to 40characters.

description “text”Provides a description of the job. Your text must be enclosed in double quotes.

{scriptname | jobfilename} filename

Specifies the name of the file the job executes. Use scriptname for UNIX andWindows NT jobs, and use jobfilename for MPE jobs. For an executable file, enterthe file name and any options and arguments. For non-expanded databases, it cancontain up to 255 characters. For expanded databases, it can contain up to 4095characters. You can also use Workload Scheduler parameters. See “Using Parametersin Job Definitions” on page 27 for more information.

For Windows NT jobs, include the file extensions. Universal Naming Convention(UNC) names are permitted. Do not specify files on mapped drives.

If spaces or special characters are included, other than slashes (/) and backslashes (\),the entire string must be enclosed in quotes (″).

If the file name contains spaces, enter the name in another file that does not havespaces in its name and use the second file’s name for this argument.

24 Version 8.1

docommand commandSpecifies a command that the job executes. Enter a valid command and any optionsand arguments (up to 4095 characters) enclosed in quotes (″). A command isexecuted directly and, unlike scriptname or jobfilename, the configuration script,jobmanrc, is not executed. Otherwise, the command is treated as a job, and all jobrules apply. You can also enter Workload Scheduler parameters. See “UsingParameters in Job Definitions” on page 27 for more information.

streamlogon username

The user name under which the job runs. The name can contain up to 47 characters.If the name contains special characters it must be enclosed in quotes (″). Specify auser that can log on to the workstation on which the job runs. You can also enterWorkload Scheduler parameters. See “Using Parameters in Job Definitions” onpage 27 for more information.

For Windows NT jobs, the user must also have a user definition. See “UserDefinitions” on page 28 for user requirements.

interactive

For Windows NT jobs, include this keyword to indicate that the job runsinteractively on the Windows NT desktop.

recovery

Recovery options for the job. The default is stop with no recovery job and norecovery prompt. Enter one of the recovery options, stop, continue, or rerun. Thiscan be followed by a recovery job, a recovery prompt or both.

stop If the job abends, do not continue with the next job.

continueIf the job abends, continue with the next job.

rerun If the job abends, rerun the job.

{recoveryjob | after} [wkstation#]jobname

Specifies the name of a recovery job to run if the parent job abends.Recovery jobs are run only once for each abended instance of the parent job.

You can specify the recovery job’s workstation if it is different than theparent job’s workstation. The default is the parent job’s workstation. Not alljobs are eligible to have recovery jobs run on a different workstation. Followthese guidelines:

¶ The parent job’s and recovery job’s workstation must be running TivoliWorkload Scheduler Version 4.5.5 or later.

¶ If either workstation is an extended agent, it must be hosted by a domainmanager or a fault-tolerant agent with a value of on for fullstatus.

¶ The recovery job workstation must be in the same domain as the parentjob workstation.

¶ If the recovery job workstation is a fault-tolerant agent, it must have avalue of on for fullstatus.

{recoveryprompt | abendprompt} “text”Specifies the text of a recovery prompt, enclosed in quotes, to be displayed


2.C

om

po

serR

eference

if the job abends. The text can contain up to 64 characters. If the text beginswith a colon (:), the prompt is displayed, but no reply is required to continueprocessing. If the text begins with an exclamation mark (!), the prompt isnot displayed, but a reply is required to proceed.

The following table summarizes all possible combinations of recovery options andactions. The table is based on the following criteria from a job stream called sked1:

¶ Job stream sked1 has two jobs, job1 and job2.

¶ If selected for job1, the recovery job is jobr.

¶ job2 is dependent on job1 and will not start until job1 is complete.

Stop Continue Rerun

Recovery prompt: NoRecovery job: No

Intervention isrequired.

Run job2. Rerun job1. If job1abends, issue schedulerprompt. If reply is yes,repeat above. If job1 issuccessful, run job2.

Recovery prompt: YesRecovery job: No

Issue recoveryprompt.Intervention isrequired.

Issue recoveryprompt. If reply isyes, run job2.

Issue recovery prompt.If reply is yes, rerunjob1. If job1 abends,repeat above. If job1 issuccessful, run job2.

Recovery prompt: NoRecovery job: Yes

Run jobr. If itabends,intervention isrequired. If it issuccessful, runjob2.

Run jobr. Runjob2.

Run jobr. If jobr abends,intervention is required.If jobr is successful,rerun job1. If job1abends, issue schedulerprompt. If reply is yes,repeat above. If job1 issuccessful, run job2.

Recovery prompt: YesRecovery job: Yes

Issue recoveryprompt. If reply isyes, run jobr. If itabends,intervention isrequired. If it issuccessful, runjob2.

Issue recoveryprompt. If reply isyes, run jobr. Runjob2.

Issue recovery prompt.If reply is yes, run jobr.If jobr abends,intervention is required.If jobr is successful,rerun job1. If job1abends, repeat above. Ifjob1 is successful, runjob2.

Notes:

1. ″Intervention is required″ means that job2 is not released from its dependency onjob1, and therefore must be released by the operator.

2. The continue recovery option overrides the abend state, which may cause theschedule containing the abended job to be marked as successful. This willprevent the schedule from being carried forward to the next day.

3. If you select the Rerun option without supplying a recovery prompt, thescheduler generates its own prompt.

26 Version 8.1

||

|

|

|

|||||

||||||||||

||||||

|||

|||||

||||||||

||||||||||

||||||||||

||||

||||||||||

|

||

|||

||

4. To reference a recovery job in Conman, you must use the name of the originaljob (job1 in the scenario above, not jobr). Recovery jobs are run only one perabend.

Using Parameters in Job DefinitionsParameters have the following uses and limitations in job definitions:¶ Parameters are allowed in the streamlogon, scriptname, and docommand values.¶ A parameter can be used as an entire string or a part of it.¶ Multiple parameters are permitted in a single variable.¶ Enclose parameter names in carets (^), and enclose the entire string in quotation marks.

See the example below in which a parameter named mis is used in the streamlogon value.For additional examples, see “Parameter Definitions” on page 31.

ExamplesThe following is a file containing two job definitions:$jobscpu1#gl1

scriptname "/usr/acct/scripts/gl1"streamlogon acctdescription "general ledger job1"

bkupscriptname "/usr/mis/scripts/bkup"streamlogon "^mis^"recovery continue after recjob1


|||

2.C

om

po

serR

eference

User DefinitionsThe user names used as the streamlogon

value for Windows NT job definitions must have user definitions. This is not required forusers who run jobs on other platforms.

Synopsis# commentusername[wkstation#]username

password “password”end

[username ...]

Arguments# comment


username [wkstation#]usernameSpecifies the name of a Windows NT user.

wkstationSpecifies the workstation on which the user is allowed to launch jobs. Thepound sign is required. The default is the blank, meaning all workstations.

username

Specifies the user name in the following form:

[domain\]user

where domain is the Windows NT domain of the user and user is the nameof the user.

For non-expanded databases, the name can contain up to eight characters.For expanded databases, the domain name can contain up to 16 characters(including the backslash), and the user name can contain up to 31 characters.

Note that Windows NT user names are case-sensitive. Also, the user must beable to log on to the workstation on which the scheduler will launch jobs,and must have the right to Log on as batch.

If the name is not unique in Windows NT, it is considered to be a local user,a domain user, or a trusted domain user, in that order.

passwordSpecifies the user’s password. The password can contain up to 29 characters, andmust be enclosed in quotes. To indicate no password, use two consecutive quoteswith no space (″″). Once a user definition is compiled, you cannot read thepassword. Users with appropriate security privileges can modify or delete a user, butpassword information is never displayed.

Trusted Domain UserIf the scheduler must launch jobs for a trusted domain user, give special attention to definingthe user accounts. Assuming the scheduler is installed in Domain1 for user account maestro,and user account sue in Domain2 needs to launch a job, the following must be true:

28 Version 8.1

¶ There must be mutual trust between Domain1 and Domain2.

¶ In Domain1 on the computers where jobs are launched, sue must have the right to Logon as batch.

¶ In Domain1, maestro must be a domain user.

¶ On the domain controllers in Domain2, maestro must have the right to Access thiscomputer from network.

ExamplesThe following example defines four users:username joe

password "okidoki"end#username server#jane

password "okitay"end#username dom1\jane

password "righto"end#username jack

password ""end


2.C

om

po

serR

eference

Calendar Definitions

Calendars are lists of dates that you can use to schedule job streams. Calendar definitionsare entered using the composer modify command. When you enter the command, Composercopies the complete list of calendar definitions into an edit file and starts an editor whereyou can modify the list.

Synopsis$calendarcalendarname [“description”]

date [...]

[calendarname ...]

Argumentscalendarname

Specifies the name of the calendar. The name can contain up to eight alphanumericcharacters, including dashes (-) and underscores (_), and must start with a letter.

“description”Provides a description of the calendar. It must be enclosed in double quotes.

date [...]Specifies one or more dates, separated by spaces. The format is mm/dd/yy.

ExamplesThe following example defines three calendars named monthend, paydays, and holidays:$calendarmonthend "Month end dates 1st half '99"

01/31/99 02/28/99 03/31/99 04/30/99 05/31/99 06/30/99paydays

01/15/99 02/15/9903/15/99 04/15/9905/14/99 06/15/99

holidays01/01/99 02/15/99 05/31/99

30 Version 8.1

||||

Parameter Definitions

Parameters are values that can be substituted variables in job and job stream definitions.Parameter definitions are entered using the composer modify command. When you enter thecommand, Composer copies the complete list of parameter definitions into an edit file andstarts an editor where you can modify the list.

Synopsis$parmparametername “value”

[parametername ...]

Argumentsparametername

The name of the parameter. The name can contain up to eight alphanumericcharacters, including dashes (-) and underscores (_), and must start with a letter.

value Specifies the value assigned to the parameter. Do not include the names of otherparameters.

Usage NotesParameters are accessible to all jobs, job streams, and prompts. When used in scheduling,parameter names are replaced by their values when the production plan is compiled for anew processing day. See Examples below.

ExamplesTwo parameters, glpath and gllogon, are defined as follows:$parmglpath "/glfiles/daily"gllogon "gluser"

In a job stream named glsched, the glpath and gllogon parameters are used in a job namedgljob2:schedule glsched on weekdays:gljob2

scriptname "/usr/gl^glpath^"streamlogon "^gllogon^"opens "^glpath^/datafile"prompt ":^glpath^ started by ^gllogon^"

end


||||

2.C

om

po

serR

eference

Prompt Definitions

You can use prompts as dependencies in jobs and job streams. A prompt must be answeredaffirmatively for the dependent job or job stream to launch. Prompt definitions are enteredusing the composer modify command. When you enter the command, Composer copies thecomplete list of prompt definitions into an edit file and starts an editor where you canmodify the list.

There are two types of prompts:

¶ ad hoc or local

¶ predefined or global

A local prompt is defined within the properties of a job or job stream and is unique to thatjob or job stream.

A global prompt is defined in the scheduler database and can be used by any job or jobstream.

Synopsis$promptpromptname “[: | !]text”

[promptname ...]

Argumentspromptname

Specifies the name of the prompt. The name can contain up to eight alphanumericcharacters, including dashes (-) and underscores (_), and must start with a letter.

text

Provides the text of the prompt. If the text begins with a colon (:), the prompt isdisplayed, but no reply is required to continue processing. If the text begins with anexclamation mark (!), the prompt is not displayed, but a reply is required to proceed.

You can use one or more parameters as part or all of the text string for a prompt. Ifyou use a parameter, the parameter string must be enclosed in carets (^). See“Parameter Definitions” on page 31 for an example.

Note: Within a local prompt, when not designating a parameter, carets (^) must bepreceded by a backslash (\) or they will cause errors in the prompt. Withinglobal prompts, carets do not have to be preceded by a backslash.

You can include backslash n (\n) within the text to create a new line.

ExamplesThe following example defines three prompts:$prompt

prmt1 "ready for job4? (y/n)"prmt2 ":job4 launched"prmt3 "!continue?"

32 Version 8.1

|||||

Resource Definitions

Resources represent physical or logical scheduling resources that can be used asdependencies for jobs and job streams. Resource definitions are entered using the composermodify command. When you enter the command, Composer copies the complete list ofresource definitions into an edit file and starts an editor where you can modify the list.

Synopsis$resourcewkstation#resourcename units [“description” ]

[wkstation#resourcename ...]

Argumentswkstation

Specifies the name of the workstation or workstation class on which the resource isused.

resourcenameSpecifies the name of the resource. The name can contain up to eight alphanumericcharacters, including dashes (-) and underscores (_), and must start with a letter.

units Specifies the number of available resource units. Values can be 0 through 1024.

“description”

Provides a description of the resource. It must be enclosed in double quotes.

ExamplesThe following example defines four resources:$resource

ux1#tapes 3 "tape units"ux1#jobslots 24 "job slots"ux2#tapes 2 "tape units"ux2#jobslots 16 "job slots"

The Composer ProgramThe Composer program manages scheduling objects in scheduler database.

Running ComposerTo run the program, use the following command:

composer [″command[&[command]][...]″]

The following are examples of the command:

¶ Runs Composer and prompts for a command:composer

¶ Executes print and version commands, and quits:composer "p parms&v"

¶ Executes print and version commands, and then prompts for a command:composer "p parms&v&"

¶ Reads commands from cmdfile:


||||

2.C

om

po

serR

eference

composer < cmdfile

¶ Pipes commands from cmdfile to Composer:cat cmdfile | composer

Control CharactersYou can enter the following control characters in conversational mode to interrupt Composerif your stty settings are configured to do so.

Ctrl+cComposer stops executing the current command at the next step that can beinterrupted and returns a command prompt.

Ctrl+dComposer quits after executing the current command.

Terminal OutputThe output to your computer is controlled by shell variables named MAESTROLINES andMAESTROCOLUMNS. If either is not set, the standard shell variables, LINES andCOLUMNS, are used. At the end of each screen page, Composer prompts to continue. IfMAESTROLINES (or LINES) is set to zero or a negative number, Composer does notpause at the end of a page.

Offline OutputThe ;offline option in Composer commands is used to print the output of a command. Whenyou include it, the following variables control the output:

Windows NT Variables

$MAESTROLPSpecifies the file into which a command’s output is written.The default is stdout.

$MAESTROLPLINESSpecifies the number of lines per page. The default is 60.

$MAESTROLPCOLUMNSSpecifies the number of characters per line. The default is 132.

UNIX VariablesThe ;offline option in Composer commands is used to print the output of a command. Whenyou include it, the following shell variables control the output:

$MAESTROLPSpecifies the destination of a command’s output. Set it to one of the following:

> file Redirects output to a file and overwrites the contents of the file. If the filedoes not exist, it is created.

>> fileRedirects output to a file and appends the output to the end of the file. If thefile does not exist, it is created.

| commandPipes output to a system command or process. The system command isexecuted whether or not output is generated.

34 Version 8.1

|| commandPipes outut to a system command or process. The system command is notexecuted if there is no output.

The default is | lp -tCONLIST which directs the command output to the printer andplaces the title “CONLIST” in the banner page of the printout.



You must export the variables before you run Composer.

The Composer EditorSeveral Composer commands automatically open a text editor. You can select which editoryou want Composer to use.

Windows NTOn Windows NT, the default editor is the MS-DOS editor ‘edit’. This editor, however,follows the 8.3 naming convention which can be a limitation when composer uses it tomodify database objects. If the name of the object is longer than 8.3 characters, theComposer MODIFY command will run into an error. You are recommended to use anothereditor, such as Notepad. To change the editor, set the variable EDITOR to the name of thenew editor before running Composer.

UNIXSeveral of Composer’s commands automatically open a text editor. The type of editor isdetermined by the value of two shell variables. If the variable VISUAL is set, it defines theeditor, otherwise the variable EDITOR defines the editor. If neither of the variables is set, avi editor is opened.

Selecting the Composer Command Prompt on UNIXThe composer command prompt is defined in the TWShomelocalopts file. The defaultcommand prompt is a dash (-). To select a different prompt, edit the composer promptoption in the localopts file and change the dash. The prompt can be up to ten characterslong, not including the required trailing pound sign (#):

#----------------------------------------------------------------------------# Custom format attributes#date format = 1 # The possible values are 0-ymd, 1-mdy,2-dmy, 3-NLS.composer prompt = -conman prompt = %switch sym prompt = <n>%#----------------------------------------------------------------------------

Command SyntaxComposer commands consist of the following elements:

commandname selection arguments

where:


||||||

||||

|||||||||

|

2.C

om

po

serR

eference

commandnameSpecifies the command name.

selectionSpecifies the object or set of objects to be acted upon.

argumentsSpecifies the command arguments.

WildcardsThe following wildcard characters are permitted in some Composer commands:

@ Replaces one or more alphanumeric characters.

? Replaces one alphabetic character.

% Replaces one numeric character.

Delimeters and Special CharactersThe following characters have special meanings in Composer commands.

Character Description

& Command delimiter. See “Running Composer” on page 33.

; Argument delimiter. For example:

;info;offline

= Value delimiter. For example:

sched=sked5

: ! Command prefixes that pass the command on to the system. These prefixes areoptional; if Composer does not recognize the command, it is passedautomatically to the system. For example:

!ls or :ls

<< >> Comment brackets. Comments can be placed on a single line anywhere in a jobstream. For example:

schedule foo <<comment>> on everyday

* Comment prefix. When this prefix is the first character on a line, the entire lineis a comment. When the prefix follows a command, the remainder of the line isa comment. For example:

*commentorprint& *comment

> Redirects command output to a file and overwrites the contents of the file. If thefile does not exist, it is created. For example:

display parms > parmlist

>> Redirects command output to a file and appends the output to the end of file. Ifthe file does not exist, it is created. For example:

display parms >> parmlist

| Pipes command output to a system command or process. The system commandis executed whether or not output is generated. For example:

display parms | grep alparm

|| Pipes command output to a system command or process. The system commandis not executed if there is no output. For example:

display parms || grep alparm

36 Version 8.1

Command DescriptionsThe following pages describe Composer’s commands.

Command Description Page

add Adds scheduling objects. “add” onpage 38

build Builds or rebuilds a Workload Scheduler file. “build” onpage 39

continue Ignores the next error. “continue” onpage 40

create Creates a file for editing. “create” onpage 41

delete Deletes scheduling objects. “delete” onpage 43

display Displays scheduling objects. “display, list,print” onpage 45

edit Edits a file. “edit” onpage 48

exit Terminates Composer. “exit” onpage 49

list Lists scheduling objects. “display, list,print” onpage 45

modify Modifies scheduling objects. “modify” onpage 50

new Edits and adds scheduling objects. “new” onpage 52

print Prints scheduling objects. “display, list,print” onpage 45

redo Edits the previous command. “redo” onpage 53

replace Replaces scheduling objects. “replace” onpage 54

validate Validates a file. “validate” onpage 55

version Displays Composer’s program banner. “version” onpage 56

system command Passes a system command to the system. “SystemCommand” onpage 57

You can type command names and keywords in either uppercase or lowercase. You can alsobe abbreviate them to as few leading characters as needed to distinguish them from oneanother.


2.C

om

po

serR

eference

add

Adds jobs, job streams, users, workstations, workstation classes, and domains. You musthave add access for new objects. If an object already exists, you must have modify accessto the object.

Synopsisadd filename

Argumentsfilename

Specifies the name of a file that contains the following:

¶ Job definitions. (The first line of the file must be $jobs.)

¶ Job stream definitions.

¶ Any combination of workstation, workstation class, and domain definitions.

¶ User definitions.

Usage NotesThe syntax of the file is always checked before it is written to the database. All errors andwarnings are reported. If there are syntax errors, you are asked if you want to edit the file tomake corrections. If an object already exists, you are asked whether or not to replace it.

ExamplesThe following example adds the jobs from the file myjobs:add myjobs

The following example adds the job streams from the file mysked:a mysked

The following example adds the workstations, workstation classes, and domains from the filecpus.src:a cpus.src

The following example adds the user definitions from the file users_nt:a users_nt

38 Version 8.1

build

Builds or rebuilds scheduler database files. You must have build access to the file.

Synopsisbuild filename

Argumentsfilename

Specifies one of the following file names:

calendarsThe file that contains calendar definitions.

cpudataThe file that contains workstation, workstation class, and domain definitions.

jobs The file that contains job definitions.

mastskedThe file that contains job stream definitions.

parms The file that contains parameter definitions.

promptsThe file that contains prompt definitions.

resourcesThe file that contains resource definitions.

userdataThe file that contains user definitions.

Usage NotesIf a file does not exist, one is created. If the file exists, it is rebuilt. Rebuilding a databasefile can be useful when the database becomes fragmented from numerous additions anddeletions. The rebuild will remove unused records and optimize the keys.

ExamplesThe following example rebuilds the files containing job stream definitions:build mastsked

The following example rebuilds the file containing calendars:build calendars

The following example rebuilds the file containing workstations:b cpudata


2.C

om

po

serR

eference

continueSpecifies to ignore the next command error.

Synopsiscontinue

Usage NotesThis command is useful when multiple commands are entered on the command line orredirected from a file. It instructs Composer to continue executing commands even if thenext command, following continue, results in an error. This command is not needed whenyou enter commands interactively because Composer will not quit on an error.

ExamplesThe following example tells Composer to continue with the print command if the deletecommand results in a error:composer "continue&delete cpu=site4&print cpu=@"

40 Version 8.1

create

Creates a file containing object definitions. You must have display access to the objectsbeing copied.

Synopsiscreate filename from calendars | parms | prompts | resources

| cpu={wkstation | wkstationclass | domain} |jobs=[wkstation#]jobname |sched=[wkstation#]jstream |users=[wkstation#]username

Argumentsfilename

Specifies a file name.

calendarsCopies all calendars into the file.

parms Copies all parameters into the file.

promptsCopies all prompts into the file.

resourcesCopies all resources into the file.

cpu Copies a workstation, workstation class, or domain into the file.

wkstationThe workstation name. Wildcard characters are permitted.

wkstationclassThe workstation class name. Wildcard characters are permitted.

domainThe domain name. Wildcard characters are permitted.

jobs Copies a job into the file.

wkstationThe name of the workstation or workstation class on which the job runs.Wildcards are permitted. The default is the workstation on which Composeris running.

jobnameThe job name. Wildcards are permitted.

sched Copies a job stream into the file.

wkstationThe name of the workstation or workstation class on which the job streamruns. Wildcard characters are permitted. The default is the workstation onwhich Composer is running.

jstreamThe job stream name. Wildcard characters are permitted.

users Copies a user into the file. The password field is not copied for security reasons.


2.C

om

po

serR

eference

wkstationThe name of the workstation on which the user is defined. Wildcardcharacters are permitted. The default is the workstation on which Composeris running.

usernameThe user name. Wildcard characters are permitted.

Usage NotesAfter you create a file, you can use the edit command to make changes to the file. The addor replace command can then be used to add or update the definition.

ExamplesThe following example creates a file containing all calendars:create caltemp from calendars

The following example creates a file containing all job streams:cr stemp from sched=@

42 Version 8.1

delete

Deletes object definitions from the database. You must have delete access to the objectsbeing deleted.

Synopsisdelete cpu={wkstation | wkstationclass | domain} |jobs=[wkstation#]jobname |sched=[wkstation#]jstream |users=[wkstation#]username

Argumentscpu Deletes a workstation, workstation class, or domain.

wkstationThe workstation name. Wildcards are permitted.

wkstationclassThe workstation class name. Wildcards are permitted.

domainThe domain name. Wildcards are permitted.

jobs Deletes a job.



sched Deletes a job stream.

wkstationThe name of the workstation or workstation class on which the job streamruns. Wildcards are permitted. The default is the workstation on whichComposer is running.

jstreamThe job stream name. Wildcards are permitted.

users Deletes a user.

wkstationThe name of the workstation on which the user is defined. Wildcards arepermitted. The default is the workstation on which Composer is running.

usernameThe user name. Wildcards are permitted.

Usage NotesIf you use wildcard characters to specify a set of definitions, Composer requiresconfirmation before deleting each matching definition.


2.C

om

po

serR

eference

ExamplesThe following example deletes job3 that is launched on workstation site3:delete jobs=site3#job3

The following example deletes all workstations with names starting with ux:de cpu=ux@

The following example deletes all job streams with names starting with test on allworkstations:de sched=@#test@

44 Version 8.1

display, list, print

Displays, lists, or prints object definitions. For display and print, you must have displayaccess to the object. Display actually displays the contents of the database object, while listand print display on the name and attributes of the database object.

Synopsisdisplay | list | print calendars | parms | prompts | resources

| cpu={wkstation | wkstationclass | domain} |jobs=[wkstation#]jobname |sched=[wkstation#]jstream |users=[wkstation#]username

Argumentscalendars

Displays all calendars.

parms Displays all parameters.

promptsDisplays all prompts.

resourcesDisplays all resources.

cpu Displays a workstation, workstation class, or domain.




jobs Displays a job.



sched Displays a job stream.



users Displays a user. (The password field is not copied for security reasons.)


2.C

om

po

serR

eference



Command OutputThe list command displays only the object names. The output of the print command iscontrolled by the variable MAESTROLP. See “Offline Output” on page 34 for moreinformation.

Calendars Format

CalendarThe calendar name.

DescriptionA free-form description of the calendar.

Following these fields is a list of calendar dates.

Cpu Format

CPU idThe of a workstation, workstation class, or domain.

CreatorThe name of the user who created the workstation definition.

Last UpdatedThe date the workstation definition was last updated.

Following these fields is the workstation or workstation class definition.

Jobs Format

CPU idThe name of the workstation on which the job runs.

Job The name of the job.

Logon The name of the logon user for the job.

Last Run DateThe date the job was last run.

Following these fields is the job definition.

Parms Format

ParameterThe name of the parameter.

Value The value of the parameter.

46 Version 8.1

Prompts Format

PromptThe name of the prompt.

MessageThe prompt message text.

Resources Format

CPU idThe name of the workstation on which the resource is defined.

ResourceThe name of the resource.

No AvailThe total number of resource units.

DescriptionThe free-form description of the resource.

Sched Format

CPU idThe name of the workstation on which the job stream runs.

ScheduleThe name of the job stream.

CreatorThe name of the user who created the job stream definition.

Last UpdatedThe date the job stream definition was last updated.

Following these fields is the job stream definition.

Users Format

CPU idThe name of the workstation on which the user is allowed to run jobs.

User The name of the user.

CreatorThe name of the user who created the user definition.

Last UpdatedThe date the user definition was last updated.

Following these fields is the user definition.

ExamplesThe following example displays all calendars:display calendars

The following example prints all job streams that are launched on workstation site2:di sched=site2#@;offline


2.C

om

po

serR

eference

editEdits a file.

Synopsisedit filename

Usage NotesAn editor is started and the specified file is opened for editing. See “The Composer Editor”on page 35 for more information.

ExamplesThe following example opens the file mytemp for editing:edit mytemp

The following example opens the file resfile for editing:ed resfile

48 Version 8.1

exitExits the Composer program.

Synopsisexit

Usage NotesWhen you are running the Composer program in help mode, this command returnsComposer to command input mode.

ExamplesThe following examples exits the Composer program:exit

e


2.C

om

po

serR

eference

modify

Modifies or adds scheduling objects. You must have modify access to the object or affecteddatabase file.

Synopsismodify calendars | parms | prompts | resources |cpu={wkstation | wkstationclass | domain} |jobs=[wkstation#]jobname |sched=[wkstation#]jstream |users=[wkstation#]username

Argumentscalendars

Modifies all calendars.

parms Modifies all parameters.

promptsModifies all prompts.

resourcesModifies all resources.

cpu Modifies a workstation, workstation class, or domain.




jobs Modifies a job.



sched Modifies a job stream.



users Modifies a user.

50 Version 8.1



Usage NotesThe modify command copies the definition or object list into a temporary file, edits the file,and then adds the contents of the file to the appropriate database file. This is equivalent tothe following sequence of commands:create file from object-specificationedit fileadd file

If the add operation is successful, the edit file is purged. For more information, refer to thedescriptions of the create, edit, and add commands in this chapter.

For user definitions, if a password field remains empty when you exit the editor, the oldpassword is retained. To specify a null password use two consecutive double quotes (“”).

ExamplesThe following example modifies all calendars:modify calendars

The following example modifies job stream sked9 that is launched on workstation site1:m sched=site1#sked9


2.C

om

po

serR

eference

newAdds a new scheduling object. You must have add

access for new objects on the workstation. For existing objects, you must have modify

access to the object or the affected database file.

Synopsisnew

Usage NotesThe new command creates a temporary file, edits the file, and then adds the contents of thefile. For calendars, parameters, resources, and prompts, use the modify command on page50.

ExamplesThe following example creates a temporary file, edits the file, and then adds the contents ofthe file to the database:new

or:n

52 Version 8.1

|||

redoEdits and reexecutes the previous command.

Synopsisredo

ContextWhen you execute the redo command, Composer displays the previous command, so that itcan be edited and reexecuted. Use the spacebar to move the cursor under the character to bemodified, and enter the following directives.

Directives

d[dir] Deletes the character above the d. This can be followed by other directives.

itext Inserts text before the character above the i.

rtext Replaces one or more characters with text, beginning with the characterabove the r. Replace is implied if no other directive is entered.

>text Appends text to the end of the line.

>d[dir | text]Deletes characters at the end of the line. This can be followed by anotherdirective or text.

>rtext Replaces characters at the end of the line with text.

Directive Examples

ddd Deletes the three characters above the ds.

iabc Inserts abc before the character above the i.

rabc Replaces the three characters, starting with the one above the r, with abc.

abc Replaces the three characters above abc with abc.

d diabcDeletes the character above the first d, skips one character, deletes thecharacter above the second d, and inserts abc in its place.

>abc Appends abc to the end of the line.

>ddabcDeletes the last two characters in the line, and inserts abc in their place.

>rabc Replaces the last three characters in the line with abc.

ExamplesThe following example inserts a character:redodislay site1#sa@

ipdisplay site1#sa@

The following example replaces a character:redodisplay site1#sa@

2display site2#sa@


2.C

om

po

serR

eference

replace

Replaces scheduling objects. You must have modify access to the objects or the affecteddatabase file.

Synopsisreplace filename

Argumentsfilename

Specifies the name of a file containing one of the following:

¶ Job definitions. The first line of the file must be $jobs.

¶ Job stream definitions.

¶ Any combination of workstation, workstation class, and domain definitions.

¶ User definitions.

¶ A complete set of calendars, parameters, prompts, or resources.

Usage NotesThe replace command is similar to the add command, except that there is no prompt toreplace existing objects. For more information, refer to “add” on page 38.

ExamplesThe following example replaces the jobs from the file myjobs:replace myjobs

The following example replaces the job streams from the file mysked:rep mysked

The following example replaces all resources with those contained in the file myres:rep myres

54 Version 8.1

validate

Validates a file containing scheduling objects.

Synopsisvalidate filename[;syntax]

Argumentsfilename

Specifies the name of a file that contains calendars, workstations, workstationclasses, domains, jobs, parameters, prompts, resources, or job streams. Enterprodsked to validate the production schedule file created during pre-production dayprocessing.

syntaxChecks the file for syntax error.

Usage NotesThe validate command performs the same syntax checks and validation that are performedwhen you add or modify objects. It can also be used to validate the production schedule file,prodsked, created during the pre-production day processing. Prodsked contains the jobstreams to be run on a particular day, and it can be modified with an editor to include adhoc changes before processing day begins. Validate should be used in these cases to ensurethat the production schedule is still valid.

For job streams, if the syntax option is omitted, validation and reporting include thefollowing:

¶ Verify job names against the master job file.

¶ Examine dependencies to ensure that the objects exist. For example, a needs dependencyon a non-existent resource is reported. This will also check for references to non-existentcalendars.

¶ Check for circular dependencies. For example, if job1 follows job2, and job2 followsjob1 there is a circular dependency.

The output of the validate command can be redirected to a file as follows:composer "validate filename" > outfile

To include error messages in the output file, use the following:composer "validate filename" > outfile 2>&1

ExamplesThe following example checks the syntax of a file containing workstation definitions:validate mycpus;syntax

The following example revalidates all job streams. This can be done to verify the integrityof references to other scheduling objects after changes have been made.create allskeds from sched=@#@validate allskeds


2.C

om

po

serR

eference

versionDisplays Composer’s program banner.

Synopsisversion

ExamplesThe following example displays Composer’s program banner:version

or:v

56 Version 8.1

System CommandExecutes a system command.

Synopsis[: | !] sys-command

Argumentssys-command Specifies any valid system command. The prefix of colon (:) or exclamation

mark (!) is required only when the command is spelled the same as aComposer command.

ExamplesThe following example executes a ps command on UNIX:ps -ef

The following example executes a dir command on Windows NT:dir \bin


2.C

om

po

serR

eference

58 Version 8.1

Scheduling Language

This chapter describes the scheduling language format and keywords used to define jobstreams for Workload Scheduler. These keywords and syntax are used to define job streamsusing the command line interface. Job streams created using the graphical user interface donot reference the keywords listed in this chapter, but all job streams in the scheduler aresaved using the same scheduling language syntax and keywords.

Syntax for Job StreamsThe following shows the structure of a job stream, with keywords in bold. A job streambegins with a schedule keyword followed by attributes and dependencies. The colondelimiter introduces the jobs that comprise the job stream. Each job has its own attributesand dependencies.

schedule [cpu#]sched[freedays Calendar_Name [-sa] [-su] ]on {date| day | calendar | request}[,...] [fdignore | fdnext | fdprev][on {date| day | calendar | request}[,...] [fdignore | fdnext | fdprev]][,...][except{date| day | calendar}[,...] [fdignore | fdnext | fdprev] ][,...][at time[timezone|tz tzname][+ n day [s] ] ] [,...][carryforward][follows { [cpu#] sched [. job] [,...] } ][in order][limit number][needs resource][opens file][priority number][prompt name|text][until time]

:job-statement

[at time][confirmed][every rate][follows job|jstream][needs resource][opens file][priority number][prompt name|text]

3


||||||||

|

3.S

ched

ulin

gL

ang

uag

e

[until time][job-statement...]end

KeywordsA brief description of the scheduling keywords is provided in the following table.

Keyword Description Page

at Defines the time of day that job stream or job executionbegins.

“at” on page 62

carryforward Carries the job stream forward if it is not completed. “carryforward”on page 63

comments Includes comments in a job stream definition “comments” onpage 64

confirmed Specifies that the completion of this job requiresconfirmation.

“confirmed” onpage 65

end Marks the end of a job stream. “end” on page 66

every Launches the job repeatedly at a specified rate. “every” onpage 67

except Specifies dates that are exceptions to the dates the jobstream is selected for execution.

“except” onpage 68

follows Specifies not to launch this job or job stream until otherjobs and job streams have completed successfully.

“follows” onpage 70

freedays Specifies a freeday calendar for calculating workdays forthe job stream. It can also set saturdays and sundays asworkdays.

“freedays” onpage 71

in order Launches jobs in this job stream in the order they arelisted.

“in order” onpage 73

job statement Defines a job and its dependencies. “job statement”on page 74

limit Sets a limit on the number of jobs that can be launchedconcurrently from the job stream.

“limit” onpage 77

needs Defines the number of units of a resource required by thejob or job stream before it can be launched.

“needs” onpage 78

on Defines the dates on which the job stream is selected forexecution.

“on” on page 79

opens Defines files that must be accessible before the job or jobstream is launched.

“opens” onpage 82

priority Defines the priority for a job or job stream. “priority” onpage 84

prompt Defines prompts that must be replied to before the job orjob stream is launched.

“prompt” onpage 85

schedule Assigns a name to the job stream. “schedule” onpage 86

until Defines a time of day after which the job or job stream isnot launched.

“until” onpage 87

60 Version 8.1

|

DependenciesA dependency is a condition that must be satisfied before a job or job stream is launched.They are to job streams with the follows, needs, opens and prompt keywords. Themaximum number of dependencies permitted for a job or job stream is 40.

Note: The only dependency that is checked immediately before running a job is NEEDS.An OPENS dependency is automatically considered resolved before the job runs.

Case SensitivityWith the exception of path names, user names, and UNIX commands, which arecase-sensitive, you can use either upper or lower case characters when writing yourschedules.

Keyword DescriptionsThe following pages describe the syntax for scheduling language keywords.


3.S

ched

ulin

gL

ang

uag

e

at

Defines the earliest time a job or job stream will be launched.

Synopsisat time [timezone|tz tzname][+n day[s] [,...]

Argumentstime Specifies a time of day. Possible values can range from 0000 to 2359.

tznameSpecifies the time zone to be used when computing the start time. See “Time ZoneNames and Descriptions” on page 285 for time zone names. The default is the timezone of the workstation on which the job or job stream is launched.

Note: If an at time and an until time are specified, the time zones must be thesame.

n Specifies an offset in days from the scheduled start date and time.

Usage NotesIf an at time is not specified for a job or job stream, its launch time is determined by itsdependencies and priority.

The time value in the at option is considered as follows:

If the time value is less than the current time, it is taken as for the following day.

If the time value is greater than the current time, it is taken as for the current day.

If you specifya time value greater than 2400, the valueis divided by 2400 to obtain thenumber of days. If you specify days, these are add to the value obtained by dividing by2400.

ExamplesThe following examples assume that the Workload Scheduler processing day starts at 6:00A.M.

¶ The following job stream, selected on Tuesdays, is launched no sooner than 3:00 A.M.Wednesday morning. Its two jobs are launched as soon as possible after that time.schedule sked7 on tu at 0300:job1job2end

¶ The time zone of workstation sfran is defined as Pacific Standard Time (pst), and thetime zone of workstation nycity is defined as Eastern Standard Time (est). Thefollowing job stream is selected for execution on Friday. It is launched on workstationsfran at 10:00 A.M. pst Saturday. job1 is launched on sfran as soon as possible afterthat time. job2 is launched on sfran at 2:00 P.M. est (11:00 A.M. pst) Saturday. job3 islaunched on workstation nycity at 4:00 P.M. est (1:00 P.M. pst) Saturday.sfran#schedule sked8 on fr at 1000 + 1 day :job1job2 at 1400 tz estnycity#job3 at 1600end

62 Version 8.1

|

|

|

|

|||

|

carryforward

Makes a job stream eligible to be carried forward to the next day’s production plan if it isnot completed before the end of the current day’s production plan.

Synopsiscarryforward

ExamplesThe following job stream is carried forward if its jobs have not completed beforepre-production processing begins for a new day.schedule sked43 on thcarryforward:job12job13job13aend


3.S

ched

ulin

gL

ang

uag

e

comments

Includes comments in a job stream definitition.

Synopsis*text | <<text>>

Arguments*text Inserts a comment line. The first character in the line must be an asterisk.

<<text>>Inserts comment text on a line. The text must be enclosed in double angle brackets.

ExamplesThe following example includes both types of comments:***************************************** The weekly cleanup jobs*****************************************schedule wkend on fr at 1830in order:job1 <<final totals and reports>>job2 <<update database >>end

64 Version 8.1

confirmed

Specifies that a job’s completion must be confirmed by executing a Conman confirmcommand. See “confirm” on page 113 for more information.

Synopsisconfirmed

ExamplesIn the following job stream, confirmation of the completion of job1 must be received beforejob2 and job3 are launched.schedule test1 on fr:job1 confirmedjob2 follows job1job3 follows job1end


3.S

ched

ulin

gL

ang

uag

e

end

Marks the end of a job stream definition.

Synopsisend

Examplesschedule test1 on monthend:job1job2job3end << end of job stream >>

66 Version 8.1

every

Defines the repitition rate for a job. The job is launched repeatedly at the specified rate.

Synopsisevery rate

Argumentsrate The repetition rate expressed in hours and minutes, in the format: hhmm. (The rate

can be greater than 24 hours.)

ExamplesThe following example launches the job testjob every hour:testjob every 100

The following example launches the job testjob1 every 15 minutes, between the hours of6:00 P.M. and 8:00 P.M.:testjob1 at 1800 every 15 until 2000


3.S

ched

ulin

gL

ang

uag

e

except

Defines the dates that are exceptions to the on dates of a job stream. See “on” on page 79for more information.

Synopsisexcept {date| day | calendar } [fdignore | fdnext | fdprev][,...][except {date| day | calendar }] [fdignore | fdnext | fdprev][,...]]

Argumentsdate A date in the format: mm/dd/yy.

day A day of the week. Specify one or more of the following:mo Mondaytu Tuesdaywe Wednesdayth Thursdayfr Fridaysa Saturdaysu Sundayweekdays

Everyday except saturday and sunday.workdays

Can be one of the following:¶ If you specified a freedays calendar, workdays are everyday excluding

saturday and sunday (unless you specified -sa or -su along with thefreedays keyword) and excluding all the dates of the specified freedayscalendar.

¶ If you did not specify a freedays calendar, workdays are everydayexcluding saturday and sunday and excluding all the dates of theholidays calendar.

freedaysThe days marked in the freedays calendar, if you specified one.

calendarThe dates specified on a calendar by this name. The calendar name can be followedby an offset in the following format:

{+ | -}n {day[s] | weekday[s] | workday[s]}

Where:

n The number of days, weekdays, or workdays.

days Stands for every day of the week.

weekdaysStands for every day of the week, except saturday and sunday.

workdaysStands for every day of the week, except for saturdays and sundays (unlessotherwise specified with the freedays keyword) and for the dates markedeither in a designated freedays calendar or in the holidays calendar.

68 Version 8.1

||

|||||||||||

||||

freeday ruleSpecifies a rule that must be applied when the date selected for exclusion falls on afreeday. Can be one of the following:

fdignoreDo not exclude the date.

fdnext Exclude the nearest workday after the freeday.

fdprevExclude the nearest workday before the freeday.

Usage NotesYou can define multiple instances of the except keyword for the same job stream. Eachinstance is equivalent to a run cycle to which you can associate a freeday rule.

Multiple except instances must be consecutive within the job stream definition.

Each instance of the keyword can contain any of the values allowed by the except syntax.

ExamplesThe following example selects job stream testskd2 to run every weekday except those dayswhose dates appear on calendars named monthend and holidays:schedule testskd2 on weekdaysexcept monthend,holidays

The following example selects job stream testskd3 to run every weekday except May15,1999 and May 23, 1999:schedule testskd3 on weekdaysexcept 05/15/99,05/23/99

The following example selects job stream testskd4 to run every day except two weekdaysprior to any date appearing on a calendar named monthend:schedule testskd4 on everydayexcept monthend-2 weekdays

Select job stream sked4 to run on mondays, tuesdays, and 2 weekdays prior to each datelisted in the MONTHEND calendar. If the run date is a freeday, run the job stream on thenearest following workday. Do not run the job stream on wednesdays.schedule sked4on moon tu, MONTHEND -2 weekdays fdnextexcept we

Select job stream testskd2 to run every weekday except for the days listed in MONTHEND.If a date in MONTHEND falls on a freeday, exclude the nearest workday before it. In thisexample, the freedays are saturdays, sundays, and all the dates listed in the default holidayscalendar .schedule testskd2on weekdaysexcept MONTHEND fdprev


|||

||

||

||

|||

|

|

|||

||||

||||

|||

|

3.S

ched

ulin

gL

ang

uag

e

follows

Defines the other jobs and job streams that must complete successfully before a job or jobstream is launched.

SynopsisUse the following syntax for job streams:

follows [netagent::][wkstation#]jstream[.jobname | @] [,...]

Use the following syntax for jobs:

follows [netagent::][wkstation#]jstream{.jobname | @} | jobname [,...]

Argumentsnetagent

The name of the network agent where the inter-network dependency is defined.

wkstationThe workstation on which the job or job stream that must be complete runs. Thedefault is the same workstation as the dependent job or job stream.

If a wkstation is not specified with netagent, the default is the workstation to whichthe network agent is connected.

jstreamThe name of the job stream that must be complete. For a job, the default is the samejob stream as the dependent job.

jobnameThe name of the job that must be complete. An at sign (@) can be used to indicatethat all jobs in the job stream must complete successfully.

ExamplesThe following example specifies to not launch job stream skedc until job stream sked4 onworkstation site1, and job joba in job stream sked5 on workstation site2 have completedsuccessfully:schedule skedc on frfollows site1#sked4,site2#sked5.joba

Do not launch sked6 until jobx in the job stream skedx on remote network cluster4 hascompleted successfully:sked6 follows cluster4::site4#skedx.jobx

The following example specifies to not launch jobd until joba in the same job stream, andjob3 in job stream skeda have completed successfully:jobd follows joba,skeda.job3

The following example specifies to not launch jobe until all jobs in job stream skedb onworkstation unix1 have completed successfully:jobe follows unix1#skedb.@

70 Version 8.1

|

freedays

Enables you to specify the name of a freedays calendar (see the User’s Guide for adescription of freedays calendars) that lists the days when the job stream should not run.Workload Scheduler uses this calendar as the base calendar for calculating workdays for thejob stream.

The keyword affects only the scheduling of the job streams for which it is specified.

Synopsisfreedays Calendar_Name [-sa] [-su]

ArgumentsCalendar_Name

The name of the calendar that must be used as the freedays calendar for the jobstream. If Calendar_Name is not in the database, Workload Scheduler issues awarning message when you save the job stream. If Calendar_Name is not in thedatabase when schedulr runs, Workload Scheduler issues an error message and usesthe default calendar holidays in its place.

-sa Count saturdays as workdays.

-su Count sundays as workdays.

Usage NotesIf you do specify a freedays calendar in the job stream definition, then the workdayskeyword takes on the following value: workdays = everyday excluding saturday and sunday(unless user specified -sa or -su along with freedays) and excluding all the dates ofCalendar_Name

If you do not specify freedays in the job stream definition, then: workdays = everydayexcluding saturday and sunday and all the dates of the holidays calendar

By default, saturday and sunday are considered as freedays unless you specify the contraryby adding -sa and/or -su after Calendar_Name.

ExamplesSelect job stream sked2 to run on 01/01/2001 and on all workdays as long as they are notlisted in the freedays calendar named GERMHOL.schedule sked2freedays GERMHOLon 01/01/2001, workdays

Select job stream sked3 to run two workdays before each date in the PAYCAL calendar.Workdays are everyday from monday to saturday as long as they are not listed in thefreedays calendar named USAHOL.schedule sked3freedays USAHOL -saon PAYCAL -2 workdays

Select job stream sked3 on the dates listed in the APDATES calendar. If the selected date isa freeday, do not run the job stream. In this example, sundays and all the dates listed in theGERMHOL calendar are to be considered as freedays. All days from monday to saturday,except for the specific dates listed in GERMHOL, are workdays.


|

||||

|

||

|

||||||

||

||

|||||

||

||

|||

|||

|||

|||

||||

3.S

ched

ulin

gL

ang

uag

e

schedule sked3freedays GERMHOL -saon APDATES fdignore

Select job stream testsked3 to run every weekday except 5/15/2002 and 5/23/2002. If5/23/2002 is a freeday, do not exclude it. In this example, saturdays, sundays, and all thedates listed in GERMHOL are to be considered as freedays. All days from monday to friday,except for the specific dates listed in GERMHOL, are workdays.schedule testskd3freedays GERMHOLon weekdaysexcept 5/15/2002 fdignoreexcept 5/23/2002

Select job stream testsked4 to run every day except two weekdays prior to every date listedin the MONTHEND calendar. If the date to be excluded is a freeday, do not exclude it, butexclude the nearest following workday. In this example, freedays are all the dates listed inUSAHOL, while workdays are all the days from monday to sunday that are not inUSAHOL.schedule testskd4freedays USAHOL -sa -suon everydayexcept MONTHEND -2 weekdays fdnext

72 Version 8.1

|||

||||

|||||

|||||

||||

|

in order

Specifies that jobs are to be launched in the order they appear in a job stream. Each jobmust complete successfully before the next job is launched. This keyword must be the lastkeyword to appear in hte job stream definition before the colon. No dependencies arepermitted for the jobs in the job stream.

Synopsisin order

Usage NotesIf an in order job does not complete successfully, and cannot be rerun successfully, the jobsthat follow it must be released with a Conman release command. For example, to release thejobs in job stream sked1, you can enter the following Conman command:rj sked1.@

If an in order job is cancelled, the next job must be released with a Conman releasecommand. The remaining jobs in the job stream will continue as normal. For example, if jobj1 is cancelled, you can release job j2 by entering the following Conman command:rj sked1.j2

The fault-tolerant agent on which an in order job runs must have Full Status mode turnedon if the job follows a job that runs on a different workstation. This is illustrated in“Examples.” For more information about Full Status mode, refer to “WorkstationDefinitions” on page 18.

ExamplesThe following example launches joba, jobb and jobc, one at a time, in the order theyappear in sked2:schedule sked2 on everyday in order :

jobajobbjobc

end

The following example launches job1, site2#job2 and job3, one at a time, in the order theyappear in sked3:schedule sked3 on tu,th in order :

job1site2#job2job3

end

If the job stream is launched on a fault-tolerant agent (site3, for example), job site2#job2will not be launched when job1 completes unless Full Status mode is turned on for site2. Inaddition, job3 will not be launched when site2#job2 completes unless Full Status mode isturned on for site3.


3.S

ched

ulin

gL

ang

uag

e

job statement

Job statements place jobs in a job stream and define job dependencies. In a job statement,you can also include job attributes and recovery options that add a new job or modify anexisting job in the database. See “Usage Notes” for more information.

Synopsis[wkstation#]jobname[description “text”][{scriptname | jobfilename} filename | docommand “commandline”][streamlogon username][interactive][recovery {stop | continue | rerun}

[{recoveryjob | after} [rwkstation#]rjobname][{recoveryprompt | abendprompt} “rtext”]]

[job-dependency [,...]]

Argumentswkstation

Specifies the name of the workstation or workstation class on which the job runs.The default is the workstation on which the job stream runs. The pound sign (#) is arequired delimiter. If you specify a workstation class, it must match the workstationclass of any job stream in which the job is included.

jobnameSpecifies the name of the job. The name must start with a letter, and can containalphanumeric characters, dashes and underscores. For non-expanded databases, it cancontain up to eight characters. For expanded databases, it can contain up to 40characters.

Note: Do not use the word recovery as the job name. This is reserved.

descriptionA free-form description of the job, enclosed in double quotes.

{scriptname | jobfilename} filename

Specifies the name of the file the job executes. Use scriptname for UNIX andWindows NT jobs, and use jobfilename for MPE jobs. For an executable file, enterthe file name and any options and arguments (up to 4095 characters). You can alsouse Workload Scheduler parameters. See “Using Parameters in Job Definitions” onpage 76 for more information.

For Windows NT jobs, include the file extensions. Universal Naming Convention(UNC) names are permitted. Do not specify files on mapped drives.

If spaces or special characters are included, other than slashes (/) and backslashes (\),the entire string must be enclosed in quotes (″).

If the file name contains spaces, enter the name in another file that does not havespaces in its name and use the second file’s name for this argument.

docommand commandSpecifies a command that the job executes. Enter a valid command and any optionsand arguments (up to 4095 characters) enclosed in quotes (″). A command isexecuted directly and, unlike scriptname or jobfilename, the configuration script,

74 Version 8.1

|

jobmanrc, is not executed. Otherwise, the command is treated as a job, and all jobrules apply. You can also enter Workload Scheduler parameters. See “UsingParameters in Job Definitions” on page 76 for more information.

streamlogon

The user name under which the job runs. The name can contain up to 47 characters.If the name contains special characters it must be enclosed in quotes (″). Specify auser that can log on to the workstation on which the job runs. You can also enterWorkload Scheduler parameters. See “Using Parameters in Job Definitions” onpage 76.

For Windows NT jobs, the user must also have a user definition. See “UserDefinitions” on page 28 for user requirements.

interactive

For Windows NT jobs, include this keyword to indicate that the job runsinteractively on the Windows NT desktop.

recovery

Recovery options for the job. The default is stop with no recovery job and norecovery prompt. Enter one of the recovery options, stop, continue, or rerun. Thiscan be followed by a recovery job, a recovery prompt or both.

stop If the job abends, do not continue with the next job.

continueIf the job abends, continue with the next job.

rerun If the job abends, rerun the job.

{recoveryjob | after} [wkstation#]jobname

Specifies the name of a recovery job to run if the parent job abends.Recovery jobs are run only once for each abended instance of the parent job.

You can specify the recovery job’s workstation if it is different than theparent job’s workstation. The default is the parent job’s workstation. Not alljobs are eligible to have recovery jobs run on a different workstation. Followthese guidelines:

¶ The parent job’s and recovery job’s workstation must be runningWorkload Scheduler Version 4.5.5 or later.

¶ If either workstation is an extended agent, it must be hosted by a domainmanager or a fault-tolerant agent with a value of on for fullstatus.

¶ The recovery job’s workstation must be in the same domain as theparent job’s workstation.

¶ If the recovery job’s workstation is a fault-tolerant agent, it must have avalue of on for fullstatus.

{recoveryprompt | abendprompt} “text”Specifies the text of a recovery prompt, enclosed in quotes, to be displayedif the job abends. The text can contain up to 64 characters. If the text beginswith a colon (:), the prompt is displayed, but no reply is required to continueprocessing. If the text begins with an exclamation mark (!), the prompt isnot displayed, but a reply is required to proceed.


3.S

ched

ulin

gL

ang

uag

e

job-dependencySpecifies scheduling keywords and arguments. The valid keywords for jobs are: at,confirmed, every, follows, needs, opens, priority, prompt, and until.

Using Parameters in Job DefinitionsParameters have the following uses and limitations in job definitions:¶ Parameters are allowed in the streamlogon, scriptname, and docommand values.¶ A parameter can be used as an entire string or a part of it.¶ Multiple parameters are permitted in a single variable.¶ Enclose parameter names in carets (^), and enclose the entire string in quotation marks.

See the example below in which a parameter named mis is used in the streamlogon value.For additional examples, see “Parameter Definitions” on page 31.

Usage NotesA job needs to be defined only once in the database, and can be used in multiple jobstreams. When a job stream is added or modified, the attributes or recovery options of itsjobs are also added or modified.

When defining jobs, keep the following in mind:

¶ Jobs can be defined independently (as described in “Job Definitions” on page 24), or aspart of job streams. In either case, the changes are made in the database and do notaffect the production plan until the start of a new processing day.

¶ When you add or replace a job stream, any job modifications affect all other job streamsthat use the jobs. Note that the Cross Reference Report can be used to determine thenames of job streams in which a particular job is included.

ExamplesThe following example defines a job stream with three previously defined jobs:schedule bkup on fr at 20:00 :

cpu1#jbk1cpu2#jbk2

needs 1 tapecpu3#jbk3

follows jbk1end

The following job stream definition contains job statements that add or modify thedefinitions of two jobs in the database:schedule sked4 on mo :

job1 scriptname “d:\apps\maestro\scripts\jcljob1”streamlogon jackrecovery stop abendprompt “continue production”

site1#job2 scriptname “d:\apps\maestro\scripts\jcljob2”streamlogon jackfollows job1

end

76 Version 8.1

limit

Limits the number of jobs that can execute simultaneously in a job stream.

Synopsislimit joblimit

Argumentsjoblimit Specifies the number of jobs that can be running at the same time in the

schedule. Possible values are 0 through 1024. If you specify 0, you preventall jobs from being launched.

ExamplesThe following example limits to five the number of jobs that can execute simultaneously injob stream sked2:schedule sked2 on fr

limit 5 :


3.S

ched

ulin

gL

ang

uag

e

needs

Defines resources that must be available before a job or job stream is launched.

Synopsisneeds [n] [wkstation#]resourcename [,...]

Argumentsn Specifies the number of resource units required. Possible values are 0

through 32. The default is one.

wkstation Specifies the name of the workstation on which the resource is locallydefined. The default is the workstation of the dependent job or job stream.Resources can be used as dependencies only by jobs and job streams thatrun on the same workstation as the resource. However, a standard agent andits host can reference the same resources.

resourcename Specifies the name of the resource.

ExamplesThe following example prevents job stream sked3 from being launched until three units ofcputime, and two units of tapes become available:schedule sked3 on fr

needs 3 cputime,2 tapes :

The jlimit resource has been defined with two available units. The following example allowsno more than two jobs to execute concurrently in job stream sked4:schedule sked4 on mo,we,fr :

joba needs 1 jlimitjobb needs 1 jlimitjobc needs 2 jlimit <<runs alone>>jobd needs 1 jlimit

end

78 Version 8.1

||||||

on

This is a required job stream keyword that defines when and how often a job stream isselected for execution. The on keyword must follow the schedule keyword. See “except” onpage 68 for more information.

Synopsison {date| day | calendar | request}[,...] [fdignore | fdnext | fdprev][,...][on {date| day | calendar | request}[,...] [fdignore | fdnext | fdprev]][,...]

Argumentsdate Specifies a date in the format, mm/dd/yy.

day A day of the week. You can specify one or more of the following:mo Mondaytu Tuesdaywe Wednesdayth Thursdayfr Fridaysa Saturdaysu Sundayweekdays

Everyday except Saturday and Sundayeveryday

Every day of the weekworkdays

Can be one of the following:¶ If you specified a freedays calendar, workdays are everyday excluding

saturday and sunday (unless you specified -sa or -su along with thefreedays keyword) and excluding all the dates of the specified freedayscalendar.

¶ If you did not specify a freedays calendar, workdays are everydayexcluding saturday and sunday and excluding all the dates of theholidays calendar.

freedaysThe days marked in the freedays calendar, if you specified one.

calendarThe dates specified on a calendar by this name. The calendar name can be followedby an offset in the following format:

{+ | -}n {day[s] | weekday[s] | workday[s]}

Where:

n The number of days, weekdays, or workdays.

days Stands for every day of the week.

weekdaysStands for every day of the week, except saturday and sunday.

workdaysStands for every day of the week, except for saturdays and sundays (unlessotherwise specified with the freedays keyword) and for the dates markedeither in a designated freedays calendar or in the holidays calendar.


||

|||||||||||||

||||

3.S

ched

ulin

gL

ang

uag

e

requestSelects the job stream only when requested. This is used for job streams that areselected by name rather than date.

freeday ruleSpecifies a rule that must be applied when the selected date falls on a freeday. Canbe one of the following:

fdignoreDo not run the job stream.

fdnext Run the job stream on the nearest workday after the freeday.

fdprevRun the job stream on the nearest workday before the freeday.

Usage NotesYou can define multiple instances of the on keyword for the same job stream. Each instanceis equivalent to a run cycle to which you can associate a freeday rule.

Multiple on instances must be consecutive within the job stream definition.

Each instance of the keyword can contain any of the values allowed by the on syntax.

You must specify the on keyword at least once in the definition of a job stream.

ExamplesThe following example selects job stream sked1 on Mondays and Wednesdays:schedule sked1 on mo,we

The following example selects job stream sked3 on June 15, 1999, and on the dates listedon the apdates calendar:schedule sked3 on 6/15/99,apdates

The following example selects job stream sked4 two weekdays before each date appearingon the monthend calendar:schedule sked4 on monthend -2 weekdays

The following example selects job stream testskd1 every weekday except Wednesdays:schedule testskd1 on weekdays

except we

The following example selects job stream testskd3 every weekday except May 15, 1999 andMay 24, 1999:schedule testskd3 on weekdays

except 05/16/99,05/24/99

The following example selects job stream testskd4 every day except two weekdays prior toany date appearing on a calendar named monthend:schedule testskd4 on everyday

except monthend -2 weekdays

Select job stream sked1 to run all mondays, fridays, and on 29/12/2001. If mondays and29/12/2001 are freedays, run the job stream on the nearest following workday. If fridays arefreedays, run the job stream on the nearest preceding day. In this example, the freedays are

80 Version 8.1

|||

|||

||

||

||

|||

|

|

|

|||

saturdays, sundays, and all the dates listed in the default HOLIDAYS calendar. Workdays areall days from monday to friday as long as they are not listed in HOLIDAYS.schedule sked1on mo, 29/12/2001 fdnexton fr fdprev


||

|||

|

3.S

ched

ulin

gL

ang

uag

e

opens

Specifies files that must be available before a job or job stream can be launched.

Synopsisopens [wkstation#]″filename″ [(qualifier)] [,...]

Argumentswkstation

Specifies the name of the workstation or workstation class on which the file exists.The default is the workstation or workstation class of the dependent job or jobstream. If you use a workstation class, it must be the same as that of the job streamthat includes this statement.

filenameSpecifies the name of the file, enclosed in quotation marks. You can use WorkloadScheduler parameters as part or all of the file name string. If you use a parameter, itmust be enclosed in carets (^).

qualifierSpecifies a valid test condition. On UNIX, the qualifier is passed to a test command,which executes as root in bin/sh.

On Windows NT, the test function is performed as the maestro user. The validqualifiers are:

-d %p True if the file exists and is a directory.

-e %p True if the file exists.

-f %p True if the file exists and is a regular file.

-r %p True if the file exists and is readable.

-s %p True if the file exists and it’s size is greater than zero.

-w %p True if the file exists and is writeable.

On both UNIX and Windows NT, the expression %p, inserts the name of the file.

Entering (notempty) is the same as entering (-s %p). If no qualifier is specified, thedefault is (-f %p).

Usage NotesThe combination of filename and qualifier cannot exceed 148 characters, within which thebase name of the file name cannot exceed 28 characters.

ExamplesThe following example checks to see that file c:\users\fred\datafiles\file88 on workstationnt5 is available for read access before launching ux2#sked6:schedule ux2#sked6 on tu opens nt5#"c:\users\fred\datafiles\file88"

The following example checks to see if three directories, /john, /mary, and /roger, existbefore launching job jobr2:jobr2 opens "/users"(-d %p/john -a -d %p/mary -a -d %p/roger)

82 Version 8.1

The following example checks to see if cron has created its FIFO file before launching jobjob6:job6 opens "/usr/lib/cron/FIFO"(-p %p)

The following example checks to see that file d:\work\john\execit1 on workstation dev3exists and is not empty, before running job jobt2:jobt2 opens dev3#"d:\work\john\execit1"(notempty)

The following example checks to see that file c:\tech\checker\startf on workstation nycexists with a size greater than zero, and is writable, before running job job77:job77 opens nyc#"C:\tech\checker\startf"(-s %p -a -w %p)

Security for test(1) CommandsOn UNIX, a special security feature prevents unauthorized use of other commands in thequalifier. For example, the file below contains a command in the qualifier:/users/xpr/hp3000/send2(-n "'ls /users/xpr/hp3000/m*'" -o -r %p)

If the qualifier contains another command, the following checks are made:

1. The Local Option jm no root must be set to no.

2. In the security file, the user documenting the schedule or adding the Open Filesdependency with a Conman addep command, must have submit access to a job with thefollowing attributes:

name=cmdstest.fileeqlogon=rootjcl=the path of the opens filescpu=the CPU on whcih the opens files resides

Note that cmdstest and fileeq do not exist.


|||

|

|

|

|||||||

|

|

3.S

ched

ulin

gL

ang

uag

e

priority

Sets the priority of a job or job stream.

Synopsispriority number | hi | go

Argumentsnumber Specifies the priority. Possible values are 0 through 99. A priority of zero

prevents the job or job stream from launching.

hi The equivalent of priority 100.

go The equivalent of priority 101, the highest priority.

ExamplesThe following example illustrates the relationship between job stream and job priorities. Thejobs are launched in the following order: job1, job2, joba, jobb.

schedule sked1 on tupriority 50:job1 priority 15job2 priority 10end

schedule sked2 on tupriority 10:joba priority 60jobb priority 50end

If the job stream priorities were the same, the jobs would be launched in the followingorder: joba, jobb, job1, job2.

84 Version 8.1

prompt

Specifies prompts that must be answered affirmatively before a job or job stream islaunched.

Synopsisprompt promptname [,...]

prompt ″[: | !]text″ [...]

Argumentspromptname Specifies the name of a prompt in the database.

text Specifies a literal prompt as a text string enclosed in quotes (″). Multiplestrings separated by backlash n (\n) can be used for long messages. If thestring begins with a colon (:), the message is displayed but no reply isnecessary. If the string begins with an exclamation point (!), the message isnot displayed but it requires a reply. You can include backslash n (\n) withinthe text for new lines.

You can use one or more parameters as part or all of the text string. To usea parameter, place its name between carets (^).

Note: Within a local prompt, when not designating a parameter, carets (^)must be preceded by a backslash (\) or they will cause errors in theprompt. Within global prompts, carets do not have to be preceded bya backslash.

ExamplesThe following example illustrates both literal and named prompts. The first prompt is aliteral prompt that uses a parameter named sys1. When a single affirmative reply is receivedfor the named prompt apmsg, the dependencies for both job1 and job2 are satisfied.schedule sked3 on tu,th

prompt "All ap users logged out of ^sys1^? (y/n)":

job1 prompt apmsgjob2 prompt apmsg

end

The following example defines a literal prompt that will appear on more than one line. It isdefined with backlash n (\n) at the end of each line:schedule sked5 on fr

prompt "The jobs in this job stream consume \nan enormous amount of cpu time.\nDo you want to launch it now? (y/n)":

j1j2 follows j1

end


3.S

ched

ulin

gL

ang

uag

e

schedule

Specifies the job stream name. With the exception of comments, this must be the firstkeyword in a job stream, and must be followed by the on keyword.

Synopsisschedule [wkstation#]jstreamname on ...

Argumentswkstation Specifies the name of the workstation on which the job stream is launched.

The default is the workstation on which Composer runs to add the jobstream.

jstreamname

Specifies the name of the job stream. The name must start with a letter, andcan contain alphanumeric characters and dashes. For non-expandeddatabases, it can contain up to eight characters. For expanded databases, itcan contain up to 16 characters.

on

Specifies when, or how often, the job stream is selected for execution. See“on” on page 79 for more information.

ExamplesThe following example names a job stream sked1 that runs on the workstation on whichComposer is running:schedule sked1 on tu

The following example names a job stream sked-2 that runs on the workstation on whichComposer is running:schedule sked-2 on everyday except fr

The following example names a job stream skedux7 that runs on workstation hpux3:schedule hpux3#skedux7 on monthend

86 Version 8.1

until

Specifies the latest time a job or job stream will be launched.

Synopsisuntil time [timezone|tz tzname][+n day[s]]

Argumentstime Specifies the time of day. The possible values are 0000 through 2359.

tznameSpecifies the time zone to be used when computing the time. See “Time ZoneNames and Descriptions” on page 285 for time zone names. The default is the timezone of the workstation on which the job or job stream is launched.

Note: If an until time and an at time are specified, the time zones must be thesame.

n Specifies an offset, in days, from the scheduled date and time.

ExamplesThe following example prevents sked1 from launching after 5:00 P.M. on Tuesdays:schedule sked1 on tu until 1700 :

The following example launches job1 between 1:00 P.M. and 5:00 P.M. on weekdays:schedule sked2 on weekdays :

job1 at 1300 until 1700end

The following example launches joba every 15 minutes between 10:30 P.M. and 11:30 P.M.on Mondays:schedule sked3 on mo :

joba at 2230 every 0015 until 2330end

The following example launches job stream sked4 on Sundays between 8:00 A.M. and 1:00P.M. The jobs are also be launched within this interval:schedule sked4 on fr at 0800 + 2 days

until 1300 + 2 days:

job1job2 at 0900 <<launched on sunday>>job3 follows job2 at 1200 <<launched on sunday>>

end


3.S

ched

ulin

gL

ang

uag

e

88 Version 8.1

Conman Reference

The Workload Scheduler production plan environment is managed with the Conmanprogram. Conman is used to start and stop processing, alter, and display the production plan(Symphony), and control workstation linking in a network. This chapter contains informationabout the following:

¶ Running Conman

¶ Selecting and qualifying jobs and job streams

¶ The syntax and usage for Conman commands

Running ConmanTo run Conman, enter the following command:conman [“command[&...][&]"]

ExamplesIn the following example, Conman starts and prompts for a command:conman

In the following example, Conman executes the sj and sp commands, and then quits:conman"sj&sp"

In the following example, Conman executes the sj and sp commands, and then prompts fora command:conman"sj&sp&"

In the following example, Conman reads commands from cfile:conman < cfile

In the following example, commands from cfile are piped to Conman:cat cfile | conman

Control CharactersYou can enter the following control characters to interrupt Conman.

Control+cConman stops executing the current command at the next step that can beinterrupted, and returns a command prompt.

Control+dConman quits after executing the current command.

4


4.C

on

man

Referen

ce

Executing System CommandsWhen a system command is entered using a pipe or a system command prefix (: or !), it isexecuted by a child process. The child process’s effective user ID is set to the ID of the userrunning Conman to prevent security breaches.

User PromptingWhen you use wildcard characters to select the objects to be acted upon by a command,Conman prompts for confirmation after finding each matching object. Responding with yesallows the action to be taken, and no skips the object without taking the action.

When Conman is run interactively, the confirmation prompts are issued at your computer.Pressing the Return key in response to a prompt is interpreted as a no response. Promptingcan be disabled by including the ;noask option in a command.

Although no confirmation prompts are issued when Conman is not running in interactivemode, it acts as though the response had been no in each case, and no objects are acted on.It is important, therefore, to include the ;noask option on commands when Conman is notrun in interactive mode.

Terminal OutputThe output to your computer is specified by shell variables named MAESTROLINES andMAESTROCOLUMNS. If either is not set, the standard shell variables, LINES andCOLUMNS, are used. The variables can be set as follows:

$MAESTROLINESSpecifes the number of lines per screen. The default is 24. At the end of each screenpage, Conman prompts to continue. If MAESTROLINES (or LINES) is set to zeroor a negative number, Conman does not pause at the end of a page.

$MAESTROCOLUMNSSpecifes the number of characters per line. The default is 80.

$MAESTRO_OUTPUT_STYLESpecifes the method of displaying object names. If set to LONG, full names aredisplayed. If not set, or set to any value other than LONG, and the global optionexpanded version is set to yes, long names are truncated to eight charactersfollowed by a plus sign (+). If expanded version is set to no, long names aretruncated to eight characters.

Offline OutputThe ;offline option in Conman commands is generally used to print the output of acommand. When you include it, the following shell variables control the output:

$MAESTROLPSpecifies the destination of a command’s output. Set it to one of the following:

> file Redirects output to a file and overwrites the contents of the file. If the filedoes not exist, it is created.

>> fileRedirects output to a file and appends the output to the end of the file. If thefile does not exist, it is created.

| commandPipes output to a system command or process. The system command isexecuted whether or not output is generated.

90 Version 8.1

|| commandPipes outut to a system command or process. The system command is notexecuted if there is no output.

The default is | lp -tCONLIST which pipes the command output to the printer andplaces the title “CONLIST” in the printout’s banner page.



The variables must be exported before running Conman.

Selecting the Conman Command PromptThe conman command prompt is, by default, a percent sign (%). This is defined in theTWShomelocalopts file. The default command prompt is a dash (-). To select a differentprompt, edit the conman prompt option in the localopts file and change the dash. Theprompt can be up to ten characters long, not including the required trailing pound sign (#).

#----------------------------------------------------------------------------# Custom format attributes#date format = 1 # The possible values are 0-ymd, 1-mdy,2-dmy, 3-NLS.composer prompt = -conman prompt = %switch sym prompt = <n>%#----------------------------------------------------------------------------

Command SyntaxConman commands consist of the following elements:

commandname selection arguments

where:

commandnameSpecifies the command name.

selectionSpecifies the object or set of objects to be acted upon.

argumentsSpecifies the command arguments.

The following is an example of a Conman command:sj sked1.@+state=holdxpriority=0;info;offline

where:

sj The abbreviated form of the showjobs command.

sked1.@+state=holdxpriority=0Selects all jobs in the job stream sked1 that are in the hold state with a priorityother than zero.


4.C

on

man

Referen

ce

;info;offlineArguments for the showjobs command.

Wildcard CharactersThe following wildcard characters are permitted:

@ Replaces one or more alphanumeric characters.

? Replaces one alphabetic character.

% Replaces one numeric character.

Delimiters and Special CharactersThe following characters have special meanings in Conman commands:

Char. Description

& Command delimiter. See “Running Conman” on page 89.

+ A delimiter used to select objects for commands. It adds an attribute the object musthave. For example:

sked1.@+priority=0

x A delimiter used to select objects for commands. It adds an attribute the object mustnot have. For example:

sked1.@xpriority=0

; Argument delimiter. For example:

;info;offline

, Repetition and range delimiter. For example:

state=hold,sked,pend

= Value delimiter. For example:

state=hold

: ! Command prefixes that pass the command on to the system. These prefixes areoptional; if Conman does not recognize the command, it is passed automatically to thesystem. For example:

!ls or :ls

<<>> Comment brackets. For example:

sj @#@.@ <<comment>>

* Comment prefix. The prefix must be the first character on a command line orfollowing a command delimiter. For example:

*comment

or

sj& *comment

> Redirects command output to a file and overwrites the contents of the file. If the filedoes not exist, it is created. For example:

sj> joblist

>> Redirects command output to a file and appends the output to the end of file. If thefile does not exist, it is created. For example:

sj >> joblist

| Pipes command output to a system command or process. The system command isexecuted whether or not output is generated. For example:

sj| grep ABEND

92 Version 8.1

Char. Description

|| Pipes command output to a system command or process. The system command is notexecuted if there is no output. For example:

sj || grep ABEND

List of CommandsThe following table lists the Conman command set. Command names and keywords can beentered in either uppercase or lowercase characters, and can be abbreviated to as few leadingcharacters as are needed to distinguish them from each other. Some of the command namesalso have short forms.

Command Short Form Description Type1 Page

adddep adj | ads Adds job or job streamdependencies.

M,F 106, 107

altpass Alters a User object definitionpassword.

M,F 108

altpri ap Alters job or job stream priorities. M,F 109

cancel cj | cs Cancels a job or a job stream. M,F 110, 112

confirm Confirms job completion. M,F 113

console Assigns the Workload Schedulerconsole.

M,F,A 114

continue Ignores the next error. M,F,A 115

deldep ddj | dds Deletes job or job streamdependencies.

M,F 116, 117

display df | dj | ds Displays files, jobs, and jobstreams.

M,F,A2 118

exit Terminates Conman. M,F,A 119

fence Sets Workload Scheduler jobfence.

M,F,A 120

help5 Displays command information. M,F,A 121

kill Stops an executing job. M,F 122

limit lc | ls Changes a workstation or jobstream job limit.

M,F,A3 123, 124

link lk Opens workstation links. M,F,A 125

listsym Displays a list of Symphony logfiles.

M,F 127

recall rc Displays prompt messages. M,F 128

redo Edits the previous command. M,F,A 129

release rj | rs Releases job or job streamdependencies.

M,F 130, 132

reply Replys to prompt message. M,F 134

rerun rr Reruns a job. M,F 135

resource Changes the number of resourceunits.

M,F 138

setsym Selects a Symphony log file. M,F 139


4.C

on

man

Referen

ce

Command Short Form Description Type1 Page

showcpus sc Displays workstation and linkinformation.

M,F,A 140

showdomain Displays domain information. M,F,A 143

showfiles sf Displays information about files. M,F 144

showjobs sj Displays information about jobs. M,F 146

showprompts sp Displays information aboutprompts.

M,F 152

showresources sr Displays information aboutresources.

M,F 154

showschedules ss Displays information about jobstreams.

M,F 156

shutdown Stops Workload Schedulerproduction processes.

M,F,A 159

start Starts Workload Schedulerproduction processes.

M,F,A 160

status Displays Workload Schedulerproduction status.

M,F,A 162

stop Stops Workload Schedulerproduction processes.

M,F,A 163

submit sbd | sbf |sbj | sbs

Submits a command, file, job, orjob stream.

M,F,A4 165,167,169,171

switchmgr Switches the domain manager. M,F 173

sys-command Sends a command to the system. M,F,A 174

tellop to Sends a message to the console. M,F,A 175

unlink Closes workstation links. M,F,A 176

version v Displays Conman’s programbanner.

M,F,A 178

1. Workstation types: domain managers (M), fault-tolerant agents (F), standard agents (S).

2. You can display only files on a standard agent.

3. You can change the limit of only workstations on a standard agent.

4. You can use submit job (sbj) and submit sched (sbs) on a standard agent only if themozart directory on the master domain manager is accessible to the standard agent.

5. Not available on Windows NT.

Selecting Jobs in CommandsFor commands that operate on jobs, the target jobs are selected by means of attributes andqualifiers. The job selection syntax is shown below, and described on the following pages.

Synopsis[wkstation#] {jobstream.job | jobnumber} [+ | xjobqualifier[...]]

or:

94 Version 8.1

netagent::[wkstation#] jobstream.job

Argumentswkstation

When used with jobstream.job, this specifies the name of the workstation on whichthe job stream runs. When used with jobnumber, it specifies the workstation onwhich the job runs. Wildcard characters are permitted.

jobstreamSpecifies the name of the job stream in which the job runs. Wildcard characters arepermitted.

job Specifies the name of the job. Wildcard characters are permitted.

jobnumberSpecifies the job number.

jobqualifierSee the following section, “Job Qualifiers”.

netagentSpecifies the name of the scheduler network agent that interfaces with the remotescheduler network containing the target job. The two colons (::) are a requireddelimiter. Wildcard characters are permitted. For more information refer to “NetworkAgent Reference” on page 245.

Job QualifiersJob qualifiers specify attributes of jobs to be acted on by a command. They are prefixed bya + or a ˜. A + means that jobs with the attribute qualify for the command. A ˜ means thatjobs with the attribute are excluded from the commanded.

Job qualifier keywords can be abbreviated to as few leading characters as needed todistinguish one from another.

at[=time | lowtime | hightime | lowtime,hightime]Selects or excludes jobs based on scheduled start time.

time

Specifies the scheduled start time expressed as follows:

hhmm[+n days | date] [timezone|tz tzname]

where:

hhmm The hour and minute.

+n daysThe next occurrence of hhmm in n number of days.

date The next occurrence of hhmm on date, expressed as mm/dd/yy.

timezone|tz tznameThe name of the time zone of the job. See “Time Zone Names andDescriptions” on page 285 for valid names.

time comforms to the following rules:

¶ When hhmm is earlier than the current time, the start time is today;when hhmm is later than the current time, the start time is tomorrow.


|

|

||

||

||

|||

|

||

4.C

on

man

Referen

ce

¶ When hhmm is greater than 2400, it is divided by 2400. Of the result,the whole part represents the number of + days, while the decimal partrepresents the time.

lowtimeSpecifies the lower limit of a time range, expressed in the same format astime. Jobs are selected that have scheduled start times on or after this time.

hightimeSpecifies the upper limit of a time range, expressed in the same format astime. Jobs are selected that have scheduled start times on or before this time.

If at is used alone, the range is open-ended, and jobs are selected or excluded ifthey have any scheduled start time.

confirmedSelects or excludes jobs that were scheduled using the confirm keyword.

every[=rate | lowrate, | ,highrate | lowrate,highrate]Selects or excludes jobs based in whether or not they have a repetition rate.

rate Specifies the scheduled execution rate, expressed as hours and minutes(hhmm).

lowrateSpecifies the lower limit of a rate range, expressed in the same format asrate. Jobs are selected that have repitition rates equal to or greater than thisrate.

highrateSpecifies the upper limit of a rate range, expressed in the same format asrate. Jobs are selected that have repitition rates less than or equal to thisrate.

If every is used alone, the range is open-ended, and jobs are selected or excluded ifthey have any repetition rate.

finished[=time | lowtime, | ,hightime | lowtime,hightime]Selects or excludes jobs based on whether or not they have finished.

time Specifies the exact time the jobs finished, expressed as follows:

hhmm [date] [timezone|tz tzname]




lowtimeSpecifies the lower limit of a time range, expressed in the same format astime. Jobs are selected that finished at or after this time.

hightimeSpecifies the upper limit of a time range, expressed in the same format astime. Jobs are selected that finished at or before this time.

96 Version 8.1

|||

If finished is used alone, the range is open-ended, and jobs are selected or excludedif they have finished executing.

follows[=[netagent::][[wkstation#] jobstream.]job]Selects or excludes jobs based on whether or not they have a follows dependency.

wkstationSpecifies the name of the workstation on which the prerequisite job runs.Wildcard characters are permitted.

jobstreamSpecifies the name of the job stream in which the prerequisite job runs.Wildcard characters are permitted. If you enter jobstream.@, you specify thatthe target job follows all jobs in the job stream.

job Specifies the name of the prerequisite job. When entered without ajobstream, it means that the prerequisite job is in the same job stream as thetarget job. Wildcard characters are permitted.

netagentSpecifies the name of the scheduler network agent that interfaces with theremote scheduler network containing the prerequisite job. Wildcardcharacters are permitted. For more information refer to “Network AgentReference” on page 245.

If follows is used alone, jobs are selected or excluded if they have any followsdependencies.

logon=usernameSelect jobs based on the user names under which they run. If username containsspecial characters it must be enclosed in quotes (″). Wildcard characters arepermitted.

needs[=[wkstation#]resourcename]Selects or excludes jobs based on whether or not they have a resource dependency.

wkstationSpecifies the name of the workstation on which the resource is defined.Wildcard characters are permitted.

resourcenameSpecifies the name of the resource. Wildcard characters are permitted.

If needs is used alone, jobs are selected or excluded if they have any resourcedependency.

opens[=[wkstation#]filename[(qualifier)]]Select jobs based on whether or not they have a file dependency.

wkstationSpecifies the name of the workstation on which the file exists. Wildcardcharacters are permitted.

filenameSpecifies the name of the file. The name must be enclosed in quotes (″) if itcontains characters other than the following: alphanumerics, dashes (-),slashes (/), backslashes (\), and underscores (_). Wildcard characters arepermitted.


4.C

on

man

Referen

ce

qualifierA valid test condition. If omitted, jobs are selected or excluded withoutregard to a qualifier.

If opens is used alone, jobs are selected or excluded if they have any filedependency.

priority=pri | lowpri, | ,highpri | lowpri,highpriSelects or excludes jobs based on their priorities.

pri Specifies the priority value. You can enter 0 through 99, hi or go.

lowpri Specifies the lower limit of a priority range. Jobs are selected with prioritiesequal to or greater than this value.

highpriSpecifies the upper limit of a priority range. Jobs are selected with prioritiesless than or equal to this value.

prompt[=promptname | msgnum]Selects or excludes jobs based on whether or not they have a prompt dependency.

promptnameSpecifies the name of a global prompt. Wildcard characters are permitted.

msgnumSpecifies the message number of a local prompt.

If prompt is used alone, jobs are selected or excluded if they have any promptdependency.

recovery=recv-optionSelects or excludes jobs based on their recovery options.

recv-optionSpecifies the job recovery option as stop, continue, or rerun.

scriptname=filenameSelects or excludes jobs based on their executable file names.

filenameSpecifies the name of an executable file. The name must be enclosed inquotes (″) if it contains characters other than the following: alphanumerics,dashes (-), slashes (/), backslashes (\), and underscores (_). Wildcardcharacters are permitted.

started[=time | lowtime, | ,hightime | lowtime,hightime]Selects or excludes jobs based on whether or not they have started.

time Specifies the exact time the jobs started, expressed as follows:





98 Version 8.1

lowtimeSpecifies the lower limit of a time range, expressed in the same format astime. Jobs are selected that started at or after this time.

hightimeSpecifies the upper limit of a time range, expressed in the same format astime. Jobs are selected that started at or before this time.

If started is used alone, the range is open-ended, and jobs are selected or excludedif they have started.

state=state[,...]Selects or excludes jobs based on their states.

state Specifies the current state of the job. Valid job states are as follows:

abend The job terminated with a non-zero exit code.

abenp An abend confirmation was received, but the job is not completed.

add The job is being submitted.

done The job completed in an unknown state.

error For internetwork dependencies only, an error occurred whilechecking for the remote status.

exec The job is executing.

extrn For internetwork dependencies only, the status is unknown. An erroroccurred, a rerun action was just performed on the job in theexternal job stream, or the remote job or job stream does not exist.

fail Unable to launch the job.

fence The job’s priority is below the fence.

hold The job is awaiting dependency resolution.

intro The job is introduced for launching by the system.

pend The job completed, and is awaiting confirmation.

ready The job is ready to launch, and all dependencies are resolved.

sched The job’s at time has not arrived.

succ The job completed with an exit code of zero.

succp A succ confirmation was received, but the job is not completed.

susp The job was suspended by a breakjob command. (MPE only)

wait The job is in the wait state. (Extended agent and MPE only)

waitd The job is in the wait state, and is deferred. (MPE only)

until[=time | lowtime, | ,hightime | lowtime,hightime]Selects or excludes jobs based on their scheduled end time.

time Specifies the scheduled end time expressed as follows:




4.C

on

man

Referen

ce




lowtimeSpecifies the lower limit of a time range, expressed in the same format astime. Jobs are selected that have scheduled end times on or after this time.

hightimeSpecifies the upper limit of a time range, expressed in the same format astime. Jobs are selected that have scheduled end times on or before this time.

If until is used alone, the range is open-ended, and jobs are selected or excluded ifthey have any scheduled end time.

Selecting Job Streams in CommandsFor commands that operate on job streams, the target job streams are selected by means ofattributes and qualifiers. The job stream selection syntax is shown below, and described onthe following pages.

Synopsis[wkstation#] jobstream [+ | xjobstreamqual[...]]

Argumentswkstation

Specifies the name of the workstation on which the job stream runs. Wildcardcharacters are permitted.

jobstreamSpecifies the name of the job stream. Wildcard characters are permitted.

jobstreamqualSee “Job Stream Qualifiers” below.

Job Stream Qualifiersat[=time | lowtime, | ,hightime | lowtime,hightime]

Selects or excludes job streams based on scheduled start time.

time Specifies the scheduled start time expressed as follows:





timezone|tz tznameThe name of the time zone of the job stream. See “Time ZoneNames and Descriptions” on page 285 for valid names.

100 Version 8.1

|

|

lowtimeSpecifies the lower limit of a time range, expressed in the same format astime. Job streams are selected that have scheduled start times on or after thistime.

hightimeSpecifies the upper limit of a time range, expressed in the same format astime. Job streams are selected that have scheduled start times on or beforethis time.

If at is used alone, the range is open-ended, and job streams are selected or excludedif they have any scheduled start time.

carriedforwardSelects or excludes job streams that were carried forward.

carryforwardSelects or excludes job streams that were scheduled using the carryforwardkeyword.

finished[=time | lowtime, | ,hightime | lowtime,hightime]Selects or excludes job streams based on whether or not they have finished.

time Specifies the exact time the job streams finished, expressed as follows:





lowtimeSpecifies the lower limit of a time range, expressed in the same format astime. Job streams are selected that finished at or after this time.

hightimeSpecifies the upper limit of a time range, expressed in the same format astime. Job streams are selected that finished at or before this time.

If finished is used alone, the range is open-ended, and job streams are selected orexcluded if they have finished executing.

follows[=[netagent::][wkstation#] jobstream[.job]Selects or excludes job streams based on whether or not they have a followsdependency.

netagentSpecifies the name of the network agent that interfaces with the remotescheduler network containing the prerequisite job or job stream. Wildcardcharacters are permitted. For more information about network agents, refer to“Network Agent Reference” on page 245.

wkstationSpecifies the name of the workstation on which the prerequisite job or jobstream runs. Wildcard characters are permitted.


4.C

on

man

Referen

ce

jobstreamSpecifies the name of the prerequisite job stream. Wildcard characters arepermitted.

job Specifies the name of the prerequisite job. Wildcard characters are permitted.

If follows is used alone, job streams are selected or excluded if they have anyfollows dependency.

limit[=limit | lowlimit, | ,highlimit | lowlimit,highlimit]Selects or excludes job streams based on whether or not they have a job limit.

limit Specifies the exact job limit value.

lowlimitSpecifies the lower limit of range. Job streams are selected that have joblimits equal to or greater than this limit.

highlimitSpecifies the upper limit of a range. Job streams are selected that have joblimits less than or equal to this limit.

If limit is used alone, the range is open-ended, and job streams are selected orexcluded if they have any job limit.

needs[=[wkstation#]resourcename]Selects or excludes job streams based on whether or not they have a resourcedependency.

wkstationSpecifies the name of the workstation on which the resource is defined.Wildcard characters are permitted.

resourcenameSpecifies the name of the resource. Wildcard characters are permitted.

If needs is used alone, job streams are selected or excluded if they have anyresource dependency.

opens[=[wkstation#]filename[(qualifier)]]Selects or excludes job streams based on whether or not they have a filedependency.

wkstationSpecifies the name of the workstation on which the file exists. Wildcardcharacters are permitted.

filenameSpecifies the name of the file. The name must be enclosed in quotes (″) if itcontains characters other than the following: alphanumerics, dashes (-),slashes (/), backslashes (\), and underscores (_). Wildcard characters arepermitted.

qualifierA valid test condition. If omitted, job streams are selected or excludedwithout regard to a qualifier.

102 Version 8.1

If opens is used alone, job streams are selected or excluded if they have any filedependency.

priority=pri | lowpri, | ,highpri | lowpri,highpriSelects or excludes job streams based on their priorities.

pri Specifies the priority value. You can enter 0 through 99, hi or go.

lowpri Specifies the lower limit of a priority range. Job streams are selected withpriorities equal to or greater than this value.

highpriSpecifies the upper limit of a priority range. Job streams are selected withpriorities less than or equal to this value.

prompt[=promptname | msgnum]Selects or excludes job streams based on whether or not they have a promptdependency.


msgnumSpecifies the message number of a local prompt.

If prompt is used alone, job streams are selected or excluded if they have anyprompt dependency.

started[=time | lowtime, | ,hightime | lowtime,hightime]Selects or excludes job streams based on whether or not they have started.

time Specifies the exact time the job streams started, expressed as follows:





lowtimeSpecifies the lower limit of a time range, expressed in the same format astime. Job streams are selected that started at or after this time.

hightimeSpecifies the upper limit of a time range, expressed in the same format astime. Job streams are selected that started at or before this time.

If started is used alone, the range is open-ended, and job streams are selected orexcluded if they have started executing.

state=state[,...]Selects or excludes job streams based on their states.

state Specifies the current state of the job stream. Valid job stream states are asfollows:

abend The job stream terminated abnormally.


4.C

on

man

Referen

ce

add The schedule has just been submitted.

exec The job stream is executing.

hold The job stream is awaiting dependency resolution.

ready The job stream is ready to launch, and all dependencies resolved.

stuck Execution is interrupted. No jobs are launched without operatorintervention.

succ The job stream completed successfully.

until[=time | lowtime, | ,hightime | lowtime,hightime]Selects or excludes job streams based on scheduled end time.

time Specifies the scheduled end time expressed as follows:






lowtimeSpecifies the lower limit of a time range, expressed in the same format astime. Job streams are selected that have scheduled end times on or after thistime.

hightimeSpecifies the upper limit of a time range, expressed in the same format astime. Job streams are selected that have scheduled end times on or beforethis time.

If until is used alone, the range is open-ended, and job streams are selected orexcluded if they any scheduled end time.

Command DescriptionsThe following pages contain detailed descriptions of Conman commands.

Note: In the commands, the terms sched and schedule refer to job streams, and the term cpurefers to workstations.

Conman Command ProcessingWhen using various commands, you should be aware of the way in which conmancommands are processed.

When you change the dependencies of a job or a schedule in the symphony, conman stopsthe dependencies from being inserted by preventing the relevant command being forwardedto batchman. However, it is possible that it might appear that such a change has notcompleted successfully, despite the fact that it has done so.

104 Version 8.1

|

|

||

||||

The reason for this is because conman does not write directly to the symphony, but asksbatchman to do so instead. Batchman receives a sequence of events as they occur on eachsystem in the network, and in the same sequence as they occur. As batchman processes theseevents, the symphony states change around the scheduler network. If a batchman should bebusy for any reason, conman commands are queued and the symphony is not updated untilsuch time as the batchman reads the commands from the mailbox and processes them. Inthis way, a conman command could perform different actions, depending when it isprocessed.

In addition, when batchman processes the event, the operator is not notifed. As a result, youcould delete a dependency and it might appear that it had not been deleted becausebatchman was busy. If you run the command again, the deletion might have been successful,even though a message is displayed saying that the command has been forwarded tobatchman.


||||||||

|||||

4.C

on

man

Referen

ce

adddep jobAdds dependencies to a job.

You must have adddep access to the job. To include needs and prompt dependencies, youmust have use access to the resources and global prompts.

Synopsisadj jobselect[;dependency[;...]][;noask]

Argumentsjobselect

See “Selecting Jobs in Commands” on page 94.

dependencyThe type of dependency. Specify one of the following. Wildcard characters are notpermitted.

at=hhmm[timezone | tz tzname][+n days | mm/dd/yy]

confirmed

every=rate

follows=[netagent::][wkstation#]jstream{.job | @} | job[,...]

needs=[num] [wkstation#]resource[,...]

opens=[wkstation#]″filename″[(qualifier)][,...] priority[=pri | hi | go]

prompt=″[: | !]text″ | promptname[,...]

until=hhmm[timezone | tz tzname][+n days | mm/dd/yy]

noask Specifies not to prompt for confirmation before taking action on each qualifying job.

Usage NotesIf you do not specify a value for priority, the job reverts to its original scheduled priority. Ifyou do not specify a workstation in follows, needs, or opens, the default is the workstationon which the job runs. To add prompt dependencies while running Conman on a faulttolerant agent, you must have access to the WShome/mozart directory on the master domainmanager.

ExamplesThe following example adds a resource dependency to job3 in job stream sked9:adddep sked9.job3;needs=2 tapes

The following example adds a file dependency, and an until time to job6 in job streamsked2:adj sked2.job6;opens="/usr/lib/prdata/file5"(-s %p);until=2330

106 Version 8.1

|

|

adddep schedAdds dependencies to a job stream.

You must have adddep access to the job stream. To include needs and promptdependencies, you must have use access to the resources and global prompts.

Synopsisads jstreamselect[;dependency[;...]][;noask]

Argumentsjstreamselect

See “Selecting Job Streams in Commands” on page 100.

dependencyThe type of dependency. Specify one of the following. Wildcard characters are notpermitted.

at=hhmm[timezone | tz tzname][+n days | mm/dd/yy]

carryforward


limit=limit




until=hhmm[timezone | tz tzname][+n days | mm/dd/yy]

noask Specifies not to prompt for confirmation before taking action on each qualifying jobstream.

Usage Notes¶ If you do not specify a value for priority, the job stream reverts to its original

scheduled priority.

¶ If you do not specify a value for limit, the value defaults to 0.

¶ If you do not specify a workstation in follows, needs, or opens, the default is theworkstation on which the job stream runs.

¶ To add prompt dependencies while running Conman on a fault tolerant agent, you musthave access to the WShome/mozart directory on the master domain manager.

ExamplesThe following example adds a prompt dependency to job stream sked3:adddep sched=sked3;prompt=msg103

The following example adds a follows dependency and a job limit to job stream sked4:ads sked4;follows=sked3;limit=2


|

4.C

on

man

Referen

ce

altpassAlters the password of a user object in the current production plan.

You must have altpass access to the user object.

Synopsisaltpass [wkstation#]username[;″password″]

Argumentswkstation Specifies the workstation on which the user is defined. The default is the

workstation on which you are running Conman.

username Specifies the name of a user.

password Specifies the new password. It must be enclosed in quotes. To indicate nopassword for the user, use two consecutive quotes (″″).

Usage NotesIf you do not specify a password, Conman prompts for a password and a confirmation. Inthis case, the password is not displayed as it is entered and should not be enclosed in quotes.Note that the change is made only in the current production plan, and is therefore temporary.To make a permanent change see “User Definitions” on page 28.

ExamplesThe following example changes the password of user jim on workstation mis5 to giraffe:altpass mis5#jim;”giraffe”

The following example changes the password of user jim on workstation mis5 to giraffewithout displaying the password:altpass mis5#jimpassword: xxxxxxxxconfirm: xxxxxxxx

108 Version 8.1

altpriAlters the priority of a job or job stream.

You must have altpri access to the job or job stream.

Synopsisap jobselect | jstreamselect[;pri][;noask]

Argumentsjobselect See “Selecting Jobs in Commands” on page 94.

jstreamselect See “Selecting Job Streams in Commands” on page 100.

pri Specifies the priority level. You can enter a value of 0 through 99, hi, or go.

noask Specifies not to prompt for confirmation before taking action on eachqualifying job or job stream.

ExamplesThe following example changes the priority of the balance job in job stream glmonth:altpri glmonth.balance;55

The following example changes the priority of all jobs in job stream mis5:ap mis5.@;25

The following example changes the priority of job stream glmonth:altpri glmonth;10

The following example changes the priority of job stream mis5:ap mis5;30


4.C

on

man

Referen

ce

cancel jobCancels a job.

You must have cancel access to the job.

Synopsiscj jobselect[;pend][;noask]


pend Cancels the job only after its dependencies are resolved.

noask Specifies not to prompt for confirmation before taking action on eachqualifying job.

Usage NotesIf a job is cancelled before it is launched, it will not launch. If you cancel a job after it islaunched, the job continues to execute. If an executing job is cancelled and it completes inthe abend state, no automatic job recovery steps are attempted.

If you do not use the ;pend option, jobs and job streams that are dependent on the cancelledjob are released immediately from the dependency.

If you include the ;pend option, and the job has not been launched, cancellation is deferreduntil all of the dependencies, including an at time, are resolved. Once all the dependenciesare resolved, the job is cancelled and any jobs or job streams that are dependent on thecancelled job are released from the dependency. During the period the cancel is deferred, thenotation [Cancel Pend] is listed in the Dependencies column of the job in a showjobsdisplay.

If you include the ;pend option and the job has already been launched, the option isignored, and any jobs or job streams that are dependent on the cancelled job are immediatelyreleased from the dependency.

You can use the rerun command to rerun jobs that have been cancelled, or that are marked[Cancel Pend]. You can also add and delete dependencies on jobs that are marked [CancelPend].

To immediately cancel a job that is marked [Cancel Pend], you can either enter a releasecommand for the job or enter another cancel command without the ;pend option.

For jobs with expired until times, the notation [Until] is listed in the Dependencies columnin a showjobs display, and their dependencies are no longer evaluated. If such a job is alsomarked [Cancel Pend], it is not cancelled until you release or delete the until time, or enteranother cancel command without the ;pend option.

To stop evaluating dependencies, set the priority of a job to zero with the altpri command.To resume dependency evaluation, set the priority to a value greater than zero.

Note: In the case of internetwork dependencies, cancelling a job in the external job streamreleases all local jobs and job streams from the dependency. Jobs in the external jobstream represent jobs and job streams that have been specified as internetwork

110 Version 8.1

dependencies. The status of an internetwork dependency is not checked after a cancelis performed. For more information see “Internetwork Dependencies” on page 247.

ExamplesThe following example cancels job report in job stream apwkly on workstation site3:cancel site3#apwkly.report

The following example cancels job setup in job stream mis5 if it is not in the abend state:cj mis5.setupxstate=abend

The following example cancels job job3 in job stream sked3 only after its dependencies areresolved:cj sked3.job3;pend


4.C

on

man

Referen

ce

cancel schedCancels a job stream.

You must have cancel access to the job stream.

Synopsiscs jstreamselect[;pend][;noask]

Argumentsjstreamselect See “Selecting Job Streams in Commands” on page 100.

pend Cancels the job stream only after its dependencies are resolved.

noask Specifies not to prompt for confirmation before taking action on eachqualifying job stream.

Usage NotesIf a job stream is cancelled before it is launched, it will not launch. If cancelled after it islaunched, jobs that have started are allowed to complete, but no other jobs are launched.

If you do not use the ;pend option, jobs and job streams that are dependent on the cancelledjob stream are released immediately from the dependency.

If you use the ;pend option and the job stream has not been launched, cancellation isdeferred until all of its dependencies, including an at time, are resolved. Once alldependencies are resolved, the job stream is cancelled and any dependent jobs or job streamsare released from the dependency. During the period the cancel is deferred, the notation[Cancel Pend] is listed in the Dependencies column of a showschedules display.

If you include the ;pend option and the job stream has already been launched, anyremaining jobs in the job stream are cancelled, and any dependent jobs and job streams arereleased from the dependency.

To immediately cancel a job stream marked [Cancel Pend], either enter a release commandfor the job stream or enter another cancel command without the ;pend option.

For job streams with expired until times, the notation [Until] appears in the Dependenciescolumn of the showschedules display and their dependencies are no longer evaluated. Ifsuch a job stream is also marked [Cancel Pend], it is not cancelled until you release ordelete the until time or enter another cancel command without the ;pend option.

To stop evaluating of dependencies, set the job stream’s priority to zero with the altpricommand. To resume dependency evaluation, set the priority to a value greater than zero.

ExamplesThe following example cancels job stream sked1 on workstation site2:cancel site2#sked1

The following example cancels job stream mis2 if it is in the stuck state:cs mis2+state=stuck

The following example cancels job stream sked3 only after its dependencies are resolved:cs sked3;pend

112 Version 8.1

confirmConfirms the completion of a job that was scheduled with the confirmed

keyword. An exception is noted in the “Usage Notes” section.

You must have confirm access to the job.

Synopsisconfirm jobselect;{succ | abend}[;noask]


succ Confirms that the job ended successfully.

abend Confirms that the job ended unsuccessfully.


Usage NotesChanging the state of a job from abend to succ does not require that the confirmedkeyword be used to schedule the job. For more information about job confirmation, see“confirmed” on page 65. For more information about external jobs, see “InternetworkDependencies” on page 247.

The following table shows the affect of the confirm command on the various states of jobs:

Initial Job State State after confirm ;succ State after confirm ;abend

ready no affect no affect

hold no affect no affect

exec succp abenp

abenp succp no affect

succp no affect no affect

pend succ abend

done succ abend

succ no affect no affect

abend succ no affect

fail no affect no affect

susp no affect no affect

skel no affect no affect

any external job succ abend

ExamplesThe following example issues a succ confirmation for job3 in job stream misdly:confirm misdly.job3;succ

The following example issues an abend confirmation to job number 234:conf 234;abend


4.C

on

man

Referen

ce

consoleAssigns the scheduler console and sets the message level.

You must have console access to the workstation.

Synopsisconsole [sess | sys][;level=msglevel]

Argumentssess Sends scheduler console messages and prompts to standard output.

sys Stops sending scheduler console messages and prompts to standard output.This occurs automatically when you exit Conman.

msglevel The level of scheduler messages that are sent to the console. Specify one ofthe following levels:

0 No messages. This is the default on fault-tolerant agents.

1 Exception messages such as operator prompts, and job abends.

2 Level 1, plus job stream successful messages.

3 Level 2, plus job successful messages. This is the default on themaster domain manager.

4 Level 3, plus job launched messages.

Usage NotesIf you enter the console command with no options, the current state of the console isdisplayed.

By default, scheduler control processes write console messages and prompts to standard listfiles. On UNIX, you can also have them sent to the syslog daemon.

ExamplesThe following example begins writing console messages and prompts to standard output andchanges the message level to 1:console sess;level=1

The following example stops writing console messages and prompts to standard output andchanges the message level to 4:cons sys;l=4

The following example displays the current state of the console:consConsole is #J675, level 2, session

675 is the process ID of the user’s shell.

114 Version 8.1

continueIgnores the next command error.

Synopsiscontinue

Usage NotesThis command is useful when commands are entered non-interactively. It instructs Conmanto continue executing commands even if the next command, following continue, results inan error.

ExamplesIn the following example, Conman continues with the rerun command even if the cancelcommands fails:conman "continue&cancel=176&rerun job=sked5.job3"


4.C

on

man

Referen

ce

deldep jobDeletes dependencies from a job.

You must have deldep access to the job.

Synopsisddj jobselect;dependency[;...][;noask]

Argumentsjobselect


dependencyThe type of dependency. Specify at lease one of the following. You can use wildcardcharacters in wkstation, jstream, job, resource, filename, and promptname.

at

confirmed

every

follows[=[netagent::][wkstation#]jstream{.job | @} | job[,...]]

needs[=[num] [wkstation#]resource[,...]]

opens[=[wkstation#]″filename″[(qualifier)][,...]]

priority

prompt[=″[: | !]text″ | promptname[,...]]

until


Usage NotesIf priority is deleted, the job reverts to its original scheduled priority. When you delete anopens dependency, you can include only the base file name and Conman performs acase-insensitive search for matching files, ignoring the directory names. Dependencies on allmatching files are deleted.

In certain circumstances, when you have submitted a deldep command, the command mighthave succeeded even though it is again forwarded to batchman. For more information, see“Conman Command Processing” on page 104.

ExamplesThe following example deletes a resource dependency from job3 in sked5:deldep sked5.job3;needs=2 tapes

The following example deletes all follows dependencies from job4 in sked3:ddj sked3.job4;follows

116 Version 8.1

|||

deldep schedDeletes dependencies from a job stream.

You must have deldep access to the job stream.

Synopsisdds jstreamselect;dependency[;...][;noask]



dependencyThe type of dependency. Specify at least one of the following. You can use wildcardcharacters in wkstation, jstream, job, resource, filename, and promptname.

at

carryforward


limit



priority


until


Usage NotesIf priority is deleted, the job reverts to its original scheduled priority. When you delete anopens dependency, you can include only the base file name, and Conman performs acase-insensitive search for matching files, ignoring the directory names. Dependencies on allmatching files are deleted.


ExamplesThe following example deletes a resource dependency from sked5:deldep sked5;needs=2 tapes

The following example deletes all follows dependencies from sked3:dds sked3;follows


|||

|

|

|

|

|

4.C

on

man

Referen

ce

displayDisplays a job file or a job stream definition.

If you specify a file by name, you must have read access to the file. For job files and jobstream definitions, you must have display access to the job or job stream.

Synopsisdf filename[;offline]

dj jobselect[;offline]

ds jstreamselect[;offline]

Argumentsfilename Specifies the name of the file, usually a job script file. The name must be

enclosed in quotes (″) if it contains characters other than the following:alphanumeric characters, dashes (-), slashes (/), backslashes (\), andunderscores (_). Wildcard characters are permitted. The file must beaccessible from your login workstation.

jobselect The job whose job file is displayed. See “Selecting Jobs in Commands” onpage 94. The job file must be accessible from your login workstation.

jstreamselect The job stream whose definition is displayed. See “Selecting Job Streams inCommands” on page 100. The scheduler mozart directory on the masterdomain manager must be accessible from your login workstation.

offline Sends the output of the command to the Conman output device. Forinformation about this device, see “Offline Output” on page 90.

ExamplesThe following example displays the file c:\maestro\jclfiles\arjob3:df c:\apps\maestro\jclfiles\arjob3

The following example displays the script file for job6 in sked3 offline:dj sked3.job6;off

The following example displays the job stream definition for sked9:ds sked9

118 Version 8.1

exitExits the Conman program.

Synopsise

Usage NotesWhen you are in help mode on UNIX, this command returns Conman to command-inputmode.

ExamplesThe following examples exit the Conman program:exit

e


4.C

on

man

Referen

ce

fenceChanges the job fence on a workstation. Jobs are not launched on the workstation if theirpriorities are less than or equal to the job fence.

You must have fence access to the workstation.

Synopsisfence workstation;pri[;noask]

Argumentsworkstation Specifies the workstation name. The default is your login workstation.

pri Specifies the priority level. You can enter 0 through 99, hi, or go. Enteringsystem sets the job fence to zero.

noask Specifies not to prompt for confirmation before taking action on eachqualifying workstation.

Usage NotesThe job fence prevents low priority jobs from being launched, regardless of the priorities oftheir job streams. It is possible, therefore, to hold back low priority jobs in high priority jobstreams, while allowing high priority jobs in low priority job streams to be launched.

When you first start Workload Scheduler following installation, the job fence is set to zero.Once you change the job fence, it is carried forward during pre-production processing to thenext day’s production plan.

To display the current setting of the job fence, use the status command.

ExamplesThe following example changes the job fence on workstation site4:fence site4;20

The following example changes the job fence on the workstation on which you are runningConman:f ;40

The following example prevents all jobs from being launched by the scheduler onworkstation tx3:f tx3;go

The following example changes the job fence to zero on the workstation on which you arerunning Conman:f ;system

120 Version 8.1

helpDisplays help information about commands. Not available on Windows NT.

Synopsishelp command

Argumentscommand

Specifies the name of a Conman or system command. For Conman commands, enterthe full command name, abbreviations and short forms are not supported. In the caseof commands consisting of two words, enter the first word, and help for all versionsof the command is displayed. For example, entering help display will displayinformation about the display file, display job, and display sched commands. Youcan also enter the following keywords:

commandsLists all Conman commands.

jobselectLists information about selecting jobs for commands.

jobstatesLists information about job states.

schedselectLists information about selecting job streams for commands.

schedstatesLists information about job stream states.

ExamplesThe following example displays a list of all Conman commands:help commands

The following example displays information about the fence command:help fence

The following example displays information about the altpri job and altpri schedcommands:h altpri


4.C

on

man

Referen

ce

killStops an executing job. On UNIX, this is accomplished with a UNIX kill

command.

Synopsiskill jobselect[;noask]



Usage NotesThe kill operation is not performed by Conman, it is executed by a scheduler productionprocess, so there might be a short delay.

Killed jobs terminate in the abend state. Any jobs or job streams that are dependent on akilled job are not released. Killed jobs can be rerun.

ExamplesThe following example kills the job report in job stream apwkly on workstation site3:kill site3#apwkly.report

The following example kills job number 456:k 456

122 Version 8.1

limit cpuChanges the job limit for a workstation.

You must have limit access to the workstation.

Synopsislc wkstation;limit[;noask]

Argumentswkstation Specifies the name of the workstation. Wildcard characters are permitted.

The default is your login workstation.

limit Specifies the job limit. You can enter 0 through 1024. Entering system setsthe job limit to zero. If a limit of zero is set, no jobs, other than hi and gopriority jobs, are launched on the workstation.


Usage NotesTo display the current job limit on your login workstation, use the status command.

When you first start Workload Scheduler following installation, the workstation job limit isset to zero, and must be raised before any jobs are launched. Once you change the limit, it iscarried forward during pre-production processing to the next day’s production plan.

The scheduler attempts to launch as many jobs as possible within the job limit. There is apractical limit to the number of processes that can be started on a workstation. If the limit isreached, the system responds with a message indicating that system resources are notavailable. When a job cannot be launched for this reason, it enters the fail state. Loweringthe job limit can prevent this from occuring.

ExamplesThe following example changes the job limit on workstation site3:limit cpu=site3;25

The following example changes the job limit on the workstation on which you are runningConman:lc ;12

The following example changes the job limit on workstation rx12:lc rx12;6


4.C

on

man

Referen

ce

limit schedChanges the job limit for a job stream.

You must have limit access to the job stream.

Synopsisls jstreamselect;limit[;noask]


limit Specifies the job limit. You can enter 0 through 1024. If you specify a limitof zero, no further jobs are launched from the job stream.

noask Specifies not to prompt for confirmation before taking action on eachqualifying job stream.

ExamplesThe following example changes the job limit on all job streams that include sales in thename:limit sched=sales@;4

The following example changes the job limit on job stream apwkly:ls apwkly;6

124 Version 8.1

linkOpens communications links between workstations. In a scheduler network, fault-tolerantand standard agents are linked to their domain managers, and domain managers are linked totheir parent domain managers. Extended agents are not linked; they communicate through ahost.

You must have link access to the target workstation.

Synopsislk [domain!]wkstation[;noask]

Argumentsdomain Specifies the name of the domain in which links are opened. Wildcard

characters are permitted.

This argument is useful when linking more than one workstation in adomain. For example, to link all the agents in domain stlouis, use thefollowing command:link stlouis!@

The domain is not needed if you do not include wildcard characters inwkstation.

If you do not include domain, and you include wildcard characters inwkstation, the default domain is the one in which Conman is running.

wkstation Specifies the name of the workstation to be linked. Wildcard characters arepermitted.


Usage NotesIf the autolink option is set to on in a workstation definition, its link is openedautomatically each time the scheduler is started. If autolink is set to off, you must use linkand unlink commands to control linking. For information about autolink see “WorkstationDefinitions” on page 18.

Assuming that a user has link access to the workstations being linked, the following rulesapply:

¶ A user running Conman on the master domain manager can link any workstation in thenetwork.

¶ A user running Conman on a domain manager other than the master can link anyworkstation in its own domain and subordinate domains. The user cannot linkworkstations in peer domains.

¶ A user running Conman on an agent can link any workstation in its local domain.

¶ To link a subordinate domain while running Conman in a higher domain, it is notnecessary that the intervening links be open.


4.C

on

man

Referen

ce

ExamplesThe illustration and table below show the links opened by link commands executed by usersin various locations in the network.

DMn are domain managers and Ann are agents.

Command Links Opened byUser1

Links Opened byUser2

Links Opened byUser3

link @!@ All links are opened. DM1-DM2DM2-A21DM2-A22DM2-DM4DM4-A41DM4-A42

DM2-A21DM2-A22

link @ DM1-A11DM1-A12DM1-DM2DM1-DM3

DM1-DM2DM2-A21DM2-A22DM2-DM4

DM2-A21DM2-A22

link DOMAIN3!@ DM3-A31DM3-A32

Not allowed. Not allowed.

link DOMAIN4!@ DM4-A41DM4-A42

DM4-A41DM4-A42

Not allowed.

link DM2 DM1-DM2 Not applicable. DM2-A21

link A42 DM4-A42 DM4-A42 Not allowed.

link A31 DM3-A31 Not allowed. Not allowed.

Figure 1. Network Links

126 Version 8.1

listsymLists the production plan (Symphony) log files.

You must have display access to the Symphony file.

Synopsislistsym [;offline]

Argumentsoffline Sends the output of the command to the Conman output device. For

information about this device, see “Offline Output” on page 90.

Command OutputSchedule Date

The date used by the schedulr command to select job streams for execution.

Actual DateThe date batchman began executing the Symphony file.

Start TimeThe time batchman began executing the Symphony file.

Log DateThe date the plan (Symphony) was logged by the stageman command.

Run NumThe run number assigned to the plan (Symphony). These are used internally forscheduler network synchronization.

Size The size of the log file in records.

Log NumThe log number indicating the chronological order of log files. This number can beused in a setsym command to switch to a specific log file.

FilenameThe name of the log file assigned by the stageman command.

ExamplesThe following example lists the production plan log files:listsym

The following example lists the production plan log files to Conman’s output device:lis ;off


4.C

on

man

Referen

ce

recallDisplays prompts that are waiting for a response.

You must have display access to the prompts.

Synopsisrc [wkstation][;offline]

Argumentswkstation Specifies the name of the workstation on which the prompt was issued. If

you do not specify a workstation, only prompts for the login workstation andglobal prompts are displayed.


Command OutputState The state of the prompt. The state of pending prompts is always ASKED.

Message or PromptFor named prompts, the message number, the name of the prompt, and the messagetext. For unnamed prompts, the message number, the name of the job or job stream,and the message text.

ExamplesThe following example displays pending prompts issued on the workstation on which youare running Conman:recall

or:rc

The following example displays pending prompts on workstation site3:rc site3

The following example displays pending prompts on all workstations and the output is sentto Conman’s offline device:rc @;offline

128 Version 8.1

redoEdits and reexecutes the previous command.

Synopsisredo

ContextWhen you execute the redo command, Conman displays the previous command, so that itcan be edited and reexecuted. Use the spacebar to move the cursor under the character to bemodified, and enter the following directives.

Directives

d[dir] Deletes the character above the d. This can be followed by other directives.

itext Inserts text before the character above the i.

rtext Replaces one or more characters with text, beginning with the characterabove the r. Replace is implied if no other directive is entered.

>text Appends text to the end of the line.

>d[dir | text]Deletes characters at the end of the line. This can be followed by anotherdirective or text.

>rtext Replaces characters at the end of the line with text.

Directive Examples

ddd Deletes the three characters above the ds.

iabc Inserts abc before the character above the i.

rabc Replaces the three characters, starting with the one above the r, with abc.

abc Replaces the three characters above abc with abc.

d diabcDeletes the character above the first d, skips one character, deletes thecharacter above the second d, and inserts abc in its place.

>abc Appends abc to the end of the line.

>ddabcDeletes the last two characters in the line, and inserts abc in their place.

>rabc Replaces the last three characters in the line with abc.

ExamplesThe following example inserts a character:redosetsm 4

iysetsym 4

The following example replaces a character:redosetsym 4

5setsym 5


4.C

on

man

Referen

ce

release jobReleases jobs from dependencies.

You must have release access to the job.

Synopsisrj jobselect[;dependency[;...]][;noask]

Argumentsjobselect

Specifies the job or jobs to be released. See “Selecting Jobs in Commands” onpage 94.

dependencyThe type of dependency. You can specify one of the following. You can use wildcardcharacters in wkstation, jstream, job, resource, filename, and promptname.

at

confirmed

every




priority


until


Usage NotesWhen you release an opens dependency, you can include only the base file name, andConman performs a case-insensitive search for matching files, ignoring the directory names.Dependencies on all matching files are released.

For needs dependencies, the released job is given the required number of units of theresource, even though they might not be available. This can cause the Available units in ashowresources to display a negative number.

When you release a job from a priority dependency, the job reverts to its original scheduledpriority.

ExamplesThe following example releases job3 in job stream ap from all of its dependencies:release job=ap.job3

The following example releases job2 in job stream skedr from all of its opensdependencies:rj skedr.job2;opens

130 Version 8.1

||

The following example releases all jobs on workstation site4 from their dependencies on aprompt named glprmt:rj site4#@.@;prompt=glprmt


4.C

on

man

Referen

ce

release schedReleases job streams from dependencies.

You must have release access to the job stream.

Synopsisrs jstreamselect[;dependency[;...]][;noask]


See “Selecting Job Streams in Commands” on page 100.

dependencyThe type of dependency. Specify one of the following. You can use wildcardcharacters in wkstation, jstream, job, resource, filename, and promptname.

at

carryforward


limit



priority


until


Usage NotesWhen deleting an opens dependency, you can include only the filename (basename), andConman performs a case-insensitive search for matching files, ignoring the directory names.Dependencies on all matching files are released.

For needs dependencies, the released job stream is given the required number of units of theresource, even though they might not be available. This can cause the Available units in ashowresources to display a negative number.

When you release a schedule from a priority dependency, the job stream reverts to itsoriginal priority.


ExamplesThe following example releases job stream ap from all of its dependencies:release sched=ap

The following example releases job stream sked5 from all of its opens dependencies:

132 Version 8.1

||

|||

rs sked5;opens

The following example releases all job streams on workstation site3 from their dependencieson job stream main#sked23:rs site3#@;follows=main#sked23


4.C

on

man

Referen

ce

replyReplies to a job or job stream prompt.

You must have reply access to the named or global prompt. To reply to an unnamed prompt,you must have reply access to prompts, and reply access to the associated job or job stream.

Synopsisreply { promptname | [wkstation#]msgnum};reply[;noask]

Argumentspromptname Specifies the name of a global prompt. Wildcard characters are permitted.

wkstation Specifies the name of the workstation on which an unnamed prompt wasissued.

msgnum Specifies the message number of an unnamed prompt. You can displaymessage numbers with the recall and showprompts commands.

reply Specifies the reply, either Y for yes or N for no.

noask Specifies not to prompt for confirmation before taking action on eachqualifying prompt.

Usage NotesIf the reply is Y, dependencies on the prompt are satisfied. If the reply is N, thedependencies are not satisfied and the prompt is not re-issued.

Prompts can be replied to before they are issued. You can use the showprompts commandto display all prompts, whether they have been issued or not.

ExamplesThe following example replies Y to the global prompt arprmt:reply arprmt;y

The following example replies N to message number 24 on workstation site4:rep site4#24;n

134 Version 8.1

rerunReruns a job.

You must have rerun access to the job.

Synopsisrr jobselect[;from=[wkstat#]job[;at=time][;pri=pri]][;noask]

rr jobselect[;step=step][;noask]

Argumentsjobselect

Specifies the name of one or more jobs. Wildcard characters are permitted.

from=[wkstat#]jobSpecifies the name of a job defined in the scheduler database whose job file orcommand will be run in place of the job specified by jobselect.

wkstat#Specifies the name of the workstation on which the from job runs. Thedefault is the workstation on which Conman is running.

job Specifies the name of the from job definition The following types of jobnames are not permitted:¶ The names of jobs submitted using the submit file and submit

docommand commands.¶ The alias names of jobs submitted using the submit job command.

To use the from argument, you must have access to the scheduler database from thecomputer on which you are running Conman

at=timeSpecifies the rerun job’s start time, expressed as follows:

hhmm [timezone|tz tzname] [+n days | date]

where:





pri=priSpecifies the priority to be assigned to the rerun job. If you do not specify a priority,the job is given the same priority as the original job.

step=stepSpecifies that the job is rerun using this name in place of the original job name. See“Usage Notes” for more information.



|

4.C

on

man

Referen

ce

Usage NotesYou can rerun jobs that are in the succ, fail or abend state. A rerun job is placed in thesame job stream as the original job, and inherits the original job’s dependencies. If yourerun a repetitive (every) job, the rerun job is scheduled to run at the same rate as theoriginal job.

Note: You can issue rerun for jobs in the external job stream that are in the error state.Jobs in the external job stream represent jobs and job streams that have beenspecified as internetwork dependencies. The job state is initially set to extrnimmediately after a rerun is executed, and Conman begins checking the state.

When ;from is used, the name of the rerun job depends on the value of the Global Optionretain rerun job names. If the option is set to Y, rerun jobs retain the original job names.If the option is set to N, rerun jobs are given the from job names. For more information,refer to the Tivoli Workload Scheduler Planning and Installtion book.

In Conman displays, rerun jobs are displayed with the notation >>rerun as. To refer to arerun job in another command, such as altpri, you must use the original job name.

When a job is rerun with the ;step option, the job runs with step in place of its originalname. Within a job script, you can use the jobinfo command to return the job name and theexecute the script differently for each iteration. For example, in the following UNIX script,the jobinfo command is used to set a variable named STEP to the name that was used torun the job. The STEP variable is then used to determine how the script is executed....MPATH=vmaestrovSTEP=v$MPATH/bin/jobinfo job_namevif [$STEP = JOB3]

then...STEP=JSTEP1fi

if [$STEP = JSTEP1]then...STEP=JSTEP2fi

if [$STEP = JSTEP2]then...fi

...

In Conman displays, jobs rerun with the ;step option are displayed with the notation>>rerun step.

For information about jobinfo, see “jobinfo Command” on page 197.

ExamplesThe following example reruns job4 in sked1 on workstation main:rerun main#sked1.job4

The following example reruns job5 in sked2 using the job definition for jobx. The job’s attime is set to 6:30 P.M. and its priority is set to 25:rr sked2.job5;from=jobx;at=1830;pri=25

136 Version 8.1

The following example reruns job3 in sked4 using the job name jstep2:rr sked4.job3;step=jstep2


4.C

on

man

Referen

ce

resourceChanges the number of total units of a resource.

You must have resource access to the resource.

Synopsisresource [wkstation#]resource;num[;noask]

Argumentswkstation Specifies the name of the workstation on which the resource is defined. The

default is the workstation on which Conman is running.

resource Specifies the name of the resource.

num Specifies the total number of resource units. Valid values are 0 through1024.

noask Specifies not to prompt for confirmation before taking action on eachqualifying resource.

ExamplesThe following example changes the number of units of resource tapes to 5:resource tapes;5

The following example changes the number of units of resource jobslots on workstationsite2 to 23:res site2#jobslots;23

138 Version 8.1

setsymSelects a production plan archive file. Subsequent display commands display the contents ofthe archived production plan. You cannot modify the information in a production planarchive file.

Synopsissetsym [filenum]

Argumentsfilenum Specifies the number of the production plan archive file. If you do not

specify a log file number, the pointer returns to zero, the current productionplan (Symphony). Use the listsym command to list archive file numbers.

ExamplesThe following example selects production plan archive file 5:setsym 5

The following example selects the current production plan (Symphony):set


4.C

on

man

Referen

ce

showcpusDisplays information about workstations and links.

Synopsissc [[domain!]wkstation][;info][;link][;offline]

Argumentsdomain Specifies the name of a domain. The default is the domain of wkstation. If

wkstation includes wildcard characters, the default is the domain in whichConman is running. Wildcard characters are permitted.

wkstation Specifies the name of a workstation. The default is the workstation on whichConman is running. Wildcard characters are permitted.

info Displays information in the info format.

link Displays information in the link format.


Command OutputThe output of the command is produced in three formats, standard, info, and link.

Standard Format

CPUIDThe name of the workstation to which this information applies.

RUN The run number of the Production Control file (Symphony).

NODEThe node type and workstation type. Node types are as follows:¶ UNIX¶ WINT¶ MPEV¶ MPIX¶ OTHER

Workstation types are as follows:¶ MASTER¶ MANAGER¶ FTA¶ S-AGENT¶ X-AGENT

LIMITThe scheduler job limit.

FENCEThe scheduler job fence.

DATE TIMEThe date and time the scheduler started executing the current production plan(Symphony).

140 Version 8.1

STATEThe state of the workstation’s links. Up to five characters are displayed as follows:[L] [D|T|H|X] [I] [J] [W|M|H|X]L The link is open (linked).D The link is DS. For MPEV and MPIX only.T The link is TCP/IP.I The jobman program has completed startup initialization.J The jobman program is running.W The workstation is linked by TCP/IP.M The workstation is linked by DS. For MPEV and MPIX only.X The workstation is linked as an extended agent (x-agent).H The workstation is linked through its host.

Note: If the workstation running Conman is the extended agent’s host, the state of thex-agent isLXI JX

If the workstation running Conman is not the extended agent’s host, the state ofthe x-agent isLHI JH

METHODThe name of the access method specified in the workstation definition. For extendedagents only.

DOMAINThe name of the domain in which the workstation is a member.

info Format


VERSIONThe version of the Workload Scheduler jobman program.

TIMEZONEThe time zone of the workstation. It is the same as the value of the TZ environmentvariable. For an extended agent, this is the time zone of its host.

INFO The Operating System version and hardware model. For extended agents, no informationis listed.

link Format


HOSTThe name of the workstation acting as the host to a standard agent or extended agent.For domain managers and fault-tolerant agents, this is the same as CPUID. For standardagent workstations, this is the name of the domain manager. For extended agents, this isthe name of the host workstation.

FLAGSThe state of the workstation’s links. Up to five characters are displayed as follows:


4.C

on

man

Referen

ce

[A] [F] [s] [D|T|B]A Autolink is turned on in the workstation definition.F Full Status mode is turned on in the workstation definition.s The ID of mailman server for the workstation.D The link is defined as DS. For MPEV and MPIX only.T The link is defined as TCP/IP.B The link is defined as both DS and TCP/IP. For MPEV and MPIX only.

ADDRThe TCP port number for the workstation.

NODEThe node name of the workstation.

ExamplesThe following example displays information about the workstation on which you are runningConman in the info format:showcpus ;info

The following example displays link information offline for all workstations:sc @!@;link;off

142 Version 8.1

showdomainDisplays domain information.

Synopsisshowdomain [domain][;info][;offline]

Argumentsdomain Specifies the name of the domain. The default is the domain in which

Conman is running. Wildcard characters are permitted.



Command OutputThe output of the command is produced in two formats, standard, and info.

Standard Format

DOMAINThe name of the domain to which this information applies.

MANAGERThe name of the domain manager.

PARENTThe name of the parent domain.

info Format

DOMAINThe name of the domain to which this information applies.

MEMBER-CPUSThe names of the workstations in the domain.

CPU-TYPEThe type of each workstation: MASTER, MANAGER, FTA, S-AGENT, or X-AGENT.

ExamplesThe following example displays information about the masterdm domain:showdomain masterdm

The following example displays the member workstations in all domains in the info format:showdomain @;info


4.C

on

man

Referen

ce

showfilesDisplays information about file dependencies.

Synopsissf [[wkstation#]file][;state[;...]][;keys][;offline]

sf [[wkstation#]file][;state[;...]][;deps[;keys | info | logon]][;offline]

Argumentswkstation Specifies the name of the workstation on which the file exists. The default is

the workstation on which Conman is running. Wildcard characters arepermitted.

file Specifies the name of the file. The name must be enclosed in quotes (″) if itcontains characters other than the following: alphanumerics, dashes (-),slashes (/), backslashes (\), and underscores (_). The default is to display allfile dependencies. Wildcard characters are permitted.

state Specifies the state of the file dependencies to be displayed. The default is todisplay file dependencies in all states. The states are as follows:

yes File exists and is available.

no File is unavailable, or does not exist.

? Availability is being checked.

<blank>The file has not yet been checked, or the file was available and usedto satisfy a job or job stream dependency.

keys Displays a single column list of the objects selected by the command.

deps Displays information in the deps format. Use keys, info, or logon to modifythe display.


Command OutputThe output of the command is produced in three formats: standard, keys, and deps. Thearguments keys, info, and logon modify the deps display.

Standard Format

Exists The state of the file dependency.

File NameThe name of the file.

keys FormatFiles are listed with one file on each line. Directory names are not included. Each file islisted in the following format:

wkstation#file

144 Version 8.1

deps FormatFiles are listed followed by the dependent jobs and job streams. Jobs are listed in thestandard showjobs format. Job streams are listed in the standard showschedules format.

deps;keys FormatJobs and job streams that have file dependencies are listed with one on each line, in thefollowing format:

wkstation#jstream[.job]

deps;info FormatFiles are listed, followed by the dependent jobs and job streams. Jobs are listed in theshowjobs;info format. Job streams are listed in the standard showschedules format.

deps;logon FormatFiles are listed followed by the dependent jobs and job streams. Jobs are listed in theshowjobs;logon format. Job streams are listed in the standard showschedules format.

ExamplesThe following example displays the status of a file dependency for d:\apps\mis\lib\data4:showfiles d:\apps\mis\lib\data4

The following example displays offline the status of all file dependencies on all workstationsin the deps format:sf @#@;deps;offline


4.C

on

man

Referen

ce

showjobsDisplays information about jobs.

Synopsissj [jobselect] [;keys | info | step | logon][;short | single][;offline]

sj [jobselect] [;deps[;keys | info | logon]][;short | single][;offline]

sj [jobselect|wkstation# {jobnumber.hhmm}] [;stdlist[;keys]][;short | single][;offline]


wkstation The name of the workstation on which the job runs. Wildcard characters arepermitted.

jobnumber The job number.

hhmm The started time of the job. Use this, together with the stdlist and singlearguments, to display a specific instance of the job.



step Displays information in the step format.

logon Displays information in the logon format.

stdlist Displays information in the stdlist format. Use the keys argument to modifythe display.


short Shortens the display for every and rerun jobs to include only the following:¶ The first iteration¶ Jobs in different states¶ Exactly matched jobs

single Selects only the parent job in a chain that can include reruns, repetitions,and recovery jobs. The job must be identified by job number in jobselect.This is particularly useful with the stdlist option.


Command OutputThe output of the showjobs command is produced in seven formats: standard, keys, info,step, logon, deps, and stdlist. The arguments keys, info, and logon modify the displays.

Standard Format

CPU The workstation on which the job runs.


Job The name of the job. The following notation may precede a job name:

146 Version 8.1

|

|||

||

|||

>> rerun asA job that was rerun with the rerun command, or as a result of automaticrecovery.

>> rerun stepA job that was rerun with the rerun ;step command.

>> every runThe second and subsequent runs of an every job.

>> recoveryThe run of a recovery job.

State The state of the job or job stream. Job states are follows:

abend The job terminated with a non-zero exit code.

abenp An abend confirmation was received, but the job is not completed.

add The job is being submitted.

done The job completed in an unknown state.

error For internetwork dependencies only, an error occurred while checking for theremote status.

exec The job is executing.

extrn For internetwork dependencies only, the status is unknown. An error occurred, arerun action was just performed on the job in the external job stream, or theremote job or job stream does not exist.

fail Unable to launch the job.

fence The job’s priority is below the fence.

hold The job is awaiting dependency resolution.

intro The job is introduced for launching by the system.

pend The job completed, and is awaiting confirmation.

ready The job is ready to launch, and all dependencies are resolved.

sched The job’s at time has not arrived.

succ The job completed with an exit code of zero.

succp A succ confirmation was received, but the job is not completed.

susp The job was suspended by a breakjob command. (MPE only)

wait The job is in the wait state. (Extended agent and MPE only)

waitd The job is in the wait state, and is deferred. (MPE only)

Job stream states are as follows:

abend The job stream terminated with a non-zero exit code.

add The job stream was added with operator intervention.

cancel The job stream was canceled.


4.C

on

man

Referen

ce

cancel pendThe job stream is pending cancellation. Cancellation is deferred until all of thedependencies, including an at time, are resolved.



extrn For internetwork dependencies only, the job stream is in a remote schedulernetwork and its status is unknown. An error occurred, a rerun action was justperformed on the EXTERNAL job stream, or the INET job or job stream doesnot exist.

hold The job stream is awaiting dependency resolution.

ready The job stream is ready to launch and all dependencies are resolved.

stuck Execution of the job stream was interrupted. No jobs are launched withoutoperator intervention.


Pr The priority of the job stream or job. A plus sign (+) preceding the priority means thejob has been launched.

(Est)StartThe start time of the job stream or job. Parentheses indicate an estimate of the start time.If the start time is more than 24 hours in the past or future, the date is listed instead ofthe time.

(Est)ElapseThe run time of the job stream or job. Parentheses indicate an estimate based on loggedstatistics.

dependenciesA list of job dependencies and comments. Any combination of the following can belisted:

¶ For a follows dependency, a job stream or job name is displayed.

¶ For an opens dependency, the file name is displayed. If the file resides on anextended agent and its name is longer than 25 characters, only the last 25 charactersare displayed.

¶ For a needs dependency, a resource name enclosed in hyphens (-) is displayed. Ifthe number of units requested is greater than one, the number is displayed before thefirst hyphen.

¶ For an every rate, the repetition rate preceded by an ampersand (&) is displayed.

¶ For an until time, the time preceded by an angle bracket (<) is displayed.

¶ For a prompt dependency, the prompt number is displayed in the format #num. Forglobal prompts, the prompt name follows in parentheses.

¶ For executing jobs, the process identification number (PID) is displayed in theformat #Jnnnnn.

¶ Jobs submitted on UNIX using the Workload Scheduler at and batch commands arelabeled [Userjcl].

148 Version 8.1

¶ Cancelled jobs are labeled [Cancelled].

¶ Jobs cancelled with ;pend option are labeled [Cancel Pend].

¶ Jobs with expired until times, including jobs cancelled with ;pend option, arelabeled [Until].

¶ [Recovery] means that operation intervention is required.

¶ [Confirm] means that confirmation is required because the job was scheduled usingthe confirm keyword.

keys FormatJob names are listed one on each line in the following format:

wkstation#jstream.job

info Format




>> rerun asA job that was rerun with the rerun command, or as a result of automaticrecovery.

>> rerun stepA job that was rerun with the rerun ;step command.

>> every runThe second and subsequent runs of an every job.

>> recoveryThe run of a recovery job.

Job FileThe name of the job’s script or executable file. Long file names might wrap, causingincorrect paging. To avoid this, pipe the output to more. For example:conman “sj;info | more

Opt The job recovery option, if any. The recovery options are RE for rerun, CO forcontinue, and ST for stop.

Job The name of the recovery job, if any.

PromptThe number of the recovery prompt, if any.

step FormatThis format is not supported on Windows NT.



Job The name of the job. The following notation might precede a job name:


4.C

on

man

Referen

ce

>> rerun asA job that was rerun with rerun command, or as a result of automaticrecovery.

>> repeated asThe second and subsequent runs of an every job.

State The state of the job or job stream. See “Standard Format” for information aboutstate.

Job# The process identification number displayed as #Jnnnnn.

Step A list of descendant processes that are associated with the job. For extended agentjobs, only host processes are listed.

logon Format




>> rerun asA job that was rerun with rerun command, or as a result of automatic recovery.

>> repeated asThe second and subsequent runs of an every job.

State The state of the job or job stream. See “Standard Format” for information about state.

Job# The process identification number displayed as #Jnnnnn.

Logon The user name under which the job executes.

stdlist FormatThe standard list files for the selected jobs are displayed.

stdlist;keys FormatThe names of the standard list files for the selected jobs are listed, one on each line.

deps FormatJobs used in follows dependencies are listed followed by the dependent jobs and jobstreams. Jobs are listed in the standard showjobs format. Job streams are listed in thestandard showschedules format.

deps;keys FormatJobs and job streams that have follows dependencies are listed, one on each line.

deps;info FormatJobs used in follows dependencies are listed, followed by the dependent jobs and jobstreams. Jobs are listed in the showjobs;info format. Job streams are listed in the standardshowschedules format.

deps;logon FormatJobs used in follows dependencies are listed, followed by the dependent jobs and jobstreams. Jobs are listed in the showjobs;logon format. Job streams are listed in the standardshowschedules format.

150 Version 8.1

ExamplesThe following example displays the status of all jobs in all acctg job streams on workstationsite3:showjobs site3#acctg@.@

The following example displays the status of all jobs on the workstation on which you arerunning Conman in the logon format:sj ;logon

The following example displays the status of all jobs in the hold state on all workstations inthe deps format:sj @#@.@+state=hold;deps

The following example displays all of the standard list files for the job gl in the job streamarec on workstation site2:sj site2#arec.gl;stdlist


4.C

on

man

Referen

ce

showpromptsDisplays information about prompts.

Synopsissp [promptselect][;keys][;offline]

sp [promptselect] [;deps[;keys | info | logon]][;offline]

Argumentspromptselect

[promptname | [wkstation#]msgnum][;state[;...]]


wkstationSpecifies the name of the workstation on which an unnamed prompt isissued. The default is the workstation on which Conman is running.

msgnumSpecifies the message number of an unnamed prompt.

state Specifies the state of prompts to be displayed. The states are as follows:

YES The prompt was replied to with y.

NO The prompt was replied to with n.

ASKEDThe prompt was issued, but no reply was given.

INACTThe prompt has not been issued.


deps Displays information in the deps format. Use keys, info, or logon to modify thedisplay.



offline Sends the output of the command to the Conman output device. For informationabout this device, see “Offline Output” on page 90.


Standard Format

State The state of the prompt.

Message or PromptFor named prompts, the message number, the name, and the text of the prompt. Forunnamed prompts, the message number, the name of the job or job stream, and the textof the prompt.

152 Version 8.1

keys FormatThe prompts are listed one on each line. Named prompts are listed with their messagenumbers and names. Unnamed prompts are listed with their message numbers, and thenames of the jobs or job streams in which they appear as dependencies.

deps FormatPrompts used as dependencies are listed, followed by the dependent jobs and job streams.Jobs are listed in the standard showjobs format. Job streams are listed in the standardshowschedules format.

deps;keys FormatJobs and job streams that have prompt dependencies are listed one on each line.

deps;info FormatPrompts used as dependencies are listed, followed by the dependent jobs and job streams.Jobs are listed in the showjobs;info format. Job streams are listed in the standardshowschedules format.

deps;logon FormatPrompts used as dependencies are listed, followed by the dependent jobs and job streams.Jobs are listed in the showjobs;logon format. Job streams are listed in the standardshowschedules format.

ExamplesThe following example displays the status of all prompts issued on the workstation on whichyou are running Conman:showprompts

The following example displays, in the deps format, the status of all mis prompts that havebeen issued:sp mis@;asked;deps

The following example displays the status of prompt number 34 on workstation main:sp main#34


4.C

on

man

Referen

ce

showresourcesDisplays information about resources.

Synopsissr [[wkstation#]resourcename][;keys][;offline]

sr [[wkstation#]resourcename][;deps[;keys | info | logon]][;offline]

Argumentswkstation Specifies the name of the workstation on which the resource is defined. The

default is the workstation on which Conman is running.

resourcename Specifies the name of the resource. Wildcard characters are permitted.







Standard Format

CPU The workstation on which the resource is defined.

Resource The name of the resource.

Total The total number of defined resource units.

Available The number of resource units that have not been allocated.

Qty The number of resource units allocated to a job or job stream.

Used By The name of the job or job stream.

keys FormatThe resources are listed one on each line.

deps FormatResources used as dependencies are listed, followed by the dependent jobs and job streams.Jobs are listed in the standard showjobs format. Job streams are listed in the standardshowschedules format.

deps;keys FormatJobs and job streams that have resource dependencies are listed one on each line.

154 Version 8.1

deps;info FormatResources used as dependencies are listed, followed by the dependent jobs and job streams.Jobs are listed in the showjobs;info format. Job streams are listed in the standardshowschedules format.

deps;logon FormatResources used as dependencies are listed, followed by the dependent jobs and job streams.Jobs are listed in the showjobs;logon format. Job streams are listed in the standardshowschedules format.

ExamplesThe following example displays information about all resources on the workstation on whichyou are running Conman:showresources

The following example displays information about the dbase resource on workstation mainin the deps format:sr main#dbase;deps


4.C

on

man

Referen

ce

showschedulesDisplays information about job streams.

Synopsisss [jstreamselect][;keys][;offline]

ss [jstreamselect][;deps[;keys | info | logon]][;offline]








Standard Format

CPU The workstation on which the job stream runs.


State The state of the job stream. The states are as follows:

add The job stream was added with operator intervention.

abend The job stream terminated with a non-zero exit code.

cancel The job stream was canceled.

cancel pendThe job stream is pending cancellation. Cancellation is deferred until all of thedependencies, including an at time, are resolved.



extrn For internetwork dependencies only, the job stream is in a remote schedulernetwork and its status is unknown. An error occurred, a rerun action was justperformed on the EXTERNAL job stream, or the INET job or job stream doesnot exist.

hold The job stream awaiting dependency resolution.

ready The job stream ready to launch and all dependencies are resolved.

156 Version 8.1

stuck Job stream execution was interrupted. No jobs are launched without operatorintervention.


Pr The priority of the job stream.

(Est)StartThe start time of the job stream. Parentheses indicate an estimate of the start time. If thestart time is more than 24 hours in the past or future, the date is listed instead of thetime.

(Est)ElapseThe run time of the job stream. Parentheses indicate an estimate based on loggedstatistics.

Jobs #The number of jobs in the job stream.

Jobs OKThe number of jobs that have completed successfully.

Sch LimThe job stream’s job limit. If one is not listed, no limit is in effect.

dependenciesA list of job stream dependencies and comments. Any combination of the following maybe listed:

¶ For a follows dependency, a job stream or job name is displayed.

¶ For an opens dependency, the file name displayed. If the file resides on an extendedagent, and its name is longer than 25 characters, only the last 25 characters aredisplayed.

¶ For a needs dependency, a resource name enclosed in hyphens (-) is displayed. Ifthe number of units requested is greater than one, the number is displayed before thefirst hyphen.

¶ For an until time, the time preceded by an angled bracket (<).

¶ For a prompt dependency, the prompt number displayed as #num. For globalprompts, the prompt name in parentheses follows.

¶ Cancelled job streams are labeled [Cancelled].

¶ Job streams cancelled with the ;pend option are labeled [Cancel Pend].

¶ Job streams with expired until times, including job streams cancelled with the ;pendoption, are labeled: [Until].

¶ Job streams that contain the carryforward keyword are labeled [Carry].

¶ For job streams that were carried forward from the previous day, the original nameand date are displayed in brackets.

keys FormatThe job streams are listed one on each line.


4.C

on

man

Referen

ce

deps FormatJob streams used in as dependencies are listed, followed by the dependent jobs and jobstreams. Jobs are listed in the standard showjobs format. Job streams are listed in thestandard showschedules format.

deps;keys FormatJob streams that have follows dependencies are listed one on each line.

deps;info FormatJob streams used in as dependencies are listed, followed by the dependent jobs and jobstreams. Jobs are listed in the showjobs;info format. Job streams are listed in the standardshowschedules format.

deps;logon FormatJob streams used in as dependencies are listed, followed by the dependent jobs and jobstreams. Jobs are listed in the showjobs;logon format. Job streams are listed in the standardshowschedules format.

ExamplesThe following example displays the status of all job streams in the hold state on theworkstation on which you are running Conman:showschedules @+state=hold

The following example displays the status of all corp job streams on workstation site2 inthe deps;info format:ss site2#corp@;deps;info

The following example displays offline the status of all job streams in the abend state on allworkstations:ss @#@+state=abend;off

158 Version 8.1

shutdownUnconditionally stops all of scheduler production processes, including Batchman, Jobman,Netman, Mailman, all Mailman servers, and all writers.

You must have shutdown access to the workstation.

Synopsisshutdown [;wait]

Argumentswait Waits until all processes have stopped before prompting for another

command.

Usage NotesThe shutdown command stops the processes only on the workstation on which Conman isrunning. To restart Netman only, execute the StartUp command. For information about theStartUp command, see “StartUp Command” on page 214. To restart the entire process tree,execute a Conman start command.

You must execute a Conman unlink @ command before executing a shutdown command.

ExamplesThe following example shuts down production on the workstation on which you are runningConman:unlink @shutdown

The following example shuts down production on the workstation on which you are runningConman and waits for all processes to stop:unlink@;noaskshut ;wait


4.C

on

man

Referen

ce

startStarts scheduler production processes.

You must have start access to the workstation.

Synopsisstart [domain!]wkstation[;mgr][;noask]

Argumentsdomain Specifies the name of the domain in which workstations are started.

Wildcard characters are permitted.

This argument is useful when starting more than one workstation in adomain. For example, to start all the agents in domain stlouis, use thefollowing command:start stlouis!@

If domain is omitted, and wkstation contains wildcard characters, the defaultdomain is the one in which Conman is running.

wkstation Specifies the name of the workstation to be started. Wildcard characters arepermitted.

mgr This can be entered only on the workstation on which Conman is running. Itstarts the local workstation as the domain manager. The workstation becomesthe new domain manager and the current domain manager becomes afault-tolerant agent. This form of the command usually follows a stopcommand. Note that the preferred method of switching a domain manager isto use a switchmgr command. See “switchmgr” on page 173 for moreinformation.


Usage NotesThe start command is used at the start of each day to restart the scheduler followingpre-production processing. At that time it causes the autolinked fault-tolerant agents andstandard agents to be initialized and started automatically. Agents that are not autolinked areinitialized and started when you execute a link command.

Assuming the user has start access to the workstations being started, the following rulesapply:

¶ A user running Conman on the master domain manager can start any workstation in thenetwork.

¶ A user running Conman on a domain manager other than the master can start anyworkstation in that domain and subordinate domains. The user cannot start workstationsin peer domains.

¶ A user running Conman on an agent can start any workstation in the local domain.

160 Version 8.1

ExamplesThe illustration and table below show the workstations started by start commands executedby users in various locations in the network.


Command Started by User1 Started by User2 Started by User3

start @!@ All workstations arestarted.

DM2A21A22DM4A41A42

DM2A21A22

start @ DM1A11A12

DM2A21A22

DM2A21A22

start DOMAIN3!@ DM3A31A32


start DOMAIN4!@ DM4A41A42

DM4A41A42

Not allowed.

start DM2 DM2 DM2 DM2

start A42 A42 A42 Not allowed.

start A31 A31 Not allowed. Not allowed.

Figure 2. Started Workstations in Network


4.C

on

man

Referen

ce

statusDisplays the Conman banner and the Workload Scheduler production status.

Synopsisstatus

Command OutputFollowing the word Schedule on the second line of output, the production plan (Symphony)mode is shown in parentheses. Def means that the production plan is in non-expanded mode,and Exp means it is in expanded mode. The mode of the production plan is determined bythe setting of the Global option expanded version. For more information, refer to the TivoliWorkload Scheduler Planning and Installation book.

ExamplesThe following example displays the status of the current production plan. Then it sets theproduction plan pointer to 2 and displays the status of that production plan.%statusMAESTRO for UNIX (HPUX)/CONMAN 6.0 (3.34) (C) Tivoli Systems 1998Schedule (Exp) 11/30/98 (#7) on DEMOCPU. Batchman down.Limit: 6, Fence: 0%setsym 2Schedule 11/29/98 (#5) on DEMOCPU. Symphony switched.(2)%statusMAESTRO for UNIX (HPUX)/CONMAN 6.0 (3.34) (C) Tivoli Systems 1998Schedule (Exp) 11/29/98 (#5) on DEMOCPU. Symphony switched.

162 Version 8.1

stopStops scheduler production processes. To stop the Netman process, use the shutdown

command.

You must have stop access to the workstation.

Synopsisstop [domain!]wkstation[;wait][;noask]

Argumentsdomain Specifies the name of the domain in which workstations are stopped.

Because workstations have unique names, the domain is not needed whenstopping a specific workstation. Wildcard characters are permitted.

This argument is useful when stopping more than one workstation in adomain. For example, to stop all the agents in domain stlouis, use thefollowing command:stop stlouis!@

If domain is omitted, and wkstation contains wildcard characters, the defaultdomain is the one in which Conman is running.

wkstation Specifies the name of the workstation to be stopped. Wildcard characters arepermitted.

wait Specifies not to accept another command until all processes have stopped.


Usage NotesIf the stop command cannot be applied to a distant workstation (if the TCP/IP path notavailable, for example), the command is stored locally in a pobox file, and is mailed to theworkstation when it becomes linked.

Assuming the user has stop access to the workstations being stopped, the following rulesapply:

¶ A user running Conman on the master domain manager can stop any workstation in thenetwork.

¶ A user running Conman on a domain manager other than the master can stop anyworkstation in that domain and subordinate domains. The user cannot stop workstationsin peer domains.

¶ A user running Conman on an agent can stop any workstation in the local domain.

When you issue a stop @ command on a domain manager, a local conman stop commandruns on the remote CPUs. The command starts running on the lowest stations in the networkhierarchy, then finally runs on the domain manager. However, the symphony files are notupdated before the CPUs go down. Therefore, if you issue a conman sc@!@ commandform any CPU, the resulting information might be an accurate picture of the states of theCPUs, even of the domain manager.


4.C

on

man

Referen

ce

ExamplesThe illustration and table below show the workstations stopped by different stop commandsexecuted by users in different locations in the network.


Command Stopped by: User1 Stopped by User2 Stopped by User3

stop @!@ All workstations arestopped.

DM2A21A22DM4A41A42

DM2A21A22

stop @ DM1A11A12

DM2A21A22

DM2A21A22

stop DOMAIN3!@ DM3A31A32


stop DOMAIN4!@ DM4A41A42

DM4A41A42

Not allowed.

stop DM2 DM2 DM2 DM2

stop A42 A42 A42 Not allowed.

stop A31 A31 Not allowed. Not allowed.

Figure 3. Stopped Workstations in Network

164 Version 8.1

submit docommandSubmits a command to be launched as a scheduler job.

You must have submit access to the job. To include needs and prompt dependencies, youmust have use access to the resources and global prompts.

Synopsissbd [wkstation#]″cmd″[;alias[=name]][;into=jobstream][;joboption[;...]]

Argumentswkstation

Specifies the name of the workstation on which the job will be launched. Wildcardcharacters are permitted, in which case, the job is launched on all qualifyingworkstations. The default is the workstation on which Conman is running. Youcannot specify a domain or workstation class.

cmd Specifies a valid system command of up to 255 characters. The entire commandmust be enclosed in quotes (″). The command is treated as a job, and all job rulesapply.

alias=nameSpecifies a unique name to be assigned to the job. If you enter the alias keywordwithout specifying a name, a name is constructed using the first two alphanumericcharacters of the command followed by a six digit random number. The name isalways upshifted. For example, if the command is rm apfile, the generated namewill be similar to RM123456.

If you do not include alias, a job name is constructed using the first eightalphanumeric characters of the command, upshifted.

into=jobstreamSpecifies the name of the job stream into which the job will be placed for launching.Enter the name as follows:

[wkstation#]jstream If you do not specify a wkstation, the default is the workstationon which Conman is running. If into is not used, the job is added to a job streamnamed JOBS.

joboptionSpecify one of the following:

at=hhmm [timezone|tz tzname] [+n days | mm/dd/yy]

confirmed

every=rate


interactive

logon=user





4.C

on

man

Referen

ce

recovery=stop | continue | rerun

recoveryjob | after=[wkstation#]job

recoveryprompt | abendprompt=″text″

until=hhmm [timezone|tz tzname] [+n days | mm/dd/yy]

Usage NotesIf you do not specify a workstation with follows, needs, or opens, the default is theworkstation of the job. If the job is executed on a fault-tolerant agent, and you want toinclude a prompt dependency or a recoveryprompt, the mozart directory (WShome/mozart)on the master domain manager must be accessible, either mounted or shared.

ExamplesThe following example submits an rm command into the JOBS job stream with a followsdependency:submit docommand="rm apfile";follows sked3

The following example submits a sort command with the alias sortit and places the job inthe reports job stream with an at time of 5:30 P.M.:sbd "sort < file1 > file2";alias=sortit;into=reports;at=1730

The following example submits chmod commands on all workstations with names beginningwith site:sbd site@#"chmod 444 file2";alias

166 Version 8.1

submit fileSubmits a file to be launched as a scheduler job.


Synopsissbf filename[;alias[=name]][;into=jobstream][;joboption[;...]][;noask]

Argumentsfilename

Specifies the name of the file, up to 255 characters. Wildcard characters arepermitted. The name must be enclosed in quotes (″) if it contains characters otherthan alphanumeric characters, dashes (-), slashes (/), backslashes (\), and underscores(_).

alias=nameSpecifies a unique name to be assigned to the job. If you enter the alias keywordwithout specifying a name, a name is constructed using the first two alphanumericcharacters of the file’s base name followed by a six digit random number. The nameis always upshifted. For example, if the file name is jclttx5, the generated name willbe similar to JC123456.

If you do not include alias, a job name is constructed using the first eightalphanumeric characters of the file’s base name, upshifted.

In either of the above cases, if the file name does not start with a letter, you areprompted to use alias= name.

into=jobstreamThe name of the job stream into which the job will be placed for launching. Enterthe name as:

[wkstation#]jstream If you do not specify a wkstation, the default is the workstationon which Conman is running. If into is not used, the job is added to a job streamnamed JOBS.



confirmed

every=rate


interactive

logon=user






4.C

on

man

Referen

ce




noask Specifies not to prompt for confirmation before taking action against each qualifyingfile.

Usage NotesIf you do not specify a workstation with follows, needs, or opens, the default is theworkstation on which Conman is running. If the job is executed on a fault-tolerant agent,and you want to include a prompt dependency or a recoveryprompt, the mozart directory(WShome/mozart) on the master domain manager must be accessible, either mounted orshared.

ExamplesThe following example submits a file into the jobs job stream. The job name is myjcl.submit file=d:\jobs\lib\daily\myjcl

The following example submits a file, with a job name of misjob4, into a job stream namedmissked. The job needs two units of the slots resource.sbf /usr/lib/mis/jcl4;alias=misjob4;into=missked ;needs=2 slots

The following example submits all files that have names beginning with back into a jobstream named bkup.sbf "/usr/lib/backup/back@";into=bkup

168 Version 8.1

submit jobSubmits a job to be launched by the scheduler.


To submit a job, you must be running Conman on the master domain manager, or haveaccess to the scheduler databases on the master domain manager.

Synopsissbj [wkstation#]jobname[;alias[=name]][;into=jobstream][;joboption[;...]][;noask]

Argumentswkstation

Specifies the name of the workstation on which the job will be launched. Wildcardcharacters are permitted, in which case, the job is launched on all qualifyingworkstations. The default is the workstation on which Conman is running. Youcannot specify a domain or workstation class.

jobnameSpecifies the name of the job. Wildcard characters are permitted, in which case, allqualifying jobs are submitted. If the job is already in the production plan, and isbeing submitted into the same job stream, you must use the alias argument to assigna unique name.

alias=nameSpecifies a unique name to be assigned to the job in place of jobname. If you enterthe alias keyword without specifying a name, a name is constructed using the firsttwo alphanumeric characters of jobname followed by a six digit random number.The name is always upshifted. For example, if jobname is jcrttx5, the generatedname will be similar to JC123456.

into=jobstreamSpecifies the name of the job stream into which the job will be placed for launching.Enter the name as:

[wkstation#]jstream If you do not specify a wkstation, the default is the workstationon which Conman is running. If into is not used, the job is added to a job streamnamed jobs.



confirmed

every=rate






4.C

on

man

Referen

ce





noask Specifies not to prompt for confirmation before taking action against each qualifyingjob.

Usage NotesIf you do not specify a workstation with follows, needs, or opens, the default is theworkstation of the job. If the job is executed on a fault-tolerant agent, and you want toinclude a prompt dependency or a recoveryprompt, the mozart directory (WShome/mozart)on the master domain manager must be accessible, either mounted or shared.

ExamplesThe following example submits the test jobs into the JOBS job stream:submit job=test@

The following example submits a job with an alias of rptx4 and places the job in thereports job stream with an at time of 5:30 P.M.:sbj rjob4;alias=rptx4;into=reports;at=1730

The following example submits job txjob3 on all workstations whose names begin with site:sbj site@#txjob3;alias

170 Version 8.1

submit schedSubmits a job stream to be launched by the scheduler.

You must have submit access to the job stream. To include needs and promptdependencies, you must have use access to the resources and global prompts.

To submit a job stream, you must be running Conman on the master domain manager orhave access to the scheduler databases on the master domain manager.

Synopsissbs [wkstation#]jstreamname[;alias[=name]][;jstreamoption[;...]][;noask]

Argumentswkstation

Specifies the name of the workstation on which the job stream will be launched.Wildcard characters are permitted, in which case, the job stream is launched on allqualifying workstations. The default is the workstation on which Conman is running.You cannot specify a domain or workstation class.

jstreamnameSpecifies the name of the job stream. Wildcard characters are permitted, in whichcase, all qualifying job streams are submitted. If the job stream is already in theproduction plan, you must use the alias argument to assign a unique name.

alias=nameSpecifies a unique name to be assigned to the job stream in place of jstreamname. Ifyou enter the alias keyword without specifying a name, a name is constructed usingthe first two alphanumeric characters of jstreamname followed by a six digit randomnumber. The name is always upshifted. For example, if jstreamname is sttrom, thegenerated name will be similar to ST123456.

jstreamoptionEnter one of the following:


carryforward


limit=joblimit





noask Specifies not to prompt for confirmation before taking action against each qualifyingjob stream.

Usage NotesIf you do not specify a workstation with follows, needs, or opens, the default is theworkstation of the job stream. If the job stream is executed on a fault-tolerant agent, and


4.C

on

man

Referen

ce

you want to include a prompt dependency or a recoveryprompt, the mozart directory(WShome/mozart) on the master domain manager must be accessible, either mounted orshared.

ExamplesThe following example submits the adhoc job stream on workstation site1 and flags it as acarryforward job stream:submit sched=site1#adhoc;carryforward

The following example submits job stream fox4 with a job limit of 2, a priority of 23, andan until time of midnight:sbs fox4;limit=2;pri=23;until=0000

The following example submits job stream sched3 on all workstations with names that startwith site:sbs site@#sched3

172 Version 8.1

switchmgrSwitches domain management from the current domain manager to a backup domainmanager.

You must have start and stop access to the backup domain manager.

Synopsisswitchmgr domain;newmgr

Argumentsdomain Specifies the domain in which you want to switch managers.

newmgr Specifies the name of the new domain manager. This must be a workstationin the same domain, and should be defined beforehand as a fault-tolerantagent with Resolve Dependencies and Full Status enabled.

Usage NotesThe command stops a specified workstation and restarts it as the domain manager. Alldomain member workstations are informed of the switch, and the old domain manager isconverted to a fault-tolerant agent in the domain.

The identification of domain managers is carried forward to each new day’s Symphony file,so that switches remain in effect until a subsequent switchmgr command is executed.However, if new day processing (the Jnextday job) is performed on the old domainmanager, the domain will act as though another switchmgr command had been executed andthe old domain manager will automatically resume domain management responsibilities.

ExamplesThe following example switches the domain manager to workstation orca in the masterdmdomain:switchmgr masterdm,orca

The following example switches the domain manager to workstation ruby in the bldg2domain:switchmgr bldg2,ruby


|

4.C

on

man

Referen

ce

System CommandExecutes a system command.

Synopsis[: | !] sys-command

Argumentssys-command Specifies any valid system command. The prefix (: or !) is required only

when a command name has the same spelling as a Conman command.

ExamplesThe following example executes a ps command on UNIX:ps -ef

The following example executes a dir command on Windows NT:dir \bin

174 Version 8.1

tellopSends a message to the scheduler console.

Synopsisto [text]

Argumentstext Specifies the text of the message. The message can contain up to 900

characters.

Usage NotesIf tellop is issued on the master domain manager, the message is sent to all linkedworkstations. If issued on a domain manager, the message is sent to all of the linked agentsin its domain and subordinate domains. If issued on a workstation other than a domainmanager, the message is sent only to its domain manager if it is linked. The message isdisplayed only if the console message level is greater than zero. See “console” on page 114.

If tellop is entered alone, it prompts for the message text. At the prompt, type each line andpress the Return key. At the end of the message, type two slashes (//) or a period (.), andpress the Return key. You can use the new line sequence (\n) to format messages. TypingControl+c at any time will exit the tellop command without sending the message.

ExamplesThe following example sends a message:tellop TWS will be stopped at\n4:30 for 15 minutes.

The following example prompts for text before sending a message:toTELLOP>*********************************TELLOP>* TWS will be stopped at *TELLOP>* 4:30 for 15 minutes. *TELLOP>*********************************TELLOP>//


4.C

on

man

Referen

ce

unlinkCloses communications links between workstations.

You must have unlink access to the target workstation.

Synopsisunlink [domain!]wkstation[;noask]

Argumentsdomain Specifies the name of the domain in which to close links. Because

workstations have unique names, a domain is not needed when unlinking aspecific workstation. Wildcard characters are permitted.

This argument is useful when unlinking more than one workstation in adomain. For example, to unlink all the agents in domain stlouis, use thefollowing command:link stlouis!@

If you do not specify domain, and wkstation includes wildcard characters,the default domain is the one in which Conman is running.

wkstation Specifies the name of the workstation to be unlinked. Wildcard charactersare permitted.


Usage NotesAssuming that a user has unlink access to the workstations being unlinked, the followingrules apply:

¶ A user running Conman on the master domain manager can unlink any workstation inthe network.

¶ A user running Conman on a domain manager other than the master can unlink anyworkstation in its own domain and subordinate domains. The user cannot unlinkworkstations in peer domains.

¶ A user running Conman on an agent can unlink any workstation in its local domain.

For additional information see “link” on page 125.

ExamplesThe illustration and table below show the links closed by unlink commands executed byusers in various locations in the network.

176 Version 8.1


Command Closed by User1 Closed by User2 Closed by User3

unlink @!@ All links are closed. DM1-DM2DM2-A21DM2-A22DM2-DM4DM4-A41DM4-A42

DM2-A21DM2-A22

unlink @ DM1-A11DM1-A12DM1-DM2DM1-DM3

DM1-DM2DM2-A21DM2-A22DM2-DM4

DM2-A21DM2-A22

unlink domain3!@ DM3-A31DM3-A32


unlink domain4!@ DM4-A41DM4-A42

DM4-A41DM4-A42

Not allowed.

unlink DM2 DM1-DM2 Not applicable. DM2-A21

unlink A42 DM4-A42 DM4-A42 Not allowed.

unlink A31 DM3-A31 Not allowed. Not allowed.

Figure 4. Unlinked Network Workstations


4.C

on

man

Referen

ce

versionDisplays Conman’s program banner.

Synopsisversion

ExamplesThe following example displays Conman’s program banner:%versionMAESTRO for UNIX (HPUX)/CONMAN 6.0 (3.34) (C) Tivoli Systems 1998Schedule 5/16/98 (#7) on SFO. Batchman down. Limit: 6, Fence: 0

178 Version 8.1

Utility Commands

This chapter describes Tivoli Workload Scheduler utility commands. These commands aretools to help you manage the scheduler. The commands, with the exception of StartUp andversion, are installed in TWShome/bin directory. StartUp is installed in the TWShomedirectory, and version is installed in the TWShome/version directory.

Command Descriptions

Command Description

at | mat For UNIX only. Submits a job to be executed at a specific time.

batch | mbatch For UNIX only. Submits a job to be executed as soon as possible.

caxtract Extracts information about calendars.

cpuinfo Returns information from a workstation definition.

datecalc Converts date and time to a desired format

dbexpand Expands scheduler databases.

delete Removes script files and standard list files by name.

evtsize Defines the maximum size of event message files.

jbxtract Extracts information about jobs.

jobinfo Returns information about a job.

jobstdl Returns the pathnames of standard list files.

listproc For Windows NT only. Lists processes. This command is unsupported.

killproc For Windows NT only. Kills processes. This command is unsupported.

maestro Returns the scheduler home directory.

makecal Creates custom calendars.

morestdl Displays the contents of standard list files.

parms Displays, changes, and adds parameters.

paxtract Extracts information about parameters.

prxtract Extracts information about prompts.

r11xtr Extracts information about job streams.

release Releases units of a resource.

rextract Extracts information about resources.

rmstdlist Removes standard list files based on age.

showexec For UNIX only. Displays information about executing jobs.

StartUp Starts the Netman process.

version For UNIX only. Displays version information.

5


5.U

tilityC

om

man

ds

Command Description

xrxtrct Extracts information about cross-references.

wmaeutil Extracts information about cross-references.

180 Version 8.1

at | batch Commands

For UNIX only. Submits ad hoc commands and jobs to be launched by Workload Scheduler.When you install the scheduler, the following links are created by default:

/usr/bin/mat —>TWShome/bin/at/usr/bin/mbatch —> TWShome/bin/batch

See at.allow and at.deny below for information about the availability to users.

Synopsisat | mat -v | -u

at | mat -sjstream | -qqueuetime-spec

batch | mbatch -v | -u

batch | mbatch [-s jstream]

Arguments-v Displays the command version and exits.

-u Displays command usage information and exits.

-s jstream

Specifies the name of a job stream into which the job is submitted. If the job streamdoes not exist, it is created. The name must start with a letter, and can containalphanumeric characters and dashes. For non-expanded databases, it can contain upto eight characters. For expanded databases, it can contain up to 16 characters.

If the -s and -q arguments are omitted, a job stream name is selected based on thevalue of the environment variable ATSCRIPT. If ATSCRIPT contains the wordmaestro, the job stream name will be the first eight characters of the user’s groupname. If ATSCRIPT is not set, or is set to a value other than maestro, the jobstream name will be at (for jobs submitted with at), or batch (for jobs submittedwith batch).

See “Other Considerations” on page 183 for more information about job streams.

-qqueueSpecifies to submit the job into a job stream with the name queue, which can be asingle letter (a through z). See “Other Considerations” on page 183 for moreinformation about job streams.

time-specSpecifies the time at which the job will be launched. For at jobs only. The syntax isthe same as that used with the UNIX at command.

Usage NotesAfter entering at or batch, enter the commands that constitute the job. End each line ofinput by pressing the Return key. The entire sequence is ended with end-of-file (usuallyControl+d), or by entering a line with a period (.). Alternatively, use an angle bracket (<) toread commands from a file. See “Examples” on page 183.


5.U

tilityC

om

man

ds

Information about at and batch jobs is sent to the master domain manager, where the jobsare added to job streams in the production plan, Symphony. The jobs are launched based onthe dependencies included in the job streams.

The UNIX shell used for jobs submitted with the Workload Scheduler at and batchcommands is determined by the SHELL_TYPE variable in the jobmanrc configurationscript. Do not use the C shell. For more information, see the Tivoli Workload SchedulerPlanning and Installation book.

Once submitted, jobs are launched in the same manner as other scheduled jobs. Each jobexecutes in the submitting user environment. To ensure that the environment is complete, setcommands are inserted into the script to match the variable settings in the user’senvironment.

Replacing the UNIX CommandsThe standard UNIX at and batch commands can be replaced by scheduler commands. Thefollowing commands illustrate how to replace the UNIX at and batch commands:$ mv /usr/bin/at /usr/bin/uat$ mv /usr/bin/batch /usr/bin/ubatch$ ln -s TWShome/bin/at /usr/bin/at$ ln -s TWShome/bin/batch /usr/bin/batch

Note that the customize script installs links to its at and batch commands by default. Thispermits the commands to be run as follows:/usr/bin/mat

/usr/bin/mbatch

The at.allow and at.deny FilesThe at and batch commands use the files /usr/lib/cron/at.allow and /usr/lib/cron/at.deny torestrict usage. If the at.allow file exists, only users listed in the file are allowed to use atand batch. If the file does not exist, at.deny is checked to see if the user is explicitly deniedpermission. If neither of the files exists, only the root user is permitted to use thecommands. If the commands are executed as mat and mbatch, at.allow and at.deny areignored, and no restrictions apply.

Script FilesThe commands entered with at or batch are stored in script files. The file are created by thescheduler using the following naming convention:

TWShome/atjobs/epoch.sss

where:

epoch The number of seconds since 00:00, 1/1/70.

sss The first three characters of the job stream name.

Note: The scheduler removes script files for jobs that are not carried forward. However,Tivoli recommends that you monitor the disc space in the atjobs directory andremove older files if necessary.

182 Version 8.1

Job NamesAll at and batch jobs are given unique names by the scheduler when they are submitted.The names consist of the user’s process ID (PID) preceded by the user’s name truncated soas not to exceed eight characters. The resulting name is upshifted.

Other ConsiderationsTivoli recommends that the job streams into which at and batch jobs are submitted becreated beforehand with Composer. The job streams can contain dependencies that determinewhen the jobs will be launched. At a minimum, the job streams should contain thecarryforward keyword. This will ensure that jobs that do not complete, or are not launched,during the current day will be carried forward to the next day’s production plan. Some othersuggestions regarding at and batch job streams:

¶ Include the expression on everyday to have the job streams selected every day.

¶ Use the limit keyword to limit the number of submitted jobs that can be runconcurrently.

¶ Use the priority keyword to set the priority of submitted jobs relative to other jobs.

If the time value is less than the current time, the value is regarded as for the following day.If the time value is greater than the current time, the value is regarded as for the current day.If the time value is greater than 2400, the value is divided by 2400 to obtain the number ofdays. If you specify the time value in days, this is added to the value obtained by dividingby 2400.

ExamplesThe following example submits a job into job stream sched8 to be launched as soon aspossible:mbatch -s sched8command <Return>...<Control d>

The following example submits a job into job stream k to be launched at 9:45 P.M.:mat -qk 21h45command <Return>...<Control d>

The following example submits a job to be launched two hours from the time at which thecommand was entered:TWShome/bin/at now + 2 hourscommand <Return>...<Control d>

If the variable ATSCRIPT is null, the job is submitted into a job stream having the samename of the user’s group. Otherwise, it is submitted into a job stream named at.

The following example submits a job into job stream sked-mis to be launched at 5:30 P.M.:mat -s sked-mis 17h30command <Return>...<Control d>


|||||

5.U

tilityC

om

man

ds

The following example is the same as the previous example, except that the job’s commandsare read from a file:mat -s sked-mis 17h30 < ./myjob

The fact that the commands are read from a file does not change the way they areprocessed. That is, the commands are copied from the ./myjob file into a script file.

184 Version 8.1

caxtract Command

Extracts information about calendars from the the scheduler database.

Synopsiscaxtract [-v | -u] [-o file]



-o file Specifies the output file. The default is stdout.

Command OutputEach calendar record contains tab-delimited, variable length fields. The fields are describedin the following table.

Field Description Max Length (bytes)

1 calendar name 8

2 calendar description 64

ExamplesExtract information about all calendar definitions and direct the output to the file cainfo:caxtract -o cainfo


5.U

tilityC

om

man

ds

cpuinfo CommandReturns information from a workstation definition.

Synopsiscpuinfo -v | -u

cpuinfo wkstation [infotype] [...]



wkstation

The name of the workstation.

infotypeThe type of information to display. Specify one or more of the following:

os_typeReturns the value of the os field: MPEV, MPIX, UNIX, WNT, or OTHER.

node Returns the value of the node field.

port Returns the value of the port field.

autolinkReturns the value of the autolink field: ON or OFF.

fullstatusReturns the value of the fullstatus field: ON or OFF.

resolvedepReturns the value of the resolvedep field: ON or OFF.

host Returns the value of the host field.

methodReturns the value of the access field.

server Returns the value of the server field.

type Returns the type of workstation: MASTER, MANAGER, FTA, S-AGENT,and X-AGENT.

time_zoneReturns the time zone of the workstation. For an extended agent, the field isblank.

versionReturns the scheduler version that is running on the workstation. For anextended agent, the field is blank.

info Returns the operating system version and workstation model. For anextended agent, the field is blank.

186 Version 8.1

Usage NotesThe values are returned, separated by new lines, in the same order that the arguments wereentered on the command line. If no arguments are specified, all applicable information isreturned with labels, separated by new lines.

ExamplesThe examples below are based on the following workstation definition:cpuname oakos UNIXnode oak.tivoli.comtcpaddr 31111

for maestroautolink onfullstatus onresolvedep on

end

The following example prints the os type for workstation oak:>cpuinfo oak os_typeUNIX

The following example prints the node and port for workstation oak:>cpuinfo oak node portoak.tivoli.com31111

The following example prints all information for workstation oak:>cpuinfo oakOS TYPE:UNIXNODE:oak.tivoli.comPORT:31111AUTOLINK:ONFULLSTATUS:ONRESOLVEDEP:ONHOST:METHOD:SERVER:TYPE: FTATIME ZONE:US/PacifVERSION:6.1INFO:SunOS 5.3 Generic 1016 sun4m


5.U

tilityC

om

man

ds

datecalc CommandResolves date expressions and returns dates in desired formats.

Synopsisdatecalc -v | -u

datecalc base-date [offset] [pic format][freedays Calendar_Name [-sa] [-su]]

datecalc -t time [base-date] [offset] [pic format]

datecalc yyyymmddhhtt [offset] [pic format]



base-date

Specify one of the following:

day | date | today | tomorrow | scheddate

where:

day Specifies a day of the week. Valid values are: su, mo, tu, we, th, fr, or sa.

date Specifies a date, in the format element/element[/element], where element is:d[d], m[m], and yy[yy].

If two digits are used for the year (yy), a number greater than 70 is a 20thcentury date, and a number less than 70 is a 21st century date.

Valid values for the month (m[m]) are jan, feb, mar, apr, may, jun, jul,aug, sep, oct, nov, or dec.

The slashes (/) can be replaced by dashes (-), periods (.), commas (,), orspaces. For example, any of the following can be entered for March 28,1999:

03/28/993-28-199928.mar.9999,28,3mar 28 199928 3 99

If numbers are used, it is possible to enter an ambiguous date, for example,2,7,98. In this case, datecalc uses the date format defined in the schedulermessage catalog to interpret the date. If the date does not match the format,datecalc generates an error message.

today Specifies the current system date.

tomorrowSpecifies the current system date plus one day, or, in the case of timecalculations, plus 24 hours.

188 Version 8.1

|

scheddateSpecifies the date of the production plan. This may not be the same as thesystem date. When used inside jobs within carried forwarded jobstreams, itwill use the production date for which it was originally scheduled (theproduction date of the carried forward jobstream).

-t time [base-date]Specify time in one of the following formats:

now | noon | midnight | [h[h][[:]mm] [am | pm] [zulu]

where:

now Specifies the current system date and time.

noon Specifies 12:00 P.M. (or 1200).

midnightSpecifies 12:00 A.M. (or 0000).

h[h][[:]mm]Specifies the hour and minute in 12-hour time (if am or pm are used), or24-hour time. The optional colon (:) delimiter can be replaced by a period(.), a comma (,), an apostrophe (’), the letter h, or a space. For example, anyof the following can be entered for 8:00 P.M.:

8:00pm20:000800pm20008pm208,00pm20.008\’00pm20 00

zulu Specifies that the time you entered is Greenwich Mean Time (UniversalCoordinated Time). datecalc will convert it to the local time.

yyyymmddhhttSpecifies the year, month, day, hour, and minute expressed in exactly twelve digits.For example, for 1999, May 7, 9:15 A.M., enter the following: 199905070915

offset Specifies an offset from base-date in the following format:

{[+ | > | - | < number | nearest] | next} day[s] | weekday[s] |workday[s] | week[s] | month[s] | year[s] | hour[s] | minute[s] |day | calendar

where:

+ | > Specifies an offset to a later date or time. Use + (Plus) on Windows NT. Use> (Greater than) on UNIX. Be sure to escape the angle bracket (″\>″).

- | < Specifies an offset to an earlier date or time. Use - (Minus) on Windows NT.Use < (Less than) on UNIX. Be sure to escape the angle bracket (″\<″).


||||

|||

|||

5.U

tilityC

om

man

ds

numberThe number of units of the specified type.

nearestSpecifies an offset to the nearest occurrence of the unit type (earlier orlater).

next Specifies the next occurrence of the unit type.

day[s] Specifies every day.

weekday[s]Specifies every day except Saturday and Sunday.

workday[s]Same as weekday[s], but also excludes the dates on the holidays calendar.

week[s]Specifies seven days.

month[s]Specifies calendar months.

year[s]Specifies calendar years.

hour[s]Specifies clock hours.

minute[s]Specifies clock minutes.

day Specifies a day of the week. Valid values are: su, mo, tu, we, th, fr, or sa.

calendarSpecifies the entries in a calendar by this name.

pic formatSpecifies the format in which the date and time are returned. The format charactersare as follows:

m Month number.

d Day number.

y Year number.

j Julian day number.

h Hour number.

t Minute number.

^|/ One space. Use ^ (carat) on UNIX (this character must be escaped (\) in theBourne shell). Use / (slash) on Windows NT.

You can also include punctuation characters. These are the same as the delimitersused in date and time.

If a format is not defined, datecalc returns the date and time in the format definedby the Native Language Support (NLS) enviroment variables. If the NLS variablesare not defined, the native language defaults to C.

190 Version 8.1

|||

freedaysSpecifies the name of a freedays calendar Calendar_Name that is to replaceholidays in the evaluation of workdays.

In this case, workdays is evaluated as everyday excluding saturday, sunday and allthe dates listed in Calendar_Name.

By default, saturday and sunday are not regarded as workdays, unless you explicitlystate the opposite by adding -sa and/or -su after Calendar_Name.

You can also specify holidays as the name of the freedays calendar.

ExamplesThe following example returns the next date, from today, on the monthend calendar:>datecalc today next monthend

In the following examples, the current system date is Friday, April 9, 1999.>datecalc today +2 days pic mm/dd/yy04/11/99

>datecalc today next tu pic yy\^mm\^dd99 04 13

>LANG=american;export LANG>datecalc -t 14:30 tomorrowSat, Apr 10, 1999 02:30:00 PM

>LANG=french;datecalc -t 14:30 tomorrowSamedi 10 avril 1999 14:30:00

In the following example, the current system time is 10:24.>datecalc -t now \> 4 hours pic hh:tt14:24


|||

||

||

|

5.U

tilityC

om

man

ds

dbexpand Command

Converts the databases on the master domain manager from non-expanded mode toexpanded mode. The command sets the expanded version global option to yes, and makesbackup copies of your old database files that you can use to return to non-expanded mode ifnecessary.

If you update your network in stages and it contains workstations running Tivoli MaestroVersion 5.x or earlier, you must use non-expanded databases until all of your computershave been updated to Tivoli Maestro 6.x or Tivoli Workload Scheduler. When all of thecomputers are updated, run dbexpand on the master domain manager to convert thedatabases to expanded mode.

Synopsisdbexpand -v | -u

dbexpand -n [-b backup-dir ]



-n

Specifies not to prompt for a backup directory name. If -b is included, the nameddirectory is used for backup. If -b is not included, the default directory is used. Ineither case, if the directory exists, it is overwritten.

-b backup-dirSpecifies a directory in which to backup the database files. The default directory is:

TWShome/mozart/mozart.old

If -n is omitted and the backup directory already exists, you are prompted for abackup directory name.

Usage NotesYou can run the dbexpand command without stopping the scheduler. However, you cannotsubmit jobs or job streams into the current production plan until after the new day turnoveroccurs. For this reason, Tivoli recommends that you run dbexpand shortly before theJnextday job runs.

ExamplesThe following example expands the databases and backs up the current files in the/usr/lib/maestro/temp directory. If the directory already exists, it overwrites its contents.dbexpand -n -b /usr/lib/maestro/temp

The following example expands the databases and backs up the current files in thec:\programs\wsched\temp directory. A prompt is displayed if the directory already exists.dbexpand -b c:\programs\wsched\temp

192 Version 8.1

delete Command

Removes files. This command is intended to remove standard list files. The users maestroand root on UNIX, and Administrator on Windows NT can remove any file. Other userscan remove only files associated with their own jobs.

Synopsisdelete -v | -u

delete filename



filename

Specifies the name of the file or group of files to be removed. The name must beenclosed in quotes (″) if it contains characters other than the following:alphanumerics, dashes (-), slashes (/), backslashes (\), and underscores (_). Wildcardcharacters are permitted.

CAUTION:Use this command carefully. Improper use of wildcard characters can result inremoving files accidentally.

ExamplesThe following example removes all the standard list files for 4/11/99:delete d:\win32app\maestro\stdlist\1999.4.11\@

The following script, included in a scheduled job on UNIX, removes the job’s standard listfile if there are no errors:...#Remove the stdlist for this job:if grep -i error $UNISON_STDLISTthenexit 1elsevmaestrov/bin/delete $UNISON_STDLISTfi...

Note that the standard configuration script, jobmanrc, sets the variable UNISON_STDLISTto the name of the job standard list file. For more information about jobmanrc refer to theTivoli Workload Scheduler Planning and Installation book.


5.U

tilityC

om

man

ds

evtsize Command

Defines the size of the scheduler event files. This command is used to increase the size ofan event file after receiving the message, “End of file on events file.” You must be maestroor root on UNIX, or Administrator on Windows NT to run evtsize.

Synopsisevtsize -v | -u

evtsize filename size



filenameThe name of the event file. Specify one of the following:

Courier.msgIntercom.msgMailbox.msgmaestro.msgnetman.msgunison.msgpobox/wkstation.msg

size The maximum size of the event file in bytes. When first built by the scheduler, themaximum size is set to 1 MB.

ExamplesThe following example sets the maximum size of the Intercom file to 2 MB:evtsize Intercom.msg 2000000

The following example sets the maximum size of the pobox file for workstation chicago to1.5 MB:evtsize pobox\chicago.msg 1500000

194 Version 8.1

jbxtract Command

Extracts information about jobs from the scheduler database.

Synopsisjbxtract [-v | -u] [-j job] [-c wkstat] [-o file]



-j job Specifies the job for which extraction is performed. The default is all jobs.

-c wkstatSpecifies the workstation of jobs for which extraction is performed. The default isall workstations.


Command OutputThe MAESTRO_OUTPUT_STYLE variable specifies the the output style for long objectnames. Set the variable to LONG to use full length (long) fields for object names. If thevariable is not set or is set to anything other than LONG, and the global option expandedversion is set to yes, long names are truncated to eight characters and a plus sign. Forexample: A1234567+. If the expanded version option is set to no, long names are truncatedto eight characters.

Each job record contains tab-delimited, variable length fields. The fields are described in thefollowing table.

Field Description Max Length (bytes) *

1 workstation name 8/16

2 job name 8/16

3 job script file name 256/4096

4 job description 65

5 recovery job name 16

6 recovery option (0=stop, 1=rerun, 2=continue) 5

7 recovery prompt text 64

8 auto-documentation flag (0=disabled, 1=enabled) 5

9 job login user name 36

10 job creator user name 36

11 number of successful runs 5

12 number of abended runs 5

13 total elapsed time of all job runs 8

14 total cpu time of all job runs 8

15 average elapsed time 8

16 last run date (yymmdd) 8

17 last run time (hhmm) 8

18 last cpu seconds 8


5.U

tilityC

om

man

ds


19 last elapsed time 8

20 maximum cpu seconds 8

21 maximum elapsed time 8

22 maximum run date (yymmdd) 8

23 minimum cpu seconds 8

24 minimum elapsed time 8

25 minimum run date (yymmdd) 8

* non-expanded databases/expanded databases

ExamplesExtract information about job myjob on workstation main and direct the output to the filejinfo:jbxtract -j myjob -c main -o jinfo

196 Version 8.1

jobinfo CommandUsed in a job script to return information about the job.

Synopsisjobinfo -v | -u

jobinfo job-option [...]



job-option

The job option. Specify one or more of the following:

confirm_jobReturns YES if the job requires confirmation.

is_commandReturns YES if the job was scheduled or submitted using the docommandconstruct.

job_nameReturns the job’s name without the workstation and job stream names.

job_priReturns the job’s priority level.

programmatic_jobReturns YES if the job was submitted with the scheduler at or batchcommand. UNIX only.

re_jobReturns YES if the job is being rerun as the result of a Conman reruncommand, or the rerun recovery option.

re_typeReturns the job’s recovery option (stop, continue, or rerun).

rstrt_flagReturns YES if the job is being run as the recovery job.

time_startedReturns the time the job started executing.

Usage NotesJob option values are returned, separated by new lines, in the same order they wererequested.

ExamplesThe script file /jcl/backup is documented twice, giving it the job names partback andfullback. If the job runs as partback, it performs a partial backup. If it runs as fullback, itperforms a full backup. Within the script, commands like the following are used to make thedetermination:


5.U

tilityC

om

man

ds

#Determine partial (1) or full (2):if [ "v\vmaestro\v/bin/jobinfo job_namev" = "PARTBACK" ]thenbkup=1elsebkup=2fi...

198 Version 8.1

jobstdl CommandReturns the names of standard list files.

Synopsisjobstdl -v | -u

jobstdl [-day num] [-first | -last | -num n | -all][-name jstream.job | jobnum]



-day numReturns the names of standard list files that are the specified number of days old (1for yesterday, 2 for the day before yesterday, and so on). The default is zero (today).

-first Returns the name of the first qualifying standard list file.

-last Returns the name of the last qualifying standard list file.

-num nReturns the name of the standard list file for the specified run of a job.

-all Returns the name of all qualifying standard list files.

-name jstream.jobSpecifies the name of the job stream and job for which standard list file names arereturned.

jobnumSpecifies the job number of the job for which standard list file names are returned.

Usage NotesFile names are returned in a format suitable for input to other commands. Multiple namesare returned separated by one space.

ExamplesThe following example returns the path names of all standard list files for the current day:jobstdl

The following example returns the path name of the standard list for the first run of jobmailxhg1.getmail on the current day:jobstdl -first -name mailxhg1.getmail

The following example returns the path name of the standard list for the second run of jobmailxhg1.getmail on the current day:jobstdl -num 2 -name mailxhg1.getmail

The following example returns the path names of the standard list files for all runs of jobmailxhg1.getmail from three days ago:jobstdl -day 3 -name mailxhg1.getmail

The following example returns the path name of the standard list for the last run of jobmailxhg1.getmail from four days ago:


5.U

tilityC

om

man

ds

jobstdl -day 4 -last -name mailxhg1.getmail

The following example returns the path name of the standard list for job number 455:jobstdl 455

The following example prints the contents of the standard list file for job number 455:cd vmaestrov/binlp -p 6 vjobstdl 455v

200 Version 8.1

maestro CommandReturns the path name of the scheduler home directory, referred to as TWShome

.

Synopsismaestro [-v | -u]



ExamplesThe following example displays the scheduler home directory:$ maestro/usr/lib/maestro

The following example changes the directory to the scheduler home directory:$ cd vmaestrov


5.U

tilityC

om

man

ds

makecal CommandCreates a custom calendar. On UNIX, the Korn shell is required to execute this command.

Synopsismakecal [-v | -u]

makecal [-c name] -d n | -e | {-f 1 | 2 | 3 -s date} | -l | -m | -p n |{-r n -s date} | -w n [-i n] [-x | -z][-freedays Calendar_Name [-sa] [-su]]



-c nameSpecifies a name for the calendar. Workload Scheduler keywords (such as Freedaysor Schedule) cannot be used as calendar names. The name can contain up to eightalphanumeric characters and must start with a letter. The default name is: Chhmm,where hhmm is the current hour and minute.

-d n Specifies the nth day of every month.

-e Specifies the last day of every month.

-f 1 | 2 | 3Creates a fiscal month-end calendar containing the last day of the fiscal month.Specify one of the following formats:

1 4-4-5 week format

2 4-5-4 week format

3 5-4-4 week format

This argument requires the -s argument.

-i n Specifies to put n dates in the calendar.

-l Specifies the last workday of every month. For this argument to work properly, theproduction plan (Symphony file) and the holidays calendar must already exist.

Note: Using this argument results in the new calendar including also the lastworkday of the month that precedes the date of creation of the calendar.

-m Specifies the first and fifteenth days of every month.

-p n Specifies the workday before the nth day of every month. For this argument to workproperly, the production plan (Symphony file) and the holidays calendar mustalready exist

-r n Specifies every nth day. This argument requires the -s argument.

-s dateSpecifies the starting date for the -f and -r arguments. The date must be enclosed inquotation marks, and must be valid and unambiguous, for example, use JAN 101999, not 1/10/99. See base-date for datecalc on page 188 for more informationabout date formats.

202 Version 8.1

||||

||

-w n Specifies the workday after the nth of the month. For this argument to workproperly, the production plan (Symphony file) and the holidays calendar mustalready exist.

-x Sends the calendar output to stdout rather than adding it to the calendar database.

-z Adds the calendar to the calendar database and compiles the production plan(Symphony file). WARNING: This argument re-submits jobs and job streams fromthe current day’s production plan. It may be necessary to cancel job streams andjobs.

-freedaysSpecifies the name of a freedays calendar Calendar_Name that is to replaceholidays in the evaluation of workdays.

In this case, workdays is evaluated as everyday excluding saturday, sunday and allthe dates listed in Calendar_Name.

By default, saturday and sunday are not regarded as workdays, unless you explicitlystate the opposite by adding -sa and/or -su after Calendar_Name.

You can also specify holidays as the name of the freedays calendar.

This keyword affects the processing of makecal with options -l, -p, and -w.

ExamplesThe following example makes a two-year calendar with the last day of every monthselected:makecal -e -i24

The following example makes a calendar wtih 30 days that starts on May 30, 1999, and hasevery third day selected:makecal -r 3 -s "30 MAY 1999" -i30


|||

||

||

|

|

5.U

tilityC

om

man

ds

morestdl CommandDisplays the contents of standard list files.

Synopsismorestdl -v | -u

morestdl [-day num] [-first | -last | -num n | -all][-name jstream.job | jobnum]



-day numDisplays standard list files that are the specified number of days old (1 for yesterday,2 for the day before yesterday, and so on). The default is zero (today).

-first Displays the first qualifying standard list file.

-last Displays the last qualifying standard list file.

-num nDisplays the standard list file for the specified run of a job.

-all Displays all qualifying standard list files.

-name jstream.jobSpecifies the name of the job stream and job for which the standard list file isdisplayed.

jobnumSpecifies the job number of the job for which the standard list file is displayed.

ExamplesThe following example displays the standard list file for the first run of jobmailxhg1.getmail on the current day:morestdl -first -name mailxhg1.getmail

The following example displays the standard list file for the second run of jobmailxhg1.getmail on the current day:morestdl -num 2 -name mailxhg1.getmail

The following example displays the standard list files for all runs of job mailxhg1.getmailfrom three days ago:morestdl -day 3 -name mailxhg1.getmail

The following example displays the standard list file for the last run of jobmailxhg1.getmail from four days ago:morestdl -day 4 -last -name mailxhg1.getmail

The following example prints the standard list file for job number 455:morestdl 455 | lp -p 6

204 Version 8.1

parms CommandReturns the current value of a parameter, changes the value of a parameter, or adds a newparameter.

Synopsisparms [-v | -u]

parms name

parms -c name value



name Specifies the name of the parameter whose value is displayed.

-c name valueSpecifies the name and the value of a parameter. The value can contain up to 72characters. Quotation marks are required if the value contains special characters. Ifthe parameter does not exist, it is added to the database. If the parameter alreadyexists, its value is changed.

Usage NotesWhen parms is run at the command line without arguments, it prompts for parameter namesand values.

ExamplesThe following example returns the value of myparm:parms myparm

The following example changes the value of myparm:parms -c myparm "item 123"

The following example creates a new parameter named hisparm:parms -c hisparm "item 789"

The following example changes the value of myparm and adds herparm:parmsName of parameter ? myparm < Return>Value of parameter? "item 456" < Return>Name of parameter ? herparm < Return>Value of parameter? "item 123" < Return>Name of parameter ? < Return>


5.U

tilityC

om

man

ds

paxtract Command

Extracts information about parameters from the scheduler database.

Synopsispaxtract [-v | -u] [-o file]




Command OutputEach parameter record contains tab-delimited, variable length fields. The fields are describedin the following table.


1 parameter name 8

2 parameter value 64

ExamplesExtract information about all parameter definitions and direct the output to the file painfo:paxtract -o painfo

206 Version 8.1

prxtract Command

Extracts information about prompts from the scheduler database.

Synopsisprxtract [-v | -u] [-o file]




Command OutputEach prompt record contains tab-delimited, variable length fields. The fields are described inthe following table.


1 prompt name 8

2 prompt value 200

ExamplesExtract information about all prompt definitions and direct the output to the file prinfo:prxtract -o prinfo


5.U

tilityC

om

man

ds

r11xtr Command

Extracts information about job streams from the scheduler database.

Synopsisprxtract [-v | -u] [-m mm[yy]] [-c wkstat] [-o file]



-m mm[yy]Specifies the month (mm) and, optionally, the year (yy) of the job streams. Thedefault is the current month and year.

-c wkstatSpecifies the workstation of the job streams. The default is all workstations.



Each job stream record contains tab-delimited, variable length fields. The fields aredescribed in the following table.



2 job stream name 8/16

3 job stream date (yymmdd) 6

4 estimated cpu seconds 6

5 multiple workstation flag (* means some jobs run on otherworkstations)

1

6 number of jobs 4

7 day of week (Su, Mo, Tu, We, Th, Fr, Sa) 2


ExamplesExtract information about job streams on June 1999 for workstation main:r11xtr -m 0699 -c main

Extract information about job streams on June of this year for all workstations, and directthe output to file r11out:r11xtr -m 06 -o r11out

208 Version 8.1

release CommandReleases units of a resource at the job stream or job level.

Synopsisrelease -v | -u

release [-s] [wkstation#]resourcename



-s Releases resource units only at the job stream level.

If -s is not used, resource units are released at the job level, or at the job streamlevel if the resource is not found at the job level.

wkstation#Specifies the name of the workstation or workstation class on which the resource isdefined. The default is the local workstation.

resourcenameSpecifies the name of the resource.

Usage NotesUnits of a resource are acquired by a job or job stream at the time it is launched and arereleased automatically when the job or job stream completes. The release command can beused in a job script to release resources before job or job stream completion. Units of aresource are released in the same order that they were acquired.

ExamplesIn the following job stream, two units of the dbase resource are required by stream sked5:schedule ux1#sked5 on tuneeds 2 dbase :job1jobrel follows job1job2 follows jobrelend

To release the dbase resource before job2 begins, the script file for jobrel contains thefollowing command:vmaestrov/bin/release -s dbase

Note that the -s argument can be omitted, since no resources were reserved at the job level.

In the following job stream, eight units of the discio resource are required by job2. This isdefined in two blocks of 5 and 3 so that they can be released incrementally in the sameorder they were acquired.schedule ux1#sked7 on weekdays:job1job2 follows job1 needs 5 discio,3 disciojob3 follows job2end


5.U

tilityC

om

man

ds

To release the discio resource incrementally while job2 is executing, the script for job2contains the following command lines:...# Release 5 units of discio:vmaestrov/bin/release discio...# Release 3 units of discio:vmaestrov/bin/release discio...

210 Version 8.1

rextract Command

Extracts information about resources from the scheduler database.

Synopsisrextract [-v | -u] [-o file]




Command OutputEach resource record contains tab-delimited, variable length fields. The fields are describedin the following table.



2 resource name 8

3 total resource units 4

4 resource description 72


ExamplesExtract information about all resource definitions and direct the output to the file reinfo:rextract -o reinfo


5.U

tilityC

om

man

ds

rmstdlist CommandRemoves or displays standard list files based on the age of the file.

Synopsisrmstdlist -v | -u

rmstdlist [-p] [age]



-p Displays the names of qualifying standard list file directories. No directories or filesare removed. If you do not specify -p, the qualifying standard list files are removed.

age The minimum age, in days, of standard list file directories to be displayed orremoved. The default is 10 days.

ExamplesThe following example displays the names of standard list file directories that are more than14 days old:rmstdlist -p 14

The following example removes all standard list files (and their directories) that are morethan 7 days old:rmstdlist 7

212 Version 8.1

showexec CommandDisplays the status of executing jobs. For UNIX only. This command is for standard agents.On domain managers and fault-tolerant agents, use the conman showjobs

command instead.

Synopsisshowexec [-v | -u | -info]



-info Displays the name of the job file name instead of the user, date, and time.

Command OutputThe output of the command is available in two formats: standard, and info.

Standard Format

CPU The workstation on which the job executes.

Schedule The name of the job stream in which the job executes.

Job The job name.

Job# The job number.

User The user name of the job.

Start Date The date the job started executing.

Start Time The time the job started executing.

(Est) Elapse The estimated time, in minutes, that the job will execute.

info Format

CPU The workstation on which the job executes.

Schedule The name of the job stream in which the job executes.

Job The job name.

Job# The job number.

JCL The file name of the job.

ExamplesThe following example displays executing jobs in the standard format:showexec

The following example displays executing jobs in the info format:showexec -info


5.U

tilityC

om

man

ds

StartUp CommandStarts the scheduler network management process, Netman. You must have start

access to the workstation.

SynopsisStartUp [-v | -u]



Usage NotesOn Windows NT, the Netman service is started automatically when a computer is restarted.StartUp can be used to restart the service if it is stopped for any reason.

On UNIX, the StartUp command is usually installed in the /etc/rc file, so that Netman isstarted each time a computer is rebooted. StartUp can be used to restart Netman if it isstopped for any reason.

The remainder of the process tree can be restarted with a conman start command. See“start” on page 160 for more information.

ExamplesThe following example displays the command name and version:StartUp -v

The following example starts the Netman process:StartUp

214 Version 8.1

version CommandDisplays scheduler version information. For UNIX only. The information is extracted from aversion file.

Synopsisversion/version -V | -u | -h

version/version [-a] [-f vfile] [-p product] [file [...]]

Arguments-V Displays the command version and exits.


-h Displays command help information and exits.

-a Displays information about all product files. The default is to display informationonly about the specified files.

-f vfile Specifies the name of the version file. The default is a file named version.info in thecurrent working directory, or the product directory specified with -p.

-p productSpecifies the Tivoli product name whose directory is directly below the currentworking directory, and contains a version.info file. If omitted, -f, or its default, isused.

file Specifies the names of product files, separated by spaces, for which versioninformation is displayed. The default is to display no file information, or, if -a isused, all file information.

Command OutputThe output header contains the product name, version, platform, patch level, and installationdate . The remaining display lists information about the file or files specified. The files arelisted in the following format:

File The name of the file.

Revision The revision number of the file.

Patch The patch level of the file, if any.

Size (bytes) The size of the file in bytes.

Checksum The checksum for the file. Checksums are calculated using the UNIX sumcommand. On AIX®, sum is used with the -o argument.

Usage NotesWorkload Scheduler file information is contained in the version.info file. This file is placedin the TWShome/version directory during installation. The version.info file is in a specificformat and should not be altered.

You can move the version.info file to another directory. However, you must then include the-f argument to locate the file.

You can use -p argument if your current directory contains the directories of multiple Tivoliproducts. This enables you to access version information by specifying the product name.


5.U

tilityC

om

man

ds

ExamplesThe following example displays information about all files:version/version -a -f version/version.info

The following example displays information about the file customize:cd version./version customize

The following example displays information about the file customize, when version.info islocated in /apps/maestro:cd version./version -f /apps/maestro/version.info customize

216 Version 8.1

wmaeutil Command

Used to stop the connector server for the plan, database, and engine. The makesec commandwill not run successfully on Windows NT until the connectors are stopped.

Synopsiswmaeutil instance_name [-stop DB | PL | EG | “*”] [-version DB | PL | EG | “*”][-dbinfo DB | PL | “*”] [-sethome] [-gethome] [ALL -stop]

Argumentsinstance_name

The name of the scheduler instance. This refers to the instance name you enteredduring installation of the scheduler engine, and the installation of the connector.

-stop DB | PL | EG | “*”This option can be used to shut down the specified connector server. The (*) asteriskcan be used to shut down all three connector servers. If used, it must be enclosed bydouble quotes.

-version DB | PL | EG | “*”This option is used to obtain the version number of the connector server for theplan, database, engine and installed on the system. The (*) asterisk can be used toobtain versions for all three connector servers at once. If used, it must be enclosedby double quotes.

-dbinfo DB | PL | “*”This option is used to find out if the scheduler database and plan to which thisconnector is linked is expanded or unexpanded. The (*) asterisk can be used toobtain versions for both database and plan. If used, it must be enclosed by doublequotes.

-sethomeThis option is used to set MaestroHomeDir attribute of the scheduler objects(Engine, Database, and Plan) in Tivoli’s object database. This attribute value linksconnectors for the specified object instance to the core scheduler product. It takesfully qualified name of the scheduler home directory as an arguments. Also thepathname string should be enclosed in quotes in order to prevent any shellinterpretation.

-gethomeThis option does not require any arguments and it prints the value of the TWShomeattribute for Engine, Database, and Plan object instances as set in the objectdatabase.

ALL -stopThis option stops the connector servers for all scheduler connector instancesconnected to the current scheduler installation, that is, it stops the connector serversfor all instances whose TWShome attribute matches the home directory of thescheduler current installation.

Usage Notes

Set Environment VariablesBefore wmaeutil can be run successfully, you must execute following file in order to setframework environment.


5.U

tilityC

om

man

ds

On Windows NT:c: \> %SystemRoot%\system32\drivers\etc\Tivoli\setup_env.cmd

For UNIX:$ . /etc/Tivoli/setup_env.sh

You can update your UNIX profile to run this file, in order to avoid having to run thecommand manually.

Makesec ConsiderationsThe wmaeutil command must be run before running the makesec command. The makeseccommand will not run successfully on Windows NT until the connectors are stopped. Youshould also stop the connectors when using the makesec command on UNIX.

Workload Scheduler Instance NameIf you do not remember the instance name that was entered at installation, perform thefollowing steps:

1. Source the Tivoli environment variables:. /etc/Tivoli/setup_env.sh (for UNIX)

C:\winnt\system32\drivers\etc\Tivoli\setup_env.cmd (for NT)

2. Run the wlookup command to get the scheduler instance name:wlookup -ar MaestroEngine

maestro2 1697429415.1.596#Maestro::Engine#

where maestro2 is the scheduler instance name.

ExamplesStop the connectors for the database, plan, and engine for an instance called maestro:wmaeutil maestro -stop *

Stop the connectors for the database for an instance called tws:wmaeutil tws -stop DB

Stop the connector versions for the database, plan and engine for an instance calledmaestro2:wmaeutil maestro2 -version *

218 Version 8.1

xrxtrct Command

Extracts information about cross-references from the scheduler database.

Synopsisxrxtrct [-v | -u]




The command output is written to eight files, xdep_job, xdep_sched, xfile, xjob, xprompt,xresources, xsched, and xwhen.

xdep_job FileThe xdep_job file contains two record types. The first contains information about jobs andjob streams that are dependent on a job. Each dependent job and job stream record containsthe fixed length fields, with no delimiters. The fields are described in the following table.

Field Description Length (bytes) *

1 03 2


3 job name 8/40


5 not used 240

6 dependent job stream workstation name 8/16

7 dependent job stream name 8/16

8 dependent job workstation name 8/16

9 dependent job name 8/40

10 not used 6

11 not used 6

12 not used 8

13 end-of-record (null) 1


The second record type contains information about jobs and job streams that are dependenton an internetwork dependency. Each dependent job and job stream record contains fixedlength fields, with no delimiters. The fields are described in the following table.


5.U

tilityC

om

man

ds


1 08 2


3 job name 120

4 not used 128





9 not used 6

10 not used 6

11 not used 8



xdep_sched FileThe xdep_sched file contains information about job streams that are dependent on a jobstream. Each dependent job stream record contains fixed length fields, with no delimiters.The fields are described in the following table.


1 02 2



4 not used 248



7 not used 8

8 not used 8

9 not used 6

10 not used 6

11 not used 8



xfile FileThe xfile file contains information about jobs and job streams that are dependent on a file.Each record contains fixed length fields, with no delimiters. The fields are described in thefollowing table.


1 07 2


3 file name 256

220 Version 8.1






8 not used 6

9 not used 6

10 not used 8



xjob FileThe xjob file contains information about the job streams in which each job appears. Eachjob record contains fixed length fields, with no delimiters. The fields are described in thefollowing table.


1 04 2


3 job name 8/40

4 not used 248

5 job stream workstation name 8/16


7 not used 8

8 not used 8

9 not used 6

10 not used 6

11 not used 8



xprompt FileThe xprompt file contains information about jobs and job streams that are dependent on aprompt. Each prompt record contains fixed length fields, with no delimiters. The fields aredescribed in the following table.


1 05 2


3 prompt name or text 20

4 not used 236





5.U

tilityC

om

man

ds



9 not used 6

10 not used 6

11 not used 8



xresource FileThe xresource file contains information about jobs and job streams that are dependent on aresource. Each resource record contains fixed length fields, with no delimiters. The fields aredescribed in the following table.


1 06 2


3 resource name 8

4 not used 248





9 units allocated 6

10 not used 6

11 not used 8



xsched FileThe xsched file contains information about job streams. Each job stream record containsfixed length fields, with no delimiters. The fields are described in the following table.


1 00 2



4 not used 248

5 workstation name (same as 2 above) 8/16

6 job stream name (same as 3 above) 8/16

7 not used 8

8 not used 8

9 not used 6

10 not used 6

222 Version 8.1


11 not used 8



xwhen FileThe xwhen file contains information about when job streams will run. Each job streamrecord contains the following fixed length fields, with no delimiters. The fields are describedin the following table.


1 01 2


3 ON/EXCEPT name or date 8

4 except flag (*=EXCEPT) 1

5 not used 247



8 not used 8

9 not used 8

10 not used 6

11 offset num 6

12 offset unit 8



ExamplesExtract information about all cross-references:xrxtrct


5.U

tilityC

om

man

ds

Unsupported CommandsThe following unsupported utility commands provide functions on Windows NT that aresimilar to UNIX ps

and kill

commands. They can be used if similar Windows NT utilities are not available.

Synopsislistproc

killproc pid

Usage Noteslistproc

Displays a tabular listing of processes on the system.

killprocKills the process with the process ID pid.

CAUTION:When executed by the Administrator, killproc is capable of killing system processes.

224 Version 8.1

Report Commands

Report CommandsWorkload Scheduler report commands are listed in the following table.

Command Report

rep1 Report 01 - Job Details Listing

rep2 Report 02 - Prompt Listing

rep3 Report 03 - Calendar Listing

rep4a Report 04A - Parameter Listing

rep4b Report 04B - Resource Listing

rep7 Report 07 - Job History Listing

rep8 Report 08 - Job Histogram

rep11 Report 11 - Planned Production Schedule

reptr Report 09A - Planned Production SummaryReport 09B - Planned Production DetailReport 09D - Planned Production Detail (Long Names)Report 10A - Actual Production SummaryReport 10B - Actual Production Detail

xref Report 12 - Cross Reference Report

Command OutputThe output of the report commands is controlled by the following variables:

MAESTROLPSpecifies the destination of the output of a command. The default is stdout. You canset it to any of the following:

filenameWrite the output to a file.

> filenameUNIX only. Redirect output to a file, overwriting the contents of the file. Ifthe file does not exist it is created.

>> filenameUNIX only. Redirect output to a file, appending to the end of file. If the filedoes not exist it is created.

| commandUNIX only. Pipe output to a system command or process. The systemcommand is always executed.

6


6.R

epo

rtC

om

man

ds

|| commandUNIX only. Pipe output to a system command or process. The systemcommand is not executed if there is no output.

MAESTROLPLINESSpecifies the number of lines per page. The default is 60.

MAESTROLPCOLUMNSThe number of characters per line. The default is 132.

MAESTRO_OUTPUT_STYLESpecifies the output style for long object names. Set the variable to LONG to usefull length (long) fields for object names.

If it is not set or it is set to anything other than LONG, and the global optionexpanded version is set to yes, long names are truncated to eight characters and aplus sign. For example: A1234567+. If expanded version is set to no, long namesare truncated to eight characters.

Changing the Date FormatThe Workload Scheduler date format is stored in the TWSHome/catalog/unison.msg messagefile. The date format affects all commands that accept a date as an input option (except thedatecalc command), and the headers in all reports. To select a different format, edit the file,locate set 50, message number 35, and enter the value for the desired format. The defaultvalue is 1, which selects a date format of mm/dd/yy. The values are:

0 To select: yy/mm/dd1 To select: mm/dd/yy2 To select: dd/mm/yy3 To use: Native language suport variables.

After changing the value, generate a new catalog file as follows:cd TWSHome/cataloggencat unison.cat unison.msg

226 Version 8.1

||||||

|||||||||||||||

||

|

rep1 - rep4b Commands

These commands print the following reports:

Report 01 - Job Details Listing

Report 02 - Prompt Messages Listing

Report 03 - User Calendar Listing

Report 04A - User Parameters Listing

Report 04B - Maestro Resource Listing

Synopsisrep[x] [-v|-u]

Argumentsx A number corresponding to the report. The numbers are: 1, 2, 3, 4a, or 4b.

-u Display the command version and exit.


ExamplesPrint Report 03, User Calendar Listing:rep3

Display usage information for the rep2 command:rep2 -u

On UNIX, print two copies of report 04A, User Parameters Listing, on printer lp2:MAESTROLP="| lp -dlp2 -n2"export MAESTROLPrep4a


6.R

epo

rtC

om

man

ds

rep7 Command

This command prints Report 07-Job History Listing.

Synopsisrep7 -v|-u

rep7 [-c wkstat] [-s jstream] [-j job] [-f date -t date] [-l]



-c wkstatSpecifies the name of the workstation on which the jobs run. The default is allworkstations.

-s jstreamSpecifies the name of the job stream in which the jobs run. The default is all jobstreams.

-j job Specifies the name of the job. The default is all jobs.

-f date Specifies to print job history from this date forward. Enter the date as yyyymmdd.The default is the earliest available date.

-t date Specifies to print job history up to this date. Enter the date as yyyymmdd. Thedefault is the most recent date.

-l Limits the summary line information to the jobs which fall in the date rangespecified by the -f or -t options. Using this option causes the order of output to bereversed: the job summary line will be printed after the individual job run lines. Thisoption is valid only if you also specify at least one of the -f or -t options.

ExamplesPrint all job history for workstation ux3:rep7 -c ux3

Print all job history for all jobs in job stream sked25:rep7 -s sked25

Print job history for all jobs in job stream mysked on workstation x15 between 1/21/99 and1/25/99:rep7 -c x15 -s mysked -f 19990121 -t 19990125

228 Version 8.1

|

|||||

rep8 Command

This command prints Report 08-Job Histogram.

Synopsisrep8 -v|-u

rep8 [-f date -b time -t date -e time] [-i file] [-p ]

rep8 [-b time -e time] [-i file] [-p ]



-f date Specifies to print job history from this date forward. Enter the date as yyyymmdd.The default is today’s date.

-b timeSpecifies to print job history from this time forward. Enter the time as hhmm. Thedefault is the scheduler start of day time.

-t date Specifies to print job history up to this date. Enter the date as yyyymmdd. Thedefault is the most recent date.

-e timeSpecifies to print job history up to this time. Enter the time as hhmm. The default isthe scheduler start of day time.

-i file Specifies the name of the log file from which job history is extracted. Note that logfiles are stored in the schedlog directory. The default is the current plan (Symphonyfile).

-p Specifies to insert a page break after each run date.

ExamplesPrint a job histogram which includes all information in the current plan (Symphony file):rep8

Print a job histogram beginning at 6:00 a.m. on 1/22/99, and ending at 5:59 a.m. on 1/26/99.This assumes that the dates requested are included in the specified log file. If some dates inthe range are missing, the report contains only those available in the log file. Print the reportwith page breaks after each date:rep8 -p -f 19990122 -b 0600 -t 19990126 -e 0559 -i schedlog/M199801260601

Print a job histogram, from the current plan (Symphony file), beginning at 6:00 am, andending at 10:00 pm:rep8 -b 0600 -e 2200


6.R

epo

rtC

om

man

ds

rep11 Command

This command prints Report 11-Planned Production Schedule.

Synopsisrep11 -v|-u

rep11 [-m mm[yy] [...]] [-c wkstat [...]] [-o file]



-m mm[yy]Specifies the months to be reported. Enter the month number as mm. The default isthe current month.

You can also enter a year as yy. The default is the current year or next year if youspecify a month earlier than the current month.

-c wkstatSpecifies workstations to be reported. The default is all workstations.

-o file Specifies the output file. The default is the file defined by the MAESTROLPvariable. If MAESTROLP is not set, the default is stdout.

ExamplesReport on June, July, and August of 1999 for workstations main, site1 and sagent1:rep11 -m 0699 0799 0899 -c main site1 sagent1

Report on June, July, and August of this year for all workstations, and direct output to thefile r11out:rep11 -m 06 07 08 -o r11out

Report on this month and year for workstation site2:rep11 -c site2

230 Version 8.1

reptr Command

This command prints the following reports:

Report 09A - Planned Production Summary Report 09B - Planned Production Detail(unexpanded databases)

Report 09D - Planned Production Detail (expanded databases)

Report 10A - Actual Production Summary Report 10B - Actual Production Detail

Synopsisreptr [-v|-u]

reptr -pre [-{summary | detail}] [symfile]

reptr -post [-{summary | detail}] [logfile]



-pre Specifies to print the pre-production reports (09A, 09B, 09D).

-post Specifies to print the post-production reports (10A, 10B).

-summarySpecifies to print the summary reports (09A, 10A). If -summary and -detail areomitted, both sets of reports are printed.

-detail Specifies to print the detail reports (09B, 09D, 10B). If -summary and -detail areomitted, both sets of reports are printed.

symfileSpecifies the name of the plan file from which reports will be printed. The default isSymnew in the current directory.

logfile Specifies the name of the log file from which the reports will be printed. Note thatplan log files are stored in the schedlog directory. The default is the current plan(Symphony file).

If the command is run with no options, all pre and post reports are printed.

ExamplesPrint the pre-production detail report from the Symnew file:reptr -pre -detail

Print the pre-production summary report from the file mysym:reptr -pre -summary mysym

Print the post-production summary report from the log file M199903170935:reptr -post -summary schedlog/M199903170935

Print all pre and post-production reports.reptr


6.R

epo

rtC

om

man

ds

The pre-production reports are based on information read from the Symnew file. Thepost-production reports are based on information read from the Symphony file.

232 Version 8.1

xref Command

This command prints Report 12-Cross Reference Report.

Synopsisxref [-V|-U]

xref [-cpu wkstat] [-depends|-files|-jobs|-prompts|-resource|-schedules|-when [...]]

Arguments-U Display the command version and exit.

-V Display command usage information and exit.

-cpu wkstatSpecifies to print the report for the named workstation. The @ wildcard is permitted,in which case, information from all qualified workstations is included. The default isall workstations.

-dependsSpecifies to print a report showing the job streams and jobs that are successors ofeach job.

-files Specifies to print a report showing the job streams and jobs that are dependent oneach file.

-jobs Specifies to print a report showing the job streams in which each job is run.

-promptsSpecifies to print a report showing the job streams and jobs that are dependent oneach prompt.

-resourceSpecifies to print a report showing the job streams and jobs that are dependent oneach resource.

-schedulesSpecifies to print a report showing the job streams and jobs that are successors ofeach job stream.

-when Specifies to print a report showing job stream Include and Exclude dates.

If the command is run with no options, all workstations and all options are selected.

ExamplesPrint a report for all workstations, showing all cross-reference information:xref

Print a report for all workstations. Include cross-reference information about all successordependencies:xref -cpu @ -depends -schedules


6.R

epo

rtC

om

man

ds

234 Version 8.1

Extended Agent Reference

This chapter describes the extended agent interface and provides information forprogrammers who need to create custom access methods.

Tivoli Systems has several extended agents that can be integrated with Tivoli WorkloadScheduler. For specific information on a particular extended agent, refer to thedocumentation for that extended agent.

What are Extended Agents?Extended agents are used to extend the job scheduling functions of Workload Scheduler toother systems and applications.

An extended agent is defined as a workstation that has a host and an access method. Thehost is any other workstation, except another extended agent. The access method is aTivoli-supplied or user-supplied script or program that is executed by the host whenever theextended agent is referenced in the production plan. For example, to launch a job on anextended agent, the host executes the access method, passing it job details as command lineoptions. The access method communicates with the external system or application to launchthe job and return the status of the job.

Workstation DefinitionEach extended agent must have a logical workstation definition. This logical workstationmust be hosted by a Workload Scheduler physical workstation, either a Master, domainmanager, or FTA workstation. The extended agent workstation definition references the nameof the access method and the host workstation. When jobs are launched on the extendedagent workstation, the access method is called and passes the job information to the externalsystem.

7


7.E

xtend

edA

gen

tR

eference

Access Method InterfaceThe interface between Workload Scheduler and an access method consists of informationpassed to the method on the command line, and messages returned to the scheduler instdout.

Method Command Line SyntaxThe scheduler host runs an access method using the following command line syntax:

methodname -t task options -- taskstring

where:

methodnameSpecifies the file name of the access method. All access methods must be stored inthe directory: WShome/methods

-t task Specifies the task to be performed, where task is one of the following:

LJ Launches a job.

MJ Manages a previously launched job. Use this option to resynchronize if aprior LJ task terminated unexpectedly.

CF Checks the availability of a file. Use this option to check file opensdependencies.

GS Gets the status of a job. Use this option to check job follows dependencies.

optionsSpecifies the options associated with the task. See “Task Options” for moreinformation.

taskstringA string of up to 255 characters associated with the task. See “Task Options.”

Task OptionsThe task options are listed in the following table. An X means that the option is valid for thetask.

Task Options Task String

-t -c -n -p -r -s -d -l -o -j -q -w

LJ X X X X X X X X X ljstring

MJ X X X X X X X X X mjstring

CF X X X X cfstring

GS X X X X X X gsstring

-c xagent,host,masterSpecifies the scheduler names of the extended agent, the host, and the masterdomain manager separated by commas.

-n nodenameSpecifies the node name of the computer associated with the extended agent, if any.This is defined in the extended agent’s workstation definition Node field.

236 Version 8.1

-p portnumberSpecifies the TCP port number associated with the extended agent, if any. This isdefined in the extended agent’s workstation definition TCP Address field.

-r currentrun,specificrunSpecifies the current run number of the scheduler and the specific run numberassociated with the job separated by a comma. The current and specific run numbersmight be different if the job was carried forward from an earlier run.

-s jstreamSpecifies the name of the job’s job stream.

-d scheddate,epochSpecifies the schedule date (yymmdd) and the epoch equivalent, separated by acomma.

-l user Specifies the job’s user name. This is defined in the job definition Logon field.

-o stdlistSpecifies the full path name of the job’s standard list file. Any output from the jobmust be written to this file.

-j jobname,idSpecifies the job’s name and the unique identifier assigned by the scheduler,separated by a comma. The name is defined in the job definition Job Name field.

-q qualifierSpecifies the qualifier to be used in a test command issued by the method againstthe file.

-w timeoutSpecifies the amount of time, in seconds, that the scheduler waits to get a reply onan external job before sending a SIGTERM signal to the access method. The defaultis 300.

-- ljstringUsed with the LJ task. The string from the Script File or Command field of thejob definition.

-- mjstringUsed with the MJ task. The information provided to the scheduler by the method ina %CJ response to an LJ task. Usually, this identifies the job that was launched.For example, a UNIX method can provide the process identification (PID) of the jobit launched, which is then sent by the scheduler as part of an MJ task.

-- cfstringUsed with the CF task. For a file opens dependency, the string from the OpensFiles field of the job stream definition.

-- gsstringUsed with the GS task. Specifies the job whose status is checked. The format is asfollows:

followsjob[,jobid]

where:

followsjobThe string from the Follows Sched/Job list of the job stream definition.


7.E

xtend

edA

gen

tR

eference

jobid An optional job identifier received by the scheduler in a %CJ response to aprevious GS task.

Method Response MessagesMethods return information to Workload Scheduler in messages written to stdout. Each linestarting with a percent sign (%) and ending with a new line is interpreted as a message. Themessages have the following format:

%CJ state [mjstring | jobid]

%JS [cputime]

%UT [errormessage]

where:

CJ Changes the job state.

state The state to which the job is changed. All scheduler job states are validexcept hold and ready. For the GS task, the following states are also valid:

ERRORAn error occurred.

EXTRNStatus is unknown.

mjstringA string of up to 255 characters that the scheduler will include in any MJtask associated with the job. See 237.

jobid A string of up to 64 characters that the scheduler will include in any GStask associated with the job. See 237.

JS [cputime]Indicates successful completion of a job and provides its elapsed run time inseconds.

UT [errormessage]Indicates that the requested task is not supported by the method. Displays a string ofup to 255 characters that the scheduler will include in its error message.

Method Options FileYou can use a method options file to specify special login information and other options.The scheduler reads the file, if it exists, before executing a method. If the file is modifiedafter the scheduler is started, the changes take effect when it is stopped and restarted.

The file can contain scheduler options and any other method information. The optionsrecognized by the scheduler are as follows:

LJuser=username

CFuser=username

GSuser=username

GStimeout=seconds

238 Version 8.1

where:

LJuser=usernameSpecifies the login to use for the LJ and MJ tasks. The default is the login from thejob definition.

CFuser=usernameSpecifies the login to use for the CF task. The default is root for UNIX, and forWindows NT it is the user name of the account in which the scheduler was installed.

GSuser=usernameSpecifies the login to use for the GS tasks. The default is root for UNIX, and forWindows NT it is the user name of the account in which the scheduler was installed.

GStimeout=secondsSpecifies the amount of time, in seconds, the scheduler waits for a response beforekilling the access method. The default is 300 seconds.

Note: If the extended agent’s host is a Windows NT computer, these users must be definedas scheduler user objects.

The options file must have the same path name as its access method, with an .opts fileextension. For example, the Windows NT path name of an options file for a method namednetmth is WShome\methods\netmth.opts.

Method ExecutionThe following topics describe the interchange between Workload Scheduler and an accessmethod.

Launch Job (LJ) TaskThe LJ task instructs the extended agent method to launch a job on an external system orapplication. Before running the method, Workload Scheduler establishes an executionenvironment. The LJuser parameter is read from the method options file to determine theuser account with which to run the method. If the parameter is not present or the options filedoes not exist, the user account specified in the Logon field of the job’s definition is used.In addition, the following environment variables are set:

HOMEThe login user’s home directory.

LOGNAMEThe login user’s name.

PATH For UNIX, it is set to /bin:/usr/bin. For Windows NT, it is set to%SYSTEM%\SYSTEM32.

TZ The time zone.

If the method cannot be executed, the job is placed in the fail state.

Once a method is running, it writes messages to its stdout that indicate the state of the jobon the external system. The messages are summarized in the following table.


7.E

xtend

edA

gen

tR

eference

Task Method Response Workload Scheduler Action

LJ and MJ %CJ state [mjstring] Sets job state to state. Includes mjstring in anysubsequent MJ task.

%JS [cputime] Sets job state to succ.

Exit code=non-zero Sets job state to abend.

%UT [errormessage] and Exitcode=2

Sets job state to abend and displayserrormessage.

A typical sequence consists of one or more %CJ messages indicating changes to the jobstate and then a %JS message before the method exits to indicate that the job endedsuccessfully. If the job is unsuccessful, the method must exit without writing the %JSmessage. A method that does not support the LJ task, writes a %UT message to stdout andexits with an exit code of 2.

Manage Job (MJ) TaskThe MJ task is used to synchronize with a previously launched job if the schedulerdetermines that the LJ task terminated unexpectedly. The scheduler sets up the environmentin the same manner as for the LJ task and passes in the mjstring. See “Launch Job (LJ)Task” on page 239 for more information.

If the method locates the specified job, it responds with the same messages as an LJ task. Ifthe method is unable to locate the job, it exits with a non-zero exit code, causing thescheduler to place the job in the abend state.

Killing a JobWhile an LJ or MJ task is running, the method must trap a SIGTERM signal (signal 15).The signal is sent when an operator issues a Kill command through the scheduler consolemanager. Upon receiving the signal, the method must attempt to stop (kill) the job and thenexit without writing a %JS message.

Check File (CF) TaskThe CF task requests the extended agent method to check the availability of a file on theexternal system. Before running the method, the scheduler establishes an executionenvironment. The CFuser parameter is read from the method options file to determine theuser account with which to run the method. If the parameter is not present or the options filedoes not exist, the root user is used on UNIX and, on Windows NT, the user name of theaccount in which the scheduler was installed is used. If the method cannot be executed, thefile opens dependency is marked as failed, that is, the file status is set to NO and anydependent job or job stream is not allowed to execute.

Once it is running, the method executes a test command, or the equivalent, against the fileusing the qualifier passed to it in the -q command line option. If the file test is true, themethod exits with an exit code of zero. If the file test is false, the method exits with anon-zero exit code. This is summarized in the following table.


CF Exit code=0 Set file state to YES.

Exit code=non-zero Set file state to NO.


Set file state to NO.

240 Version 8.1

A method that does not support the CF task writes a %UT message to stdout and exits withan exit code of 2.

Get Status (GS) TaskThe GS task tells the extended agent’s method to check the status of a job. This is necessarywhen another job is dependent on the successful completion of an external job. Beforerunning the method, the GSuser parameter is read from the method options file to determinethe user account with which to run the method. If the parameter is not present or the optionsfile does not exist, the root user is used on UNIX, and, on Windows NT, the user name ofthe account in which the scheduler was installed is used. If the method cannot be executed,the dependent job or job stream is not allowed to execute. If a jobid is available from a priorGS task, it is passed to the method.

The method checks the state of the specified job, and returns it in a %CJ message writtento stdout. It then exits with an exit code of zero. At a rate set by the bm check status localoption, the method is re-executed with a GS task until one of the following job states isreturned:

abend The job ended abnormally.

succ The job completed successfully.

cancl The job was cancelled.

done The job is done, but its success or failure is not known.

fail The job could not be run.

error An error occurred in the method while checking job status.

extrn The job check failed or the job status could not be determined.

Note that GStimeout in the method options file specifies how long the scheduler will waitfor a response before killing the method. See “Method Options File” on page 238 for moreinformation.

Method responses are summarized in the following table:


GS %CJ state [jobid] Sets job state to state and includes jobid in anysubsequent GS task.


Job state is unchanged.

A method that does not support the GS task writes a %UT message to stdout and exits withan exit code of 2.

The cpuinfo CommandThe cpuinfo command can be used in an access method to return information from aworkstation definition. See “cpuinfo Command” on page 186 for complete commandinformation.


7.E

xtend

edA

gen

tR

eference

TroubleshootingThe following topics are provided to help troubleshoot and debug extendend agent andaccess method problems.

Job Standard List Error MessagesAll output messages from an access method, except those that start with a percent sign (%),are written to the job’s standard list (stdlist) file. For GS and CF tasks that are notassociated with scheduler jobs, messages are written to the cheduler standard list file. Forinformation regarding a problem of any kind, check these files.

Method Not ExecutableIf an access method cannot be executed, the following will occur:

¶ For LJ and MJ tasks, the job is placed in the fail state.

¶ For the CF task, the file dependency is unresolved and the dependent job remains in thehold state.

¶ For the GS task, the job dependency is unresolved and the dependent job remains in thehold state.

To get more information, review the standard list files (stdlist) for the job and for thescheduler.

Console Manager MessagesThis error message is displayed if you issue a start, stop, link or unlink command for anextended agent:Error executing command: Not implemented for extendedagents. [2202.58]

This error is not displayed if an extended agent is selected as the result of using wildcardcharacters.

Composer and Compiler MessagesThe following error messages are generated when Composer encounters invalid syntax in aworkstation definition:ACCESS METHOD is syntactically invalid [1116.45]

Duplicate ACCESS keyword [1116.46]

Missing or invalid ACCESS METHOD [1116.47]

If an extended agent is defined with an access method but without a host, the followingmessage is displayed:"Method needs a Host CPU"

Jobman MessagesFor extended agents, error, warning, and information messages are written to Jobman’sstdlist file.

A successful job launch generates the following message:Launched job jobname for wkstation, #Jjobid for user username.

Failure to launch a job generates the following message:Error launching jobname for wkstation: errortext

242 Version 8.1

Failure of a check file task generates the following message:Error invoking methodname for wkstation: errortext

Failure of a manage job task generates the following message:Error managing jobname for wkstation using methodname: errortext

When a method sends a message to Jobman that is not recognized, the following message isgenerated:Error: message invalid for jobname, #jjobnumber forwkstation using methodname.

"first 64 characters of the offending message"


7.E

xtend

edA

gen

tR

eference

244 Version 8.1

Network Agent Reference

Workload Scheduler internetwork dependencies permit jobs and job streams in a localscheduler network to use jobs and job streams in a remote network as follows dependencies.This chapter describes how to use internetwork dependencies.

OverviewA network agent is a logical workstation definition that allows follows dependenciesbetween a local scheduler network and a remote scheduler network. Remote followsdependencies are assigned to jobs and job streams in the same manner as local followsdependencies, except that the network agent’s name is included to identify that the job or jobstream is in an external scheduler network. These type of dependencies are calledinternetwork dependencies.

If any job streams with internetwork dependencies are included in the plan, a special jobstream named EXTERNAL is created to display the status of these dependencies. ThisEXTERNAL job stream contains place holder jobs to represent each remote followsdependency.

The workstation definition for a network agent contains the name of the network accessmethod, netmth. An options file is used to specify the user under which the method runs,and the rate that the remote job or job stream dependency is checked. This options file musthave the same path name as the access method, and must be called netmth.opts.

The access method is invoked by the scheduler each time it needs to check the status of aremote job or job stream. The access method queries the remote network for the status ofthe predecessor job or job stream. The scheduler continues checking until the remote job orjob stream reaches the SUCC, CANCL, or ERROR state.

You can monitor the status of internetwork dependencies with the Job Scheduling Consoleby displaying the EXTERNAL job stream.

Configuring a Network Agent WorkstationBefore you can specify an internetwork dependency, you must create a scheduler workstationdefinition for the remote network. The workstation definition for a remote network is calleda Network Agent. Network agent workstation definitions are defined in the standard manneras Extended Agents and require a host workstation and an access method, netmeth.

To define a Network Agent workstation in the scheduler database:

1. Highlight the scheduler Engine.

8


8.N

etwo

rkA

gen

tR

eference

2. From the Selected Menu, click New Workstation. The Properties - Workstation inDatabase window is displayed.

3. In the Name field, specify a name for this workstation. The workstation name can haveup to 8 alphanumeric characters for unexpanded database or 16 alphanumeric charactersfor expanded database. The name can including a dash and underscore, but must beginwith a letter.

4. In the Node field, specify the node name or the IP address for this workstation. Fullyqualified domain names are accepted. This is a required field.

5. In the TCP Port field, enter 0.

6. In the Operating System field, enter OTHER.

7. In the Domain field, specify the domain of the host workstation.

8. In the Time Zone field, specify the time zone of this workstation (optional).

9. In the Description field, specify a description of the workstation. The description can beup to 40 characters long, and must begin with a letter.

10. In the Workstation Type field, select Extended Agent from the pull down list.

11. Leave the Auto Link checkbox blank.

12. Leave the Full Status checkbox blank.

13. Leave the Ignore checkbox blank.

14. Leave the Resolve Dependencies checkbox blank.

15. Leave the Server field blank.

16. In the Access Method field, enter netmeth.

17. In the Host field, specify the node name of the host workstation or select one from thelist provided by clicking the Workstations button.

18. Click OK. The Network Agent workstation is saved in the scheduler database.

Network Agent Command Line ExampleThe following example shows a command line workstation definition for the network agent:CPUNAME NETAGT

DESCRIPTION "NETWORK AGENT"

OS OTHER

NODE MAIN

TCPADDR 31111

FOR maestro

HOST MASTER

ACCESS NETMTH

END

Options FileAn options file must be created to specify the user under which the access method runs, andhow often a remote job or job stream dependency is checked. Changes to this file do nottake effect until you stop and restart the scheduler.

This options file must have the same path name as the access method, and must be callednetmth.opts.

246 Version 8.1

TWShome/methods/netmth.opts

SyntaxGSuser=login_name

GStimeout=seconds

where:

login_nameThe login used to run the method. If the network agent’s host is a Windows NTcomputer, this user must be defined in the scheduler.

secondsThe amount of time, in seconds, the scheduler waits for a response before killing theaccess method. The default is 300 seconds. If the access method is called again itwill start up automatically.

Example Options FileAn example options file for method netmth is as follows:GSuser=bunyon

GStimeout=400

Internetwork DependenciesUsing the Job Scheduling Console, internetwork dependencies are specified in the JobStream Editor. Use the Add Dependency to Internetwork button to add an Internetworkjob icon to the job stream (representing the predecessor) and then create the followsdependency from this icon to any other job using the Add Link button.

Note: Remote jobs and job streams are defined and run on their local network in thestandard manner. Their use as internetwork dependencies has no effect on their localbehavior.

When remote jobs and job streams are specified as Follows dependencies in local jobstreams, they are tracked by Conman in a specially created EXTERNAL job stream. Namesare generated for the dependencies and they are treated as jobs in the EXTERNAL jobstream.

Creating an Internetwork DependencyTo add an internetwork dependency to a job:

1. Open the job stream in the Job Stream Editor.

2. From the Graph View of the Job Stream Editor, click Add Dependency onInternetwork button on the toolbar and then click the cursor in the window where youwant the job stream icon to be placed. The Internetwork Dependency window isdisplayed.

3. In the Network Agent field, enter the name of the Network Agent.

4. In the Workstation field, enter the name of the workstation that owns the predecessorjob. This workstation must reside in the network that your Network Agent is connectingtoo.

5. In the Job Stream field, enter the name of the predecessor job stream.

6. In the Job field, enter the name of the predecessor job.


8.N

etwo

rkA

gen

tR

eference

7. Click OK. An icon representing the predecessor job is displayed in the window. Notethat you can drag and drop the job stream icon to position it in the window.

8. Click the Add Link button to create a follows dependency from the INET job icon to thesuccessor job. An internetwork job can be a predecessor, but not a successor, to any jobin your job stream.

9. Save the job stream.

Using the Command LineInternetwork dependencies can be included in job streams composed with the command lineComposer. For example, use the follows keyword as in the following examples:jstream6 follows netagent1::remotewrkstn#skedx.@

apjob follows netagent2::ahab#qa5.jobc1

Internetwork Dependencies and ConmanInternetwork dependencies are displayed and manipulated in the plan in several ways.

¶ Adhoc scheduling

¶ the EXTERNAL job stream

Adhoc Scheduling and Internetwork DependenciesInternetwork dependencies can be used as follows dependencies for jobs and job streamssubmitted into the plan. The dependencies are specified as they are for other followsdependencies. Refer to “Creating an Internetwork Dependency” on page 247 for moreinformation.

EXTERNAL Job StreamAll internetwork dependencies are displayed in a job stream named EXTERNAL. Thedependencies are listed as jobs regardless of whether they are defined for jobs or jobstreams. There is an EXTERNAL job stream for every network agent in the plan.

Unique job names are generated as follows:Ennnmmss

where:

nnn is a random number.

mm is the current minutes.

ss is the current seconds.

The actual name of the job or job stream is stored in the JCL portion of the job record.

External Job StatesThe release status of the jobs is determined by the access method and listed in the ReleaseStatus field of the EXTERNAL job stream. The status is only as current as the last time theremote network was polled. Jobs may appear to skip states that occur between polls.

All states for jobs and job streams are listed, except FENCE. In addition there are two statesthat are unique to EXTERNAL jobs:

ERRORAn error occurred while checking for the remote status.

248 Version 8.1

EXTRNUnknown status. An error occurred, a Rerun action was performed on theEXTERNAL job stream, or the INET job or job stream does not exist.

Taking Action on External JobsYou can take three actions on remote jobs in an EXTERNAL schedule: Cancel, Rerun, andConfirm.

Note: None of these commands have any effect on the remote job or schedule on theremote network. They simply manipulate the the dependency for the local network.

CancelCancels the EXTERNAL job, releasing the dependency for all local jobs andschedules. The status of the dependency ceases to be checked.

Rerun Instructs Conman to restart checking the state of the EXTERNAL job. The job stateis set to EXTRN immediately after a Rerun is performed.

Rerun is useful for EXTERNAL jobs in the ERROR state. For example, if anEXTERNAL job cannot be launched because the network access method does notgrant execute permission, the job enters the ERROR state and its status ceases to bechecked. After you correct the permissions, the method can start but Conman willnot start checking the EXTERNAL job state until you perform a Rerun.

Confirm SUCC / ABENDSets the status of the EXTERNAL to SUCC or ABEND, releasing the dependencyfor all local jobs and schedules. The status of the dependency ceases to be checked.

Taking Action on Internetwork Dependencies for Jobs and SchedulesInternetwork dependencies are listed in the Dependencies column of the SHOWJOBS andSHOWSCHEDULES windows in the following format:

net::net_dep

where:

net The CPU name of the network agent. The two colons (::) are a requireddelimiter. Wildcards are valid.

net_dep The internetwork dependency in the following format:

[cpu#] sched[.job]

If no CPU is specified, the default is the scheduler CPU to which thenetwork agent is connected. This is determined by the Node and TCPAddress fields of the network agent CPU definition. Wildcards are valid.

The Release, Add Dependency, and Delete Dependency actions work the same forinternetwork dependencies as they do for other dependencies.


|||

||

|||

|||

|||||

|||

|||

|

|

||||

||

|

||||

||

8.N

etwo

rkA

gen

tR

eference

Conman Command Line SpecificationConman commands that can specify internetwork dependencies are listed below with anexample based on:

¶ A local scheduler CPU called local1

¶ A schedule defined for local1 called sched1

¶ A job in local1#sched1 called job1

¶ A scheduler network agent called netagt

¶ A scheduler CPU in the netagt remote network called remote1

¶ A schedule defined for remote1 called rcshed

¶ A job in remote1#rsched called rjob

adddep jobAdd a remote job as a Follows dependency to a job:adj local1#sched1.job1;follows=netagt::remote1#rsched.rjob

adddep schedAdd a remote schedule as a Follows dependency to a schedule:ads local1#sched1;follows=netagt::remote1#rsched

cancel jobCancel all EXTERNAL jobs for a network agent (the two commands are equivalent):cj netagt#EXTERNAL.@cj netagt::@

confirmConfirm that an EXTERNAL job has completed successfully:confirm netagt::remote1#rsched.rjob;succ

deldep jobDelete a remote job dependncy from a job:ddj local1#sched1.job1;follows=netagt::remote1#rsched.rjob

deldep schedDelete a remote job dependency from a scheduledds local1#sched1;follows=netagt::remote1#rsched.rjob

release jobRelease a job from an internetwork dependency:rj local1#sched1.job1;follows=netagt::remote1#rsched.rjob

release schedRelease a schedule from an internetwork dependency:rs local1#sched1;follows=netagt::remote1#rsched.rjob

rerunRerun an EXTERNAL job (the two commands are equivalent):rr netagt#EXTERNAL.rjobrr netagt::remote1#rsched.rjob

250 Version 8.1

|||

|

|

|

|

|

|

|

||

|

||

|

||

||

||

|

||

|

||

|

||

|

||

|

||

||

showjobs;infoDisplay all the remote dependencies for a network agent with their original names and theirscheduler-generated names:sj netagt#EXTERNAL.@;info

submitSubmit a rm command into the JOBS schedule with a remote schedule as Followsdependency:sbd "rm apfile";follows=netagt::remote1#rsched


|||

|

|||

|

8.N

etwo

rkA

gen

tR

eference

252 Version 8.1

Integration with Other Products

Integration with NetViewThis section describes the integration of Tivoli Workload Scheduler on UNIX with NetViewfor AIX.

General InformationTivoli Workload Scheduler/NetView is a NetView application that gives network managersthe ability to monitor and diagnose Workload Scheduler networks from a NetViewmanagement node. It includes a set of submaps and symbols to view scheduler networkstopographically, and determine the status of job scheduling activity and critical schedulerprocesses on each workstation. Menu actions are provided to start and stop schedulerprocessing, and to run conman on any workstation in the network.

How Tivoli Workload Scheduler/NetView WorksTivoli Workload Scheduler/NetView consists of manager and agent software. The managerruns on the NetView management nodes, and the agent runs on the managed nodes. Allnodes must have Workload Scheduler for UNIX installed. The manager ( mdemon ) polls itsagents ( magent ) periodically to obtain information about scheduler processing. If theinformation returned during a poll is different from that of the preceding poll, the color of acorresponding symbol is changed to indicate a state change, for example, from green(normal) to red (critical) or yellow (marginal). After you have taken action to remedy amarginal or critical condition, the state of the corresponding symbol is returned to normal bythe next poll.

The agents also generate SNMP traps to inform the manager of asynchronous events, such asjob abends, stuck schedules, and restarted scheduler processes. Although polling and trapsare functionally independent, the information that accompanies a trap can be correlated withsymbol state changes. If, for example, a scheduled job abends, the symbol for theworkstation changes color, and a job abend trap is logged in the NetView event log. Byscanning the log, you can quickly isolate the problem and take appropriate action.

The muser process runs commands issued by a NetView user, and updates the user’s map.An muser is started for each NetView user whose map has the Workload Scheduler/NetViewapplication activated.

Types of InformationThe manager collects two types of information by polling its agents:

Job schedulingThis indicates the status of jobs and schedules in a Workload Scheduler network. Theinformation is provided by a single agent, usually running on the master of the network.

9


|

|

||

|

||||||

||||||||||

||||||

|||

||

|||

9.In

tegratio

nw

ithO

ther

Pro

du

cts

Alternatively, the information can be provided by an agent running on a fault-tolerantagent that has been configured as a backup master.

Monitored prcocessThis indicates the status of scheduler critical processes on a workstation ( netman,mailman, batchman, jobman, mailman servers, writers , and all extended agentconnections). This information is provided only by local agents running on eachworkstation.

DefinitionsCpu and Node

The terms cpu and node are used interchangeably to mean a workstation.

Management NodesA NetView management node that runs a Workload Scheduler/NetView manager(mdemon). In NetView 4.1 and later, the management node functions can be distributedacross a server and one or more clients.

Managed NodeThe nodes that comprise a Workload Scheduler network and that have the WorkloadScheduler/NetView agent (magent) running.

Managed Workload Scheduler NetworkA group of nodes that are configured as a Workload Scheduler network, and whose jobscheduling status is managed from a NetView management node. More than onenetwork can be managed from a single management node

General RequirementsThe basic configuration requirements are:

¶ Management nodes (server and clients) must have Workload Scheduler installed, butneed not be members of managed scheduler networks.

¶ There must be at least one managed node in a managed scheduler network. To obtainaccurate job scheduling information, this should be either the master, or the backupmaster— that is, a fault-tolerant agent with fullstatus on and resolvedep on in itsdefinition.

ConfigurationsThe NetView management node can be a member of a managed Workload Schedulernetwork or not.

The Workload Scheduler/NetView agent can run on master workstations, providing accurateinformation about job scheduling in their respective Workload Scheduler networks.Alternatively, the agents can run on backup masters. In either case, additional agents can beinstalled on other scheduler workstations to monitor the status of their critical processes.

When you plan for your configuration, you should consider the following:

¶ If you choose to use a master workstation, or a backup master, as the NetViewmanagement node, it can also have a Workload Scheduler/NetView agent that providesjob scheduling status for its Workload Scheduler network. This will minimize WorkloadScheduler/NetView manager-agent traffic when polling. However, you must alsoconsider the additional workload imposed by NetView management, particularly in largenetworks and those with several NetView applications, which can noticeably slow downWorkload Scheduler processing.

254 Version 8.1

||

|||||

|

||

||||

|||

||||

||

||

||||

|||

||||

|

|||||||

¶ Choosing an existing Workload Scheduler standard agent as a NetView managementnode, or making the current NetView management node a standard agent, has theadvantage of not overloading the master, and of letting you use Workload Scheduler onthat node to schedule certain NetView management tasks, like clearing out log files.

Installing the Integration SoftwareThe Workload Scheduler/NetView software is delivered and installed as part of WorkloadScheduler on UNIX. Before performing the following steps for Tivoli WorkloadScheduler/NetView, make certain that Workload Scheduler for UNIX is properly installed onthe management node (server and clients) and on each managed node. For more information,refer to the Tivoli Workload Scheduler Planning and Installation book.

Since the purpose of Workload Scheduler/NetView is to monitor the operation of WorkloadScheduler for UNIX, new users should take a two-stage approach. First, install andimplement Workload Scheduler for UNIX to the point that you have a good understandingof its operation, and are successfully scheduling and tracking your own jobs. Second, followthe steps outlined below to install Workload Scheduler/NetView.

The customize ScriptAs part of the installation procedure, you run the Workload Scheduler/NetView customizescript on the NetView management nodes and managed nodes. It performs the followingsteps:

The Tivoli Workload Scheduler Home DirectoryThe home directory of the Workload Scheduler user, usually /usr/lib/maestro, is referred toas maestrohome throughout this section. This is the directory you defined at the time youinstalled Workload Scheduler. The Workload Scheduler/NetView customize script determinesthe user’s home directory, and uses it to correctly install Workload Scheduler/NetView.

Using customize on Managed NodesOn managed modes, customize does the following:

1. Modifies maestrohome /StartUp to add a command to run the Maestro/NV agent (magent ).

2. Creates the following configuration files:maestrohome /BmEvents.confmaestrohome /MAgent.conf

3. In addition, for each AIX node:

a. Modifies /etc/snmpd.conf to add a new smux agent, and define the destination nodefor traps.

b. Modifies /etc/snmpd.peers to configure the new smux agent.

c. Modifies /etc/mib.defs to add Unison Software’s MIB.

4. For NetView version 4.1 and above, if the managed node is a NetView client, theWorkload Scheduler Application Registration File (ARF) is installed.

Using customize on the Management Node and Version 4.1 NetView ServerOn the management node and version 4.1 NetView server, customize:

1. Performs the steps listed above for managed nodes.


||||

|

|||||

|||||

||||

|||||

||

||

|||

|

||

|

|

||

||

|

9.In

tegratio

nw

ithO

ther

Pro

du

cts

2. Registers the Workload Scheduler/NetView mdemon process so that it is started byNetView.

3. Adds Unison Software’s enterprise traps.

4. Copies the Workload Scheduler fields, application, MIB, and help files into theappropriate directory structure.

Using customize on Version 4.1 NetView ClientsOn version 4.1 NetView clients, customize does the following:

1. Performs the steps listed above for managed nodes.

2. Copies the Workload Scheduler/NetView application and help files into the appropriatedirectory structure. The Application Registration File (ARF) installed by WorkloadScheduler/NetView uses NetView’s nvserver_run facility to launch the application on theserver.

Reviewing ChangesIf you want to review the changes made by customize before actually installing any files,execute the script with the -noinst option, as follows:/bin/sh maestrohome/OV/customize -noinst

This will create the files in the /tmp directory. As customize executes, it tells you where tomove the files to complete the installation. Alternatively, you can remove the /tmp files andrerun customize without the -noinst option.

Removing ChangesTo uninstall Workload Scheduler/NetView, and to remove the changes made by customize,execute the decustomize script:/bin/sh maestrohome /OV/decustomize

customize SynopsisThe syntax of customize is:

customize[-prev3] [-noinst] [-client] [-manager host ]

where:

-prev3Include this option if your version of NetView is below 3.

-noinstDo not overwrite existing NetView configuration files. See “Reviewing Changes”.

-client For NetView version 4.1 and above, include this option for management clients.

-managerThe host name of the management node. For NetView version 4.1 and above, this isthe host name of the NetView server. This is required for managed nodes andNetView clients. Do not use this option on the management node or NetView server.

InstallingThe installation procedure is made up by the following two steps:

1. Installing on managed nodes and on NetView clients

256 Version 8.1

||

|

||

||

|

||||

|||

|

|||

|||

|

||

|||

|

||

||

||

||||

||

|

2. Installing on the management node or NetView server

Installing on Managed Nodes and NetView ClientsThe management node can also be a managed node. For the management node or NetViewserver, skip this step and perform step 2.

1. Make certain that no Workload Scheduler processes are running. If necessary, issue aconman shutdown command.

2. Log in as root.

3. For managed nodes, including those that are also NetView clients that are not used tomanage Workload Scheduler, run the customize script as follows:/bin/sh maestrohome/OV/customize -manager host

Where host is the host name of the management node.

4. For NetView clients that are used to manage Workload Scheduler, run the customizescript as follows:/bin/sh maestrohome/OV/customize -client [-manager host]

Where host is the host name of the management node.

5. Execute the StartUp script:maestrohome/StartUp

Installing on the Management Node or NetView Server

1. Make certain that no Workload Scheduler processes are running. If necessary, issue a conmanshutdown command.

2. Log in as root .

3. Run the customize script as follows:/bin/sh maestrohome/OV/customize

4. If you do not want the Workload Scheduler/NetView agent to run on this node, edit the filemaestrohome /StartUp, and remove the run of magent.

5. If you want Workload Scheduler to run on this node, execute the StartUp script:maestrohome/StartUp

6. Start the Workload Scheduler/NetView daemon ( mdemon ) as follows:/usr/OV/bin/ovstart Unison_Maestro_Manager

or, for NetView versions below 3, stop and start as follows:/usr/OV/bin/ovstop

/usr/OV/bin/ovstart

Setting UpFollow these steps:

1. Determine the user who will be managing Workload Scheduler with NetView.

a. On each managed node, enter the host name of the management node in the user’s$HOME/.rhosts file.

b. To allow the user to execute certain scheduler commands, you must add a userdefinition to the scheduler security file. You can, for example, give this user the same


|

|||

||

|

||

|

|

||

|

|

|

|

|

||

|

|

|

||

|

|

|

|

|

|

|

|

|

|

||

||

9.In

tegratio

nw

ithO

ther

Pro

du

cts

capabilities as the default maestro user. For more information about WorkloadScheduler security, refer to the Tivoli Workload Scheduler Planning and Installationbook.

2. On the management node, run NetView.

3. Bring up the map you intend to use.

a. From the File menu, select Describe Map....

b. When the Map Description dialog box appears, select Maestro-Unison Software(c)from the Configurable Applications list, and click Configure For This Map....

c. When the Configuration dialog box appears, click True under Enable Maestro forthis map.

d. Click Verify.

e. Click OK to close the Configuration dialog box.

f. Click OK to close the Map Description dialog box.

4. If you want to use the MIB browser, load the Workload Scheduler MIB as follows:

a. From the Options menu, select Load/Unload MIBs:SNMP... .

b. When the Load/Unload MIBs dialog box appears, click Load.

c. When the Load MIB From File dialog box appears, enter/usr/OV/snmp_mibs/Maestro.mib

in the MIB File to Load field. Click OK.

d. Click Close to close the Load/Unload MIBs dialog box.

5. If the management node is not also a managed Workload Scheduler node, or if you willbe managing more than one Workload Scheduler network, use the NetView objectdescription function to identify the managed nodes where Workload Scheduler/NetViewagents are running.

a. Move down the IP Internet tree to the IP segment submap showing all the nodes.

b. Select a node where a Workload Scheduler/NetView agent is running. Press Ctrl-O toopen the Object Description dialog.

c. On the Object Description dialog, select General Attributes from the ObjectAttributes list, and click View/Modify Object Attributes.

d. On the Attributes for Object dialog, click the True button under theisUTMaestroAgent attribute.

e. Click OK to close the Attributes for Object dialog.

f. Click OK to close the Object Description dialog.

g. Repeat steps 5b through 5f for each node where a Workload Scheduler/NetViewagent is running.

h. Return to the Root submap. From the Tools menu, select Workload Scheduler, thenselect Re-discover.

i. When the Unison Software(c) symbol appears, double-click it to open the UnisonSoftware(c) submap displaying a symbol for each Workload Scheduler network.

258 Version 8.1

|||

|

|

|

||

||

|

|

|

|

|

|

|

|

|

|

||||

|

||

||

||

|

|

||

||

||

Double-click a Workload Scheduler network symbol to open a Workload SchedulerNetwork submap showing a topographical representation of the network.

You are now ready to use Workload Scheduler/NetView. On the Workload Scheduler masterissue a conman start@ command to restart Workload Scheduler in the network. This can bedone in NetView on the Workload Scheduler Network submap as follows:

1. Select all of the nodes in the network.

2. From the Tools menu, select Workload Scheduler, and then select Start.

Objects, Symbols, and SubmapsThe Workload Scheduler/NetView objects and symbols are described in Table 2.

Table 2. Tivoli Workload Scheduler/NetView Objects and SymbolsSymbol Description

The Unison Software application. This symbol appears onthe root submap. Its color indicates the aggregate status ofall Workload Scheduler networks.

On the Unison Software (c) submap, a Workload Schedulernetwork. Its color indicates the aggregate status of allworkstations and links that comprise a Workload Schedulernetwork.

On the Workload Scheduler Network submap, a host. Itscolor indicates the aggregate status of the host, all itsagents, and their links.

On a Workload Scheduler Network submap, a topographicalrepresentation of the workstations and links that comprise aWorkload Scheduler network. The color of a workstationsymbol indicates the status of job scheduling on theworkstation. The color of a link symbol (a line) indicatesthe status of the workstation link. Workstation symbols alsoappear on IP node submaps.

If a workstation on the network is a host but is not themaster, the workstation is represented by a network symbol(for example, SLAVE3 ). A Host Network submap exists forthe host and its attached agents.

The Workload Scheduler software on a workstation. Thissymbol appears on the IP node submap. Its color indicatesthe aggregate status of all monitored processes on aWorkload Scheduler workstation.

Note, extended agents have no monitored processes.

The monitored processes on a Workload Schedulerworkstation. These symbols appear on the monitoredprocesses submap. The color of a process symbol indicatesthe status of the process. Clicking the NETMAN symbolperforms the Start Up action (see “Menu Actions” onpage 261). Clicking the MAGENT symbol starts the magentprocess on the workstation.


||

|||

|

|

|

|

||

||

|

|

|||

|

|

||||

|||

|

|

|||||||

||||

|

|

||||

|

|

|

||||||||

9.In

tegratio

nw

ithO

ther

Pro

du

cts

Status of Tivoli Workload Scheduler/NetView SymbolsThe color of a Workload Scheduler/NetView symbol indicates its current status. The colorsare described in Table 3. The status of the monitored process symbols and WorkloadSchedulerworkstation symbols is propagated up the submap tree in the manner defined inNetView. Propagation is defined by selecting Describe Map from the File menu, andselecting the desired Compound Status.

Table 3. Tivoli Workload Scheduler/NetView StatusColor Monitored Processes

(Monitored processsymbols)

Job Scheduling(Maestro cpu symbols)

Communications(Maestro linksymbols)

Black na na Up or unknown *

Blue (Unknown) * * na

Green(Normal/Up)

Running No unacknowledgedevents

na

Yellow (Marginal) Stopped Abended, failed, orsuspended job(s)

Down (unlinked)

Red(Critical/Down)

Abended or gone Abended, stuck, orsuspended schedule(s)

Down (error)

Tan (Unmanaged) No longer being polled No longer being polled na

Dk Green(Acknowledged)

Ignore untilunacknowledged

Ignore untilunacknowledged

na

*The Unknown state is set by Workload Scheduler/NetView whenever the status of an objectcannot be determined. This may be the result of one of the following situations:

¶ If a fault-tolerant or standard agent is not linked to the master, job scheduling status onthat workstation is unknown.

¶ If communications with the mdemon process fails, the status of all monitored processesand all job scheduling is unknown.

¶ If communications with an agent process fails, its status is Critical, and all othermonitored processes on that workstation are unknown.

¶ If an agent process cannot be found on the master, the backup master, or a fullstatus onfault-tolerant agent, the job scheduling status on all the workstations of the WorkloadScheduler network is unknown.

¶ If the Workload Scheduler master is down, or unmanaged, the communications (link)status is unknown.

For more information about Workload Scheduler workstation status, see “ConfiguringWorkstation Status in NetView” on page 268.

Extended Agent MappingIf the host of an extended agent is the master, the extended agent is displayed as connectedto the master in the Workload Scheduler Network submap. If the host of an extended agentis not the master:

¶ The extended agent is not displayed in the Workload Scheduler Network submap.

¶ The host is represented by a network symbol and extended agents are displayed in theHost Network submap.

260 Version 8.1

||||||

||

||||

|||||

||||

||||

||||||

|||||

||||||

||||

|||||||

|

||

||

||

||

|||

||

||

||||

|

||

Menu ActionsTo use Workload Scheduler/NetView menu actions, select Workload Scheduler from theTools menu. These actions are also available from the object context menu by clicking asymbol with mouse button three.

The menu actions are:

View Open a child submap for a Workload Scheduler/NetView symbol. Choosing Viewafter selecting a workstation symbol on the Workload Scheduler network submapopens the monitored processes submap. Choosing View after selecting a workstationsymbol on the IP node submap returns to the Workload Scheduler network submap.

Master conmanRun the conman program on the Workload Scheduler master. Running the programon the master permits you to execute all conman commands (except shutdown ) forany workstation in the Workload Scheduler network. For information about conmancommands, see “Conman Reference” on page 89.

AcknowledgeAcknowledge the status of selected Workload Scheduler/NetView symbols. Whenacknowledged, the status of a symbol returns to normal. It is not necessary toacknowledge critical or marginal status for a monitored process symbol—it willreturn to normal when the monitored process itself is running again. Critical ormarginal status of a Workload Scheduler workstation symbol should beacknowledged either before or after you have taken some action to remedy theproblem—it will not return to normal otherwise.

ConmanRun the conman program on the selected Workload Scheduler workstations. Runningthe program on a workstation other than the master, permits you to execute allconman commands on that workstation only. For information about conmancommands, see “Conman Reference” on page 89. For an extended agent, conman isrun on its host.

Start Issue a conman start command for the selected workstations. By default, thecommand for this action is:remsh %H %P/bin/conman 'start %c'

Down (stop)Issue a conman stop command for the selected workstations. By default, thecommand for this action is:remsh %H %P/bin/conman 'stop %c'

start UpExecute the Workload Scheduler StartUp script on the selected workstations. Bydefault, the command for this action is:remsh %h %P/StartUp

For an extended agent, conman is run on its host.

Re-discoverLocate new agents and new Workload Scheduler objects, and update all WorkloadScheduler/NetView submaps.

Note: Run Re-discover each time you change the Workload Scheduler workstationconfiguration.


|

|||

|

|||||

|||||

||||||||

||||||

|||

|

|||

|

|||

|

|

|||

||

9.In

tegratio

nw

ithO

ther

Pro

du

cts

The substituted parameters in the command lines are:

%c The Workload Scheduler workstation name of a selected workstation symbol.

%D The current DISPLAY name.

%h The host name of a selected workstation symbol.

%H The host name of the Workload Scheduler master.

%p The process name of a selected process symbol, or “MAESTRO” if it is not aprocess.

%P The maestro user’s home directory (usually /usr/lib/maestro ).

Changing the CommandsThe commands executed by selecting Workload Scheduler/NetView actions can be modifiedin NetView by choosing Describe Map from the File menu. When the Map Descriptiondialog box appears, select Maestro-Unison Software(c) from the Configurable Applicationslist, and click Configure For This Map.... Make your changes in the Configuration dialogbox. For instructions, refer to your NetView documentation or online help. Also see notesbelow.

Notes:

1. The user running NetView must be defined in the Workload Scheduler security file toexecute certain conman commands. For more, information, see “Conman Reference” onpage 89.

2. Remove the remsh command if they are not required. For example, if the managementnode is the Workload Scheduler master, the remsh for the Master conman, Start, andDown (stop) actions are not required.

3. As written, the remsh commands require that the NetView user be able to login on othernodes without a password prompt.

Tivoli Workload Scheduler/NetView EventsThe Tivoli Workload Scheduler/NetView events are listed in Table 4. The first four (1-53)indicate the status of critical processes that are monitored by the WorkloadScheduler/NetView agents, including the agents themselves (event 1). The remaining events(101-252) indicate the status of the job scheduling activity.

All of the listed events can result in SNMP traps generated by the WorkloadScheduler/NetView agents. Whether or not traps are generated is controlled by options set inthe configuration files of the agents. See “Tivoli Workload Scheduler/NetView ConfigurationFiles” on page 264 for more information.

The Additional Actions column in Table 4 lists the actions available to the operator for eachevent. The actions can be initiated by selecting Additonal Actions from the Options menu,then selecting an action from the Additional Actions window.

Note: The operator must have the appropriate Workload Scheduler security access toperform the chosen action.

262 Version 8.1

|

||

||

||

||

|||

||

|||||||

|

|||

|||

||

|

||||

||||

|||

||

Table 4. Tivoli Workload Scheduler/NetView EventsTrap # Name Description Additional Actions

1 * uTtrapReset The magent processwas restarted.

na

51 uTtrapProcessReset A monitored processwas restarted.

na

52 * uTtrapProcessGone A monitored process isno longer present.

na

53 * uTrapProcessAbend A monitored processabended.

na

54 * uTrapXagentConnLost The connection betweena host and xagent hasbeen lost.

na

101 * uTtrapJobAbend A scheduled jobabended.

Show Job, Rerun Job,Cancel Job

102 * uTtrapJobFailed A scheduled job couldnot be launched.


103 uTtrapJobLaunch A scheduled job waslaunched successfully.


104 uTtrapJobDone A scheduled jobfinished in a state otherthan ABEND.


105* uTtrapJobUntil A scheduled job’sUNTIL time haspassed, it will not belaunched.


151 * uTtrapSchedAbend A schedule ABENDed. Show Schedule, CancelSchedule

152 * uTtrapSchedStuck A schedule is in theSTUCK state.

Show Schedule, CancelSchedule

153 uTtrapSchedStart A schedule has startedexecution.


154 uTtrapSchedDone A schedule has finishedin a state other thanABEND.


155* uTtrapSchedUntil A schedule’s UNTILtime has passed, it willnot be launched.


201 * uTtrapGlobalPrompt A global prompt hasbeen issued.

Reply

202 * uTtrapSchedPrompt A schedule prompt hasbeen issued.

Reply

203 * uTtrapJobPrompt A job prompt has beenissued.

Reply

204 * uTtrapJobRerunPrompt A job rerun prompt hasbeen issued.

Reply

251 uTtrapLinkDropped The link to aworkstation has closed.

Link


||

||||

|||||

|||||

|||||

|||||

|||||

|

||||||

||||||

||||||

|||||

||

||||||

||

|||||

||||||

||||||

|||||

||

|||||

||

|||||

|||||

|||||

|||||

|||||

9.In

tegratio

nw

ithO

ther

Pro

du

cts

Table 4. Tivoli Workload Scheduler/NetView Events (continued)Trap # Name Description Additional Actions

252 * uTtrapLinkBroken The link to aworkstation has closeddue to an error.

Link

* These traps are enabled by default.

Polling and SNMP TrapsSince SNMP uses an unreliable transport protocol (UDP), Workload Scheduler/NetView doesnot rely on SNMP traps to indicate the status of its symbols. Instead, the manager polls itsagents periodically, requesting specific MIB values. The returned values are compared withthose returned by the previous poll, and differences are indicated as status changes inWorkload Scheduler/NetView symbols. The default polling interval is one minute. See“Tivoli Workload Scheduler/NetView Configuration Options” on page 267 for informationabout changing the polling interval.

To obtain critical process status, the manager polls all of its agents. For job schedulingstatus, the manager determines which of its agents is most likely to have the requiredinformation, and polls only that agent. The choice is made in the following order ofprecedence:

1. The agent running on the Workload Scheduler master.

2. The agent running on a Workload Scheduler backup master.

3. The agent running on any Workload Scheduler fault-tolerant agent that has fullstatus onin its workstation definition.

Enabling Workload Scheduler/NetView traps provides the following advantages:

1. Event-specific variables are included with each trap

2. Traps are logged in NetView’s event log.

If job abend traps (101) are enabled, for example, sufficient information is collected toidentify an abended job, its schedule, and the workstation on which it runs. This is usefulwhen deciding what actions to take to remedy a problem.

You may choose to disable some or all of the Workload Scheduler/NetView traps for thefollowing reasons:

1. To reduce network traffic.

2. To avoid confusion on the part of other NetView users by limiting the number of loggedevents.

For more information about the Unison Software’s enterprise-specific traps and theirvariables, see “Reconfiguring Enterprise-Specific Traps” on page 269.

Tivoli Workload Scheduler/NetView Configuration FilesOn each managed node (each node running a Tivoli Workload Scheduler/NetView agent), theselection of events and how they are reported is controlled by setting variables in twoconfiguration files:

264 Version 8.1

|

||||

|||||

|

||||

||||||||

||||

|

|

||

|

|

|

|||

||

|

||

||

|

|||

¶ The BmEvents configuration file controls the reporting of job scheduling events(101-252 in Table 4) by the mailman and batchman production processes. These eventsare passed on to the agent, which may convert them to SNMP traps, depending on thesettings in its configuration file.

¶ The MAgent configuration file controls reporting by the Workload Scheduler/NetViewagent, magent. Events selected in this file are turned into SNMP traps, which are passedto NetView by the Workload Scheduler/NetView manager, mdemon, on the managementnode. The traps can also be processed by other network management systems.

The BmEvents Configuration FileThe BmEvents configuration file is named maestrohome /BmEvents.conf . Use it toconfigure Workload Scheduler production processes on each workstation that has an agentinstalled. Its contents are described below.

# commentA comment line.

OPTIONS=MASTER|OFFIf it is set to MASTER, this workstation will report all job scheduling events for allworkstations in the Workload Scheduler network. If it is set toOFF, no jobscheduling events are reported by this workstation. If it is omitted, it defaultstoMASTER on the master, and to OFF on other workstations.

This variable is required only if the master will not be used to report job schedulingevents for the network. For example, if the master is not a managed node (no agentis installed), you should set this variable toMASTER on a backup master that has anagent installed.

LOGGING=ALL|KEYIf the value is KEY, the key flag filter mechanism is enabled. Events are sent onlyfor key jobs and job streams (refer to the 5.3 paragraph to find the events filtered bythe key flag and to Table 6 for a list of events that are forwarded regardless ofwhether the job or job stream is key or not). If the value is ALL, events are sentalso for non-key jobs and job streams.

EVENT= n [ n ...]The list of events to be reported. Event numbers must be separated by at least onespace. If omitted, the events reported by default are:51 101 102 105 151 152 155 201 202 203 204 251 252

Event 51 causes mailman and batchman to report the fact that they were restarted.Events 1, 52, and 53 are not valid in this file (see “The MAgent Configuration File”on page 266).

If theEVENT parameter is included, it completely overrides the defaults. To removeonly event 102 from the list, for example, you must enter the following:EVENT=51 101 105 151 152 155 201 202 203 204 251 252

See Table 4for a description of events.

PIPE=filenameIf set, job scheduling events are written to a FIFO file. To have events sent to theWorkload Scheduler/NetView agent, the setting must be:PIPE=MAGENT.P


||||

||||

||||

||

|||||

||||

||||||

|||

|

|||

||

|

|

|||

|

9.In

tegratio

nw

ithO

ther

Pro

du

cts

A BmEvents configuration file is included with the Workload Scheduler software. It containsseveral comment lines, and a single parameter setting:PIPE=MAGENT.P

This causes events to be reported as follows:

¶ If installed on the master, it will report all job scheduling events (101-252) for allworkstations in the network. If installed on any other workstation, no job schedulingevents will be reported. The process restart event (51) is reported regardless of theworkstation type.

¶ The following events are reported:51 101 102 105 151 152 155 201 202 203 204 251 252

¶ Event information is written to a FIFO file named MAGENT.P, which is read by theWorkload Scheduler/NetView agent.

The MAgent Configuration FileThe MAgent configuration file is named maestrohome /MAgent.conf. Use it to configure theagent on each workstation. Its contents are described below.

# commentA comment line.

OPTIONS=MASTER|OFFIf set to MASTER, the agent on this workstation will send the job scheduling eventsread from the MAGENT.P file as SNMP traps. If set to OFF , no job schedulingtraps are generated by this workstation. If omitted, it defaults to MASTER on themaster, and OFF on other workstations.

This variable is required only if the master will not be used to generate jobscheduling traps for the network. For example, if the master is not a managed node(no agent is installed), you should set this variable to MASTER on a backup masterthat has an agent installed.

EVENT= n [ n ...]The list of events to be sent as SNMP traps. With the exception of events 1, 52, and53, traps will not be generated unless the corresponding events are turned on in theBmEvents configuration file. Event numbers must be separated by at least one space.If omitted, the events sent as traps by default are:1 52 53 54 101 102 105 151 152 155 201 202 203 204 252

Event 1 (magent restarted) cannot be turned off.

If this parameter is included, it completely overrides the defaults. To remove onlyevent 102 from the list, for example, you must enter the following:EVENT=1 52 53 54 101 105 151 152 155 201 202 203 204 252

See Table 4for a description of events.

+name [pidfilename]By default, the list of processes monitored by the Workload Scheduler/NetViewagent contains the following processes: magent, netman, mailman, batchman,jobman, all mailman servers, all writers, and all extended agent connections. Usethis syntax to add processes to the list. If it is not a Workload Scheduler process,you must include its pid file name. Some examples are:

266 Version 8.1

||

|

|

||||

|

|

||

|||

||

|||||

||||

|||||

|

|

||

|

|

||||||

+SENDMAIL /etc/sendmail.pid

+SYSLOG /etc/syslogd.pid

-name Use this syntax to remove processes from the list of monitored processes. To removewriter processes, use this form:- cpuid :writer

For example, to remove the writers for all workstations with ids starting with“SYS”, enter:-SYS@:WRITER

To remove all writers , enter:-@:WRITER

To remove mailman servers “5” and “A”, enter:-SERVER5

-SERVERA

To remove all mailman servers, enter:-SERVER@

An MAgent configuration file is included with the Workload Scheduler/NetView software. Itcontains all comment lines—no parameters are set. This causes SNMP traps to be generatedas follows:

¶ If installed on the master, traps are generated for job scheduling events (101-252) on allworkstations in the network. If installed on any other workstation, no job schedulingtraps are generated.

¶ The following events result in SNMP traps:1 52 53 54 101 102 105 151 152 155 201 202 203 204 252

¶ The following processes are monitored: magent, netman, mailman, batchman, jobman ,all mailman servers, all writers, and all extended agent connections.

Monitoring Writers and Serverswriter and mailman server processes are started and stopped when Workload Schedulerworkstations are linked and unlinked. Their transitory nature, and the resulting number ofstatus changes in NetView, can cause confusion, particularly in large Workload Schedulernetworks where linking and unlinking is common. For this reason, and after gaining someexperience with Workload Scheduler/NetView on your system, you may choose to removewriter and mailman server processes from the list of monitored processes.

Tivoli Workload Scheduler/NetView Configuration OptionsTivoli Workload Scheduler/NetView submaps, symbols, and objects can be modified likeothers in NetView. The following topics describe some specific configuration options forWorkload Scheduler/NetView.

Agent Scan RateBy default, the Workload Scheduler/NetView agents scan and update the status of theirmonitored processes every 60 seconds. To change the rate:

1. Login on the managed node and edit the file maestrohome /StartUp.

2. Add the -timeout option to the magent command line.


|

|

|||

|

||

|

|

|

|

|

|

|

|

|||

|||

|

|

||

|||||||

|

|||

|||

|

|

9.In

tegratio

nw

ithO

ther

Pro

du

cts

For example, to change the rate to 120 seconds, make the following change:maestrohome /bin/magent -peers hosts -timeout 120

Manager Polling RateThe Workload Scheduler/NetView manager ( mdemon ) polls its agents to retrieve statusinformation about the managed nodes. The rate is defined in the file/usr/OV/lrf/Mae.mgmt.lrf on the management node. Unless otherwise specified, the pollingrate defaults to 60 seconds.

To change the rate:

1. Edit the file to add the -timeout option to the mdemon command line. For example, tochange the rate to 120 seconds, make the following change:Unison_Software_Maestro_Manager: maestrohome /bin/mdemon:OVs_YES_START:pmd,ovwdb:-pmd,-timeout,120:OVs_WELL_BEHAVED

2. After making a change, delete the old registration by running the ovdelobj command.

3. Register the manager by running the ovaddobj command and supplying the name of thelrf file.

For more information, review the man pages for ovaddobj(8) and lrf(4). See alsoConfiguring Agents in NetView.

Configuring Agents in NetViewTo change the configuration of Workload Scheduler/NetView agents in NetView, followthese steps:

1. Move down the IP Internet tree to the IP Segment submap showing all the nodes.

2. Select a node where a Workload Scheduler/NetView agent is running. Press Ctrl-O toopen the Object Description dialog.

3. On the Object Description dialog, select Maestro - Unison Software(c) from the ObjectAttributes list.

4. Click the View/Modify Object Attributes button.

5. On the Attributes for Object dialog:

a. To ignore this agent altogether, click the False button under Does a Maestro agentexist on this cpu?.

b. To change the rate at which mdemon polls this agent, enter the number of secondsunder Enter the number of seconds between polling. If this number is other than zero,it overrides the rate defined for the mdemon process (see Manager Polling Rateabove).

c. Click Verify, and then OK to close the Attributes for Object dialog.

6. Click OK to close the Object Description dialog.

Configuring Workstation Status in NetViewTo modify the way status is indicated for a Workload Scheduler workstation symbol, followthese steps:

1. Select a workstation symbol on the Workload Scheduler network submap.

2. Press Ctrl-O to open the Object Description dialog.

268 Version 8.1

|

|

|||||

|

||

||

|

||

||

|||

|

||

||

|

|

||

||||

|

|

|||

|

|

3. On the Object Description dialog, select Workload Scheduler from the Object Attributeslist.

4. Click the View/Modify Object Attributes button.

5. On the Attributes for Object dialog, click the True or False buttons to either ignore orrecognize the various job scheduling events. For example, to ignore job abend events,click the True button under Workload Scheduler should ignore JobAbend Events.

6. Click Verify, and then OK to close the Attributes for Object dialog.

7. Click OK to close the Object Description dialog.

Unison Software MIBFor a complete listing of the Unison Software enterprise MIB, review the file maestrohome/OV/Maestro.mib .

Reconfiguring Enterprise-Specific TrapsThe Tivoli Workload Scheduler/NetView enterprise-specific traps are configured with defaultmessages that will serve most users’ needs. To reconfigure the traps, choose EventConfiguration from the Options menu. For instructions, refer to your NetViewdocumentation or online help. It may also be helpful to review the man page fortrapd.conf(4) .

The enterprise-specific traps and their positional variables are listed in Table 5. Trapdescriptions are listed in Table 4 earlier in this chapter.

The following table lists enterprise-specific traps:

Table 5. Enterprise-specific TrapsTrap Identifier Positional Variables

1 * uTtrapReset 1Agent identifier number

2Software version

3Workload Scheduler messagestring, if any

5152 *53 *

uTtrapProcessResetuTtrapProcessGoneuTrapProcessAbend

1Process pid

2Program name


54 * uTrapXagentConnLost 1Program name



||

|

|||

|

|

|

||

||||||

||

|

||

|||

|||

|

||

|||

|||

|

|

||

|||

||

9.In

tegratio

nw

ithO

ther

Pro

du

cts

Table 5. Enterprise-specific Traps (continued)Trap Identifier Positional Variables

101 *102 *103104105*204 *

uTtrapJobAbenduTtrapJobFaileduTtrapJobLaunchuTtrapJobDoneuTtrapJobUntiluTtrapJobRerunPrompt

1workstation name of theschedule.

2Schedule name.

3Job name. For jobs submittedwith at or batch , if the namesupplied by the user is notunique, this is the WorkloadScheduler-generated name, andthe name supplied by the userappears as variable 7 below.

4workstation name on which thejob runs.

5Job number (pid).

6Job state, indicated by aninteger: 1 (ready),2 (hold), 3 (exec), 5 (abend), 6(succ), 7 (cancl),8 (done), 13 (fail), 16 (intro), 23(abenp), 24 (succp), 25 (pend).

7Job’s submitted (real) name.For jobs submitted with at orbatch , this is the name suppliedby the user if not unique. Theunique name generated byMaestro appears as variable 3above.

8User name under which the jobruns.

9Name of the job’s script file,or the command it executes.White space is replaced by theoctal equivalent; for example, aspace appears as 040.

270 Version 8.1

|

|||

||||||

||||||

||

|

|||||||

||

|

||||||

|||||||

||

|||||


(Continued)

101 *102 *103104105*204 *

(Continued)

uTtrapJobAbenduTtrapJobFaileduTtrapJobLaunchuTtrapJobDoneuTtrapJobUntiluTtrapJobRerunPrompt

(Continued)

10The rate at which an “ every” job runs, expressed as hhmm .If every was not specified forthe job, this is -32768.

11Job recovery step, indicatedby an integer: 1 (stop), 2 (stopafter recovery job), 3 (rerun), 4(rerun after recovery job), 5(continue), 6 (continue afterrecovery job), 10 (this is thererun of the job), 20 (this is therun of the recovery job).

12An event timestamp,expressed as: yyyymmddhhmmss00(that is, year, month, day, hour,minute, second, hundredthsalways zeroes).

13The prompt number, or zeroif there is no prompt.

14The prompt text, or WorkloadScheduler error message.

151 *152 *153154155*

uTtrapSchedAbenduTtrapSchedStuckuTtrapSchedStartuTtrapSchedDoneuTtrapSchedUntil

1workstation name of theschedule.

2Schedule name.

3Schedule state, indicated by aninteger: 1(ready), 2 (hold), 3(exec), 4 (stuck), 5 (abend), 6(succ),7 (cancl).

4Workload Scheduler errormessage, if any.

201 * uTtrapGlobalPrompt 1Prompt name

2Prompt number

3Prompt text

202 * uTtrapSchedPrompt 1workstation name of theschedule

2Schedule name

3Prompt number

4Prompt text


|

|||

|

||||||

|

||||||

|

||||

||||||||

||||||

||

||

|||||

|||||

||

|

|||||

||

|||

|

|

||||

|

|

|

9.In

tegratio

nw

ithO

ther

Pro

du

cts


203 * uTtrapJobPrompt 1workstation name of theschedule

2Schedule name

3Job name

4workstation name of the job

5Prompt number

6Prompt text

251252 *

uTtrapLinkDroppeduTtrapLinkBroken

1The “to” workstationname.

2 Link state, indicated by aninteger: 1 (unknown), 2 (downdue to an unlink), 3 (down dueto an error), 4 (up).

3Workload Scheduler errormessage.

* These traps are enabled by default.

Tivoli Workload Scheduler/NetView Program ReferenceThe following information is provided for those who want to run the Tivoli WorkloadScheduler/NetView programs manually. The manager program, mdemon, is normally startedwith NetView as part of the ovstart sequence, and its run options are included in the/usr/OV/lrf/Mae.mgmt.lrf file. The agent program, magent, is normally started within theWorkload SchedulerStartUp script (maestrohome /bin/StartUp).

mdemon Synopsis

mdemon [-timeout secs ] [-pmd] [-port port ] [-retry secs ]

where:

-timeoutThe rate at which agents are polled, expressed in seconds. The default is 60 seconds.See “Manager Polling Rate” on page 268 and “Configuring Agents in NetView” onpage 268 for more information about changing the rate.

-pmd This option causes mdemon to run under NetView pmd (Port Map Demon).Otherwise, it must be run manually. This option is included by default in the file/usr/OV/lrf/Mae.mgmt.lrf file.

-port For HP-UX agents only. This identifies the port address on the managed nodes onwhich the HP-UX agents will respond. The default is 31112. (See -port for magentbelow.)

-retry The period of time mdemon will wait before trying to reconnect to a non-respondingagent. The default is 600 seconds.

272 Version 8.1

|

|||

||||

|

|

|

|

|

|||||

||||

||

||

|

|||||

|

|||

|

||||

||||

||||

|||

-deleteDefinition

magent SynopsisThe syntax of magent is:

magent -peers host [, host [,...]] [-timeout secs ] [-notraps] [-port port ]

where:

-peers For HP-UX agents only. This defines the hosts (names or IP addresses) to which theagent will send its traps. The default is 127.0.0.1 (loopback).

For AIX agents, the /etc/snmpd.conf file must be modified to define the hosts towhich the agent will send its traps. To add another host, for example, duplicate theexisting “trap” line and change the host name:# This file contains Workload Scheduler

# agent registration.

#

trap public host1 1.3.6.1.4.1.736 fe

trap public host2 1.3.6.1.4.1.736 fe

-timeoutThe rate at which the agent checks its monitored processes, expressed in seconds.The default is 60 seconds.

-notrapsIf included, the agent will not generate traps.

-port For HP-UX agents only. This defines the port address on which this agent responds.The default is 31112. (See -port for mdemon above).

-communityDefinition

-agentIDDefinition

-usecurrentDefinition


||

||

|||

|

|||

|||

|

|

|

|

|

|||

||

|||

||

||

||

|

9.In

tegratio

nw

ithO

ther

Pro

du

cts

Integration with Tivoli Business Systems ManagerThis section describes the integration of Tivoli Workload Scheduler with Tivoli BusinessSystems Manager.

General InformationTivoli Business Systems Manager is an object-oriented systems management application thatprovides monitoring and event management of resources, applications and subsystems withinthe enterprise with the objective of providing continuous availability. Monitoring WorkloadScheduler daily plans with Tivoli Business Systems Manager provides quick determinationof problems that can jeopardize the successful and timely completion of the schedules.Integrating Workload Scheduler with Tivoli Business Systems Manager provides the abilityto manage schedules from a unique business systems perspective.

Integration is accomplished by the following:

¶ A special flag (key flag) in Workload Scheduler that marks those jobs or job streamsthat you want Tivoli Business Systems Manager to monitor more thoroughly.Information on these key objects is sent in the form of events.

¶ A bulk discovery mechanism that sends information on all the key jobs and job streamsof the daily plan to Tivoli Business Systems Manager.

¶ A delta discovery mechanism that sends daily plan changes for key jobs and job streamsto Tivoli Business Systems Manager.

Using these mechanisms, the Workload Scheduler CommonListener agent interacts with theTivoli Business Systems Manager adapter CommonListener. The next figure shows howevents and commands are passed from batchman and mailman to the common listener agentwhich in turn interprets them and executes proper requests to the TBSM adapter.

For bulk discovery, the TBSM database is populated with all the key objects that are in thedaily plan of Workload Scheduler. For every key object in the plan, information about itstype, properties, and status is forwarded by the scheduler to the common listener interface ofTBSM. The common listener then populates the TBSM database with this data.

TWS

Key Job

Key JStream

Not-Key Job

Not-Key JStream

TWS daily plan

clagent

TBSM

TBSM

Console

CCoommmmoonn

LLiisstteenneerr

Figure 5. Common Listener Agent Architecture

274 Version 8.1

|

|||

|

||

|

|||||||

|

|||

||

||

|||||

||||

When a new key job or job stream is added to theWorkload Scheduler plan, a deltadiscovery add function forwards related information to Tivoli Business Systems Manager.Likewise, when a key object attribute is changed, a delta discovery modify function notifiesTivoli Business Systems Manager.

Using the Key Flag MechanismThe key flag identifies the more critical jobs or job streams that are to be monitored withTivoli Business Systems Manager. Such jobs and job streams are commonly referred to askey jobs and key job streams.

Marking a job or job stream as key causes Tivoli Business Systems Manager to be notifiedevery time there is a status change or a property change.

In any case, notification of certain critical events is forwarded for all jobs and job streams,regardless of whether they have the key flag or not. The table below lists these events.

Table 6. Forwarded events for key and non-key scheduling objects.Scheduler event ID Type TBSM Event Type Severity

TWS_Job_Abend Batch Exception Critical

TWS_Sched_Abend BatchCycle Exception Critical

TWS_Job_Cancel Batch Message Warning

TWS_Sched_Cancel BatchCycle Message Warning

TWS_Job_Failed Batch Exception Critical

Setting the Key FlagTo enable the key flag mechanism on your workstation, you must have properly configuredthe LOGGING parameter of the BmEvents.conf file (see “Customizing BmEvents.conf” onpage 276).

You can mark a job or job stream as key in both the database and daily plan. In thedatabase, key jobs can be defined just as if inserted into a job stream.

To mark a job or a job stream as key, you can use one of the following:

¶ The keywords KEYSCHED (for job streams) and KEYJOB (for jobs), as the followingexample shows.SCHEDULE cpu1#sched1

KEYSCHEDON mo,tu...AT 0100:cpu1#myjob1 KEYJOB

END

cpu1#myjob1SCRIPTNAME"C:\my.bat"STREAMLOGON"twsusr1"RECOVERY STOP

¶ The job and job stream properties windows in the Job Scheduling Console.

The job properties windows display, both at the database and plan levels, an IsMonitored Job checkbox that you mark to specify Tivoli Business Systems Managermonitoring. In the job properties window at the plan level you can change this settingfor the specific job instance.


||||

|

|||

||

||

||

||||

||||

||||

||||

||||

|||||

||||

||

|

||

|||||||||||

|

||||

9.In

tegratio

nw

ithO

ther

Pro

du

cts

The job stream properties windows display, at the database and plan levels, thefollowing two items:

v An Is Monitored Job Stream check box that you mark to specify that the jobstream is to be monitored by Tivoli Business Systems Manager. You can change thissetting at the job stream instance level.

v A read-only field named Contains Monitored Job that indicates if any of the jobscomprised in the job stream have been marked as key.

Also, you can choose the key flag as a filtering criterion when you run lists of jobs orjob streams in the database or in the plan.

Installing the Common Listener AgentThe common listener agent is automatically installed with Workload Scheduler. It should runon every agent of your Workload Scheduler network.

The following files are installed in a directory named maestrohome/CommonListener:

¶ The common listener agent executable that will run the common listener process.

¶ The ClEvents.conf configuration file.

¶ The customize executable that you need to run after installation of Workload Schedulerhas completed.

When you run customize, it performs the following actions:

1. Install ClEvents.conf in the maestrohome directory.

2. Install the BmEvents.conf configuration file into the maestrohome directory if it is notyet installed and customize it for use by the common listener agent.

Note: To run customize, you must be logged on as an Administrator.

Customizing the Configuration FilesTwo configuration files are important for running the common listener agent:

¶ BmEvents.conf

¶ ClEvents.conf

These files are configured with default values when you run customize. You can change thedefaults if you have different preferences with respect to which events are reported to TivoliBusiness Systems Manager and how they must be reported.

Mailman, batchman, or the common listener agent read form these configuration files whenthey are initialized. If you make any changes in these files, then you have to restart them.

Customizing BmEvents.confYou can change the following parameters:

OPTIONS=MASTER|OFFIf the value is OFF, only local events are forwarded to Tivoli Business SystemsManager. If the value is MASTER, also the events occurring in the attachedworkstations are forwarded. The value should be MASTER for the masterworkstation and OFF for the other workstations.

276 Version 8.1

||

|||

||

||

|

||

|

|

|

||

|

|

||

|

|

|

|

|

|||

||

||

|||||

LOGGING=ALL|KEYIf the value is KEY, the key flag filter mechanism is enabled. Events are sent onlyfor key jobs and job streams (refer to the 5.3 paragraph to find the events filtered bythe key flag and to Table 6 for a list of events that are forwarded regardless ofwhether the job or job stream is key or not). If the value is ALL, events are sentalso for non-key jobs and job streams.

EVENTS = <n>The list of events to report to Tivoli Business Systems Manager. By default, all theevents listed in Table 7 on page 279 are sent. You can exclude some events if youare not interested in reporting them. In this case, write here a list of the eventnumbers that you want to send.

PIPE = <pipe_path>The name and the path of the pipe file where batchman and mailman will write theevents for the common listener agent to read. You can add more than one pipe file.

A pipe file provides the quickest device to transmit events. However, it does notallow for event buffering as log files do and therefore it does not prevent eventsfrom going unrecorded when the common listener agent is down for a long time. Inthis case, the daily plan that is transmitted to Tivoli Business Systems Manager willbe very different from the actual one.

FILE = <file_path>The name and the path of the log file where batchman and mailman will write theevents for the common listener agent to read. You can add more than one log file.

Using log files rather than pipe or message files has the following advantages:

¶ Event buffering

Log files allow for event buffering. This eliminates the risk of events being lostif the common listener agent is down.

¶ Synchronization

Using log files allows for synchronization between bulk or delta discovery andthe forwarding of events. In fact if the common listener agent reads from theevent log file, during a bulk or delta discovery request, it will stop to readevents from the file and just at the end of the discovery it will continue toprocess the events sent by the scheduler. If the common listener agent readsevents from pipe, it will stop to read from it, batchman will write the events intothe log file and the agent will start to execute the discovery. After that, beforerestoring the communication via pipe with batchman, the agent will send all theevents stored into the event file. In this way, you risk losing the transmission ofproperty changes that are stored in the pipe file and end up with the TivoliBusiness Systems Manager database that does not reflect all the propertychanges of the objects in the Workload Scheduler current plan.

MSG = <msg_path>The name and the path of the message file where batchman and mailman will writethe events for the common listener agent to read. You can add more than onemessage file.

The message file should be used mainly for transmitting commands from batchmanand mailman to the common listener agent. Use it in addition to log (preferably) orpipe files that will have in contrast the main task of transmitting events.


||||||

|||||

|||

|||||

|||

|

|

||

|

||||||||||||

||||

|||

9.In

tegratio

nw

ithO

ther

Pro

du

cts

Customizing ClEvents.confYou can change the following parameters:

EVENTS = <n>The list of events to report to Tivoli Business Systems Manager. By default, all theevents listed in Table 7 on page 279 are sent. You can exclude some events if youare not interested in reporting them. In this case, write here a list of the eventnumbers that you want to send.

MSG = <msg_path>The name and the path of the message file where batchman and mailman will writethe events for the common listener agent to read. The name and path of this filemust match one of the output files you specified in BmEvents.conf.

RETRYINTERVAL=<seconds>The amount of time after which the cl_agent tries to reconnect to the Tivoli BusinessSystems Manager adapter.

Starting and Stopping the Common Listener AgentThe common listener agent process is independent from the other Workload Schedulerprocesses. You can run it with the following commands:

conman cl_agentstartStarts the agent by sending a new service request to netman. Like the conman startcommand, this request will also start netman, if it is down.

conman cl_agentstopStops the agent by placing a message in the mailbox.

conman cl_bulkdiscoveryGathers information about the key jobs and job streams.

278 Version 8.1

||

|||||

||||

|||

|

||

|||

||

||

|

Workload Scheduler/Tivoli Business Systems Manager EventsTable 7 lists the events that are reported to Tivoli Business Systems Manager unless youspecify otherwise in the configuration files (see “Customizing the Configuration Files” onpage 276).

Table 7. Tivoli Workload Scheduler Events for Tivoli Business Systems ManagerEvent

NumberType Description Key Flag Filter

Enabled

101 mstJobAbend Job abended No

102 mstJobFailed Job is in error status No

103 mstJobLaunch Job launched Yes

104 mstJobDone Job finished Yes

107 mstJobCancel A job has been canceled No

108 mstJobReady Job is in ready status Yes

109 mstJobHold Job is in hold status Yes

110 mstJobRestart Job is in restart status Yes

111 mstJobCant Batchman failed to stream the job No

112 mstJobSuccp Job in succ-pending status Yes

113 mstJobExtrn Job is in extern status Yes

114 mstJobIntro Job is in intro status Yes

115 mstJobStuck Job is in stuck status Yes

116 mstJobWait Job is in wait status Yes

117 mstJobWaitd Job is in wait-deferred status Yes

118 mstJobSched Job is in sched status Yes

151 mstSchedAbend Schedule abended No

152 mstSchedStuck Schedule is in stuck state No

153 mstSchedStart Schedule started Yes

154 mstSchedDone Schedule finished Yes

157 mstSchedCancel Schedule has been canceled No

158 mstSchedReady Schedule is in ready status Yes

159 mstSchedHold Schedule is in hold status Yes

160 mstSchedExtrn Schedule is in extern status Yes

161 mstSchedCnPend Schedule is in cancel-pendingstatus

Yes


|

|||

||

||||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

||||

|||||

||

9.In

tegratio

nw

ithO

ther

Pro

du

cts

280 Version 8.1

Maintaining Tivoli Workload Scheduler

As with any complex software system, Tivoli Workload Scheduler brings with it the need toprovide routine, scheduled maintenance to keep it functioning at its highest level ofperformance.

This Appendix discusses:

¶ Defragmenting Workload Scheduler databases using the Composer build command

¶ Creating text-bases backups of Workload Scheduler databases using the Composer createcommand

¶ Restoring Tivoli Workload Scheduler databases from text files using Composer

¶ Listing and describing the directories and files to be copied to a standby master domainmanager

¶ Maintaining the subset of Tivoli Workload Scheduler files that continue to expand

DatabasesFor optimum efficiency and minimum downtime, there are some preventative measures youcan take regarding Tivoli Workload Scheduler databases:

¶ Defragmenting build

¶ Backing up and archiving

¶ Reporting

Defragmenting BuildAs the number of additions and deletions to the Workload Scheduler scheduling databasesgrows, the data files become fragmented. Rebuilding the master files removes unusedrecords and optimizes the keys.

To rebuild a master data file, use the Composer build command:

composer "build object_file"

Where object_file can be one of:

calendarsMaster calendar file.

cpudataMaster CPU file.

jobs Master job file.

A


|

|

|||

|

|

||

|

||

|

|

||

|

|

|

|

|||

|

|

|

||

||

||

A.

Main

tainin

gTivo

liW

orklo

adS

ched

uler

mastskedMaster schedule file. This also build the job.sched file.

parms Master parameter file.

promptsMaster prompt file.

resourcesMaster resource file.

users Master user file.

If a master file does not exist, it is created. If the file exists, it is rebuilt.

Backing UpTo minimize downtime during disaster recovery, backup your master data files to eitheroffline storage or a backup master CPU.

Creating Text FilesOne way to backup the master data files is to create text files that contain the master filedata. The following procedure uses the Composer create command to do this. Thecommands in this procedure extract the information in the databases to text files. The filesare created only if one or more of the associated objects exist.

To create the text files, start Composer from a command prompt and enter the followingcommands:create cpu.txt from cpu=@create jobs.txt from jobs=@#@create sched.txt from sched=@#@create users.txt from users=@#@create cal.txt from calendarscreate prompt.txt from promptscreate parms.txt from parmscreate res.txt from resources

Restoring From Text FilesIf the master data files need to be reloaded, the following procedure can restore the filesfrom the text files. The commands in this procedure create the databases and populate themwith the scheduling objects extracted in “Creating Text Files”.

Note: Some of the files will not exist if there no objects of the associated type.

To restore the master files, start Composer from a command prompt and enter the followingcommands:add cpu.txtadd jobs.txtadd sched.txtadd users.txtreplace cal.txtreplace prompt.txtreplace parms.txtreplace res.txt

282 Version 8.1

||

||

||

||

||

|

|

||

|||||

||

||||||||

||||

|

||

||||||||

|

Using a Standby MasterIf you have configured a fault-tolerant workstation to act as a standby master domainmanager, you will need to preserve copies of your master scheduling databases on thatfault-tolerant workstation that are as current as possible.

To create backup of the master scheduling files to the standby master:

1. Copy the following files from the TWShome/../unison/network directory on the masterdomain manager to the TWShome/../unison/network directory on the standby master:cpudatacpudata.keyuserdatauserdata.key

2. Copy all the files in the TWShome/mozart directory on the master domain manager to theTWShome/mozart directory on the on the standby master.

This procedure should be performed each day, or whenever there are significant changes toany scheduling objects.

Using Disk or Tape ArchiveYou should include all Workload Scheduler files and directories, including log files, in yoursystem backup to offline storage.

ReportingTivoli Workload Scheduler provides several report and database extract programs which canhelp in the tracking of maintenance issues in the Workload Scheduler system. Forinformation, see “Report Commands” on page 225.

Maintaining the File SystemSome of the file systems and directories will need periodic maintenance.

File SetsEach job that runs under Workload Scheduler control creates a log file in the WorkloadScheduler stdlist directory. These log files are created by the Workload Scheduler jobmanager process and remain there until deleted by the system administrator.

The master domain manager creates post-production log file in the Workload SchedulerTWShome/schedlog directory for each complete production day. These log files are createdby the Workload Scheduler job manager process and remain there until deleted by thesystem administrator.

The easiest method of controlling the growth of these directories is to decide how long thelog files are needed, then schedule a Workload Scheduler job to remove any files older thanthe given number of days. Use the rmstdlist command to remove files from the stdlistdirectory. For details about the rmstdlist command, see “rmstdlist Command” on page 212.

Temporary FilesThe Workload Scheduler master domain manager uses temporary files when compiling newproduction control databases. These files are deleted when compiling is complete.


||||

|

||

||||

||

||

|||

|

|||

|

|

|

|||

||||

||||

|

||

A.

Main

tainin

gTivo

liW

orklo

adS

ched

uler

284 Version 8.1

Time Zone Names and DescriptionsName Description Relative to GMT

GMT Greenwich Mean Time GMT

UTC Universal Coordinated Time GMT

ECT European Central Time GMT+1:00

EET Eastern European Time GMT+2:00

ART (Arabic) Egypt Standard Time GMT+2:00

EAT Eastern African Time GMT+3:00

MET Middle East Time GMT+3:30

NET Near East Time GMT+4:00

PLT Pakistan Lahore Time GMT+5:00

IST India Standard Time GMT+5:30

BST Bangladesh Standard Time GMT+6:00

VST Vietnam Standard Time GMT+7:00

CTT China Taiwan Time GMT+8:00

JST Japan Standard Time GMT+9:00

ACT Australia Central Time GMT+9:30

AET Australia Eastern Time GMT+10:00

SST Solomon Standard Time GMT+11:00

NST New Zealand Standard Time GMT+12:00

MIT Midway Islands Time GMT-11:00

HST Hawaii Standard Time GMT-10:00

AST Alaska Standard Time GMT-9:00

PST Pacific Standard Time GMT-8:00

PNT Phoenix Standard Time GMT-7:00

MST Mountain Standard Time GMT-7:00

CST Central Standard Time GMT-6:00

EST Eastern Standard Time GMT-5:00

IET Indiana Eastern Standard Time GMT-5:00

PRT Puerto Rico and US Virgin Islands Time GMT-4:00

CNT Canada Newfoundland Time GMT-3:30

AGT Argentina Standard Time GMT-3:00

BET Brazil Eastern Time GMT-3:00

CAT Central African Time GMT-1:00

B


B.

Time

Zo

ne

Nam

esan

dD

escriptio

ns

286 Version 8.1

Glossary

A

Access methodAn access method is an executable used by extended agents to connect and control job execution on otheroperating systems (for example, MVS) and applications (for example, Oracle Applications, Peoplesoft, and Baan).The access method must be specified in the workstation definition for the extended agent.

B

BatchmanBatchman is a process started at the beginning of each Workload Scheduler processing day to launch jobs inaccordance with the information in the Symphony file.

C

CalendarA calendar is a defined object in the Tivoli Workload Scheduler database that contains a list of scheduling dates.Because it is a unique object defined in database, it can be assigned to multiple job streams. Assigning a calendarto a job stream causes that job stream to be executed on the days specified in the calendar. Note that a calendarcan be used as an inclusionary or exclusionary run cycle.

ConmanConman (console manager) is a legacy command-line application for managing the production environment.Conman performs the following tasks: start and stop production processes, alter and display schedules and jobs inthe plan, and control workstation linking in a network.

ComposerComposer is a legacy command-line application for managing the definitions of your scheduling objects in thedatabase.

D

DatabaseThe database contains all the definitions you have created for scheduling objects (for example, jobs, job streams,resources, workstations, etc). In addition, the database holds other important information such as statistics of joband job stream execution, information on the user ID who created an object, and an object’s last modified date.In contrast, the plan contains only those jobs and job streams (including dependent objects) that are scheduled forexecution in today’s production.

DeadlineThe last moment in time that a job or job stream can begin execution. This corresponds to the Until time inlegacy Maestro.

DependencyA dependency is a prerequisite that must be satisfied before the execution of a job or job stream can proceed.The maximum number of dependencies permitted for a job or job stream is 40. The four types of dependenciesused by Tivoli Workload Scheduler are follows dependencies, resource dependencies, file dependencies, andprompt dependencies.

DomainA domain is a named group of Workload Scheduler workstations consisting of one or more agents and a domainmanager acting as the management hub. All domains have a parent domain except for the master domain.

Domain ManagerThe management hub in a Tivoli Workload Scheduler domain. All communications to and from the agents in thedomain are routed through the domain manager.


Glo

ssary

DurationThe time you expect the job to take to complete. In the Timeline view of jobs in the database, the duration isrepresented by a light blue bar at the center of the activity bar or by a light blue diamond.

E

Earliest start timeThe time before which the job or job stream cannot start. The earliest start time is an estimate based on previousexperiences running the job or job stream. However, the job or job stream can start after the time you specify aslong as all other dependencies are satisfied. In the timeline, the start time is represented by the beginning (leftedge) of the navy blue activity bar. For job instances, the start time that Tivoli Workload Scheduler for z/OScalculates is represented by a light blue bar. See also “Actual start time” and “Planned start time”.

Exclusionary run cycleA run cycle that specifies the days a job stream cannot be run. Exclusionary run cycles take precedent overinclusionary run cycles.

Expanded databaseExpanded databases allow longer names for database objects such as jobs, job streams, workstations, domains,and users. Expanded databases are configured using the dbexpand command or as an option during installation.Do not expand your database before understanding the implications and impact of this command.

Extended agentExtended agents are used to integrate Tivoli Workload Scheduler’s job control features with other operatingsystems (for example, MVS) and applications (for example, Oracle Applications, Peoplesoft, and Baan). Extendedagents use scripts called access methods to communicate with external systems.

External jobA job from one job stream that is a predecessor for a job in another job stream. An external job is represented bya place holder icon in the Graph view of the job stream.

F

Fault-tolerant agentAn agent workstation in the Tivoli Workload Scheduler network capable of resolving local dependencies andlaunching its jobs in the absence of a domain manager.

FenceThe job fence is a master control over job execution on a workstation. The job fence is a priority level that a jobor job stream’s priority must exceed before it can execute. For example, setting the fence to 40 prevents jobswith priorities of 40 or less from being launched.

Final Job StreamThe FINAL job stream should be the last job stream that is executed in a production day. It contains a job thatruns the script file Jnextday.

Follows dependencyA dependency where a job or job stream cannot begin execution until other jobs or job streams have completedsuccessfully.

G

Global optionsThe global options are defined on the master domain manager in the globalopts file, and these options apply toall workstations in the Workload Scheduler network. See also “Local options”.

H

HostA Workload Scheduler workstation required by extended agents. It can be any scheduler workstation exceptanother extended agent.

288 Version 8.1

I

Inclusionary Run CycleA run cycle that specifies the days a job stream is scheduled to run. Exclusionary run cycles take precedent overinclusionary run cycles.

Interactive jobsA job that runs interactively on a Windows NT desktop.

Internal statusInternal status reflects the current status of jobs and job streams in the scheduler engine. Internal status is uniqueto Workload Scheduler. See also Status.

Internetwork (INET) dependenciesA dependency between jobs or job streams in separate Tivoli Workload Scheduler networks. See also “Networkagent”.

Internetwork (INET) job / job streamA job or job stream from a remote Tivoli Workload Scheduler network that is a predecessor to a job or jobstream in the local network. An Internetwork job is represented by a place holder icon in the Graph view of thejob stream. See also “Network agent”.

J

Jnextday jobPre- and post-production processing can be fully automated by scheduling the Jnextday job to run at the end ofeach day. A sample jnextday job is provided as TWShome\Jnextday. The Jnextday job does the following: setsup the next day’s processing (contained in the Symphony file), prints reports, carries forward unfinished jobstreams, and stops and restarts the scheduler.

JobA job is a unit of work that is processed at a workstation. The job definition consists of a unique job name in thescheduler database along with other information necessary to run the job. When you add a job to a job stream,you can define its dependencies and its time restrictions such as the estimated start time and deadline.

Job InstanceA job scheduled for a specific run date in the plan. See also “Job”.

Job statusSee “Status”.

Job StreamA Job Stream consists of a list of jobs that execute as a unit (such as a weekly backup application), along withtimes, priorities and other dependencies that determine the exact order of job execution.

Job stream instanceA job stream that is scheduled for a specific run date in the plan. See also “Job stream”.

L

LimitJob limits provide a means of allocating a specific number of job slots into which Tivoli Workload Scheduler isallowed to launch jobs. A job limit can be set for each job stream, and for each workstation. For example, settingthe workstation job limit to 25 permits the scheduler to have no more than 25 jobs executing concurrently on theworkstation.

ListA list displays job scheduling objects. You must create separate lists for each job scheduling object. For each jobscheduling object, there are two types of lists: one of definitions in the database and another of instances in theplan.


Glo

ssary

Local optionsThe local options are defined in the localopts file. Each workstation in the Tivoli Workload Scheduler networkmust have a localopts file. The settings in this file apply only to that workstation. See also “Global options”.

M

Master Domain ManagerIn a Tivoli Workload Scheduler network, the master domain manager maintains the files used to document thescheduling objects. It creates the plan at the start of each day, and performs all logging and reporting for thenetwork.

N

Network agentA type of extended agent used to create dependencies between jobs and job streams on separate Tivoli WorkloadScheduler networks. See also “Internetwork (INET) dependency”.

P

ParameterParameters are used to substitute values into your jobs and job streams. When using a parameter in a job script,the value is substituted at run time. In this case, the parameter must be defined on the workstation where it willbe used. Parameters cannot be used when scripting extended agent jobs.

PlanThe plan contains all job scheduling activity planned for a period of one day. In Workload Scheduler, the plan iscreated every 24 hours and consists of all the jobs, job streams, and dependency objects that are scheduled toexecute for that day. All job streams for which you have created run cycles are automatically scheduled andincluded in the plan. As the production cycle progresses, the jobs and job streams in the plan are executedaccording to their time restrictions and other dependencies. Any jobs or job streams that do not executesuccessfully are rolled over into the next day’s plan.

Planned Start TimeThe time that the scheduler estimates a job instance will start. This estimate is based on start times of previousexecutions.

PredecessorA job that must complete successfully before successor jobs can begin execution.

PriorityThe scheduler has a queuing system for jobs and job streams in the plan. You can assign a priority level for eachjob and job stream from 0 to 101. A priority of 0 will not execute.

PromptPrompts can be used as dependencies for jobs and job streams. A prompt must be answered affirmatively for thedependent job or job stream to launch. There are two types of prompts: predefined and ad hoc. An ad hoc promptis defined within the properties of a job or job stream and is unique to that job or job stream. A predefinedprompt is defined in the scheduler database and can be used by any job or job stream.

R

ResourceResources can represent either physical or logical resources on your system. Once defined in Tivoli WorkloadScheduler database, they can be used as dependencies for jobs and job streams. For example, you can define aresource named ″tapes″ with a unit value of two. Then, define jobs that require two available tape drives as adependency. Jobs with this dependency cannot run concurrently because each time a job is run the “tapes”resource is in use.

Run cycleA run cycle specifies the days that a job stream is scheduled to run. In Workload Scheduler, there are three typesof run cycles you can specify for a job stream: a Simple run cycle, a Weekly run cycle, or a Calendar run cycle

290 Version 8.1

(commonly called a calendar). Note that each type of run cycle can be inclusionary or exclusionary. That is, eachrun cycle can define the days a job stream is included in the production cycle, or the days a job stream isexcluded from the production cycle. When you define multiple run cycles to a job stream, and inclusionary andexclusionary run cycles specify the same days, the exclusionary run cycles take precedent.

S

Simple Run CycleA simple run cycle is a specific set of user-defined days a job stream is executed. A simple run cycle is definedfor a specific job stream and cannot be used by multiple job streams. For more information see Run Cycle.

StatusStatus reflects the current job or job stream status within the Job Scheduling Console. The Job SchedulingConsole status is common to both Tivoli Workload Scheduler and Tivoli Workload Scheduler for z/OS. See alsoInternal status.

stdlist fileA standard list file is created for each job launched by Tivoli Workload Scheduler. Standard list files containheader and trailer banners, echoed commands, errors, and warnings. These files can be used to troubleshootproblems in job execution.

SuccessorA job that cannot start until all of the predecessor jobs on which it is dependent are completed successfully.

Symphony fileThis file contains the scheduling information needed by the Production Control process (batchman) to execute theplan. The file is built and loaded during the pre-production phase. During the production phase, it is continuallyupdated to indicate the current status of production processing: work completed, work in progress, work to bedone. To manage production processing, the contents of the Symphony file (plan) can be displayed and alteredwith the Job Scheduling console.

T

Time restrictionsTime restrictions can be specified for both jobs and job streams. A time can be specified for execution to begin,or a time can be specified after which execution will not be attempted. By specifying both, you can define awindow within which a job or job stream will execute. For jobs, you can also specify a repetition rate. Forexample, you can have Tivoli Workload Scheduler launch the same job every 30 minutes between the hours of8:30 a.m. and 1:30 p.m.

Tivoli Management Framework (TMF)The base software that is required to run the applications in the Tivoli product suite. This software infrastructureenables the integration of systems management applications from Tivoli Systems Inc. and the Tivoli Partners. TheTivoli Management Framework includes the following: vObject request broker (oserv) vDistributed objectdatabase vBasic administration functions vBasic application services vBasic desktop services such as the graphicaluser interface In a Tivoli environment, the Tivoli Management Framework is installed on every client and server.However, the TMR server is the only server that holds the full object database.

Tivoli Management Region (TMR)In a Tivoli environment, a Tivoli server and the set of clients that it serves. An organization can have more thanone TMR. A TMR addresses the physical connectivity of resources whereas a policy region addresses the logicalorganization of resources.

Tree viewThe view on the left side of the Job Scheduling Console that displays the scheduler server, groups of default lists,and groups of user created lists.


Glo

ssary

U

UserFor Windows NT only, the user name specified in a job definition’s “Logon” field must have a matching userdefinition. The definitions furnish the user passwords required by the scheduler to launch jobs.

Utility commandsA set of command-line executables for managing the scheduler.

W

Weekly Run CycleA run cycle that specifies the days of the week that a job stream is executed. For example, a job stream can bespecified to execute every Monday, Wednesday, and Friday using a weekly run cycle. A weekly run cycle isdefined for a specific job stream and cannot be used by multiple job streams. For more information see RunCycle.

WildcardsThe wildcards for Tivoli Workload Scheduler are: ? Replaces one alpha character. % Replaces one numericcharacter. * Replaces zero or more alphanumeric characters. Wildcards are generally used to refine a search forone or more objects in the database. For example, if you want to display all workstations, you can enter theasterisk (*) wildcard. To get a listing of workstations site1 through site8, you can enter site%.

WorkstationA workstation is usually an individual computer on which jobs and job streams are executed. They are defined inthe Tivoli Workload Scheduler database as a unique object. A workstation definition is required for everycomputer that executes jobs or job streams in the Workload Scheduler network.

Workstation classA workstation class is a group of workstations. Any number of workstations can be placed in a class. Job streamsand jobs can be assigned to execute on a workstation class. This makes replication of a job or job stream acrossmany workstations easy.

X

X-agentSee “Extended agent”.

292 Version 8.1

Index

Aadddep job command 106adddep sched command 106altpass command 107altpri command 108at command 180at keyword 61

Bbatch command 180books

feedback xiionline xiiordering xii

Ccalendar definition 29cancel job command 111cancel sched command 111carryforward keyword 63caxtract command 184command prompt 35command prompt, conman 91command syntax, conman 91comments keyword 63composer command descriptions 37composer command syntax 35composer control characters 34composer editor 35composer program 33composer reference 17confirm command 113confirmed keyword 64conman, running 89conman command list 93conman command prompt 91conman command syntax 91conman reference 89console command 114continue command 114control characters 34control characters, conman 89cpuinfo command 187creating an internetwork dependency 247Customer Support xiii

Ddatabase entries 17database object editor 35datecalc command 187dbexpand command 191deldep command 115deldep sched command 116delete command 192delimiters 36delimiters, conman 92dependency

internetwork 247directory names, notation xiiidisplay command 117domain definition 22

Ee-mail contact xiiieditor, database object 35end keyword 65environment variables, notation xiiievery keyword 66evtsize command 194except keyword 67exit command 118extended agent

overview 235reference 235workstation definition 235

Ffeedback about publications xiiifence command 119follows keyword 69freedays keyword 70

Hhelp command 120


Ind

ex

Iin order keyword 72internetwork dependency 247

Jjbxtract command 194job definition 23job statement keyword 73job states 99jobinfo command 196jobstdl command 198

Kkeywords, scheduling language 60kill command 121killproc command 224

Llimit cpu command 122limit keyword 76limit sched command 123link command 124listproc command 224listsym command 126

Mmaestro command 200makecal command 201manuals


morestdl command 203

Nneeds keyword 77netmth access method 245network agent

internetwork dependency 247netmth 245option file 246overview 245workstation 245workstation command line example 246

notationenvironment variables xiiipath names xiiitypeface xiii

Ooffline output 90offline output for UNIX 34on keyword 78online publications xiiopens keyword 81ordering publications xii

Pparameter definition 30parms command 204path names, notation xiiipaxtract command 205priority keyword 83prompt definition 31prompt keyword 84prxtract command 206publications


Rr11xtract command 207recall command 128redo command 128release command 208release job command 130release sched command 131reply command 133rerun command 134resource command 137resource definition 32rextract command 210rmstdlist command 211running composer 33running conman 89

Sschedule keyword 85scheduling language 59scheduling language keywords 60scheduling objects 17

294 Version 8.1

selecting job streams in commands 100selecting jobs in commands 94setsym command 138showcpus command 139showdomains command 142showexec command 212showfiles command 143showjobs command 145showprompts command 153showresources command 153showschedules command 155shutdown command 158special characters, composer 36special characters, conman 92start command 159startup command 213states, jobs 99status command 161stop command 162submit docommand 164submit file command 166submit job command 168submit sched command 170switchmgr command 172syntax, scheduling language 59system command, conman 173system commands, conman 90

Ttellop command 174terminal output 34, 90Tivoli Customer Support xiii

Uunlink command 175unsupported commands 224until keyword 86user definition 27user prompts 90utility commands 179

Vvariables, notation for xiiiversion command 177, 214

Wwildcard characters 36, 92wmaeutil command 11, 216workstation class definition 22workstation definition 18

Xxrxtrct command 218


Ind

ex

296 Version 8.1

Program Number: 5698-WKB

Printed in Denmark by IBM Danmark A/S

SH19-4556-00

tivoli workload scheduler reference...

Documents