Control-M_Server for Unix Admin guide

CONTROL-M®/Server for Unix

Administrator Guide

Version 6.0.03

September 16, 2001

Copyright © 2001 BMC Software, Inc. All rights reserved.

BMC Software, the BMC Software logos, and all other BMC Software product or service names are registered trademarks or trademarks of BMC Software, Inc. All other registered trademarks or trademarks belong to their respective companies.

MM-6003G-A0107A-UNIX

Restricted Rights Legend

U.S. GOVERNMENT RESTRICTED RIGHTS. UNPUBLISHED–RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure by the U.S. Government is subject to restrictions set forth in FAR Section 52.227-14 Alt. III (g)(3), FAR Section 52.227-19, DFARS 252.227-7014 (b), or DFARS 227.7202, as amended from time to time. Send any contract notices to Contractor/Manufacturer:

BMC Software, Inc.2101 CityWest Blvd.Houston TX 77042-2827USA

Contacting BMC Software

You can access the BMC Software Web site at http://www.bmc.com. From this Web site, you can obtain general information about the company, its products, special events, and career opportunities. For a complete list of all BMC Software offices and locations, go to http://www.bmc.com/corporate/offices.html.

http://www.bmc.com/corporate/offices.html

http://www.bmc.com

BMC Software, Inc., Confidential and Proprietary Information

iii

USA and Canada Outside USA and Canada

Address BMC Software, Inc.2101 CityWest Blvd.Houston TX 77042-2827

Telephone

Fax

(01) 713 918 8800

(01) 713 918 8000

Telephone 713 918 8800 or800 841 2031

Fax 713 918 8000


iv CONTROL-M/Server for Unix Administrator Guide

Customer Support

You can obtain technical support by using Response Online™ (support from the Web) or Response On Demand™. To expedite your inquiry, please see “Before Contacting BMC Software,” below.

Response Online

You can obtain technical support from BMC Software 24 hours a day, seven days a week by accessing the technical support Web site at http://www.bmc.com/support.html. From this site, you can

• read overviews about support services and programs that BMC Software offers

• find the most current information about BMC Software products• search a database for problems similar to yours and possible

solutions• order or download product documentation• report a problem or ask a question• subscribe to receive e-mail notices when new product versions are

released• find worldwide BMC Software support center locations and contact

information, including e-mail addresses, fax numbers, and telephone numbers

Response On Demand

In the USA and Canada, if you need technical support and do not have access to the Web, call 800 537 1813. Outside the USA and Canada, please contact your local support center or your local sales office for assistance.

Before Contacting BMC Software

Before you contact BMC Software, have the following information available so that a technical support analyst can begin working on your problem immediately:

• product information

— product name— product version (release number)— license number and password (trial or permanent)

• operating-system and environment information

— machine type

http://www.bmc.com/support.html


v

— operating system type, version, and service pack or program temporary fix (PTF)

— system hardware configuration— serial numbers— related software (database, application, and communication)

including type, version, and service pack or PTF

• sequence of events leading to the problem

• commands and options that you used

• messages received (and the time and date that you received them)

— product error messages— messages from the operating system, such as file system

full— messages from related software


vi CONTROL-M/Server for Unix Administrator Guide


Contents vii

Contents

Contents

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixRelated Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiNotational Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii

Chapter 1 OverviewCONTROL-M Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Server-Agent Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Identification of Agent Platforms . . . . . . . . . . . . . . . . . . . . . . . . 1-6Communication Status of Agent Platforms . . . . . . . . . . . . . . . . 1-6Interrupted Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8Time-Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8Authorized CONTROL-M Servers File . . . . . . . . . . . . . . . . . . . 1-9Agent Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 1-9

Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9Failover Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10Host Identification in the Agent Platform . . . . . . . . . . . . . . . . . . . . . 1-12New Day Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13

Scheduling Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15User Daily Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18Date Control Record (UDLAST) . . . . . . . . . . . . . . . . . . . . . . . . 1-21Handling of Interruptions During a User Daily Job . . . . . . . . . . 1-23Issuing a Job Order Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23

Shout Destination Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24Shout Message Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26

Runtime Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-28CONTROL-M Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-31Daylight Savings Time Considerations . . . . . . . . . . . . . . . . . . . . . . . 1-33

Advancing the Clock Forward . . . . . . . . . . . . . . . . . . . . . . . . . . 1-33


viii CONTROL-M/Server for Unix Administrator Guide

Moving the Clock Backwards . . . . . . . . . . . . . . . . . . . . . . . . . . .1-34CONTROL-M Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-36Heartbeat Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-37Advanced Problem Detection Tools . . . . . . . . . . . . . . . . . . . . . . . . .1-38

Setting Event Logger Parameters . . . . . . . . . . . . . . . . . . . . . . . .1-39Managing Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-41Stack Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-42

Watchdog Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-44Watchdog User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-47Error Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-48

User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-50Processing Overhead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-50

Chapter 2 UtilitiesUtility Reference Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4Reports Generated from Utilities . . . . . . . . . . . . . . . . . . . . . . . . .2-6Directing Output From Utilities . . . . . . . . . . . . . . . . . . . . . . . . .2-7

Accessing Utilities From Other Unix Users . . . . . . . . . . . . . . . . . . .2-9Define Variables in the User’s Environment . . . . . . . . . . . . . . . .2-9Add an Executable Library to the User’s Path . . . . . . . . . . . . . .2-12Assign Read/Write Permissions . . . . . . . . . . . . . . . . . . . . . . . . .2-14

Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15ctm_agstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15ctm_backup_bcp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17ctm_restore_bcp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-19ctmcontb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-21ctmcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-25ctmdbapasswd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-36ctmdbbck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-37ctmdbcheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-39ctmdbrst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-44ctmdbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-45ctmdbtrans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-46ctmdefine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-47ctmdiskspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-62ctmexdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-64ctmfw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-66ctmgrpdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-75ctmjsa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-77ctmkilljob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-81


Contents ix

ctmldnrs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-82ctmloadset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-86ctmlog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-91ctmordck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-94ctmorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-96ctmpasswd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-102ctmping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-103ctmpsm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-106ctmrpln . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-120ctmruninf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-124ctmshout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-127ctmshtb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-129ctmstats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-130ctmstvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-133ctmsuspend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-134ctmsys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-135ctmudchk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-145ctmudlst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-147ctmudly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-149ctmvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-150ctmwhy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-154ctm2snmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-155ecactltb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-157ecaqrtab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-158

Chapter 3 SecurityLevel of Application Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2CONTROL-M Security Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Scheduling Table Authorization . . . . . . . . . . . . . . . . . . . . . . . . . 3-4Active Jobs File Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5Entities Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Agent Platform Security Checks . . . . . . . . . . . . . . . . . . . . . . . . . 3-8Summary of Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

Security Maintenance Utility (Interactive Mode) . . . . . . . . . . . . . . . 3-11User Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13Group Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18Scheduling Table Authorization . . . . . . . . . . . . . . . . . . . . . . . . . 3-21Active Jobs File Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24Entities Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28


x CONTROL-M/Server for Unix Administrator Guide

Security Maintenance Utility (Batch Mode) . . . . . . . . . . . . . . . . . . .3-32User Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-32Group Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-33Scheduling Table Authorization . . . . . . . . . . . . . . . . . . . . . . . . .3-33Active Jobs File Authorization . . . . . . . . . . . . . . . . . . . . . . . . . .3-34Entities Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-34Exporting Security Definition Tables . . . . . . . . . . . . . . . . . . . . .3-35Importing Security Definition Tables . . . . . . . . . . . . . . . . . . . . .3-36

Chapter 4 MaintenanceStarting/Stopping CONTROL-M Tasks . . . . . . . . . . . . . . . . . . . . . . .4-2Periodic Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-3

Checking Available Space in the CONTROL-M Database . . . .4-4Cleaning Up the SQL Database Message Log . . . . . . . . . . . . . .4-4Cleaning Up the Proclog Directory . . . . . . . . . . . . . . . . . . . . . . .4-5

CONTROL-M Menu System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-6CONTROL-M Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-6CONTROL-M Manager Menu . . . . . . . . . . . . . . . . . . . . . . . . . .4-8Database Creation Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-10Database Maintenance Menu . . . . . . . . . . . . . . . . . . . . . . . . . . .4-12Database Mirroring Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-27Security Authorization Menu . . . . . . . . . . . . . . . . . . . . . . . . . . .4-29Parameter Customization Menu . . . . . . . . . . . . . . . . . . . . . . . . .4-30Node Group Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-36Agent Status Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-38Troubleshooting Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40

Chapter 5 Customization ParametersParameter Coordination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-2

Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-3System Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-3Communication Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-9Operational Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-11Parameters for Communicating With Agent Platforms . . . . . . . .5-13Database Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-15Mirroring Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-20Performance Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-21Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-22


Contents xi

Chapter 6 User ExitsConfiguring CONTROL-M Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3User Exit Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4Job Order Exit (CTMUE101) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5Job Submission Exit (CTMUE102) . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7Before New Day Procedure Exit (CTMUE103) . . . . . . . . . . . . . . . . 6-9After New Day Procedure Exit (CTMUE104) . . . . . . . . . . . . . . . . . 6-10Before User Daily Exit (CTMUE105) . . . . . . . . . . . . . . . . . . . . . . . 6-11After User Daily Exit (CTMUE106) . . . . . . . . . . . . . . . . . . . . . . . . . 6-11

Chapter 7 Mirroring and FailoverFailover Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1Failover Administration Procedures . . . . . . . . . . . . . . . . . . . . . . 7-13Synchronizing the Primary and Mirror Databases . . . . . . . . . . . 7-35

Appendix A Messages and CodesMessages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2

Appendix B Structure of CONTROL-M Log Entries

Glossary

Index


xii CONTROL-M/Server for Unix Administrator Guide


Figures xiii

Figures

Figures

Figure 1-1 New Day Procedure and User Daily Jobs . . . . . . . . . . . . . . . . . . 1-16Figure 1-2 Directing Shouts Via the Active Shout Destination Table . . . . . 1-25Figure 2-1 ON_FILEWATCH Statements . . . . . . . . . . . . . . . . . . . . . . . . . . 2-71Figure 2-2 ctmordck Sample Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-95Figure 2-3 ctmpsm – Production Support Menu . . . . . . . . . . . . . . . . . . . . . 2-106Figure 2-4 ctmpsm - Active Jobs File Menu Options . . . . . . . . . . . . . . . . . . 2-108Figure 2-5 List of Scheduling Tables output by the ctmpsm utility . . . . . . . 2-111Figure 2-6 List of Jobs output by the ctmpsm utility . . . . . . . . . . . . . . . . . . 2-113Figure 2-7 CONTROL-M System Parameters (Page 1) . . . . . . . . . . . . . . . . 2-143Figure 2-8 CONTROL-M System Parameters (Page 2) . . . . . . . . . . . . . . . . 2-144Figure 3-1 Security Maintenance Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13Figure 3-2 User Maintenance Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14Figure 3-3 Group Maintenance Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18Figure 3-4 Scheduling Table Authorization Menu . . . . . . . . . . . . . . . . . . . . 3-22Figure 3-5 Active Jobs File Authorization Menu . . . . . . . . . . . . . . . . . . . . . 3-25Figure 3-6 Entities Authorizations Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29Figure 4-1 CONTROL-M Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6Figure 4-2 CONTROL-M Manager Menu . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8Figure 4-3 Database Creation Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10Figure 4-4 Database Maintenance Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13Figure 4-5 Database Mirroring Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27Figure 4-6 Security Authorization Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-29Figure 4-7 Parameter Customization Menu . . . . . . . . . . . . . . . . . . . . . . . . . 4-31Figure 4-8 Communication Parameters Menu . . . . . . . . . . . . . . . . . . . . . . . 4-32Figure 4-9 Operational Parameters Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32Figure 4-10 Communication Parameters for Agent Platforms . . . . . . . . . . . . 4-35Figure 4-11 Communication Parameters for Specific Agent Platforms . . . . . 4-36Figure 4-12 Node Group Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-37


xiv CONTROL-M/Server for Unix Administrator Guide

Figure 4-13 Agent Status Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-38Figure 4-14 Troubleshooting Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40Figure 4-15 Troubleshooting Report Information . . . . . . . . . . . . . . . . . . . . . .4-45Figure 7-1 Database Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2Figure 7-2 Server Platform Failover - Primary Environment and Mirror

Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-9Figure 7-3 Mirroring Parameters for Database Copying - Sybase . . . . . . . .7-17Figure 7-4 Mirroring Parameters for Database Build/Rebuild - Sybase . . . .7-18Figure 7-5 Mirroring Parameters for Database Copying - Oracle . . . . . . . .7-21Figure 7-6 Mirroring Parameters for Database Build/Rebuild - Oracle . . . .7-21


Tables xv

Tables

Tables

Table 1-1 Communication Statuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7Table 1-2 Options for Issuing a Job Order Manually. . . . . . . . . . . . . . . . . 1-24Table 1-3 Shout Message Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-27Table 1-4 Heartbeat Monitor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-37Table 1-5 Heartbeat Monitor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 1-38Table 1-6 Advanced Problem Detection Tools . . . . . . . . . . . . . . . . . . . . . 1-39Table 1-7 Event Logger Severity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-40Table 1-8 Managing Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-42Table 1-9 General Watchdog Facility Parameters . . . . . . . . . . . . . . . . . . . 1-44Table 1-10 Heartbeat Monitor Exit Parameters . . . . . . . . . . . . . . . . . . . . . . 1-45Table 1-11 Parameters for Watchdog System User Exits . . . . . . . . . . . . . . 1-46Table 1-12 Parameters for Watchdog Facility User Exits . . . . . . . . . . . . . . 1-47Table 1-13 Watchdog Facility Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-48Table 1-14 Processing Overhead for Job Processing Features. . . . . . . . . . . 1-50Table 2-1 CONTROL-M Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Table 2-2 CONTROL-M Utility Reference . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Table 2-3 Utility Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6Table 2-4 Required Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . 2-9Table 2-5 Shared Library Path for Sybase Variables . . . . . . . . . . . . . . . . . 2-10Table 2-6 Shared Library Path for Oracle Variables . . . . . . . . . . . . . . . . . 2-10Table 2-7 Read/Write Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14Table 2-8 ctm_agstat Utility Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15Table 2-9 ctmcontb – Listing Prerequisite Conditions. . . . . . . . . . . . . . . . 2-21Table 2-10 ctmcontb – Adding Prerequisite Conditions . . . . . . . . . . . . . . . 2-22Table 2-11 ctmcontb – Deleting Prerequisite Conditions . . . . . . . . . . . . . . 2-22Table 2-12 ctmcontb – Deleting Conditions in a Date Range . . . . . . . . . . . 2-23Table 2-13 Parameter Name Cross Reference . . . . . . . . . . . . . . . . . . . . . . . . 2-27Table 2-14 SAP Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-33


xvi CONTROL-M/Server for Unix Administrator Guide

Table 2-15 Oracle Applications Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 2-34Table 2-16 ctmdbcheck – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-40Table 2-17 ctmdbcheck – Displayed Fields for Sybase . . . . . . . . . . . . . . . . 2-40Table 2-18 ctmdbcheck – Displayed Fields for Oracle . . . . . . . . . . . . . . . . 2-41Table 2-19 ctmdefine – Parameter Name Cross Reference . . . . . . . . . . . . . .2-50Table 2-20 SAP Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-58Table 2-21 Oracle Applications Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 2-59Table 2-22 ctmdiskspace – Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-62Table 2-23 ctmexdef – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-64Table 2-24 ctmfw – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-68Table 2-25 ctmfw – Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-69Table 2-26 ON_FILEWATCH Statements – Additional Parameters . . . . . . 2-70Table 2-27 ctmfw – Valid Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-71Table 2-28 cmtgrpdef – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-76Table 2-29 ctmjsa – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-78Table 2-30 ctmkilljob – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-81Table 2-31 ctmldnrs – Creating a Manual Conditions File. . . . . . . . . . . . . . 2-84Table 2-32 ctmldnrs – Listing or Loading Manual Conditions . . . . . . . . . . 2-85Table 2-33 ctmloadset Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-87Table 2-34 ctmlog – Valid Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-91Table 2-35 ctmlog – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-92Table 2-36 ctmordck – Output Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-94Table 2-37 ctmordck – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-95Table 2-38 ctmorder – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-97Table 2-39 ctmping – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-103Table 2-40 ctmpsm - Menu Options for Active Jobs File . . . . . . . . . . . . . . .2-107Table 2-41 ctmpsm - Active Jobs File Actions. . . . . . . . . . . . . . . . . . . . . . . .2-109Table 2-42 ctmpsm - Menu Options for the Resource Table . . . . . . . . . . . . .2-110Table 2-43 ctmpsm - Menu Options for Scheduling Functions . . . . . . . . . . .2-110Table 2-44 ctmpsm - Options for Scheduling Functions . . . . . . . . . . . . . . . .2-111Table 2-45 ctmpsm - Options in the Scheduling Table List Jobs Menu. . . . .2-113Table 2-46 ctmpsm - Mode Descriptions and Syntax. . . . . . . . . . . . . . . . . . .2-115Table 2-47 ctmrpln – Report Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-120Table 2-48 ctmrpln – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-121Table 2-49 ctmruninf – Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-124Table 2-50 ctmshout – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-127Table 2-51 ctmstats – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-130Table 2-52 ctmstvar – Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-133Table 2-53 cmtsuspend – Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-134Table 2-54 Fields of the Shout Destination Table . . . . . . . . . . . . . . . . . . . . 2-138


Tables xvii

Table 2-55 ctmudchk – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-145Table 2-56 ctmudlst – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-147Table 2-57 ctmvar – Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-151Table 2-58 Fields of SNMP Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-155Table 2-59 ctm2snmp – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-155Table 2-60 ecaqrtab – Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-158Table 2-61 ecaqrtab – Resource Status Fields . . . . . . . . . . . . . . . . . . . . . . . 2-159Table 3-1 Security Levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Table 3-2 Scheduling Table Authorization . . . . . . . . . . . . . . . . . . . . . . . . 3-4Table 3-3 Active Jobs File Authorization . . . . . . . . . . . . . . . . . . . . . . . . . 3-5Table 3-4 Entities Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Table 3-5 Authorization – job submission from a User Daily job . . . . . . . 3-9Table 3-6 Authorization – job submission from the New Day procedure . 3-9Table 3-7 Authorization – Order/Force a Scheduling Table from

ENTERPRISE/CS 3-9Table 3-8 Authorization – Ordering/Forcing a job from ENTERPRISE/CS 3-10Table 3-9 Authorization – Do Forcejob . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10Table 3-10 Authorization – Actions on a Job in the Active network. . . . . . 3-10Table 4-1 CONTROL-M Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7Table 4-2 Options of the CONTROL-M Manager Menu . . . . . . . . . . . . . 4-9Table 4-3 Options of the Database Creation Menu . . . . . . . . . . . . . . . . . . 4-10Table 4-4 Logical Device Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20Table 4-5 Menu Options for Modifying Database Size . . . . . . . . . . . . . . . 4-21Table 4-6 Options of the Database Mirroring Menu . . . . . . . . . . . . . . . . . 4-27Table 4-7 Security Authorization Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . 4-29Table 4-8 Customization Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-31Table 4-9 Options of the Node Group Menu . . . . . . . . . . . . . . . . . . . . . . . 4-37Table 4-10 Options of the Agent Status Menu. . . . . . . . . . . . . . . . . . . . . . . 4-39Table 4-11 Options of the Troubleshooting Menu . . . . . . . . . . . . . . . . . . . . . 4-40Table 4-12 Two-Letter Codes for CONTROL-M Processes . . . . . . . . . . . . 4-43Table 4-13 Diagnostic Level Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-44Table 4-14 Columns of the Show Process Flags Table . . . . . . . . . . . . . . . . 4-47Table 4-15 CONTROL-M/Server Shut Down . . . . . . . . . . . . . . . . . . . . . . . 4-49Table 4-16 Sleep Time Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-50Table 5-1 Parameter Coordination With ENTERPRISE/CS . . . . . . . . . . . . 5-2Table 5-2 Parameter Coordination With Agent Platforms . . . . . . . . . . . . . . 5-2Table 5-3 System Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Table 5-4 Communication Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9Table 5-5 Operational Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12Table 5-6 Parameters for Communicating with Agent Platforms . . . . . . . 5-14


xviii CONTROL-M/Server for Unix Administrator Guide

Table 5-7 Sybase Database Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15Table 5-8 Oracle Database Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18Table 5-9 Mirroring Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20Table 5-10 Performance Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22Table 5-11 CONTROL-M/Server Parameters . . . . . . . . . . . . . . . . . . . . . . . 5-23Table 5-12 Performance Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26Table 5-13 Communication Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26Table 5-14 ENTERPRISE/CS Communication Parameters. . . . . . . . . . . . . 5-27Table 5-15 User Exit Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27Table 5-16 CONTROL-M Server and Agent Parameters. . . . . . . . . . . . . . . 5-28Table 5-17 CONTROL-M/Agent Parameters. . . . . . . . . . . . . . . . . . . . . . . . 5-28Table 5-18 General Watchdog Process Parameters . . . . . . . . . . . . . . . . . . . 5-31Table 5-19 Watchdog Parameters for CONTROL-M System Exits. . . . . . . 5-32Table 5-20 Watchdog Parameters User Exit . . . . . . . . . . . . . . . . . . . . . . . . . 5-34Table 6-1 CONTROL-M General User Exits . . . . . . . . . . . . . . . . . . . . . . . 6-2Table 6-2 Exit Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .6-3Table 7-1 Database Mirroring Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3Table 7-2 Server Failover Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11Table 7-3 Database Mirroring Menu Options. . . . . . . . . . . . . . . . . . . . . . . 7-14Table 7-4 Sybase Mirroring Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-19Table 7-5 Oracle Mirroring Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-22Table 7-6 Utilities Affecting the Primary Database . . . . . . . . . . . . . . . . . . .7-36Table A-1 Message Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1Table B-1 Fields of the CONTROL-M Log . . . . . . . . . . . . . . . . . . . . . . . . B-1


xix

About . . .

About This Book

This book describes how to install, customize and maintain CONTROL-M/Server on a Unix platform. The following Unix operating systems are currently supported:

• Solaris 2.6, 2.7, and 2.8

• AIX 4.3.2, and 4.3.3 with 64-bit support

• HP-UX 9000 10.2 (Sybase only), 11.0 and 11i with 64-bit support

• Digital Unix (OSF) 4.0f with 64-bit support, and 5.0a, 5.0b and 5.1

CONTROL-M/Server is packaged with Sybase SQL Server 11.9.2.4 and Oracle 8.1.6. This guide describes concepts relating to CONTROL-M administration, and provides details regarding parameters and utilities that the administrator will utilize in fulfilling his/her function.


xx CONTROL-M/Server for Unix Administrator Guide

This book is comprised of the following chapters:

Chapter 1 OverviewIntroduces key features and concepts of CONTROL-M.

Chapter 2 UtilitiesProvides a detailed description of CONTROL-M utilities. Operating instructions and examples are included for each utility.

Chapter 3 SecurityDiscusses security concepts of CONTROL-M and ENTERPRISE/CS. Provides instructions for the security utility included with CONTROL-M.

Chapter 4 MaintenanceDescribes how to perform various functions related to startup/shutdown of CONTROL-M/Server, maintenance of the CONTROL-M database, setting CONTROL-M parameters and troubleshooting.

Chapter 5 Customization ParametersDescribes parameters used to customize and configure the CONTROL-M/Server installation.

Chapter 6 User ExitsDescribes user-defined procedures that can be used to modify certain information before it is processed.

Chapter 7 Mirroring and FailoverDescribes how to implement a Mirror (backup) environment for CONTROL-M/Server and the CONTROL-M database.

Appendix A Messages and Codes

Appendix B Structure of CONTROL-M Log Entries

Glossary

Index


xxi

Related Publications

• CONTROL-M/Server for Unix Installation Guide describes installation and configuration of CONTROL-M/Server for Unix.

• CONTROL-M Quick Installation Guide describes a default Unix-based installation of CONTROL-M Business Integrated Scheduling solution. It is intended primarily for trial and proof-of-concept implementations.

• CONTROL-M/Agent Administrator Guides each describe installation and maintenance of CONTROL-M/Agent on a supported platform.

• Enterprise Controlstation User Guide describes ENTERPRISE/CS concepts, features, facilities and operating instructions.

• Enterprise Controlstation Administrator Guide describes administrator responsibilities, customization, maintenance and security of ENTERPRISE/CS.

• Enterprise Controlstation Installation Guide describes how to install and configure ENTERPRISE/CS.

• CONTROL-M/Desktop User Guide describes components used to define and manage CONTROL-M job processing definitions, Scheduling tables, and Calendars in Enterprise Controlstation.


xxii CONTROL-M/Server for Unix Administrator Guide

Notational Conventions

The following abbreviations and terms are used in this guide:

ENTERPRISE/CS = Enterprise Controlstation.

The following table describes conventions used in this guide.

<key> When describing keystrokes, angle brackets are used to enclose the name of a key (e.g., <F1>). When two keys are joined with “+” as in <Shift>+<F1>, hold down <Shift> while pressing <F1>.

Menu => Option This represents an option selection sequence. For example:

Users and Groups=>Groups=>Add

means that you first select Users and Groups from the menu bar; then select the Groups option from the submenu. Finally, select the Add option from the Groups submenu.

{Option A|Option B} The vertical bar is used to separate choices. For example:

{AND|OR}

means that you specify either AND or OR.

[Option] Square brackets are used to enclose parameters that are optional.

<variable> In commands and parameters, angle brackets are used to enclose variable information. For example, the command:cd <controlm_path>

means that you specify cd followed by the path of CONTROL-M.


xxiii

Wildcards or Mask Characters

Certain CONTROL-M utilities and parameters support wild cards. These are also sometimes referred to as mask characters. A mask is a string value containing wild cards.The following wild card characters are supported:

? Indicates any one character.

* Indicates any number of characters.

Note: Values containing mask characters must be enclosed in single or double quotes.


xxiv CONTROL-M/Server for Unix Administrator Guide


Overview 1-1

1

Overview 1

CONTROL-M/Server is a component of CONTROL-M for Business Integrated Scheduling. This family of products handles production control and schedules, submits and tracks jobs across your network. The load-balancing feature of CONTROL-M/Server enables you to attain maximum production throughput by ensuring that each job is submitted on a machine with sufficient resources to execute the job efficiently.

This guide describes concepts and tools required by the administrator to set up and manage CONTROL-M/Server on a Unix platform.

BMC Software’s Business Integrated Solution consists of the following components:

• Enterprise Controlstation This component is the central point of control for production operations. It provides the graphical user interface to the production control and scheduling system. From this workstation (referred to as the ENTERPRISE/CS workstation), you can view the status of jobs in any part of the system. You can issue requests, modify job parameters, and handle exceptions to ensure smooth production job flow.


1-2 CONTROL-M/Server for Unix Administrator Guide

• CONTROL-M Data CenterProduction component of the system. In for versions of CONTROL-M earlier than version 2.2.x, the data center consisted of a single platform which ran the CONTROL-M application in addition to all production jobs. In the current version, the functions of the data center have been distributed among various platforms, each running one of the following CONTROL-M components:

— CONTROL-M/ServerThe central software component of CONTROL-M. CONTROL-M/Server runs on a Unix workstation (referred to as the Server platform). From this location, CONTROL-M/Server exchanges data with ENTERPRISE/CS and with multiple production machines, and maintains the CONTROL-M database.

— CONTROL-M/AgentThis is the component of CONTROL-M that runs on each production machine (referred to as the Agent platform) and which executes job-handling requests received from CONTROL-M/Server. Any number of Agent platforms with different operating systems can be handled by a single Server platform.

CONTROL-M/Agent is also installed on the Server platform. This enables CONTROL-M/Server to utilize the Server platform as an additional production machine.

In the above configuration, each instance of CONTROL-M/Server and its associated CONTROL-M/Agents is viewed by Enterprise Controlstation as a single data center. All processing definitions reside in a database managed by CONTROL-M/Server. The active scheduling environment is also managed by CONTROL-M/Server, including all scheduling logic.

A typical job execution proceeds as follows:


Overview 1-3

1. A job waiting to be submitted “waits” on the Server platform.

2. When all its prerequisite conditions, resource requirements and all other scheduling constraints are satisfied, CONTROL-M/Server instructs CONTROL-M/Agent to submit the job.

3. Upon receiving a request to submit the job, CONTROL-M/Agent submits the job for execution locally according to the job definition.

4. CONTROL-M/Agent monitors the job and reports any exceptional situation to CONTROL-M/Server.

5. Upon completion of the job, CONTROL-M/Agent performs the postprocessing analysis. Job sysout is not transmitted over the network, thus keeping network resource consumption at an absolute minimum.

The CONTROL-M/Agent Administrator Guide describes how to install and manage CONTROL-M/Agent on various Agent platforms.

An overall description of concepts relating to ENTERPRISE/CS and CONTROL-M is provided in the first chapters of the Enterprise Controlstation User Guide. It is highly recommended that you familiarize yourself with the material contained there before proceeding with this guide.

The overview in this chapter includes the following topics:

Topic Description

CONTROL-M Database Contents and functions of the CONTROL-M Database.

Server-Agent Interaction CONTROL-M mechanism for distributed execution of production jobs.

Load Balancing CONTROL-M mechanism for maximizing throughput by automatic selection of the platform to execute jobs, based on workload considerations.



CONTROL-M Database

The CONTROL-M database is the repository of operational data relating to the functioning of the CONTROL-M data center. One database exists for each CONTROL-M data center. The database is maintained by CONTROL-M/Server, using a dedicated or shared SQL server.

The CONTROL-M database contains the following information:

• CONTROL-M log.

Failover Planning Contingency planning for the possibility of failure of the Server platform or CONTROL-M database.

New Day Procedure Daily scheduling and housekeeping procedures which run on the Server platform.

Group Scheduling and Processing

Handling jobs as a group.

Shout Destination Tables Tables used to determine the recipients of Shout messages.

Runtime Statistics Job statistics used for planning and forecasting.

CONTROL-M Log Audit trail of all CONTROL-M events.

Automatic Problem Detection Tools (APDT)

Tools to detect real or potential problems.

Daylight Savings Time Considerations when moving the system clock forward or backward.

CONTROL-M Administrator CONTROL-M administration responsibilities.

Heartbeat Monitor Special monitor which checks the status of TCP/IP communication with ENTERPRISE/CS.

Watchdog Facility Mechanism that automatically monitors CONTROL-M processes and resources.

User Exits Mechanism which enables the user to modify CONTROL-M operations to suit site needs.

Topic Description


Overview 1-5

• Active Jobs file.• Job processing definitions.• CONTROL-M system, communication and operational parameters.• Security authorizations.• Shout Destination tables.• Node groups.• Agent Parameter table.• Status tables for Quantitative resources, Control resources and

prerequisite conditions.

Server-Agent Interaction

CONTROL-M/Agent handles requests from CONTROL-M/Server. A request can consist of:

• Instructions to submit a job on the Agent platform.• Requests for information regarding jobs on the Agent platform that

are currently executing or recently completed.• Requests to view/edit job script statements.• Requests to view job sysout or job documentation.



In addition, CONTROL-M/Agent can perform the following functions as instructed by job processing parameters supplied with the job submission request:

• Handling of job sysout.• Issuing Shout messages.

Each Agent platform requires a “listener” process to accept requests from CONTROL-M/Server. Unix platforms accomplish this using operating system services. On other platforms, CONTROL-M/Agent, as started at boot-time, includes this listener process.

Identification of Agent Platforms

A discovery process must be run for each Agent before CONTROL-M/Server can communicate with it. For more information about the Discovery process, see “Edit Node Group” on page 4-37.

After discovery has been performed, the Agent platform is known to CONTROL-M/Server by its node ID. This is generally the Agent platform’s host name. The job processing definition for each job should include the node ID of the Agent platform on which the job should be submitted by CONTROL-M/Server.

NoteIf load balancing is used, the job processing definition includes a Node group. For more information, see “Load Balancing” on page 1-9.

Communication Status of Agent Platforms

CONTROL-M/Server uses the TCP/IP protocol to communicate with all Agent platforms. CONTROL-M/Server maintains a list of all Agent platforms to which it submits requests and assigns a status to each platform indicating the success or failure of communication with the platform. Valid statuses for Agent platforms are described in Table 1-1.


Overview 1-7

The communication status of Agent platforms can be viewed or modified via the Agent Status menu described in Chapter 4, “Maintenance.”

Depending upon the type of protocol used for communication, certain user-defined communication parameters determine timeouts and the number of retries attempted before the status of an Agent platform is changed. Communication parameters are described in Chapter 5, “Customization Parameters.”

Table 1-1 Communication Statuses

Status Description

Available Communication to the Agent is checked periodically by the ctmping utility. When the ctmping utility detects an Agent, the Agent is assigned the status Available. Communication with the Agent continues to be checked and if the check fails, the Agent‘s status is returned to Unavailable.

Unavailable If an Agent does not successfully complete the discovery process it is assigned a status of Unavailable.This status is also assigned to an agent if communication to the Agent ends with an error.CONTROL-M periodically checks the status of all Agents. When this check is successful for an Agent that is marked Unavailable, the Agent’s status is changed to Available.

Disabled You can manually assign this status to an Agent platform if you want to temporarily prevent CONTROL-M/Server from submitting jobs to that platform. CONTROL-M/Server will not attempt to communicate with a disabled Agent platform until its status is manually changed to Available. When an Agent platform’s status is changed to Disabled, any jobs that were running on the platform at that moment are assigned the status Disappeared.



Interrupted Communication

If communication is interrupted between CONTROL-M/Server and one or more Agent platforms, CONTROL-M/Server sends a special Shout message to ENTERPRISE/CS. All jobs that were running on the affected Agent platform(s) are reclassified in the Active Jobs file as Unknown. The status of the Agent platform is changed to Unavailable.

If processing on the Agent platform was not interrupted, any job submitted to a platform prior to the interruption continues executing.

When communication between CONTROL-M/Server and an Agent platform is restored, CONTROL-M checks the status of any jobs that were running on the Agent platform and updates the status in the Active Jobs file. If a job completed execution during the period of interrupted communication, CONTROL-M/Server retrieves its completion status from the Agent platform.

Time-Related Functions

The time value used for any CONTROL-M function is determined by the system time on the Server platform. This applies to the following:

• The time window in which a job can be submitted (according to the job processing parameters Time From and Time Until).

• Time values recorded for operations in the CONTROL-M log.

Examples

• The time value for SUBMITTED AT recorded for a job in the CONTROL-M log is the time that CONTROL-M/Server issued the job submission request to the Agent platform, not the time that the request was received or the time that the job actually started executing on the platform.

• The time value recorded for ENDED is the time that CONTROL-M/Server received notification that the job completed execution.


Overview 1-9

Authorized CONTROL-M Servers File

CONTROL-M contains a security mechanism to ensure that Agent platforms process only legitimate job-handling requests.

To ensure that an Agent platform does not receive a request from any unintended source, each Agent platform contains a file listing host names of Server platforms that are authorized to issue requests to that platform. A request from any Server platform not listed in this file is rejected by CONTROL-M/Agent on the Agent platform.

The Authorized CONTROL-M Servers file for each Agent platform typically contains the host name of the Server platform to which the Agent platform is assigned and the host name of a backup CONTROL-M/Server platform. For a Windows NT Agent platform, this information resides in the Windows NT registry database.

Agent Configuration Parameters

Each Agent platform has a unique set of configuration parameters. These parameters include specification of directories used by the Agent platform when executing jobs and parameters required by CONTROL-M/Agent for communicating with the Server platform (see “Communication Parameters” on page 5-9).

Load Balancing

Under the Agent Technology implementation of CONTROL-M, you have the additional option of scheduling jobs using the CONTROL-M load-balancing feature. This feature enables you to submit a job to a node group rather than to a specific Agent platform. This node group represents a user-defined list of Agent platforms that are capable of executing a given job. CONTROL-M/Server uses a load-balancing algorithm to determine which of these Agent platforms is best able to handle execution of the job at that moment and submits the job to that node.



This feature enables CONTROL-M to optimize utilization of available resources and ensure maximum production throughput.

The following CONTROL-M facilities are used to administer load balancing on the Server platform.

• The Node Group menu (described in Chapter 4, Maintenance) is used to define which Agent platforms are contained in each node group.

• The ctmloadset utility is used to report utilization of Quantitative resources on an Agent platform by non-CONTROL-M jobs.

• The Quantitative Resources window (in Enterprise Controlstation) is used to view or define Quantitative resources available on the Server platform or Agent platforms.

For an overview of the load balancing facility, refer to “Load Balancing” in the CONTROL-M Concepts chapter of the Enterprise Controlstation User Guide.

Failover Planning

As CONTROL-M is integrated in the production environment of the data center, it becomes increasingly important to ensure that interruptions of CONTROL-M functionality are as short as possible.

A properly designed and executed failover plan ensures that CONTROL-M functions are resumed as soon as possible if a recovery is necessary.

Failover planning for CONTROL-M should provide for the following contingencies:

• Loss of integrity in the CONTROL-M (primary) database due to a failure of the SQL server which maintains the database.


Overview 1-11

• Failure of the platform on which CONTROL-M/Server runs (Server platform).

CONTROL-M provides two levels of failover protection, which address these two scenarios: database mirroring and server platform failover.

CONTROL-M Database Mirroring

Failover protection for the CONTROL-M database is provided using database mirroring. In addition to the primary database installed on the CONTROL-M platform, a backup database is defined on another SQL server. All database updates from CONTROL-M are sent simultaneously to both instances of the SQL database, each on its own server.

If the CONTROL-M primary database loses integrity, CONTROL-M can continue to function using the secondary database. The primary database is later restored from the secondary database.

Server Platform Failover

To handle an irrecoverable hardware or software failure on the CONTROL-M/Server platform, failover capability can be provided by preparing a backup installation of CONTROL-M/Server on a separate workstation. This backup installation, or “mirror environment,” contains a constantly updated mirrored database, and is connected to the same agent platforms and ENTERPRISE/CS workstations as the primary environment.

If the primary CONTROL-M installation fails, the mirror environment’s CONTROL-M installation and its mirrored database are activated. The backup CONTROL-M installation maintains communications with Agents and ENTERPRISE/CS workstations. This ensures that active jobs continue despite failure of the primary CONTROL-M platform.



Host Identification in the Agent Platform

Each Agent platform has a unique set of configuration data. This data includes the following items:

• CONTROL-M/Server Host NameThis is the host interface name of the Server platform currently issuing job-handling requests to the platform.

• Authorized CONTROL-M Servers FileThis file contains a list of the host names of Server platforms that are authorized to issue job-handling requests to the platform. The current Server platform host name appears in this list.

Each job submission or job tracking request from CONTROL-M/Server contains the host name of the Server platform.

The CONTROL-M/Server Host Name is retained by the Agent platform as a part of CONTROL-M’s failover mechanism. If the Agent platform detects that the host name accompanying a request does not match the current host name in the Agent Configuration file, CONTROL-M/Agent performs the following actions:

• CONTROL-M/Agent verifies that the new host name (contained in the request) is listed in the Authorized CONTROL-M Servers file. If the host name does not appear in the list, CONTROL-M/Agent rejects the request.

• If the new host name appears in the list, CONTROL-M/Agent automatically modifies the current host name in the Agent Configuration file and processes the request. This situation indicates that a failover has occurred.

This mechanism enables a backup Server platform to take over job submission and tracking functions in the event a failure occurs in the primary Server platform. Its purpose is to prevent an Agent platform from receiving job-handling requests from two or more Server platforms concurrently. It is the administrator’s responsibility to ensure that CONTROL-M/Server is not running simultaneously in the primary and backup Server platforms.


Overview 1-13

New Day Procedure

CONTROL-M processes execute as background processes on the Server platform and remain active at all times. Once a day, at the time specified by the CONTROL-M system parameter Day Time (starting time of working day), CONTROL-M starts the New Day procedure (formerly known as the “General Daily procedure”).

The New Day procedure performs automatic functions that start a new day under CONTROL-M. This procedure is used as a master scheduler for all CONTROL-M activities.

In this overview, Scheduling tables refers to both regular Scheduling tables and Group Scheduling tables.

The New Day procedure performs the following sequence of operations:

1. A new Odate (CONTROL-M date) is calculated (based on the system date and CONTROL-M system parameter Day Time).

NoteOdate is the scheduling date assigned to a job when the job is ordered. See “Date Definition Concepts” in Chapter 2 of the Enterprise Controlstation User Guide for more information regarding this date.

2. The message FORMATTING AJF is displayed in the ENTERPRISE/CS Communication Status window for the data center.

3. A selective cleanup of the Active Jobs file is performed. Jobs that have already executed and ended OK, and jobs whose parameter Max Wait has been exceeded (and are not Held), are erased from the Active Jobs file.

NoteA job for which the Max Wait parameter is specified that ends with a status of NOTOK is not deleted from the Active Jobs file until the Max Wait parameter is exceeded.



4. A selective cleanup of prerequisite conditions is performed. Prerequisite conditions are deleted if their date reference (month and day) is equal to the new CONTROL-M date. This prevents jobs from being triggered by prerequisite conditions remaining from the previous year.

You can partially or completely disable cleanup of prerequisite conditions by using the CONTROL-M system parameter Ignore New Day Conditions.

5. A partial cleanup of the statistics in the CONTROL-M database is performed. For each job, CONTROL-M retains statistical information regarding the last 20 successful executions. This value can be changed by defining the RUNINF_PURGE_LIMIT in the CONTROL-M config.dat file. CONTROL-M must be shut down and restarted for this change to take effect.

6. A partial cleanup of the CONTROL-M log is performed, based on system parameter Maximum Days Retained By CONTROL-M Log. This parameter specifies the maximum number of days that entries are retained in the CONTROL-M log before being deleted by the cleanup procedure.

7. A partial cleanup of job sysout directories on Agent platforms is performed, based on system parameter Maximum Days to Retain Sysout Files. This parameter specifies the maximum number of days that job sysout files are retained in the sysout directory before being deleted by the cleanup procedure.

8. Job orders are placed in the Active Jobs file according to job processing parameters contained in Scheduling tables (assigned to User Daily “SYSTEM”). These job orders can include the submission of User Daily jobs (see “User Daily Jobs” on page 1-18).

9. The end of a daily run is marked by updating the parameter UDLAST in the Date Control record of User Daily “SYSTEM”. This parameter represents the last date on which the New Day procedure ordered jobs.


Overview 1-15

10. CONTROL-M begins downloading the new Active Jobs file to the ENTERPRISE/CS workstation.

NoteSee “Date Control Record (UDLAST)” on page 1-21 for a description of UDLAST and the Date Control record.

Scheduling Jobs

The New Day procedure is the master scheduler for production jobs. It orders production jobs according to their job processing definitions, and can also order User Daily jobs that, in turn, order regular production jobs.

In a site with a relatively small number of production jobs, the simplest and most straightforward method of scheduling jobs is to order them directly via the New Day procedure.

It is preferable to order jobs using User Daily jobs if two or more of the following conditions exist:

• There are a large number of jobs.• Jobs can be clearly divided into separate categories.• Different jobs are managed by different people.

User Daily jobs can be defined according to function (e.g., by department, project or factory).

The New Day procedure scans the Scheduling tables assigned to User Daily “SYSTEM” and places relevant job orders in the Active Jobs file. Some of these jobs may be regular production jobs, and some may be User Daily jobs.

Each User Daily job is submitted and monitored by CONTROL-M and will, in turn, place job orders in the Active Jobs file.

Figure 1-1 demonstrates how the association of Scheduling tables and User Daily jobs affects the scheduling of jobs under CONTROL-M:



Figure 1-1 New Day Procedure and User Daily Jobs

1. As part of its daily routine, CONTROL-M activates the New Day procedure.

2. The New Day procedure scans the CONTROL-M database for all Scheduling tables assigned to User Daily “SYSTEM” (in this example, UDAILIES and TABLE1). These Scheduling tables can consist of regular production jobs and/or User Daily jobs. In this example, UDAILIES consists of User Daily jobs and TABLE1 consists of production jobs.

3. The New Day procedure places the relevant job orders in the Active Jobs file.

PAYABLES

PAYABLES

RECEIVABLES

INVENTORY

INVENTORY

Active Jobs File

CONTROL-MMonitor

SYSTEM

SYSTEM

UDAILY1

UDAILY1

UDAILY2

RECEIVABLES

UDAILIES

TABLE1

PAYABLES

INVENTORY

SchedulingTable Name

CONTROL-MDatabase

UDAILIES

UDAILIES

TABLE1

UDAILY1

UDAILY2

1

4

5

6

2

3

DailyUser

PROD_JOB3

PROD_JOB4

PROD_JOB5

PROD_JOB6

PROD_JOB7

UDAILY1

UDAILY2

SchedulingTable Name Job

PROD_JOB1

TABLE1 PROD_JOB2

New DayProcedure


Overview 1-17

4. As part of its regular processing of ordered jobs, CONTROL-M scans the Active Jobs file for jobs to submit.

5. Upon determining that all requirements for User Daily jobs UDAILY1 and UDAILY2 have been met, the CONTROL-M submits them for execution.

6. The User Daily jobs then order the corresponding tables (PAYABLES, RECEIVABLES, INVENTORY). The jobs in these tables are added to the Active Jobs file if their scheduling criteria are satisfied. All ordered jobs are submitted for execution when their submission criteria are satisfied.

Group Scheduling tables are ordered only if the scheduling criteria of at least one Schedule Tag in the table is satisfied. Individual jobs in each Group Scheduling table will be ordered or not, depending on the value of the Relationship parameter and on values specified for job-specific basic scheduling parameters.

NoteA Group Scheduling table is ordered as a separate entity, and can be ordered even if no jobs in the table are ordered. If this happens, the final status of the group is set to OK, and post-processing for the group is performed. (That is, setting prerequisite Out Conditions, Shouts and ON_GROUP_END OK actions.)

Each User Daily job scans all the Scheduling tables assigned to it in the CONTROL-M database, and orders the jobs based on their Scheduling criteria, the date in the computer, and the Date Control record (see “User Daily Jobs” in this chapter). For jobs in a Group Scheduling table, the User Daily job also orders jobs according to Scheduling criteria of the Schedule Tags in the Group Scheduling table. Each User Daily job scans a different set of Scheduling tables and uses a different Date Control record (see “Date Control Record (UDLAST)” on page 1-21).

Many variations of the method described can be used. For example, additional User Daily jobs can be defined, each one executing at a specific time.



User Daily Jobs

For large installations, User Daily jobs are the most suitable mechanism for adding new job orders under CONTROL-M.

A User Daily job is actually no different from any other regular job handled by CONTROL-M. The User Daily job is defined via the ENTERPRISE/CS Graphical User Interface, using the same procedure and the same job processing parameters as any other job. User Daily jobs run on the Server platform.

NoteUser Daily jobs require CONTROL-M/Agent to be installed on the Server platform.

A User Daily job must include in its script file (specified by its Mem Name job parameter) the command to run the ctmudly utility. The ctmudly utility accepts a parameter containing the name of a specific User Daily job, and it orders Scheduling tables associated with that User Daily job. (The name of the User Daily job can be stated explicitly in the script file or it can be specified using AutoEdit Assignment statements.)

Each User Daily job scans the Scheduling tables assigned to it to determine which jobs are potential job orders for this specific date. An ordered job will not necessarily be executed by CONTROL-M (e.g., a job is not executed if its prerequisite conditions are not met or if resources required for the job are not available).

When a User Daily job determines that a specific job should be ordered, it places the job order in the Active Jobs file.

The normal sequence of actions performed by a User Daily job is as follows:


Overview 1-19

1. If no Scheduling tables are assigned to the User Daily, an error is generated and the User Daily job exits. Otherwise, the User Daily job continues with the next step.

2. The date UDLAST of the User Daily Date Control record is compared with Odate.

• If UDLAST is earlier than Odate, the program updates the starting date of this User Daily job and continues executing.

• If UDLAST is later than or equal to Odate, the program writes a message to the CONTROL-M log and terminates without performing any further operations.

3. Each of the Scheduling tables assigned to the User Daily job is scanned, and relevant job orders are placed in the Active Jobs file.

4. The successful completion of the User Daily job run is marked by updating UDLAST on the Date Control record with the current value of Odate.

NoteIt is recommended that User Daily jobs be scheduled to run sequentially, not concurrently. This can be accomplished using the standard scheduling parameters in job processing definitions (e.g., assign the same Control resource in exclusive mode to all the User Daily jobs, and sequence the jobs for execution in a specific order using the priority mechanism).

Example

Assume that a set of jobs is defined in a Scheduling table named ACCOUNTING assigned to User Daily UDAILY1. Another set of jobs is defined in a Group Scheduling table named ACCGROUP.

The job processing definition below describes a job that could be used to order the ACCOUNTING Scheduling table and the ACCGROUP Group Scheduling table. This type of job is referred to as a User Daily job.



You can manually order the User Daily job ACCUDAILY1 whenever you want to order the jobs in the ACCOUNTING Scheduling table and the jobs in the ACCGROUP Group Scheduling table, or you can assign Scheduling table ACCTDAILY to User Daily name SYSTEM, in which case ACCUDAILY1 is ordered by the New Day procedure.

When ACCUDAILY1 submits the script file with the parameter $1 set to UDAILY1, the command actually executed by the script is:

ctmudly UDAILY1

This causes all Scheduling tables assigned to UDAILY1 to be ordered (including Scheduling table ACCOUNTING and Group Scheduling table ACCGROUP referred to above).

The script file UDAILY can also be used by other User Daily jobs. In each job processing definition, assign the appropriate User Daily name to the AutoEdit variable %%PARM1.

Job Processing Parameters Script File

Job Name ACCUDAILY1 Script file udaily (referred to by the Job Processing parameter Mem Name) contains the following line:ctmudly $1The ctmudly utility used in this file is described in Chapter 2, “Utilities.”

Application USER_DAILIES

Task Type Job

Description Accounting User Daily

Scheduling Table ACCTDAILY

Author michelle

Owner bill

Mem Name udaily

Mem Lib /usr/bill/bin

AutoEdit Assignments

%%PARM1 = UDAILY1


Overview 1-21

Date Control Record (UDLAST)

User Daily jobs are used to place job orders in the Active Jobs file. Each User Daily job usually runs once a day, scanning one or more user Scheduling tables. As with any regular job, the User Daily job is ordered according to its defined Scheduling criteria. This means that the User Daily job is date-dependent. As a result, certain special situations must be taken into account.

For example:

• The computer has not been working for a day or more (e.g., weekend, holidays or hardware failure).

• The user wants to run a job or a group of jobs with an Odate (original scheduling date) that is prior to the current working date.

Each User Daily job has its own Date Control record, enabling the User Daily job to maintain control over its last running date. The last running date of the User Daily job is recorded in the Date Control record in a field called UDLAST. The Date Control record is analyzed to determine the current running date, the last running date, and possible error situations.

The ctmudlst utility can be used to change the UDLAST field in the Date Control record. Changing this date field affects the scheduling of jobs as described below.

Use of the Date Control Record by User Daily Jobs

When a User Daily is run, UDLAST (the last running date of the User Daily job, recorded in the Date Control record) is compared to Odate (the current installation working date).

• If UDLAST is earlier than Odate (the normal situation), UDLAST is updated automatically to the current installation working date. This date is then used by the User Daily job as the current scheduling date.



• If UDLAST and Odate are equal, it means that the User Daily job has already run today. In that case, a message is issued to the CONTROL-M log, and the User Daily job does not order any jobs.

• If UDLAST is later than Odate, an exceptional situation has occurred. The User Daily job writes a message to the CONTROL-M log and stops executing. You can use the ctmudlst utility, if required, to modify UDLAST.

• If, for any reason (e.g., hardware problems), the New Day procedure did not run for one or more days, it is not necessary to run it for days missed. However, production jobs (including User Daily jobs) whose job processing definition includes the parameter Retro will be ordered automatically for all the dates on which they were supposed to be ordered. Retroactive ordering of jobs is performed according to each job’s scheduling criteria.

For example, if the computer did not operate from the 20th to the 23rd, then a job which was originally scheduled to run on the 20th will not have run on that day. When it is finally run on the 24th, the New Day procedure determines whether or not its associated jobs should be retroactively scheduled to run using the logical date of the 20th. For additional information, refer to the Retro parameter in Chapter 5, Job Processing Parameters, of the Enterprise Controlstation User Guide.

NoteThere is no need to specify the Retro parameter in the job processing definition of a User Daily job which is scheduled to run on a daily basis. In the event that production days are missed (as described above), one execution of the User Daily job will order retroactively all jobs defined using the Retro parameter.

The Retro parameter can be used in the job processing definition of a User Daily job that is not scheduled to run on a daily basis.


Overview 1-23

Handling of Interruptions During a User Daily Job

CONTROL-M contains provisions for dealing with interruptions during the execution of a User Daily job (i.e., when some of the job orders have already been placed in the Active Jobs file and some have not).

If a User Daily job is interrupted for any reason (e.g., operating system crashes, User Daily job errors or ordering is erroneously stopped for any other reason), the entire daily process (starting from execution of the New Day procedure) can be rerun manually. User Dailies ordered by the first run of the New Day procedure are not reordered. Therefore, If a User Daily other than SYSTEM was interrupted, you must run the ctmudchk utility for that User Daily to order jobs that were not ordered because of the interruption. The ctmudchk utility verifies that a job is not already present in the Active Jobs file before ordering the job.

Issuing a Job Order Manually

Most job orders are handled automatically by the New Day procedure or by User Daily jobs. However, it is sometimes necessary to issue job orders manually (e.g., an ad hoc job) or to issue a job order for a different working date.

The following options are available on the ENTERPRISE/CS workstation for issuing a job order manually:



For more information regarding the use of the Order and Force options, see “Ordering/Forcing Jobs” in the Job Processing Definitions Chapter of the Enterprise Controlstation User Guide.

Shout Destination Tables

The CONTROL-M Shout facility sends messages to specified recipients (e.g., users, terminals, files, CONTROL-M log) based on a destination specified by the parameters Shout and/or Do Shout in a job processing definition.

The Shout Destination table contains a list of logical destinations and the equivalent physical destination of each logical destination.

You can create any number of Shout Destination tables, but only one of them is designated as the active Shout Destination table at any given time. By changing the designation of the active table, you can change the actual recipients of messages sent to specific logical recipients.

Table 1-2 Options for Issuing a Job Order Manually

Option Description

Order Requests that the specified job or Scheduling table be ordered. Each job is placed in the Active Jobs file if its Scheduling criteria are satisfied. Individual jobs in a Group Scheduling table cannot be ordered. However, a Group Scheduling table can be ordered.

Force Forces the specified job or Scheduling table. Each job is placed in the Active Jobs file regardless of its Scheduling criteria.

The Force option can also be used to order jobs in a Group Scheduling table. These jobs can be ordered in any of the following ways:

• As additional jobs in an already ordered instance of the same Group Scheduling table.

• As jobs in a new instance of the Group Scheduling table.• As standalone jobs that are not part of a Group Scheduling

table.


Overview 1-25

Example

Figure 1-2 Directing Shouts Via the Active Shout Destination Table

• The system administrator defined two Shout Destination tables, labeled DAYSHIFT and NIGHTSHIFT. In DAYSHIFT, the logical recipient SYS_MANAGER is equated to user Susan, who is the daytime systems manager. In NIGHTSHIFT, the logical recipient SYS_MANAGER is equated to user Robert, the night-time systems manager.

• When the DAYSHIFT Shout Destination table is active, Shout messages addressed to SYS_MANAGER are sent to Susan’s terminal. At 5 p.m., a job is run which changes the active Shout Destination table to NIGHTSHIFT. From that point forward, Shout messages addressed to SYS_MANAGER are sent to Robert’s terminal.

Shout Destination tables are created and maintained using the ctmsys utility (described in Chapter 2, “Utilities”).

Designation of the active Shout Destination table can be performed using one of the following methods:

• Using the interactive utility ctmsys. In addition to creating and maintaining Shout Destination tables, ctmsys can display the currently-active table and allows you to change the active table by selecting a different table from a list.



• Using utility ctmshtb. This utility accepts the name of the Shout Destination table to make active.

This second method is especially useful. By defining CONTROL-M jobs that execute the ctmshtb utility at specified times, the active Shout Destination table designation can be changed automatically according to the schedule that suits your requirements. ctmshtb is described in Chapter 2, “Utilities.”

The ctmshout utility can also be used to issue a Shout message to an indicated destination. ctmshout is described in Chapter 2, “Utilities.”

Shout Message Destinations

When defining logical and physical destinations in the Shout Destination table (using the ctmsys utility), you are requested to supply the following information for each recipient:


Overview 1-27

Table 1-3 Shout Message Destinations

Logical Name Name used in the Shout or Do Shout parameter to identify the recipient of the Shout message.

Destination Type One-letter code, indicating the type of recipient. Possible values are:

U Destination is the user name of a person logged onto the Server platform. If the user is not logged on when a message is sent, the message is placed in the user’s mail.

M Destination is a user’s mail.

T Destination is a specific terminal or file.

O Destination is the system console.

L Destination is the CONTROL-M log.

E Destination is the Alert window of ENTERPRISE/CS.

P Destination is a program, which performs the Shout operation.

Address Type For Destination Types U, M, T, P or O, a one-letter code indicating the location of the recipient relative to the Server platform. Possible values are:

S Recipient is a user on the Server platform.

A Recipient is located on the Agent platform where the job that caused the Shout message was executed.



NoteAll Shout messages are recorded in the CONTROL-M log. You would select the log as a destination only when you do not wish to send the message to any additional destination.

Runtime Statistics

CONTROL-M includes an option for accumulating and collating runtime statistics for each defined job. These statistics are used for the following purposes:

• The job processing parameter Shout can be specified to issue a message if the execution time required by a job varies from its average runtime by more than a stated interval. This can help highlight possible errors. (The Shout parameter is described in Chapter 5, Job Processing Parameters, of the Enterprise Controlstation User Guide.)

Physical Name A one-letter code indicating the address of the recipient. Possible values are:

U and M The user name of the recipient

T The terminal ID or full path name of a file. If the file exists, the message will be appended to the end of the file

P The full path name of the program to be executed.

The recipient program must accept input in the format:<hostname> <severity> <message>

O, L, and E No physical name is specified, as each of these is a unique destination

Table 1-3 Shout Message Destinations


Overview 1-29

• When a simulation is run using the ENTERPRISE/CS Simulation facility, job statistics are used by the facility to determine how much time to allow for the execution of each job.

• When viewing information regarding a scheduled job (that is, a job in the Active Jobs file) in ENTERPRISE/CS, you are provided with the average runtime and the standard deviation in the Job Details window. In addition, you can view the job statistics recorded in the Statistical Details table by selecting the Statistics option from the Job Node menu.

• The ENTERPRISE/CS display for currently-running jobs includes a real-time graphical indication of the percentage of the runtime remaining for each job, based on the job’s runtime statistics.

CONTROL-M generates runtime statistics by compiling information contained in the Statistical Details table of the CONTROL-M database and storing this information in a summary table. Runtime statistics for a given job are passed to the ENTERPRISE/CS workstation each time that job is ordered.

The compilation and recording of statistical data depends upon the following CONTROL-M components:

• The CONTROL-M system parameter Statistics must be set to Y (the default value). This notifies CONTROL-M that you want statistical data from each successful job execution to be recorded in the Statistical Details table of the CONTROL-M database. System parameters are modified via the ctmsys utility.

• The CONTROL-M operational parameter Statistics Mode indicates the mode used by the ctmjsa utility to collect summary statistics: JOBNAME compiles statistics for each CONTROL-M Job Name and Node ID where the job was submitted; MEMNAME (default) compiles statistics for each CONTROL-M Mem Name/Mem Lib and Node ID. Operational parameters are modified via the Parameter Customization menu in the CONTROL-M Menu system (see Figure 4-9 on page 4-32 and the bulleted item about changing Statistics Mode on page 4-34).



• The CONTROL-M ctmjsa utility is used to compile the data in the Statistical Details table and store the results in a Statistical Summary table in the CONTROL-M database. For additional information, see the description of the ctmjsa utility on page 2-77.

It is recommended that you define a CONTROL-M job to run the ctmjsa utility on a daily basis. This helps to ensure that the CONTROL-M database contains current statistics on all jobs executed under CONTROL-M. A partial cleanup of the Statistical Details table is performed by the New Day procedure. See “New Day Procedure” in this chapter for additional information.

The ctmruninf utility displays and deletes data from the Statistical Details table. The ctmstats utility displays and deletes data from the Statistical Summary table. Both utilities can be filtered according to date and job information. For additional information, see the descriptions of ctmruninf and ctmstats in Chapter 2, “Utilities.”


Overview 1-31

CONTROL-M Log

The CONTROL-M log contains a complete audit trail of every event occurring in the CONTROL-M production environment. CONTROL-M logs every item of meaningful information about its operation and about the jobs under its supervision. Notification of both routine procedures and error occurrences are recorded in the log.

Among the types of entries recorded in the CONTROL-M log are messages regarding the following:

• Operation of the New Day procedure and User Daily jobs.

• Changes in the availability of Control resources, Quantitative resources and prerequisite conditions.

• Job submissions and terminations, reruns, job log (Sysout) handling and Shout performance.

• User actions affecting jobs, whether performed via the ENTERPRISE/CS workstation or via utilities on the Server platform.

• Failures to adhere to security definitions on the Server platform.

• All Shout messages issued by CONTROL-M.

On the ENTERPRISE/CS workstation, CONTROL-M Log entries relating to a specific job displayed in the active network can be viewed using the Log window.

On the Server platform, all CONTROL-M Log entries can be viewed using the CONTROL-M the ctmlog utility (described in Chapter 2, “Utilities” ).



Entries are placed in the CONTROL-M log continually as long as CONTROL-M is active. To prevent the log from becoming too large, the CONTROL-M log is purged once a day by the New Day procedure. The number of days that entries are retained in the CONTROL-M log before deletion is determined by CONTROL-M system parameter Maximum Days Retained by CONTROL-M Log (described in Chapter 5, “Customization Parameters”).

A description of the structure of CONTROL-M log entries can be found in Appendix B, “Structure of CONTROL-M Log Entries.”


Overview 1-33

Daylight Savings Time Considerations

Daylight savings time considerations are described in the following paragraphs. All examples assume 02:00 a.m. as the time of change.

Advancing the Clock Forward

The following examples assume that the clock is moved ahead at 2:00 a.m. (2:00 a.m. becomes 3:00 a.m.). If the computer is capable of changing the clock without restarting the system, do not bring down the CONTROL-M when the clock is being advanced.

New Day Procedure

No special action should be taken once the clock is advanced.

• If the New Day procedure starts before you reset the clock, the New Day procedure will start working before the clock is advanced, and will continue normally (even if the clock is advanced while the New Day procedure is in process). For more information about the New Day procedure, see page 1-13.

• If the New Day procedure is scheduled to begin at exactly 2:00 a.m., the same considerations apply. It is possible that the New Day procedure will start execution before the clock is manually changed. Otherwise, changing the clock will initiate New Day processing.

• If the New Day procedure is scheduled to begin between 2:00 a.m. and 3:00 a.m., after the computer clock is advanced, CONTROL-M will start the normal New Day processing.

• If the New Day procedure is scheduled to begin after 3:00 a.m., no action is required. CONTROL-M will start the standard New Day procedure.



Time-Dependent Shouts

• Shout messages scheduled before 2:00 a.m. do not require any action.

• Shout messages scheduled between 2:00 a.m. and 3:00 a.m. will be issued, even though there may not be a delay in production since the time frame for production is smaller.

• The above also applies to jobs which have shout messages scheduled at a later time (e.g., 6:00 a.m.). These jobs may be considered late because of the tighter production time frame.

Time-Dependent Schedules (FROM UNTIL or Cyclic Jobs)

Jobs whose scheduled time overlaps the time gap created by the clock shift may need manual intervention. For example, it is possible that a job with a FROM value of 2:15 a.m. and an UNTIL value of 2:45 a.m. may not be submitted at all. These jobs should be manually adjusted. A cyclic job may have to be deleted and then resubmitted to continue the processing cycle during the current day.

CONTROL-M Log File

The CONTROL-M Log file will not contain entries with timestamps between 2:00 a.m. and 3:00 a.m. Any scripts and/or programs that rely on log entry time should be checked for possible discrepancies as a result of advancing the clock.

Moving the Clock Backwards

The following examples assume that the clock is moved back at 2:00 a.m. (2:00 a.m. becomes 1:00 a.m.).


Overview 1-35

New Day Procedure

• If the New Day procedure starts before 1:00 am, no special action should be taken. The New Day procedure will run only once (between 00:00 and 00:59).

• If the New Day procedure starts exactly at 1:00 a.m., computer time should not be turned back to 1:00 a.m. to avoid another New Day process. A second New Day procedure requires manual intervention. It is advisable to wait until 2:01 a.m., for example, and turn the clock back to 1:01 a.m.

• If the New Day procedure is scheduled to begin between 1:00 a.m. and 2:00 a.m., do one of the following:

— Wait at least a full hour after the daily run, and then turn the clock back as needed; the New Day procedure will have ended.

— Update the clock before New Day processing begins.

For example, if the New Day time is 1:45 a.m., the clock should be moved back one hour no later than 1:44 a.m. If this was not done by 1:44 a.m., the user should wait until 2:46 a.m. and then shift the time back.

• If the New Day procedure is scheduled to begin after 2:00 a.m., no special action should be taken.

Time-Dependent Shouts

Shout messages scheduled between 1:00 a.m. and 2:00 a.m. may be issued twice.

Time-Dependent Schedules (FROM-UNTIL or Cyclic Jobs)

No special action should be taken for jobs with FROM-UNTIL or cyclic schedules. Jobs scheduled to start between 1:00 a.m. and 2:00 a.m. will start at the first occurrence of the hour (provided that other conditions, such as input conditions and resources are met). However, they can be restarted after the clock is moved back.



CONTROL-M Log File

The CONTROL-M Log file may contain entries with times earlier than previous entries, due to the time shift. The same considerations that apply to advancing the clock forward, should be applied to moving the clock backwards.

CONTROL-M Administrator

The aim of the CONTROL-M administrator is to ensure the smooth and efficient running of CONTROL-M with minimum interruptions and optimal usage of available resources. To achieve this aim, the responsibilities of the CONTROL-M administrator can be summarized as follows:

• Providing appropriate security authorizations to CONTROL-M users via the CONTROL-M Security Maintenance Utility (ctmsec).

• Backing up the CONTROL-M database, CONTROL-M home directory files and CONTROL-M “data” directory on a periodic basis to ensure complete recovery in case of system failure.

• Planning CONTROL-M production schedules.

• Performing troubleshooting functions, such as:

— Performing basic CONTROL-M database maintenance functions (e.g., increasing available space, dumping logs, increasing locks).

— Detecting common system problems by analyzing CONTROL-M logs and APDT logs.

— Detecting database problems by analyzing CONTROL-M database logs.

— Collecting and analyzing debug information.— Checking for enough disk space.— Monitoring the CONTROL-M production system; checking that

the database is not at full capacity; removing old prerequisite conditions.


Overview 1-37

— Cleaning up old and unnecessary log files from the proclog directory.

— Installing all CONTROL-M releases and patches, as needed.

Heartbeat Monitor

CONTROL-M contains an integral Heartbeat monitor that verifies that TCP/IP communication with ENTERPRISE/CS is functional and that ENTERPRISE/CS is responsive to messages from CONTROL-M.

This feature complements the ENTERPRISE/CS Heartbeat monitor that verifies that communication with CONTROL-M is functional and that CONTROL-M is responsive to messages from ENTERPRISE/CS.

The CONTROL-M Heartbeat monitor can operate in either of two modes. These modes are described in Table 1-4.

Table 1-4 Heartbeat Monitor Modes

Mode Description

Active Mode The CONTROL-M Heartbeat monitor periodically sends a “heartbeat check” message through one TCP/IP connection to ENTERPRISE/CS. ENTERPRISE/CS repeats the message through the second TCP/IP connection back to CONTROL-M. If CONTROL-M does not receive a response to a heartbeat check message within a limited time period, CONTROL-M assumes that communication with ENTERPRISE/CS is temporarily interrupted. CONTROL-M then initiates a procedure to restore communication with ENTERPRISE/CS. In addition, CONTROL-M issues a response to heartbeat checks initiated by ENTERPRISE/CS.

Passive Mode CONTROL-M does not initiate heartbeat checks, but CONTROL-M does respond to the heartbeat checks initiated by ENTERPRISE/CS. In this mode, CONTROL-M does not automatically attempt to restore communication with ENTERPRISE/CS if communication is interrupted.



The CONTROL-M Heartbeat monitor uses the following parameters that are contained in file ~controlm/ctm/data/config.dat:

Example

CTM_PRM_KPA_ACTIVE YCTM_PRM_KPA_BETWEEN_MSGS 300CTM_PRM_KPA_ROUNDTRIP_TIMEOUT 300

Advanced Problem Detection Tools

CONTROL-M/Server invokes Advanced Problem Detection Tools to help you maintain software integrity and protect data. Use of these tools enhances system monitoring to help avoid failures and provides multiple methods for safeguarding data. In the event of a system or process crash you may be asked to run one of these tools and submit their output to Technical Support.

In addition to the tools mentioned below, also refer to:

Table 1-5 Heartbeat Monitor Parameters

Parameter Description

CTM_PRM_KPA_ACTIVE

Whether or not the CONTROL-M Heartbeat monitor operates in active (Y) or passive (N) mode. Default: Y.

CTM_PRM_KPA_BETWEEN_MSGS

Amount of time (in seconds) to wait after receiving a response to a heartbeat check before issuing the next heartbeat check. Default: 300 seconds.

CTM_PRM_KPA_ROUNDTRIP_TIMEOUT

Time (in seconds) to wait for a response after issuing a heartbeat check before declaring a communication failure and initiating corrective actions. Default: 300 seconds.


Overview 1-39

• Contingency planning for the possibility of failure of the Server platform or the CONTROL-M database. For more information, see “Failover Planning” on page 1-10.

• Writing diagnostic files when the diagnostic level setting is greater than zero. For more information, see “Set Diagnostics Level” on page 4-43.

Setting Event Logger Parameters

The Event logger records events that occur in CONTROL-M. The following types of events can be recorded:

Table 1-6 Advanced Problem Detection Tools

Tool Description

Event logger Generates log files for events that match the specified severity and category. For more information, see “Setting Event Logger Parameters” on page 1-39.

Log file size monitor Monitor the size of log files. Save files that exceed a specified size to a new version of the file. For more information, see “Managing Log Files” on page 1-41.

Stack trace logger A log of the functions called and the events leading up to a process crash. For more information, see “Stack Trace” on page 1-42.

Watchdog Monitors CONTROL-M processes and resources and sends an alert if a problem is detected. For more information, see“Watchdog Facility” on page 1-44.

ctmdbcheck Checks database integrity, displays information about database memory utilization and automatically monitors database and transaction logs. For more information, see “ctmdbcheck” on page 2-39.

ctmdbtrans Lists active transactions in the database. For more information, see “ctmdbtrans” on page 2-46.

ctmlog Performs selective cleanup of the CONTROL-M log or produces a report of CONTROL-M log entries. For more information, see “ctmlog” on page 2-91.



• IOALOG eventsThese are analogous to ctmlog events and involve reading and writing to the IOA database.

• DBASE eventsThese are associated with database access and involve reading and writing to the CONTROL-M database.

CONTROL-M generates log entries when an event matches the logger parameters specified in the config.dat file relating to severity and category. The keywords in the parameter related to severity refer to the message types that are generated when the category they refer to is matched, for example, informational messages concerning the database are generated when events occur matching parameters that relate to the severity keyword INFO and the category DBASE.

The log entries generated are saved in the following location:

<controlm_home>/ctm/proclog/logger.

NoteIf not manually archived, these log files can occupy a large amount of disk space. Careful selection of events to be logged will prevent unnecessary large log files. For information about how to maintain the log files, see “Managing Log Files” on page 1-41.

To configure the Event logger, insert the following commands in the config.dat file (the text must be entered in uppercase):

CTM_LOGGER_SEVERITY {INFO|WARNING|ERROR}CTM_LOGGER_CATEGORY {IOALOG|DBASE}

Table 1-7 Event Logger Severity

Keyword Description

INFO Informational messages for the specified category.

WARNING Warning messages for the specified category.

ERROR Error messages for the specified category.


Overview 1-41

Example

To record IOALOG events with a severity of WARNING and ERROR, include the following in the config.dat file:

CTM_LOGGER_SEVERITY WARNING ERRORCTM_LOGGER_CATEGORY IOALOG

Managing Log Files

CONTROL-M saves information about its processes, operations, errors and the jobs under its supervision in log files. If not periodically backed up and cleaned, these files can occupy a large amount of disk space.

CONTROL-M/Server provides a mechanism for archiving log files over a specified size and to assign a generation number for each archived log. You can determine the size of the log files and the number of file generations by using the parameters described below. CONTROL-M monitors the size and version of log files utilizing configurable parameters in the <controlm_home>/ctm/data/config.dat file. These parameters specify the required size and number of generations of the log file.

NoteIf no values are specified, no limits are placed on the size of the log file.

If values are specified, the size of the log file is checked and when the limit is reached, the file is renamed logger.1. Entries continue to be saved in the default logger file, and when the file next reaches its limit, the file is renamed logger.2, and so on, until the maximum number of specified generations is reached. The oldest file is deleted when another log file exceeds the limit.

To set size and generation limits, specify the following parameters in the config.dat file:

LIMIT_LOG_FILE_SIZE <file-size>LIMIT_LOG_VERSIONS <number>



Example

To set a limit to the size of the log file to 10 MB and to limit the number of generations of the log file to 3, specify the following parameters in the config.dat file:

LIMIT_LOG_FILE_SIZE 10LIMIT_LOG_VERSIONS 3

Stack Trace

A stack trace is a useful debugging aid in working out how program control reached a specific point. The stack trace is a file containing a record of the events leading up to a process that abends.

CONTROL-M records the progression of the invocations called by functions. If a process crashes, CONTROL-M generates a stack trace sequence of functions that were called, leading up to the unexpected error.

The stack trace is output to a proclog file, providing information about the process that aborted. The log file generated contains information relevant to Technical Support and is located in the directory:

<controlm_path>/ctm/proclog/<process_name>.<proc_ID>

The variables in this command line are described in the following table:

Table 1-8 Managing Log Files

Variable Description

LIMIT_LOG_FILE_SIZE File size, specified in megabytes.

LIMIT_LOG_VERSIONS Number of generations of the log file that should be kept. The valid number must be a positive integer between 1 and 9.


Overview 1-43

Example

controlm/ctm/proclog/CS_LOG.6509

<controlm_path> Home directory of CONTROL-M/Server account owner.

<process-name> Two-character code identifying the process.

<process-ID> ID of the CONTROL-M/Server process.



Watchdog Facility

CONTROL-M contains a special Watchdog (WD) facility which automatically monitors various CONTROL-M processes and resources, essential to the running of CONTROL-M, and sends an appropriate alert when there is a problem. The Watchdog facility can also be used to automatically execute user-defined scripts or CONTROL-M utilities. (See Chapter 2, “Utilities.”)

If a Watchdog facility-monitoring check fails, appropriate error messages can be sent to special error handlers such as CONTROL-O/Server and ENTERPRISE/CS (see below). The Watchdog facility automatically sends these messages to the CONTROL-M IOALOG and PROCLOG.

The Watchdog facility is enabled by configuration parameters defined in the ~controlm/ctm/data/config.dat file. For additional information, see “Configuration Parameters” on page 5-22.

Certain parameters in the config.dat file indicate general information about the Watchdog facility. These parameters are listed in Table 1-9.

• To disable the various Watchdog exits, set their parameters to 0.• To enable the various Watchdog exits specify the values described in

Table 1-9.

Table 1-9 General Watchdog Facility Parameters


WD_CTMEXIT_NUMBER Indicates the number of predefined Watchdog user exits to be enabled. There are two built-in user exits. Valid values are: 0,1 and 2, where:• 0 disables the built-in user exits.• 1 invokes the first built-in user exit.• 2 invokes both built-in user exits.

WD_USEREXIT_NUMBER Indicates the number of Watchdog user exits to be enabled. Specify the number of desired user exits or specify 0 to disable all Watchdog user exits.


Overview 1-45

The following categories of user exits are described in detail below:

• Heartbeat check (see below)• Predefined Watchdog user exits (see below)• Watchdog user exits (see page 1-47)

Heartbeat Check

A special heartbeat check runs automatically when the Watchdog facility is enabled. This checks that all the primary CONTROL-M processes (SU, CO, SL, TR, LG) are functioning. If any of the processes do not respond to the check, a message is sent to the error handlers.

Predefined Watchdog User Exits

The Watchdog facility monitors CONTROL-M processes and resource usage using two built-in CONTROL-M utilities. These utilities are enabled via CONTROL-M System user exit parameters (WD_CTMEXIT_<n>) in the config.dat file. All these exits reside in the ~controlm/ctm/exe_<platform> directory and cannot be changed.

Two predefined built-in system user exits are included in the config.dat file.

• Exit 1Runs a Disk Space utility to check the amount of free disk space on a specified device and sends an error message if it is below a specified amount. See ctmdiskspace in Chapter 2, “Utilities,” for a complete description

Table 1-10 Heartbeat Monitor Exit Parameters


WD_HEARTBEAT_INTERVAL Amount of time (in seconds) to wait after receiving a response to a heartbeat check before issuing the next heartbeat check.

WD_HEARTBEAT_TIMEOUT Time (in seconds) to wait for a response after issuing a heartbeat check before sending a message to the error handlers.



• Exit 2Runs a Database Usage utility to check data and log usage in the CONTROL-M database and sends an error message if it is above a specified percentage. See ctmdbspace in Chapter 2, “Utilities,” for a complete description.

The parameters for these two built-in Watchdog system user exits are described in Table 1-11.

NoteValid values for <n> in the parameters in Table 1-11 are either 1 or 2.

Table 1-11 Parameters for Watchdog System User Exits


WD_CTMEXIT_<n>_CMD_LINE Contains parameters to be passed to the exit script.

WD_CTMEXIT_<n>_ERROR_MSG Indicates the message to be sent if an exit script fails.

WD_CTMEXIT_<n>_INTERVAL Indicates the number of time units during which the exit script should not be invoked. Parameter WD_INTERVAL defines the time units. For more information, see Table 1-13.

WD_CTMEXIT_<n>_RUN_STATE Indicates if the exit script should be run when CONTROL-M is running. Valid values are Y or N.

WD_CTMEXIT_<n>_SCRIPT_FILE File name of the script or binary that resides in the ctm/exe_<platform> directory.

WD_CTMEXIT_<n>_SUSPEND_STATE Indicates if the exit script should be invoked when CONTROL-M is suspended. Valid values are Y or N.

WD_CTMEXIT_<n>_TIMEOUT Time (number of minutes) which should be allowed before the exit script is terminated.


Overview 1-47

Watchdog User Exits

The Watchdog facility can also be used to execute user-defined scripts or CONTROL-M utilities automatically during different intervals of the Watchdog facility. These scripts are enabled using user exit parameters which are specified in the config.dat file. The full path name and arguments for each script or utility are required to add these functions to the Watchdog facility. If the user exit ends with a “failed” status, a specified error message can be sent to the error handlers. For more information, see “Error Handlers” on page 1-48.

Table 1-12 describes all parameters that can be defined for each user exit of the Watchdog facility.

Table 1-12 Parameters for Watchdog Facility User Exits


WD_USEREXIT_<n>_CMD_LINE Contains parameters to be passed to the exit script.

WD_USEREXIT_<n>_ERROR_MSG Indicates the message to be sent if an exit script fails.

WD_USEREXIT_<n>_INTERVAL Indicates the number of time units during which the exit script should not be invoked. Parameter WD_INTERVAL defines the time units. For more information, see Table 1-13.

WD_USEREXIT_<n>_RUN_STATE Indicates if the exit script should be run when CONTROL-M is running. Valid values are Y or N.

WD_USEREXIT_<n>_SCRIPT_FILE Full path of the exit script.

WD_USEREXIT_<n>_SUSPEND_STATE Indicates if the exit script should be invoked when CONTROL-M is suspended. Valid values are Y or N.

WD_USEREXIT_<n>_TIMEOUT Time (number of minutes) which should be allowed before the exit script is terminated.



Example

CONTROL-M utility ctmping can be added to the Watchdog facility to automatically test the communication link between CONTROL-M/Server and Agent platforms and update the available Agent list. Add the following parameters to the config.dat file:

WD_USEREXIT_1_CMD_LINE -file /ctm/ctmuser/agntlistWD_USEREXIT_1_ERROR_MSG Agent not availableWD_USEREXIT_1_INTERVAL 5WD_USEREXIT_1_RUN_STATE YWD_USEREXIT_1_SCRIPT_ FILE $HOME/ctm/exe_AIX/ctmpingWD_USEREXIT_1_SUSPEND_STATE NWD_USEREXIT_1_TIMEOUT 5

Error Handlers

If a Watchdog facility check fails, the error message specified for that check is sent to the defined error handler. Two other error-handling options are available: CONTROL-O/Server and a user defined script. These options are enabled via the parameters in the config.dat file described in Table 1-13.

NoteError messages are automatically sent to the CONTROL-M IOALOG and PROCLOG.

For more information about error handlers, see Chapter 5, “Customization Parameters.”

Table 1-13 Watchdog Facility Parameters


WD_ALIVE_MSG Indicates the message to be sent in response to successful heartbeat checks. Place a ”#” character in front of the parameter in the config.dat file to inhibit the message.

WD_CTO_HOSTNAME Host name or IP Address CONTROL-O/Server.


Overview 1-49

Example

If you specify 5 minutes for parameter WD_INTERVAL and specify 2 time units for parameter WD_CTMEXIT_1_INTERVAL, the Watchdog facility will run the system script for system user exit 1 once every 10 minutes.

WD_CTO_TIMEOUT Maximum time for the Watchdog facility to send messages to CONTROL-O/Server.

WD_ERROR_HANDLER_SCRIPT_FILE Path name of the user-defined script called by the Watchdog facility.

WD_ERROR_HANDLER_TIMEOUT Maximum time for the Watchdog facility to wait for the user defined script to run.

WD_INTERVAL Defines the time unit interval, in minutes, when the next exit must be checked.

Table 1-13 Watchdog Facility Parameters (continued)




User Exits

A user exit is a user-defined procedure that can be used to modify certain information before it is processed. At certain points in processing a flat text file is produced describing information that is to be passed to next step in a procedure. This text file can be modified by a user-defined exit script before it is passed on for processing.

CONTROL-M user exits can be used to enforce site standards (for example, file naming conventions or valid date formats), and to apply security definitions to limit certain user’s actions. Exits can also be used to trigger other actions prior or subsequent to execution of a CONTROL-M job.

For more information, see Chapter 6, “User Exits.”

Processing Overhead

CONTROL-M provides a wide variety of mechanisms that can be used to control job scheduling. When determining which mechanisms to use, it helps to be aware of the different levels of processing overhead that each mechanism requires.

Table 1-14 lists certain basic scheduling features and their relative levels of processing overhead. By choosing the right features for your job processing definitions, you can ensure that your CONTROL-M processes are fast and efficient.

Table 1-14 Processing Overhead for Job Processing Features

FeatureRelative Processing Overhead

Time window (Basic scheduling parameters) Very low

In (prerequisite) conditions Low

Control Resources Medium


Overview 1-51

Quantitative Resources High

Designation of a job as “Critical” Very High

Table 1-14 Processing Overhead for Job Processing Features

FeatureRelative Processing Overhead


Utilities 2-1

2

Utilities 2

General maintenance can be performed using the utilities described in this chapter. Some of these utilities generate reports, which are useful for managing the data center, and for planning job processing definitions and calendars.

NoteMany of these utilities are intended for use only by the CONTROL-M administrator. Because they require extensive authorization in the CONTROL-M database, they may not work if submitted by a regular user.

All utilities described in this chapter are included with CONTROL-M. These utilities are run either from the system prompt or submitted as batch jobs (except where noted).

Utilities that can be submitted as batch jobs can also be defined as CONTROL-M jobs. This enables you to utilize the CONTROL-M job handling features such as automatic scheduling and the use of AutoEdit variables (see examples in this chapter). Refer to “Accessing Utilities From Other Unix Users” in this chapter before using this feature.

NoteRefer to Table 2-2 to determine which subsystems must be active before invoking a CONTROL-M utility.



Table 2-1 lists the available utilities. Detailed information about each utility is provided later in this chapter.

Table 2-1 CONTROL-M Utilities (Part 1 of 3)

Utility Description

ctm_agstat Lists or updates an Agent’s status.

ctm_backup_bcp Exports data from a CONTROL-M database.

ctm_restore_bcp Imports data to a CONTROL-M database.

ctmcontb Performs operations on the Prerequisite Conditions table.

ctmcreate Creates a job in the Active Jobs file.

ctmdbapasswd Changes the database password.

ctmdbbck Backs up the CONTROL-M database.

ctmdbcheck Checks database integrity and displays information about database memory utilization.

ctmdbrst Restores the CONTROL-M database.

ctmdbspace Checks data and log usage in the CONTROL-M database.

ctmdbtrans List the active transactions in the database.

ctmdefine Defines a job in the CONTROL-M database.

ctmdiskspace Checks the amount of free disk space on a device.

ctmexdef Exports job specifications from the job processing Definitions table in the CONTROL-M database to an ASCII file in either ctmcreate or ctmdefine format.

ctmfw Detects the successful completion of a file transfer activity.

ctmgrpdef Creates a definition for a new Group Scheduling table.

ctmjsa Accumulates statistical data and records it in the Statistics Summary table in the CONTROL-M database.

ctmkilljob Terminates a CONTROL-M job and its associated processes.

ctmldnrs Creates and loads the Manual Conditions file.


Utilities 2-3

ctmloadset Updates a resource in the Quantitative Resources table with regard to usage on an Agent platform.

ctmlog Performs a selective cleanup of the CONTROL-M log or produces a report of CONTROL-M log entries, according to user-supplied parameters.

ctmordck Lists a user’s job processing definitions which can be ordered by a specific User Daily job.

ctmorder Orders one or more jobs from a Scheduling table contained in the CONTROL-M database.

ctmpasswd Allows changing CONTROL-M user’s password into the database.

ctmping Collects configuration information aboutCONTROL-M/Agents not in the CONTROL-M database and performs a communication test.

ctmpsm Interactive utility for performing functions affecting jobs or conditions in the Active environment.

ctmrpln Creates a report that lists all or a selection of jobs in a specified Scheduling table, and indicates when the jobs are scheduled to run. The report can be requested for a specific date, month or a five-year period.

ctmruninf Lists and deletes runtime data from the Statistical Details table of the CONTROL-M database.

ctmsec Defines users in the CONTROL-M security database and assigns them authorizations for working with CONTROL-M. For more details, see “Security Maintenance Utility (Interactive Mode)” on page 3-11.

ctmshout Issues a Shout message to an indicated destination.

ctmshtb Sets the active Shout Destination table.

ctmstats Displays or deletes statistical data from the Statistical Summary table in the CONTROL-M database.

ctmstvar Displays the current value of an AutoEdit variable or function.

ctmsuspend Suspends CONTROL-M/Server scheduling processes for mass batch uploads/downloads from ENTERPRISE/CS.


Utility Description



Utility Reference Table

ctmsys Maintains CONTROL-M system parameters and Shout Destination tables.

ctmudchk Allows recovery from interruption of a User Daily.

ctmudlst Enables you to manually set the User Daily last run date.

ctmudly Orders jobs for a specific User Daily name.

ctmvar Manipulates AutoEdit variables for data centers, Group Scheduling tables, or jobs in Group Scheduling tables.

ctmwhy Displays a report stating why a job waiting in the Active Jobs file is not being submitted for execution.

ctm2snmp Sends messages to Network Management applications via SNMP traps.

ecactltb Lists the status of each resource in the Control Resources table.

ecaqrtab Performs operations on the Quantitative Resources table.

Table 2-2 CONTROL-M Utility Reference (Part 1 of 3)

Utility Requires CTM Active

Requires SQL Active

Executable By User Other Than CTM Admin

Executable As Batch Job

Supports AutoEdit Variables

Executable From Agent Platform (Batch Jobs)

ctm_agstat X

ctm_backup_bcp X X

ctm_restore_bcp X X

ctm_restore_aut X X

ctmcontb X X X X X X

ctmcreate X X X X X X

ctmdbapasswd X


Utility Description


Utilities 2-5

ctmdbbck X X

ctmdbrst X X

ctmdbcheck X X X

ctmdbspace X X X

ctmdbtrans X X X

ctmdefine X X X X

ctmdiskspace X X

ctmexdef X X X

ctmfw X X X

ctmgrpdef X X X

ctmjsa X X X

ctmkilljob X X X X

ctmldnrs X X X

ctmloadset X X X X X

ctmlog X X X

ctmordck X X X

ctmorder X X X X

ctmping X X X

ctmpsm X X

ctmrpln X X X

ctmruninf X X

ctmshout X X X X X

ctmshtb X X

ctmstats X X X

ctmstvar X X X X

ctmsuspend X X

ctmsys X X



Requires SQL Active







Reports Generated from Utilities

The following reports can be generated using utilities described in this chapter:

ctmudchk X X X

ctmudlst X X

ctmudly X X X

ctmvar X X X X

ctmwhy X X X

ctm2snmp

ecactltb X X X X X

ecaqrtab X X X X X

Table 2-3 Utility Reports (Part 1 of 2)

Report Description

Daily Job Order Generates a projection of which jobs in a Scheduling table will be ordered on a given day using a specific calendar. See “ctmrpln” on page 2-120.

Monthly Job Order Generates a projection of which jobs in a Scheduling table will be ordered in a given month using a specific calendar. See “ctmrpln” on page 2-120.

Yearly Job Order Generates a projection of which jobs in a Scheduling table will be ordered over a five-year period using a specific calendar. See “ctmrpln” on page 2-120.



Requires SQL Active






Utilities 2-7

Directing Output From Utilities

Certain utilities described in this chapter generate reports that can be directed to a file. Each such utility is identified by the inclusion of <Output> among the utility’s parameters. If this parameter is not specified, the output is routed to the default output device.

When directing output to a file, do one of the following:

CONTROL-M Log Lists entries in the CONTROL-M log for speci-fied (or all) CONTROL-M/Server processes. See “ctmlog” on page 2-91.

Active Jobs File Lists jobs in the Active Jobs file according to various criteria. See “ctmpsm” on page 2-106.

User Daily:Associated JobProcessing Definitions

Lists all jobs associated with a specific User Daily job and displays security parameters regarding each job. See “ctmordck” on page 2-94.

Prerequisite Conditions Displays existing prerequisite conditions. See “ctmcontb” on page 2-21.

Control Resources Status

Lists the status of Control resources. See “ecactltb” on page 2-157.

Quantitative Resources Status

Lists the status of Quantitative resources. See “ecaqrtab” on page 2-158.

Summary Statistical Data

Lists summarized runtime statistics. See “ctmjsa” on page 2-77 and “ctmstats” on page 2-130.

Runtime Statistical Data Lists runtime statistical data by timestamp. See “ctmruninf” on page 2-124.

Global AutoEdit Variables

Lists Global AutoEdit variables, See “ctmvar” on page 2-150.

Table 2-3 Utility Reports (Part 2 of 2)

Report Description



• Specify the full path name of the file (for example, /ctm/user1/rprt.txt).

• Specify the relative name of the file to be placed in the <controlm_user_dir>/ directory.


Utilities 2-9

Accessing Utilities From Other Unix Users

To access CONTROL-M utilities from a Unix user other than the CONTROL-M/Server account owner, the following modifications must be made to the user’s environment:

• Define variables in the user’s environment.• Add an executable library to the user’s path.• Assign Read/Write permissions.

Define Variables in the User’s Environment

The following variables must be defined in the user’s environment:

CONTROLM

CONTROLM_USERCONTROLM_DATABASELIBPATH or LD_LIBRARY_PATH

Use the following formats to define the shared library path variables in the user’s environment, depending upon the Server platform type:

Table 2-4 Required Environment Variables

For SYBASE For ORACLE

SYBASE ORACLE_BASE

DSLISTEN ORACLE_HOME

DSQUERY ORACLE_SID

DSCONSOLE NLS_LANG

MIRROR_DSLISTEN

MIRROR_DSQUERY



In both Table 2-5 and Table 2-6 above, <ctm_owner> refers to the Unix user account under which CONTROL-M/Server is installed.

Setting environmental variables

Using csh or tcsh

When using csh or tcsh, specify the following command for each variable:

setenv <variable-name> <value>

Table 2-5 Shared Library Path for Sybase Variables

Platform Path Variable

AIX LIBPATH <ctm_owner>/sybase/lib:<ctm_owner>/ctm/exe_AIX

HP-UX 10 SHLIB_PATH <ctm_owner>/sybase/lib:<ctm_owner>/ctm/exe_HP-UX-10

Solaris LD_LIBRARY_PATH <ctm_owner>/sybase/lib:<ctm_owner>/ctm/exe_Solaris

Compaq TRU64 Unix

LD_LIBRARY_PATH <ctm_owner>/sybase/lib:<ctm_owner>/ctm/exe_OSF1

Table 2-6 Shared Library Path for Oracle Variables

Platform Path Variable

AIX LIBPATH <ctm_owner>./oracle/product/8.1.5/lib:<ctm_owner>/ctm/exe_AIX

HP-UX 10 LIBPATH <ctm_owner>./oracle/product/8.1.5/lib:<ctm_owner>/ctm/exe_HP-UX-10

Solaris LD_LIBRARY_PATH <ctm_owner>./oracle/product/8.1.5/lib:<ctm_owner>/ctm/exe_Solaris

Compaq TRU64 Unix

LD_LIBRARY_PATH <ctm_owner>./oracle/product/8.1.5/lib:<ctm_owner>/ctm/exe_OSF1


Utilities 2-11

Sybase Example

setenv CONTROLM /home/controlm/ctmsetenv SYBASE /home/controlm/sybasesetenv DSLISTEN CTRLMsetenv DSQUERY CTRLMsetenv DSCONSOLE CTRLMsetenv MIRROR_DSQUERY MIRRORsetenv MIRROR_DSLISTEN MIRRORsetenv CONTROLM_USER ctrlmsetenv CONTROLM_DATABASE ctrlmsetenv LD_LIBRARY_PATH /home/controlm/ctm/exe_Solaris: /home/controlm/sybase/bin

Oracle Example

setenv CONTROLM /home/ora_ctm/ctmsetenv ORACLE_HOME /home/ora_ctm/oracle/product/8.1.5setenv ORACLE_SID ctrlmsetenv ORACLE_BASE /home1/ora_ctm/oraclesetenv NLS_LANG AMERICAN_AMERICA.WE8ISO8859P1 setenv CONTROLM_USER ctrlmsetenv CONTROLM_DATABASE ctrlmsetenv LD_LIBRARY_PATH /home/controlm/ctm/exe_OSF1: /home/controlm/oracle/product/8.1.5/lib

Using Other Shells

When using other shells (for example, sh, ksh), specify the following command for each variable:

<variable-name>=<value>; export <variable-name>



Sybase Example

CONTROLM=/home/controlm/ctm; export CONTROLMSYBASE=/home/controlm/sybase; export SYBASEDSLISTEN=CTRLM; export DSLISTENDSQUERY=CTRLM; export DSQUERYDSCONSOLE=ctrlm; export DSCONSOLEMIRROR_DSQUERY=MIRROR; export MIRROR_DSQUERYMIRROR_DSLISTEN=MIRROR; export MIRROR_DSLISTENCONTROLM_USER=ctrlm; export CONTROLM_USERCONTROLM_DATABASE=ctrlm; export CONTROLM_DATABASELIBPATH=/home/controlm/ctm/exe_HP-UX-10; export LIBPATH

Oracle Example

CONTROLM=/home/controlm/ctm; export CONTROLMCONTROLM_USER=ctrlm; export CONTROLM_USERCONTROLM_DATABASE=ctrlm; export CONTROLM_DATABASELIBPATH=/home/controlm/ctm/exe_HP-UX-10; export LIBPATH

Determining the values to assign to variables

Specify the following command for each variable from user controlm:

echo $<variable-name>

Example

echo $SYBASE

Add an Executable Library to the User’s Path

The executable directory of CONTROL-M/Server must be added to the user’s path.


Utilities 2-13

Using csh or tcsh

Use the following command to modify the path when using csh or tcsh:

set path=($path ~<controlm_owner>/ctm/exe_<OS_ID>)

The following table describes the variables of this command.

Example

set path=($path ~controlm/ctm/exe_Solaris)

Using Other Shells

Use the following command to modify the path when using other shells (for example, sh, ksh):

PATH="$PATH: <controlm_path>/ctm/exe_<OS_ID>"

The following table describes the variables of this command.

Example

PATH="$PATH: controlm/ctm/exe_HP-UX-10"


<controlm_owner> Unix user account under which CONTROL-M/Server is installed.

<OS_ID> Identifier for the type of operating system on the Server platform (AIX, HP-UX-10 or Solaris).


<controlm_path> Home directory of the CONTROL-M/Server account owner.

<OS_ID> Identifier for the type of operating system on the Server platform. Specify AIX, HP-UX-10 or Solaris.



Assign Read/Write Permissions

The user must have the following read/write permissions:

The recommended method for providing security access to these files is as follows:

• Group controlm should be provided with read permission for the files.

• All users who require access to CONTROL-M utilities should belong to group controlm.

Table 2-7 Read/Write Permissions

Permission Type Directory

Read permission for file: <controlm-directory>/.controlm

Read and Write permission for all files in directory:

prflag/


Utilities 2-15

Utilities

ctm_agstat

This utility enables you to list or update an Agent’s status, or to delete an inactive Agent. (See “Communication Status of Agent Platforms” on page 1-7.)

To invoke the ctm_agstat utility, specify the following command:

ctm_agstat ACTION( {LIST|LIST_INACT|UPDATE|DELETE} ) [AGTNAME(<agent name>)][STATUS( {*SAME | AVAILABLE | DISABLED} )][QUIET( {*YES | *NO} )] [DEBUG(<debug level>)]

The parameters of this command are described below in Table 2-8.

Table 2-8 ctm_agstat Utility Parameters


ACTION Action to be performed by the utility:• LIST – List the current status of the specified Agent.• LIST_INACT – List all inactive (disabled or unavailable)

Agents and their status.• UPDATE – Change the status of the specified Agent to the

value of the STATUS parameter.• DELETE – Delete the specified inactive Agent from the list of

Agents.

<agent name>

Host name of the Agent to be listed / updated. This parameter must be specified for LIST, UPDATE, and DELETE actions but is ignored for the LIST_INACT action.

STATUS Current status of the specified Agent. Valid values: *SAME, AVAILABLE, DISABLED. This parameter must be specified for UPDATE action but is ignored for all other actions.

QUIET To activate the utility without displays and interaction, specify *YES. Default: *NO.

<debug level>

Desired diagnostic level. Valid values: 0 (no diagnostics) to 5 (highest level of diagnostics), *DFT, *SYSVAL, *SAME. Default: *SAME (or zero for first startup).



Examples

1. To show the current status of Agent CMAGENT, type:

ctm_agstat ACTION(LIST) AGTNAME(CMAGENT

2. To list all inactive Agents, type:

ctm_agstat ACTION(LIST_INACT

3. To change the status of Agent CMAGENT to DISABLED, type:

ctm_agstat ACTION(UPDATE) AGTNAME(CMAGENT) STATUS(DISABLED)

4. To delete inactive Agent CMAGENT, type:

ctm_agstat ACTION(DELETE) AGTNAME(CMAGENT)


Utilities 2-17

ctm_backup_bcp

The ctm_backup_bcp utility exports data from the CONTROL-M database to directory <controlm>/ctm/backup_db. Each database table is backed up as a separate ASCII file.

To invoke the ctm_backup_bcp utility:

1. Shut down CONTROL-M using command shut-ctm.

2. Specify the command:

ctm_backup_bcp [-n]

where -n runs the utility in silent mode. In this mode, confirmation prompt and “backing up contents” messages are not displayed.

Differences between the ctm_backup_bcp and ctmdbbck utilities:

• You can only use the ctm_backup_bcp utility if CONTROL-M/Server is down.

• ctm_backup_bcp exports the data in the CONTROL-M database. ctmdbbck backs up an image of the database for later restoration using ctmdbrst.

• When using ctm_backup_bcp, you cannot specify the backup directory.

• ctm_backup_bcp backs up each database table to a separate ASCII file. ctmdbbck backs up the entire database to a single binary file.

• When using ctmdbbck and ctmdbrst, the restored database must be the same size as the original database. When using ctm_backup_bcp and ctm_restore_bcp, the original and restored databases do not need to be the same size.

Example 1

ctm_backup_bcp



Backing up contents of databasePlease confirm [y/n] : Y

Messages similar to the following are displayed:

backing up contents of CMS_NODGRPbacking up contents of CMR_AGSTATbacking up contents of CMS_AGCOMMbacking up contents of CMS_AGSRVTIMbacking up contents of CMR_AJFbacking up contents of CMS_JOBDEFbacking up contents of CMS_USERS…Database backup ended successfully.

Example 2

ctm_backup_bcp -n

In this case, CONTROL-M does not display the confirmation prompt and does not issue messages. Only dots are displayed.


Utilities 2-19

ctm_restore_bcp

The ctm_restore_bcp utility imports the CONTROL-M database from the bcp_backup directory. The content of this directory was created by the ctm_backup_bcp utility.

To invoke the ctm_restore_bcp utility:

1. Shut down CONTROL-M using the shut-ctm command.


ctm_restore_bcp [-n]

where -n runs the utility in silent mode. In silent mode, the confirmation prompt and restoring contents messages are not displayed.

The ctm_restore_bcp utility is similar to the ctmdbrst utility. The following bullets describe the differences between these utilities:

• The ctm_restore_bcp utility imports files created by the ctm_backup_bcp utility. The ctmdbrst utility restores a backup created by the ctmdbbck utility.

• When using the ctm_restore_bcp utility, you cannot specify the directory containing the exported files.

• You can only use the ctm_restore_bcp utility if CONTROL-M/Server is down.

• The ctm_restore_bcp utility imports ASCII files. The ctmdbrst utility restores from a binary file.

Example 1

ctm_restore_bcpRestoring contents of database.This procedure DELETES any information in main databasePlease confirm [y/n]: y



Messages similar to the following are displayed:

restoring contents of CMS_NODGRPrestoring contents of CMR_AGSTATrestoring contents of CMS_AGCOMMrestoring contents of CMS_AGSRVTIMrestoring contents of CMR_AJFrestoring contents of CMS_JOBDEFrestoring contents of CMS_USERS…Database restore ended successfully.

Example 2

ctm_restore_bcp -n

In this case, CONTROL-M does not display the confirmation prompt and the “restoring contents” messages. Only dots are displayed.


Utilities 2-21

ctmcontb

The ctmcontb utility performs operations on the Prerequisite Conditions table. These operations include:

• Listing existing prerequisite conditions.• Adding/deleting a prerequisite condition.• Deleting a range of conditions (from/to specified dates).

Use the following command to list existing prerequisite conditions:

ctmcontb -LIST <Condition Name> <Condition Date> [<Output>]

The parameters of this utility are described in Table 2-9.

Table 2-9 ctmcontb – Listing Prerequisite Conditions


<Condition Name> Name of the prerequisite condition to include in the report. The condition name can include the mask character ∗ to match any character string (including no characters). In this instance, the condition name must be enclosed in quotation marks (for example, “LVL∗”). Specify “∗” by itself to include all existing conditions.

<Condition Date> Date of the prerequisite condition. Must be specified in mmdd format. The condition date can include mask character ∗ to match any character string (including no characters). In this case, enclose the condition date in quotation marks (for example, “12∗ ”).

• Specify “∗” by itself to include all dates.• Specify ODAT to accept the CONTROL-M

date. • Specify STAT to indicate that the date

reference of the condition is not relevant.

<Output> Full path name to which the report should be sent (optional). If this parameter is not specified, the output is routed to the default output device.



Use the following command to add prerequisite conditions:

ctmcontb -ADD <Condition Name> <Condition Date>

The parameters for this command are described in Table 2-10.

Use the following command to delete prerequisite conditions:

ctmcontb -DELETE <Condition Name> <Condition Date>


Table 2-10 ctmcontb – Adding Prerequisite Conditions


<Condition Name> Name of prerequisite condition to add.

<Condition Date> Date of the prerequisite condition. Must be specified in mmdd format. • Specify ODAT to accept the CONTROL-M date.• Specify STAT to indicate that the date reference

of the condition is not relevant.

Table 2-11 ctmcontb – Deleting Prerequisite Conditions


<Condition Name> Name of prerequisite condition to delete. The condition name can include the mask character ∗ to match any character string (including no characters). In this instance, the condition name must be enclosed in quotation marks (for example, “LVL∗ ”). Specify “∗” by itself to include all existing conditions.

<Condition Date> Date of the prerequisite condition. Must be specified in mmdd format. The condition date can include the mask character ∗ to match any character string (including no characters). In this instance, the condition date must be enclosed in quotation marks (for example, “12∗ ”).• Specify “∗” by itself to include all dates.• Specify ODAT to accept the CONTROL-M date. • Specify STAT to indicate that the date reference

of the condition is not relevant.


Utilities 2-23

Use the following command to delete prerequisite conditions with condition dates in a given range:

ctmcontb -DELETEFROM <Condition Name> <From Date> <To Date>


Example 1

The following command specifies that the prerequisite condition bckp_end with condition dates in December should be deleted:

ctmcontb -DELETE bckp_end "12∗"

Example 2

The following command specifies that all prerequisite conditions with prefix a, whose condition dates are between December 1st and December 15th should be deleted:

ctmcontb -DELETEFROM "a∗" 1201 1215

Table 2-12 ctmcontb – Deleting Conditions in a Date Range


<Condition Name> Name of prerequisite conditions to delete. The condition name can include the mask character ∗ to match any character string (including no characters). In this instance, the condition name must be enclosed in quotation marks (for example, “LVL∗ ”). Specify “∗” by itself to include all existing conditions.

<From Date><To Date>

Starting and ending dates for range of condition dates of prerequisite conditions to delete. Each date must be specified in mmdd format.If the To Date is less than the From Date, the range of condition dates will include the From Date up to the end of the year (1231) plus the beginning of the year (0101) up to the To Date.



Example 3

The following command specifies that existing prerequisite conditions should be listed:

ctmcontb -LIST "∗" "∗"

When this command is specified, a report similar to the following is generated:

Date: 30-JUN-2000. Page 1

Conditions list

CONDNAME CONDDATEAPR1- L20 0629APR1-L20 0630ARD- L30K 0630LVL11-LVL22 0628LVL11-LVL22 0629LVL11-LVL22 0630PKR11-LVL01 0630

This example demonstrates the advantage of defining a CONTROL-M job to run a utility. The following job processing definition causes CONTROL-M to run ctmcontb each work day, each time deleting all prerequisite conditions which are between five and ten days old:

Week Days 2,3,4,5,6AutoEdit Assignment %%A=%%CALCDATE %%DATE –10%%B=%%CALCDATE %%DATE –5%%A=%%SUBSTR %%A 3 4%%B=%%SUBSTR %%B 3 4Command Line ctmcontb -DELETEFROM “ ∗” %%A %%B


Utilities 2-25

ctmcreate

ctmcreate is an API (Application Program Interface) utility that allows an ad hoc job to be inserted directly into the Active Jobs file. The job does not have to be defined in the CONTROL-M database. The function performed by this utility is equivalent to the Force function in ENTERPRISE/CS.

The ctmcreate utility can also be used to define jobs for specific applications such as SAP and Oracle Applications. For more information, see “Creating Application-specific Jobs” on page 2-31.

To invoke the ctmcreate utility, specify the following command:

ctmcreate-tasktype {JOB|DETACHED|COMMAND|DUMMY|GROUP} \ [-group <group name>] \ [-application <application name>] \ [ -group_ord <grp_orderno|ALONE|LAST>\ [ -adjust_cond {Y|N}\ [ -nodegrp <node ID/group> ] \ [ -memlib <directory name> ] \ [ -memname <file name> ] \ [ -cmdline <command line text> ] \ [ -jobname <name of job> ] \ [ -schedtab <name of scheduling table> ] \ [ -owner <user name of job owner> ] \

[ -author <user name of the job creator>] \[ -odate <scheduling date>|ODAT ]\

[ -maxrerun <maximum reruns> ]\ [ -timefrom <earliest submission time> ]\ [ -timeuntil <latest submission time> ]\ [ -priority <job priority> ]\ [ -critical {Y|N} ]\ [ -cyclic {Y|N} ]\

[ -intervalfrom {START|END}]\[ -confirm {Y|N} ]\

[ -taskclass {DISTRIBUTION|DECOLLATION}|SAP|OAP ]\ [ -interval <minutes> ]\ [ -overlib <alternate directory> ]\ [ -maxwait <days> ]\ [ -description <job description> ]\ [ -docmem <file name> ]\ [ -doclib <directory name> ]\ [ -incond ‘(<condition1> ’ <date1> {AND|OR} … -incond ‘ <condition2>)’ <date2> {AND|OR} … -incond ‘ <condition3>)’ <date3> {AND|OR}]\[ -outcond <cond> <date> {ADD|DEL} ]\[ -autoedit <variable name> <expression> ]\[ -quantitative <quantitative resource> <quantity> ]\[ -sysout {RELEASE|DELETE|COPY|MOVE} [<parameter>] ]\[ -control <control resource> {E|S} ]\[ -shout {OK|NOTOK|RERUN|LATESUB|LATETIME| EXECTIME} <destination> R|U|V} <message> [<time>] ]\[ -on <statement> <code>\

[ -dook ]\[ -donotok ]\



[ -dorerun ]\[ -doshout <destination> {R|U|V} <message> ]\[ -dostopcylic]\[ -domail <destination> <cc> <urgency> {R|U|V} <subject> <message>\[ -docond <condition> <date> {ADD|DEL} ]\[ -doautoedit <variable name> <expression> ]\[ -doforcejob <table name> <job name> <odate> ]\[ -dosysout {RELEASE|DELETE|COPY|MOVE}[<parameter>]]\

[ -debug <level> ] \[ -quiet ]

Each of the parameters of this utility, except for group_ord, debug and quiet, is described in detail in Chapter 5 of the Enterprise Controlstation User Guide.

Table 2-13 lists each parameter available for the utility and the name by which the parameter appears in the User Guide.


-group_ord Specifies in which order of a Group Scheduling table to put the job. Valid values are:

<order-no> A specific order number of the Group Scheduling table.If the specified order number does not exist the command is not executed and an error message is displayed.

ALONE The job is on its own (not in any table).

LAST The last order of the specified Group Scheduling table.

Note: When an order ID or LAST is specified for this parameter, the -group and -schedtab parameters are mandatory and must both contain the name of Group Scheduling table that is currently in the Active Jobs file.

-debug Level of debug messages, 0 to 5.Default: 0 (no debug messages).

-quiet If specified, no informational messages are displayed during the execution of the command.


Utilities 2-27

Table 2-13 Parameter Name Cross Reference

Utility ParameterENTERPRISE/CS Parameter Utility Parameter

ENTERPRISE/CS Parameter

adjust_cond Adjust condition interval Interval

application Application intervalfrom Interval (From field)

autoedit AutoEdit Assignments

jobname Job Name

cmdline Command Line maxrerun Max Rerun

confirm Confirm Submission maxwait Max Wait

control Control Resources memlib Mem Lib

critical Critical memname Mem Name

cyclic Cyclic nodegrp Node ID/Group

description Description odate see note below

doautoedit Do AutoEdit on On Statement/Code

doclib Doc Lib outcond Out Conditions

docmem Doc Mem overlib Over Lib

docond Do Cond owner Owner

doforcejob Do Forcejob priority Priority

domail Do Mail quantitative Quantitative Resources

donotok Do NOTOK schedtab Scheduling Table

dook Do OK shout Shout

dorerun Do Rerun sysout Sysout Handling

doshout Do Shout taskclass Task Class

dostopcyclic Do Stop Cyclic tasktype Task Type

dosysout Do Sysout timefrom Time

group Group timeuntil Time

incond In Conditions



The following syntax rules apply when using this utility:

• More than one parameter can be specified on a line.

• Parameter odate specifies the date to use as the job’s scheduling date. Specify a date in yyyymmdd format, or specify ODAT to accept the CONTROL-M date.

• The %%NEXT, %%$NEXT, %%PREV, and %%$PREV AutoEdit variables cannot be specified for the ctmcreate utility. These variables refer to the next or previous scheduling dates and are therefore not relevant for this utility which places jobs directly in the Active Jobs file.

• The length of the command line, after decoding, must not exceed 999 characters.

• Although most parameters are listed as optional, certain parameters are required depending upon the option specified for the -tasktype parameter.

• All fields of each parameter (as specified in the syntax on page 2-25) must contain values. If no value is desired for a parameter field, a null string "" must be specified in the relevant position in the parameter specification.

For example

The -domail parameter has the following syntax:-domail <destination> <cc> <severity> <subject> <message>

To specify this command without a value for the cc field, include a null string in the appropriate location. For example:

-domail [email protected] "" R "subject line" "My message"

• All task types require parameters group and application. In addition:

— JOB and DETACHED require parameters memname and memlib.


Utilities 2-29

— COMMAND requires parameter cmdline.

• Strings containing blanks must be enclosed in quotes (for example, -cmdline “ctmudlst list payroll” ).

• A Unix metasymbol (which must be enclosed in quotation marks) appearing in a command line string should be enclosed in single quotes (for example, -cmdline “ctmcontb list '*' ” ).

• An AutoEdit variable that does not contain a $ sign can be enclosed in single (‘ ’) or double (“ ”) quote marks. An AutoEdit variable that does contain a $ sign should be enclosed in single quote marks. An AutoEdit variable containing a $ sign cannot be resolved if it is enclosed in double quote marks.

• Condition dates are specified in mmdd format. Time is specified in hhmm format.

• A parameter requiring more than one entry can be repeated as many times as necessary (for example, if a job must wait for several prerequisite conditions, specify a separate -incond parameter for each prerequisite condition).

• An -on parameter must be followed by at least one -do... parameter.

• -do... parameters are dependent upon the last -on parameter preceding them.

• Normally, when a -dorerun parameter is implemented, the current run of the job ends with a status of NOTOK. To ensure that the job will have a status of OK even though it is rerun, specify a -dook parameter immediately after the -dorerun parameter.

• The order of the parameters does not affect the outcome of the job, with the exception of -on and -do... parameters.

• When using -doforcejob to force an entire table, <job name> must be specified as a blank enclosed in quotes (that is, “ ”).



• When the ctmcreate utility is invoked from a script: To use the ∗∗∗∗ option for a -incond date parameter, specify this parameter as \“ ∗∗∗∗\”

• If a single character is specified for the priority parameter, the first character is assumed to be A. For example, priority 1 is interpreted as priority A1.

• A maximum of 99 prerequisite conditions can be specified for the Do Cond parameter.

• A maximum of 99 prerequisite conditions can be specified for the Out Conditions parameter.

Example 1

-incond pk_oly_ok \"∗∗∗∗\"

When the Unix symbol ~ is used in parameter -memlib, -overlib, or -doclib to represent the user’s home directory, the entire parameter should be enclosed in double quotes. This ensures that the ~ will be translated by the Agent before submission, and not by the Server before transmission to the Agent platform.

-memlib "~/controlm/scripts/"

Example 2

The following command contains the minimum parameters required to create a job in the Active Jobs file:

ctmcreate -tasktype comman -group ecs\-application test -cmdline "ls -l /etc/passwd"

Example 3

The following command includes examples of most of the parameters that can be used to create a job in the Active Jobs file:

ctmcreate -tasktype JOB \ -cyclic N \ -description "Daily Summary" \


Utilities 2-31

-group SUPPLY -application SUPPLIES \ -memlib /users/ctm/ -memname PROLYPAR -nodegrp UNIXGRP \ -jobname PROLYPAR \ -owner suppman \ -odate 19981130 \ -timeuntil 1800 \ -priority AA -critical N \ -confirm Y \ -doclib /users/supply/doc/ -docmem prolypardoc \ -incond pk_oly_ok ODAT AND \ -incond pk_olp_ok ODAT AND \ -outcond pk_oly_ok ODAT DEL \ -outcond pk_olp_ok ODAT DEL \ -outcond pk_olypar ODAT ADD \ -autoedit %%PARM1 "%%CALCDATE %%ODATE -2" \ -quantitative tape 2 -quantitative cpu 50 \ -sysout MOVE /test/logs/ \ -control disk2 E \ -shout OK oper2 U "Daily summary completed" \ -on "COPY JWINFO_2507" "%COPY-E-OPENIN, error" \ -dosysout MOVE /oper/openerr

Creating Application-specific Jobs

The ctmcreate utility can be used to define jobs for specific applications such as SAP and Oracle Applications. These jobs are defined by setting the – TASKCLASS parameter to SAP or OAP.

• If TASKCLASS is set to SAP, the job will run under SAP.

• If TASKCLASS is set to OAP, the job will run under Oracle Applications.

NoteThe program that is used to run an application-specific job resides in a script directory in the agent platform. This program is located under $HOME/ctm/script. SAP and the EXE directory is /r3/exe. is the name for the SAP script. OAP. is the name for the Oracle Applications script. Make sure that the path to the script directory is located in the user’s environment path.

The following CONTROL-M system parameters must also be set in order to allow support for application specific jobs:

• The AUTOEDIT_INC_SEC parameter must be set to SYSTEM in the $home/ctm/data/config.dat file of CONTROL-M/Server for Unix.



• The AUTOEDIT_INLINE parameter must be set to Y in the $home/ctm/data/agconfig.dat file of CONTROL-M/Agent for Unix.

The following parameters must be specified for the utility:

– MEMLIB– MEMNAME– TASKCLASS

In addition to these parameters, you can specify application-specific parameters.

Table 2-14, “SAP Parameters,” on page 2-33 lists parameters for SAP jobs. The parameters for SAP applications are described in detail in the CONTROL-M Option for R/3 Administrator Guide version 3.0.04 or later.

Table 2-15, “Oracle Applications Parameters,” on page 2-34 lists the parameters for Oracle Applications. The parameters for Oracle Applications are described in detail in the CONTROL-M Option for Oracle Applications Administrator Guide version 2.0.01or later.

When the ctmcreate command line is processed, the application-specific parameters are used to create special AutoEdit variables with the specified values. These AutoEdit variables are used to pass information to the CONTROL-M Option for the specified application. The parameters are added as AutoEdit variables in the command line. For more information, see the “ERP Job Parameters” appendix in the CONTROL-M/Desktop User Guide.

In the tables below:

• Type indicates whether a parameter value is a character string (c) or an integer (n).

• Minimum and Maximum determine– for characters: the number of characters that are allowed in a string.– for integers: the minimum and maximum values for the parameter.


Utilities 2-33

.

Table 2-14 SAP Parameters (Part 1 of 2)

SAP Parameters Type Minimum Maximum

–account c 0 80

–archive_info c 0 2

–archive_object c 0 10

–archive_sapobject c 0 10

–asap c 0 1

–host c 0 80

–job_mode c 1 10

–job_in_file c 0 80

–jobcount c 0 8

–language c 0 2

–print_archmode c 0 1

–print_authorization c 0 68

–print_banner c 0 1

–print_banner_page c 1 1

–print_copies n 0 255

–print_destination c 0 4

–print_expiration n 1 9

–print_immediately c 1 1

–print_numcolumns n 1 255

–print_numlines n 0 130

–print_recipient c 0 32

–print_release c 0 1

–program c 0 80



–polling_interval c 0 80

–spool c 0 80

–step_num n 0 999

–r3_owner c 0 80

–variant c 0 80

–waitonly c 0 1

Table 2-15 Oracle Applications Parameters (Part 1 of 2)

OAP Parameters Type Minimum Maximum

–ioa_appl c 1 30

-display_output c 0 1

-notification_<n>where n is 1 - 30

c 0 30

–username c 1 30

-ver c 0 6

–respname c 1 30

–respapp c 1 50

–tasktype c 1 20

–progname c 1 30

–appname c 1 50

–printername c 0 100

–printstyle c 0 20

–printcopies c 0 6

–profile_<n> where n is 1 - 30

c 0 80

–description c 0 80

Table 2-14 SAP Parameters (Part 2 of 2)



Utilities 2-35

Sample of a Command Line

ctmcreate -tasktype job -memname MEMSAP -memlib /home/ag6tst/ctm/scripts -jobname sap6 -job_mode run_copy-account ABC -taskclass SAP

The following messages are issued when this command-line is processed:

AUTOEDIT ’%%SAPR3_JOB_MODE’ addedAUTOEDIT ’%%SAPR3_ACCOUNT’ addednew ORDER created, orderid:00001b(47) for JOBNAME=sap6.

–waitchild c 1 1

–security_groupname c 0 80

–parm<n> where n is 1-100

c 0 80

–stageparm<n> where n is 1-100

c 0 80

Table 2-15 Oracle Applications Parameters (Part 2 of 2)




ctmdbapasswd

The ctmdbapasswd utility enables the administrator to change the database password of a dedicated CONTROL-M/Server. Only an administrator can change a database password.

Specify the following command to invoke the ctmdbapasswd utility:

ctmdbapasswd

The system will prompt you to enter the old password:

Please enter the old password for System Administrator account:

1. Enter the old password for the System Administrator account. The system will prompt you to enter the new password:

Please enter the new password for System Administrator account:

2. Enter the new password for the System Administrator account. Make sure that the password has at least 6 characters. You will not see your entry on the screen. The system will then prompt you to reenter the password:

Enter again to verify:

3. Reenter the new password for the System Administrator account. The system will respond with the message that the password was successfully changed:

Password was successfully changed


Utilities 2-37

ctmdbbck

The ctmdbbck utility backs up the CONTROL-M database.

NoteThe ctmdbbck utility can be used only to back up a dedicated database server. It should not be used if CONTROL-M was installed using an existing database server.To back up an existing database, use the ctm_backup_bcp utility (described on page 2-17).

To invoke the ctmdbbck utility, specify the following command:

ctmdbbck [<Backup Device>]

where <Backup Device> is the device to be used for backup of the existing database. A list of devices can be obtained using the option List Backup Devices from the Database Maintenance menu. The device specified for this parameter must be either:

• a valid device defined in Sybase

-or-

• the full path name of a file to be created by the backup procedure for Sybase or Oracle

The default backup device is tapedump2, which points to one of the following devices:

Operating System Device

AIX /dev/rmt0

HP-UX /dev/rmt/0m

Solaris /dev/rmt/0mn

Compaq TRU64 Unix /dev/nrmt0h



Example

ctmdbbck tapedump2


Utilities 2-39

ctmdbcheck

The ctmdbcheck utility displays information about the memory capacity and the status of the CONTROL-M database. To invoke the ctmdbcheck utility, specify the following command:

ctmdbcheck

The ctmdbcheck utility can also be used with the following syntax to monitor the database and the transaction log:

ctmdbcheck [-d <db_threshold_%>] [-l <log_threshold_%>][-n]ctmdbcheck [general_threshold_%]

These commands trigger a shout message to ENTERPRISE/CS if more than the specified percentage of the database or the database transaction log are full. This message can then be used to trigger actions that will extend the appropriate CONTROL-M database component.

The ctmdbcheck utility can be run as a cyclic job.

NoteIf the -n switch is specified in the ctmdbcheck command, only database capacity information is returned, and database thresholds and integrity are not checked.

For performance reasons, run the ctmdbcheck utility during non-peak hours or when CONTROL-M is down. If you need to determine database sizes frequently, use the ctmdbused command. This command displays the size (in KB) of the data and log components of the database plus the amount and percentage of space currently used in each component.

The parameters in these commands are described in Table 2-16.



ctmdbcheck Output

The ctmdbcheck utility returns information about the CONTROL-M database. Table 2-17 describes the fields that are returned by this utility for a Sybase database. Table 2-18 describes the fields that are returned by this utility for an Oracle database.

Table 2-16 ctmdbcheck – Parameters


db_threshold_%

Threshold for usage of the CONTROL-M database. If more than the specified percentage of the database is full, a Shout message is sent to ENTERPRISE/CS warning that the database should be extended. This variable must be preceded by the -d switch. For example, -d80 indicates that a shout message should be issued if the database is more than 80% full.

log_threshold_%

Threshold for usage of the transaction log of the CONTROL-M database. If more than the specified percentage of the database is full, a Shout message is sent to ENTERPRISE/CS warning that the transaction log should be extended. This variable must be preceded by the -l switch. For example, -l80 indicates that a shout message should be issued if the transaction log is more than 80% full.

general_threshold_%

Checks data and log partitions of the CONTROL-M database by the same percentage (for example, if percent usage of either the data area or the transaction log exceeds 80%, ctmdbcheck 80 triggers a Shout message).

Table 2-17 ctmdbcheck – Displayed Fields for Sybase

Field Description

db total Total amount of memory (in KB) allocated for the database.

data Total amount of memory (in KB) allocated to the Data partition of the database.

log Total amount of memory (in KB) allocated to the Log partition of the database.

Data used Total memory currently used in the Data partition.

Log used Total memory currently used in the Log partition.


Utilities 2-41

In addition to the above fields, ctmdbcheck also returns one of the following messages describing the current database status:

• Database is OK.• WARNING: Database is more than half full.• ATTENTION: Database log segment is more than 90% full.• ATTENTION: Database is more than 80% full.

Example 1

This example uses the ctmdbcheck utility to check the status of a Sybase database without specifying any parameters (that is, no shout messages will be issued for this run on the utility, even if database is over the desired threshold).

Utility Input

ctmdbcheck

Utility Output

db total = 25000.0 KB (data= 19500.00 , log= 5500.00)data used = 3696 KB (18%).log used = 0 KB (0%).Checking database...Database is OK.

Example 2

This example uses the ctmdbcheck utility to check the status of an Oracle database without specifying any additional parameters.

Utility Input

ctmdbcheck

Table 2-18 ctmdbcheck – Displayed Fields for Oracle

Field Description

Tablespace Name of the Tablespace.

Size Allocated size of the Tablespace in MB.

Percent Free Percent of allocated Tablespace size that is not used.



Utility Output

Tablespace Size % Free -------------------- ----- -------MADONA6A 120M 77%MADONA6A_INDX 40M 99%RBS 90M 68%

Checking database...Database is OK.

Example 3

Utility Input

ctmdbcheck -d80

Utility Output

Message ’Warning: DB is more than 80% full’, urgency ’U’ NodeID ’linda’ – Shout to user 'ECS' 'SUCCESS'db total = 25000.0 KB (data= 19500.00 , log= 5500.00)data used = 21250 KB (85%).log used = 0 KB (0%).Checking database...Database is OK.

This example produces the same display as ctmdbcheck except that a warning message is generated if the percent usage of the data area is higher than the percentage specified in the command. In this example, the message data used = 21250 KB (85%) was generated because 85% exceeds the specified threshold of 80%. This message is also sent to the ENTERPRISE/CS alert window.

Example 3

Utility Input

ctmdbcheck -l80

Utility Output

db total = 25000.0 KB (data= 19500.00 , log= 5500.00)data used = 21250 KB (85%).log used = 0 KB (0%).Checking database...Database is OK.


Utilities 2-43

This command is similar to the example above except that here the Log partition is being checked. No warning message is generated because 0% is less than the specified threshold of 80%.

Example 4

Utility Input

ctmdbcheck 50

The general threshold % option is used to specify the same percentage for both the database and the log. In this example, if either the database or log exceeds 50%, ctmdbcheck 50 will trigger a shout message.



ctmdbrst

ctmdbrst restores the CONTROL-M database.

To invoke the ctmdbrst utility, specify the following command:

ctmdbrst [<Backup Device>]

where <Backup Device> is the device from which the database should be restored. The device specified for this parameter must be either a valid device defined in Sybase, or the full path name of a file to be used as input for the ctmdbrst utility. A list of devices can be obtained using the option List Backup Devices from the Database Maintenance menu.

NoteCONTROL-M must be shut down before invoking this utility. Make sure that no other users or processes are connected to the SQL Server.

The default backup device is tapedump2, which points to one of the following devices:

Example

The following command causes the CONTROL-M database to be restored from the default backup device:

ctmdbrst

Operating System Device

AIX /dev/rmt0

HP-UX /dev/rmt/0m

Solaris /dev/rmt/0mn

Compaq TRU64 Unix /dev/nrmt0h


Utilities 2-45

ctmdbspace

ctmdbspace checks the data and log usage in the CONTROL-M database and displays the usage. The utility returns a “failed” status if the usage exceeds the specified limit.

Notectmdbspace can be included in the CONTROL-M Watchdog process. See “Watchdog Facility” on page 1-44 for more information.

To invoke the ctmdbspace utility, specify the following command:

ctmdbspace -limit <amount> [-quiet]

where <amount> is the maximum amount (percentage) of data and log usage in the database. If the -quiet parameter is specified, no informational messages are displayed during the execution of the command.

Example

The following command returns a “failed” status if the CONTROL-M database usage is more than 50%:

ctmdbspace -limit 50%



ctmdbtrans

The ctmdbtrans utility lists the active transactions in the database. A transaction is defined as the unit of work performed by CONTROL-M in the database. Each transaction is assigned a unique name identifying that specific unit of work.

You may be asked by technical support to run this utility and to provide them with the output for debugging purposes.

To see which transactions are active in the database, specify the following command:

ctmdbtrans

-or-

Select “List Active Transactions” from the Troubleshooting menu (described on page 4-40).


Utilities 2-47

ctmdefine

ctmdefine is an API (Application Program Interface) utility that adds a job processing definition to a Scheduling table, or creates a new Group Scheduling table in the CONTROL-M database. This utility can be used when converting job scheduling information from other job control products to CONTROL-M. The function performed by this utility is equivalent to the manual process of creating job processing definitions, described in Chapter 7, “Job Processing Definitions”, in the Enterprise Controlstation User Guide.

The ctmcreate utility can also be used to define jobs for specific applications such as SAP and Oracle Applications. For more information, see “Defining Application-specific Jobs” on page 2-57.

NoteGroup Scheduling tables can also be defined using the ctmgrpdef utility (described on page 2-75).

When creating new Scheduling tables or job processing definitions, the following considerations are applicable:

• If the job name specified when using this utility already exists in a job processing definition in the Scheduling table, the new job processing definition does not overwrite the existing one. Both job processing definitions will appear in the table, each with a different internal job number.

• If the Scheduling table specified when using this utility does not exist, the utility creates it.

• After using this utility to create one or more job processing definitions, the modified Scheduling tables should be downloaded to the ENTERPRISE/CS database (see “Table Synchronization” in Chapter 7, Job Processing Definitions, in the Enterprise Controlstation User Guide).



• A newly created Scheduling table can be assigned a User Daily parameter via the ENTERPRISE/CS GUI after the Scheduling table is downloaded to the ENTERPRISE/CS database or using the ctmpsm utility.

• Values for a creation/modification timestamp and the user ID of the user who created or modified the job processing definition are automatically added to the communication protocol between Enterprise Controlstation and CONTROL-M and are stored in the ENTERPRISE/CS database. These values are initialized by the CTMDEFINE utility and are sent to Enterprise Controlstation when the Scheduling table is downloaded. When the Scheduling Table is uploaded, Enterprise Controlstation sends these values to CONTROL-M.

Use the following command to invoke the ctmdefine utility:

ctmdefine -table <Scheduling table name> \ -jobname <job name> \ -group <group name> \ -application <application name> \ [-tasktype {JOB|DETACHED|COMMAND|DUMMY}] \ [-adjust_cond Y|N] \ [ -nodegrp <node ID/group> ] \ [ -memlib<directory name> ] \ [ -memname <file name> ] \ [ -cmdline <command line text> ] \ [ -owner <user name of job owner> ] \

[ -author <user name of the job creator>] \[ -maxrerun <maximum reruns> ] \

[ -timefrom <earliest submission time> ] \ [ -timeuntil <latest submission time> \ [ -priority <job priority> ] \ [ -critical {Y|N} ] \ [ -cyclic {Y|N} ] \

[ -intervalfrom {START|END}]\[ -confirm {Y|N} ] \

[ -taskclass {DISTRIBUTION|DECOLLATION|SAP|OAP}] \ [ -interval <minutes> ] \ [ -overlib <alternate directory> ] \ [ -maxwait <days> ] \ [ -description <job description> ] \ [ -docmem <file name> ] \ [ -doclib <directory name> ] \ [ -incond <condition> <date> {AND|OR} ] \ [ -outcond <condition> <date> {ADD|DEL} ] \ [ -autoedit <variable name> <expression> ] \ [ -quantitative <resource name> <quantity> ] \ [ -sysout {RELEASE|DELETE|COPY|MOVE} [<parameter>] ] \ [ -control <resource name> {E|S} ] \ [ -shout{OK|NOTOK|RERUN|LATESUB|LATETIME|EXECTIME} <destination> {R|U|V} <message> [<time>] ] \ [ -on <statement> <code> \ [ -dook ] \

[ -donotok ] \


Utilities 2-49

[ -dorerun ] \ [ -doshout <destination {R|U|V} <message> ] \ [ -docond <condition> <date> {ADD|DEL} ] \ [ -doautoedit <variable name> <expression> ] \ [ -doforcejob <table name> <job name> <odate> ] \

[ -dosysout {RELEASE|DELETE|COPY|MOVE}[<parameter>]]] \[ -domail <destination> <cc> {R|U|V} <subject> <message>]\

[ -dostopcyclic ] \ [ -days <days string> ] \ [ -weekdays <weekdays string> ] \

[ -month {ALL|JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC} {Y|N}] \ [ -date <mmdd> ] \ [ -dayscal <calendar name> ] \ [ -weekcal <calendar name> ] \ [ -confcal <calendar name> ] \ [ -shift {‘<’|’>‘} ] \ [ -cal_andor {AND|OR} ] \ [ -retro {Y|N} ] \ [ -debug <level> ] \ [ -quiet ] \ [ -TAG <tagname> ]\

[ -RELATIONSHIP AND|OR ]

Each parameter included in the above syntax, except debug and quiet, is described in detail in Chapter 5, “Job Processing Parameters”, in the Enterprise Controlstation User Guide.

Table 2-19 lists each parameter of the ctmdefine utility, and the name under which the parameter appears in the Enterprise Controlstation User Guide.


debug Level of debug messages, 0 to 5. Default: 0 (no debug messages).

quiet If specified, no information messages are displayed during execution of the command.



Table 2-19 ctmdefine – Parameter Name Cross Reference

Utility ParameterENTERPRISE/CS Parameter Utility Parameter

ENTERPRISE/CS Parameter

adjust_cond Adjust Condition interval Interval

application Application intervalfrom Interval (From field)

autoedit AutoEdit Assignments jobname Job Name

cal_andor AND/OR maxrerun Max Rerun

cmdline Command Line maxwait Max Wait

confcal Conf Calendar memlib Mem Lib

confirm Confirm Submission memname Mem Name

control Control Resources month See below

critical Critical nodegrp Node ID/Group

cyclic Cyclic on On Statement/Code

date Dates outcond Out Conditions

days Days overlib Over Lib

dayscal Days Calendar owner Owner

description Description priority Priority

doautoedit Do AutoEdit quantitative Quantitative Resources

doclib Doc Lib relationship Relationship

docmem Doc Mem retro Retro

docond Do Cond shift Shift

doforcejob Do Forcejob shout Shout

donotok Do NOTOK sysout Sysout Handling

domail Do Mail table Scheduling Table

dostopcyclic Do Stopcyclic tag Schedule Tag

dook Do OK taskclass Task Class

dorerun Do Rerun tasktype Task Type

doshout Do Shout timefrom Time

dosysout Do Sysout timeuntil Time

group Group weekcal Weekdays Calendar

incond In Conditions weekdays Weekdays


Utilities 2-51

NoteFor the -month parameter, specify the first three letters of a month (for example, JAN) or ALL for all months (the default is none). To specify two or more individual months, use a separate -month parameter for each month. See Months parameter.

The following syntax rules apply for this utility:

• More than one parameter can be specified on a line.

• Keywords can be written in either uppercase or lowercase, but parameter values are case-sensitive.

Example:

-GROUP ACCGROUP and -group ACCGROUP

specify the same group ACCGROUP.

-group accgroup

specifies a different group Accgroup.

• If a single character is specified for the priority parameter, the first character is assumed to be A. For example, priority 1 is interpreted as priority A1.

• The length of the command line, after decoding, must not exceed 999 characters.

• The -taskclass parameter can accept either DECOLLATION or DISTRIBUTION as a value. This attribute enables integration with CONTROL-D.

• Although most parameters are listed as optional, certain parameters may be required, depending on the option specified for parameter -tasktype.



• All task types require the group and application parameters. In addition:

— JOB and DETACHED require parameters memname and memlib.

— COMMAND requires parameter cmdline.

— GROUP requires the tag parameters. Each tag definition is followed by its scheduling parameters.

Example:

-tag mytag1-maxwait 1-days 0,2,3-dayscal cal1

• Strings containing blanks must be enclosed in quotes (for example, -cmdline “ctmudlst list payroll” ).

• A Unix metasymbol (which must be enclosed in quotation marks) appearing in a command line string should be enclosed in single quotes (for example, -cmdline “ctmcontb list '*' ” ).

• An AutoEdit variable that does not contain a $ sign can be enclosed in single (‘ ’) or double (“ ”) quote marks. An AutoEdit variable that does contain a $ sign should be enclosed in single quote marks. An AutoEdit variable containing a $ sign cannot be resolved if it is enclosed in double quote marks.

• Condition dates are specified in mmdd format. Time is specified in hhmm format.

• A parameter requiring more than one entry can be repeated as needed:

— If a job is dependent upon several prerequisite conditions, specify a separate -incond parameter for each prerequisite condition.


Utilities 2-53

— If a job can run only in January and July, specify a separate -month parameter for each month. (For example, -month ALL N -month JAN Y -month JUL Y.)

— If a job should run every month except July, specify -month ALL Y and -month JUL N.

— If a job is in a Group Scheduling table and is scheduled according to tags FIRSTDAY and SALARY1, specify –tag FIRSTDAY –tag SALARY1.

• The default for the -month parameter is ALL Y. This means that if you wish to define a job that should run only in one specific month, you must first indicate that it should not run on any month. For example:-month ALL N -month NOV Y

• An -on parameter must be followed by at least one -do... parameter.

• -do... parameters are dependent upon the last -on parameter preceding them.

• The order of parameters does not affect the outcome of the job, with the exception of -on and -do... parameters.

• All fields of each parameter (as specified in the syntax on page 2-48) must contain values. If no value is desired for a parameter field, a null string "" must be specified in the relevant position in the parameter specification.

For example

The -domail parameter has the following syntax:-domail <destination> <cc> <severity> <subject> <message>

To specify this command without a value for the cc field, include a null string in the appropriate location. For example:

-domail [email protected] "" R "subject line" "My message"



• Normally, when a -dorerun parameter is implemented, the current run of the job ends with a status of NOTOK. To ensure that the job will have a status of OK even though it is rerun, specify a -dook parameter immediately after the -dorerun parameter.

• When using -doforcejob to force an entire table, <job name> must be specified as a blank enclosed in quotes (that is, “ ”).

• IN condition statements using complex boolean logic can be specified.

Example:

-incond ‘(job_a’ ODAT OR -incond ‘job_b)’ ODAT AND -incond ‘job_c)’ AND -incond job_d

For more information, see the description of the In Conditions parameter in Chapter 5, “Job Processing Parameters”, in the Enterprise Controlstation User Guide.

• When ctmdefine is invoked from a script: To use the ∗∗∗∗ option for a -incond date parameter, specify this parameter as \“ ∗∗∗∗\”

Example: -incond pk_oly_ok \"****\"

• When the Unix symbol ~ is used in parameter -memlib, -overlib, or -doclib to represent the user’s home directory, the entire parameter should be enclosed in double quotes. This ensures that the ~ will be translated by the Agent before submission, and not by the Server before transmission to the Agent platform.

Example: -memlib "~/controlm/scripts/"

• A maximum of 99 prerequisite conditions can be specified for the Do Cond parameter.

• A maximum of 99 prerequisite conditions can be specified for the Out Conditions parameter.


Utilities 2-55

Example 1

The following command contains the minimum parameters required to define a job:

ctmdefine -table cmmnds -jobname cmls13 \-tasktype command -group ecs -application test \-date 0101 -cmdline "ls -l /etc/passwd"



Example 2

The following command includes examples of most of the parameters that can be used to define a job:

ctmdefine -tasktype JOB -cyclic N\ -table djsales -jobname dj102\ -description "Daily Summary"\ -group SUPPLY -application SUPPLIES\ -memlib /users/ctm/ -memname PROLYPAR -nodegrp UNIXGRP\ -owner suppman\-month ALL N\-month MAR Y -month JUN Y -month SEP Y -month DEC Y\

-timeuntil 1800\ -priority AA -critical N\ -confirm Y\ -doclib /users/supply/doc/ -docmem prolypardoc\ -incond pk_oly_ok ODAT AND\ -incond pk_olp_ok ODAT AND\ -outcond pk_oly_ok ODAT DEL\ -outcond pk_olp_ok ODAT DEL\ -outcond pk_olypar ODAT ADD\ -autoedit %%PARM1 "%%CALCDATE %%ODATE -2"\ -quantitative tape 2 -quantitative cpu 50 \ -sysout MOVE /test/logs/\ -control disk2 E\ -shout OK oper2 U "Daily summary completed"\ -on "COPY JWINFO_2507" "%COPY-E-OPENIN, error"\ -dosysout MOVE /oper/openerr/\ -on "*" notok\ -dorerun\ -doshout ecs v "Daily summary failed. Attempting rerun"


Utilities 2-57

Defining Application-specific Jobs

The ctmdefine utility can be used to define jobs for specific applications such as SAP and Oracle Applications. These jobs are defined by setting the – TASKCLASS parameter to SAP or OAP.

• If TASKCLASS is set to SAP, the job will run under SAP.

• If TASKCLASS is set to OAP, the job will run under Oracle Applications.

NoteThe program that is used to run an application-specific job resides in a script directory in the agent platform. This program is located under $HOME/ctm/script. SAP and the EXE directory is /r3/exe. is the name for the SAP script. OAP. is the name for the Oracle Applications script. Make sure that the path to the script directory is located in the user’s environment path.

The following CONTROL-M system parameters must also be set in order to allow support for application specific jobs:

• The AUTOEDIT_INC_SEC parameter must be set to SYSTEM in the $home/ctm/data/config.dat file of CONTROL-M/Server for Unix.

• The AUTOEDIT_INLINE parameter must be set to Y in the $home/ctm/data/agconfig.dat file of CONTROL-M/Agent for Unix.

The following parameters must be specified for the utility:

– MEMLIB– MEMNAME– TASKCLASS

In addition to these parameters, you can specify application-specific parameters.



Table , “,” on page 2-58 lists the SAP parameters. The parameters for SAP applications are described in detail in theCONTROL-M Option for R/3 Administrator Guide version 3.0.04.

Table 2-21, “Oracle Applications Parameters,” on page 2-59 lists the Oracle Applications parameters. The parameters for Oracle Applications are described in detail in the CONTROL-M Option for Oracle Applications Administrator Guide version 2.0.01 or later.

When the ctmcreate command line is processed, the application-specific parameters are used to create special AutoEdit variables with the specified values. These AutoEdit variables are used to pass information to the CONTROL-M Option for the specified application. The parameters are added as AutoEdit variables in the command line. For more information, see the “ERP Job Parameters” appendix in the CONTROL-M/Desktop User Guide.

In the tables below:

• Type indicates whether a parameter value is a character string (c) or an integer (n).

• Minimum and Maximum determine– for characters: the number of characters that are allowed in a string.– for integers: the minimum and maximum values for the parameter.

Table 2-20 SAP Parameters


–account c 0 80

–archive_info c 0 2

–archive_object c 0 10

–archive_sapobject c 0 10

–asap c 0 1

–host c 0 80

–job_mode c 1 10

–job_in_file c 0 80


Utilities 2-59

–jobcount c 0 8

–language c 0 2

–print_archmode c 0 1

–print_authorization c 0 68

–print_banner c 0 1

–print_banner_page c 1 1

–print_copies n 0 255

–print_destination c 0 4

–print_expiration n 1 9

–print_immediately c 1 1

–print_numcolumns n 1 255

–print_numlines n 0 130

–print_recipient c 0 32

–print_release c 0 1

–program c 0 80

–polling_interval c 0 80

–r3_owner c 0 80

–spool c 0 80

–step_num n 0 999

–variant c 0 80

–waitonly c 0 1

Table 2-21 Oracle Applications Parameters


–ioa_appl c 1 30

-display_output c 0 1

Table 2-20 SAP Parameters




Sample of a Command Line

ctmdefine -tasktype job -group SAP1 -application SAPA -table SAPjobs -memname MEMSAP -memlib /home/ag6tst/ctm/scripts -jobname sap6 -job_mode run_copy -account ABC -taskclass SAP

The following messages are issued when this command-line is processed:

AUTOEDIT ’%%SAPR3_JOB_MODE’ added

-notification_<n>where n is 1 - 30

c 0 30

–username c 1 30

–respname c 1 30

–respapp c 1 50

–tasktype c 1 20

–progname c 1 30

–appname c 1 50

–printername c 0 100

–printstyle c 0 20

–printcopies c 0 6

–profile_<n> where n is 1-30

c 0 80

–description c 0 80

–waitchild c 1 1

–security_groupname c 0 80

–parm<n> where n is 1-100

c 0 80

–stageparm<n> where n is 1-100

c 0 80

Table 2-21 Oracle Applications Parameters



Utilities 2-61

AUTOEDIT ’%%SAPR3_ACCOUNT’ addednew JOB defined, TABLE=’SAPjobs’, JOBNAME=’sap6’, JOBNO = 00005p(205)ddx



ctmdiskspace

ctmdiskspace checks the amount of free disk space on a device and displays the result. The utility returns a “failed” status if the current free space is below the specified limit.

ctmdiskspace can be included in the CONTROL-M Watchdog process. For more information, see “Watchdog Facility” on page 1-44.

Use the following command to invoke the ctmdiskspace utility:

ctmdiskspace -limit <amount> -path <path_name> [-quiet]

Table 2-22 describes the parameters of this command.

NoteMore than one -path <path_name> statement can be specified for each run of the ctmdiskspace utility.

Example 1

The following command returns a “failed” status if the amount of free disk space in the CONTROL-M user directory is below 25%:

ctmdiskspace -limit 25% -path /ctm/ctmuser

Table 2-22 ctmdiskspace – Parameters


amount Specifies the minimum amount (percentage, K, or M) of free space on the device as a whole number (integer).

path_name Specifies the full path name of the device. Multiple devices can be specified on the command line.

-quiet Suppresses informational messages from being displayed during the execution of the command.


Utilities 2-63

Example 2

The following command returns a “failed” status if the amount of free disk in the CONTROL-M user directory is below 20M:

ctmdiskspace -limit 20M -path /ctm/ctmuser



ctmexdef

The ctmexdef utility exports job processing definitions from the CONTROL-M database to a flat (ASCII) file. This file can then be used as input for either the ctmcreate utility or the ctmdefine utility.

The ctmexdef utility can be used to:

• Modify existing job processing definitions in batch mode (together with the ctmdefine utility). The job processing definitions in the file exported by ctmexdef can be edited offline and then returned to the CONTROL-M database using ctmdefine. For more information, see “ctmdefine” on page 2-47.

• Creating ad hoc jobs to be inserted in the Active Jobs file based on previously defined jobs. Together with the ctmcreate utility, the ctmexdef utility can copy and modify job processing definitions in batch mode which can then be sent directly to the Active Jobs file using ctmcreate. See ctmcreate in this chapter for a complete description of the utility.

Use the following command to invoke the ctmexdef utility:

ctmexdef -TABLE <table_name> \{-JOBNAME <jobname>|-MEMNAME <memname>} \[-ACTION {CREATE|DEFINE}] \[-FILE <output_file>] \

Table 2-23 ctmexdef – Parameters


<table_name> Scheduling table containing the job processing definition.

<jobname> Name of the job. Either the JOBNAME or MEMNAME parameter is required.

<memname> Mem name of the job.

CREATE The exported flat file will use the ctmcreate format.


Utilities 2-65

The <jobname> and <memname> parameters can include mask characters as follows:

* Represents any number of characters (including no characters). Any parameter including ∗ should be enclosed in quotation marks (see example below).

? Represents any single character.

Example

To export all job processing definitions from Scheduling table PROD to file tabprod, specify the following command:

ctmexdef -FILE /tmp/tabprod -TABLE PROD -JOBNAME “*”

DEFINE The exported flat file is in ctmdefine format. Default.

<output_file_name>

Full path name of the file to contain the exported job specifications. If this parameter is not specified, the output is routed to the default output device.

Table 2-23 ctmexdef – Parameters




ctmfw

The CONTROL-M File Watcher utility (ctmfw) detects the following file processes:

• Successful completion of file transfer• Creation of a file• Deletion of a file

ctmfw can be used before activating a job or before performing a task (for example, sending a shout message or adding/deleting conditions) that is dependent upon creation or deletion of a file.

NoteThe ctmfw utility cannot be used to monitor files larger than 4GB.

The ctmfw utility runs as a process on a client machine. The process waits for the creation or deletion of specified file(s).

• For a file transfer activity, when the file is detected, the job continues to monitor the size of the file. When the file reaches a specified minimum size and does not increase in size for a specified period of time, the File Watcher utility either completes with a status of OK or executes a specified DO action. DO actions can consist of adding or deleting conditions or executing a command.

• For file creation or deletion, if a wildcard is specified as part of the filename, file size is ignored.

• For file deletion, ctmfw must first detect the existence of the file before it can detect its deletion.

The ctmfw utility can also be run from the command line.

The ctmfw utility can be invoked to detect either a single file or multiple files.


Utilities 2-67

Specify the following command to invoke ctmfw for a single file:

ctmfw <filename> [mode] [min_size] [sleep_int] [mon_int] [min_detect] [wait_time]

The parameters are described in Table 2-24, “ctmfw – Parameters,” on page 2-68.

The procedure for watching multiple files is described on page 2-69.

NoteThe parameters in this command are identified by their sequence. Although all parameters are optional, you cannot skip a parameter and assign a value to a subsequent parameter. The first value is assumed to be the desired mode, the second value is assumed to be the min_size, and so forth. If only five values are specified, the default value for wait_time is used. If four parameters are specified, default values for min_detect and wait_time are used, and so forth. For example:

ctmfw /tmp/temp1/ CREATE 100 10

is resolved using default values for mon_int, min_detect and wait-time as follows:

ctmfw /tmp/temp1/ CREATE 100 10 10 3 0



Table 2-24 ctmfw – Parameters

Param Description

filename Path of the file to be detected. The file name can include mask character * to represent any number of characters (including no characters). In this case, enclose the full path name in quotation marks (for example, “c:\ctm\a*.txt” ). When including an * as part of a file name in a Rules file, (see page 2-70), the name should not be enclosed in quotation marks. When a wildcard is used, the ctmfw utility does not monitor the size of the file.

mode CREATE Detects creation of a file. If filename includes a wildcard, the size of the file is ignored. Default. Note: If a mask is specified for the filename, the ctmfw utility will end successfully after detection of the first file that matches the specified mask.

DELETE Detects deletion of a file. When the ctmfw utility is run in this mode, it first checks for files that match the specified name. After a specified file is detected, the ctmfw utility checks at the specified interval for deletion of that file. Note: If a mask is specified as the filename, the ctmfw utility will end successfully only after all detected files that match the specified mask have been deleted.

min_size Minimum file size in bytes. This parameter is ignored when using wildcards in filename or when using DELETE mode. Default: 0 (any size detected).

sleep_int Interval between successive attempts to detect the existence/deletion of a file (in seconds). Default: 60 seconds.

mon_int Interval between attempts to monitor the size of a file after it is detected (in seconds). This parameter is ignored when using wildcards in filename or when using DELETE mode. Default: 10.

min_detect Number of attempts to monitor file size where the size remains static and greater than or equal to min_size (indicating successful creation of the file). This parameter is ignored when using wildcards in filename or when using DELETE mode. Default: 3.

wait_time Maximum time (in minutes) to run the process without detecting the file at its minimum size (CREATE) or detecting its deletion (DELETE). If the file is not detected/deleted in this specified time frame, the process terminates with an error return code, as described in Table 2-25. Default: 0 (no time limit).


Utilities 2-69

Return Codes

The return codes listed in Table 2-25 are issued by the ctmfw utility after detecting if a file is created or deleted in the specified time frame.

To watch multiple files:

Use the following command to invoke the ctmfw utility:

ctmfw -input <rules_filename>

where <rules_filename> is the complete path name of the file containing the definitions for each file to be detected.

Table 2-25 ctmfw – Return Codes

Return Code Description

0 File successfully created (file arrived in the specified time frame and file size is above or equal to the minimum specified size) or deleted.

1 File was not created or deleted in the specified time frame.

2 Indicates that the ctmfw request timed-out.Note: This return code will be issued only if the ctmfw utility is executed in command line mode.



The Rules file contains two sections:

• ON_FILEWATCH statements identifying which files to detect, specific criteria for each file, and the action to take upon detection or non-detection. Any number of ON_FILEWATCH statements can appear in a Rules file.

• Default values to use for the ON_FILEWATCH statements. The MIN-SIZE, MIN-DETECT, and WAIT-TIME parameters are the same as for a single file, see Table 2-24. Two additional parameters are available, as described in Table 2-26.

NoteAll keywords must be entered in uppercase.

If any mandatory parameter is omitted from a Rules file, the default value for that parameter is used. Parameters entered for ON_FILEWATCH statements override the default values. If entered, they must appear in the order shown in Figure 2-1.

NoteIn a Rules file, if a wildcard (*) is used in a filename in an ON_FILEWATCH statement, the name and path must not be embedded in quote marks.

Table 2-26 ON_FILEWATCH Statements – Additional Parameters


INTERVAL Sleep interval between succeeding scans for all the files. This parameter replaces the individual sleep_int and mon_int parameters for each file. Default: 10 seconds.

FROM_TIME Starting time for detecting all the files (default FROM_TIME). Used with WAIT_TIME to identify the time frame for detecting and monitoring the files. This parameter is expressed in 24-hour, hhmm format. Default: 0000.


Utilities 2-71

Figure 2-1 ON_FILEWATCH Statements#******************************************************************# Mandatory ParametersINTERVAL <60> # Sleep interval (seconds)FROM_TIME <0000> # Starting time for all files (hhmm)MIN_SIZE <0> # Minimum size for all files (bytes)MIN_DETECT <3> # Number of iterations for all filesWAIT_TIME <0> # Time limit for all files (minutes)

# ON_FILEWATCH statementsON_FILEWATCH <filename> [mode] [min_size] [min_detect] [wait_time] [from_time] [cyclic_interval]THEN <action>ELSE<action> END_ON#******************************************************************

Figure 2-1 displays a sample Rules file. In this sample:

• # indicates comments.• Default values are shown for all mandatory parameters.• from_time is the time from which to watch for the specified file

action.• cyclic_interval is the interval between multiple operations of

detecting the file (in minutes). This interval must be greater than the value for wait_time. If the cyclic_interval is 0, only one attempt to detect the file will be performed. Default: 0.

• <action> refers to any of the actions described in Table 2-27.

NoteAll key words must be entered in uppercase.

Table 2-27 ctmfw – Valid Actions

Action Description

DO_COND <condition name> <condition date> <+|->

Add (+) or delete (-) a condition.

DO_CMD <command> Execute a valid command under the command interpreter. Full path names are required for files.

DO_OK Terminate ctmfw with status OK.

DO_NOTOK [exit code] Terminate ctmfw with status NOTOK. Exit code is optional and replaces the standard return code, as described in Table 2-25.



• If the file is detected and the size remains static within the time frame (CREATE) or the file has been deleted (DELETE), the DO commands in the THEN block are executed.

• If the file is not detected/deleted within the time frame, the statements following the ELSE block are executed.

• ctmfw terminates when either all the files in the Rules file have been processed or a DO_OK/DO_NOTOK action is executed.

NoteIf any ON_FILEWATCH statement contains a cyclic_interval parameter, ctmfw will only terminate on a DO_OK/DO_NOTOK action.


Utilities 2-73

Example 1

The ctmfw utility is invoked to watch multiple conditions. A Rules file contains the definitions that the ctmfw utility uses for watching each file.

The following instructions are defined in the Rules file:

• The sleep interval between succeeding scans must be 10 seconds.• If the ctmfw utility detects that the file datafile.txt in directory

c:\controlm is created in the specified time interval, then:— condition datafile dated 1 January must be added.— The command interpreter must execute the command to move

the contents of the file c:\ctm\datafile.,txt to c:\ctm\workfile.txt.• If the ctmfw utility detects that the datafile.txt file in the

c:\controlm directory is not created in the specified time interval, then condition datafile dated 1 January must be deleted.

• When the ctmfw utility detects that the c:\ctm\tempfile.txt file is deleted, condition tempfile dated 1 January must be deleted.

#******************************************************************INTERVAL 10ON_FILEWATCH /controlm/datafile.txt CREATE THENDO_COND datafile 0101 +DO_CMD move /ctm/datafile.txt /ctm/workfile.txtELSEDO_COND datafile 0101 -END_ONON_FILEWATCH /ctm/tempfile.txt DELETETHENDO_COND tempfile 0101 -END_ON#*******************************************************************



Example 2

A job processing definition is created to implement a File Watcher job. The file must arrive between 19:00 to 22:00, and be created in the \tmp directory under the name trans.dat. The minimum file size is 100 bytes. The detection process should be performed each minute. The file size monitored every 10 seconds, and the number of intervals where the file size remains static is 5. If the file is not detected by 22:00, an alert should be sent to ENTERPRISE/CS.

Parameter Value

Job Name FileWatch

Mem Name FileWatch

Owner <control_m_user>

From Time 1900

Command line ctmfw /tmp/trans.dat CREATE 100 60 10 5 180

On Statement/Code processing:

Stmt *

Code COMPSTAT=0

Do Cond file_trans_dat_ok Date: ODAT Sign: +

Stmt *

Code COMPSTAT=1

Do Shout To: ENTERPRISE/CS Text: “File trans.dat did not arrive on time”


Utilities 2-75

ctmgrpdef

The ctmgrpdef utility creates a definition for a new Group Scheduling table.

Group Scheduling tables are used for jobs whose processing should be treated as a single unit. The definition created via this utility contains values for parameters that affect handling of the entire group.

For more information about parameters of a group definition, see the description of the Group Editing form in the CONTROL-M/Desktop User Guide.

Use the following command to invoke ctmgrpdef:

ctmgrpdef -GROUP <group_name> -APPLICATION <appl_name>

-TAG <tagname> [ -MAXWAIT <maxwait> ] [ -DAYS <daystr> ] [ -WEEKDAYS <weekdaystr> ] [ -MONTH ALL|JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC Y|N ] [ -DATE <MMDD> ] [ -DAYSCAL <days calendar> ] [ -WEEKCAL <week calendar> ] [ -CONFCAL <conf calendar> ] [ -CAL_ANDOR AND|OR ] [ -SHIFT ’>’|’<’ ]

[ -ADJUST_COND Y|N ] [ -OWNER <username> ] [ -AUTHOR <username> ] [ -DEBUG <level> ] [ -QUIET ] [ -TIMEFROM <earliest submission time> ] [ -TIMEUNTIL <latest submission time> ] [ -PRIORITY <job priority> ] [ -CONFIRM Y|N ]

[ -DESCRIPTION <string> ] [ -DOCMEM <filename> ] [ -DOCLIB <directory name> ] [ -INCOND <condition> <dateref>|ODAT AND|OR ] [ -OUTCOND <condition> <dateref>|ODAT ADD|DEL ] [ -AUTOEDIT <varname> <expression> ] [ -SHOUT OK|NOTOK|LATESUB|LATETIME|EXECTIME <destination> <urgency R|U|V> <message> [<time>] ] [ -ONGROUPEND {OK|NOTOK} [ -DOOK ] [ -DONOTOK ] [ -DOSHOUT <destination> <urgency R|U|V> <message> ] [ -DOCOND <condname> <dateref>|ODAT ADD|DEL ] [ -DOAUTOEDIT <varname> <expression> ]

[ -DOFORCEJOB <tablename> <jobname> <odate>|ODAT ][ -DOMAIL <destination> <cc> {R|U|V} <subject> <message> ]



Most parameters in the command shown above are described in detail in Chapter 5, Job Processing Parameters, in the Enterprise Controlstation User Guide. See Table 2-19 for the names under which these parameters are listed in the Enterprise Controlstation User Guide.

NoteAt least one Schedule tag must be specified (using the -TAG parameter) for each run of the ctmgrpdef utility. Definition of additional tags is optional.

Parameters not in the user guide are described in Table 2-28.

After the ctmgrpdef utility is used to create a Group Scheduling table, you will need to create job processing definitions for the table. These definitions can be created using the ctmdefine utility. See “ctmdefine” on page 2-47.

When using AutoEdit variables in cmtgrpdef parameters, an AutoEdit variable that does not contain a $ sign can be enclosed in single (‘ ’) or double (“ ”) quote marks. An AutoEdit variable that does contain a $ sign should be enclosed in single quote marks. An AutoEdit variable containing a $ sign cannot be resolved if it is enclosed in double quote marks.

Table 2-28 cmtgrpdef – Parameters


debug Level of debug messages, 1 to 5. The default value is 0 (no debug messages.

quiet If specified, no information messages are displayed during execution of the command.


Utilities 2-77

ctmjsa

ctmjsa compiles runtime data from the Statistical Details table and records it in the Statistics Summary table of the CONTROL-M database.

Each time it is run, this utility:

• Scans the statistical data for jobs that terminated with a status of OK. The jobs scanned can be limited to a range of dates as described below.

• Computes the average run time and standard deviation for each job for which data was found.

• Records the statistical data in a summary table in the CONTROL-M database (from which the data is made available to ENTERPRISE/CS).

NoteStatistical data is only accumulated when the CONTROL-M system parameter Statistics is set to Y. Operational parameter Statistics Mode determines the mode to be used to compile summary statistics: JOBNAME or MEMNAME. The default is MEMNAME.

For more information regarding runtime statistical data, see “Runtime Statistics” on page 1-28.

ctmjsa also includes an option to display the summary data filtered according to specified parameters.

Specify one of the following commands to invoke the ctmjsa utility:

ctmjsa <From Date> <To Date>ctmjsa -<Delta1> -<Delta2> <Date>ctmjsa "∗"ctmjsa -list [<Filter>]



Table 2-29 ctmjsa – Parameters


<From Date> Starting date of statistical data to be compiled. The date is specified in yyyymmdd or yymmdd format.

<To Date> Ending date of statistical data to be compiled. The date is specified in yyyymmdd or yymmdd format.

-<Delta1> Unsigned number used to establish the starting date for statistical data to be compiled. This date is determined by subtracting <Delta1> from <Date> (for example, if <Delta1> is 10 and <Date> is 991220, the starting date is 991210).

-<Delta2> Unsigned number used to establish the ending date for statistical data to be compiled. This date is determined by adding <Delta2> to <Date> (for example, if <Delta2> is 5 and <Date> is 991220, the ending date is 991225).

<Date> Date used together with <Delta1> and <Delta2> to determine the range of dates used for compiling statistical data. The date is expressed in yyyymmdd or yymmdd format.

“∗” Asterisk enclosed in quotation marks. Specifies that the utility collects all statistical data available without regard to date.

-list Display data from the Statistical Summary table filtered according to specified subparameters. Use this option after you have updated the summary table. This information is also available from ENTERPRISE/CS in the Statistics window.

<Filter> Specify one of the following options and its subparameter or leave blank to display statistics for all jobs.

-JOBNAME <jobname> Identify the job by its Job Name parameter.

-MEMNAME <memname> Identify the job by its Mem Name parameter.

-MEMLIB <memlib> Identify jobs by their Mem Lib parameter.

-NODEID <nodeid> Identify jobs by their node group parameter (Agent platform).


Utilities 2-79

NoteIf the Statistics Mode parameter is JOBNAME, Mem Name and Mem Lib fields in the Statistical Summary table are blank. If the Statistics Mode parameter is MEMNAME, the Job Name field is blank.

If the Statistics Summary table contains duplicate lines, see the bulleted item about changing Statistics Mode on page 4-34.

Each <Filter> option subparameter can include these mask characters:

* Represents any number of characters (including no characters). Any parameter that includes a * should be enclosed in quotation marks (see examples below).


Example 1

The following commands compile statistical data for the 5-day period from June 21, 2000 through June 25, 2000 (assuming this data is available). In the second command, the hyphens indicate the beginning of unsigned parameter values; they are not minus signs.

ctmjsa 000621 000625ctmjsa -3 -1 000624

Example 2

The following command compiles statistical data using all data currently available:

ctmjsa "∗"



Example 3

This command displays summary data for all jobs whose Mem Name parameter starts with “pgmac”: ctmjsa -list -MEMNAME "pgmac*"A report similar to the following is displayed:

JOBNAME MEMNAME MEMLIB NODEID CPU [sec]ELAPSED (sec)

pgmacct1 prod.acct.pgm diana 0.19 233.15

pgmacct2 prod.acct.pgm verdi 0.12 6.12




Utilities 2-81

ctmkilljob

The ctmkilljob utility terminates a specified CONTROL-M job and all its processes. ctmkilljob terminates only jobs that are currently executing.

NoteOnly jobs running on CONTROL-M/Agent version 2.2.5 and later can be terminated using ctmkilljob.

This utility can only be run interactively. Specify the following command to invoke the ctmkilljob utility:

ctmkilljob {[-orderid <unique order ID>] | [-nodeid <name>] | [-memlib <path>] | [-memname <filename>] | [-jobname <name>]}

If the action was successful, the utility responds with the statement:

Job was killed.

and the specified job is ended with a status of NOTOK.

NoteThe parameters specified for ctmkilljob must indicate one unique job. If more than one job fits the description specified in the command, you are informed that a unique name must be entered to carry out the action. Reenter the command with parameters that specify one unique job.

Table 2-30 ctmkilljob – Parameters


orderid CONTROL-M Order ID of the job to be terminated.

nodeid Host name of an Agent platform, or name of a node group to which the job should be submitted.

memlib Name of the library/directory in which the job script resides.

memname Name of the file that contains the job script statements.

jobname Descriptive reference for a job processing definition.



ctmldnrs

ctmldnrs creates and loads the Manual Conditions file. This file contains prerequisite conditions that are required by jobs in the Active Jobs file but which will not be available (that is, added to the Conditions/Resources table) unless there is some form of manual intervention.

For example:

• Conditions that are never added automatically by scheduled jobs because manual confirmation is always desired.

• Conditions that are normally added automatically by scheduled jobs but the jobs which add them are not scheduled for the day.

How to View the Manual Conditions File

Use one of the following methods to make prerequisite conditions contained in the Manual Conditions file available to the system:

• ctmcontb utility (see page 2-21).• LOAD option of ctmldnrs (see page 2-85).• Prerequisite Conditions window (see Chapter 11, “Resources and

Conditions”, in the Enterprise Controlstation User Guide).• WHY option in the ENTERPRISE/CS job menu (see Chapter 10,

“Viewing and Updating Details”, in the Enterprise Controlstation User Guide).

Identifying Conditions to be Placed in the Manual Conditions File

The ctmldnrs utility identifies conditions that should be placed in the Manual Conditions file by first performing a search for all prerequisite conditions required for submission of jobs on the particular day. The search for prerequisite conditions is performed by checking the In Conditions of the job processing definitions for all jobs in the Active Jobs file.

Once these prerequisite conditions have been identified, the utility eliminates any “non-manual” conditions from the list that satisfy either of the following criteria:


Utilities 2-83

• The prerequisite condition already exists in the Conditions/Resources table.

• The prerequisite condition is added to the Conditions/Resources table by an Out Conditions or DO COND job processing parameter in a job scheduled to run that day.

All prerequisite conditions in Conditions parameters that do not meet the above criteria are assumed to be manual conditions and are placed in the Manual Conditions file. These conditions can be limited further with the use of IGNOREx parameters passed to the utility (see below).

The ADDMODE parameter determines if the Manual Conditions file will be re-created with all previous conditions deleted from the file or whether previous conditions will be retained in the new file.

The following options are available for using this utility:

• Create the Manual Conditions file.

• List prerequisite conditions from the Manual Conditions file.

• Load prerequisite conditions from the Manual Conditions file to the Conditions/Resources table.

Creating the Manual Conditions File

» Specify the following to create the Manual Conditions file:

ctmldnrs -CALCCOND [ -ADDMODE {YES|NO}] \ [ -OUTPUT <Filename> ] \ [ -IGNOREIN <Condition Name> ] \ [ -IGNOREOUT <Condition Name> ] \ [ -IGNORECODES <Condition Name> ]



NoteMultiple IGNOREx parameters can be included in the command in any order.

Listing Prerequisite Conditions

» Specify the following command to list prerequisite conditions in the Manual Conditions file:

ctmldnrs -LIST <Condition Name> [-INPUT <Filename>]

Table 2-31 ctmldnrs – Creating a Manual Conditions File


ADDMODE • YES – When the new Manual Conditions file is created, conditions from the previous file are retained in the new file.

• NO – The Manual Conditions file is recreated and all previous conditions are deleted. Default.

OUTPUT Output file to be created. If this parameter is not specified, the default file is <controlm_user_dir>/ctmldnrs.dat.

<Filename> Full path name of the output file to be created.

IGNOREIN All conditions that satisfy the specified condition name are ignored when the file is created.

IGNOREOUT References to conditions that satisfy a condition name that is specified in Out Conditions job processing parameters are ignored by the algorithm that builds the file.

IGNORECODES References to conditions that satisfy a condition name that is specified in DO COND job processing parameters are ignored by the algorithm that builds the file.

<Condition Name>

Name of the prerequisite condition. The condition name can include the mask character ∗ to represent any number of characters (including no characters). In this instance, the condition name must be enclosed in quotation marks (for example, “LVL ∗”). Specify “∗” by itself to include all existing conditions.


Utilities 2-85

Loading Prerequisite Conditions

» Specify the following command to load prerequisite conditions from the Manual Conditions file to the Conditions/Resources table:

ctmldnrs -LOAD <Condition Name> [-INPUT <Filename>]

Example 1

The following command re-creates the default Manual Conditions file in the user’s directory:

ctmldnrs -CALCCOND -ADDMODE NO

Example 2

The following command creates a Manual Conditions file /h/mcond/data/output.dat which ignores all conditions with prefix “a”:

ctmldnrs -CALCCOND -ADDMODE NO -OUTPUT \ /h/mcond/data/output.dat \-IGNOREIN “a ∗” \-IGNOREOUT cond

Example 3

The following command loads all conditions from the default input Manual Conditions file to the Conditions/Resources table:

ctmldnrs -LOAD “ ∗”

Table 2-32 ctmldnrs – Listing or Loading Manual Conditions


<Filename> Path name of the input Manual Conditions file. If this parameter is not specified, the default input file is <controlm_user_dir>/ctmldnrs.dat .

<Condition Name> All conditions in the input file which satisfy the specified characters are loaded or listed. Specify “∗” by itself to load/list all conditions.



ctmloadset

The ctmloadset utility is used to record current resource usage on an Agent platform in the Quantitative Resources table. This utility is typically invoked by a cyclic job that runs on the Agent platform and measures usage of a certain resource on the platform. Usage data is then used to update the Quantitative Resources table on the server platform.

ctmloadset is used when load balancing is implemented. The load-balancing algorithm uses the data recorded in the Quantitative Resources table to determine to which Agent platform a job should be submitted.

CONTROL-M maintains the following information regarding usage of each Quantitative resource:

Update resource usage values in the Quantitative Resources table in either of two ways:

• Specify the value for Total Used for a resource. ctmloadset subtracts the value for Used by CONTROL-M from the value you specify and places the remainder in the field Used by Others.

• Specify the value for Used by Others for a resource. This value is added to the value Used by CONTROL-M to calculate the value Total Used for the resource.

Values for the utility can be expressed as an absolute number of units or as a percentage of the total number of units defined (Max value).

Item Description

Total Used Units of the resource currently in use. This parameter represents the sum of the values specified in the other two columns of this table (described below).

Used by CONTROL-M

Units of the resource currently in use by jobs submitted by CONTROL-M/Server.

Used by Others Units of the resource currently in use by non-CONTROL-M jobs.


Utilities 2-87

The utility’s output is displayed as type Q rows in the Quantitative Resources window. However, the field Mem Name remains blank since this represents usage by one or more non-CONTROL-M jobs.

Specify the following command to invoke the ctmloadset utility:

ctmloadset {TOTAL|OTHERS} <QR name> <Load value>[%]

Example 1

A node group contains three Agent platforms: diana, jacklin and ruby. Each platform is defined in the Quantitative Resource table as having 200 units of resource CPU_load, representing the load on the platform’s CPU.

• Platform jacklin is used exclusively to run jobs submitted by CONTROL-M. The platform is currently executing a job that uses 120 units of resource CPU_load.

• Platform ruby is used exclusively to run jobs submitted by CONTROL-M. The platform is currently executing a job that uses 150 units of resource CPU_load.

Table 2-33 ctmloadset Parameters


TOTAL Indicates that the load value provided specifies the total usage of the resource by all jobs (both CONTROL-M jobs and non-CONTROL-M jobs).

When this option is specified, the utility calculates the usage of the resource by non-CONTROL-M jobs and updates the table accordingly.

OTHERS Indicates that the load value provided specifies the units of the resource used by one or more non-CONTROL-M jobs.

<QR name> Name of the Quantitative resource to update.

<Load value>

Number of units of the resource currently used.-or-When % is specified, the amount of the resource currently used, expressed as a percentage of the maximum available units defined for this Quantitative resource.



• Platform diana is used both for CONTROL-M and non-CONTROL-M jobs. The platform is currently executing a job submitted by CONTROL-M that uses 75 units of resource CPU_load.

A cyclic job is defined to run periodically on diana to measure the total load on the CPU. The job updates the Quantitative Resources table using the ctmloadset utility to indicate to CONTROL-M exactly what the load is on that platform. The last run of this job determined that the load on the CPU is 80% of total capacity. The job invokes ctmloadset as follows:

ctmloadset TOTAL CPU@diana 80%

The Total Used for diana is set to 80% of 200, or 160. Since the usage by CONTROL-M jobs is currently 75 units, ctmloadset calculates that the “Other” (non-CONTROL-M usage) is 160 – 75, or 85.

As a result, the Quantitative Resources table now contains the following values:

The CONTROL-M load-balancing algorithm uses these values when determining where to submit the next job.

Example 2

The following examples demonstrate the effect of ctmloadset on the Quantitative Resources table, as represented by the display generated by the ecaqrtab utility. All examples below are based on the following premise:

For agent platform diana, 30 units of resource CPU@diana are currently used by CONTROL-M jobs.

Resource MaxTotal Used by CONTROL-M

Total Used by Others Free

CPU@jacklin 200 120 80

CPU@ruby 200 150 50

CPU@diana 200 75 85 40


Utilities 2-89

The output from the ecaqrtab utility is as follows:

Example 3

The following command specifies that the current usage of the Quantitative resource CPU@diana by non-CONTROL-M jobs is 12 units:

ctmloadset OTHERS CPU@diana 12

As a result, the output from the ecaqrtab utility is now as follows:

Example 4

The following command specifies that the current usage of the Quantitative resource CPU@diana by non-CONTROL-M jobs is 12%:

ctmloadset OTHERS CPU@diana 12%

The non-CONTROL-M usage of the resource is calculated as 12% of 50, or 6 units. As a result, the output from the ecaqrtab utility is now as follows:

Resource Name Type Max-Avail Reserved Used Free

CPU@diana L 50 0 30 20







Example 5

The following command specifies that the current total usage of the Quantitative resource CPU@diana by all jobs is 48 units:

ctmloadset TOTAL CPU@diana 48

As a result, the output from the ecaqrtab utility is now as follows:




Utilities 2-91

ctmlog

ctmlog is used to create a report from entries in the CONTROL-M log or to delete entries in the CONTROL-M log.

Specify one of the following commands to invoke the ctmlog utility:

ctmlog <Action> <Action Option> \ <From date> <From Time> <To Date> <To Time> \ [<Output> [<Report Width>] ]

ctmlog <Action> <Action Option> "∗" \ [<Output> [<Report Width>] ]

Valid values for <Action> and <Action Option> are listed in Table 2-34. All other parameters of this utility are described in Table 2-35.

NoteAll actions are limited to log entries in the range specified using the time and date parameters.

Table 2-34 ctmlog – Valid Actions (Part 1 of 2)

Action Action Option

listss Prints a report for a specific subsystem

<subsystem> Subsystem to include in the report. Specify one of the following:• SU Supervisor• TR Tracker• SL Selector• CD Download, Database

update• NS Communication with Agent

platforms• LG Agent utilities• UT Utilities• WD Watchdog

list Prints a report of all entries. None.



listord Prints a report of entries for a specific Order ID.

<Order ID> Order ID to include in the report.Note: The Order ID as displayed in the Job Details window of ENTERPRISE/CS is a base 36 number. If you want to specify the Order ID here as a base 10 number, precede the number with an asterisk and enclose the result in quotation marks (for example, “∗1234”).

listjob Prints a report including all entries for a specific job number.

<Job no.> Job number to include in the report.

listmsg Prints a report of messages with a specific message ID.

<msgid> Message ID to include in the report.

delete Deletes entries in a specified date and time range.

None

listjobname Prints a report including all entries for the specified job name.

<jobname> The name of the job whose entries should be printed in the report.

Table 2-35 ctmlog – Parameters


<From Date><From Time><To Date><To Time>

Starting and ending dates and times for the range of entries to be scanned by the specified action. Date is specified in yyyymmdd format. Time is specified in hhmm format.

“∗” Asterisk enclosed in quotation marks. Scan all entries in the CONTROL-M log (without regard to date or time).

<Output> Full path name to which the report should be sent (optional). If this parameter is not specified, the output is routed to the default output device. This parameter is not applicable for the delete action.

<Report Width> Width (in columns) of the report to generate. Specify a number in the range of 80 – 132 (default is 80). This parameter can only be specified if the Output parameter is specified.

Table 2-34 ctmlog – Valid Actions (Part 2 of 2)

Action Action Option


Utilities 2-93

Example 1

The following command produces a report of all entries in the CONTROL-M log between 10:00 A.M. March 12th, 1999 and 8:00 A.M. March 14th, 1999. The report is output to file rprt.txt in 80-column format:

ctmlog list 19990312 1000 19990314 0800 /ctm/user1/rprt.txt

Example 2

The following command produces a report of all entries in the CONTROL-M log relating to downloads to the ENTERPRISE/CS database and to CONTROL-M database updates, without regard to date or time. The report is output to file gdrprt.txt in 132-column format:

ctmlog listss CD "∗" /ctm/user1/gdrprt.txt 132



ctmordck

The ctmordck utility lists job processing definitions associated with a specific User Daily name and indicates the security status of each job with regard to the owner of the User Daily job (that is, whether or not the CONTROL-M security mechanism will allow jobs associated with a User Daily name to run with the authorizations currently assigned to the owner of the User Daily job).

This utility displays the following fields:

• Name of the job.• Number of the job in the CONTROL-M database.• Author of the job processing definition.• Owner of the job processing definition.

The following information is displayed for each job processing definition:

NoteThis utility can be used non-interactively for non-terminal destinations (see the description of the <Output> parameter below).

Specify the following command to invoke the ctmordck utility:

ctmordck <User Name> <User Daily> [<Output>]

Table 2-36 ctmordck – Output Columns

Column Description

TB Whether or not the owner of the User Daily job is authorized to order the Scheduling table of the job listed.

FL Whether or not the owner of the User Daily job is authorized to execute the script file of the job listed.

UA Whether or not the owner of the User Daily job is authorized to order jobs for the owner of the job listed.


Utilities 2-95

Example

The following command generates a list for user SYSTEM and the User Daily SYSTEM. The list is directed to the udlist file:

ctmordck SYSTEM SYSTEM /ctm/user1/udlist

The following is sample output from the above command:

Figure 2-2 ctmordck Sample Output

Date: 10-NOV-2000. Page: 1 User SYSTEM , Daily SYSTEM Ordering list

JOBNAME No. AUTHOR OWNER TB FL UA---------- --- ------ ----- -- -- --CTMLOG HAN 2066 root root Y N YPURGE JOB 2067 root root Y N Yuser3-DAIL 2033 BARRY user3 Y N Yuser2-DAIL 2032 STEVE user2 Y N Yuser1-DAIL 2031 STEVE user1 Y N YJEAN-UD 2000 jean jean Y N YJOB-STATUS 2068 root root Y N YGD-TEST1 20 jean user1 Y N YGD-TEST2 21 jean user2 Y N YGD-TEST3 22 jean user3 Y N YGD-user4 2008 jean user4 Y N YGD-user5 2009 jean user5 Y N Y

Table 2-37 ctmordck – Parameters


<User Name> Owner of the User Daily job.

<User Daily> User Daily name.

<Output> Full path name to which the report should be sent. If this parameter is not specified, the output is routed to the default output device.



ctmorder

ctmorder orders or forces one or more jobs from a Scheduling table in the CONTROL-M database.

• Ordered jobs are placed in the Active Jobs file if their scheduling criteria are met.

• Forced jobs are placed in the Active Jobs file regardless of their scheduling criteria.

If two jobs with the same name exist in a Scheduling table and you use the ctmorder utility to force a job with that name, only the first job is forced.

NoteIf the ctmorder utility is running when the New Day procedure begins, it is automatically suspended until New Day procedure is ended.

Syntax

The ctmorder utility can be invoked using either of two formats.

• The first format includes a limited number of parameters in a specific order:

ctmorder <scheduling table> <job name> <odate> / [{order|force}]

NoteThis short format cannot be used on CONTROL-M/Agents. Use the second, more explicit format described below.


Utilities 2-97

• The second format allows specification of more details and requires each parameter to be named. The parameters in this format can be specified in any order. This format is as follows:

ctmorder -schedtab <scheduling_table> \-jobname <job_name> \-odate <odate> \[-force {y|n>}] \[-seqno <job_sequence_number>] \[-ingrouporderid <group_order_id>|last|alone|newg]\[-debug <level>] \[-quiet] \[-noduplication] \[-autoedit <variable> <expression>]

NoteAs of CONTROL-M version 6.0.00, the ctmorder utility can be accessed using a command line interface only. The interactive interface available in earlier versions is no longer supported.

All parameters of the ctmorder utility are described in Table 2-38.

Table 2-38 ctmorder – Parameters (Part 1 of 3)


-schedtab Name of the Scheduling table containing the jobs.

-jobname Job name (or mask) of the job(s) to order or force.

You can order a group scheduling table, but you cannot order an individual job, or selection of jobs, from a Group Scheduling table.

The specified job name can include mask characters as follows:• * indicates any number of characters (or no characters at

all). Specify * by itself to include all jobs in the table. Note: Any parameter including * must be enclosed in double quotes (see the example provided below).

• ? Represents any single character.



-odate Date to use as the job’s scheduling date. Specify a date in yyyymmdd format, or specify the keyword ODAT to use the current CONTROL-M date.

-force Add the specified jobs to the Active Jobs file regardless of scheduling criteria. If -force is not specified, jobs are added to the Active Jobs file only if their scheduling criteria are satisfied (known as order).

Y Force the specified jobs.

N Order the specified jobs. Default.

-seqno A counter identifying the row number of the job in the Scheduling table. The first job in each Scheduling table is numbered 1 and each subsequent job increments the counter by one. If this parameter is not specified, the first job in the specified table is ordered.

-ingrouporderid Note: This parameter is relevant only for jobs in a Group Scheduling table.

<group_order_ID> Order ID of an existing Group Scheduling table.

last The specified jobs are added to the last ordered instance of their Group Scheduling table in the Active Jobs file.

alone The specified jobs are ordered individually. They are not associated with any Group Scheduling table.

Note: group_order_ID, last and alone options can only be used when -force parameter is set to Y.

newg A new group is created and the specified jobs are ordered to that Group Scheduling table. Default.

-debug level Activates a debug trace at the specified level.Valid levels are 0 – 5. Default: 0Performance is somewhat slower when operating in debug mode. It is recommended that you activate debug mode only when requested by Technical Support.

-quiet Suppresses display of the utility output. If specified, no information messages are displayed during execution of the command.




Utilities 2-99

NoteIf neither ORDER nor FORCE is included in the command activating this utility, the specified jobs are ordered.

Example 1

The following command orders all jobs contained in Scheduling table ACCT100. Any jobs placed in the Active Jobs file will have the current CONTROL-M date as their original scheduling date:

ctmorder -schedtab ACCT100 -jobname “*” -odate odat

Example 2

The following command orders all jobs contained in the Scheduling table ACCT100 whose job name begins with ga. Any jobs placed in the Active Jobs file will have the date March 15, 2000 as their original scheduling date:

-noduplication Allow jobs to be ordered and added to an existing ordered Group Scheduling table only if those jobs have not already been ordered in that instance of the Group Scheduling table.This parameter can be specified only if last or <group_order_ID> is specified for the -ingrouporderid parameter.Note: This parameter is relevant only for jobs in a Group Scheduling table.

-autoedit Assigns an AutoEdit variable to a new Group Scheduling table.This parameter can be specified only if newg is specified for the -ingrouporderid parameter.For more information, see the description of AutoEdit Facility in the Enterprise Controlstation User Guide. The following information must be specified for each new AutoEdit variable.

<variable> Name of the variable.

<expression> Value assigned to the variable.





ctmorder -schedtab ACCT100 -jobname "ga*" \-odate 20000315 -force y

Example 3

The following command forces all jobs contained in the Scheduling table ACCT100 whose job name is prodyjob. Any jobs placed in the Active Jobs file will have the date December 31, 2000 as their original scheduling date:

ctmorder -schedtab ACCT100 -jobname prodyjob \-odate 20001231 -force y

Example 4

The following command forces the third job contained in the Group Scheduling table ACCT200 whose job name parameter consists of prodyjob. This job is placed in the Active Jobs file and will have the date December 31, 2000 as its original scheduling date. This job is added to an active group whose orderid is B2.

ctmorder -schedtab ACCT200 -jobname prodyjob \-odate 20001231 -force y -seqno 3 -ingrouporderid B2

Example 5

The following command assigns the AutoEdit variable %%PRDNDATE with the value of %%ODATE, and orders every job in the PRODUCTION Group Scheduling table whose job name has a prefix of PRDN. These jobs are placed in the Active Jobs file in a new group and are assigned December 31, 2000 as their original scheduling date.

ctmorder -schedtab PRODUCTION -jobname “PRDN*” \-odate 20001231 -force n -ingrouporderid newg \-autoedit ‘%%PRDNDATE’ ‘%%ODATE’


Utilities 2-101

Example 6

The following command orders every job in the INVENTORY Group Scheduling table whose job name has a prefix in the range BIN_A1 to BIN_A9. These jobs are placed in the Active Jobs file in a new Group Scheduling table, and are assigned December 31, 2001 as their original scheduling date. The APPLICATION and OWNER parameters of these jobs are modified to STOCK_COUNT and STOREMAN, respectively.

ctmorder -schedtab INVENTORY -jobname “BIN_A?” \-odate 20011231 -force n -ingrouporderid newg \-autoedit ‘%%PRDNDATE’ ‘%%ODATE’ \-autoedit ‘%%APPLIC’ ‘STOCK_COUNT’ \-autoedit ‘%%OWNER’ ‘STOREMAN’



ctmpasswd

The ctmpasswd utility enables the administrator to change the CONTROL-M User’s password for accessing the database. Only an administrator can change the password.

To invoke the ctmpasswd utility, specify the following command:

>ctmpasswd

The system will prompt you to enter the old password:

Please enter the old password for CONTROL-M account:

1. Enter the old password for the CONTROL-M account. The system will prompt you to enter the new password:

Please enter the new password for CONTROL-M account:

2. Enter the new password for the CONTROL-M account. Make sure that the password consists of at least 6 characters. Note that you will not see your entry on the screen. The system will then prompt you to enter the password again:

Enter again to verify:

3. Re-enter the new password for the CONTROL-M account. The system will respond with the message that the password was successfully changed:

Password was successfully changed


Utilities 2-103

ctmping

The ctmping utility detects and collects configuration information about CONTROL-M/Agents. This utility can also connect Agents that are already in the database, and test communication between them and the CONTROL-M/Server.

Notectmping can be included in the Watchdog process. See “Watchdog Facility” on page 1-44 for details.

This utility can check if an Agent is down and, if necessary, register it in the database as unavailable. When the Agent again becomes available, the state of the Agent is changed and information about it is gathered by a CONTROL-M process.

To invoke the ctmping utility, specify the following command:

ctmping -nodeid <agent_name> [-file <path_name>] \ [-discover {y|n}] \ [-debug <level>] \ [-quiet]

Table 2-39 contains descriptions of the parameters in this command.

Table 2-39 ctmping – Parameters (Part 1 of 2)


-nodeid Host name of the Agent platform to be pinged (tested). At least one Node ID must be specified for each run of the ctmping utility. Additional Node IDs can optionally be specified to enable a single run of this utility to test communication with more than one Agent platform.

-file Full path name of a file containing a list of Agents to be pinged. Each line in the specified file contains the hostname or IP address of an Agent.



Example 1

To connect and perform a communication test with the Agent jacklin, specify the following command:

ctmping -nodeid jacklin

The response is:

Agent: jacklin is alive

Example 2

To attempt to connect and test communication with the Agent diana which is currently down, specify the following command:

ctmping -nodeid diana

The response is:

Agent: diana, Msg: Agent not available.Add it to the database? y/n:

-discover Indicates whether to update the database.Y – Update the database with information gathered by the utility.N – Do not update the database. Default.

-debug Activates a debug trace at the specified level. Valid levels: 0 through 5. Default: 0. Performance is slower when operating in debug mode. It is recommended that you activate debug mode only when requested by Technical Support and use the specified level.

-quiet Suppresses display of utility output.

Table 2-39 ctmping – Parameters (Part 2 of 2)



Utilities 2-105

Example 3

To connect and test communication with the Agent jacklin and collect configuration information needed for the discovery process, specify the following command:

ctmping -nodeid jacklin -discover y

The response is:

Agent: jacklin is alive

Example 4

To connect and test communication with the Agent jacklin and generate a debug trace without displaying the results on screen, specify the following command:

ctmping -nodeid jacklin -debug 1 -quiet

Only the return code of the utility will indicate if it was successful. The debug trace information is saved to the following file:

ctm-home\ctm\proclog\ping<PID>.<PID>

where PID is the Process Identity number.



ctmpsm

The ctmpsm utility can be invoked interactively to display the CONTROL-M Production Support menu. This menu is used to perform functions affecting jobs or conditions in the active environment of the data center. It provides an alternative to using the ENTERPRISE/CS GUI and enables you to perform many of the GUI functions directly in the data center.

NoteThe ctmpsm utility can also be invoked by the Command Line Interface, as described in “Command Line Invocation” on page 2-115.

To invoke the ctmpsm utility interactively:

1. Log on to the Server platform as the CONTROL-M/Server owner (for example, user controlm).

2. Specify the command: ctmpsm.

The following menu is displayed:

Figure 2-3 ctmpsm – Production Support Menu

Active Jobs File Resource Map---------------- ------------

1) List All 61) Control Resources 2) List All (Show Started/Ended) 62) Quantitative Resources 3) List All (Show Application) 63) Prerequisite Conditions 4) List All (Show Mem Name) 64) Control Resources Usage

65) Quantitative Resources Usage 5) List Jobs That Ended OK 6) List Jobs That Ended NOTOK 7) List Submitted/Executing Jobs 8) List Cyclic Jobs 9) List Jobs Waiting for Time Window10) List Jobs Waiting for Confirmation

Scheduling Functions--------------------

40) List Application/Group Tree 71) Scheduling Tables41) List Scheduling Tables 72) Order Tables/Jobs42) List Group Entities

Q) Quit

Enter Option:


Utilities 2-107

The functions in this menu are divided into three categories:

• Active Jobs File functions provide various views of the Active Jobs file. Each view displays information about the jobs and provides options to perform such actions on the jobs as Hold, Free, Delete, Rerun, Why, Confirm, View or modify job details, and view the CONTROL-M log.

• Resource Map functions enable you to view and modify Quantitative resources, Control resources, and prerequisite conditions. The first three of these functions activate the ecactltb, ecaqrtab, and ctmcontb utilities respectively.

• Scheduling Functions enable you to order or force Scheduling tables or specific jobs in Scheduling tables. You can also generate monthly or yearly scheduling plans using the ctmrpln utility.

Active Jobs File Options

Perform various tasks using information in the Active Jobs file. These options are described in Table 2-40 below.

Table 2-40 ctmpsm - Menu Options for Active Jobs File (Part 1 of 2)

Code Option Description

1 List All Lists all jobs in the Active Jobs file.

2 List All(Show Started/Ended)

Lists all jobs in the Active Jobs file. Indicates which jobs have started or ended execution.

3 List All(Show Application)

Lists all jobs in the Active Jobs file. Indicates the application to which each job belongs.

4 List All(Show Mem Name)

Lists all jobs in the Active Jobs file. Indicates the Mem Name for each job.

5 List Jobs ThatEnded OK

Lists jobs in the Active Jobs file with a completion status of Ended OK.

6 List Jobs That Ended NOTOK

Lists jobs in the Active Jobs file that have a completion status of Ended NOTOK.

7 List Submitted/Executing Jobs

Lists jobs in the Active Jobs file that are currently executing.



All Active Jobs file options display the following menu at the bottom of the screen:

Figure 2-4 ctmpsm - Active Jobs File Menu Options

H) Hold, F) Free, D) Delete, U) Undelete, R) Rerun, W) Why, Z) DetailsLO) LogOrd, LJ) LogJob, C) Confirm, Sx)Sort[x: 1.ORDERNO 2.JOBNAME]J) Sysout A) Statistics V) View Script/JCL K) Force OK I)Dependencies JobsGx) Global action x [x: H(Hold), F(Free), D(Delete), U(Undelete), R(Rerun)]Q)QuitEnter Option:

These actions are described in Table 2-41:

8 List Cyclic Jobs Lists jobs in the Active Jobs file that are cyclic.

9 List Jobs Waiting for Time Window

Lists jobs in the Active Jobs file that are waiting to begin executing based on the time specified in their Time From parameter.

10 List Jobs Waiting for Confirmation

Lists jobs in the Active Jobs file that are waiting for confirmation.

40 List Application/Group Tree

Displays a summarized list of the applications and groups for all jobs currently contained in the Active Jobs file.

41 List Scheduling Tables Displays a list of all Scheduling tables in the Active Jobs file.

42 List Ordered Groups Displays a list of all CONTROL-M groups in the Active Jobs file.

Table 2-40 ctmpsm - Menu Options for Active Jobs File (Part 2 of 2)



Utilities 2-109

Table 2-41 ctmpsm - Active Jobs File Actions (Part 1 of 2)

Option Action Description

H Hold Hold a job.

F Free Free a previously held job.

D Delete Mark a job for deletion.

R Rerun Rerun a job.

U Undelete Undelete a job marked for deletion.

W Why Display why a job has not yet been submitted.

Z Details View or modify a job’s parameters. This is also referred to as zooming and saving a job’s parameters.Note1: When a job is being viewed, it is automatically held. After changes are made and saved, the job is freed.Note2: If prerequisite conditions are added to or deleted from a job in the Active Jobs File with the Z option, the changes are automatically saved when you quit.

LO LogOrd List CONTROL-M log entries for a specific Order ID.

LJ LogJob List CONTROL-M log entries for a specific Job Name.

C Confirm Confirm submission of a job.

S1 Sort (by Order No.) Sort jobs displayed by Order number.

S2 Sort (by Job Name) Sort jobs displayed by Job Name.

J Sysout Display the jobs sysout.

A Statistics Display the job statistics (last 20 runs).

V View script/JCL View a job’s script or JCL.Note: This option is not available if CONTROL-M/Server is not active.

K Force OK Force a job’s status to be OK.

I Dependencies Jobs Displays all jobs that have conditions that depend on the specified job.

GH Global Action (Hold) Hold all jobs in the displayed list.

GF Global Action (Free) Free all jobs in the displayed list.

GD Global Action (Delete) Mark all jobs in the displayed list for deletion.

GR Global Action (Rerun) Rerun all jobs in the displayed list.



Resource Table Options

Scheduling Function Options

GU Global Action (Undelete) Undelete all jobs marked for deletion.

Note: The R (Rerun) option and the Global options (GH, GF, GD, GR, and GU) affect only jobs and not group scheduling tables.

Table 2-42 ctmpsm - Menu Options for the Resource Table


61 Control Resources Lists Control resources currently used in the Active environment. This option activates the ecactltb utility.

62 Quantitative Resources Allows you to list, add, modify or delete Quantitative resources in the Active environment. This option activates the ecaqrtab utility.

63 Prerequisite Conditions Allows you to view, add or delete prerequisite conditions in the Active environment. This option activates the ctmcontb utility.

64 Control Resources Usage Shows current usage of Control resources by jobs in the Active Jobs file.

65 Quantitative Resources Usage

Shows current usage of Quantitative resources by jobs in the Active Jobs file.

Table 2-43 ctmpsm - Menu Options for Scheduling Functions


71 Scheduling Tables Lists Scheduling tables and jobs defined in theCONTROL-M database. Allows you to force Scheduling tables or jobs, associate User Dailies with Scheduling Tables, and generate scheduling reports.

72 Order Tables/Jobs Allows you to order Scheduling tables or jobs. You are prompted to specify the Scheduling table, Job Name (optional) and Odate for the table or job to order.

Table 2-41 ctmpsm - Active Jobs File Actions (Part 2 of 2)

Option Action Description


Utilities 2-111

When the Scheduling Tables option is selected, output similar to the following is displayed:

Figure 2-5 List of Scheduling Tables output by the ctmpsm utility

Scheduling Tables ----------------- Table name Daily name Table type 1) supply Quarterly GROUP 2) temp REGULAR 3) inventory GROUP 4) Payroll Monthly GROUP 5) inventory SYSTEM GROUP 6) RE_SYSOUT vitaly REGULAR

D#) Delete UserDaily Table # U#) Update table #F#) Force table # J#) List jobs #A) Add R) Remove Table Q) Quit.

Option []:

The options in Table 2-44 are available from the above screen.

NoteIf a table that is associated with more than one User daily is modified using ENTERPRISE/CS and then uploaded to CONTROL-M, that table is removed from all User dailies except the one that is associated with it in ENTERPRISE/CS.

Table 2-44 ctmpsm - Options for Scheduling Functions


A Add Associates a User Daily with a Scheduling Table. When selected, you are prompted for the Table name and its associated User Daily name. Both the Schedule Table and the User Daily should already exist in the database.

R Remove Deletes a specific Scheduling table and all its associated jobs (for example, specify R RE_SYSOUT to delete table RE_SYSOUT).



When the List Jobs # option is selected, output similar to the following is displayed:

D# Delete # Removes an instance of a scheduling table from the CONTROL-M database.• If the specified instance is the only instance of the table (that is,

that table is ordered by only one user daily), the scheduling table and all its associated jobs are deleted.

• If the specified instance is not the only instance of the table, then only the specified instance is removed from the CONTROL-M database.

F# Force table # Forces a specific Scheduling table (for example, specify F6 to force table RE_SYSOUT).The following prompt is displayed:Odate (YYYYMMDD/ODAT) [ODAT]:Enter the odate for the job to be forced in YYYYMMDD format, or enter the value ODAT to indicate that the job should use the current working date as its odate.

If the specified table is a Group Scheduling table, the following prompt is displayed:Please choose one of the following:A) Alone.N) New group.L) Last.B) Bind to existing group Orderno.These options are described below:• A – Forces each job in the table separately as a non-group job.• N – Forces the jobs in the table as a new group in the Active Jobs

file.• L – Forces the jobs in the table, and adds them to the most

recently ordered group in the Active Jobs file.• B – Forces the jobs in the table, and adds them to a specified

group in the Active Jobs file.

J# List jobs # Lists jobs in a Scheduling table and provides options to force a specific job or generate a report (for example, specify J1 to list the jobs in table supply).

U# Update table # Updates the User Daily name for a specific Scheduling table (for example, specify U6 to update the User Daily name for table RE_SYSOUT).

Table 2-44 ctmpsm - Options for Scheduling Functions



Utilities 2-113

Figure 2-6 List of Jobs output by the ctmpsm utility

Scheduling Table RE_SHED Jobs-----------------------------

1) Jobname:DAYS_CAL_N, Memname:DAYS_CAL_NONE2) Jobname:DAYS_30_FE, Memname:DAYS_30_FEB3) Jobname:DAYS_28_29, Memname:DAYS_28_29_FEB4) Jobname:NO_CALENDA, Memname:NO_CALENDAR5) Jobname:DATES_0101, Memname:DATES_0101_02026) Jobname:DATES_2902, Memname:DATES_29027) Jobname:DAYS_CAL_M, Memname:DAYS_CAL_MINUS8) Jobname:DAYS_CAL_P, Memname:DAYS_CAL_PLUS 9) Jobname:DAYS_CAL_W, Memname:DAYS_CAL_WITHOUT

10) Jobname:CALENDAR_O, Memname:CALENDAR_ONLY11) Jobname:wdays_all , Memname:WDAYS_ALL12) Jobname:wdays_1_2_, Memname:WEEKDAYS_1_2_3

Q) Quit. F#) Force job #M#) Month Schedule Plan # Y#) Year Schedule Plan for job #

Option []:

The options in Table 2-45 are available from the above screen.

The ctmpsm utility can display the sysout for a specified order ID and runcount.

To display the sysout for a given order ID and runcount, invoke the following command:

ctmpsm -listsysout <order ID> [-sysoutnumber <number>]

Table 2-45 ctmpsm - Options in the Scheduling Table List Jobs Menu


F# Force job # Forces a specific job (for example, specify F2 to force job DAYS_30_FEB).

M# Month Schedule Plan Generates a monthly Job Order report for the table. You are prompted to enter the year and month in format YYYYMM.

Y# Year Schedule Plan for job # Generates a yearly Job Order report for a specific job. You are prompted to enter the year in format YYYY.



Examples

To display the most recent sysout of the job whose order ID is 1234, specify the following command:

ctmpsm -listsysout 1234

To display the second sysout of the job whose order ID is 1234, specify the following command:

ctmpsm -listsysout 1234 -sysoutnumber 2

The ctmpsm utility redirects the display of the sysout of a job to the viewer defined by parameter CTMPSM_VIEWER. This parameter is specified in the ctm/config.dat file. If no viewer is specified, the more viewer opens in the active screen.

If the viewer opens in a new window, the DISPLAY environment variable should be set to your host name. For more consult your Unix Administrator.

To specify the CTMPSM_VIEWER parameter in the config.dat file, type the following:

CTMPSM_VIEWER <viewer command>

where <viewer command> is the name of the viewer application selected by the user for displaying the sysout.


<order ID> The order ID of a job.

<number> A counter incremented by one each time a job is run. Default: the runcount number of the most recent run of the specified job.


Utilities 2-115

Example

To specify the CTMPSM_VIEWER parameter in the config.dat file, opening a viewer in a new window and showing the sysout using the switch more:

CTMPSM_VIEWER xterm -e more

Command Line Invocation

The format and valid values for each mode of the ctmpsm utility command line interface are described in Table 2-46.

Table 2-46 ctmpsm - Mode Descriptions and Syntax

Mode Description

CHILD Lists dependent jobs with IN conditions that are created by the job whose order ID is specified in this command.

Syntax:

ctmpsm -CHILD <order_ID> [<tasktype>]

order_ID Identifies the “parent” job.

tasktype B=batch jobD=detachedC=commandU=dummy

IMPORT_CAL Imports a calendar from the Enterprise Controlstation.ctmpsm -IMPORT_CAL <file_name>where file_name is the full pathname of the calendar file to be uploaded from Enterprise Controlstation.

LISTCAL Lists available calendars. The list can be restricted by calendar name and year.ctmpsm -LISTCAL [<Calen_name>][<Calen_year>]

Calen_name Restricts the list to calendars with the specified name or prefix (indicated by * at the end).

Calen_year Restricts the list to calendars for the specified year.



LISTALL Lists jobs in the Active Jobs file. The list can be filtered by time, application, and member name. The list can be sorted by order ID or job name.

Syntax:

ctmpsm -LISTALL [TIME|APPLICATION|MEMNAME|ALL|ALLFIELDS] [-SORT {ORDERID|JOBNAME}]

In addition to the order ID and the job name, one of the following fields can also be included in the LISTALL output:TIME _ Time execution started and ended.APPLICATION _ Application to which the job belongs.MEMNAME _ Member name for the job.ALL – Includes ODAT and TIME fields.ALLFIELDS – Includes ODAT, MEMNAME, and APPLICATION fields.

–SORT indicates the order in which the jobs should be listed. Valid orders are: ORDERID, and JOBNAME .

LISTJOB List in Active Jobs file with a specified status. Jobs can be restricted by status: OK, NOTOK, executing, cyclic, waiting for the end of a time interval, waiting for confirmation.

ctmpsm -LISTJOB {OK|NOTOK|EXECUTING|CYCLIC| WAITTIME|WAITCONFIRM} [-SORT {ORDERID|JOBNAME}]

OK _ Jobs with a completion status of Ended OK.NOTOK _ Jobs with a completion status of Ended NOTOK.EXECUTING _ Jobs that are currently executing.CYCLIC _ Jobs that are cyclic.WAITTIME _ Jobs waiting to begin executing based on the time specified in their Time From parameter.WAITCONFIRM _ Jobs waiting for confirmation.

–SORT indicates the order in which the jobs should be listed. Valid orders are: ORDERID, and JOBNAME .

LISTGROUP Lists jobs in the specified group that are associated with the specified application.ctmpsm -LISTGROUP <application> <group>

Wildcards can used as part of the specified application or group names.* represents any number of characters.? represents any single character.

Mode Description


Utilities 2-117

LISTAJFTAB Lists jobs in the Active Jobs file that were ordered from the specified scheduling table.ctmpsm -LISTAJFTAB <table_name>

Wildcards can used as part of the specified table name.* represents any number of characters.? represents any single character.

SCHEDTAB Lists Scheduling tables and jobs defined in the CONTROL-M database, and allows you to add or delete Scheduling tables.

Syntax

ctmpsm -SCHEDTAB {-LISTTABLE <table_name>|-UPDATE <row_number> <udaily_name>|-ADD <table_name> <udaily_name>|-DUDAILY <row_number>|-REMOVE <table_name>|-LISTJOBS <row_number>}

The options in this command are described below:

-LISTTABLE Lists all instances of scheduling tables that match the specified name or mask. For example, if a scheduling table is ordered by two different user dailies, that table will appear twice in the output of this option.

Wildcards can used as part of the table name for this option.* represents any number of characters.? represents any single character.

-UPDATE Updates the User Daily name for a specific Scheduling table.

-ADD Adds a Scheduling table to the CONTROL-M database. The Table name and User Daily name must be specified when this option is used.

-DUDAILY Removes an instance of a scheduling table from the CONTROL-M database.• If the specified instance is the only instance of the table

(that is, that table is ordered by only one user daily), the scheduling table and all its associated jobs are deleted.

• If the specified instance is not the only instance of the table, then only the specified instance is removed from the CONTROL-M database.

-REMOVE Deletes a specific Scheduling table and all its associated jobs.

-LISTJOBS Lists jobs in a Scheduling table.

Mode Description



LISTSYSOUT List the sysouts for an order ID. The list can be restricted by runcount number.

Syntax:

ctmpsm -LISTSYSOUT <order_ID> [SYSOUTNUMBER {<number>|ALL}]

order_ID Identifies the job whose sysouts are listed.

number Restricts the list to the sysout whose runcount is specified.If ALL is specified, the output will contain only a list of all sysouts related to the specified order ID.

LISTDETAILS Lists the details of the job associated with the specified order ID.Valid syntax is:LISTDETAILS <orderid>

UPDATEAJF Performs a specified command or updates conditions for a job in the Active Jobs that is associated with a specified order ID.

Syntax

ctmpsm -UPDATEAJF <order ID> <command>Where command is one of the following:• HOLD _ Set a job’s status to HELD.• FREE _ Free a previously held job.• DELETE _ Mark a job for deletion.• UNDELETE _ Undelete a job marked for deletion.• RERUN _ Rerun a job.• CONFIRM _ Confirm submission of a job.• FORCEOK _ Force a job’s status to be OK.• CONDADDIN <cond> <date> <AND|OR> _ Add the specified IN condition with

the specified date reference. You can include one or more additional IN conditions by using the AND or OR conjunctional parameter.

• CONDADDOUT <cond> <date> <+|-> _ Add the specified OUT condition with the specified date reference. Use + to indicate that the condition must be present. Use - to indicate that the condition must not be present.

• CONDDELIN <cond> _ Delete the specified IN condition.• CONDDELOUT <cond> _ Delete the specified OUT condition.Note: Conditions specified using this mode are applied only to the specified instance of the job in the Active Jobs file. Subsequent orders of that job are not affected by these changes.

Mode Description


Utilities 2-119

UPDATEGROUP Applies a specified command to jobs in the specified group that are associated with the specified application.ctmpsm -UPDATEGROUP <application> <group> <command>

Where <command> is one of the following:• HOLD _ Set the jobs’ status to HELD.• FREE _ Free previously held jobs.• DELETE _ Mark the jobs for deletion.• UNDELETE _ Undelete the jobs marked for deletion.• RERUN _ Rerun the jobs.• CONFIRM _ Confirm submission of the jobs.

UPDATETABLE Applies a specified command to jobs in the Active Jobs file that were ordered from the specified table.ctmpsm -UPDATETABLE <table> <command>

Where command is one of the following:• HOLD _ Set the jobs’ status to HELD.• FREE _ Free previously held jobs.• DELETE _ Mark the jobs for deletion.• UNDELETE _ Undelete the jobs marked for deletion.• RERUN _ Rerun the jobs.• CONFIRM _ Confirm submission of the jobs.

Mode Description



ctmrpln

ctmrpln creates a report that lists all or a selection of jobs in a specified Scheduling table, and indicates when the jobs are scheduled to run. In addition, it enables you to test the effect of different calendars on the scheduling of jobs in the table.

Each report can be created in one of three formats, as described in Table 2-47:

The following characters can appear in this report. The characters indicate that a job is scheduled to run (that is, the job is placed in the Active Jobs file.)

Table 2-47 ctmrpln – Report Formats

Format Description

Daily Report Displays jobs in the specified Scheduling table that are scheduled to run on a specific day. Each job’s Mem Name (or Job Name), Group and Description parameters are also displayed.

Monthly Report Displays a table of all days in a specified month and marks (with an asterisk “∗”) the days of the month on which jobs in the specified Scheduling table are scheduled to run. Jobs can be identified either by their Mem Name or Job Name parameters.

NOTE: To print the monthly report, the <Output> parameter (described below) must specify a printer that can print 132-column reports.

Yearly Report Displays five individual year-calendar tables and marks each day with various characters (described below) which indicate if jobs in the specified Scheduling table are scheduled to run. The years displayed encompass the period ranging from two years prior to the specified year until two years following the specified year.

Char Description

∗ The days on which the job is scheduled is indicated by an asterisk “∗”


Utilities 2-121

Specify the following command to invoke the ctmrpln utility:

ctmrpln <Report_type> <Calendar> <Schedtab> <Jobname> <Date> [<Output>]

Table 2-48 describes the parameters in the ctmrpln utility.

. Job is not scheduled; the day is not a calendar day.

- Job is not scheduled because job processing parameter contains a minus sign (-). Placing a minus in the job order overrides the other characters “*” and “.”.

Table 2-48 ctmrpln – Parameters (Part 1 of 2)


<Report_type> Specify one of the following values:

DM (or D)

Creates a daily report, identifying each job by its Mem Name parameter.

DJ Creates a daily report, identifying each job by its Job Name parameter.

MM (or M)

Creates a monthly report, identifying each job by its Mem Name parameter.

MJ Creates a monthly report, identifying each job by its Job Name parameter.

Y Creates a year report.

<Calendar> Specify one of the following values:

Y Creates the report using the calendar specified in the job’s scheduling parameters.

N Creates the report ignoring the calendar specified in the job’s scheduling parameters.

<Name> Creates the report using a calendar whose name you specify (ignores the calendar specified in the job’s scheduling parameters, if any). Use this option to see the effect another calendar would have on the schedule.

Char Description



Example 1

The following command causes the utility to generate a report for Scheduling table PROD1. The report will include all jobs whose Job Name parameter begins with “jn” and that will run on Jan. 1, 2000 based on the calendar work_days. The output is directed to the user’s display:

ctmrpln D work_days PROD1 "jn∗" 20000101

<Schedtab> Name of the Scheduling table on which to base the report. The Scheduling table name can include the following mask characters:

* Represents any number of characters (including no characters). Specify * by itself to include all Scheduling tables. Any parameter including * should be enclosed in quotation marks.


<Jobname> Contents of the job processing parameter Job Name of the job or jobs to include in the report. The Job Name can include mask characters (see <Schedtab> above). Specify * by itself to include all jobs in the Scheduling table.

<Date> Date for the report:• For daily reports: A date in yyyymmdd format.• For monthly reports: A month in yyyymm format.• For yearly reports: A year in yyyy or yy format.Note: The ctmrpln utility supports only years from 1972 to 2037.

<Output> Full path name to which the report should be sent (optional). If this parameter is not specified, the output is routed to the default output device.

Table 2-48 ctmrpln – Parameters (Part 2 of 2)



Utilities 2-123

Example 2

The following command causes the utility to generate a table of days on which job PRDJ02 in Scheduling table PROD1 will run during the month of April, 2000, based on the calendar work_days. The output is directed to printer lp1:

ctmrpln M work_days PROD1 PRDJ02 200004 lp1

Example 3

The following command causes the utility to generate a five-year report encompassing the period Jan. 1999 through Dec. 2003, indicating on which days each job in Scheduling table PROD1 runs, based on the calendar work_days. The output is directed to printer lp1:

ctmrpln Y work_days PROD1 "∗" 2001 lp1



ctmruninf

ctmruninf displays runtime data from the Statistical Details table of the CONTROL-M database. An option is available to delete data from this table. The jobs scanned for both options can be limited to a range of dates as described below.

NoteStatistical data is only accumulated when the CONTROL-M system parameter Statistics is set to Y.

For more information about runtime statistical data, see “Runtime Statistics” on page 1-28.

Specify one of the following commands to invoke the ctmruninf utility:

ctmruninf -list <From Date> <To Date> [<Filter>] [-total]ctmruninf -list "∗" [<Filter>] [-total]ctmruninf -delete <From Date> <To Date>

The parameters for the above commands are described in Table 2-49.

Table 2-49 ctmruninf – Parameters (Part 1 of 2)


-list Displays data from the Statistical Summary table within the dates specified by the From Date and To Date parameters. The data listed can be limited with use of the Filter subparameter (see below).

-delete Deletes data from the Statistical Summary table in the range specified by the From Date and To Date parameters.

<From Date> Starting date of statistical data to be displayed/deleted. The date is specified in yyyymmddhhmmss format.

<To Date> Ending date of statistical data to be displayed/deleted. The date is specified in yyyymmddhhmmss format.

“∗” Asterisk enclosed in quotation marks. Specifies that the utility should list all statistical data currently available, without regard to date.


Utilities 2-125

Example 1

The following command displays runtime data for the period January 21, 2000 through January 25, 2000 (assuming that this data is available):

ctmruninf -list 20000121000000 20000125000000

<Filter> Specify one of the following options and its associated subparameter or leave blank to display the statistics for all jobs in the range.

-JOBNAME <jobname>Identify the job by its Job Name parameter.

-MEMNAME <memname>Identify the job by its Mem Name parameter.

-MEMLIB <memlib>Identify jobs by their Me Lib parameter.

-NODEID <nodeid>Identify jobs by their Node ID parameter (Agent platform).

Each of the subparameters in the filter can include the following mask characters:

• * — Represents any number of characters (including no characters). Any parameter including ∗ should be enclosed in quotation marks (see example below).

• ? — Represents any single character

-total Displays a line that contains the total CPU and elapsed times for the jobs selected.

Table 2-49 ctmruninf – Parameters (Part 2 of 2)




Example 2

The following command causes the utility to display and total runtime data for all jobs on Agent platform diana.

ctmruninf -list "∗" -NODEID "diana" -total

A report similar to the following is displayed:

TIMESTAMP JOBNAME ORDERID RUN# NODEID MEMNAME MEMLIB CPU ELAPSED------------- ---------- -------- ---- ------------ ---------- -------------- ----- -------2000012160524 acct12 00000007 1 diana pgmacct prod.acct.pgm 0.19 233.15 2000012161205 gen786 0000000b 1 diana genx prod.general 0.12 6.12 2000012162311 acct14 00000011 1 diana pgmacct prod.acct.pgm 0.05 170.45 2000012164512 acct15 00000012 1 diana pgmacct prod.acct.pgm 0.14 145.23 ------------- ---------- -------- ---- ------------ ---------- -------------- ----- -------Total records printed : 2 0.50 555.35

Example 3

The following command deletes the statistical data for January 31, 2000

ctmruninf -delete 20000131000000 20000131235959


Utilities 2-127

ctmshout

ctmshout issues Shout messages to an indicated destination. It can be entered directly or from a job script. See “Shout Destination Tables” on page 1-24, for more information about Shout message destinations.

Specify the following command to invoke the ctmshout utility:

ctmshout [-ORDERID <Order_ID>] [-NODEID <Node_ID>] -USER <Destination> [-USER <Destination>]\ -MESSAGE <Message_text> [-MESSAGE <Message_text>] \ [-SEVERITY <{R|U|V}>]

Table 2-50 ctmshout – Parameters


<Order_ID>a

a. This parameter is required for releases of ENTERPRISE/CS prior to Version 2.1.3 Level 9605.

Order ID of a job, as displayed in the Job Details window in ENTERPRISE/CS. The Order ID associates the message with a specific job in the Active Network.

<Node_ID> Node ID of the agent platform. This parameter is used for messages whose destination is either a user in the data center or a user defined in the Shout Destination table. If -ORDERID is also specified, this Node_ID will overwrite the Node ID specified for the job with that Order ID.

<Destination> Name of a user in the data center or a valid destination name in the Shout Destination table. Shout messages can be sent to multiple destinations in the same command.

<Message_text> Free text to be sent to the destination. If the text is more than one word, it must be enclosed in quotation marks. Multiple messages can be sent in the same command.

<{R|U|V}> One letter character indicating the urgency of the message where:

R Regular (Default)

U Urgent

V Very urgent

If this parameter is not specified, the urgency of the message is Regular.



Each parameter name can be shortened to the minimum number of letters required to identify the parameter. For example: -ORDERID can be shortened to -O.

Example 1

The following command sends the message “File not found” to the Alerts window in ENTERPRISE/CS and associates it with a job whose Order ID is 1234:

ctmshout -ORDERID 1234 -USER ECS -MESSAGE "File not found" \-SEVERITY V

Example 2

The following command sends the message “The weekly paycheck job has abended” to user John on Agent platform diana:

ctmshout -NODEID diana -USER John -MESSAGE "The weekly paycheck job\ has abended" -SEVERITY V

Example 3

The following illustrates the use of the ctmshout utility in a job script command to send the Shout message “Job started” to the Alerts window in ENTERPRISE/CS.

The job processing definition for a certain job contains the following AutoEdit Assignment parameter:

%%PARM1 = %%ORDERID

The script used to execute the job contains the following command:

ctmshout -O $1 -USER ECS -MESSAGE "Job started" \-SEVERITY R


Utilities 2-129

ctmshtb

ctmshtb sets the active Shout Destination table. The Shout Destination table associates physical output destinations with logical destination names specified in Shout and Do Shout statements in job processing definitions. For more information, refer to “Shout Destination Tables” in Chapter 1, Overview.

Activation of this utility changes the active Shout Destination table to the table specified.

You can add, delete and modify Shout Destination tables using the ctmsys utility, described earlier in this chapter. The ctmsys utility can also be used to specify the active Shout Destination table interactively.

Specify the following command to invoke the ctmshtb utility:

ctmshtb <Table>

where <Table> is the new Shout Destination table name.

NoteBy defining CONTROL-M jobs that execute the ctmshtb utility at specified times, the active Shout Destination table designation can be changed automatically according to the schedule that suits your installation.

Example

The following command sets the current active Shout Destination table designation to SHIFTMAN:

ctmshtb SHIFTMAN



ctmstats

ctmstats displays and deletes statistical data from the Statistical Summary table of the CONTROL-M database. The data scanned for both options can be limited to a range of dates. The Statistical Summary table is created via the ctmjsa utility.

NoteStatistical data is only accumulated when the CONTROL-M system parameter Statistics is set to Y. For more information, see “System Parameters” on page 5-3.

Specify one of the following commands to invoke the ctmstats utility:

ctmstats -list <From Date> <To Date> [<Filter>] [-total]ctmstats -list "∗" [<Filter>] [-total]ctmstats -delete <From Date> <To Date>

Table 2-51 ctmstats – Parameters (Part 1 of 2)


-list Displays data from the Statistical Summary table within the dates specified by the From Date and To Date parameters. The data listed can be limited with use of the Filter sub-parameter (see below).

-delete Deletes data from the Statistical Summary table in the range specified by the From Date and To Date parameters.

<From Date> Starting date of statistical data to be dis-played/deleted. The date is specified in yyyymmddh-hmmss format.

<To Date> Ending date of statistical data to be displayed/deleted. The date is specified in yyyymmddhhmmss format.

“∗” Asterisk enclosed in quotation marks. Specifies that the utility should list all statistical data currently avail-able, without regard to date.


Utilities 2-131

Example 1

The following command displays statistical data for the period January 21, 1999 through January 25, 1999 (assuming that this data is available):

ctmstats -list 19990121000000 19990125000000


<Filter> Specify one of the following options and its associated subparameter or leave blank to display the statistics for all jobs in the range.

-JOBNAME <jobname>

Identify the job by its Job Name parameter.

-MEMNAME <memname>

Identify the job by its Mem Name parameter.

-MEMLIB <memlib>

Identify jobs by their Mem Lib parameter.

-NODEID <nodeid>

Identify jobs by their node id parameter (Agent plat-form).

Each of the subparameters in the filter can include the following mask characters:

* – Represents any number of characters (including no characters). Any parameter including ∗ should be enclosed in quotation marks (see example below).

? – Represents any single character

-total Displays a line that contains the total CPU and elapsed times for the jobs selected.

Table 2-51 ctmstats – Parameters (Part 2 of 2)




TIMESTAMP JOBNAME NODEID MEMNAME MEMLIB AVG CPU AVG ELAPSED-------------- ---------- ------------ ---------- -------------- ------- -----------19990122141214 acct12 diana pgmacct prod.acct.pgm 0.19 233.15 19990122032025 gen786 diana genx prod.general 0.12 6.12 19990121123111 acct14 diana pgmacct prod.acct.pgm 0.05 170.45 19990121113512 acct15 diana pgmacct prod.acct.pgm 0.14 145.23

Example 2

The following command displays statistical data for all jobs on Agent platform diana:

ctmstats -list "∗" -NODEID diana -total

Example 3

The following command deletes the statistical data for January 31, 1999:

ctmstats -delete 19990131000000 19990131235959


Utilities 2-133

ctmstvar

The ctmstvar utility displays the current value of an AutoEdit variable or function. Specify the following command to invoke the ctmstvar utility:

ctmstvar <order id> <autoedit string>

An AutoEdit variable that does not contain a $ sign can be enclosed in single (‘ ’) or double (“ ”) quote marks. An AutoEdit variable that does contain a $ sign should be enclosed in single quote marks. An AutoEdit variable containing a $ sign cannot be resolved if it is enclosed in double quote marks.

Examples

ctmstvar a1 ‘%%$CALCDATE %%ODATE -2’ctmstvar 0 "%%ODATE"

Table 2-52 ctmstvar – Parameters


<order id> The Order ID of a job waiting in the Active Jobs file (as displayed in the Job Details window of ENTERPRISE/CS). The Order ID displayed in ENTERPRISE/CS is a base 36 number. If you want to specify the Order ID here as a base 10 number, precede the number with an asterisk, and enclose it in quotation marks (for example,“∗1234”).Use “0” to indicate no specific Order ID.

<autoedit string> The AutoEdit variable or string enclosed in quotes.



ctmsuspend

ctmsuspend suspends and restores CONTROL-M/Server non-communication processes for mass batch uploads/downloads from ENTERPRISE/CS. During suspension mode, CONTROL-M inactivates its job processing functions by suspending the TR, SL, NS, and LG processes. For more information, see “CONTROL-M/Server Processes” on page 4-43. Requests for job processing during this mode are suspended until execution of ctmsuspend restoration mode.

This utility should be invoked before executing the Mass Upload or Mass Download features on the ENTERPRISE/CS Graphical User Interface.

Specify the following command to invoke the ctmsuspend utility:

ctmsuspend {-s|-r}

Example

The following command causes CONTROL-M/Server scheduling processes to be restored.

ctmsuspend -r

Table 2-53 cmtsuspend – Options

Var Description

-s Suspends CONTROL-M/Server scheduling processes. Leaves the gateway to ENTERPRISE/CS open.

-r Restores CONTROL-M/Server processes. Resumes normal operating mode.


Utilities 2-135

ctmsys

The ctmsys utility is an interactive utility for maintaining the following CONTROL-M parameters:

• Shout Destination tables (for directing Shout messages).• CONTROL-M system parameters.

To invoke the ctmsys utility:

1. Log on to the Server platform as the CONTROL-M/Server owner (for example, user controlm).


ctmsys


+------------------------------------------------+| CONTROL-M SYSTEM MAINTENANCE UTILITY || Main Menu |+------------------------------------------------+

1) Shout Destination Tables2) System Parameters

q) Quit

Enter option:

The options in this menu and in all other menus provided by this utility can be selected by typing the option number or command letter and pressing Enter.

Each option appearing in the main menu is described below.



Shout Destination Tables

Shout Destination tables associate logical output destinations (specified in Shout and Do Shout statements in job processing definitions) with physical destination names. See “Shout Destination Tables” on page 1-24, for additional information.

To access the Shout Destination Tables menu:

Select Option 1 from the main menu.


Shout Destination Tables Menu-----------------------------Active Shout Destination Table: <table_name>

1) Create/Modify a Table2) Set Active Table3) List Tables4) Delete Table

q) Quit and return to main menu

Enter option:

The name of the currently-active Shout Destination table is displayed in the <table_name> field on the menu.

To create or modify a Shout Destination table:

Step 1 Select Option 1 from the Shout Destination Tables menu.

A list of available tables, similar to the following, is displayed:


Utilities 2-137

Shout Destination Tables------------------------SYSTEMNIGHT_SHIFT

Table to create/modify or ’q’ to quit [SYSTEM]:

Step 2 Specify the name of the table to be created or modified (or press <Enter> to accept the default).

If the name you specify is not the name of an existing Shout Destination table, a new table will be created with the specified name.

A display similar to the following is displayed. For an existing table, the display lists the defined destinations.

Shout Destination Table ’SYSTEM’--------------------------------

# Destination Type Addr Logical Name Physical Name- ---------------- ---- ------------ -------------1 E S ECS 2 T S Term_B $TTB.#B

q) Quit e#) Edit entry # n) New entry d#) Delete entry #

Enter option:



The following fields in the table are displayed:

To create a new entry in the table:

1. Specify n.

The following prompts appear:

Dest. Type: (U)ser (M)ail (T)erminal c(O)nsole (L)og (P)rogram (E)NTERPRISE/CS:

Table 2-54 Fields of the Shout Destination Table

Item Description

# Entry number in the table.

Destination Type One-letter code indicating the type of recipient:

U—Specific user. If the user is not logged onto the data center when the Shout message is sent, the message is placed in the user’s mail.

M—User’s mail.

T—Specific terminal or file.

O—System console.

L—CONTROL-M log.

E—Alert window of ENTERPRISE/CS.

P—Program which will perform the Shout operation.

Address Type One-letter code indicating whether the destination is on the Server (S) or Agent (A) platform.

Logical Name Name used in the Shout or Do Shout parameter of the job processing definition to identify the recipient of the Shout message.

Physical Name For Destination Types U and M, name of a user in the data center.For Destination Type T, terminal ID or full path name (max. 96 characters) of a file. If the file exists, the message will be appended to the end of the file.For Destination Type P, the full path name of the program file/script which will perform the Shout operation.For Destination Types O, L and E, no physical name is specified, as each of these is a unique destination.


Utilities 2-139

2. Specify the letter corresponding to the desired destination type.

The following prompt is displayed:

Address Type (S)erver or (A)gent:

3. For Destination types U, M, P, T or O, specify whether the destination is on the Server (S) or Agent (A). For Destination type E, specify S.


Logical Name:

4. Specify the logical name for this destination.


Physical Name:

5. For Destination types U, M, P or T, specify the physical name. For Destination types O and E, leave this field blank.

The new entry is added to the table.

To modify an existing entry (physical name only) in the table:

1. Specify e<entry_number>. For example, to modify entry number 2, specify e2.


Dest Type:Address Type:Physical Name:

Note that this option cannot be used to modify a logical name.



2. Specify a new physical name for the entry. The table is redisplayed with the modified entry.

To delete an existing entry in the table:

1. Specify d<entry #>. For example, to delete entry # 2, specify d2.

The entry is deleted.

2. Specify q to return to the Shout Destination Tables menu.

To change the active Shout Destination table:

1. Select Option 2 from the Shout Destination Tables menu.

A list similar to the following is displayed:

Existing Shout Destination Tables---------------------------------SYSTEMNIGHT_SHIFTEnter name of table to make active or q to quit [SYSTEM]:

2. Specify the name of the table to set as the active Shout Destination table.

The following message is displayed:

Table <table name> is now active.Press ENTER to continue.

3. Press <Enter> to return to the Shout Destination Tables menu.


Utilities 2-141

The active Shout Destination table is changed immediately, affecting Shout and Do Shout operations performed by CONTROL-M.

NoteTo specify the active Shout Destination table via a batch job, run the ctmshtb utility, described earlier in this chapter.

To list existing Shout Destination tables:



Shout Destination Tables------------------------SYSTEMNIGHT_SHIFT

Press ENTER to continue




To delete an existing Shout Destination table by name:


A list of existing Shout Destination Tables is displayed.

2. Specify the name of the table to delete.

The following message is displayed:

Delete completed successfully.Press ENTER to continue.


NoteIt is not possible to delete the active Shout Destination table.

System Parameters

This option is used to view/modify CONTROL-M system parameters.

NoteThese parameters are described in Chapter 5, “Customization Parameters.”


Utilities 2-143

To view or modify CONTROL-M system parameters:

Step 1 Choose Option 2 from the Main menu.

The first group of parameters (and their current values) is displayed. See Figure 2-7.

Figure 2-7 CONTROL-M System Parameters (Page 1)

CONTROL-M System Parameters (Page 1/2)--------------------------------------

Computer System :sparcOperating System :SolarisCONTROL-M Version :6.0.0Database Version/schema :6.0.0Executable Path :/home3/ctmssl/ctm/exe_Solaris1) Day Time :+0700 CONTROL-M Date :200102192) Statistics :Y3) Maximum Retries :504) Start Day of the Week :2 Active Shout Table :SYSTEM5) Full Security :N n) Next Pages) Save and Return to Main Menuc) Cancel Enter command, or item number you wish to change [n]:

When you specify n, the second page of parameters is displayed. See Figure 2-8.



Figure 2-8 CONTROL-M System Parameters (Page 2)

CONTROL-M System Parameters (Page 2/2)--------------------------------------

6) Maximum Days Retained by CONTROL-M Log :27) Maximum Days to Retain Sysout Files :18) Ignore New Day Conditions :N9) Secure Socket Layer :DISABLED

p) Previous Pages) Save and Return to Main Menuc) Cancel

Enter command, or item number you wish to change [p]:

Parameters that can be modified are preceded by a number.

Step 2 Modify or view parameters as follows:

• To switch between the two pages of parameters, type n (next page) or p (previous page) as required.

• To modify a parameter, type the number preceding the parameter.

— If the parameter has a Y/N value, typing the parameter’s option number toggles the value between Y and N and redisplays the page.

— If the parameter requires any other value, you are prompted to type the value. After you supply the value, the page is redisplayed.

Step 3 When you want to exit:

• Type s to save your changes and exit to the main menu. Modifications are not saved until you perform this action.

• Type c to cancel all changes and exit to the main menu.


Utilities 2-145

ctmudchk

ctmudchk checks whether all the jobs which should have been ordered by a User Daily job are in the Active Jobs file. This utility facilitates recovery from the interruption of a User Daily job.

When using the ctmudchk utility, the New Day procedure must not be running (that is, the status of the data center in the Communication Status window of ENTERPRISE/CS must not be “Formatting AJF”).

Use the following command to invoke the ctmudchk utility:

ctmudchk -DAILY <User Daily name> -ACTION {LIST|ORDER} -FILE <File Name>

The parameters of this command are described in Table 2-55.

Example 1

Use the following command to check the Active Jobs file for jobs which are ordered by the User Daily whose name is payroll. The Job Name and Scheduling table are listed for each job that is not in the Active Jobs file.

ctmudchk -DAILY payroll -ACTION LIST

Table 2-55 ctmudchk – Parameters


-DAILY Name of the User Daily to be checked.

-ACTION Indicates whether jobs that are missing from the Active Jobs file should be listed or ordered.The following values can be specified for this parameter:

LIST Lists the job name and the name of the scheduling table for each missing job.

ORDER Orders the missing jobs.

-FILE Indicates the path name for the output of the ctmudchk utility. This parameter is required only if LIST is specified for the ACTION parameter.



Example 2

Use the following command to check the Active Jobs file for jobs which are ordered by the User Daily whose name is admin1. The utility orders each job that is not in the Active Jobs file.

ctmudchk -DAILY admin1 -ACTION ORDER

Return Codes

The utility returns status code 1 (NOTOK) if it attempts to order a job, but fails to do so. Otherwise, the utility returns status code 0 (OK).


Utilities 2-147

ctmudlst

The ctmudlst utility is used to display or modify UDLAST (the User Daily last run date). See “Date Control Record (UDLAST)” on page 1-21, for more information.

When using the ctmudlst utility, the New Day procedure must not be running (that is, the status of the data center in the Communication Status window of ENTERPRISE/CS must not be “Formatting AJF”).

To invoke the ctmudlst utility, specify one of the following commands:

ctmudlst LIST <User Daily>ctmudlst LIST "∗"ctmudlst UPDATE <User Daily> <Date>

The parameters of these commands are described in Table 2-56.

Example 1

The following command lists the last run date for User Daily payroll:

ctmudlst LIST payroll

Table 2-56 ctmudlst – Parameters


LIST Lists the User Daily last run date.

UPDATE Updates the User Daily last run date.

<User Daily> User Daily name.

“∗” Asterisk enclosed in quotation marks. Displays a list of all User Daily names and corresponding last run dates.

<Date> Requested value for the last running date in yyyymmdd format.



Example 2

The following command changes the last run date for User Daily inventory to Aug. 10, 1998:

ctmudlst UPDATE inventory 19980810


Utilities 2-149

ctmudly

ctmudly orders jobs for a specific User Daily name.

The utility orders all Scheduling tables associated with a specific User Daily name. Each job in the ordered Scheduling tables whose Scheduling criteria are satisfied is placed in the Active Jobs file.

See “User Daily Jobs” on page 1-18, for more information and examples.

To invoke the ctmudly utility, specify the command:

ctmudly <User Daily>

where <User Daily> is a User Daily name associated with one or more Scheduling tables. This parameter is case-sensitive.

Example

The following command orders all Scheduling tables whose User Daily parameter is prod:

ctmudly prod



ctmvar

The ctmvar utility defines, deletes, modifies and displays AutoEdit variables. This utility can be applied to variables that are:

• In a specific job processing definition in a Group Scheduling table• Common to all jobs in a Group Scheduling table• Global for an entire data center (a CONTROL-M/Server and all

associated agents)

Special notes:

• If a group scheduling table specified in the ctmvar utility has been ordered more than once, the utility updates every instance of that group scheduling table in the Active Jobs file.

• AutoEdit variables in jobs that are not part of a group scheduling table cannot be modified using the ctmvar utility.

• A value specified for a Global AutoEdit variable is overridden if a local variable with the same name is defined in a job processing definition or for a group scheduling table.

Syntax

To invoke the ctmvar utility, specify the following command:

ctmvar -action <LOAD|SET|DELETE|LIST> \[-var “%%[\<gptble>[\<jobname>]]\<varname>”]\[-varexpr <variable expression>] \[-filename <filename>] \[-quiet] \[-debug <level>]


Utilities 2-151

Table 2-57 ctmvar – Parameters (Part 1 of 3)


-action Indicates the action to be performed on the specified AutoEdit variable. The possible actions are:

LOAD Loads AutoEdit variables from a file. When this option is used, parameter -filename is required. The format for each variable in the specified file is: %%[\<gptble>[\<job>]]\<varname>=<expression>• If the variable does not exist in the data center or

the specified group scheduling table or job, it is created.

• If the variable already exists, it is updated with the specified value.

SET Defines a new AutoEdit variable. When this option is used, parameters -var and -varexpr are required.• If the variable does not exist in the data center or

the specified group scheduling table or job, it is created.

• If the variable already exists, it is updated with the specified value.

DELETE Deletes an AutoEdit variable. When this option is used, the -var parameter is mandatory.

LIST Displays all Global AutoEdit variables for the data center or all variables for the specified group scheduling table specified in the -var parameter.

Example 1:ctmvar -action LIST Displays all Global AutoEdit variables for the data center.

Example 2:ctmvar -action LIST -var “%%\PAYROLL”Displays all AutoEdit variables that are global for the PAYROLL group scheduling table.

Variable values can also be displayed using the ctmstvar utility. However, the ctmstvar utility resolves the current value of only a specified AutoEdit variable or function. The ctmvar utility displays all AutoEdit variables in the data center or the specified group scheduling table.



-var Name and location of the AutoEdit variable that the specified action should be applied to. The valid format for this parameter depends on the type of variable being handled.

• For a variable that is global for an entire data center, valid format is:-var “%%\<var_name>”

• For a variable that is global for all jobs in a Group Scheduling table, valid format is:-var “%%\<group_table_name>\<var_name>”

• For variable in a specific job in a group scheduling table, valid format is:-var “%%\<group_table_name>\<jobname>\<var_name>”

Notes:

This parameter cannot be specified together with -action LOAD .For more information about AutoEdit variables, see the AutoEdit chapter in the Enterprise Controlstation User Guide.

-varexpr Value to be assigned to the specified AutoEdit variable. The specified value can be:• a string (embedded in quotes)• an integer (a numeric value)• an AutoEdit expression (for example, with an AutoEdit

function)• another (existing) global variable.This parameter cannot be specified together with-action LOAD.For more information, see the AutoEdit chapter in the Enterprise Controlstation User Guide.

-filename File containing the list of AutoEdit variables. The value specified for this parameter must be a valid path and filename. This parameter is only valid when specified together with -action LOAD.The syntax for each line in the specified file is %%[\<gptble>[\<job>]]\<varname>=<expression>Note: The entire pathname must be specified in this parameter.




Utilities 2-153

Examples

The following command assigns the value UP to AutoEdit variable %%CTMSTATUS:

ctmvar -action set -var “%%\CTMSTATUS” -varexpr “UP”

The following command assigns the value 31 to AutoEdit variable %%MONTHDAYS in the group scheduling table called PAYROLL:

ctmvar -action set -var “%%\PAYROLL\MONTHDAYS”-varexpr 31

The following command assigns the current value of system variable %%TIME to AutoEdit variable %%AAA:

ctmvar -action set -var “%%\AAA” -varexpr %%TIME

The format AutoEdit variable %%@varname indicates that the variable should contain a value to be resolved by each job that uses it. In the following example, the command assigns the value %%@TIME to AutoEdit variable %%AAA:

ctmvar -action set -var “%%\AAA” -varexpr %%@TIME

For more information about AutoEdit variables that resolve at definition or reference time, see the AutoEdit Facility chapter in the Enterprise Controlstation User Guide.

-quiet Suppresses the display of the results.

-debug Sets a debug level for the utility. This parameter is used for maintenance and troubleshooting purposes. The level, a numeric value from 0 to 5, must be used only if requested and specified by Technical Support.Note: Performance is somewhat slower and requires a larger number of resources when operating in debug mode. It is recommended that you activate debug mode only when absolutely necessary and revert to normal mode as soon as possible.





ctmwhy

ctmwhy displays a report stating why a job waiting in the Active Jobs file is not being submitted for execution. This utility is equivalent to the Why option available from the Job Node menu in the Enterprise Controlstation window.

To invoke the ctmwhy utility, specify the command:

ctmwhy <Order ID>

where <Order ID> is the Order ID of a job waiting in the Active Jobs file (as displayed in the Job Details window of ENTERPRISE/CS).

NoteThe Order ID as displayed in the Job Details window is a base 36 number. If you wish to specify the Order ID here as a base 10 number, precede the number with an asterisk, and enclose it in quotation marks (for example, “ ∗1234”).

Example 1

Specify the following command to determine why the job with Order ID A4X is not being submitted for execution:

ctmwhy A4X

A typical response might be QR: ’TAPE4’ : needed 2. None reserved, which indicates that the job is not being submitted because it requires two of the Quantitative resource TAPE4, and none is available.

Example 2

Specify the following command to determine why the job with Order ID 11 is not being submitted for execution. The Order ID in this example is expressed as a base 10 number:

ctmwhy "∗37"


Utilities 2-155

ctm2snmp

The ctm2snmp utility enables the user to send messages to various Network Management applications (for example, HP-OpenView, NetView for AIX, and Tivoli Management Environment Console) via SNMP traps. See the SNMP Interface appendix in the Enterprise Controlstation Administrator Guide for a description of SNMP traps.

SNMP traps issued via CONTROL-M consist of the fields described in Table 2-58.

To invoke the ctm2snmp utility, specify the following command:

ctm2snmp -hostname <host_name> -severity <severity> -message <message>

Table 2-58 Fields of SNMP Traps

# Field Description

1 SEVERITY Severity of the alert. Possible values are:• R Regular• U Urgent• V Very urgent

2 SEND TIME Time/date that the alert was issued (format yyyymmddhhmmss).

3 USER NAME Name of the CONTROL-M user who invoked the utility.

4 MSG TEXT Full text of the alert.

Table 2-59 ctm2snmp – Parameters


-host_name Host name or IP address of the machine containing the Network Management application.

-severity Severity of the alert (R, U, V)

-message Message to be sent.



Special customization is required to support SNMP traps issued by CONTROL-M:

• SNMP traps can be issued in either Single Variable format or Multiple Variable format. The format is determined by the CTM_SNMP_SEND_FORMAT parameter specified in the ~controlm/ctm/config.dat file. The default is Single Variable (S) format. For more information, see “Configuration Parameters” on page 5-22.

— Single Variable FormatThe trap is contained in one SNMP variable. This variable is a string consisting of four trap fields separated by blanks. There are three specific traps:

A. Specific-trap 1: Regular CONTROL-M alerts.B. Specific-trap 2: Urgent CONTROL-M alerts.C. Specific-trap 3: Very urgent CONTROL-M alerts.

— Multiple Variable FormatThe trap consists of 4 distinct SNMP variables. There is one specific trap type:

A. Specific-trap 10: CONTROL-M alerts.

• The following entry must be added to the /etc/services/ file (if not already present):snmp-trap 162/udp # snmp monitor trap port

• The Network Management applications, HP-OpenView, NetView for AIX, and Tivoli Management Environment Console, must be customized so that they recognize the Enterprise ID of CONTROL-M and the generated trap codes. Follow the procedure for each application described in the “SNMP Interface” appendix in the Enterprise Controlstation Administrator Guide.

Use CTMS_4D and 1.3.6.1.4.1.954.6 for the CONTROL-M Enterprise name and MID. Edit all the described file entries replacing ECS with CTMS.


Utilities 2-157

ecactltb

ecactltb displays a list of Control resources and the status of each resource.

To invoke the ecactltb utility, specify the following command:

ecactltb [<Output>]

<Output> is the full path name to which the report should be sent (optional). If this parameter is not specified, the output is routed to the default output device.

Example

The following command generates a list of Control resources in the file rprt.txt.

ecactltb /ctm/user1/rprt.txt



ecaqrtab

ecaqrtab performs operations on the Quantitative Resources table. These operations include:

• Listing Quantitative resources.• Adding/deleting a Quantitative resource.• Manually altering availability of a Quantitative resource.

NoteIf the resource name is longer than 20 characters, the resource is not created.

Use the following command to invoke the ecaqrtab utility:

ecaqrtab {LIST|ADD|DELETE|UPDATE}[<QR_Name>][<Max>][<Output>]

Table 2-60 describes the parameters for this utility.

Table 2-60 ecaqrtab – Parameters


LIST Displays the status of the specified Quantitative resources. This information is also available from ENTERPRISE/CS in the Quantitative Resources window.

ADD Defines a new Quantitative resource and sets the maximum availability for the resource.

DELETE Deletes an existing Quantitative resource.

UPDATE Changes the maximum availability for an existing Quantitative resource.

<QR_Name> Name of the Quantitative resource. For the LIST option, the QR_Name can include mask character ∗ to indicate any number of characters (including no characters). If a mask character is specified, the name must be enclosed in quotation marks (for example, “LVL ∗” ). You can specify “ ∗” by itself to include all existing Quantitative resources (default).


Utilities 2-159

To list Quantitative resources:

Specify the following command:

ecaqrtab LIST[<QR_Name>][<Output>]

Table 2-61 describes the fields that are displayed for each Quantitative resource that matches the specified resource name or mask.

Example

The following command lists the current status of all Quantitative resources contained in the Quantitative Resource table:

<Max> Specifies the maximum availability for the specified resource. This parameter should only be specified with the ADD and UPDATE options

<Output> This parameter can only be specified for the LIST option. It indicates the full path name to which the report should be sent (optional). If this parameter is not specified, the output is routed to the default output device.

Table 2-61 ecaqrtab – Resource Status Fields


QR name Quantitative resource name (with @<Node ID> where applicable).

Type For future use.

Max Avail Maximum number of units of this resource in the platform.

Reserved Number of units of the resource reserved for critical-path jobs.

Used Number of units of the resource currently in use or reserved. If the ctmloadset utility is used in the data center, this number can include usage of the resource by non-CONTROL-M jobs.

Free Number of units of the resource currently available for use. This represents the difference between Max Avail and Used.

Table 2-60 ecaqrtab – Parameters




ecaqrtab LIST “*” or ecaqrtab LIST


+--------------------------------------------------------------+Resource Name Type Max-Avail Reserved Used Free+--------------------------------------------------------------+CPU@linda L 10 0 10 0CPU@linda L 20 0 15 5MEM@diana L 10 0 0 10Tape2 L 12 2 2 10

To add a Quantitative resource:


ecaqrtab ADD <QR name> <Max>

Example

The following command specifies that the new Quantitative resource tape2 is to be added to the Quantitative Resource table, with a maximum availability of 12 units:

ecaqrtab ADD tape2 12

To delete a Quantitative resource:

• Specify the following command:ecaqrtab DELETE <QR name>

Example

The following command specifies that the Quantitative resource tape3 is to be deleted from the table:

ecaqrtab DELETE tape3

To alter the availability of a Quantitative resource:


ecaqrtab UPDATE <QR name> <Max>


Utilities 2-161

Example

The following command specifies that the new maximum availability for the existing Quantitative resource linerje2 on platform diana is 12 units:

ecaqrtab UPDATE linerje2@diana 12


Security 3-1

3

Security 3

CONTROL-M includes security features that protect CONTROL-M against unauthorized usage or modification. These features enhance the standard Unix security, and provide an additional application-level security layer.

Using CONTROL-M security, you can specify actions that each ENTERPRISE/CS user or CONTROL-M user is authorized to perform. These authorizations used to perform security checks each time one of the following actions is attempted:

• Accessing a Scheduling table (to add, delete, or modify a job definition).

• Ordering a job.

• Selecting and submitting a job.

• Commands affecting jobs in the Active Jobs file (for example, Hold, Confirm, Rerun).

• Maintenance of CONTROL-M entities (for example, calendars, prerequisite conditions).

Security verifications for the above actions are implemented according to the specifications in a database of authorizations. This database can be modified by the security officer or systems manager to meet the needs of the enterprise. For more information, see “Security Maintenance Utility (Interactive Mode)” on page 3-11.



Level of Application Security

CONTROL-M provides the following levels of application security for users not explicitly defined in the CONTROL-M security database:

Regardless of which level is implemented:

• A user, for whom one or more authorizations have been assigned in the security database, can only perform those actions for which the user has authorization.

• The owner of each job processing definition must be defined as a user on the Agent platform. Otherwise, CONTROL-M will not order or execute the job.

The security level is determined by the value of the CONTROL-M system parameter Full Security (described in Chapter 5, “Customization Parameters”).

Table 3-1 Security Levels

Security Level Description

Restricted A user not defined in the CONTROL-M security database is regarded as having no authorizations and cannot perform any function requiring security authorization.

Unrestricted A user not defined in the CONTROL-M security database is regarded as having all CONTROL-M application authorizations.


Security 3-3

CONTROL-M Security Concepts

Overview

Every time a user or a job attempts to perform an action that requires access to or updates any component of the CONTROL-M database, CONTROL-M verifies that the user or job is authorized to perform the attempted action. Tables that list authorizations are contained in a portion of the CONTROL-M database referred to as the Security database. The Security database is maintained using the Security Maintenance utility. See “Security Maintenance Utility (Interactive Mode)” on page 3-11.

Authorizations in the CONTROL-M Security database are divided into the following areas:

• Scheduling Table AuthorizationUser actions performed on specific Scheduling tables.

• Active Jobs File AuthorizationUser actions performed on jobs in the Active Jobs file.

• Entities AuthorizationUser actions performed on various CONTROL-M entities (for example, prerequisite conditions).

Each security check relates to one of the following:

• Whether or not the current ENTERPRISE/CS user is authorized to perform the action that he/she is attempting to perform.

• Whether or not the owner of an executing job is authorized to order or force additional jobs belonging to the same or different owners.



Scheduling Table Authorization

Scheduling Table Authorization determines a user’s authorization to perform actions on an entire Scheduling table. The actions are controlled by this authorization are described in Table 3-2.

Ordering a Scheduling Table

Authorization for an OrderTable action for a Scheduling table is checked in the following situations:

• When a user of ENTERPRISE/CS attempts to order or force a Scheduling table or a job in the table, CONTROL-M checks the user’s authorization for the action.

• When a job executing under CONTROL-M attempts to perform a Do Forcejob action on a Scheduling table or a job in the table, CONTROL-M checks the authorization of the job’s Owner.

• When the Scheduling table is ordered by a User Daily job, CONTROL-M checks the authorization of the User Daily job’s Owner.

Table 3-2 Scheduling Table Authorization

Action Description

Delete Deletes an entire Scheduling table or a job contained in the table.

Read Downloads a Scheduling table from the Server platform to the ENTERPRISE/CS workstation.

Update Uploads a Scheduling table from the ENTERPRISE/CS workstation to the Server platform.

OrderTable Orders or forces an entire Scheduling table or a job in the table. For more information about when this authorization is checked, see “Ordering a Scheduling Table” below.

Delete Deletes an entire Scheduling table or a job contained in the table.


Security 3-5

• When a Scheduling table is ordered by the New Day procedure, CONTROL-M checks the authorization of the CONTROL-M account owner.

NoteIn addition to the security checks described above, CONTROL-M checks authorization for each job in the Scheduling table, as described in “Active Jobs File Authorization” below.

Active Jobs File Authorization

Active Jobs File Authorization determine a user’s authorization to perform actions that affect jobs in the Active Jobs file, or that place jobs in the Active Jobs file. Authorizations are assigned to a user for jobs belonging to specific owners. (For example, user Robert is or is not authorized to order a job whose owner is Michelle). For each ENTERPRISE/CS user, the security facility enables you to specify what action the user is authorized to perform on jobs owned by other users.

NoteCONTROL-M requires that a user be assigned authorization to perform actions even if that user is specified in the job’s Owner parameter.

The actions that can be controlled are described in Table 3-3.

Table 3-3 Active Jobs File Authorization (Part 1 of 2)

Action Authorization

Order Order a job.

Force Force a job.

Rerun Select the Rerun option from the job Details menu.

Hold Select the Hold/Free option from the job Details menu.

Confirm Select the Confirm option from the job Details menu.

Delete Select the Delete option from the job Details menu.

Why Select the Why option from the job Details menu.



Authorization for the Order action is checked in the following situations:

• When a user of ENTERPRISE/CS attempts to order a job from the Job List window, CONTROL-M checks the authorization of the user with regard to the job’s owner.

• When a job is ordered or forced (regardless of how), CONTROL-M checks the authorization of the job’s author with regard to the job’s owner.

Authorization for the Force action is checked in the following situations:

• When a user of ENTERPRISE/CS attempts to force a job from the Job List window, CONTROL-M checks the authorization of the user with regard to the job’s owner.

• When a job executing under CONTROL-M attempts to perform a Do Forcejob action on an entire table or on a job, CONTROL-M checks the authorization of the job’s Owner with regard to the owner of each job contained in the Scheduling table or each job.

NoteWhen performing Order or Force actions on an entire table, CONTROL-M checks Scheduling table authorizations, as described in “Scheduling Table Authorization” on page 3-21, in addition to the security checks described above.

Sysout Select the Sysout option from the job Details menu.

Log Select the Log option from the job Details menu.

Statistics Select the Statistics option from the job Details menu.

Zoom & Save Select the Zoom & Save option from the job Details menu.

Terminate Job Select the Kill job option from the job Details menu.

Table 3-3 Active Jobs File Authorization (Part 2 of 2)

Action Authorization


Security 3-7

The ctmordck utility can be used to generate a report that indicates whether or not the CONTROL-M security mechanism will allow jobs associated with a given User Daily name to run with the authorizations currently assigned to the owner of the User Daily job. See Chapter 2, “Utilities,” for more information.

For the other actions listed above (Rerun, Hold, Confirm, Delete, Why, Sysout, Log, Statistics, Zoom-and-Save, Kill job), CONTROL-M checks that the ENTERPRISE/CS user performing the action is authorized to perform the specific action with regard to the job’s owner.

Entities Authorization

Entities Authorization determines a user’s authorization to perform actions on certain CONTROL-M entities. These entities are accessed either directly from the ENTERPRISE/CS workstation or via utilities on CONTROL-M Server or Agent platforms. Table 3-4 describes the entities that are controlled by these authorizations.

For each of the above entities, a user can be assigned authorization to perform Add, Delete, and Change actions. No special authorization is required to view any of these entities.

Table 3-4 Entities Authorization

Entity Authorization Access

Condition CONTROL-M prerequisite conditions, (including global conditions)

ENTERPRISE/CS ctmcontb

Control Control resources ENTERPRISE/CS

Resource Quantitative resources ENTERPRISE/CS ecaqrtab

Calendar Calendars used when specifying job processing parameters

ENTERPRISE/CS

Log CONTROL-M log ctmlog



Passing Global Conditions Between Data Centers

When a global condition is added or deleted in one data center, ENTERPRISE/CS also performs that action in other data centers. In each of these other data centers, the addition or deletion of the global condition is attributed to a special user named GCSERV.

When the CONTROL-M security mechanism is implemented in a data center to which actions on global conditions will be passed, user GCSERV must be defined in the CONTROL-M security facility at that data center. User GCSERV should be assigned authorization to add and delete prerequisite conditions.

Agent Platform Security Checks

In addition to the security checks detailed above, CONTROL-M utilizes checks provided by the Agent platform operating system to further enhance data center security. These security checks are applied regardless of the security mode (restricted or unrestricted) implemented in the data center.

Agent platform operating system authorization is verified by CONTROL-M in the following instances:

• Before a job is selected or submitted, the operating system security mechanism on the relevant Agent platform is called to verify that the job’s Owner is authorized to execute the job script file. Actions not authorized by the operating system are rejected.

NoteThe owner of each job processing definition must be defined as a user on the Agent platform. Otherwise, CONTROL-M will not order or execute the job.

• When an ENTERPRISE/CS user attempts to perform the Edit JCL/Script action, CONTROL-M/Agent verifies that the user is defined on the Agent platform and that the user has write permission to update the relevant files.


Security 3-9

Summary of Authorizations

The following tables summarize the authorizations required to perform various actions under CONTROL-M.

Table 3-5 Authorization – job submission from a User Daily job

Who Authorization

User Daily job’s owner Scheduling Table authorization: OrderTable for the Scheduling table containing the jobs.

Owner of each job ordered by the User Daily job

Agent platform operating system authorization to execute the job script file.

Author of each job ordered Active Jobs File authorization: Order for the owner of the job.

Table 3-6 Authorization – job submission from the New Day procedure

Who Authorization

CONTROL-M account owner

Scheduling Table authorization: OrderTable for the Scheduling table containing the jobs.

Owner of each job ordered by the User Daily job


Author of each job ordered Active Jobs File authorization: Order for the owner of the job.

Table 3-7 Authorization – Order/Force a Scheduling Table from ENTERPRISE/CS

Who Authorization

ENTERPRISE/CS user Scheduling Table authorization: OrderTable for the Scheduling table containing the jobs.

Owner of each job ordered or forced


Author of each job ordered or forced

Active Jobs File authorization to order/force: Order/Force for the owner of the job.



Table 3-8 Authorization – Ordering/Forcing a job from ENTERPRISE/CS

Who Authorization

ENTERPRISE/CS user Scheduling Table authorization: OrderTable for the Scheduling table containing the job.Active Jobs File authorization to order/force a job: Order/Force for the owner of the job.Agent platform operating system authorization to execute the job script file.

Owner of each job ordered or forced


Author of each job ordered or forced

Active Jobs File authorization: Order for the owner of the job.

Table 3-9 Authorization – Do Forcejob

Who Authorization

Owner of the job performing the Do Forcejob action

Scheduling Table authorization: OrderTable for Scheduling table containing the job(s) to be forced.Active Jobs File authorization: Force for the owner of the job(s) being forced.

Owner of each job forced Agent platform operating system authorization to execute the job script file.

Author of each job forced Active Jobs File authorization: Order for the owner of the job.

Table 3-10 Authorization – Actions on a Job in the Active network

Who Action Authorization

ENTERPRISE/CS user

All actions A user on the Agent platform.

Rerun, Hold, Confirm, Delete, Why, Sysout, Log, Statistics, Kill Job, Zoom-and-Save

Separate Active Jobs File authorization for each specified action.

Edit JCL/Script Operating system write permission for the script files on the Agent platform.


Security 3-11

Security Maintenance Utility (Interactive Mode)

The ctmsec CONTROL-M Security Maintenance utility defines users in the CONTROL-M Security database, assigns authorization types for various action relevant to working with CONTROL-M using an ENTERPRISE/CS workstation. The ctmsec utility is run on the Server platform.

NoteModifications to authorizations by this utility are implemented only after the utility is exited.

Users can also be defined as part of a group. Authorizations can be specified for a specific user, for a group, or for both. See “User Authorization” on page 3-32.

When assigning a user to a group, the following rules apply:

• If there are no authorizations defined for the specific user, the user inherits the authorizations specified for the group.

• If there are authorizations defined for a specific user, these authorizations take precedence.

• When defining an authorization for a user (for example, Scheduling Table), use of the (D)efault setting enables the specific authorization (for example, Read) defined for the group.

• If all authorizations for a specific CONTROL-M element (for example, Scheduling Table) for a user are defined with a (D)efault setting, it is more efficient to delete the authorizations for that element for the user.

• Authorizations not specifically defined for a group or for a user not belonging to a group revert to the Full Security parameter setting. See “System Parameters” on page 5-3.



Certain functions of the ctmsec utility can be activated in batch mode from the command line. For more information, see “Security Maintenance Utility (Batch Mode)” on page 3-32.

NoteWhen working with CONTROL-M via the ENTERPRISE/CS workstation, mask characters are available for all options. Mask characters * and $ that are used when assigning authorizations in the CONTROL-M Security database, are translated as mask characters during runtime security checking. (For example, if User1 is granted full Scheduling Table authorization for table ACC*, CONTROL-M allows User1 to update and/or order any table whose name starts with ACC). Valid mask characters are:

* represents any number of characters (including no characters).$ represents a single character.

Mask character authorizations do not override full name authorizations. (For example, if User1 from the example above is also defined to have only Read privileges for ACC999, CONTROL-M will not allow User1 to update and/or order table ACC999).

To invoke the CONTROL-M Security Maintenance utility, log on to the Server platform as the CONTROL-M/Server owner (for example, user controlm) and specify the command:

• ctmsec

-or-

• Select Security Authorization => Security Maintenance Utility from the CONTROL-M Main Menu. See “CONTROL-M Main Menu” on page 4-6.

The CONTROL-M Security Maintenance Utility Main menu is displayed.


Security 3-13

Figure 3-1 Security Maintenance Menu

+-----------------------------------------------+| CONTROL-M SECURITY MAINTENANCE UTILITY || Main Menu |+-----------------------------------------------+

1) User Maintenance2) Group Maintenance3) Scheduling Table Authorization4) Active Jobs File Authorization5) Entities Authorizationq) Quit Enter option:

Each of the options appearing in the Main menu is described below.

User Maintenance

The User Maintenance option of the ctmsec utility is used to add, delete, or modify specific users in the CONTROL-M Security database.

NoteEach ENTERPRISE/CS user who performs actions affecting the CONTROL-M database or jobs in the Active Jobs file must be defined in the CONTROL-M Security database when full security is on. In addition, all other users who invoke CONTROL-M Security utilities must be defined in the Security database and assigned appropriate privileges.

Select Option 1 from the Security Maintenance Main menu. The User Maintenance menu is displayed.



Figure 3-2 User Maintenance Menu

User Maintenance Menu1) List Users2) Add User3) Delete User4) Modify User Information5) Copy Userq) Quit

Enter option:

To list existing users in the CONTROL-M Security database:

Select Option 1 from the User Maintenance menu.


Name Description GroupGCSERV For passing Global conds. Group1User1 Group2

Press ENTER to continue:

Press <Enter> to return to the User Maintenance menu.

To add a new user to the CONTROL-M Security database:

1. Select Option 2 from the User Maintenance menu.

A prompt similar to the following is displayed:

User []:

2. Specify the user name of the ENTERPRISE/CS user (maximum 30 characters, case-sensitive).


Security 3-15


User ‘User2’ is not defined in the CONTROL-M Security database. Add this user now [Y/N]?

3. Enter Y to add the new user.

The following prompts are displayed:

Description []:Group []:

4. Specify a value for Description (maximum length: 50 characters) or press <Enter>.

This field is optional and is for documentation purposes only.

5. Specify a value for Group (maximum length: 32 characters) or press <Enter>.

This field is optional. If specified, the user inherits all authorizations defined for the group that are not specifically defined for the user.

6. Press <Enter> to return to the User Maintenance menu.

To delete an existing user from the CONTROL-M Security database:



User [User1]:

2. Specify the user name of the ENTERPRISE/CS user to delete. After confirmation, the user is deleted from the Security database, and the User Maintenance menu is displayed.



To modify the Description or Group fields for an existing user:



User/Group [User1]:

2. Specify the user name of the ENTERPRISE/CS user to modify.

A user definition similar to the following is displayed:

User: User1-----------------------Modify User Information1) Description :2) Group :s) Save and return to menuc) Cancel and return to menuEnter command, or specify item number to modify:

3. To modify a field, type the number preceding the field.

You are prompted to supply a value for the field.

• Maximum length for Description is 50 characters. The Description field is for documentation purposes only

• Maximum length for Group is 32 characters.

4. Type s to save your changes and return to the previous menu. Modifications are not saved until you perform this action.

-or-

Type c to cancel all changes and return to the previous menu.


Security 3-17

To copy an existing user:



FROM user:

2. Specify the exact name of the user to be copied.


TO user:

3. Specify a new user name for the ENTERPRISE/CS user (maximum 30 characters, case-sensitive).


User ‘User2’ is not defined in the CONTROL-M Security database.Add this user now [Y/N]?

4. Enter Y to add the new user. The following prompt is displayed:

Description []:

5. Specify a value for Description (maximum length 50 characters). This field is optional and is for documentation purposes only.


Group []:

6. Specify a value for Group (maximum length 32 characters).

This field is optional. If specified, the user inherits all authorizations defined for the group that are not specifically defined for the user.

7. Press <Enter> to return to the User Maintenance menu.



Group Maintenance

Each ENTERPRISE/CS user with a user account on the Server platform, who is defined in the CONTROL-M Security database, can be defined as part of a group. Belonging to a group is optional. All users belonging to a group inherit the authorizations defined for the group.

Select Option 2 from the Security Maintenance Main menu to display the Group Maintenance menu.

Figure 3-3 Group Maintenance Menu

Group Maintenance Menu-----------------------1) List Groups2) Add Group3) Delete Group4) Modify Group Informationq) QuitEnter option:

To list existing groups in the CONTROL-M Security database:

1. Select Option 1 from the Group Maintenance menu.


Group DescriptionGroup1 CONTROL-M GroupGroup2 Press ENTER to continue:

2. Press <Enter> to return to the Group Maintenance menu.


Security 3-19

To add a new group to the CONTROL-M Security database:

1. Select Option 2 from the Group Maintenance menu. The following prompt is displayed:

Groupname []:

2. Specify the Group name (maximum length 32 characters).

This name must be unique. It cannot be an existing user or group name. The following prompt is displayed:

Description []:

3. Specify a Description (maximum length 50 characters) or press <Enter>. The Description field is optional and is for documentation purposes only. The group is added to the Security database, and the Group Maintenance menu is displayed.

To delete an existing group from the CONTROL-M Security database:

1. Select Option 3 from the Group Maintenance menu. A prompt similar to the following is displayed:

Group [Group1]:

2. Specify the name of the group to delete. After confirmation, the group is deleted from the Security database, and the Group Maintenance menu is displayed.

To modify the Description field for an existing group:

1. Select Option 4 from the Group Maintenance menu. A prompt similar to the following is displayed:

Group [Group1]:

2. Specify the name of the group to modify.

A group definition similar to the following is displayed:



Group: Group1Modify Group Information-----------------------1) Description :s) Save and return to menuc) Cancel and return to menu

Enter command, or specify item number to modify:

3. To modify the Description field, type 1.

You are prompted to supply a value for the field (maximum length 50 characters). This field is optional and is for documentation purposes only.


-or-



Security 3-21


This option is used to assign authorizations to a user or group to perform actions on a Scheduling table.

For more information about the types of authorization that can be granted using this option, see “Scheduling Table Authorization” on page 3-4.

To maintain Scheduling Table authorizations:

1. Select Option 3 from the Main menu. A prompt similar to the following is displayed:

+--------------------------------------+| SCHEDULING TABLE AUTHORIZATION |+--------------------------------------+

User/Group [User1]:

2. Specify the user or group for whom you are defining authorizations.

If the user or group is not defined in the CONTROL-M/Server database, the following message is displayed:

User/Group ‘name’ is not defined in the CONTROL-M Security database.


3. Press <Enter> to return to the Main menu. The Scheduling Table Authorization menu is displayed:



Figure 3-4 Scheduling Table Authorization Menu

Scheduling Table Authorization Menu-----------------------------------1) List Tables2) Create/Modify Table Authorization3) Delete Table Authorization

q) Quit

Enter option:

To list existing Scheduling Table authorizations for the specified user/group:

» Select Option 1 from the Scheduling Table Authorization menu.


List for user: User1Table Delete Read Update OrderTableSched1 N N N NSched2 N Y Y YPress ENTER to continue:

Press <Enter> to return to the Scheduling Table Authorization menu.

To create or modify Scheduling Table authorizations for the specified user:

1. Select Option 2 from the Scheduling Table Authorization menu. The following prompt is displayed:

Table Name:

2. Specify the name of a Scheduling table (maximum 20 characters, case-sensitive). The Scheduling table does not have to exist at the time you specify authorizations for it.


Security 3-23

A table definition similar to the following is displayed:

Scheduling Table Name: Sched1, User/Group: User1Create/Modify Table Authorization---------------------------------1) Delete :N2) Read :N3) Update :N4) OrderTable :N

s) Save and return to menuc) Cancel and return to menu

Enter command, or specify item number to toggle Y/N/D:

The Y setting enables authorization for the action (for example, Read), N disables the authorization, and (D)efault uses the authorization defined for the user’s group. If the user was previously authorized for this scheduling table, the user’s current authorizations are displayed; otherwise, all authorizations are set toN.

3. To modify an authorization, type the number preceding the authorization. Press <Enter> to toggle the authorization between N, Y and D.

Type s to save your changes and return to the previous menu. Modifications are not saved until you perform this action.

-or-


To delete Scheduling Table authorizations for the specified user/group:

1. Select Option 3 from the Scheduling Table Authorization menu. The following prompt is displayed:

Table Name:



2. Specify the name of the Scheduling table whose authorizations you want to delete for this user or group (or press <Enter> to return to the menu).

The user’s authorizations for this table are deleted from the Security database, and the Scheduling Table Authorizations menu is displayed. If the user belongs to a group, authorizations for the Scheduling Table revert to the authorizations defined for the group.


This option is used to assign authorizations to a user or group for actions on jobs in the Active Jobs file. The authorizations assigned are with regard to specific job owners (the user appearing in the Owner parameter for each job).

For more information about the types of authorization that can be granted using this option, see “Active Jobs File Authorization” on page 3-5.

To maintain Active Jobs File authorizations:

1. Select Option 4 from the Main menu.


+--------------------------------------+| ACTIVE JOBS FILE AUTHORIZATION |+--------------------------------------+

User/Group[]:

Specify the user or group for whom you are defining authorizations.

If the user or group is not defined in the CONTROL-M/Server database, the following message is displayed:

User/Group ‘name’ is not defined in the CONTROL-M Security database.Press ENTER to continue:


Security 3-25

2. Press <Enter> to return to the Main menu. The Active Jobs File Authorization menu is displayed:

Figure 3-5 Active Jobs File Authorization Menu

Active Jobs File Authorization Menu-----------------------------------1) List Owner Names2) Create/Modify AJF Authorization3) Delete AJF Authorization

q) Quit

Enter option:

To list owners for whom the user has Active Jobs File authorizations:

Select Option 1 from the Active Jobs File Authorization menu.


List for user: User1

Owner Node Group Hold Force Del Rerun Log Why Statist Sysout Order Conf Z&S Kill

----- ---------- ---- ----- --- ----- --- --- ------- ------ ----- ---- --- ----

Owner1 Node1 N Y Y Y N N N N Y N N Y

Owner2 Node2 Y Y Y Y Y Y Y Y Y Y N N


To create or modify Active Jobs File authorizations for the specified user:

1. Select Option 2 from the Active Jobs File Authorization menu.The following prompt is displayed:

Owner:

2. Specify the name of a job owner.




Node Group:

3. Specify the node group of the Agents where the job can be scheduled to run (maximum 30 characters, case-sensitive).

NoteA value must be specified for the Node Group prompt. (Null is not a valid value.) To indicate all node groups, specify an asterisk (*) for this prompt.


Owner: Owner1, Node Group: Node1 User/Group: User1

Create/Modify Active Jobs File Authorization--------------------------------------------

1) Order :Y2) Force :Y3) Rerun :Y4) Hold :N5) Confirm :N6) Delete :Y7) Why :N8) Sysout :N9) Log :N10) Statistics :N11) Zoom & Save :N12) Kill job :Ns) Save and return to menuc) Cancel and return to menu



Security 3-27

The Y setting enables authorization for the action (for example, Read), N disables the authorization, and (D)efault uses the authorization defined for the user’s group. If the user was previous authorized for this owner and node, the user’s current authorizations are displayed; otherwise, all authorizations are set toN.


5. Type s to save your changes and return to the previous menu.

-or-


To delete Active Jobs File authorizations for the specified user:

1. Select Option 3 from the Active Jobs File Authorization menu.


Owner:

2. Specify the name of the Job owner for whom authorizations should be deleted (or press <Enter> to return to the menu).

The following prompt is displayed

Node Group:

3. Specify the name of the Node group of the Job owner for whom authorizations should be deleted (or press <Enter> to return to the menu).

The user authorizations for this owner on the Node group are deleted from the Security database, and the Active Jobs File Authorization menu is displayed.




This option is used to assign authorizations to a user or group to perform actions relating to CONTROL-M entities.

For more information about the types of authorization that can be granted using this option, see “Entities Authorization” on page 3-7.

To maintain Entities authorizations:

1. Select Option 5 from the Main menu.


+----------------------------------------+| CONTROL-M ENTITIES AUTHORIZATION |+----------------------------------------+

User/Group [User1]:

2. Specify the user or group for whom you are defining authorizations.

• If the user or group name is not defined on the Server platform, a message similar to the following is displayed:

User ‘name’ is not defined in the CONTROL-M Security databasePress ENTER to continue:

Press <Enter> to return to the Main menu.

• If the user or group name is defined the Entities Authorizations menu is displayed:


Security 3-29

Figure 3-6 Entities Authorizations Menu

Entities Authorizations Menu----------------------------1) List Entity Categories2) Create/Modify Entity Authorizations3) Delete Entity Category

q) Quit

Enter option:

To list Entity categories for which the user or group has authorizations:

1. Select Option 1 from the Entities Authorizations menu.


List for user: User1Category Add Delete ChangeCALENDAR Y N YQUANTITATIVE RESOURCE Y N NCONTROL RESOURCE Y N NPress ENTER to continue:

2. Press <Enter> to return to the Entities Authorizations menu.



To create or modify Entity authorizations for the specified user or group:

1. Select Option 2 from the Entities Authorizations menu. The following menu is displayed:

Categories----------1) CALENDAR2) LOG3) QUANTITATIVE RESOURCE4) CONDITION5) CONTROL RESOURCEq) QuitCategory number:

2. Specify the number of the category for which to create or modify authorizations. For example, if you specify 1, a list similar to the following is displayed:

Category: CALENDAR, User: User1

Create/Change Entity Authorizations-----------------------------------1) Add :Y2) Delete :N3) Change :Ns) Save and return to menuc) Cancel and return to menu


The Y setting enables the specific authorization (for example, Read), N disables the authorization, and (D)efault uses the authorization defined for the group with which the user is associated. If the user was previous authorized for this category, the user’s current authorizations are displayed; otherwise, all authorizations are set toN.


Security 3-31



-or-


To delete Entity authorizations for the specified user or group:

1. Select Option 3 from the Entities Authorizations menu. The following menu is displayed:

Categories----------1) CALENDAR2) LOG3) QUANTITATIVE RESOURCE4) CONDITION5) CONTROL RESOURCEq) Quit

Category number:

2. Specify the number of the category for which to delete authorizations and press <Enter>.

The user or group’s authorizations for this category are deleted from the Security database and the Entities Authorizations menu is displayed.



Security Maintenance Utility (Batch Mode)

Certain ctmsec Security Maintenance utility functions can be activated in batch mode. These functions include listing, updating, and deleting entries in the CONTROL-M Security database. These functions are described in “Security Maintenance Utility (Interactive Mode)” on page 3-11.

User Authorization

The user authorization options of the ctmsec command are used to list, update, delete, and copy users in the CONTROL-M Security database.

• Use the following command to list user authorizations:ctmsec -USER_LIST <user>

• Use the following command to update user authorizations:ctmsec -USER_UPDATE <user> <description> <group>

• Use the following command to delete user authorizations:ctmsec -USER_DELETE <user>

• Use the following command to copy user authorizations from one user to another:ctmsec -USER_COPY <from_user> <to_user>

NoteIf the user in the commands listed above is a CONTROL-M/Agent user, then the <user> format is <username@node_id>.


Security 3-33

Group Authorization

Group authorization options of the ctmsec command are used to copy, list, modify, and delete groups in the CONTROL-M Security database.

• Use the following command to list group authorizations:ctmsec -GROUP_LIST <group>

• Use the following command to update group authorizations:ctmsec -GROUP_UPDATE <group> <description>

• Use the following command to delete group authorizations:ctmsec -GROUP_DELETE <group>


The Scheduling table authorization options of the ctmsec command are used to assign authorizations to users and groups to perform actions on Scheduling tables.

• Use the following command to list Scheduling table authorizations:ctmsec -SCHED_LIST {<user>|<group>}

• Use the following command to update Scheduling table authorizations:ctmsec -SCHED_UPDATE {<user>|<group>} <table>

[-DELETE {Y|N|D}] [ -READ {Y|N|D}][ -ORDER {Y|N|D}] [ -UPDATE {Y|N|D}]

• Use the following command to delete Scheduling table authorizations:ctmsec -SCHED_DELETE {<user>|<group>} <table>





The Active Jobs File authorization options of the ctmsec command are used to assign authorizations to users and groups to perform actions on jobs in the Active Jobs file.

• Use the following command to list Active Jobs File authorizations:ctmsec -ACT_LIST {<user>|<group>}

• Use the following command to update Active Jobs File authorizations:

ctmsec -ACT_UPDATE {<user>|<group>} <owner> <node>[-HOLD {Y|N|D}]

[-FORCE {Y|N|D}] [-ORD {Y|N|D}] [-CONFIRM {Y|N|D}] [-DELETE {Y|N|D}] [-WHY {Y|N|D}] [-RERUN {Y|N|D}] [-SYSOUT {Y|N|D}] [-LOG {Y|N|D}] [-STATISTICS {Y|N|D}] [-ZOOM_AND_SAVE {Y|N|D}] [-KILL_JOB {Y|N|D}]

• Use the following command to delete Active Jobs File authorizations:ctmsec -ACT_DELETE {<user>|<group>} <owner>



The entity authorization options of the ctmsec command are used to assign authorizations to users and groups to perform actions relating to CONTROL-M entities.

• Use the following command to list entity authorizations:ctmsec -ENTITY_LIST {<user>|<group>}


Security 3-35

• Use the following command to update entity authorizations:ctmsec -ENTITY_UPDATE {<user>|<group>}

{LOG|QR|CONTROL|CALENDAR|CONDITION}[-ADD {Y|N|D}] [-DELETE {Y|N|D}] [-CHANGE {Y|N|D}]

• Use the following command to delete entity authorizations:ctmsec -ENTITY_DELETE {<user>|<group>}

{LOG|QR|CONTROL|CALENDAR|CONDITION}


Exporting Security Definition Tables

The EXPORT option of the ctmsec command is used to export CONTROL-M Security Definition tables. The file that is generated by the ctmsec command is an executable file containing API functions that will redefine all the security entries when the script is run. The generated file can be modified, and imported to any CONTROL-M installation.

NoteThe file created using the EXPORT option of the ctmsec utility, can be modified before security definitions are imported either back to the same installation, or to a different CONTROL-M installation. This is different from the file that is created using the Backup Security Definition Tables option of the Security Authorization Menu (which cannot be modified). For more information about exporting CONTROL-M Security Definition tables, see “Security Authorization Menu” on page 4-29.

Use the following command to export CONTROL-M Security Definition tables:

ctmsec -EXPORT <filename>

where <filename> is the full path name of the file to be exported.



Example

ctmsec -EXPORT /home/controlm/securedata

Importing Security Definition Tables

The file created using the -EXPORT option of the ctmsec utility contains multiple ctmsec commands that describe the various security definitions in your CONTROL-M installation. If necessary, these ctmsec commands can be modified before the security definitions are imported either back to the same installation, or to a different CONTROL-M installation.

To import security definitions execute the script file that was created using the ctmsec utility.

For Example:

/home/controlm/securedata

NoteThis procedure will work only with a file that was created using the -EXPORT option of the ctmsec utility. If your input is a file created using the Backup Security Definition Tables option of the Security Authorization menu, then you must import using the Restore option in that same menu. for more information, see Table 4-7, “Security Authorization Menu,” on page 4-29.


Security 3-37

Importing Security Definitions from CONTROL-M version 2.2.5

Use the following steps to import security definitions from an installation of CONTROL-M version 2.2.5:

1. Creating a security definitions export file: in the version 2.2.5 installation, choose the Export Security Definition Tables option from the Security Authorization menu.

2. Importing the security definitions export file: in the version 6.0.03 installation, use the following command to import the security definitions:

ctm_restore_aut <filename>

where <filename> is the full path name of the file created by the option chosen in step 1.

NoteThe security definitions cannot be modified before they are imported to the version 6.0.03 installation.


Maintenance 4-1

4

Maintenance 4

This chapter describes how to maintain the CONTROL-M installation and database. The following topics are covered:

• Starting/stopping CONTROL-M Tasks.• Periodic Maintenance.• CONTROL-M Menu System.



Starting/Stopping CONTROL-M Tasks

To start CONTROL-M functions in the data center, the following tasks must be running on the Server platform:

• SQL Database Server.• CONTROL-M/Server.

The SQL Database Server must be started before CONTROL-M/Server and must be active as long as CONTROL-M/Server is active.

NoteIf CONTROL-M is implemented using an existing SQL Database Server, starting and stopping the server is the responsibility of the database administrator and is beyond the scope of this document.

CONTROL-M tasks can be started or stopped on the Server platform using one of the following methods:

• Automatic startup/shutdown (as part of the Server platform boot and shutdown processes).

The installation procedure for CONTROL-M/Server includes directions for adding startup of SQL Database Server and CONTROL-M/Server to the boot procedure and shutdown procedure of the Server platform. For more information see the CONTROL-M/Server for Unix Installation Guide.

• Using the CONTROL-M Menu system.

The CONTROL-M Menu system provides the necessary options for easily starting/stopping CONTROL-M/Server and the SQL Database Server. For more information, see “CONTROL-M Manager Menu” on page 4-8.


Maintenance 4-3

• Using supplied scripts.

CONTROL-M is supplied with scripts for starting up and shutting down CONTROL-M/Server and the SQL Database Server. You can invoke these scripts directly (as described below) or incorporate them into your own scripts.

To start up the SQL Database Server and CONTROL-M/Server manually:

1. Log in as the CONTROL-M/Server account owner.

2. For the SQL server, specify the command: startdb

3. For CONTROL-M/Server, specify the command: start-ctm

To shut down CONTROL-M/Server and the SQL Database Server manually:

1. Log in as the CONTROL-M/Server account owner.

2. For CONTROL-M/Server, specify the command: shut-ctm

3. For the SQL database server, specify the command: shutdb

Periodic Maintenance

The following procedures should be performed on a regular basis:

• Check available space in the CONTROL-M database.• Clean up the SQL database message log.• Clean up the proclog directory.

Each of these topics is discussed below.



Checking Available Space in the CONTROL-M Database

It is recommended that the amount of available space in the CONTROL-M database be checked on a regular basis. If the available space falls below 20%, the database should be extended (see “Extending the Size of the CONTROL-M Database” later in this chapter).

You can check the available space in the CONTROL-M database using the option Check Database in the Database Creation menu (described on page 4-10).

You can also define a CONTROL-M job that automatically checks the database on a regular basis and issues a Shout message if a problem is detected. Such a job would call the script:

<controlm_home>/ctm/scripts/ctmdbcheck

This is the same script used by the Check Database option. Possible messages generated by this script relating to the amount of available space in the CONTROL-M database are:

WARNING: Database is more than half fullATTENTION: Database is more than 80% fullATTENTION: Database log segment is more than 90% full

These messages can be detected in a CONTROL-M job using the On Statement/Code parameter. Appropriate Shout messages could then be issued as required.

Cleaning Up the SQL Database Message Log

The SQL database server writes a message to a log file when the server is started or shut down, and when a database error occurs. This file is not automatically truncated. If not manually truncated, the file will utilize a large amount of disk space.

The responsibility of maintaining the log file depends on whether CONTROL-M/Server uses the dedicated SQL database server provided with the installation, or an existing SQL database server.


Maintenance 4-5

• When CONTROL-M/Server uses a dedicated SQL database Server provided during installation, it is the responsibility of the CONTROL-M administrator to truncate this file on a regular basis. The location of this file depends on the database type:

For Sybase:

<controlm_path>/sybase/data/errorlog

For Oracle:

<controlm_path>/oracle/admin/<$CONTROLM_DATABASE>/bdump/alert_<$CONTROLM_DATABASE>.log

• If CONTROL-M/Server is configured to use an existing SQL Database Server, it is the responsibility of the database administrator to truncate this file on a regular basis.

NoteIn both the above mentioned paths, <controlm_path> is the home directory of the CONTROL-M account owner.

Cleaning Up the Proclog Directory

When CONTROL-M/Server is using a diagnostic level greater than zero, diagnostics log files are written to the following directory:

<controlm_path>/ctm/proclog/

where <controlm_path> is the home directory of the CONTROL-M/Server account owner. For more information, see “Set Diagnostics Level” on page 4-43.

NoteIf CONTROL-M/Server is operated in this manner for long time, these log files will utilize a large amount of disk space. The CONTROL-M administrator should delete these files when they are no longer needed.



CONTROL-M Menu System

The CONTROL-M Menu system enables you to access a variety of functions and utilities used to maintain CONTROL-M.

The functions accessible from these menus are organized according to function group, enabling you to easily locate the desired option. These menus can only be accessed from the account of the CONTROL-M/Server owner.

CONTROL-M Main Menu

The CONTROL-M Main menu is the entry point for accessing the CONTROL-M Menu system.

To open the CONTROL-M Main menu:

1. Log into the Server platform as the CONTROL-M/Server owner (for example, user controlm).

2. Enter the following command:ctm_menu


Figure 4-1 CONTROL-M Main Menu

CONTROL-M Main Menu: Select one of the following menus:1 - CONTROL-M Manager2 - Database Creation3 - Database Maintenance4 - Database Mirroring5 - Security Authorization6 - Parameter Customization7 - Node Group8 - Agent Status9 - Troubleshooting

q - Quit

3. Enter the corresponding number and press Enter. Each menu is described in this chapter.


Maintenance 4-7

The following menus are available:

Table 4-1 CONTROL-M Main Menu

Menu Item Description

CONTROL-M Manager Start up and shut down CONTROL-M and the SQL database server.

Database Creation Create or delete the CONTROL-M database.

Database Maintenance Perform various CONTROL-M database maintenance functions.

Database Mirroring Perform various CONTROL-M mirror database functions.

Security Authorization Export or import Security Definition tables and invoke the CONTROL-M Security Maintenance utility (ctmsec) to define user authorizations.

Parameter Customization

View and update parameters for customizing CONTROL-M/Server.

Node Group Maintain Node Groups for load balancing.

Agent Status View and update the communication status of Agent platforms.

Troubleshooting Perform various troubleshooting functions.

Quit Exit to the shell prompt.



CONTROL-M Manager Menu

The CONTROL-M Manager menu is used to start and stop the SQL database server and CONTROL-M/Server. Selecting CONTROL-M Main Menu => CONTROL-M Manager displays the following:

Figure 4-2 CONTROL-M Manager Menu

CONTROL-M Manager Menu: Select one of the following options:1 - Check All2 - Start All3 - Start Database4 - Start CONTROL-M/Server5 - Stop All6 - Stop Database7 - Stop CONTROL-M/Serverq - Quit

• All references below to starting and stopping the SQL database server are applicable only when CONTROL-M/Server uses a dedicated instance of the SQL database server.

• If CONTROL-M/Server uses a shared instance of the SQL database server to maintain the CONTROL-M database, the database administrator is responsible for starting and stopping the server.

• Similarly, if mirroring of the CONTROL-M database is implemented, the database administrator is responsible for starting and stopping the mirroring server.


Maintenance 4-9

Table 4-2 Options of the CONTROL-M Manager Menu


Check All Determines whether the SQL database server task and the CONTROL-M/Server task are currently running, and reports the status of each task.

Start All Starts any tasks required for CONTROL-M that are not already running. The SQL database server is started first, followed by CONTROL-M/Server.

Start Database Starts the SQL database server (only if dedicated to the CONTROL-M database).

Start CONTROL-M/Server

Starts CONTROL-M/Server. The SQL database server must be running when this option is selected.

Stop All Stops all CONTROL-M tasks. CONTROL-M/Server is stopped first, followed by the SQL database server.

Stop Database Stops the SQL database server (only if dedicated to the CONTROL-M database). CONTROL-M/Server should not be running when this option is selected.

Stop CONTROL-M/Server

Stops CONTROL-M/Server.

Quit Quits the CONTROL-M Manager menu and returns to the CONTROL-M Main menu.



Database Creation Menu

The Database Creation menu is used to perform functions related to creating and deleting the CONTROL-M database. Selecting CONTROL-M Main Menu => Database Creation displays the following:

Figure 4-3 Database Creation Menu

Database Creation Menu-----------------------------

Select one of the following options:

1 - Show Database Parameters2 - Build Database3 - Delete Database4 - Erase Database Contents5 - Check Database

q - Quit

Table 4-3 Options of the Database Creation Menu


Show Database Parameters

Displays the CONTROL-M database parameters. To choose this option, select 1 from the Database Creation menu. Information similar to the following is displayed:

SQL Server/<SQL version number>/...

SYBASE=/home/ctm/sybaseCONTROLM_USER=ctrlmCONTROLM_DATABASE=ctrlmDSQUERY=CTRLMDSLISTEN=CTRLM

Build Database Builds a new CONTROL-M database. CONTROL-M/Server must be shut down before selecting this option. For a detailed description of the database build process, see the “Build the Database” step in Chapter 3 of the CONTROL-M/Server for Unix Installation Guide.


Maintenance 4-11

Delete Database Drops (deletes) the CONTROL-M database entirely and removes the database files. After using this option, you cannot use CONTOL-M. To use CONTOL-M, you must rebuild the entire database, rebuild the objects as well as redefine CONTROL-M objects. Server must be shut down before selecting this option.Note: The Delete Database option is not supported for CONTROL-M installations that were installed using an existing database server.

Erase Database Contents

Erases the contents of the CONTROL-M database after verification. For example, Scheduling tables, calendars, CONTROL-M log, Active Jobs file. The database files are not deleted. After using this option, you can still use CONTROL-M, but no previous data exists. CONTROL-M/Server must be shut down before selecting this option.





Database Maintenance Menu

The Database Maintenance menu is used to perform functions related to maintaining the CONTROL-M database. Selecting CONTROL-M Main Menu Database Maintenance displays a menu similar to Figure 4-4.

NoteIf you are using a dedicated Oracle SQL database server, an additional option called Archive Mode appears at the beginning of this menu. This option is described below.

Check Database Displays the size of the CONTROL-M database and availability of space, and verifies database integrity. Information similar to the following is displayed:

db total = 29000.0 KB (data= 23500.00 log= 5500.00)data used = 1928 KB (8%).log used = 0 KB (0%).Checking database

This function is also available by running the script:<controlm_home>/ctm/SCRIPTS/ctmdbcheck.ctmdbcheck can also be used to provide automatic database and transaction log monitoring. The following options are available:

ctmdbcheck [db threshold %] [log threshold %]ctmdbcheck [general threshold %]

where db threshold % and log threshold % are user defined percentages which, when exceeded, generate shout messages to ENTERPRISE/CS warning that the CONTROL-M database or log should be extended.

Quit Quits the Database Creation menu and returns to the CONTROL-M Main menu.




Maintenance 4-13

Figure 4-4 Database Maintenance Menu

Database Maintenance Menu-----------------------------

Select one of the following options:1 - Archive mode 2 - Backup Database or 3 - Restore Database4 - List All Devices5 - List Backup Devices6 - Add Backup Device7 - Drop Backup Device8 - Extend Database Size9 - Extend Temporary Database (Tempdb) Size10 - Extend Database Log Size11 - Show Database Parameters12 - Check Database

q - Quit

Archive Mode

Activates Oracle archive mode. In this mode, Oracle database logs are written to a special backup destination when they are full, and before they are overwritten by new information.

If you specify the same device for each backup, make sure the previous backup is copied to the appropriate media for archive purposes.

Two types of back up can be performed, depending on the archive mode:

• Cold backup – copies the contents of the database to a file when CONTROL-M is down.

• Hot backup – copies the contents of the database to a file when CONTROL-M is active.

When the Archive Mode option is chosen in the Database Maintenance menu, you are asked to supply the name of the destination to contain archived Oracle logs. The archived logs can be used in case of a database crash to restore the database up until the most recent SQL transaction.



If you choose to use Archive mode, it should be a choice for long term use. If this option is activated and deactivated frequently, the archived logs will not provide useful information for database restoration.

NoteIf Archive mode is activated, database transactions may be performed more slowly and archive files will require more disk space.

Backup Database

This option backs up the CONTROL-M database onto a backup device. The function performed by this option is identical to the function performed by the ctmdbbck utility. See “ctmdbbck” on page 2-37 for more details. This option can be invoked while the database is running.

The Backup Database procedure should be performed periodically. Daily backup is recommended.

Sybase Backup

To back up a Sybase database:

Step 1 Select 2 from the Database Maintenance menu.

Step 2 The following prompt is displayed:

Enter backup device name [tapedump2]:

Enter the name of the backup device. The backup device must be either a valid device defined in the SQL database, or the full path name of a file to be created by the backup procedure. Use the option List Backup Devices (see“List Backup Devices” on page 4-19) to display a list of valid devices.

The backup procedure backs up the Sybase database.

Oracle Backup

To back up an Oracle database:


Maintenance 4-15

Step 1 Select 2 from the Database Maintenance menu.


Enter a destination directory name [<ctm_home_dir>]:

Press <Enter> to accept the default directory, or enter the name of a different directory where you want the backup to be saved. The backup procedure assigns its own filename.

Step 3 If Archive mode is not active at your site, a Cold backup (described below) is automatically performed.

If Archive mode is active, the following prompt is displayed:

Enter your choice for backup mode (Hot or Cold) [H/C]:

You have the choice between two types of Oracle database backup; Hot or Cold.

Cold Backup

• Can be used to restore the database to the state it was in when the backup was performed.

• Is performed in non-Archive mode.

WarningCONTROL-M is automatically shut down when a Cold backup is performed. After the backup is completed, CONTROL-M will have to be manually restarted.

Hot Backup

• Can be used to restore the database to the state it was in after the last completed transaction (the last COMMIT command executed).

• Is performed in Archive mode, and the backup procedure sets the mode if it was not previously set. Running the database in Archive mode requires extra disk space for Control files.



• Requires that the directory you specify exist prior to starting the backup.

NoteYou can perform a Hot backup on a dedicated database. However, you cannot perform a Hot backup on an existing database.

Type H for a Hot backup or C for a Cold backup.


Specify archiving process destination directory:

Enter the directory in which the archive process will store its Control files.

The backup procedure shuts down CONTROL-M/Server before beginning the backup, and starts it again after the backup is completed. The procedure displays informational messages indicating its progress.

Restore Database

This option restores the CONTROL-M database from a backup device. The function performed by this option is identical to the function performed by the ctmdbrst utility. For more information, see “ctmdbrst” on page 2-44.

Sybase Restore

To restore a Sybase database:

1. Select 3 from the Database Maintenance menu.

2. The following prompt is displayed:

Enter restore device name [tapedump2] :


Maintenance 4-17

Press <Enter> to accept the default or enter the name of your backup device. The backup device must be either a valid device defined in Sybase, or the full path name of a backup file to be used as input for the ctmdbrst utility. Use the option List Backup Devices to display a list of valid devices. For more information on this option, see“List Backup Devices” on page 4-19.

Oracle Restore

To restore an Oracle database:

1. Select 3 from the Database Maintenance menu.

2. The following prompt is displayed:

Enter a destination directory name [<ctm_home_dir>]:

Press <Enter> to accept the default directory, or type the name of the directory in which the backup was saved.

3. If Archive mode is not active at your site, a restore is automatically performed using the information from the most recent Cold backup.

If Archive mode is active, a restore is automatically performed using the information from the most recent Hot backup.

For details about Hot and Cold backups, see Step 3 on page 4-15.



The restore procedure shuts down both CONTROL-M/Server and the Oracle database server before performing the restore. After the restore is completed, the restore procedure starts up only the Oracle database server. CONTROL-M/Server must to be restarted manually after the procedure is finished.

NoteIf you wish to perform a restore from a Cold backup and Archive mode is active, deactivate Archive mode (using option 1 of the Database Maintenance menu) before performing the steps described above.

WarningIf you attempt to restore a dedicated Oracle database using the ctmdbrst utility without previously having backed up the database, the database will become unavailable. To access the database, enter the following procedure from the CONTROL-M home directory command line:

svrmgrlconnect internaldalter database mountaltere database openexit

To restore a Sybase database if it is corrupted:

1. Shut down CONTROL-M. Make sure there are no users or processes connected to the SQL Server.

2. Use the option Database Creation => Build Database to rebuild the database.

3. Use the Restore Database option to load the data into the new database.


Maintenance 4-19

List All Devices

Displays a list of all Sybase devices.

NoteThis menu option is relevant only for sites using a Sybase database server.

List Backup Devices

Displays a list of Sybase backup devices. Use this option to locate a device for backing up the CONTROL-M database (see above).


Add Backup Device

Adds a backup device to the list of devices available for backing up the CONTROL-M database.



Enter <dev_logical_name> {disk|tape} <device_name> <[size_in_MB]>

The variables in this prompt are described in Table 4-4.



This device can be either a disk file or a tape drive. (Backups to disk files are faster and do not require operator intervention.)

Enter the required parameters for the new device.

Example

cont tape cont_dev

In this instance the following messages are displayed:

Creating Tape device.‘Tape’ device added.(return status = 0)

Drop Backup Device


Deletes a device from the list of backup devices. The following prompt is displayed:

Enter <dev_logical_name>:

Enter the logical name of the device to delete from the list. Upon completion of the process, the following message is displayed:

Device dropped (return status = 0)

Table 4-4 Logical Device Description


<dev_logical_name> Logical name of the device.

{disk | tape} Disk or tape device.

<device_name> Path and name of the device.

<size_in_MB> Size of the device (optional).


Maintenance 4-21

Extending the Size of the CONTROL-M Database

Table 4-5 describes the menu options that can be used to extend the size of different segments of the CONTROL-M database. These options can be used while CONTROL-M/Server is active or when it is shut down. See “Checking Available Space in the CONTROL-M Database” on page 4-4 for additional information.

NoteThe options in Table 4-5 can be applied only when CONTROL-M/Server uses the dedicated Sybase Database Server supplied with CONTROL-M. If CONTROL-M/Server is configured to use an existing (remote) server, you can use the commands disk init and alter database to extend the CONTROL-M database. To extend the log segment, the command sp_logdevice is also used. These commands are described in the Sybase Commands Reference Manual. Similarly, you can use these commands to extend the CONTROL-M mirror database.

Extend Database Size

This option extends the size of the data segment only. The size of the log segment is not extended.

To extend the size of the data segment of the CONTROL-M database:

Table 4-5 Menu Options for Modifying Database Size

Option Description

Extend Database Size Extends the data segment of the database.

Extend Temporary Database Size

Extends the temporary storage area of the database (tempdb).

Extend Database Log Size Extends the log segment of the database (Sybase).

Extend Rollback Tablespace Size

Extends the log segment of the database (Oracle).



1. Select option Extend Database Size from the Database Maintenance menu. The following prompt is displayed:

Enter size of database extension in MB (default 10):

2. Specify the amount to extend the database, or press <Enter> to accept the default. The following prompt is displayed:

For Sybase:

Enter physical device name for database extension(default <Sybase data directory>/controlm_extend.dat):

For Oracle:

Enter size of database extension in MB (default 10):The entered value is: 10

1 - /disk2/controlm/oracle/oradata/ctrlm/rbs01.dbf

0 - New Data File

Your choice ? (0/1) [0]:

3. Supply a full path name or press <Enter> to accept the default (Sybase). [0] New Data File is the default in Oracle. The file specified must not exist. The local file system where the file will be located must have enough free space to accommodate the size specified above.

Upon completion of the process, the following message is displayed:

For Sybase:

Extension request succeeded

For Oracle:


Maintenance 4-23

SVRMGR> Connected.SVRMGR> Statement processed.SVRMGR> Server Manager complete.


The size of the temporary storage area of the database should be approximately 10% of the data segment size.

To extend the size of the temporary area of the CONTROL-M database:

1. Select the option Extend Temporary Database Size from the Database Maintenance menu.The following prompt is displayed:

Enter size of temporary db extension in MB (default 10):

2. Specify amount to extend the database, or press <Enter> to accept the default. The following prompt is displayed:

For Sybase:

Enter physical device name for temporary db extension (default <Sybase data directory>/controlm_temp.dat):

For Oracle:


1 - /disk2/controlm/oracle/oradata/ctrlm/temp01.dbf

0 - New Data File


3. Supply a full path name or press <Enter> to accept the default. [0] New Data File is the default in Oracle.



The file specified must not exist. The local file system where the file will be located must have enough free space to accommodate the size specified above. Upon completion of the process, the following message is displayed:

For Sybase:


For Oracle:


Extend Database Log Size (Sybase) orExtend Rollback Tablespace Size (Oracle)

The size of the log segment of the database should be approximately 1/3 of the data segment size.

To extend the size of the log segment of the CONTROL-M database:

1. Select option Extend Database Log Size from the Database Maintenance menu (Sybase). In Oracle, select the Extend Rollback Tablespace Size option from the Database Maintenance menu. The following prompt is displayed:

Enter size of transaction log extension in MB (default 10):

2. Specify amount to extend the database, or press <Enter> to accept the default. The following prompt is displayed:

For Sybase:

Enter physical device name for transaction log extension (default <Sybase data directory>/controlm_extend.log):

For Oracle:


Maintenance 4-25


1 - /disk2/controlm/oracle/oradata/ctrlm/rbs01.dbf

0 - New Data File


3. Supply a full path name or press <Enter> to accept the default. The file specified must not exist. The local file system where the file will be located must have enough free space to accommodate the size specified above.

Upon completion of the process, the following message is displayed:

For Sybase:


For Oracle:


Show Database Parameters

Displays the CONTROL-M database parameters. To choose this option, select 11 from the Database Maintenance menu. Information similar to the following is displayed:

SQL Server/<SQL version number>/...

SYBASE=/home/ctm/sybaseCONTROLM_USER=ctrlmCONTROLM_DATABASE=ctrlmDSQUERY=CTRLMDSLISTEN=CTRLM



Check Database

Displays the size of the CONTROL-M database and availability of space, and verifies database integrity. Information similar to the following is displayed:

db total = 29000.0 KB (data= 23500.00 log= 5500.00)data used = 1928 KB (8%).log used = 0 KB (0%).Checking database

This function is also available by running the script:<controlm_home>/ctm/SCRIPTS/ctmdbcheck.

The ctmdbcheck utility can also be used to provide automatic database and transaction log monitoring. The following options are available:

ctmdbcheck [db threshold %] [log threshold %]ctmdbcheck [general threshold %]

where db threshold % and log threshold % are user defined percentages which, when exceeded, generate shout messages to ENTERPRISE/CS warning that the CONTROL-M database or log should be extended.


Maintenance 4-27

Database Mirroring Menu

The Database Mirroring menu is used to perform functions related to initializing/disabling database mirroring, recovering from CONTROL-M database failure, initializing failover, and recovering from Server platform failure. Selecting CONTROL-M Main Menu => Database Mirroring displays the following:

Figure 4-5 Database Mirroring Menu

Database Mirroring Menu-----------------------Select one of the following options:

Primary Server Options1 - Check Mirroring Status2 - Initialize Mirroring3 - Disable Mirroring4 - Use Mirror Database5 - Restore CONTROL-M Database From Mirror

Failover Server Options6 - Initialize Failover7 - Start Failover8 - Stop Failover

q - Quit

Table 4-6 Options of the Database Mirroring Menu

Option Description

Check Mirroring Status

Indicates whether or not mirroring of the CONTROL-M database is currently enabled.

Initialize Mirroring

Builds the CONTROL-M mirror database from the existing CONTROL-M database and configures CONTROL-M to maintain the mirror database. This procedure is described in Chapter 7, “Mirroring and Failover.” CONTROL-M/Server must be shut down before selecting this option.



Disable Mirroring

Discontinues mirroring of the CONTROL-M database (if mirroring was previously initialized). To restore mirroring after selecting this option, use option Initialize Mirroring. This option is used in the following circumstances:Mirroring is enabled but CONTROL-M cannot be started because it cannot attach to the mirroring SQL server.-or-Mirroring is no longer desired.

Use Mirror Database

Configures CONTROL-M to use the mirror database as its primary database. This option can be used in the event that there was a failure of the primary CONTROL-M database and mirroring was active. CONTROL-M/Server must be shut down before you select this option.To resume using the primary database, use the option Restore CONTROL-M Database from Mirror.For more information, see Chapter 7, “Mirroring and Failover.”.

Restore CONTROL-M Database from Mirror

Rebuilds the CONTROL-M database using the mirror database. This option is used when there was a failure of the primary CONTROL-M database and mirroring was active. CONTROL-M must be shut down before selecting this option.For more information, see Chapter 7, “Mirroring and Failover.”.

Initialize Failover

Saves site specific information about the backup Server platform. This data is needed to start CONTROL-M on the backup Server platform in case of failure of the primary Server.

Start Failover Copies the saved site-specific information about the backup Server platform to the Mirror database. This data is needed to start CONTROL-M on the backup Server using the Mirror database.

Stop Failover Restores the site-specific information about the primary Server platform to the Mirror database. This data is used to restore the primary database.

Quit Quits the Mirror Database menu and returns to the CONTROL-M Main menu.

Table 4-6 Options of the Database Mirroring Menu

Option Description


Maintenance 4-29

Security Authorization Menu

The Security Authorization menu is used to invoke the ctmsec Security Maintenance utility and export or import Security Definition tables. Selecting CONTROL-M Main Menu => Security Authorization displays the following:

Figure 4-6 Security Authorization Menu

Security Authorization Menu---------------------------------Select one of the following options:1 - Security Maintenance Utility2 - Backup Security Definition Tables3 - Restore Security Definition Tablesq - Quit

Table 4-7 Security Authorization Menu (Part 1 of 2)

Option Description

Security Maintenance Utility

Invokes the Security Maintenance utility (ctmsec). This utility is used to define users in the CONTROL-M Security database and assign authorizations for working with CONTROL-M. For more information, see “Security Maintenance Utility (Interactive Mode)” on page 3-11“.

Backup Security Definition Tables

Exports Security Definition tables. Specify the full path name of the file. This function can be run only on the CONTROL-M/Server platform. A message confirming the completion of the export to file process is displayed. Press <Enter> to return to the Security Authorization menu.



NoteThe Backup Security Definition Tables and Restore Security Definition Tables options in this menu can be used only to transfer or backup existing security definitions.

To modify security definitions before copying them to another installation, or before restoring them to the current installation, it is recommended that you use the ctmsec utility –EXPORT option. For more information, see “Exporting Security Definition Tables” on page 3-35.

Parameter Customization Menu

The Parameter Customization menu is used to view and maintain the various groups of parameters used by CONTROL-M. Selecting CONTROL-M Main Menu => Parameter Customization displays the following:

Restore Security Definition Tables

Restores Security Definition tables from a file created using the Backup Security Definition Tables option of this menu. The restored definitions override all existing Security Definition tables.

Specify the full path name of the file. This function can be run only on the CONTROL-M/Server platform. A message confirming the completion of the import is displayed.

Press <Enter> to return to the Security Authorization menu.

Note: Security Definition tables that were generated by the export utility under CONTROL-M/Server version 2.2.5 can be imported only using the ctm_restore_aut utility. For more information, see “Importing Security Definitions from CONTROL-M version 2.2.5” on page 3-37

Quit Quits the Security Authorization menu and returns to the CONTROL-M Main menu.

Table 4-7 Security Authorization Menu (Part 2 of 2)

Option Description


Maintenance 4-31

Figure 4-7 Parameter Customization Menu

Parameter Customization Menu-----------------------------


1 - Communication and Operational Parameters2 - System Parameters and Shout Destination Tables3 - Default Parameters for Communicating with Agent Platforms4 - Parameters for Communicating with Specific Agent Platforms

q - Quit

All the parameters that appear in these menus are described in:

NoteFor parameter changes to take effect, you must shut down and restart CONTROL-M/Server.

Table 4-8 Customization Parameters

Option Description

Communication and Operational Parameters

Displays/updates CONTROL-M operational and communication parameters. This option is described below.

System Parameters and Shout Destination Tables

Calls the ctmsys utility to view or update system parameters and Shout Destination tables. This utility is described in Chapter 2, “Utilities.”

Default Parameters for Communicating With Agent Platforms

Displays/updates the default values of parameters used for communication with Agent platforms. When communicating with an Agent platform, these values are used unless overridden using the following option. This option is described below.

Parameters for Communicating With Specific Agent Platforms

Displays/updates parameters for communicating with a specific Agent platform. This option is used to assign values other than the default parameter values for a specific Agent platform. This option is described below.

Quit Quits the Parameter Customization menu and returns to the CONTROL-M Main menu.



Communication and Operational Parameters

When this option is selected, the Communication Parameters menu is displayed. The current value for each parameter follows the parameter name:

Figure 4-8 Communication Parameters Menu

Communication Parameters:

1) Local IP Host Interface Name:2) Agent-to-Server Port Number:

Communication Protocol: TCP

a) Modify all of the aboveq) Quitn) Next page

Enter command or item number you wish to change [n]:

When you enter n, the operational parameters menu is displayed.

Figure 4-9 Operational Parameters Menu

Operational Parameters:

1) Input Process Communication Port Number: 2) Maximum Job State Changes: 3) ENTERPRISE/CS TCP/IP Port Number: 4) Statistics Mode: 5) ENTERPRISE/CS RELVER param:6) Maximum server processes (CS): 7) Minimum server processes (CS):

a) Modify all of the above.p) Previousq) Quit


Maintenance 4-33

• To modify parameters, specify the number appearing next to the parameter that you want to change, or specify a to change all the parameters in the menu. You are prompted for the parameter value(s) as required.

See Chapter 5, “Customization Parameters,” for a description of each parameter.

• To switch between the two menus, specify n (next) or p (previous) as required.

• To exit, specify q from either menu.

• If you modify either of the parameters Agent-to-Server Port Number or ENTERPRISE/CS TCP/IP Port Number, the following prompt is displayed:

You have modified one or more network port numbers.It is recommended that you record the port numbers used by CONTROL-M in the /etc/services file on your machine. This requires access to the root password.Do you wish these port numbers to be recorded in the /etc/services file now (y/n) [y]:

If you respond y to the prompt above, the following prompt is displayed:

Password:

Specify the root password. The/etc/services file is updated.

The /etc/services file contains a description of the usage of each port on the Server platform. Proper maintenance of this file prevents conflicting usage of ports by various applications. The CONTROL-M Maintenance facility can automatically modify the/etc/services file for changes you made to one or both of the port number parameters mentioned above.

• If you modify the Communication Protocol parameter, the following message is displayed:



For this change will take effect in CONTROL-M, you will need to re-start CONTROL-M. Use ’shut-ctm’ and ’start-ctm’ to re-start CONTROL-M.

If the Communication Protocol parameter defined on an Agent platform is different from the modified one, after shutting down and starting CONTROL-M/Server again, you must also redefine this parameter on the Agent platform according to its requirements. Refer to the appropriate chapter for the platform in theCONTROL-M/Agent Administrator Guide.

NoteRedefining the Communication Protocol parameter on a Unix Agent platform requires that you re-customize the CONTROL-M/Agent installation.

• If you modify the Statistics Mode parameter, existing entries in the statistics database are updated and new entries are added. This may cause duplicate lines in the output of the ctmjsa utility. After switching modes, you can eliminate these duplicate output lines by running:

sql truncate table CMR_STATIS go

Afterwards, run the ctmjsa utility again for statistics compilation.

Default Parameters for Communicating With Agent Platforms

When this option is selected, the following menu is displayed. The current value for each parameter follows the parameter name:


Maintenance 4-35

Figure 4-10 Communication Parameters for Agent Platforms

Default Parameters for Communicating With Agent Platforms:

1) Polling Interval:2) Communication Timeout:3) Maximum Retries:4) Retry Interval:5) Server-to-Agent Port Number:6) Communication Protocol Version:

a) Modify all of the aboveq) Quit

(All time parameters expressed in seconds)Enter command or item number you wish to change [q]:

• To modify parameters, specify the number appearing next to the parameter that you want to change, or specify a to change all the parameters in the menu. You are prompted for the parameter value(s) as required.


Parameters for Communicating With a Specific Agent Platform

When this option is selected, the following prompt is displayed:

To view/modify communication parameters,enter node ID of Agent Platform:

1. Specify the node ID of the desired Agent platform.

NoteUse of this option does not require communication with the Agent platforms. There is no verification that the specified Agent platform exists at the time this option is used.



The following menu is displayed. The current value for each parameter follows the parameter name:

Figure 4-11 Communication Parameters for Specific Agent Platforms

Parameters for Communicating With Specific Agent Platform (<node ID>)

1) Communication Timeout:2) Maximum Retries:3) Retry Interval:4) Server-to-Agent Port Number:5) Communication Protocol Version:6) Check Interval(Available)

a) Modify all of the aboveq) Quit

(All time parameters expressed in seconds)

Enter command or item number you wish to change [q]:

2. To modify parameters, specify the number appearing next to the parameter that you want to change, or specify a to change all the parameters in the menu.

You are prompted for the parameter value(s) as required.


3. To exit, specify q.

Node Group Menu

The Node Group menu is used to maintain and view node groups. Node groups are used by the CONTROL-M load-balancing function. Selecting CONTROL-M Main Menu => Node Group displays the following menu:


Maintenance 4-37

Figure 4-12 Node Group Menu

Node Group Menu ---------------


1 - List All Node Groups2 - Edit Node Group3 - Delete Node Group

q - Quit

The options in this menu are described in Table 4-9.

Edit Node Group

This option is used to view, create or modify a node group. When this option is selected, the following prompt is displayed:

Node Group Name:

Specify the name for a new node group or specify the name of an existing node group whose member list you want to view or modify. The following menu is displayed:

Table 4-9 Options of the Node Group Menu

Option Description

List All Node Groups Displays a list of all existing node groups.

Edit Node Group Views, creates or modifies a node group. For details, see the next section.

Delete Node Group Requests the name of an existing node group, and then deletes the group.

Quit Quits the Node Group menu and returns to the CONTROL-M Main menu.



Edit Node Group Menu-------------------


1 - View Current Node Group 2 - Add Node ID 3 - Delete Node ID

q - Quit

Enter Option (Group: <node_group>) :

Specify the number for the desired option:

Agent Status Menu

The Agent Status menu is used to view and update the communication status of Agent platforms. Selecting CONTROL-M Main Menu =>

Agent Status displays the following:

Figure 4-13 Agent Status Menu

Agent Status Menu-----------------


1 - List Last Known Status of Agents Platform 2 - Change Agent Platform Status to Available 3 - Change Agent Platform Status to Disabled 4 - Delete Agent Platform Status Entry 5 - Ping Agent Platform 6 - Discover Agent

View Current Node Group

Displays the node IDs included in the specified node group.

Add Node ID Prompts you for the name of a node ID to add to the specified group.

Delete Node ID Prompts you for the name of a node ID to delete from the specified group.


Maintenance 4-39

q - Quit

Enter option number --->

For more information about statuses for Agent platforms, see “Communication Status of Agent Platforms” on page 1-6.

The first four options in the above table do not require communication with the Agent platforms. They do not verify that the Agent platforms exist. As a result, the following may occur:

• The Change options can be used to modify the status of a non-existent platform.

Table 4-10 Options of the Agent Status Menu

Option Description

List Last Known Status of Agents Platform

Prompts for the node ID of an Agent platform, and then displays the last known status of the platform (Available, Unavailable or Disabled).

Change Agent Platform Status to Available

Prompts for the node ID of an Agent platform, and then changes the communication status of the platform to Available.

Change Agent Platform Status to Disabled

Prompts for the node ID of an Agent platform, and then changes the communication status of the platform to Disabled.

Delete Agent Platform Status Entry

Displays a list of all Agent platforms whose communication status is Disabled, and prompts for the node ID of the platform you want to delete.

Ping Agent Platform Prompts for the node ID of an Agent platform and then tests the communication link with the platform. The response indicates whether the Agent platform is available or unavailable.This option cannot be used to test communication with an Agent platform whose status is Disabled.

Discover Agent Prompts for the node ID of an Agent platform, and then pings the agent and gathers information about the Agent platform.

Quit Quits the Agent Status menu and returns to the CONTROL-M Main menu.



• If you request the status of a non-existent platform, the default status of Available is displayed. If the status of the platform has been changed to Disabled, the platform will appear in the list of platforms that are Not Available.

Troubleshooting Menu

The Troubleshooting menu is used to perform a variety of diagnostic activities. Selecting CONTROL-M Main Menu => Troubleshooting displays the following:

Figure 4-14 Troubleshooting Menu

Troubleshooting Menu -----------------------------


1 - Set Diagnostics Level 12 - Erase Proclog File 2 - Set Sleep Time 13 - Show Calendar names 3 - Show Processes Flags (prf) 14 - Interactive SQL Commands 4 - Show All Processes (shctm) 15 - Communication Diagnostic Report 5 - Show Communication Environment 16 - Force Download

6 - Restart New Day Procedure 17 - Check directory permissions 7 - Reset CONTROL-M Active Environment 8 - Truncate Database Log 9 - Troubleshooting Report10 - Check Kernel Configuration11 - List Active Transactions

q - Quit

Enter option number ---> []:

Table 4-11 Options of the Troubleshooting Menu (Part 1 of 3)

Option Description

Set Diagnostics Level

Determines the diagnostic level for all CONTROL-M/Server processes or for any specific process. For details, see “Set Diagnostics Level” on page 4-43.

Set Sleep Time Determines the sleep time for all CONTROL-M/Server processes or for any specific process. For details, see “Set Sleep Time” on page 4-45.

Show ProcessFlags (prf)

Displays the status of CONTROL-M/Server processes. For details, see “Show Process Flags (prf)” on page 4-46


Maintenance 4-41

Show All Processes (shctm)

Displays all CONTROL-M/Server processes currently running. For details, see “Show All Processes (shctm)” on page 4-47.

Show Communication Environment

Displays the port numbers used by CONTROL-M/Server to communicate with ENTERPRISE/CS. Information similar to the following is displayed:ENTERPRISE/CS <-> CONTROL-M communication-port:----------------------------------------------INPUT_SPN=2371OUTPUT_SPN=2370

[ SPN - Socket Port Number ]

Restart New Day Procedure

Starts the New Day procedure again (after confirmation).

Reset CONTROL-MActive Environment

Clears all components of the CONTROL-M active environment (Active Jobs file, prerequisite conditions, and so on) and forces CONTROL-M to start a download of the entire Active Jobs file to ENTERPRISE/CS. This option is described in “Reset CONTROL-M Active Environment” on page 4-48.

Truncate Database Log

Truncates the CONTROL-M database log. This option should be used if the Sybase message “Can’t allocate space for <text> in database <name> because the log segment is full” occurs in one of the log files located in directory ~controlm/ctm/proclog/.

Troubleshooting Report

Creates a report containing specified CONTROL-M system information. This option is typically used at the request of Technical Support to determine the cause of a CONTROL-M problem. This option is described in “Troubleshooting Report” on page 4-45.

Check Kernel Configuration

For Solaris platforms, checks whether the current configuration settings of the kernel comply with requirements for CONTROL-M/Server.If all parameters are configured correctly, the following message is displayed:Check kernel configuration for <system>terminated successfully If one or more parameters are not configured correctly, the parameters are listed followed by:Check kernel configuration for <system>terminated unsuccessfullyNote: This option is not relevant for AIX platforms.

List Active Transactions

Runs the ctmdbtrans utility to list the active transactions in the database.A transaction is a unit of work performed by CONTROL-M in the database. Each transaction is assigned a unique name identifying that specific unit of work.You may be asked by technical support to run this option and to provide them with the output for debugging purposes.


Option Description



Erase Proclog Files

Erases the contents of the current process log file for all active CONTROL-M/Server processes or for any specific active process. The following prompt is displayed:Enter <process-name> [SU,TR,SL,CO,NS,LG,ALL]Specify the two-character code for a specific process or ALL for all current process log files. See “Set Diagnostics Level“ earlier in this table for more information about process log files.

Show Calendar Names

Displays a list of all Calendar names defined in the CONTROL-M database.

Interactive SQL Commands

Starts an interactive SQL session that enables you to issue Sybase Database commands to perform actions in the CONTROL-M database. To end this session, enter the command: quit.This option should only be used when requested by Technical Support.

Communication Diagnostic Report

Checks parameters and environmental conditions relevant to communication between the Server platform and a specific Agent platform. This option is typically used at the request of Technical Support to determine the cause of a communication problem. When this option is selected, you are prompted to supply the node ID of an Agent platform. A diagnostic program is then executed and a report listing the findings is generated.

Force Download Forces CONTROL-M to start download of the entire Active Jobs file to ENTERPRISE/CS.

Check directory permissions

Checks the current directory and all sub-directories under it for permissions and displays a report similar to the following:

’/home/ctm600’ directory permissions OK.’/home/ctm600/ctm’ directory permissions OK.’/home/ctm600/ctm/scripts’ directory permissions OK.’/home/ctm600/ctm/exe_Solaris’ directory permissions OK.’/home/ctm600/ctm/sql’ directory permissions OK.’/home/ctm600/ctm/sysout’ directory permissions OK.’/home/ctm600/ctm/proclog’ directory permissions OK.

Quit Quits the Troubleshooting menu and returns to the CONTROL-M Main menu.


Option Description


Maintenance 4-43

CONTROL-M/Server Processes

When implemented under a Unix operating system, CONTROL-M/Server consists of several integrated processes. Most of the processes run whenever CONTROL-M/Server is active. Each process is identified by a two-letter code:

Several options in the Troubleshooting menu act on one or more processes. See Table 4-11, “Options of the Troubleshooting Menu,” on page 4-40 for details.

Set Diagnostics Level

Determines the diagnostic level for all CONTROL-M/Server processes or for any specific process. If modified while CONTROL-M/Server is running, the diagnostic level specified is effective immediately.

The following prompts are displayed:

Enter <diagnostics-level> [0 - 5] : [0]:Enter Module <module_number> [0,1,2,3] : [0]:Enter PROCESS NAME [CD,CS,CO,LG,NS,SL,SU,TR,RT,WD,ALL] : []:

Table 4-12 Two-Letter Codes for CONTROL-M Processes

Code Description

SU Supervisor.

TR Tracker.

SL Selector and submitter.

NS Communication with Agent platforms.

CO Communication gateway.

CD New Day procedure, downloads, updates to the CONTROL-M database.

CS Communication (user requests from ENTERPRISE/CS).

LG Utilities invoked from Agent platforms.

WD Watchdog process.

RT Inter-process Communication Router



Table 4-13 describes the parameters that are set when responding to these prompts.

Table 4-13 Diagnostic Level Parameters


<diagnostic-level> The diagnostic level ranges from 0 (no diagnostics) to 5 (highest level of diagnostics). Output from each process is written to a separate process log file named:<controlm_path>/ctm/proclog/<process-name>_LOG.<process-ID>

For example:~controlm/ctm/proclog/SU_LOG.5609

The variables in this pathname are:


<process_name> Two-character code identifying the process.

<process-ID> ID of the CONTROL-M/Server process.

<module_number> Indicates which components are to be traced for diagnostic purposes.

Valid values are:0 – All components. Default1 – Common functionality flow.2 – Event manager.3 – Database layer.

Process Name Indicates a two-character code for a specific process, or ALL for all CONTROL-M/Server processes.

See “CONTROL-M/Server Processes” on page 4-43, for a description of the process codes appearing in this prompt.


Maintenance 4-45

Set Sleep Time

Determines the sleep time for all CONTROL-M/Server processes or for any specific process. The sleep time is the length of time that the process lies dormant before “waking up” to check if any request to perform an action was received. If modified while CONTROL-M/Server is running, the sleep time specified becomes effective immediately. See “Sleep Time Considerations” on page 4-49.


Enter <process-name> [SU,TR,SL,RT,CO,NS,LG,ALL] and <seconds-sleep-time>:

See “CONTROL-M/Server Processes” below for a description of the process codes appearing in the prompt. Specify the two-character code for a specific process, or ALL for all CONTROL-M/Server processes, followed by the desired sleep time (in seconds).

Example

SL 130

Troubleshooting Report

Creates a report containing specified CONTROL-M system information. This option is typically used at the request of Technical Support to determine the cause of a CONTROL-M problem.


Figure 4-15 Troubleshooting Report Information

Troubleshooting Report Information

---------------------------------- 1) Control-M Active Processes Map: Y2) Control-M Environment Variables: Y3) Active Jobs File Statistics: Y4) System Communication Data: Y5) Conditions and Resources Maps: Y6) SU (Supervisor) Logs: Y7) SL (Selector) Logs: Y



8) TR (Tracker) Logs: Y9) CD (New Day Procedure) Logs: Y10) CO (Communication Gateway) Logs: Y11) CS (Communication with ENTERPRISE/CS) Logs: Y12) LG (Agent Utilities) Logs: Y13) NS (Communication with Agents) Logs: Y14) Database Error Log: Y15) Logs of Failed Jobs within the Last 24 Hours: Y16) Logs of All Jobs run within the Last 24 Hours: N R) Generate Troubleshooting ReportQ) Quit

Select item to include/exclude:

To change the information included in the report, enter the number of the item to change and switch the flag from Y to N. Default options include all information. Enter “R” to generate the report.

The generated report is compressed and placed in the CONTROL-M user’s home directory.

<controlm_path >/ctmtsrpt.<mmddyyhhmm>.tar.Z

where:

Show Process Flags (prf)

When selected, the Show Process Flags option displays the status of CONTROL-M/Server processes as recorded in the CONTROL-M database.

A table similar to the following is displayed:

PROCNAME PROCID PROCSTAT PSTAT_REQ SLEEP_TIME DIAG_LVLCD 21176 R R 60 0CO 21199 R R 60 0LG 21178 R R 360 0NS 21180 R R 120 0RT 21166 R R 60 0SL 21182 R R 60 0SU 21167 R R 60 0TR 21184 R R 30 0WD 21185 R R 30 0


<mmddyyhhmm> Date and time of report.


Maintenance 4-47

The columns in this table are described in Table 4-14.

Show All Processes (shctm)

When selected, the Show All Processes option displays all CONTROL-M/Server processes currently running on the Server platform. A list similar to the following is displayed:

controlm 5703 0:02 /usr1/controlm/ctm/exe_AIX/p_ctmcocontrolm 5620 0:00 /usr1/controlm/ctm/exe_AIX/p_ctmnscontrolm 5645 0:00 /usr1/controlm/ctm/exe_AIX/p_ctmlgcontrolm 5691 0:00 /usr1/controlm/ctm/exe_AIX/p_ctmtrcontrolm 5705 0:00 /usr1/controlm/ctm/exe_AIX/p_ctmslcontrolm 5609 0:01 /usr1/controlm/ctm/exe_AIX/p_ctmsucontrolm 5712 0:01 /usr1/controlm/ctm/exe_AIX/p_ctmcdcontrolm 5714 0:01 /usr1/controlm/ctm/exe_AIX/p_ctmwdcontrolm 5713 0:01 /usr1/controlm/ctm/exe_AIX/p_ctmcscontrolm 5610 0:01 /usr1/controlm/ctm/exe_AIX/p_ctmrt

NoteThe operating system identifier (in the above example, AIX) in the path of the run module varies according to the type of Unix running on the Server platform.

Table 4-14 Columns of the Show Process Flags Table

PROCNAME Two-letter code identifying the CONTROL-M/Server process (described above).

PROCID Process ID of the CONTROL-M/Server process. If this entry is missing, the process is not currently running.

PROCSTAT and PSTAT_REQ

Current statuses of the process. The codes that can appear in these columns have the following meaning:• PROCSTAT—PSTAT_REQ• R– RUNNING—R–Run requested• T,Z – Terminated—T,Z–Terminate requested• S–Suspended—Suspend requested• SLEEP_TIME—Current sleep time of the process• DIAG_LVL—Current diagnostic level of the process

DIAG_LVL Current diagnostic level.



The columns displayed in this list are:

• User name under which the process is running (for example, controlm)

• Process ID (for example, 5703)• Run time (for example, 0:02)• Full path of the process’ run module (for example,

/usr1/...ctmco). The last two characters of the path identify the process (for example, the first line in the list above represents the CO process – the Communication module).

The following additional columns are displayed for the CS process (the last line in the list above):

• Two columns of mailbox numbers (for example, 603 604)• Diagnostic level (for example, 0)

Reset CONTROL-M Active Environment

NoteShut down CONTROL-M/Server before selecting this option.

When selected from the Troubleshooting menu, the Reset CONTROL-M Active Environment option performs the following actions (after confirmation by the user):

• The contents of the Active Jobs file are erased.

• All prerequisite conditions, Quantitative resources and Control resources are deleted.

• The entire Active Jobs file is downloaded to ENTERPRISE/CS.

It is also possible to reset the CONTROL-M/Server process sleep times and diagnostic level using the init_prflag utility. This utility performs the following actions:

• The sleep times for all CONTROL-M/Server processes are reset to their initial (installation) values, as follows:


Maintenance 4-49

• The diagnostic level for all CONTROL-M/Server processes is reset to zero.

Sleep Time Considerations

The sleep time setting for CONTROL-M processes can affect the functionality of CONTROL-M and the performance of your data center. Sleep time is the length of time that a process lies dormant before “waking up” to check if any request to perform an action was received. When modifying certain CONTROL-M process sleep time settings, it is important to consider the number of jobs that are processing, the job schedule plan, and the overall load on the machine.

Table 4-15 CONTROL-M/Server Shut Down

Process Sleep Time

SU 60

TR 30

SL 30

NS 120

CO 60

CD 60

LG 360

WD 360

RT 60



Table 4-16 Sleep Time Considerations

Process Task

Sleep Time Initial Settings

Sleep TIme Modification Considerations

SU Supervisor 60 Increase: Delay in startup, downloads, and New Day procedure.

TR Job Tracking 15 Increase: Delay in freeing resources after job ends and delay in Shout messages. Can be increased during period of minimal job processing. Decrease: Additional CPU resources.

SL Job Selector 30/60 Increase: Delay in Job Submission and Shout messages for late submission Can be increased during period of minimal job processing. Decrease: Additional CPU resources.

NS Communication 120 No effect.

CO Communication 60 No effect.

CD New Day Procedure; Database uploads and downloads

60 No effect.

LG Utilities 360 No effect.

WD Watchdog 30 No effect.

RT Inter-process Communication Router

60 No effect.


Customization Parameters 5-1

5

Customization Parameters 5

You can customize the CONTROL-M/Server installation by modifying parameters used by the various CONTROL-M/Server modules. You can assign values to most of the parameters described in this chapter during the CONTROL-M/Server installation procedure. Certain parameters are assigned default values during installation and can be modified later.

CONTROL-M/Server parameters are divided into the following categories:

• System parameters.• Communication parameters.• Operational parameters.• Agent Communication parameters.• Database parameters.• Mirroring parameters.• Performance parameters.• Configuration parameters.

CONTROL-M/Agent customization parameters are described in Chapter 1, General Information, of the CONTROL-M/Agent Administrator Guide.



Parameter Coordination

For CONTROL-M/Server to communicate with Agent platforms and with the ENTERPRISE/CS workstation, the values assigned to certain parameters described in this chapter must be coordinated with values assigned to parameters on these systems. These parameters are listed in the following tables.

Table 5-1 Parameter Coordination With ENTERPRISE/CS

CONTROL-M/Server Parameter

ENTERPRISE/CS Parameter Default Value

ENTERPRISE/CS TCP/IP Port Number

TCP/IP Port Number 2370

Local IP Host Interface Name TCP/IP Host Name Local hostname as returned by Unix command hostname.

Table 5-2 Parameter Coordination With Agent Platforms

CONTROL-M/Server Parameter

CONTROL-M/Agent Parameter Default Value

Communication Protocol Communication Protocol TCP

Agent-to-Server Port Number Agent-to-Server Port Number 7005

Server-to-Agent Port Number Server-to-Agent Port Number 7006

Local IP Host Interface Name Authorized CONTROL-M/Servers

No default value. Specify the Interface Name of the machine where CONTROL-M/Server is installed.



Parameter Descriptions

System Parameters

CONTROL-M system parameters are assigned default values during installation. These parameters can be modified using the ctmsys utility, described in Chapter 2, “Utilities”. CONTROL-M system parameters are listed below. Modifiable parameters are identified by an asterisk (*). All other parameters are “display only”.

Table 5-3 System Parameters (Part 1 of 4)


DBO Password

Sybase password for the CONTROL-M database owner (6 to 30 characters, alphanumeric). The characters you enter are not echoed. This password is used by CONTROL-M processes and utilities to access the CONTROL-M database. Default: password.

Computer System

Platform type and model where CONTROL-M/Server is installed (for example, HP700).

Operating System

Operating system running on the Server platform (for example, AIX).

CONTROL-M Version

Version number of the CONTROL-M/Server.

Database Version

Internal database scheme version number (not the Sybase version number).

Sysout Log Directory *

Location where CONTROL-M puts job log (Sysout) files after a job’s execution (for example, /usr/controlm/ctm/sysout). This directory is created during the installation procedure.To change this location, create the new directory first (using the Unix mkdir command). This parameter cannot be modified while CONTROL-M is active.

Executable Path

Location where CONTROL-M/Server expects to find all its executable programs (for example, /usr/controlm/ctm/exe_Solaris).



Day Time * Installation start-of-day time used by CONTROL-M. This is the time at which the CONTROL-M date (Odate) changes and the New Day procedure is run. Default: +0700. The Day Time parameter is specified using one of the following formats:+hhmm CONTROL-M date is changed at the specified time after midnight.-hhmm CONTROL-M date is changed at the specified time before midnight.Time is expressed in 24-hour format (for example, 2200 is equivalent to 10 p.m.). This parameter is commonly set using the +hhmm format.

Example

+0600 Specifies that the hours between midnight and 6:00 a.m. are considered part of the previous date’s work day (that is, system date February 10th, 5:59 a.m. is still the CONTROL-M work day February 9th).-2200 Specifies that the hours between 10 p.m. and midnight are considered part of the next date’s work day (that is, at 10:00 p.m. on system date February 10th, the CONTROL-M date changes to February 11th).

CONTROL-M Date

Date that CONTROL-M/Server regards as the actual working date (Odate). This date is determined using the operating system date and the value of the parameter Day Time (described above). The format is yyyymmdd (for example, 20000215). The value is initially set to 00000000 by the installation procedure. The value is then updated by the New Day procedure each time it runs.

Statistics * Whether or not job statistics should be written to the CONTROL-M database. Valid values are Y (record job statistics) and N (do not record job statistics). See “Runtime Statistics” on page 1-28 for more information. Default: Y.

Maximum Retries *

Number of times the CONTROL-M auto-recovery mechanism can reactivate CONTROL-M/Server processes in case of failure. If this number is exceeded, CONTROL-M/Server is shut down. Default: 10.





Start Day of the Week *

Day of the week on which the work week at your site starts. Valid values: 0 (Saturday), 1 (Sunday), …, 6 (Friday). This parameter affects the usage of the job processing parameter Weekdays (described in Chapter 5 in the Enterprise Controlstation User Guide). Default: 2 (Monday).

Active Shout Table *

Currently-active Shout Destination table. Default: SYSTEM.

Full Security *

Whether CONTROL-M operates in a restricted or unrestricted level of security. Valid values: Y (restricted) and N (unrestricted). Default: N.

• For restricted security (value Y), a user not defined in the CONTROL-M security database does not have any application authorizations.

• For unrestricted security (value N), a user not defined in the CONTROL-M security database is regarded as having all application authorizations.

A user for whom one or more authorizations have been assigned in the security database can only perform the actions for which the user is specifically authorized.

Maximum DaysRetained by CONTROL-M Log *

Maximum number of days that entries are retained in the CONTROL-M log before being deleted by the New Day cleanup procedure. Default: 2.

Max.Days to RetainSysout Files *

Number of days that job sysout files are retained for jobs executed by Agent platforms. After this period, all job sysout files are deleted by the New Day procedure. Default: 2.





Ignore New Day Conditions Parameter

After assigning the new CONTROL-M date, the New Day procedure performs a selective cleanup of prerequisite conditions. By default, any prerequisite condition whose reference date (month and day) is equal to the new CONTROL-M date is deleted. This is done to prevent jobs from being triggered by any prerequisite conditions remaining from the previous year.

This cleanup function of the New Day procedure can conflict with user intentions under certain circumstances. For example, if a job processing definition contains the parameter Out Conditions with the Date field containing the value Next, a prerequisite condition is created with a reference date one or more days in the future. This prerequisite condition would normally be deleted by the New Day procedure before it can be used to trigger the submission of a job.

Ignore New Day Conditions *

Specifies whether the New Day procedure should ignore prerequisite conditions whose reference date (day and month) matches the CONTROL-M date.• When this parameter is N, the New Day procedure deletes

any prerequisite condition whose reference date matches the CONTROL-M date. Default.

• When this parameter is Y, the New Day procedure accesses a file containing prefixes of prerequisite conditions that should be ignored (that is, not deleted) by the daily cleanup procedure. (See “Ignore New Day Conditions Parameter” below.)

Secure Socket Layer

Indicates if the SSL protocol is used for communications:• Disabled: CONTROL-M/Server does not communicate

using SSL.• Enabled: CONTROL-M/Server uses only SSL for

communications.• Inactive: CONTROL-M/Server does not use SSL, but will

communicate initially with a CONTROL-M/Agent using SSL. The CONTROL-M/Server renegotiates the communications link with the CONTROL-M/Agent to non-SSL communications.

SSL support must be installed on CONTROL-M/Server for the Enabled and Inactive settings to take effect.





You have the option of selectively or completely disabling the cleanup of such prerequisite conditions by using the CONTROL-M system parameter Ignore New Day Conditions.

The Ignore New Day Conditions parameter specifies whether or not the New Day procedure should delete all prerequisite conditions whose reference date (day and month) matches the new CONTROL-M date.

• When this parameter is N, the New Day procedure deletes any prerequisite condition whose reference date matches the CONTROL-M date. This is the default.

• When this parameter is Y, the New Day procedure accesses a user-defined file that contains prefixes of prerequisite conditions that should be ignored (that is, not deleted) by the cleanup procedure.

The Ignore New Day Conditions parameter can be modified using the ctmsys utility.

When this parameter is set to Y, CONTROL-M searches for a file called:

<home_dir>/ctm/data/dbs_ignrcond.dat

where <home_dir> is the home directory of the CONTROL-M owner account. This file (referred to as the Ignore Conditions file) should contain a list of prefixes of prerequisite conditions, and/or including masks, that should not be deleted by the New Day procedure. (Note that prerequisite condition names are case-sensitive.)

The mask characters that can be used in this file are:

* Indicates any number of characters (including no characters). Specify ∗ by itself to signify all existing conditions (see the examples below).

? Indicates any single character.



You can create and maintain this file using any text editor available at your site. Place one prerequisite condition prefix on each line in the file.

NoteIf Ignore New Day Conditions parameter is set to Y but CONTROL-M cannot locate the Ignore Conditions file, CONTROL-M behaves as if the parameter is set to N (that is, all prerequisite conditions whose reference date matches the new CONTROL-M date will be deleted).

Example 1

If the new CONTROL-M date is 15-01-00 and Ignore New Day Conditions parameter is set to Y, the Ignore Conditions file contains the following prefixes:

prq_rs_*rptpre_prnsrt_def_?

The following table demonstrates which prerequisite conditions will be deleted from the Conditions/Resources table in the CONTROL-M database by the New Day procedure:

Conditions Existing Before Executing New Day Procedure

Conditions Remaining After Executing New Day Procedure

bra_fn_01 14/01bra_fn_01 15/01prq_rs_21rpts 14/01prq_rs_21rpts 15/01pre_prn_01 14/01pre_prn_01 15/01pre_prn_02 14/01pre_prn_02 15/01srt_def_a 14/01srt_def_a1 14/01srt_def_a 15/01srt_def_a1 15/01

bra_fn_01 14/01

prq_rs_21rpts 14/01prq_rs_21rpts 15/01pre_prn_01 14/01pre_prn_01 15/01pre_prn_02 14/01pre_prn_02 15/01srt_def_a 14/01srt_def_a1 14/01srt_def_a 15/01



Example 2

If Ignore New Day Conditions parameter is set to Y, The Ignore Conditions file contains the following entry:

*

No prerequisite conditions will be deleted from the Conditions/Resources table by the New Day procedure.

Communication Parameters

Communication parameters are modifiable during installation. You can also modify these parameters afterwards using the Parameter Customization menu, described in Chapter 4, “Maintenance.”

Valid Communication parameters are described in Table 5-4.

Table 5-4 Communication Parameters (Part 1 of 2)


Local IP Host Interface Name

Host interface name of the TCP/IP network interface card on the Server platform to use for communication with ENTERPRISE/CS. This is typically the host name of the Server platform. The default value for this parameter is the default host interface name defined in the Server platform operating environment. This parameter can also be specified by its IP address (for example, 192.123.186.20). This parameter should be modified only if the Server platform contains more than one network interface card (for example, Ethernet and Token-Ring). See additional information about this parameter below.



Local IP Host Interface Name Parameter

CONTROL-M/Server only listens on one network interface card for messages from ENTERPRISE/CS. If the Server platform contains more than one network interface card, it is necessary to ensure that ENTERPRISE/CS is sending messages to the same interface card listened to by CONTROL-M/Server. This is accomplished by ensuring that CONTROL-M/Server parameter Local IP Host Interface Name and ENTERPRISE/CS parameter TCP/IP Host Name both refer to the same IP address.

Agent-to-Server Port Number

CONTROL-M/Server communicates with CONTROL-M/Agent via two TCP/IP ports. One port is used for data flowing from CONTROL-M/Server to CONTROL-M/Agent. The other port is used for data flowing in the reverse direction. This parameter specifies the port used in the Server platform for receiving data from the Agent platform. The second port is specified using Server-to-Agent Port Number parameter (described in See “Parameters for Communicating With Agent Platforms” on page 5-13.) Default: 7005.The value for this parameter must match the value assigned to Agent-to-Server Port Number parameter on the Agent platform.Verify that the port number specified for this parameter is not used for any other purpose in the Server platform. The value for this parameter must be a number between 1024 and 65533 inclusive.

Communication Protocol

Protocol used to communicate with the Agent platforms. Specify UDP or TCP. It is recommended that you use TCP when there are many jobs running simultaneously reporting to CONTROL-M/Server. The protocol specified here must be the same as that specified on the Agent platform. Default: TCP.

Table 5-4 Communication Parameters (Part 2 of 2)




If one or both of these parameters contain a logical host name, you can determine the IP address mapped to the logical host name by specifying the following command at the Unix prompt:

arp <host_name>

The system responds with the IP address mapped to the host name on the local machine.

NoteEven if the same logical host name is specified for these two parameters, the host name can be mapped to different IP addresses on the Server platform and the ENTERPRISE/CS workstation. Use the arp command (see above) to verify that the host name on each machine is mapped to the same IP address.

You can also ensure that both machines are using the same address by specifying the actual IP address of the network interface card for each of these parameters. The IP address specified must be a local address on the Server platform.

Operational Parameters

Operational parameters are modifiable during installation. You can also modify these parameters afterwards using the Parameter Customization menu, described in Chapter 4, “Maintenance.”

The operational parameters are described below:



Table 5-5 Operational Parameters (Part 1 of 2)


Input Process Communication Port Number

Socket Port number used for communication between CONTROL-M processes. The parameter replaces the Input Mailbox Key and Output Mailbox Key parameters in earlier versions of CONTROL-M/Server.As of CONTROL-M/Server version 6.0.00, all inter- process communication is handled by the RT process.

Maximum Job State Changes

Number of job state changes retained by CONTROL-M/Server in the event communication with ENTERPRISE/CS is interrupted. If the number of job state changes that occur exceeds the value specified for this parameter, CONTROL-M/Server will initiate a download when communication with ENTERPRISE/CS is resumed. Default: 1000.

ENTERPRISE/CS TCP/IP Port Number

CONTROL-M communicates with Enterprise Controlstation using a pair of consecutive TCP/IP ports (for example, 2370 and 2371). The lower port is used for data flowing from CONTROL-M to ENTERPRISE/CS. The higher port is used for data flowing in the reverse direction. Default: 2370. This parameter is used to specify the lower of the two port numbers and must correspond to the value assigned to field TCP/IP Port Number in the definition of the CONTROL-M data center in the ENTERPRISE/CS Data Centers window. Verify that the two port numbers are not used for any other purpose on the Server platform. The value for this parameter must be a number between 1024 and 65533 inclusive.

ENTERPRISE/CS Release Version

ENTERPRISE/CS version number.

Statistics Mode Mode used by the ctmjsa utility to collect summary statistics. JOBNAME compiles statistics for each CONTROL-M Job Name and Node ID where the job was submitted. MEMNAME compiles them for each CONTROL-M Mem Name/Mem Lib and Node ID. Default: MEMNAME.



Parameters for Communicating With Agent Platforms

Parameters for communicating with Agent platforms are modifiable during installation. The values specified for these parameters are used as the default values for communication with each Agent platform. Parameter values for specific Agent platforms can be modified separately afterwards. You can also modify these parameters using the Parameter Customization Menu, described in Chapter 4, “Maintenance.”

The parameters for communicating with agent platforms are described in Table 5-6.

Minimum Server Processes

Minimum number of communication server processes that the CONTROL-M/Server gateway process will run concurrently. Default: 1.

Maximum Server Processes

Maximum number of communication server processes that the CONTROL-M/Server gateway process can run concurrently. Default: 1.

Table 5-5 Operational Parameters (Part 2 of 2)




Table 5-6 Parameters for Communicating with Agent Platforms


Polling Interval Time interval (in seconds) between requests from CONTROL-M/Server for status updates from Agent platforms that are executing jobs. Specify -1 to disable polling. Default: 900.

Communication Timeout

Maximum length of time (in seconds) that CONTROL-M/Server should spend attempting to communicate with an Agent platform before assigning it the status Unavailable. Default: 120. During this time, CONTROL-M/Server attempts to communicate with the Agent platform x times, where x is the value specified by parameter Maximum Retries.

Example

If the value of Communication Timeout is 120 and Maximum Retries is 12, CONTROL-M/Server attempts to communicate with the Agent platform once every 10 seconds (120/12) during the timeout period.

Maximum Retries

Number of communication retries to attempt in the period of time specified before assigning the status Unavailable to an Agent platform. Default: 12.

Retry Interval Length of time to wait (in seconds) between attempts to communicate with an Agent platform whose status is Unavailable. Default: 90.

Server-to-Agent Port Number

Port number in the Agent platform through which data is received from the Server platform. The value assigned to this parameter must correspond to the value assigned to the field Server-to-Agent Port Number in the Configuration file on the corresponding Agent platform. Default: 7006.

Communication Protocol Version

Version of CONTROL-M Agent.Specify 01 (2.2.4), 02 (2.2.5), or 03 (6.0.00). Default: 03.



Database Parameters

Sybase

Sybase Database configuration parameters are specified during installation before the CONTROL-M database is created. You can also modify these parameters and rebuild the CONTROL-M database using the Database Creation menu, described in Chapter 4, “Maintenance.”

The Sybase database parameters are described below:

Table 5-7 Sybase Database Parameters (Part 1 of 3)


CONTROL-M Database Owner

Sybase name for the CONTROL-M database owner. The custom script creates this user in the database. This name is used by CONTROL-M when accessing its database. Default: ctrlm

DBO Password Sybase password for the CONTROL-M database owner (6 to 30 characters, alphanumeric). The characters you enter are not echoed for security reasons. This password is used by CONTROL-M processes and utilities to access the CONTROL-M database. Default: password

Database Administrator’s Password

Password (6 to 30 characters, alphanumeric) for the Sybase database administrator (user sa). The characters you enter are not echoed for security reasons. This password is used by CONTROL-M utilities to access restricted sections of the CONTROL-M database. Default: password

Database (Data Portion) Size

Amount of space (in MB) to allocate for the data portion of the CONTROL-M database. Default: 20.If the database will be located in a file system, the custom script allocates the amount of space you specify plus an additional 50% to accommodate the Sybase transaction log. For example, if you specify 30 MB, the amount of space actually allocated is 45 MB.Sybase recommends that you use raw partitions for the data device. In this case, the size of the raw partition must be equal to the size of the Data portion plus 4 MB.



Query Socket Port Number -and-Backup Socket Port Number

Sybase utilizes these two TCP/IP ports for communication between CONTROL-M and Sybase SQL Server. The port numbers must be different from each other. If these port numbers are already used by an existing application, choose other values, each in the range 1024 to 65534 inclusive. Query Socket and Backup Socket each comprise 2 ports. Therefore, each value entered should be the lower port of a pair of available ports. For example, if the Query Port Socket is 7102, then port 7103 will also be used for Query Port communications.Default: 7102 and 7104

Master Device Type

Type of disk storage (raw partition or file system) used for the master Sybase database. (A raw partition installation offers enhanced database integrity.) Default: FILE.If you want Sybase to use a raw partition, type y in response to the prompt. An additional prompt will be displayed requesting the physical device name (described below).

Master Physical Device/Path Name

For Master Device Type FILE: Full path name where the master Sybase database will be located.Default: <controlm_home_dir>/sybase/data/master.datFor Master Device Type RAW: Physical device name of the raw partition on which the Sybase database will be located.

Data Device Type

Type of disk storage (raw partition or file system) used for the CONTROL-M database. Default: FILE

Data Physical Device/Path Name

For Data Device Type FILE: Full path name where the CONTROL-M database will be located. Default: /<controlm_home_dir>/sybase/data/ctrlm_ux.datFor Data Device Type RAW: Physical device name of the raw partition in which the CONTROL-M database will be located.

Log Device Type Type of disk storage (raw partition or file system) used for the CONTROL-M database log. Default: FILE.





Oracle

Oracle Database configuration parameters are specified during installation before the CONTROL-M database is created. You can also modify these parameters and rebuild the CONTROL-M database using the Database Creation menu, described in Chapter 4, “Maintenance.”

The Oracle database parameters are described below:

Log Physical Device/Path Name

For Log Device Type FILE: Full path name where the CONTROL-M database log will be located. Default: /<controlm_home_dir>/sybase/data/ctrlm_log.datFor Log Device Type RAW: Physical device name of the raw partition in which the CONTROL-M database log will be located.

Sybase Interface Directory

Directory in which the Sybase interfaces file is located. This path should be visible to CONTROL-M.

Sybase Server Name

Name of the SQL server. When you choose to modify this value, the custom script reads the Sybase interfaces file and displays a list of the available SQL servers. Specify the name of an SQL server from the displayed list (contact your system administrator for this information). Default: SYBASE

Remote Sybase Host Name

Name of the host for an existing Sybase Database server installation.

CONTROL-M Database Name

Name for the CONTROL-M database. This name must be unique. Default: ctrlm

CONTROL-M Database Data Device Name

Name of the Sybase device on which the CONTROL-M database will be created. (See the disk init command in the Sybase Commands Reference Manual for information about creating a Sybase device.) Default: ctrlm_ux

CONTROL-M Database Log Device Name

Name of the Sybase device on which the CONTROL-M database log will be created. (See the disk init command in the Sybase Commands Reference Manual for information about creating a Sybase device.) Default: ctrlm_log





Table 5-8 Oracle Database Parameters (Part 1 of 2)


CONTROL-M Database Instance name

The name of the Oracle SQL server (1 to 8 characters, alphabetic plus “_”). Default: ctrlm

Database User Name of CONTROL-M database user.Default: controlm

User Password Password for the CONTROL-M database user (6 to 30 characters, alphanumeric). The characters you enter are not echoed for security reasons. This password is used by CONTROL-M processes and utilities to access the CONTROL-M database. Default: password

Tablespace size Total size of the CONTROL-M database.Default: 250 MB

Oracle home directory Directory where Oracle binary files are stored.Default: /<controlm_home_dir>/oracle

Size of CONTROL-M database log files

The size of each database log file. There are two files of equal size.Default: 20 MB

Name of the Tablespace data file

Full path name of the CONTROL-M database data file.Default: /<controlm_home_dir>/oracle/oradata/ctrlm/data.dbf

Name of the first database log file

Full path name of the first database log file.Default: /<controlm_home_dir>/oracle/oradata/ctrlm/log01.dbf

Name of the second database log file

Full path name of the second database log file.Default: /<controlm_home_dir>/oracle/oradata/ctrlm/log02.dbf

Oracle CDROM name Name of CDROM device containing the Oracle installation CDROM.

CONTROL-M Listener port number

Oracle utilizes this TCP/IP port for communication between CONTROL-M and Oracle SQL Server. The port must be dedicated to this purpose. Choose a number in the range 1024 to 65534 inclusive. Default: 1521



Oracle SYSTEM user password

Password of the Oracle SYSTEM user.

CONTROL-M SYSTEM tablespace file location

Full path name to the CONTROL-M SYSTEM tablespace file.Default: /<controlm_home_dir>/oracle/oradata/ctrlm/system01.dbf

CONTROL-M SYSTEM tablespace size

Size of the CONTROL-M SYSTEM tablespace file. Default: 50 MB

CONTROL-M RBS (Rollback Segment) tablespace file location

Full path name to the CONTROL-M RBS tablespace file.Default: /<controlm_home_dir>/oracle/oradata/ctrlm/rbs01.dbf

CONTROL-M RBS tablespace size

Size of the CONTROL-M RBS tablespace file. Default: 50 MB

CONTROL-M TEMP tablespace file location

Full path name to the CONTROL-M TEMP tablespace file.Default: /<controlm_home_dir>/oracle/oradata/ctrlm/temp01.dbf

CONTROL-M TEMP tablespace size

Size of the CONTROL-M TEMP tablespace file. Default: 100 MB

CONTROL-M INDEX tablespace file location

Full path name to the CONTROL-M INDEX tablespace file.Default: /<controlm_home_dir>/oracle/oradata/ctrlm/indx01.dbf

CONTROL-M INDEX tablespace size

Size of the CONTROL-M INDEX tablespace file. Default: 50 MB

Oracle Server Host name

The host machine name of an existing Oracle server.

Table 5-8 Oracle Database Parameters (Part 2 of 2)




Mirroring Parameters

Parameters for database mirroring are specified when mirroring is initialized, either during CONTROL-M/Server installation or any time afterwards. You can modify these parameters by mirror initialization using the Database Mirroring menu described in Chapter 4, “Maintenance.”

Database mirroring parameters are described in Table 5-9.

Table 5-9 Mirroring Parameters (Part 1 of 2)


CONTROL-M Mirror Database Owner (Sybase and Oracle)

Name for the CONTROL-M mirror database owner. The install_mirror script creates this user in the database. This name is used by CONTROL-M when accessing the mirror database. Default: ctrlm

DBO Password (Sybase and Oracle)

Password for the CONTROL-M mirror database owner (6 to 30 characters, alphanumeric). The characters you enter are not echoed for security reasons. This password is used by CONTROL-M processes and utilities to access the CONTROL-M mirror database.

Mirror Sybase Server Name (Sybase)

Name of the SQL server to which CONTROL-M will connect for mirroring. When you choose to modify this value, the install_mirror script reads the Sybase interfaces file and displays a list of the available SQL servers. Specify the name of an SQL server from the displayed list (contact your system administrator for this information). Default: CTRLM2

Mirror Sybase/Oracle Host Name (Sybase and Oracle)

Host name of machine that runs the instance of the database SQL Server used for mirroring.

Mirror Sybase/Oracle Port Number (Sybase and Oracle)

TCP/IP query port number for the database SQL Server used for mirroring. If you are using a CONTROL-M dedicated database SQL Server for the mirror database, you can find its Sybase/Oracle Port Number in the QUERY_SPN field in the <controlm_owner>/install/install_defs file.



Performance Parameters

Special parameters are available for tuning CONTROL-M performance. These parameters affect how jobs are selected for both scheduling and post-processing. Table 5-10 describes the performance parameters in the CONTROL-M <controlm>/ctm/data/config.dat file where <controlm> is the CONTROL-M home directory.

CONTROL-M Mirror database name (Sybase)

Name of the Sybase CONTROL-M mirror database. This name must be unique. Default: ctrlm

Mirror Oracle Instance name (SID) (Oracle)

The name of the Oracle mirror SQL server (1 to 8 characters, alphabetic plus “_”). Default: ctrlm

CONTROL-M Mirror tablespace name (Oracle)

Name of the Oracle CONTROL-M mirror database. This name must be unique. Default: ctrlm

CONTROL-M Mirror database data device name (Sybase)

Name of the Sybase device on which the CONTROL-M mirror database will be created.Default: ctrlm_ux

CONTROL-M Mirror database log device name (Sybase)

Name of the Sybase device on which the CONTROL-M mirror database log will be created.Default: ctrlm_log

CONTROL-M Mirror Database Data Device Name (Sybase)

Name of the Sybase device on which the CONTROL-M mirror database will be created. (See the disk init command in the Sybase Commands Reference Manual for information about creating a Sybase device.) Default: ctm

CONTROL-M Mirror Database Log Device Name (Sybase)

Name of the Sybase device on which the CONTROL-M mirror database log will be created. (See the disk init command in the Sybase Commands Reference Manual for information about creating a Sybase device.) Default: ctmlog

Table 5-9 Mirroring Parameters (Part 2 of 2)




The sleep time setting for CONTROL-M processes can also affect the performance and functionality of CONTROL-M. For example, setting the sleep time of the Selector (SL) and/or Tracking (TR) process to 5, will improve performance, but CONTROL-M will consume more CPU. For more information, see “Sleep Time Considerations” on page 4-49.

Configuration Parameters

The following tables contain the current parameters in the CONTROL-M/Server configuration parameter file (config.dat) and CONTROL-M/Agent configuration parameter file (agconfig.dat). The config.dat file resides in directory <controlm>/ctm/data/ on the Server platform. The agconfig.dat file resides on the Agent platform.

Table 5-10 Performance Parameters


PRIORITY_SL_SCAN Indicates if job priority should be used during the job selection process (when deciding which job should run next. Valid values are:

0 - Use job priority. Default1 - Do not use job priority. This setting increases CONTROL-M performance.

SL_BREAK_INT Specify how many jobs to scan in the selection process before checking for jobs in the post processing queue. The lower the value, the faster the performance. The downside is that jobs at the bottom of the queue will take longer to be scheduled. Value range: 1-99999. Default: 100

PP_THRESHOLD Specify the maximum number of jobs that can wait in the post processing queue before post processing is initiated. The lower the value, the faster the jobs get post processed, but jobs at the bottom of the queue will take longer to be processed. Value range: 1-99999. Default: 10



CONTROL-M/Server Parameters (config.dat)

Table 5-11 CONTROL-M/Server Parameters (Part 1 of 3)

Parameter Name {Valid Values} Explanation

ALARM_DEST Logical name of the Shout destination for critical Alert messages. Default: ECS

AUTOEDIT_INC_SEC

{SYSTEM|GLOBAL|GROUP|LOCAL}Indicates which AutoEdit variables are sent to the Agent for each submitted job.Valid values:SYSTEM – All the AutoEdit variables for each submitted job are sent to the Agent. These include System, Global, Group, and Local variables. GLOBAL – Global, Group, and Local AutoEdit variables are sent to the Agent for each submitted job. System AutoEdit variables are not sent.GROUP – Group and Local AutoEdit variables are sent to the Agent for each submitted job. System and Global variables are not sent.LOCAL – Only Local AutoEdit variables are sent to the Agent. Default: LOCAL

CTM_DB_TIMEOUT

{300 – 3600}Timeout value (in seconds) for long database transactions. Default: 600

CTM_GROUP_ADJUST_DUMMY

{Y|N}When this parameter is set to Y, and a Group Scheduling table is ordered, jobs in the group that should not be ordered at this time are ordered as DUMMY jobs. This functionality is useful for data centers that require identical job flow regardless of whether certain jobs in a group are ordered for a specific instance of the group. Default: N



CTM_GROUP_RECHECK

{Y|N}Indicates if group conditions should be checked for each job in a Group Scheduling table after the groups conditions have been satisfied.

• N (default) group conditions are ignored when ordering specific jobs in a group.

• Y group conditions are checked for each job in the group (in addition to conditions specified for the job).

Note: If N is specified for this parameter, groups are activated when the necessary conditions exist, and remain active regardless of whether or not any of those conditions are deleted. Default: N

CTM_SLP_SUSPEND

{30 – 1200}During the New Day Procedure and Download of the Active Jobs file to ENTERPRISE/CS, the ctmcreate, ctmudly, and ctmorder utilities are suspended. They stay suspended until the Download or New Day Procedure is complete or until the specified timeout period. Default: 30 minutes

CTM_SNMP_SEND_FORMAT

{S,M}Indicates whether Single (S) or Multiple (M) variable format is used for SNMP traps. For more information, see “ctm2snmp” on page 2-155. Default: S

CTM_WRITE_CONSOLE

{YES, NO}If this parameter is set, critical alerts are sent to the console of the Server in addition to being sent as Shout messages to ENTERPRISE/CS. Default: NO

CTMLOG_DEL_CHK {YES, NO}When this parameter is set to Y, the use of the ctmlog utility for delete operation to Control-M is restricted. Administrator only.Default: N

CTMORDER_FORCE {Y, N}The default action of the utility is to order, not force, jobs in the Active Jobs file. This action can be modified by adding keyword Force to the command that invokes the utility. To change the default to force, set this parameter to Y. Default: N





CYCLIC_MAXWAIT Indicates when cyclic jobs, that have previously executed at least once, should be removed from the Active Jobs file by the New Day procedure.Valid values:• KEEP – jobs are removed from the Active Jobs file

when MAXWAIT days have passed regardless of whether or not the job ended OK.

• NOT KEEP – jobs are removed from the Active Jobs file at the next run of the New Day procedure. Default.

CYCLIC_RERUN {OK, NOTOK}If a cyclic job ends NOTOK and this parameter is set to OK, the cyclic job will be rerun. If set to NOTOK, the job will not be rerun. Default: OK.

IOALOG_DEL_INT {1 – 24}During the New Day procedure, old IOALOG records are removed. The default is to delete the old records in hourly bundles. If set to 24, all the old logs are deleted in one bundle. Default: 1.

RUNINF_PURGE_LIMIT

{0 – 65K}Number of Run Information records to keep for a given MemName/MemLib/NodeID. If RUNINF_PURGE_MODE is 0, the New Day Procedure deletes all Run Information records for each unique name except the last n records, where n is the value of this parameter. Default: 20.

RUNINF_PURGE_MODE

{0, 1}New Day Procedure algorithm for cleaning Run Information records. If set to 1, the New Day procedure will keep records for the last two days only. If 0, it uses the RUNINF_PURGE_LIMIT value. Default: 0.

STATS_TIME Indicates how the START TIME and END TIME for a job should be set. Valid values are:• SERVER – START TIME and END TIME are set by

CONTROL-M/Server.• AGENT – START TIME and END TIME are set

using information received from the CONTROL-M/Agent.

STATS_TIME SERVER or AGENT

START TIME and END TIME of a job can be set relative to either server or agent.





Table 5-12 Performance Parameters


PP_THRESHOLD {1 – 99999}Maximum number of jobs that can wait in the post processing queue before the Selector process is interrupted and post-processing is initiated. Default: 10.

PRIORITY_SL_SCAN

{0, 1}Indicates whether to disable (0) or enable (1) the use of the a job’s Priority in the selection process. Disabling priority increases performance. Default: 0.

SL_BREAK_INT {0 – 99999}The maximum number of jobs to scan in the selection process before checking for jobs in the post processing queue. Default: 100.

Table 5-13 Communication Parameters


CMN_PRM_CD_IPC_IN

Inter processing Communication (IPC) Input Queue. IPC between the CD and CO processes is performed by using Message Queue kernel resources. The CO process creates the resource and the CD process uses the value specified by this parameter to connect to the resource. The value specified must be unique for the machine where CONTROL-M is running.

CMN_PRM_CD_IPC_OUT

IPC Output Queue.

CMN_PRM_CD_MAX_DBU

{1000 – 65K}CONTROL-M accumulates all updates to the database before sending them to ENTERPRISE/CS. This parameter determines the maximum number of updates to accumulate before requesting a Download. Default 1000.

CMN_PRM_CD_MAX_SERVICE

{60 – 32K}Sets the maximum number of requests that can be queued by CONTROL-M/Server that originate from ENTERPRISE/CS gateways. Default: 60.



ENTERPRISE/CS Communication Parameters

Table 5-14 ENTERPRISE/CS Communication Parameters


CTM_PRM_KPA_ACTIVE

{Y, N}Indicates whether the Heartbeat monitor operates in active (Y) or passive (N) mode. Default: Y (Active)

CTM_PRM_KPA_BETWEEN_MSGS

{n}Time in seconds between heartbeat checks. Default: 300.

CTM_PRM_KPA_ROUNDTRIP_TIMEOUT

{n}Time in seconds to wait for a confirmation from ENTERPRISE/CS. If confirmation does not arrive, a timeout is generated and the connection is severed. Default: 300.

Table 5-15 User Exit Parameters (Part 1 of 2)


CTM_PRM_ENABLE_UE {Y, N}Indicates whether CONTROL-M user exits and Watchdog process exits are enabled. (See “Watchdog Process Parameters (config.dat)” on page 5-31.) Default: Y

CTM_PRM_ENABLE_UExxx (101-106)

{Y, N}Indicates whether the associated UExxx user exit is enabled. For more information, see “User Exits” on page 1-50. The following user exits are available:• UE101 Job Ordering User Exit• UE102 Job Submission User Exit• UE103 Before New Day Procedure User Exit• UE104 After New Day Procedure User Exit• UE105 Before User Daily User Exit• UE106 After User Daily User ExitDefault: N



CONTROL-M Server and Agent Parameters (config.dat and agconfig.dat)

CONTROL-M/Agent Parameters (agconfig.dat)

CTM_PRM_SCRIPT_UExxx

Name of the Uexxx user exit script. These scripts must reside in the ~controlm/ctm/ue_exit directory. Default: ctm_exitxxx.sh

CTM_PRM_TIMEOUT_UExxx

{n}Time in seconds to wait for a user exit script to run before it is terminated. Default: 20.

Table 5-16 CONTROL-M Server and Agent Parameters


COMM_TRACE {0, 1}Debug trace for communication. Default: 0.

COMTIMOUT {20-360}Communication timeout in seconds. Default: 120.

COMTRYNO {1-20}Communication retry value. Default: 12.

DEBUG_LEVEL CONTROL-M debug level.

OS_PRM_HOSTNAME Specifies a local Host Name other than the machine default Host Name.

PROTOCOL {TCP, UDP}Communication protocol. Default: TCP

Table 5-17 CONTROL-M/Agent Parameters (Part 1 of 3)


AG_PORT_NUM Agent Port number.

AGENT_DIR CONTROL-M/Agent installation directory.

PRINTER_NAME Printer name for Sysout.

CTM_PRM_DONT_DELETE

{YES}At the end of job execution, temporary scripts generated from jobs are deleted. If this value is set to Yes, temporary scripts are not deleted.

Table 5-15 User Exit Parameters (Part 2 of 2)




CTM_PRM_KSH_FLAGS

{-v,-x}Flags to include when running a job that is written in Korn Shell. Default: –x.

CTM_PRM_SH_FLAGS

{-v,-x}Flags to include when running a job that is written in Borne Shell. Default: –x.

CTM_SU_PATH Alternate path for the /bin/su binary that is used by CONTROL-M to launch user jobs.

CTM_PARM_ENC Character to use to enclose parameters before the job script is launched.To use blanks (version 2.1.0), leave the value blank.Default: Double quotes (“) .Each parameter passed to the script contains this character before and immediately after the parameter. If more than one parameter is used, the parameters are delimited by a space between the parameters.Use double quotes (“ ) if the CTM_PARM_ENC parameter is not defined in the agconfig.dat file.To specify the CTM_PARM_ENC parameter without a value, leave the enclosing character blank ( ).CONTROL-M launches a job using su - owner -c memlib/memname parm1 parm2 parm3 ...The user can control the evaluation of parameters by enclosing the parameters with different characters.If double quotes are used (") then variables are resolved in the owners environment before they are passed to the script. If single quotes (’) are used then the parameters are not evaluated before the script is launched.Before enclosing a parameter with predefined characters CONTROLM checks if the user already enclosed the parameter. If the parameter is already encapsulated, then CONTROLM skips the encapsulation process so that the parameter will not be encapsulated twice.

CTMS_ADDR_MODE

{IP}If this parameter is set to IP, the IP address is saved in CTMS_HOSTNAME instead of the host name. Use this parameter when CONTROL-M runs on a platform with more than one network card.





CTMS_COMVERSION

{01| 02| 03}Specifies the CONTROL-M/Server version with which the agent is working. Valid values are:• 01 for 2.2.4• 02 for 2.2.5• 03 for 6.0.00. Default

CTMS_HOSTNAME Primary host running CONTROL-M/Server.

CTMS_PORT_NUM Port number that CONTROL-M/Server listens to.

EXIT_STATUS_DIR Redefined Exit Status directory on the Agent platform used to store job status.

SYSOUT_NAME {JOBNAME | MEMNAME}If this parameter is set to JOBNAME, parameter Jobname is used in the sysout file instead of parameter Memname. Default: MEMNAME.

SYSOUT_MODE Octal value indicating file access mode of the Sysout (output) file.For example, 777 indicates the highest level of access.

TRANSLATE_$0 {Y | N}If this parameter is set to N, $0 is not translated in a script before it is run. Otherwise, $0 is replaced by a file name before the script is run. Default: Y





Watchdog Process Parameters (config.dat)

The following parameters are used for the Watchdog Process. (For more information, see “Watchdog Facility” on page 1-44.) Parameter CTM_PRM_ENABLE_UE must be set to Y to enable the WD process.

General Parameters

Table 5-18 General Watchdog Process Parameters (Part 1 of 2)


WD_INTERVAL {n}Amount of time in minutes between each set of Watchdog checks. If the checks take longer than the specified time, the time interval is saved and the longest interval time is included in the message sent automatically to the error handler(s) once every 50 intervals. Default: 5.

WD_HEARTBEAT_INTERVAL

{n}Nth interval in the Watchdog process to check CONTROL-M processes. If this parameter is set to 5, the Watchdog process sends a message to each of the primary CONTROL-M processes every 5th interval and awaits a response. Default: 5

WD_HEARTBEAT_TIMEOUT

{n}Maximum time (in seconds) to wait for a response from each of the CONTROL-M processes, after issuing a Heartbeat check, before sending a message to the error handlers. Default: 360.

WD_CTMEXIT_NUMBER

{n}Total number of CONTROL-M system exits to run. Default: 2.

WD_USEREXIT_NUMBER

{n}Total number of user exits to run. Default: 0.

WD_ALIVE_MSG Message string sent every interval to the error handlers if all the Watchdog processes are functioning. We recommend that you use this parameter when using CONTROL-O/Server as an error handler (see WD_CTO_HOSTNAME below). Default: WD is alive.



CONTROL-M System Exit Parameters

The # used in each of the following CONTROL-M system exit parameters represents the corresponding CONTROL-M utility that can be included in the CONTROL-M Watchdog process: Disk Space Utility (1) and Database Usage Utility (2). See “ctmdiskspace” on page 2-62 and “ctmdbspace” on page 2-45 for more information.

WD_CTO_HOSTNAME

Host name or IP address of the machine running CONTROL-O/Server. If this parameter is specified, the Watchdog process sends all error messages to the CONTROL-O/Server Central Message window.

WD_CTO_TIMEOUT {1-10}Maximum time (in second) to send messages to CONTROL-O/Server before terminating the communication. Default: 10 seconds.

WD_ERROR_HANDLER_SCRIPT_FILE

Full path name of a user defined script called by the Watchdog process as an error handler. The error messages are included as arguments to the script. Default: ./scripts/UE_handler that sends alerts to ENTERPRISE/CS.

WD_ERROR_HANDLER_TIMEOUT

{n}Maximum time in seconds to wait for the error handler script to run before terminating the script. Default: 5.

Table 5-19 Watchdog Parameters for CONTROL-M System Exits (Part 1 of 2)


WD_CTMEXIT_#_CMD_LINE Arguments to be passed to the utility. Arguments must start with a ‘-’ sign. Values separated by either a space or a ‘-’ sign must be enclosed in double quotes. Mandatory.Default for #1: -Limit 10M -Path $HOMEDefault for #2: -Limit 90

WD_CTMEXIT_#_ERROR_MSG Error message string to be passed to the error handler(s) if the utility returns a “failed” status. Optional.

Table 5-18 General Watchdog Process Parameters (Part 2 of 2)




Watchdog User Exit Parameters

The # used in the following user exit parameters represents a separate number for each user exit that can be included in the CONTROL-M Watchdog process (see “Watchdog Facility” on page 1-44). A user exit can be either a user supplied script/executable file or a CONTROL-M utility (see Chapter 2, “Utilities”).

WD_CTMEXIT_#_INTERVAL {1-1440 intervals per day}Interval in the Watchdog process in which to run this utility. Required. Default: 5.

WD_CTMEXIT_#_RUN_STATE {Y, N}Specify whether (Y) or not (N) to run the utility in Run (that is, normal) mode. A Y must be specified for either this parameter or for parameter WD_CTMEXIT_#_SUSPEND _STATE for the utility to be run. Default: N.

WD_CTMEXIT_#_SCRIPT_FILE Relative path of the executable file from the ~controlm\ctm\exe_<platform> directory. Default for #1: CTMDISKSPACEDefault for #2: CTMDBSPACE

WD_CTMEXIT_#_SUSPEND_STATE

{Y, N}Specify whether (Y) or not (N) to run the utility in Suspend mode (that is, during New Day procedure or download, when the database inaccessible). A Y must be specified for either this parameter or for parameter WD_CTMEXIT_#_RUN _STATE for the utility to be run. Default: N.

WD_CTMEXIT_#_TIMEOUT {n}Maximum time (in seconds) that the utility is allowed to run. If the utility runs longer than the time indicated, it will terminate and an error message will be sent. Mandatory. Default: 5 seconds.

Table 5-19 Watchdog Parameters for CONTROL-M System Exits (Part 2 of 2)




Table 5-20 Watchdog Parameters User Exit


WD_USEREXIT_#_CMD_LINE Arguments to be passed to the script/executable file. Arguments must start with a ‘-’ sign. Values separated by either a space or a ‘-’ sign must be enclosed in double quotes. Optional.

WD_USEREXIT_#_ERROR_MSG

Error message string to be passed to the error handler(s) if the check returns a “failed” status. Optional.

WD_USEREXIT_#_INTERVAL {1-1440 intervals per day}Interval in the Watchdog process in which to run this script. Mandatory. Default: 5.

WD_USEREXIT_#_RUN_STATE

{Y, N}Specify whether (Y) or not (N) to run the script in Run (that is, normal) mode. This parameter or WD_CTMEXIT_#_SUSPEND _STATE must be set to Y for the script to be run. Default: N.

WD_USEREXIT_#_SCRIPT_FILE

Full path of the user script/executable file. Mandatory. Example: ~controlm\ctm\exe_<platform>\ctm_ping_list

WD_USEREXIT_#_SUSPEND_STATE

{Y, N}Specify whether (Y) or not (N) to run the script in Suspend mode (that is, during New Day procedure or download, when the database inaccessible). This parameter or WD_CTMEXIT_#_RUN _STATE must be set to Y for the script to be run. Default: N.

WD_USEREXIT_#_TIMEOUT {n}Maximum time in seconds that the script is allowed to run. If the script runs longer than the time indicated, it will terminate and an error message will be sent. Mandatory. Default: 5.


User Exits 6-1

6

User Exits 6

A user exit is a user-defined procedure that can be used to modify certain information before it is processed. At certain points in CONTROL-M processing a flat text file is produced describing information that is to be passed to next step in a procedure. This text file can be modified by a user-defined exit script before it is passed on for processing.

CONTROL-M user exits can be used to enforce site standards (for example, file naming conventions or valid date formats), and to apply security definitions to limit certain user’s actions. Exits can also be used to trigger other actions prior or subsequent to execution of a CONTROL-M job or a CONTROL-M procedure.

All user-defined exit scripts must be located in the ~<controlm_owner>/ctm/ue_exit directory and have default file names in the format ctm_exitxxx.sh, where xxx is the exit number.

Table 6-1 describes the available CONTROL-M user exits.



NoteA special category of user exits can be defined for the Watchdog facility. For more information, see “Watchdog Facility” on page 1-44.

Table 6-1 CONTROL-M General User Exits

User Exit Description

CTMUE101 Job Ordering User Exit – executed for each CONTROL-M job before it is ordered. For more information, see “Job Order Exit (CTMUE101)” on page 6-5.

CTMUE102 Job Submission User Exit – executed for each CONTROL-M job before it is submitted for execution. For more information, see “Job Submission Exit (CTMUE102)” on page 6-7.

CTMUE103 Before New Day Procedure User Exit – executed before the New Day procedure is run. For more information, see “Before New Day Procedure Exit (CTMUE103)” on page 6-9.

CTMUE104 After New Day Procedure User Exit – executed after the New Day procedure is run. For more information, see “After New Day Procedure Exit (CTMUE104)” on page 6-10.

CTMUE105 Before User Daily User Exit – executed before each run of a CONTROL-M User Daily job (except SYSTEM).For more information, see “Before User Daily Exit (CTMUE105)” on page 6-11.

CTMUE106 After User Daily User Exit – executed after each run of a CONTROL-M User Daily job (except SYSTEM).For more information, see “After User Daily Exit (CTMUE106)” on page 6-11.


User Exits 6-3

Configuring CONTROL-M Exits

To enable CONTROL-M exits, you must specify Y for parameter CTM_PRM_ENABLE_UE in the config.dat file. Certain other parameters are used to enable and disable specific exits.

Some of these parameters are described in Table 6-2. For more information, see Chapter 5, “Customization Parameters.”

Table 6-2 Exit Configuration Parameters

Parameter NameValid Values Description

CTM_PRM_ENABLE_UE {Y, N} Indicates whether or not CONTROL-M user exits are enabled. This parameter must be set to Y to enable all user exits. Default: Y

CTM_PRM_ENABLE_UExxx {Y, N} Indicates whether or not the Associated UExxx user exit is enabled (where xxx = 101-106). • UE101 Job Ordering User Exit• UE102 Job Submission User Exit• UE103 Before New Day Procedure User Exit• UE104 After New Day Procedure User Exit• UE105 Before User Daily User Exit• UE106 After User Daily User ExitDefault: N

CTM_PRM_SCRIPT_UExxx string Name of the UExxx user exit script (where xxx = 101-106). These scripts must reside in the ~<controlm_owner>/ctm/ue_exit directory. Default: ctm_exitxxx.sh

CTM_PRM_TIMEOUT_UExxx {n} Time (in seconds) to wait for the associated user exit script to run before it is terminated. Default: 20 seconds



User Exit Workflow

Each user exit is triggered at a specific point in CONTROL-M processing. The following steps illustrate what happens when an exit has been enabled.

NoteUser exits are implemented only if they have been enabled by setting the appropriate configuration parameters (described in Table 6-2, “Exit Configuration Parameters,” on page 6-3).

1. A flat text file is produced containing parameters to be processed by CONTROL-M.

2. The name of the text file is passed as the $1 parameter to the user exit script in the ue_exit directory.

3. The user exit script is run. This script is often used to modify the contents of the text file. However, it can also be used to perform any other action (for example, to copy information from the text file to another location).

4. CONTROL-M continues processing using the modified text file.


User Exits 6-5

Job Order Exit (CTMUE101)

This exit is executed for each CONTROL-M job before it is ordered. The flat text file passed to the exit is a job record from the Scheduling definition table. User exit CTMUE101 can be used to alter the job information in this after it is fetched from the database and before it is passed to the procedure that will determine if the job will be ordered for the current day.

The following is a sample text file in the format that is passed to the CTMUE101 exit:

JOBNAME daily_jobJOBNO 30DESCRIPTAPPLIC STRESSAPPLGROUP STRESSSCHEDTAB STRESSAUTHOR ctm600OWNER ctm600PRIORITY 0CRITICAL NCYCLIC NRETRO NAUTOARCH NTASKCLASSCYCLICINT 0TASKTYPE CDATEMEMNODEGRPPLATFORM NODEIDDOCLIBDOCMEMMEMLIBMEMNAME OVERLIBCMDLINE ./stress_cmd_spl.ctm600MAXRERUN 0MAXDAYS 0MAXRUNS 0FROMTIME



UNTIL MAXWAIT 0DAYSTR ALL WDAYSTRMONTHSTR YYYYYYYYYYYYAJFSONSTR NNNNNNNNNNNNNCONF NUNKNOWNTIM 0DAYSCAL WEEKCAL CONFCAL CAL_ANDOR O SHIFT ADJUST_COND STARTENDCYCIND S CREATIONUSERID ctm600 CREATIONDATETIME 20001113070229CHANGEUSERID CHANGEDATETIME RELATIONSHIP GROUPID 0TABROWNO 1

Example

The following exit script changes the Days parameter (DAYSTR) for jobs that were scheduled on the first day of the month, so that these jobs will be ordered on the second day of the month.

#!/bin/kshcp $1 /tmp/ue101.$$sed -e ’s/DAYSTR 1/DAYSTR 2/’ /tmp/ue101.$$ > $1


User Exits 6-7

Job Submission Exit (CTMUE102)

This exit is executed for each CONTROL-M job before it is submitted for execution. The flat text file passed to the exit contains a job record from the Active Job File table. User exit CTMUE102 can be used to alter job information in this record before it is passed to the CONTROL-M/Agent for job submission.


JOBNO 0ORDERNO 19450PRIORITY 1039CRITICAL N TASKTYPE C CYCLIC N CONFIRM_R N CONFIRMED N RETRO N AUTOARCH N TASKCLASS HOLDFLAG N STATUS N STATE ECYCLICINT 0APPLGROUP dw_S_A_AASNODEGRPNODEID fireMEMLIB /mdw/oper/tgt/scripts/shells MEMNAME dw##r##### OVERLIB /mdw/oper/tgt/scripts/shells/overlib_all CMDLINE sleep 30ODATE 19960229PROCID RERUN_NO 0OSCOMPSTAT 0OSCOMPMSG NEXTTIME PREVDATE NEXTDATE STARTRUN



ENDRUN MAXRERUN 0FROMTIME UNTIL JOBNAME dwlnr21AASSCHEDTAB CREATED OWNER ctm600 MAXWAIT 7APPLIC DW_ln RUNCOUNT 1DAILYNAME ctm600 AJFSONSTR YYNNYNNNNNNNNDESCRIPT Datawarehouse ln snapshot sort and form DOCMEM dwlnr1 DOCLIB /mdw/cntlm/doc MAXDAYS 0MAXRUNS 0UNKNOWNTIM 0STARTENDCYCIND S TRIGGER_TAG GROUP_ORD 0AUTHOR

Example

The following exit script checks if the job has a Owner of root and changes the Owner for these jobs to nobody.

#!/bin/kshcp $1 /tmp/ue102.$$sed -e ’s/OWNER root/OWNER nobody/’ /tmp/ue102.$$ > $1


User Exits 6-9

Before New Day Procedure Exit (CTMUE103)

This exit is executed before the New Day procedure is run. The New Day Procedure performs automatic functions at the beginning of each new CONTROL-M working day. This procedure is used as a master scheduler for all CONTROL-M activities. For more information, see “New Day Procedure” on page 1-13.

The flat text file that is passed to the exit contains the name of the Daily (SYSTEM), time, and original scheduling date (Odate) of the procedure.


DAILY_NAME SYSTEMTIME 1300ODATE 20001121

Example

The following exit script runs a procedure that performs various actions before the New Day procedure is run.

#!/bin/ksh/opt/controlm/scripts/run_pre_New_Day_proc



After New Day Procedure Exit (CTMUE104)

This exit is executed after each run of the CONTROL-M New Day procedure. The flat text file that is passed to the exit contains the name of the Daily (SYSTEM), time, and original scheduling date (Odate) of the procedure.


DAILY_NAME SYSTEMTIME 1319ODATE 20001121

Example

The following exit script runs a procedure that performs various actions after completion of the New Day procedure.

#!/bin/ksh/opt/controlm/scripts/run_post_New_Day_proc


User Exits 6-11

Before User Daily Exit (CTMUE105)

This exit is executed before each CONTROL-M User Daily job (except SYSTEM) is run. User Daily jobs can be used to order new jobs. For more information, see “User Daily Jobs” on page 1-18.

The flat text file that is passed to the exit contains the name of the User Daily, time, and original scheduling date (Odate) of the User Daily job.


DAILY_NAME my_dailyTIME 1321ODATE 20001121

After User Daily Exit (CTMUE106)

This exit is executed after each CONTROL-M User Daily job (except SYSTEM) is run. User Daily jobs can be used to order new jobs. For more information, see “User Daily Jobs” on page 1-18.

The flat text file that is passed to the exit contains the name of the User Daily, time, and original scheduling date (Odate) of the User Daily job.


DAILY_NAME my_dailyTIME 1322ODATE 20001121


Mirroring and Failover 7-1

7

Mirroring and Failover 7

This chapter provides in-depth information about database mirroring and failover support for the CONTROL-M/Server platform. General planning considerations and detailed administrative procedures are discussed.

Failover Planning

You can implement either one of the following levels of failover capability:

• Mirror Database - a database on an independent database server mirrors the CONTROL-M/Server database.

• Failover Server - a secondary CONTROL-M/Server installation on a different computer, including a mirror database.


7-2 CONTROL-M/Server for Unix Installation Guide

Mirror Database

The Mirror Database option is illustrated schematically in Figure 7-1. In addition to the primary database installed with CONTROL-M/Server, a secondary database is built on another Database Server platform. All transactions to the primary CONTROL-M database are written to the secondary mirror database.

Figure 7-1 Database Mirroring

If the CONTROL-M primary database server fails, or if the primary database loses integrity, CONTROL-M/Server operation can be restored using either of the following manual interventions:

• You can direct CONTROL-M/Server to use the mirror database instead of the primary database. The primary CONTROL-M database can be rebuilt when time allows.

• You can rebuild the CONTROL-M primary database from the mirror database.

If communication with the mirror database fails, the mirror database is considered damaged and writing to it is disabled. Normal CONTROL-M operation is not affected. Mirroring can be re-initialized after you repair the communications link.

Implementing a Mirror Database

Database mirroring can be initialized any time after CONTROL-M/Server has been installed.



The mirror database should be built on a separate database server, independent of the database server that hosts the primary CONTROL-M database.

• Requirements and preparatory steps for a mirror database on a Sybase database server are described in “Preparing a CONTROL-M Mirror Database on a Sybase Server” on page 7-4.

• Requirements and preparatory steps for a mirror database on an Oracle database server are described in “Preparing a CONTROL-M Mirror Database on an Oracle Server” on page 7-7.

Several administrative functions are used to initialize, enable, and restore CONTROL-M database mirroring. They are described in Table 7-1. These functions are accessed from the Database Mirroring menu of the CONTROL-M/Server Main Menu (see “The Database Mirroring Menu” on page 7-13).

For a description of database failover, recovery, and restoration procedures, see “Recovering from Database Failure (Mirror Database)” on page 7-29.

Table 7-1 Database Mirroring Functions (Part 1 of 2)

Menu Option Description


Reports the current mirroring status:Enabled: system writes transactions to mirror database.Disabled: system does not write to mirror database.Damaged: mirror database is damaged, mirroring is disabled.Mirroring is not defined: the query process did not succeed in accessing the primary database server.

Initialize Mirroring

Initializes Mirroring with a secondary database. You can choose to copy the primary database to an existing database, or build/rebuild the secondary database from scratch. Running this procedure leaves mirroring enabled. See “Initializing the Mirror Database - Copy/Build” on page 7-16.

Disable Mirroring

Stops Mirroring. Transactions are no longer written to the secondary database server. You must use the Initialize Mirroring option to re-enable mirroring.



Preparing a CONTROL-M Mirror Database on a Sybase Server

To prepare the mirror database, verify the requirements listed here, and perform the specified configuration steps.

NoteDatabase and account names that you create must conform to Sybase naming conventions.

1. Verify that the Sybase SQL Server used for mirroring will be running, both when initializing mirroring, and whenever CONTROL-M/Server is operational.

2. When building a database from scratch, you will need the password of the Sybase system administrator for installation.

3. Determine the following parameter values:

• Sybase Host Name - Host name of the machine that runs the Sybase SQL Server to be used for mirroring.

• Sybase Port Number - TCP/IP query port number for the Sybase SQL Server to be used for mirroring. Use the dsedit utility to find this value.

Use Mirror Database

Used when the primary database has failed or become damaged. CONTROL-M/Server operates using the mirror database. See “Operating CONTROL-M/Server with the Mirror Database” on page 7-30.


Restores normal function after the primary database has been repaired. Copies mirror database to primary database. CONTROL-M/Server operates using the primary database. After restoring, you must run the Initialize Mirroring option to re-enable mirroring. See “Restoring the Primary Database and Initializing Mirroring” on page 7-31.

Table 7-1 Database Mirroring Functions (Part 2 of 2)



• Parameters user connections, memory, and locks must contain appropriate values. For more information, see the CONTROL-M/Server for Unix Installation Guide.

If you change the value of any of these parameters, the change will not be implemented until you shut down and restart Sybase SQL Server. For more information about Sybase parameters see descriptions of dsedit, sp_configure, and reconfigure in the Sybase Commands Reference Manual.

4. The following details are needed to construct the database:

• A database name and a database owner (DBO) name for the mirror database. The database name can be the same as the database owner name, but the database name and database owner name must each be unique for a particular Sybase SQL Server. Therefore, when selecting names for the CONTROL-M database (using an existing Sybase SQL Server), verify that the database name and database owner name are unique for the Sybase SQL Server.

• Unix system paths or raw partitions for the temp and log datafiles. These paths must be unique.

• Sybase device names for the temp and log databases. These names must be unique for the database server. Use the sp_helpdevice command to view existing devices on the database server.

If you will be building a database, you must supply values for the database owner, database name, devices and file/partition paths:

• Specifying existing owner name, database name, and device assigments will erase and recreate these database elements.

• Specifying new, unique values for owner name, database name, and device assigments will build a new database on the server.

• Any filenames you specify for a file-based installation must not exist on the mirror database server.



For more information about database names, see create database in the Sybase Commands Reference Manual. For more information about login names, see sp_addlogin in the Sybase Commands Reference Manual.

5. Every platform type uses a different character set for Sybase. If the character set for the primary database and mirror database are not the same, the character set for the primary database must be installed on the mirror Sybase SQL Server. Use the dsedit Sybase utility to configure the character set for the existing SQL Server.



Preparing a CONTROL-M Mirror Database on an Oracle Server

To prepare the mirror database, verify the requirements listed here, and perform the specified configuration steps.

NoteDatabase and account names that you create must conform to Oracle naming conventions.

1. Verify that the Oracle SQL Server and the listener for the mirror database will be running, both when initializing mirroring, and whenever CONTROL-M/Server is operational.

2. When building a database from scratch, you will need the password of the Oracle system administrator for installation.

3. Determine the following parameter values:

• Oracle SID - Server ID of the secondary database server.

• Oracle Host Name - Host name of the machine that runs the Oracle SQL Server to be used for mirroring.

• Oracle Port Number - TCP/IP query port number for the Oracle SQL Server used for mirroring.

To find the values for these parameters, specify the following commands on the secondary database server:

echo $ORACLE_SIDcat $ORACLE_HOME/network/admin/tnsnames.ora

4. The tablespace name and database owner name must each be unique for a particular Oracle SQL Server. However, the tablespace name and the DBO name can be identical to each other. Therefore, when selecting names for the CONTROL-M mirror database, verify that the tablespace name and owner name are each unique for the particular Oracle SQL Server.



If you will be building a database, you must supply values for the database owner and tablespace name:

• Specifying existing owner and tablespace will erase and recreate these database elements.

• Specifying new, unique values for owner and tablespace name will build a new database on the server.



Failover Server

The Failover Server option is illustrated schematically in Figure 7-2. A secondary installation of the CONTROL-M/Server resides on a separate computer. Typically the database of the secondary CONTROL-M/Server, created as part of the CONTROL-M/Server installation, acts as a mirror database.

The secondary CONTROL-M/Server, including its database, acts as a backup to the primary CONTROL-M/Server. This secondary CONTROL-M/Server platform is sometimes called the Mirror Environment.

The secondary CONTROL-M/Server duplicates all of the primary CONTROL-M/Server’s links to CONTROL-M/Agents or ENTERPRISE/CS workstations. The secondary CONTROL-M/Server is defined in the each ENTERPRISE/CS workstation’s Data Centers window, and in each Agent’s list of authorized server hosts.

Figure 7-2 Server Platform Failover - Primary Environment and Mirror Environment

During normal operation, the secondary database is constantly updated to remain identical with the primary database. The secondary CONTROL-M/Server remains inactive.



If the primary CONTROL-M/Server fails due to a hardware/software problem on the primary platform, the administrator activates failover to the secondary CONTROL-M/Server. The secondary CONTROL-M/Server performs all normal CONTROL-M functions until the primary CONTROL-M/Server is repaired.

Jobs submitted to Agent platforms before failover continue executing. The secondary CONTROL-M/Server polls the Agent platforms to determine the status of jobs listed in the Active Jobs file.

When the primary CONTROL-M/Server is stable, normal operation is restored. The failover server is shut down, the primary database is restored, and the primary CONTROL-M./Server is restarted. The secondary server returns to passive readiness.

Implementing a Failover Server

A failover server can be implemented any time after CONTROL-M/Server has been installed.

The secondary CONTROL-M/Server installation should be built on a separate computer and database server, independent of the platforms server that host the primary CONTROL-M/Server and its database.

Requirements and preparatory steps for the failover server are described in “Preparing a Failover Server” on page 7-12.

Several administrative functions are used to initialize, enable, and restore database mirroring. They are described in . These functions are accessed from the Database Mirroring menu of the CONTROL-M/Server Main Menu (see “The Database Mirroring Menu” on page 7-13).

For a description of server failover, recovery, and restoration procedures, see “Recovering from Primary CONTROL-M/Server Failure (Server Failover)” on page 7-33.



Table 7-2 Server Failover Functions

Menu Option Description

Initialize Failover Initializes the Failover Server on the secondary CONTROL-M/Server. The secondary CONTROL-M/Server is dormant and inactive. See “Initializing the Failover Server” on page 7-27.

Start Failover Used when primary CONTROL-M/Server platform fails. To activate the secondary CONTROL-M/Server using the mirror database, you must first run this option, then start CONTROL-M/Server on the secondary platform. See “Failover to the Secondary CONTROL-M/Server” on page 7-33.

Stop Failover Stops failover operation. See “Restoring the Primary CONTROL-M/Server” on page 7-34.

Disable Failover Disengages the secondary CONTROL-M/Server from the primary CONTROL-M/Server. To restore failover, you must initialize the failover server from scratch using the Initialize Failover and Initialize Mirroring options.



Preparing a Failover Server

Install CONTROL-M/Server on the secondary, failover computer using the standard installation procedures described in the CONTROL-M/Server for Unix Installation Guide. Verify the following conditions for the secondary installation:

• The Agent-to-Server Port Number and Server-to-Agent Port Number communication parameters must be the same on both CONTROL-M/Server platforms. These ports must also be dedicated to the use of CONTROL-M/Server. You should also ensure that both machines are using the same date.

• Although the failover server can be configured to use a dedicated or a non-dedicated database SQL Server, it should not use the same instance of the database SQL Server used by the primary environment.

• The parameter Database (Data Portion) Size should be assigned the same value as the current size of the primary database.

• All Agent platforms or ENTERPRISE/CS workstations that are defined on the primary CONTROL-M/Server should also be defined on the failover server. These definitions must be identical. If you installed CONTROL-M/Agent on the primary CONTROL-M computer, it should also be installed on the failover server. The parameters should be the same on both CONTROL-M/Server installations.

The failover server’s host name must be added to each Agent’s list of authorized hosts. Similarly, each ENTERPRISE/CS workstation.should include the mirror environment host name in the Data Center window.



Failover Administration Procedures

This section details the steps you will take to prepare failover systems, to implement them if necessary, and to restore normal function.

The Database Mirroring Menu

Most of the commands and procedures used to manage mirroring and failover are accessed through the Database Mirroring menu.

To access the Database Mirroring Menu:

Step 1 Log in to the platform as the CONTROL-M/Server owner.

Step 2 Enter the following command to open the CONTROL-M Main Menu:

ctm_menu

Step 3 The following menu is displayed:

CONTROL-M Main Menu: Select one of the following menus:1 - CONTROL-M Manager2 - Database Creation3 - Database Maintenance4 - Database Mirroring5 - Security Authorization6 - Parameter Customization7 - Node Group8 - Agent Status9 - Troubleshooting

q - Quit

Type 4 to select Database Mirroring and press <Enter>.



Step 4 The Database Mirroring menu is displayed:

Database Mirroring Menu----------------------------Select one of the following options:

Primary Server Options:1 - Check Mirroring Status2 - Initialize Mirroring3 - Disable Mirroring4 - Use Mirror Database5 - Restore CONTROL-M Database from Mirror

Failover Server Options:6 - Initialize Failover7 - Start Failover8 - Stop Failover9 - Disable Failover

q - Quit

Enter option number ---> []:

The options of the Database Mirroring menu are divided into procedures implemented on the primary CONTROL-M/Server, and procedures implemented on the secondary, failover CONTROL-M/Server. Table 7-3 summarizes the Database mirroring options.

NoteMost options on the Database Mirroring menu change system variables in the user environment (in file .cshrc). To start CONTROL-M/Server in the current window after running these options, specify the command source ~/.cshrc to restore user environment variables.

Table 7-3 Database Mirroring Menu Options (Part 1 of 2)

Primary Server Options

Option Description


Reports the current mirroring status:Enabled: system writes transactions to mirror database.Disabled: system does not write to mirror database.Damaged: mirror database is damaged, mirroring is disabled.Mirroring is not defined: the query process did not succeed in accessing the primary database server.



Initialize Mirroring Initializes Mirroring with a secondary database. You can choose to copy the primary database to an existing database, or build/rebuild the secondary database from scratch. Running this procedure leaves mirroring enabled.

Disable Mirroring Stops Mirroring. Transactions are no longer written to the secondary database. You must use the Initialize Mirroring option to re-enable mirroring.

Use Mirror Database

Used when the primary database has failed or become damaged. CONTROL-M/Server operates using the mirror database.


Restores normal function after the primary database has been repaired. Copies mirror database to primary database. CONTROL-M/Server operates using the primary database. After restoring, you must run the Initialize Mirroring option to re-enable mirroring.

Failover Server Options

Option Description

Initialize Failover Initializes the Failover Server on the secondary CONTROL-M/Server. The secondary CONTROL-M/Server remains dormant and inactive.

Start Failover Used when primary CONTROL-M/Server platform fails. First run this option on the secondary CONTROL-M/Server, then start the secondary CONTROL-M/Server.

Stop Failover Stops failover operation.

Disable Failover Disengages the secondary CONTROL-M/Server from the primary CONTROL-M/Server. To restore failover, you must implement the failover server from scratch using the Initialize Failover and Initialize Mirroring options.

Table 7-3 Database Mirroring Menu Options (Part 2 of 2)



Initializing Mirror Database and Failover Server

This section describes the procedures for initializing the mirror database and failover server.

• For a Mirror Database, the initialization process copies the contents of the existing database to an existing secondary database, or builds a new secondary database from scratch and copies the contents of the existing database. Then database mirroring is activated between the primary and secondary databases.

To initialize a mirror database, follow the procedure “Initializing the Mirror Database - Copy/Build” on page 7-16.

• For a Failover Server, the initialization process synchronizes primary and secondary CONTROL-M/Servers and activates failover readiness. The Mirror Database is also initialized.

To initialize a mirror environment, follow the procedure “Initializing the Failover Server” on page 7-27.

Initializing the Mirror Database - Copy/Build

The following procedure is used to initialize database mirroring for the CONTROL-M database.

NoteDuring the procedure to initialize the CONTROL-M mirror database: for Sybase: a new entry is automatically added to the interfaces file with the Sybase Server Name MIRROR.for Oracle: a new entry is automatically added to the tnsnames.ora file with the Oracle Server Name ctrlm_mirror.

Step 1 Verify that the secondary database server conforms to the requirements for mirroring as described in:

• “Preparing a CONTROL-M Mirror Database on a Sybase Server” on page 7-4 for a Sybase SQL Server

• “Preparing a CONTROL-M Mirror Database on an Oracle Server” on page 7-7 for an Oracle SQL Server



Step 2 Verify that:

• The primary CONTROL-M/Server is not running.• Both the primary and mirror database servers are running.

Step 3 Log in to the primary platform as the CONTROL-M/Server owner.

Step 4 Specify the ctm_menu command to open the CONTROL-M Main Menu. Type 4 to select Database Mirroring and press <Enter>. From the Database Mirroring menu, type 2 to select Initialize Mirroring and press <Enter>.

Step 5 The following messages are displayed:

+----------------------------------------+|Copy/Build the CONTROL-M Mirror database|+----------------------------------------+

Do you wish to build a new CONTROL-M Mirror database [y/n] :

To copy the primary database to an existing secondary database, type n and press <Enter>.

To build a secondary database from scratch, type y and press <Enter>.

NoteIf you are initializing database mirroring for the first time, you must select the build option to create the mirror database. You cannot use the copy option until the mirror database has been built.

• For Sybase database servers, continue with Step 6.

• For Oracle database servers, continue with Step 8 on page 7-21.

Step 6 The Mirroring Parameters screen is displayed.

If you selected the copy option, Figure 7-3 shows the Mirroring Parameters screen for Sybase Database Servers.

Figure 7-3 Mirroring Parameters for Database Copying - Sybase



Mirroring Parameters:

1) CONTROL-M Mirror Database owner(DBO): ctmfox2) DBO password: ######

Mirror database (data portion) size: 80 MBSybase interface directory: /home/ctm600us/sybase

3) Mirror Sybase Host Name: jordan4) Mirror Sybase Port Number: 41005) CONTROL-M Mirror database name: FoxDb

a|A) Modify all of the aboveb|B) Build Mirror Databaseq|Q) Quit

Enter command or item number you wish to change [b]:

If you selected the build option, additional parameters are displayed as in Figure 7-4.

Figure 7-4 Mirroring Parameters for Database Build/Rebuild - Sybase


1) CONTROL-M Mirror Database owner(DBO): ctmfox2) DBO password: ######

Mirror database (data portion) size: 80 MBSybase interface directory: /home/ctm600us/sybase

3) Mirror Sybase Host Name: jordan4) Mirror Sybase Port Number: 4100

Mirror Sybase server name: MIRROR5) CONTROL-M Mirror database name: FoxDb6) CONTROL-M Mirror database data device name: FoxDb_data7) CONTROL-M Mirror database log device name: FoxDb_log8) Data Physical Device Path Name: /home1/syb12/FoxDb/FoxDb_data.dat9) Log Physical Device Path Name: /home1/syb12/FoxDb/FoxDb_log.dat



Step 7 The following options are available on these screens:



Verify that the Mirroring Parameters match the port, host, and database values of the target mirror database server. Modify the values as necessary. Table 7-4 describes the parameters. Parameter values must conform to Sybase naming conventions.

If mirroring has already been implemented, the parameter values shown generally reflect the settings of the existing mirror database server. However, some parameters may have been changed since the last database initialization.

Continue with Step 10 on page 7-23.

Option Description

aor a specific number

Prompts you for a new value for a parameter.

To modify all parameters enter a. You will be prompted for a value for each parameter in the current parameter page. For more information about these parameters, see Chapter 5, “Customization Parameters.”

b Continues with Step 10, copying or building the database.

q Quits the initialization procedure. You can restart the initialization at a later time from the CONTROL-M Main Menu. Modifications you have made may not be saved.

Table 7-4 Sybase Mirroring Parameters (Part 1 of 2)


CONTROL-M Mirror Database Owner

Name of the CONTROL-M Mirror database owner. This name is used by CONTROL-M when accessing the mirror database.When building a new mirror database, the initialization script creates this user on the database server.When copying to an existing database, this user must already be defined on the database server.

DBO Password Password for the CONTROL-M Mirror database owner (6 to 30 characters, alphanumeric). The characters you enter are not echoed for security reasons. This password is used by CONTROL-M processes and utilities to access the mirror database.



Mirror Database (Data Portion) Size

Amount of space (in MB) to allocate for the data portion of the CONTROL-M Mirror database.This value is taken from the current size of the primary database. It cannot be modified. Verify that the secondary database server can host a database of this size.

Sybase Interface Directory

Full path to the Sybase interfaces file on the primary system. This value is displayed, but cannot be modified.

Mirror Sybase Host Name

Name of the host computer for the mirror Sybase Database server.

Mirror Sybase Port Number

The communications port on which the secondary database server listens for queries.

Mirror Sybase Server Name

Name of the mirror database server. This entry is automatically added to the primary database’s interfaces file. This value is displayed, but cannot be modified.

CONTROL-M Mirror Database Name

Name for the CONTROL-M Mirror database. This name must be unique.When building a new mirror database, the initialization script creates this user on the database server.When copying to an existing database, this user must already be defined on the database server.

CONTROL-M Mirror Database Data Device Name

Name of the Sybase device on which the CONTROL-M Mirror database will be created.

CONTROL-M Mirror Database Log Device Name

Name of the Sybase device on which the CONTROL-M Mirror database log will be created.

Data Physical Device Path Name

Full path or physical device name where the mirror database will be located on the secondary database server. Specifying a pathname initiates a File-based installation. Specifying a device name initiates an installation to a Raw partition.

Log Physical Device Path Name

Full path or physical device name where the mirror database’s log database will be located on the secondary database server. Specifying a pathname initiates a File-based installation. Specifying a device name initiates an installation to a Raw partition.

Table 7-4 Sybase Mirroring Parameters (Part 2 of 2)




Step 8 The Mirroring Parameters screen is displayed.

If you selected the copy option, Figure 7-5 shows the Mirroring Parameters screen for Oracle Database Servers.

Figure 7-5 Mirroring Parameters for Database Copying - Oracle


1) CONTROL-M Mirror Database Owner(DBO): ctrlm2) DBO Password: #####3) Mirror Oracle Host Name:4) Mirror Oracle Port Number:5) Mirror Oracle Instance name (SID):



If you selected the build option, additional parameters are displayed as in Figure 7-6.

Figure 7-6 Mirroring Parameters for Database Build/Rebuild - Oracle


1) CONTROL-M Mirror Database Owner(DBO): ctrlm2) DBO Password: #####3) Mirror Oracle Host Name:4) Mirror Oracle Port Number:5) Mirror Oracle Instance name (SID):6) CONTROL-M Mirror tablespace name: ctrlm



Step 9 The following options are available on these screens:



Verify that the Mirroring Parameters match the port, host, and database values of the target mirror database server. Modify the values as necessary. Parameters are described in Table 7-5. Parameter values must conform to Oracle naming conventions.

If mirroring has already been implemented, the parameter values shown generally reflect the settings of the existing mirror database server. However, some parameters may have been changed since the last database initialization.

Option Description

aor a specific number

Prompts you for a new value for a parameter.

To modify all parameters enter a. You will be prompted for a value for each parameter in the current parameter page. For more information about these parameters, see Chapter 5, “Customization Parameters.”

b Continues with Step 10, copying or building the database.

q Quits the initialization procedure. You can restart the initialization at a later time from the CONTROL-M Main Menu. Modifications you have made may not be saved.

Table 7-5 Oracle Mirroring Parameters (Part 1 of 2)


CONTROL-M Mirror Database Owner

Name of the CONTROL-M Mirror database owner. This name is used by CONTROL-M when accessing the mirror database.When building a new mirror database, the initialization script creates this user on the database server.When copying to an existing database, this user must already be defined on the database server.

Database Owner Password

Password for the CONTROL-M database user. The characters you enter are not echoed for security reasons. This password is used by CONTROL-M processes and utilities to access the CONTROL-M database.

Mirror Oracle Host Name

The host machine name of an existing Oracle server.



Continue with Step 10.

Step 10 When you are satisfied with the values of all the parameters, specify b and press <Enter>.

• If you selected the copy option, the initialization process continues with Step 12.

• If you selected the build/rebuild option, the initialization process continues with Step 11.


Please confirm that you wish to build a new CONTROL-M Mirror database [y/n]:

Specify y to start building the CONTROL-M mirror database.

The following messages are displayed during the process:

+----------------------------------------------+| CONTROL-M Database Mirroring Customization |+----------------------------------------------+

Working...Building CONTROL-M database ...Building the CONTROL-M database requires the System Administrator’s password.Do you wish to continue? [y]: y

Mirror Oracle Port Number

Oracle utilizes this TCP/IP port for communication between CONTROL-M/Server and Oracle Database Server. The port must be dedicated to this purpose.

Mirror Orcale Instance Name (SID)

The name of the Oracle Database Server.To find out this name use the following command on the mirror database server:echo $ ORACLE_SID

Tablespace name Name of a defined tablespace on the database server that will be used by the mirror database.

Table 7-5 Oracle Mirroring Parameters (Part 2 of 2)




Specify y or press <Enter> to continue. The following prompt is displayed:

Please enter mirror database administrator’s password:

Specify the requested password. The following message is displayed:

For Sybase Database Servers:

This procedure creates new devices on the following physical files:/home/sybase/<data_file>.dat/home/sybase/<log_file>.datcopying database contents.......

During the copy/rebuild process, messages may appear if server settings do not match recommended settings for database operation. For example:

Locks (sp_configure) is less than 30000 for CONTROL-M database of 50 Mb size.Please modify the above resource(s) before starting CONTROL-M.Press <Return> to continue.

Note the system parameters that need to be changed, then press <Enter> to complete the copy/rebuild procedure. You will need to manually change these system settings after the copy/build procedure.

The initialization process continues with Step 13.

For Oracle Database Servers:

If the database you wish to build does not exist on the secondary database server, the following message is displayed:

ATTENTION !!!The data tablespace file location is on the Server Host Machine

Enter the data tablespace file name with full path:/home/ctm600uo/oracle/oradata/hurr224uo.dbf

Enter the full path and name of the tablespace file, or press <Enter> to accept the default path and file . The filename must conform to Oracle naming conventions.

The following messages are displayed:

Creating CONTROL-M/Server database schema...copying database contents.......



The initialization process continues with Step 13.


Please confirm that you wish to copy the contents of CONTROL-M primary database to CONTROL-M Mirror database [y/n] :y



Specify y or press <Enter> to continue. The following message is displayed:

+-----------------------------------------------+ | CONTROL-M Database Mirroring Customization | +-----------------------------------------------+

Working...copying database contents......................................

Step 13 The following message is displayed:

In order to complete this procedure after exiting the menu, please execute ‘source ~/.cshrc’ command.

CONTROL-M Database Mirroring initialization completed successfully

Press Enter to continue

Press <Enter> to return to the CONTROL-M Main Menu.

This marks the conclusion of the procedure to build the CONTROL-M mirror database and initialize mirroring. From now on, any changes CONTROL-M/Server makes to the primary database are copied to the mirror database.

Step 14 Exit the current session and start a new login session, or specify the command source ~/.cshrc to reset user environment variables in the current window.

Step 15 Restart CONTROL-M/Server.



Initializing the Failover Server

Step 1 Install the secondary CONTROL-M/Server on the secondary computer. Verify the configuration requirements listed in “Preparing a Failover Server” on page 7-12.

Step 2 Verify that the secondary CONTROL-M database conforms to the requirements for the mirror database as described in:

• “Preparing a CONTROL-M Mirror Database on a Sybase Server” on page 7-4 for a Sybase SQL Server

• “Preparing a CONTROL-M Mirror Database on an Oracle Server” on page 7-7 for an Oracle SQL Server

Step 3 Duplicate all communications links to Agent platforms and ENTERPRISE/CS workstations that are configured on the primary CONTROL-M/Server platform. Enter the mirror environment’s host computer in each Agent’s list of authorized servers (see Chapter 1, “Authorized CONTROL-M Servers File”), and in the ENTERPRISE/CS Data Center window.

Step 4 Verify that:

• Both primary and secondary installations of CONTROL-M/Server are shut down.

• Both the primary and mirror database servers are running.

Step 5 Log in to the secondary platform as the CONTROL-M/Server owner.

Step 6 Specify the ctm_menu command to open the CONTROL-M Main Menu. Type 4 to select Database Mirroring and press <Enter>. From the Database Mirroring menu, type 6 to select Initialize Failover and press <Enter>.




CONTROL-M failover initialization completed successfully.


Press <Enter> to return to the Database Mirroring menu. Then type q and press <Enter> to exit the Main Menu.

Step 8 Continue with Step 3 of “Initializing the Mirror Database - Copy/Build” on page 7-16. When you restart CONTROL-M/Server on the primary platform, CONTROL-M/Server on the failover server remains down until it is needed.



Recovering from Database Failure (Mirror Database)

If database mirroring has been implemented and the primary database fails, two options exist for restoring CONTROL-M/Server operation:

• Operate CONTROL-M/Server using the mirror database instead of the primary database. The primary CONTROL-M database can be rebuilt at a later stage.

This method resumes CONTROL-M/Server operation in the minimum time possible. However, mirroring cannot be reactivated until after the primary database is rebuilt.

To implement this option, follow the procedure “Operating CONTROL-M/Server with the Mirror Database” on page 7-30.

When the primary database is stable, restore normal operation using the procedure “Restoring the Primary Database and Initializing Mirroring” on page 7-31.

• Restore the CONTROL-M primary database from the mirror database and start CONTROL-M/Server again.

This method allows the CONTROL-M database to continue to operate with mirroring. However, you will not be able to start CONTROL-M/Server until you have completed restoring the CONTROL-M database - and this can result in significant downtime.

To implement this option, follow the procedure “Restoring the Primary Database and Initializing Mirroring” on page 7-31 to rebuild the primary database and resume normal operation.



Operating CONTROL-M/Server with the Mirror Database

Step 1 Verify that the primary CONTROL-M/Server is not running. Log in to the primary platform as the CONTROL-M/Server owner.

Step 2 Specify the ctm_menu command to open the CONTROL-M Main Menu. Type 4 to select Database Mirroring and press <Enter>. From the Database Mirroring menu, type 4 to select Use Mirror Database and press <Enter>.


Please confirm that you wish to use the Mirror Database INSTEAD of the Main Control-M database [y/n]:

Type y and press <Enter>. The following message is displayed:

In order to complete this procedure after exiting the menu, please execute ’source ~/.cshrc’ command.


Step 5 Restart CONTROL-M/Server on the primary platform. CONTROL-M/Server uses the Mirror Database instead of the primary database.

NoteThis is intended as a temporary solution to restore CONTROL-M/Server operation as quickly as possible. At the first opportunity, the primary database should be restored and CONTROL-M/Server should be re-configured to use the primary database.



Restoring the Primary Database and Initializing Mirroring

Step 1 Log in to the primary platform as the CONTROL-M/Server owner. Verify that CONTROL-M/Server is not running.

Step 2 Specify the ctm_menu command to open the CONTROL-M Main Menu. Type 4 to select Database Mirroring and press <Enter>. From the Database Mirroring menu, type 5 to select Restore CONTROL-M Database from Mirror and press <Enter>.


Restore Database from Mirror [N]:y

Type y and press <Enter> to restore the database.


Warning: Attempt to restore primary CONTROL-M database without rebuilding it.Please confirm that this is your intention [y/n]:y

Type y and press <Enter>.

Step 5 The following messages are displayed:

For Oracle databases:

Oracle is up and runnning ...

For both Oracle and Sybase databases:

...........................................................In order to complete this procedure after exiting the menu, please execute ’source ~/.cshrc’ command


Press <Enter> to return to the Database Mirroring menu.




Step 7 Continue with Step 3 of “Initializing the Mirror Database - Copy/Build” on page 7-16.

Before restarting CONTROL-M/Server, remember to exit the current session and start a new login session, or specify the command source ~/.cshrc to reset user environment variables in the current window.



Recovering from Primary CONTROL-M/Server Failure (Server Failover)

These procedures assume that a failover server has already been installed and initialized on a secondary platform. Two procedures are used during failover situations:

• When the primary CONTROL-M/Server fails, use the procedure “Failover to the Secondary CONTROL-M/Server” on page 7-33 to activate the secondary CONTROL-M/Server.

• After the primary CONTROL-M/Server has been stabilized, use the procedure “Restoring the Primary CONTROL-M/Server” on page 7-34 to restore normal function.

Failover to the Secondary CONTROL-M/Server

Step 1 Verify that:

• Both primary and secondary CONTROL-M/Server installations are not running.

• Both the primary and mirror database servers are running.

Step 2 Log in to the secondary platform as the CONTROL-M/Server owner.

Step 3 Specify the ctm_menu command to open the CONTROL-M Main Menu. Type 4 to select Database Mirroring and press <Enter>. From the Database Mirroring menu, type 7 to select Start Failover and press <Enter>.

WarningDo not start the secondary CONTROL-M/Server while the primary CONTROL-M/Server is running, or before the Start Failover procedure finishes executing. If the secondary CONTROL-M/Server is started too early, the following message is displayed:

** Unable to start CONTROL-M due to path specified for PROCLIB directory $PROCLIB. This path is invalid **




This operation disables CONTROL-M database mirroring,and starts FailOver CONTROL-M !!!

Confirm that CONTROL-M in the primary data center is not running.

Continue [y/n] :

Type y and press <Enter> to continue with failover.


Failover started successfully



Step 6 From the Database Mirroring menu, specify q to return to the CONTROL-M Main Menu.

Step 7 From the CONTROL-M Main Menu, type 1 to select CONTROL-M Manager. Then select the Start CONTROL-M/Server option. This starts CONTROL-M/Server on the failover server, using the mirror database. Database mirroring is disabled.

Step 8 In the ENTERPRISE/CS Data Centers window, modify the parameters TCP/IP Host Name and TCP/IP Port Number to the values appropriate to the secondary CONTROL-M/Server.

NoteAt the first opportunity, the primary CONTROL-M/Server environment should be returned to operational status. The primary database should be restored and CONTROL-M/Server should be restarted on the primary environment.

Restoring the Primary CONTROL-M/Server

Step 1 Log in to the secondary platform as the CONTROL-M/Server owner. Shut down CONTROL-M/Server.

Step 2 Specify the ctm_menu command to open the CONTROL-M Main Menu. Type 4 to select Database Mirroring and press <Enter>. From



the Database Mirroring menu, type 8 to select Stop Failover and press <Enter>.


This procedure stops FailOver CONTROL-MContinue [y/n] :y

Type y and press <Enter> to continue.


Failover Stopped



Step 5 Continue with “Restoring the Primary Database and Initializing Mirroring” on page 7-31.

Step 6 Continue with Step 3 of “Initializing the Mirror Database - Copy/Build” on page 7-16. In Step 15 of that procedure, start the primary CONTROL-M/Server.

Step 7 In the ENTERPRISE/CS Data Centers window, modify parameters TCP/IP Host Name and TCP/IP Port Number to values appropriate for the primary CONTROL-M/Server.

Synchronizing the Primary and Mirror Databases

When database mirroring is enabled, all database updates from CONTROL-M/Server are sent simultaneously to both the primary and mirror CONTROL-M database. However, if a CONTROL-M/Server administrative utility modifies the primary database, the mirror database will not automatically reflect these changes. Either the same or a similar utility must be run against the mirror database, or the mirror database must be re-initialized as described in “Initializing the Mirror Database - Copy/Build” on page 7-16.



The following table lists CONTROL-M/Server utilities that affect the primary database. Also included is the action to perform to get the mirror database in sync. For more information about these utilities, see Chapter 2, “Utilities.”

Table 7-6 Utilities Affecting the Primary Database

ctm_menu Option Database Utility Action

Database Creation Menu

Build Database All make_db Initialize Mirroring

Delete Database All Initialize Mirroring

Erase Database All ctm_clean_db Initialize Mirroring

Database Maintenance Menu

Restore Database All ctmdbrst Initialize Mirroring

Add Backup Devices Sybase addumpdev No action necessary

Delete Backup Devices Sybase deldumpdev No action necessary

Extend Database Size All ctm_db_extend Initialize mirroring


Sybase ctm_tempdb_extend Either run the utility on the backup Server platform or see your Systems Administrator.

Extend Temp Tablespace Size

Oracle ctm_tempdb_extend Either run the utility on the backup Server platform or see your Systems Administrator.

Extend Rollback Tablespace Size

Oracle ctm_rollback_extend Either run the utility on the backup Server platform or see your Systems Administrator.

Extend Database Log Size Sybase ctm_logdb_extend Either run the utility on the backup Server platform or see your Systems Administrator.

Troubleshooting Menu

Truncate Database Log Sybase ctm_cleanlog Either run the utility on the backup Server platform or see your Systems Administrator.



Restart New Day Procedure All reset_gd Initialize Mirroring.

Reset CONTROL-M Active Environment

All clean_ajf Clears all components of the CONTROL-M active environment (Active Jobs file, prerequisite conditions, and so on) and forces CONTROL-M to start a download of the entire Active Jobs file to ENTERPRISE/CS.

Table 7-6 Utilities Affecting the Primary Database

ctm_menu Option Database Utility Action


Messages and Codes A-1

A

Messages and Codes A

The messages described in this appendix are displayed on the Server-platform and/or recorded in the CONTROL-M log. Each CONTROL-M/Server message is preceded by a two character code identifying the Server process that generated the message. Each ENTERPRISE/CS message is preceded by the code CTM.

Example

TR5103 COMSTAT=OK. STATUS CHANGED TO OK

Table A-1 Message Prefixes

Code Server Process

SU Supervisor

TR Tracker

SL Selector and submittor

NS Communication with Agent platforms

CO Communication gateway

CD New Day procedure, downloads, updates to CONTROL-M database

CS Communication (user requests from ENTERPRISE/CS)

LG Utilities invoked from Agent platforms

WD Watchdog process

CTM Enterprise Controlstation


A-2 CONTROL-M/Server for Unix Administrator Guide

Messages

5000 CONTROL-M IS NOW INACTIVE

Explanation: All CONTROL-M processes have been terminated.

5001 FORCING <process_ID> OUT

Explanation: The CONTROL-M supervisor process is about to force a CONTROL-M process to stop. An attempt to perform an orderly termination of a CONTROL-M process failed. The process is being stopped.

System Action: The CONTROL-M process is stopped.

5002 PROCESS <process_ID> IS RUNNING

Explanation: CONTROL-M process <process_ID> (Tracker, Submittor, and so forth) has been successfully activated.

5003 MAXRETRY REACHED FOR <process_ID>. SUPERVISOR IS SHUTTING DOWN

Explanation: CONTROL-M is shutting down. The supervisor tried to activate CONTROL-M process <process_ID> (Tracker, Submittor, and so forth) the number of times specified in the CONTROL-M system parameter MAXRETRY, and failed.

User Response: Restart CONTROL-M. If the problem persists, notify your BMC Software technical support representative.

5004 RUNNING NEW DAY PROCEDURE

Explanation: The New Day procedure is executing.

System Action: While this process is executing, all other CONTROL-M processes are suspended.

5005 NEW DAY PROCEDURE TERMINATED

Explanation: The New Day procedure has terminated successfully.

System Action: Operation of all other CONTROL-M processes resumes.



5006 CONTROL-M LOG CLEANUP ENDED. DAYS=<days>

Explanation: This information message indicates that the New Day procedure has performed a partial cleanup of the CONTROL-M log. Data for the specified number of days is retained, as determined by the value assigned to the CONTROL-M system parameter Maximum Days Retained by CONTROL-M Log.

System Action: New Day processing continues.

5007 STATISTICS INFORMATION CLEANUP ENDED

Explanation: This information message indicates that the New Day procedure has performed a partial cleanup of CONTROL-M job statistics. When the CONTROL-M system parameter Statistics is set to Y, CONTROL-M retains statistical data regarding the last 20 executions of each job. Older data is deleted by the New Day procedure.


5008 PREREQUISITE CONDITIONS WITH DATEREF <mmdd> CLEANUP ENDED

Explanation: This information message indicates that the New Day procedure has performed a partial cleanup of prerequisite conditions. The New Day procedure deletes prerequisite conditions whose reference date is equal to the specified month and day (from the new CONTROL-M date).


5009 RESET CYCLIC FLAG TO NO

Explanation: This message indicates that the job is being modified to a non-cyclic job. A cyclic job that is executing at the time the New Day procedure is started is changed to a non-cyclic job. This is because CONTROL-M cannot determine what action to take regarding this job while it is executing.

System Action: The job completes its current cycle and is changed to a non-cyclic job.

User Response: If the job should continue executing as a cyclic job modify the job processing parameter Cyclic accordingly.



5010 MIRRORING HAS FAILED

Explanation: A failure of the mirroring SQL server has occurred. If you installed the database mirroring option for CONTROL-M, the instance of Sybase SQL server that handles the CONTROL-M mirror database must be running whenever CONTROL-M is running. This error message is displayed if the mirroring Sybase SQL Server fails. In this event, the mirror database is no long synchronized with the CONTROL-M database.

System Action: CONTROL-M continues operating normally. The mirror database is no longer updated.

User Response: You can allow CONTROL-M to continue operating without updating the mirror database. However, to restore the mirroring function, you must stop CONTROL-M normally and then rebuild the mirror database. (See “Security Authorization Menu” on page 4-29.)

5020 PROCESS STATE CHANGED FROM <old_state> TO <new_state>

Explanation: This information message indicates that a CONTROL-M process that was interrupted has restarted.

5030 ACTIVE JOBS FILE DOWNLOADED TO ENTERPRISE/CS {STARTED|ENDED}

Explanation: This information message indicates that the New Day procedure has completed and the Active Jobs file has started/ended downloading to the ENTERPRISE/CS workstation.

System Action: All other CONTROL-M processes that were suspended during the New Day procedure are resumed.

5040 NEW DAY PROCEDURE STARTED

Explanation: The New Day procedure has been submitted.

System Action: While this procedure is executing, all other CONTROL-M processes are suspended.



5041 ACTIVE JOBS FILE CLEANUP ENDED

Explanation: The New Day procedure has finished cleaning up the Active Jobs file. This message is issued by the New Day procedure just before it starts inserting new job orders into the Active Jobs file.

5042 NEW DAY PROCEDURE TERMINATED – DATES INCORRECT

Explanation: The New Day procedure cannot run due to a date inconsistency. The date inconsistency is due to one of the following causes:

• The New Day procedure has already run today.• The last running date of the New Day procedure is later than today's

date.

User Response: If the New Day procedure has already run today, no user action is required. If the last running date of the New Day procedure is later than today’s date, run the ctmudlst utility and modify the last running date.

5043 QUANTITATIVE RESOURCE INTEGRITY ERROR. <quantitative_resource> USED = <n1>, QRTAB = <n2>

Explanation: Due to an internal accounting problem, there is a discrepancy between the actual usage count (<n1>) of the specified Quantitative resource, and the calculated sum of the usage of this resource by all jobs (<n2>) in the Quantitative Resource table.

User Response: Hold all jobs using this resource and run the ecaqrtab utility to adjust the usage count in the table so that it matches the actual usage count.

5044 CONTROL RESOURCE <resource> INTEGRITY ERROR. USED=<n1>, CTLTAB=<n2>

Explanation: Due to an internal accounting problem, there is a discrepancy between actual usage count (<n1>) of the specified Control resource by all submitted and not-ended jobs (in Shared mode), and the calculated sum of the usage of this resource by all jobs (<n2>) in the Control Resource Database table.

User Response: Contact your BMC Software representative for assistance.



5045 CONTROL RESOURCE <resource_ID> INTEGRITY ERROR. MODE EXCLUSIVE, USED = <n>

Explanation: Due to an internal accounting problem, Control resource <resource_ID> appears to be used in exclusive mode by more than one job.

User Response: Allow the jobs using this resource to terminate. If the problem persists, notify your BMC Software technical support representative.

5046 CONTROL RESOURCE <resource_ID> INTEGRITY ERROR. MODE EXCLUSIVE, CTLTABCOUNT=<n>

Explanation: Due to an internal accounting problem, Control resource <resource_ID> appears in the Conditions/Resources table as being used in Exclusive mode by more than one job.

User Response: Allow the jobs using this resource to terminate. If the problem persists, notify your BMC Software technical support representative.

5047 MAXWAIT PARAMETER EXCEEDED

Explanation: The job was deleted from the Active Jobs file because it existed in the Active Jobs file without being submitted for more than the number of days specified in the MAXWAIT parameter.

User Response: Check the job’s pre-processing parameters.

5060 LAST RUN DATE OF USER <daily_ID> NONEXISTENT. STATUS = <status_text>

Explanation: The User Daily job was run for the first time. When a new User Daily job is run (that is, the User Daily job is run for the first time), the last run date is nonexistent and therefore cannot be accessed. No user action is required. At the end of this run (as at the end of all runs), a new last run date will automatically be generated.

5061 USER DAILY <daily_ID> STARTED

Explanation: This is the normal start message of User Daily job <daily_ID>.



5062 USER DAILY <daily_ID> ENDED

Explanation: This is the normal termination message of User Daily job <daily_ID>.

5063 CALENDAR <calendar_ID> NOT FOUND OR NOT COMPLETE

Explanation: The calendar referred to in the job processing definition (of the User Daily) could not be found, or does not contain all the relevant years.

System Action: The User Daily job cannot be run.

User Response: Use Enterprise Controlstation to either create the calendar or to verify that all relevant years appear in the calendar.

5064 USER DAILY <daily_ID> STOPPED – DATE PROBLEM. LAST <date1>, NEXT <date2>

Explanation: The specified User Daily job cannot run due to a date inconsistency. The inconsistent date can be due to one of the following:

• The User Daily job has already been run today.• The last running date of the User Daily job is later than today's date.

System Action: The User Daily job stops executing.

User Response: If the User Daily job has already been run today, no user action is required. If the last running date of the User Daily job is later than today’s date, run the ctmudlst utility (see Chapter 2, “Utilities”) to modify the last running date according to your requirements.

5065 ORDERED JOB: <job_ID>; DAILY <daily_ID>, ODATE <odate_spec>

Explanation: This information message indicates that Job <job_ID> with ODATE <odate_spec> has been inserted into the Active Jobs file by User Daily job <daily_ID>.



5070 USER HOME DIRECTORY IS NOT DEFINED

Explanation: The owner of the job does not have a home directory in the data center. No home directory is defined in the data center for the user specified in the job processing parameter Owner for this job.

System Action: The job is not submitted.

User Response: Define a home directory for the job owner; then rerun the job.



5080 FAILED TO SUBMIT JOB <job_name>. <reason>

Explanation: The requested job could not be submitted due to <reason>. The reasons include:

For UNIX Platforms:

• Mem Lib <mem_lib> does not exist – the path/library was not found.• Mem Name <mem_name> does not exist – the script was not found.• User <userr_name> does not exist – there was a security violation.• Owner <owner_name> does not exist – there was a security violation• Owner <owner_name> is not allowed to execute this script – there was

a security violation• The script <script_name> does not have execute permissions – there

was a security violation

For Windows NT Platforms:

• There are currently no logon servers available to service the logon request.

• Logon failure: unknown user name or bad password.• Logon failure: user account restriction.• Logon failure: account logon time restriction violation.• Logon failure: user not allowed to log on to this computer.• Logon failure: the specified account password has expired.• A specified privilege does not exist.• A required privilege is not held by the client.• The name provided is not a properly formed account name.• The specified user already exists.• The specified user does not exist.• Logon failure: the user has not been granted the requested logon type

at this computer.• A specified logon session does not exist. It may have been terminated.

For All Platforms:

• CONTROL-M/Server <host_name> is not authorized to run jobs on this agent – the CONTROL-M/Server specified is not listed in the Authorized CONTROL-M Servers file for the Agent platform.

System Action: The job is not submitted.

User Response: Examine the job processing definition to verify the information that caused the problem. Either make the necessary corrections, provide the necessary security authorizations, or add the Server platform to the Authorized CONTROL-M Servers List. Rerun the job.



5100 ENDED AT <time.> OSCOMPSTAT <return_code.> RUNCNT <rerun_counter>

Explanation: This information message indicates that the job ended its execution at the specified time with the given return code and the given run count of the job.

5101 STARTED ON <node_ID>

Explanation: This information message indicates that the job began executing on the specified Agent platform.

5102 DISAPPEARED AT <time>. RUNCNT <rerun_counter>

Explanation: A job cannot be found in the system. After the job was submitted, it could not be located by the system (that is, the job has disappeared). The job’s status, and the location of its log, cannot be determined. The job may have been stopped by a user, or the Agent platform on which the job was running may have been rebooted.

System Action: The job is assigned the completion status NOTOK.

User Response: Either rerun the job, or force the job if the job processing definition has changed since the last New Day procedure or User Daily job.

5103 <message _text>. STATUS CHANGED TO {OK|NOTOK}

Explanation: This information message indicates that after analyzing the job, CONTROL-M has changed the job’s status to either OK or NOTOK. The reason for the status change is indicated in the <message_text>:

• SYSOUT LOST The job’s sysout file cannot be located.

• DISAPPEARED The job that was executing cannot be located by CONTROL-M.

• COMSTAT=OK The job’s completion code indicated that the job ended OK.

• COMSTAT=NOTOK The job’s completion code indicated that the job ended not OK.



• DUMMY The job submitted is one of “dummy” format

• NOT SUBMIT Job Submission failed. This might have resulted from a Server/Agent communication problem.

5104 PID=<procID>, CPU:<cpu_time>, EL:<elapsed_time>, END:<end_time>

Explanation: A job terminated with the status OK. This statistical message is written to the sysout file when a job terminates with the status OK and the CONTROL-M system parameter Statistics has been set to Y.

5105 SUBMITTED AT <time> TO <node_ID>

Explanation: This information message indicates that the job was submitted for execution at the specified time to the specified Agent platform.

5106 DISAPPEARED AT <time>. RUNCNT <rerun_counter>. AGENT IS DISABLED

Explanation: CONTROL-M cannot track a job because a user changed the communication status of the Agent platform on which it was running to Disabled.

System Action: The job is assigned the completion status NOTOK.

User Response: Rerun the job or force the job on a different Agent platform.

5110 LIBMEMSYM FILE <pathname> NOT FOUND

Explanation: The file <pathname> that is specified in a %%LIBMEMSYM AutoEdit variable was not found. AutoEdit variable %%LIBMEMSYM can be used to refer to a list of AutoEdit assignments contained in a file in the data center. The file referred to in this instance was not found.

System Action: The job continues to execute.

User Response: Determine why the file was not found. Create the file or correct the pathname specified for the AutoEdit variable.



5120 JOB STATE CHANGED TO <state_text>

Explanation: This information message indicates that after analyzing the job, CONTROL-M has changed the job’s state to <state_text>.

5121 SYSOUT FILE COPIED TO <location>

Explanation: The sysout file of the specified job was copied to location <location>. This message is issued following a successful SYSOUT or DO SYSOUT copy operation.

System Action: The sysout file is copied to the specified location.

5122 SYSOUT FILE MOVED TO <location>

Explanation: The sysout file of the specified job was moved to location <location>. This message is issued following a successful SYSOUT or DO SYSOUT move operation.

System Action: The sysout file is moved to the specified location.

5123 SYSOUT FILE RELEASED

Explanation: The sysout file of the specified job was released to the print queue. This message is issued following a successful SYSOUT or DO SYSOUT release operation.

System Action: The sysout file is placed on the print queue.

5124 SYSOUT FILE DELETED

Explanation: The sysout file for the specified job was deleted. This message is issued following a successful SYSOUT or DO SYSOUT delete operation.



5125 SYSOUT FILE OPEN ERROR

Explanation: The sysout file for the specified job cannot be opened. Either the sysout file could not be found, or it is corrupt. Since the sysout file could not be opened, the job’s output cannot be analyzed.

System Action: The sysout file is not opened, the job is not analyzed, and the job fails.

User Response: Check if the file is missing, and rerun the job if applicable. If other information in the system indicates that the job has run successfully (for example, other output data, new files), use available maintenance utilities to adjust condition values to the state in which they would be if the job had been analyzed.

5126 SYSOUT FILE COPY TO <location> FAILED

Explanation: The sysout file for the specified job could not be copied.CONTROL-M was unable to perform the specified SYSOUT or DO SYSOUT copy action. Possible reasons are operating system security restrictions, or lack of disk space.

System Action: The sysout file is not copied.

User Response: Verify user authorization of CONTROL-M, examine operating system security information, and verify that there is enough disk space.

5127 SYSOUT FILE MOVE TO <location> FAILED

Explanation: The sysout file for the specified job could not be moved. CONTROL-M was unable to perform the SYSOUT or DO SYSOUT move action. Possible reasons are operating system security restrictions, or lack of disk space.

System Action: The sysout file is not moved.

User Response: Verify user authorization of CONTROL-M, examine operating system security information, and verify that there is enough disk space.



5128 SYSOUT FILE RELEASE FAILED

Explanation: The sysout file for the specified job could not be printed. CONTROL-M was unable to perform the SYSOUT or DO SYSOUT release-to-print action. Possible reasons are the print queue is stopped, closed or nonexistent.

System Action: The sysout file is not printed.

User Response: Try to correct the print queue problem. If you cannot, notify your ENTERPRISE/CS administrator.

5129 SYSOUT FILE DELETE FAILED

Explanation: The sysout file for the specified job could not be deleted. CONTROL-M was unable to perform the SYSOUT or DO SYSOUT delete action. Possible reasons are that the file does not exist, or that the user is not authorized to delete the file.

System Action: The sysout file is not deleted.

User Response: Check if the file actually exists. If it does, check the job owner’s authorization (both system and CONTROL-M authorization). If necessary, contact your ENTERPRISE/CS administrator.

5132 STATUS SET TO <job_status> AS A RESULT OF DO OK/NOTOK

Explanation: This information message indicates that the completion status of the job was changed as a result of Do OK or Do NOTOK post-processing actions.

5133 ENDED OK

Explanation: This information message indicates that the job has terminated with status OK. Following job execution and post-processing, CONTROL-M has analyzed the results and has assigned the completion status OK to the job.



5134 ENDED NOTOK

Explanation: The job has terminated with a final status of NOTOK. Following job execution and post-processing, CONTROL-M has analyzed the results, and assigned a final status of NOTOK to the job, indicating that a problem occurred during job processing.

User Response: Examine the job log (SYSOUT) to determine why the job terminated with a status of NOTOK.

5135 AUTHORIZATION PROBLEM – <problem_description>

Explanation: The job has terminated abnormally due to a security authorization problem. CONTROL-M attempted to execute a job contained in the Active Jobs file. The job failed to execute due to the security-related problem stated in <problem_description>.

System Action: The job is not executed.

User Response: Determine what authorization is lacking. Request that your CONTROL-M system administrator define the necessary authorization then rerun the job.

5136 JOB STATE CHANGED TO RETRY – SUBMIT

Explanation: This information message indicates that CONTROL-M attempted to submit the job to the Agent platform but it failed due to the Agent not responding. The job’s state was changed to Retry and the job was resubmitted.

5160 SYSOUT LOST. STATUS CHANGED TO NOTOK

Explanation: The job’s sysout file cannot be located. The sysout file is required to determine which post-processing actions, if any, are required for the job.

System Action: The job is assigned a completion status of NOTOK.

User Response: Determine what happened to the sysout. Once the cause of the problem has been corrected, resubmit the job.



5161 DISAPPEARED. STATUS CHANGED TO NOTOK

Explanation: The job that was executing cannot be located by CONTROL-M. Something occurred to the job while it was running that caused it to “disappear” from CONTROL-M’s control. A possible cause is that a user canceled the job directly and not via CONTROL-M.


User Response: Using the operating system’s process identification number, determine what happened to the job and act accordingly.

5162 COMPSTAT=OK. STATUS CHANGED TO OK

Explanation: This information message indicates that the job ended OK. CONTROL-M assigns the job a status of OK based on the job’s completion code.

5163 COMPSTAT=NOTOK. STATUS CHANGED TO NOTOK

Explanation: This information message indicates that the job ended not OK. CONTROL-M assigns the job a status of NOTOK based on the job’s completion code.

5164 DUMMY. STATUS CHANGED TO OK

Explanation: This information message indicates that the job was assigned a status of Ended OK because it is a dummy job.

5165 NOT SUBMITTED. STATUS CHANGED TO NOTOK

Explanation: Job Submission failed. This might have resulted from a Server/Agent communication problem.


User Response: Using the operating system’s process identification number, determine why the Job Submission failed and act accordingly.

5200 ORDER STATE CHANGED TO <state_text>

Explanation: This information message indicates that CONTROL-M has finished job post-processing, and changed the job's state to <state_text>.



5201 SHOUT TO <destination> PERFORMED

Explanation: This information message indicates that a Shout message was issued to the specified destination.

5202 SHOUT TO <destination> FAILED

Explanation: An attempt to issue a Shout message to the specified destination was not successful. Possible reasons for the failure are that the terminal is not connected, an invalid destination was specified, and so forth.

System Action: The Shout message is not issued.

User Response: Check the validity of the destination.

5203 CONTROL RESOURCE <resource_ID> RESERVED

Explanation: This information message indicates that Control resource <resource_ID> has been reserved for the specified critical job.

5204 CONTROL RESOURCE <resource_ID> ALLOCATED. MODE: <mode>

Explanation: This information message indicates that Control resource <resource_ID> has been allocated for the specified non-critical job in the indicated mode (Shared or Exclusive).

5205 RESERVED CONTROL RESOURCES ALLOCATED

Explanation: This information message indicates that all reserved Control resources for the specified critical job have been allocated successfully.

5206 CONTROL RESOURCES RELEASED

Explanation: This information message indicates that all Control resources allocated for the job order have now been released because the job has terminated.



5207 QUANTITATIVE RESOURCE <resource_ID> QUANTITY <resource_quantity> RESERVED

Explanation: This information message indicates that Quantitative resource <resource_ID> has been reserved in quantity <resource_quantity> for the specified critical job, and is ready to be allocated.

5208 QUANTITATIVE RESOURCE <resource_ID> QUANTITY <resource_quantity> ALLOCATED

Explanation: This information message indicates that quantity <resource_quantity> of Quantitative resource <resource_ID> has been allocated for a non-critical job.

5209 CONDITION <condition_ID> <date_ref> ADDED

Explanation: This information message indicates that following job termination, the specified condition has been added to the Conditions/Resources table.

5210 CONDITION <condition_ID> <date_ref> DELETED

Explanation: This information message indicates that following job termination, the specified condition (with the matching date reference) has been deleted from the Conditions table.

5211 FORCEJOB FAILURE. JOB <job_number>, TABLE <table_ID>

Explanation: A FORCEJOB operation for the specified job number in the specified table failed. Failure may have been due to problems with the job processing definition (for example, job not found), security verification problems, and so forth.

User Response: Verify the existence of the script file, and check CONTROL-M and operating system security restrictions.

5212 JOB <job_number>, TABLE <table_ID> FORCED

Explanation: This information message indicates that the FORCEJOB operation for the specified job/table has completed successfully.



5213 RESERVED QUANTITATIVE RESOURCES ALLOCATED

Explanation: This information message indicates that all reserved Quantitative resources for the specified critical job have been allocated.

5214 QUANTITATIVE RESOURCES RELEASED

Explanation: This information message indicates that all allocated Quantitative resources for the specified job have now been released.

5215 ALL RERUNS HAVE BEEN PERFORMED. MAXRERUN = <number>

Explanation: This information message indicates that all the reruns requested for the specified job have been performed.

5216 <shout_text>

Explanation: The Shout message <shout_text> was issued to the CONTROL-M log. The text in this message is issued by a Shout statement and is written to the CONTROL-M log.

5217 FORCE NOT PERFORMED: JOB <job_ID>, TABLE <table_ID> DOES NOT EXIST

Explanation: An attempt to force job <job_ID>, located in table <table_ID>, failed because the job/table does not exist. Either the table specified in <table_ID> does not exist, or the job specified in <job_ID> does not exist in the specified table.

An ENTERPRISE/CS user attempted to force a job via the Scheduling menu option in the Enterprise Controlstation window.

-or-

A CONTROL-M job attempted to execute a Do Forcejob statement as part of its Post-processing parameters.

System Action: No action is taken.

User Response: Determine the source of the problem (missing job processing definition, missing Scheduling table, incorrectly specified Do Forcejob statement, and so forth). Correct the problem and re-execute the Force.



5218 FORCE WAS NOT PERFORMED – TABLE <table_ID> DOES NOT EXIST

Explanation: An attempt to force Scheduling table <table_ID> failed because the table specified in <table_ID> does not exist.

An ENTERPRISE/CS user attempted to force a Scheduling table via the Scheduling menu option in the Enterprise Controlstation window.

-or-

A CONTROL-M job attempted to execute a Do Forcejob statement as part of its post-processing parameters.

System Action: No action is taken.

User Response: Determine the source of the problem (missing Scheduling table, incorrectly specified Do Forcejob statement, and so forth). Correct the problem and re-execute the Force.

5220 STATUS OF AGENT PLATFORM <node_ID> CHANGED TO AVAILABLE

Explanation: This information message indicates that CONTROL-M changed the communication status of the Agent platform identified by <node_ID> from Unavailable to Available. The communication status of the Agent platform had been changed from Available to Unavailable due to failed communication. As a result of resumed communication, the status of the Agent platform has been returned to Available.

System Action: CONTROL-M resumes sending job-handling requests to the Agent platform.

5221 STATUS OF AGENT PLATFORM <node_ID> CHANGED TO AVAILABLE BY USER

Explanation: This information message indicates that an authorized user changed the communication status of the Agent platform identified by <node_ID> from Disabled to Available. The communication status of the Agent platform had been previously changed to Disabled, either by a user or due to a communication failure.

System Action: CONTROL-M resumes sending job-handling requests to the Agent platform.



5222 STATUS OF AGENT PLATFORM <node_ID> CHANGED TO UNAVAILABLE

Explanation: CONTROL-M changed the communication status of the Agent platform identified by <node_ID> from Available to Unavailable due to repeated communication timeouts. A communication failure has occurred between the Server platform and the specified Agent platform.

-or-

<node_ID> was not specified correctly in the job processing definition or in the node group.

System Action: CONTROL-M tries to communicate with the Agent platform but does not send job-handling requests to the platform. If CONTROL-M succeeds to communicate with the Agent platform, the status of the platform will be returned to Available; otherwise, the status of the platform will be changed to Disabled.

User Response: Verify that the node ID specified in the job processing definition or in the node group is valid. Determine the cause of the failed communication and correct it.



5223 STATUS OF AGENT PLATFORM <node_ID> CHANGED TO DISABLED

Explanation: CONTROL-M changed the communication status of the Agent platform identified by <node_ID> from Unavailable to Disabled due to repeated communication timeouts.

A communication failure has occurred between the Server platform and the specified Agent platform.

-or-

The node ID was not specified correctly in the job processing definition or in the node group.

System Action: CONTROL-M no longer attempts to communicate with the Agent platform and does not send job-handling requests to the platform.

User Response: Verify that the node ID specified in the job processing definition or in the node group is valid. Determine the cause of the failed communication and correct it. After correcting the problem, use the Agent Status menu to change the status of the Agent platform to Available.

5224 STATUS OF AGENT PLATFORM <node_ID> CHANGED TO DISABLED BY USER

Explanation: An authorized user changed the communication status of the Agent platform identified by <node_ID> from Unavailable to Disabled.

System Action: CONTROL-M no longer attempts to communicate with the Agent platform and does not send job-handling requests to the platform.

User Response: When desired, use the utility to change the status of the Agent platform to Available.



5250 ACCESS TO TABLE <table_ID> IS NOT ALLOWED TO USER <user_ID>

Explanation: A User Daily job attempted to order a job from a table that it is unauthorized to access. This is a security violation.

System Action: Access to the scheduling table is denied to the User Daily job.

User Response: Verify/modify user authorizations pertaining to the specific scheduling table.

5251 THIS OWNER IS NOT AUTHORIZED TO EXECUTE THE JOB SCRIPT

Explanation: The owner of the job processing definition is not authorized to execute the script file specified by the job processing parameters.

System Action: The job terminates with a NOTOK status.

User Response: Either modify the script file protection accordingly, or grant the owner execution privileges.

5252 ENTERPRISE/CS USER <user_ID> NOT AUTHORIZED FOR OWNER <owner_ID>

Explanation: User <user_ID> tried to perform an unauthorized action on a job belonging to owner <owner_ID>. There are restrictions on the operations that users can perform on jobs belonging to other owners unless the user is authorized by the security administrator.

User Response: If you still want to perform the specified operation, contact your security manager for the required authorization.

5260 – 5330 See Appendix C, “Messages and Codes”, in the Enterprise Controlstation User Guide.

5351 QUANTITATIVE RESOURCE <resource_ID> QUANTITY <resource_quantity> DEFINED

Explanation: The user defined a new Quantitative resource, and its maximum quantity.

System Action: The resource is added to the CONTROL-M resource pool.



5352 QUANTITATIVE RESOURCE <resource_ID> DELETED

Explanation: This information message indicates that by user request, Quantitative resource <resource_ID> has been deleted from the CONTROL-M resource pool.

5353 QUANTITATIVE RESOURCE <resource_ID> QUANTITY INCREASED BY <resource_quantity>

Explanation: This information message indicates that by user request, the maximum quantity of Quantitative resource <resource_ID> has been increased by quantity <resource_quantity>. The use of Quantitative resources is discussed in Chapter 2 in the Enterprise Controlstation User Guide.

5354 QUANTITATIVE RESOURCE <resource_ID> QUANTITY DECREASED BY <resource_quantity>

Explanation: This information message indicates that by user request, the maximum quantity of Quantitative resource <resource_ID> has been decreased by quantity <resource_quantity>. The use of Quantitative resources is discussed in Chapter 2 in the Enterprise Controlstation User Guide.

5355 QUANTITATIVE RESOURCE <resource_ID> QUANTITY <resource_quantity> RELEASED

Explanation: This information message indicates that the number of units <resource_quantity> of Quantitative resource <resource_ID>, that were allocated by a job, have been released and are now available for other jobs that require this resource. The use of Quantitative resources is discussed in Chapter 2 in the Enterprise Controlstation User Guide.

5356 CONTROL RESOURCE <resource_ID> DEFINED

Explanation: This information message indicates that the user requested allocation of a Control resource that does not exist.

System Action: Control resource <resource_ID> is defined and allocated to the user.

5357 CONTROL RESOURCE <resource_ID> RELEASED

Explanation: This information message indicates that by ENTERPRISE/CS user request, Control resource <resource_ID> has been released.



5401 HELD BY USER <user_name>

Explanation: This information message indicates that the job associated with the message was held by the ENTERPRISE/CS user <user_name>.

5402 FREED BY USER <user_name>

Explanation: This information message indicates that the job associated with the message was released from its held state by the ENTERPRISE/CS user <user_name>.

5403 DELETED BY USER <user_name>

Explanation: This information message indicates that the job associated with the message was marked as deleted by the ENTERPRISE/CS user <user_name>.

5404 RERUN BY USER <user_name>

Explanation: This information message indicates that the job associated with the message was rerun by the ENTERPRISE/CS user <user_name>.

5405 CONFIRMED BY USER <user_name>

Explanation: This information message indicates that the job associated with the message, that was waiting for confirmation prior to submission, was confirmed by the ENTERPRISE/CS user <user_name>.

5406 CHANGED BY USER <user_ID>

Explanation: This information message indicates that the indicated ENTERPRISE/CS user changed a parameter of an active job.

5407 CREATED BY USER <user_name>

Explanation: This information message indicates that the job associated with the message was placed in the Active Jobs file by the ctmcreate utility.

5500 – 5599 See Appendix C, “Messages and Codes”, in the Enterprise Controlstation User Guide.


Structure of CONTROL-M Log Entries B-1

B

Structure of CONTROL-M Log EntriesB

The CONTROL-M log is part of the CONTROL-M database in each data center. For more information, see “CONTROL-M Log” on page 1-31.

Table B-1 Fields of the CONTROL-M Log

Field Description Characters

Logtime Message time 6

Logdate Message date 8

Subsystem CONTROL-M process that generated the message 2

Jobname Job name of the job that generated the message 10

Jobno. Job number (from job processing definition) 4 (integers)

Orderno Order number of the job 4 (integers)

Owner User name of job’s owner 30

Odate Original scheduling date of job 8

Msgid Message ID (messages are described in Appendix A) 4

Message Text of message 66

Tasktype Task Type identifier (for example, batch, detached, command) 2

Memname Member name 30


B-2 CONTROL-M/Server for Unix Administrator Guide


Glossary 1

Glossary

Glossary

Active Jobs File (AJF) The Active Jobs file lists all jobs scheduled for submission in the current day. Each job in the Active Jobs file is not submitted until all conditions contained in the job processing definition for the job are satisfied. The Active Jobs file is contained in the CONTROL-M database.

Agent Platform Platform on which CONTROL-M/Agent runs. The Agent platform handles requests from CONTROL-M/Server to execute jobs or provide information.

Calendar A collection of dates which are used by CONTROL-M/Server to schedule the ordering of jobs.

CONTROL-M Software product which schedules, submits, tracks and follows up the execution of jobs in a data center. CONTROL-M functions are divided between two separate components: CONTROL-M/Server and CONTROL-M/Agent.

CONTROL-M (Primary) Database

Repository of operational data relating to the functioning of the CONTROL-M data center. Contents of the database include the Active Jobs file, Scheduling tables (job processing definitions) and the Resources/Conditions table. The database is maintained by CONTROL-M/Server, using Sybase SQL Server.

CONTROL-M Date Date used by CONTROL-M to assign the Scheduling date (Odate) to jobs.


2 CONTROL-M/Server for Unix Administrator Guide

CONTROL-M Log Log containing a complete audit trail of every significant event occurring in the CONTROL-M production environment.

CONTROL-M Platform Platform on which CONTROL-M/Server runs.

CONTROL-M/Agent The component of CONTROL-M which runs on each Agent platform. CONTROL-M/Agent submits jobs and performs other tasks based on requests from CONTROL-M/Server, and performs post-processing analysis of completed jobs.

CONTROL-M/Server The component of CONTROL-M which runs on the Server platform. CONTROL-M/Server maintains the CONTROL-M database (including the Active Jobs file), schedules jobs, performs load balancing, sends job-handling requests to Agent platforms, and handles requests from ENTERPRISE/CS.

Conditions/Resources Table

A component of the CONTROL-M database which lists the current status of all prerequisite conditions, Control resources and Quantitative resources in the data center.

Control Resource User-defined variable representing a physical or logical resource in the data center. For each job, the user specifies whether the job requires exclusive or shared access to the resource. CONTROL-M/Server verifies that a job is not submitted for execution unless the Control resources required by the job are available in the required state (shared/exclusive). This prevents deadlock situations or contention between jobs for a given resource. Control resources are recorded in the Conditions/Resources table.

Data Center (or CONTROL-M Data Center)

A Server platform and all the Agent platforms that it handles.

Download (of active environment)

Transmission of the Active Jobs file and other elements of the CONTROL-M database to the ENTERPRISE/CS database. This allows ENTERPRISE/CS to provide the user with a graphical display of the current situation in the data center. Download occurs upon completion of the New Day procedure, after which updates are issued to maintain the accuracy of the graphical display.


Glossary 3

Enterprise Controlstation or ENTERPRISE/CS

Software product that provides a central point of control for CONTROL-M data centers. ENTERPRISE/CS provides the GUI which allows users to graphically view the status of job schedules and execution in data centers, to issue requests for additional information and to handle problems. ENTERPRISE/CS also passes global conditions among data centers.

Force To “force” a job is to instruct CONTROL-M/Server to place the job in the Active Jobs file for possible submission, regardless of the scheduling parameters contained in the job processing definition for the job. See also “Order”.

Gateway The process that handles communication between CONTROL-M/Server and ENTERPRISE/CS. There are gateway processes on both the Server platform and the ENTERPRISE/CS workstation.

General Daily Procedure

See “New Day Procedure”.

Global Condition A prerequisite condition that is passed between data centers via ENTERPRISE/CS. Global conditions allow jobs in one data center to be dependent on completion of a job in another data center.

Heartbeat Monitor Special monitor which verifies that TCP/IP communication with ENTERPRISE/CS is functional.

Job Processing Definition

Set of user-defined parameters for each job which provide CONTROL-M with detailed instructions for processing the job. Job processing definitions are organized into Scheduling tables.

Load Balancing CONTROL-M mechanism for maximizing throughput of production jobs by automatic selection of the platform to execute each job, based on workload considerations.



Manual Conditions File

The Manual Conditions file contains prerequisite conditions which are required by jobs in the Active Jobs file but which will not be available (that is, added to the Conditions/Resources table) unless there is some form of manual intervention. These conditions include conditions which are never added automatically by scheduled jobs because manual confirmation is always desired, as well as conditions which are normally added automatically, but the jobs which add them are not scheduled for the day.

Mirror Database A backup copy of the CONTROL-M database which is constantly updated. The Mirror database allows CONTROL-M/Server to resume functioning with minimal time loss in the event of a primary database failure.

New Day Procedure Formerly “General Daily Procedure”. Daily scheduling and housekeeping procedures which run on the Server platform. The CONTROL-M date is advanced to the next day when this procedure runs.

Node Group A user-defined collection of Node IDs. A node group is specified in a Job Processing definition to indicate a group of Agent platforms from which CONTROL-M/Server can select a platform to execute the job.

Node ID Name by which an Agent platform is identified to the Server platform. This is generally the Agent platform’s host name.

Odate (Original Scheduling Date)

Jobs managed by CONTROL-M are assigned a date when they are ordered (placed in the Active Jobs file). This date, referred to as the Odate, is the CONTROL-M date at the time the job is ordered and represents the date on which the job should be submitted for execution. Odate is also the default date assigned to prerequisite conditions at the time they are created. The variable ODAT (representing the Odate) is used when defining job dependencies to insure that a job waiting for completion of another job is only triggered by a job with the same working date.


Glossary 5

Order To “order” a job is to request that CONTROL-M/Server review the scheduling parameters contained in the job processing definition for the job and, if the parameters are satisfied, place the job in the Active Jobs file for possible submission. See also “Force”.

Prerequisite Conditions or Conditions

A flag representing a user-specified situation or condition. Submission of a job for execution can be made dependent on the existence of one or more prerequisite conditions. Prerequisite conditions are recorded in the Conditions/Resources table.

Quantitative Resource User-defined variable representing a resource in the data center. The user defines the total quantity of this resource in the data center and, for each job, the quantity require/used by that job. CONTROL-M/Server verifies that a job is not submitted for execution unless the Quantitative resources required by the job are available. Quantitative resources are recorded in the Conditions/Resources table.

Scheduling Table A collection of related job processing definitions. Scheduling tables are stored in the CONTROL-M database (and duplicated in the ENTERPRISE/CS database). Scheduling tables are “ordered” by the New Day procedure or User Daily jobs.

Server Platform Platform on which CONTROL-M/Server runs. The Server platform communicates with the ENTERPRISE/CS workstation and with the Agent platforms.

Sleep Time The length of time that a CONTROL-M/Server process lies dormant before “waking up” to determine if any request to perform an action was received. The value assigned to Sleep Time affects CONTROL-M/Server throughput and the load on the Server platform’s resources.

Sybase SQL Server Software product used by CONTROL-M/Server to maintain the CONTROL-M database. The database can be maintained using either a dedicated instance of Sybase SQL Server (provided with CONTROL-M) or an existing instance of Sybase SQL Server (provided by the user).



User Daily Job User-defined job which can be used to automate the ordering of production jobs.

User Exits Mechanism which enables users to modify CONTROL-M operations to suit site needs.

Watchdog Process Mechanism which automatically monitors CONTROL-M processes and resources


Index 1

Index

Index

Aaccount parameter

SAP (ctmcreate) 2-33SAP (ctmdefine) 2-58

ACTION parameterctmudchk utility 2-145ctmvar utility 2-151

Active Jobs filead hoc jobs 2-25ctmpsm utility 2-107, 2-109downloading 4-42, 4-48erasing contents 4-48forcing download 4-42listing job details 2-107New Day procedure 1-13options 2-108security 3-5, 3-24

Active shout tablesystem parameter 5-5

ad hoc jobscreating 2-25

Add Backup Device optionDatabase Maintenance menu 4-19

addingbackup devices 4-19groups 3-18prerequisite conditions 2-21

users 3-13AG_PORT_NUM

agent parameter 5-28agconfig.dat file

description 5-22Agent communication parameters

defaults 4-34description 5-13modifying 4-35

Agent platformdeleting 2-15status 2-15

Agent platformscommunication parameters 5-13communication status 1-6, 2-103, 4-38,

A-11configuration information 2-103ctmping utility 2-103definition 1-2disabled A-22identification 1-6Shout messages to 2-138

Agent Status menudescription 4-38

AGENT_DIRagent parameter 5-28

Agent-to-Serverport number 5-10



ALARM_DESTserver parameter 5-23

application security 3-1appname parameter

Oracle Applications (ctmcreate) 2-34Oracle Applications (ctmdefine) 2-60

Archive Mode optionDatabase Maintenance menu 4-13

archive_info parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-58

archive_object parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-58

archive_sapobject parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-58

arp commandIP address locator 5-11

asap parameterSAP jobs (ctmcreate) 2-33SAP jobs (ctmdefine) 2-58

ASCII filesctm_restore_bcp utility 2-19ctmexdef utility 2-64

authorization. See securityAuthorization menu, Security 4-29Authorized CONTROL-M/Servers file

host names 1-12overview 1-9, 1-12usage A-9

AutoEdit variablesctmstvar utility 2-133ctmvar utility 2-150quote marks 2-29, 2-52, 2-76, 2-133

AUTOEDIT_INC_ SEC parameter 5-23Available status

agent platform 1-7

Bbacking up

CONTROL-M database 2-37backup

Oracle 4-14Sybase 4-14

Backup Databaseoption

Database Maintenance menu 4-14Backup Socket port number

Sybase 5-16batch mode

Security Maintenance utility 3-32binary files

ctmdbrst utility 2-17, 2-19

CCDROM name

Oracle parameter 5-18character set

Sybase SQL server 7-6Check Database option

Database Maintenance menu 4-26Check Kernel Configuration parameter 4-41checking

free disk space 2-62User Daily jobs 2-145waiting jobs 2-154

CHILD modectmpsm utility 2-113

cleanup. See maintenanceclosing. See stoppingCMN_PRM_CD_IPC_IN

communication parameter 5-26CMN_PRM_CD_IPC_OUT

communication parameter 5-26


Index 3

CMN_PRM_CD_MAX_DBUcommunication parameter 5-26

CMN_PRM_CD_MAX_SERVICEcommunication parameter 5-26

Cold backuparchive mode 4-13

COMM_TRACEagent parameter 5-28server parameter 5-28

communicationsee also interactionagent parameters 4-34agent platforms 5-13Available status 1-7ctmping utility 2-103defaults for parameters 4-34Diagnostic report 4-42Disabled status 1-7interruptions 1-8parameter defaults 4-34parameter descriptions 5-9parameter modification 4-32, 4-35status 1-6, 2-103, 4-38, A-11Timeout parameter 5-14Unavailable status 1-7

Communication protocol parameterdescription 5-10version 5-14

Computer systemsystem parameter 5-3

COMTIMOUTagent parameter 5-28

COMTRYNOserver parameter 5-28

Condition Date parameterctmcontb utility 2-21

Condition Name parameterctmcontb utility 2-21

conditions. See prerequisite conditionsConditions file, Manual 2-82

config.dat fileEvent logger configuration 1-40parameters 5-21user exit parameters 6-3watchdog parameters 5-31

configurationCONTROL-M/Agent 1-12

Configuration parameter, Check Kernel 4-41configuration parameters

agconfig.dat file 5-22, 5-28description 5-22Watchdog parameters 5-31

Control resourcesdeleting 4-48listing 2-157reserved A-17

CONTROL-Madministrator 1-36Authorized Servers file 1-9failover planning 1-10log B-1main menu 4-6maintenance 4-3menu system 4-6sample job flow 1-2security facility 3-1, 3-7



CONTROL-M databasebacking up 2-37, 4-14checking data usage 2-45checking integrity 2-39, 4-4creation menu 4-10defining jobs 2-47extending 4-21maintenance 4-4Oracle parameters 5-18, 7-23overview 1-4owner parameter (Sybase) 5-15, 7-19parameters 4-25, 5-15, 5-17percent utilization 2-39recovery procedure 7-29restoring 2-44, 4-16statistics 2-77, 2-124Sybase parameter 5-17, 7-20

CONTROL-M dateDay Time parameter 5-4description 1-13Odate 1-13

CONTROL-M logcleanup by New Day procedure 1-14deleting entries 2-91description 1-31fields B-1listing entries 2-91messages A-1recorded times 1-8Shout destination 1-27Shout utility 2-138

CONTROL-M Mirror database parameters 5-21

CONTROL-M SYSTEM tablespace parameters 5-19

CONTROL-M versionsystem parameter 5-3

CONTROL-M/Agentsee also Agent platformsconfiguration 1-12

description 1-2discovery 1-6interrupted communication 1-8

CONTROL-M/Serversee also Serveragent interaction 1-5backup server 7-33host name 1-12, 5-9, 5-28messages and codes A-1parameters 5-1processes 2-134, 4-43recovery 1-11Shout messages 2-138starting 4-2, 4-8stopping 4-2, 4-8TCP/IP port number 5-12Windows NT 1-9

creatingsee also ctmcreate, definingad hoc jobs 2-25application-specific jobs 2-31CONTROL-M database 4-10files 2-66Manual Conditions file 2-82

csh commandenvironment variables 2-10path modification 2-13

CTLTABCOUNTmessages and codes A-6

CTM_AGSTAT utilityAgent status 2-15description 2-15

ctm_backup_bcp utilitycomparison with ctmdbbck 2-17exporting database data 2-17

CTM_CB_TIMEOUTserver parameter 5-23

CTM_GROUP_ADJUST_DUMMYserver parameter 5-23


Index 5

CTM_GROUP_RECHECKserver parameter 5-24

ctm_menu command 4-6CTM_PARM_ENC

agent parameter 5-29CTM_PRM_DONT_DELETE

agent parameter 5-28CTM_PRM_ENABLE_UExxx

user exit parameter 5-27, 6-3CTM_PRM_KPA_ACTIVE

communication parameter 5-27Heartbeat monitor 1-38

CTM_PRM_KPA_BETWEEN_MSGSHeartbeat monitor 1-38

CTM_PRM_KPA_ROUNDTRIP_...communication parameter 5-27Heartbeat monitor 1-38

CTM_PRM_KSH_FLAGSagent parameter 5-29

CTM_PRM_SCRIPT_UExxxuser exit parameter 5-28, 6-3

CTM_PRM_SH_FLAGSagent parameter 5-29

CTM_PRM_TIMEOUT_UExxxuser exit parameter 5-28wait interval 6-3

ctm_restore_bcp utilityASCII files 2-19comparison with ctmdbrst 2-19importing database data 2-19

CTM_SLP_SUSPENDserver parameter 5-24

CTM_SNMP_SEND_FORMATserver parameter 5-24

CTM_SU_PATHagent parameter 5-29

CTM_WRITE_CONSOLEserver parameter 5-24

ctm2snmp utilitymessage distribution 2-155

ctmcontb utilityprerequisite conditions 2-21

ctmcreate utilityad hoc jobs 2-25application-specific jobs 2-31Oracle Applications parameters table

2-34SAP parameters table 2-33

ctmdbapasswd utlitydatabase password maintenance 2-36

ctmdbbck utilitydatabase backup 2-37

ctmdbcheck utilitydatabase status 2-39problem detection 1-39vs ctmdbused command 2-39

ctmdbrst utilitycomparison with ctm_restore_bcp 2-19database size 2-17database, restoring the 2-44

ctmdbspace utilityspace verification 1-46, 2-45

ctmdbtrans utilityproblem detection 1-39

ctmdbused commanddatabase utilization 2-39

ctmdefine utility 2-47application-specific jobs 2-57Oracle Applications parameters table

2-59SAP parameters table 2-58

ctmdiskspace utilitydisk space check 1-45, 2-62

ctmexdef utilityexport job definitions 2-64

ctmfw utility 2-66ctmjsa utility 2-77

job statistics 1-30ctmkilljob utility

job termination 2-81



ctmldnrs utilityManual Conditions file 2-82

ctmloadset utilityload balancing 1-10resource usage 2-86

ctmlog utilityCONTROL-M log 2-91problem detection 1-39

CTMLOG_DEL_CHKconfiguration parameter 5-24

ctmordck utilityjob processing definition list 2-94

ctmorder utilitydescription 2-96forcing a job 2-98

CTMORDER_FORCEserver parameter 5-24

ctmpasswd utilitydatabase passwords 2-102

ctmping utilityAgent configuration information 2-103communication status 1-7Watchdog facility 1-48

ctmpsm utilityActive Jobs file 2-107job listing 2-113mode descriptions 2-113Production Support menu 2-106Resource Table options 2-110scheduling function options 2-110Scheduling tables 2-111syntax 2-113

ctmrpln utilitydescription 2-120

ctmruninf utility 1-30Statistical Details table 2-124

CTMS_ADDR_MODEagent parameter 5-29

CTMS_COMVERSIONagent parameter 5-30

CTMS_HOSTNAMEagent parameter 5-30

CTMS_PORT_NUMagent parameter 5-30

ctmsec utility 3-11see also Security Maintenance utilityUser Maintenance option 3-13

ctmshout utilitymessage distribution 2-127

ctmshtb utility 1-26Shout destination table 2-129

ctmstats utility 1-30statistical summary table 2-130

ctmstvar utilityAutoEdit variables 2-133

ctmsuspend utilityENTERPRISE/CS communication

2-134ctmsys utility

parameter modification 5-7system parameters 2-135

ctmudchk utilityordering jobs 2-145User Daily job check 2-145

ctmudlst utilityDate Control record 1-21description 2-147messages and codes A-5, A-7

ctmudly utilityUser Daily jobs 1-18, 2-149

CTMUE101 user exitjob ordering 6-5

CTMUE102 user exitjob submission 6-7

CTMUE103 user exitNew Day procedure 6-9

CTMUE104 user exitNew Day procedure 6-10

CTMUE105 user exitUser Daily jobs 6-11


Index 7

CTMUE106 user exitUser Daily jobs 6-11

ctmwhy utilitywaiting jobs 2-154

customizingCustomization menu 4-30customization parameters 4-30, 5-1platform coordination 5-2

CYCLIC_MAXWAITserver parameter 5-25

CYCLIC_RERUNserver parameter 5-25

DDAILY parameter

ctmudchk utility 2-145Daily report

ctmrpln utility 2-120data

CONTROL-M database 1-4data center

description 1-2data device name

Sybase parameter 5-17, 7-20data device type

Sybase parameter 5-16data device, physical

Sybase parameter 5-16, 7-20database

backup 2-17CONTROL-M 1-4log files 5-18mirroring A-4parameters 5-15, 5-17password maintenance 2-36recovery procedure 7-29restoration 2-17server 4-9size 2-17, 5-15, 7-20

Sybase SQL server name 5-17synchronization 7-36transaction listing 1-39transaction log 2-39utilization percentage 2-39verification 2-37, 2-39

Database Administrator passwordSybase 5-15

Database Creation menu 4-10database mirroring

see alsomirror databasesee alsomirroringmessages and codes A-4

Database Size parameterSybase 5-15, 7-20

database statusctmdbcheck utility 2-41

Database versionsystem parameter 5-3

Date Control recorddescription 1-21inconsistency A-5, A-7modifying manually 2-147UDLAST parameter 1-14

Date parameterdescription 5-4

Day Time parameterdescription 5-4New Day procedure 1-13

Daylight Savings Time 1-33DBASE events

problem detection 1-40DBO password

Oracle parameter 5-20Sybase parameter 5-15, 5-20, 7-19system parameter 5-3

debug parameterctmvar utility 2-153



DEBUG_LEVELagent parameter 5-28server parameter 5-28

definingsee also creating, ctmdefineapplication-specific jobs 2-57CONTROL-M jobs 2-47

deletingbackup devices 4-20CONTROL-M log entries 2-91files 2-66groups 3-18prerequisite conditions 1-14, 2-21, 4-48,

5-6statistics 1-14, 2-124users 3-13

dependencies. See prerequisite conditionsdescription parameter


diagnostic levelsetting 4-49

Disabled statuscommunication 1-7

Disappeared statusagent platform 1-7messages and codes A-10, A-16

discovery process 1-6, 2-103disk space

see also df commanddownloading

Active Jobs file 4-42, 4-48Drop Backup Device option

Database Maintenance menu 4-20

Eecactltb utility 2-157ecaqrtab utility

description 2-158

messages and codes A-5enabling

user exits 6-3ENDED time

CONTROL-M log 1-8ENTERPRISE/CS

ctmsuspend utility 2-134description 1-1release version 5-12Shout messages 2-138TCP/IP port number 5-12

entity authorizationSecurity Maintenance utility 3-28

environment variablesrequired 2-9setting 2-10

event loggerproblem detection 1-39

executable pathsystem parameter 5-3

Executable Path parameter 5-3EXIT_STATUS_DIR

agent parameter 5-30exits

CTMUE101 6-5CTMUE102 6-7CTMUE103 6-9CTMUE104 6-10CTMUE105 6-11CTMUE106 6-11Watchdog facility 1-45, 1-47

exportingjob definitions 2-64

Extend Database Size optionDatabase Maintenance menu 4-21

extendingCONTROL-M database 4-21


Index 9

Ffailover

levels 7-1overview 1-10server platform 1-11

FILE parameterctmudchk utility 2-145

File Watcher utility 2-66file, Manual Conditions 2-82filename parameter

ctmvar utility 2-152first database log file

Oracle parameter 5-18forcing a job

authorization 3-5ctmorder utility 2-98failure A-18, A-19

forcing a tablefailure A-20

forcing downloadActive Jobs file 4-42

Full Security parameterdescription 5-5usage 3-2

GGCSERV user

global condition security 3-8General Daily. See New Day proceduregeneral threshold %

ctmdbcheck utility 2-43GLOBAL

value for AUTOEDIT_INC_SEC 5-23global conditions

security considerations 3-8global variables

batch utility (ctmvar) 2-150

GROUPvalue for AUTOEDIT_INC_SEC 5-23

group schedulingAutoedit variables 2-150New Day procedure 1-17

groupssee also node IDassigning users to 3-11

HHeartbeat monitor

active mode 1-37description 1-37parameters 1-38passive mode 1-37

home directorymessages and codes A-8

host nameagent platforms 1-6CONTROL-M/Agent 1-12

host parameterSAP jobs (ctmcreate) 2-33SAP jobs (ctmdefine) 2-58

Hot backuparchive mode 4-13

Iidentification

agent platforms 1-6Ignore Conditions file

description 5-7mask characters 5-7

Ignore New Day Conditions parameterdescription 5-6usage 1-14

IMPORT_CAL modectmpsm utility 2-113



In conditionssee prerequisite conditions

Index tablespace fileOracle parameter 5-19

init_prflag 4-48Input process communication port number

operational parameter 5-12install_mirror script 7-17interaction

see also communicationServer-Agent 1-5

ioa_appl parameterOracle Applications (ctmcreate) 2-34Oracle Applications (ctmdefine) 2-59

IOALOG eventsproblem detection 1-40

IOALOG_DEL_INTserver parameter 5-25

IP addressarp command 5-11communication parameter 5-9

Jjob status

Disappeared A-11messages and codes A-10

job submissionerror messages A-9

job_in_file parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-58

job_mode parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-58

jobcount parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

Jobname fieldCONTROL-M log B-1

Jobno fieldCONTROL-M log B-1

jobsCTMUE101 user exit 6-5CTMUE102 user exit 6-7Disappeared status 1-7order options 1-24ordering 6-5ordering by New Day procedure 1-14ordering manually 1-23retroactive ordering 1-22sample flow 1-2scheduling 1-15submitting 6-7terminating 2-81User Daily 1-18

jobs orderingmanually 2-96

jobs submissionfailure A-16

KKernel Configuration parameter, Check 4-41killing

ctmkilljob utility 2-81

Llanguage parameter


Last Run dateDate Control record 1-21

level, Restricted security 3-2LIBMEMSYM file

AutoEdit variable A-11List All Devices option

Database Maintenance menu 4-19


Index 11

List Backup Devices optionDatabase Maintenance menu 4-19

LISTAJFTAB modectmpsm utility 2-117

LISTALL modectmpsm utility 2-116

LISTCAL modectmpsm utility 2-113

LISTDETAILS modectmpsm utility 2-118

listener port numberOracle parameter 5-18, 7-23

LISTGROUP modectmpsm utility 2-116

listingActive Jobs file 2-107job processing definitions 2-94jobs 2-113prerequisite conditions 2-21scheduling tables 2-111statistics 2-77, 2-124unordered jobs 2-145

LISTJOB modectmpsm utility 2-116

LISTSYSOUT modectmpsm utility 2-118

load balancingagent identification 1-6overview 1-9resource usage 2-86

loadingManual Conditions file 2-82

LOCALvalue for AUTOEDIT_INC_SEC 5-23

Local IP Host Interface Namecommunication parameter 5-10

locationuser exits 6-1

Log device nameSybase parameter 5-17, 7-20

Log device typeSybase parameter 5-16

log filesarchiving 1-41CONTROL-M 1-31generation limits 1-41managing 1-41problem detection 1-39purged by New Day procedure 1-32renaming 1-41size limits 1-41size monitor 1-39

log physical deviceSybase parameter 5-17, 7-20

Logdate fieldCONTROL-M log B-1

logical devicesadding 4-19

Logtime fieldCONTROL-M log B-1

Mmaintainence

CONTROL-M menu 4-6maintaining

CONTROL-M database 2-17, 4-4database passwords 2-36, 2-102New Day procedure 1-14security 3-11, 4-29Sybase SQL server 4-4system parameters 2-135

Manual Conditions file 2-82mask characters

Ignore Conditions file 5-7Master Device Type

Sybase parameter 5-16Master physical device

Sybase parameter 5-16



Max Wait parameterNew Day procedure 1-13

Maximum Days Retained by CONTROL-M Log

system parameter 1-14, 5-5Maximum Days to Retain Sysout Files

system parameter 1-14, 5-5Maximum job state changes

operational parameter 5-12Maximum Retries parameter

description 5-4, 5-14Maximum server processes

operational parameter 5-13Memname field

CONTROL-M log B-1menu, Production Support 2-106menu, Security Authorization 4-29menus

CONTROL-M main menu 4-6Database Creation 4-10

Message fieldCONTROL-M log B-1

messagessee also shout messages

messages and codesdescription A-1prefixes A-1

messages, distribution ofctm2snmp utility 2-155

Minimum server processesoperational parameter 5-13

mirror databaseextending 4-21messages and codes A-4Oracle 5-20parameters 5-20port numbers 5-20, 7-4QUERY_SPN field 7-4Sybase 5-20, 7-4synchronization 7-35

mirror database data deviceSybase parameter 5-21

mirror database log deviceSybase parameter 5-21

mirroringfailure A-4server environment 1-11

modeSysout file access 5-30

modifyingsee also changingsee also creatingsee also editingsee also updatingenvironment variables 2-9

monitoringQuantitative resources 2-86

Monthly reportctmpln utility 2-120

MSGID fieldCONTROL-M log B-1

NNetwork Management applications

ctm2snmp utility 2-155New Day procedure

Active Jobs file 1-13CTMUE103 user exit 6-9CTMUE104 user exit 6-10Daylight Savings Time 1-35description 1-13group scheduling 1-17ordering jobs 1-14prerequisite conditions cleanup 5-6purging log files 1-32restarting 4-41scheduling 1-15sysout files cleanup 1-14UDLAST parameter 1-14


Index 13

Node groupload balancing 1-9menu 4-36modifying 4-36usage 1-9

Node IDagent platforms 1-6

OOdate

CONTROL-M log B-1ctmcontb utility 2-21, 2-22ctmcreate utility 2-28ctmdefine utility 2-51ctmorder utility 2-98ctmpsm utility 2-110Date Control record 1-21Date parameter 5-4description 1-13New Day procedure 1-13working date 1-21

ON_GROUP_END OK actionsNew Day procedure 1-17

operating systemsystem parameter 5-3

operational parametersdescription 5-11modifying 4-32

Oraclebacking up 4-14database logs 4-13

Oracle Applicationsjob parameters (ctmcreate) 2-34

Oracle SQL serverhome directory 5-18host parameter 5-19, 7-22listner port number 5-18, 7-23parameters 5-18, 7-22

ordering jobs

authorization 3-5job security 3-5New Day procedure 1-14

Orderno fieldCONTROL-M log B-1

OS_PRM_HOSTNAMEagent parameter 5-28server parameter 5-28

outputsee reportssee sysout files

Owner fieldCONTROL-M log B-1

Pparameter, Check Kernel Configuration 4-41parameters

see also variablesCONTROL-M/Server 5-1coordination 5-2customization 5-1Customization menu 4-30database 5-15performance 5-21Sybase database 5-15system 5-3

PARM1 AutoEdit variableUser Daily jobs 1-20

PARMn parameterOracle Applications 2-35Oracle Applications (ctmcreate) 2-35Oracle Applications (ctmdefine) 2-60

passwordsdatabase 2-102

path modificationtcsh command 2-13

permission. See securitypinging

ctmping utility 2-103



Polling interval parametercommunication 5-14description 5-14

polling_interval parameterSAP (ctmcreate) 2-34SAP (ctmdefine) 2-59

port numbersAgent-to-Server 5-10backup socket 5-16CONTROLM/Server 4-41ENTERPRISE/CS TCP/IP 5-12mirror database 5-20, 5-21query socket 5-16Server-to-Agent 5-14

post-processingperformance parameters 5-21

PP_THRESHOLDperformance parameter 5-22

prefixesmessages and codes A-1

prerequisite conditionsadding 2-21cleanup 5-6ctmcontb utility 2-21deleting 1-14, 2-21, 4-48, 5-6listing 2-21unscheduled 2-82

print_archmode parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

print_authorization parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

print_banner parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

print_banner_page parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

print_copies parameter


print_destination parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

print_expiration parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

print_immediately parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

print_numcolumns parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

print_numlines parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

print_recipient parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

print_release parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

printcopies parameterOracle Applications (ctmcreate) 2-34Oracle Applications (ctmdefine) 2-60

PRINTER_NAMEagent parameter 5-28

printername parameterOracle Applications (ctmcreate) 2-34Oracle Applications (ctmdefine) 2-60

printstyle parameterOracle Applications (ctmcreate) 2-34Oracle Applications (ctmdefine) 2-60

PRIORITY_SL_SCANperformance parameter 5-22server parameter 5-26


Index 15

problem detectionIOALOG events 1-40log file size monitor 1-39tools 1-38

Process log fileerasing contents 4-42

process, discovery 1-6, 2-103processes

CONTROL-M/Server 4-43suspending 2-134

proclog filestack trace output 1-42

Production Support menu 2-106profile_ parameter


progname parameterOracle Applications (ctmcreate) 2-34Oracle Applications (ctmdefine) 2-60

program parameterSAP (ctmcreate) 2-33SAP (ctmdefine) 2-59

Protocolcommunication parameter 5-10, 5-28communication with agents 1-6

Protocol Version parameterdescription 5-14

QQuantitative resources

agent platform usage 2-86ctmloadset utility 2-86deleting 4-48discrepancy A-5listing 2-158maintaining 2-158reserved A-18

Query Socketport number 5-16

QUERY_SPN fieldmirror database 7-4

quiet parameterctmvar utility 2-153

quotation marksAutoEdit variables 2-29, 2-52, 2-76,

2-133

RR/3See SAPr3_owner parameter

SAP jobs (ctmdefine) 2-59SAP jobs(ctmcreate) 2-34

raw partitions. See partitionsRBS tablespace file

Oracle parameter 5-19read permission

assigning 2-14reading. See downloadingrecovery

see also failoverdata center failure 7-33database failure 7-29failover planning 1-10

relationship parameterNew Day procedure 1-17

release versionENTERPRISE/CS parameter 5-12

Remote Sybase host namedatabase parameter 5-17, 7-20

removing. See deletingreordering jobs

User Daily 2-145reporting

CONTROL-M log entries 2-91



reportsctmcontb utility 2-21ctmlog utility 2-92ctmordck utility 2-95ctmrpln utility 2-120description 2-6ecactltb utility 2-157ecaqrtab utility 2-159

resourcessee Control resourcessee Quantitative resources

Resource Table optionsctmpsm utility 2-110

respapp parameterOracle Applications (ctmcreate) 2-34Oracle Applications (ctmdefine) 2-60

respname parameterOracle Applications (ctmcreate) 2-34Oracle Applications (ctmdefine) 2-60

Restore Database optionDatabase Maintenance menu 4-16

restoringCONTROL-M database 2-44, 4-16ctmdbrst utility 2-44

Restricted security level 3-2Retro parameter

job processing 1-22Retry Interval parameter

description 5-14Rollback segment tablespace file

Oracle parameter 5-19RUNCNT

rerun counter A-10RUNINF_PURGE_LIMIT

server parameter 1-14, 5-25RUNINF_PURGE_MODE

server parameter 5-25runtime statistics 1-28

SSAP

job parameters (ctmcreate) 2-33job parameters (ctmdefine) 2-58

Savings Time, Daylight 1-33SCHEDTAB mode

ctmpsm utility 2-117scheduling function options

ctmpsm utility 2-110, 2-111scheduling jobs

New Day procedure 1-15performance parameters 5-21

scheduling tablesauthorization 3-21ctmpsm utility 2-113defining jobs 2-47listing jobs 2-120security 3-4

scopeAutoEdit variables 2-150

script, install_mirror 7-17Secure Socket Layer

ctmsys utility 2-142


Index 17

securityActive Jobs file 3-5agent platform 3-8application 3-1assigning users to groups 3-11authorization problem A-15authorizations 3-2, 3-9CONTROL-M entities 3-7ctmsec maintenance utility 3-11database 3-11export defintion tables 4-29Global conditions 3-8import definition tables 4-29job script execution denied A-23job status 2-94levels 3-2permission assignment 2-14Restricted security level 3-2, 5-5Scheduling tables 3-4Security Authorization menu 4-29Servers file 1-9setting levels 5-5summary 3-9table access denied A-23Unrestricted security level 3-2, 5-5user ID not authorized A-23

Security Authorization menu 4-29security level, Restricted 3-2Security Maintenance utility

Active Jobs file 3-24adding groups 3-18adding users 3-13batch mode 3-32deleting groups 3-18deleting users 3-13description 3-11entity authorization 3-28menu 4-29Scheduling table authorization 3-21

security, application 3-1

security_groupname parameterOracle Applications (ctmcreate) 2-35Oracle Applications (ctmdefine) 2-60

serversee also CONTROL-M/Serversee also Oracle SQL Serversee also Sybase SQL Serverfailover 1-11

Server processmessage prefix A-1

Server-to-Agentport numbers 5-14

setting. See customizingShout Destination tables

active table 2-129ctmsys utility 2-135description 1-24maintenance 2-135specifying destinations 1-28

Shout facilitydescription 1-24

Shout messagesagent platforms 2-138ctmshout utility 2-127Daylight Savings Time 1-34, 1-35ENTERPRISE/CS 2-138invalid destination A-17

Show Database Parameters optionDatabase Maintenance menu 4-25

SID mirrorOracle parameter 5-21

size monitorlog files 1-39

size of database log filesOracle parameter 5-18

SL_BREAK_INTperformance parameter 5-22server parameter 5-26



Sleep Timeconsiderations 4-49, 5-22resetting 4-48

SNMP trapsctm2snmp utility 2-155

space usagedatabase 2-45

spool parameterSAP jobs (ctmcreate) 2-34SAP jobs (ctmdefine) 2-59

SQL serversee also Oracle SQL serversee also Sybase SQL server

SSLsee also Secure Socket Layer

stack tracedebugging 1-42problem detection 1-39proclog file 1-42

stageparm parameterOracle Applications (ctmdefine) 2-60

stageparm parameterOracle Applications (ctmcreate) 2-35

Start Day of the Week parameter 5-5starting

CONTROL-M/Server 4-2, 4-8Sybase SQL server 4-9

Statistical Details tablectmjsa utility 1-30

Statistical Summary tablectmstats utility 2-130

statisticscompiling 2-77ctmjsa utility 1-30deleting 1-14, 2-124listing 2-77, 2-124overview 1-28runtime 1-28summary mode 5-12systems parameter 1-29, 5-4

viewing 2-130Statistics Mode parameter

description 1-29, 2-77, 5-12Statistics Summary table

ctmjsa utility 1-30statistics, runtime 1-28STATS_TIME

server parameter 5-25step_num parameter

SAP jobs (ctmcreate) 2-34SAP jobs (ctmdefine) 2-59

stoppingCONTROL-M/Server 4-2, 4-8ctmkilljob utility 2-81Sybase SQL server 4-9

SUBMITTED AT timeCONTROL-M log 1-8

Subsystem fieldCONTROL-M log B-1

Support menu, Production 2-106Sybase

backing up 4-14Sybase interface directory

database parameter 5-17Sybase parameter

log physical device 5-17, 7-20Master physical device 5-16owner 5-15, 7-19

Sybase SQL servercharacter set 7-6considerations 7-4, 7-7database mirroring 7-4database name 5-17database parameters table 5-15dedicated 7-4maintenance 4-4starting 4-9stopping 4-9


Index 19

synchronizationdatabase 7-36mirror database 7-36

sysout filescleanup by New Day procedure 1-14copy error A-13days retained 5-5delete failure A-14lost A-15move failure A-13open error A-13release failure A-14

sysout log directorysystem parameter 5-3

Sysout Log Directory parameter 5-3SYSOUT_MODE

agent parameter 5-30SYSOUT_NAME

agent parameter 5-30SYSTEM

value for AUTOEDIT_INC_SEC 5-23system parameters

description 5-3maintenance 2-135

System User DailyUDLAST parameter 1-14

System user passwordOracle parameter 5-19

Ttable. See Scheduling tablestable security

access denied A-23Tablespace

data file 5-18Oracle SQL server 7-7size 5-18user 5-18

Tasktype field

CONTROL-M log B-1tasktype parameter


TCP/IP host name parametercompatibility 5-10

TCP/IP port numberENTERPRISE/CS 5-12

TCP/IP protocolagent communication 1-6

tcsh commandenvironment variables 2-10path modification 2-13

terminatingjobs 2-81

timeCONTROL-M functions 1-8

Time From parameterJob Submission window 1-8

Time Until parameterJob Submission window 1-8

Time, Daylight Savings 1-33Timeout parameter

description 5-14transfering

files 2-66TRANSLATE_$0

agent parameter 5-30Troubleshooting

menu 4-40report 4-45

UUDLAST parameter

description 1-21New Day procedure 1-14User Daily 1-14

ue_exit directoryuser exits 6-4



Unavailable statusagent platform 1-7

Unknown statusagent platform 1-8

unordered jobslisting 2-145User Daily jobs 2-145

Unrestricted security leveldescription 3-2

UPDATEAJF modectmpsm utility 2-118

UPDATEGROUP modectmpsm utility 2-119

UPDATETABLE modectmpsm utility 2-119

User DailyAutoEdit variable %%PARM1 1-20ctmordck utility 2-94CTMUE105 user exit 6-11CTMUE106 user exit 6-11Date Control record 1-21example 1-19interruptions 1-23reordering jobs 2-145scheduling 1-15workflow 1-18

User Daily jobschecking 2-145ctmudly utility 2-149last run date 2-147listing job definitions 2-94unordered jobs list 2-145

user exitssee also exitsconfiguration parameters 5-27, 6-3location 6-1Watchdog facility 1-47workflow 6-3

user IDsee also owner

unauthorized A-23User Maintenance option

ctmsec utility 3-13User password

Oracle parameter 5-18, 7-22userexits

enabling 6-3username parameter

Oracle Applications (ctmcreate) 2-34Oracle Applications (ctmdefine) 2-34,

2-60utilities

ctm_backup_bcp 2-17ctm_restore_bcp 2-19ctm2snmp 2-155ctmcontb 2-21ctmcreate 2-25ctmdbapasswd 2-36ctmdbbck 2-37ctmdbcheck 2-39ctmdbrst 2-44ctmdbspace 2-45ctmdbtrans 2-46ctmdefine 2-47ctmdiskspace 2-62ctmexdef 2-64ctmfw 2-66ctmgrpdef 2-75ctmjsa 2-77ctmkilljob 2-81ctmldnrs 2-82ctmloadset 2-86ctmlog 2-91ctmordck 2-94ctmorder 2-96ctmping 2-103ctmpsm 2-106ctmrpln 2-120ctmruninf 2-124ctmsec 3-13


Index 21

ctmshout 2-127ctmshtb 2-129ctmstats 1-30, 2-130ctmstvar 2-133ctmsuspend 2-134ctmsys 2-135ctmudchk 2-145ctmudlst 2-147ctmudly 2-149ctmvar 2-150ctmwhy 2-154ecactltb 2-157ecaqrtab 2-158environment variables 2-9Oracle variables 2-10output destination 2-7reference table 2-4reports 2-6summary table 2-2Sybase variables 2-10user access to 2-9

Vvar parameter

ctmvar utility 2-152varexpr parameter

ctmvar utility 2-152variables. See AutoEdit variables.

Environment variables, and parametersvariant parameter

SAP (ctmcreate) 2-34SAP jobs (ctmcreate) 2-34SAP jobs (ctmdefine) 2-59

verifyingdatabase integrity 2-37User Daily jobs 2-145

viewingsee also listingstatistics 2-130

Wwaitchild parameter


waitonly parameterSAP jobs (ctmcreate) 2-34SAP jobs (ctmdefine) 2-59

Watchdog facilityconfiguration parameters 5-31description 1-44error handlers 1-48parameters 5-31predefined exits 1-45problem detection 1-39user exits 1-47

Watcher utility, File 2-66WD_ALIVE_MSG parameter

Watchdog facility 1-48WD_CTMEXIT__CMD_LINE parameter

Watchdog exit 1-46WD_CTMEXIT__ERROR_MSG parameter

Watchdog exit 1-46WD_CTMEXIT__INTERVAL parameter

Watchdog exit 1-46WD_CTMEXIT__RUN_STATE parameter

Watchdog exit 1-46WD_CTMEXIT__SCRIPT_FILE parameter

Watchdog exit 1-46WD_CTMEXIT__SUSPEND_STATE

Watchdog exit 1-46WD_CTMEXIT__TIMEOUT parameter

Watchdog exit 1-46WD_CTMEXIT_NUMBER parameter

Watchdog facility 1-44WD_CTO_HOSTNAME parameter

Watchdog facility 1-48WD_CTO_TIMEOUT parameter

Watchdog facility 1-49



WD_ERROR_HANDLER_SCRIPT_FILEWatchdog facility 1-49

WD_ERROR_HANDLER_TIMEOUTWatchdog facility 1-49

WD_HEARTBEAT_INTERVAL exitHeartbeat check 1-45

WD_INTERVAL parameterWatchdog facility 1-49

WD_USEREXIT__CMD_LINE parameterWatchdog exit 1-47

WD_USEREXIT__ERROR_MSGWatchdog exit 1-47

WD_USEREXIT__INTERVAL parameterWatchdog exit 1-47

WD_USEREXIT__RUN_STATE parameterWatchdog exit 1-47

WD_USEREXIT__SCRIPT_FILEWatchdog exit 1-47

WD_USEREXIT__SUSPEND_STATEWatchdog exit 1-47

WD_USEREXIT__TIMEOUT parameterWatchdog exit 1-47

WD_USEREXIT_NUMBER parameterWatchdog facility 1-44

Windows NTCONTROL-M/Server 1-9

workflowCONTROL-M jobs 1-2New Day procedure 1-13scheduling jobs 1-15User Daily jobs 1-18

write permissionassigning 2-14

YYearly report

ctmpln utility 2-120

*100037648**100037648**100037648**100037648*

*100037648*

Control-M_Server for Unix Admin guide

Documents

Transcript of Control-M_Server for Unix Admin guide