Supporting
CONTROL-M/Server for UNIX and Microsoft Windows
version 6.3.01
July 2007
www.bmc.com
Contacting BMC Software
You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information
about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada
Address BMC SOFTWARE INC Telephone 713 918 8800 or Fax 713 918 8000
2101 CITYWEST BLVD 800 841 2031
HOUSTON TX 77042-2827
USA
Outside United States and Canada
Telephone (01) 713 918 8800 Fax (01) 713 918 8000
Copyright 2007 BMC Software, Inc., as an unpublished work. 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.
IBM is a registered trademark of International Business Machines Corporation.
Oracle is a registered trademark, and the Oracle product names are registered trademarks or trademarks of Oracle
Corporation.
All other trademarks belong to their respective companies.
BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this
information is subject to the terms and conditions of the applicable End User License Agreement for the product and the
proprietary and restricted rights notices included in this documentation.
Support website
You can obtain technical support from BMC Software 24 hours a day, 7 days a week at
http://www.bmc.com/support_home. From this website, 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
3
4 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide
Contents
Chapter 1 Overview 17
About CONTROL-M/Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Contents 5
Adding and modifying time zone definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Daylight saving time considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
CONTROL-M administrator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Heartbeat monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Advanced problem detection tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Setting event log parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Managing log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Stack trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Watchdog facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Error handlers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
User exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Processing overhead. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Language capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Chapter 3 Utilities 77
Utility reference table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Reports generated from utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
-input_file parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Directing output from utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Accessing utilities from other users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
For users on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
For users on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
ctm_agstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
ctm_backup_bcp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
ctm_diag_comm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
ctm_restore_bcp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
ctmagcln. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
ctmcalc_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
ctmcheckmirror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
ctmcontb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
ctmcpt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
ctmcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
ctm2snmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
ctmdbbck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
ctmdbcheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
ctmdbmused . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
ctmdbopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
ctmdbrst. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
ctmdbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
ctmdbtrans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
ctmdbused . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
ctmdefine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
ctmdiskspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
ctmexdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
ctmfw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
ctmgetcm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
ctmgrpdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
ctmhostmap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Contents 7
Database Creation menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Database Maintenance menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Database Mirroring menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Synchronizing the primary and mirror databases . . . . . . . . . . . . . . . . . . . . . . . . . 340
Security Authorization menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Parameter Customization Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Node Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
View NodeID details option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Agent Status menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Troubleshooting menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
CONTROL-M/Server processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Shout destination tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Shout message destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Glossary 465
Index 471
Contents 9
10 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide
Figures
New Day procedure and User Daily jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Sample Rull.dat file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Sample Trace File Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
FileWatch - File Watcher panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Sample rule file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Node Group Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
ctmordck sample output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
ctmpsm – production support menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
ctmpsm - Active Jobs File Menu Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
List of scheduling tables output by the ctmpsm utility . . . . . . . . . . . . . . . . . . . . . . . . 223
List of Jobs output by the ctmpsm utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Security Maintenance Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
User Maintenance Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Group Maintenance Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Scheduling Table Authorization Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Active Jobs File Authorization Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Entities Authorizations Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
CONTROL-M System Parameters (Page 1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
CONTROL-M/Server System Parameters (Page 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
CONTROL-M Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
CONTROL-M Manager Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Database Mirroring Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Security Authorization Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Parameter Customization Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Default Parameters for Communicating with Agent computers menu . . . . . . . . . . 344
Communication parameters for specific agent computers . . . . . . . . . . . . . . . . . . . . . 345
Simple Mail Transfer Protocol Parameters Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Agent Status Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Troubleshooting Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Troubleshooting Report Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Directing shouts using the Active Shout Destination Table . . . . . . . . . . . . . . . . . . . . 359
Database Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Server computer Failover - Primary Environment and Mirror Environment . . . . . 423
Mirroring parameters for database copying - Sybase . . . . . . . . . . . . . . . . . . . . . . . . . 433
Mirroring parameters for database copying - Oracle . . . . . . . . . . . . . . . . . . . . . . . . . 440
Mirroring parameters for database build or rebuild - Oracle . . . . . . . . . . . . . . . . . . 440
Figures 11
12 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide
Tables
Communication statuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Options for issuing a job order manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Time zone values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Time zone syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Heartbeat monitor modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Heartbeat monitor parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Advanced problem detection tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Event logger severity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Managing log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
General Watchdog facility parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Heartbeat monitor exit parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Parameters for Watchdog system exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Parameters for Watchdog Facility User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Watchdog Facility parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Processing overhead for job processing features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
CONTROL-M utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
CONTROL-M utility reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Utility reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Utilities that support the -input_file parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Additional required environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Shared library path for Sybase variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Shared library path for Oracle variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Shared library path variables for Sybase and Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Read/Write permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
ctm_agstat parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
ctmdiskspace parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
ctmcalc_date parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
ctmcontb utility parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
ctmcreate parameter descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
ctmcreate parameter name cross reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Fields of SNMP traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
ctm2snmp parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
ctmdbcheck parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
ctmdbcheck output – displayed fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
ctmdefine parameter description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
ctmdefine parameter name cross reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
ctmdiskspace parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
ctmexdef parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
ctmfw parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Rule file global parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Tables 13
ctmfw – valid actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
ctmfw – return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
ctmgetcm parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
cmtgrpdef parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
ctmhostmap actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
ctmhostmap parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
ctmjsa parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
ctmkeygen actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
ctmkeygen parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
REMEDY Keystore Menu parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
ctmkilljob parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
ctmldnrs – creating a manual conditions file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
ctmldnrs – listing or loading manual conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
ctmloadset parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
ctmlog – valid actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
ctmlog parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
ctmnodegrp – variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Options of the Node Group Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
ctmordck – output columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
ctmordck parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
ctmorder parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
ctmping parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
ctmpsm - menu options for Active Jobs file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
ctmpsm - Active Jobs file actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
ctmpsm - menu options for the resource map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
ctmpsm - menu options for scheduling functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
ctmpsm - options for scheduling functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
ctmpsm - options in the Scheduling Table List Jobs menu . . . . . . . . . . . . . . . . . . . . . 225
ctmpsm STATE and STATUS fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
ctmpsm - mode descriptions and syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
ctmrpln – report formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
ctmrpln parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
ctmruninf parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Security levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
ctmsetown actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
ctmsetown parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
ctmshout parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
ctmspdiag options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
ctmspdiag parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
ctmstats parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
ctmstvar parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
cmtsuspend options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Fields of the Shout Destination table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
ctmudchk parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
ctmudlst parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
ctmudly parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
ctmvar parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
ecaqrtab parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
ecaqrtab – resource status fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Tables 15
MSSQL environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Mirroring parameters for copying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Sybase mirroring parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Oracle mirroring parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Oracle database server passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Initialize mirroring parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Initialize mirroring parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Utilities affecting the primary database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Fields of the CONTROL-M/Server log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
1
1 Overview
This book describes how to maintain CONTROL-M/Server on either a UNIX or a
Microsoft Windows computer.
Use this book with the CONTROL-M Job Parameter and AutoEdit Variable Reference
Guide, the CONTROL-M/Enterprise Manager Utilities Reference Guide and the
CONTROL-M Concepts Guide.
About CONTROL-M/Server
CONTROL-M/Server is a component of CONTROL-M for Business Integrated
Scheduling. This family of products manages production control and schedules, and
submits and tracks jobs across your network. CONTROL-M/Server enables you to
attain maximum production throughput by ensuring that each job is submitted with
the appropriate timing and on a computer with sufficient resources to execute the job
efficiently.
This guide describes concepts and tools that are required by the administrator to set
up and manage CONTROL-M/Server on either a UNIX or a Microsoft Windows
computer.
Chapter 1 Overview 17
Conventions
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 according to the job definition. CONTROL-M/Agent can connect to a
remote host and can perform requests and actions on that remote host.
Conventions
Text and examples are given according to UNIX usage, unless otherwise stated. The
default full path name of the home directory of the UNIX user account under which
CONTROL-M/Server is installed is $HOME/ctm_server, for example, $HOME/
ctm_server/data.
Abbreviation Description
CONTROL-M/EM CONTROL-M/Enterprise Manager
CM CONTROL-M/Control Module
The CM connects the agent with an application such as the
operating system or a database.
Convention Description
<key> When describing keystrokes, angle brackets are used to
enclose the name of a key (for example, <F1>). When two
keys are joined with “+” as in <Shift>+<F1>, hold down
<Shift> while pressing <F1>.
Menu => Option This convention represents an option selection sequence.
{AND|OR}
cd <controlm_path>
Chapter 1 Overview 19
Conventions
2
2 Working with CONTROL-M/Server
This chapter includes the following topics:
CONTROL-M/Server database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Server interaction with agents and remote hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Load balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Backup and restore procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Failover planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Host identification in agent computers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
User Daily jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
New Day procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Group scheduling and processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Shout facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Runtime statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
CONTROL-M/Server log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Time zone support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
CONTROL-M administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Heartbeat monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Advanced problem detection tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Watchdog facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
User exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Processing overhead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Language capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
CONTROL-M/Server database
The CONTROL-M/Server database is the repository of operational data that relates
to the functioning of the CONTROL-M data center. One database exists for each
CONTROL-M data center. CONTROL-M/Server maintains the database by using a
dedicated or shared SQL server.
■ CONTROL-M log
■ 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
Agent computers
An agent computer is one on which CONTROL-M/Agent has been installed.
CONTROL-M/Agent submits jobs for execution, monitors the jobs, and performs
post-processing analysis of output files. The completion status of jobs and the results
of post-processing analysis are transmitted back to CONTROL-M/Server.
If you have a computer that has CONTROL-M/Agent installed and you want to use
the computer as a remote host, see Appendix C, “Conversion of agents and remote
hosts.”
For more information about agent computers, see the CONTROL-M Concepts Guide.
One CONTROL-M/Agent can connect to many remote hosts. When jobs are
designated to run on a remote host computer, the job owner must be defined in the
CONTROL-M/Server owner’s authentication settings. For more information, see
“ctmsetown” on page 265.
For each new remote host, you must define the job owners that can use the remote
host (the owners of the CONTROL-M jobs that list the remote host computer in the
Node group field), and appropriate owner authentication parameters. You can
define these settings using the CONTROL-M Configuration Manager or using the
CONTROL-M/Server ctmsetown utility.
2. Define the connection technology settings that will be used to establish connection
between CONTROL-M/Agents and new remote hosts.
You can define these settings using either the CONTROL-M Configuration
Manager or the CONTROL-M/Server ctmhostmap utility:
For information about the discovery process, see “Discovering agents and
remote hosts” on page 27.
If you have a computer with a CONTROL-M/Agent installed and you want to use
the computer as a remote host, or if you have a remote host computer and you want
to use it as an agent computer, see Appendix C, “Conversion of agents and remote
hosts.”
For more information about remote host computers, see the CONTROL-M Concepts
Guide. For more information about the CONTROL-M Configuration Manager, see the
CONTROL-M/EM Administration Guide.
A discovery process must be run for each agent and remote host before
CONTROL-M/Server can work with it and submit jobs. CONTROL-M/Server
performs a discovery procedure automatically to determine the communication
status of agent and remote host computers. This procedure can also be performed
manually by using ctm_menu utility. For more information, see “Agent Status menu”
on page 348 for agent computers and “ctmping” on page 212 for remote hosts.
Depending upon the type of protocol that is used for communication, certain
user-defined communication parameters determine timeouts and the number of
retries attempted before the status of an agent or remote host computer is changed.
Communication parameters are described in Chapter 5, “Customization parameters.”
After a computer is in discovery status, the system checks it for type, as follows:
After the server creates a persistent connection to the Agent Router, the Agent
Tracker and Agent Utilities processes use this connection to communicate freely with
the server.
To set the communication mode to persistent between the server and the agent,
perform the following steps:
3 Select the Parameters for Communicating with Specific Agent computers option
and press <Enter>.
5 From the Parameters for Communicating with Specific Agent computers menu,
select Persistent Connection and press <Enter>.
To set the agent so that it does not attempt to connect to the server, perform the
following steps:
1 In the agent configuration utility advanced menu, select Allow Comm Init.
2 Specify N.
Interrupted communication
If communication is interrupted between CONTROL-M/Server and one or more
agent computers, CONTROL-M/Server sends a special Shout message to
CONTROL-M/EM. All jobs that were running on the affected agent computers are
reclassified in the Active Jobs file as Unknown. The status of the agent computer is
changed to Unavailable.
If processing on the agent computer was not interrupted, any job submitted to a
computer prior to the interruption continues executing.
Time-related functions
The time value that is used for any CONTROL-M function is determined by the
system time on the server computer, including:
■ the time window in which a job can be submitted (according to the job processing
parameters Time From and Time Until).
EXAMPLE
The SUBMITTED AT value recorded in the CONTROL-M/Server log is the time when
CONTROL-M/Server issued the job submission request to the CONTROL-M/Agent or
remote host computer, not the time that the request was received and not the time that the job
actually started executing.
The ENDED value recorded in the same log is the time when CONTROL-M/Server received
notification that the job completed execution.
To ensure that an agent computer does not receive a request from any unintended
source, each agent computer contains a file listing host names of server computers
that are authorized to issue requests to that computer. A request from any server
computer that is not listed in this file is rejected by CONTROL-M/Agent on the agent
computer.
The Authorized CONTROL-M Servers file for each agent computer typically contains
the host name of the server computer to which the agent computer is assigned and
the host name of a backup CONTROL-M/Server computer (see “Failover planning”
on page 35). For a Windows agent computer, this information resides in the Windows
registry database.
Load balancing
Under the Agent Technology implementation of CONTROL-M, you have the
additional option of scheduling jobs by 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 computer. This node group represents a user-defined list of agent
computers that are capable of executing a given job. CONTROL-M/Server uses a
load-balancing algorithm to determine which of these agent computers is best able to
handle execution of the job at that moment and submits the job to that node.
The following CONTROL-M facilities are used to administer load balancing on the
server computer:
For an overview of the load balancing facility, see “Load Balancing” in the
CONTROL-M Concepts Guide.
Backup procedure
CONTROL-M supports the following backup procedures:
■ Cold backup – This procedure shuts down CONTROL-M/Server and its database
and copies database files to a "safe" location. If a restore procedure is needed,
transactions made after the backup are lost. For more information, see “Cold
backup” on page 329.
The main disadvantage of this procedure is that the Oracle Archiving feature must
be activated. This feature requires a lot of disk space to maintain a consistent
instance of the data on the file system so it can be fully recovered if needed. Oracle
Archiving can be activated by using the CONTROL-M/Server backup procedure.
For more information, see “Archive mode” on page 329.
Restore procedure
CONTROL-M/Server provides only a single restore procedure. The same procedure
is used for restoring hot and cold backups. For more information, see “To restore an
Oracle database” on page 332.
■ The system crashed. When it was restarted, the database is “hung” in "startup
mount" mode.
■ The file system structure did not change. All directories in which database files are
located are available.
■ Physical damage has occurred to one or more database data files. CONTROL-M
does not automatically handle corruption to the control file or to the redo log files
because they are not likely to become corrupted.
■ Data should be recovered to that point in time when the system crash occurred.
These assumptions are based on the likely state of a corrupted database and are
designed to minimize the time and effort required for recovery.
NOTE
This CONTROL-M/Server restore operation can only be executed on a database that is in
“startup mount”.The CONTROL-M/Server restore procedure can only be executed on a
corrupted database. If the database is not corrupted, it does not need to be restored.
1. The last backup is restored. This backup is a cold backup, since hot backups are not
available if the database is not running in archive mode.
2. The database is opened. Transactions that took place since the backup was created
are lost.
1. The last backup is restored. (It makes no difference whether the last backup was a
hot or cold backup.)
2. Transactions that took place since the last backup are recovered by using the
Oracle Archiving feature.
Backup procedure
To back up the CONTROL-M/Server database (Sybase) onto a backup device, use
either the ctmdbbck utility or, from the CONTROL-M Main Menu, select the
Database Maintenance menu. Follow the procedure described in “Backup database”
on page 330.
Restore procedure
For information about the restore procedure for a CONTROL-M/Server database
(Sybase), see “To restore a Sybase or MSSQL database” on page 332.
For a list of the assumptions on which this procedure is based, see “Restore
procedure” on page 32.
Backup procedure
For information about the back up procedure for a CONTROL-M/Server database
(MSSQL), see “Backup database” on page 330.
Restore procedure
For information about the restore procedure for a CONTROL-M/Server database
(MSSQL), see “Backup database” on page 330.
For a list of the assumptions on which this procedure is based, see “Restore
procedure” on page 32.
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:
Ideally, your failover plan should include a complete backup for both the server
computer and the CONTROL-M/Server database.
For more information about database mirroring and failover planning, see Chapter 7,
“Mirroring and Failover.”
Each job submission or job tracking request from CONTROL-M/Server contains the
host name of the server computer.
■ 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.
This mechanism enables a backup server computer to take over job submission and
tracking functions in the event a failure occurs in the primary server computer. Its
purpose is to prevent an agent computer from receiving job-handling requests from
two or more server computers concurrently. It is the administrator’s responsibility to
ensure that CONTROL-M/Server is not running simultaneously in the primary and
backup server computers.
A User Daily job is actually no different from any other regular job handled by
CONTROL-M. The User Daily job is defined using CONTROL-M/EM or using the
ctmpsm utility (see page 224), using the same job processing parameters as any other
job.
NOTE
If a User Daily job will be run using a CONTROL-M/Agent prior to version 6.0.00, that
CONTROL-M/Agent must be installed on the server computer.
[Solaris] Prior to CONTROL-M/Server version 6.1.03, not more than 255 jobs could be
ordered if the server ran on a Solaris operating system. Beginning with version 6.1.03, this
limitation has been removed.
A User Daily job must include in its script file (specified by its Mem Name job
parameter) the command to run the ctmudly utility. ctmudly accepts a parameter that
contains 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 that are 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 (for example, 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.
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/Server 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.
NOTE
BMC Software recommends that User Daily jobs be scheduled to run sequentially, not
concurrently. This can be accomplished using the standard scheduling parameters in job
processing definitions. For example, 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 conditions.
Example
Assume that a set of jobs is defined in a Scheduling table named ACCOUNTING that
is assigned to User Daily UDAILY1. Another set of jobs is defined in a Group
Scheduling table named ACCGROUP.
The following job processing definition 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 $1 parameter set to UDAILY1,
the command actually executed by the script is:
ctmudly UDAILY1
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.
For example:
■ The computer has not been working for a day or more (for example, 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.
ctmudlst can be used to change the UDLAST field in the Date Control record.
Changing this date field affects the scheduling of jobs as described in the following
section.
■ 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/Server 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/Server log and stops executing.
You can use the ctmudlst utility, if required, to modify UDLAST.
■ If, for any reason (for example, 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 Retro parameter, 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 the
CONTROL-M Job Parameter and Variable Reference Guide.
NOTE
There 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.
If a User Daily job is interrupted for any reason (for example, 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. ctmudchk verifies that a job is not
already present in the Active Jobs file before ordering the job.
The following options are available on the CONTROL-M Configuration Manager for
issuing a job order manually:
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:
For more information regarding the use of the Order and Force options, see
“Ordering/Forcing Jobs” in the CONTROL-M Job Parameter and Variable Reference
Guide.
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.
As of version 6.2.01, the following actions can now be disabled from New Day and a
new utility can be executed as a batch job during the day to perform the cleanup:
■ Agents cleanup
■ Statistics cleanup
1. A new Odate (CONTROL-M date) is calculated (based on the system date and
CONTROL-M system parameter Day Time).
NOTE
Odate is the scheduling date assigned when the job is ordered. See “Date Definition
Concepts” in the CONTROL-M/Enterprise Manager User Guide for more information about this
date.
5. 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.
NOTE
A job for which the Max Wait parameter is specified that ends with NOTOK status is not
deleted from the Active Jobs file until the Max Wait parameter is exceeded.
7. A partial cleanup of the information in the JOBINF table that is specific to any one
instance of a job run, is performed.
9. 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 37).
10. The end of a daily run is marked by updating the UDLAST parameter in the Date
Control record of User Daily “SYSTEM”. This parameter represents the last date on
which the New Day procedure ordered jobs.
11. CONTROL-M begins downloading the new Active Jobs file to the CONTROL-M
Configuration Manager. During download, CONTROL-M processes are
suspended.
NOTE
See “Date control record (UDLAST)” on page 39 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. For more information about
User Daily jobs, see “User Daily jobs” on page 37.
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 by using the New
Day procedure.
It is preferable to order jobs by using User Daily jobs if two or more of the following
conditions exist:
User Daily jobs can be defined according to function (for example, 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 demonstrates how the association of
Scheduling tables and User Daily jobs affects the scheduling of jobs under
CONTROL-M:
1. As part of its daily routine, CONTROL-M activates the New Day procedure.
2. The New Day procedure scans the CONTROL-M/Server 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, User
Daily jobs, or both. 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.
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 the values that are specified for job-specific basic scheduling parameters.
NOTE
A 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 that are assigned to it in the
CONTROL-M/Server database, and orders the jobs based on their Scheduling
criteria, the date in the computer, and the Date Control record (see “User Daily jobs”
on page 37). 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 39).
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.
NOTE
A 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, prerequisite Out Conditions are set, and
Shouts and ON_GROUP_END OK actions are performed.)
Each User Daily job scans all the Scheduling tables assigned to it in the
CONTROL-M/Server database, and orders the jobs based on their Scheduling
criteria, the date in the computer, and the Date Control record (see “User Daily jobs”
on page 37). 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 39).
Variations of the method described can be used. For example, additional User Daily
jobs can be defined, each one executing at a specific time.
A Group Scheduling table contains processing parameters that are usually found in
the job processing definitions of individual jobs. The processing parameters that are
defined for the Group Scheduling table are applied to all jobs in the table.
Shout facility
The CONTROL-M Shout facility sends messages to specified recipients (for example,
users, terminals, files, CONTROL-M/Server log) based on a destination specified by
the Shout or Do Shout parameters in a job processing definition.
The ctmshout utility can also be used to issue a Shout message to an indicated
destination. ctmshout is described in Chapter 3, “Utilities.”
The Shout Destination table contains a list of logical destinations and the equivalent
physical destination of each logical destination. For more information about creating
and maintaining Shout Destination tables, see “Shout destination tables” on page 359.
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 that is required by a job varies from its average runtime by more
than a stated interval. This message can help highlight possible errors. (The Shout
parameter is described in the CONTROL-M Job Parameter and Variable Reference
Guide.)
■ When viewing information regarding a scheduled job (that is, a job in the Active
Jobs file) in CONTROL-M/EM, you are provided with the average runtime and
the standard deviation in the Job Details window. In addition, you can view the job
statistics that are recorded in the Statistical Details table by selecting the Statistics
option from the Job Node menu.
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 setting 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/Server database. System parameters are modified by using 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, Scheduling table, 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 by
using the Parameter Customization menu in the CONTROL-M Menu system (see
Figure 24 on page 343).
■ 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/Server database. For additional information, see the description of
the ctmjsa utility on page 174.
BMC Software recommends that you define a CONTROL-M job to run the ctmjsa
utility on a daily basis, which helps to ensure that the CONTROL-M/Server database
contains current statistics on all jobs that are executed under CONTROL-M. A partial
cleanup of the Statistical Details table is performed by the New Day procedure. For
more information, see “New Day procedure” on page 42.
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 3, “Utilities.”
CONTROL-M/Server log
The CONTROL-M/Server log contains a complete audit trail of every event that
occurs in the CONTROL-M production environment. CONTROL-M/Server 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/Server log are messages
regarding the following information:
■ job submissions and terminations, reruns, job log (SYSOUT) handling and Shout
performance
On the server computer, all CONTROL-M/Server log entries can be viewed using the
CONTROL-M ctmlog utility (described in Chapter 3, “Utilities”).
■ Time zone file —contains a list of time zones and a time offset for each time zone.
■ Time zone field—this job processing definition field identifies which time zone
offset in the time zone file to use for time calculations. Generally, the time zone of
the remote agent computer is specified.
When you specifying a time zone name in the time zone field of the job processing
definition, CONTROL-M adjusts the time calculations for processing according to the
offset of the specified time zone.
To define a job to be executed in a specific time zone, specify the time zone name in
the time zone parameter in the job processing definition. If no time zone is specified
in the job processing definition, the local time of the CONTROL-M/Server that
ordered the job is used.
To add a time zone to the predefined list or to modify an existing time zone, see
“Adding and modifying time zone definitions” on page 54.
■ Newly defined jobs with specified time zones must be saved at least 48 hours
before their intended execution dates (in order to ensure that they are ordered
automatically by the appropriate New Day Procedure or User Daily).
If they must run “today” they should be ordered manually (for example, by using
the ctmorder utility).
■ Specified Odates are calculated according to the working date (not the actual date).
This distinction means that if a job is defined as working on the 5th of the month at
03:00 A.M., and the working day begins at 05:00 A.M, then the job will actually be
run at 03:00 A.M on the morning of the 6th (which is still part of the working day
of the 5th).
■ In addition to time zones, you can also order a job that is intended for execution on
a future date. For more information, see the odate and odate_option parameters in
any of the following CONTROL-M/Server utilities:
— ctmudly
— ctmudchk
— ctmorder
— ctmcreate
■ BMC Software recommends that you do not combine jobs that have time zone
specifications with jobs that do not specify a time zone in the same Scheduling
table or Group Scheduling table.
■ When a job with a time zone definition is considered for ordering by the New Day
procedure, it is ordered if its scheduling date occurs within the next 48 hours.
When a job is ordered by a User Daily job, it will be ordered only if its scheduling
criteria are satisfied for the current working date. For this reason, BMC Software
recommends that you arrange the jobs for each time zone in a separate table. For
more information, see the recommended method described in the following
section.
As of version 6.1.01, jobs with specified time zones can be ordered as early as 48 hours
before their actual run, and they may remain in the Active Jobs file after their
specified scheduling date. Because these jobs must normally be ordered from the
New Day procedure, an unusually large number of jobs can accumulate in the Active
Jobs file for a long period of time, which can result in slower processing.
1 Create a separate scheduling table for each time zone that you will be using and
place the jobs definitions for that time zone in that table.
2 Define a User Daily job (by using the ctmudly utility) for each scheduling table that
was created in Step 1.
■ Specify a time for the User daily that corresponds to a time just after the
beginning of the working day in that time zone.
■ In the -odate parameter, specify the working date for the time zone (usually
either the current CONTROL-M/Server working date, or the next day).
■ In the -odate_option parameter, specify run_date, to indicate that the odate
value should be used to determine the working day on which the jobs should
run.
NOTE
The run_date functionality can be implemented only in CONTROL-M/Server utilities.
This aspect of time zone support cannot be implemented from CONTROL-M/EM.
3 List the User Daily jobs in the ctmorder section of the New Day procedure.
NOTE
The daylight saving time feature is not supported in the CONTROL-M/EM TimeZone.dat
file.
■ modify the TimeZone.dat file as close to the actual time change as possible,
preferably within in seconds or minutes of the time change
■ stop and restart CONTROL-M/Server to implement the changes
■ synchronize the TimeZone.dat files used by CONTROL-M/Server and
CONTROL-M/EM, as needed
If a time zone is deleted from the TimeZone.dat file, job definitions that specify that
time zone will become invalid. In addition, if the three-character name for the time
zone is modified in the TimeZone.dat file but not in the job processing definition, the
time zone becomes invalid.
As of version 6.1.01, the syntax to specify time zones without daylight saving
considerations, is as follows. You should use this syntax when configuring the
TimeZone.dat file for CONTROL-M/EM:
xxx (GMT±hh:mm)
EXAMPLE
To create a time zone for New York city that is five hours earlier than Greenwich Mean Time,
specify
NYC (GMT-05:00)
As of version 6.3.01, time zone specification takes account of daylight saving, and the
syntax for the format is displayed below. For the syntax earlier than version 6.3.01,
see “Syntax to specify time zone without daylight saving time.”
Zone 1 Zone 2
This format sets the start of daylight saving from one time zone relative to the other.
In the northern hemisphere, Zone 1 indicates the standard time (for example,
GMT+02:00), while Zone 2 indicates the standard time after adjustments for daylight
saving time (for example, GMT+03:00). This syntax is reversed for the southern
hemisphere. The FROM and TO keywords specify the start and end settings for
daylight saving to take effect.
NOTE
DD.MM is the only acceptable format in this file (MM.DD is not supported).
This value should be specified in the time zone parameter of relevant job
processing definitions.
± plus or minus sign to indicate whether the time zone is earlier (minus) or later
(plus) than Greenwich Mean Time (GMT)
hh the difference in hours between the relevant time zone and Greenwich Mean Time
(GMT), expressed as a 2-figure number
hh and mm are the time in hours and minutes when the clock time is changed, each
expressed as a 2-figure number.
TO the end of the daylight saving time period
dd.mm
hh:mm dd and mm are the date and the month when the clock time is changed, each
expressed as a 2-figure number.
hh and mm are the time in hours and minutes when the clock time is changed, each
expressed as a 2-figure number.
Example 1
To create a new daylight saving time zone definition, JST, for Japan, where the time is
nine hours later than Greenwich Mean Time (GMT), and daylight saving time begins
on March 1st at 01:59 and ends on October 24th at 02:00, use the following syntax:
Example 2
To create a new daylight saving time zone definition, EST use the following syntax:
This syntax means that between the dates April 2 and October 29 the EST time zone is
defined as GMT-04:00 (summer time). For all other dates, EST is defined as
GMT-05:00 (winter time). In this example, the last date of the time zone GMT-05:00 is
02.04 01:59 and the last date of the time zone GMT-04:00 is 29.10 02:00.
Example 3
When time zone definitions in the northern hemisphere are set to summer daylight
saving, the time zone definition in the southern hemisphere are set to winter. Sydney
(time zone SYD), in New South Wales, Australia, is defined in winter time as follows:
This syntax means that from 25 of March 03:00 until 01 of October 02:00 the time zone
will be GMT+09:00 (winter time zone) and during all other dates it will be
GMT+10:00 (summer time zone).
NOTE
While TimeZone.dat files are used by both CONTROL-M/Server and CONTROL-M/EM, as
of 6.3.01 these files are no longer equivalent. The TimeZone.dat file in CONTROL-M/EM
contains only standard time zone parameters, and does not contain daylight saving
parameters. However, when specifying time zones, use the same names in both
CONTROL-M/Server and CONTROL-M/EM.
NOTE
If your data center includes multiple time zones, you may need to adjust the time zone
configuration file to reflect the different offsets that result from a switch to or from daylight
saving time. This adjustment is especially important because the switch to daylight saving
time is often not made on the same date in each time zone.
For more information about how to change time zone offsets, see “Adding and modifying
time zone definitions” on page 54.
■ Shout messages that are scheduled before 02:00 A.M. do not require any action.
■ Shout messages that are scheduled between 02:00 A.M. and 03:00 A.M. will be
issued, even though there may not be a delay in production because the time frame
for production is smaller.
■ The above information also applies to jobs that have Shout messages scheduled at
a later time (for example, 06:00 A.M.). These jobs might be considered late because
of the tighter production time frame.
Time-dependent schedules
■ FROM UNTIL
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 02:15 A.M. and an UNTIL value of 02:45 A.M. might not be submitted at all.
These jobs should be manually adjusted.
■ Cyclic Jobs
The next run of cyclic jobs with an interval of more than one hour runs one hour
sooner than it was scheduled. Cyclic jobs with an interval of less than one hour run
immediately. A cyclic job may have to be deleted and then resubmitted to continue
the processing cycle during the current day.
The CONTROL-M/Server log file will not contain entries with timestamps between
02:00 A.M. and 03:00 A.M. Any scripts or programs that rely on log entry time should
be checked for possible discrepancies as a result of advancing the clock.
■ If the New Day procedure starts before 01:00 A.M., 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 01:00 A.M., computer time should not
be turned back to 01:00 A.M. to avoid another New Day process. A second New
Day procedure requires manual intervention. It is advisable to wait until
02:01 A.M., for example, and turn the clock back to 01:01 A.M.
■ If the New Day procedure is scheduled to begin between 01:00 A.M. and
02:00 A.M., do one of the following actions:
— 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.
For example, if the New Day time is 01:45 A.M., the clock should be moved back
one hour at no later than 01:44 A.M. If the shift was not done by 01:44 A.M., the
user should wait until 02:46 A.M. and then shift the time back.
■ If the New Day procedure is scheduled to begin after 02:00 A.M., no special action
should be taken.
Shout messages scheduled between 01:00 A.M. and 02:00 A.M. might be issued twice.
Time-dependent schedules
■ FROM UNTIL
No special action should be taken for jobs with FROM-UNTIL or cyclic schedules.
Jobs scheduled to start between 01:00 A.M. and 02: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.
■ Cyclic Jobs
The next run of cyclic jobs run one hour later than it was scheduled.
The CONTROL-M/Server log file might 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:
— cleaning up old and unnecessary log files from the proclog directory
Heartbeat monitor
CONTROL-M/Server contains an integral Heartbeat monitor that verifies that
TCP/IP communication with CONTROL-M/EM is functional and that
CONTROL-M/EM is responsive to messages from CONTROL-M/Server.
This feature complements the CONTROL-M/EM Heartbeat monitor that verifies that
communication with CONTROL-M/Server is functional and that
CONTROL-M/Server is responsive to messages from CONTROL-M/EM.
The CONTROL-M/Server Heartbeat monitor uses the following parameters that are
contained in the ~<controlm_owner>/ctm_server/data/config.dat file.
Example
CTM_PRM_KPA_ACTIVE Y
CTM_PRM_KPA_BETWEEN_MSGS 300
CTM_PRM_KPA_ROUNDTRIP_TIMEOUT 300
■ contingency planning for the possibility of failure of the server computer or the
CONTROL-M/Server database
■ writing diagnostic files when the diagnostic level setting is greater than zero
For more information, see “Setting event log parameters” on page 65.
Log file size monitor the size of log files. Save files that exceed a specified size to a
monitor new version of the file
■ IOALOG events
These events are analogous to ctmlog events and involve reading and writing to
the IOA database.
■ DBASE events
These events are associated with database access and involve reading and writing
to the CONTROL-M/Server database.
CONTROL-M generates log entries when an event matches the logger parameters
that are specified in the config.dat file relating to severity and category. The
keywords in the parameter that are 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.
~<controlm_owner>/ctm_server/proclog/logger
NOTE
If 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 66.
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}
Example
To record IOALOG events with a severity of WARNING and ERROR, include the
following text in the config.dat file:
CONTROL-M monitors the size and generation number of diagnostic log files by
using parameters in the ~<controlm_owner>/ctm_server/data/config.dat file. Use the
parameters described below to specify the file size and number of file generations for
diagnostic log files. If these parameters are changed, CONTROL-M/Server must be
shut down and restarted for the changed values to become effective.
NOTE
If no values are specified, no limits are placed on the size of the log files.
If values are specified, the size of log files is checked. When the limit is reached, the
file is renamed (for example, logger.1). Entries continue to be saved in the default
logger file. When the file next reaches its limit, if is renamed logger.2, and so on, until
the specified number of generations is reached. The oldest file is deleted if the next
log file exceeds the generation limit.
To set size and generation limits, specify the following parameters in the config.dat
file.
OS_DIAG_LIMIT_LOG_FILE_SIZE <file-size>
OS_DIAG_LIMIT_LOG_VERSIONS <number>
Example
To set a limit for the size of the diagnostic log file to 10 MB and to limit the number of
generations of the diagnostic log file to 3, specify the following parameters in the
config.dat file:
OS_DIAG_LIMIT_LOG_FILE_SIZE 10
OS_DIAG_LIMIT_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.
The stack trace is output to a proclog file, providing information about the process
that aborted. The log file that is generated contains information relevant to Technical
Support and is located in:
~<controlm_owner>/ctm_server/proclog/<process_name>.<proc_ID>
The variables in this command line are described in the following table:
Example
~<controlm_owner>/ctm_server/proclog/CS_LOG.6509
Watchdog facility
CONTROL-M/Server contains a special Watchdog (WD) facility that automatically
monitors essential CONTROL-M/Server processes and resources. This facility sends
an appropriate alert when it detects a problem. The Watchdog facility can also be
used to execute user-defined scripts or CONTROL-M/Server utilities automatically.
See Chapter 3, “Utilities.”
Certain parameters in the config.dat file indicate general information about the
Watchdog facility. These parameters are listed in Table 10.
Heartbeat check
A special heartbeat check runs automatically when the Watchdog facility is enabled.
This utility checks that all the primary CONTROL-M/Server 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.
■ Exit 1
This utility runs 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 3, “Utilities,” for a complete description.
■ Exit 2
This utility runs a Database Usage utility to check data and log usage in the
CONTROL-M/Server database and sends an error message if it is above a
specified percentage. See ctmdbspace in Chapter 3, “Utilities,” for a complete
description.
The parameters for these two built-in Watchdog system exits are described in
Table 12.
Table 13 describes all parameters that can be defined for each user exit of the
Watchdog facility.
Example
Error handlers
If a Watchdog facility check fails, the error message that is 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 by using
the parameters in the config.dat file described in Table 14.
NOTE
Error messages are sent automatically to the CONTROL-M IOALOG and PROCLOG.
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 the 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/Server 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 15 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.
Language capabilities
Starting with version 6.3.01, CONTROL-M supports two foreign language modes:
This is automatically set during installation to Latin1 (default) and must be changed
manually. Information about CONTROL-M/Agent language support is found in the
CONTROL-M Language and Customization Guide.
3
3 Utilities
General maintenance can be performed by using the utilities that are described in this
chapter. Some of these utilities generate reports that are useful for managing the data
center and for planning job processing definitions and calendars.
NOTE
Many of these utilities are intended for use by the CONTROL-M/Server administrator. Because
they require extensive authorization, they might not work if submitted by a regular user.
All utilities that are described in this chapter are included with CONTROL-M/Server.
These utilities are run from either the system prompt or submitted as jobs (except
where noted).
NOTE
When CONTROL-M/Server and CONTROL-M/Agent are installed on the same account on
the same computer, CONTROL-M/Server utilities will run as default. To run an agent utility,
specify the full path name of the utility. [UNIX]
Utilities that can be submitted as jobs can also be defined as CONTROL-M jobs,
which enables you to utilize the CONTROL-M/Server job handling features such as
automatic scheduling and the use of AutoEdit variables (see examples in this
chapter). See “Accessing utilities from other users” on page 85 before using this
feature.
NOTE
Refer to Table 17 on page 80 to determine which subsystems must be active before invoking a
CONTROL-M utility.
Table 16 on page 78 lists the available utilities. Detailed information about each utility
is provided later in this chapter.
Chapter 3 Utilities 77
Table 16 CONTROL-M utilities (part 1 of 3)
Utility Description
ctm_agstat Lists or updates the status of an agent.
ctm_backup_bcp Exports data from a CONTROL-M/Server database.
ctm_diag_comm Generates a report about the connection details of the specified
CONTROL-M/Agent and remote host computers.
ctm_restore_bcp Imports data to a CONTROL-M/Server database.
ctm2snmp Sends messages to Network Management applications by using SNMP
traps [UNIX only]
ctmagcln Sends a request to all available CONTROL-M/Agents, or to a specified
agent, to remove all SYSOUT files and exit status files that are no longer
needed.
ctmcalc_date Calculates the date a job can be ordered, after adding or deducting a
specified number of days.
ctmcheckmirror Checks and displays the mirroring status of the CONTROL-M/Server
database.
ctmcontb Performs operations on the Prerequisite Conditions table.
ctmcpt Registers a user in the CONTROL-M/Server product registry database.
[Windows only]
ctmcreate Creates a job in the Active Jobs file.
ctmdbbck Backs up the CONTROL-M/Server database.
ctmdbcheck Checks CONTROL-M/Server database integrity and displays data
about database memory utilization.
ctmdbmused Displays the size of a CONTROL-M/Server database data and log plus
the amount and percentage of space currently used in each part.
ctmdbopt Calculate database statistics.
ctmdbrst Restores the CONTROL-M/Server database.
ctmdbspace Checks data and log usage in the CONTROL-M/Server database.
ctmdbtrans List the active transactions in the database.
ctmdbused Displays the size of the CONTROL-M/Server database data and log,
plus the amount and percentage of space currently used in each part.
ctmdefine Defines a job in the CONTROL-M/Server 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/Server database to an ASCII file in either ctmcreate
or ctmdefine format.
ctmfw Detects the successful completion of a file event processing.
ctmgetcm Collects and displays CONTROL-M/Agent application information.
ctmgrpdef Creates a definition for a new Group Scheduling table.
ctmhostmap Manages the mapping of remote host computers to agents and the
conversion of CONTROL-M/Agents to remote host computers.
ctmjsa Accumulates statistical data and records the data in the Statistics
Summary table in the CONTROL-M/Server database.
Chapter 3 Utilities 79
Utility reference table
Chapter 3 Utilities 81
Utility reference table
Chapter 3 Utilities 83
-input_file parameter
-input_file parameter
Parameters for CONTROL-M/Server utilities can be specified on the command line.
The maximum length for all parameters in a utility command line is 2000 characters.
When invoking the utilities listed in Table 19, you can include an -input_file
parameter that identifies a file containing the parameters for the utility. In this file,
each parameter and its values (if any) are on a separate line with the same syntax they
would have on the command line.
For more information about this parameter, see the descriptions of the utilities in
Table 19.
■ temp
■ proclog
■ prflag
CONTROLM_SERVER
CONTROLM_USER
CONTROLM_DATABASE
CONTROLM_MIRROR_USER
CONTROLM_MIRROR_DATABASE
CTM_DATABASE_TYPE
MIRROR_DB_SERVER
machine
LIBPATH, or LD_LIBRARY_PATH, or SHLIB_PATH
Table 20 lists additional environment variables that are required, according to the
type of database.
Chapter 3 Utilities 85
For users on UNIX
Specify the following command for each variable from the controlm user:
echo $<variable-name>
Example
echo $SYBASE
Use the following formats to define the shared library path variables in the user
environment, depending on the server computer type:
Chapter 3 Utilities 87
For users on UNIX
Sybase example
Oracle example
When using other shells (for example, sh, ksh), specify the following command for
each variable:
Sybase example
Oracle example
~<controlm_owner>/ctm_server/scripts
Use the following command to modify the path when using csh or tcsh:
For Sybase
For Oracle
Example
Use the following command to modify the path when using other shells (for example,
sh, ksh):
PATH="$PATH: ~<controlm_owner>/ctm_server/exe_<OS_ID>"
Example
PATH="$PATH: ~<controlm_owner>/ctm_server/exe_HP-UX-11"
Chapter 3 Utilities 89
For users on UNIX
■ All users who require access to CONTROL-M utilities should belong to group
controlm.
Utilities
ctm_agstat
The ctm_agstat utility enables you to list or update the status of an agent, or to delete
an inactive agent. (See “Communication status of agents and remote hosts” on page
25.)
ctm_agstat
{ -LIST <agentName> | -UPDATE <agentName> {AVAILABLE | DISABLED} }
[ -DEBUG <debug level 1-5> ]
[ -QUIET ]
Note:
■ this parameter is mandatory if the -LIST parameter is not
specified
■ the permissions of the AGSTAT directory must be modified to
allow access to users who will run the ctm_agstat utility with
the -UPDATE parameter
<agentName> Host name of the agent to be listed or updated.
This name must be specified for -LIST and
-UPDATE parameters.
AVAILABLE Status where CONTROL-M/Server is able to
communicate with the specified
CONTROL-M/Agent.
DISABLED Status where CONTROL-M/Server ignores
(does not attempt to communicate with) the
specified CONTROL-M/Agent.
Chapter 3 Utilities 91
ctm_agstat
Examples
ctm_backup_bcp
The ctm_backup_bcp utility exports data from a CONTROL-M/Server database to
the ~<controlm_owner>/ctm_server/backup_db directory. Each database table is backed
up as a separate ASCII file.
NOTE
The user running the ctm_backup_bcp utility must have access permission to create the
directory bcp_backup.
ctm_backup_bcp [-n]
-n runs the utility in silent mode. In this mode, confirmation prompt and “backing
up contents” messages are not displayed.
■ 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.
Chapter 3 Utilities 93
ctm_backup_bcp
Example 1
ctm_backup_bcp
Backing up contents of database
Please confirm [y/n] : Y
Example 2
ctm_backup_bcp -n
In this case, CONTROL-M/Server does not display the confirmation prompt and
does not issue messages. Only progress dots are displayed.
ctm_diag_comm
The ctm_diag_comm utility generates a report about the connection details between
the specified CONTROL-M/Agent or remote host and CONTROL-M/Server. You
can either specify the host name of a computer where CONTROL-M/Agent is
installed, or the host name of a computer with which you want CONTROL-M/Server
to communicate.
ctm_diag_comm
You are prompted for the host name of the CONTROL-M/Agent or remote host.
Example
Assume that CONTROL-M/Server is installed on the UNIX computer with host
name taurus. CONTROL-M/Agent has not yet been defined in the
CONTROL-M/Server database, so when ctm_diag_comm is invoked, it will try to
generate a report connecting it as an agent or remote host. The report below is
displayed after invoking the following command: ctm_diag_comm mars
Chapter 3 Utilities 95
ctm_diag_comm
ctm_restore_bcp
The ctm_restore_bcp utility imports the CONTROL-M/Server database from the
bcp_backup directory. The content of this directory was created by the
ctm_backup_bcp utility.
ctm_restore_bcp [-n]
-n runs the utility in silent mode. In silent mode, the confirmation prompt and
restoring contents messages are not displayed.
■ When using ctm_restore_bcp, you cannot specify the directory containing the
exported files.
Chapter 3 Utilities 97
ctm_restore_bcp
Example 1
ctm_restore_bcp
Restoring contents of database.
This procedure DELETES any information in main database
Please confirm [y/n]: y
Example 2
ctm_restore_bcp -n
In this case, CONTROL-M/Server does not display the confirmation prompt and the
“restoring contents” messages. Only progress dots are displayed.
ctmagcln
The ctmagcln utility sends a request to all available CONTROL-M/Agents, or to a
specified CONTROL-M/Agent, to remove all SYSOUT files and exit status files that
are no longer needed. This utility should run while CONTROL-M/Server is up and
running. The files that are no longer needed are determined according to the
Maximum Days to Retain Sysout Files parameter. For more information, see
“Max.Days to Retain Sysout Files *” on page 367.
The New Day procedure can request that Agents remove SYSOUT files and exit
status files that are no longer needed. In an environment with multiple Agents, it can
take a long time to send the cleanup request to the Agents during New Day. BMC
Software recommends that you use the AGENTS_CLEANUP_IN_NEWDAY
configuration parameter to disable this action during the New Day procedure, and
instead use the ctmagcln utility. For more information, see
“AGENTS_CLEANUP_IN_NEWDAY” on page 386.
The ctmagcln utility can be run as a daily job. A message is added to the IOALOG
when the cleanup of the Agents has ended.
NOTE
BMC Software recommends running ctmagcln as soon as possible after the New Day
procedure is complete.
Chapter 3 Utilities 99
ctmagcln
Example 1
The following command requests that all Agents remove SYSOUT files and exit
status files that are no longer needed.
Example 2
The following command requests that the specified agent, saturn, removes SYSOUT
files that have already been retained for two days, and removes all exit status files
that are no longer needed.
ctmcalc_date
The ctmcalc_date utility calculates the date that a job can be ordered after adding or
deducting a specified number of days. You can specify whether the calculated date
can be any day of the week or must be a work day.
Example 1
Issue the following command to display the calculated scheduling date that the
prodyjob job in the Production scheduling table will be ordered if its scheduling
criteria are met, if two days are added to the original scheduling date of the job,
August 02, 2005:
20050804
Example 2
As in Example 1, displaying the calculated scheduling date and indicating if the job
will be scheduled:
20050804 Y
Example 3
ctmcheckmirror
The ctmcheckmirror utility checks the mirroring of the CONTROL-M/Server
database and displays the status.
ctmcheckmirror
■ Mirroring is enabled.
■ Mirroring is disabled.
■ Mirroring is damaged.
For more information about database mirroring, see “Database Mirroring menu” on
page 338.
ctmcontb
The ctmcontb utility performs the following operations on prerequisite conditions in
the CONTROL-M/Server database:
The following special characters are disabled when they occur in prerequisite
condition names:
( open parenthesis
) close parenthesis
| vertical bar
space
■ When using both open and closed square brackets ([ and ]),
the condition name must be enclosed in quotation marks (for
example, “RATE[A1]”).
■ When using both open and closed square brackets ([ and ]),
the condition name must be enclosed in quotation marks (for
example, “RATE[A1]”).
■ When using both open and closed square brackets ([ and ]),
the condition name must be enclosed in quotation marks (for
example, “RATE[A1]”).
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 next year (0101) up to the To Date.
<outputFileName> For Listing
Displays 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 (the terminal).
<fullPathFileName> Displays the name and full path of a file containing parameters for
the utility. In this file, each parameter and its values (if any) are on
a separate line with the same syntax they would have on the
command line. Using the -input_file parameter enables you to:
Example 1
Example 2
The following command deletes all prerequisite conditions with prefix a and
condition dates between December 1 and December 15 inclusive:
Example 3
The following command deletes the prerequisite condition aa* with condition date
ODAT:
Example 4
Example 5
The following command lists the prerequisite condition named aa* with all its dates.
Example 6
Conditions list
CONDNAME CONDDATE
APR01-L20 0629
APR01-L20 0630
ARD01-L30K 0630
LVL11-LVL22 0628
LVL11-LVL22 0629
LVL11-LVL22 0630
PKR11-LVL01 0630
Example 7
Example 8
This example illustrates ctmcontb input and output when using the -XML option.
ODAT automatically generates the CONTROL-M/Server system date that, in this
example, was March 15th.
ctmcpt
The ctmcpt utility registers a user in the CONTROL-M/Server product registry
database. The Shout to E-Mail facility requires that CONTROL-M/Server be running
as either a service or a program under the account of a user who is registered in the
CONTROL-M/Server product registry database. [Windows only]
Specify the following command to register a user for the first time:
Specify the following command to change the password for a user who is already
registered:
Example 1
The following command registers new user user1 with password default:
Example 2
The following command changes the password for user1 from default to do2day:
ctmcreate
The ctmcreate utility is an API (Application Program Interface) that allows a specific
purpose job to be inserted directly into the Active Jobs file. The job does not have to
be defined in the CONTROL-M/Server database. The function performed by this
utility is equivalent to the Force function in CONTROL-M/EM.
The ctmcreate utility can be used to create a specific purpose (nonpermanent) group
that is not defined in the CONTROL-M/Server database by specifying
ctmcreate
-TASKTYPE <JOB|EXTERNAL|DETACHED|COMMAND|DUMMY|GROUP>
[ -GROUP <groupName> ]
[ -APPLICATION <applicName> ]
[ -DEBUG <debug level 0-5> ]
[ -QUIET ]
[ -GROUP_ORD <grpOrderNo|ALONE|LAST> ]
[ -ADJUST_COND Y|N ]
[ -MULTIAGENT Y|N ]
[ -NODEGRP <name> ]
[ -MEMLIB <path> ]
[ -MEMNAME <filename> ]
[ -CMDLINE <string> ]
[ -JOBNAME <name> ]
[ -SCHEDTAB <name> ]
[ -OWNER <username> ]
[ -AUTHOR <username> ]
[ -ODATE <date>|ODAT ]
[ -ODATE_OPTION VALUE_DATE|RUN_DATE ]
[ -MAXRERUN <value> ]
[ -TIMEZONE <xxx> ]
[ -TIMEFROM <earliestSubmissionTime> ]
[ -TIMEUNTIL <latestSubmissionTime> | '>' ]
[ -PRIORITY <jobPriority> ]
[ -CRITICAL Y|N ]
[ -CYCLIC Y|N ]
[ -CONFIRM Y|N ]
[ -TASKCLASS DISTRIBUTION|DECOLLATION ]
[ -APPLTYPE <agentApplication> ]
[ -APPLVER <applicationVersion> ]
[ -CMVER <CMversion> ]
[ -APPLFORM <applicationForm> ]
[ -INTERVAL <45d(days) | 1080h(hours) | 64800m (minutes)> ]
[ -INTERVALFROM START | END | TARGET ]
[ -OVERLIB <alternativeDirectory> ]
[ -MAXWAIT <days> ]
[ -DESCRIPTION <string> ]
[ -DOCMEM <filename> ]
[ -DOCLIB <directoryName> ]
[ -INCOND <condition> <dateref>|ODAT AND|OR ]
[ -OUTCOND <condition> <dateref>|ODAT ADD|DEL ]
[ -AUTOEDIT <varname> <expression> ]
[ -QUANTITATIVE <name> <quantity> ]
[ -SYSOUT RELEASE|DELETE|COPY|MOVE [<parameter>]]
[ -CONTROL <name> E|S ]
[ -SHOUT OK|NOTOK|RERUN|LATESUB|LATETIME|EXECTIME
<destination> <urgency R|U|V> <message> [<time>] ]
[ -ON <statement> <code>
[ -DOOK ]
[ -DONOTOK ]
[ -DORERUN ]
[ -DOSHOUT <destination> <urgency R|U|V> <message> ]
[ -DOCOND <condname> <dateref>|ODAT ADD|DEL ]
[ -DOAUTOEDIT <varname> <expression> ]
[ -DOFORCEJOB <tablename> <jobname> <odate>|ODAT ]
[ -DOSYSOUT RELEASE|DELETE|COPY|MOVE [<parameter>] ] ]
[ -DOSTOPCYCLIC ]
[ -DOMAIL <destination> <cc> <urgency R|U|V> <subject> <message>]
[ -DOREMEDY <summary> <description> <urgency L|M|H|U|C>
The ctmcreate utility can be invoked by using the -input_file parameter, as follows:
Most of the parameters listed above are described in the CONTROL-M Job Parameter
and Variable Reference Guide.
Parameters that are specific for this utility are described in Table 29.
Example:
-input_file ~<controlm_owner>/ctm_server/data/ctmcreate_parms.txt
Table 30 lists each parameter available for the utility and the name by which the
parameter appears in the CONTROL-M Job Parameter and Variable Reference Guide.
Syntax
The following syntax rules apply when using this utility:
■ The odate parameter 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 system
date.
■ The length of the command line, after decoding, must not exceed 999 characters.
■ All parameter fields (as specified in the syntax on page 111) must contain values. If
no value is desired, specify a null string "" in the relevant position in the parameter
specification. For example:
To specify this command without a value for the cc field, include a null string in
the appropriate location. For example:
■ If a parameter value begins with a $ sign, the operating system will try to replace
the value. For example, -jobname $USER will cause the shell to substitute the
current user. If a parameter value should contain a $ sign, enclose the value in
single quotation marks. For example, -jobname 'test$' will set the jobname
parameter to test$.
■ An AutoEdit variable that does not contain a $ sign can be enclosed in single or
double quotation marks. An AutoEdit variable that does contain a $ sign should be
enclosed in single quotation marks. An AutoEdit variable containing a $ sign
cannot be resolved if it is enclosed in double quotation 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).
The following special characters are disabled when they occur in prerequisite
condition names:
( open parenthesis
) close parenthesis
| vertical bar
space
■ -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 NOTOK status. To ensure that the job will have OK status 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 quotation marks (that is, “ ”).
■ When the ctmcreate utility is invoked from a script, to use the **** option for a
-incond date parameter, specify the 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.
Example 1
-memlib "~/controlm/scripts/"
Example 2
The following command contains the minimum parameters required to create a job in
the Active Jobs file:
You can get the same result by using the -input_file parameter as follows:
-tasktype command
-group em
-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:
ctm2snmp
The ctm2snmp utility enables you to send messages to various Network Management
applications (for example, HP-OpenView, NetView for AIX, and Tivoli Management
Environment Console) using SNMP traps. See the SNMP Interface appendix in the
CONTROL-M/Enterprise Manager Guide for a description of SNMP traps. [UNIX only]
SNMP traps issued using CONTROL-M consist of the fields described in Table 31.
■ 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.
■ 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_owner>/ctm_server/config.dat file. The default
is Single Variable (S) format. For more information, see “Configuration
parameters” on page 385.
■ The following entry must be added to the /etc/services/ file (if not already present):
snmp-trap 162/udp # snmp monitor trap port
Use CTMS_4D and 1.3.6.1.4.1.954.6 for the CONTROL-M/EM name and MID.
Edit all the described file entries replacing ECS with CTMS.
ctmdbbck
The ctmdbbck utility backs up the CONTROL-M/Server database in the following
cases:
For information about Archive mode and backup types (Hot backup and Cold
backup), see “Archive mode” on page 329.
NOTE
When using Oracle, after specifying this utility you are prompted to enter the DBA password
to access the CONTROL-M/Server database.
ctmdbbck
For Sybase or MSSQL – You are prompted for the backup device
(<backupDevice>). This device or path is where the backup will be stored. A list of
devices can be obtained by using the option List Backup Devices from the
Database Maintenance menu, see “List backup devices” on page 333.
■ the full path name of a file to be created by the backup procedure for Sybase or
MSSQL
NOTE
If no backup devices exist, or you want to use a new backup device, choose 6 - Add Backup
Device from the Database Maintenance menu. For more information, see “Database
Maintenance menu” on page 328.
If no device is specified for backup of a Sybase database, the default device will be used.
BMC Software does not recommend this option.
Example 1
ctmdbbck
Example 2
ctmdbbck controlm_data_bkp
ctmdbcheck
The ctmdbcheck utility displays information about the memory capacity and the
status of the CONTROL-M/Server database.
ctmdbcheck
The ctmdbcheck utility can also be used with the following syntax to monitor the
database and the transaction log:
NOTE
If 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/Server 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 that is used in
each component.
For example, if percent usage of either the data area or the transaction
log exceeds 80%, ctmdbcheck 80 triggers a Shout message).
ctmdbcheck output
The ctmdbcheck utility returns information about the CONTROL-M/Server
database. Table 34 describes the fields that are returned by this utility.
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 database status without specifying
any parameters (that is, no Shout messages will be issued for this run on the utility,
even if the database is over the desired threshold).
Utility input
ctmdbcheck
Example 2
Utility input
ctmdbcheck -d80
Message 'Warning: DB is more than 80% full', urgency 'U' NodeID 'linda'
– Shout to user 'EM' '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 Example 1 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 CONTROL-M/EM alert window.
Example 3
Utility input
ctmdbcheck -l80
This command is similar to Example 2 except that 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 specifies 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.
Example 5
Utility input
ctmdbcheck -d10
Example 6
Utility input
ctmdbcheck -d10
ctmdbmused
The ctmdbmused utility returns the size of a CONTROL-M/Server Master database
(Sybase only) and the percent used.
Syntax
ctmdbmused
Sample output
If the data used is more than 80% of the size of the CONTROL-M/Server Master
database, the utility output contains the message:
If the data used is more than 90%, the utility output contains the message:
NOTE
BMC Software recommends running this utility as a cyclic job that automatically generates an
appropriate Shout message if the utility output (SYSOUT) contains the phrase “DB near
capacity” or “DB free space”.
For more information about extending the database size, see “Database Maintenance
menu” on page 328.
ctmdbopt
The ctmdbopt utility calculates database statistics. This utility wraps the relevant
database packages that collect statistics on all CONTROL-M/Server database tables.
You can run this utility while CONTROL-M/Server is running.
BMC Software recommends that you run this utility on a daily basis, so that the
database optimizer has updated statistics.
Syntax
ctmdbopt
ctmdbrst
The ctmdbrst utility restores the CONTROL-M/Server database in the following
cases:
[UNIX only] After specifying this utility you are prompted to enter the DBA
password to access the CONTROL-M/Server database.
For information about Archive mode and backup types (Hot backup and Cold
backup), see “Archive mode” on page 329.
1 Shut down CONTROL-M/Server before invoking this utility. Make sure that no
other users or processes are connected to the SQL server.
ctmdbrst
For Oracle – the CONTROL-M/Server database is restored from the backup file in
the Oracle home directory.
For Sybase or MSSQL – you are prompted for the backup device
(<backupDevice>). This device was used to back up the CONTROL-M/Server
database. 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 by using the option List Backup
Devices from the Database Maintenance menu.
NOTE
If no device is specified for restoration of a Sybase database, the default device (tapedump2)
will be used. This option is not recommended.
Example
ctmdbrst
ctmdbspace
The ctmdbspace utility checks the data and log usage in the CONTROL-M/Server
database and displays the usage. The utility returns a “failed” status if the usage
exceeds the specified limit.
NOTE
ctmdbspace can be included in the CONTROL-M Watchdog process. See “Watchdog facility”
on page 69 for more information.
The <amount> variable is the maximum amount (percentage) of data and log usage
in the database. Use the optional -quiet parameter to suppress the display.
Example
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.
NOTE
After specifying this utility you are prompted to enter the DBA password to access the
CONTROL-M/Server database.
Specify the following command to see which transactions are active in the database:
ctmdbtrans
-or-
To run the ctmdbtrans utility in batch mode, specify the DBA password in a file, and
specify the following command:
<fullPathFileName> is the full path to the file in which the DBA password is specified.
ctmdbused
The ctmdbused utility displays the size (in KB), amount, and percentage of current
space usage in the CONTROL-M/Server database data and log.
ctmdbused
Example 1
Utility input
ctmdbused
Utility output
Example 2
Utility input
ctmdbused
ctmdefine
The ctmdefine utility is an API (Application Program Interface) that adds a job
processing definition to a Scheduling table, or creates a new Group Scheduling table
in the CONTROL-M/Server database. This utility can be used when converting job
scheduling information from other job control products to CONTROL-M/Server. The
function performed by this utility is equivalent to the manual process of creating job
processing definitions, described in the CONTROL-M/Desktop User Guide.
The ctmdefine utility can also be used to define jobs for specific applications, for
example, SAP and Oracle Applications (OAP). For more information, see “Defining
application-specific Jobs” on page 145.
NOTE
Group Scheduling tables can also be defined using the ctmgrpdef utility (described on page
page 165).
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, download
the modified Scheduling tables to the CONTROL-M/EM database.
■ A newly created Scheduling table can be assigned a User Daily parameter using
the CONTROL-M/EM GUI after the Scheduling table is downloaded to the
CONTROL-M/EM database or by 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 CONTROL-M/EM and CONTROL-M/Server
and are stored in the CONTROL-M/EM database. These values are initialized by
the ctmdefine utility and are sent to CONTROL-M/EM when the Scheduling table
is downloaded. When the Scheduling Table is uploaded, CONTROL-M/EM sends
these values to CONTROL-M/Server.
ctmdefine
-TABLE <name>
-JOBNAME <name>
-TASKTYPE <JOB|EXTERNAL|DETACHED|COMMAND|DUMMY>
-GROUP <groupName>
-APPLICATION <applicName>
[ -CMDLINE <string> ]
[ -MAXRERUN <value> ]
[ -CRITICAL Y|N ]
[ -CYCLIC Y|N ]
[ -INTERVAL <45d(days) | 1080h(hours) | 64800m (minutes)> ]
[ -INTERVALFROM START | END | TARGET ]
[ -OVERLIB <alternativeDirectory> ]
[ -RELATIONSHIP AND|OR ]
[ -MAXWAIT <days> ]
[ -NODEGRP <name> ]
[ -MEMLIB <path> ]
[ -MEMNAME <filename> ]
[ -MULTIAGENT Y|N ]
[ -ADJUST_COND Y|N ]
[ -OWNER <username> ]
[ -AUTHOR <username> ]
[ -DEBUG <debug level 0-5> ]
[ -QUIET ]
[ -TIMEZONE <xxx> ]
[ -TIMEFROM <earliestSubmissionTime> ]
[ -TIMEUNTIL <latestSubmissionTime> | '>' ]
[ -PRIORITY <jobPriority> ]
[ -CONFIRM Y|N ]
[ -TASKCLASS DISTRIBUTION|DECOLLATION ]
[ -APPLTYPE <agentApplication> ]
[ -APPLVER <applicationVersion> ]
[ -CMVER <CMversion> ]
[ -APPLFORM <applicationForm> ]
[ -DESCRIPTION <string> ]
[ -DOCMEM <filename> ]
[ -DOCLIB <directoryName> ]
[ -INCOND <condition> <dateref>|ODAT AND|OR ]
[ -OUTCOND <condition> <dateref>|ODAT ADD|DEL ]
[ -AUTOEDIT <varname> <expression> ]
[ -QUANTITATIVE <name> <quantity> ]
[ -SYSOUT RELEASE|DELETE|COPY|MOVE [<parameter>]]
[ -CONTROL <name> E|S ]
[ -SHOUT OK|NOTOK|RERUN|LATESUB|LATETIME|EXECTIME
<destination> <urgency R|U|V> <message> [<time>] ]
[ -ON <statement> <code>
[ -DOOK ]
[ -DONOTOK ]
[ -DORERUN ]
[ -DOSYSOUT RELEASE|DELETE|COPY|MOVE [<parameter>] ] ]
[ -DOSTOPCYCLIC ]
The debug, quiet, and input_file parameters are described in Table 35. All other
parameters are described in the CONTROL-M Job Parameter and Variable Reference
Guide.
Example:
-input_file ~<controlm_owner>/ctm_server/data/ctmdefine_parms.txt
Table 36 lists each parameter of the ctmdefine utility, and the name under which the
parameter appears in the CONTROL-M Job Parameter and Variable Reference Guide.
Example:
-group accgroup
■ For 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.
■ 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.
— 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
■ If a parameter value begins with a $ sign, the operating system will try to replace
the value. For example, -jobname $USER will cause the shell to substitute the
current user. If a parameter value should contain a $ sign, enclose the value in
single quotation marks. For example, -jobname ‘test$’ will set the jobname
parameter to test$.
■ An AutoEdit variable that does not contain a $ sign can be enclosed in single or
double quotation marks. An AutoEdit variable that does contain a $ sign should be
enclosed in single quotation marks. An AutoEdit variable containing a $ sign
cannot be resolved if it is enclosed in double quotation marks.
■ Condition dates are specified in mmdd format. Time is specified in hhmm format.
■ The default for the -month parameter is ALL Y, which means that if you want 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
EXAMPLE
On statement: *
Code: RUNCOUNT>4
Do Shout: To: CONTROL-M/EM
Text: “Job ran more than four times”
■ -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 139) 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
To specify this command without a value for the cc field, include a null string in
the appropriate location. For example:
■ Normally, when a -dorerun parameter is implemented, the current run of the job
ends with NOTOK status. To ensure that the job will have an OK status, 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 quotation marks (that is, “ ”).
For more information, see the description of the In Conditions parameter in the
CONTROL-M Job Parameter and Variable Reference Guide.
■ When ctmdefine is invoked from a script: To use the **** option for a -incond date
parameter, specify this parameter as “****”
■ Condition names using both open and closed square brackets ([ and ]) must be
enclosed in quotation marks (for example, “RATE[A1]”).
The following special characters are disabled when they occur in prerequisite
condition names:
( open parenthesis
) close parenthesis
| vertical bar
space
■ The -shift parameter has been extended to four characters (xyyy). The first
character (x) indicates how to shift scheduling of the job if the original scheduling
day of the job is not a working day in the CONFCAL calendar. Valid values are:
The remaining three characters (yyy) shift scheduling of the job forward or
backward the specified number of working days, as defined in the CONFCAL
calendar. Valid values are:
NOTE
■ If the result of shifting by yyy days is a day that is not allowed (-n was entered for that day
in the DAYS parameter), the job is shifted to the next working day (for a forward shift), or
to the previous working day (for a backward shift).
■ If the original scheduling day of the job is a working day in the CONFCAL calendar, the x
value is ignored and the yyy value determines when the job is scheduled.
■ If the original scheduling day of the job is not a working day in the CONFCAL calendar,
job scheduling is shifted according to the x value and then shifted again according to the
yyy value (if specified) to determine when the job is scheduled.
■ If the original scheduling day of the job is not a working day in the CONFCAL calendar,
and no value (blank) is specified for the x value, the job is not scheduled, and the yyy
value (if specified) is ignored.
■ Confcal and Shift parameters are applied to a scheduling date only if that date already
satisfies the Basic Scheduling criteria as specified in the Days, Months, Dates, and
Weekdays parameters.
Example 1
The following command contains the minimum parameters required to define a job:
You can get the same result by using the -input_file parameter as follows:
-table cmmnds
-jobname cmls13
-tasktype command
-group em
-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:
The -memname and -memlib parameters must also be specified for the ctmdefine
utility when defining application-specific jobs.
Example:
ctmdiskspace
The ctmdiskspace utility 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.
NOTE
More 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%:
Example 2
The following command returns a “failed” status if the amount of free disk in the
CONTROL-M user directory is below 20M:
ctmexdef
The ctmexdef utility exports job processing definitions from the
CONTROL-M/Server database to a flat (ASCII) file. This file can then be used as
input for either the ctmcreate utility or the ctmdefine utility.
■ 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/Server database by
using ctmdefine. For more information, see “ctmdefine” on page 136.
■ Creating specific purpose 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 that can then be sent
directly to the Active Jobs file by using ctmcreate. See “ctmcreate” on page 111 for
a complete description of the utility.
ctmexdef
-TABLE <name>
-JOBNAME|-MEMNAME <name>
[ -ACTION <DEFINE|CREATE> ]
[ -FILE <filename> ]
Table 38 ctmexdef parameters
Parameter Description
-TABLE Scheduling table containing the job processing definition.
name Name of the table or of the job. Either the JOBNAME or MEMNAME
parameter is required.
-MEMNAME Mem name of the job.
DEFINE The exported file will be in ctmdefine format. Default.
CREATE The exported file will be in ctmcreate format.
filename 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.
The <jobname> and <memname> parameters can include the following mask
characters:
Example
To export all job processing definitions from Scheduling table PROD to file tabprod,
specify the following command:
ctmfw
The ctmfw (CONTROL-M File Watcher) utility detects the following file processes:
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.
The ctmfw utility runs as a process on a client computer. The process waits for the
creation or deletion of specified files.
■ 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 finishes
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, file size is ignored if a wildcard is specified as part of the file name
unless the mon_size_wildcard parameter is set to Y.
■ 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, or be invoked to detect
either a single file or multiple files.
Usage as a service
As a service, ctmfw takes its parameters (rules) during startup from the rull.dat file
whose full path name is specified in <CONTROL-M/Agent>\data\ctmfw.cfg.
To change one or more rules, change the contents of the rull.dat file or specify the full
path name of a different file.
NOTE
The rull.dat file provided with CONTROL-M/Agent is a sample file and should be changed
to reflect your requirements.
The full path name to the ctmfw.cfg configuration file must be specified under the
following Microsoft Windows registry key that is generated automatically by the
installation script:
HKEY_LOCAL_MACHINE\SOFTWARE\BMC Software\
CONTROL-M/FileWatcher\SYSPRM\File Watcher
Configuration File
<CONTROL-M/Agent_install_directory>\DATA\ctmfw.cfg
NOTE
BMC Software recommends that this default value not be changed.
The variable <ruleFileName> is the full path name of a rule file containing the File
Watcher rules. Figure 2 shows a sample rule file.
Network resources
The FileWatcher service running under the local system account cannot detect
network resources (files located on remote systems). If you want the File Watcher to
detect network resources, configure the FileWatcher Service to run under a regular
user account.
When running as a service, ctmfw generates an execution log file. This file is saved in
the CONTROL-M/Agent proclog directory under the following name:
U_CTMFW_<process_id>.log
By default, logs in the proclog directory are retained for three days. If the “maximum
days to retain sysout” parameter is set to a number higher than 3, logs are retained for
the number of days specified in that parameter.
2002/03/10 13:04:24 182 FW:File 'test' has reached the minimum size of 4.
size=265 bytes id=1.
2002/03/10 13:04:24 182 FW:File 'abc' does not exist. id=3.
2002/03/10 13:04:36 182 FW:File transfer was completed. The size of file 'test'
is 265. id=1.
2002/03/10 13:04:36 182 FW:Executing:<ctmcontb add 'aaa' '0101'>
2002/03/10 13:05:09 182 FW:Executing:< dir >
2002/03/10 13:05:27 182 FW:File 'prd' was not CREATED within the time limit.
id=2.
2002/03/10 13:05:27 182 FW:File prd will be scanned at 1315. id=2.
2002/03/10 13:05:27 182 FW:File 'abc' was not DELETED within the time limit.
id=3.
2002/03/10 13:05:27 182 FW:File abc will be scanned at 1315. id=3.
2002/03/10 13:05:30 182 FW:File prd, is out of time window. next time:1315, id=2.
2002/03/10 13:05:30 182 FW:File abc, is out of time window. next time:1315, id=3.
2002/03/10 13:15:01 182 FW:File prd, entered the time window from '1315' for
monitoring, id=2.
2002/03/10 13:15:01 182 FW:File abc, entered the time window from '1315' for
monitoring, id=3.
Usage as a utility
When running as a utility, ctmfw is invoked from the command line. Rules can be
provided on the command line or by a rule file.
ctmfw
< mode (CREATE|DELETE)> Default: CREATE
< minimum detected size <number>
[' '|Bytes(B)|Kilo(K)|Mega(M)|Giga(G)] >Default:0
< interval between file search (seconds) > Default: 60sec
< interval between filesize comparison iterations (seconds) >
Default: 10sec
< number of iterations while the size is static > Default: 3 iterations
< time limit for the process (minutes). Default: 0 (no time limit)
Effective while the file does not exists or,
the file size is static and the minimum size
was not reached >
< monitor file size when wildcard is used > Default: N
< starting time for detecting files (HHMM or YYYYMMDDHHMM >
Default: NOW
< absolute stop time (HHMM or YYYYMMDDHHMM > Default: 0 ( No stop time )
< minimal age of file ( modified time )
format:xxxxYxxxxMxxxxDxxxxHxxxxMin > Default: 0
All parameters must be assigned a value, even if that value is zero. If only six values
are specified, the default value for mon_size_wildcard is used. If five parameters are
specified, default values for wait_time and mon_size_wildcard are used, and so
forth.
EXAMPLE
ctmfw /home/watchedfile.txt CREATE 100 10
Note: The path and file name must not exceed 214 characters.
■ N, the ctmfw utility will end OK after detection of the first file that
matches the specified mask.
■ Y, the ctmfw utility will end OK after detection of the first file that
matches the filename and file size.
For more information about monitor file size when wildcard is used, see
below.
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.
minimum detected Minimum file size in bytes. This parameter is ignored if the FILE parameter contains
size wildcards (unless the monitor file size when wildcard is used parameter is set to Y) or
if the mode parameter is set to DELETE. Default: 0 (any size detected).
interval between file Interval between successive attempts to detect the existence/deletion of a file (in
searches seconds). Default: 60
interval between Interval between attempts to monitor the size of a file after it is detected (in seconds).
filesize comparison This parameter is ignored when using wildcards in FILE or when using DELETE
iterations mode. Default: 10
number of iterations Number of attempts to monitor file size where the size remains static and greater than
while size is static or equal to minimum detected size (indicating successful creation of the file). This
parameter is ignored when using wildcards in FILE or when using DELETE mode.
Default: 3
time limit for the Maximum time (in minutes) to run the process without detecting the file at its
process 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 42 on page 161. Default: 0 (no time limit).
monitor file size Indicates whether file size should be monitored if the filename contains wildcards.
when wildcard is This parameter is ignored if the filename does not contain a wildcard. Valid values:
used
N – do not monitor file size. Default.
Y – monitor the file size.
If this parameter is set to Y and more than one file matches the specified mask, the
ctmfw utility randomly selects one matching file, monitors its file size, and ignores all
other matching files.
The following procedure ensures that File Watcher job parameters (in the File
Watcher panel) are displayed in the Job Editing form in CONTROL-M/EM and
CONTROL-M/Desktop.
NOTE
The procedure to import the File Watcher panel is relevant only if ctmfw is run as a job.
2 Navigate to the Forms directory on the installation CD. Select the FileWatch.xml file
and click Import.
3 Shut down the CONTROL-M/Enterprise Manager GUI, and then restart it. This
enables the newly imported File Watcher panel functionality.
For more information about the parameters in the File Watcher panel, see Table 39
on page 152. For more information about the Job Editing form, see the
CONTROL-M/Enterprise Manager User Guide.
NOTE
The path and file name must not exceed 214 characters
Use the following command to invoke the ctmfw utility for multiple files:
The variable <ruleFileName> is the complete path name of the file containing the
definitions for each file to be detected.
■ # indicates comments.
■ Default values are shown for all global parameters.
■ <action> refers to any of the actions described in Table 41.
# ON_FILEWATCH statements
ON_FILEWATCH <filename>(absolute path) [CREATE/DELETE] [min_size] [min_detect]
[wait_time]
[start_time] [cyclic_interval] [wildcards] [minimal_file_age]
THEN
<action>
ELSE
<action>
END_ON
#******************************************************************
If a wildcard is used in the file name, the found file can be referenced as
%FILENAME%.
EXAMPLE
INTERVAL 10
ON_FILEWATCH /controlm/datafile*.txt CREATE
THEN
DO_COND %FILENAME% 0101 +
DO_CMD move %FILENAME% ~<controlm_owner>/ctm_server/workfile.txt
ELSE
DO_COND %FILENAME% 0101 -
END_ON
NOTE
All global parameters must be delimited by the new line character.
■ Global parameters, whose default values apply to all the files in the rule file.
NOTE
All keywords must be entered in uppercase.
You can also use the HHMM format, which uses the current date, plus the HHMM
entered. Default: 0 (meaning, no stop time)
If this parameter is set to Y and more than one file matches the specified mask, the
ctmfw utility randomly selects one matching file, monitors its file size, and ignores all
other matching files.
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 42. Default: 0 (no time limit).
NOTE
For a description of the ON_FILEWATCH parameters, refer to Table 39 on page 152.
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 5.
■ 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 or deleted within the time frame, the statements following
the ELSE block are executed.
■ ctmfw terminates when all the files in the Rules file have been processed.
NOTE
If an ON_FILEWATCH statement contains a cyclic_interval parameter, ctmfw will only stop
monitoring a file on a DO_OK or DO_NOTOK action.
Example 1
The ctmfw utility is invoked to watch multiple conditions. The definitions the ctmfw
utility uses for watching each file are contained in a rule file.
Example 2
A job processing definition is created to implement a FileWatcher job. The file must
arrive between 19:00 and 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 is 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 CONTROL-M/EM.
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
Parameter Value
Do Cond file_trans_dat_ok Date: ODAT Sign: +
Stmt *
Code COMPSTAT=1
Do Shout To: CONTROL-M/EM
Text: “File trans.dat did not arrive on time”
Return codes
The return codes listed in Table 42 are issued by the ctmfw utility after detecting if a
file is created or deleted in the specified time frame.
HKEY_LOCAL_MACHINE\SOFTWARE\BMC_Software\
CONTROL-M\FileWatcher\SYSPRM\Silent_Mode
ctmgetcm
The ctmgetcm utility is used to collect, store and display application server
information from CONTROL-M/Agents (version 6.1.01 or later).
■ When the action parameter is set to VIEW, previously stored application server
information is displayed.
NOTE
CONTROL-M/CM information is updated only after ctmgetcm is run, or each time ctmgetcm
is reconfigured.
ctmgetcm
You are prompted for the required parameters as if you had selected the View
Node ID Details option of the CONTROL-M Main Menu (see “CONTROL-M
Main Menu options” on page 322).
■ As a single command, specify the following command from the command prompt:
ctmgetcm
Note: OS can be specified to return information about the control module for
the current operating system.
-ACTION Indicates the action that the ctmgetcm utility should perform. Valid values
are:
GET Collect and display updated application information from the
specified CONTROL-M/Agent. The information collected is
stored in the CONTROL-M/Server database.
VIEW Display application server information that was previously
collected from the specified agent computer.
Note: This action will display only information that was retrieved
previously using a GET action.
Example 1
Specify the following command to view existing information for all applications on
the CONTROL-M/Agent sahara computer:
Example 2
Specify the following command to view existing information for all applications with
prefix O on the CONTROL-M/Agent sahara computer:
Example 3
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 using 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/Enterprise Manager User Guide.
ctmgrpdef
-GROUP <groupName>
-APPLICATION <applicName>
[ -ADJUST_COND Y|N ]
[ -OWNER <username> ]
[ -AUTHOR <username> ]
[ -DEBUG <debug level 0-5> ]
[ -QUIET ]
[ -TIMEZONE <xxx> ]
[ -TIMEFROM <earliestSubmissionTime> ]
[ -TIMEUNTIL <latestSubmissionTime> | '>' ]
[ -PRIORITY <jobPriority> ]
[ -CONFIRM Y|N ]
[ -TASKCLASS DISTRIBUTION|DECOLLATION ]
[ -APPLTYPE <agentApplication> ]
[ -APPLVER <applicationVersion> ]
[ -CMVER <CMversion> ]
[ -APPLFORM <applicationForm> ]
[ -DESCRIPTION <string> ]
[ -DOCMEM <filename> ]
[ -DOCLIB <directoryName> ]
[ -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> <urgency R|U|V> <subject> <message> ]
[ -DOREMEDY <summary> <description> <urgency L|M|H|U|C> ]
-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> ]
[ -DATEFROM <YYYYMMDD> ]
[ -DATEUNTIL <YYYYMMDD> ]
[ -DAYSCAL <daysCalendar> ]
[ -WEEKCAL <weekCalendar> ]
[ -CONFCAL <confCalendar> ]
[ -CAL_ANDOR AND|OR ]
[ -SHIFT [</>/@][+/-]nn ]
Most parameters in the command shown above are described in detail in the
CONTROL-M/Enterprise Manager User Guide. See Table 36 for the names under which
these parameters are listed in the CONTROL-M/Enterprise Manager User Guide.
NOTE
At least one Schedule tag must be specified (using the -TAG parameter) for each run of the
ctmgrpdef utility. Definition of additional tags is optional.
Example:
-input_file ~<controlm_owner>/ctm_server/data/ctmgrpdef_parms.txt
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 136.
ctmhostmap
The ctmhostmap utility manages the mapping of remote host computers to agents
and the conversion of CONTROL-M/Agents to remote host computers. This utility
can be run from the command line, or by using the CONTROL-M Configuration
Manager. For more information about using the CONTROL-M Configuration
Manager, see the CONTROL-M/Enterprise Manager Administrator Guide.
■ ctmhostmap help
Separate the agent names with a semicolon (;) when adding more than one agent.
For UNIX: If more than one CONTROL-M/Agent is being added, the entire list
must be enclosed in quotation marks, for example "jupiter;andromeda;taurus".
update Modifies the details of the specified remote host computer in the
CONTROL-M/Server database.
Separate the agent names with a semicolon when adding more than one agent.
For UNIX: If more than one CONTROL-M/Agents are being added, the entire list
must be enclosed in quotation marks, for example "jupiter;andromeda;taurus".
delete Deletes the details of the specified remote host computer in the
CONTROL-M/Server database.
list Lists the details of the specified remote host computer in the
CONTROL-M/Server database. The resultant list includes all remote host
computers and their statuses, except when list is specified with -node (see
description below).
help Displays the usage of the ctmhostmap utility.
This option is used in order to convert regular agent to remote host. For more
information, see Appendix C, “Conversion of agents and remote hosts.”
-node Specifies the name of the remote host computer or <Default>. The name of the
node cannot exceed 50 characters.
This parameter is:
■ mandatory when specified with add, update, and delete
■ optional when specified with list
If -node is specified with -list, the remote host is not <Default>, and the status is
not Discovering, the details of the specified remote host are displayed. The
output includes the following:
■ all the remote host definition parameter values
■ remote host status
■ status of each agent, showing which remote host is defined to be available
through it
For example, to list more than one CONTROL-M/Agent, the entire list must be
separated by semi-colons, for example pluto;mars;saturn. For UNIX, the list
would be: "pluto;mars;saturn".
■ BLOWFISH
■ AES
■ DES
■ 3DES
-compression Valid values are:
■ Y – compression is used
■ N – compression is not used
If WMI is specified, then the parameter below must be specified.
Note: The sysoutdir must either be prefaced with double back-slashes (for
example d:\\sysout_dir), or be enclosed with quotation marks (for example
"d:\sysout_dir").
-sysoutdir Indicates the directory used for the SYSOUT files created by
jobs that have been submitted. The name of the sysoutdir
cannot exceed 1,024 characters.
Example 1
To add remote host mars to the CONTROL-M/Server database, mapped through
CONTROL-M/Agents pluto, neptune, and venus, using SSH protocol, run the
following command:
ctmhostmap -action add -node mars -agent “pluto;neptune;venus” -protocol ssh -sshport 54
-sshalg des -compression N
Example 2
■ To add remote host saturn, mapped through CONTROL-M/Agent jupiter, using
WMI protocol, run the following command:
ctmhostmap -action add -node saturn -agent jupiter -protocol wmi -sysoutdir d:\\ctm\\data
■ As described above, but the sysout directory contains spaces. Run the following
command:
ctmhostmap -action add -node saturn -agent jupiter -protocol wmi -sysoutdir “c:\ctm eur\data”
Example 3
To add remote host saturn, mapped through CONTROL-M/Agents jupiter,
andromeda, and taurus using SSH protocol, run the following command:
Example 4
When modifying an existing entry, only the parameters that are being updated are
mandatory. To change the SSH port number of remote host mars from 54 to 48, and to
change the SSH algorithm from DES to 3DES, run the following command:
Example 5
To delete remote host mars from the CONTROL-M/Server database, specify the
following command:
Example 6
To display a list of remote hosts, run the following command:
orion Available
taurus Unavailable
pegasus Unavailable
Example 7
To display the details of remote host orion, run the following command:
Protocol : SSH
Port Number : 22
Encryption : BLOWFISH
Compression : NO
Agents : (comet) (meteor) (cyborg)
ctmjsa
The ctmjsa utility compiles runtime data from the Statistical Details table and records
it in the Statistics Summary table of the CONTROL-M/Server database.
■ Scans the statistical data for jobs that terminated with OK status. 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.
NOTE
Statistical 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 about runtime statistical data, see “Runtime statistics” on page
48.
ctmjsa also includes an option to display the summary data filtered according to
specified parameters.
NOTE
If 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.
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.
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:
ELAPSED
JOBNAME MEMNAME MEMLIB NODEID CPU [sec] (sec) Scheduling table
pgmacct1 prod.acct.pgm diana 0.19 233.15 accountq1
pgmacct2 prod.acct.pgm verdi 0.12 6.12 accountq2
pgmacct3 prod.acct.pgm diana 0.05 170.45 accountq3
pgmacct4 prod.acct.pgm diana 0.34 145.23 accountq4
ctmkeygen
The ctmkeygen utility generates SSH private and public key pairs.
When creating or modifying the job owner definition, you can choose to use either
public or private key authentication instead of password authentication. For more
information about using the CONTROL-M Configuration Manager, see the
CONTROL-M/Enterprise Manager Administrator Guide.
The ctmkeygen utility manages the key table that contains the logical key name as the
unique table key, the private key, and the key passphrase (encrypted). The generated
public key (unencrypted) is stored in a file.
The ctmkeygen utility can be run either in interactive mode or batch invocation.
ctmkeygen
The CONTROL-M Key Generator Utility menu is displayed. 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.
■ ctmkeygen help
NOTE
If the ctmkeygen utility is specified with a passphrase that is blank, the passphrase receives
the Agent_PASS dummy value. This value is used to encrypt the key and store its encrypted
version in the table.
Example:
ctmkeygen -action export -filename $HOME/ctm_server/data/key_details.txt
import Imports the details of the keys stored in the key table. Using the import
parameter enables you to:
■ specify utility input longer than the number of characters allowed in the
command line
Example:
ctmkeygen -action import -filename $HOME/ctm_server/data/key_details.txt
help Displays the usage of the ctmkeygen utility.
■ RSA
■ DSA
■ 512
■ 768
■ 1024
■ 2048
■ 3076
Note: The minimum value of the bits must be at least equal to the minimum
value of bits specified for the SSH server.
-format Specifies the public key file format. It must match the format used by the SSH
server. Mandatory when used with add, optional when used with update.
Valid values are:
Copy the public key to the SSH server according to the SSH server requirements.
<jobOwnerHomeDirectory>/.ssh/authorized_keys
<jobOwnerHomeDirectory>/.ssh2/authorization
<jobOwnerHomeDirectory>\.ssh2\authorization
Example 1
Create an entry in the key table with the following specifications:
Parameter Value
key name key1
passphrase myphrase
type dsa
bits 512
format ssh2
path /home/ctm630
ctmkeygen -action add -name key1 -passphrase myphrase -type dsa -bits 512 -format ssh2
-path /home/ctm630
Example 2
Assume that modifications are required to the key created in Example 1. To change
the type to rsa, the number of bits to 1024 and the format to openssh, specify the
following command:
ctmkeygen -action update -name key1 -passphrase myphrase -type rsa -bits 1024 -format
openssh -path /home/ctm630
Example 3
To delete the key entry created in Example 3, specify the following command:
Example 4
To display a list of SSH keys in the key table, specify the following command:
Example 5
To create an export text file containing the details of the SSH keys, specify the
following command:
Example 6
To import the my.ex0p text file, which contains the details of the SSH keys that
replaces the current information, specify the following command:
ctmkeystore_mng
The ctmkeystore_mng utility enables you to create, modify, and delete user names
and passwords.
NOTE
To work with Do Remedy, first activate this utility.
ctmkeystore_mng
+------------------------------------------------------+
| CONTROL-M/Server Keystore Management Utility |
| Main Menu |
+------------------------------------------------------+
1) REMEDY Keystore
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.
The REMEDY Keystore option, appearing in the Main Menu, is described below.
REMEDY Keystore
Specify this utility to create, modify, and delete Remedy user names and passwords.
+--------------------------------------+
REMEDY Keystore Menu
+--------------------------------------+
1) Add User
2) Delete User
3) Update User password
q) Quit
Enter option:
After confirming the password, a message is displayed stating that the user name
was successfully added.
A message is displayed stating that the user name was successfully deleted.
You are prompted to enter new password and then confirm it.
ctmkilljob
The ctmkilljob utility terminates a specified CONTROL-M job and all its processes.
ctmkilljob terminates only jobs that are currently executing.
NOTE
Only 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 one of the following commands to
invoke the ctmkilljob utility:
usage: ctmkilljob
[ -ORDERID <uniqueOrderID> ]
[ -NODEID <name> ]
[ -MEMLIB <path> ]
[ -MEMNAME <filename> ]
[ -JOBNAME <name> ]
-or-
Example:
-input_file ~<controlm_owner>/ctm_server/data/ctmkilljob_parms.txt
If the action was successful, the utility responds with the statement:
NOTE
The 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.
ctmldnrs
The ctmldnrs utility creates and loads the Manual Conditions file. This file contains
prerequisite conditions that are required by jobs in the Active Jobs file but will not be
added to the Conditions/Resources table without manual intervention. These
conditions fall into two categories:
■ 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
that add them are not scheduled for the day.
Prerequisite conditions in the Manual Conditions file can be made available to the
system using the load option of ctmldnrs (see below), using the ctmcontb utility
(described on page 105), using the Prerequisite Conditions window (see Chapter 13,
“Managing Resources and Conditions”, in the CONTROL-M/Enterprise Manager User
Guide), or using the WHY option in the job menu (see Chapter 12, “Getting and
Updating Details”, in the CONTROL-M/Enterprise Manager User Guide).
The ctmldnrs utility identifies conditions that should be in the Manual Conditions file
by searching 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 parameters of the job processing definitions for all jobs in the Active Jobs
file.
Then, the utility eliminates any “non-manual” conditions that satisfy either of the
following criteria:
Prerequisite conditions that do not meet the above criteria are assumed to be manual
conditions and are placed in the Manual Conditions file.
NOTE
The following special characters are disabled when they occur in prerequisite condition
names:
( open parenthesis
) close parenthesis
| vertical bar
space
■ When using both open and closed square brackets ([ and ]), the
condition name must be enclosed in quotation marks (for
example, “RATE[A1]”).
■ When using both open and closed square brackets ([ and ]),
the condition name must be enclosed in quotation marks (for
example, “RATE[A1]”).
<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.
Example 1
The following command re-creates the default Manual Conditions file in the user’s
directory:
Example 2
Example 3
The following command loads all conditions from the default input Manual
Conditions file to the Conditions/Resources table:
ctmloadset
The ctmloadset utility records current resource usage on an agent computer in the
Quantitative Resources table. This utility is typically invoked by a cyclic job that runs
on the agent computer and measures usage of a certain resource on the computer.
Usage data is then used to update the Quantitative Resources table on the
CONTROL-M/Server computer.
Item Description
Total Used Units of the resource currently in use. This parameter represents
the sum of the values specified in the other two rows of this table.
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.
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.
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.
<QRname> Name of the Quantitative resource to update.
<loadValue> Number of units of the resource currently used.
-or-
Example 1
A node group contains three agent computers: diana, jacklin and ruby. Each
computer is defined in the Quantitative Resource table as having 200 units of
resource CPU_load, representing the load on the computer’s CPU.
■ computer diana is used both for CONTROL-M and non-CONTROL-M jobs. The
computer 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 computer. The last run of
this job determined that the load on the CPU is 80% of total capacity. The job invokes
ctmloadset as follows:
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:
Total used by
Resource Max CONTROL-M Total used by others Free
CPU@jacklin 200 120 80
CPU@ruby 200 150 50
CPU@diana 200 75 85 40
Example 2
For agent computer diana, 30 units of resource CPU@diana are currently used by
CONTROL-M jobs.
Example 3
The following command specifies that the current usage of the Quantitative resource
CPU@diana by non-CONTROL-M jobs is 12 units:
Example 4
The following command specifies that the current usage of the Quantitative resource
CPU@diana by non-CONTROL-M jobs is 12%:
Example 5
The following command specifies that the current total usage of the Quantitative
resource CPU@diana by all jobs is 48 units:
ctmlog
The ctmlog utility creates a report from entries in the CONTROL-M log or deletes
entries in the CONTROL-M log.
Valid values for <action> and <actionOption> are listed in Table 55. All other
parameters of this utility are described in Table 56.
NOTE
All actions are limited to log entries in the range specified using the time and date parameters.
■ SU Supervisor
■ TR Tracker
■ SL Selector
■ LG Agent utilities
■ UT Utilities
■ WD Watchdog
list Prints a report of all entries. None.
Example 1
The following command produces a report of all entries in the CONTROL-M log
between 10:00 A.M. March 12, 2002 and 8:00 A.M. March 14, 2002. The report is
output to file rprt.txt in 80-column format:
Example 2
The following command produces a report of all entries in the CONTROL-M log
relating to downloads to the CONTROL-M/EM database and to
CONTROL-M/Server database updates, without regard to date or time. The report is
output to file gdrprt.txt in 132-column format:
ctmnodegrp
The ctmnodegrp utility is used to maintain and view node groups. This utility
provides the command line facility for running the options available from the Node
Group Menu.
ctmnodegrp
[ -LIST |
-EDIT -NODEGRP <nodeGroup>
-APPLTYPE <applicationType>
[ -VIEW |
-ADD <nodeid> |
-DELETE <nodeid> ] |
q - Quit
To list all node groups, select the List All Node Groups option in the Node Group
Menu.
This option is used to view, create or modify a node group. When this option is
selected, the following prompt is displayed:
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:
q - Quit
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.
Quit Quits the Mode Group menu and returns to the CONTROL-M
Main Menu.
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).
NOTE
This utility can be used non-interactively for non-terminal destinations (see the description of
the <Output> parameter below).
Example
The following command generates a list for user SYSTEM and the User Daily
SYSTEM. The list is directed to the udlist file:
ctmorder
The ctmorder utility orders or forces one or more jobs from a Scheduling table in the
CONTROL-M/Server 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 order or force a job with that name, only the first job is added to the Active
Jobs file.
NOTE
If the ctmorder utility is running when the New Day procedure begins, it is automatically
suspended until New Day procedure is ended.
Syntax
This first format cannot be used if the ctmorder utility is invoked from a
CONTROL-M/Agent computer.
■ The second format allows specification of all optional parameters in any order but
requires each specified parameter to be named. Format:
-or-
NOTE
The ctmorder utility can only be accessed using a command line interface. The interactive
interface in versions prior to version 6.0.01 is no longer supported.
You can order a Group Scheduling table, but you cannot order an
individual job, or selection of jobs, from a Group Scheduling table.
Example:
-input_file ~<controlm_owner>/ctm_server/data/ctmorder_parms.txt
NOTE
If neither ORDER nor FORCE is included in the command, 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:
You can get the same result using the -input_file parameter as follows:
-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, 2006 as their original scheduling date:
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, 2005 as their original scheduling date:
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, 2005 as its original scheduling
date. This job is added to an active group whose orderid is 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, 2005 as their original scheduling
date.
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, 2005 as their original scheduling date. The APPLICATION and
OWNER parameters of these jobs are modified to STOCK_COUNT and
STOREMAN, respectively.
ctmpasswd
The ctmpasswd utility enables the administrator to change the CONTROL-M/Server
User’s password for accessing the database. Only an administrator can change the
password.
ctmpasswd
2 Enter the new password. Make sure that the password contains at least 6
characters. You will not see your entry on the screen.
ctmping
The ctmping utility tests, configures, and reports on the connection and availability
between CONTROL-M/Server and CONTROL-M/Agents or remote host computers.
NOTE
ctmping can be included in the Watchdog process. See “Watchdog facility” on page 69 for
details.
This utility can check if an agent or remote host is down and, if required, register it in
the database as unavailable. When the agent or remote host again becomes available,
the state is changed and information about it is gathered by a CONTROL-M/Server
process.
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 computer.
The delimiter between the name and the NODETYPE is a blank or any
number of blank spaces.
Example
Assume the following computers must be pinged:
Name Type
dime not specified
comet CONTROL-M/Agent
mars remote host computer
Example 1
To connect and perform a communication test with the agent jacklin, specify the
following command:
Example 2
To attempt to connect and test communication with agent diana (that is currently
down), specify the following command:
Example 3
To connect and test communication with the agent jacklin and collect configuration
information needed for the discovery process, specify the following command:
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:
Only the return code of the utility indicates if it was successful. The debug trace
information is saved to the following file:
~<controlm_owner>/ctm_server/proclog/ping<PID>_<PID>.log
Example 5
The agents, comet and mars, have been configured to connect to remote host dime.
To generate a report showing the result of the test and the connection details, specify
the following command:
Example 6
Assume the nodeid_list.txt text file contains the full path to the following node IDs:
To generate a report showing the result of pinging the node IDs specified in
nodeid_list.txt, specify the following command:
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 CONTROL-M/EM GUI and enables you to perform many of the GUI
functions directly in the data center.
NOTE
If long names have been used for the In condition, jobname, overlib, memlib, and doclib
parameters, these values will be truncated in the output of the ctmpsm utility. To view the
complete values for these parameters, use the CONTROL-M/Enterprise Manager GUI.
NOTE
The following special characters are disabled when they occur in prerequisite condition
names:
( open parenthesis
) close parenthesis
| vertical bar
space
NOTE
The ctmpsm utility can also be invoked by the Command Line Interface, as described in
“Command line invocation” on page 227.
Q) Quit
Enter Option:
■ 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.
All Active Jobs file options display the following menu at the bottom of the screen:
Notes:
■ Scheduling table
■ Job Name (optional)
■ Odate (YYYYMMDD/ODAT)
■ Odate_option (VALUE_DATE|RUN_DATE) [VALUE_DATE]
■ Hold Option (Y|N)
For more information about ordering jobs and Scheduling tables, see
“ctmorder” on page 204.
When the Scheduling Tables option is selected, output similar to the following is
displayed:
Option []:
NOTE
If a table that is associated with more than one User daily is modified using
CONTROL-M/EM and then uploaded to CONTROL-M/Server, that table is removed from
all User dailies except the one that is associated with it in CONTROL-M/EM.
■ 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/Server
database.
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.
■ To wait until the specified odate begins before running the jobs,
specify RUN_DATE.
A) Alone.
N) New group.
L) Last.
■ 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 Updates the User Daily name for a specific Scheduling table (for
table # example, specify U6 to update the User Daily name for table
RE_SYSOUT).
When the List Jobs # option is selected, output similar to the following is displayed:
1) Jobname:DAYS_CAL_N, Memname:DAYS_CAL_NONE
2) Jobname:DAYS_30_FE, Memname:DAYS_30_FEB
3) Jobname:DAYS_28_29, Memname:DAYS_28_29_FEB
4) Jobname:NO_CALENDA, Memname:NO_CALENDAR
5) Jobname:DATES_0101, Memname:DATES_0101_0202
6) Jobname:DATES_2902, Memname:DATES_2902
7) Jobname:DAYS_CAL_M, Memname:DAYS_CAL_MINUS
8) Jobname:DAYS_CAL_P, Memname:DAYS_CAL_PLUS
9) Jobname:DAYS_CAL_W, Memname:DAYS_CAL_WITHOUT
10) Jobname:CALENDAR_O, Memname:CALENDAR_ONLY
11) Jobname:wdays_all , Memname:WDAYS_ALL
12) Jobname:wdays_1_2_, Memname:WEEKDAYS_1_2_3
Option []:
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>]
Parameter Description
<order ID> The order ID of a job.
<number> A counter incremented by one each time a job is run. Default: runcount
number of the most recent run of the specified job.
Examples
To display the most recent SYSOUT of the job whose order ID is 1234, specify the
following command:
To display the second SYSOUT of the job whose order ID is 1234, specify the
following command:
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
~<controlm_owner>/ctm_server/data/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. [UNIX only]
<viewerCommand> is the name of the viewer application selected by the user for
displaying the SYSOUT.
Example
Examples
■ After a successful import of a calendar, the following message is
displayed:
ctmpsm -LISTALL
[{ODAT|TIME|APPLICATION|MEMNAME|ALL|ALLFIELDS}]
[-SORT {ORDERID|JOBNAME}]
In addition to the order ID and the job name, one of the following fields
must also be included in the LISTALL output:
–SORT indicates the order in which the jobs should be listed. Valid
values: ORDERID and JOBNAME.
Two additional job statuses are visible only when using the LISTALL
option:
These job statuses are used in the CONTROL-M/Server Active Jobs file.
However, in CONTROL-M/EM, jobs with these statuses will appear with
Wait Condition status. In non-interactive mode, WAIT_Condition and
WAIT_CONFIRM are both displayed as Wait Con.
ctmpsm -LISTJOB
{OK|NOTOK|EXECUTING|CYCLIC|
WAITTIME|WAITCONFIRM}
[-SORT {ORDERID|JOBNAME}]
–SORT indicates the order in which the jobs should be listed. Valid
values: ORDERID and JOBNAME.
LISTGROUP Lists jobs in the specified group that are associated with a specified
application.
ctmpsm -SCHEDTAB
{-LISTTABLE <table_name>|-UPDATE <row_number>
<udaily_name>|
-ADD <table_name> <udaily_name>|-DUDAILY <row_number>|
-REMOVE <table_name>|-LISTJOBS <row_number>}
-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.
LISTDETAILS <order_ID>
LISTFULL Lists the parameters of a specified job in the Active Jobs file. In addition to
DETAILS the data provided by LISTDETAILS (above), LISTFULLDETAILS
provides data about In conditions, Out conditions, and AutoEdit values.
(LISTFULLDETAILS was added for use with the “Zoom and Save”
option in WebAccess.)
ctmpsm -LISTFULLDETAILS <orderid>
Note: Conditions specified using this mode apply only to the specified
instance of the job in the Active Jobs file. Subsequent orders of that job are
not affected.
ctmpsm -XML
[{ODAT|TIME|APPLICATION|MEMNAME|ALL|ALLFIELDS}]
[-SORT <ORDERID|JOBNAME>]
To list jobs in the Active Jobs file in XML format, specify ctmpsm -XML
plus at least one of the following fields:
Example 1
To filter the list of jobs in the Active Jobs file according to the member
name of the job, specify the following:
Example 2
To sort the list in Example 1 above according to job name, specify the
following:
ctmreindex
The ctmreindex utility accesses the CONTROL-M/Server database, reads the data
dictionary, reads the index definitions, and then reorganizes indexes. [UNIX only]
NOTE
This utility can only be used with Sybase databases.
ctmreindex
Example
The following command causes the ctmreindex utility to reorganize indexes in the
CONTROL-M/Server Sybase database:
ctmreindex
ctmrpln
The ctmrpln utility creates a report that lists selected jobs in selected Scheduling
tables, and indicates when the jobs are scheduled to run. It enables you to test the
effect of different calendars on job scheduling.
The following characters can appear in this report. The characters indicate whether a
job is scheduled to run (that is, whether the job is placed in the Active Jobs file.)
Char Description
* The job is scheduled to run on this day.
. The job is not scheduled to run on this day.
- The job is scheduled to not run on this day. For example, if DAYS=-3, the job is
scheduled to not run on the 3rd day of the month.
To invoke the ctmrpln utility, specify ctmrpln (and you will be prompted for
parameter values) or specify:
Note: The ctmrpln utility supports years from 1972 to 2035, inclusive.
<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.
Note: To print the Monthly Report, specify a device that can print
132-column reports.
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, 2002 based on the calendar work_days. The job is
identified by its Mem Name. (To identify jobs by Job Name, specify Report_type DJ.)
The output is directed to the user’s display.
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, 2002, based
on the calendar work_days. The job is identified by Mem Name. (To identify jobs by
Job Name, specify Report_type MJ.) The output is directed to printer lp1.
Example 3
ctmruninf
The ctmruninf utility displays runtime data from the Statistical Details table of the
CONTROL-M/Server 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.
NOTE
Statistical data is only accumulated when the CONTROL-M/Server system parameter
Statistics is set to Y.
For more information about runtime statistical data, see “Runtime statistics” on page
48.
■ -JOBNAME <jobname>
Identify the job by the first 10 characters in its Job Name
parameter.
■ -MEMNAME <memname>
Identify the job by its Mem Name parameter.
■ -MEMLIB <memlib>
Identify jobs by their Mem Lib parameter specifications.
■ -NODEID <nodeid>
Identify jobs by their Node ID parameter (agent computer).
■ -ORDERID <orderid>
Identify jobs by their Order ID parameter.
Each of the subparameters in the filter can include the following mask
characters:
Running the ctmruninf utility with the -PURGE option performs the
statistics cleanup as if it was done during New Day with the
RUNINF_PURGE_MODE set to 0 (default).
Note:
■ You can speed up the New Day procedure by specifying N for the
STATISTICS_CLEANUP_IN_NEWDAY parameter and running
ctmruninf -PURGE in a job that is run daily. For more information,
see “STATISTICS_CLEANUP_IN_NEWDAY” on page 392.
■ Only the last n run information records of a job are kept, where n is
the value of RUNINF_PURGE_LIMIT (default 20). For more
information, see “RUNINF_PURGE_LIMIT” on page 391.
Example 1
The following command displays runtime data for the period January 21, 2002
through January 25, 2002 (assuming that this data is available):
Example 2
The following command deletes the statistical data for January 31, 2002:
Example 3
The following command causes the utility to display and total runtime data for all
jobs on agent computer diana.
ctmsec
The ctmsec utility can be invoked in interactive or batch mode. For more information
about CONTROL-M security concepts, see the CONTROL-M/EM Administrator Guide.
■ Security considerations
■ Security maintenance utility (Interactive mode)
■ Security maintenance utility (Batch mode)
■ Exporting security definition tables
■ Importing security definition tables
Security considerations
CONTROL-M/Server includes security features that protect CONTROL-M against
unauthorized usage or modification. These features enhance the standard UNIX and
Windows security, and provides an additional application-level security layer.
Using CONTROL-M security, you can specify actions that each CONTROL-M/EM
user or CONTROL-M/Server user is authorized to perform. These authorizations are
used to perform security checks each time one of the following actions is attempted:
■ Ordering a job.
■ Commands affecting jobs in the Active Jobs file (for example, Hold, Confirm,
Rerun).
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 245.
CONTROL-M provides the following levels of application security for users not
explicitly defined in the CONTROL-M Security database:
■ A user, for whom one or more authorizations have been assigned in the Security
database, can only perform those actions.
■ The owner of each job processing definition must be defined as a user on the agent
computer. Otherwise, CONTROL-M/Agent will not 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”).
If CONTROL-M Option for SSL is installed, Secure Sockets Layer encryption and
compression provide security for CONTROL-M/Server communication with
CONTROL-M/EM and CONTROL-M/Agents. For more information, see the
CONTROL-M Option for SSL Administrator Guide.
NOTE
When working with the CONTROL-M/Server Security facility, mask characters are available
for all options. Mask characters * and $ are translated during runtime security checking. (For
example, if User1 is granted full Scheduling Table authorization for table ACC*,
CONTROL-M allows User1 to update or order any table whose name starts with ACC). Valid
mask characters:
* represents any number of characters (including none).
$ 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 or order table ACC999).
NOTE
Changes made by this utility are implemented only after you exit the utility.
Users can 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 261.
■ If there are no authorizations defined for the user, the user inherits the
authorizations for the group.
■ If there are authorizations defined for a 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.
■ 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 365.
Certain functions of the ctmsec utility can be activated directly from a command line.
For more information, see “Security maintenance utility (Batch mode)” on page 261.
In addition, certain functions of the ctmsec utility can be activated using the
CONTROL-M Configuration Manager. For more information, see the
CONTROL-M/Enterprise Manager Administration Guide.
-or-
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.
NOTE
Each CONTROL-M/EM user who performs actions affecting the CONTROL-M/Server
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.
If the user in the commands listed below is a CONTROL-M/Agent user, then the <user>
format is <username@NODE_ID>.
Select Option 1 from the Security Maintenance Main Menu. The User Maintenance
menu is displayed.
Enter option:
User []:
Description []:
Group []:
This field is optional. If specified, the user inherits all authorizations defined for
the group that are not specifically defined for the user.
Username []:
2. Specify the user name of the CONTROL-M/EM user to delete. After confirmation,
the user is deleted from the Security database, and the User Maintenance menu is
displayed.
User []:
User: User1
-----------------------
Modify User Information
1) Description :
2) Group :
s) Save and return to menu
4. Type s to save your changes and return to the previous menu. Modifications are
not saved until you perform this action.
-or-
FROM user:
TO user:
3. Specify a new user name for the CONTROL-M/EM user (maximum 30 characters,
case-sensitive).
Description []:
Group []:
This field is optional. If specified, the user inherits all authorizations defined for
the group that are not specifically defined for the user.
Group maintenance
Each user who has a user account on the CONTROL-M/Server computer and 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.
Group Description
Group1 CONTROL-M Group
Group2
Press ENTER to continue:
1. Select Option 2 from the Group Maintenance menu. The following prompt is
displayed:
Groupname []:
This name must be unique. It cannot be an existing user or group name. The
following prompt is displayed:
Description []:
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.
1. Select Option 4 from the Group Maintenance menu. A prompt similar to the
following is displayed:
Group: Group1
Modify Group Information
-----------------------
1) Description :
s) Save and return to menu
c) Cancel and return to menu
You are prompted to supply a value for the field (maximum length 50 characters).
This field is optional and is for documentation purposes only.
4. Type s to save your changes and return to the previous menu. Modifications are
not saved until you perform this action.
-or-
For more information about the types of authorization that can be granted using this
option, see “Scheduling table authorization option” on page 262.
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 Security database, the
following message is displayed:
3. Press <Enter> to return to the Main Menu. The Scheduling Table Authorization
menu is displayed:
q) Quit
Enter option:
1. Select Option 2 from the Scheduling Table Authorization menu. The following
prompt is displayed:
Table Name:
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 to N.
Type s to save your changes and return to the previous menu. Modifications are
not saved until you perform this action.
-or-
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 262.
+--------------------------------------+
| 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 Security database, the
following message is displayed:
2. Press <Enter> to return to the Main Menu. The Active Jobs File Authorization
menu is displayed:
q) Quit
Enter option:
To list owners for whom the user has Active Jobs File authorizations
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:
Node Group:
3. Specify the node group of the Agents where the job can be scheduled to run
(maximum 30 characters, case-sensitive).
NOTE
A value must be specified for the Node Group prompt. To indicate all node groups, specify an
asterisk (*) for this prompt.
1) Order :Y
2) Force :Y
3) Rerun :Y
4) Hold :N
5) Confirm :N
6) Delete :Y
7) Why :N
8) Sysout :N
9) Log :N
10) Statistics :N
11) Zoom & Save :N
12) Kill job :N
s) Save and return to menu
c) Cancel and return to menu
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 to N.
NOTE
When working in full security mode and ordering Group Scheduling tables where Y has
been specified for Order, BMC Software recommends to specify Y also for Hold. The
Group Scheduling table remains in Hold status if the user has only ORDER/FORCE
permissions.
-or-
Owner:
2. Specify the name of the Job owner for whom authorizations should be deleted (or
press <Enter> to return to the menu).
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.
Entities authorization
For more information about the types of authorization that can be granted using this
option, see “Entities authorization options” on page 263.
+----------------------------------------+
| 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 computer, a message
similar to the following is displayed:
q) Quit
Enter option:
To list Entity categories for which the user or group has authorizations
1. Select Option 2 from the Entities Authorizations menu. The following menu is
displayed:
Categories
----------
1) CALENDAR
2) LOG
3) QUANTITATIVE RESOURCE
4) CONDITION
5) CONTROL RESOURCE
q) Quit
Category 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:
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 to N.
4. Type s to save your changes and return to the previous menu. Modifications are
not saved until you perform this action.
-or-
1. Select Option 3 from the Entities Authorizations menu. The following menu is
displayed:
Categories
----------
1) CALENDAR
2) LOG
3) QUANTITATIVE RESOURCE
4) CONDITION
5) CONTROL RESOURCE
q) 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.
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 copy user authorizations from one user to another:
ctmsec -USER_COPY <from_user> <to_user>
NOTE
If the user in the commands listed above is a CONTROL-M/Agent user, then the <user>
format is <username@node_id>.
Group authorization
Group authorization options of the ctmsec command are used to list, modify, and
delete groups in the CONTROL-M Security database.
The Scheduling table authorization options of the ctmsec command are used to
assign authorizations to users and groups to perform actions on Scheduling tables.
NOTE
If the user in the commands listed above is a CONTROL-M/Agent user, then the <user>
format is <username@node_id>.
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.
NOTE
If the user in the commands listed above is a CONTROL-M/Agent user, then the <user>
format is <username@node_id>.
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.
NOTE
If the user in the commands listed above is a CONTROL-M/Agent user, then the <user>
format is <username@node_id>.
NOTE
The file created by the EXPORT option of the ctmsec utility can be modified before security
definitions are imported back to the same (or a different) CONTROL-M/Server 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 information about
exporting CONTROL-M Security Definition tables, see “Security Authorization menu” on
page 341.
Example
Importing updates the security definitions in your CONTROL-M installation. Use the
restore security procedure to replace security definitions. For more information about
restoring security definitions, see “Restore Security Definition Tables” on page 342.
Execute the script file that was created using the ctmsec utility.
Example
/home/controlm/securedata
NOTE
This 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 102 on page 342.
ctmsetown
The ctmsetown utility manages the details of CONTROL-M/Agent and remote host
users. This utility can be run from the command line, or by using the CONTROL-M
Configuration Manager. For more information about using the CONTROL-M
Configuration Manager, see the CONTROL-M/Enterprise Manager Administrator Guide.
In addition, the ctmsetown utility also enables the authentication details of users to be
imported or exported from different CONTROL-M environments. This can only be
done from the command line.
■ ctmsetown help
export Exports the security details of the existing users to a text file.
Example:
ctmsetown -action export -filename $HOME/ctm_server/data/user_report.txt
For example:
ctmsetown -action delete -owner s -host "<All>"
-password Specifies the password of the owner. The password cannot exceed 120
characters.
-encpassword The encrypted password of the owner. The encpassword cannot exceed 512
characters. The value must be divisible by 4 without a remainder.
-keyname The logical name of the key. The key itself is kept in a separate table with its
passphrase. For more information about generating and maintaining the
key, see “ctmkeygen” on page 177. The same key can be used for multiple
users.
Note: This parameter is used only when either -action export or -action
import is specified.
-data Describes what action to take with the data from the imported text file.
Valid actions are:
append details of the users from the imported text file are added to
the existing users
truncate details of the users from the imported text file replace the
details of the existing users
Example 1
To create an entry with the security details of a user whose name is username1, the
name of the host computer is saturn and the user password is pass01, specify the
following command:
Example 2
Create a user entry as in Example 1, however, use the keyname k1 and passphrase
BMC user. Specify the following command:
ctmsetown -action add -owner username1 -host saturn -keyname k1 -passphrase “BMC user”
Example 3
Assume that the security details of the owner, described in Example 1, already exists.
To change the password from pass01 to newpass, specify the following command:
Example 4
To delete the user entry created in Example 1, specify the following command:
Example 5
To list the security details of user entries, specify the following command:
Example 6
To create an export text file containing a list of security details of user entries, specify
the following command:
Example 7
To import the /home/ctm630oe/sec.exp text file created in Example 6, containing a list of
security user entries, and to replace the current security user information, specify the
following command:
ctmshout
The ctmshout utility sends a message to the specified user or destination using the
specified severity level. For information about Shout message destinations, see
“Shout destination tables” on page 359. For information about attaching the SYSOUT
of a job to Shout messages, see “CONTROL-M/Server e-mail configuration
parameters” on page 397.
ctmshout
-USER <username> or -DEST <destinationName>
-MESSAGE "<messageText>"
[ -ORDERID <orderID>]
[ -NODEID <nodeID>]
[ -SEVERITY <severityLevel>]
-or-
Each parameter name can be shortened to the minimum number of letters required to
uniquely identify the parameter. For example: -ORDERID can be shortened to -O.
R – Regular (Default)
U – Urgent
V – Very urgent
<fullPathFileName> Name and full path of a file containing the utility parameters. In this
file, each parameter and its values (if any) are on a separate line with
the same syntax they would have on the command line. The
-input_file parameter enables you to:
Example:
-input_file~<controlm_owner>/ctm_server/data/ctmshout_parms.txt
NOTE
Shout messages can be sent to multiple destinations or users in the same command.
Example 1
The following command sends the message “File not found” to the Alerts
window in CONTROL-M/EM and associates it with a job whose Order ID is 1234:
You can get the same result using the -input_file parameter as follows:
-ORDERID 1234
-USER EM
-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 computer diana:
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 CONTROL-M/EM.
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:
ctmshtb
The ctmshtb utility specifies the active Shout Destination table.
You can add, delete, and modify Shout Destination tables using the ctmsys utility,
described on page 282. The ctmsys utility can also be used to specify the active Shout
Destination table interactively.
NOTE
The Shout Destination table associates physical output destinations with logical destination
names. The names are specified in Shout and Do Shout statements in job processing
definitions and in the ctmshout utility. For more information, see “Shout facility” on page 47.
ctmshtb <table>
NOTE
By defining CONTROL-M jobs that execute this 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
ctmspdiag
The ctmspdiag utility is a tool to print or erase diagnostic messages recorded from
stored procedures (SPs) in the CONTROL-M/Server database. ctmspdiag can also set
or show the diagnostic request status of SPs.
-PRINT Print the recorded diagnostic messages for the specified SP name. The SP
name can include the mask character * to indicate any number of characters
(including none). When using an *, enclose the SP name in quotation marks,
for example, “clean* ”.
-DEL Erase diagnostic messages that are equal to, or older than, the TO_DATE
parameter.
-TRUNCATE Erase all SP diagnostic messages in the CONTROL-M/Server database.
-SHOW Displays the current diagnostic request status for the specified SP. If the SP
name is omitted, the diagnostic request status of all the SPs is displayed.
Table 79 describes the parameters that can be specified with the ctmspdiag utility
options.
■ Y
■ N (Default)
Note: If both this parameter and TO_DATE are not specified, all the
messages are printed.
-TO_DATE End date for the date range of diagnostic messages to print. Each date is in
yyyymmddhhmm format.
Note:
■ For the -PRINT option , if both this parameter and -FROM_DATE are
not specified , all the messages are printed .
■ For the -DEL option , if this parameter is not specified, all the messages
are deleted.
Example 1
This example sets the status request value Y for the SP named saturn in the
CONTROL-M/Server database.
Example 2
This example prints messages found in the CONTROL-M/Server database that were
recorded from the SP named saturn.
To print the date range from minute after midnight on November 14, to midnight on
December 20, 2004, specify the following command:
Example 3
This example erases all the messages older than 08:30 December 14, 2004 found in the
CONTROL-M/Server database, that were recorded from the SP named saturn.
Example 4
This example erases all the diagnostic information found in the CONTROL-M/Server
database, that were recorded from SPs.
ctmspdiag -TRUNCATE
Example 5
This example displays the current diagnostic request status for the SP named saturn.
ctmstats
The ctmstats utility displays and deletes statistical data from the Statistical Summary
table of the CONTROL-M/Server database. The data scanned for both options can be
limited to a range of dates. The Statistical Summary table is created using the ctmjsa
utility.
NOTE
Statistical data is only accumulated when the CONTROL-M system parameter Statistics is set
to Y. For more information, see “System parameters” on page 365.
Example 1
The following command displays statistical data for the period January 21, 2002
through January 25, 2002 (assuming that this data is available):
Example 2
The following command displays statistical data for all jobs on agent computer diana:
Example 3
The following command deletes the statistical data for January 31, 2002:
ctmstvar
The ctmstvar utility displays the current value of an AutoEdit variable or function.
Specify the following command to invoke the ctmstvar utility:
[UNIX only] An AutoEdit variable that does not contain a $ sign can be enclosed in
single or double quotation marks. An AutoEdit variable that does contain a $ sign
must be enclosed in single quotation marks. An AutoEdit variable that contains a $
sign cannot be resolved if it is enclosed in double quotation marks.
[Windows only] AutoEdit variables must be enclosed with double quotation marks.
Example
For UNIX
For Windows
ctmsuspend
The ctmsuspend utility suspends and restores CONTROL-M/Server
non-communication processes for mass uploads and downloads from
CONTROL-M/EM. During suspension mode, CONTROL-M inactivates its job
processing functions by suspending the TR, SL, NS, LG, and WD processes. For more
information, see “CONTROL-M/Server processes” on page 352. 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 CONTROL-M/EM GUI.
ctmsuspend {-s|-r
Example
ctmsuspend -r
ctmsys
The ctmsys utility is an interactive utility for maintaining:
ctmsys
+------------------------------------------------+
| CONTROL-M SYSTEM MAINTENANCE UTILITY |
| Main Menu |
+------------------------------------------------+
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.
1) Create/Modify a Table
2) Set Active Table
3) List Tables
4) Delete Table
q) Quit and return to main menu
Enter option:
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.
Enter option:
1 Specify n.
Logical Name:
Physical Name:
Dest Type:
Address Type:
Physical Name:
2 Specify a new physical name for the entry. The table is redisplayed with the
modified entry.
2 Specify the name of the table to set as the active Shout Destination table.
The active Shout Destination table is changed immediately, affecting Shout and
Do Shout operations performed by CONTROL-M.
NOTE
To specify the active Shout Destination table using a job, run the ctmshtb utility, described on
page 273.
NOTE
It is not possible to delete the active Shout Destination table.
System parameters
This option is used to view/modify CONTROL-M system parameters.
NOTE
These parameters are described in Chapter 5, “Customization parameters.”
The first group of parameters (and their current values) is displayed. See Figure 18.
2) Statistics :Y
3) Maximum Retries :50
4) Start Day of the Week :2
Active Shout Table :SYSTEM
5) Full Security :N
n) Next Page
s) Save and Return to Main Menu
c) Cancel
When you specify n, the second page of parameters is displayed. See Figure 19.
p) Previous Page
s) Save and Return to Main Menu
c) Cancel
— 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.
■ Type s to save your changes and exit to the Main Menu. Modifications are not
saved until you perform this action.
-or-
ctmudchk
The ctmudchk utility checks if all jobs that 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 (the
status of the data center in the Communication Status window of CONTROL-M/EM
must not be “Formatting AJF”).
Example 1
Use the following command to check the Active Jobs file for jobs that 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.
Example 2
Use the following command to check the Active Jobs file for jobs that are ordered by
the User Daily whose name is admin1. The utility orders each job that is not in the
Active Jobs file.
Return codes
The utility returns code 1 status (NOTOK) if it attempts to order a job, but fails to do
so. Otherwise, the utility returns code 0 status (OK).
ctmudlst
The ctmudlst utility is used to display or modify UDLAST (the User Daily last run
date). For more information, see “Date control record (UDLAST)” on page 39.
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
CONTROL-M/EM must not be “Formatting AJF”).
Example 1
The following command lists the last run date for User Daily payroll:
Example 2
The following command changes the last run date for User Daily inventory to Aug.
10, 2002:
ctmudly
The ctmudly utility orders jobs whose scheduling tables are 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 37, for more information and examples.
-or-
Notes:
Scheduling issues – If one or more jobs in a scheduling table is not ordered by a User
Daily due to scheduling criteria, the type of Alert sent to CONTROL-M/EM is
determined by the value of the CONTROL-M configuration parameter
NOT_ORDERED_JOB_ALERT. For information about this parameter, see page 391.
PARTIAL COPY message – If one or more jobs in a scheduling table was not ordered
by a User Daily due to scheduling criteria or security settings, the User Daily
(ctmudly) ended with the following error message in the job output (SYSOUT).
The following command orders all Scheduling tables that are associated with the
User Daily named prod:
ctmudly prod
The following command orders all Scheduling tables that are associated with the
Japan User daily job, with an odate of March 31, 2002. These jobs will not be run until
that working day begins.
ctmvar
The ctmvar utility defines, deletes, modifies and displays AutoEdit variables. This
utility can be applied to variables that are:
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.
Syntax
-or-
Example 1:
ctmvar -action LIST
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>”
Note:
This parameter cannot be specified together with -action LOAD.
For more information about AutoEdit variables, see the AutoEdit chapter
in the CONTROL-M/Enterprise Manager User Guide.
-VAREXPR Value to be assigned to the specified AutoEdit variable. The specified
value can be:
Note:
This parameter cannot be specified together with
-action LOAD.
For more information, see the AutoEdit chapter in the
CONTROL-M/Enterprise Manager User Guide.
-FILENAME Path and name of the file containing the list of AutoEdit variables. The file
must be accessible to CONTROL-M/Server. This parameter is only valid
when specified together with -action LOAD.
Note:
Performance is somewhat slower and requires a larger number of
resources when operating in debug mode. BMC Software recommends
that you activate debug mode only when absolutely necessary and revert
to normal mode as soon as possible.
-input_file Name and full path of a file containing parameters for the utility. In this
file, each parameter and its values (if any) are on a separate line with the
same syntax they would have on the command line. Using the -input_file
parameter enables you to:
Example:
-input_file ~<controlm_owner>/ctm_server/data/ctmvar_parms.txt
Examples
The following command assigns the current value of system variable %%TIME to
AutoEdit variable %%AAA:
You can get the same result using the -input_file parameter as follows:
-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:
For more information about AutoEdit variables, see the AutoEdit chapter in the
CONTROL-M Job Parameter and Variable Reference Guide.
ctmwhy
The ctmwhy utility 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 CONTROL-M/EM window.
ctmwhy <orderID>
The variable <orderID> is the Order ID of a job waiting in the Active Jobs file (as
displayed in the Job Details window of CONTROL-M/EM).
NOTE
The 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, prefix the number with an asterisk, and enclose
the result 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. This response
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"
dbversion
The dbversion utility displays a general description of the CONTROL-M/Server
database in use, including the current version number. A database can be Oracle,
Sybase, or MSSQL.
dbversion
ecactltb
The ecactltb utility displays a list of Control resources and the status of each resource.
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.
NOTE
If the name of an output file is specified, but no path is specified for this file, the output file is
placed in the CONTROL-M/Server home directory.
Example
The following command generates a list of Control resources in the file rprt.txt.
ecactltb ~<controlm_owner>/ctm_server/user1/rprt.txt
ecaqrtab
The ecaqrtab utility performs operations on the Quantitative Resources table. These
operations include:
Use this command to invoke the ecaqrtab utility from the server:
-or-
Use this command to invoke the LIST option of this utility from the agent:
-or-
NOTE
If a resource name is longer than 20 characters, the resource is not added.
Example:
-input_file ~<controlm_owner>/ctm_server/data/ecaqrtab_parms.txt
Note: The path that is specified for this parameter must be accessible by
the CONTROL-M/Server account (even if this utility is requested by
CONTROL-M/Agent.
Table 89 describes the fields that are displayed for each Quantitative resource that
matches the specified resource name or mask.
Example
The following command can be invoked by the server or the agent to list the current
status of all Quantitative resources in the Quantitative Resource table:
+--------------------------------------------------------------+
Resource Name Type Max-Avail Reserved Used Free
+--------------------------------------------------------------+
CPU@linda L 10 0 10 0
CPU@linda L 20 0 15 5
MEM@diana L 10 0 0 10
Tape2 L 12 2 2 10
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:
Example
The following command specifies that the Quantitative resource tape3 is to be deleted
from the table:
Example
The following command specifies that the new maximum availability for the existing
Quantitative resource linerje2 on computer diana is 12 units:
You can get the same result using the -input_file parameter as follows:
UPDATE
linerje2@diana
12
4
4 Maintenance
This chapter describes how to maintain CONTROL-M/Server entities.
You can use CONTROL-M/Server utilities and the CONTROL-M Main Menu
options to access a variety of functions required to customize and maintain the
CONTROL-M/Server data center.
■ CONTROL-M/Server entities
■ Database configuration
■ Periodic maintenance
■ Failover procedures
■ CONTROL-M Main Menu options
■ CONTROL-M/Server processes
■ Shout destination tables
CONTROL-M/Server entities
CONTROL-M/Server is comprised of the following entities:
To start CONTROL-M/Server functions in the data center, run the following entities
on the CONTROL-M/Server computer:
NOTE
If CONTROL-M/Server 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.
■ Automatic startup or shutdown (as part of the server computer boot and
shutdown processes)
You are prompted to enter the DBA password to shut down the SQL database
server.
The Windows administrator, using the Microsoft Windows Services window, can
manually start or stop:
2 In the directory tree of the Cluster Administrator window, right-click the Group in
which CONTROL-M/Server was installed, select CONTROL-M/Server resources
and bring them online.
2 In the directory tree of the Cluster Administrator window, right-click the Group in
which CONTROL-M/Server was installed, select CONTROL-M/Server resources
and take them offline.
Database configuration
The recommended database configuration is described in the CONTROL-M/Server
and CONTROL-M/Agent Installation Guide.
Periodic maintenance
The following procedures should be performed on a regular basis:
You can check the available space in the CONTROL-M/Server database using the
Check Database option in the Database Creation menu (described on page 326).
You can also define a CONTROL-M/Server 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 following utility:
ctmdbcheck
This is the same utility used by the Check Database option. Possible messages
generated by this utility relating to the amount of available space in the
CONTROL-M/Server database are:
$ORACLE_BASE/admin/$ORACLE_SID/bdump/alert$ORACLE_SID.log
■ Trace log files are saved in files with the extension .trc
$ORACLE_BASE/admin/$ORACLE_SID/bdump/$ORACRR_SID_*.trc
Each time CONTROL-M/Server is started, the proclog file from the previous session
is saved to one of the following files:
■ For UNIX
$CONTROLM_SERVER/proclog
■ For Windows
<ctm_installation>\proclog
If CONTROL-M/Server entities are operated for a long time using a trace level
greater than zero, these log files will utilize a large amount of disk space. The
CONTROL-M/Server administrator should delete these files when they are no longer
needed. For more information, see “Erase Proclog Files” on page 351.
By default, the trace log file may have 10 generations (set using the
OS_DIAG_LIMIT_LOG_VERSION parameter), with each file limited to 10 MB (set
using the OS_DIAG_LIMIT_LOG_FILE_SIZE parameter). These, and other relevant
parameters, can be set in the config.dat file. For more information, see “Managing log
files” on page 66.
Failover procedures
The following procedures are used to implement CONTROL-M/Server features
required for failover processing:
Many of the functions for these procedures are accessible from the CONTROL-M
Main Menu. For more information about this menu, see page 322.
3 Choose Database Mirroring => Initialize Mirroring from the CONTROL-M Main
Menu.
NOTE
After mirroring is operational, it cannot be initialized unless the mirroring status is
“damaged” or “disabled”.
■ Rebuild the CONTROL-M/Server primary database from the mirror database and
start CONTROL-M/Server again.
2 Choose Database Mirroring => Use Mirror Database from the CONTROL-M Main
Menu. The following message is displayed:
If you select y, CONTROL-M/Server will start to use the Mirror Database instead
of the primary database. The following message is displayed:
NOTE
This is intended as a temporary solution to restore CONTROL-M/Server functionality as
quickly as possible. At the first opportunity, the CONTROL-M/Server primary database
should be rebuilt and CONTROL-M/Server should be reconfigured to use the primary
database using the following procedure.
3 Under certain conditions (for example, environment variables need to be reset), the
following message is displayed:
B Repeat step 2.
4 Choose Database Mirroring => Initialize Mirroring from the CONTROL-M Main
Menu.
1 Verify that the instance of the database SQL Server used for the mirror database is
running.
2 On the mirror environment, choose Database Mirroring => Start Failover from the
CONTROL-M Main Menu.
NOTE
Do not start CONTROL-M/Server on the mirror environment while CONTROL-M/Server or
the CONTROL-M/Server Configuration Agent is running on the primary computer, or before
the Start Failover procedure finishes executing. If the second CONTROL-M/Server is started,
the following message is displayed:
2 On the mirror environment, choose Database Mirroring => Stop Failover from the
CONTROL-M Main Menu.
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.
ctm_menu
1 - CONTROL-M Manager
2 - Database Creation
3 - Database Maintenance
4 - Database Mirroring
5 - Security Authorization
6 - Parameter Customization
7 - Node Group
8 - View NodeID details
9 - Agent Status
10 - Troubleshooting
q - Quit
3 Enter the number corresponding to the menu you require and press <Enter>. Each
menu is described in this chapter.
1 - Check All
2 - Start All
3 - Start Database
4 - Start CONTROL-M/Server
5 - Start CONTROL-M/Server Configuration Agent
6 - Stop All
7 - Stop Database
8 - Stop CONTROL-M/Server
9 - Stop CONTROL-M/Server Configuration Agent
q - 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.
Table 94 describes the options available from the CONTROL-M Manager Menu.
Note:
■ This option is not available when using an Oracle database.
■ After specifying this utility, you are prompted to enter the DBA
password to access the CONTROL-M/Server database.
Erase Database Erases CONTROL-M/Server database contents after confirmation.
Contents
This option causes the sequential Order number to start again from 1.
Therefore, manually clean the following directories in every
CONTROL-M/Agent that is working with this server:
■ SYSOUT
■ BACKUP
■ STATUS
■ TEMP
■ PROCID
ctmdbcheck
Build database
Use this option to rebuild the CONTROL-M/Server database.
NOTE
During the rebuild procedure a series of parameters are displayed for your specification.
These parameters are the same as those that are requested during installation of
CONTROL-M/Server. For more information about these parameters, see the CONTROL-M/
Server and CONTROL-M/Agent Installation Guide.
Before rebuilding the database, old data can be kept by backing up the data at the
beginning of the rebuild process. The backup can be used to restore the data at the
end of the process.
Follow the prompts on the screens and specify or change the parameters, as
required. The parameters are described in Chapter 5, “Customization parameters.”
Default values are provided for most of these parameters.
NOTE
When rebuilding the database, working in an existing mode, the full path names of the log
and data devices must be different from the original path names.
These menu items are described in detail below. For each item, refer to the above
table to determine which database is applicable.
Archive mode
Use this option to activate the archive mode. In this mode, when database logs are
full, they are written to a special backup destination 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.
If you choose Archive mode, it should be a choice for long term use. If this option is
activated and deactivated frequently, the archived log files will not provide useful
information for database restoration.
NOTE
If 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/Server database onto a backup device. The
function performed by this option is identical to the function performed by
ctmdbbck. For more information, see “ctmdbbck” on page 122. This option can be
invoked while the database is running.
You are prompted to 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.
2 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.
■ 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]:
3 Select either H or C and press <Enter>. The hot and cold backup modes are
described below.
5 Enter the directory in which the archive process will store its control files.
6 Start CONTROL-M/Server.
Restore database
This option restores the CONTROL-M/Server 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 131.
The backup device must be a valid device defined in the database, or the full path
name of a backup file to be used as input for the ctmdbrst utility.
3 Use the List Backup Devices option to display a list of valid devices. For more
information on this option, see“List backup devices” on page 333.
This restore procedure assumes that CONTROL-M/Server and the Oracle database
server are down as the result of a crash. If this is not the case, the restore procedure
will fail.
If you want 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 below.
1 Shut down CONTROL-M/Server. Make sure there are no other users or processes
connected to the SQL Server.
2 Select 3 from the Database Maintenance menu. The following prompt is displayed:
3 Press <Enter> to accept the default directory, or type the name of the directory in
which the backup was saved.
For details about Hot and Cold backups, see step 3 on page 331.
WARNING
If you try 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/Server home directory command line:
sqlplus /nolog
connect / as sysdba
alter database mount;
alter database open;
exit
2 Use the Database Creation => Build Database option to rebuild the database.
3 Use the Restore Database option to load the data into the new database.
A list of backup devices is displayed. Use this option to locate a device for backing up
the CONTROL-M/Server database (see “Backup Database” on page 330).
1 Select the Add Backup Devices option in the Database Maintenance Menu.
Enter <dev_logical_name> :
Enter <disk|tape> :
Enter <file_full_path_name|device name> :
<file_full_path_name| Full name of the path for a disk file or name of the device for a tape.
device_name>
This device can be either a disk file or a tape drive. (Backups to disk files are faster
and do not require operator intervention.)
Example
When prompted, specify the following values for the Add Backup Devices option in
the Database Maintenance Menu:
Variable Value
<dev_logical_name> cont
{disk|tape} tape
<file_full_path_name|device_name> cont_dev
1 Run the Drop Backup Device option from the Database Maintenance Menu.
Enter <dev_logical_name>:
2 Enter the logical name of the device to delete from the list.
The Extend Database Size option extends the size of the data segment only. The size of
the log segment is not extended.
1 Select the Extend Database Size option from the Database Maintenance menu.
When prompted for a logical name for the device, the name you specify must be
unique. The local file system where the device will be located must have enough
free space to accommodate the size that you will specify.
2 Follow the prompts that are displayed. Specify the values, or press <Enter> to
accept the default values.
This option extends the size of the temporary storage area of the database. This
should be approximately 10% of the data segment size.
NOTE
When this option is used, a message similar to the following may be issued:
1 Select the Extend Temporary Database Size option from the Database Maintenance
menu.
2 You are prompted to enter the size to which the database must be extended.
Specify the amount to extend the database, 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, a message is displayed, indicating that the database has
been successfully extended.
Extend database log size (Sybase or MSSQL) or extend rollback tablespace size
(Oracle)
The size of the log segment of the database should be approximately one-third of the
data segment size.
1 Select the Extend Database Log Size option [Sybase and MSSQL] or select the Extend
Rollback Tablespace Size option [Oracle] from the Database Maintenance menu.
2 You are prompted to enter the size of the extension. Specify amount to extend the
database, or press <Enter> to accept the default.
3 Follow the prompts that are displayed. Specify the values, or press <Enter> to
accept the default values. When prompted to supply a file name, 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 you specified above.
For an MSSQL database, the path on the computer where the MSSQL Server is
installed, excluding the name of the computer, is:
drive:\<MSSQLserverDir>\data\ <logicalDeviceName>
To choose this option, select the Show Database Parameters option from the Database
Maintenance menu.
Check database
Displays the size of the CONTROL-M/Server database and availability of space, and
verifies database integrity. Information similar to the following is displayed:
ctmdbcheck can also be used to provide automatic database and transaction log
monitoring. The following options are available:
Quit
Quits the Database Maintenance menu and returns to the CONTROL-M Main menu.
q - Quit
-or-
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.
NOTE
After specifying certain utilities in the table below, you are prompted to enter the DBA
password to access the CONTROL-M/Server database server.
Oracle make_db
Delete Database All <internal utility> 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
Extend Temporary Sybase ctm_tempdb_extend Either run the utility on the
Database Size backup server computer or refer
to your Systems Administrator
1. Specify the full path name of the file. This function can be run only
on the CONTROL-M/Server computer. A message confirming
the completion of the import is displayed.
NOTE
The 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, BMC Software recommends that you use the ctmsec utility
with the -EXPORT option. For more information, see “Exporting security definition tables” on
page 263.
q - Quit
Modify the parameters as required. For a description of each parameter, see Chapter
5, “Customization parameters”. To ensure that changes take effect, stop and restart
CONTROL-M/Server. For more information about starting and stopping
CONTROL-M/Server manually, see page 311.
■ To modify parameters, specify the number appearing next to the parameter that
you want to change. You are prompted for the parameter value.
Modify the parameters as needed. For a description of each parameter, see Chapter 5,
“Customization parameters”. To ensure that changes take effect, stop and restart
CONTROL-M/Server. For more information about starting and stopping
CONTROL-M/Server manually, see page 311.
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.
NOTE
BMC Software recommends that the default for Persistent Connection be left unchanged.
Setting this parameter to Y and restarting CONTROL-M/Server causes the server to try to
connect to all Agents with a persistent connection. Before changing this parameter, ensure that
all the Agents are version 6.2.01 and later.
The following menu is displayed. The current value for each parameter follows the
parameter name:
8) Persistent Connection: N
9) Allow Agent Disconnection: Y
10) Session Idle Timeout: 900
11) Maximum Disconnect Time: 300
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.
NOTE
If you select Save, CONTROL-M/Server sets Persistent Connection with the new value
and attempts to connect to the specific agent. When a connection is established with the
agent, the new configuration is transferred to the agent. The updated agent is reset. This
process can take a few minutes.
4 To exit, specify q.
s) – Save Parameters
q) – Quit
1 To modify a parameter, specify the number appearing next to the parameter that
you want to change.
You are prompted for the parameter value as required. Table 104 describes the
options in the SMTP Parameters Menu.
3 To exit, specify q.
Node Group
For more information about maintaining node groups and application groups for
load balancing, see “ctmnodegrp” on page 199.
q - Quit
For more information about statuses for agent and remote host computers, see
“Communication status of agents and remote hosts” on page 25.
Note:
■ Ensure that no jobs have been submitted or are currently
being executed before invoking this option.
■ The <Local> agent cannot be deleted.
Ping Agent Platform Prompts for the node ID of a computer and then tests the
communication link with the computer. The response
indicates whether the computer is available or unavailable.
The first four options in the above table do not require communication with the agent
or remote host computers. They do not verify that these computers exist. As a result,
the following may occur:
■ The Change options can be used to modify the status of a non-existent computer.
■ If you request the status of a computer that is non-existent, the Discovering default
status is displayed. If the status of the computer has been changed to Disabled, the
computer will appear in the list of Not Available computers.
Troubleshooting menu
The Troubleshooting menu is used to perform a variety of trace activities. Choosing
CONTROL-M Main Menu => Troubleshooting displays the following (the menu
displayed was run on UNIX; for Windows the Check Kernel Configuration option does
not exist):
q - Quit
If one or more parameters are not configured correctly, the parameters are listed
followed by:
Specify the 2-character code for a specific process or ALL for all current process log
files. For more information, see “Set Diagnostics Level” on page 350.
Show Calendar Displays a list of all Calendar names defined in the CONTROL-M/Server database.
Names
Interactive SQL Starts an interactive SQL session that enables you to issue SQL commands to perform
Commands actions in the CONTROL-M/Server database. To end this session, enter the command:
quit.
When this option is selected, you are prompted to supply the node ID of an agent
computer. A trace program is then executed and a report is generated. For more
information, see “ctm_diag_comm” on page 95.
Force Download Forces CONTROL-M/Server to start download of the entire Active Jobs file to
CONTROL-M/EM.
Check directory Checks the current directory and all sub-directories under it for permissions.
permissions
Set communication Enables the communication trace value to be modified while CONTROL-M/Server is
trace up. This value determines whether there will be a communication trace between
CONTROL-M/Server and CONTROL-M/Agents. (Prior to this menu option, the trace
value could only be changed by directly accessing the Configuration parameters, which
required stopping and starting CONTROL-M/Server.)
Quit Quits the Troubleshooting menu and returns to the CONTROL-M Main Menu.
CONTROL-M/Server processes
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
106 on page 350 for details.
NOTE
If CONTROL-M/Server is restarted, the trace level for all CONTROL-M/Server processes is
automatically reset to zero.
Table 108 describes the parameters that are set when responding to these prompts.
$CONTROLM_SERVER/proclog/
<process-name><process-ID>.log
0 – All components.
2 – Event manager.
3 – Database layer.
Process Name Indicates a two-character code for a specific process, or ALL for
all CONTROL-M/Server or CONTROL-M/Server
Configuration Agent processes.
Specify the desired sleep time (in seconds), and then specify the two-character code
for a specific process, or ALL for all CONTROL-M/Server processes.
See Table 110 on page 358 for a description of the process codes appearing in the
prompt.
Troubleshooting report
Creates a report containing specified CONTROL-M/Server system information. This
option is typically used at the request of Technical Support to determine the cause of
a CONTROL-M/Server problem.
2 Switch the flag from Y to N. The default value for each option is “include all
information”.
For UNIX
For Windows
The generated report is saved in a file named CtmReport.txt and placed in the
data\Temp sub-directory.
Example
[UNIX]
<controlm_path >/report.<mmddyyhhmm>.tar.Z
■ 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
■ User name under which the process is running (for UNIX only)
■ Process ID (for example, 5703)
■ Run time (for example, 0:02) (for UNIX only)
■ 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).
NOTE
Shut 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):
It is also possible to reset the CONTROL-M/Server process sleep times and trace
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. See Table 110 on page 358.
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.
Example
Figure 31 Directing shouts using the Active Shout Destination Table
■ 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 3, “Utilities”).
Designation of the active Shout Destination table can be performed using one of the
following methods:
■ Using the ctmsys interactive utility. 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 the ctmshtb utility. This utility accepts the name of the Shout Destination
table to make active.
NOTE
Shout messages are automatically recorded in the CONTROL-M/Server log. Select the log as
a destination only if you do not want to send the message to any additional destination.
<hostname><message> <severity>
O, L, and No physical name is specified because each of these
E destinations is unique.
■ the Shout Destination Type is set to M and the Shout Address Type is set to S in
the Shout Destination table.
■ CONTROL-M/Server service runs under the user specified in This Account and
this user:
5
5 Customization parameters
You can customize CONTROL-M/Server 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.
■ System parameters
■ Communication parameters
■ Operational parameters
■ Agent Communication parameters
■ Database parameters
■ Mirroring parameters
■ Performance parameters
■ Configuration parameters
■ Watchdog process parameters
Parameter coordination
For CONTROL-M/Server to communicate with agent computers and with the
CONTROL-M Configuration Manager, 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.
System parameters
CONTROL-M system parameters are assigned default values during installation. For
more information, see the CONTROL-M/Server for UNIX and Microsoft Windows
Installation Guide. These parameters can be modified using the ctmsys utility,
described in Chapter 3, “Utilities”. CONTROL-M system parameters are listed below.
Modifiable parameters are identified by an asterisk (*). All other parameters are
“display only”.
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).
Executable Path Location where CONTROL-M/Server expects to find all its executable
programs (for example, /usr/controlm/ctm_server/exe_Solaris).
Full Security * Whether CONTROL-M operates in a restricted or unrestricted level of
security. Valid values:
Y (restricted) and N (unrestricted). Default: N
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.
Ignore New Day Specifies whether the New Day procedure should ignore prerequisite
Conditions * conditions whose reference date (day and month) matches the
CONTROL-M date+1. See “Ignore new day conditions parameter”
below.
The value of this parameter also affects the number of days old nets are
saved. To view SYSOUT files of jobs in old nets, in some cases SYSOUT
files must be saved an extra calendar day.
Maximum Days Maximum number of days that entries are retained in the
Retained by CONTROL-M log before being deleted by the New Day cleanup
CONTROL-M procedure. Default: 2
Log *
Note:
■ If you set the number of days to be retained to a number greater
than 2, the syslogs can run out of space. Either delete the transaction
log or use ALTER DATABASE to increase the size of the segment.
■ For Sybase, if you set the number of days to be retained to a number
greater than 4, enlarge size of the tempdb. BMC Software
recommends using the following formula to determine the size by
which the tempdb should be increased: 6% of the data portion size
of the database multiplied by the number of days to be retained.
For more information about enlarging the tempdb, see “Extend
temporary database size” on page 336.
Example
When using Sybase, if the data device size is 400 MB and the history for
10 days must be retained, enlarge the tempdb to 240 MB.
Maximum Number of times the CONTROL-M auto-recovery mechanism can
Retries * reactivate CONTROL-M/Server processes in case of failure. If this
number is exceeded,
CONTROL-M/Server is shut down. Default: 10
Operating System Operating system running on the server computer (for example, AIX).
Secure Sockets Handshake protocol for communications between CONTROL-M/
Layer Server and CONTROL-M/EM and between CONTROL-M/Server and
CONTROL-M/Agent. Valid values:
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
Out Conditions parameter 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.
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 day after the new CONTROL-M date.
■ When this parameter is N, the New Day procedure deletes any prerequisite
condition whose reference date matches the day after 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.
~<controlm_owner>/ctm_server/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.)
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.
NOTE
If 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 day after 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_*rpt
pre_prn
srt_def_?
The following table demonstrates which prerequisite conditions will be deleted from
the Conditions/Resources table in the CONTROL-M/Server database by the New
Day procedure:
Conditions existing before executing New Conditions remaining after executing New
Day Procedure Day Procedure
bra_fn_01 14/01 bra_fn_01 14/01
bra_fn_01 15/01
srt_def_a1 15/01
Example 2
If Ignore New Day Conditions parameter is set to Y, The Ignore Conditions file
contains an asterisk (*).
■ When the cleanup has completed the cleanup on one database, it performs a
cleanup on the other database. For example the clean_ajf stored procedure starts on
the mirror database only after it ends successfully on the primary database.
■ When run in an asynchronous way, the cleanup is performed in parallel on both
databases.
■ Mirroring is disabled (marked as damaged) in the following cases:
— If the transaction fails on the primary database.
— If the transaction fails on the mirror database.
For information about the usage of SSL and how to set the Secure Sockets Layer
parameter, see the SSL for CONTROL-M Administrator Guide.
Communication parameters
You can modify communication parameters during installation. You can also modify
these parameters afterwards using the Parameter Customization menu. For more
information, see “Parameter Customization Menu” on page 342.
This parameter specifies the port used in the server computer for
receiving data from the agent computer. The second port is specified
using Server-to-Agent Port Number parameter (described in “Agent
communication parameters” on page 375) Default: 7005
The value for this parameter must match the value assigned to
Agent-to-Server Port Number parameter on the agent computer.
Verify that the port number specified for this parameter is not used
for any other purpose in the server computer. The value for this
parameter must be a number between 1024 and 65533 inclusive.
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:
■ For UNIX
arp <host_name>
■ For Windows
ipconfig
The system responds with the IP address mapped to the host name on the local
computer.
NOTE
Even 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 computer and the CONTROL-M
Configuration Manager. Use the arp command (see above) to verify that the host name on
each computer is mapped to the same IP address.
You can also ensure that both computers 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 computer.
Operational parameters
Operational parameters are modifiable during installation. You can also modify these
parameters afterwards using the Parameter Customization menu. For more
information, see “Parameter Customization Menu” on page 342.
The parameters for communicating with agent computers are described in Table 117.
Default: 07
Example
If the value of Communication Timeout is 120 and Maximum Retries
is 12, CONTROL-M/Server attempts to communicate with the agent
computer once every 10 seconds (120/12) during the timeout period.
Maximum Indicates the maximum number of concurrent sessions that the NS
Concurrent Sessions process will hold.
Default values are N for a new agent installation and N for an agent
that is known to CONTROL-M/Server before upgrading to version
6.2.01 and above.
Database parameters
Database configuration parameters are specified during installation before the
CONTROL-M/Server database is created. You can also modify these parameters and
rebuild the CONTROL-M/Server database using the Database Creation menu,
described in Chapter 4, “Maintenance.”
Configuration parameters for the following databases are discussed in this section:
Sybase
Table 118 Sybase database parameters (part 1 of 2)
Parameter Description
CONTROL-M Name of Sybase device on which CONTROL-M/Server database will
Database Data be created. (See the disk init command in the Sybase Commands
Device Name Reference Manual for information about creating a Sybase device.)
Default: ctrlm_ux
CONTROL-M Name of Sybase device on which CONTROL-M/Server database log
Database Log Device will be created. (See the disk init command in the Sybase Commands
Name Reference Manual for information about creating a Sybase device.)
Default: ctrlm_log
CONTROL-M Name for the CONTROL-M/Server database. This name must be
Database Name unique. Default: ctrlm
CONTROL-M Sybase name for the CONTROL-M/Server database owner. The
Database Owner custom script creates this user in the database. This name is used by
CONTROL-M when accessing its database. Default: ctrlm
Data Device Type Type of disk storage (raw partition or file system) used for the
CONTROL-M/Server database. Default: FILE
Data Physical For Data Device Type FILE: Full path name where the
Device/Path Name CONTROL-M/Server database will be located.
Default: /<controlm_home_dir>/sybase/data/ctrlm_ux.dat
For Data Device Type RAW: Physical device name of the raw
partition in which the CONTROL-M/Server database will be located.
Database (Data Amount of space (in MB) to allocate for the data portion of the
Portion) Size CONTROL-M/Server database. Default: 50
For Log Device Type RAW: Physical device name of the raw
partition in which the CONTROL-M/Server database log will be
located.
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
For Master Device Type RAW: Physical device name of the raw
partition on which the Sybase database will be located.
Query Socket Port Sybase utilizes these two TCP/IP ports for communication between
Number CONTROL-M and Sybase SQL Server. The port numbers must be
-and- different from each other. If these port numbers are already used by
Backup Socket Port an existing application, choose other values, each in the range 1024 to
Number 65534 inclusive. Default: 7102 and 7103
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
Oracle
Table 119 Oracle database parameters (part 1 of 2)
Parameter Description
CONTROL-M Database The name of the Oracle SQL server (1 to 8 characters,
Instance name alphabetic plus “_”). Default: ctrlm
CONTROL-M INDEX Full path name to the CONTROL-M INDEX tablespace file.
tablespace file location
Default: /<controlm_home_dir>/oracle/oradata/ctrlm/
indx01.dbf
CONTROL-M INDEX Size of the CONTROL-M INDEX tablespace file. Default: 50
tablespace size MB
CONTROL-M Listener port Oracle utilizes this TCP/IP port for communication between
number 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
Default: /<controlm_home_dir>/oracle
Oracle Server Host name The host computer name of an existing Oracle server.
Oracle SYSTEM user Password of the Oracle SYSTEM user.
password
Size of CONTROL-M The size of each database log file. There are two files of equal
database log files size. Default: 20 MB
Tablespace size Total size of the CONTROL-M/Server database. Default:
250 MB
Tablespace User Name of CONTROL-M/Server database user. Default:
controlm
User Password Password for the CONTROL-M/Server 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/Server database. Default: password
MSSQL
Table 120 MSSQL database parameters (part 1 of 2)
Parameter Description
Server Host Name Host name of the machine where the SQL Server resides. If
the dedicated SQL Server was installed, the value is the
current machine. For a silent installation the value of this
parameter is blank, and the installation procedure uses the
name of the current machine.
Query Port Number The database utilizes these two TCP/IP ports for
communication between CONTROL-M/Server and the SQL
-and- Server. The port numbers must be different from each other.
If these port numbers are already used by an existing
Backup Port Number application, choose other values, each in the range 1024 to
65534 inclusive. Default: 7102 and 7103
Default: c:\<sql_dir>\data\ctrlm_log
Log Device Size Amount of space (in MB) to allocate for the CONTROL-M/
Server database log. Default: 25
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.”
(Oracle)
CONTROL-M Mirror Name for the CONTROL-M/Server mirror database owner.
Database Owner The install_mirror script creates this user in the database. This
name is used by CONTROL-M when accessing the mirror
(Sybase and Oracle) database. Default: ctrlm
(Oracle)
Mirror Sybase Server Name of the SQL server to which CONTROL-M will connect for
Name mirroring. When you choose to modify this value, the
install_mirror script reads the Sybase interfaces file and
(Sybase) 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 of computer that runs the instance of the database
Host Name (Sybase and SQL Server used for mirroring.
Oracle)
Mirror Sybase/Oracle Port TCP/IP query port number for the database SQL Server used
Number (Sybase and for mirroring. If you are using a CONTROL-M dedicated
Oracle) 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 parameter
A special parameter is available for tuning CONTROL-M performance. This
parameter affects how jobs are selected for both scheduling and post-processing.
Table 122 describes the performance parameter in the CONTROL-M
~<controlm_owner>/ctm_server/data/config.dat file. The variable <controlm> is the
CONTROL-M home directory.
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 358.
Configuration parameters
The following tables contain the parameters in the CONTROL-M/Server
configuration parameter file (~<controlm_owner>/ctm_server/data/config.dat on the
server computer).
Valid values:
Default: LOCAL
■ Y group conditions are checked for each job in the group (in
addition to conditions specified for the job).
Note:
■ To implement a change to this parameter, you must shut
down and then restart CONTROL-M/Server. For more
information about starting and stopping CONTROL-M/
Server manually, see page 311.
■ 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_MULTIP_LIB {Y|N}. Default: N
_REPLACE
Indicates if AutoEdit variable %%MEMLIB overrides the
MEMLIB value for all jobs in a Scheduling table with a
command such as:
Default: YES
CTMLOG_DEL_CHK {YES, NO}
When 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
■ 1 – User Daily job ends with an exit code of 14 if not all jobs
are ordered.
Example
Assume that the value of the Local IP Host Interface Name parameter must be
modified.
2 Modify the value of the Local IP Host Interface Name parameter using either
regedit or ctm_menu.
4 Start CONTROL-M/Server.
NOTE
To set parameters described in Table 124 to the specified value permanently, update the ~/
.cshrc file and re-logon to CONTROL-M/Server.
CONTROL-M/Server communication
parameters
Table 125 CONTROL-M/Server communication parameters
Parameter name {Valid values} Explanation
CMN_PRM_CD {1000 – 65K}
_MAX_DBU CONTROL-M accumulates all updates to the database before
sending them to CONTROL-M/EM. This parameter determines
the maximum number of updates to accumulate before requesting
a Download. Default 1000
CMN_PRM_CD {60 – 32K}
_MAX_SERVICE Maximum number of requests (originating from CONTROL-M/
EM gateways) that can be queued by CONTROL-M/Server.
Default: 60
MAX_GET_HOST {1 - 2048}
_RETRIES Maximum attempts by CONTROL-M/Server to retrieve network
information about a CONTROL-M/Agent computer. Default: 5.
If the information is not retrieved within the specified number of
attempts, the status of the agent computer is listed as Unavailable
by CONTROL-M/Server.
NOTE
The SYSOUT of a job can be attached to an e-mail message only if the job has completed
processing.
Note:
■ If the SYSOUT file is larger than the specified
maximum size, the SYSOUT will not be attached to the
e-mail message.
■ To implement a change to this parameter, you must
shut down and then restart CONTROL-M/Server. For
more information about starting and stopping
CONTROL-M/Server manually, see page 311.
To close a Remedy help case, users must have both Administrator and Administrator
Problem Management permissions.
■ New (Default)
■ Assigned
■ Work In Progress
■ Pending
■ L = Low (Default)
■ M = Medium
■ H = High
■ U= Urgent
■ C = Clear
REMEDY_CASE_SOURCE Displays the source of a Remedy help ticket.
Default: REQUESTER
REMEDY_CASE_TYPE Displays the case type of a Remedy help ticket.
Default: INCIDENT
■ General parameters
■ CONTROL-M/Server system exit parameters
■ Watchdog user exit parameters
General parameters
Table 131 General Watchdog Process parameters (part 1 of 2)
Parameter name {Valid values} Explanation
WD_ALIVE_MSG Message string sent every interval to the error handlers if all the
Watchdog processes are functioning. BMC Software
recommends that you use this parameter when using
CONTROL-O/Server as an error handler (see
WD_CTO_HOSTNAME below). Default: WD is alive
WD_CTMEXIT_ {n}
NUMBER Total number of CONTROL-M/Server system exits to run.
Default: 2
WD_CTO_HOSTNAME Host name or IP address of the computer 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 Full path name of a user defined script called by the Watchdog
_SCRIPT_FILE process as an error handler. The error messages are included as
arguments to the script. Default: ./scripts/UE_handler that
sends alerts to CONTROL-M/EM.
WD_ERROR_HANDLER {n}
_TIMEOUT Maximum time in seconds to wait for the error handler script to
run before terminating the script. Default: 5
WD_HEARTBEAT_ {n}
INTERVAL Nth interval in the Watchdog process to check CONTROL-M/
Server processes. If this parameter is set to 5, the Watchdog
process sends a message to each of the primary CONTROL-M/
Server processes every 5th interval and awaits a response.
Default: 5
WD_HEARTBEAT_ {n}
TIMEOUT Maximum time (in seconds) to wait for a response from each of
the CONTROL-M/Server processes, after issuing a Heartbeat
check, before sending a message to the error handlers. Default:
360
6
6 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 CONTROL-M processing, a flat text file is
produced describing information that is to be passed to the 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.
■ For UNIX
■ For Windows
NOTE
A special category of user exits can be defined for the Watchdog facility. For more
information, see “Watchdog facility” on page 69.
Some of these parameters are described in Table 135. For more information, see
Chapter 5, “Customization parameters.”
Default: N
CTM_PRM_SCRIPT_UExxx string Name of the UExxx user exit script (where xxx = 101-106).
These scripts must reside in the directory
~<controlm_owner>/ctm_server/ue_exit
Default: ctm_exitxxx.sh
CTM_PRM_TIMEOUT_UExxx {n} Time to wait for the associated user exit script to run
before it is terminated (where xxx = 101-106). Default: 20
NOTE
User exits are implemented only if they have been enabled by setting the appropriate
configuration parameters (described in Table 135 on page 409).
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).
The following is a sample text file in the format that is passed to the CTMUE101 exit:
JOBNAME daily_job
JOBNO 30
DESCRIPT
APPLIC STRESS
APPLGROUP STRESS
SCHEDTAB STRESS
AUTHOR ctm600
OWNER ctm600
PRIORITY 0
CRITICAL N
CYCLIC N
RETRO N
AUTOARCH N
TASKCLASS
CYCLICINT 0
TASKTYPE C
DATEMEM
NODEGRP
computer
NODEID
DOCLIB
DOCMEM
MEMLIB
MEMNAME
OVERLIB
CMDLINE ./stress_cmd_spl.ctm600
MAXRERUN 0
MAXDAYS 0
MAXRUNS 0
FROMTIME
UNTIL
MAXWAIT 0
DAYSTR ALL
WDAYSTR
MONTHSTR YYYYYYYYYYYY
AJFSONSTR NNNNNNNNNNNNN
CONF N
UNKNOWNTIM 0
DAYSCAL
WEEKCAL
CONFCAL
CAL_ANDOR O
SHIFT
ADJUST_COND
STARTENDCYCIND S
CREATIONUSERID ctm600
CREATIONDATETIME 20001113070229
CHANGEUSERID
CHANGEDATETIME
RELATIONSHIP
GROUPID 0
TABROWNO 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/ksh
cp $1 /tmp/ue101.$$
sed -e 's/DAYSTR 1/DAYSTR 2/' /tmp/ue101.$$ > $1
The following is a sample text file in the format that is passed to the CTMUE102 exit:
JOBNO 0
ORDERNO 19450
PRIORITY 1039
CRITICAL N
TASKTYPE C
CYCLIC N
CONFIRM_R N
CONFIRMED N
RETRO N
AUTOARCH N
TASKCLASS
HOLDFLAG N
STATUS N
STATE E
CYCLICINT 0
APPLGROUP dw_S_A_AAS
NODEGRP
NODEID fire
MEMLIB /mdw/oper/tgt/scripts/shells
MEMNAME dw##r#####
OVERLIB /mdw/oper/tgt/scripts/shells/overlib_all
CMDLINE sleep 30
ODATE 19960229
PROCID
RERUN_NO 0
OSCOMPSTAT 0
OSCOMPMSG
NEXTTIME
PREVDATE
NEXTDATE
STARTRUN
ENDRUN
MAXRERUN 0
FROMTIME
UNTIL
JOBNAME dwlnr21AAS
SCHEDTAB CREATED
OWNER ctm600
MAXWAIT 7
APPLIC DW_ln
RUNCOUNT 1
DAILYNAME ctm600
AJFSONSTR YYNNYNNNNNNNN
DESCRIPT Datawarehouse ln snapshot sort and form
DOCMEM dwlnr1
DOCLIB /mdw/cntlm/doc
MAXDAYS 0
MAXRUNS 0
UNKNOWNTIM 0
STARTENDCYCIND S
TRIGGER_TAG
GROUP_ORD 0
AUTHOR
Example
The following exit script checks if the job has a Owner of root and changes the Owner
for these jobs to nobody.
#!/bin/ksh
cp $1 /tmp/ue102.$$
sed -e 's/OWNER root/OWNER nobody/' /tmp/ue102.$$ > $1
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.
The following is a sample text file in the format that is passed to the CTMUE103 exit:
DAILY_NAME SYSTEM
TIME 1300
ODATE 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
The following is a sample text file in the format that is passed to the CTMUE104 exit:
DAILY_NAME SYSTEM
TIME 1319
ODATE 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
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.
The following is a sample text file in the format that is passed to the CTMUE105 exit:
DAILY_NAME my_daily
TIME 1321
ODATE 20001121
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.
The following is a sample text file in the format that is passed to the CTMUE106 exit:
DAILY_NAME my_daily
TIME 1322
ODATE 20001121
NOTE
If the User Daily job fails, the User Exit 106 (UE106) will not be executed.
7
7 Mirroring and Failover
As CONTROL-M/Server is integrated in the production environment of the data
center, it becomes increasingly important to ensure that interruptions of
CONTROL-M/Server functionality are as short as possible.
This chapter provides in-depth information about database mirroring and failover
support for the CONTROL-M/Server computer. 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
The Mirror Database option is illustrated schematically in Figure 32. In addition to
the primary database installed with CONTROL-M/Server, a secondary database is
built on another Database Server computer. All updates to the primary
CONTROL-M/Server database are written to the secondary mirror database.
If updates to the mirror database fails, the mirror database is considered damaged
and writing to it is disabled. Normal CONTROL-M/Server operation is not affected.
Mirroring can be re-initialized after you repair the communications link.
■ You can direct CONTROL-M/Server to use the mirror database instead of the
primary database. The primary CONTROL-M/Server database can be rebuilt
when time allows.
■ You can repair and rebuild the CONTROL-M/Server primary database and
restore it from the mirror database.
The mirror database should be built on a separate database server, independent of the
database server that hosts the primary CONTROL-M/Server database.
NOTE
Database 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 mirror database from scratch, you will need the password of the
Sybase system administrator to build the database.
■ Sybase Host Name - host name of the computer 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 Sybase dsedit utility to find this value. For more
information about the Sybase dsedit utility, see Sybase documentation.
■ The user connections, memory, and locks parameters must contain appropriate
values. For more information, see the CONTROL-M/Server and CONTROL-M/
Agent Installation Guide.
If you change the value of any of these parameters, the change will not be
implemented until you shut down and restart the Sybase SQL Server. For more
information about Sybase parameters see descriptions of dsedit, sp_configure, and
reconfigure in the Sybase Commands Reference Manual.
If you will be building a database, you must supply values for the database owner,
database name, devices and file or partition paths:
■ Specifying existing owner name, database name, and device assignments will
erase and recreate these database elements.
■ Specifying new, unique values for owner name, database name, and device
assignments will build a new database on the server.
For more information about database names, see create database in the Sybase
Commands Reference Manual. For more information about logon names, see
sp_addlogin in the Sybase Commands Reference Manual.
5 Every computer 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 sp_configure to configure the character set for the existing SQL Server. See the
description of sp_configure in the Sybase Commands Reference Manual.
NOTE
Database 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 mirror database from scratch, you will need the password of the
Oracle system administrator for installation.
■ Oracle Host Name - Host name of the computer 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_SID
Run the following command referring to the entry found based on the result of the
command issued above.
cat $TNS_ADMIN/listener.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/Server 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.
NOTE
Database and account names that you create must conform to MSSQL naming conventions.
1 Verify that the MSSQL Server used for mirroring will be running, both when
initializing mirroring, and whenever CONTROL-M/Server is operational.
2 When building a mirror database from scratch, you will need the password of the
MSSQL system administrator to build the database.
3 Determine the value of the MSSQL Host Name parameter. This is the host name
of the computer that runs the MSSQL Server to be used for mirroring.
If you will be building a database, you must supply values for the database owner,
database name, devices and file or partition paths:
■ Specifying existing owner name, database name, and device assignments will
erase and recreate these database elements.
■ Specifying new, unique values for owner name, database name, and device
assignments 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.
5 Every computer type uses a different character set for MSSQL. 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 MSSQL Server.
Failover Server
The Failover Server option is illustrated schematically in Figure 33. 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.
Jobs submitted to agent computers before failover continue executing. The secondary
CONTROL-M/Server polls the agent computers to determine the status of jobs listed
in the Active Jobs file.
Requirements and preparatory steps for the failover server are described in
“Preparing a failover server” below.
Several administrative functions are used to initialize and use the failover server, and
restore the primary computer. These functions are accessed from the Database
Mirroring menu of the CONTROL-M/Server Main Menu. (For details, see “The
Database Mirroring menu” on page 426). The functions are described in Table 136 on
page 427.)
■ The Database (Data Portion) Size parameter should be assigned the same value
as the current size of the primary database.
The host name of the failover server must be added to the list of authorized
hosts of each agent.
ctm_menu
1 - CONTROL-M Manager
2 - Database Creation
3 - Database Maintenance
4 - Database Mirroring
5 - Security Authorization
6 - Parameter Customization
7 - Node Group
8 - View NodeID details
9 - Agent Status
10 - Troubleshooting
q - Quit
q - Quit
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 136 summarizes the Database
mirroring options.
NOTE
[UNIX only] Most 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, re-log on to the CONTROL-M/Server account to update user
environment variables414.
■ 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” on page
432.
3 Verify all communications links to agent computers that are configured on the
primary CONTROL-M/Server computer. Enter the host computer of the mirror
environment in each list of authorized servers for each agent. Verify that the
CONTROL-M/Server Configuration Agent port number specified for the
secondary CONTROL-M/Server is the same as that specified for the primary
CONTROL-M/Server.
Each time that you run this command, replace the <remoteHostName> variable with
the name of remote host from the list generated in step 4 above.
6 Verify that:
A Specify the ctm_menu command to open the CONTROL-M Main Menu. Type 4
to select Database Mirroring and press <Enter>.
B From the Database Mirroring menu, type 6 to select Initialize Failover and
press <Enter>.
D Press <Enter> to return to the Database Mirroring menu. Then type q and press
<Enter> to exit the Main Menu.
For Sybase
Use the table below to determine the values of required Sybase database
environment variables.
For Oracle
Use the table below to determine the values of required Oracle database
environment variables.
For MSSQL
Use the table below to determine the values of required MSSQL database
environment variables.
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.
1 Verify that the secondary database server conforms to the requirements for
mirroring, as described in:
2 Verify that:
■ To initialize a mirror database for a Sybase SQL Server, continue with the
procedure “Copying or building the mirror database for a Sybase SQL Server,”
below.
■ To initialize a mirror database for an Oracle SQL Server, continue with the
procedure “Copying or building the mirror database for an Oracle SQL Server”
on page 439.
■ To initialize a mirror database for an MSSQL database, continue with the
procedure “Copying or building the mirror database for an MSSQL database”
on page 444.
1 From the Database Mirroring menu, type 2 to select Initialize Mirroring and press
<Enter>.
+----------------------------------------+
|Copy/Build the CONTROL-M Mirror database|
+----------------------------------------+
To copy the primary database to an existing secondary database, type c and press
<Enter>.
NOTE
If you are initializing database mirroring for the first time, and you are not using a Failover
server, you must select the build option to create the mirror database.
2 The Mirroring Parameters screen is displayed. The variable names that are
displayed are for explanatory purposes only.
■ If you selected the copy option in step 1 above, the Mirroring Parameters screen
for Sybase Database Servers is displayed.
Verify the Mirroring parameters and modify the values as necessary. Table 141
describes the parameters. Parameter values must conform to Sybase naming
conventions.
5 Type Y to confirm the start of the copying procedure, and press <Enter>.
■ If you selected the build option in step 1 on page 432, the following confirmation
screen is displayed:
+------------------------------------------------------+
| Control-M Server database Mirroring Customization |
+------------------------------------------------------+
Working...**********************************************************
This script can cause changes to files from the existing Sybase
installation !!!
Would you like to continue ?( default : No )
y
continuing with the current installation.
Verify the Mirroring parameters and modify the values as necessary. Table 141
describes the parameters. Parameter values must conform to Sybase naming
conventions.
This value is taken from the current size of the primary database. It
should not be modified. Verify that the secondary database server
can host a database of this size. Verify that this value is the same as
the primary database.
== <H> Help <C> Cancel <P> Previous Panel <N> Next Panel ==
Verify the Mirroring parameters and modify the values as necessary. Table 141
describes the parameters.
== <H> Help <C> Cancel <P> Previous Panel <N> Next Panel ==
Verify the Mirroring parameters and modify the values as necessary. Table 141
describes the parameters.
== <H> Help <C> Cancel <P> Previous Panel <N> Next Panel ==
Verify the Mirroring parameters and modify the values as necessary. Table 141
describes the parameters.
■ If the database is being built with a database name that already exists, the
following message is displayed:
copying database
contents............................................................
............
Create indexes. This may take several minutes, please wait...
source ~/.cshrc
If the device name specified already exists, the following message is displayed.
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.
14 Exit the current session and start a new logon session, or re-log on to the
CONTROL-M/Server account to reset user environment variables in the current
window.
1 From the Database Mirroring menu, type 2 to select Initialize Mirroring and press
<Enter>.
+----------------------------------------+
|Copy/Build the CONTROL-M Mirror database|
+----------------------------------------+
To copy the primary database to an existing secondary database, type c and press
<Enter>.
NOTE
If you are initializing database mirroring for the first time, and you are not using a Failover
server, you must select the build option to create the mirror database.
2 The Mirroring Parameters screen is displayed. The variable names that are
displayed are for explanatory purposes only.
■ If you selected the copy option in step 1 on page 432, Figure 35 shows the Mirroring
Parameters screen for Oracle Database Servers.
If you selected the build option step 1 on page 432, additional parameters are
displayed as in Figure 36.
Mirroring Parameters:
3 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 142. 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.
echo $ORACLE_SID
4 When you are satisfied with the values of all the parameters, specify b to build or c
to copy, and press <Enter>.
If you selected the copy option, the initialization process continues with step 9.
Please confirm that you wish to build a new CONTROL-M Mirror database
[y/n] :y
+------------------------------------------------------+
| Control-M Server database Mirroring Customization |
+------------------------------------------------------+
Working...
8 Specify the mirror and primary passwords, as prompted. The following message is
displayed:
ATTENTION !!!
The data tablespace file location is on the Server Host Machine
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.
9 Specify 2 and press <Enter>. Enter the password for the mirror database.
10 To copy the primary database to an existing mirror database, specify c and press
<Enter>.
+-----------------------------------------------+
| CONTROL-M Database Mirroring Customization |
+-----------------------------------------------+
Working...
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.
13 Exit the current session and start a new logon session, or specify the command
source ~/.cshrc to reset user environment variables in the current window.
2 From the Database Mirroring menu, type 2 to select Initialize Mirroring and press
Enter.
You can choose to use a copy of an existing database for mirroring, or build a new
database on an existing database server.
NOTE
If you are initializing database mirroring for the first time, and you are not using a Failover
server, you must build a new database for mirroring.
Data is copied from the primary database to the database you specified. Go to step
8 on page 447.
This procedure builds the mirror database on the target server. Data is copied from
the primary database to the mirror database.
3 In the dialog box that is displayed after clicking Build, type or select a Database
Server Name from the drop-down list and click Next.
4 Click Next. In the dialog box that is displayed, specify the parameters, as described
in the table below.
Parameter Description
CONTROL-M/Server Name for the CONTROL-M/Server database. The name must
Database Name begin with a letter (A-Z, a-z) followed by up to 29
alpha-numeric characters (includes underscores).
Database Size Amount of space (in MB) to allocate for the data portion of the
database. Take into consideration the number of jobs in the
Active Jobs file.
5 Click Next. In the dialog box that is displayed, specify the parameters, as described
in the table below.
Parameter Description
Data Device Physical Full Specify a new filename which includes the full path to the
Path File Name physical device where the CONTROL-M/Server database
resides.
Data Device Size Amount of space (in MB) to allocate for the data portion of
the database. Take into consideration the number of jobs in
the Active Jobs file.
Log Device Physical Full Path Specify a new filename which includes the full path to the
File Name physical device where the CONTROL-M/Server database
log resides.
Log Device Size Amount of space (in MB) to allocate for the transaction log.
The recommended amount is 1/3 of the data device size.
6 Click Next.
8 To verify that mirroring is active, select Database Mirroring => Check Mirroring
Status from the CONTROL-M/Server Main menu.
When the primary database is stable, restore normal operation using the procedure
“Restoring the primary database from the mirror database” on page 449.
■ Restore the CONTROL-M primary database from the mirror database and start
CONTROL-M/Server again.
To implement this option, follow the procedure “Restoring the primary database
from the mirror database” on page 449 to rebuild the primary database and
resume normal operation.
3 Specify the ctm_menu command to open the CONTROL-M Main Menu. Type 4 to
select Database Mirroring and press <Enter>.
4 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]:
For UNIX
■ specify the command source ~/.cshrc to reset user environment variables in the
current window.
For Windows
NOTE
This 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 reconfigured to use the primary database.
8 [For UNIX] Exit the current session and start a new logon session, or specify the
command source ~/.cshrc to reset user environment variables in the current
window.
■ When the primary CONTROL-M/Server fails, use the procedure “Failover to the
secondary CONTROL-M/Server,” see below, 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 452 to restore normal
function.
5 From the Database Mirroring menu, type 7 to select Start Failover and press
<Enter>.
WARNING
Do 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 may be displayed:
Continue [y/n] :
9 From the Database Mirroring menu, specify q to return to the CONTROL-M Main
Menu.
NOTE
At 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. For more
information about starting and stopping CONTROL-M/Server manually, see page 311.
5 From the Database Mirroring menu, type 8 to select Stop Failover and press
<Enter>.
Failover Stopped
8 Continue with “Restoring the primary database from the mirror database” on
page 449. After this step is completed, the mirroring status is enabled. In the
CONTROL-M Configuration Manager, double-click the CONTROL-M/Server
component. In the dialog box that is displayed, modify the host name to that of the
primary CONTROL-M/Server.
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 3, “Utilities.”
3 After failing to restart the primary CONTROL-M/Server, you initiate the failover
procedure on the mirror environment. This starts CONTROL-M/Server, which
will operate using the mirror database.
NOTE
If the primary CONTROL-M/Server does not respond to a CONTROL-M/Agent or remote
host computer request to execute a utility (other than ctmping), the request is automatically
redirected to the first non-primary server listed in the Authorized CONTROL-M/Server
Hosts parameter. If the redirection is successful, that agent, or remote host computer,
continues to work with the replacement server.
A
Structure of CONTROL-M/Server Log
A
Entries
The CONTROL-M/Server log is part of the CONTROL-M/Server database in each
data center. For more information, see “CONTROL-M/Server log” on page 49.
B
B Unsupported Utilities
The following utilities are provided “as is.”
BMC Software does not support these utilities and assumes no responsibility for
problems that may occur as a result from using these utilities. BMC Software advises
users not to use these utilities:
■ addevice
■ addto_interfaces_file
■ ags
■ ajf
■ ctm_backup_aut
■ ctm_grj
■ ctm_jcl
■ ctm_mirrordb_bck
■ ctm_newday
■ ctm_shout
■ ctm_sysout_down
■ ctm_sysout_hndl
■ ctmdbcount
■ ctmeditjcl
■ ctmgtsch
■ ctmjckdl
■ ctmjcopy
■ ctmlbsel
■ ctmmksch
■ ctmshdst
■ ctmtunnelreq
■ ctmweb
■ CtoSrvDa
■ dbbackupora
C
Conversion of agents and remote
C
hosts
This appendix describes how to convert a computer that is defined in the
CONTROL-M/Server database as a CONTROL-M/Agent computer, to a remote host
computer, or the other way around.
1 Ensure that no jobs have been submitted or are running on the required agent.
Log onto the sql database server and run the following SQL commands to
determine all the owners used on the agent computer:
Add one of the following on a separate line at the end of the commands:
■ For Oracle: ;
■ For Sybase or MSSQL: go
Example
To convert a node with the name cyborg on Oracle, log onto the sql database server
and run the following commands to determine all the owners used on cyborg:
Use the CONTROL-M Configuration Manager to define all the owners used on the
agent computer. For more information about using the CONTROL-M
Configuration Manager, see the CONTROL-M/Enterprise Manager Administrator
Guide.
For the procedure to determine all users, see step 2 on page 462.
You can run a script using the ctmsetown utility to define all the owners used on
the agent computers. For more information, see “ctmsetown” on page 265.
3 For each agent, ensure that no jobs have been submitted or are running.
4 Use ctmhostmap, with the -force option, for each required agent to be defined as a
remote host. For more information, see “ctmhostmap” on page 168.
1 Ensure that no jobs have been submitted to, or are running on, the required remote
host.
2 Delete the remote host from the CONTROL-M/Server environment. Use the
CONTROL-M Configuration Manager to delete the remote host. For more
information about using the CONTROL-M Configuration Manager, see the
CONTROL-M/Enterprise Manager Administrator Guide.
1 Ensure that no jobs have been submitted to, or are running on, the required remote
host.
2 Disable the remote host. Use the Agent Status menu, selected from CONTROL-M
Main Menu, to disable the remote host, or use the ctm_agstat utility. For more
information about the Agent Status menu, see “Agent Status menu” on page 348.
For more information about the ctm_agstat utility, see “ctm_agstat” on page 91.
3 Delete the remote host from the CONTROL-M/Server environment. Use the Agent
Status menu, selected from CONTROL-M Main Menu, to delete the remote host, or
use the ctmhostmap utility. For more information about the ctmhostmap utility,
see “ctmhostmap” on page 168.
4 Discover the regular agent. Use ctmping to discover the agent. For more
information, see “ctmping” on page 212.
Glossary
A
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/Server database.
Agent computer
computer on which CONTROL-M/Agent runs. The agent computer handles requests from
CONTROL-M/Server to execute jobs or provide information.
C
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 Date
Date used by CONTROL-M to assign the Scheduling date (Odate) to jobs.
Glossary 465
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
CONTROL-M Log
Log containing a complete audit trail of every significant event occurring in the CONTROL-M
production environment.
CONTROL-M computer
computer on which CONTROL-M/Server runs.
CONTROL-M/Agent
The component of CONTROL-M which runs on each agent computer. 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 computer. CONTROL-M/Server
maintains the CONTROL-M/Server database (including the Active Jobs file), schedules jobs,
performs load balancing, sends job-handling requests to agent computers, and handles requests
from CONTROL-M/EM.
Conditions/Resources Table
A component of the CONTROL-M/Server 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.
D
Database
This is the CONTROL-M/Server database that holds all CONTROL-M/Server-related
information. Can be either Oracle, Sybase or MSSQL.
F
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”.
G
Gateway
The process that handles communication between CONTROL-M/Server and CONTROL-M/
EM. There are gateway processes on both the server computer and the CONTROL-M
Configuration Manager (prior to version 6.3.01 this was CONTROL-M/EM workstation).
Global Condition
A prerequisite condition that is passed between data centers using CONTROL-M/EM. Global
conditions allow jobs in one data center to be dependent on completion of a job in another data
center.
H
Heartbeat Monitor
Special monitor which verifies that TCP/IP communication with CONTROL-M/EM is
functional.
J
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.
Glossary 467
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
L
Load Balancing
CONTROL-M mechanism for maximizing throughput of production jobs by automatic selection
of the computer to execute each job, based on workload considerations.
M
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/Server 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.
N
New Day Procedure
Formerly “General Daily Procedure”. Daily scheduling and housekeeping procedures which
run on the server computer. 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 computers from which CONTROL-M/Server can select a computer
to execute the job.
Node ID
Name by which an agent or remote host computer is identified to the server computer. This is
generally the host name of the computer.
O
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.
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”.
P
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.
Primary Database
See “CONTROL-M/Server (Primary) Database”.
Q
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.
R
Remedy Helpdesk
CONTROL-M/Server can open problem tickets in the Remedy Helpdesk System when
specified ON statement criteria are satisfied.
S
Scheduling Table
A collection of related job processing definitions. Scheduling tables are stored in the
CONTROL-M/Server database (and duplicated in the CONTROL-M/EM database).
Scheduling tables are “ordered” by the New Day procedure or User Daily jobs.
Server computer
Computer on which CONTROL-M/Server runs. The server computer communicates with the
CONTROL-M Configuration Manager and with the agent computers.
Glossary 469
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
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 computer’s resources.
SQL Server
Software used to maintain the CONTROL-M/Server database on Microsoft Windows
computers. The database can be maintained using an existing SQL Server (provided by the
user).
U
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.
W
Watchdog Process
Mechanism which automatically monitors CONTROL-M processes and resources
Index
Symbols
+nn description 375
shift the job 143 modifying 345
Agent platforms
application server information 348
Index 471
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index 473
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index 475
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index 477
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index 479
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index 481
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index 483
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index 485
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index 487
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z