You are on page 1of 490

CONTROL-M/Server

for UNIX and Microsoft Windows


Administrator Guide

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.

Restricted rights legend


U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE
COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the
U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS
252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is
BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX 77042-2827, USA. Any contract notices should be sent to
this address.
Customer support
You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer
Support by telephone or e-mail. To expedite your inquiry, please see “Before Contacting BMC Software.”

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

Support by telephone or e-mail


In the United States and Canada, if you need technical support and do not have access to the web, call 800 537 1813 or
send an e-mail message to support@bmc.com. Outside the United States and Canada, contact your local support center for
assistance.

Before contacting BMC Software


Before you contact BMC Software, have the following information available so that Customer Support can begin working
on your problem immediately:
■ product information
— product name
— product version (release number)
— license number and password (trial or permanent)
■ operating system and environment information
— machine type
— operating system type, version, and service pack or other maintenance level such as PUT or PTF
— system hardware configuration
— serial numbers
— related software (database, application, and communication) including type, version, and service pack or
maintenance level
■ sequence of events leading to the problem
■ commands and options that you used
■ messages received (and the time and date that you received them)
— product error messages
— messages from the operating system, such as file system full
— messages from related software

3
4 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide
Contents
Chapter 1 Overview 17
About CONTROL-M/Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 2 Working with CONTROL-M/Server 21


CONTROL-M/Server database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Server interaction with agents and remote hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Agent computers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Remote host computers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Managing requests from CONTROL-M/Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Communication status of agents and remote hosts . . . . . . . . . . . . . . . . . . . . . . . . . 25
Discovering agents and remote hosts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
CONTROL-M/Server behind a firewall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Using a persistent connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Interrupted communication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Time-related functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Authorized CONTROL-M servers file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Agent configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Load balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Backup and restore procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Backup and restore–using Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Backup and restore–using Sybase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Backup and restore–using MSSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Failover planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Host identification in agent computers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
User Daily jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Date control record (UDLAST) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Handling of interruptions during a User Daily job . . . . . . . . . . . . . . . . . . . . . . . . . 40
Issuing a job order manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
New Day procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Scheduling Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Ordering of Group Scheduling tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Group scheduling and processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Shout facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Runtime statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
CONTROL-M/Server log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Time zone support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Time zones and job ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Time zone jobs in the Active Jobs file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

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

6 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmjsa. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
ctmkeygen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
ctmkeystore_mng . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
ctmkilljob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
ctmldnrs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
ctmloadset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
ctmlog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
ctmnodegrp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
ctmordck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
ctmorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
ctmpasswd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
ctmping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
ctmpsm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
ctmreindex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
ctmrpln . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
ctmruninf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
ctmsec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
ctmsetown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
ctmshout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
ctmshtb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
ctmspdiag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
ctmstats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
ctmstvar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
ctmsuspend. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
ctmsys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
ctmudchk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
ctmudlst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
ctmudly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
ctmvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
ctmwhy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
dbversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
ecactltb. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
ecaqrtab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Chapter 4 Maintenance 309


CONTROL-M/Server entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Database configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Periodic maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Checking available space in CONTROL-M/Server database. . . . . . . . . . . . . . . . 313
Cleaning up the database message log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Increasing the size of the master database log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Cleaning up the proclog directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Failover procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
CONTROL-M/Server database mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Recovering from database failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Recovering from CONTROL-M/Server computer failure . . . . . . . . . . . . . . . . . . 320
CONTROL-M Main Menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Opening CONTROL-M Main Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
CONTROL-M Manager menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

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

Chapter 5 Customization parameters 363


Categorizing CONTROL-M/Server parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Parameter coordination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
System parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Ignore new day conditions parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Database cleanup actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Secure Sockets Layer (SSL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Local IP host interface name parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Operational parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Agent communication parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Database parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
MSSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Mirroring parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Performance parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
CONTROL-M/Server configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Parameters that reside in the registry [Windows] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
CONTROL-M/Server environment parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
CONTROL-M/Server communication parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
CONTROL-M/EM communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
CONTROL-M/Server e-mail configuration parameters . . . . . . . . . . . . . . . . . . . . . . . 397
CONTROL-M/Server Do Remedy parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
User exit parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
CONTROL-M/Server communication and debug parameters. . . . . . . . . . . . . . . . . . 401
Watchdog process parameters (config.dat) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
General parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
CONTROL-M/Server system exit parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Watchdog user exit parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

Chapter 6 User Exits 407


Configuring CONTROL-M Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

8 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


User Exit workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Job Order Exit (CTMUE101) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Job Submission Exit (CTMUE102) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Before New Day Procedure Exit (CTMUE103) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
After New Day Procedure Exit (CTMUE104) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Before User Daily Exit (CTMUE105) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
After User Daily Exit (CTMUE106) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

Chapter 7 Mirroring and Failover 417


Failover planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Mirror database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Preparing a mirror CONTROL-M/Server database on a Sybase server. . . . . . . 419
Preparing a mirror CONTROL-M/Server database on an Oracle server . . . . . . 421
Preparing a mirror CONTROL-M/Server database on an MSSQL server . . . . . 422
Failover Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Failover administration procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
The Database Mirroring menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Initializing failover server and mirror database . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Initializing mirror database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Recovering from database failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Recovering from primary CONTROL-M/Server failure (Server failover). . . . . 450
Synchronizing the primary and mirror databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Example of a failover scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

Appendix A Structure of CONTROL-M/Server Log Entries 457


CONTROL-M/Server log fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

Appendix B Unsupported Utilities 459

Appendix C Conversion of agents and remote hosts 461


Converting an agent to a remote host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Converting multiple agents to remote hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Converting a remote host to an agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

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

14 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Entities that run on the CONTROL-M/Server computer . . . . . . . . . . . . . . . . . . . . . . 310
Location of the dedicated database message log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Increasing the size of the master database log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
CONTROL-M Main Menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
CONTROL-M Manager Menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Database Creation Menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Database Maintenance Menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Types of backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Logical device description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Menu Options for Modifying Database Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Options of the Database Mirroring Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Utilities affecting the primary database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Security Authorization Menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Customization parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Options in the SMTP parameters menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Agent Status Menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Troubleshooting Menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Two-Letter codes for CONTROL-M/Server processes . . . . . . . . . . . . . . . . . . . . . . . . 352
Diagnostic level parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Columns of the Show Process Flags table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Sleep Time Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Shout message destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Parameter coordination with CONTROL-M/EM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Parameter coordination with Agent computers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
System parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Operational parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Parameters for communicating with agent computers . . . . . . . . . . . . . . . . . . . . . . . . 375
Sybase database parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Oracle database parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
MSSQL database parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Mirroring parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Performance parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
CONTROL-M/Server configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
CONTROL-M/Server environment parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
CONTROL-M/Server communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
CONTROL-M/EM communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
E-mail configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Do Remedy configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
User exit parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
CONTROL-M/Server communication and debug parameters . . . . . . . . . . . . . . . . . 401
General Watchdog Process parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Watchdog parameters for CONTROL-M/Server system exits . . . . . . . . . . . . . . . . . 403
Watchdog parameters user exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
CONTROL-M General User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Exit Configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Database Mirroring menu options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Sybase environment variables and alternative names . . . . . . . . . . . . . . . . . . . . . . . . 430
Oracle environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

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

16 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Chapter

1
1 Overview
This book describes how to maintain CONTROL-M/Server on either a UNIX or a
Microsoft Windows computer.

This book describes concepts relating to CONTROL-M administration, and provides


details regarding parameters and utilities that administrators will utilize in fulfilling
their functions.

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.

CONTROL-M/Server submits jobs for execution on Agent or remote host computers,


monitors the jobs and performs post-processing analysis, after which it may perform
post processing actions. The completion status of jobs and the results of
post-processing analysis are transmitted to CONTROL-M/Enterprise Manager.

Chapter 1 Overview 17
Conventions

A typical job execution proceeds as follows:

1. A job waiting to be submitted “waits” on the server computer.

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.

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


CONTROL-M/Server.

5. Upon completion of the job, CONTROL-M/Agent and CONTROL-M/Server


perform the post-processing analysis.

The CONTROL-M Installation Guide describes how to install and manage


CONTROL-M/Server on UNIX and Microsoft Windows computers. The installation
guide also describes how to install and manage CONTROL-M/Agent on various
computers.

An overall description of CONTROL-M/EM and CONTROL-M concepts is provided


in the first chapters of the CONTROL-M Concepts Guide. BMC Software recommends
that you familiarize yourself with the material contained there before proceeding
with this guide.

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.

The following abbreviations and terms are used in this guide:

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.

18 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Conventions

The following table describes conventions used in this guide.

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.

Users and Groups=>Groups=>Add

An option selection sequence means that you first select


Users and Groups from the menu bar. Then, select the
Groups option from the submenu. Finally, select the Add
option from the Groups submenu.
{Option A|Option B} The vertical bar is used to separate choices.

{AND|OR}

This example shows that you specify either AND or OR.


[Option] Square brackets are used to enclose parameters that are
optional.
<variable> In commands and parameters, angle brackets are used to
enclose variable information.

cd <controlm_path>

In this command, you specify cd followed by the installation


path of CONTROL-M.
italic An italic font is used for the name of publications.
Messages Messages are presented in this font.
Wildcards or Certain CONTROL-M utilities and parameters support
Mask Characters wildcards. These are also sometimes referred to as mask
characters. A mask is a string value containing wildcards.

The following wildcard characters are supported:

? indicates any one character

* indicates any number of characters

Note: Values containing mask characters must be enclosed in


single or double quotation marks.

Chapter 1 Overview 19
Conventions

20 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Chapter

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

Chapter 2 Working with CONTROL-M/Server 21


CONTROL-M/Server database

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.

The CONTROL-M/Server database contains the following information:

■ 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

Server interaction with agents and remote


hosts
The following topics are discussed in this section:

■ “Agent computers” on page 22


■ “Remote host computers” on page 23
■ “Managing requests from CONTROL-M/Server” on page 24
■ “Communication status of agents and remote hosts” on page 25
■ “Discovering agents and remote hosts” on page 27

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.

CONTROL-M/Agent can submit jobs to a remote host for execution.

22 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Remote host computers

When you install CONTROL-M/Server, a CONTROL-M/Agent might be installed


on the same computer (for UNIX, it is installed on the same account). When a
CONTROL-M/Agent is installed on the same computer as CONTROL-M/Server, it is
called the <Local> agent in the CONTROL-M/Server mapping table.

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.

Remote host computers


As of version 6.3.01, a CONTROL-M/Agent does not have to be installed on each
computer where jobs run. Jobs can run on agentless computers called remote hosts.
Each remote host is identified by its node ID.

Although remote host computers do not require a resident CONTROL-M/Agent,


remote hosts come under the control of CONTROL-M/Agents on other computers.
CONTROL-M/Server submits job requests to a CONTROL-M/Agent, which
connects to the remote host computer where the jobs must run.

If a CONTROL-M/Agent is installed on the CONTROL-M/Server computer, that


<Local> agent is mapped as the default agent for connecting to remote hosts. But you
can also designate other CONTROL-M/Agents, installed on other computers, to
connect to remote host computers under the same CONTROL-M/Server. (For more
information, see “ctmhostmap” on page 168.)

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.

Configuring computers to act as a remote hosts

For new computers (computers without agents)

1. Define the job owner and authentication settings.

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.

Chapter 2 Working with CONTROL-M/Server 23


Managing requests from CONTROL-M/Server

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:

■ If you plan to use any non-default settings, the CONTROL-M Configuration


Manager, which requires that you fully define the settings, is recommended.

■ If you plan to use default settings, the ctmhostmap utility is recommended


because it then requires only that you specify the Node ID. A job submitted to
this Node ID will cause CONTROL-M/Server to discover the computer as a
remote host, using default remote host map settings. In this case, you must
ensure that no agent using the same agent default communication parameters as
CONTROL-M/Server runs on this computer.

For information about the discovery process, see “Discovering agents and
remote hosts” on page 27.

For existing agent computers

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.

Managing requests from CONTROL-M/Server


CONTROL-M/Agent and remote host computers manage requests from
CONTROL-M/Server, such as

■ instructions to submit a job on a remote host or a computer that is running


CONTROL-M/Agent
■ requests for information regarding jobs on the agent or remote host computer that
are currently executing or were recently completed
■ requests to view or edit job script statements
■ requests to view job SYSOUT or job documentation

24 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Communication status of agents and remote hosts

In addition, CONTROL-M/Agent can perform the following functions as instructed


by job processing parameters supplied with the job submission request:

■ handling of job SYSOUT


■ issuing of Shout messages

CONTROL-M/Agent uses a “listener” process to accept requests from


CONTROL-M/Server. By default, CONTROL-M/Agent includes this listener
process.

Communication status of agents and remote hosts


CONTROL-M/Agents and remote hosts are identified by their node IDs. The node
ID is the computer host name.

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.

CONTROL-M/Server uses TCP/IP protocol to communicate with agent and remote


host computers. The connection to remote hosts can be made either by using SSH or
WMI communication protocol. CONTROL-M/Server maintains a list of agent and
remote host computers to which it submits requests, and assigns a status to each
computer. This status indicates the success or failure of communication with the
computer. Valid communication statuses are described in Table 1.

Chapter 2 Working with CONTROL-M/Server 25


Communication status of agents and remote hosts

Table 1 Communication statuses


Status Description
Available After running the discovery process, an agent or remote host computer
has the Available communication status if it is accessible and can
receive requests from CONTROL-M/Server.

Communication to the agent or remote host is checked periodically by


CONTROL-M/Server. If the agent or remote host is marked Available
and the check fails, the status of the agent or remote host is changed to
Unavailable.
Unavailable If the discovery process for an agent or remote host is not completed
successfully, that agent or remote host is assigned Unavailable status.

This status is also assigned if communication with the agent or remote


host ends with an error.

Communication to the agent or remote host is checked periodically by


CONTROL-M/Server. If the agent or remote host is marked
Unavailable and the check succeeds, the status of the agent or remote
host is changed to Available.
Disabled You can manually assign the Disabled status to an agent or remote
host computer if you want to temporarily prevent
CONTROL-M/Server from submitting jobs to that computer.
CONTROL-M/Server will not attempt to communicate with a
disabled agent or remote host computer until its status is manually
changed to Available. When the status of an agent computer or remote
host is changed to Disabled, any jobs that were running on the
computer at that moment are assigned Disappeared status.
Discovering A computer is in discovering status until its type and status is
determined. The following computer types are subjected to the
discovery process:
■ if the computer type is agent and no attempt has been made to
communicate with the computer since the computer was last in
discovery status
■ if the type is remote host and no attempt has been made to see if
the remote host is alive or not, since the remote host was last in
discovery status
■ if the agent type is unknown and CONTROL-M/Server could not
determine the type of computer (whether it is an agent or remote
host)

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

26 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Discovering agents and remote hosts

Discovering agents and remote hosts


The CONTROL-M/Server discovery process attempts to communicate with other
specified computers. At the conclusion of the discovery process, the type (agent or
remote host) and status (available, unavailable, and so on) of the other computer is
determined and set. The computers with which the discovery process attempts to
communicate remain in a discovery process loop until the type and status of the
specified computers are determined.

Discovery process loop

After a computer is in discovery status, the system checks it for type, as follows:

1. If the type of computer is agent, CONTROL-M/Server attempts to communicate


with the agent.

■ If communication is successful, the status is set to available


■ If communication is not successful, the status is set to unavailable

2. If the type of computer is remote host, CONTROL-M/Server attempts to


communicate with the computer.

■ If communication is successful, the status is set to available


■ If communication is not successful, the status is set to unavailable

3. If the type of computer is unknown, CONTROL-M/Server attempts to connect to


the computer as if an agent is installed on the computer.

■ If connection is successful, CONTROL-M/Server updates the type of


computer to regular agent and sets its status to available
■ If connection is not successful, CONTROL-M/Server attempts to connect to
the computer as if it is a remote host
— If CONTROL-M/Server successfully connects to the computer as remote
host, it registers the computer type as a remote host and sets its status to
available
— If CONTROL-M/Server is not successful in connecting to the computer as
remote host, the computer remains as unknown type with discover status.
The computer will continue to be checked periodically by
CONTROL-M/Server.

Chapter 2 Working with CONTROL-M/Server 27


CONTROL-M/Server behind a firewall

CONTROL-M/Server behind a firewall


If CONTROL-M/Server is located behind a firewall on your internal network, and
the CONTROL-M/Agents that communicate with this server are on the other side of
your firewall (on your internal network or on an external network), the agent to
server port is blocked. As a result, CONTROL-M/Server can connect to
CONTROL-M/Agent, but CONTROL-M/Agent cannot connect to
CONTROL-M/Server.

Using a persistent connection


For CONTROL-M/Server to connect to an agent through a firewall, set the agent
communication mode to persistent and in the agent, modify the settings so that it
does not attempt to connect to the server. With a persistent connection, the
connection between server and agent is constant and can be initiated by either the
server or the agent.

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:

1 Enter the command ctm_menu.

2 Select the Parameter Customization Menu and press <Enter>.

3 Select the Parameters for Communicating with Specific Agent computers option
and press <Enter>.

4 Specify the agent name and press <Enter>.

5 From the Parameters for Communicating with Specific Agent computers menu,
select Persistent Connection and press <Enter>.

6 Specify Yes 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.

28 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Interrupted communication

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.

When communication between CONTROL-M/Server and an agent computer is


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

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

■ time values recorded for operations in the CONTROL-M log.

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.

Chapter 2 Working with CONTROL-M/Server 29


Authorized CONTROL-M servers file

Authorized CONTROL-M servers file


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

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.

Agent configuration parameters


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

30 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Load balancing

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.

This feature enables CONTROL-M to optimize utilization of available resources and


ensure maximum production throughput.

The following CONTROL-M facilities are used to administer load balancing on the
server computer:

■ The Node Group menu (described in Chapter 4, “Maintenance”) is used to define


which agent computers are contained in each node group.

■ The ctmloadset utility is used to report utilization of Quantitative resources on an


agent computer by non-CONTROL-M jobs.

■ The Quantitative Resources window (in CONTROL-M/EM) is used to view or


define Quantitative resources available on the server computer or agent
computers.

For an overview of the load balancing facility, see “Load Balancing” in the
CONTROL-M Concepts Guide.

Chapter 2 Working with CONTROL-M/Server 31


Backup and restore procedures

Backup and restore procedures


The following topics are described in this section:

■ “Backup and restore–using Oracle” on page 32


■ “Backup and restore–using Sybase” on page 34
■ “Backup and restore–using MSSQL” on page 34

Backup and restore–using Oracle

Backup procedure
CONTROL-M supports the following backup procedures:

■ Hot backup – This procedure does not shut down CONTROL-M/Server. A


backup can be made while running CONTROL-M/Server. Also, the database can
be restored without losing transactions. For more information, see “Hot backup”
on page 331.

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

This restore procedure is based on the following assumptions:

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

32 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Backup and restore–using Oracle

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

Workflow for the restore procedure


The CONTROL-M/Server restore executable first connects to the Oracle database.
This database should be in “startup mount" mode. Then, the executable checks
whether the database is running in "Archiving" mode.

If Archiving is not enabled, the following steps are performed:

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.

If Archiving is enabled, the following steps are performed:

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.

Chapter 2 Working with CONTROL-M/Server 33


Backup and restore–using Sybase

Backup and restore–using Sybase

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 and restore–using MSSQL

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.

34 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Failover planning

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

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

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

■ loss of integrity in the CONTROL-M/Server primary database due to a failure of


the SQL server that maintains the database

■ failure of the computer on which CONTROL-M/Server runs (server computer)

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

Chapter 2 Working with CONTROL-M/Server 35


Host identification in agent computers

Host identification in agent computers


Each agent computer has a unique set of configuration data. This data includes the
following items:

■ CONTROL-M/Server Host Name


This is the host interface name of the server computer currently issuing
job-handling requests to the computer.

■ Authorized CONTROL-M/Servers File


This file contains a list of the host names of server computers that are authorized to
issue job-handling requests to the computer. The current server computer host
name appears in this list.

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

The CONTROL-M/Server Host Name is retained by the agent computer as a part of


the CONTROL-M failover mechanism. If the agent computer detects that the host
name accompanying a request does not match the current host name in the Agent
Configuration file, CONTROL-M/Agent performs the following actions:

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

■ If the new host name appears in the list, CONTROL-M/Agent automatically


modifies the current host name in the agent Configuration file and processes the
request. This situation indicates that a failover has occurred.

This mechanism enables a backup server 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.

36 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


User Daily jobs

User Daily jobs


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

A User Daily job is actually no different from any other regular job handled by
CONTROL-M. The User Daily job is defined 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.

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

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.

Chapter 2 Working with CONTROL-M/Server 37


User Daily jobs

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.

Job Processing parameters Script file


Job Name ACCUDAILY1 Script file udaily (referred to by the
Application USER_DAILIES Job Processing parameter Mem
Name) contains the following line:
Task Type Job
Description Accounting User Daily ctmudly $1
Scheduling Table ACCTDAILY
For more information about the
Author michelle ctmudly utility, see Chapter 3,
Owner bill “Utilities.”
Mem Name udaily
Mem Lib /usr/bill/bin
AutoEdit Assignments %%PARM1 = UDAILY1

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

38 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Date control record (UDLAST)

This causes all Scheduling tables assigned to UDAILY1 to be ordered (including


Scheduling table ACCOUNTING and Group Scheduling table ACCGROUP referred
to above).

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

Date control record (UDLAST)


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

For example:

■ The computer has not been working for a day or more (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.

Use of the date control record by User Daily jobs


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

■ If UDLAST is earlier than Odate (the normal situation), UDLAST is updated


automatically to the current installation working date. This date is then used by the
User Daily job as the current scheduling date.

Chapter 2 Working with CONTROL-M/Server 39


Handling of interruptions during a User Daily job

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

Handling of interruptions during a User Daily job


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

If a User Daily job is interrupted for any reason (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.

40 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Issuing a job order manually

Issuing a job order manually


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

The following options are available on the CONTROL-M Configuration Manager for
issuing a job order manually:

Table 2 Options for issuing a job order manually


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

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

■ as additional jobs in an already ordered instance of the same Group


Scheduling table

■ as jobs in a new instance of the Group Scheduling table

■ as standalone jobs that are not part of a Group Scheduling table

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.

Chapter 2 Working with CONTROL-M/Server 41


New Day procedure

New Day procedure


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

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

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

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

The New Day procedure performs the following sequence of operations:

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

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.

2. The message FORMATTING AJF is displayed in the CONTROL-M/EM


Communication Status window for the data center.

3. A partial cleanup of the CONTROL-M/Server log is performed, based on system


parameter Maximum Days Retained By CONTROL-M Log. This parameter
specifies the maximum number of days that entries are retained in the
CONTROL-M/Server log before being deleted by the cleanup procedure.

4. A partial cleanup of job SYSOUT directories on agent computers is performed,


based on system parameter Maximum Days to Retain Sysout Files. This
parameter specifies the maximum number of days that job SYSOUT files are
retained in the SYSOUT directory before being deleted by the cleanup procedure.

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.

42 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


New Day procedure

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.

You can partially or completely disable cleanup of prerequisite conditions by using


the CONTROL-M system parameter Ignore New Day Conditions.

6. A partial cleanup of the statistics in the CONTROL-M/Server database is


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

7. A partial cleanup of the information in the JOBINF table that is specific to any one
instance of a job run, is performed.

8. A selective cleanup of prerequisite conditions is performed. Prerequisite


conditions are deleted if their date reference (month and day) is equal to the new
CONTROL-M date +1 (tomorrow). This prevents jobs from being triggered by
prerequisite conditions remaining from the previous year.

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.

Chapter 2 Working with CONTROL-M/Server 43


Scheduling Jobs

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:

■ There are a large number of jobs.


■ Jobs can be clearly divided into separate categories.
■ Different jobs are managed by different people.

User Daily jobs can be defined according to function (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:

44 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Scheduling Jobs

Figure 1 New Day procedure and User Daily jobs

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

2. The New Day procedure scans the CONTROL-M/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.

Chapter 2 Working with CONTROL-M/Server 45


Ordering of Group Scheduling tables

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.

Ordering of Group Scheduling tables


Group Scheduling tables are ordered only if the scheduling criteria of at least one
Schedule Tag in the table is satisfied. Whether individual jobs in each Group
Scheduling table are ordered depends on the Relationship parameter and on the
values of 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, prerequisite Out Conditions are set, and
Shouts and ON_GROUP_END OK actions are performed.)

46 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Group scheduling and processing

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.

Group scheduling and processing


Jobs whose processing (scheduling, submission, and post-processing) should be
handled as a group, can be defined in a special Scheduling table, called a Group
Scheduling table. Each Group Scheduling table consists of the processing definitions
for each job in the group. It also contains preprocessing and post-processing
parameters to be applied to all jobs in the Group Scheduling table. Defining common
information for all jobs in a group saves time and enforces standardization of
production handling for the relevant jobs.

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.

Chapter 2 Working with CONTROL-M/Server 47


Runtime statistics

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 CONTROL-M/EM display of currently running jobs includes a real-time


graphical indication of the percentage of the runtime remaining for each job, based
on the job’s runtime statistics.

CONTROL-M generates runtime statistics by compiling information that is contained


in the Statistical Details table of the CONTROL-M/Server database and storing this
information in a summary table. Runtime statistics for a given job are passed to the
CONTROL-M Configuration Manager each time that job is ordered.

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

■ The CONTROL-M system parameter Statistics must be set to Y (the default value).
This 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.

48 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server log

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:

■ operation of the New Day procedure and User Daily jobs

■ changes in the availability of Control resources, Quantitative resources and


prerequisite conditions

■ job submissions and terminations, reruns, job log (SYSOUT) handling and Shout
performance

■ user actions affecting jobs, whether performed using the CONTROL-M


Configuration Manager or using utilities on the server computer

■ failures to adhere to security definitions on the server computer

■ all Shout messages issued by CONTROL-M

On the CONTROL-M Configuration Manager, CONTROL-M/Server log entries


relating to a specific job that is displayed in the active network can be viewed by
using the Log window.

On the server computer, all CONTROL-M/Server log entries can be viewed using the
CONTROL-M ctmlog utility (described in Chapter 3, “Utilities”).

Chapter 2 Working with CONTROL-M/Server 49


CONTROL-M/Server log

Entries are placed in the CONTROL-M/Server log continually as long as


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

The structure of CONTROL-M/Server log entries is described in Appendix A,


“Structure of CONTROL-M/Server Log Entries.”

50 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Time zone support

Time zone support


Beginning with version 6.1.01, CONTROL-M provides time zone support. This
support is intended for sites that have CONTROL-M/Agent computers in different
time zones than the CONTROL-M/Server computer.

As of version 6.3.01, CONTROL-M provides automatic support for daylight saving


time. For more information, see “Daylight saving time zone definitions” on page 55.

Time zone support consists of the following components:

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

Time zones and job ordering


CONTROL-M provides a file containing a list of predefined time zones and their
offsets (from GMT) in the TimeZone.dat file in the CONTROL-M_ home/data directory.
These predefined time zones and offsets are described in Table 3.

Table 3 Time zone values (part 1 of 2)


Value Time zone description Offset
HNL Honolulu GMT-10:00
HAW Hawaii GMT-10:00
Note: HAW is maintained for backward compatibility purposes
ANC Anchorage Standard Time GMT-09:00
PST Pacific Standard Time GMT-08:00
MST Mountain Standard Time GMT-07:00
CST Central Standard Time GMT-06:00
EST Eastern Standard Time GMT-05:00
ATL Atlantic Standard Time GMT-04:00
RIO Rio de Janeiro GMT-03:00
GMT Greenwich Mean Time GMT+00:00
WET Western European Time GMT+01:00

Chapter 2 Working with CONTROL-M/Server 51


Time zones and job ordering

Table 3 Time zone values (part 2 of 2)


Value Time zone description Offset
CET Central European Time GMT+02:00
EET Eastern European Time GMT+03:00
DXB Abu Dhabi GMT+04:00
KHI Karachi GMT+05:00
DAC Dacca GMT+06:00
BKK Bangkok GMT+07:00
HKG Hong Kong GMT+08:00
TYO Tokyo GMT+09:00
TOK Tokyo GMT+09:00
Note: TOK is maintained for backward compatibility purposes
SYD Sydney GMT+10:00
MEL Melbourne GMT+10:00
NOU Noumea GMT+11:00
AKL Auckland GMT+12:00

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.

Note the following points

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

52 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Time zone jobs in the Active Jobs file

■ 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

For more information about these utilities, see Chapter 3, “Utilities.”

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

Time zone jobs in the Active Jobs file


In versions of CONTROL-M earlier than 6.1.01, the Active Jobs file contained only
jobs that were ordered for the current working day.

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.

To avoid this problem:

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.

Chapter 2 Working with CONTROL-M/Server 53


Adding and modifying time zone definitions

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.

Adding and modifying time zone definitions


You can add or modify lines in the TimeZone.dat file. Modifying existing time zone
definitions is useful when clocks within a particular time zone change (for example,
to and from daylight saving time). Creating new time zone definitions is useful when
clocks in the same time zone reflect different times (for example, if remote Agents in
the same time zone are situated in different countries and these countries implement
daylight saving time on different dates).

NOTE
The daylight saving time feature is not supported in the CONTROL-M/EM TimeZone.dat
file.

To create a daylight saving time for a time zone, you must

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

54 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Adding and modifying time zone definitions

Standard time zone definitions


Definitions in the time zone TimeZone.dat file must conform to one of several formats.
The format without daylight saving considerations is discussed in the following
section. For more information about the other formats and their syntax, see “Daylight
saving time zone definitions” on page 55.

Syntax to specify time zone without daylight saving time

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)

Table 4 on page 56 describes this syntax.

EXAMPLE
To create a time zone for New York city that is five hours earlier than Greenwich Mean Time,
specify
NYC (GMT-05:00)

Daylight saving time zone definitions


The following section discusses the format for definitions in the time zone
TimeZone.dat file with daylight saving considerations. You should use this syntax
when configuring the TimeZone.dat file for CONTROL-M/Server.

Syntax to specify time zone as of version 6.3.01

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

Specifying time zone with daylight saving considerations

Zone 1 Zone 2

xxx (GMT±hh:mm) FROM dd.mm hh:mm TO dd.mm hh:mm (GMT±hh:mm)

Chapter 2 Working with CONTROL-M/Server 55


Adding and modifying time zone definitions

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

Table 4 Time zone syntax


Format Description
xxx three upper case letters designating the time zone

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

Use a leading zero if necessary.


mm the difference in minutes between the relevant time zone and Greenwich Mean
Time (GMT), expressed as a 2-figure number

Note: The only valid values for mm are 00 or 30.


FROM the beginning 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.
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.

56 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Adding and modifying time zone definitions

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:

JST (GMT+09:00) FROM 01.03 01:59 TO 24.10 02:00 (GMT+10:00)

Example 2

To create a new daylight saving time zone definition, EST use the following syntax:

EST (GMT-05:00) FROM 02.04 01:59 TO 29.10 02:00 (GMT-04:00)

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:

SYD (GMT+10:00) FROM 25.03 03:00 TO 01.10. 02:00 (GMT+09:00)

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.

Chapter 2 Working with CONTROL-M/Server 57


Daylight saving time considerations

Daylight saving time considerations


The following topics discuss adjusting the time setting forward or backward by one
hour to take account of daylight saving time. All examples assume 02:00 A.M. as the
time of change.

■ “Advancing the clock forward”


■ “Moving the clock backwards” on page 59

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.

Advancing the clock forward


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

New Day procedure

No special action need be taken after the clock is advanced.

Time-dependent shout messages

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

58 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Daylight saving time considerations

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.

CONTROL-M/Server log file

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.

Moving the clock backwards


The following examples assume that the clock is moved back at 02:00 A.M. (02:00
A.M. becomes 01:00 A.M.):

New Day procedure

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

— Update the clock before New Day processing begins.

Chapter 2 Working with CONTROL-M/Server 59


Daylight saving time considerations

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.

Time-dependent shout messages

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.

CONTROL-M/Server log file

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.

60 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M administrator

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

■ providing appropriate security authorizations to CONTROL-M users by using the


CONTROL-M Security Maintenance Utility (ctmsec)

■ backing up the CONTROL-M/Server database, CONTROL-M home directory files


and CONTROL-M “data” directory on a periodic basis to ensure complete
recovery in case of system failure

■ planning CONTROL-M production schedules

■ performing troubleshooting functions, such as

— performing basic CONTROL-M/Server database maintenance functions (for


example, increasing available space, dumping logs, increasing locks)

— detecting common system problems by analyzing CONTROL-M/Server logs


and APDT logs

— detecting database problems by analyzing CONTROL-M/Server database logs

— collecting and analyzing debug information

— checking for enough disk space

— monitoring the CONTROL-M production system; checking that the database is


not at full capacity; removing old prerequisite conditions

— cleaning up old and unnecessary log files from the proclog directory

— installing all CONTROL-M releases and patches, as needed

Chapter 2 Working with CONTROL-M/Server 61


Heartbeat monitor

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 can operate in either of the following


modes that are described in Table 5.

Table 5 Heartbeat monitor modes


Mode Description
active mode The CONTROL-M/Server Heartbeat monitor periodically sends a
“heartbeat check” message through one TCP/IP connection to
CONTROL-M/EM. CONTROL-M/EM repeats the message through the
second TCP/IP connection back to CONTROL-M/Server.

If CONTROL-M/Server does not receive a response to a heartbeat check


message within a limited time period, CONTROL-M/Server assumes that
communication with CONTROL-M/EM is temporarily interrupted.
CONTROL-M/Server then initiates a procedure to restore communication
with CONTROL-M/EM. In addition, CONTROL-M/Server issues a
response to heartbeat checks initiated by CONTROL-M/EM.
passive mode CONTROL-M/Server does not initiate heartbeat checks, but
CONTROL-M/Server does respond to the heartbeat checks initiated by
CONTROL-M/EM. In this mode, CONTROL-M/Server does not
automatically attempt to restore communication with CONTROL-M/EM
if communication is interrupted.

The CONTROL-M/Server Heartbeat monitor uses the following parameters that are
contained in the ~<controlm_owner>/ctm_server/data/config.dat file.

Table 6 Heartbeat monitor parameters (part 1 of 2)


Parameter Description
CTM_PRM_KPA_ACTIVE
This parameter indicates whether the CONTROL-M/Server Heartbeat
monitor operates in active (Y) or passive (N) mode. Default: Y
CTM_PRM_KPA_BETWEEN_MSGS
This parameter indicates the amount of time (in seconds) to wait after
receiving a response to a heartbeat check before issuing the next
heartbeat check. Default: 300 seconds

62 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Heartbeat monitor

Table 6 Heartbeat monitor parameters (part 2 of 2)


Parameter Description
CTM_PRM_KPA_ROUNDTRIP_TIMEOUT
This parameter indicates the time (in seconds) to wait for a response
after issuing a heartbeat check before declaring a communication
failure and initiating corrective actions. Default: 300 seconds

Example

CTM_PRM_KPA_ACTIVE Y
CTM_PRM_KPA_BETWEEN_MSGS 300
CTM_PRM_KPA_ROUNDTRIP_TIMEOUT 300

Chapter 2 Working with CONTROL-M/Server 63


Advanced problem detection tools

Advanced problem detection tools


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

In addition to the tools mentioned in Table 7, also refer to

■ contingency planning for the possibility of failure of the server computer or the
CONTROL-M/Server database

For more information, see “Failover planning” on page 35.

■ writing diagnostic files when the diagnostic level setting is greater than zero

For more information, see “Set trace level” on page 353.

Table 7 Advanced problem detection tools (part 1 of 2)


Tool Description
Event logger generates log files for events that match the specified severity and
category

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

For more information, see “Managing log files” on page 66.


Stack trace logger a log of the functions called and the events leading up to a process crash

For more information, see “Stack trace” on page 67.


Watchdog monitors CONTROL-M processes and resources and sends an alert if a
problem is detected

For more information, see“Watchdog facility” on page 69.


ctmdbcheck checks database integrity, displays information about database memory
utilization and automatically monitors database and transaction logs

For more information, see “ctmdbcheck” on page 124.

64 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Setting event log parameters

Table 7 Advanced problem detection tools (part 2 of 2)


Tool Description
ctmdbtrans lists active transactions in the database

For more information, see “ctmdbtrans” on page 134.


ctmlog performs selective cleanup of the CONTROL-M log or produces a
report of CONTROL-M log entries

For more information, see “ctmlog” on page 196.

Setting event log parameters


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

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

The log entries generated are saved in the following location:

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

Chapter 2 Working with CONTROL-M/Server 65


Managing log files

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

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

Table 8 Event logger severity


Keyword Description
INFO informational messages for the specified category
WARNING warning messages for the specified category
ERROR error messages for the specified category

Example

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

CTM_LOGGER_SEVERITY WARNING ERROR


CTM_LOGGER_CATEGORY IOALOG

Managing log files


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

CONTROL-M 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.

66 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Stack trace

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>

Table 9 Managing log files


Variable Description
OS_DIAG_LIMIT_ diagnostic log file size, specified in megabytes
LOG_FILE_SIZE
OS_DIAG_LIMIT_ number of generations of diagnostic log files to keep
LOG_VERSIONS
Valid value: number from 1 through 10.

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.

CONTROL-M records the progression of the invocations called by functions. If a


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

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

~<controlm_owner>/ctm_server/proclog/<process_name>.<proc_ID>

Chapter 2 Working with CONTROL-M/Server 67


Stack trace

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

~<controlm_owner> home directory of CONTROL-M/Server account owner


<process_name> two-character code identifying the process
<proc_ID> ID of the CONTROL-M/Server process

Example

~<controlm_owner>/ctm_server/proclog/CS_LOG.6509

68 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Watchdog facility

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

If a Watchdog facility-monitoring check fails, appropriate error messages can be sent


to special error handlers such as CONTROL-O/Server and CONTROL-M/EM. The
Watchdog facility sends these messages to the CONTROL-M IOALOG and
PROCLOG automatically.

The Watchdog facility is enabled by configuration parameters defined in the


~<controlm_owner>/ctm_server/data/config.dat file. For additional information, see
“Configuration parameters” on page 385.

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

■ To disable the various Watchdog exits, set their parameters to 0.


■ To enable the various Watchdog exits, specify the values described in Table 10.
Table 10 General Watchdog facility parameters
Parameter Description
WD_CTMEXIT_NUMBER indicates which built-in Watchdog user exits are
enabled

■ 0 disables the built-in user exits.

■ 1 enables user exit 1 (that runs the ctmdiskspace


utility).

■ 2 enables both exit 1 and exit 2 (that runs the


ctmdbspace utility). Default.
WD_USEREXIT_NUMBER number of user-defined Watchdog user exits to be
enabled

Specify the number of enabled exits, or specify 0 to


disable all user-defined Watchdog user exits.

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

■ “Heartbeat check” on page 70


■ “Predefined watchdog system exits” on page 70
■ “Watchdog user exits” on page 71

Chapter 2 Working with CONTROL-M/Server 69


Watchdog facility

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.

Table 11 Heartbeat monitor exit parameters


Parameter Description
WD_HEARTBEAT_INTERVAL amount of time (in seconds) to wait after receiving a
response to a heartbeat check before issuing the next
heartbeat check; default: 1
WD_HEARTBEAT_LIMIT time (in seconds) to wait for a response after issuing a
heartbeat check before sending a message to the error
handlers; default: 360

Predefined watchdog system exits


The Watchdog facility monitors CONTROL-M/Server processes and resource usage
by using two built-in utilities. Each utility is enabled by a CONTROL-M/Server
system exit parameter (WD_CTMEXIT_# _) in the config.dat file. All these exits reside
in the ~<controlm_owner>/ctm_server/exe_<computer> directory and cannot be
changed.

The # that is used in each of the following CONTROL-M/Server system exit


parameters represents the corresponding CONTROL-M/Server utility that can be
included in the CONTROL-M/Server Watchdog process:

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

70 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Watchdog facility

Table 12 Parameters for Watchdog system exits


Parameter Description
WD_CTMEXIT_# _CMD_LINE Contains parameters to be passed to the exit script.
WD_CTMEXIT_# _ERROR_MSG Indicates the message to be sent if an exit script
fails.
WD_CTMEXIT_# _INTERVAL Indicates the number of basic time interval units
that should pass before reinvoking the exit script.
The basic time interval unit is defined in parameter
WD_INTERVAL (see Table 14). For example, if the
value of this parameter is 20, and the basic time
interval unit (as defined in parameter
WD_INTERVAL) is 6 minutes, the exit script will be
invoked every 120 minutes (20 x 6 minutes).

Range: 1-1440. Default: 20


WD_CTMEXIT_# _RUN_STATE Indicates if the exit script should be run when
CONTROL-M/Server is running. Valid values are
Y or N
WD_CTMEXIT_# _SCRIPT_FILE File name of the script or binary that resides in the
ctm/exe_<computer> directory.
WD_CTMEXIT_# _SUSPEND_STATE Indicates if the exit script should be invoked when
CONTROL-M/Server is suspended. Valid values
are Y or N
WD_CTMEXIT_# _TIMEOUT Time (number of minutes) which should be allowed
before the exit script is terminated.

Watchdog user exits


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

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

Table 13 Parameters for Watchdog Facility User Exits (part 1 of 2)


Parameter Description
WD_USEREXIT_# _CMD_LINE Contains parameters to be passed to the exit
script.
WD_USEREXIT_# _ERROR_MSG Indicates the message to be sent if an exit script
fails.

Chapter 2 Working with CONTROL-M/Server 71


Error handlers

Table 13 Parameters for Watchdog Facility User Exits (part 2 of 2)


Parameter Description
WD_USEREXIT_# _INTERVAL Indicates the number of basic time interval units
that should pass before reinvoking the exit script.
The basic time interval unit is defined in
parameter WD_INTERVAL (see Table 14.) For
example, if the value of this parameter is 2, and
the basic time interval unit (as defined in
parameter WD_INTERVAL) is 5 minutes, the exit
script will be invoked every 10 minutes (2 x 5
minutes). Default: 2
WD_USEREXIT_# _RUN_STATE Indicates if the exit script should be run when
CONTROL-M/Server is running. Valid values are
Y or N
WD_USEREXIT_# _SCRIPT_FILE Full path of the exit script.
WD_USEREXIT_# _SUSPEND_STATE Indicates if the exit script should be invoked when
CONTROL-M/Server is suspended. Valid values
are Y or N
WD_USEREXIT_# _TIMEOUT Time (number of minutes) which should be
allowed before the exit script is terminated.

Example

CONTROL-M/Server ctmping utility can be added to the Watchdog facility to


automatically test the communication link between
CONTROL-M/Server and agent computers and update the available agent list. Add
the following parameters to the config.dat file:

WD_USEREXIT_1_CMD_LINE -file ~<controlm_owner>/ctm_server/ctmuser/agntlist


WD_USEREXIT_1_ERROR_MSG Agent not available
WD_USEREXIT_1_INTERVAL 5
WD_USEREXIT_1_RUN_STATE Y
WD_USEREXIT_1_SCRIPT_ FILE $HOME/ctm_server/exe_AIX/ctmping
WD_USEREXIT_1_SUSPEND_STATE N
WD_USEREXIT_1_TIMEOUT 5

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.

72 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Error handlers

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

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


parameters.”

Table 14 Watchdog Facility parameters


Parameter Description
WD_ALIVE_MSG Indicates message to be sent in response to successful heartbeat
checks. Place a ”# ” character in front of the parameter in the
config.dat file to inhibit the message.
WD_CTO_HOSTNAME Host name or IP Address CONTROL-O/Server.
WD_CTO_TIMEOUT Maximum time for the Watchdog facility to send messages to
CONTROL-O/Server.
WD_ERROR_HANDLER_SCRIPT_FILE Path name of the user-defined script called by the Watchdog
facility.
WD_ERROR_HANDLER_TIMEOUT Maximum time for the Watchdog facility to wait for the user
defined script to run.
WD_INTERVAL Basic time unit interval, in minutes. When the value in either
the WD_CTMEXIT_# _INTERVAL parameter or the
WD_CTMEXIT_# _INTERVAL parameter is multiplied by the
value in this parameter, the resulting value is the number of
minutes that must pass before reinvoking the exit script.

For example, if the value of this parameter is 6 (minutes), and


the value of the WD_CTMEXIT_1_INTERVAL parameter is 20,
the script for system exit 1 will run once every 120 minutes
(20 x 6 minutes). Default: 6

Chapter 2 Working with CONTROL-M/Server 73


User exits

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.

Table 15 Processing overhead for job processing features


Feature Relative processing overhead
Time window (Basic scheduling parameters) very low
In (prerequisite) conditions low
Control Resources medium
Quantitative Resources high
Designation of a job as “Critical” very high

74 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Language capabilities

Language capabilities
Starting with version 6.3.01, CONTROL-M supports two foreign language modes:

■ Latin1 (German, French, and Spanish)


■ CTJK (Chinese, Japanese, Korean)

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.

Chapter 2 Working with CONTROL-M/Server 75


Language capabilities

76 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Chapter

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.

78 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Table 16 CONTROL-M utilities (part 2 of 3)
Utility Description
ctmkeygen Generates SSH private and public key pairs.
ctmkeystore_mng Creates, modifies, and deletes keys with secure information such as
passwords.
ctmkilljob Terminates a CONTROL-M job and its associated processes.
ctmldnrs Creates and loads the Manual Conditions file.
ctmloadset Updates a resource in the Quantitative Resources table with regard to
usage on an agent computer.
ctmlog Performs a selective cleanup of the CONTROL-M log or produces a
report of CONTROL-M log entries.
ctmnodegrp Maintain and view node groups.
ctmordck Lists job processing definitions that can be ordered by a specific User
Daily job.
ctmorder Orders one or more jobs from a Scheduling table contained in the
CONTROL-M/Server database.
ctmpasswd Allows changing CONTROL-M/Server user’s password into the
database.
ctmping Collects configuration information about CONTROL-M/Agents not in
the CONTROL-M/Server database and performs a communication test.
ctmpsm Interactive utility for performing functions affecting jobs or conditions
in the Active environment.
ctmreindex Reorganizes indexes after accessing the CONTROL-M/Server database
(Sybase only). [UNIX only]
ctmrpln Creates a report that lists all or a selection of jobs in a specified
Scheduling table, and indicates when the jobs are scheduled to run.
ctmruninf Lists and deletes runtime data from the Statistical Details table of the
CONTROL-M/Server database.
ctmsec Defines users in the CONTROL-M security database and assigns them
authorizations for working with CONTROL-M. For more details, see
“Security maintenance utility (Interactive mode)” on page 245.
ctmsetown Creates, updates, deletes, and lists user authentication details. The
utility can also import or export user details from different
CONTROL-M environments.
ctmshout Issues a Shout message to a specified destination.
ctmshtb Sets the active Shout Destination table.
ctmspdiag Prints or erases diagnostic messages recorded from stored procedures
(SPs) in the CONTROL-M/Server database. Also used to set or show
diagnostic request status of SPs.
ctmstats Displays or deletes statistical data from the Statistical Summary table in
the CONTROL-M/Server database.
ctmstvar Displays the current value of an AutoEdit variable.
ctmsuspend Suspends CONTROL-M/Server scheduling processes for mass uploads
or downloads from CONTROL-M/EM.

Chapter 3 Utilities 79
Utility reference table

Table 16 CONTROL-M utilities (part 3 of 3)


Utility Description
ctmsys Maintains CONTROL-M/Server system parameters and Shout
Destination tables.
ctmudchk Allows recovery from interruption of a User Daily.
ctmudlst Enables you to manually set the User Daily last run date.
ctmudly Orders jobs for a specific User Daily name.
ctmvar Manipulates Global AutoEdit variables for data centers, Group
Scheduling tables, or jobs in Group Scheduling tables.
ctmwhy Displays a report indicating why a job waiting in the Active Jobs file is
not being submitted for execution.
dbversion Displays a general description of the database used by
CONTROL-M/Server.
ecactltb Lists the status of each resource in the Control Resources table.
ecaqrtab Performs operations on the Quantitative Resources table.
start_ctm Launches CONTROL-M/Server.
shut_ctm Shuts down CONTROL-M/Server.

Utility reference table


Table 17 CONTROL-M utility reference (part 1 of 3)
Can be run by
Requires user other than Supports Can be run
CONTROL-M SQL CONTROL-M Can be run as a AutoEdit from agent
Utility active Access Administrator Batch Job variables computer
ctm_agstat X X
ctm_backup_bcp X X
ctm_diag_comm X X X
ctm_menu X X X X X
ctm_restore_bcp X X
ctmagcln X X X
ctmcalc_date X X X
ctmcheckmirror X X X
ctmcontb X X X X X X
ctmcpt
ctmcreate X X X X X X
ctmdbbck X X
ctmdbcheck X X X
ctmdbmused X X

80 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Utility reference table

Table 17 CONTROL-M utility reference (part 2 of 3)


Can be run by
Requires user other than Supports Can be run
CONTROL-M SQL CONTROL-M Can be run as a AutoEdit from agent
Utility active Access Administrator Batch Job variables computer
ctmdbopt X X
ctmdbrst X X
ctmdbspace X X X
ctmdbtrans X X X
ctmdbused X X
ctmdefine X X X X X
ctmdiskspace X X
ctmexdef X X X
ctmfw X X X
ctmgetcm X X X X
ctmgrpdef X X X
ctmhostmap X X X
ctmjsa X X X
ctmkeygen X X X
ctmkeystore_mng
ctmkilljob X X X X X
ctmldnrs X X X
ctmloadset X X X X X
ctmlog X X X
ctmnodegrp X X X
ctmordck X X X
ctmorder X X X X X
ctmpasswd X X
ctmping X X X X
ctmpsm X X
ctmreindex X X
ctmrpln X X X
ctmruninf X X
ctmsec X X
ctmsetown X X X
ctmshout X X X X X
ctmshtb X X
ctmspdiag X
ctmstats X X X
ctmstvar X X X X
ctmsuspend X X

Chapter 3 Utilities 81
Utility reference table

Table 17 CONTROL-M utility reference (part 3 of 3)


Can be run by
Requires user other than Supports Can be run
CONTROL-M SQL CONTROL-M Can be run as a AutoEdit from agent
Utility active Access Administrator Batch Job variables computer
ctmsys X X
ctmudchk X X X
ctmudlst X X
ctmudly X X X X
ctmvar X X X X X
ctmwhy X X X
dbversion X X X
ecactltb X X X X X
ecaqrtab X X X X X
start_ctm X X
shut_ctm X X X

82 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Reports generated from utilities

Reports generated from utilities


The following reports can be generated by using the referenced utilities:

Table 18 Utility reports


Report Description
Daily Job Order Generates a projection of which jobs in a Scheduling table will be
ordered on a given day by using a specific calendar. See “ctmrpln”
on page 237.
Monthly Job Order Generates a projection of which jobs in a Scheduling table will be
ordered in a given month by using a specific calendar. See “ctmrpln”
on page 237.
Yearly Job Order Generates a projection of which jobs in a Scheduling table will be
ordered over a five-year period by using a specific calendar. See
“ctmrpln” on page 237.
CONTROL-M Log Lists entries in the CONTROL-M log for specified (or all)
CONTROL-M/Server processes. See “ctmlog” on page 196.
Active Jobs File Lists jobs in the Active Jobs file according to various criteria. See
“ctmpsm” on page 218.
User Daily: Lists all jobs associated with a specific User Daily job and displays
Associated Job security parameters for each job. See “ctmordck” on page 202.
Processing
Definitions
Prerequisite Displays existing prerequisite conditions. See “ctmcontb” on page
Conditions 105.
Control Resources Lists the status of Control resources. See “ecactltb” on page 304.
Status
Quantitative Lists the status of Quantitative resources. See “ecaqrtab” on page
Resources Status 305.
Summary Statistical Lists summarized runtime statistics. See “ctmjsa” on page 174 and
Data “ctmstats” on page 277.
Runtime Statistical Lists runtime statistical data by timestamp. See “ctmruninf” on page
Data 240.
Global AutoEdit Lists Global AutoEdit variables, See “ctmvar” on page 297.
Variables

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.

Using the -input_file parameter enables you to:

■ prepare and save files of utility parameters that can be reused


■ specify utility input longer than the number of characters allowed in the command
line

For more information about this parameter, see the descriptions of the utilities in
Table 19.

Table 19 Utilities that support the -input_file parameter


ctmcontb ctmping
ctmcreate ctmshout
ctmdefine ctmvar
ctmgrpdef ecaqrtab
ctmkilljob ctmkeygen
ctmfw ctmsetown
ctmorder

Directing output from utilities


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

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

■ Specify the full path name of the file (for example,


~<controlm_owner>/ctm_server/user1/rprt.txt).
■ Specify the relative name of the file to be placed in the <controlm_user_dir>/
directory.

84 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Accessing utilities from other users

Accessing utilities from other users

For users on Windows


To allow a user other than the CONTROL-M administrator to run
CONTROL-M/Server utilities on a Windows computer, change the permissions of
the following directories:

■ temp
■ proclog
■ prflag

The user requires the permission to write to these directories.

For users on UNIX


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

■ define variables in the user environment


■ add an executable library to the user’s path
■ assign Read/Write permissions

Define variables in the environment of the user


The following environment variables must be defined:

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

Table 20 Additional required environment variables


For SYBASE For ORACLE
SYBASE ORACLE_BASE
DSLISTEN ORACLE_HOME
DSQUERY ORACLE_SID
DSCONSOLE NLS_LANG
MIRROR_DSLISTEN
MIRROR_DSQUERY
SYBASE_OCS, with the value OCS-12_5

Determining the values to assign to variables

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:

Table 21 Shared library path for Sybase variables


Computer Path Variable
AIX LIBPATH ~<controlm_owner>/ctm_server/exe_AIX:
~<controlm_owner>/sybase/OCS-12_5/lib
HP-UX SHLIB_PATH ~<controlm_owner>/ctm_server/exe_HP-UX-11:
~<controlm_owner>/sybase/OCS-12_5/lib

Note: When the computer is Itanium, the shared directory is:


~<controlm_owner>/ctm_server/exe_HP-UX-ia64
Solaris LD_LIBRARY_PATH ~<controlm_owner>/ctm_server/exe_Solaris:
~<controlm_owner>/sybase/OCS-12_5/lib
Red Hat LD_LIBRARY_PATH ~<controlm_owner>/ctm_server/exe_RedHat:
~<controlm_owner>/sybase/OCS-12_5/lib
SuSE LD_LIBRARY_PATH ~<controlm_owner>/ctm_server/exe_SuSE:
~<controlm_owner>/sybase/OCS-12_5/lib

86 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


For users on UNIX

Table 22 Shared library path for Oracle variables


Computer Path Variable
AIX LIBPATH ~<controlm_owner>/oracle/product/<DB_ver>/lib:
~<controlm_owner>/ctm_server/exe_AIX
HP-UX SHLIB_PATH ~<controlm_owner>/oracle/product/<DB_ver>/lib:
~<controlm_owner>/ctm_server/exe_HP-UX-11

Note: When the computer is Itanium, the shared directory is:


~<controlm_owner>/ctm_server/exe_HP-UX-ia64
Solaris LD_LIBRARY_PATH ~<controlm_owner>/oracle/product/<DB_ver>/lib:
~<controlm_owner>/ctm_server/exe_Solaris
Red Hat LD_LIBRARY_PATH ~<controlm_owner>/oracle/product/<DB_ver>/lib:
~<controlm_owner>/ctm_server/exe_RedHat
SuSE LD_LIBRARY_PATH ~<controlm_owner>/oracle/product/<DB_ver>/lib:
~<controlm_owner>/ctm_server/exe_SuSE

Table 23 describes the variables in both Table 21 and Table 22.

Table 23 Shared library path variables for Sybase and Oracle


Variable Description
~<controlm_owner> The default full path name of the UNIX user account home
directory under which CONTROL-M/Server is installed.
<DB_ver> Version of the Oracle database. Valid value: Oracle 10.1.0.2
<OS_ID> Identifier for the type of operating system on the server computer
(AIX, HP-UX-11, HP-UX-ia64, Solaris, RedHat and SuSE).

Setting environmental variables

Using csh or tcsh

Specify the following command for each variable:

setenv <variable-name> <value>

Chapter 3 Utilities 87
For users on UNIX

Sybase example

setenv CONTROLM_SERVER /home/controlm/ctm_server


setenv SYBASE /home/controlm/sybase
setenv DSLISTEN CTRLM
setenv DSQUERY CTRLM
setenv DSCONSOLE CTRLM
setenv MIRROR_DSQUERY MIRROR
setenv MIRROR_DSLISTEN MIRROR
setenv CONTROLM_USER ctrlm
setenv CONTROLM_DATABASE ctrlm
setenv MIRROR_DB_SERVER ctrlm_mirror
setenv CTM_DATABASE_TYPE SYBASE
setenv LD_LIBRARY_PATH ~<controlm_owner>/ctm_server/exe_Solaris:
/home/controlm/sybase/OCS-12_5/lib

Oracle example

setenv CONTROLM_SERVER /home/ora_ctm/ctm_server


setenv ORACLE_HOME /home/ora_ctm/oracle/product/10.1.0.2
setenv ORACLE_SID ctrlm
setenv ORACLE_BASE /home/ora_ctm/oracle
setenv NLS_LANG AMERICAN_AMERICA.WE8ISO8859P1
setenv CONTROLM_USER ctrlm
setenv CONTROLM_DATABASE ctrlm
setenv MIRROR_DB_SERVER ctrlm_mirror
setenv CTM_DATABASE_TYPE ORACLE
setenv LD_LIBRARY_PATH /home/ora_ctm/ctm_server/exe_SuSE:
/home/ora_ctm/oracle/product/10.1.0.2/lib

Using other shells

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

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

Sybase example

CONTROLM_SERVER=/home/controlm/ctm_server; export CONTROLM_SERVER


SYBASE=/home/controlm/sybase; export SYBASE
DSLISTEN=CTRLM; export DSLISTEN
DSQUERY=CTRLM; export DSQUERY
DSCONSOLE=ctrlm; export DSCONSOLE
MIRROR_DSQUERY=MIRROR; export MIRROR_DSQUERY
MIRROR_DSLISTEN=MIRROR; export MIRROR_DSLISTEN
CONTROLM_USER=ctrlm; export CONTROLM_USER
CONTROLM_DATABASE=ctrlm; export CONTROLM_DATABASE
LIBPATH=/home/controlm/ctm_server/exe_HP-UX-11:/home/controlm/sybase
/OCS-12_5/lib; export LIBPATH

88 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


For users on UNIX

Oracle example

CONTROLM_SERVER=/home/controlm/ctm_server; export CONTROLM_SERVER


CONTROLM_USER=ctrlm; export CONTROLM_USER
CONTROLM_DATABASE=ctrlm; export CONTROLM_DATABASE
LIBPATH=/home/controlm/ctm_server/exe_HP-UX-11:
/home/controlm/oracle/product/10.1.0.2/lib; export LIBPATH

Adding an executable library to the path of the user


The executable directory of CONTROL-M/Server must be added to the path of the
user. This path must include:

~<controlm_owner>/ctm_server/scripts

Using csh or tcsh

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

For Sybase

set path=($path ${SYBASE}/OCS-12_5/bin ~<controlm_owner>/ctm_server/exe_<OS_ID>)

For Oracle

set path=($path ${ORACLE_HOME}/bin ~<controlm_owner>/ctm_server/exe_<OS_ID>)

Example

set path=($path ~<controlm_owner>/ctm_server/exe_Solaris)

Using other shells

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

Assign Read/Write permissions


The user must have the following read/write permissions:

Table 24 Read/Write permissions


Permission type Directory
Read permission for file <controlm-directory>/.controlm
Read and Write permission for all files in directory <controlm_owner>/ctm_server/prflag
If mirroring is enabled, Read permission for file <controlm-directory>/.controlm_mirror

You must provide security access to these files as follows:

■ Give group controlm read permission for the files.

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

90 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Utilities

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

To invoke the ctm_agstat utility

Specify the following command

ctm_agstat
{ -LIST <agentName> | -UPDATE <agentName> {AVAILABLE | DISABLED} }
[ -DEBUG <debug level 1-5> ]
[ -QUIET ]

Table 25 describes the parameters of the ctm_agstat utility.

Table 25 ctm_agstat parameters


Parameter Description
-LIST Lists the current status of the specified agent.

Note: This parameter is mandatory if the -UPDATE parameter is


not specified.
-UPDATE Changes the status of the specified agent to the specified status.

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

Table 25 ctm_agstat parameters


Parameter Description
-DEBUG <debug level> Set the required diagnostic level. Valid values: 0 (no diagnostics)
to 5 (highest level of diagnostics).
-QUIET If this parameter is specified, the utility runs without displaying
output messages.

Examples

To display the current status of agent CMAGENT, type

ctm_agstat -LIST CMAGENT

To change the status of agent CMAGENT to DISABLED, type

ctm_agstat -UPDATE CMAGENT DISABLED

92 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctm_backup_bcp

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.

To invoke the ctm_backup_bcp utility

1 Shut down CONTROL-M/Server by using command shut_ctm.

2 Specify the following command:

ctm_backup_bcp [-n]

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

Differences between the ctm_backup_bcp and ctmdbbck


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

■ ctm_backup_bcp exports the data in the CONTROL-M/Server database. ctmdbbck


backs up an image of the database for later restoration using ctmdbrst.

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

■ ctm_backup_bcp backs up each database table to a separate ASCII file. ctmdbbck


backs up the entire database to a single binary file.

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

Chapter 3 Utilities 93
ctm_backup_bcp

Example 1

ctm_backup_bcp
Backing up contents of database
Please confirm [y/n] : Y

Messages similar to the following examples are displayed:

backing up contents of CMS_NODGRP


backing up contents of CMR_AGSTAT
backing up contents of CMS_AGCOMM
backing up contents of CMS_AGSRVTIM
backing up contents of CMR_AJF
backing up contents of CMS_JOBDEF
backing up contents of CMS_USERS

Database backup ended successfully.

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.

94 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctm_diag_comm

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.

The ctm_diag_comm utility can be invoked:

■ As an interactive utility, by specifying the following command from the command


prompt:

ctm_diag_comm

You are prompted for the host name of the CONTROL-M/Agent or remote host.

■ As a single command, by specifying the following command from the command


prompt:

ctm_diag_comm <agent> | <remoteHost>

<agent> is the host name of the computer where CONTROL-M/Agent is installed.

<remoteHost> is the name of the specified remote host with which


CONTROL-M/Server should attempt to communicate.

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

CONTROL-M/Server to CONTROL-M/Agent Communication Diagnostic Report


-------------------------------------------------------------------

CTMS User Name : ctm630sd


CTMS Directory : /home1/ctm630sd/ctm
CTMS Platform Architecture : Solaris
CTMS Installed Version : DRCTV.6.3.01
CTMS Local IP Host Interface Name : taurus
Server-to-Agent Port Number : 12666
Agent-to-Server Port Number : 7420
Server-Agent Comm. Protocol : TCP
Server-Agent Protocol Version : 07

Chapter 3 Utilities 95
ctm_diag_comm

Server-Agent Connection mode : Transient


Agent Platform Name : mars
Agent Status : Unknown
Agent known Type : Undefined
UNIX ping to Agent or Remote host : Succeeded
CTMS ping to Agent or Remote host : Succeeded

CTMS Ping mars as Regular Agent


==============================
Agent [mars] responded with "Agent not available."

CTMS Ping mars as Remote Host


============================
Remote host [mars] is available through Agent [nova]
Connection protocol : SSH
Port number : 22
Encryption method : BLOWFISH
Compression : No

96 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctm_restore_bcp

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.

To invoke the ctm_restore_bcp utility

1. Shut down CONTROL-M/Server by using the shut_ctm command. Make sure no


other users or processes are connected to the SQL Server.

2. Specify the command:

ctm_restore_bcp [-n]

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

Differences between the ctm_restore_bcp and ctmdbrst


utilities
■ ctm_restore_bcp imports files created by ctm_backup_bcp. ctmdbrst restores a
backup created by ctmdbbck.

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

■ You can only use ctm_restore_bcp if CONTROL-M/Server is down.

■ ctm_restore_bcp imports ASCII files. ctmdbrst restores from a binary file.

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

Messages similar to the following examples are displayed:

restoring contents of CMS_NODGRP


restoring contents of CMR_AGSTAT
restoring contents of CMS_AGCOMM
restoring contents of CMS_AGSRVTIM
restoring contents of CMR_AJF
restoring contents of CMS_JOBDEF
restoring contents of CMS_USERS

Database restore ended successfully.

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.

98 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmagcln

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.

To invoke the ctmagcln utility

Specify the following command:

ctmagcln -agent <"*" | agentName> [-days <sysoutRetainDays>]

Table 26 describes the parameters of this command.

Table 26 ctmdiskspace parameters


Parameter Description
* Specifies that all Agents remove SYSOUT files and exit status files that
are no longer needed.
agentName Specifies that the specified agent must remove SYSOUT files and exit
status files that are no longer needed.
sysoutRetainDays Specifies the number of days that SYSOUT files must be retained before
being removed. Default: 1

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.

ctmagcln -agent "*"

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.

ctmagcln -agent saturn -days 2

100 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmcalc_date

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.

Use the following command to invoke the ctmcalc_date utility:

ctmcalc_date -SCHEDTAB <schedulingTableName>


-JOBNAME <jobName>
-DATE <schedulingDate>
-SHIFT <+/-n>
-ONLY_WORKING_DAYS <Y/N>
-OUTPUT_FORMAT DATE | EXTENDED (Date and flag) | FLAG
[ -DEBUG <debug level 0-5> ]

Table 27 describes the parameters in the ctmcalc_date utility.

Table 27 ctmcalc_date parameters (part 1 of 2)


Parameter Description
-SCHEDTAB name of the Scheduling table that contains the job
-JOBNAME name of the job
-DATE indicates the scheduling date (odate) to be associated with the job

Specify the date in yyyymmdd format.


-SHIFT indicates how many days to shift the scheduling criteria of the job

Valid values are +n or -n. n is the number of days to be shifted.

Specify +n to shift the job forward n number of days, or specify -n to


shift the job backward n number of days. The scheduling criteria of
the job are shifted either by work days or any day, according to the
value specified for the -ONLY_WORKING_DAYS parameter.
-ONLY_WORKING indicates whether the scheduling day can be any day of the week or
_DAYS must be a work day

Valid values are Y and N.

■ Y – the job can be scheduled to run only on a work day


■ N – the job can be scheduled to run on any day of the week

Chapter 3 Utilities 101


ctmcalc_date

Table 27 ctmcalc_date parameters (part 2 of 2)


Parameter Description
OUTPUT_FORMAT displays the following information:
DATE when specified, displays the calculated date
EXTENDED when specified, displays the calculated date and
indicates if the job will be scheduled

Valid values are Y and N.

■ Y – scheduled to run on the calculated date


■ N – not scheduled to run on the calculated date
FLAG when specified, indicates if the job will be scheduled

Valid values are Y and N.

■ Y – scheduled to run on the calculated date


■ N – not scheduled to run on the calculated date
-DEBUG activates a debug trace at the specified level

Valid levels are 0–5. The default is 0

Note: Performance is somewhat slower when operating in debug


mode. BMC Software recommends that you activate debug mode
only when requested by Customer Support.

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:

ctmcalc_date -SCHEDTAB Production -jobname prodyjob -date 20050802 \


-shift +2 -ONLY_WORKING_DAYS Y -OUTPUT_FORMAT DATE

20050804

Example 2

As in Example 1, displaying the calculated scheduling date and indicating if the job
will be scheduled:

ctmcalc_date -SCHEDTAB Production -jobname prodyjob -date 20050802 \


-shift +2 -ONLY_WORKING_DAYS Y -OUTPUT_FORMAT EXTENDED

20050804 Y

102 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmcalc_date

Example 3

As in Example 1, indicating if the job will be scheduled without displaying the


calculated scheduling date:

ctmcalc_date -SCHEDTAB Production -jobname prodyjob -date 20050802 \


-shift +2 -ONLY_WORKING_DAYS Y -OUTPUT_FORMAT FLAG

Chapter 3 Utilities 103


ctmcheckmirror

ctmcheckmirror
The ctmcheckmirror utility checks the mirroring of the CONTROL-M/Server
database and displays the status.

Use the following command to invoke the ctmcheckmirror utility:

ctmcheckmirror

The utility returns one of the following statuses:

■ Mirroring is enabled.
■ Mirroring is disabled.
■ Mirroring is damaged.

For more information about database mirroring, see “Database Mirroring menu” on
page 338.

104 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmcontb

ctmcontb
The ctmcontb utility performs the following operations on prerequisite conditions in
the CONTROL-M/Server database:

■ Lists existing prerequisite conditions while treating an asterisk in a condition name


as a wildcard. (-LIST)
■ Lists existing prerequisite conditions while treating an asterisk in a condition name
as a regular character. (-LISTNOWILD)
■ Adds a prerequisite condition. (-ADD)
■ Generates a prerequisite condition in XML format. (-XML)
■ Deletes a prerequisite condition while treating an asterisk in a condition name as a
wildcard. (-DELETE)
■ Deletes a prerequisite condition while treating an asterisk in a condition name as a
regular character. (-DELETENOWILD)
■ Deletes conditions within a specified range of dates. (-DELETEFROM)

The following special characters are disabled when they occur in prerequisite
condition names:
( open parenthesis
) close parenthesis
| vertical bar
space

Syntax for listing conditions

ctmcontb -LIST <conditionName>


<conditionName> [-output <outputFileName>][-FULLDETAILS]
or
ctmcontb -LISTNOWILD <conditionName> <conditionDate>
[-output <outputFileName>][-FULLDETAILS]
or
ctmcontb -input_file <fullPathFileName>

Syntax for deleting a range of conditions

ctmcontb -DELETEFROM <conditionName>


<fromDate> <toDate>
or
ctmcontb -input_file <fullPathFileName>

Chapter 3 Utilities 105


ctmcontb

Syntax for all other operations

ctmcontb {-ADD|-XML|-DELETE|-DELETEONWILD} <conditionName>


<conditionDate>
or
ctmcontb -input_file <fullPathFileName>

Table 28 ctmcontb utility parameters (part 1 of 2)


Variable Description
-FULLDETAILS Displays the prerequisite condition name without truncation.
<conditionName> For LIST, DELETE and DELETEFROM

The condition name can include mask character * to indicate any


number of characters (including none).

■ When using an *, the condition name must be enclosed in


quotation marks (for example, “LVL*”).

■ Specify “*” by itself to include all existing conditions.

■ When using both open and closed square brackets ([ and ]),
the condition name must be enclosed in quotation marks (for
example, “RATE[A1]”).

■ Maximum length for a condition name is 255 characters.

For LISTNOWILD and DELETENOWILD

The character * in condition name is referred to as a regular


character.

■ When using an *, the condition name must be enclosed in


quotation marks (for example, "LVL*").

■ When using both open and closed square brackets ([ and ]),
the condition name must be enclosed in quotation marks (for
example, “RATE[A1]”).

■ Maximum length for a condition name is 255 characters.

For Adding or Generating in XML Format

■ When using both open and closed square brackets ([ and ]),
the condition name must be enclosed in quotation marks (for
example, “RATE[A1]”).

■ Maximum length for a condition name is 255 characters.

106 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmcontb

Table 28 ctmcontb utility parameters (part 2 of 2)


Variable Description
<conditionDate> Displays the date of the prerequisite condition in mmdd format.

For Listing and Deleting

The condition date can include mask character * to indicate any


number of characters (including none). When using an *, enclose
the date in quotation marks (for example, “12* ”).

■ Specify “*” by itself to include all dates.


■ Specify ODAT to accept the CONTROL-M date.
■ Specify STAT if a date is not relevant.

For Adding or Generating in XML Format

■ Specify ODAT to use the CONTROL-M working date.


■ Specify STAT if a date is not relevant.
<fromDate> <toDate> For Deleting in a Date Range

Displays the starting and ending dates for date range of


prerequisite conditions to delete. Each date is in mmdd format.

If the To Date is less than the From Date, the range of condition
dates will include the From Date up to the end of the year (1231)
plus the beginning of the 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:

■ prepare, save, and reuse files of utility parameters.

■ specify utility input longer than the number of characters


allowed in the command line.

Example: -input_file /ctm_server/data/ctmcontb_list.txt

Example 1

The following command deletes prerequisite condition bckp_end with condition


dates in December:

ctmcontb -DELETE bckp_end "12*"

Chapter 3 Utilities 107


ctmcontb

Example 2

The following command deletes all prerequisite conditions with prefix a and
condition dates between December 1 and December 15 inclusive:

ctmcontb -DELETEFROM "a*" 1201 1215

Example 3

The following command deletes the prerequisite condition aa* with condition date
ODAT:

ctmcontb -DELETENOWILD "aa*" ODAT

Example 4

You can implement Example 2 with the -input_file parameter as follows:

ctmcontb -input_file ~<controlm_owner>/ctm_server/data/ctmcontb_delfr.txt

where the referenced file contains the line:

ctmcontb -DELETEFROM "a*" 1201 1215

Example 5

The following command lists the prerequisite condition named aa* with all its dates.

Ctmcontb -LISTNOWILD "aa*" "*"

Example 6

The following command lists all existing prerequisite conditions:

ctmcontb -LIST "*" "*"

108 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmcontb

A report similar to the following example is generated:

Date: 30-JUN-2002. Page 1

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

This example demonstrates the advantage of defining a CONTROL-M job to run a


utility. The following job processing definition causes CONTROL-M to run ctmcontb
each work day, each time deleting all prerequisite conditions that are between five
and ten days old:

Week Days 2,3,4,5,6


AutoEdit Assignment
%%A=%%CALCDATE %%DATE -10
%%B=%%CALCDATE %%DATE -5
%%A=%%SUBSTR %%A 3 4
%%B=%%SUBSTR %%B 3 4
Command Line ctmcontb -DELETEFROM “*” %%A %%B

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.

D:\>ctmcontb -XML cond1 ODAT


<?xml version="1.0" encoding="utf-8" ?>
<CTMCONTB
CONDNAME="cond1"
CONDDATE="0315">
<COND
CONDNAME="cond1"
CONDDATE=" 0315">
</COND>
</CTMCONTB>

Chapter 3 Utilities 109


ctmcpt

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:

ctmcpt <username> "" <password>

The quotation marks “” indicates the absence of an old password.

Specify the following command to change the password for a user who is already
registered:

ctmcpt <username> <old_password> <new_password>

Example 1

The following command registers new user user1 with password default:

ctmcpt user1 "" default

Example 2

The following command changes the password for user1 from default to do2day:

ctmcpt user1 default do2day

110 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmcreate

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

-tasktype GROUP -group <group_name>

To invoke the ctmcreate utility

Specify the following command:

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 ]

Chapter 3 Utilities 111


ctmcreate

[ -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:

ctmcreate -input_file <fullPathFileName>

The referenced file contains all the desired parameters.

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.

112 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmcreate

Table 29 ctmcreate parameter descriptions (part 1 of 3)


Parameter Description
-appltype Name of the application server (for example, SAP).

A mask character can be used to specify more than one application:

■ Specify * to retrieve information for all applications.

■ Specify O* to retrieve information for all applications beginning


with O (for example, ORA or OS).

Note: OS can be specified to return information about the control


module for the current operating system.
-odate Indicates the scheduling date (odate) to be associated with job(s).

Valid values are:


ODAT The current working date of the computer on which
CONTROL-M/Server is running.

This is the default value.


yyyymmdd A specific working day in yyyymmdd format.
Note: The interpretation of this parameter value is dependant on the
value specified for the -odate_option parameter (described below).

Chapter 3 Utilities 113


ctmcreate

Table 29 ctmcreate parameter descriptions (part 2 of 3)


Parameter Description
-odate_option Indicates how the specified -odate value should be used.

Valid values are:


value_date The specified odate is the odate value for the job.
However, the job should be run during the current
working day.

This is the default value for the -odate_option


parameter.

Note: If a time zone is specified in the job processing


definition, then the job is run according to those time
zones.
run_date The jobs that are ordered by this run of the ctmcreate
utility should be run only when the specified odate
begins.

■ If the specified odate is the current working day,


this job will work in the same way as value_date
(described above).

■ If the specified odate has not begun (for example,


due to time zone specifications), then the job will
wait in the Active Jobs file (with WAIT_ODAT
status) until the start of the specified working
day.

Note: If the specified odate has already passed, the


ctmcreate utility will not run, and an error message
will be displayed.
-group_ord Specifies in which order of a Group Scheduling table to put the job.
Valid values are:
<order-no> A specific order number of the Group Scheduling
table.

If the specified order number does not exist the


command is not executed and an error message is
displayed.
ALONE The job is on its own (not in any table).
LAST The last order of the specified Group Scheduling
table.
Note: When an order ID or LAST is specified for this parameter, the
-group and -schedtab parameters are mandatory and must both
contain the name of Group Scheduling table that is currently in the
Active Jobs file.
-debug Level of debug messages, 0 to 5.

Default: 0 (no debug messages).

114 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmcreate

Table 29 ctmcreate parameter descriptions (part 3 of 3)


Parameter Description
-quiet Indicates, if specified, that no informational messages are displayed
during the execution of the command.
-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:

■ prepare and save files of utility parameters that can be reused.

■ specify utility input longer than the number of characters allowed


in the command line.

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.

Table 30 ctmcreate parameter name cross reference (part 1 of 2)


CONTROL-M/EM
Utility parameter parameter Utility parameter CONTROL-M/EM parameter
adjust_cond Adjust condition group Group
application Application incond In Conditions
applform Application Form interval Interval
appltype Application Type intervalfrom Interval (From field)
applver Application Version jobname Job Name
autoedit AutoEdit Assignments maxrerun Max Rerun
cmdline Command Line maxwait Max Wait
confirm Confirm Submission memlib Mem Lib
control Control Resources jobname Job Name
cmver Control Module Version memname Mem Name
critical Critical nodegrp Node ID/Group
cyclic Cyclic odate see Syntax (below)
description Description on On Statement/Code
doautoedit Do AutoEdit outcond Out Conditions
doclib Doc Lib overlib Over Lib
docmem Doc Mem owner Owner
docond Do Cond priority Priority
doforcejob Do Forcejob quantitative Quantitative Resources
domail Do Mail schedtab Scheduling Table
donotok Do NOTOK shout Shout

Chapter 3 Utilities 115


ctmcreate

Table 30 ctmcreate parameter name cross reference (part 2 of 2)


CONTROL-M/EM
Utility parameter parameter Utility parameter CONTROL-M/EM parameter
dook Do OK sysout Sysout Handling
dorerun Do Rerun taskclass Task Class
doshout Do Shout tasktype Task Type
dostopcyclic Do Stop Cyclic timefrom Time
dosysout Do Sysout timeuntil Time

Syntax
The following syntax rules apply when using this utility:

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

■ 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 %%NEXT, %%$NEXT, %%PREV, and %%$PREV AutoEdit variables cannot


be specified for the ctmcreate utility. These variables refer to the next or previous
scheduling date and are not relevant for a utility that places jobs directly in the
Active Jobs file.

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

■ Although most parameters are optional, certain parameters are required


depending on the value specified for -tasktype.

■ On computers that support Disk Clustering, the -nodegrp parameter is required


(including either a node group name, or the virtual name of the
CONTROL-M/Agent).

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

The -domail parameter has the following syntax:


-domail <destination> <cc> <severity> <subject> <message>

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

-domail johnsmith@bmc.com "" R "subject line" "My message"

116 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmcreate

For more information, see “CONTROL-M/Server e-mail configuration


parameters” on page 397.

■ All task types require group and application parameters.

— JOB and DETACHED require memname and memlib parameters.


— COMMAND requires the cmdline parameter.

■ Strings containing blanks must be enclosed in quotation (for example, -cmdline


“ctmudlst list payroll”).

■ A UNIX metasymbol (that must be enclosed in quotation marks) appearing in a


command line string should be enclosed in single quotation (for example,
-cmdline “ctmcontb list '*' ”).

■ 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

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

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

■ Normally, when a -dorerun parameter is implemented, the current run of the job
ends with 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 -dorerun parameter cannot be specified for a cyclic job.

Chapter 3 Utilities 117


ctmcreate

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

■ A maximum of 99 prerequisite conditions can be specified for the docond, incond,


and outcond parameters.

Example 1

-incond pk_oly_ok "****"

When the UNIX symbol ~ is used in parameter -memlib, -overlib, or -doclib to


represent the user’s home directory, the entire parameter should be enclosed in
double quotation marks. The quotation marks ensure that the ~ will be translated by
the agent before submission, and not by the server before transmission to the agent
computer.

-memlib "~/controlm/scripts/"

Example 2

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

ctmcreate -tasktype command -group em\


-application test -cmdline "ls -l /etc/passwd"

You can get the same result by using the -input_file parameter as follows:

ctmcreate -input_file ~<controlm_owner>/ctm_server/data/ctmcreate_delfr.txt

The referenced file contains the following lines:

-tasktype command
-group em
-application test
-cmdline "ls -l /etc/passwd"

118 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmcreate

Example 3

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

ctmcreate -tasktype JOB \


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

Chapter 3 Utilities 119


ctm2snmp

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.

Table 31 Fields of SNMP traps


# Field Description
1 SEVERITY Severity of the alert. Possible values are:

■ R Regular
■ U Urgent
■ V Very urgent
2 SEND TIME Time/date that the alert was issued (format
yyyymmddhhmmss).
3 USER NAME Name of the CONTROL-M user who invoked the utility.
4 MSG TEXT Full text of the alert.

To invoke the ctm2snmp utility

Specify the following command:

ctm2snmp -hostname <hostName> -message <message> -severity <severity>

Table 32 ctm2snmp parameters


Parameter Description
-hostname Host name or IP address of the computer containing the Network
Management application.
-message Message to be sent.
-severity Severity of the alert (R, U, V)

120 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctm2snmp

Special customization is required to support SNMP traps issued by CONTROL-M:

■ SNMP traps can be issued in either Single Variable format or Multiple Variable
format. The format is determined by the CTM_SNMP_SEND_FORMAT
parameter specified in the ~<controlm_owner>/ctm_server/config.dat file. The default
is Single Variable (S) format. For more information, see “Configuration
parameters” on page 385.

— Single Variable Format


The trap is contained in one SNMP variable. This variable is a string consisting
of four trap fields separated by blanks. There are three specific traps:

A. Specific-trap 1: Regular CONTROL-M alerts.

B. Specific-trap 2: Urgent CONTROL-M alerts.

C. Specific-trap 3: Very urgent CONTROL-M alerts.

— Multiple Variable Format


The trap consists of 4 distinct SNMP variables. There is one specific trap type:

Specific-trap 10: CONTROL-M alerts.

■ The following entry must be added to the /etc/services/ file (if not already present):
snmp-trap 162/udp # snmp monitor trap port

■ The Network Management applications, HP-OpenView, NetView for AIX, and


Tivoli Management Environment Console, must be customized so that they
recognize the Enterprise ID of CONTROL-M and the generated trap codes. Follow
the procedure for each application described in the “SNMP Interface” appendix in
the CONTROL-M/Enterprise Manager Administrator Guide.

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.

Chapter 3 Utilities 121


ctmdbbck

ctmdbbck
The ctmdbbck utility backs up the CONTROL-M/Server database in the following
cases:

■ CONTROL-M/Server was installed by using a dedicated Oracle database server.


Do not use this utility if CONTROL-M/Server was installed with an existing
Oracle database. To back up an existing Oracle database, use the ctm_backup_bcp
utility (described on page 93).

■ CONTROL-M/Server was installed by using either an existing or a dedicated


Sybase database server. When working with an existing Sybase database, the
ctmdbbck utility must be specified with the device name only, and not with a full
path.

■ CONTROL-M/Server was installed by using an MSSQL database server

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.

To back up the CONTROL-M/Server database

1 Shut-down CONTROL-M/Server and CONTROL-M/Server Configuration Agent


before running this utility.

2 Specify the following command:

ctmdbbck

Continue the backup by following the prompts.

For Oracle – The CONTROL-M/Server database is backed up to a reserved


location in the Oracle home directory.

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.

122 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdbbck

The device that is specified for this parameter must be either:


■ a valid device defined in an existing Sybase server or MSSQL

■ 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

Specify the following command to back up the CONTROL-M/Server database where


CONTROL-M/Server was installed by using a dedicated Oracle database server:

ctmdbbck

You are then prompted for the following required parameters:

Please Enter Oracle Administrator Password:

Enter a destination directory name:

Example 2

Specify the following command to backup the CONTROL-M/Server database where


CONTROL-M/Server was installed using an existing Sybase or MSSQL database
server and the backup device is controlm_data_bkp:

ctmdbbck controlm_data_bkp

Chapter 3 Utilities 123


ctmdbcheck

ctmdbcheck
The ctmdbcheck utility displays information about the memory capacity and the
status of the CONTROL-M/Server database.

To invoke the ctmdbcheck utility

Specify the following command:

ctmdbcheck

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

ctmdbcheck [-d <dbThreshold_%>] [-l <logThreshold_%>][-n]


ctmdbcheck [generalThreshold_%]

These commands trigger a Shout message to CONTROL-M/EM if more than the


specified percentage of the database or the database transaction log are full. This
message can then be used to trigger actions that will extend the appropriate
CONTROL-M/Server database component.

The ctmdbcheck utility can be run as a cyclic job.

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.

The parameters in these commands are described in Table 33.

124 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdbcheck

Table 33 ctmdbcheck parameters


Parameter Description
dbThreshold_% Threshold for usage of the CONTROL-M/Server database.

If more than the specified percentage of the database is full, a Shout


message to CONTROL-M/EM warns that the database should be
extended. This variable must be preceded by the -d switch. For
example, -d80 indicates that a shout message should be issued if the
database is more than 80% full.
logThreshold_% Threshold for usage of the transaction log of the
CONTROL-M/Server database.

If more than the specified percentage of the database is full, a Shout


message to CONTROL-M/EM warns that the transaction log should
be extended. This variable must be preceded by the -l switch. For
example, -l80 indicates that a shout message should be issued if the
transaction log is more than 80% full.
generalThreshold_% Checks data and log partitions of the CONTROL-M/Server database
by the same percentage.

For example, if percent usage of either the data area or the transaction
log exceeds 80%, ctmdbcheck 80 triggers a Shout message).

ctmdbcheck output
The ctmdbcheck utility returns information about the CONTROL-M/Server
database. Table 34 describes the fields that are returned by this utility.

Table 34 ctmdbcheck output – displayed fields


Field Description
db total Total amount of memory (in KB) allocated for the database.
data Total amount of memory (in KB) allocated to the Data partition of the
database.
log Total amount of memory (in KB) allocated to the Log partition of the
database.
Data used Total memory currently used in the Data partition.
Log used Total memory currently used in the Log partition.

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.

Chapter 3 Utilities 125


ctmdbcheck

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

Sybase database – utility output

db total = 25000.0 KB (data= 19500.00 , log= 5500.00)


data used = 3696 KB (18%).
log used = 0 KB (0%).
Checking database...
Database is OK.

Example 2

Utility input

ctmdbcheck -d80

Sybase database – utility output

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

126 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdbcheck

Sybase database – utility output

db total = 25000.0 KB (data= 19500.00 , log= 5500.00)


data used = 21250 KB (85%).
log used = 0 KB (0%).
Checking database...
Database is OK.

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

Oracle 817 database – utility output

Tablespace Size % Free


-------------------- ------- -------
RBS 200M 85%
WIN613O 150M 95%
WIN613O_INDX 50M 98%

Example 6

Utility input

ctmdbcheck -d10

Chapter 3 Utilities 127


ctmdbcheck

Oracle 92 Database – Utility Output

Tablespace Size % Free


-------------------- ------- -------
CTRLM 250M 96%
TEMP 100M 90%
RBS 300M 99%

128 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdbmused

ctmdbmused
The ctmdbmused utility returns the size of a CONTROL-M/Server Master database
(Sybase only) and the percent used.

Syntax
ctmdbmused

Sample output

db master total = 20000.0 KB


data used = 4334 KB (21%)

If the data used is more than 80% of the size of the CONTROL-M/Server Master
database, the utility output contains the message:

CAUTION - DB near capacity. Increase master DB size.

If the data used is more than 90%, the utility output contains the message:

URGENT - Not enough Master DB free space.

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.

Chapter 3 Utilities 129


ctmdbopt

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

130 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdbrst

ctmdbrst
The ctmdbrst utility restores the CONTROL-M/Server database in the following
cases:

■ CONTROL-M/Server was installed by using a dedicated Oracle database server.


Do not use this utility if CONTROL-M/Server was installed by using an existing
Oracle database server. To restore an existing Oracle database, use the
ctm_restore_bcp utility (described on page 97).

■ CONTROL-M/Server was installed by using either an existing or a dedicated


Sybase database server.

■ CONTROL-M/Server was installed using an MSSQL database server.

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

To restore the CONTROL-M/Server database

1 Shut down CONTROL-M/Server before invoking this utility. Make sure that no
other users or processes are connected to the SQL server.

2 Specify the following command:

ctmdbrst

Continue the restore procedure by following the prompts.

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.

Chapter 3 Utilities 131


ctmdbrst

Example

The following command causes the CONTROL-M/Server database to be restored


from the default backup device:

ctmdbrst

You are then prompted for the following required parameters:

Enter restore device name [tapedump2] :

Please Enter Sybase Administrator Password:

132 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdbspace

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.

To invoke the ctmdbspace utility

Specify the following command

ctmdbspace -limit <amount> [-quiet]

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

The following command returns a “failed” status if CONTROL-M/Server database


usage is more than 50%:

ctmdbspace -limit 50%

Chapter 3 Utilities 133


ctmdbtrans

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-

Select “List Active Transactions” from the Troubleshooting menu (described on


page 350).

To run the ctmdbtrans utility in batch mode, specify the DBA password in a file, and
specify the following command:

ctmdbtrans < <fullPathFileName>

<fullPathFileName> is the full path to the file in which the DBA password is specified.

134 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdbused

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.

To invoke this utility

Specify the following command:

ctmdbused

Use this utility if you need to determine CONTROL-M/Server database sizes


frequently.

Example 1

This example uses the ctmdbused utility to display CONTROL-M/Server database


data and log size, amount of current usage and percentage of space.

Utility input

ctmdbused

Utility output

db total = 45000.0 KB (data= 3000.00 , log= 15000.00)


data used = 4174 KB (13%).
log used = 40.00 KB (0%)

Example 2

This example uses the ctmdbused utility to display CONTROL-M/Server database


data and log size, amount of current usage and percentage of space, using Oracle 9.2.

Utility input

ctmdbused

Oracle 92 database – utility output

db total = 563200.0 KB (data= 256000.00 , log= 307200.00)


data used = 10048 KB (4%).
RBS log used = 1344 KB (0%).

Chapter 3 Utilities 135


ctmdefine

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.

136 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdefine

Use the following command to invoke the ctmdefine utility:

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 ]

Chapter 3 Utilities 137


ctmdefine

[ -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> ]
[ -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 <calendar> ]
[ -WEEKCAL <calendar> ]
[ -CAL_ANDOR AND|OR ]
[ -SHIFT [</>/@][+/-]nn ]
[ -CONFCAL <calendar> ]
[ -RETRO Y|N ]
[ -TAG <tagname> ]

The ctmdefine utility can be invoked by using the -input_file parameter:

-ctmdefine -input_file <fullPathFileName>

The referenced file contains all the desired parameters.

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.

Table 35 ctmdefine parameter description


Parameter Description
-debug Level of debug messages, 0 to 5. Default: 0 (no debug messages).
-quiet If specified, no information messages are displayed during execution
of the command.
-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:

■ prepare and save files of utility parameters that can be reused.

■ specify utility input longer than the number of characters


allowed in the command line.

Example:
-input_file ~<controlm_owner>/ctm_server/data/ctmdefine_parms.txt

138 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdefine

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.

Table 36 ctmdefine parameter name cross reference


CONTROL-M/EM
Utility parameter CONTROL-M/EM parameter Utility parameter parameter
adjust_cond Adjust Condition dosysout Do Sysout
application Application group Group
applform Application Form incond In Conditions
appltype Application Type interval Interval
applver Application Version intervalfrom Interval (From field)
autoedit AutoEdit Assignments jobname Job Name
cal_andor AND/OR maxrerun Max Rerun
cmdline Command Line maxwait Max Wait
confcal Conf Calendar memlib Mem Lib
confirm Confirm Submission memname Mem Name
control Control Resources month See below
cmver Control Module Version nodegrp Node ID/Group
critical Critical on On Statement/Code
cyclic Cyclic outcond Out Conditions
date Dates overlib Over Lib
datefrom Active From Date owner Owner
dateuntil Active To Date priority Priority
days Days quantitative Quantitative Resources
dayscal Days Calendar relationship Relationship
description Description retro Retro
doautoedit Do AutoEdit shift Shift
doclib Doc Lib shout Shout
docmem Doc Mem sysout Sysout Handling
docond Do Cond table Scheduling Table
doforcejob Do Forcejob tag Schedule Tag
donotok Do NOTOK taskclass Task Class
domail Do Mail tasktype Task Type
dostopcyclic Do Stopcyclic timefrom Time
dook Do OK timeuntil Time
dorerun Do Rerun weekcal Weekdays Calendar
doshout Do Shout weekdays Weekdays

The following syntax rules apply for this utility:

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

Chapter 3 Utilities 139


ctmdefine

■ Keywords can be written in either uppercase or lowercase, but parameter values


are case sensitive.

Example:

-GROUP ACCGROUP and -group ACCGROUP

specify the same group ACCGROUP.

-group accgroup

specifies a different group accgroup.

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

■ Although most parameters are listed as optional, certain parameters may be


required, depending on the option specified for parameter -tasktype.

■ All task types require the group and application parameters.

— JOB and DETACHED require parameters memname and memlib.

— COMMAND requires parameter cmdline.

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

Example:

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

■ Strings containing blanks must be enclosed in quotation marks


(for example, -cmdline “ctmudlst list payroll”).

■ A UNIX metasymbol (that must be enclosed in quotation marks) in a command


line string should be enclosed in single quotation (for example, -cmdline
“ctmcontb list '*' ”).

140 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdefine

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

■ On computers that support Disk Clustering, the -nodegrp parameter is required


(including either a node group name, or the virtual name of the
CONTROL-M/Agent).

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

— If a job is dependent upon several prerequisite conditions, specify a separate


-incond parameter for each prerequisite condition.

— If a job can run only in January and July, specify a separate


-month parameter for each month. (For example,
-month ALL N -month JAN Y -month JUL Y.)

— If a job should run every month except July, specify


-month ALL Y and -month JUL N.

— If a job is in a Group Scheduling table and is scheduled according to tags


FIRSTDAY and SALARY1, specify –tag FIRSTDAY –tag SALARY1.

■ The default for the -month parameter is ALL Y, 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

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

■ Additional post-processing conditions can be set by using -on <statement>


<code>.

EXAMPLE
On statement: *
Code: RUNCOUNT>4
Do Shout: To: CONTROL-M/EM
Text: “Job ran more than four times”

Chapter 3 Utilities 141


ctmdefine

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

The -domail parameter has the following syntax:


-domail <destination> <cc> <severity> <subject> <message>

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

-domail johnsmith@bmc.com "" R "subject line" "My message"

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

■ The -dorerun parameter cannot be specified for a cyclic job.

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

■ IN condition statements that use complex boolean logic can be specified.

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 “****”

Example: -incond pk_oly_ok "****"

■ When the UNIX symbol ~ is used in a -memlib, -overlib, or -doclib parameter to


represent the user’s home directory, the entire parameter should be enclosed in
double quotation marks, which ensures that the ~ will be translated by the agent
before submission, and not by CONTROL-M/Server before transmission to the
agent computer.

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

142 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdefine

■ A maximum of 99 prerequisite conditions can be specified for the docond, incond,


and outcond parameters.

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

— "" (Blank) – No shifting occurs. The job is not scheduled. Default.


— > – Job scheduling is shifted to the next working day in the CONFCAL
calendar. Additional shifting may be performed, depending on the yyy value,
described below.
— < – Job scheduling is shifted to the previous working day in the CONFCAL
calendar. Additional shifting may or may not be performed, depending on the
yyy value, described below.
— @ – Tentatively schedule the job for the current day, even if the current day is
not a working day in the CONFCAL calendar. Additional shifting may or may
not be performed, depending on the yyy value, described below.

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:

— Blank - no shifting occurs


— -nn or +nn shifts the job forward or backward nn working days in the
CONFCAL calendar. nn can be any value from 0 to 62.

Chapter 3 Utilities 143


ctmdefine

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:

ctmdefine -table cmmnds -jobname cmls13 \


-tasktype command -group em -application test \
-date 0101 -cmdline "ls -l /etc/passwd"

You can get the same result by using the -input_file parameter as follows:

ctmdefine -input_file ~<controlm_owner>/ctm_server/data/ctmdefine_cmmnds.txt

where the referenced file contains the following lines:

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

144 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmdefine

ctmdefine -tasktype JOB -cyclic N\


-table djsales -jobname dj102\
-description "Daily Summary"\
-group SUPPLY -application SUPPLIES\
-memlib /users/ctm_server/ -memname PROLYPAR -nodegrp UNIXGRP\
-owner suppman\
-month ALL N\
-month MAR Y -month JUN Y -month SEP Y -month DEC Y\
-timeuntil 1800\
-priority AA -critical N\
-confirm Y\
-doclib /users/supply/doc/ -docmem prolypardoc\
-incond pk_oly_ok ODAT AND\
-incond pk_olp_ok ODAT AND\
-outcond pk_oly_ok ODAT DEL\
-outcond pk_olp_ok ODAT DEL\
-outcond pk_olypar ODAT ADD\
-autoedit %%PARM1 "%%CALCDATE %%ODATE -2"\
-quantitative tape 2 -quantitative cpu 50 \
-sysout MOVE /test/logs/\
-control disk2 E\
-shout OK oper2 U "Daily summary completed"\
-on "COPY JWINFO_2507" "%COPY-E-OPENIN, error"\
-dosysout MOVE /oper/openerr/\
-on "*" notok\
-dorerun\
-doshout em v "Daily summary failed. Attempting rerun"

Defining application-specific Jobs


The ctmdefine utility can be used to define jobs for specific applications, for example,
SAP and Oracle Applications. These jobs are defined by setting the -appltype
parameter to, for example, SAP or OAP.

The -memname and -memlib parameters must also be specified for the ctmdefine
utility when defining application-specific jobs.

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


AutoEdit variables. These variables are described in detail in the SAP and Oracle
Applications chapters in the CONTROL-M Job Parameter and Variable Reference Guide.

Example:

ctmdefine -tasktype job -jobname sap1 -MEMNAME test -memlib sap


-AUTOEDIT %%SAPR3-JOB_MODE CREATE -AUTOEDIT %%SAPR3-ACCOUNT DV2
-AUTOEDIT %%SAPR3-STEP-S01-PROGRAM ZQA_SIMPLE -owner sapr3 -AUTOEDIT
%%SAPR3-STEP-S01-STEP_TYPE A -APPLTYPE SAP -nodegrp nord -AUTOEDIT
%%SAPR3-JOBNAME sap1 -table SAP1 -application SAP1 -group SAP1

Chapter 3 Utilities 145


ctmdiskspace

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.

ctmdiskspace can be included in the CONTROL-M Watchdog process. For more


information, see “Watchdog facility” on page 69.

Use the following command to invoke the ctmdiskspace utility:

ctmdiskspace -limit <amount>{%|K|M} -path <pathName> [-quiet]

Table 37 describes the parameters of this command.

Table 37 ctmdiskspace parameters


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

For example: -limit 25%


path_name Specifies the full path name of the device. Multiple devices can be
specified on the command line (see Example 2 below).
-quiet Suppresses informational messages from being displayed during the
execution of the command.

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%:

ctmdiskspace -limit 25% -path /ctm_server/ctmuser

Example 2

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

ctmdiskspace -limit 20M -path /ctm_server/ctmuser -path /ctm/tmp

146 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmexdef

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.

The ctmexdef utility can be used to:

■ Modify existing job processing definitions in batch mode (together with the
ctmdefine utility). The job processing definitions in the file exported by ctmexdef
can be edited offline and then returned to the CONTROL-M/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.

Use the following command to invoke the ctmexdef 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:

■ * Represents any number of characters (including none). Any parameter including


∗ should be enclosed in quotation marks (see example below).
■ ? Represents any single character.

Chapter 3 Utilities 147


ctmexdef

Example

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

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

148 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmfw

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

■ successful completion of a file transfer activity


■ creation of a file
■ deletion of a file

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

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.

Chapter 3 Utilities 149


ctmfw

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

The default value for this key is

<CONTROL-M/Agent_install_directory>\DATA\ctmfw.cfg

NOTE
BMC Software recommends that this default value not be changed.

The configuration file must contain the following line:


-input <ruleFileName>

The variable <ruleFileName> is the full path name of a rule file containing the File
Watcher rules. Figure 2 shows a sample rule file.

Figure 2 Sample Rull.dat file


INTERVAL 5
FROM_TIME 0001
MIN_SIZE 50
MIN_DETECT 5
WAIT_TIME 2
ON_FILEWATCH NONEXIST CREATE 10 3 1
THEN
DO_CMD "BAD FILE WAS CREATED IN 1 MINUTE"
DO_COND ON_2 0101 +
ELSE
DO_CMD "GOOD FILE WAS NOT CREATED IN 1 MINUTE"
DO_CMD ctmshout -USER ECS -MESSAGE "Running the Filewatcher on with
default configuration!"
END_ON

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.

150 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmfw

FileWatcher service trace

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.

Sample trace file

Figure 3 Sample Trace File Output


2002/03/10 13:04:24 182 FW:set INTERVAL=3
2002/03/10 13:04:24 182 FW:set MIN_SIZE=4
2002/03/10 13:04:24 182 FW:set FROM_TIME=0909
2002/03/10 13:04:24 182 FW:ctmfw:command line 'ON_FILEWATCH tst CREATE'(arg#=3).
id=1.
2002/03/10 13:04:24 182 FW:ctmfw:command line 'ON_FILEWATCH prd CREATE 0 0 1 NOW
10'(arg#=8)id=2
2002/03/10 13:04:24 182 FW:ctmfw:command line 'ON_FILEWATCH abc DELETE 0 0 1 NOW
10'(arg#=8)id=3
2002/03/10 13:04:24 182 FW:File 'test' exists, its current size is 265. id=1.

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.

Chapter 3 Utilities 151


ctmfw

To watch a single file

The syntax of the ctmfw utility is:

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

The parameters of the ctmfw utility are described in Table 39.

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

is resolved by using default values for mon_int, min_detect, wait_time, and


mon_size_wildcard as follows:

ctmfw /home/samplefile.txt CREATE 100 10 10 3 0 N

Table 39 ctmfw parameters (part 1 of 3)


Parameter Description
FILE Path of the file to be detected. The file name can include mask character * to represent
any number of characters (including no characters) or ? to represent any one character.

Note: The path and file name must not exceed 214 characters.

152 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmfw

Table 39 ctmfw parameters (part 2 of 3)


Parameter Description
mode CREATE Detects creation of a file. Default. File size is ignored if the filename
parameter contains wildcards (unless the monitor file size when
wildcard is used parameter is set to Y).
Note: If a mask is specified for the filename, and the monitor file size
when wildcard is used parameter is set to

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

Chapter 3 Utilities 153


ctmfw

Table 39 ctmfw parameters (part 3 of 3)


Parameter Description
starting time for Indicates an absolute time at which the utility starts monitoring the file. For example,
detecting files 200512061400, means that at 2 PM on December 6th, 2005 the FileWatcher utility will
stop watching the file.
Alternatively, you can use the HHMM format, in which case the current date is used.
absolute stop time Indicates an absolute time at which the file is no longer watched. For example,
200502061400, would mean that at 2 PM on February 6th, 2005 the FileWatcher utility
will stop watching the file.
Alternatively, you can use the HHMM format, in which case the current date is used.
maximal age of file Indicates the maximum amount of time that can pass since the file you want to watch
was last modified. For example, 2y3d5h means that after 2years, 3 days, and 5 hours
has passed, the file will no longer be watched. Entering a value of 2H10Min, means
that after 2 hours and 10 minutes has passed, the file will no longer be detected.
This parameter is ignored if the mode parameter is set to DELETE. Default: 0
minimal age of file Indicates the minimum amount of time that must have passed since the file you want
to watch was last modified. For example, 2y3d5h means that 2years, 3 days, and 5
hours must pass before the file will be watched. Entering a value of 2H10Min, means
that 2 hours and 10 minutes must pass before the file will be detected.
This parameter is ignored if the mode parameter is set to DELETE. Default: 0

Importing the File Watcher panel (optional)

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.

Before you begin

Ensure that the CONTROL-M/Agent application CD is mounted or easily accessible


through your network.

154 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmfw

To import the File Watcher panel

Perform this procedure on every computer that has CONTROL-M/Enterprise


Manager client component(s) installed.

1 In CONTROL-M/Desktop, choose Tools => Import Applications Forms. A browse


window is displayed.

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.

Figure 4 FileWatch - File Watcher panel

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

Chapter 3 Utilities 155


ctmfw

To watch multiple files

Use the following command to invoke the ctmfw utility for multiple files:

ctmfw -input <ruleFileName>

The variable <ruleFileName> is the complete path name of the file containing the
definitions for each file to be detected.

Sample rule file

Figure 5 displays a sample rule file. In this sample:

■ # indicates comments.
■ Default values are shown for all global parameters.
■ <action> refers to any of the actions described in Table 41.

Figure 5 Sample rule file


#******************************************************************
# Global Parameters
INTERVAL <60> # Sleep interval (seconds)
MIN_SIZE 4Kilo
MIN_AGE 3M24D4h5min
FROM_TIME <0000> # Starting time for all files (hhmm)
MIN_SIZE <0> # Minimum size for all files (bytes)
MIN_DETECT <3> # Number of iterations for all files
WAIT_TIME <0> # Time limit for all files (minutes)

# 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%.

156 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmfw

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.

The Rules file contains the following sections:

■ Global parameters, whose default values apply to all the files in the rule file.

■ ON_FILEWATCH statements identifying which files to detect, specific criteria for


each file, and the action to take upon detection or non-detection. Any number of
ON_FILEWATCH statements can appear in a Rules file.

NOTE
All keywords must be entered in uppercase.

Table 40 Rule file global parameters (part 1 of 2)


Parameter Description
INTERVAL Sleep interval (in seconds) between successive scans for all the files. This parameter
replaces individual sleep_int and mon_int parameters for each file. Default: 10
MIN_SIZE Minimum file size in bytes. This parameter is ignored if the FILE parameter contains
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).
MIN_AGE Indicates the minimum amount of time that must have passed since the file you want
to watch was last modified. For example, 2y3d5h means that 2years, 3 days, and 5
hours must pass before the file will be watched.

This parameter is ignored if the mode parameter is set to DELETE. Default: 0

Chapter 3 Utilities 157


ctmfw

Table 40 Rule file global parameters (part 2 of 2)


Parameter Description
MAX_AGE Indicates the maximum amount of time that can pass since the file you want to watch
was last modified.
■ If MAX_AGE = 0, any change to the file timestamp means that the condition is
met.
■ IF MAX_AGE = 10 Min and if the amount of time of the watched file that has
passed is less than 10 minutes, then the condition is met.

This parameter is ignored if the mode parameter is set to DELETE.


Default: 0
FROM_TIME Starting time for detecting all the files (default FROM_TIME). Used with WAIT_TIME
to identify the time frame for detecting and monitoring the files. This parameter is
expressed in 24-hour, hhmm format. Default: 0000 or Now
STOP_TIME Indicates an absolute time at which the file is no longer watched. For example,
200502061400, means that at 2 PM on February 6th, 2005 the FileWatcher utility will
stop watching the file.

You can also use the HHMM format, which uses the current date, plus the HHMM
entered. Default: 0 (meaning, no stop time)

Note: STOP_TIME can only be used as a global parameter.


CYCLIC_INTERVAL Indicates the interval between multiple operations of detecting the file (in minutes).
This interval must be greater than the value for WAIT_TIME. If the cyclic_interval is
0, only one attempt to detect the file will be performed. Default: 0
MON_SIZE_ Indicates whether file size should be monitored if the filename contains wildcards.
WILDCARD This parameter is ignored if the filename does not contain a wildcard. Valid values:
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.
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.

158 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmfw

Table 41 ctmfw – valid actions


Action Description
DO_COND <condition name> Add (+) or delete (-) a condition.
<condition date> <+|->
DO_CMD <command> Execute a valid command under the command interpreter.
Full path names are required for files.
DO_OK Terminate an ON_FILEWATCH statement with status OK.
If there is more than one file in the Rule file, the result
displayed is that of an AND algorithm.
DO_NOTOK [exit code] Terminate an ON_FILEWATCH statement with status
NOTOK. Exit code is optional and replaces the standard
return code, as described in Table 42.
DO_EXIT [exit code] Terminate ctmfw with the user-defined exit code.

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

Chapter 3 Utilities 159


ctmfw

The following instructions are defined in the Rules file:

■ The sleep interval between succeeding scans must be 10 seconds.


■ If the ctmfw utility detects that the datafile.txt file in the /home/controlm directory is
created in the specified time interval, then:
— the datafile condition dated 1 January must be added.
— the command interpreter must execute the command to move the contents of
the ~<controlm_owner>/ctm_server/datafile.txt file to
~<controlm_owner>/ctm_server/workfile.txt.
■ If the ctmfw utility detects that the datafile.txt file in the
~<controlm_owner>/controlm directory is not created in the specified time interval,
then condition datafile dated 1 January must be deleted.
■ When the ctmfw utility detects that the ~<controlm_owner>/ctm_server/tempfile.txt
file is deleted, condition tempfile dated 1 January must be deleted.
#******************************************************************
INTERVAL 10
ON_FILEWATCH ~<controlm_owner>\ctm_server\datafile.txt CREATE
THEN
DO_COND datafile 0101 +
DO_CMD move \ctm\datafile.txt \ctm\workfile.txt
ELSE
DO_COND datafile 0101 -
END_ON
ON_FILEWATCH \ctm\tempfile.txt DELETE
THEN
DO_COND tempfile 0101 -
END_ON
#****************************************************************

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

160 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmfw

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.

Table 42 ctmfw – return codes


Return code Description
0 File was successfully created or deleted (file arrived in the specified
time frame and file size is above or equal to the minimum specified
size).
1 ■ Utility failed, for example, because of a syntax error.
■ A DO_NOTOK statement occured, but no user-defined exit code
was provided for the DO_NOTOK statement.
7 Indicates that the ctmfw request timed out. That is, the file was not
detected in the specified time frame.

FileWatcher silent mode registry key


The FileWatcher service does not open an additional window during execution. If
you want visual feedback while running the service, the following registry key
setting must be changed to N.

HKEY_LOCAL_MACHINE\SOFTWARE\BMC_Software\
CONTROL-M\FileWatcher\SYSPRM\Silent_Mode

Chapter 3 Utilities 161


ctmgetcm

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 GET, application server information is


collected, stored in a table in the CONTROL-M/Server database, and displayed.

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

The ctmgetcm utility can be invoked:

■ As an interactive utility, specify the following command from the command


prompt:

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

-NODEID agent -APPLTYPE OS -ACTION <get|view>

Table 43 describes the parameters for this utility.

162 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmgetcm

Table 43 ctmgetcm parameters


Parameters Description
-NODEID Host name of the agent computer.
-APPLTYPE Name of the application server (for example, SAP).

A mask character can be used to specify more than one application:

■ Specify * to retrieve information for all applications.

■ Specify O* to retrieve information for all applications beginning with O


(for example, ORA or OS).

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:

ctmgetcm -nodeid sahara -appltype “*” -action VIEW

Output similar to the following is displayed:

NODEID APPLTYPE APPLVER CMVER


------- --------- -------- ------
sahara ORA 7 2.0.00
sahara SAP 4.5 2.0.01
sahara OS SOLARIS 1.0.00

Example 2

Specify the following command to view existing information for all applications with
prefix O on the CONTROL-M/Agent sahara computer:

ctmgetcm -nodeid sahara -appltype O* -action VIEW

Chapter 3 Utilities 163


ctmgetcm

Output similar to the following is displayed:

NODEID APPLTYPE APPLVER CMVER


------- --------- -------- ------
sahara ORA 7 2.0.00
sahara OS SOLARIS 1.0.00

Example 3

Specify the following command to update the CONTROL-M/Server database with


new information for all applications with prefix O on the CONTROL-M/Agent
sahara computer.

ctmgetcm -nodeid sahara -appltype O* -action GET

The CONTROL-M/Server database is updated and output similar to the following is


displayed:

NODEID APPLTYPE APPLVER CMVER


------- --------- -------- ------
sahara ORA 7 2.0.00
sahara ORA 8 2.0.00
sahara OS SOLARIS 1.0.00

164 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmgrpdef

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.

Use the following command to invoke ctmgrpdef:

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> ]

Chapter 3 Utilities 165


ctmgrpdef

[ -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 ]

The ctmgrpdef utility can be invoked using the -input_file parameter:

ctmgrpdef -input_file <fullPathFileName>

The referenced file contains all the desired parameters.

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.

Parameters not in the user guide are described in Table 44.

Table 44 cmtgrpdef parameters


Parameter Description
debug Level of debug messages, 1 to 5. The default value is 0 (no debug
messages.
quiet If specified, no information messages are displayed during execution of
the command.
-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:

■ prepare and save files of utility parameters that can be reused.

■ specify utility input longer than the number of characters allowed


in the command line.

Example:
-input_file ~<controlm_owner>/ctm_server/data/ctmgrpdef_parms.txt

166 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmgrpdef

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.

When using AutoEdit variables in cmtgrpdef parameters, 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 containing a $ sign cannot be resolved if it is
enclosed in double quotation marks.

Chapter 3 Utilities 167


ctmhostmap

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.

Each computer that is defined as a remote host is listed in the CONTROL-M/Server


database. The ctmhostmap utility enables you to manage the entries in the database.

Specify one of the following commands to invoke the ctmhostmap utility:

■ ctmhostmap -action add [-force] -node <remoteHost>


-agent <agentsList>
-protocol SSH|WMI [-sshport <SSHportNumber>
-sshalg BLOWFISH|AES|DES|3DES
-compression <SSH compression Y/N>] [-sysoutdir <WMIsysoutDirectory>]

■ ctmhostmap -action update -node <remoteHost> [-agent <agentsList>]


[-protocol SSH|WMI]
[[-sshport <SSHportNumber>
-sshalg BLOWFISH|AES|DES|3DES
-compression <SSH compression Y/N>] [-sysoutdir <WMIsysoutDirectory>]]

■ ctmhostmap -action delete -node <remoteHost>

■ ctmhostmap -action list [-node <remoteHost>]

■ ctmhostmap help

Table 45 describes the actions in the ctmhostmap utility.

168 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmhostmap

Table 45 ctmhostmap actions


Action Description
add Specifies the details of the remote host computer that is being defined in the
CONTROL-M/Server database.

CONTROL-M/Server discovers the specified computer using default remote


host map settings if the following is specified without further parameters:
ctmhostmap -action add -node <remoteHost>

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.

Table 46 describes the parameters in the ctmhostmap utility.

Chapter 3 Utilities 169


ctmhostmap

Table 46 ctmhostmap parameters (part 1 of 2)


Parameter Description
-force Override a regular agent computer that has the same name as the specified
computer. Optional.

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

Note: <Default > is not applicable if the delete action is specified.


-agent List of agent names, separated by semi-colons (;). For UNIX: Enclose the entire list
in quotation marks.
This parameter is:
■ mandatory when specified with add
■ optional when specified with update

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

170 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmhostmap

Table 46 ctmhostmap parameters (part 2 of 2)


Parameter Description
-protocol Indicates which protocol is used by the agent to execute jobs on the remote host
computer. Mandatory. Valid values are:

■ SSH – Secure Shell (SSH) for UNIX or Windows computers


■ WMI – Windows Management Instrumentation (WMI) for Windows
computers

If SSH is specified, then the following parameters must be specified:


-sshport Specifies the SSH port number that the SSH daemon is
listening to on the remote host computer. Valid value: 22 or
an integer from 1024 through 65535
-sshalg Indicates which SSH encryption algorithm is being used.
Valid values are:

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

Note: Configure the specified directory on the remote host


as a shared directory, with the shared name of SYSOUT.

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

The following message is displayed:

Remote host added successfully.

Chapter 3 Utilities 171


ctmhostmap

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

The following message is displayed:

Remote host added successfully.

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

The following message is displayed:

Remote host added successfully.

Example 3
To add remote host saturn, mapped through CONTROL-M/Agents jupiter,
andromeda, and taurus using SSH protocol, run the following command:

ctmhostmap -action add -node mars -agent “jupiter;andromeda;taurus” -protocol ssh


-sshport 22 -sshalg blowfish -compression N

The following message is displayed:

Remote host added successfully.

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:

ctmhostmap -action update -node mars -sshport 48 -sshalg 3des

The following message is displayed:

Remote host updated successfully.

172 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmhostmap

Example 5
To delete remote host mars from the CONTROL-M/Server database, specify the
following command:

ctmhostmap -action delete -node mars

The following message is displayed:

Action 'delete' ended successfully.

Example 6
To display a list of remote hosts, run the following command:

ctmhostmap -action list

The following report is displayed:

Remote Host Status

orion Available
taurus Unavailable
pegasus Unavailable

Action 'list' ended successfully.

Example 7
To display the details of remote host orion, run the following command:

ctmhostmap -action list -node orion

The following report is displayed:

Remote host 'orion' settings:

Protocol : SSH
Port Number : 22
Encryption : BLOWFISH
Compression : NO
Agents : (comet) (meteor) (cyborg)

Remote Host Status : Available


Agents Statuses : (comet: Available) (meteor: Available) (cyborg: Available)

Action 'list' ended successfully.

Chapter 3 Utilities 173


ctmjsa

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.

Each time it is run, this utility:

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

■ Records the statistical data in a summary table in the CONTROL-M/Server


database (from which the data is made available to CONTROL-M/EM).

■ No other output is generated by this utility.

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.

Specify one of the following commands to invoke the ctmjsa utility:

ctmjsa <fromDate> <toDate>


ctmjsa -<delta1> -<delta2> <date>
ctmjsa -list [ -MEMNAME <memname> ]
[ -MEMLIB <memlib> ]
[ -NODEID <nodeid> ]
Table 47 ctmjsa parameters (part 1 of 2)
Parameter Description
<fromDate> Starting date of statistical data to be compiled. The date is specified in
yyyymmdd or yymmdd format.
<toDate> Ending date of statistical data to be compiled. The date is specified in
yyyymmdd or yymmdd format.
-<delta1> Unsigned number used to establish the starting date for statistical data to
be compiled. This date is determined by subtracting <delta1> from <date>
(for example, if <delta1> is 10 and <date> is 991220, the starting date is
991210).

174 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmjsa

Table 47 ctmjsa parameters (part 2 of 2)


Parameter Description
-<delta2> Unsigned number used to establish the ending date for statistical data to
be compiled. This date is determined by adding <Delta2> to <Date> (for
example, if <Delta2> is 5 and <Date> is 991220, the ending date is 991225).
<date> Date used together with <Delta1> and <Delta2> to determine the range of
dates used for compiling statistical data. The date is expressed in
yyyymmdd or yymmdd format.
“*” Asterisk enclosed in quotation marks. Specifies that the utility collects all
statistical data available without regard to date.
-list Display data from the Statistical Summary table filtered according to
specified subparameters. Use this option after you have updated the
summary table. Output includes the Scheduling table name for each job.
This information is also available from CONTROL-M/EM in the Statistics
window.
Filter Specify one of the following options and its subparameter, or specify the
null character " " to display statistics for all jobs. This works the same way
as "*".
-MEMNAME <memname> Identify the job by its Mem Name
parameter.
-MEMLIB <memlib> Identify jobs by their Mem Lib parameter.
-NODEID <nodeid> Identify jobs by their node group parameter
(agent computer).

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.

Each Filter option subparameter can include these mask characters:

■ * Represents any number of characters (including none). Any parameter that


includes a * should be enclosed in quotation marks (see examples below).

■ ? Represents any single character.

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.

Chapter 3 Utilities 175


ctmjsa

ctmjsa 000621 000625


ctmjsa -3 -1 000624

Example 2

The following command compiles statistical data using all data currently available:

ctmjsa "*"

Example 3

This command displays summary data for all jobs whose Mem Name parameter
starts with “pgmac”: ctmjsa -list -MEMNAME "pgmac*"
A report similar to the following is displayed:

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

176 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmkeygen

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.

To run ctmkeygen in interactive mode, specify the following command

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.

To run ctmkeygen in batch mode, specify one of the following commands

■ ctmkeygen -action add -name <logicalKeyName> -passphrase <keyPassphrase>


-type rsa|dsa -bits 512|768|1024|2048|3076 -format openssh|ssh2
-path <publicKeyPath>

■ ctmkeygen -action update -name <logicalKeyName> -passphrase <keyPassphrase>


[-type rsa|dsa] [-bits 512|768|1024|2048|3076] [-format openssh|ssh2]
-path <publicKeyPath>

■ ctmkeygen -action delete -name <logicalKeyName> -passphrase <keyPassphrase>

■ ctmkeygen -action list

■ ctmkeygen -action export -filename <exportFileName>

■ ctmkeygen -action import -filename <importFileName> -data append|truncate

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

Chapter 3 Utilities 177


ctmkeygen

Table 48 describes the actions in the ctmkeygen utility.

Table 48 ctmkeygen actions


Action Description
add Creates a new entry in the key table. It also verifies that a key with the same
name does not exist. All the parameters are mandatory.
update Modifies the details of an existing entry in the key table. The entry includes the
same fields as used to create a new key pair. The updated entry replaces the
existing entry in the key table in the database and the public key file. The
passphrase must match the one that was used to create the existing key.
Note: For the optional parameters, if a value not specified, the value stored in the
CONTROL-M/Server database is used.
delete Deletes the entry associated with the logical key name. The passphrase must
match the one that was used to create the existing key.
list Returns a list of lines, each containing: the logical key name, type, bits, and
format.
export Exports the details of the keys stored in the key table to a text file.

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:

■ prepare and save files of keys that can be reused

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

Table 49 describes the parameters in the ctmkeygen utility.

Table 49 ctmkeygen parameters (part 1 of 2)


Parameter Description
-name Logical name of the key that is used as a unique identifier. It also determines
the name of the public key file. The name is comprised of letters, numbers,
and underscores.
-passphrase Phrase used as a key to encrypt the key itself. Default: Agent_PASS
-type Specifies the standard used for the key. Mandatory when used with add,
optional when used with update.Valid values are:

■ RSA
■ DSA

178 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmkeygen

Table 49 ctmkeygen parameters (part 2 of 2)


Parameter Description
-bits Specifies the strength of the encryption key in bits. Mandatory when used
with add, optional when used with update. Valid values are:

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

■ openssh – for OpenSSH servers


■ ssh2 – for ssh2 servers
-path Specifies the location where the public key file is created.
-filename Specifies the public key name. The format of the file depends on what is
specified for the –format parameter, described above.
-data Describes what action to take with the imported data from the text file. Specify
one of the following:
append the details of the SSH keys from the imported text file are added
to the existing SSH keys
truncate the details of the SSH keys from the imported text file replace the
existing SSH keys

Copying public keys to the SSH server


The public key must be copied to the SSH server. If such a file already exists on the
SSH server, you must choose to either append or truncate the new file to the existing
one.

Copy the public key to the SSH server according to the SSH server requirements.

■ For OpenSSH on UNIX, the public keys file is:

<jobOwnerHomeDirectory>/.ssh/authorized_keys

■ For SSH Tectia on UNIX, the public keys file is:

<jobOwnerHomeDirectory>/.ssh2/authorization

■ For SSH Tectia on WINDOWS, the public keys file is:

Chapter 3 Utilities 179


ctmkeygen

<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

Specify the following command:

ctmkeygen -action add -name key1 -passphrase myphrase -type dsa -bits 512 -format ssh2
-path /home/ctm630

The following message is displayed:

Creating SSH key. Please wait...

SSH key created successfully.

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

The following message is displayed:

Updating SSH key. Please wait...

SSH key update ended successfully.

180 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmkeygen

Example 3
To delete the key entry created in Example 3, specify the following command:

ctmkeygen -action delete -name key1 -passphrase myphrase

The following message is displayed:

Entry deleted successfully.

Example 4
To display a list of SSH keys in the key table, specify the following command:

ctmkeygen -action list

The following is displayed:

Name Type Bits Format


---- ---- ---- ------
first RSA 512 OPENSSH
mykey RSA 1024 OPENSSH

2 keys were found.

Example 5
To create an export text file containing the details of the SSH keys, specify the
following command:

ctmkeygen -action export -filename /home/ctm630/my.exp

The following is displayed:

Exporting data, please wait...

Export ended successfully.

Check report file


~<controlm_owner>/ctm_server/proclog/export_report_5020.txt' for
details.

Chapter 3 Utilities 181


ctmkeygen

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:

ctmkeygen -action import -filename /home/ctm630oe/my.exp -data truncate

The following message is displayed:

Importing data, please wait...

Import ended successfully.

Check report file


~<controlm_owner>/ctm_server/proclog/import_report_535a.txt' for
details.

182 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmkeystore_mng

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.

To invoke the interactive ctmkeystore_mng utility

Specify the following command:

ctmkeystore_mng

The following menu is displayed:

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

To access the REMEDY Keystore Menu

Select option 1 from the Main Menu.

The following menu is displayed:

Chapter 3 Utilities 183


ctmkeystore_mng

+--------------------------------------+
REMEDY Keystore Menu
+--------------------------------------+

1) Add User
2) Delete User
3) Update User password
q) Quit

Enter option:

Table 50 REMEDY Keystore Menu parameters


Parameter Description
user Specifies a user name. Specify an alphanumeric value from 1 through 127
characters long.
password Specifies the password for the user defined above.

To create a REMEDY user and password

1 Select Option 1 from the REMEDY Keystore Menu.

You are prompted to specify a username and password.

After confirming the password, a message is displayed stating that the user name
was successfully added.

2 Press Enter to continue.

The REMEDY Keystore Menu is again displayed.

To delete a REMEDY user

1 Select Option 2 from the REMEDY Keystore Menu.

You are prompted to specify a username.

2 Press Enter to continue.

A message is displayed stating that the user name was successfully deleted.

3 Press Enter to continue.

The REMEDY Keystore Menu is again displayed.

184 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmkeystore_mng

To modify the password of a REMEDY user

1 Select Option 3 from the REMEDY Keystore Menu.

You are prompted to specify a username.

2 Press Enter to continue.

You are prompted to enter new password and then confirm it.

3 Press Enter to continue.

The REMEDY Keystore Menu is again displayed.

Chapter 3 Utilities 185


ctmkilljob

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-

ctmkilljob -input_file <fullPathFileName>

Table 51 ctmkilljob parameters


Parameter Description
-ORDERID CONTROL-M Order ID of the job to be terminated.
-NODEID Host name of an agent computer, or name of a node group to which the
job should be submitted.
-MEMLIB Name of the library/directory in which the job script resides.
-MEMNAME Name of the file that contains the job script statements.
-JOBNAME Descriptive reference for a job processing definition.
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:

■ prepare and save files of utility parameters that can be reused.

■ specify utility input longer than the number of characters allowed


in the command line.

Example:
-input_file ~<controlm_owner>/ctm_server/data/ctmkilljob_parms.txt

If the action was successful, the utility responds with the statement:

186 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmkilljob

Job was killed.

and the specified job is ended with NOTOK status.

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.

Chapter 3 Utilities 187


ctmldnrs

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:

■ The prerequisite condition already exists in the Conditions/Resources table.

■ The prerequisite condition is added to the Conditions/Resources table by an Out


Conditions or DO COND job processing parameter in a job scheduled to run that
day.

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

188 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmldnrs

The following options are available for using this utility:

-CALCCOND Create the Manual Conditions file


-LIST List prerequisite conditions from the Manual Conditions file
-LOAD Load prerequisite conditions from the Manual Conditions file to the
Conditions/Resources table

Creating the manual conditions file


Specify the following to create the Manual Conditions file:

ctmldnrs -CALCCOND [-ADDMODE {YES | NO} ]


[-OUTPUT <filename> ]
[-IGNOREIN <condition-mask>]
[-IGNOREOUT <condition-mask>]
[-IGNORECODES <condition-mask>]

Table 52 ctmldnrs – creating a manual conditions file


Parameter Description
ADDMODE ■ YES – When the new Manual Conditions file is created,
conditions from the previous file are retained in the new file.

■ NO – The Manual Conditions file is recreated and all previous


conditions are deleted. Default.
OUTPUT Output file to be created. If this parameter is not specified, the
default file is <controlm_user_dir>/ctmldnrs.dat.
<Filename> Full path name of the output file to be created.
IGNOREIN All conditions that satisfy the specified condition name are ignored
when the file is created.
IGNOREOUT References to conditions that satisfy a condition name that is
specified in OUT COND job processing parameters are ignored by
the algorithm that builds the file.
IGNORECODES References to conditions that satisfy a condition name that is
specified in DO COND job processing parameters are ignored by the
algorithm that builds the file.
<condition-mask> Name of the prerequisite condition.

■ The condition name can include the mask character * to represent


any number of characters (including no characters). In this
instance, the condition name must be enclosed in quotation
marks (for example, “LVL *”). Specify “*” by itself to include all
existing conditions.

■ When using both open and closed square brackets ([ and ]), the
condition name must be enclosed in quotation marks (for
example, “RATE[A1]”).

Chapter 3 Utilities 189


ctmldnrs

Listing prerequisite conditions in the manual conditions file


Specify the following to list prerequisite conditions in the Manual Conditions file:

ctmldnrs -LIST <Condition Name> [-INPUT <Filename>]

The parameters for this option are described in Table 53.

Loading prerequisite conditions to the


Conditions/Resources table
Specify the following to load prerequisite conditions from the Manual Conditions file
to the Conditions/Resources table:

ctmldnrs -LOAD <Condition Name> [-INPUT <Filename>]

Table 53 ctmldnrs – listing or loading manual conditions


Parameter Description
<Condition Name> All conditions in the input file that satisfy the specified
characters are loaded or listed.

■ Specify “*” by itself to load/list all conditions.

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

ctmldnrs -CALCCOND -ADDMODE NO

190 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmldnrs

Example 2

The following command creates a Manual Conditions file /h/mcond/data/output.dat


that ignores conditions with prefix “a”:

ctmldnrs -CALCCOND -ADDMODE NO -OUTPUT /h/mcond/data/output.dat \


-IGNOREIN “a*” \

Example 3

The following command loads all conditions from the default input Manual
Conditions file to the Conditions/Resources table:

ctmldnrs -LOAD “*”

Chapter 3 Utilities 191


ctmloadset

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.

ctmloadset is used when load balancing is implemented. The load-balancing


algorithm uses the data recorded in the Quantitative Resources table to determine to
which agent computer a job should be submitted.

CONTROL-M maintains the following information about usage of each Quantitative


resource:

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.

Values for the utility can be expressed as an absolute number of units or as a


percentage of the total number of units defined (Max value).

The utility’s output is displayed as type Q rows in the Quantitative Resources


window. However, the Mem Name field remains blank since this represents usage by
one or more non-CONTROL-M jobs.

Specify the following command to invoke the ctmloadset utility:

ctmloadset {TOTAL|OTHERS} <QRname> <loadValue>[%]

192 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmloadset

Table 54 ctmloadset parameters


Parameter Description
TOTAL Indicates that the load value provided specifies the total usage of the
resource by all jobs (both CONTROL-M jobs and non-CONTROL-M jobs).

When this option is specified, the utility calculates the usage of the
resource by non-CONTROL-M jobs and updates the table accordingly.
OTHERS Indicates that the load value provided specifies the units of the resource
used by one or more non-CONTROL-M jobs.
<QRname> Name of the Quantitative resource to update.
<loadValue> Number of units of the resource currently used.

-or-

When % is specified, the amount of the resource currently used, expressed


as a percentage of the maximum available units defined for this
Quantitative resource.

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 jacklin is used exclusively to run jobs submitted by CONTROL-M. The


computer is currently executing a job that uses 120 units of resource CPU_load.

■ computer ruby is used exclusively to run jobs submitted by CONTROL-M. The


computer is currently executing a job that uses 150 units of resource CPU_load.

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

ctmloadset TOTAL CPU@diana 80%

The Total Used for diana is set to 80% of 200, or 160. Since the usage by CONTROL-M
jobs is currently 75 units, ctmloadset calculates that the “Other” (non-CONTROL-M
usage) is 160 – 75, or 85.

Chapter 3 Utilities 193


ctmloadset

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

The CONTROL-M load-balancing algorithm uses these values when determining


where to submit the next job.

Example 2

The following examples demonstrate the effect of ctmloadset on the Quantitative


Resources table, as represented by the display generated by the ecaqrtab utility. All
examples below are based on the following premise:

For agent computer diana, 30 units of resource CPU@diana are currently used by
CONTROL-M jobs.

The output from the ecaqrtab utility is as follows:

Resource Name Type Max-Avail Reserved Used Free


CPU@diana L 50 0 30 20

Example 3

The following command specifies that the current usage of the Quantitative resource
CPU@diana by non-CONTROL-M jobs is 12 units:

ctmloadset OTHERS CPU@diana 12

As a result, the output from the ecaqrtab utility is now as follows:

Resource Name Type Max-Avail Reserved Used Free


CPU@diana L 50 0 42 8

194 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmloadset

Example 4

The following command specifies that the current usage of the Quantitative resource
CPU@diana by non-CONTROL-M jobs is 12%:

ctmloadset OTHERS CPU@diana 12%

The non-CONTROL-M usage of the resource is calculated as 12% of 50, or 6 units. As


a result, the output from the ecaqrtab utility is now as follows:

Resource Name Type Max-Avail Reserved Used Free


CPU@diana L 50 0 36 14

Example 5

The following command specifies that the current total usage of the Quantitative
resource CPU@diana by all jobs is 48 units:

ctmloadset TOTAL CPU@diana 48

As a result, the output from the ecaqrtab utility is now as follows:

Resource Name Type Max-Avail Reserved Used Free


CPU@diana L 50 0 48 2

Chapter 3 Utilities 195


ctmlog

ctmlog
The ctmlog utility creates a report from entries in the CONTROL-M log or deletes
entries in the CONTROL-M log.

Specify one of the following commands to invoke the ctmlog utility:

ctmlog <action> <actionOption> \


<fromDate> <fromTime> <toDate> <toTime> \
[<output> [<reportWidth>] ]

ctmlog <action> <actionOption> "*" \


[<output> [<reportWidth>] ]

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.

Table 55 ctmlog – valid actions (part 1 of 2)


Action Action option
listss Prints a report for a specific <subsystem> Subsystem to include in the report.
subsystem. Specify one of the following:

■ SU Supervisor

■ TR Tracker

■ SL Selector

■ CD Download, Database update

■ NS Communication with agent


computers

■ LG Agent utilities

■ UT Utilities

■ WD Watchdog
list Prints a report of all entries. None.

196 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmlog

Table 55 ctmlog – valid actions (part 2 of 2)


Action Action option
listord Prints a report of entries for a <Order ID> Order ID to include in the report.
specific Order ID.
Note: The Order ID as displayed in
the Job Details window of
CONTROL-M/EM is a base 36
number. If you want to specify the
Order ID here as a base 10 number,
precede the number with an asterisk
and enclose the result in quotation
marks (for example, “*1234”).
listjob Prints a report including all entries <Job no.> Job number to include in the report.
for a specific job number.
listmsg Prints a report of messages with a <msgid> Message ID to include in the report.
specific message ID.
delete Deletes entries in a specified date None
and time range.
listjobname Prints a report including all entries <jobname> The name of the job whose entries
for the specified job name. should be printed in the report.

Table 56 ctmlog parameters


Parameter Description
<From Date> Starting and ending dates and times for the range of entries to be
<From Time> scanned by the specified action. Date is specified in yyyymmdd
<To Date> format. Time is specified in hhmm format.
<To Time>
“*” Asterisk enclosed in quotation marks. Scan all entries in the
CONTROL-M log (without regard to date or time).
<Output> Full path name to which the report should be sent (optional). If
this parameter is not specified, the output is routed to the default
output device. This parameter is not applicable for the delete
action.
<Report Width> Width (in columns) of the report to generate. Specify a number in
the range of 80 – 132 (default is 80). This parameter can only be
specified if the Output parameter is specified.

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:

ctmlog list 20020312 1000 20020314 0800


~<controlm_owner>/ctm_server/user1/rprt.txt

Chapter 3 Utilities 197


ctmlog

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:

ctmlog listss CD "*" ~<controlm_owner>/ctm_server/user1/gdrprt.txt 132

198 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmnodegrp

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.

Specify the following command to invoke the ctmnodegrp utility:

ctmnodegrp
[ -LIST |
-EDIT -NODEGRP <nodeGroup>
-APPLTYPE <applicationType>
[ -VIEW |
-ADD <nodeid> |
-DELETE <nodeid> ] |

Table 57 describes the variables of this command.

Table 57 ctmnodegrp – variables (part 1 of 2)


Variable Description
-LIST Displays a list of all existing node groups.
-EDIT Views, creates, or modifies a node group.
-NODEGRP Specifies which node group to be viewed, created, or
modified.
-APPLTYPE Specify the application with which the node group is
associated.

Valid values are:

■ OS – None Control Modules applications (Default)


■ SAP – SAP Applications
■ OAP – Oracle Applications
■ Any other application type defined by the user. For
more information, see the Software Development Guide
for Control Modules.

Chapter 3 Utilities 199


ctmnodegrp

Table 57 ctmnodegrp – variables (part 2 of 2)


Variable Description
-VIEW Displays the node IDs in the specified
node group.
-ADD Prompts for the name of a node ID to
add to the specified group.

Note: The selected node ID must be able


to run jobs associated with the
application type specified for this node
group.
-DELETE Prompts for the name of a node ID to
delete from the specified group.
-DELETE Prompts for the name of the node group to delete from the specified
group.

Node Group Menu


The Node Group menu is used to maintain and view node groups. Node groups are
used by the CONTROL-M/Server load-balancing function.

1 Start the CONTROL-M Main Menu.

2 Choose CONTROL-M Main Menu => Node Group.

The following menu is displayed.

Figure 6 Node Group Menu


Node Group Menu
---------------

Select one of the following options:

1 - List All Node Groups


2 - Edit Node Group
3 - Delete Node Group

q - Quit

The options in this menu are described in Table 58.

Table 58 Options of the Node Group Menu


Option Description
List All Node Groups Displays a list of all existing node groups.
Edit Node Group Views, creates or modifies a node group. For details, see the next
section.

200 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmnodegrp

Table 58 Options of the Node Group Menu


Option Description
Delete Node Group Requests the name of an existing node group, and then deletes the
group.
Quit Quits the Node Group menu and returns to the CONTROL-M Main
Menu.

List All Node Groups

To list all node groups, select the List All Node Groups option in the Node Group
Menu.

Edit node group

This option is used to view, create or modify a node group. When this option is
selected, the following prompt is displayed:

Node Group Name:

Specify the name for a new node group or specify the name of an existing node group
whose member list you want to view or modify. The following menu is displayed:

Edit Node Group Menu


-------------------

Select one of the following options:


1 - View Current Node Group
2 - Add Node ID
3 - Delete Node ID

q - Quit

Enter Option (Group: <node_group>) :

Specify the number for the desired option:

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.

Chapter 3 Utilities 201


ctmordck

ctmordck
The ctmordck utility lists job processing definitions associated with a specific User
Daily name and indicates the security status of each job with regard to the owner of
the User Daily job (that is, whether or not the CONTROL-M security mechanism will
allow jobs associated with a User Daily name to run with the authorizations currently
assigned to the owner of the User Daily job).

This utility displays the following fields:

■ Name of the job.


■ Number of the job in the CONTROL-M/Server database.
■ Author of the job processing definition.
■ Owner of the job processing definition.

The following information is displayed for each job processing definition:

Table 59 ctmordck – output columns


Column Description
TB Whether or not the owner of the User Daily job is authorized to order
the Scheduling table of the job listed.
FL Whether or not the owner of the User Daily job is authorized to execute
the script file of the job listed.
UA Whether or not the owner of the User Daily job is authorized to order
jobs for the owner of the job listed.

NOTE
This utility can be used non-interactively for non-terminal destinations (see the description of
the <Output> parameter below).

Specify the following command to invoke the ctmordck utility:

ctmordck <User Name> <User Daily> [<Output>]

Table 60 ctmordck parameters


Parameter Description
<User Name> Owner of the User Daily job.
<User Daily> User Daily name.
<Output> Full path name to which the report should be sent. If this parameter is
not specified, the output is routed to the default output device.

202 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmordck

Example

The following command generates a list for user SYSTEM and the User Daily
SYSTEM. The list is directed to the udlist file:

ctmordck SYSTEM SYSTEM ~<controlm_owner>/ctm_server/user1/udlist

The following is sample output from the above command:

Figure 7 ctmordck sample output


Date: 10-NOV-2000. Page: 1
User SYSTEM , Daily SYSTEM Ordering list
JOBNAME No. AUTHOR OWNER TB FL UA
---------- --- ------ ----- -- -- --
CTMLOG HAN 2066 root root Y N Y
PURGE JOB 2067 root root Y N Y
user3-DAIL 2033 BARRY user3 Y N Y
user2-DAIL 2032 STEVE user2 Y N Y
user1-DAIL 2031 STEVE user1 Y N Y
JEAN-UD 2000 jean jean Y N Y
JOB-STATUS 2068 root root Y N Y
GD-TEST1 20 jean user1 Y N Y
GD-TEST2 21 jean user2 Y N Y
GD-TEST3 22 jean user3 Y N Y
GD-user4 2008 jean user4 Y N Y
GD-user5 2009 jean user5 Y N Y

Chapter 3 Utilities 203


ctmorder

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

The ctmorder utility can be invoked using either of two formats.

■ The first format contains only a few parameters in a specific order:

ctmorder <scheduling_table> <job_name> <odate>\


[{order|force}]

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:

ctmorder -schedtab <scheduling_table_name> \


-jobname <job_name> \
-odate <scheduling_date> \
[-force {y|n}] \
[-hold {y|n}] \
[-seqno <job_sequence_number>] \
[-ingrouporderid {<group_order_id>|last|alone|newg]} \
[-noduplication] \
[-debug <debug_level 0-5>] \
[-quiet] \
[-autoedit <varname> <expression>]
[-odate_option {value_date|run_date}] \

204 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmorder

-or-

ctmorder -input_file <full_path_file_name>

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.

Table 61 ctmorder parameters (part 1 of 4)


Parameter Description
-schedtab Name of the Scheduling table containing the jobs.
-jobname Job name (or mask) of the job(s) to order or force. Mandatory.

You can order a Group Scheduling table, but you cannot order an
individual job, or selection of jobs, from a Group Scheduling table.

The job name can include the following mask characters:

■ * — represents any number of characters (or none). Specify * by itself


to include all jobs in the table.
Note: Any parameter including * must be enclosed in double
quotation (see Example 2 below).

■ ? — represents any single character.

■ $ — represents any single character.

Note: Whether the *, ?, and $ characters act as wildcards or as ordinary


characters in a job name is determined by the presence or absence of a
-seqno parameter:

■ The *, ?, and $ characters will only act as wildcards in the -jobname


parameter if no -seqno parameter is specified.

■ The *, ?, and $ characters will only act as ordinary characters in the


-jobname parameter if a -seqno parameter is specified. In this case,
the specified job name must exactly match the name of the job in the
indicated sequence, or the job will not be ordered.
-odate Indicates the scheduling date (odate) to be associated with job(s). Valid
values:
ODAT The current working date of the computer on which
CONTROL-M/Server is running.
This is the default value.
yyyymmdd A specific working day in yyyymmdd format.
Note: The interpretation of this parameter value depends on the value
specified for the -odate_option parameter (described below).

Chapter 3 Utilities 205


ctmorder

Table 61 ctmorder parameters (part 2 of 4)


Parameter Description
-force Add the specified jobs to the Active Jobs file regardless of scheduling
criteria. If -force is not specified, jobs are added to the Active Jobs file
only if their scheduling criteria are satisfied (known as order).
Y Force the specified jobs.
N Order the specified jobs. Default.
-hold Place the specified jobs in the Active Jobs file in Hold status.
Y Hold the specified jobs.
N The specified jobs are not held. Default.
-seqno A counter identifying the row number of the job in the Scheduling table.
The first job in each Scheduling table is numbered 1 and each subsequent
job increments the counter by one. If this parameter is not specified, the
first job in the specified table is ordered. Optional.
Note: If this parameter is specified, any *, ?, and $ characters in the
-jobname parameter are assumed to be ordinary characters rather than
wildcards. Therefore:

■ Do not specify a -seqno parameter if you are specifying wildcards in


the -jobname parameter.

■ If you are specifying *, ?, or $ characters as ordinary characters (not


wildcards) in the -jobname, you must specify the appropriate -seqno
parameter (and the specified job name must exactly match the actual
job name).
-ingrouporderid Note: This parameter is relevant only for jobs in a Group Scheduling
table. If the table being ordered is not a Group Scheduling table, this
parameter is ignored.
<group_ Order ID of an existing Group Scheduling table.
order_ID>
last Jobs are added to the last ordered instance of their Group
Scheduling table in the Active Jobs file.
alone Jobs are ordered individually. They are not associated
with any Group Scheduling table.
Note: The group_order_ID, last, and alone options can only be used
when the -force parameter is set to Y.
newg A new group is created and the specified jobs are ordered
to that Group Scheduling table. Default.
-noduplication Allow jobs to be ordered and added to an existing ordered Group
Scheduling table only if those jobs have not already been ordered in that
instance of the Group Scheduling table.

This parameter can be specified only if last or <group_order_ID> is


specified for the -ingrouporderid parameter.

Note: This parameter is relevant only for jobs in a Group Scheduling


table.

206 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmorder

Table 61 ctmorder parameters (part 3 of 4)


Parameter Description
-debug level Activates a debug trace at the specified level.
Valid levels: 0 – 5. Default: 0

Performance is somewhat slower when operating in debug mode. BMC


Software recommends that you activate debug mode only when
requested by Technical Support.
-quiet Suppresses display of the utility output. If specified, no information
messages are displayed during execution of the command.
-autoedit Adds an AutoEdit expression to each job, Scheduling table, or Group
Scheduling table that is ordered by the utility.

For more information, see the description of AutoEdit Facility in the


CONTROL-M Job Parameter and Variable Reference Guide. The following
information must be specified for each new AutoEdit variable.
<varname> Name of the variable.
<expression> Value assigned to the variable.
-odate_option Indicates how the specified -odate value should be used.
Valid values, one of the following:
value_date The specified odate is the odate value for the job(s). The
jobs should be run during the current working day.
Default.

Note: If a time zone is specified in a job processing


definition, the job is run according to the specified time
zone.
run_date Jobs ordered by this run of the ctmorder utility should be
run only when the specified odate begins.

■ If the specified odate is the current working day, the


job will run as described in value_date above.

■ If the specified odate has not begun (for example, due


to time zone specifications), then the job will wait in
the Active Jobs file (with WAIT_ODAT status) until
the start of the specified working day.

Note: If the specified odate has already passed, the


ctmorder utility will not run and an error message will be
displayed.

Chapter 3 Utilities 207


ctmorder

Table 61 ctmorder parameters (part 4 of 4)


Parameter Description
-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:

■ prepare and save files of utility parameters that can be reused.

■ specify utility input longer than the number of characters allowed in


the command line.

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:

ctmorder -schedtab ACCT100 -jobname “*” -odate odat

You can get the same result using the -input_file parameter as follows:

ctmorder -input_file ~<controlm_owner>/ctm_server/data/ctmorder_acct100.txt

where the referenced file contains the following lines:

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

208 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmorder

ctmorder -schedtab ACCT100 -jobname "ga*" \


-odate 20060315 -force y

Example 3

The following command forces all jobs contained in the Scheduling table ACCT100
whose job name is prodyjob. Any jobs placed in the Active Jobs file will have the date
December 31, 2005 as their original scheduling date:

ctmorder -schedtab ACCT100 -jobname prodyjob \


-odate 20051231 -force y

Example 4

The following command forces the third job contained in the Group Scheduling table
ACCT200 whose job name parameter consists of prodyjob. This job is placed in the
Active Jobs file and will have the date December 31, 2005 as its original scheduling
date. This job is added to an active group whose orderid is B2.

ctmorder -schedtab ACCT200 -jobname prodyjob \


-odate 20051231 -force y -seqno 3 -ingrouporderid B2

Example 5

The following command assigns the AutoEdit variable %%PRDNDATE with the
value of %%ODATE, and orders every job in the PRODUCTION Group Scheduling
table whose job name has a prefix of PRDN. These jobs are placed in the Active Jobs
file in a new group and are assigned December 31, 2005 as their original scheduling
date.

ctmorder -schedtab PRODUCTION -jobname “PRDN*” \


-odate 20051231 -order y -ingrouporderid newg\
-autoedit %%PRDNDATE %%ODATE

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.

Chapter 3 Utilities 209


ctmorder

ctmorder -schedtab INVENTORY -jobname “BIN_A?” \


-odate 20051231 -force n -ingrouporderid newg \
-autoedit %%PRDNDATE %%ODATE \
-autoedit %%APPLIC STOCK_COUNT \
-autoedit %%OWNER STOREMAN

210 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmpasswd

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.

To invoke the ctmpasswd utility, specify the following command

ctmpasswd

The system displays the prompt:

Please enter the old password for <CONTROL-M_DatabaseUser> account:

1 Enter the old password for the CONTROL-M/Server account.

The system displays the following prompt:

Please enter the new password for <CONTROL-M_DatabaseUser> account:

2 Enter the new password. Make sure that the password contains at least 6
characters. You will not see your entry on the screen.

The system displays the following prompt:

Enter again to verify:

3 Re-enter the new password.

The system responds with the following prompt:

Password was successfully changed

Chapter 3 Utilities 211


ctmping

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.

To invoke the ctmping utility, specify the following command

ctmping -NODEID <hostName> [ -NODETYPE <REGULAR|REMOTE> ]


[ -NODEID <hostName> [ -NODETYPE <REGULAR|REMOTE> ] ]
[ -FILE <inputFile> ]
[ -DISCOVER <y|n>]
[ -DEBUG <debug level 0-5> ]
[ -QUIET ]
[ -FULLDETAILS ]

Table 62 contains descriptions of the parameters in the ctmping command.

Table 62 ctmping parameters (part 1 of 4)


Parameter Description
-NODEID Host name of the agent or remote host computer to be pinged (tested).

At least one Node ID must be specified for each run of the ctmping utility.
Additional Node IDs can optionally be specified to enable a single run of
this utility to test communication with more than one agent computer.

212 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmping

Table 62 ctmping parameters (part 2 of 4)


Parameter Description
-NODETYPE Describes the type of computer that is being pinged.

■ REGULAR – A computer that is registered as an agent in the


CONTROL-M/Server database. CONTROL-M/Agent is installed on
this computer.

■ REMOTE – A computer that is registered as a remote host in the


CONTROL-M/Server database. It is not necessary for a
CONTROL-M/Agent to be installed on this computer. A computer
that has a CONTROL-M/Agent installed on it, can also be registered
as a remote host.

If you do not specify a NODETYPE:


■ if the node ID of the computer is already defined, the NODETYPE that
was defined is used again
■ if the node ID of the computer was not used previously, then
REGULAR is used as the default
■ in the event that the type is unknown, that is, still in node discovery
state, the utility is unable to complete the request. Wait for the
discovery process to complete, then run the utility again.
If you specify a NODETYPE:
■ if the node ID is already defined in CONTROL-M/Server and it
conflicts with the earlier definition (for example, it was defined earlier
as REGULAR and you are now specifying REMOTE), then the utility
will not be able to complete the request. If the intention was to convert
the defined node type, then for more information about how to
convert a computer from one type to another, see “ctmhostmap” on
page 168 and Appendix C, “Conversion of agents and remote hosts”.
■ if the node ID is already defined in CONTROL-M/Server and the
NODETYPE being specified now is same as that of the earlier
definition, then the utility will use the specified NODETYPE for the
node ID.
■ if the node ID has not been previously defined in
CONTROL-M/Server, then the utility will use the specified
NODETYPE for the node ID.

Chapter 3 Utilities 213


ctmping

Table 62 ctmping parameters (part 3 of 4)


Parameter Description
-FILE Full path and name of a file containing a list of host computers to be
pinged.

Each line in the specified file contains:


■ the name (node ID) of the agent or remote host (mandatory)
■ the NODETYPE (optional)

The delimiter between the name and the NODETYPE is a blank or any
number of blank spaces.

Note: Where the computer type is not specified, a discovery process


attempts to determine the type to be used. See -NODETYPE above.

Example
Assume the following computers must be pinged:
Name Type
dime not specified
comet CONTROL-M/Agent
mars remote host computer

The text below specifies the above details in a file:

dime (NODETYPE is not specified)


comet REGULAR
mars REMOTE
-DISCOVER Indicates whether to update the database.

■ Y – Update the database with information gathered by the utility


■ N – Do not update the database

Note: If -DISCOVER is not specified, ctmping performs an automatic


discovery, as follows:
If an agent is
■ available – the CONTROL-M/Server database is updated with the
details of the agent or remote host
■ unavailable, for a new agent or remote host in the
CONTROL-M/Server database, a message is displayed, asking if you
want to add the discovered agent to the CONTROL-M/Server
database

Default: automatic discovery


-DEBUG Activates a debug trace at the specified level. Valid levels: 0 through 5.
Default: 0. Performance is slower when operating in debug mode. BMC
Software recommends that you activate debug mode only when requested
by Technical Support and use the specified level.
-QUIET Suppresses display of utility output.

214 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmping

Table 62 ctmping parameters (part 4 of 4)


Parameter Description
-FULLDETAILS Generates a status report of the communication parameters of each
specified agent or remote host. Where an agent is unavailable, the report
displays the reason why the agent is unavailable. Where a remote host is
available it displays the connection information.

Example 1

To connect and perform a communication test with the agent jacklin, specify the
following command:

ctmping -nodeid jacklin

The response is:

Agent: jacklin is alive

Example 2

To attempt to connect and test communication with agent diana (that is currently
down), specify the following command:

ctmping -nodeid diana

The response is:

Agent: diana, Msg: Agent not available.


Add it to the database? y/n:

Example 3

To connect and test communication with the agent jacklin and collect configuration
information needed for the discovery process, specify the following command:

ctmping -nodeid jacklin -discover y

The response is:

Agent: jacklin is alive

Example 4

To connect and test communication with the agent jacklin and generate a debug trace
without displaying the results on screen, specify the following command:

Chapter 3 Utilities 215


ctmping

ctmping -nodeid jacklin -debug 1 -quiet

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

PID is the Process Identity number.

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:

ctmping -nodeid dime -nodetype remote -fulldetails

The following response is displayed:

Remote host [dime] is available through Agent [comet]


Connection protocol : SSH
Port number : 22
Encryption method : Blowfish
Compression : No
Remote host [dime] is available through Agent [mars]
Connection protocol : SSH
Port number : 22
Encryption method : Blowfish
Compression : No

Example 6

Assume the nodeid_list.txt text file contains the full path to the following node IDs:

■ local agent jacklin


■ remote host dime
■ regular agent diana

To generate a report showing the result of pinging the node IDs specified in
nodeid_list.txt, specify the following command:

ctmping -file ~<controlm_owner>/ctm_server/nodeid_list.txt

The response is:

Agent : jacklin is alive

216 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmping

Remote host : dime is alive

Agent: diana Msg: Agent not available

Chapter 3 Utilities 217


ctmpsm

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

To invoke the ctmpsm utility interactively

1. Log on to the server computer as the CONTROL-M/Server owner (for example,


user controlm).

2. Specify the command: ctmpsm.

The following menu is displayed:

NOTE
The ctmpsm utility can also be invoked by the Command Line Interface, as described in
“Command line invocation” on page 227.

Figure 8 ctmpsm – production support menu


Active Jobs File Resource Map
---------------- ------------

1) List All 61) Control Resources


2) List All (Show Started/Ended) 62) Quantitative Resources
3) List All (Show Application) 63) Prerequisite Conditions
4) List All (Show Mem Name) 64) Control Resources Usage
65) Quantitative Resources
Usage

218 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmpsm

5) List Jobs That Ended OK


6) List Jobs That Ended NOTOK
7) List Submitted/Executing Jobs
8) List Cyclic Jobs
9) List Jobs Waiting for Time Window
10) List Jobs Waiting for Confirmation
Scheduling Functions
--------------------
40) List Application/Group Tree 71) Scheduling Tables
41) List Scheduling Tables 72) Order Tables/Jobs
42) List Group Entities

Q) Quit

Enter Option:

The functions in this menu are divided into three categories:

■ Active Jobs File functions provide various views of the Active Jobs file. Each view
displays information about the jobs and provides options to perform such actions
on the jobs as Hold, Free, Delete, Rerun, Why, Confirm, View or modify job details,
and view the CONTROL-M log.

■ Resource Map functions enable you to view and modify Quantitative resources,
Control resources, and prerequisite conditions. The first three of these functions
activate the ecactltb, ecaqrtab, and ctmcontb utilities respectively.

■ Scheduling Functions enable you to order or force Scheduling tables or specific


jobs in Scheduling tables. You can also generate monthly or yearly scheduling
plans using the ctmrpln utility.

Active Jobs file options


Perform various tasks using information in the Active Jobs file. These options are
described in Table 63.

Table 63 ctmpsm - menu options for Active Jobs file (part 1 of 2)


Code Option Description
1 List All Lists all jobs in the Active Jobs file.
2 List All Lists all jobs in the Active Jobs file. Indicates which jobs
(Show have started or ended execution.
Started/Ended)
3 List All Lists all jobs in the Active Jobs file. Indicates the application
(Show Application) to which each job belongs.

Chapter 3 Utilities 219


ctmpsm

Table 63 ctmpsm - menu options for Active Jobs file (part 2 of 2)


Code Option Description
4 List All Lists all jobs in the Active Jobs file. Indicates the Mem Name
(Show Mem Name) for each job.
5 List Jobs That Lists jobs in the Active Jobs file with a completion Ended
Ended OK OK status.
6 List Jobs That Lists jobs in the Active Jobs file that have a completion
Ended NOTOK Ended NOTOK status.
7 List Submitted/ Lists jobs in the Active Jobs file that are currently executing.
Executing Jobs
8 List Cyclic Jobs Lists jobs in the Active Jobs file that are cyclic.
9 List Jobs Waiting for Lists jobs in the Active Jobs file that are waiting to begin
Time Window executing based on their Time From parameter.
10 List Jobs Waiting for Lists jobs in the Active Jobs file that are waiting for
Confirmation confirmation.
40 List Displays a summarized list of the applications and groups
Application/Group for all jobs currently contained in the Active Jobs file.
Tree
41 List Scheduling Displays a list of all Scheduling tables in the Active Jobs file.
Tables
42 List Ordered Groups Displays a list of all CONTROL-M groups in the Active Jobs
file.

All Active Jobs file options display the following menu at the bottom of the screen:

Figure 9 ctmpsm - Active Jobs File Menu Options


H) Hold, F) Free, D) Delete, U) Undelete, R) Rerun, W) Why, Z)
Details
LO) LogOrd, LJ) LogJob, Cn) Confirm, Sx)Sort[x: 1.ORDERNO 2.JOBNAME]
J) Sysout A) Statistic V) View Script/JCL K) Force OK I)Dependencies
JobsGx) Global action x [x: H(Hold), F(Free), D(Delete), U(Undelete),
R(Rerun)]
Q)Quit
Enter Option:

These actions are described in Table 64:

Table 64 ctmpsm - Active Jobs file actions (part 1 of 3)


Option Action Description
H Hold Hold a job.
F Free Free a previously held job.
D Delete Mark a job for deletion.

Note: Jobs with Executing or Submitted status cannot be deleted.


U Undelete Undelete a job marked for deletion.

220 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmpsm

Table 64 ctmpsm - Active Jobs file actions (part 2 of 3)


Option Action Description
R Rerun Rerun a job.
Note: Rerun actions cannot be performed on a group entity.
W Why Display why a job has not yet been submitted.
Z Details View or modify (zoom and save) a job’s parameters.

Notes:

■ When a job is being viewed, it is automatically held. After


changes are made and saved, the job is freed.

■ If prerequisite conditions are added to or deleted from a job in


the Active Jobs file using the Z option, the changes are
automatically saved when you quit.

■ If a cyclic job is terminated by a Do Stop Cyclic,


-dostopcyclic, or DO ACTION=”SPCYC” parameter, the view
will contain Cyclic:T where T indicates Terminated.
LO LogOrd List CONTROL-M log entries for a specific Order ID.
LJ LogJob List CONTROL-M log entries for a specific Job Name.
Cn Confirm Confirm submission of a job.
S1 Sort (by Sort jobs displayed by Order number.
Order No.)
S2 Sort (by Job Sort jobs displayed by Job Name.
Name)
J Sysout Display the job SYSOUT.
A Statistic Display the job statistics
V View View a job’s script or JCL.
Script/JCL
Note: This option is available if CONTROL-M/Server is active.
K Force OK Force the status of a job to be OK.
I Dependenc Display all jobs that depend on the specified job.
ies Jobs
GH Global Hold all jobs in the displayed list.
Action
(Hold)
GF Global Free all jobs in the displayed list.
Action
(Free)
GD Global Mark all jobs in the displayed list for deletion.
Action
(Delete)
GU Global Undelete all jobs marked for deletion.
Action
(Undelete)

Chapter 3 Utilities 221


ctmpsm

Table 64 ctmpsm - Active Jobs file actions (part 3 of 3)


Option Action Description
GR Global Rerun all jobs in the displayed list.
Action Note: Rerun actions cannot be performed on a group entity.
(Rerun)
Note: The R (Rerun) option and the Global options (GH, GF, GD, GU, and GR) affect only
jobs and not group scheduling tables.

Resource map options

Table 65 ctmpsm - menu options for the resource map


Code Option Description
61 Control Lists Control resources currently used in the Active environment.
Resources Activates the ecactltb utility.
62 Quantitative Allows you to list, add, modify, or delete Quantitative resources in
Resources the Active environment. Activates the ecaqrtab utility.
63 Prerequisite Allows you to view, add or delete prerequisite conditions in the
Conditions Active environment. Activates the ctmcontb utility.
64 Control Shows current usage of Control resources by jobs in the Active Jobs
Resources file.
Usage
65 Quantitative Shows current usage of Quantitative resources by jobs in the Active
Resources Jobs file.
Usage

Scheduling function options

Table 66 ctmpsm - menu options for scheduling functions


Code Option Description
71 Scheduling Lists Scheduling tables and jobs defined in the CONTROL-M/Server
Tables database. Allows you to force Scheduling tables or jobs, add or delete
Scheduling tables and generate scheduling reports.
72 Order Allows you to order Scheduling tables or jobs. You are prompted to
Tables/Jobs specify:

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

222 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmpsm

When the Scheduling Tables option is selected, output similar to the following is
displayed:

Figure 10 List of scheduling tables output by the ctmpsm utility


Scheduling Tables
-----------------
Table name Daily name Table type
1) supply Quarterly GROUP
2) temp REGULAR
3) inventory GROUP
4) Payroll Monthly GROUP
5) inventory SYSTEM GROUP
6) RE_SYSOUT vitaly REGULAR

D#) Delete UserDaily Table # U#) Update table #


F#) Force table # J#) List jobs #
A) Add R) Remove Table Q) Quit.

Option []:

The options in Table 67 are available from the above screen.

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.

Table 67 ctmpsm - options for scheduling functions (part 1 of 2)


Code Option Description
A Add Adds a User Daily to an existed table. When selected, you are prompted
for the Table name and User Daily name.
R Remove Deletes a specific Scheduling table and all its associated jobs (for
example, specify R RE_SYSOUT to delete table RE_SYSOUT).
D# Delete # Removes an instance of a scheduling table from the
CONTROL-M/Server database.

■ If the specified instance is the only instance of the table (that is, that
table is ordered by only one user daily), the scheduling table and all
its associated jobs are deleted.

■ If the specified instance is not the only instance of the table, then only
the specified instance is removed from the CONTROL-M/Server
database.

Chapter 3 Utilities 223


ctmpsm

Table 67 ctmpsm - options for scheduling functions (part 2 of 2)


Code Option Description
F# Force Forces a specific Scheduling table (for example, specify F6 to force table
table # RE_SYSOUT).

The following prompt is displayed:

Odate (YYYYMMDD/ODAT) [ODAT]:

Enter the odate for the job to be forced in YYYYMMDD format, or enter
the value ODAT to indicate that the job should use the current working
date as its odate.

The following prompt is displayed:

ODATE option (VALUE_DATE|RUN_DATE) [VALUE_DATE]:

■ To run jobs now with the specified odate, specify, VALUE_DATE

■ To wait until the specified odate begins before running the jobs,
specify RUN_DATE.

If the specified table is a Group Scheduling table, the following prompt is


displayed:

Please choose one of the following:

A) Alone.

N) New group.

L) Last.

B) Bind to existing group Orderno.

These options are described below:

■ A – Forces each job in the table separately as a non-group job.

■ N – Forces the jobs in the table as a new group in the Active Jobs file.

■ L – Forces the jobs in the table, and adds them to the most recently
ordered group in the Active Jobs file.

■ B – Forces the jobs in the table, and adds them to a specified group in
the Active Jobs file.
J# List jobs # Lists jobs in a Scheduling table and provides options to force a specific
job or generate a report (for example, specify J1 to list the jobs in table
supply).
U# Update 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).

224 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmpsm

When the List Jobs # option is selected, output similar to the following is displayed:

Figure 11 List of Jobs output by the ctmpsm utility


Scheduling Table RE_SHED Jobs
-----------------------------

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

Q) Quit. F#) Force job #


M#) Month Schedule Plan # Y#) Year Schedule Plan for job #

Option []:

The options in Table 68 are available from the above screen.

Table 68 ctmpsm - options in the Scheduling Table List Jobs menu


Code Option Description
F# Force job # Forces a specific job (for example, specify F2 to force job
DAYS_30_FEB).
M# Month Generates a monthly Job Order report for the table. You are
Schedule Plan prompted to enter the year and month in format YYYYMM.
Y# Year Schedule Generates a yearly Job Order report for a specific job. You are
Plan for job # prompted to enter the year in format YYYY.

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.

Chapter 3 Utilities 225


ctmpsm

Examples

To display the most recent SYSOUT of the job whose order ID is 1234, specify the
following command:

ctmpsm -listsysout 1234

To display the second SYSOUT of the job whose order ID is 1234, specify the
following command:

ctmpsm -listsysout 1234 -sysoutnumber 2

The ctmpsm utility redirects the display of the SYSOUT of a job to the viewer defined
by parameter CTMPSM_VIEWER. This parameter is specified in the
~<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]

To specify the CTMPSM_VIEWER parameter in the config.dat file, type the


following:
CTMPSM_VIEWER <viewerCommand>

<viewerCommand> is the name of the viewer application selected by the user for
displaying the SYSOUT.

Example

To specify the CTMPSM_VIEWER parameter in the config.dat file, open a viewer in


a new window and display SYSOUT with the more switch:

CTMPSM_VIEWER xterm -e more

Values in STATE and STATUS ctmpsm fields


Table 69 displays the values that are listed in the STATE and STATUS fields when
ctmpsm is executed.

Table 69 ctmpsm STATE and STATUS fields (part 1 of 2)


Value Description
STATUSES
OK The job completed okay.

226 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmpsm

Table 69 ctmpsm STATE and STATUS fields (part 2 of 2)


Value Description
NOTOK The job did not complete okay.
STATES
Wait Sche The job is waiting to be scheduled.
Wait Conf The job is waiting for user confirmation.
Wait Reru The job is waiting to be rerun.
Wait Time The job is waiting for its time frame.
Wait Cond The job is waiting for a condition.
Wait Reso The job is waiting for a resource.
Submitted The job was submitted (that is, the job was sent to an agent).
Retry Sub The job is waiting for a submission retry.
Executing The job is executing.
Ended The job has ended.
Analyzed The job is being analyzed.
Disappear The job has disappeared in the agent.
Post proc The job has performed its post processing activities.
Wait ODAT The job is waiting for the appropriate ODAT.
Post ODAT The appropriate ODAT of the job already passed.
Unknown The status of the job is unknown.

Command line invocation


The format and valid values for each mode of the ctmpsm utility command line
interface are described in Table 70.

Table 70 ctmpsm - mode descriptions and syntax (part 1 of 9)


Mode Description
CHILD Lists dependent jobs with IN conditions that are created by the job whose
order ID is specified in this command.

ctmpsm -CHILD <order_ID> [<tasktype>]


order_ID Identifies the “parent” job.
tasktype B=batch job
D=detached
C=command
U=dummy
X=external job

Chapter 3 Utilities 227


ctmpsm

Table 70 ctmpsm - mode descriptions and syntax (part 2 of 9)


Mode Description
IMPORT_CAL Imports a calendar from the CONTROL-M/EM.

ctmpsm -IMPORT_CAL <CONTROL-M/EMexportedFileName> [overwrite]

<CONTROL-M/EMexportedFileName> is the full path name of the


calendars file to be imported from CONTROL-M/EM.

If overwrite is specified, when the specified calendar to be imported from


CONTROL-M/EM already exists in the CONTROL-M/Server database,
the import action will overwrite it. Default: overwrite is not specified.

Note: There is a line of output for every calendar handled by the


import_cal option.

Examples
■ After a successful import of a calendar, the following message is
displayed:

Calendar <x>, for year <y>, has been imported.

■ Assume calender <x>, that is being imported, already exists in the


CONTROL-M/Server database, and that the overwrite option has not
been specified. The following message is displayed:

Calendar <x>, for year <y>, that already exists, has


not been imported.
LISTCAL Lists available calendars. The list can be restricted by calendar name and
year.

ctmpsm -LISTCAL [<Calen_name>][<Calen_year>]


Calen_name Restricts the list to calendars with the specified name
or prefix (indicated by * at the end).
Calen_year Restricts the list to calendars for the specified year.

228 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmpsm

Table 70 ctmpsm - mode descriptions and syntax (part 3 of 9)


Mode Description
LISTALL Lists jobs in the Active Jobs file. The list can be filtered by time,
application, and member name. The list can be sorted by order ID or job
name.

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:

ODAT – Order date.

TIME _ Time execution started and ended.

APPLICATION _ Application to which the job belongs.

MEMNAME _ Member name for the job.

ALL – Includes ODAT, FROMTIME and UNTIL fields.

ALLFIELDS – Includes ODAT, MEMNAME, and APPLICATION fields.

–SORT indicates the order in which the jobs should be listed. Valid
values: ORDERID and JOBNAME.

Note for other job statuses:

Two additional job statuses are visible only when using the LISTALL
option:

■ WAIT_ODAT The Job's Odate is later than the


CONTROL-M/Server working date for the relevant timezone. The
job is waiting for the relevant day (Odate) to begin.
■ POST_ODAT The job's Odate is earlier than the
CONTROL-M/Server working date for the relevant timezone. The
job will be deleted during the next run of the New Day procedure.

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.

Chapter 3 Utilities 229


ctmpsm

Table 70 ctmpsm - mode descriptions and syntax (part 4 of 9)


Mode Description
LISTJOB Lists jobs that are cyclic, as well as jobs in the Active Jobs file with a
specified status. Jobs can be filtered by status: OK, NOTOK, executing,
waiting for the end of a time interval, waiting for confirmation.

ctmpsm -LISTJOB
{OK|NOTOK|EXECUTING|CYCLIC|
WAITTIME|WAITCONFIRM}
[-SORT {ORDERID|JOBNAME}]

OK _ Jobs with a completion Ended OK status.

NOTOK _ Jobs with a completion Ended NOTOK status.

EXECUTING _ Jobs that are currently executing.

CYCLIC _ Jobs that are cyclic.

WAITTIME _ Jobs waiting to begin executing based on the time specified


in their Time From parameter.

WAITCONFIRM _ Jobs waiting for confirmation.

–SORT indicates the order in which the jobs should be listed. Valid
values: ORDERID and JOBNAME.
LISTGROUP Lists jobs in the specified group that are associated with a specified
application.

ctmpsm -LISTGROUP <application> <group>> [<scheduling date>]

Wildcards can used as part of the specified application or group names.

* represents any number of characters.

? represents any single character.


LISTAJFTAB Lists jobs in the Active Jobs file that were ordered from the specified
scheduling table.

ctmpsm -LISTAJFTAB <table_name>

Wildcards can used as part of the specified table name.

* represents any number of characters.

? represents any single character.

230 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmpsm

Table 70 ctmpsm - mode descriptions and syntax (part 5 of 9)


Mode Description
SCHEDTAB Lists Scheduling tables and jobs defined in the CONTROL-M/Server
database, and allows you to add or delete Scheduling tables.

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.

Wildcards can used as part of the table name for this


option.

* represents any number of characters.

? represents any single character.


-UPDATE Updates the User Daily name for a specific
Scheduling table.
-ADD Adds a User Daily to an existing table. The Table
name and User Daily name must be specified when
this option is used.
-DUDAILY Removes an instance of a scheduling table from the
CONTROL-M/Server database.

■ If the specified instance is the only instance of the


table (that is, that table is ordered by only one
user daily), the scheduling table and all its
associated jobs are deleted.
■ If the specified instance is not the only instance of
the table, then only the specified instance is
removed from the CONTROL-M/Server
database.
-REMOVE Deletes a specific Scheduling table and its associated
jobs.
-LISTJOBS Lists jobs in a Scheduling table.

Chapter 3 Utilities 231


ctmpsm

Table 70 ctmpsm - mode descriptions and syntax (part 6 of 9)


Mode Description
LISTSYSOUT List the SYSOUTs for an order ID. The list can be restricted by runcount
number.

ctmpsm -LISTSYSOUT <order_ID> [SYSOUTNUMBER


{<number>|ALL}]
order_ID Identifies the job whose SYSOUTs are listed.
number Restricts the list to the SYSOUT whose runcount is
specified.

If ALL is specified, the output will contain only a list


of all SYSOUTs related to the specified order ID.
LISTDETAILS Lists the details of the job associated with the specified order ID.

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>

232 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmpsm

Table 70 ctmpsm - mode descriptions and syntax (part 7 of 9)


Mode Description
UPDATEAJF Performs a specified command or updates conditions for a job in the
Active Jobs file that is associated with a specified order ID.

ctmpsm -UPDATEAJF <order_ID> <command>

command is one of the following:

■ HOLD _ Set the status of a job to HELD.

■ FREE _ Free a previously held job.

■ DELETE _ Mark a job for deletion.


Note: Jobs with Executing or Submitted status cannot be deleted.

■ UNDELETE _ Undelete a job marked for deletion.

■ RERUN _ Rerun a job.

■ CONFIRM _ Confirm submission of a job.

■ FORCEOK _ Force the status a job to be OK.


Note: FORECEOK can only be applied to inactive jobs (that is, jobs
that are not running).

■ STATISTICS – Display a job’s statistics.

■ CONDADDIN <cond> <date> <AND|OR> _ Add the specified IN


condition with the specified date reference. You can include one or
more additional IN conditions by using the AND or OR conjunctional
parameter.

■ CONDADDOUT <cond> <date> <+|-> _ Add the specified OUT


condition with the specified date reference. Use + to indicate that the
condition must be present. Use - to indicate that the condition must
not be present.

■ CONDDELIN <cond> _ Delete the specified IN condition.

■ CONDDELOUT <cond> _ Delete the specified OUT condition.

Note: Conditions specified using this mode apply only to the specified
instance of the job in the Active Jobs file. Subsequent orders of that job are
not affected.

Chapter 3 Utilities 233


ctmpsm

Table 70 ctmpsm - mode descriptions and syntax (part 8 of 9)


Mode Description
UPDATEGROUP Applies a specified command to jobs in the specified group that are
associated with the specified application.

ctmpsm -UPDATEGROUP <application> <group> <command>

<command> is one of the following:

■ HOLD _ Set the status of a job to HELD.


■ FREE _ Free previously held jobs.
■ DELETE _ Mark the jobs for deletion.
■ UNDELETE _ Undelete the jobs marked for deletion.
■ CONFIRM _ Confirm submission of the jobs.
UPDATETABLE Applies a specified command to jobs in the Active Jobs file that were
ordered from the specified table.

ctmpsm -UPDATETABLE <table> <command>

command is one of the following:

■ HOLD _ Set the status of a job to HELD.


■ FREE _ Free previously held jobs.
■ DELETE _ Mark the jobs for deletion.
■ UNDELETE _ Undelete the jobs marked for deletion.
■ RERUN _ Rerun the jobs.
■ CONFIRM _ Confirm submission of the jobs.

234 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmpsm

Table 70 ctmpsm - mode descriptions and syntax (part 9 of 9)


Mode Description
XML Lists jobs in the Active Jobs file in XML format. The list can be filtered by
order date, time, application, and member name. The list can be sorted by
order ID or job name.

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:

ODAT – Order date.

TIME _ Time execution started and ended.

APPLICATION _ Application to which the job belongs.

MEMNAME _ Member name for the job.

ALL – Includes ODAT and TIME fields.

ALLFIELDS – Includes ODAT, MEMNAME, and APPLICATION fields.

In addition, you can specify the following:

–SORT indicates the order in which the jobs should be listed.


Valid values: ORDERID and JOBNAME.

Example 1
To filter the list of jobs in the Active Jobs file according to the member
name of the job, specify the following:

ctmpsm -XML MEMNAME

Example 2
To sort the list in Example 1 above according to job name, specify the
following:

ctmpsm -XML MEMNAME -SORT JOBNAME

Chapter 3 Utilities 235


ctmreindex

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.

The CONTROL-M/Server Sybase database must be running so that the required


index operations can be performed. However, this utility should be run only when
database activity is low.

This utility enables CONTROL-M/Server database queries to execute faster by


ensuring that indexes are well-balanced. For more information about indexes, refer to
Sybase manuals.

To invoke the ctmreindex utility, specify the following command

ctmreindex

Example

The following command causes the ctmreindex utility to reorganize indexes in the
CONTROL-M/Server Sybase database:

ctmreindex

236 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmrpln

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.

Each report can be created in one of the following formats:

Table 71 ctmrpln – report formats


Format Description
Daily Report Displays jobs in the specified Scheduling table that are scheduled to
run on a specific day. Each job’s Mem Name (or Job Name), Group,
and Description parameters are displayed.
Monthly Report Displays a table of all days in a specified month and marks (with an
asterisk “*”) the days of the month on which jobs in the specified
Scheduling table are scheduled to run. Jobs can be identified either by
their Mem Name or Job Name parameters.
Yearly Report Displays the year, the two years before, and the two years after the
year specified in the <Date> parameter. Marks each day with various
characters (described in the next table) that indicate if jobs in the
specified Scheduling tables are scheduled to run.

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:

ctmrpln <Report_type> <Calendar> <Schedtab> <Jobname> <Date> [<Output>]

Chapter 3 Utilities 237


ctmrpln

Table 72 ctmrpln parameters


Parameter Description
<Report_type> Specify one of the following values:
DM (or D) Creates a daily report, identifying each job according
to its Mem Name parameter.
DJ Creates a daily report, identifying each job according
to its Job Name parameter.
MM (or M) Creates a monthly report, identifying each job
according to its Mem Name parameter.
MJ Creates a monthly report, identifying each job by its
Job Name parameter.
Y Creates a yearly report.
<Calendar> Specify one of the following values:
Y Creates the report using the calendar specified in the
job’s scheduling parameters.
N Creates the report ignoring the calendar specified in
the job’s scheduling parameters.
<Name> Creates the report using a calendar you specify
(ignoring calendars specified in the job scheduling
parameters). Use this option to see how another
calendar affects scheduling.
<Schedtab> Name of the Scheduling table on which to base the report. The
Scheduling table name can include the following mask characters:
* represents any number of characters (including no characters).
Specify * by itself to include all Scheduling tables. Any parameter
including * should be enclosed in quotation marks.
? represents any single character.
<Jobname> Job Name of the jobs to include in the report. The Job Name can
include mask characters (see <Schedtab> above). Specify * by itself
to include all jobs in the Scheduling table.
<Date> Date for the report:

■ For daily reports: A date in yyyymmdd format.

■ For monthly reports: A month in yyyymm format.

■ For yearly reports: A year in yyyy or yy format.

Note: The ctmrpln utility supports 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.

238 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmrpln

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.

ctmrpln D work_days PROD1 "jn*" 20020101

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.

ctmrpln M work_days PROD1 PRDJ02 200204 lp1

Example 3

The following command causes the utility to generate a five-year report


encompassing the period Jan. 2001 through Dec. 2005. This indicates on which days
each job in Scheduling table PROD1 runs, based on the calendar work_days. The
output is directed to printer lp1.

ctmrpln Y work_days PROD1 "*" 2003 lp1

Chapter 3 Utilities 239


ctmruninf

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.

Specify one of the following commands to invoke the ctmruninf utility:

ctmruninf -list <fromDate> <toDate> [<filter>] [-total]


ctmruninf -list "*" [<filter>] [-total]
ctmruninf -delete <fromDate> <toDate>
ctmruninf -PURGE
Table 73 ctmruninf parameters (part 1 of 2)
Parameter Description
-list Displays data from the Statistical Details table within the dates
specified in the From Date and To Date parameters. The data listed
can be limited by using the Filter subparameter (described in this
table).
-delete Deletes data from the Statistical Details table in the range specified in
the From Date and To Date parameters.
<From Date> Start date of statistical data to be displayed or deleted. Format:
yyyymmddhhmmss
<To Date> End date of statistical data to be displayed or deleted. Format:
yyyymmddhhmmss
“*” Asterisk enclosed in quotation marks. Specifies that the utility should
list all statistical data currently available, without regard to date.

240 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmruninf

Table 73 ctmruninf parameters (part 2 of 2)


Parameter Description
<Filter> Specify one of the following options and its associated subparameter
or leave blank to display the statistics for all jobs in the range.

■ -JOBNAME <jobname>
Identify the job by 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:

* represents any number of characters (including none). Any


parameter including * should be enclosed in quotation marks (see
Example 3 below).

? represents any single character


-total Displays the total CPU and elapsed times for the jobs selected.
-PURGE Purge data from the Statistical Details table based on the number of
job executions.

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

The Statistics algorithm (JOBNAME or MEMNAME) and the


RUNINF_PURGE_LIMIT parameter are taken from the config.dat
table, if configured.

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.

Chapter 3 Utilities 241


ctmruninf

Example 1

The following command displays runtime data for the period January 21, 2002
through January 25, 2002 (assuming that this data is available):

ctmruninf -list 20020121000000 20020125235959

Example 2

The following command deletes the statistical data for January 31, 2002:

ctmruninf -delete 20020131000000 20020131235959

Example 3

The following command causes the utility to display and total runtime data for all
jobs on agent computer diana.

ctmruninf -list "*" -NODEID "diana" -total

A report similar to the following is displayed:

TIMESTAMP JOBNAME ORDERID RUN# NODEID MEMNAME MEMLIB CPU ELAPSED


------------- ---------- -------- ---- ------------ ---------- -------------- ----- -------
2000012160524 acct12 00000007 1 diana pgmacct prod.acct.pgm 0.19 233.15
2000012161205 gen786 0000000b 1 diana genx prod.general 0.12 6.12
2000012162311 acct14 00000011 1 diana pgmacct prod.acct.pgm 0.05 170.45
2000012164512 acct15 00000012 1 diana pgmacct prod.acct.pgm 0.14 145.23
------------- ---------- -------- ---- ------------ ---------- -------------- ----- -------
Total records printed : 4 0.50 555.35

242 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsec

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.

The ctmsec utility is used to:

■ add, delete, or modify specific users in the CONTROL-M Security database


■ add, delete, or modify specific groups in the CONTROL-M Security database
■ assign authorizations to a user or group to perform actions on a Scheduling table
■ assigns authorizations to a user or group to perform actions relating to
CONTROL-M entities

The following topics are discussed in this section:

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

■ Accessing a Scheduling table (to add, delete, or modify a job definition).

■ Ordering a job.

■ Selecting and submitting a job.

■ Commands affecting jobs in the Active Jobs file (for example, Hold, Confirm,
Rerun).

■ Maintenance of CONTROL-M entities (for example, calendars, prerequisite


conditions).

Chapter 3 Utilities 243


ctmsec

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.

Level of application security

CONTROL-M provides the following levels of application security for users not
explicitly defined in the CONTROL-M Security database:

Table 74 Security levels


Security level Description
Restricted A user not defined in the CONTROL-M Security database is
regarded as having no authorizations and cannot perform any
function requiring security authorization.
Unrestricted A user not defined in the CONTROL-M Security database is
regarded as having all CONTROL-M application authorizations.

Regardless of which level is implemented:

■ A user, for whom one or more authorizations have been assigned in the Security
database, can only perform those actions.

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

Encryption and compression

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.

244 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsec

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

Security maintenance utility (Interactive mode)


The ctmsec CONTROL-M Security Maintenance utility defines users in the
CONTROL-M Security database and assigns authorizations required for working
with CONTROL-M using the CONTROL-M Configuration Manager. ctmsec runs on
the CONTROL-M/Server computer.

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.

When assigning a user to a group, the following rules apply:

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

■ If all of a user’s authorizations for a specific CONTROL-M element (for example,


Scheduling Table) are defined with a (D)efault setting, the user’s authorizations for
that element can be deleted more efficiently.

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

Chapter 3 Utilities 245


ctmsec

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.

To display the CONTROL-M Security Maintenance utility

1 Log on to the CONTROL-M/Server computer as the CONTROL-M/Server owner


(for example, user controlm).

2 Specify the command ctmsec.

-or-

Choose Security Authorization => Security Maintenance Utility from the


CONTROL-M/Server Main Menu. See “Opening CONTROL-M Main Menu” on
page 322.

Figure 12 Security Maintenance Menu


+-----------------------------------------------+
| CONTROL-M SECURITY MAINTENANCE UTILITY |
| Main Menu |
+-----------------------------------------------+
1) User Maintenance
2) Group Maintenance
3) Scheduling Table Authorization
4) Active Jobs File Authorization
5) Entities Authorization
q) Quit
Enter option:

Each of these options is described below.

User maintenance

The User Maintenance option of the ctmsec utility is used to add, delete, or modify
specific users in the CONTROL-M Security database.

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

246 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsec

Select Option 1 from the Security Maintenance Main Menu. The User Maintenance
menu is displayed.

Figure 13 User Maintenance Menu


User Maintenance Menu
---------------------
1) List Users
2) Add User
3) Delete User
4) Modify User Information
5) Copy User
q) Quit

Enter option:

To list existing users in the CONTROL-M Security database

Select Option 1 from the User Maintenance menu.

A list similar to the following is displayed:

Name Description Group


GCSERV For passing Global conds. Group1
User1 Group2

Press ENTER to continue:

Press <Enter> to return to the User Maintenance menu.

To add a new user to the CONTROL-M Security database

1. Select Option 2 from the User Maintenance menu.

A prompt similar to the following is displayed:

User []:

2. Specify the user name of the CONTROL-M/EM user (maximum 30 characters,


case-sensitive).

A prompt similar to the following is displayed:

User ‘User2’ is not defined in the CONTROL-M Security


database.
Add this user now [Y/N]?

3. Enter Y to add the new user.

Chapter 3 Utilities 247


ctmsec

The following prompts are displayed:

Description []:
Group []:

4. Specify a value for Description (maximum length: 50 characters) or press <Enter>.

This field is optional and is for documentation purposes only.

5. Specify a value for Group (maximum length: 32 characters) or press <Enter>.

This field is optional. If specified, the user inherits all authorizations defined for
the group that are not specifically defined for the user.

6. Press <Enter> to return to the User Maintenance menu.

To delete an existing user from the CONTROL-M Security database

1. Select Option 3 from the User Maintenance menu.

A prompt similar to the following is displayed:

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.

To modify the Description or Group fields for an existing user

1. Select Option 4 from the User Maintenance menu.

A prompt similar to the following is displayed:

User []:

2. Specify the user name of the CONTROL-M/EM user to modify.

A user definition similar to the following is displayed:

User: User1
-----------------------
Modify User Information
1) Description :
2) Group :
s) Save and return to menu

248 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsec

c) Cancel and return to menu


Enter command, or specify item number to modify:

3. To modify a field, type the number preceding the field.

You are prompted to supply a value for the field.

■ Maximum length for Description is 50 characters. The Description field is for


documentation purposes only

■ Maximum length for Group is 32 characters.

4. Type s to save your changes and return to the previous menu. Modifications are
not saved until you perform this action.

-or-

Type c to cancel all changes and return to the previous menu.

To copy an existing user

1. Select Option 5 from the User Maintenance menu.

The following prompt is displayed:

FROM user:

2. Specify the exact name of the user to be copied.

The following prompt is displayed:

TO user:

3. Specify a new user name for the CONTROL-M/EM user (maximum 30 characters,
case-sensitive).

A prompt similar to the following is displayed:

User ‘User2’ is not defined in the CONTROL-M Security


database.
Add this user now [Y/N]?

4. Enter Y to add the new user. The following prompt is displayed:

Description []:

Chapter 3 Utilities 249


ctmsec

5. Specify a value for Description (maximum length 50 characters). This field is


optional and is for documentation purposes only.

The following prompt is displayed:

Group []:

6. Specify a value for Group (maximum length 32 characters).

This field is optional. If specified, the user inherits all authorizations defined for
the group that are not specifically defined for the user.

7. Press <Enter> to return to the User Maintenance menu.

Group maintenance

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

Figure 14 Group Maintenance Menu


Group Maintenance Menu
-----------------------
1) List Groups
2) Add Group
3) Delete Group
4) Modify Group Information
q) Quit
Enter option:

To list existing groups in the CONTROL-M Security database

1. Select Option 1 from the Group Maintenance menu.

A list similar to the following is displayed:

Group Description
Group1 CONTROL-M Group
Group2
Press ENTER to continue:

2. Press <Enter> to return to the Group Maintenance menu.

250 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsec

To add a new group to the CONTROL-M Security database

1. Select Option 2 from the Group Maintenance menu. The following prompt is
displayed:

Groupname []:

2. Specify the Group name (maximum length 32 characters).

This name must be unique. It cannot be an existing user or group name. The
following prompt is displayed:

Description []:

3. Specify a Description (maximum length 50 characters) or press <Enter>. The


Description field is optional and is for documentation purposes only. The group is
added to the Security database, and the Group Maintenance menu is displayed.

To delete an existing group from the CONTROL-M Security database

1. Select Option 3 from the Group Maintenance menu. A prompt similar to the
following is displayed:

Group [Group1]:

2. Specify the name of the group to delete. After confirmation, the group is deleted
from the Security database, and the Group Maintenance menu is displayed.

To modify the Description field for an existing group

1. Select Option 4 from the Group Maintenance menu. A prompt similar to the
following is displayed:

Group name []:

2. Specify the name of the group to modify.

A group definition 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

Enter command, or specify item number to modify:

Chapter 3 Utilities 251


ctmsec

3. To modify the Description field, type 1.

You are prompted to supply a value for the field (maximum length 50 characters).
This field is optional and is for documentation purposes only.

4. Type s to save your changes and return to the previous menu. Modifications are
not saved until you perform this action.

-or-

Type c to cancel all changes and return to the previous menu.

Scheduling table authorization

This option is used to assign authorizations to a user or group to perform actions on a


Scheduling table.

For more information about the types of authorization that can be granted using this
option, see “Scheduling table authorization option” on page 262.

To maintain Scheduling Table authorizations

1. Select Option 3 from the Main Menu. A prompt similar to the following is
displayed:

+--------------------------------------+
| SCHEDULING TABLE AUTHORIZATION |
+--------------------------------------+

User/Group [User1]:

2. Specify the user or group for whom you are defining authorizations.

If the user or group is not defined in the CONTROL-M Security database, the
following message is displayed:

User/Group ‘name’ is not defined in the CONTROL-M Security


database.

Press ENTER to continue:

3. Press <Enter> to return to the Main Menu. The Scheduling Table Authorization
menu is displayed:

252 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsec

Figure 15 Scheduling Table Authorization Menu


Scheduling Table Authorization Menu
-----------------------------------
1) List Tables
2) Create/Modify Table Authorization
3) Delete Table Authorization

q) Quit

Enter option:

To list existing Scheduling Table authorizations for the specified user/group

Select Option 1 from the Scheduling Table Authorization menu.

A list similar to the following is displayed:

List for user: User1


Table Delete Read Update OrderTable
Sched1 N N N N
Sched2 N Y Y Y
Press ENTER to continue:

Press <Enter> to return to the Scheduling Table Authorization menu.

To create or modify Scheduling Table authorizations for the specified


user/group

1. Select Option 2 from the Scheduling Table Authorization menu. The following
prompt is displayed:

Table Name:

2. Specify the name of a Scheduling table (maximum 20 characters, case-sensitive).


The Scheduling table does not have to exist at the time you specify authorizations
for it.

A table definition similar to the following is displayed:

Scheduling Table Name: Sched1, User/Group: User1


Create/Modify Table Authorization
---------------------------------
1) Delete :N
2) Read :N
3) Update :N
4) OrderTable :N

s) Save and return to menu

Chapter 3 Utilities 253


ctmsec

c) Cancel and return to menu

Enter command, or specify item number to toggle Y/N/D:

The Y setting enables authorization for the action (for example, Read), N disables the
authorization, and (D)efault uses the authorization defined for the user’s group. If the
user was previously authorized for this scheduling table, the user’s current
authorizations are displayed; otherwise, all authorizations are set to N.

3. To modify an authorization, type the number preceding the authorization and


press <Enter>. (You may need to do this more than once in order to achieve the
desired authorization.)

Type s to save your changes and return to the previous menu. Modifications are
not saved until you perform this action.

-or-

Type c to cancel all changes and return to the previous menu.

To delete Scheduling Table authorizations for the specified user/group

1. Select Option 3 from the Scheduling Table Authorization menu. The following
prompt is displayed:

Table Name:

2. Specify the name of the Scheduling table whose authorizations you want to delete
for this user or group (or press <Enter> to return to the menu).

The user’s authorizations for this table are deleted from the Security database, and
the Scheduling Table Authorizations menu is displayed. If the user belongs to a
group, authorizations for the Scheduling Table revert to the authorizations defined
for the group.

Active Jobs file authorization option

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.

254 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsec

To maintain Active Jobs File authorizations

1. Select Option 4 from the Main Menu.

A prompt similar to the following is displayed:

+--------------------------------------+
| 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:

User/Group ‘name’ is not defined in the CONTROL-M Security


database.
Press ENTER to continue:

2. Press <Enter> to return to the Main Menu. The Active Jobs File Authorization
menu is displayed:

Figure 16 Active Jobs File Authorization Menu


Active Jobs File Authorization Menu
-----------------------------------
1) List Owner Names
2) Create/Modify AJF Authorization
3) Delete AJF Authorization

q) Quit

Enter option:

To list owners for whom the user has Active Jobs File authorizations

Select Option 1 from the Active Jobs File Authorization menu.

A list similar to the following is displayed:

List for user: User1

Owner Node Group Hold Force Del Rerun Log Why Statist Sysout Order Conf Z&S Kill
----- ---------- ---- ----- --- ----- --- --- ------- ------ ----- ---- --- ----
Owner1 Node1 N Y Y Y N N N N Y N N Y
Owner2 Node2 Y Y Y Y Y Y Y Y Y Y N N

Press ENTER to continue:

Chapter 3 Utilities 255


ctmsec

To create or modify Active Jobs File authorizations for the specified user

1. Select Option 2 from the Active Jobs File Authorization menu.The following
prompt is displayed:

Owner:

2. Specify the name of a job owner.

The following prompt is displayed:

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.

A list similar to the following is displayed:

Owner: Owner1, Node Group: Node1 User/Group: User1

Create/Modify Active Jobs File Authorization


--------------------------------------------

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

Enter command, or specify item number to toggle Y/N/D:

The Y setting enables authorization for the action (for example, Read), N disables
the authorization, and (D)efault uses the authorization defined for the user’s
group. If the user was previous authorized for this owner and node, the user’s
current authorizations are displayed; otherwise, all authorizations are set to N.

256 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsec

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.

4. To modify an authorization, type the number preceding the authorization and


press <Enter> (you may need to do this more than once in order to achieve the
desired authorization).

5. Type s to save your changes and return to the previous menu.

-or-

Type c to cancel all changes and return to the previous menu.

To delete Active Jobs File authorizations for the specified user

1. Select Option 3 from the Active Jobs File Authorization menu.

The following prompt is displayed:

Owner:

2. Specify the name of the Job owner for whom authorizations should be deleted (or
press <Enter> to return to the menu).

The following prompt is displayed

Node Group:

3. Specify the name of the Node group of the Job owner for whom authorizations
should be deleted (or press <Enter> to return to the menu).

The user authorizations for this owner on the Node group are deleted from the
Security database, and the Active Jobs File Authorization menu is displayed.

Entities authorization

This option assigns authorizations to a user or group to perform actions relating to


CONTROL-M entities.

For more information about the types of authorization that can be granted using this
option, see “Entities authorization options” on page 263.

Chapter 3 Utilities 257


ctmsec

To maintain Entities authorizations

1. Select Option 5 from the Main Menu.

A prompt similar to the following is displayed:

+----------------------------------------+
| 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:

User ‘name’ is not defined in the CONTROL-M Security


database
Press ENTER to continue:

Press <Enter> to return to the Main Menu.

■ If the user or group name is defined the Entities Authorizations menu is


displayed:

Figure 17 Entities Authorizations Menu


Entities Authorizations Menu
----------------------------
1) List Entity Categories
2) Create/Modify Entity Authorizations
3) Delete Entity Category

q) Quit

Enter option:

To list Entity categories for which the user or group has authorizations

1. Select Option 1 from the Entities Authorizations menu.

A list similar to the following is displayed:

List for user: User1


Category Add Delete Change
CALENDAR Y N Y
QUANTITATIVE RESOURCE Y N N
CONTROL RESOURCE Y N N
Press ENTER to continue:

258 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsec

2. Press <Enter> to return to the Entities Authorizations menu.

To create or modify Entity authorizations for the specified user or group

1. Select Option 2 from the Entities Authorizations menu. The following menu is
displayed:

Categories
----------
1) 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:

Category: CALENDAR, User: User1

Create/Change Entity Authorizations


-----------------------------------
1) Add :Y
2) Delete :N
3) Change :N
s) Save and return to menu
c) Cancel and return to menu

Enter command, or specify item number to toggle Y/N/D:

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.

3. To modify an authorization, type the number preceding the authorization and


press <Enter> (you may need to do this more than once in order to achieve the
desired authorization).

4. Type s to save your changes and return to the previous menu. Modifications are
not saved until you perform this action.

-or-

Type c to cancel all changes and return to the previous menu.

Chapter 3 Utilities 259


ctmsec

To delete Entity authorizations for the specified user or group

1. Select Option 3 from the Entities Authorizations menu. The following menu is
displayed:

Categories
----------
1) 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.

260 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsec

Security maintenance utility (Batch mode)


Certain ctmsec Security Maintenance utility functions can be activated in batch mode.
These functions include listing, updating, and deleting entries in the CONTROL-M
Security database. These functions are described in “Security maintenance utility
(Interactive mode)” on page 245.

User authorization

The user authorization options of the ctmsec command are used to list, update,
delete, and copy users in the CONTROL-M Security database.

■ Use the following command to list user authorizations:


ctmsec -USER_LIST <user>

■ Use the following command to update user authorizations:


ctmsec -USER_UPDATE <user> <description> <group>

■ Use the following command to delete user authorizations:


ctmsec -USER_DELETE <user>

■ Use the following command to copy user authorizations from one user to another:
ctmsec -USER_COPY <from_user> <to_user>

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.

■ Use the following command to list group authorizations:


ctmsec -GROUP_LIST <group>

■ Use the following command to update group authorizations:


ctmsec -GROUP_UPDATE <group> <description>

■ Use the following command to delete group authorizations:


ctmsec -GROUP_DELETE <group>

Chapter 3 Utilities 261


ctmsec

Scheduling table authorization option

The Scheduling table authorization options of the ctmsec command are used to
assign authorizations to users and groups to perform actions on Scheduling tables.

■ Use the following command to list Scheduling table authorizations:


ctmsec -SCHED_LIST {<user>|<group>}

■ Use the following command to update Scheduling table authorizations:


ctmsec -SCHED_UPDATE {<user>|<group>} <table>
[-DELETE {Y|N|D}] [ -READ {Y|N|D}]
[ -ORDER {Y|N|D}] [ -UPDATE {Y|N|D}]

■ Use the following command to delete Scheduling table authorizations:


ctmsec -SCHED_DELETE {<user>|<group>} <table>

NOTE
If the user in the commands listed above is a CONTROL-M/Agent user, then the <user>
format is <username@node_id>.

Active Jobs file authorization

The Active Jobs File authorization options of the ctmsec command are used to assign
authorizations to users and groups to perform actions on jobs in the Active Jobs file.

■ Use the following command to list Active Jobs File authorizations:


ctmsec -ACT_LIST {<user>|<group>}

■ Use the following command to update Active Jobs File authorizations:

ctmsec -ACT_UPDATE {<user>|<group>} <owner> <node>


[-HOLD {Y|N|D}]
[-FORCE {Y|N|D}]
[-ORDER {Y|N|D}]
[-CONFIRM {Y|N|D}]
[-DELETE {Y|N|D}]
[-WHY {Y|N|D}]
[-RERUN {Y|N|D}]
[-SYSOUT {Y|N|D}]
[-LOG {Y|N|D}]
[-STATISTICS {Y|N|D}]
[-ZOOM_AND_SAVE {Y|N|D}]
[-KILL_JOB {Y|N|D}]

■ Use the following command to delete Active Jobs File authorizations:


ctmsec -ACT_DELETE {<user>|<group>} <owner> <node>

262 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsec

NOTE
If the user in the commands listed above is a CONTROL-M/Agent user, then the <user>
format is <username@node_id>.

Entities authorization options

The entity authorization options of the ctmsec command are used to assign
authorizations to users and groups to perform actions relating to CONTROL-M
entities.

■ Use the following command to list entity authorizations:


ctmsec -ENTITY_LIST {<user>|<group>}

■ Use the following command to update entity authorizations:


ctmsec -ENTITY_UPDATE {<user>|<group>}
{LOG|QR|CONTROL|CALENDAR|CONDITION}
[-ADD {Y|N|D}] [-DELETE {Y|N|D}] [-CHANGE {Y|N|D}]

■ Use the following command to delete entity authorizations:


ctmsec -ENTITY_DELETE {<user>|<group>}
{LOG|QR|CONTROL|CALENDAR|CONDITION}

NOTE
If the user in the commands listed above is a CONTROL-M/Agent user, then the <user>
format is <username@node_id>.

Exporting security definition tables


The EXPORT option of the ctmsec command is used to export CONTROL-M Security
Definition tables. The file that is generated by the ctmsec command is an executable
file containing API functions that will redefine all the security entries when the script
is run. The generated file can be modified and imported to any CONTROL-M
installation.

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.

Chapter 3 Utilities 263


ctmsec

Use the following command to export CONTROL-M Security Definition tables:

ctmsec -EXPORT <filename>

<filename> is the full path name of the file to be exported.

Example

ctmsec -EXPORT /home/controlm/securedata

Importing security definition tables


The file created using the -EXPORT option of the ctmsec utility contains multiple
ctmsec commands that describe the various security definitions in your
CONTROL-M installation. If necessary, these ctmsec commands can be modified
before the security definitions are imported back to the same or a different
CONTROL-M installation.

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.

To import security definitions

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.

264 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsetown

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.

Specify one of the following commands to invoke the ctmsetown utility:

■ ctmsetown -action add -owner <userName> -host <hostName>


[-password <password> | -encpassword <encryptedPassword> | -keyname <keyName>
[-passphrase <keyPassphrase> | -encpassphrase <encryptedKeyPassphrase>]]

■ ctmsetown -action update -owner <userName> -host <hostName> [-password


<password> | -encpassword <encryptedPassword> | -keyname <keyName >
[-passphrase <keyPassphrase> | -encpassphrase <encryptedKeyPassphrase>]]

■ ctmsetown -action delete -owner <userName> -host <hostName>

■ ctmsetown -action list [-owner <userName>] [-host <hostName>]

■ ctmsetown -action export -filename <exportFileName>

■ ctmsetown -action import -filename <importFileName> -data append|truncate

■ ctmsetown help

Table 75 describes the actions in the ctmsetown utility.

Table 75 ctmsetown actions (part 1 of 2)


Action Description
add Specifies the security details of a new owner entry (user).
update Modifies the security details of an existing owner entry (user).
delete Removes the security details of an owner entry. The owner name and host
name must match an existing entry in the table.
list Lists the details of the user.
Wildcards can be used to specify -owner and -host parameters, as follows:
■ * represents any number of characters
■ ? represents any single character

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

Chapter 3 Utilities 265


ctmsetown

Table 75 ctmsetown actions (part 2 of 2)


Action Description
import Imports the details of the users stored in the specified import file.
help Displays the usage of the ctmsetown utility.

Table 76 describes the parameters in this utility.

Table 76 ctmsetown parameters


Parameter Description
-owner Specifies the name of the user under whose name the job will run.
-host Specifies the name of the computer where the owner of the job is defined.
Specify <All> to include all hosts.

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.

If -keyname is specified, then specify one of the following parameters:


-passphrase Phrase used as a key to encrypt the key itself.
-encpassphrase The encrypted phrase used as a key to encrypt the key
itself. The encpassphrase cannot exceed 512 characters.
The value must be divisible by 4 without a remainder.
-filename Specifies the name of the file that contains the security details of the users.
The filename cannot exceed 1024 characters.

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

266 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsetown

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:

ctmsetown -action add -owner username1 -host saturn -password pass01

The following message is displayed:

Entry created successfully.

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”

The following message is displayed:

Entry created successfully.

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:

ctmsetown -action update -owner username1 -host saturn -password newpass

The following message is displayed:

Entry updated successfully.

Example 4
To delete the user entry created in Example 1, specify the following command:

ctmsetown -action delete -owner username1 -host saturn

The following message is displayed:

Entry deleted successfully.

Chapter 3 Utilities 267


ctmsetown

Example 5
To list the security details of user entries, specify the following command:

ctmsetown -action list

Owner Host Password/Key Flag Key value


----- ---- ----------------- ---------
jupiter saturn Key Key1
jupiter venus Password Not Applicable

2 entries were found.

Example 6
To create an export text file containing a list of security details of user entries, specify
the following command:

ctmsetown -action export -filename /home/ctm630oe/sec.exp

The following is displayed:

Exporting data, please wait...

Export ended successfully.

Check report file


~<controlm_owner>/ctm_server/proclog/export_report_53d1.txt' for
details.

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:

ctmsetown -action import -filename /home/ctm630oe/sec.exp -data truncate

The following is displayed:

Importing data, please wait...

Import ended successfully.


Check report file
~<controlm_owner>/ctm_server/proclog/import_report_53d9.txt' for
details.

268 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsetown

Chapter 3 Utilities 269


ctmshout

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.

Specify the following command to invoke the ctmshout utility:

ctmshout
-USER <username> or -DEST <destinationName>
-MESSAGE "<messageText>"
[ -ORDERID <orderID>]
[ -NODEID <nodeID>]
[ -SEVERITY <severityLevel>]

-or-

ctmshout -input_file <fullPathFileName>

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.

Table 77 ctmshout parameters (part 1 of 2)


Parameter Description
<username> User ID that should receive the message. DEST and USER can be
specified in the same ctmshout command.
<destinationName> Logical destination device name or a valid destination name in the
Shout Destination table. DEST and USER can be specified in the same
ctmshout command.
<message> Free text to be sent to the destination (1 - 255 characters). If the text is
more than one word, it must be enclosed in quotation marks.
<orderID> Order ID of a job, as displayed in the Job Details window in
CONTROL-M/EM. Associates the message with a specific job in the
Active Network.
<nodeID> Node ID of the agent computer. Used for messages whose destination
is either a user in the data center or a user defined in the Shout
Destination table.
Note: If -ORDERID is also specified, this Node_ID overrides the Node
ID specified in the job with that Order ID.

270 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmshout

Table 77 ctmshout parameters (part 2 of 2)


Parameter Description
<severityLevel> One letter character indicating the urgency of the message. Valid
values:

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:

■ prepare and save files of utility parameters that can be reused.

■ specify utility input longer than the number of characters allowed


in the command line.

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:

ctmshout -ORDERID 1234 -USER EM \


-MESSAGE "File not found" -SEVERITY V

You can get the same result using the -input_file parameter as follows:

ctmshout -input_file ~<controlm_owner>/ctm_server/data/ctmshout_payroll.txt

The referenced file contains the following lines:

-ORDERID 1234
-USER EM
-MESSAGE "File not found"
-SEVERITY V

Chapter 3 Utilities 271


ctmshout

Example 2

The following command sends the message “The weekly paycheck job has
abended” to user John on agent computer diana:

ctmshout -NODEID diana -USER John -MESSAGE


"The weekly paycheck job\ has abended" -SEVERITY V

Example 3

The following illustrates the use of the ctmshout utility in a job script command to
send the Shout message “Job started” to the Alerts window in 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:

ctmshout -O $1 -USER EM -MESSAGE "Job started" \


-SEVERITY R

272 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmshtb

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.

Specify the following command to invoke the ctmshtb utility:

ctmshtb <table>

The variable <table> is the new Shout Destination table name.

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

Chapter 3 Utilities 273


ctmspdiag

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.

Specify one of the following commands to invoke the ctmspdiag utility:

ctmspdiag -SET -SPNAME <storeProcedureName> -MODE <Y/N>


ctmspdiag -PRINT -SPNAME <storeProcedureName>
[-FROM_DATE<timeStamp>] [-TO_DATE <timeStamp>]
ctmspdiag -DEL -TO_DATE <timeStamp>[-SPNAME <storeProcedureName>]
ctmspdiag -SHOW [-SPNAME <storeProcedureName>]
ctmspdiag -TRUNCATE

Table 78 describes the options that the ctmspdiag utility supports.

Table 78 ctmspdiag options


Option Description
-SET Set the diagnostic request status of a specified SP in the
CONTROL-M/Server database.
■ If the diagnostic request status does not exist in the
CONTROL-M/Server database, it is created and its value is set.
■ If the diagnostic request status does exist, its value is updated.

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

Table 79 ctmspdiag parameters (part 1 of 2)


Parameter Description
-SPNAME Specifies the stored procedure name.
-MODE Specifies whether diagnostic messages from SPs should be recorded in the
CONTROL-M/Server database. The values are:

■ Y
■ N (Default)

274 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmspdiag

Table 79 ctmspdiag parameters (part 2 of 2)


Parameter Description
-FROM_DATE Start date for the date range of diagnostic messages to print. The date is in
yyyymmddhhmm format.

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.

ctmspdiag -SET -SPNAME saturn -MODE Y

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:

ctmspdiag -PRINT -SPNAME saturn -FROM_DATE 200411140001


-TO_DATE 200412200000

To print all the messages, specify the following command:

ctmspdiag -PRINT -SPNAME saturn

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.

ctmspdiag -DEL -TO_DATE 200412140830 -SPNAME saturn

Chapter 3 Utilities 275


ctmspdiag

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.

ctmspdiag -SHOW -SPNAME saturn

276 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmstats

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.

Specify one of the following commands to invoke the ctmstats utility:

ctmstats -list <fromDate> <toDate> [<filter>] [-total]


ctmstats -list "*" [<filter>] [-total]
ctmstats -delete <fromDate> <toDate>
Table 80 ctmstats parameters (part 1 of 2)
Parameter Description
-list Displays data from the Statistical Summary table within the dates
specified by the From Date and To Date parameters. The data listed
can be limited with use of the Filter sub-parameter (see below).
-delete Deletes data from the Statistical Summary table in the range specified
by the From Date and To Date parameters.
<From Date> Starting date of statistical data to be displayed/deleted. The date is
specified in yyyymmddhhmmss format.
<To Date> Ending date of statistical data to be displayed/deleted. The date is
specified in yyyymmddhhmmss format.
“∗” Asterisk enclosed in quotation marks. Specifies that the utility should
list all statistical data currently available, without regard to date.

Chapter 3 Utilities 277


ctmstats

Table 80 ctmstats parameters (part 2 of 2)


Parameter Description
<Filter> Specify one of the following options and its associated subparameter
or leave blank to display the statistics for all jobs in the range.
-JOBNAME <jobname>
Identify the job by its Job Name parameter.
-MEMNAME <memname>
Identify the job by its Mem Name parameter.
-MEMLIB <memlib>
Identify jobs by their Mem Lib parameter.
-NODEID <nodeid>
Identify jobs by their node id parameter (agent computer).
Each of the subparameters in the filter can include the following mask
characters:

* – Represents any number of characters (including no characters).


Any parameter including ∗ should be enclosed in quotation marks (see
example below).

? – Represents any single character


-total Displays a line that contains the total CPU and elapsed times for the
jobs selected.

Example 1

The following command displays statistical data for the period January 21, 2002
through January 25, 2002 (assuming that this data is available):

ctmstats -list 20020121000000 20020125235959

A report similar to the following is displayed:

TIMESTAMP JOBNAME NODEID MEMNAME MEMLIB AVG CPU AVG ELAPSED


-------------- ------ ------ ------- ------------- ------- -----------
20020122141214 acct12 diana pgmacct prod.acct.pgm 0.19 233.15
20020122032025 gen786 diana genx prod.general 0.12 6.12
20020121123111 acct14 diana pgmacct prod.acct.pgm 0.05 170.45
20020121113512 acct15 diana pgmacct prod.acct.pgm 0.14 145.23

Example 2

The following command displays statistical data for all jobs on agent computer diana:

ctmstats -list "*" -NODEID diana -total

278 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmstats

Example 3

The following command deletes the statistical data for January 31, 2002:

ctmstats -delete 20020131000000 20020131235959

Chapter 3 Utilities 279


ctmstvar

ctmstvar
The ctmstvar utility displays the current value of an AutoEdit variable or function.
Specify the following command to invoke the ctmstvar utility:

ctmstvar <orderID> <autoEditString>

Table 81 ctmstvar parameters


Variable Description
<orderID> Order ID of a job waiting in the Active Jobs file (as displayed in the
Job Details window of CONTROL-M/EM). The Order ID displayed
in CONTROL-M/EM is a base 36 number. If you want to specify the
Order ID here as a base 10 number, prefix the number with an
asterisk, and enclose it in quotation marks (for example,“*1234”).

Use “0” to indicate no specific Order ID.


<autoEditString> The AutoEdit variable or string enclosed in quotation.

[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

ctmstvar a1 ‘%%$CALCDATE %%ODATE -2’


ctmstvar 0 "%%ODATE"

For Windows

ctmstvar a1 “%%$CALCDATE %%ODATE -2”


ctmstvar 0 "%%ODATE"

280 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsuspend

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.

Specify the following command to invoke the ctmsuspend utility:

ctmsuspend {-s|-r

Table 82 cmtsuspend options


Var Description
-s Suspends CONTROL-M/Server scheduling processes. Leaves the gateway to
CONTROL-M/EM open.
-r Restores CONTROL-M/Server processes. Resumes normal operating mode.

Example

The following command causes CONTROL-M/Server scheduling processes to be


restored.

ctmsuspend -r

Chapter 3 Utilities 281


ctmsys

ctmsys
The ctmsys utility is an interactive utility for maintaining:

■ Shout Destination tables (for directing Shout messages).


■ CONTROL-M system parameters.

To invoke the ctmsys utility

1. Log on to the server computer as the CONTROL-M/Server owner (for example,


user controlm).

2. Specify the command:

ctmsys

The following menu is displayed:

+------------------------------------------------+
| CONTROL-M SYSTEM MAINTENANCE UTILITY |
| Main Menu |
+------------------------------------------------+

1) Shout Destination Tables


2) System Parameters
q) Quit

Enter option:

The options in this menu and in all other menus provided by this utility can be
selected by typing the option number or command letter and pressing Enter.

Each option appearing in the Main Menu is described below.

Shout destination tables


Shout Destination tables associate logical output destinations (specified in Shout and
Do Shout statements in job processing definitions) with physical destination names.
See “Shout facility” on page 47, for more information.

To access the shout destination tables menu

Select Option 1 from the Main Menu.

The following menu is displayed:

282 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsys

Shout Destination Tables Menu


-----------------------------
Active Shout Destination Table: <table_name>

1) Create/Modify a Table
2) Set Active Table
3) List Tables
4) Delete Table
q) Quit and return to main menu

Enter option:

The name of the currently-active Shout Destination table is displayed in the


<table_name> field on the menu.

To create or modify a shout destination table

1 Select Option 1 from the Shout Destination Tables menu.

A list of available tables, similar to the following, is displayed:

Shout Destination Tables


------------------------
SYSTEM
NIGHT_SHIFT

Table to create/modify or 'q' to quit [SYSTEM]:

2 Specify the name of the table to be created or modified (or press <Enter> to accept
the default).

If the name you specify is not the name of an existing Shout Destination table, a
new table will be created with the specified name.

A display similar to the following is displayed. For an existing table, the display
lists the defined destinations.

Shout Destination Table 'SYSTEM'


--------------------------------

# Destination Type Addr Logical Name Physical Name


- ---------------- ---- ------------ -------------
1 E S EM
2 T S Term_B $TTB.#B

q) Quit e#) Edit entry # n) New entry d#) Delete entry #

Enter option:

Chapter 3 Utilities 283


ctmsys

The following fields are displayed in the table:

Table 83 Fields of the Shout Destination table


Item Description
# Entry number in the table.
Destination Type One-letter code indicating the type of recipient:
U—Specific user. If the user is not logged onto the data center when
the Shout message is sent, the message is placed in the user’s mail.
M – User’s mail.
T – Destination is a specific terminal or file known to the operating
system from which the shout was invoked.
O – System console.
L – CONTROL-M/Server log.
E – Alert window of CONTROL-M/EM.
P – Sends the shout message to a specific program.
Addr One-letter code indicating whether the destination is on the server
(S) or agent (A) computer.
Logical Name Name used in the Shout or Do Shout parameter of the job
processing definition to identify the recipient of the Shout message.
Physical Name For Destination Type U, name of a user in the data center.

For Destination Type M, e-mail address of the user (for example,


username@xxx.zzz).

For Destination Type T, terminal ID or full path name (max. 96


characters) of a file. If the file exists, the message will be appended
to the end of the file.

For Destination Type P, the full path name of the program


file/script that will perform the Shout operation.

For Destination Types O, L, and E, no physical name is specified


because each of these is a unique destination.

To create a new entry in the table

1 Specify n.

The following prompts appear:

Dest. Type: (U)ser (M)ail (T)erminal c(O)nsole (L)og


(P)rogram CONTROL-M/(E)M:

2 Specify the letter corresponding to the desired destination type.

The following prompt is displayed:

284 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsys

Address Type (S)erver or (A)gent:

3 For Destination types U, M, P, T, or O, specify whether the destination is on the


server (S) or agent (A). For Destination type E, specify S.

The following prompt is displayed:

Logical Name:

4 Specify the logical name for this destination.

The following prompt is displayed:

Physical Name:

5 For Destination types U, M, P, or T, specify the physical name. For Destination


types O and E, leave this field blank.

The new entry is added to the table.

To modify an existing entry (physical name only) in the table

1 Specify e<entry_number>. For example, to modify entry number 2, specify e2.

The following prompt is displayed:

Dest Type:
Address Type:
Physical Name:

This option cannot be used to modify a logical name.

2 Specify a new physical name for the entry. The table is redisplayed with the
modified entry.

To delete an existing entry in the table

1 Specify d<entry # >. For example, to delete entry # 2, specify d2.

The entry is deleted.

2 Specify q to return to the Shout Destination Tables menu.

Chapter 3 Utilities 285


ctmsys

To change the active shout destination table

1 Select Option 2 from the Shout Destination Tables menu.

A list similar to the following is displayed:

Existing Shout Destination Tables


---------------------------------
SYSTEM
NIGHT_SHIFT
Enter name of table to make active or q to quit [SYSTEM]:

2 Specify the name of the table to set as the active Shout Destination table.

The following message is displayed:

Table <table name> is now active.


Press ENTER to continue.

3 Press <Enter> to return to the Shout Destination Tables menu.

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.

To list existing shout destination tables

1 Select Option 3 from the Shout Destination Tables menu.

A list similar to the following is displayed:

Shout Destination Tables


------------------------
SYSTEM
NIGHT_SHIFT
Press ENTER to continue

2 Press <Enter> to return to the Shout Destination Tables menu.

286 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsys

To delete an existing shout destination table by name

1 Select Option 4 from the Shout Destination Tables menu.

A list of existing Shout Destination Tables is displayed.

2 Specify the name of the table to delete.

The following message is displayed:

Delete completed successfully.


Press ENTER to continue.

3 Press <Enter> to return to the Shout Destination Tables menu.

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

To view or modify CONTROL-M system parameters

1 Choose Option 2 from the Main Menu.

The first group of parameters (and their current values) is displayed. See Figure 18.

Figure 18 CONTROL-M System Parameters (Page 1)


CONTROL-M System Parameters (Page 1/2)
--------------------------------------

Computer System :sparc


Operating System :Solaris
CONTROL-M Version :6.3.0
Database Version/schema :6.3.0
Executable Path :/home3/ctmssl/ctm_server/exe_Solaris
1) Day Time :+0700
CONTROL-M Date :20041216

Chapter 3 Utilities 287


ctmsys

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

Enter command, or item number you wish to change [n]:

When you specify n, the second page of parameters is displayed. See Figure 19.

Figure 19 CONTROL-M/Server System Parameters (Page 2)


CONTROL-M System Parameters (Page 2/2)
--------------------------------------

6) Maximum Days Retained by CONTROL-M Log :2


7) Maximum Days to Retain Sysout Files :1
8) Ignore New Day Conditions :N
9) Secure Sockets Layer :DISABLED

p) Previous Page
s) Save and Return to Main Menu
c) Cancel

Enter command, or item number you wish to change [p]:

Parameters that can be modified are preceded by a number.

2 Modify or view parameters as follows:

■ To switch between the two pages of parameters, type n (next page) or p


(previous page) as required.
■ To modify a parameter, type the number preceding the parameter.

— If the parameter has a Y/N value, typing the parameter’s option number toggles
the value between Y and N and redisplays the page.

— If the parameter requires any other value, you are prompted to type the value.
After you supply the value, the page is redisplayed.

3 When you want to exit:

■ Type s to save your changes and exit to the Main Menu. Modifications are not
saved until you perform this action.

288 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmsys

-or-

■ Type c to cancel all changes and exit to the Main Menu.

Chapter 3 Utilities 289


ctmudchk

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”).

Use the following command to invoke the ctmudchk utility:

ctmudchk -DAILY <UserDailyname>


-ACTION {LIST|ORDER}
[-FILE <fileName>]
[-odate {ODAT|<yyyymmdd>}]
[-odate_option {value_date|run_date}]

The parameters of this command are described in Table 84.

Table 84 ctmudchk parameters (part 1 of 2)


Parameter Description
-DAILY Name of the User Daily to be checked.
-ACTION Indicates whether jobs that are missing from the Active Jobs file should
be listed or ordered.

The following values can be specified for this parameter:


LIST Lists the job name and the name of the scheduling
table for each missing job.
ORDER Orders the missing jobs.
-FILE Indicates the path name for the output of the ctmudchk utility. This
parameter is required only if LIST is specified for the ACTION
parameter.
-odate Indicates the scheduling date (odate) to be associated with jobs that are
ordered by this user daily job.

Valid values are:


ODAT The current working date of the computer on which
CONTROL-M/Server is running.

This is the default value.


yyyymmdd A specific working day in yyyymmdd format.
Note: The interpretation of this parameter value is dependant on the
value specified for the -odate_option parameter (described below).

290 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmudchk

Table 84 ctmudchk parameters (part 2 of 2)


Parameter Description
-odate_option Indicates how the specified -odate value should be used.

Valid values are:


value_date The specified odate is the odate value for the jobs.
However, the jobs ordered by the user daily job
should be run during the current working day.

This is the default value for the -odate_option


parameter.

Note: If time zones specified in specific job


processing definitions in the scheduling tables, then
the jobs are run according to those time zones.
run_date The jobs ordered by the user daily job should be run
only when the specified odate begins.

■ If the specified odate is the current working day,


then this will work in the same way as
value_date (described above).

■ If the specified odate has not begun (for example,


due to time zone specifications), then the job will
wait in the Active Jobs file (with WAIT_ODAT
status) until the start of the specified working
day.

Note: If the specified odate has already passed, the


ctmudchk utility will not run, and an error message
will be displayed.

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.

ctmudchk -DAILY payroll -ACTION LIST

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.

ctmudchk -DAILY admin1 -ACTION ORDER

Chapter 3 Utilities 291


ctmudchk

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

292 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmudlst

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”).

To invoke the ctmudlst utility, specify one of the following commands


ctmudlst LIST <userDaily>
ctmudlst LIST "*"
ctmudlst UPDATE <userDaily> <date>

The parameters of these commands are described in Table 85.

Table 85 ctmudlst parameters


Parameter Description
LIST Lists the User Daily last run date.
UPDATE Updates the User Daily last run date.
<User Daily> User Daily name.
“*” Asterisk enclosed in quotation marks. Displays a list of all User Daily
names and corresponding last run dates.
<Date> Requested value for the last running date in yyyymmdd format.

Example 1

The following command lists the last run date for User Daily payroll:

ctmudlst LIST payroll

Example 2

The following command changes the last run date for User Daily inventory to Aug.
10, 2002:

ctmudlst UPDATE inventory 20020810

Chapter 3 Utilities 293


ctmudly

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.

To invoke the ctmudly utility, specify either of the following commands


ctmudly <userDaily>
[-odate {ODAT|<yyyymmdd>}]
[-odate_option {value_date|run_date}]

-or-

ctmudly -DAILY_NAME <userDaily>


[-odate {ODAT|<yyyymmdd>}]
[-odate_option {value_date|run_date}]

The parameters of this command are described in Table 86.

Table 86 ctmudly parameters (part 1 of 2)


Parameter Description
<userDaily> Name of a user daily job that is associated with one or more Scheduling
tables. This parameter is case-sensitive.

Notes:

■ The specified name must be no longer than 10 characters. If a longer


name is specified, it will be truncated to 10 characters.

■ If the ctmudly utility command is issued from a


CONTROL-M/Agent, it must include the -DAILY_NAME
keyword (as shown above).

294 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmudly

Table 86 ctmudly parameters (part 2 of 2)


Parameter Description
-odate Indicates the scheduling date (odate) to be associated with jobs that are
ordered by this user daily job.

Valid values are:


ODAT The current working date of the computer on which
CONTROL-M/Server is running.

This is the default value.


yyyymmdd A specific working day in yyyymmdd format.
Note: The interpretation of this parameter value is dependant on the
value specified for the -odate_option parameter (described below).
-odate_option Indicates how the specified -odate value should be used.

Valid values are:


value_date The specified odate should be used as the odate value
for the job. However, the jobs ordered by the user
daily job should be run during the current working
day.

This is the default value for the -odate_option


parameter.

Note: If time zones specified in specific job


processing definitions in the scheduling tables, then
the jobs are run according to those time zones.
run_date The jobs ordered by the user daily job should be run
only when the specified odate begins.

■ If the specified odate is the current working day,


then this will work in the same way as
value_date (described above).

■ If the specified odate has not begun (for example,


due to time zone specifications), then the job will
wait in the Active Jobs file (with WAIT_ODAT
status) until the start of the specified working
day.

Chapter 3 Utilities 295


ctmudly

Messages issued when a job is not ordered


Security Issues – When a job is not scheduled due to security protection, the
following Alert is sent to CONTROL-M/EM:

DAILY <userdaily name> FAILED TO ORDER JOBNAME <jobname> - Security

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

UDAILY: PARTIAL COPY

The exit code of the ctmudly utility is determined by CONTROL-M configuration


parameter UDLY_PARTCOPY_ERR. See page 393 for more information.

Example 1 – ordering a specific User Daily

The following command orders all Scheduling tables that are associated with the
User Daily named prod:

ctmudly prod

Example 2 – ordering a User Daily for a specific time zone

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.

ctmudly -DAILY_NAME Japan


-odate 20020331
-odate_option run_date

296 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmvar

ctmvar
The ctmvar utility defines, deletes, modifies and displays AutoEdit variables. This
utility can be applied to variables that are:

■ In a specific job processing definition in a Group Scheduling table


■ Common to all jobs in a Group Scheduling table
■ Global for an entire data center (a CONTROL-M/Server and all associated agents)

Special notes

■ If a group scheduling table specified in the ctmvar utility has been ordered more
than once, the utility updates every instance of that group scheduling table in the
Active Jobs file.

■ AutoEdit variables in jobs that are not part of a group scheduling table cannot be
modified using the ctmvar utility.

■ A value specified for a Global AutoEdit variable is overridden if a local variable


with the same name is defined in a job processing definition or for a group
scheduling table.

Syntax

To invoke the ctmvar utility, specify the following command


ctmvar
-ACTION <LOAD|SET|DELETE|LIST>
[ -VAR <Variable> ]
[ -VAREXPR <Variable Expression> ]
[ -FILENAME <Filename> ]
[ -QUIET ]
[ -DEBUG <debug level> ]

-or-

ctmvar -input_file <fullPathFileName>

Chapter 3 Utilities 297


ctmvar

Table 87 ctmvar parameters (part 1 of 3)


Parameter Description
-ACTION Indicates the action to be performed on the specified AutoEdit variable.
The possible actions are:
LOAD Loads AutoEdit variables from a file. When this option is
used, parameter -filename is required. The format for each
variable in the specified file is:
%%[\<gptble>[\<job>]]\<varname>=<expression>

■ If the variable does not exist in the data center or the


specified group scheduling table or job, it is created.

■ If the variable already exists, it is updated with the


specified value.
SET Defines a new AutoEdit variable. When this option is used,
parameters -var and -varexpr are required.

■ If the variable does not exist in the data center or the


specified group scheduling table or job, it is created.

■ If the variable already exists, it is updated with the


specified value.
DELETE Deletes a Global AutoEdit variable. When this option is
used, the -var parameter is mandatory.

Note: This action cannot be used for AutoEdit variables that


have been defined for a specific job or Group Scheduling
table.
LIST Displays all Global AutoEdit variables for the data center or
all variables for the specified group scheduling table
specified in the -var parameter.

Example 1:
ctmvar -action LIST

Displays all Global variables for the data center.


Example 2:
ctmvar -action LIST -var “%%\PAYROLL”

Displays all AutoEdit variables that are global for the


PAYROLL group scheduling table.

Variable values can also be displayed using the ctmstvar


utility. However, the ctmstvar utility resolves the current
value of only a specified AutoEdit variable or function. The
ctmvar utility displays all AutoEdit variables in the data
center or the specified group scheduling table.

298 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmvar

Table 87 ctmvar parameters (part 2 of 3)


Parameter Description
-VAR Name and location of the AutoEdit variable that the specified action
should be applied to.

The valid format for this parameter depends on the type of variable being
handled.

■ For a variable that is global for an entire data center, valid format is:
-var “%%\<var_name>”

■ For a variable that is global for all jobs in a Group Scheduling table,
valid format is:
-var “%%\<group_table_name>\<var_name>”

■ For variable in a specific job in a group scheduling table, valid format


is:
-var “%%\<group_table_name>\<jobname>\<var_name>”

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:

■ a string (embedded in quotation)

■ an integer (a numeric value)

■ an AutoEdit expression (for example, with an AutoEdit function)

■ another (existing) global variable.

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.

The syntax for each line in the specified file is


%%[\<gptble>[\<job>]]\<varname>=<expression>

Note: Specify the entire pathname in this parameter.


-QUIET Suppresses the display of the results.

Chapter 3 Utilities 299


ctmvar

Table 87 ctmvar parameters (part 3 of 3)


Parameter Description
-DEBUG Sets a debug level for the utility. This parameter is used for maintenance
and troubleshooting purposes. The level, a numeric value from 0 to 5,
must be used only if requested and specified by Technical Support.

Note:
Performance is somewhat slower and requires a larger number of
resources when operating in debug mode. 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:

■ prepare and save files of utility parameters that can be reused.

■ specify utility input longer than the number of characters allowed in


the command line.

Example:
-input_file ~<controlm_owner>/ctm_server/data/ctmvar_parms.txt

Examples

The following command assigns the value UP to AutoEdit variable %%CTMSTATUS:

ctmvar -action set -var “%%\CTMSTATUS” -varexpr “UP”

The following command assigns the value 31 to AutoEdit variable


%%MONTHDAYS in the group scheduling table called PAYROLL:

ctmvar -action set -var “%%\PAYROLL\MONTHDAYS”


-varexpr 31

The following command assigns the current value of system variable %%TIME to
AutoEdit variable %%AAA:

ctmvar -action set -var “%%\AAA” -varexpr %%TIME

You can get the same result using the -input_file parameter as follows:

ctmvar -input_file ~<controlm_owner>/ctm_server/data/var_expr_parms.txt

300 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ctmvar

The referenced file contains the following lines:

-action set
-var “%%\AAA”
-varexpr %%TIME

The format AutoEdit variable %%@varname indicates that the variable should contain
a value to be resolved by each job that uses it. In the following example, the command
assigns the value %%@TIME to AutoEdit variable %%AAA:

ctmvar -action set -var “%%\AAA” -varexpr %%@TIME

For more information about AutoEdit variables, see the AutoEdit chapter in the
CONTROL-M Job Parameter and Variable Reference Guide.

Chapter 3 Utilities 301


ctmwhy

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.

To invoke the ctmwhy utility, specify the command

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"

302 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


dbversion

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.

Specify the following command to invoke the dbversion utility:

dbversion

Chapter 3 Utilities 303


ecactltb

ecactltb
The ecactltb utility displays a list of Control resources and the status of each resource.

To invoke the ecactltb utility, specify the following command

ecactltb [<output>]

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

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

304 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ecaqrtab

ecaqrtab
The ecaqrtab utility performs operations on the Quantitative Resources table. These
operations include:

■ Listing Quantitative resources.


■ Adding/deleting a Quantitative resource.
■ Manually changing availability of a Quantitative resource.

Use this command to invoke the ecaqrtab utility from the server:

ecaqrtab {LIST|ADD|DELETE|UPDATE}{<QR_Name>|”*”}[<Max>][-OUTPUT <Output>]

-or-

ecaqrtab -input_file <fullPathFileName>

Use this command to invoke the LIST option of this utility from the agent:

ecaqrtab LIST ”*” [-OUTPUT <Output>]

-or-

ecaqrtab -input_file <fullPathFileName>

NOTE
If a resource name is longer than 20 characters, the resource is not added.

Table 88 ecaqrtab parameters (part 1 of 2)


Parameter Description
LIST Displays the status of the specified Quantitative resources. This
information is also available from CONTROL-M/EM in the Quantitative
Resources window.
ADD Defines a new Quantitative resource and sets the maximum availability
for the resource.
DELETE Deletes an existing Quantitative resource.
UPDATE Changes the maximum availability of an existing Quantitative resource.
<QR_Name> Name of the Quantitative resource. For the LIST option, QR_Name can
include mask character * to indicate any number of characters (including
none). If * is specified, enclose the name in quotation marks, for example,
“LVL*”. When invoked by the server or agent, specify “*” (including the
quotation marks) to include all existing Quantitative resources (default
when invoked by the server).

Chapter 3 Utilities 305


ecaqrtab

Table 88 ecaqrtab parameters (part 2 of 2)


Parameter Description
<Max> Maximum availability for the specified resource. Can only be specified
with the ADD and UPDATE options.
<Output> Full path name to which the report should be sent (optional). If not
specified, output is routed to the default output device. This parameter
can only be specified with the LIST option.
<fullPathFile Name and full path of a file containing parameters for the utility. In this
Name> 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:

■ Prepare and save files of utility parameters that can be reused.

■ Specify utility input longer than the number of characters allowed in


the command line.

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.

To list Quantitative resources

Specify the following command when invoked by the server:

ecaqrtab LIST {<QR_Name>|“*”} [-OUTPUT <Output>]

or the following command when invoked by the agent:

ecaqrtab LIST “*” [-OUTPUT <Output>]

Table 89 describes the fields that are displayed for each Quantitative resource that
matches the specified resource name or mask.

Table 89 ecaqrtab – resource status fields


Parameter Description
QR name Quantitative resource name (with @<Node ID> where applicable).
Type For future use.
Max Avail Maximum number of units of this resource in the computer.
Reserved Number of units of the resource reserved for critical-path jobs.

306 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


ecaqrtab

Table 89 ecaqrtab – resource status fields


Parameter Description
Used Number of units of the resource currently in use or reserved. If the
ctmloadset utility is used in the data center, this number can include usage
of the resource by non-CONTROL-M jobs.
Free Number of units of the resource currently available for use. This represents
the difference between Max Avail and Used.

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:

ecaqrtab LIST “*” -OUTPUT D:\ctm_server\QR.txt

A report similar to the following is displayed:

+--------------------------------------------------------------+
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

To add a Quantitative resource

Specify the following command:

ecaqrtab ADD <QR name> <Max>

Example

The following command specifies that the new Quantitative resource tape2 is to be
added to the Quantitative Resource table, with a maximum availability of 12 units:

ecaqrtab ADD tape2 12

To delete a Quantitative resource

Specify the following command:

ecaqrtab DELETE <QR name>

Chapter 3 Utilities 307


ecaqrtab

Example

The following command specifies that the Quantitative resource tape3 is to be deleted
from the table:

ecaqrtab DELETE tape3

To alter the availability of a Quantitative resource

Specify the following command:

ecaqrtab UPDATE <QR name> <Max>

Example

The following command specifies that the new maximum availability for the existing
Quantitative resource linerje2 on computer diana is 12 units:

ecaqrtab UPDATE linerje2@diana 12

You can get the same result using the -input_file parameter as follows:

ecaqrtab -input_file ~<controlm_owner>/ctm_server/data/ecaqrtab_lines.txt

The referenced file contains the following lines:

UPDATE
linerje2@diana
12

308 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Chapter

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.

The following topics are covered in this chapter:

■ CONTROL-M/Server entities
■ Database configuration
■ Periodic maintenance
■ Failover procedures
■ CONTROL-M Main Menu options
■ CONTROL-M/Server processes
■ Shout destination tables

Chapter 4 Maintenance 309


CONTROL-M/Server entities

CONTROL-M/Server entities
CONTROL-M/Server is comprised of the following entities:

■ SQL Database Server


■ CONTROL-M/Server
■ CONTROL-M/Server Configuration Agent
■ CONTROL-M/Server utilities

To start CONTROL-M/Server functions in the data center, run the following entities
on the CONTROL-M/Server computer:

Table 90 Entities that run on the CONTROL-M/Server computer


Entity Remark
SQL Database Server The SQL Database Server must be started before
CONTROL-M/Server and must be active as long as
CONTROL-M/Server is active. Mandatory.
CONTROL-M/Server Configuration This entity is started automatically when the
Agent computer is started. Default.
CONTROL-M/Server Mandatory.
CONTROL-M/Server utilities Run CONTROL-M/Server utilities as required.
Optional.

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.

CONTROL-M/Server entities can be started or stopped on the CONTROL-M/Server


computer using one of the following methods:

■ Automatic startup or shutdown (as part of the server computer boot and
shutdown processes)

The installation procedure for CONTROL-M/Server includes directions for


adding startup of SQL Database Server, CONTROL-M/Server, and
CONTROL-M/Server Configuration Agent to the boot procedure and shutdown
procedure of the server computer. For more information, see the CONTROL-M/
Server for UNIX and Microsoft Windows Installation Guide.

On Windows, CONTROL-M/Server Configuration Agent is started automatically


at boot time2.

310 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server entities

The CONTROL-M Configuration Manager provides options for starting or


stopping CONTROL-M/Server remotely. For more information, see the
CONTROL-M/Enterprise Manager Administration Guide.

If CONTROL-M/Server is installed in a disk cluster environment, the Cluster


Administrator must be used to start and stop CONTROL-M/Server. For more
information, see the CONTROL-M on UNIX Clusters and CONTROL-M on Windows
Clusters guides.

■ Using the CONTROL-M/Server menu options

The CONTROL-M/Server menu options provides the necessary options for


starting or stopping CONTROL-M/Server, the SQL Database Server, and
CONTROL-M/Server Configuration Agent. For more information, see
“CONTROL-M Manager menu” on page 324.

■ Using supplied utilities

CONTROL-M/Server is supplied with utilities for starting and shutting down


CONTROL-M/Server, the SQL Database Server, and CONTROL-M/Server
Configuration Agent. You can invoke these utilities directly (as described below)
or incorporate them into your own utilities.

To start CONTROL-M/Server entities

1 Log on as the CONTROL-M/Server account owner.

2 For the SQL server, specify the command: startdb

3 For CONTROL-M/Server Configuration Agent: start_ca

4 For CONTROL-M/Server, specify the command: start_ctm

To shut down CONTROL-M/Server entities

1 Log on as the CONTROL-M/Server account owner.

2 For the SQL database server, specify the command: shutdb

You are prompted to enter the DBA password to shut down the SQL database
server.

3 For CONTROL-M/Server Configuration Agent: shut_ca

4 For CONTROL-M/Server, specify the command: shut_ctm

Chapter 4 Maintenance 311


Database configuration

Using the Microsoft Windows Services window

The Windows administrator, using the Microsoft Windows Services window, can
manually start or stop:

■ the CONTROL-M/Server Configuration Agent Windows service


■ the CONTROL-M Server Windows service

To start CONTROL-M/Server in a disk cluster environment

1 Choose Start=>Programs=>Administrative Tools=>Cluster Administrator.

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.

To stop CONTROL-M/Server in a disk cluster environment

1 Choose Start=>Programs=>Administrative Tools=>Cluster Administrator.

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:

■ check available space in the CONTROL-M/Server database


■ clean up the database message log
■ increase the size of the master database log
■ clean up the proclog directory

Each of these topics is discussed below.

312 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Checking available space in CONTROL-M/Server database

Checking available space in CONTROL-M/Server database


BMC Software recommends that the amount of available space in the CONTROL-M/
Server database be checked on a regular basis. If the available space falls below 20%,
the database should be extended (see “Extending the size of the database” on page
335).

The CONTROL-M/Server default installation uses autoextend. For more


information, see the CONTROL-M/Server for UNIX and Microsoft Windows
Installation Guide.

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:

WARNING: Database is more than half full


ATTENTION: Database is more than 80% full
ATTENTION: Database log segment is more than 90% full

These messages can be detected in a CONTROL-M/Server job using the On


Statement/Code parameter. Appropriate Shout messages could then be issued as
required.

Cleaning up the database message log


The database server writes a message to a log file when the server is started or shut
down, and when a database error occurs. This file is not automatically truncated. If
not manually truncated, the file will utilize a large amount of disk space. The file
created is an error log for Sybase and an alert log for Oracle. [UNIX only]

The responsibility of maintaining the log file depends on whether CONTROL-M/


Server uses the dedicated database server provided with the installation, or an
existing database server.

Chapter 4 Maintenance 313


Cleaning up the database message log

■ When CONTROL-M/Server uses a dedicated database server provided during


installation, it is the responsibility of the CONTROL-M/Server administrator to
truncate this file on a regular basis. The location of this file depends on the
database type.

Table 91 Location of the dedicated database message log


Database Dedicated database message log location
Sybase $SYBASE/ASE-12_5/data/errorlog
Oracle ■ Alerts are saved in files with the extension .log

$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

■ If CONTROL-M/Server is configured to use an existing database server, it is the


responsibility of the database administrator to truncate this file on a regular basis.

314 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Increasing the size of the master database log

Increasing the size of the master database log


This procedure varies according to the type of database.

Table 92 Increasing the size of the master database log


Database Description
Sybase When using a Sybase CONTROL-M/Server database, the master database log
can become full if the trunc log on chkpt option is not set. If this problem occurs,
the following message is displayed in the Sybase error_log:
Cannot allocate space for object ‘syslogs’ in database
‘master’ because the ‘logsegment’ segment is full or has no
free extents.
■ To fix this in the short term, log on to Sybase using the sa user, and issue the
command:
dump tran master with no_log
■ To fix this in the long term, log on to Sybase using the sa user, and set the
trunc log on chkpt option for the master database using the following
commands:
sp_configure "allow updates", 1'
update master..sysdatabases set status = 8 where dbid = 1
sp_configure "allow updates", 0
checkpoint
If the master log gets full often, add more space to the master log segment by
specifying the following command:
alter database master log on
master=<increase>
The <increase> variable is the number of 2K blocks to be added to the master
database.
Oracle This option is not applicable. Consult your database administrator.

Cleaning up the proclog directory


CONTROL-M/Server writes a trace log to the directories and files below. The higher
the trace level, the larger the log files. For more information, see “Set trace level” on
page 353.

Each time CONTROL-M/Server is started, the proclog file from the previous session
is saved to one of the following files:

Chapter 4 Maintenance 315


Cleaning up the proclog directory

■ For UNIX

$CONTROLM_SERVER/proclog

The files are saved in the proclog.save file.

■ For Windows

<ctm_installation>\proclog

The files are saved in the proclog.sav file.

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.

316 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Failover procedures

Failover procedures
The following procedures are used to implement CONTROL-M/Server features
required for failover processing:

■ CONTROL-M/Server database mirroring


■ Recovering from database failure
■ Recovering from CONTROL-M/Server computer failure

Many of the functions for these procedures are accessible from the CONTROL-M
Main Menu. For more information about this menu, see page 322.

CONTROL-M/Server database mirroring


Mirroring of the CONTROL-M/Server database allows rapid recovery of
CONTROL-M/Server functionality in the event of a failure of the CONTROL-M/
Server database. You can implement mirroring during or after CONTROL-M/Server
installation. For additional information regarding database requirements for
mirroring, see the CONTROL-M/Server for UNIX and Microsoft Windows
Installation Guide.

To implement CONTROL-M/Server database mirroring

1 Review the database requirements for mirroring as described in the


CONTROL-M/Server for UNIX and Microsoft Windows Installation Guide. For
additional information regarding database mirroring, see “Failover planning” on
page 35.

2 Verify that CONTROL-M/Server, CONTROL-M/Server Configuration Agent, and


CONTROL-M/Server utilities are not running. Ensure that the SQL database is
running.

3 Choose Database Mirroring => Initialize Mirroring from the CONTROL-M Main
Menu.

4 At the conclusion of the procedure, restart CONTROL-M/Server and the


CONTROL-M/Server Configuration Agent. For more information about starting
CONTROL-M/Server manually, see page 311.

NOTE
After mirroring is operational, it cannot be initialized unless the mirroring status is
“damaged” or “disabled”.

Chapter 4 Maintenance 317


Recovering from database failure

Recovering from database failure


If database mirroring has been implemented and there is a failure of the
CONTROL-M/Server primary database, two options exist for restoring
CONTROL-M/Server functionality:

■ Configure CONTROL-M/Server to operate using the mirror database instead of


the primary database. The primary CONTROL-M/Server database can be rebuilt
at a later stage.

This method resumes CONTROL-M/Server functionality in the minimum time


possible. However, mirroring cannot be resumed until after the primary database
is rebuilt.

■ Rebuild the CONTROL-M/Server primary database from the mirror database and
start CONTROL-M/Server again.

This method allows mirroring of the CONTROL-M/Server database to continue


without interruption. However, you will not be able to start CONTROL-M/Server
until you have completed rebuilding the CONTROL-M/Server database and this
can take several minutes.

If the CONTROL-M/Server mirror database fails (and the primary database is


functioning normally), CONTROL-M/Server operation is not affected. Mirroring can
be resumed by choosing Database Mirroring => Initialize Mirroring from the
CONTROL-M Main Menu.

To configure CONTROL-M/Server to operate using the mirror database

1 Verify that CONTROL-M/Server, CONTROL-M/Server Configuration Agent, and


CONTROL-M/Server utilities are not running. Ensure that the SQL database is
running.

2 Choose Database Mirroring => Use Mirror Database from the CONTROL-M Main
Menu. The following message is displayed:

Please confirm that you wish to use the Mirror Database


INSTEAD of the Main CONTROL-M database
[y/n]

If you select y, CONTROL-M/Server will start to use the Mirror Database instead
of the primary database. The following message is displayed:

In order to complete this procedure after exiting the menu,


please execute 'source ~/.cshrc' command.

If you select n, exit to the Database Mirroring menu.

318 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Recovering from database failure

3 Restart CONTROL-M/Server and the CONTROL-M/Server Configuration Agent.


For more information about starting CONTROL-M/Server manually, see page
311.

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.

To rebuild the CONTROL-M/Server primary database from the mirror database


and restart mirroring

1 Verify that CONTROL-M/Server, CONTROL-M/Server Configuration Agent, and


CONTROL-M/Server utilities are not running. Ensure that the SQL database is
running.

2 Choose Database Mirroring => Restore CONTROL-M/Server Database from Mirror


from the CONTROL-M Main Menu.

3 Under certain conditions (for example, environment variables need to be reset), the
following message is displayed:

You must exit this menu and logout of this session


for the environment changes to take effect. When
you log back in rerun "Restore Database from
Mirror".

If this message is displayed:

A Exit the current environment and start a new logon session.

B Repeat step 2.

4 Choose Database Mirroring => Initialize Mirroring from the CONTROL-M Main
Menu.

5 Exit the current environment and start a new logon session.

6 Restart CONTROL-M/Server and the CONTROL-M/Server Configuration Agent.


For more information about starting CONTROL-M/Server manually, see page
311.

Chapter 4 Maintenance 319


Recovering from CONTROL-M/Server computer failure

Recovering from CONTROL-M/Server computer failure


If an irrecoverable software/hardware failure occurs in the primary environment,
and you prepared a backup environment earlier, you can restore functionality using
the following procedure.

To start CONTROL-M/Server on the mirror environment

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:

** Unable to start CONTROL-M due to path specified for PROCLIB


directory $PROCLIB. This path is invalid **

3 On the mirror environment, choose CONTROL-M Manager => Start CONTROL-M/


Server Configuration Agent and CONTROL-M Manager => Start CONTROL-M/
Server from the CONTROL-M Main Menu.

CONTROL-M/Server is started on the mirror environment, using the mirror


database. Database mirroring is disabled.

4 In the CONTROL-M/Server Definition dialog box in the CONTROL-M


Configuration Manager, modify the Host and CONTROL-M/EM Port parameters
to the values appropriate to the mirror environment. For more information, see the
Configuration Management Server in the CONTROL-M/Enterprise Manager User
Guide.

At the first opportunity, the CONTROL-M primary environment should be returned


to operational status. The CONTROL-M/Server primary database should be rebuilt
and CONTROL-M/Server on the primary environment should be started again.

320 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Recovering from CONTROL-M/Server computer failure

To restore CONTROL-M/Server on the primary server computer

1 On the mirror environment, choose CONTROL-M Manager => Stop CONTROL-M/


Server Configuration Agent and CONTROL-M Manager => Stop CONTROL-M/
Server from the CONTROL-M Main Menu.

2 On the mirror environment, choose Database Mirroring => Stop Failover from the
CONTROL-M Main Menu.

3 On the primary environment, choose Database Mirroring => Restore CONTROL-M


Database From Mirror from the CONTROL-M Main Menu.

4 On the primary environment, choose Database Mirroring => Initialize Mirroring


from the CONTROL-M Main Menu.

5 Exit the current environment and start a new logon session.

6 On the primary environment, start CONTROL-M/Server. For more information


about starting CONTROL-M/Server manually, see page 311.

7 In the CONTROL-M/Server Definition dialog box in the CONTROL-M


Configuration Manager, modify Host and CONTROL-M/EM Port to values
appropriate for the primary environment. For more information, see the
Configuration Management Server in the CONTROL-M/Enterprise Manager User
Guide.

Chapter 4 Maintenance 321


CONTROL-M Main Menu options

CONTROL-M Main Menu options


The CONTROL-M Main Menu options enables you to access a variety of functions
and utilities used to maintain CONTROL-M/Server.

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.

Opening CONTROL-M Main Menu

To open the CONTROL-M Main Menu

1 Log on to the server computer as the CONTROL-M/Server owner.

2 Enter the following command:

ctm_menu

The following menu is displayed:

Figure 20 CONTROL-M Main Menu


CONTROL-M Main Menu
-----------------------------

Select one of the following menus:

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.

The following menus are available:

322 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Opening CONTROL-M Main Menu

Table 93 CONTROL-M Main Menu options


Menu item Description
CONTROL-M Manager Start up and shut down CONTROL-M/Server entities. For
more information, see “CONTROL-M/Server entities” on
page 310.
Database Creation Create or delete the CONTROL-M/Server database.
Database Maintenance Perform various CONTROL-M/Server database maintenance
functions.
Database Mirroring Perform various CONTROL-M/Server mirror database
functions.
Security Authorization Export or import Security Definition tables and invoke the
CONTROL-M/Server Security Maintenance utility (ctmsec) to
define user authorizations.
Parameter Customization View and update parameters for customizing CONTROL-M/
Server.
Node Group Maintain Node Groups and application groups for load
balancing.
View NodeID details Collect and view application server information from agent
and remote host computers.
Agent Status View and update the communication status of agent
computers.
Troubleshooting Perform various troubleshooting functions.
Quit Exit to the shell prompt.

Chapter 4 Maintenance 323


CONTROL-M Manager menu

CONTROL-M Manager menu


The CONTROL-M Manager menu is used to start and stop CONTROL-M/Server
entities. Choosing CONTROL-M Main Menu => CONTROL-M Manager displays the
following:

Figure 21 CONTROL-M Manager Menu


CONTROL-M Manager Menu
-----------------------------

Select one of the following options:

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.

■ If CONTROL-M/Server uses a shared instance of the SQL database server to


maintain the CONTROL-M/Server database, the database administrator is
responsible for starting and stopping the server.

■ Similarly, if mirroring of the CONTROL-M/Server database is implemented, the


database administrator is responsible for starting and stopping the mirroring
server.

Table 94 describes the options available from the CONTROL-M Manager Menu.

324 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M Manager menu

Table 94 CONTROL-M Manager Menu options


Menu Item Description
Check All Determines whether the SQL database server task and the
CONTROL-M/Server task are currently running and reports
the status of each task.
Start All Starts any entities required for CONTROL-M/Server that are
not already running. The SQL database server is started first,
followed by CONTROL-M/Server and the Configuration
Agent process.
Start Database Starts the SQL database server (only if dedicated to the
CONTROL-M/Server database).
Start CONTROL-M/ Starts CONTROL-M/Server. The SQL database server must be
Server running when this option is selected.
Start CONTROL-M/ Starts CONTROL-M/Server Configuration Agent.
Server Configuration
Agent
Stop All Stops all CONTROL-M/Server entities. Configuration Agent
process is stopped first, followed by the CONTROL-M/Server
and then the SQL database server.
Stop Database Stops the SQL database server (only if dedicated to the
CONTROL-M/Server database). CONTROL-M/Server should
not be running when this option is selected.

Note: After specifying this utility, you are prompted to enter


the DBA password to shut down the SQL database server.
Stop CONTROL-M/ Stops CONTROL-M/Server.
Server
Stop CONTROL-M/ Stops CONTROL-M/Server Configuration Agent.
Server Configuration
Agent
Quit Quits the CONTROL-M Manager menu and returns to the
CONTROL-M Main Menu.

Chapter 4 Maintenance 325


Database Creation menu

Database Creation menu


The Database Creation menu is used to perform functions related to creating and
deleting the CONTROL-M/Server database. Choose CONTROL-M Main Menu =>
Database Creation to display the Database Creation Menu.

Table 95 describes the options in the Database Creation Menu.

Table 95 Database Creation Menu options (part 1 of 2)


Menu item Description
Show Database Displays the CONTROL-M/Server database parameters.
Parameters
Build Database Rebuilds the CONTROL-M/Server database. For more information about
building the CONTROL-M/Server database, see “Build database” on
page 327
Delete Database Drops (deletes) the CONTROL-M/Server database and removes database
files. Shut down CONTROL-M/Server before selecting this option. After
using this option, you cannot use CONTROL-M/Server until you rebuild
the database.

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

Note: Shut down CONTROL-M/Server before selecting this option. When


this option is used, certain CONTROL-M/Server configuration
parameters revert to their defaults (for example, CONTROL-M/EM TCP/
IP Port Number). After using this option, you can use CONTROL-M/
Server, but no previous data exists.

326 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Database Creation menu

Table 95 Database Creation Menu options (part 2 of 2)


Menu item Description
Check Database Displays the CONTROL-M/Server database size, availability of space,
and database integrity data similar to the following:

db total = 29000.0 KB (data = 23500.00 log = 5500.00)


data used = 1928 KB (8%). log used = 0 KB (0%).
Checking database

This function is also available by running the utility:

ctmdbcheck

ctmdbcheck can provide automatic database and transaction log


monitoring. The following options are available:

ctmdbcheck [db threshold %]


[log threshold %]
ctmdbcheck [general threshold %]

When db threshold % and log threshold % are exceeded, shout messages


to CONTROL-M/EM warn that the server database or log should be
extended.
Quit Quits the Database Creation menu and returns to the CONTROL-M Main
Menu.

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.

Chapter 4 Maintenance 327


Database Maintenance menu

To rebuild the database

1 Verify that CONTROL-M/Server and CONTROL-M/Server Configuration Agent


are not running. Ensure that the SQL database is running. For more information,
see page 311. Make sure there are no CONTROL-M/Server utilities connected to
the SQL Server.

2 Choose Database Creation => Build Database to build the database.

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.

Database Maintenance menu


The Database Maintenance menu is used to perform functions related to maintaining
the CONTROL-M/Server database. Choose CONTROL-M Main Menu => Database
Maintenance to display the Database Maintenance Menu.

Table 96 describes the options in the Database Maintenance Menu.

Table 96 Database Maintenance Menu options (part 1 of 2)


Applicable
Menu item Description database
Archive mode When database logs are full, they are written to a special Oracle
backup destination before they are overwritten by new
information.
Backup Backs up the CONTROL-M/Server database onto a All
Database backup device.
Restore Restores the CONTROL-M/Server database from a All
Database backup device.
List All Devices Display list of all devices. Sybase and
MSSQL
List Backup Display a list of valid devices. Sybase and
Device MSSQL
Add Backup Add a device to the list of devices. Sybase and
Device MSSQL
Drop Backup Deletes a device from the list of backup devices. Sybase and
Device MSSQL

328 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Database Maintenance menu

Table 96 Database Maintenance Menu options (part 2 of 2)


Applicable
Menu item Description database
Extend Database Extends the data segment of the database. All
Size
Extend Extends the temporary storage area of the database. Sybase
Temporary
Database
(Tempdb) Size
Extend Database Extends the log segment of the database. Sybase and
Log Size MSSQL
Extend TEMP Extends the tablespace of the database. Oracle
Tablespace Size
Extend Rollback Extends the log segment of the database. Oracle
Tablespace Size
Show Database Displays the CONTROL-M/Server database parameters All
Parameters
Check Database Displays the size of the CONTROL-M/Server database All
and availability of space, and verifies database integrity.
Quit Quits the Database Maintenance menu and returns to the All
CONTROL-M Main menu.

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.

Two types of backup can be performed, depending on the archive mode:

Table 97 Types of backup


Type Description
Hot backup Copies the contents of the database to a file when CONTROL-M/Server is
active. The backup and log file can be used to restore the database up to the
last completed transaction. For more information, see “Hot backup” on
page 331.
Cold backup Copies the contents of the database to a file when CONTROL-M/Server is
down. The database can be restored up to the date/time of the last backup.
For more information, see “Cold backup” on page 331.

Chapter 4 Maintenance 329


Database Maintenance menu

If Archive Mode is chosen in the Database Maintenance menu, CONTROL-M/Server


is shut down automatically and you are asked to supply the name of the destination
for archived log files. These archived log files can be used in case of a database crash
to restore the database up until the most recent SQL transaction.

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.

The Backup Database procedure should be performed periodically. BMC Software


recommends that a daily backup be performed.

To back up a Sybase or MSSQL database

1 Select 2 from the Database Maintenance menu.

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 Respond to the prompts that are displayed.

The CONTROL-M/Server database is backed up onto a backup device. This


option can be invoked while the database is running.

To back up an Oracle database

1 Select 2 from the Database Maintenance menu.

The following prompt is displayed:

Enter a destination directory name [<ctm_home_dir>]:

330 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Database Maintenance menu

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.

Type of backup Description


Hot backup ■ Can be used to restore a dedicated database to the state it was in after
the last completed transaction last COMMIT command executed).
■ Is performed in Archive mode. The backup procedure sets the mode if it
was not previously set. Running the database in Archive mode requires
extra disk space for Control files.
■ Requires that the directory you specify exist prior to starting the
backup.
Cold backup ■ Can be used to restore the database to the state it was in when the
backup was performed.
■ Is performed in non-Archive mode.

Note: Shut down CONTROL-M/Server before performing a cold backup.

4 The following prompt is displayed:

Specify archiving process destination directory:

5 Enter the directory in which the archive process will store its control files.

The backup procedure begins.

The procedure displays informational messages indicating the progress of the


backup.

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.

Chapter 4 Maintenance 331


Database Maintenance menu

To restore a Sybase or MSSQL database

Restores the CONTROL-M/Server database from a backup device. This function is


identical to the function performed by the ctmdbrst utility.

1 Select option 2 from the Database Maintenance Menu.

2 Follow the prompts that are displayed.

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.

To restore an Oracle database

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:

Enter a destination directory name [<ctm_home_dir>]:

3 Press <Enter> to accept the default directory, or type the name of the directory in
which the backup was saved.

4 If Archive mode is not active, a restore is automatically performed using


information from the most recent Cold backup. If Archive mode is active, a restore
is automatically performed using information from the most recent Hot backup.

For details about Hot and Cold backups, see step 3 on page 331.

332 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Database Maintenance menu

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

To restore a Sybase or MSSQL database if it is corrupted

1 Shut down CONTROL-M/Server, CONTROL-M/Server utilities and the


CONTROL-M/Server Configuration Agent. Make sure there are no users or
processes connected to the SQL Server.

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.

List all devices


Select the List All Devices option in the Database Maintenance Menu.

A list of all devices is displayed.

List backup devices


Select the List Backup Devices option in the Database Maintenance Menu.

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

Add backup device


This option adds a backup device to the list of devices available for backing up the
CONTROL-M/Server database.

1 Select the Add Backup Devices option in the Database Maintenance Menu.

Interactive prompts similar to the following are displayed:

Enter <dev_logical_name> :
Enter <disk|tape> :
Enter <file_full_path_name|device name> :

Chapter 4 Maintenance 333


Database Maintenance menu

Table 98 describes the variables in this prompt.

Table 98 Logical device description


Variable Description
<dev_logical_name> Logical name of the device.
{disk|tape} Type of device. Valid values are disk or tape.
■ If you specify disk, you must specify the file full path name.
■ If you specify tape, you must specify the 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.)

2 Enter the required parameters for the new device.

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

The following messages are displayed:

Creating Tape device.


‘Tape’ device added.
(return status = 0)

Drop backup device


Use this option to delete a device from the list of backup devices. [Sybase and
MSSQL]

1 Run the Drop Backup Device option from the Database Maintenance Menu.

The following prompt is displayed:

Enter <dev_logical_name>:

334 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Database Maintenance menu

2 Enter the logical name of the device to delete from the list.

Upon completion of the process, the following message is displayed:

Device dropped (return status = 0)

Extending the size of the database


Table 99 describes the menu options that can be used to extend the size of different
segments of the CONTROL-M/Server database. These options can be used while
CONTROL-M/Server is active or when it is shut down. See “Checking available
space in CONTROL-M/Server database” on page 313 for additional information.

Table 99 Menu Options for Modifying Database Size


Applicable
Option Description database
Extend Database Extends the data segment of the database. All
Size
Extend Extends the temporary storage area of the database Sybase
Temporary (tempdb).
Database Size
Extend Database Extends the log segment of the database. Sybase and
Log Size MSSQL
Note: Autoextend is also used.
Extend Rollback Extends the log segment of the database. Oracle
Tablespace Size
Extend TEMP Extends the tablespace of the database. Oracle
Tablespace Size

Extend database size

The Extend Database Size option extends the size of the data segment only. The size of
the log segment is not extended.

To extend the size of the data segment of the CONTROL-M/Server database

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.

Chapter 4 Maintenance 335


Database Maintenance menu

Extend temporary database size

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:

Extending database by 5120 pages on disk ctrlm_tempdbextend_2


Warning: The database 'tempdb' is using an unsafe virtual device
'ctrlm_tempdbextend_1'. The recovery of this database can not be
guaranteed.

Ignore this message.

To extend the size of the temporary area of the CONTROL-M/Server database

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.

3 Specify a full path name or press <Enter> to accept the default.

The file specified must not exist. The local file system where the file will be located
must have enough free space to accommodate the size specified above. Upon
completion of the process, 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.

To extend the size of the log segment of the CONTROL-M/Server database

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.

336 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Database Maintenance menu

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>

Upon completion of the process, a message is displayed, indicating that the


database log segment has been successfully extended.

Show database parameters


Use this option to display the CONTROL-M/Server database parameters.

To choose this option, select the Show Database Parameters option from the Database
Maintenance menu.

Information about the database parameters is displayed.

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:

db total = 29000.0 KB (data= 23500.00


log= 5500.00)
data used = 1928 KB (8%).
log used = 0 KB (0%).
Checking database

This function is also available by running the ctmdbcheck utility.

ctmdbcheck can also be used to provide automatic database and transaction log
monitoring. The following options are available:

ctmdbcheck [db_threshold_%] [log_threshold_%]


ctmdbcheck [general_threshold_%]

Chapter 4 Maintenance 337


Database Mirroring menu

db_threshold_% and log_threshold_% are user defined percentages which, when


exceeded, generate shout messages to CONTROL-M/EM warning that the
CONTROL-M/Server database or log should be extended.The general_threshold_%
option is used to specify the same percentage for both (for example, ctmdbcheck 50
will trigger a shout message if either the database or transaction log becomes more
than 50% full). ctmdbcheck can be run as a cyclic job.

Quit
Quits the Database Maintenance menu and returns to the CONTROL-M Main menu.

Database Mirroring menu


The Database Mirroring menu is used to perform functions related to initializing/
disabling database mirroring, recovering from CONTROL-M/Server database
failure, initializing failover, and recovering from server computer failure. Choosing
CONTROL-M Main Menu => Database Mirroring displays the following:

Figure 22 Database Mirroring Menu


Database Mirroring Menu
-----------------------
Select one of the following options:

Primary Server Options


1 - Check Mirroring Status
2 - Initialize Mirroring
3 - Disable Mirroring
4 - Use Mirror Database
5 - Restore CONTROL-M Database From Mirror

Failover Server Options


6 - Initialize Failover
7 - Start Failover
8 - Stop Failover

q - Quit

338 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Database Mirroring menu

Table 100 Options of the Database Mirroring Menu (part 1 of 2)


Option Description
Check Mirroring Indicates whether or not mirroring of the CONTROL-M/Server
Status database is currently enabled.
Initialize Mirroring Builds the CONTROL-M/Server mirror database from the existing
CONTROL-M/Server database and configures CONTROL-M/
Server to maintain the mirror database. This procedure is described
in the CONTROL-M/Server for UNIX and Microsoft Windows
Installation Guide. CONTROL-M/Server must be shut down before
selecting this option.
Disable Mirroring Discontinues mirroring of the CONTROL-M/Server database (if
mirroring was previously initialized). To restore mirroring after
selecting this option, use the Initialize Mirroring option. This option
is used in the following circumstances:

■ Mirroring is enabled but CONTROL-M/Server cannot be started


because it cannot connect to the mirroring SQL server.

-or-

■ Mirroring is no longer desired.


Use Mirror Configures CONTROL-M/Server to use the mirror database as its
Database primary database. This option can be used in the event that there was
a failure of the primary CONTROL-M/Server database and
mirroring was active. CONTROL-M/Server must be shut down
before you select this option.

To resume using the primary database, use the Restore


CONTROL-M Database from Mirror option.

For more information, see “Recovering from database failure” on


page 318.
Restore Rebuilds the CONTROL-M/Server database using the mirror
CONTROL-M database. This option is used when there was a failure of the primary
Database from CONTROL-M/Server database and mirroring was active.
Mirror CONTROL-M/Server must be shut down before selecting this
option.

For more information, see “Recovering from database failure” on


page 318.
Initialize Failover Saves site specific information about the backup server computer.
This data is needed to start CONTROL-M/Server on the backup
server computer in case of failure of the primary server.
Start Failover Copies the saved site-specific information about the backup server
computer to the Mirror database. This data is needed to start
CONTROL-M/Server on the backup server using the Mirror
database.

Chapter 4 Maintenance 339


Synchronizing the primary and mirror databases

Table 100 Options of the Database Mirroring Menu (part 2 of 2)


Option Description
Stop Failover Restores the site-specific information about the primary server
computer to the Mirror database. This data is used to restore the
primary database.
Quit Quits the Mirror Database menu and returns to the CONTROL-M
Main Menu.

Synchronizing the primary and mirror databases


When database mirroring is enabled, all database updates from CONTROL-M/
Server are sent simultaneously to both the primary and mirror CONTROL-M/Server
database. However, if the primary database is modified through one of the
CONTROL-M/Server database utilities, the mirror database will not automatically
reflect these changes. Either the same or a similar utility must be run against the
mirror database, or the mirror database must be re-initialized using the Database
Mirroring => Initialize Mirroring option on the CONTROL-M Main Menu.

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.

Table 101 Utilities affecting the primary database (part 1 of 2)


ctm_menu Option Database Utility Action
Database Creation Menu
Build Database Sybase build_db.sh Initialize Mirroring

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

340 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Security Authorization menu

Table 101 Utilities affecting the primary database (part 2 of 2)


ctm_menu Option Database Utility Action
Extend Temp Oracle ctm_tempdb_extend Either run the utility on the
Tablespace Size backup server computer or see
your Systems Administrator
Extend Rollback Oracle ctm_rollback_extend Either run the utility on the
Tablespace Size backup server computer or see
your Systems Administrator
Extend Database Log Size Sybase ctm_logdb_extend Either run the utility on the
backup server computer or see
your Systems Administrator
Troubleshooting Menu
Truncate Database Log Sybase ctm_cleanlog Either run the utility on the
backup server computer or see
your Systems Administrator
Restart New Day Procedure All <internal utility> Initialize Mirroring
Reset CONTROL-M Active All clean_ajf Initialize Mirroring
Environment

Security Authorization menu


The Security Authorization menu is used to invoke the ctmsec Security Maintenance
utility and export or import Security Definition tables. Choosing CONTROL-M Main
Menu => Security Authorization displays the following:

Figure 23 Security Authorization Menu


Security Authorization Menu
---------------------------------
Select one of the following options:
1 - Security Maintenance Utility
2 - Backup Security Definition Tables
3 - Restore Security Definition Tables
q - Quit

Chapter 4 Maintenance 341


Parameter Customization Menu

Table 102 Security Authorization Menu options


Option Description
Security Invokes the Security Maintenance utility (ctmsec). This utility is used
Maintenance Utility to define users in the CONTROL-M/Server Security database and
assign authorizations for working with CONTROL-M/Server. For
more information, see “Security maintenance utility (Interactive
mode)” on page 245.
Backup Security Exports Security Definition tables. Specify the full path name of the
Definition Tables file. This function can be run only on the CONTROL-M/Server
computer. A message confirming the completion of the export to file
process is displayed. Press <Enter> to return to the Security
Authorization menu.
Restore Security Restores Security Definition tables from a file created using the
Definition Tables Backup Security Definition Tables option of this menu. The
restored definitions override all existing Security Definition tables.

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.

2. Press <Enter> to return to the Security Authorization menu.

Note: Security Definition tables that were generated by the export


utility under CONTROL-M/Server version 2.2.5 can be imported
only using the ctm_restore_aut utility. For more information, see
“Importing security definition tables” on page 264.
Quit Quits the Security Authorization menu and returns to the
CONTROL-M Main Menu.

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.

Parameter Customization Menu


The Parameter Customization Menu is used to view and maintain the various groups
of parameters used by CONTROL-M/Server:

342 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Parameter Customization Menu

Figure 24 Parameter Customization Menu


Parameter Customization Menu
-----------------------------

Select one of the following options:

1 - Basic Communication and Operational Parameters


2 - Advanced Communication and Operational Parameters
3 - System Parameters and Shout Destination Tables
4 - Default Parameters for Communicating with Agent Platforms
5 - Parameters for Communicating with Specific Agent Platforms
6 - Simple Mail Transfer Protocol Parameters

q - Quit

Enter option number ---> []:

Table 103 describes the parameters in the Parameter Customization Menu.

Table 103 Customization parameters


Option Description
Basic Communication and Displays/updates CONTROL-M/Server communication
Operational Parameters and operational parameters configured during the
installation procedure. This option is described below.
Advanced Communication and Displays/updates CONTROL-M/Server communication
Operational Parameters and operational parameters that are available after
installation. This option is described below.
System Parameters and Shout Calls the ctmsys utility to view or update system
Destination Tables parameters and Shout Destination tables. This utility is
described in Chapter 3, “Utilities.”
Default Parameters for Displays/updates the default values of parameters used
Communicating With Agent for communication with agent computers. When
Platforms communicating with an agent computer, these values are
used unless overridden using the option described below.
Parameters for Communicating Displays/updates parameters for communicating with a
With Specific Agent Platforms specific agent computer. This option is used to assign
values other than the default parameter values for a
specific agent computer. This option is described below.
Simple Mail Transfer Protocol Displays/updates Simple Mail Transfer Protocol (SMTP)
Parameters parameters. This option is described below.
Quit Quits the Parameter Customization Menu and returns to
the CONTROL-M Main Menu.

Basic communication and operational parameters


When this option is selected, the current values for Basic Communication parameters
and Operational parameters are displayed.

Chapter 4 Maintenance 343


Parameter Customization Menu

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.

■ To return to the Parameter Customization Menu, specify C.

Advanced communication and operational parameters


When this option is selected, the current values for Advanced Communication
parameters and Operational parameters are displayed.

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.

Default parameters for communicating with agent


computers
When this option is selected, the following menu is displayed. The current value for
each parameter follows the parameter name:

Figure 25 Default Parameters for Communicating with Agent computers menu


Default Parameters for Communicating with Agent computers

1) Polling Interval: 900


2) Communication Timeout: 120
3) Maximum Retries: 12
4) Retry Interval (Unavailable): 90
5) Server-to-Agent Port Number: 7006
6) Communication Protocol Version: 07
7) Check Interval (Available): 7200
8) Unavailability Shout Urgency: R
9) Persistent Connection: N
10) Maximum Concurrent Sessions: 256
11) Allow Agent Disconnection: Y
12) Session Idle Timeout: 900
13) Maximum Disconnect Time: 300

a) Modify all of the above


q) Quit

(All time parameters expressed in seconds)

344 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Parameter Customization Menu

Enter option or item number you wish to change: [q]:

Press Enter to continue

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.

If MAX_CONCURRENT_SESSIONS is set to a number less than the number of


connected sessions, the difference is the number of Agents that will be unavailable.
The NS process adjusts this value over time. To set the number of connected sessions
immediately, restart CONTROL-M/Server. For more information about starting
CONTROL-M/Server manually, see page 311.

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.

Parameters for communicating with specific agent


computers
When this option is selected, the following prompt is displayed:

To view/modify communication parameters,


enter node ID of Agent computer:

1 Specify the node ID of the desired agent computer.

The following menu is displayed. The current value for each parameter follows the
parameter name:

Figure 26 Communication parameters for specific agent computers


Parameters for Communicating with Specific Agent computer (wind)

1) Communication Timeout: 120


2) Maximum Retries: 12
3) Retry Interval (Unavailable): 90
4) Server-to-Agent Port Number: 7006
5) Communication Protocol Version: 07
6) Check Interval (Available): 7200
7) Unavailability Shout Urgency: R

Chapter 4 Maintenance 345


Parameter Customization Menu

8) Persistent Connection: N
9) Allow Agent Disconnection: Y
10) Session Idle Timeout: 900
11) Maximum Disconnect Time: 300

a) Modify all of the above


s) Save agent configuration
q) Quit

(All time parameters expressed in seconds)

Enter option or item number you wish to change: [q]:

Press Enter to continue

2 To modify parameters, specify the number appearing next to the parameter that
you want to change, or specify a to change all the parameters in the menu.

You are prompted for the parameter value(s) as required.

See Chapter 5, “Customization parameters,” for a description of each parameter.

3 It is mandatory to save the modified parameters and to transfer the current


connection configuration to the specified agent. To do this, specify s.

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.

Simple Mail Transfer Protocol Parameters


When this option is selected, the following menu is displayed. The current value for
each SMTP parameter follows the parameter name:

Figure 27 Simple Mail Transfer Protocol Parameters Menu


Simple Mail Transfer Protocol Parameters Menu

1 – SMTP Server (Relay) Name :


2 – Sender Email : CONTROL@M
3 – Port Number : 25
4 – Sender Friendly Name :
5 – Reply–To Email :

346 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Node Group

s) – Save Parameters

q) – Quit

Enter option number ---> []:

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.

Table 104 Options in the SMTP parameters menu


Option Description
SMTP Server (Relay) Name Modify the name of the SMTP server relay.
Valid values: 0 – 50 characters. Default: blank.
Sender Email Modify the e-mail address used by CONTROL-M/Server.
Valid values: 0 – 99 characters. Default: CONTROL@M
Port Number Modify the port number to which the service is assigned.
Valid values: 0 – 65535. Default: 25
Sender Friendly Name Modify the regular text name used to identify the sender.
Valid values: 0 – 99 characters. Default: blank
Reply–To Email E-mail address where e-mail messages are returned if a
return address is not otherwise specified. Valid values: 0 – 99
characters. Default: blank.

Note: If this parameter is blank, when the receiver replies to


the message, the Sender Email e-mail address is used by
default.
Quit Quits the Simple Mail Transfer Protocol Parameters menu
and returns to the CONTROL-M Main Menu.

2 To save the modified parameters, specify s.

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.

Chapter 4 Maintenance 347


View NodeID details option

View NodeID details option


The View NodeID Details option is used to collect and view application server
information of CONTROL-M/Agent computers. Choosing CONTROL-M Main Menu
=> View NodeID Details invokes ctmgetcm as an interactive utility. For a description
of this utility, see “ctmgetcm” on page 162.

Agent Status menu


The Agent Status menu is used to view and update the communication status of
agent and remote host computers. Choosing CONTROL-M Main Menu => Agent Status
displays the following:

Figure 28 Agent Status Menu


Agent Status Menu
-----------------

Select one of the following options:

1 - List Last Known Status of Agents Platform


2 - Change Agent Platform Status to Available
3 - Change Agent Platform Status to Disabled
4 - Delete Agent Platform Entry
5 - Ping Agent Platform
6 - Discover Agent

q - Quit

Enter option number --->

For more information about statuses for agent and remote host computers, see
“Communication status of agents and remote hosts” on page 25.

348 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Agent Status menu

Table 105 Agent Status Menu options


Option Description
List Last Known Status of Prompts for the node ID of a computer, and then displays the
Agents Platform last known status of the computer (Available, Unavailable,
Disabled, or Discovering).
Change Agent Platform Prompts for the node ID of a computer, and then changes the
Status to Available communication status as follows:
■ for regular agent computers, the computer
communication status becomes Available. This causes
the communication status all remote hosts using this
regular agent to be updated.
■ for remote hosts, the computer communication status
becomes Discovery
Change Agent Platform Prompts for the node ID of a computer, and then changes the
Status to Disabled communication status of the computer to Disabled. This
causes the communication status all remote hosts using this
regular agent to be updated.
Delete Agent Platform Entry Displays a list of all computer statuses, and prompts for the
node ID of the computer you want to delete. This causes the
communication status all remote hosts using this regular
agent to be updated.

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.

This option cannot be used to test communication with an


agent computer whose status is Disabled. For more
information, see “ctmping” on page 212.
Discover Agent Prompts for the node ID of a computer, and then pings and
gathers information about the computer. For more
information, see “ctmping” on page 212.
Quit Quits the Agent Status menu and returns to the
CONTROL-M Main Menu.

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.

Chapter 4 Maintenance 349


Troubleshooting menu

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):

Figure 29 Troubleshooting Menu


Troubleshooting Menu
-----------------------------

Select one of the following options:

1 - Set Diagnostics Level 12 - Erase Proclog File


2 - Set Sleep Time 13 - Show Calendar names
3 - Show Processes Flags (prf) 14 - Interactive SQL Commands
4 - Show All Processes (shctm) 15 - Communication Diagnostic Report
5 - Show Communication Environment 16 - Force Download

6 - Restart New Day Procedure 17 - Check directory permissions


7 - Reset CONTROL-M Active Environment 18 - Set communication trace
8 - Truncate Database Log
9 - Troubleshooting Report
10 - Check Kernel Configuration
11 - List Active Transactions

q - Quit

Enter option number ---> []:

Table 106 Troubleshooting Menu options (part 1 of 3)


Option Description
Set Diagnostics Determines the trace level for all CONTROL-M/Server processes, or for any specific
Level process, and for the CONTROL-M/Server Configuration Agent. For more information,
see page 353.
Set Sleep Time Determines the sleep time for all CONTROL-M/Server processes or for any specific
process. For more information, see page 354.
Show Process Displays the status of CONTROL-M/Server processes. For more information, see page
356
Flags (prf)
Show All Processes Displays all CONTROL-M/Server processes currently running. For more information,
(shctm) see page 357.
Show Displays the port numbers used by CONTROL-M/Server to communicate with
Communication CONTROL-M/EM.
Environment

350 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Troubleshooting menu

Table 106 Troubleshooting Menu options (part 2 of 3)


Option Description
Restart New Day Starts the New Day procedure again after confirmation.
Procedure
Reset Clears all components of the CONTROL-M/Server active environment (Active Jobs
CONTROL-M file, prerequisite conditions, and so on) and forces CONTROL-M/Server to start a
Active download of the entire Active Jobs file to CONTROL-M/EM. This option is described
Environment on page 357.
Truncate Database [Sybase and MSSQL] Truncates the CONTROL-M/Server database log. This option
Log should be used if the Sybase message “Can’t allocate space for <text> in database
<name> because the log segment is full” occurs in one of the log files located in
directory $CONTROLM_SERVER/proclog.
Troubleshooting Creates a report containing specified CONTROL-M/Server system information. This
Report option is described in page 354.
Check Kernel [UNIX] Checks whether the current configuration settings of the kernel comply with
Configuration requirements for CONTROL-M/Server. For more information, see the CONTROL-M/
Server for UNIX and Microsoft Windows Installation Guide.

If all parameters are configured correctly, the following message is displayed:

Check kernel configuration for <system> terminated successfully

If one or more parameters are not configured correctly, the parameters are listed
followed by:

Check kernel configuration for <system> terminated unsuccessfully


List Active Lists the active transactions in the database. (A transaction is a unit of work performed
Transactions by CONTROL-M/Server in the database. Each transaction is assigned a unique name.)
You may be asked by technical support to run this option and to provide them with the
output for debugging purposes.
Erase Proclog Files Erases the contents of the current process log file for all active CONTROL-M/Server
processes or for any specific active process.

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.

This option should only be used when requested by Technical Support.

Chapter 4 Maintenance 351


CONTROL-M/Server processes

Table 106 Troubleshooting Menu options (part 3 of 3)


Option Description
Communication Checks parameters and environmental conditions relevant to communication between
Diagnostic Report the CONTROL-M/Server computer and a specific agent computer. This option is
typically used at the request of Technical Support to determine the cause of a
communication problem.

When this option is selected, you are prompted to supply the node ID of an agent
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.

Table 107 Two-Letter codes for CONTROL-M/Server processes


Code Description
SU Supervisor
TR Tracker
SL Selector and submitter
NS Communication with Agent computers
CO Communication gateway
CD New Day procedure, downloads, updates to CONTROL-M/Server database
CS CONTROL-M/EM user requests
LG Utilities invoked from Agent computers
WD Watchdog process
RT Inter-process Communication Router

352 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server processes

Set trace level


Determines the trace level for all CONTROL-M/Server processes, CONTROL-M/
Server Configuration Agent, or for any specific process. If modified while
CONTROL-M/Server is running, the trace level specified is effective immediately.

NOTE
If CONTROL-M/Server is restarted, the trace level for all CONTROL-M/Server processes is
automatically reset to zero.

Prompts similar to the following are displayed:

Enter <diagnostics-level> [0 - 5] : [0]:


Enter Module <module_number> [0,1,2,3] : [1]:
Enter PROCESS NAME [CD,CS,CO,LG,NS,SL,SU,TR,RT,WD,ALL] : []:

Table 108 describes the parameters that are set when responding to these prompts.

Table 108 Diagnostic level parameters (part 1 of 2)


Parameter Description
<diagnostic-level> The trace (diagnostic) level ranges from 0 (no diagnostics) to 5
(highest level of diagnostics). Output from each process is
written to a separate process log file named:

$CONTROLM_SERVER/proclog/
<process-name><process-ID>.log

The variables in this pathname are:


<controlm_path> Home directory of CONTROL-M/
Server account owner.
<process_name> Two-character code identifying the
process.
<process-ID> ID of the CONTROL-M/Server
process.

Chapter 4 Maintenance 353


CONTROL-M/Server processes

Table 108 Diagnostic level parameters (part 2 of 2)


Parameter Description
<module_number> Indicates which components are to be traced for diagnostic
purposes.

Valid values are:

0 – All components.

1 – Common functionality flow. Default.

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.

See “CONTROL-M/Server processes” on page 352, for a


description of the process codes appearing in this prompt.

Set sleep time


Determines the sleep time for all CONTROL-M/Server processes or for any specific
process. The sleep time is the length of time that the process lies dormant before
“waking up” to check if any request to perform an action was received. If modified
while CONTROL-M/Server is running, the sleep time specified becomes effective
immediately. See “Sleep Time Considerations” on page 358.

Prompts similar to the following are displayed:

Enter option number ---> [4]:2


Enter seconds_sleep_time : [30]: 60
Enter PROCESS NAME [CD,CO,LG,NS,SL,SU,TR,RT,WD,ALL] : [CD]:ALL

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.

354 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server processes

The following menu is displayed:

Figure 30 Troubleshooting Report Information


Troubleshooting Report Information
----------------------------------

1) Control-M Active Processes Map: Y


2) Control-M Environment Variables: Y
3) Active Jobs File Statistics: Y
4) System Communication Data: Y
5) Conditions and Resources Maps: Y
6) SU (Supervisor) Logs: Y
7) SL (Selector) Logs: Y
8) TR (Tracker) Logs: Y
9) CD (New Day Procedure) Logs: Y
10) CO (Communication Gateway) Logs: Y
11) CS (Communication with CONTROL-M/EM) Logs: Y
12) LG (Agent Utilities) Logs: Y
13) NS (Communication with Agents) Logs: Y
14) Database Error Log: Y
15) Logs of Failed Jobs within the Last 24 Hours: Y
16) Logs of All Jobs run within the Last 24 Hours: N

R) Generate Troubleshooting Report


Q) Quit

Select item to include/exclude:

To change the information in the report

1 Enter the number of the item to change.

2 Switch the flag from Y to N. The default value for each option is “include all
information”.

3 Enter R to generate the report.

For UNIX

The generated report is compressed and placed in the CONTROL-M/Server user’s


home directory.

For Windows

The generated report is saved in a file named CtmReport.txt and placed in the
data\Temp sub-directory.

Chapter 4 Maintenance 355


CONTROL-M/Server processes

Example

[UNIX]

<controlm_path >/report.<mmddyyhhmm>.tar.Z

The variables are:

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


<mmddyyhhmm> Date and time of report.

Show process flags (prf)


When selected, the Show Process Flags option displays the status of CONTROL-M/
Server processes as recorded in the CONTROL-M/Server database.

A table similar to the following is displayed:

PROCNAME PROCID PROCSTAT PSTAT_REQ SLEEP_TIME DIAG_LVL


CD 21176 R R 60 0
CO 21199 R R 60 0
LG 21178 R R 360 0
NS 21180 R R 30 0
RT 21166 R R 30 0
SL 21182 R R 5 0
SU 21167 R R 60 0
TR 21184 R R 5 0
WD 21185 R R 360 0

The columns in this table are described in Table 109.

Table 109 Columns of the Show Process Flags table


PROCNAME Two-letter code identifying the CONTROL-M/Server process
(described above).
PROCID Process ID of the CONTROL-M/Server process. If this entry is
missing, the process is not currently running.
PROCSTAT and Current statuses of the process. The codes that can appear in these
PSTAT_REQ columns have the following meaning:

■ PROCSTAT—PSTAT_REQ
■ R– RUNNING—R–Run requested
■ T,Z – Terminated—T,Z–Terminate requested
■ S–Suspended—Suspend requested
SLEEP_TIME Current sleep time of the process
DIAG_LVL Current diagnostic level of the process

356 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server processes

Show all processes (shctm)


When selected, the Show All Processes option displays all CONTROL-M/Server
processes currently running on the server computer.

The columns displayed in this list are:

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

Reset CONTROL-M/Server active environment

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):

■ The contents of the Active Jobs file are erased.

■ All prerequisite conditions, Quantitative resources, and Control resources are


deleted.

■ The entire Active Jobs file is downloaded to CONTROL-M/EM.

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.

■ The trace level for all CONTROL-M/Server processes is reset to zero.

Chapter 4 Maintenance 357


CONTROL-M/Server processes

Sleep Time Considerations


The sleep time setting for CONTROL-M/Server processes can affect the functionality
of CONTROL-M/Server and the performance of your data center. Sleep time is the
length of time that a process lies dormant before “waking up” to check if any request
to perform an action was received. When modifying certain CONTROL-M/Server
process sleep time settings, it is important to consider the number of jobs that are
processing, the job schedule plan, and the overall load on the computer.

Table 110 Sleep Time Considerations


Sleep Time
Process Task Initial Settings Sleep TIme Modification Considerations
SU Supervisor 60 Increase: Delay in startup, downloads, and New
Day procedure.
RT Inter-process 30 No effect.
Communication Router
WD Watchdog 360 No effect.
SL Job Selector and job post 5 Increase: Delay in Job Submission and Shout
processing messages for late submission. Can be increased
during period of minimal job processing.
Decrease: Additional CPU resources.
TR Job Tracking 5 Increase: Delay in freeing resources after job ends
and delay in Shout messages. Can be increased
during period of minimal job processing.
Decrease: Additional CPU resources.
NS Communication with 30 No effect.
CONTROL-M/EM
LG Utilities 360 No effect.
Agent
invoker
CO Communication agents 60 No effect.
CD New Day Procedure; 60 No effect.
Database uploads and
downloads
CS N/A No effect.
CA N/A No effect.

358 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Shout destination tables

Shout destination tables


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

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

Example
Figure 31 Directing shouts using the Active Shout Destination Table

■ The system administrator defined two Shout Destination tables, labeled


DAYSHIFT and NIGHTSHIFT. In DAYSHIFT, the logical recipient
SYS_MANAGER is equated to user Susan, who is the daytime systems manager.
In NIGHTSHIFT, the logical recipient SYS_MANAGER is equated to user
Robert, the night-time systems manager.

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

Shout Destination tables are created and maintained using the ctmsys utility
(described in Chapter 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.

Chapter 4 Maintenance 359


Shout message destinations

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

This second method is especially useful. By defining CONTROL-M/Server jobs


that execute the ctmshtb utility at specified times, the active Shout Destination
table designation can be changed automatically according to the schedule that
suits your requirements. ctmshtb is described in Chapter 3, “Utilities.”

Shout message destinations


When using the ctmsys utility to define logical and physical destinations in the Shout
Destination table, you are asked to supply the following information for each
recipient.

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.

Table 111 Shout message destinations (part 1 of 2)


Logical Name Name used in the Shout or Do Shout parameter to identify the recipient
of the Shout message.
Destination Type One-letter code indicating the destination type of the recipient:
U Destination is the user name of a user logged onto the server
computer. If the user is not logged on when a message is sent,
the message is placed in the user’s mail.
M Destination is user mail. See “CONTROL-M/Server e-mail
configuration parameters” on page 397.
T Destination is a specific terminal or file known to the
operating system from which the shout was invoked.
O Destination is the system console.
L Destination is the CONTROL-M/Server log.
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.
E Destination is the Alert window of CONTROL-M/EM.
P Destination is a program. When the shout message is sent,
CONTROL-M/Server invokes the specified program and
sends the shout message as input parameters for that
program.

360 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Shout message destinations

Table 111 Shout message destinations (part 2 of 2)


Address Type For Destination Types U, M, T, P, or O, a one-letter code indicating the
location of the recipient. Valid values:
S Recipient is a user on the server computer.
A Recipient is located on the agent computer where the job that
caused the Shout message was executed.
Physical Name One-letter code indicating the address of the recipient. Values:
U and M User name of the recipient
T Terminal ID or full path name of a file. If the file exists, the
message is appended to the end of the file
P Full path name of the program to be executed.
CONTROL-M/Server sends the following parameters to the
recipient program as input:

<hostname><message> <severity>
O, L, and No physical name is specified because each of these
E destinations is unique.

Sending shout messages from CONTROL-M/Server


CONTROL-M/Server can send a Shout message to an e-mail recipient if the
following requirements are satisfied: [Windows only]

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

— is also the job owner.


— is registered as a CONTROL-M/Server user with the ctmcpt utility.
— can access the network to communicate with the Mail Server.

The default Windows Messaging component (for example, Microsoft Outlook) is


installed and running on the Microsoft Windows Server computer. This component is
not installed by the CONTROL-M/Server installation procedure.

Chapter 4 Maintenance 361


Shout message destinations

362 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Chapter

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.

The following topics are discussed in this chapter:

Categorizing CONTROL-M/Server parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364


Parameter coordination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
System parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Operational parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Agent communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Database parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Mirroring parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Performance parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Configuration parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Parameters that reside in the registry [Windows] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
CONTROL-M/Server environment parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
CONTROL-M/Server communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
CONTROL-M/EM communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
CONTROL-M/Server e-mail configuration parameters . . . . . . . . . . . . . . . . . . . . . . . 397
CONTROL-M/Server Do Remedy parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
User exit parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
CONTROL-M/Server communication and debug parameters . . . . . . . . . . . . . . . . . 401
Watchdog process parameters (config.dat) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

Chapter 5 Customization parameters 363


Categorizing CONTROL-M/Server parameters

Categorizing CONTROL-M/Server parameters


CONTROL-M/Server parameters are divided into the following categories:

■ System parameters
■ Communication parameters
■ Operational parameters
■ Agent Communication parameters
■ Database parameters
■ Mirroring parameters
■ Performance parameters
■ Configuration parameters
■ Watchdog process parameters

CONTROL-M/Agent customization parameters are described in Appendix A of the


CONTROL-M/Agent for UNIX and Microsoft Windows Administrator Guide.

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.

Table 112 Parameter coordination with CONTROL-M/EM


CONTROL-M/Server parameter CONTROL-M/EM parameter Default value
CONTROL-M/EM TCP/IP TCP/IP Port Number 2370
Port Number
Local IP Host Interface Name TCP/IP Host Name Local hostname.

[For UNIX] Hostname returned


by the hostname command.

Table 113 Parameter coordination with Agent computers


CONTROL-M/Agent
CONTROL-M/Server parameter parameter Default value
Agent-to-Server Port Number Agent-to-Server Port 7005
Number
Communication Protocol Communication Protocol TCP

364 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


System parameters

Table 113 Parameter coordination with Agent computers


CONTROL-M/Agent
CONTROL-M/Server parameter parameter Default value
Local IP Host Interface Name Authorized No default value. Specify the
CONTROL-M/Servers Interface Name of the computer
where CONTROL-M/Server is
installed.
Server-to-Agent Port Number Server-to-Agent Port 7006
Number

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

Table 114 System parameters (part 1 of 4)


Parameter Description
Active Shout Currently-active Shout Destination table. Default: SYSTEM
Table
Computer System computer type and model where CONTROL-M/Server is installed (for
example, HP700).
CONTROL-M Date that CONTROL-M/Server regards as the actual working date
Date (Odate). This date is determined using the operating system date and
the value of the Day Time parameter (described above). The format is
yyyymmdd (for example, 20000215). The value is initially set to
00000000 by the installation procedure (for more information, see the
CONTROL-M/Server for UNIX and Microsoft Windows Installation
Guide). The value is then updated by the New Day procedure each time
it runs.
CONTROL-M Version number of the CONTROL-M/Server.
Version
Database Version/ Internal database schema version number (not the Sybase or MSSQL
Schema version number).

Chapter 5 Customization parameters 365


System parameters

Table 114 System parameters (part 2 of 4)


Parameter Description
Day Time * Installation start-of-day time used by CONTROL-M. This is the time at
which the CONTROL-M date (Odate) changes and the New Day
procedure is run. Default: +0700

The Day Time parameter is specified using one of the following


formats:

■ +hhmm CONTROL-M date is changed at the specified time after


midnight.

■ -hhmm CONTROL-M date is changed at the specified time before


midnight.

Time is expressed in 24-hour format (for example, 2200 is equivalent to


10 P.M.). This parameter is commonly set using the +hhmm format.

Example

+0600 Specifies that the hours between midnight and 6:00 A.M. are
considered part of the previous date’s work day (that is, system date
February 10th, 5:59 A.M. is still the CONTROL-M work day February
9th).

-2200 Specifies that the hours between 10 P.M. and midnight are
considered part of the next date’s work day (that is, at 10:00 P.M. on
system date February 10th, the CONTROL-M date changes to February
11th).
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

■ For restricted security (value Y), a user not defined in the


CONTROL-M Security database does not have any application
authorizations.
■ For unrestricted security (value N), a user not defined in the
CONTROL-M Security database is regarded as having all
application authorizations.

A user for whom one or more authorizations have been assigned in the
security database can only perform the actions for which the user is
specifically authorized.
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.

366 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


System parameters

Table 114 System parameters (part 3 of 4)


Parameter Description
Max.Days to Number of days that job SYSOUT files are retained for jobs executed by
Retain agent computers. After this period, all job SYSOUT files are deleted by
Sysout Files * the New Day procedure. Default: 1

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:

■ ENABLED - CONTROL-M/Server works in SSL mode.


■ INACTIVE - CONTROL-M/Server works in non-SSL mode. If
CONTROL-M/Agent is in SSL mode, the server tries to switch that
agent to non-SSL mode.
■ DISABLED - CONTROL-M/Server works in non-SSL mode. If
CONTROL-M/Agent is in SSL mode, the server does not try to
switch that agent to non-SSL mode.

Chapter 5 Customization parameters 367


Ignore new day conditions parameter

Table 114 System parameters (part 4 of 4)


Parameter Description
Start Day of Day of the week on which the work week at your site starts. Valid
the Week * values: 0 (Saturday), 1 (Sunday), …, 6 (Friday). This parameter affects
the usage of the job processing parameter Weekdays (see Chapter 5,
CONTROL-M/Enterprise Manager User Guide). Default: 2 (Monday)
Statistics * Whether or not job statistics should be written to the CONTROL-M/
Server database. Valid values are:

■ Y (record job statistics)

■ N (do not record job statistics).

See “Runtime statistics” on page 48 for more information. Default: Y

Ignore new day conditions parameter


After assigning the new CONTROL-M date, the New Day procedure performs a
selective cleanup of prerequisite conditions. By default, any prerequisite condition
whose reference date (month and day) is equal to the day after the new CONTROL-M
date is deleted. This is done to prevent jobs from being triggered by any prerequisite
conditions remaining from the previous year.

This cleanup function of the New Day procedure can conflict with user intentions
under certain circumstances. For example, if a job processing definition contains the
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.

368 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Ignore new day conditions parameter

The Ignore New Day Conditions parameter can be modified using the ctmsys utility.

When this parameter is set to Y, CONTROL-M searches for a file called:

~<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.)

The mask characters that can be used in this file are:

■ * – Indicates any number of characters (including no characters). Specify ∗ by itself


to signify all existing conditions (see the examples below).
■ ? – Indicates any single character.

You can create and maintain this file using any text editor available at your site. Place
one prerequisite condition prefix on each line in the file.

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:

Chapter 5 Customization parameters 369


Database cleanup actions

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

prq_rs_21rpts 14/01 prq_rs_21rpts 14/01

prq_rs_21rpts 15/01 prq_rs_21rpts 15/01

pre_prn_01 14/01 pre_prn_01 14/01

pre_prn_01 15/01 pre_prn_01 15/01

pre_prn_02 14/01 pre_prn_02 14/01

pre_prn_02 15/01 pre_prn_02 15/01

srt_def_a 14/01 srt_def_a 14/01

srt_def_a1 14/01 srt_def_a1 14/01

srt_def_a 15/01 srt_def_a 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 (*).

No prerequisite conditions will be deleted from the Conditions/Resources table by


the New Day procedure.

Database cleanup actions


The main database cleanup actions take place during New Day procedure on the
Active Jobs file, as well as the log and statistics. When a mirror database is
configured, these cleanups are performed on the mirror database as well.

370 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Secure Sockets Layer (SSL)

The cleanup can be run sequentially or with asynchronous execution.

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

The NEW_DAY_ASYNC_SP_EXECUTION parameter can be modified in the .cshrc


file.

■ When this parameter is set to Y, the cleanup is performed in an asynchronous


way. Default.
■ When this parameter is set to N, the cleanup is performed sequentially.

Secure Sockets Layer (SSL)


If CONTROL-M Option for SSL (Secure Sockets Layer) is installed, the SSL protocol
can provide a secure means for CONTROL-M/Server to communicate with
CONTROL-M/EM and CONTROL-M/Agent. You can enable and disable this
protocol using the Secure Sockets Layer parameter in page 2 of the CONTROL-M
Systems Parameters menu (see Figure 19 on page 288).

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.

Table 115 describes the communication parameters.

Chapter 5 Customization parameters 371


Communication parameters

Table 115 Communication parameters


Parameter Description
Agent-to-Server Port CONTROL-M/Server communicates with CONTROL-M/Agent
Number using two TCP/IP ports. One port is used for data flowing from
CONTROL-M/Server to CONTROL-M/Agent. The other port is
used for data flowing in the reverse direction.

This parameter specifies the port used in the server 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.

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.
Communication Protocol used to communicate with the agent computers. Valid
Protocol value: TCP. The protocol specified here must be the same as that
specified on the agent computer. Default: TCP
EM Gateway Port Port number that is used by CONTROL-M/Server to listen for
communication from CONTROL-M/EM.
IPC port Inter-processing Communication (IPC) port number. [UNIX only]
Local IP Host Host interface name of the TCP/IP network interface card on the
Interface Name server computer to use for communication with CONTROL-M/EM.
This is typically the host name of the server computer. The default
value for this parameter is the default host interface name defined in
the server computer operating environment. This parameter can also
be specified by its IP address (for example, 192.123.186.20). This
parameter should be modified only if the server computer contains
more than one network interface card (for example, Ethernet and
Token-Ring). See additional information about this parameter below.
Configuration Agent {2369}
Port
The CONTROL-M/Server Configuration Agent port number.
Default: 2369

372 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Local IP host interface name parameter

Local IP host interface name parameter


CONTROL-M/Server only listens on one network interface card for messages from
CONTROL-M/EM. If the server computer contains more than one network interface
card, it is necessary to ensure that CONTROL-M/EM is sending messages to the
same interface card listened to by CONTROL-M/Server. This is accomplished by
ensuring that CONTROL-M/Server parameter Local IP Host Interface Name and
CONTROL-M/EM parameter TCP/IP Host Name both refer to the same IP address.

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 operational parameters are described below:

Chapter 5 Customization parameters 373


Operational parameters

Table 116 Operational parameters (part 1 of 2)


Parameter Description
Basic parameters
CONTROL-M/EM CONTROL-M/EM version number.
Release Version
CONTROL-M/EM CONTROL-M communicates with CONTROL-M/EM using a pair
TCP/IP Port Number of consecutive TCP/IP ports (for example, 2370 and 2371). The
lower port is used for data flowing from CONTROL-M to
CONTROL-M/EM. The higher port is used for data flowing in the
reverse direction. Default: 2370

This parameter is used to specify the lower of the two port


numbers and must correspond to the value assigned to field TCP/
IP Port Number in the definition of the CONTROL-M data center
in the CONTROL-M Definition dialog box in the CONTROL-M
Configuration Manager. Verify that the two port numbers are not
used for any other purpose on the server computer. The value for
this parameter must be a number between 1025 and 32767
inclusive.

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.
Inter Process Socket Port number used for communication between
Communication Port CONTROL-M processes. This parameter replaces the Input
Number Mailbox Key and Output Mailbox Key parameters in earlier
versions of CONTROL-M/Server. Default: 6005

All inter- process communication is handled by the RT process.


The value for this parameter must be a number between 1025 and
32767 inclusive.

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.
Advanced parameters
Maximum Job State Number of job state changes retained by
Changes CONTROL-M/Server in the event communication with
CONTROL-M/EM is interrupted. If the number of job state
changes that occur exceeds the value specified for this parameter,
CONTROL-M/Server will initiate a download when
communication with CONTROL-M/EM is resumed. Default: 1000
Maximum Server Maximum number of communication server (CS) processes that
Processes communicate with the CONTROL-M/Server gateway process
concurrently. Default: 2
Minimum Server Minimum number of communication server (CS) processes that
Processes communicate with the CONTROL-M/Server gateway process
concurrently. Default: 2

374 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Agent communication parameters

Table 116 Operational parameters (part 2 of 2)


Parameter Description
Statistics Mode 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 compiles statistics for each CONTROL-M Mem
Name/Mem Lib and Node ID. Default: MEMNAME

Agent communication parameters


Parameters for communicating with agent computers are modifiable during
installation. For more information, see the CONTROL-M/Server for UNIX and
Microsoft Windows Installation Guide. The values specified for these parameters are
used as the default values for communication with each agent computer. Parameter
values for specific agent computers can be modified separately afterwards. You can
also modify these parameters 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.

Table 117 Parameters for communicating with agent computers (part 1 of 3)


Parameter Description
Allow Agent Set the ALLOW_ AG_DISCONNECTION parameter to determine if
Disconnection the current connection to this AGT can be disconnected when
MAX_CONCURRENT_SESSIONS is reached. Valid values are Y and
N. Default: Y
Check Interval Interval (in seconds) between status checks for each CONTROL-M/
Agent that communicates with CONTROL-M/Server. Default: 7200
(2 hours).
Communication Version of CONTROL-M/Agent. Valid values:
Protocol Version
■ 01 – 2.2.4
■ 02 – 2.2.5
■ 03 – 6.0.0x (UNIX or Microsoft Windows using short path names)
■ 05 – 6.0.0x (Microsoft Windows using long path names)
■ 06 – 6.1.0x and 6.2.0x
■ 07 – 6.3.0x

Default: 07

Chapter 5 Customization parameters 375


Agent communication parameters

Table 117 Parameters for communicating with agent computers (part 2 of 3)


Parameter Description
Communication Maximum length of time (in seconds) that CONTROL-M/Server
Timeout should spend attempting to communicate with an agent computer
before assigning it Unavailable status. Default: 120

During this time, CONTROL-M/Server attempts to communicate


with the agent computer x times, where x is the value specified by
parameter Maximum Retries.

Example
If the value of Communication Timeout is 120 and Maximum Retries
is 12, CONTROL-M/Server attempts to communicate with the agent
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.

Once the maximum of the MAX_CONCURRENT_SESSIONS


parameter is reached, the session with the maximum idle time will be
terminated in order to open a new connection. If this agent
connection is marked as not allowed to be disconnected (see the
ALLOW_ AG_DISCONNECTION parameter) then the next one in
line will be disconnected. Valid values: All integers in the range of 16
to the maximum available according to the operating system.
Default: 256
Maximum Sets the maximum time in which the NS allows an agent to be
Disconnect Time disconnected before it will initiate a session with it (although there's
nothing to submit to it). The MAX_DISCONNECT_TIME parameter
is relevant only if the ALLOW_COMM_INIT parameter on the agent
is set to NO. Acceptable values, in seconds, are integers in the range
30 - 86400. Default: 300
Maximum Retries Number of communication retries to attempt in the period of time
specified before assigning the Unavailable status to an agent
computer. Default: 12
Persistent Indicates the persistent connection setting. Set the
Connection PERSISTENT_CONNECTION parameter to connect to a specific
agent with either a persistent or transient connection.

When Persistent Connection is set to Y (for example, with an agent


version 6.2.01), the NS process creates a persistent connection with
the agent and manages the session with this agent. If the connection
is broken with an agent or NS is unable to connect with an agent, the
agent is marked as Unavailable. When the connection with the agent
is resumed, the NS recreates a persistent connection with the agent
and marks the agent as Available.Valid values are: Y or N.

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.

376 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Database parameters

Table 117 Parameters for communicating with agent computers (part 3 of 3)


Parameter Description
Polling Interval Time interval (in seconds) between requests from CONTROL-M/
Server for status updates from agent computers that are executing
jobs. Default: 900
Retry Interval Length of time to wait (in seconds) between attempts to
communicate with an agent computer whose status is Unavailable.
Default: 90
Server-to-Agent Port Port number in the agent computer through which data is received
Number from the server computer. The value assigned to this parameter must
correspond to the value assigned to the Server-to-Agent Port
Number field in the Configuration file on the corresponding agent
computer. Default: 7006

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.
Session Idle Timeout Indicates the maximum time a session can be in idle before NS
terminates it. Acceptable values, in seconds, for the
SESSION_IDLE_TIMEOUT parameter are integers in the range 30 -
86400. Default: 900
Unavailability Shout Indicates messages with a high priority sent from an agent assigned
Urgency Unavailable status. Urgent message are sent with a special
indication so that the recipient of the message is aware of the
urgency. Valid values are: R, U, or V. Default: R

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” on page 378

■ “Oracle” on page 380

■ “MSSQL” on page 382

Chapter 5 Customization parameters 377


Sybase

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

If the database will be located in a file system, the custom script


allocates the amount of space you specify plus an additional 33% to
accommodate the Sybase transaction log. For example, if you specify
60 MB, the amount of space actually allocated is 80 MB.
Database Password (6 to 30 characters, alphanumeric) for the Sybase database
Administrator’s administrator (user sa). The characters you enter are not echoed for
Password security reasons. This password is used by CONTROL-M utilities to
access restricted sections of the CONTROL-M/Server database.
Default: password
DBO Password Sybase password for the CONTROL-M/Server database owner (6 to
30 characters, alphanumeric). The characters you enter are not
echoed for security reasons. This password is used by CONTROL-M
processes and utilities to access the CONTROL-M/Server database.
Default: password
Log Device Type Type of disk storage (raw partition or file system) used for the
CONTROL-M/Server database log. Default: FILE

378 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Sybase

Table 118 Sybase database parameters (part 2 of 2)


Parameter Description
Log Physical Device/ For Log Device Type FILE: Full path name where the CONTROL-M/
Path Name Server database log will be located.
Default:
/<controlm_home_dir>/sybase/data/ctrlm_log.dat

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

If you want Sybase to use a raw partition, type y in response to the


prompt. An additional prompt will be displayed requesting the
physical device name (described below).
Master Physical For Master Device Type FILE: Full path name where the master
Device/Path Name Sybase database will be located.
Default: <controlm_home_dir>/sybase/data/master.dat

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

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.
Remote Sybase Host Name of the host for an existing Sybase Database server installation.
Name
Sybase Interface Directory in which the Sybase interfaces file is located. This path
Directory should be visible to CONTROL-M.
Sybase Server Name Name of the SQL server.

When you choose to modify this value, the custom script reads the
Sybase interfaces file and displays a list of the available SQL servers.
Specify the name of an SQL server from the displayed list (contact
your system administrator for this information). Default: SYBASE

Chapter 5 Customization parameters 379


Oracle

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

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.
CONTROL-M RBS Full path name to the CONTROL-M RBS tablespace file.
(Rollback Segment)
tablespace file location Default: /<controlm_home_dir>/oracle/oradata/
ctrlm/rbs01.dbf
CONTROL-M RBS Size of the CONTROL-M RBS tablespace file. Default: 50 MB
tablespace size
CONTROL-M SYSTEM Full path name to the CONTROL-M SYSTEM tablespace file.
tablespace file location
Default: /<controlm_home_dir>/oracle/oradata/
ctrlm system01.dbf
CONTROL-M SYSTEM Size of the CONTROL-M SYSTEM tablespace file. Default:
tablespace size 50 MB
CONTROL-M TEMP Full path name to the CONTROL-M TEMP tablespace file.
tablespace file location
Default: /<controlm_home_dir>/oracle/oradata/ctrlm
/temp01.dbf
CONTROL-M TEMP Size of the CONTROL-M TEMP tablespace file. Default:
tablespace size 100 MB
Name of the first database Full path name of the first database log file. Default: /
log file <controlm_home_dir>/oracle/oradata/ctrlm/
log01.dbf
Name of the second database Full path name of the second database log file.
log file
Default: /<controlm_home_dir>/oracle/oradata/ctrlm/
log02.dbf

380 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Oracle

Table 119 Oracle database parameters (part 2 of 2)


Parameter Description
Name of the Tablespace data Full path name of CONTROL-M/Server database data file.
file Default:
/<controlm_home_dir>/oracle/oradata/
ctrlmdata.dbf
Oracle CDROM name Name of CDROM device containing the Oracle installation
CDROM.
Oracle home directory Directory where Oracle binary files are stored.

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

Chapter 5 Customization parameters 381


MSSQL

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

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.
System Administrator (SA) Password (6 to 30 alphanumeric characters) for the database
Password administrator (user sa). The characters you enter are not
echoed for security reasons. This password is used by
CONTROL-M/Server utilities to access restricted sections of
the CONTROL-M/Server database.

Default password: password


CONTROL-M/Server Name for the CONTROL-M/Server database. This name
Database Name must be unique. Default: ctrlm
CONTROL-M/Server Database name for the CONTROL-M/Server database
Database Owner owner. The installation script creates this user in the
database. This name is used by CONTROL-M/Server when
accessing its database. Default: ctrlm
CONTROL-M/Server Password for the CONTROL-M/Server database owner (6 to
Database Owner (DBO) 30 alphanumeric characters). The characters you enter are not
Password echoed for security reasons. The first character must be a
letter (A – Z). This password is used by CONTROL-M/
Server processes and utilities to access the
CONTROL-M/Server database. Default: password
Data Device Logical Name Name of the device on which the CONTROL-M/Server
database will be located. Default: ctrlm_ux
Data Device Path Full path name for the CONTROL-M/Server database.
Default: c:\<sql_dir>\data\ctrlm_ux
Data Device Size Amount of space (in MB) to allocate for the data portion of
the CONTROL-M/Server database. Default: 75
Log Device Logical Name Name of the device on which the CONTROL-M/Server
database log will be located. Default: ctrlm_log

382 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Mirroring parameters

Table 120 MSSQL database parameters (part 2 of 2)


Parameter Description
Log Device Location Full path name where the CONTROL-M/Server database log
will be located.

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

Database mirroring parameters are described in Table 121.

Table 121 Mirroring parameters (part 1 of 2)


Parameter Description
CONTROL-M Mirror Name of the Oracle CONTROL-M/Server mirror database. This
tablespace name name must be unique. Default: ctrlm

(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

Note: After specifying this utility, you are prompted to enter


the DBA password to access the CONTROL-M/Server database
server.
CONTROL-M Mirror Name of the Sybase device on which the CONTROL-M/Server
Database Data Device mirror database will be created. (See the disk init command in
Name the Sybase Commands Reference Manual for information about
creating a Sybase device.) Default: ctm
(Sybase)
CONTROL-M Mirror Name of the Sybase device on which the CONTROL-M/Server
Database Log Device mirror database log will be created. (See the disk init command
Name in the Sybase Commands Reference Manual for information
about creating a Sybase device.) Default: ctmlog
(Sybase)

Chapter 5 Customization parameters 383


Mirroring parameters

Table 121 Mirroring parameters (part 2 of 2)


Parameter Description
CONTROL-M Mirror Name of the Sybase device on which the CONTROL-M/Server
database data device mirror database will be created.
name (Sybase)
Default: ctrlm_ux
CONTROL-M Mirror Name of the Sybase device on which the CONTROL-M/Server
database log device name mirror database log will be created. Default: ctrlm_log
(Sybase)
CONTROL-M Mirror Name of the Sybase CONTROL-M/Server mirror database.
database name (Sybase) This name must be unique. Default: ctrlm
DBO Password Password for the CONTROL-M/Server mirror database owner
(6 to 30 characters, alphanumeric). The characters you enter are
(Sybase and Oracle) not echoed for security reasons. This password is used by
CONTROL-M processes and utilities to access the
CONTROL-M mirror database.
Mirror Oracle Instance The name of the Oracle mirror SQL server (1 to 8 characters,
name (SID) alphabetic plus “_”). 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.

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.

384 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Performance parameter

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.

Table 122 Performance parameter


Parameter Description
SL_BREAK_COUNT Counts the number of submitted jobs before jumping to the
beginning of the Active Jobs file list, which is sorted by
performance. If SL_BREAK_COUNT = 0, no break occurs.
Default: 15

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

CONTROL-M/Server configuration parameters


Table 123 describes the CONTROL-M/Server configuration parameters.

Chapter 5 Customization parameters 385


CONTROL-M/Server configuration parameters

Table 123 CONTROL-M/Server configuration parameters (part 1 of 8)


Parameter name {Valid values} Explanation
AGENTS_CLEANUP_IN_ {Y|N}
NEWDAY
■ Y (default) The New Day procedure sends a request to the
CONTROL-M/Agents to remove SYSOUT files and exit
status files that are no longer needed.

■ N The New Day procedure does not send a request to the


CONTROL-M/Agents to remove SYSOUT files and exit
status files that are no longer needed.

Note: You can speed up the New Day procedure by specifying


N for this parameter and running the ctmagcln utility. For more
information, see “ctmagcln” on page 99.
ALARM_DEST Logical name of the Shout destination for critical Alert
messages. Default: EM
AUTOEDIT_INC_SEC {SYSTEM|GLOBAL|GROUP|LOCAL}

Indicates which AutoEdit variables are sent to the agent for


each submitted job.

Valid values:

SYSTEM – All the AutoEdit variables for each submitted job


are sent to the agent. These include System, Global, Group, and
Local variables.

GLOBAL – Global, Group, and Local AutoEdit variables are


sent to the agent for each submitted job. System AutoEdit
variables are not sent.

GROUP – Group and Local AutoEdit variables are sent to the


agent for each submitted job. System and Global variables are
not sent.

LOCAL – Only Local AutoEdit variables are sent to the agent.

Default: LOCAL

386 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server configuration parameters

Table 123 CONTROL-M/Server configuration parameters (part 2 of 8)


Parameter name {Valid values} Explanation
CTM_ADJUST {AJF|GROUP}
_COND_SCOPE
■ AJF – Ignore predecessor jobs in the Active Jobs file level.
When selected, jobs in the Group Scheduling table ignore
conditions set by jobs in the active jobs file that are not
scheduled.
■ GROUP – Ignore predecessor jobs in the group level. When
selected, jobs in the Group Scheduling table ignore
conditions set by jobs in the Group Scheduling table that are
not scheduled. Default.

Note: This parameter is relevant only when ADJUST_COND is


set to Y. For more information, see ADJUST_COND in the
CONTROL-M Job Parameter and Variable Reference Guide.
CTM_CONFIG_AGENT_ The CONTROL-M Configuration Manager issues the message
AGENT_UNAVAIL_ below when the number of unavailable agents is equal to or
THRESHOLD greater than the threshold. Default: 1

"Some of the CONTROL-M/Agents are unavailable."


CTM_CONFIG_AGENT_ {0 - 2}
MODE
Determines the mode of the CONTROL-M/Server
Configuration Agent. Valid values are the integers 0, 1, and 2, as
follows:

■ 0 = OFF_MODE. Disable Configuration Agent process, no


communication with CMS is allowed.
■ 1 = READ_MODE. Only life check and information requests
are honored, any modifying request is rejected.
■ 2 = ALL_MODE. Any CMS request is honored. Default.
CTM_CONFIG_AGENT_ {2369}
PORT_NUMBER
The CONTROL-M/Server Configuration Agent port number.
Default: 2369
CTM_DB_TIMEOUT {300 – 3600}
Timeout value (in seconds) for long New Day database
transactions. Default: 300

Chapter 5 Customization parameters 387


CONTROL-M/Server configuration parameters

Table 123 CONTROL-M/Server configuration parameters (part 3 of 8)


Parameter name {Valid values} Explanation
CTM_GROUP_ {Y|N}
ADJUST_DUMMY
■ Y – a dummy job waits for the prerequisite conditions
expected by the job it is replacing, and performs the post
processing of the job. When a Group Scheduling table is
ordered, jobs in the group that should not be ordered at this
time are ordered as DUMMY jobs. This functionality is
useful for data centers that require identical job flow
regardless of whether certain jobs in a group are ordered for
a specific instance of the group.
■ N – Out conditions of the jobs that were not ordered are
ignored by the ordered jobs in the group scheduling table.
(Default)

Note: This parameter is relevant only when ADJUST_COND is


set to Y. For more information, see ADJUST_COND in the
CONTROL-M Job Parameter and Variable Reference Guide.
CTM_GROUP_ {Y|N}
RECHECK
■ N (default) group conditions are ignored when ordering
specific jobs in a group.

■ Y group conditions are checked for each job in the group (in
addition to conditions specified for the job).

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

ctmorder -schedtab test2...-jobname “*”


-autoedit %%MEMLIB d:/testdir

If you use the same command for a specific jobname, this


parameter is ignored.

388 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server configuration parameters

Table 123 CONTROL-M/Server configuration parameters (part 4 of 8)


Parameter name {Valid values} Explanation
CTM_SEM_KEY_ID {01 – 99}
Value of the semaphore key. BMC Software recommends that
this parameter not be changed, unless there is a conflict. A
conflict occurs if this key is not unique. Change the value of the
key until the conflict is resolved. Default: 75
CTM_SLP_SUSPEND {30 – 1200}
During the New Day Procedure and Download of the Active
Jobs file to CONTROL-M/EM, the ctmcreate, ctmudly, and
ctmorder utilities are suspended. They stay suspended until the
Download or New Day Procedure is complete or until the
specified timeout period. Default: 30 minutes
CTM_SNMP_ {S,M}
SEND_FORMAT Indicates whether Single (S) or Multiple (M) variable format is
used for SNMP traps. For more information, see “ctm2snmp”
on page 120. Default: S
CTM_TIMEZONE_ {Y|N}
DISPLAY
■ N – the Next Run time of a cyclic job is in local computer
time, not adjusted to time zone. Default.

■ Y – the Why on the Next Run time of a cyclic job is adjusted


to the correct time zone.
CTM_WRITE_CONSOLE {YES, NO}
If this parameter is set, critical alerts are sent to the console of
the server in addition to being sent as Shout messages to
CONTROL-M/EM. Default: NO
CTM_WD_ENABLE {YES, NO}
[UNIX only] When CTM_WD_ENABLE is set to YES, the utility
init_prflag creates a prflag file for the WD process.

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

Chapter 5 Customization parameters 389


CONTROL-M/Server configuration parameters

Table 123 CONTROL-M/Server configuration parameters (part 5 of 8)


Parameter name {Valid values} Explanation
CYCLIC_MAXWAIT Indicates when cyclic jobs, that have previously executed at
least once, are removed from the Active Jobs file by the New
Day procedure. Valid values:

■ KEEP – each job is removed when MAXWAIT days have


passed regardless of whether it ended OK. Default.

■ NOT_KEEP – each job is removed by the next New Day


procedure that begins when the job is not executing. If a job
is still in the Active Jobs file when this parameter expires,
the job is changed to non-cyclic and is removed by the next
New Day procedure.
CYCLIC_RERUN {OK, NOTOK}
If a cyclic job ends NOTOK and this parameter is set to OK, the
cyclic job will be rerun. If set to NOTOK, the job will not be
rerun. Default: OK
GD_FORWARD {Y, N}
Indicates if job with a time zone specified should be ordered
according to the current odate, or tomorrow’s odate.

Y – During the New Day Procedure, jobs with a specified time


zone are ordered only if they are scheduled for tomorrow’s
Odate. Default.

N – During the New Day Procedure, jobs with a specified time


zone are ordered only if they are scheduled for the current
Odate.
IOALOG_DEL_INT {1 – 24}
During the New Day procedure, old IOALOG records are
removed. The default is to delete the old records in hourly
bundles. If set to 24, all the old logs are deleted in one bundle.
Default: 1
NEW_DAY_ASYNC_SP_ {Y, N}
EXECUTION [Windows only] Improves the performance of initialize
mirroring.

Y – the cleanup is performed in an asynchronous way. Default.

N – the cleanup is performed sequentially.

390 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server configuration parameters

Table 123 CONTROL-M/Server configuration parameters (part 6 of 8)


Parameter name {Valid values} Explanation
NOT_ORDERED_ {0, 1, 2}
JOB_ALERT
Type of Alert message to send to CONTROL-M/EM when a job
is not ordered due to scheduling criteria.

0 – One General Alert per User Daily: ONE OR MORE JOBS IN


DAILY <daily_name> WERE NOT ORDERED (Default)

1 – One Alert message per job: DAILY <daily_name> FAILED


TO ORDER JOBNAME <jobname>

2 – Do not issue Alert messages


RUNINF_CUTOFF_ {0-65K}
NUMBER
Affects the statistics cleanup algorithm that is performed during
New Day when the RUNINF_PURGE_MODE is set to 0
(default). If the number of records to be deleted from the table is
less than the value of this parameter, then records are deleted
directly from the statistics table, otherwise a temporary table is
used to delete the records. Default: 2000
RUNINF_CUTOFF_ {decimal fraction between 0-1}
RATIO
Affects the statistics cleanup algorithm that is performed during
New Day when the RUNINF_PURGE_MODE is set to 0
(default). If the ratio between the number of records to be
deleted, and the number of records in the table is less than the
value of this parameter, then records are deleted directly from
the statistics table, otherwise a temporary table is used to delete
the records. Default: 0.33
RUNINF_PURGE_LIMIT {1 – 65K}
Number of Run Information records to keep for a given
MemName/MemLib/NodeID. If RUNINF_PURGE_MODE is
0, the New Day Procedure deletes all Run Information records
for each unique name except the last n records, where n is the
value of this parameter. Default: 20

Chapter 5 Customization parameters 391


CONTROL-M/Server configuration parameters

Table 123 CONTROL-M/Server configuration parameters (part 7 of 8)


Parameter name {Valid values} Explanation
RUNINF_PURGE_MODE {0, 1}

0 – Performs -PURGE cleanup. Statistics records per job are kept


according to the specified Statistics Mode (either MEMNAME
or JOBNAME). Default: 20 records of each MEMNAME or
JOBNAME are kept.

If the RUNINF_PURGE_LIMIT in the config.dat is specified,


the number of records that are kept is determined by this
parameter.

1 – Performs -DELETE cleanup. Only the amount of days that


are specified are kept. Default: The number of days kept is
specified by the How Many Days to Retain ioalog parameter.

If the RUNINF_PURGE_LIMIT in the config.dat is specified,


the number of days that are kept is determined by this
parameter.
STATISTICS_CLEANUP_ {Y|N}
IN_NEWDAY
■ Y (default) – The statistics cleanup action is executed during
New Day procedure.

■ N – The statistics cleanup action is not executed during


New Day procedure.

Note: You can speed up the New Day procedure by specifying


N for this parameter and running ctmruninf -PURGE. For more
information, see “ctmruninf” on page 240.
STATS_TIME Indicates how the START TIME and END TIME for a job should
be set. Valid values are:

■ SERVER – START TIME and END TIME are set by


CONTROL-M/Server. Default.

■ AGENT – START TIME and END TIME are set using


information received from the CONTROL-M/Agent.
SYSOUT_LIMIT_SIZE Maximum SYSOUT size that can be viewed by the sysout
command from CONTROL-M/Server and CONTROL-M/EM.
The value is set in Kilobytes. Default: 0 (unlimited)

If a SYSOUT file exceeds the value specified by the


SYSOUT_LIMIT_SIZE configuration parameter, it cannot be
viewed from CONTROL-M/Server or CONTROL-M/EM, and
the following message is displayed:

SYSOUT FILE EXCEEDED LIMIT SIZE (CAN BE VIEWED


FROM FILE SYSTEM)

392 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server configuration parameters

Table 123 CONTROL-M/Server configuration parameters (part 8 of 8)


Parameter name {Valid values} Explanation
SYSOUT_WINDOW_ Specifies the length of the SYSOUT line. Valid values for the
SIZE length of the line is: 80–132 characters
UDLY_PARTCOPY_ERR Error code to return if one or more jobs in a scheduling table are
not ordered by a User Daily job (due to scheduling criteria or
security settings).

■ 0 (default) – User Daily job ends with an exit code of 0 even


if not all jobs are ordered.

■ 1 – User Daily job ends with an exit code of 14 if not all jobs
are ordered.

Chapter 5 Customization parameters 393


Parameters that reside in the registry [Windows]

Parameters that reside in the registry


[Windows]
To modify a parameter that resides in the registry, ensure that CONTROL-M/Server
is running. Change the parameter using regedit or through a utility, for example,
ctm_menu. When you have modified the parameter, shut CONTROL-M/Server and
then restart it for the change to take effect.

For parameters on a cluster environment, the Cluster Administrator must be used to


start and stop CONTROL-M/Server. For more information, see the CONTROL-M on
UNIX Clusters and CONTROL-M on Windows Clusters guides.

Example

Assume that the value of the Local IP Host Interface Name parameter must be
modified.

The steps are:

1 Ensure that CONTROL-M/Server is working.

2 Modify the value of the Local IP Host Interface Name parameter using either
regedit or ctm_menu.

3 Shut down CONTROL-M/Server.

4 Start CONTROL-M/Server.

394 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server environment parameter

CONTROL-M/Server environment parameter


Table 124 describes the CONTROL-M/Server environment parameter.

Table 124 CONTROL-M/Server environment parameter


Parameter name {Valid values} Explanation
DO_NOT_COPY_LOG_ {YES, NO}
TO_MIRROR This parameter improves the performance of initialize mirroring.
When set to YES, the CONTROL-M/Server log is truncated on
the secondary database when mirroring is initialized. When
restoring from the mirror, the log is truncated in the primary
database. CONTROL-M/Server log is not copied during
initializing or restoring from mirroring. Default: NO

NOTE
To set parameters described in Table 124 to the specified value permanently, update the ~/
.cshrc file and re-logon to CONTROL-M/Server.

Chapter 5 Customization parameters 395


CONTROL-M/Server communication parameters

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.

CONTROL-M/EM communication parameters


Table 126 CONTROL-M/EM communication parameters
Parameter name {Valid values} Explanation
CTM_PRM_KPA {Y, N}
_ACTIVE Indicates whether the Heartbeat monitor operates in active (Y) or
passive (N) mode. Default: Y (Active)
CTM_PRM_KPA {n}
_BETWEEN_MSGS Time in seconds between heartbeat checks. Default: 300
CTM_PRM_KPA {n}
_ROUNDTRIP Time in seconds to wait for a confirmation from CONTROL-M/EM.
_TIMEOUT If confirmation does not arrive, a timeout is generated and the
connection is severed. Default: 300

For more information, see “Heartbeat monitor” on page 62.

396 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server e-mail configuration parameters

CONTROL-M/Server e-mail configuration


parameters
The following parameters are applicable to DOMAIL, -DOSHOUT (when shout
destination is mail), ctmshout, and –SHOUT (when shout destination is mail).

NOTE
The SYSOUT of a job can be attached to an e-mail message only if the job has completed
processing.

Table 127 E-mail configuration parameters (part 1 of 2)


Parameters Description
ADD_SYSOUT_TO_EMAIL Determines whether the SYSOUT of a job can be attached
to e-mail messages. Valid values:

■ N – No. When specified, the SYSOUT of a job is not


attached. This setting overrides any specification made
elsewhere. Default.

■ A – Attachment. When specified, the SYSOUT of a job


is attached. This setting overrides any specification
made elsewhere.

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.
ADD_SYSOUT_TO_EMAIL_ Determines the maximum size of the attachment SYSOUT
LIMIT_SIZE file in kilobytes. You can specify the value 0 for unlimited
size. Default: 5120KB (5MB)

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.

Chapter 5 Customization parameters 397


CONTROL-M/Server Do Remedy parameters

Table 127 E-mail configuration parameters (part 2 of 2)


Parameters Description
ADD_SYSOUT_TO_EMAIL_ Determines the maximum time to receive SYSOUT from
TIMEOUT_LIMIT CONTROL-M/Agent and to send the mail request to the
SMTP server with the SYSOUT attached. Valid values:
From 1 to 300 seconds. Default: 30 seconds

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.
MAIL_ADD_SUBJECT_PREFIX Determines if the CONTROL-M/Server Shout by orderno
prefix must be added to the subject of the e-mail message.
Default: Y
MAIL_TIMEOUT Determines the maximum time to send the mail request to
the SMTP server when no SYSOUT is attached. Valid
values: from 1 to 30 seconds. Default: 5 seconds

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.

CONTROL-M/Server Do Remedy parameters


Problem tickets can be opened in the Remedy Helpdesk System when specified ON
statement criteria are satisfied. Table 128 lists the modifiable Do Remedy
configuration parameters.

To close a Remedy help case, users must have both Administrator and Administrator
Problem Management permissions.

Table 128 Do Remedy configuration parameters (part 1 of 2)


Parameters Description
REMEDY_USER_NAME User name to access the AR Server. Mandatory.
Default: Demo
REMEDY_SERVER_NAME The Remedy AR Server hostname. Mandatory.
Default: localhost
REMEDY_PORT_NUMBER Port number to which the Remedy AR Server is
assigned. Default: 0
REMEDY_CATEGORY_NAME Name of the category used in the help ticket created
for the specified event. Default: IT Services
REMEDY_TYPE Description of the type used in the help ticket
created for the specified event. Default: Other

398 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server Do Remedy parameters

Table 128 Do Remedy configuration parameters (part 2 of 2)


Parameters Description
REMEDY_ITEM Description of the item in the help ticket created for
the specified event. Default: Other
REMEDY_REQUESTER_NAME Name of the user who is creating a Remedy ticket.
Default: Demo
REMEDY_REQUESTER_LOGIN Login name of the user who is creating a Remedy
ticket. Default: Demo
REMEDY_SCHEMA Name for the Remedy schema. The name must
begin with a letter (A-Z, a-z) followed by up to 7
alpha-numeric characters (including underscores).
Default: HPD:HelpDesk
REMEDY_OPEN_TICKET_STATUS Status of the help ticket created for the specified
event. Valid values are:

■ New (Default)
■ Assigned
■ Work In Progress
■ Pending

Note: When the value of this configuration


parameter is New, the ticket is opened according to
the Remedy default value.
REMEDY_CLOSE_TICKET_STATUS Status of the help ticket created for the specified
event. Default: Resolved and Closed
REMEDY_DEFAULT_URGENCY Specifies the default urgency of a Remedy help
ticket, if a DOREMEDY statement opens a Help
Desk ticket with the Urgency value Clear. Valid
values are:

■ 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

Chapter 5 Customization parameters 399


User exit parameters

User exit parameters


Table 129 User exit parameters
Parameter name {Valid values} Explanation
CTM_PRM_ENABLE_UE {Y, N}
Indicates whether CONTROL-M user exits and Watchdog
process exits are enabled.
(See “Watchdog process parameters (config.dat)” on page
401.) Default: Y
CTM_PRM_ENABLE_ {Y, N}
UExxx (101-106) Indicates whether the associated UExxx user exit is enabled.
For more information, see “User exits” on page 74. Default: N
The following user exits are available:

■ UE101 Job Ordering User Exit

■ UE102 Job Submission User Exit

■ UE103 Before New Day Procedure User Exit

■ UE104 After New Day Procedure User Exit

■ UE105 Before User Daily User Exit

■ UE106 After User Daily User Exit


CTM_PRM_SCRIPT_ Name of the Uexxx user exit script. These scripts must reside
UExxx in the ~<controlm_owner>/ctm_server/ue_exit directory.
Default: ctm_exitxxx.sh
CTM_PRM_TIMEOUT_ {n}
UExxx Time to wait for a user exit script to run before it is
terminated. Default: 20

For UNIX: Time is measured in units of seconds

For Windows: Time is measured in units of milliseconds

400 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server communication and debug parameters

CONTROL-M/Server communication and debug


parameters
Table 130 CONTROL-M/Server communication and debug parameters
Parameter name {Valid values} Explanation
COMTIMOUT {20-360}
Communication timeout in seconds. Default: 130
COMTRYNO {1-20}
Communication retry value. Default: 5
DEBUG_LEVEL CONTROL-M debug level. Valid range: 0 - 4 (0 = only
critical messages are displayed).
MAX_GET_HOST_RETRIES {1 - 2048}
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.
PROTOCOL {TCP}
Communication protocol. Default: TCP

Watchdog process parameters (config.dat)


The following parameters are used for the Watchdog Process. (For more information,
see “Watchdog facility” on page 69.) The CTM_PRM_ENABLE_UE parameter must be
set to Y to enable the WD process.

The Watchdog Process parameters discussed in this section are:

■ General parameters
■ CONTROL-M/Server system exit parameters
■ Watchdog user exit parameters

Chapter 5 Customization parameters 401


General 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

402 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


CONTROL-M/Server system exit parameters

Table 131 General Watchdog Process parameters (part 2 of 2)


Parameter name {Valid values} Explanation
WD_INTERVAL {n}
Basic time unit interval, in minutes. When the value in either
the WD_CTMEXIT_# _INTERVAL parameter or the
WD_CTMEXIT_# _INTERVAL parameter is multiplied by the
value in this parameter, the resulting value is the number of
minutes that must pass before reinvoking the exit script.

For example, if the value of this parameter is 6 (minutes), and


the value of the WD_CTMEXIT_1_INTERVAL parameter is 20,
the script for system exit 1 will run once every 120 minutes (20 x
6 minutes). Default: 6
WD_USEREXIT_ {n}
NUMBER Total number of user exits to run. Default: 0

CONTROL-M/Server system exit parameters


The # used in each of the following CONTROL-M/Server system exit parameters
represents the corresponding CONTROL-M/Server utility that can be included in the
CONTROL-M/Server Watchdog process: Disk Space Utility (1) and Database Usage
Utility (2). See “ctmdiskspace” on page 146 and “ctmdbspace” on page 133 for more
information.

Table 132 Watchdog parameters for CONTROL-M/Server system exits (part 1 of 2)


Parameter name {Valid values} Explanation
WD_CTMEXIT_# _CMD_LINE Arguments to be passed to the utility. Arguments
must start with a ‘-’ sign. Values separated by
either a space or a ‘-’ sign must be enclosed in
double quotation. Mandatory.
Default for # 1: -Limit 10M -Path $HOME
Default for # 2: -Limit 90
WD_CTMEXIT_# _ERROR_MSG Error message string to be passed to the error
handler(s) if the utility returns a “failed” status.
Optional.

Chapter 5 Customization parameters 403


Watchdog user exit parameters

Table 132 Watchdog parameters for CONTROL-M/Server system exits (part 2 of 2)


Parameter name {Valid values} Explanation
WD_CTMEXIT_# _INTERVAL Number of basic time interval units that should
pass before reinvoking the exit script. The basic
time interval unit is defined in parameter
WD_INTERVAL.

For example, if the value of this parameter is 20,


and the basic time interval unit (as defined in
parameter WD_INTERVAL) is 5 minutes, the exit
script will be invoked every 100 minutes (20 x 5
minutes).

Range: 1-1440. Default: 20


WD_CTMEXIT_# _RUN_STATE {Y, N}
Specify whether (Y) or not (N) to run the utility in
Run (that is, normal) mode.
A Y must be specified for either this parameter or
for parameter WD_CTMEXIT_# _SUSPEND
_STATE for the utility to be run. Default: N
WD_CTMEXIT_# _SCRIPT_FILE Relative path of the executable file from the
~controlm\ctm_server\exe_<computer>
directory.
Default for # 1: CTMDISKSPACE
Default for # 2: CTMDBSPACE
WD_CTMEXIT_# _SUSPEND_STATE {Y, N}
Specify whether (Y) or not (N) to run the utility in
Suspend mode (that is, during New Day procedure
or download, when the database inaccessible). A Y
must be specified for either this parameter or for
parameter WD_CTMEXIT_# _RUN _STATE for the
utility to be run. Default: N
WD_CTMEXIT_# _TIMEOUT {n}
Maximum time (in seconds) that the utility is
allowed to run. If the utility runs longer than the
time indicated, it will terminate and an error
message will be sent. Mandatory. Default: 5
seconds

Watchdog user exit parameters


The # used in the following user exit parameters represents a separate number for
each user exit that can be included in the CONTROL-M Watchdog process (see
“Watchdog facility” on page 69). A user exit can be either a user supplied script/
executable file or a CONTROL-M utility (see Chapter 3, “Utilities”).

404 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Watchdog user exit parameters

Table 133 Watchdog parameters user exit


Parameter name {Valid values} Explanation
WD_USEREXIT_# _CMD_LINE Arguments to be passed to the script/executable
file. Arguments must start with a ‘-’ sign. Values
separated by either a space or a ‘-’ sign must be
enclosed in double quotation. Optional.
WD_USEREXIT_# _ERROR_MSG Error message string to be passed to the error
handler(s) if the check returns a “failed” status.
Optional.
WD_USEREXIT_# _INTERVAL Number of basic time interval units that should
pass before reinvoking the exit script. The basic
time interval unit is defined in parameter
WD_INTERVAL.

For example, if the value of this parameter is 2, and


the basic time interval unit (as defined in parameter
WD_INTERVAL) is 5 minutes, the exit script will be
invoked every 10 minutes (2 x 5 minutes). Default: 2
WD_USEREXIT_# _RUN_STATE {Y, N}
Specify whether (Y) or not (N) to run the script in
Run (that is, normal) mode. This parameter or
WD_CTMEXIT_# _SUSPEND _STATE must be set
to Y for the script to be run. Default: N
WD_USEREXIT_# _SCRIPT_FILE Full path of the user script/executable file.
Mandatory. Example:
~controlm\ctm\exe_<computer>\ctm_ping_list
WD_USEREXIT_# _SUSPEND_ {Y, N}
STATE Specify whether (Y) or not (N) to run the script in
Suspend mode (that is, during New Day procedure
or download, when the database inaccessible). This
parameter or WD_CTMEXIT_# _RUN _STATE
must be set to Y for the script to be run. Default: N
WD_USEREXIT_# _TIMEOUT {n}
Maximum time in seconds that the script is allowed
to run. If the script runs longer than the time
indicated, it will terminate and an error message
will be sent. Mandatory. Default: 5

Chapter 5 Customization parameters 405


Watchdog user exit parameters

406 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Chapter

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.

To enable user exits in the CONTROL-M/Server system

■ For UNIX

All user-defined exit scripts must be located in the ~<controlm_owner>/


ctm_server/ue_exit directory and have default file names in the format
ctm_exitxxx.sh, where xxx is the exit number.

■ For Windows

Specify Y for parameter CTM_PRM_ENABLE_UE in the config.dat file.

Table 134 describes the available CONTROL-M user exits.

Table 134 CONTROL-M General User Exits (part 1 of 2)


User Exit Description
CTMUE101 Job Ordering User Exit – executed for each CONTROL-M job before it
is ordered. For more information, see “Job Order Exit (CTMUE101)”
on page 410.
CTMUE102 Job Submission User Exit – executed for each CONTROL-M job
before it is submitted for execution. For more information, see “Job
Submission Exit (CTMUE102)” on page 412.

Chapter 6 User Exits 407


Table 134 CONTROL-M General User Exits (part 2 of 2)
User Exit Description
CTMUE103 Before New Day Procedure User Exit – executed before the New Day
procedure is run.
For more information, see “Before New Day Procedure Exit
(CTMUE103)” on page 413.
CTMUE104 After New Day Procedure User Exit – executed after the New Day
procedure is run. For more information, see “After New Day
Procedure Exit (CTMUE104)” on page 414.
CTMUE105 Before User Daily User Exit – executed before each run of a
CONTROL-M User Daily job (except SYSTEM).

For more information, see “Before User Daily Exit (CTMUE105)” on


page 414.
CTMUE106 After User Daily User Exit – executed after each run of a
CONTROL-M User Daily job (except SYSTEM).

For more information, see “After User Daily Exit (CTMUE106)” on


page 414.

NOTE
A special category of user exits can be defined for the Watchdog facility. For more
information, see “Watchdog facility” on page 69.

408 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Configuring CONTROL-M Exits

Configuring CONTROL-M Exits


To enable CONTROL-M exits, you must specify Y for parameter
CTM_PRM_ENABLE_UE in the config.dat file. Certain other parameters are used to
enable and disable specific exits.

Some of these parameters are described in Table 135. For more information, see
Chapter 5, “Customization parameters.”

Table 135 Exit Configuration parameters


Valid
Parameter name values Description
CTM_PRM_ENABLE_UE {Y, N} Indicates whether or not CONTROL-M user exits are
enabled. This parameter must be set to Y to enable all user
exits. Default: Y
CTM_PRM_ENABLE_UExxx {Y, N} Indicates whether or not the Associated UExxx user exit is
enabled (where xxx = 101-106).

■ UE101 Job Ordering User Exit

■ UE102 Job Submission User Exit

■ UE103 Before New Day Procedure User Exit

■ UE104 After New Day Procedure User Exit

■ UE105 Before User Daily User Exit

■ UE106 After User Daily User Exit

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

For UNIX: Time is measured in units of seconds

For Windows: Time is measured in units of milliseconds

Chapter 6 User Exits 409


User Exit workflow

User Exit workflow


Each user exit is triggered at a specific point in CONTROL-M processing. The
following steps illustrate what happens when an exit has been enabled.

NOTE
User exits are implemented only if they have been enabled by setting the appropriate
configuration parameters (described in Table 135 on page 409).

1. A flat text file is produced containing parameters to be processed by


CONTROL-M.

2. The name of the text file is passed as the $1 parameter to the user exit script in the
ue_exit directory.

3. The user exit script is run. This script is often used to modify the contents of the
text file. However, it can also be used to perform any other action (for example, to
copy information from the text file to another location).

4. CONTROL-M continues processing using the modified text file.

Job Order Exit (CTMUE101)


This exit is executed for each CONTROL-M job before it is ordered. The flat text file
passed to the exit is a job record from the Scheduling definition table. User exit
CTMUE101 can be used to alter the job information in this file after it is fetched from
the database and before it is passed to the procedure that determines if the job will be
ordered for the current day.

The following is a sample text file in the format that is passed to the CTMUE101 exit:

JOBNAME daily_job
JOBNO 30
DESCRIPT
APPLIC STRESS
APPLGROUP STRESS
SCHEDTAB STRESS
AUTHOR ctm600
OWNER ctm600
PRIORITY 0
CRITICAL N
CYCLIC N
RETRO N

410 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Job Order Exit (CTMUE101)

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

Chapter 6 User Exits 411


Job Submission Exit (CTMUE102)

Job Submission Exit (CTMUE102)


This exit is executed for each CONTROL-M job before it is submitted for execution.
The flat text file passed to the exit contains a job record from the Active Job File table.
User exit CTMUE102 can be used to alter job information in this record before it is
passed to the CONTROL-M/Agent for job submission.

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

412 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Before New Day Procedure Exit (CTMUE103)

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

Before New Day Procedure Exit (CTMUE103)


This exit is executed before the New Day procedure is run. The New Day Procedure
performs automatic functions at the beginning of each new CONTROL-M working
day. This procedure is used as a master scheduler for all CONTROL-M activities. For
more information, see “New Day procedure” on page 42.

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

Chapter 6 User Exits 413


After New Day Procedure Exit (CTMUE104)

After New Day Procedure Exit (CTMUE104)


This exit is executed after each run of the CONTROL-M New Day procedure. The flat
text file that is passed to the exit contains the name of the Daily (SYSTEM), time, and
original scheduling date (Odate) of the procedure.

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

Before User Daily Exit (CTMUE105)


This exit is executed before each CONTROL-M User Daily job (except SYSTEM) is
run. User Daily jobs can be used to order new jobs. For more information, see “User
Daily jobs” on page 37.

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

After User Daily Exit (CTMUE106)


This exit is executed after each CONTROL-M User Daily job (except SYSTEM) is run.
User Daily jobs can be used to order new jobs. For more information, see “User Daily
jobs” on page 37.

414 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


After User Daily Exit (CTMUE106)

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.

Chapter 6 User Exits 415


After User Daily Exit (CTMUE106)

416 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Chapter

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 - a database on an independent database server mirrors the


CONTROL-M/Server database. If this level of failover is implemented, only
CONTROL-M/Server database is backed-up and will be available in case of loss.
There is no failover support for any loss of information affecting the
CONTROL-M/Server installation.

■ Failover Server - a secondary CONTROL-M/Server installation on a different


computer. The CONTROL-M/Server database of the secondary installation is
considered the mirror database. If this level of failover is implemented, failover
support is provided for loss of information affecting both the CONTROL-M/
Server installation and the CONTROL-M/Server database.

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.

Chapter 7 Mirroring and Failover 417


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.

Figure 32 Database Mirroring

If the CONTROL-M/Server primary database server fails, or if the primary database


loses integrity, CONTROL-M/Server operation can be restored using either of the
following manual interventions:

■ You can direct CONTROL-M/Server to use the mirror database instead of the
primary database. The primary CONTROL-M/Server database can be rebuilt
when time allows.

This method ensures that CONTROL-M/Server functionality is resumed as soon


as possible. However, mirroring is not resumed until after you repair the failed
primary database and restore it from the mirror database.

■ You can repair and rebuild the CONTROL-M/Server primary database and
restore it from the mirror database.

This method allows mirroring of the CONTROL-M/Server database to continue


without interruption. However, depending on database size and the cause of the
failure of the database, it may take some time to rebuild the CONTROL-M/Server
database before CONTROL-M/Server can be restarted.

Implementing a mirror database


Database mirroring can be initialized any time after CONTROL-M/Server has been
installed.

The mirror database should be built on a separate database server, independent of the
database server that hosts the primary CONTROL-M/Server database.

Several administrative functions are used to initialize, enable, and restore


CONTROL-M/Server database mirroring. 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.)

418 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Preparing a mirror CONTROL-M/Server database on a Sybase server

For a description of database failover, recovery, and restoration procedures, see


“Recovering from database failure” on page 447.

■ Requirements and preparatory steps for a mirror database on a Sybase database


server are described in “Preparing a mirror CONTROL-M/Server database on a
Sybase server” on page 419.

■ Requirements and preparatory steps for a mirror database on an Oracle database


server are described in “Preparing a mirror CONTROL-M/Server database on an
Oracle server” on page 421.

■ Requirements and preparatory steps for a mirror database on an MSSQL database


server are described in “Preparing a mirror CONTROL-M/Server database on an
MSSQL server” on page 422.

Preparing a mirror CONTROL-M/Server database on a Sybase


server
To prepare the mirror database, verify the requirements listed here, and perform the
specified configuration steps.

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.

3 Determine the following parameter values:

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

Chapter 7 Mirroring and Failover 419


Preparing a mirror CONTROL-M/Server database on a Sybase server

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.

4 The following details are needed to implement the mirror database:

Details required Description


A database name and a The database name can be the same as the database owner
database owner (DBO) name name, but the database name and database owner name
for the mirror database. must each be unique for a particular Sybase SQL Server.
Therefore, when selecting names for the CONTROL-M/
Server database (using an existing Sybase SQL Server), verify
that the database name and database owner name are unique
for the Sybase SQL Server.
UNIX system paths or raw These paths must be unique.
partitions for the data and log
files.
Sybase device names for the These names must be unique for the database server. Use the
data and log database Sybase sp_helpdevice command to view existing devices on
devices. the database server when building the database.

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.

420 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Preparing a mirror CONTROL-M/Server database on an Oracle server

Preparing a mirror CONTROL-M/Server database on an Oracle


server
To prepare the mirror database, verify the requirements listed here, and perform the
specified configuration steps.

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.

3 Determine the following parameter values:

■ Oracle SID - Server ID of the secondary database server.

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

Chapter 7 Mirroring and Failover 421


Preparing a mirror CONTROL-M/Server database on an MSSQL server

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

Preparing a mirror CONTROL-M/Server database on an MSSQL


server
To prepare the mirror database, verify the requirements listed here, and perform the
specified configuration steps.

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.

4 The following details are needed to implement the mirror database:

Details required Description


A database name and a The database name can be the same as the database owner
database owner (DBO) name name, but the database name and database owner name
for the mirror database. must each be unique for a particular MSSQL Server.
Therefore, when selecting names for the CONTROL-M/
Server database (using an existing MSSQL Server), verify
that the database name and database owner name are unique
for the MSSQL Server.
System path names for the These paths must be unique.
data and log files.
MSSQL device names for the These names must be unique for the database server.
data and log database
devices.

If you will be building a database, you must supply values for the database owner,
database name, devices and file or partition paths:

422 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Failover Server

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

The secondary CONTROL-M/Server, including its database, acts as a backup to the


primary CONTROL-M/Server. This secondary CONTROL-M/Server computer is
sometimes called the Mirror Environment.

The secondary CONTROL-M/Server duplicates all of the primary CONTROL-M/


Server’s links to CONTROL-M/Agents, and CONTROL-M/Server Configuration
Agent. The secondary CONTROL-M/Server is defined in each agent’s list of
authorized server hosts.

Figure 33 Server computer Failover - Primary Environment and Mirror Environment

Chapter 7 Mirroring and Failover 423


Failover Server

During normal operation, the secondary database is constantly updated to remain


identical with the primary database. The secondary CONTROL-M/Server remains
inactive.

If the primary CONTROL-M/Server fails due to a hardware/software problem on


the primary computer, the administrator activates failover on the secondary
CONTROL-M/Server. The secondary CONTROL-M/Server performs all normal
CONTROL-M/Server functions until the primary CONTROL-M/Server is repaired.

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.

When the primary CONTROL-M/Server is stable, normal operation is restored. The


failover server is shut down, the primary database is restored, and the primary
CONTROL-M/Server is restarted. The secondary server returns to passive readiness.

Implementing a Failover Server


A failover server can be implemented any time after CONTROL-M/Server has been
installed.

The secondary CONTROL-M/Server installation should be built on a separate


computer and database server, independent of the computers that host the primary
CONTROL-M/Server and its database.

Requirements and preparatory steps for the failover server are described in
“Preparing a failover server” 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.)

For a description of server failover, recovery, and restoration procedures, see


“Recovering from primary CONTROL-M/Server failure (Server failover)” on page
450.

Preparing a failover server


Install CONTROL-M/Server on the secondary, failover computer using the standard
installation procedures described in the CONTROL-M/Server and CONTROL-M/Agent
Installation Guide. Verify the following conditions for the secondary installation:

424 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Failover Server

■ The Agent-to-Server Port Number and Server-to-Agent Port Number


communication parameters must be the same on both CONTROL-M/Server
computers. These ports must also be dedicated to the use of CONTROL-M/
Server. You should also ensure that both computers are using the same date.

■ The failover server can be configured to use a dedicated or a non-dedicated SQL


database server. However, it should not use the same instance of the database
server used by the primary environment.

■ The Database (Data Portion) Size parameter should be assigned the same value
as the current size of the primary database.

■ All agent computers that are defined on the primary CONTROL-M/Server


should also be defined on the failover server. These definitions must be
identical. If you installed CONTROL-M/Agent on the primary CONTROL-M/
Server computer, it should also be installed on the failover server. The
parameters should be the same on both CONTROL-M/Server installations.

The host name of the failover server must be added to the list of authorized
hosts of each agent.

Chapter 7 Mirroring and Failover 425


Failover administration procedures

Failover administration procedures


This section details the steps to take to prepare failover systems, to implement them if
necessary, and to restore normal function.

The Database Mirroring menu


Most of the commands and procedures used to manage mirroring and failover are
accessed through the Database Mirroring menu.

To access the Database Mirroring menu

1 Log on to the computer as the CONTROL-M/Server owner.

2 Enter the following command to open the CONTROL-M Main Menu:

ctm_menu

3 The following menu is displayed:

CONTROL-M Main Menu


-----------------------------

Select one of the following menus:

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

Enter option number ---> []:4

4 Type 4 to select Database Mirroring and press <Enter>.

5 The Database Mirroring menu is displayed:

426 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


The Database Mirroring menu

Database Mirroring Menu


----------------------------
Select one of the following options:

Primary Server Options:


1 - Check Mirroring Status
2 - Initialize Mirroring
3 - Disable Mirroring
4 - Use Mirror Database
5 - Restore CONTROL-M Server Database from Mirror

Failover Server Options:


6 - Initialize Failover
7 - Start Failover
8 - Stop Failover
9 - Disable Failover

q - Quit

Enter option number ---> []:

The options of the Database Mirroring menu are divided into procedures
implemented on the primary CONTROL-M/Server, and procedures implemented on
the secondary, failover CONTROL-M/Server. Table 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.

Table 136 Database Mirroring menu options (part 1 of 2)


Primary Server Options
Option Description
Check Mirroring Reports the current mirroring status:
Status
■ Enabled: system writes updates to mirror database.
■ Disabled: system does not write to mirror database.
■ Damaged: mirror database is damaged, mirroring is disabled.
■ Mirroring is not defined: the query process did not succeed in
accessing the primary database server.
Initialize Initializes Mirroring with a secondary database. You can choose to copy
Mirroring the primary database to an existing database, or build/rebuild the
secondary database from scratch. Running this procedure leaves
mirroring enabled. See “Initializing the mirror database” on page 432.

Chapter 7 Mirroring and Failover 427


Initializing failover server and mirror database

Table 136 Database Mirroring menu options (part 2 of 2)


Disable Mirroring Stops Mirroring. Updates are no longer written to the secondary
database. You must use the Initialize Mirroring option to re-enable
mirroring.
Use Mirror Used when the primary database has failed or become damaged.
Database CONTROL-M/Server operates using the mirror database. See
“Operating CONTROL-M/Server with the Mirror database” on page
448.
Restore Restores normal function after the primary database has been repaired.
CONTROL-M Copies mirror database to primary database. CONTROL-M/Server
Server Database operates using the primary database and mirroring is enabled again. See
from Mirror “Restoring the primary database from the mirror database” on page 449.
Failover Server Options
Option Description
Initialize Failover Initializes the Failover Server on the secondary CONTROL-M/Server.
The secondary CONTROL-M/Server remains dormant and inactive. See
“Initializing the failover server” on page 429.
Start Failover Used when primary CONTROL-M/Server computer fails. To activate
the secondary CONTROL-M/Server using the mirror database, you
must first run this option on the secondary CONTROL-M/Server, then
start the secondary CONTROL-M/Server. See “Failover to the
secondary CONTROL-M/Server” on page 451.
Stop Failover Stops failover operation. See “Restoring the primary CONTROL-M/
Server” on page 452.
Disable Failover Disengages the secondary CONTROL-M/Server from the primary
CONTROL-M/Server. To start using failover again, you must
implement the failover server from scratch using the Initialize Failover
and Initialize Mirroring options.

Initializing failover server and mirror database


This section describes the procedures for initializing the failover server and mirror
database.

■ For a Failover Server, the initialization process synchronizes primary and


secondary CONTROL-M/Servers and activates failover readiness. The Mirror
Database is also initialized. To initialize a Failover Server, follow the procedure
“Initializing the failover server” on page 429.

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

428 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Initializing failover server and mirror database

Initializing the failover server


1 Install the secondary CONTROL-M/Server on the secondary computer. Verify the
configuration requirements listed in “Preparing a failover server” on page 424.

2 Verify that the secondary CONTROL-M/Server database conforms to the


requirements for the mirror database as described in:

■ “Preparing a mirror CONTROL-M/Server database on a Sybase server” on


page 419 for a Sybase SQL Server
■ “Preparing a mirror CONTROL-M/Server database on an Oracle server” on
page 421 for an Oracle SQL Server
■ “Preparing a mirror CONTROL-M/Server database on an MSSQL server” on
page 422 for an SQL Server

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.

4 On the primary CONTROL-M/Server environment, enter the following command:

ctmhostmap -action list

A report is displayed, listing remote host computers in the primary


CONTROL-M/Server.

5 Enter the following command in the secondary CONTROL-M/Server


environment for each remote host that is displayed in step 4 above:

ctm_agstat -AGSTAT <remoteHostName> R R

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:

■ both primary and secondary installations of CONTROL-M/Server and the


CONTROL-M/Server Configuration Agent are shut down
■ both the primary and mirror database servers are running

7 Log on to the secondary computer as the CONTROL-M/Server owner.

Chapter 7 Mirroring and Failover 429


Initializing failover server and mirror database

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

C The following message is displayed:

CONTROL-M failover initialization completed successfully.

Press Enter to continue

D Press <Enter> to return to the Database Mirroring menu. Then type q and press
<Enter> to exit the Main Menu.

E Determine the values needed when initializing mirroring, as follows:

For Sybase

Use the table below to determine the values of required Sybase database
environment variables.

Table 137 Sybase environment variables and alternative names


To determine the value, run this
Field name Equivalent name command
Database Owner Login CONTROL-M Mirror echo $CONTROLM_USER
Database Owner (DBO)
Database Name CONTROL-M Mirror echo $CONTROLM_DATABASE
database name
Sybase Server Query Port Mirror Sybase Port number sybedit (Sybase utility)
Number
Sybase Server Host Name Mirror Sybase Host name sybedit (Sybase utility)

For Oracle

Use the table below to determine the values of required Oracle database
environment variables.

430 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Initializing mirror database

Table 138 Oracle environment variables


Variable To determine the value of the variable ...
CONTROL-M Mirror Database owner Run the echo $CONTROLM_USER command
(DBO)
Mirror Oracle Host Name Check the tnsnames.ora file. For more
information about tnsnames.ora, see Oracle
documentation.
Mirror Oracle Port Number Check the tnsnames.ora file. For more
information about tnsnames.ora, see Oracle
documentation.
Mirror Oracle Instance name (SID) Run the echo $ORACLE-SID command

For MSSQL

Use the table below to determine the values of required MSSQL database
environment variables.

Table 139 MSSQL environment variables


To determine the value of the variable, check this
Variable registry name
Mirror Database Server Name SQLSRVRNAME
Mirror CONTROL-M/Server Database CONTROLM_DATABASE
CONTROL-M/Server Mirror DBO User DBO Owner
Name
Database Owner Login DBO Owner

8 Continue with step 3 of “Initializing the mirror database” on page 432.

When you restart CONTROL-M/Server on the primary computer, CONTROL-M/


Server on the failover server remains down until it is needed.

Initializing mirror database


This section describes the procedures for initializing the mirror database and failover
server.

For a Mirror Database, the initialization process copies the contents of the existing
database to an existing secondary database, or builds a new secondary database from
scratch and copies the contents of the existing database. Then database mirroring is
activated between the primary and secondary databases.

Chapter 7 Mirroring and Failover 431


Initializing mirror database

Initializing the mirror database


The following procedure is used to initialize database mirroring for the
CONTROL-M/Server database.

1 Verify that the secondary database server conforms to the requirements for
mirroring, as described in:

■ “Preparing a mirror CONTROL-M/Server database on a Sybase server” on


page 419 for a Sybase SQL server.
■ “Preparing a mirror CONTROL-M/Server database on an Oracle server” on
page 421 for an Oracle server.
■ “Preparing a mirror CONTROL-M/Server database on an MSSQL server” on
page 422 for an SQL server.

2 Verify that:

■ the primary CONTROL-M/Server and the CONTROL-M/Server Configuration


Agent are not running
■ both the primary and mirror database servers are running

3 Log on to the primary computer as the CONTROL-M/Server owner.

4 Specify the ctm_menu command to open the CONTROL-M/Server Main Menu.

5 Type 4 to select Database Mirroring and press <Enter>.

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

Copying or building the mirror database for a Sybase SQL


Server
The instructions below continues the procedure to initialize the mirror database from
step 5 above, for a Sybase SQL Server.

1 From the Database Mirroring menu, type 2 to select Initialize Mirroring and press
<Enter>.

432 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Initializing mirror database

The following messages are displayed:

+----------------------------------------+
|Copy/Build the CONTROL-M Mirror database|
+----------------------------------------+

Do you wish to build the CONTROL-M Mirror database from scratch, or


copy to an existing database?
Enter b to build or c to copy [b/c]:b

To build a secondary database from scratch, type b and press <Enter>.

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.

Figure 34 Mirroring parameters for database copying - Sybase


Mirroring Parameters:

1) CONTROL-M Mirror Database owner(DBO): mctmdb


2) DBO password:
Mirror database (data portion) size: 300 MB
Sybase interface directory: /home2/ctm630sd/sybase
3) Mirror Sybase Host Name: cyborg
4) Mirror Sybase Port Number: 7701
5) Mirror Sybase server name: MIRROR
6) CONTROL-M Mirror database name: mctmdb

a|A) Modify all of the above


c|C) Copy Primary Database to an existing Mirror Database
q|Q) Quit

Enter command or item number you wish to change [c] :

Verify the Mirroring parameters and modify the values as necessary. Table 141
describes the parameters. Parameter values must conform to Sybase naming
conventions.

Chapter 7 Mirroring and Failover 433


Initializing mirror database

3 Type C to start the copying procedure, and press <Enter>.

4 A confirmation message is displayed.

Please confirm that you wish to copy the contents of CONTROL-M


primary database to CONTROL-M Mirror database [y/n]

5 Type Y to confirm the start of the copying procedure, and press <Enter>.

The Mirror database is copied. Go to step 13 on page 439.

Table 140 Mirroring parameters for copying


Parameter Description
CONTROL-M Mirror Name of the CONTROL-M/Server Mirror database owner.
Database Owner (DBO) This name is used by CONTROL-M when accessing the
mirror database. When copying to an existing database, this
user must already be defined on the database server.
DBO password Password for the CONTROL-M/Server database user. The
characters you enter are not echoed for security reasons. This
password is used by CONTROL-M processes and utilities to
access the CONTROL-M/Server database.
Mirror Database (Data Amount of space (in MB) to allocate for the data portion of
Portion) Size the CONTROL-M/Server Mirror database.

This value is taken from the current size of the primary


database. It cannot be modified. Verify that the secondary
database server can host a database of this size.
Sybase Interface Directory Directory in which the Sybase interface file is located.
Mirror Sybase Host Name Name of the host computer for the mirror Sybase Database
server.
Mirror Sybase Port Number The communications port on which the secondary database
server listens for queries.
Mirror Sybase server name Name of the mirror database server. This entry is
automatically added to the primary database’s interfaces file.
This value should be unique.
CONTROL-M Mirror Name for the CONTROL-M/Server Mirror database. This
database name name must be unique. When copying to an existing database,
this database must already be defined on the database server.

■ If you selected the build option in step 1 on page 432, the following confirmation
screen is displayed:

+------------------------------------------------------+
| Control-M Server database Mirroring Customization |
+------------------------------------------------------+

434 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Initializing mirror database

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.

6 Type y and press <Enter>.

The Build database for CONTROL-M/Server screen is displayed.

=== Build database for CONTROL-M/Server ===

Mirror Database connection parameters

1 : Sybase Server name : MIRROR


2 : Sybase Server Host Name : menta

3 : Sybase Server Query Port Number : 7103

== <H> Help <C> Cancel <N> Next Panel ==

Enter command or item number you wish to change : 2


Enter a new value for sybase server host name: cyborg

Verify the Mirroring parameters and modify the values as necessary. Table 141
describes the parameters. Parameter values must conform to Sybase naming
conventions.

Table 141 Sybase mirroring parameters (part 1 of 2)


Parameter Description
Sybase Server Name Name of the mirror database server. This entry is automatically
added to the primary database’s interfaces file. This value must be
unique.
Sybase Server Host Name of the host computer for the mirror Sybase Database server.
Name
Sybase Server Query The communications port on which the secondary database server
Port Number listens for queries.
Database Owner Name of the CONTROL-M Mirror database owner. This name is
Login used by CONTROL-M when accessing the mirror database. When
building a new mirror database, the initialization script creates this
user on the database server.
Database Name of the database administrator.
Administrator Login

Chapter 7 Mirroring and Failover 435


Initializing mirror database

Table 141 Sybase mirroring parameters (part 2 of 2)


Parameter Description
Database Password of the database administrator.
Administrator
Password
Database Owner Password for the CONTROL-M/Server Mirror database owner (6 to
Password 30 characters, alphanumeric). The characters you enter are not
echoed for security reasons. This password is used by CONTROL-M
processes and utilities to access the mirror database.
Database Name Name for the CONTROL-M/Server Mirror database. This name
must be unique within the Sybase SQL server.

■ When building a new mirror database, the initialization script


creates this database on the database server.
■ When copying to an existing database, this database must already
be defined on the database server.
Database Size Amount of space (in MB) to allocate for the data portion of the
CONTROL-M/Server Mirror database.

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.

7 Type N and press <Enter>.

The following screen is displayed.

=== Build database for CONTROL-M/Server ===

Mirror Database general parameters

1 : Database Owner Login : mctmdb


2 : Database Administrator Login : sa
3 : Database Administrator Password:
4 : Database Owner Password :

== <H> Help <C> Cancel <P> Previous Panel <N> Next Panel ==

Enter command or item number you wish to change : 1


Enter a new value for database owner login: mctmdb

Verify the Mirroring parameters and modify the values as necessary. Table 141
describes the parameters.

8 Type N to display the next screen and press <Enter>.

The following screen is displayed.

436 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Initializing mirror database

=== Build database for CONTROL-M/Server ===

Mirror Database parameters

1 : Database Name : men630sd


2 : Database Size : medium

== <H> Help <C> Cancel <P> Previous Panel <N> Next Panel ==

Enter command or item number you wish to change : 1


Enter a new value for database name: mctmdb

Verify the Mirroring parameters and modify the values as necessary. Table 141
describes the parameters.

9 Type N to display the next screen and press <Enter>.

The following screen is displayed.

=== Build database for CONTROL-M/Server ===

Mirror Database devices parameters

1 : Data Device Full Path File Name:


/home2/ctm630sd/sybase/data/mctmdb_data.dat
2 : Data Device Size : 300MB
3 : Log Device Full Path File Name :
/home2/ctm630sd/sybase/data/mctmdb_log.dat
4 : Log Device Size : 100MB

== <H> Help <C> Cancel <P> Previous Panel <N> Next Panel ==

Enter command or item number you wish to change : 1


Enter a new value for data device full path file name: /home/syb1253/
sam/mctmdb_data.dat

Verify the Mirroring parameters and modify the values as necessary. Table 141
describes the parameters.

10 Type N to display the next screen and press <Enter>.

The following summary screen is displayed.

=== Build database for CONTROL-M/Server ===

=== Mirror Database Parameters: Summary ===

Sybase Server Host Name : cyborg


Sybase Server Query Port Number : 7701

Chapter 7 Mirroring and Failover 437


Initializing mirror database

Database Owner Login : mctmdb


Database Name : mctmdb

== <H> Help <C> Cancel <P> Previous Panel <I> Install ==

Enter command or item number you wish to change : i


Do you want to install? (Y/N) y

Verify the Mirroring parameters and modify the values as necessary.

11 Type I to start the installation procedure, and press <Enter>.

■ If the database is being built with a database name that already exists, the
following message is displayed:

Starting installation of CONTROL-M Sybase database component.

Install: [ 0%] done.

We are going to drop database ctrlm630!!!

Are you sure?(Y/N)

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

The following messages are displayed:

Installation of CONTROL-M Sybase database component completed


successfully.

copying database
contents............................................................
............
Create indexes. This may take several minutes, please wait...

In order to complete this procedure after exiting the menu,


please execute 'source ~/.cshrc' command.

Run the following command:

source ~/.cshrc

The following message is displayed:

438 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Initializing mirror database

CONTROL-M Server database Mirroring Initialization completed successfully.

Press Enter to continue

A success message is also sent by e-mail.

12 To continue press <Enter>.

If the device name specified already exists, the following message is displayed.

Please delete physical device file [/home1/ctm630a/sybase/data/


ctrlm623_log.dat] from remote host
Enter Y after deleting the file or N to exit (Default : No) y

continuing with the current installation.


Please delete physical device file [/home1/ctm630a/sybase/data/
ctrlm630_data.dat] from remote host
Enter Y after deleting the file or N to exit (Default : No)

13 The CONTROL-M/Server database Mirroring Initialization process is completed.

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.

15 Restart CONTROL-M/Server. If CONTROL-M/Server is managed by


CONTROL-M Configuration Manager, also start the CONTROL-M/Server
Configuration Agent. For more information about starting and stopping
CONTROL-M/Server manually, see page 311. For more information about
managed and unmanaged CONTROL-M/Server, see the CONTROL-M/Enterprise
Manager Administration Guide.

Copying or building the mirror database for an Oracle SQL


Server
The instructions below continues the procedure to initialize the mirror database from
step 5 on page 432 for an Oracle SQL Server.

1 From the Database Mirroring menu, type 2 to select Initialize Mirroring and press
<Enter>.

Chapter 7 Mirroring and Failover 439


Initializing mirror database

The following messages are displayed:

+----------------------------------------+
|Copy/Build the CONTROL-M Mirror database|
+----------------------------------------+

Do you wish to build the CONTROL-M Mirror database from scratch, or


copy to an existing database?
Enter b to build or c to copy [b/c]:b

To build a secondary database from scratch, type b and press <Enter>.

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.

Figure 35 Mirroring parameters for database copying - Oracle


Mirroring Parameters:

1) CONTROL-M Mirror Database owner(DBO): mcom630oe


2) DBO password: ##########
3) Mirror Oracle Host Name: rizoto
4) Mirror Oracle Port Number: 1775
5) Mirror Oracle Instance Name(SID): ora10103
6) CONTROL-M Mirror SID : ctrlm_mirror

a|A) Modify all of the above


c|C) Copy Primary Database to an existing Mirror Database
q|Q) Quit

Enter command or item number you wish to change [c] :c

If you selected the build option step 1 on page 432, additional parameters are
displayed as in Figure 36.

Figure 36 Mirroring parameters for database build or rebuild - Oracle

440 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Initializing mirror database

Mirroring Parameters:

1) CONTROL-M Mirror Database Owner(DBO): ctrlm


2) DBO Password: #####
3) Mirror Oracle Host Name:
4) Mirror Oracle Port Number:
5) Mirror Oracle Instance name (SID):
6) CONTROL-M Mirror tablespace name: ctrlm
7) CONTROL-M Mirror SID : ctrlm_mirror

a|A) Modify all of the above


b|B) Build Mirror Database
q|Q) Quit

Enter command or item number you wish to change [b]:

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.

Table 142 Oracle mirroring parameters (part 1 of 2)


Parameter Description
CONTROL-M Mirror Name of the CONTROL-M/Server Mirror database owner.
Database Owner (DBO) This name is used by CONTROL-M when accessing the mirror
database.

■ When building a new mirror database, the initialization


script creates this user on the database server.
■ When copying to an existing database, this user must
already be defined on the database server.
DBO password Password for the CONTROL-M/Server database user. The
characters you enter are not echoed for security reasons. This
password is used by CONTROL-M processes and utilities to
access the CONTROL-M/Server database.
Mirror Oracle Host Name The host computer name of an existing Oracle server.
Mirror Oracle Port Number The communication port of the Oracle Database Server.
Mirror Oracle Instance The Server ID of the Oracle Database Server.
Name (SID)
To find out this name use the following command on the
mirror database server:

echo $ORACLE_SID

Chapter 7 Mirroring and Failover 441


Initializing mirror database

Table 142 Oracle mirroring parameters (part 2 of 2)


Parameter Description
CONTROL-M Mirror Name of a defined tablespace on the database server that will
tablespace name be used by the mirror database.
CONTROL-M Mirror SID Instance name of the CONTROL-M/Server database.
Default: ctrlm_mirror

The ORACLE_SID parameter must be unique and not appear


more than once in the tnsnames.ora file. For more information
about the tnsnames.ora file, see Oracle documentation.

Note: The Oracle database instance name must conform to the


Oracle naming convention.

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.

5 The following prompt is displayed:

Please confirm that you wish to build a new CONTROL-M Mirror database
[y/n] :y

6 Specify y to confirm that you wish to build a new CONTROL-M/Server Mirror


database.

7 The following screen is displayed:

+------------------------------------------------------+
| Control-M Server database Mirroring Customization |
+------------------------------------------------------+

Working...

Building the Control-M Server database requires the Oracle


System
Administrator's password.
Do you wish to continue? [y]:
Please Enter Mirror Oracle Administrator Password:

Please Enter Primary Oracle Administrator Password:

442 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Initializing mirror database

Table 143 Oracle database server passwords


Parameter Description
Mirror Oracle Password for the mirror Oracle database server.
Administrator Password
Primary Oracle Password for the primary Oracle database server.
Administrator Password

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 data tablespace file name with full path:/home1/ora10103/


user/mcom630oe_dta.dbf

Enter the full path and name of the tablespace file, or press <Enter> to accept the
default path and file. The filename must conform to Oracle naming conventions.

The following message is displayed:

Creating CONTROL-M/Server database schema...


Done.

Continue with step 13.

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

11 The following prompt is displayed:

Please confirm that you wish to copy the contents of CONTROL-M


primary database to CONTROL-M Mirror database [y/n] :y

Specify y or press <Enter> to continue. The following message is displayed:

+-----------------------------------------------+
| CONTROL-M Database Mirroring Customization |
+-----------------------------------------------+

Working...

Chapter 7 Mirroring and Failover 443


Initializing mirror database

12 The following message is displayed:

copying database contents......................................


Create indexes. This may take several minutes, please wait...

In order to complete this procedure after exiting the menu, please


execute ‘source ~/.cshrc’ command.

CONTROL-M Server Database Mirroring initialization completed


successfully

Press Enter to continue

Press <Enter> to return to the CONTROL-M/Server Main Menu.

This marks the conclusion of the procedure to build the CONTROL-M mirror
database and initialize mirroring. From now on, any changes CONTROL-M/
Server makes to the primary database are copied to the mirror database.

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.

14 Restart CONTROL-M/Server. If CONTROL-M/Server is managed by


CONTROL-M Configuration Manager, also start the CONTROL-M/Server
Configuration Agent. For more information about starting and stopping
CONTROL-M/Server manually, see page 311. For more information about
managed and unmanaged CONTROL-M/Server, see the CONTROL-M/Enterprise
Manager Administration Guide.

Copying or building the mirror database for an MSSQL


database
The instructions below continues the procedure to initialize the mirror database from
step 5 on page 432 for an MSSQL database.

1 Type 4 to select Database Mirroring and press Enter.

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.

444 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Initializing mirror database

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.

■ To use an existing database as the mirror database, click Copy.

Specify the parameters described in Table 144 and click OK.

Table 144 Initialize mirroring parameters


Parameter Description
Mirror Database Server Specify a name for the mirror Database Server.
Name
Mirror CONTROL-M/ Name of the CONTROL-M/Server Database that will be a
Server Database mirror of the primary database.
CONTROL-M/Server Name of the database server administrator.
Mirror DBO Username
CONTROL-M/Server Password for the CONTROL-M/Server database owner. The
Mirror DBO Password password must begin with a letter (A-Z, a-z) followed by 5 to 29
alpha-numeric characters (includes underscores). If the
specified password is longer than 30 characters, only the first 30
are accepted. Default: password
Confirm DBO Password Re-enter the Database Owner Password, confirming its
correctness.

Data is copied from the primary database to the database you specified. Go to step
8 on page 447.

■ To build a new database on an existing database server, click Build.

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.

Specify the parameters described in Table 145.

Chapter 7 Mirroring and Failover 445


Initializing mirror database

Table 145 Initialize mirroring parameters


Parameter Description
Database Owner Login Name for the CONTROL-M/Server database schema owner.
The name must begin with a letter (A-Z, a-z) followed by up to 7
alpha-numeric characters (includes underscores). Default: ctrlm
Database Owner Password Password for the CONTROL-M/Server database owner. The
password must begin with a letter (A-Z, a-z) followed by 5 to 29
alpha-numeric characters (includes underscores). If the
specified password is longer than 30 characters, only the first 30
are accepted. Default: password
Confirm Database Owner Re-enter the Database Owner Password, confirming its
Password correctness.
Database Administrator Name of the database server administrator.
Login
Database Administrator Password of the database server administrator.
Password

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.

446 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Recovering from database failure

A window showing a summary of installation options is displayed.

7 Click Initialize. The database is built. The following screen is displayed.

8 To verify that mirroring is active, select Database Mirroring => Check Mirroring
Status from the CONTROL-M/Server Main menu.

9 Restart CONTROL-M/Server. If CONTROL-M/Server is managed by


CONTROL-M Configuration Manager, also start the CONTROL-M/Server
Configuration Agent. For more information about starting and stopping
CONTROL-M/Server manually, see page 311. For more information about
managed and unmanaged CONTROL-M/Server, see the CONTROL-M/Enterprise
Manager Administration Guide.

Recovering from database failure


If the primary database fails, two options exist for restoring CONTROL-M/Server
operation:

■ Operate CONTROL-M/Server using the mirror database instead of the primary


database. The primary CONTROL-M/Server database can be rebuilt at a later
stage.

This method resumes CONTROL-M/Server operation in the minimum time


possible. However, mirroring cannot be reactivated until after the primary
database is repaired.

To implement this option, follow the procedure “Operating CONTROL-M/Server


with the Mirror database” on page 448.

Chapter 7 Mirroring and Failover 447


Recovering from database failure

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.

This method allows the CONTROL-M/Server database to continue to operate with


mirroring. However, you will not be able to start CONTROL-M/Server until you
have completed restoring the CONTROL-M/Server database - and this can result
in significant downtime.

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.

Operating CONTROL-M/Server with the Mirror database


1 Verify that the primary CONTROL-M/Server and the CONTROL-M/Server
Configuration Agent are not running.

2 Log on to the primary computer as the CONTROL-M/Server owner.

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

The following message is displayed:

Please confirm that you wish to use the Mirror Database INSTEAD of
the Main Control-M database [y/n]:

5 Type y and press <Enter>.

For UNIX

Perform one of the following:


■ exit the current session and start a new logon session

■ specify the command source ~/.cshrc to reset user environment variables in the
current window.

For Windows

Exit the Database Mirroring menu.

448 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Recovering from database failure

6 Restart CONTROL-M/Server on the primary computer. If CONTROL-M/Server is


managed by CONTROL-M Configuration Manager, also start the CONTROL-M/
Server Configuration Agent. For more information about starting and stopping
CONTROL-M/Server manually, see page 311. For more information about
managed and unmanaged CONTROL-M/Server, see the CONTROL-M/Enterprise
Manager Administration Guide.

CONTROL-M/Server now uses the Mirror Database instead of the primary


database.

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.

Restoring the primary database from the mirror database


1 Log on to the primary computer as the CONTROL-M/Server owner. Verify that
CONTROL-M/Server and the CONTROL-M/Server Configuration Agent are not
running.

2 Specify the ctm_menu command to open the CONTROL-M Main Menu.

3 Type 4 to select Database Mirroring and press <Enter>.

The Database Mirroring menu is displayed.

4 From the Database Mirroring menu, type 5 to select Restore CONTROL-M


Database from Mirror and press <Enter>.

The following prompt is displayed:

Restore Database from Mirror [N]:y

5 Type y and press <Enter> to restore the database.

The following prompt is displayed:

Warning: Attempt to restore primary CONTROL-M database without


rebuilding it.
Please confirm that this is your intention [y/n]:y

6 Type y and press <Enter>.

The following messages are displayed:

Chapter 7 Mirroring and Failover 449


Recovering from primary CONTROL-M/Server failure (Server failover)

For Oracle databases:

Oracle is up and runnning ...

For both Oracle and Sybase databases:

In order to complete this procedure after exiting the menu, please


execute 'source ~/.cshrc' command

Press Enter to continue

For MSSQL databases:

Press Enter to continue

7 Press <Enter> to return to the Database Mirroring menu.

The mirror status is now enabled.

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.

9 Start CONTROL-M/Server on the primary computer. If CONTROL-M/Server is


managed by CONTROL-M Configuration Manager, also start the CONTROL-M/
Server Configuration Agent. For more information about starting and stopping
CONTROL-M/Server manually, see page 311. For more information about
managed and unmanaged CONTROL-M/Server, see the CONTROL-M/Enterprise
Manager Administration Guide.

Recovering from primary CONTROL-M/Server failure (Server


failover)
These procedures assume that a failover server has already been installed and
initialized on a secondary computer. Two procedures are used during failover
situations:

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

450 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Recovering from primary CONTROL-M/Server failure (Server failover)

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

Failover to the secondary CONTROL-M/Server


1 Verify that:

■ Both primary and secondary CONTROL-M/Server installations and


CONTROL-M/Server Configuration Agent are not running.

■ Both the primary and mirror database servers are running.

2 Log on to the secondary computer as the CONTROL-M/Server owner.

3 Specify the ctm_menu command to open the CONTROL-M Main Menu.

4 Type 4 to select Database Mirroring and press <Enter>.

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:

** Unable to start CONTROL-M due to path specified for PROCLIB


directory $PROCLIB. This path is invalid **

6 The following message is displayed:

This operation disables CONTROL-M database mirroring,


and starts FailOver CONTROL-M !!!

Confirm that CONTROL-M in the primary data center is not running.

Continue [y/n] :

7 Type y and press <Enter> to continue with failover.

The following message is displayed:

Chapter 7 Mirroring and Failover 451


Recovering from primary CONTROL-M/Server failure (Server failover)

Failover started successfully

Press Enter to continue

8 Press <Enter> to return to the Database Mirroring menu.

9 From the Database Mirroring menu, specify q to return to the CONTROL-M Main
Menu.

10 Start CONTROL-M/Server on the secondary computer. If CONTROL-M/Server is


managed by CONTROL-M Configuration Manager, also start the CONTROL-M/
Server Configuration Agent. For more information about starting and stopping
CONTROL-M/Server manually, see page 311. For more information about
managed and unmanaged CONTROL-M/Server, see the CONTROL-M/Enterprise
Manager Administration Guide.

11 In the CONTROL-M Configuration Manager, double-click the CONTROL-M/


Server component. In the dialog box that is displayed, modify the host name of the
primary CONTROL-M/Server to the name of the secondary CONTROL-M/
Server, and click OK.

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.

Restoring the primary CONTROL-M/Server


1 Log on to the secondary computer as the CONTROL-M/Server owner.

2 If CONTROL-M/Server is working using CONTROL-M/Server Configuration


Agent, shut down the CONTROL-M/Server Configuration Agent, then shut down
CONTROL-M/Server.

3 Specify the ctm_menu command to open the CONTROL-M Main Menu.

4 Type 4 to select Database Mirroring and press <Enter>.

5 From the Database Mirroring menu, type 8 to select Stop Failover and press
<Enter>.

The following prompt is displayed:

This procedure stops FailOver CONTROL-M


Continue [y/n] :y

452 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Synchronizing the primary and mirror databases

6 Type y and press <Enter> to continue.

The following message is displayed:

Failover Stopped

Press Enter to continue

7 Press <Enter> to return to the Database Mirroring menu.

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.

Synchronizing the primary and mirror


databases
When database mirroring is enabled, all database updates from CONTROL-M/
Server are sent simultaneously to both the primary and mirror CONTROL-M/Server
database. However, if a CONTROL-M/Server administrative utility modifies the
primary database, the mirror database will not automatically reflect these changes.
Either the same or a similar utility must be run against the mirror database, or the
mirror database must be re-initialized as described in “Initializing the mirror
database” on page 432.

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

Table 146 Utilities affecting the primary database (part 1 of 3)


ctm_menu Option Database Utility Action
Database Creation Menu
Build Database Sybase build_db.sh Initialize Mirroring
Oracle make_db Initialize Mirroring
MSSQL build_db Initialize Mirroring
Delete Database All Initialize Mirroring
Erase Database All ctm_clean_db Initialize Mirroring

Chapter 7 Mirroring and Failover 453


Synchronizing the primary and mirror databases

Table 146 Utilities affecting the primary database (part 2 of 3)


ctm_menu Option Database Utility Action
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 backup server
Database Size computer or see your Systems Administrator.

Note: When running this utility with a Sybase


12.5.3 dedicated database, a message similar to
the following is displayed:

Warning: The database 'tempdb' is


using an unsafe virtual device
'dev_CONTROLM_tempdb'. The recovery
of this database can not be
guaranteed.
Extend Temp Oracle ctm_tempdb_extend Either run the utility on the backup server
Tablespace Size computer or see your Systems Administrator.
Extend Rollback Oracle ctm_rollback_extend Either run the utility on the backup server
Tablespace Size computer or see your Systems Administrator.
Extend Database Sybase ctm_logdb_extend Either run the utility on the backup server
Log Size computer or see your Systems Administrator.
Troubleshooting Menu
Truncate Database Log Sybase ctm_cleanlog Either run the utility on the backup server
computer or see your Systems Administrator.
Restart New Day All <internal utility> Initialize Mirroring.
Procedure
Reset CONTROL-M All clean_ajf Initialize Mirroring.
Active Environment

454 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Example of a failover scenario

Table 146 Utilities affecting the primary database (part 3 of 3)


ctm_menu Option Database Utility Action
Remote Host computers All ctmhostmap or add – add the details of a remote host computer
CONTROL-M to the CONTROL-M/Server database
Configuration
Manager Run the following command on the secondary
CONTROL-M/Server:

ctm_agstat -AGSTAT <remoteHostName> R R

Replace the <remoteHostName> variable with


the name of remote host that was added.
update – modify the details of the specified
remote host computer in the CONTROL-M/
Server database

Run the following command on the secondary


CONTROL-M/Server:

ctm_agstat -AGSTAT <remoteHostName> R R

Replace the <remoteHostName> variable with


the name of remote host that was updated.
delete – delete the details of the specified
computer from the CONTROL-M/Server
database
Remote Host compute All ctmhostmap or Convert a CONTROL-M/Agent to a remote
CONTROL-M host
Configuration
Manager Run the following command on the secondary
CONTROL-M/Server:

ctm_agstat -AGSTAT <remoteHostName> R R

Replace the <remoteHostName> variable with


the node that was updated.

Example of a failover scenario


The following steps illustrate a typical example of a failover scenario:

1 CONTROL-M/Server, running on the primary environment, fails due to a


hardware/software problem on the primary computer. CONTROL-M/Server
cannot be restarted.

2 Jobs already submitted to an agent computer continue executing.

Chapter 7 Mirroring and Failover 455


Example of a failover scenario

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.

4 When the CONTROL-M/Server is started on the mirror environment, it polls the


agent computers to determine the status of jobs listed in the Active Jobs file.

5 The CONTROL-M/Server on the mirror environment continues performing all


normal CONTROL-M functions until the primary environment is repaired and
you restore the CONTROL-M/Server on the primary environment as the current
active server.

To install a mirror environment, use the same procedure as for installation of a


primary CONTROL-M/Server. For more information, see the CONTROL-M
Installation Guide. Procedures for activating and deactivating a mirror environment
are described in “Recovering from CONTROL-M/Server computer failure” on page
320.

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.

456 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Appendix

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.

CONTROL-M/Server log fields


Table 147 describes the fields in the CONTROL-M/Server log.

Table 147 Fields of the CONTROL-M/Server log


Field Description Characters
Logtime Message time 6
Logdate Message date 8
Subsystem CONTROL-M/Server process that generated the message 2
Jobname Job name of the job that generated the message 64
Jobno. Job number (from job processing definition) 4 (integers)
Orderno Order number of the job 4 (integers)
Owner User name of job's owner 30
Odate Original scheduling date of job 8
Msgid Message ID (messages are described in the CONTROL-M Messages 4
Manual)
Message Text of message 255
Tasktype Task Type identifier (for example, batch, detached, command) 2
Memname Member name 30

Appendix A Structure of CONTROL-M/Server Log Entries 457


CONTROL-M/Server log fields

458 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Appendix

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

Appendix B Unsupported Utilities 459


■ dbbackupsyb
■ dbcheckora
■ dbchecksyb
■ dbloadora
■ dbloadsyb
■ dbrestoreora
■ dbrestoresyb
■ dbunloadora
■ dbunloadsyb
■ dbupstatora
■ dbupstatsyb
■ dsdisp
■ dsmk
■ ecacontb
■ shdest
■ upg_ping

460 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Appendix

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.

The following topics are discussed in this appendix:

Converting an agent to a remote host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462


Converting multiple agents to remote hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Converting a remote host to an agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

Appendix C Conversion of agents and remote hosts 461


Converting an agent to a remote host

Converting an agent to a remote host


To convert an agent computer to a remote host

1 Ensure that no jobs have been submitted or are running on the required agent.

2 Determine all the owners used on the agent computer.

Log onto the sql database server and run the following SQL commands to
determine all the owners used on the agent computer:

select OWNER from CMR_AJF where lower(NODEID)='<agentNameToBeConverted>'


union
select OWNER from CMS_JOBDEF where
lower(NODEGRP)='<agentNameToBeConverted>' or exists
(select 1 from CMS_NODGRP where GRPNAME=CMS_JOBDEF.NODEGRP and
lower(NODEID)='<agentNameToBeConverted>')

Add one of the following on a separate line at the end of the commands:

■ For Oracle: ;
■ For Sybase or MSSQL: go

The <agentNameToBeConverted> variable must be specified in lower case.

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:

select OWNER from CMR_AJF where lower(NODEID)='cyborg'


union
select OWNER from CMS_JOBDEF where lower(NODEGRP)='cyborg' or exists
(select 1 from CMS_NODGRP where GRPNAME=CMS_JOBDEF.NODEGRP and
lower(NODEID)='cyborg')
;

3 In the owner’s authentication settings in the CONTROL-M Configuration


Manager, define all the owners from step 2.

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.

462 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Converting multiple agents to remote hosts

4 Shut down the agent on the agent environment.

5 Do one of the following:

— If the remote host should be connected using default communication settings,


delete the agent by using the CONTROL-M Configuration Manager. Once a job
is then scheduled on this node, the remote host will be automatically
configured.

— If the remote host should be connected using non-default communication


settings, use the Convert to Remote Host option in the CONTROL-M
Configuration Manager.

Converting multiple agents to remote hosts


To convert multiple agents to remote hosts

1 Determine all owners used by agents you wish to convert.

For the procedure to determine all users, see step 2 on page 462.

2 In the CONTROL-M/Server owner’s authentication settings, define all the owners


from step 1.

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.

The remote hosts are now configured.

Appendix C Conversion of agents and remote hosts 463


Converting a remote host to an agent

Converting a remote host to an agent


To convert a remote host to an agent computer using the CONTROL-M
Configuration Manager

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.

3 Define the agent computer in the CONTROL-M/Server environment. Use the


CONTROL-M Configuration Manager to define the agent.

The agent computer is now configured.

To convert a remote host to an agent computer using CONTROL-M Main Menu

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.

The agent computer is now configured.

464 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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

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 Configuration Manager


This central management console in CONTROL-M/EM can be used to perform administrative
tasks. The CONTROL-M Configuration Manager is the central point of administration for the
CONTROL-M environment.

CONTROL-M Configuration Manager Server


This collects all the relevant data from all CONTROL-M components through the Configuration
Agents, which can then be managed from the CONTROL-M Configuration Manager. Only one
instance of CONTROL-M Configuration Management Server can be run at any one time.

CONTROL-M Configuration Manager Agent


This enables you to monitor and manage CONTROL-M/Servers components. A CONTROL-M
Configuration Manager Agent is installed on every computer on which a CONTROL-M/Server
6.3.01 or later is installed.

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/Enterprise Manager or CONTROL-M/EM


Software product that provides a central point of control for CONTROL-M data centers.
CONTROL-M/EM provides the GUI which allows users to graphically view the status of job
schedules and execution in data centers, to issue requests for additional information and to
handle problems. CONTROL-M/EM also passes global conditions among data centers.

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.

CONTROL-M/Server (Primary) Database


Repository of operational data relating to the functioning of the CONTROL-M data center.
Contents of the database include the Active Jobs file, Scheduling tables (job processing
definitions) and the Resources/Conditions table. The database is maintained by CONTROL-M/
Server, using an SQL Server

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.

466 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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

Data Center (or CONTROL-M Data Center)


A server computer and all the agent computers that it handles.

Download (of active environment)


Transmission of the Active Jobs file and other elements of the CONTROL-M/Server database to
the CONTROL-M/EM database. This allows CONTROL-M/EM to provide the user with a
graphical display of the current situation in the data center. Download occurs upon completion
of the New Day procedure, after which updates are issued to maintain the accuracy of the
graphical display.

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

General Daily Procedure


See “New Day Procedure”.

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.

468 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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

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.

Remote Host Computers


Computers that can run jobs and perform other tasks based on requests from CONTROL-M/
Server.

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

Sybase SQL Server


Software product used by CONTROL-M/Server to maintain the CONTROL-M/Server
database. The database can be maintained using either a dedicated instance of Sybase SQL
Server (provided with CONTROL-M) or an existing instance of Sybase SQL Server (provided by
the user).

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

470 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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
Symbols
+nn description 375
shift the job 143 modifying 345
Agent platforms
application server information 348

A communication parameters 375


communication status 25, 212, 348
Abu Dhabi time zone 52 configuration information 212
ACTION parameter ctmping utility 212
ctmgetcm utility 163 deleting 91
ctmudchk utility 290 Shout messages to 284
ctmvar utility 298 status 91
Active Jobs File Agent Router
report 83 persistent connection 28
Active Jobs file Agent Status menu 348
ctmpsm utility 219, 220 AGENTS_CLEANUP_IN_NEWDAY
downloading 352, 357 Server parameter 386
erasing contents 357 Agent-to-Server
forcing download 352 port number 372
listing job details 219 Agent-to-Server Port Number parameter 372
New Day procedure 43 AIX
options 220 shared library path 86
security 254 AKL time zone 52
specific purpose jobs 111 ALARM_DEST
time zones 53 Server parameter 386
Active shout table ANC time zone 51
system parameter 365 Anchorage Standard Time 51
Add Backup Device option append
Database Maintenance 333 add details of the users 266
ADD parameter add SSH key details 179
ctmnodegrp utility 200 application security 243
ADD_SYSOUT_TO_EMAIL applications
e-mail configuration parameter 397 ctmgetcm utility 162
ADD_SYSOUT_TO_EMAIL_ TIMEOUT_LIMIT display nodeID data 163
e-mail configuration parameter 398 APPLTYPE parameter
ADD_SYSOUT_TO_EMAIL_LIMIT_SIZE ctmnodegrp utility 199
e-mail configuration parameter 397 appltype parameter
adding ctmgetcm utility 163
backup devices 333 AR Server
groups 250 Do Remedy 398
prerequisite conditions 105 Archiving mode
users 246 Oracle databases 33
ADJUST_COND arp command
parameter 388 IP address locator 373
Agent communication parameters ASCII files
defaults 344 ctm_restore_bcp utility 97
ctmexdef utility 147

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

Associated Job Processing Definitions ctmreindex utility 236


report 83
ATL time zone 51
Atlantic Standard Time 51
Auckland time zone 52
C
Authorized CONTROL-M/Servers file calendar
description 30 calculate date of a job 101
host names 36 ctmcalc_date 101
overview 36 CCM support 320
AutoEdit variables CDROM name
ctmstvar utility 280 Oracle parameter 381
ctmvar utility 297 Central European Time 52
quotation marks 117, 141, 167, 280 Central Standard Time 51
AUTOEDIT_INC_ SEC parameter 386 CET time zone 52
autoextend character set
used during installation 313 Sybase SQL server 420
automatic discovery Check Database option
ctmping 214 Database Maintenance 337
description 214 Check Kernel Configuration parameter 351
automatically check checking
database 313 free disk space 146
available space mirroring 104
database 313 User Daily jobs 290
Available status waiting jobs 302
Agent platform 26 CHILD mode
ctmpsm utility 225
Cluster Administrator
B start and stop the Server 394
cluster parameters
backing up modifying 394
CONTROL-M database 122 CMN_PRM_CD_MAX_DBU
MSSQL database 34 communication parameter 396
Oracle database 32 CMN_PRM_CD_MAX_SERVICE
Sybase database 34 communication parameter 396
backup cold backup
Oracle 330 archive mode 329
Sybase 330 Oracle database 32
Sybase database 34 communication
Backup Database option Agent parameters 344
Database Maintenance menu 330 Agent platforms 375
backup procedure Available status 26
MSSQL database 34 ctmping utility 212
Oracle database 32 defaults for parameters 344
Sybase database 34 Diagnostic report 352
Backup Socket port number Disabled status 26
Sybase 379 discovering status 26
Bangkok time zone 52 interruptions 29
batch mode parameter defaults 344
Security Maintenance utility 261 parameter descriptions 371
utilities 84 parameter modification 343, 345
binary files Secure Socket Layer 371
ctmdbrst utility 93, 97 status 25, 212, 348
bits Timeout parameter 376
ctmkeygen parameters 179 Unavailable status 26
BKK time zone 52 communication parameters
BMC Software, contacting 2 ctmping 215
B-tree indexes Communication Protocol parameter 372

472 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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

Communication protocol parameter 372 percent utilization 124


Communication Protocol Version parameter 375 rebuilding 319
-compression recovery procedure 318, 447
SSH parameter 171 restoring 131, 331
compression statistics 174, 240
SSL 244 Sybase parameter 378, 434, 436
Computer System parameter 365 CONTROL-M date
COMTIMOUT Day Time parameter 366
Agent parameter 401 description 42
COMTRYNO Odate 42
Server parameter 401 CONTROL-M Date parameter 365
Condition Date parameter CONTROL-M Log
ctmcontb utility 107 report 83
Condition Name parameter CONTROL-M log
ctmcontb utility 106 cleanup 42
Conditions file, Manual 188 deleting entries 196
config.dat file description 49
Event logger configuration 66 fields 457
parameters 385 listing entries 196
user exit parameters 409 recorded times 29
watchdog parameters 401 Shout destination 360
configuration Shout utility 284
CONTROL-M/Agent 36 CONTROL-M Mirror database parameters 384
Configuration Agent Port CONTROL-M SYSTEM tablespace parameters 380
Server parameter 372 CONTROL-M Version parameter 365
configuration parameters CONTROL-M/Agent
Watchdog 401 configuration 36
Control Modules description 17
ctmgetcm utility 162 interrupted communication 29
Control resources CONTROL-M/EM
deleting 357 ctmsuspend utility 281
listing 304 release version 374
Control Resources Status Shout messages 284
report 83 TCP/IP port number 374
CONTROL-M CONTROL-M/EM Release Version parameter 374
administrator 61 CONTROL-M/EM TCP/IP Port Number parameter 374
failover planning 35 CONTROL-M/Server
log 457 Agent interaction 24
main menu 322 backup server 320, 450
maintenance 312 host name 36, 372
menu system 322 Microsoft Windows 30
mirror database 417 parameters 364
product registry database 110 processes 281, 352
security facility 243 recovery 424
CONTROL-M database Shout messages 284
backing up 122, 330 starting 310, 324
checking data usage 133 stopping 310, 324
creation menu 326 TCP/IP port number 374
defining jobs 136 Windows service 310
extending 335 CONTROL-M/Server database
failover planning 417 backing up 330
integrity 124, 313 ctmdbmused utility 129
maintenance 313 ctmdbused utility 135
Oracle parameters 380, 441 restoring 332
overview 22 CONTROL-M/Server entities
owner parameter (Sybase) 378, 435 description 310
parameters 337, 377, 378, 380 CONTROL-M/Server service 310

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

creating Server parameter 389


application-specific jobs 145 CTM_SNMP_SEND_FORMAT
CONTROL-M database 326 Server parameter 389
files 149 CTM_WRITE_CONSOLE
Manual Conditions file 188 Server parameter 389
specific purpose jobs 111 ctm2snmp utility
csh command message distribution 120
environment variables 87 ctmcalc_date utility
path modification 89 calculate scheduling date 101
CST time zone 51 ctmcheckmirror
CTM_ADJUST_COND_SCOPE checks mirroring 104
Server parameter 387 ctmcheckmirror utility
CTM_AGSTAT utility check mirroring 104
Agent status 91 ctmcontb utility
description 91 prerequisite conditions 105
ctm_backup_bcp utility ctmcpt utility 110
comparison with ctmdbbck 93 ctmcreate utility
exporting database data 93 application-specific jobs 145
CTM_CONFIG_AGENT_AGENT_UNAVAIL_ specific purpose jobs 111
THRESHOLD ctmdbbck utility
Server parameter 387 database backup 122
CTM_CONFIG_AGENT_MODE ctmdbcheck utility
Server parameter 387 ctmdbused command 124
CTM_CONFIG_AGENT_PORT_NUMBER database status 124
Server parameter 387 problem detection 64
CTM_DB_TIMEOUT ctmdbmused utility
Server parameter 387 description 129
ctm_diag_comm ctmdbopt utility
utility 95 database statistics 130
CTM_GROUP_ADJUST_DUMMY ctmdbrst utility
Server parameter 388 database restoring 131
CTM_GROUP_RECHECK database size 93
Server parameter 388 ctmdbspace utility
ctm_menu command 322 space verification 70, 133
CTM_MULTIP_LIB _REPLACE ctmdbtrans utility
server parameter 388 problem detection 65
CTM_PRM_ENABLE_UExxx ctmdbused command
user exit parameter 400, 409 database utilization 124
CTM_PRM_KPA_ACTIVE ctmdbused utility
communication parameter 396 description 135
Heartbeat monitor 62 ctmdefine utility
CTM_PRM_KPA_BETWEEN_MSGS application-specific jobs 145
Heartbeat monitor 62 summary 136
CTM_PRM_KPA_ROUNDTRIP_... ctmdiskspace utility
communication parameter 396 disk space check 70, 146
Heartbeat monitor 63 ctmexdef utility
CTM_PRM_SCRIPT_UExxx export job definitions 147
user exit parameter 400, 409 CTMFW utility
CTM_PRM_TIMEOUT_UExxx execution log file 151
user exit parameter 400 ctmfw utility 149
wait interval 409 ctmgetcm
ctm_restore_bcp utility mode descriptions 162
ASCII files 97 ctmgetcm utility
importing database data 97 get application server information 162
CTM_SEM_KEY_ID ctmjsa utility
server parameter 389 job statistics 48
CTM_SLP_SUSPEND summary 174

474 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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

ctmkeystore_mng statistical summary table 277


Do Remedy 183 summary 49
REMEDY Ketstore Menu 183 ctmstvar utility
ctmkilljob utility AutoEdit variables 280
job termination 186 ctmsuspend utility
ctmldnrs utility CONTROL-M/EM communication 281
Manual Conditions file 188 ctmsys utility
ctmloadset utility parameter modification 369
load balancing 31 system parameters 282
resource usage 192 ctmudchk utility
ctmlog utility ordering jobs 290
CONTROL-M log 196 User Daily job check 290
problem detection 65 ctmudlst utility
CTMLOG_DEL_CHK configuration parameter 389 Date Control record 39
ctmnodegrp utility description 293
Node Group Menu 199 ctmudly utility
ctmordck utility User Daily jobs 37, 294
job processing definition 202 CTMUE101 user exit
ctmorder utility job ordering 410
description 204 CTMUE102 user exit
forcing a job 206 job submission 412
CTMORDER_FORCE CTMUE103 user exit
Server parameter 389 New Day procedure 413
ctmpasswd utility CTMUE104 user exit
database passwords 211 New Day procedure 414
ctmping CTMUE105 user exit
automatic discovery 214 User Daily jobs 414
ctmping utility CTMUE106 user exit
Agent configuration information 212 User Daily jobs 414
communication status 26 ctmwhy utility
Watchdog facility 72 waiting jobs 302
ctmpsm utility customer support 3
Active Jobs file 219 customizing
job listing 225 Customization menu 342
mode descriptions 225 customization parameters 342, 363
Production Support menu 218 platform coordination 364
Resource Table options 222 CYCLIC_INTERVAL
scheduling function options 222 rule file global parameters 158
Scheduling tables 223 CYCLIC_MAXWAIT
syntax 225 Server parameter 390
ctmreindex utility CYCLIC_RERUN
description 236 Server parameter 390
ctmrpln utility
description 237
ctmruninf utility
Statistical Details table 240
D
summary 49 DAC time zone 52
ctmsec utility Dacca time zone 52
see also Security Maintenance utility Daily Job Order
summary 245 report 83
User Maintenance option 246 DAILY parameter
ctmshout utility ctmudchk utility 290
message distribution 270 Daily report
ctmshtb utility ctmrpln utility 237
Shout destination table 273 data
summary 360 CONTROL-M database 22
ctmstats utility ctmkeygen parameters 179

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

ctmsetown parameters 266 ctmcalc_date utility 101


data device name Date parameter
Sybase parameter 378 description 365
data device type DATE sub- parameter
Sybase parameter 378 ctmcalc_date utility 102
data device, physical Day Time * parameter 366
Sybase parameter 378 Day Time parameter
database description 366
application server information 163 New Day procedure 42
automatically check 313 Daylight Saving Time 58
available space 313 Daylight Savings Time 58
backup 93 DBASE events
CONTROL-M 22 problem detection 65
ctmgetcm utility 163 DBO password
dedicated instance 324 Oracle parameter 384
log files 380 Sybase parameter 378, 384, 436
parameters 377, 378, 380 dbversion utility 303
recovery procedure 318, 447 DEBUG
restoration 93 ctmping parameter 214
Server 325 DEBUG parameter
shared instance 324 ctmcalc_date utility 102
size 93, 378, 434, 436 debug parameter
Sybase SQL server 379 ctmvar utility 300
synchronization 340, 453 DEBUG_LEVEL
transaction listing 65 Agent parameter 401
transaction log 124 Server parameter 401
utilization 124 dedicated instance
verification 122, 124 database server 324
Database Administrator Login defining
Sybase parameter 435 application-specific jobs 145
Database Administrator Password CONTROL-M jobs 136
Sybase parameter 436 jobs for time zones 52
Database Administrator password DELETE parameter
Sybase 378 ctmnodegrp utility 200
Database Creation menu 326 deleting
database mirroring 417 backup devices 334
database restoring CONTROL-M log entries 196
assumptions 32 files 149
database size groups 250
ctmdbmused utility 129 prerequisite conditions 43, 105, 357, 368
ctmdbused utility 135 statistics 43, 240
Database Size parameter users 246
Sybase 378, 434, 436 diagnostic level
database statistics setting 357
ctmdbopt utility 130 Disabled status
database status communication 26
ctmdbcheck utility 125 Disappeared status
database usage Agent platform 26
ctmdbmused utility 129 DISCOVER
ctmdbused utility 135 ctmping parameter 214
Database version Discovering status
system parameter 365 communication 26
Date Control record discovery process 212
description 39 Do Remedy
modifying manually 293 AR Server 398
UDLAST parameter 43 ctmkeystore_mng 183
DATE parameter help ticket category 398

476 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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

help ticket item 399 entities


help ticket status 399 description 310
help ticket type 398 start 311
port number 398 stop 311
DO_CMD entity authorization
ctmfw action 159 Security Maintenance utility 257
DO_COND environment variables
ctmfw action 159 required 86
DO_EXIT setting 87
ctmfw action 159 EST time zone 51
DO_NOT _COPY_LOG_ TO_MIRROR event logger
configuration parameter 395 problem detection 64
DO_NOTOK executable path
ctmfw action 159 system parameter 365
DO_OK Executable Path parameter 366
ctmfw action 159 exits
-domail CTMUE101 410
e-mail parameter 116 CTMUE102 412
downloading CTMUE103 413
Active Jobs file 352, 357 CTMUE104 414
Drop Backup Device option CTMUE105 414
Database Maintenance 334 CTMUE106 414
DUMMY jobs 388 Watchdog facility 70, 71
DXB time zone 52 exporting
job definitions 147
Extend Database Size option
E Database Maintenance 335
EXTENDED sub- parameter
Eastern European Time 52 ctmcalc_date utility 102
Eastern Standard Time 51 extending
ecactltb utility CONTROL-M database 335
summary 304
ecaqrtab utility
description 305
EDIT parameter
F
ctmnodegrp utility 199 failover
EET time zone 52 levels 417
e-mail configuration overview 35
attached SYSOUT messages 397 procedures 317
ctmshout 397 Server platform 423
DOMAIL 397 FILE
-DOSHOUT 397 ctmfw parameter 152
parameters 397 ctmping parameter 214
-SHOUT 397 file
shout message destination 360 FileWatch.xml 155
e-mail parameter FILE parameter
-domail 116 ctmudchk utility 290
enabling File Watcher
user exits 409 panel 155
encpassword File Watcher utility 149
ctmsetown parameters 266 service trace 151
encryption file, Manual Conditions 188
SSL 244 filename
encryption key ctmkeygen parameters 179
ctmkeygen 179 ctmsetown parameters 266
ENDED time filename parameter
CONTROL-M log 29 ctmvar utility 299

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

FileWatch.xml Heartbeat monitor


import 155 active mode 62
firewall description 62
affect on communication 28 parameters 62
first database log file passive mode 62
Oracle parameter 380 help ticket
FLAG sub- parameter category 398
ctmcalc_date utility 102 item 399
forcing a job status 399
ctmorder utility 206 type 398
forcing download urgency 399
Active Jobs file 352 HKG time zone 52
foreign language modes HNL time zone 51
CJK 75 Hong Kong time zone 52
Latin1 75 Honolulu time zone 51
format host
ctmkeygen parameters 179 ctmsetown parameters 266
forms host name
FileWatch.xml 155 Agent platforms 25
FROM_TIME CONTROL-M/Agent 36
rule file global parameters 158 hot backup
Full Security * parameter 366 archive mode 329
Full Security parameter Oracle database 32, 34
description 366 HP-UX
usage 244 shared library path 86
FULLDETAILS
ctmping parameter 215
I
G Ignore Conditions file
description 369
GD_FORWARD configuration parameter 390 mask characters 369
general threshold % Ignore New Day Conditions parameter
ctmdbcheck utility 127 description 366
GET usage 43
ctmgetcm utility 163 import
GLOBAL FileWatch.xml 155
value for AUTOEDIT_INC_SEC 386 IMPORT_CAL mode
Global AutoEdit Variables ctmpsm utility 225
report 83 Index tablespace file
global variables Oracle parameter 380
batch utility (ctmvar) 297 init_prflag 357
GMT time zone 51 Input process communication port number
Greenwich Mean Time 51 operational parameter 374
GROUP input_file parameter
value for AUTOEDIT_INC_SEC 386 batch mode utilities 84
group scheduling install_mirror script 433, 440
AutoEdit variables 297 integrity
New Day procedure 46 failover planning 417
groups Inter Process Communication Port Number
assigning users to 245 operational parameter 374
interaction
Server-Agent 24
H interfaces file
directory 434
HAW time zone 51 INTERVAL
Hawaii time zone 51 rule file global parameters 157

478 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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

IOALOG events shared library path 86


problem detection 65 List All Devices option
IOALOG_DEL_INT Database Maintenance menu 333
Server parameter 390 List Backup Devices option
IP address Database Maintenance menu 333
arp command 373 LIST parameter
communication parameter 372 ctmnodegrp utility 199
LISTAJFTAB mode
ctmpsm utility 230
J LISTALL mode
ctmpsm utility 229
Jobname LISTCAL mode
CONTROL-M/Server log field 457 ctmpsm utility 225
Jobname field LISTDETAILS mode
CONTROL-M log 457 ctmpsm utility 232
JOBNAME parameter listener port number
ctmcalc_date utility 101 Oracle parameter 380, 441
Jobno field LISTFULL DETAILS mode
CONTROL-M log 457 ctmpsm utility 232
Jobno. LISTGROUP mode
CONTROL-M/Server log field 457 ctmpsm utility 230
jobs listing
CTMUE101 user exit 410 Active Jobs file 219
CTMUE102 user exit 412 job processing definitions 202
Disappeared status 26 jobs 225
order options 41 prerequisite conditions 105
ordering 410 scheduling tables 223
ordering by New Day procedure 43 statistics 174, 240
ordering manually 41 unordered jobs 290
retroactive ordering 40 LISTJOB mode
scheduling 44 ctmpsm utility 230
submitting 412 LISTSYSOUT mode
terminating 186 ctmpsm utility 232
User Daily 37 load balancing
jobs ordering overview 31
manually 204 resource usage 192
loading
Manual Conditions file 188
K LOCAL
value for AUTOEDIT_INC_SEC 386
Karachi time zone 52 Local IP Host Interface Name
Kernel Configuration parameter, Check 351 communication parameter 373
keyname Local IP Host Interface Name parameter 372
ctmsetown parameters 266 location
KHI time zone 52 user exits 407
killing Log device name
ctmkilljob utility 186 Sybase parameter 378
Log device type
Sybase parameter 378
L log files
archiving 66
language capabilities
CONTROL-M 49
CJK 75
generation limits 67
Latin1 75
managing 66
Last Run date
problem detection 64
Date Control record 39
purged by New Day procedure 50
level, Restricted security 244
renaming 66
Linux

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

size limits 67 operational parameter 374


size monitor 64 Maximum Server Processes parameter 374
log physical device MEL time zone 52
Sybase parameter 379 Melbourne time zone 52
Logdate Memname
CONTROL-M/Server log field 457 CONTROL-M/Server log field 457
Logdate field Memname field
CONTROL-M log 457 CONTROL-M log 457
logical devices menu, Production Support 218
adding 333 menu, Security Authorization 341
Logtime menus
CONTROL-M/Server log field 457 CONTROL-M main menu 322
Logtime field Database Creation 326
CONTROL-M log 457 Message
CONTROL-M/Server log field 457
Message field
M CONTROL-M log 457
messages, distribution of
MAIL_ADD_SUBJECT_PREFIX ctm2snmp utility 120
e-mail configuration parameter 398 Microsoft Windows
MAIL_TIMEOUT CONTROL-M/Server 30
e-mail configuration parameter 398 MIN_AGE
maintaining rule file global parameters 157
CONTROL-M database 93, 313 MIN_SIZE
database passwords 211 rule file global parameters 157
New Day procedure 42 minimal_age
security 245, 341 ctmfw parameter 154
Sybase SQL server 313 Minimum server processes
system parameters 282 operational parameter 374
maintenance Minimum Server Processes parameter 374
CONTROL-M menu 322 mirror database
Manual Conditions file 188 implementation 317
mask characters Oracle 384
Ignore Conditions file 369 parameters 383
Master Device Type port numbers 384, 419
Sybase parameter 379 primary database 318
Master physical device QUERY_SPN field 419
Sybase parameter 379 rebuilding primary database 319
Max Wait parameter Sybase 384, 419
New Day procedure 42 synchronization 340, 453
MAX_AGE mirror database data device
rule file global parameters 158 Sybase parameter 384
MAX_GET_HOST _RETRIES parameter 396 mirror database log device
MAX_GET_HOST_RETRIES Sybase parameter 383
Server parameter 401 mirroring
Maximum Days Retained by CONTROL-M Log Server environment 423
system parameter 42, 367 mode
Maximum Days Retained by CONTROL-M Log parameter ctmfw parameter 153
367 modifying
Maximum Days to Retain Sysout Files environment variables 85
system parameter 42 MON_SIZE_ WILDCARD
Maximum job state changes rule file global parameters 158
operational parameter 374 monitoring
Maximum Retries * parameter 367 Quantitative resources 192
Maximum Retries parameter 376 Monthly Job Order
description 367, 376 report 83
Maximum server processes Monthly report

480 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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

ctmpln utility 237 NODETYPE


Mountain Standard Time 51 ctmping parameter 213
Msgid NOT_ORDERED_ JOB_ALERT parameter 391
CONTROL-M/Server log field 457 NOU time zone 52
MSGID field Noumea time zone 52
CONTROL-M log 457
MSSQL
dbversion utility 303
display general description 303
O
MSSQL databases Odate
backing up 34 CONTROL-M log 457
backup procedure 34 CONTROL-M/Server log field 457
MST time zone 51 ctmcontb utility 107
ctmcreate utility 116
ctmdefine utility 140
N ctmorder utility 113, 205
Date Control record 39
name Date parameter 365
ctmkeygen parameters 178 description 42
network interface card New Day procedure 42
listening for messages 373 working date 39
local IP host 373 odate
Network Management applications time zone support 52
ctm2snmp utility 120 odate_option parameter
New Day procedure ctmorder utility 207
Active Jobs file 43 ON_GROUP_END OK actions
CTMUE103 user exit 413 New Day procedure 46
CTMUE104 user exit 414 ON_GROUP_END_OK actions
Daylight Saving Time 59 New Day procedure 46
description 42 ONLY_WORKING _DAYS parameter
group scheduling 46 ctmcalc_date utility 101
ordering jobs 43 openssh
prerequisite conditions cleanup 368 public key file format 179
purging log files 50 Operating System parameter 367
restarting 351 Operating Systems
scheduling 44 ctmgetcm utility 162
sysout files cleanup 42 operational parameters
time zone support 53 description 373
UDLAST parameter 43 modifying 343
NEW_DAY_ASYNC_SP_EXECUTION Oracle
cleanup parameter 371, 390 backing up 330
Node group database logs 329
load balancing 31 Oracle Applications
menu 200 ctmgetcm utility 162
modifying 200 Oracle databases
usage 31 backing up 32
Node ID backup procedure 32
Agent platforms 25 restore procedure 33
node ID Oracle SQL server
ctmgetcm utility 163 home directory 381
displaying information 163 host parameter 381, 441
NODEGRP parameter listener port number 380, 441
ctmnodegrp utility 199 parameters 380, 434, 441, 443
NODEID ordering
ctmping parameter 212 jobs for time zones 390
nodeid parameter ordering jobs
ctmgetcm utility 163 New Day procedure 43

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

Orderno backup socket 379


CONTROL-M/Server log field 457 CONTROL-M/EM TCP/IP 374
Orderno field CONTROLM/Server 350
CONTROL-M log 457 mirror database 384
OS_DIAG_LIMIT_LOG_FILE_SIZE query socket 379
cleaning the log file 316 Server-to-Agent 377
Output POST_ODAT job status 229
ctmordck utility 202 post-processing
OUTPUT_FORMAT parameter performance parameters 385
ctmcalc_date utility 102 predefined time zones
Owner TimeZone.dat file 51
CONTROL-M/Server log field 457 Prerequisite Conditions
owner report 83
ctmsetown parameters 266 prerequisite conditions
Owner field adding 105
CONTROL-M log 457 cleanup 368
ctmcontb utility 105
deleting 43, 105, 357, 368
P listing 105
unscheduled 188
Pacific Standard Time 51 problem detection
panel IOALOG events 65
File Watcher 155 log file size monitor 64
parameters tools 64
Basic Communication and Operational 343 Process log file
CONTROL-M/Server 364 erasing contents 351
coordination 364 process, discovery 212
customization 342, 363 processes
database 377, 378 CONTROL-M/Server 352
performance 385 CONTROLM/Server 352
Sybase database 377, 378 suspending 281
system 365 proclog file
PARM1 AutoEdit variable stack trace output 67
User Daily jobs 39 product support 3
passphrase Production Support menu 218
ctmkeygen parameters 178 Protocol
password communication parameter 372, 401
ctmsetown parameters 266 communication with Agents 25
passwords PST time zone 51
database 211 public key file
path append 179
ctmkeygen parameters 179 copying to SSH server 179
path modification ctmkeygen 179
tcsh command 89 truncate 179
persistent connection
Agent Router 28
description 28
pinging
Q
ctmping utility 212 Quantitative resources
Polling interval parameter Agent platform usage 192
communication 377 ctmloadset utility 192
description 377 deleting 357
Port Number listing 305
SMTP parameter 347 maintaining 305
port numbers Quantitative Resources Status
Agent-to-Server 372 report 83
backup Server 320 Query Socket

482 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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

port number 379 REMEDY_ITEM


QUERY_SPN field Do Remedy parameter 399
mirror database 419 REMEDY_OPEN_TICKET_STATUS
QUIET Do Remedy parameter 399
ctmping parameter 214 REMEDY_PORT_NUMBER
quiet parameter Do Remedy parameter 398
ctmvar utility 299 REMEDY_REQUESTER_LOGIN
Quit Do Remedy parameter 399
SMTP parameter 347 REMEDY_REQUESTER_NAME
quotation marks Do Remedy parameter 399
AutoEdit variables 117, 141, 167, 280 REMEDY_SCHEMA
Do Remedy parameter 399
REMEDY_SERVER_NAME
R Do Remedy parameter 398
REMEDY_TYPE
RBS tablespace file Do Remedy parameter 398
Oracle parameter 380 REMEDY_USER_NAME
read permission Do Remedy parameter 398
assigning 90 remote host computer
rebuilding agent 23
CONTROL-M database 319 description 23
Sybase database 327 identification 23
recovery Remote Sybase host name
data center failure 320, 450 database parameter 379, 434, 435
database failure 318, 447 reordering jobs
failover planning 35 User Daily 290
regedit Reply–To Email
cluster environment 394 SMTP parameter 347
modifying parameters 394 report
registry Active Jobs File 83
cluster parameters 394 Associated Job Processing Definitions 83
parameter modification 394 Control Resources Status 83
relationship parameter CONTROL-M Log 83
New Day procedure 46 Daily Job Order 83
release version Global AutoEdit Variables 83
CONTROL-M/EM parameter 374 Monthly Job Order 83
REMEDY Prerequisite Conditions 83
passwords 183 Quantitative Resources Status 83
user and password creation 184 Runtime Statistical Data 83
user and password deletion 184 Summary Statistical Data 83
user and password modification 185 Yearly Job Order 83
user names 183 reporting
REMEDY Ketstore Menu CONTROL-M log entries 196
ctmkeystore_mng 183 reports
REMEDY Keystore ctmcontb utility 107
description 183 ctmlog utility 197
menu 183 ctmordck utility 202
REMEDY_CASE_SOURCE ctmrpln utility 237
Do Remedy parameter 399 description 83
REMEDY_CASE_TYPE ecactltb utility 304
Do Remedy parameter 399 job status 230
REMEDY_CATEGORY_NAME Resource Table options
Do Remedy parameter 398 ctmpsm utility 222
REMEDY_CLOSE_TICKET_STATUS Restore Database option
Do Remedy parameter 399 Database Maintenance 331
REMEDY_DEFAULT_URGENCY restoring
Do Remedy parameter 399 CONTROL-M database 131, 331

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

ctmdbrst utility 131 job status 202


Restricted security level 244 levels 244
Retro parameter permission assignment 90
job processing 40 Restricted security level 244, 366
Retry Interval parameter 377 Secure Socket Layer 371
description 377 Security Authorization menu 341
return e-mail address 347 setting levels 366
Rio de Janeiro time zone 51 Unrestricted security level 244, 366
RIO time zone 51 Security Authorization menu 341
Rollback segment tablespace file security level, Restricted 244
Oracle parameter 380 Security Maintenance utility
run_date Active Jobs file 254
ctmorder utility 207 adding groups 250
RUNINF_CUTOFF_ NUMBER parameter 391 adding users 246
RUNINF_CUTOFF_ RATIO parameter 391 batch mode 261
RUNINF_PURGE_LIMIT deleting groups 250
Server parameter 43, 391 deleting users 246
RUNINF_PURGE_MODE description 245
Server parameter 392 entity authorization 257
Runtime Statistical Data menu 341
report 83 Scheduling table authorization 252
runtime statistics 48 security, application 243
Sender Email
SMTP parameter 347
S Sender Friendly Name
SMTP parameter 347
SAP Server
ctmgetcm utility 162 failover 423
SCHEDTAB mode Server-to-Agent
ctmpsm utility 231 port numbers 377
SCHEDTAB parameter Server-to-Agent Port Number parameter 377
ctmcalc_date utility 101 service trace
scheduling function options File Watcher utility 151
ctmpsm utility 222, 223 shared instance
scheduling jobs database server 324
New Day procedure 44 shared library path
performance parameters 385 AIX 86
scheduling tables HP-UX 86
authorization 252 Linux 86
ctmpsm utility 225 Solaris 86
defining jobs 136 SHIFT parameter
listing jobs 237 ctmcalc_date utility 101
scope Shout Destination tables
AutoEdit variables 297 active table 273
Secure Socket Layer ctmsys utility 282
ctmsys utility 287 description 47
Secure Sockets Layer maintenance 282
encryption 244 specifying destinations 48
Secure Sockets Layer parameter 367 Shout facility
security ctmcpt utility 110
application 243 description 47
assigning users to groups 245 Shout messages
authorizations 244 Agent platforms 284
ctmsec maintenance utility 245 CONTROL-M/EM 284
database 245 ctmshout utility 270
export defintion tables 341 Daylight Saving Time 58, 60
import definition tables 341 Show Database Parameters option

484 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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

Database Maintenance menu 337 Statistical Summary table


SID mirror ctmstats utility 277
Oracle parameter 384 statistics
Simple Mail Transfer Protocol compiling 174
parameter 343 ctmdbopt utility 130
size monitor ctmjsa utility 48
log files 64 deleting 43, 240
size of database log files listing 174, 240
Oracle parameter 381 overview 48
Sleep Time runtime 48
considerations 358, 385 summary mode 375
resetting 357 systems parameter 48, 368
SMTP viewing 277
CONTROL-M/Server e-mail address 347 Statistics * parameter 368
port number 347 Statistics Mode parameter 375
relay 347 description 48, 174, 375
return e-mail address 347 Statistics Summary table
SMTP Server (Relay) Name ctmjsa utility 48
SMTP parameter 347 statistics, runtime 48
SNMP traps STATS_TIME
ctm2snmp utility 120 Server parameter 392
Solaris status
shared library path 86 job status 230
space usage stop
database 133 entities 311
specific purpose jobs STOP_TIME
creating 111 rule file global parameters 158
SSH stop_time
algorithm 171 ctmfw parameter 154
compression 171 stopping
ctmhostmap utility 171 CONTROL-M/Server 310, 324
port 171 ctmkilljob utility 186
secure shell 171 Sybase SQL server 325
SSH Tectia SUBMITTED AT time
on UNIX 179 CONTROL-M log 29
on Windows 179 Subsystem
ssh2 CONTROL-M/Server log field 457
public key file format 179 Subsystem field
-sshalg CONTROL-M log 457
SSH encryption algorithm 171 Summary Statistical Data
-sshport report 83
SSH port number 171 support, customer 3
stack trace Sybase
debugging 67 backing up 330
problem detection 64 rebuilding database 327
proclog file 67 reindex utility 236
start Sybase databases
entities 311 backing up 34
Start Day of the Week * parameter 368 backup procedure 34
Start Day of the Week parameter 368 Sybase Interface Directory
start_time Sybase parameter 434
ctmfw parameter 154 Sybase interface directory
starting database parameter 379
CONTROL-M/Server 310, 324 Sybase parameter
Sybase SQL server 325 log physical device 379
Statistical Details table Master physical device 379
ctmjsa utility 48 owner 378, 435

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

Sybase SQL server time


character set 420 CONTROL-M functions 29
considerations 419, 421, 422 Time From parameter
database mirroring 419 Job Submission window 29
database name 379 Time Until parameter
database parameters table 377, 378 Job Submission window 29
dedicated 419 time zones
maintenance 313 default values 51
starting 325 enabling early job ordering 390
stopping 325 TimeZone.dat file 51
SYD time zone 52 Timeout parameter
Sydney time zone 52 description 376
synchronization TimeZone.dat
database 340, 453 file with predefined time zones 51
mirror database 340, 453 TOK time zone 52
SYSOUT Tokyo time zone 52
attach to an e-mail message 397 trace file
sysout files File Watcher utility 151
cleanup by New Day procedure 42 transferring
sysout log directory files 149
system parameter 365 Troubleshooting
SYSOUT_LIMIT_SIZE parameter 392 menu 350
SYSOUT_WINDOW_ SIZE parameter 393 report 354
SYSTEM truncate
value for AUTOEDIT_INC_SEC 386 replace details of the users 266
system parameters replace SSH key details 179
description 365 TYO time zone 52
maintenance 282 type
System User Daily ctmkeygen parameters 178
UDLAST parameter 43
System user password
Oracle parameter 381 U
UDLAST parameter
T description 39
New Day procedure 43
Tablespace User Daily 43
data file 381 UDLY_PARTCOPY_ ERR parameter 393
Oracle SQL server 421 ue_exit directory
size 381 user exits 410
user 381 Unavailable status
Tasktype 457 Agent platform 26
CONTROL-M/Server log field 457 Unknown status
Tasktype field Agent platform 29
CONTROL-M log 457 unordered jobs
TCP/IP host name parameter listing 290
compatibility 373 User Daily jobs 290
TCP/IP port number Unrestricted security level
CONTROL-M/EM 374 description 244
TCP/IP protocol UPDATEAJF mode
Agent communication 25 ctmpsm utility 233
tcsh command UPDATEGROUP mode
environment variables 87 ctmpsm utility 234
path modification 89 UPDATETABLE mode
technical support 3 ctmpsm utility 234
terminating user
jobs 186 change password 110

486 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


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

first password 110 ctmgrpdef 165


register 110 ctmjsa 174
User Daily ctmkeystore_mng 183
AutoEdit variable %%PARM1 39 ctmkilljob 186
ctmordck utility 202 ctmldnrs 188
CTMUE105 user exit 414 ctmloadset 192
CTMUE106 user exit 414 ctmlog 196
Date Control record 39 ctmordck 202
example 38 ctmorder 204
interruptions 40 ctmping 212
reordering jobs 290 ctmpsm 218
scheduling 44 ctmreindex 236
workflow 37 ctmrpln 237
User Daily jobs ctmruninf 240
checking 290 ctmsec 246
ctmudly utility 294 ctmshout 270
last run date 293 ctmstats 49, 277
listing job definitions 202 ctmstvar 280
unordered jobs list 290 ctmsuspend 281
user exits ctmsys 282
configuration parameters 400, 409 ctmudchk 290
enabling 409 ctmudlst 293
location 407 ctmudly 294
Watchdog facility 71 ctmvar 297
workflow 409 ctmwhy 302
User Maintenance option deldumpdev 454
ctmsec utility 246 ecactltb 304
User Name ecaqrtab 305
ctmordck utility 202 environment variables 85
User password make_db 453
Oracle parameter 381 Oracle variables 87
utilities output destination 84
addumpdev 454 reference table 80
batch mode 84 reports 83
clean_ajf 454 summary table 77
ctm_backup_bcp 93 Sybase variables 86
ctm_clean_db 453 time zone support 53
ctm_cleanlog 454 user access 85
ctm_db_extend 454 utility
ctm_logdb_extend 454 ctm_diag_comm 95
ctm_restore_bcp 97
ctm_rollback_extend 454
ctm_tempdb_extend (Oracle) 454
ctm_tempdb_extend (Sybase) 454
V
ctm2snmp 120 value_date
ctmcontb 105 ctmorder utility 207
ctmcreate 111 var parameter
ctmdbbck 122 ctmvar utility 299
ctmdbcheck 124 varexpr parameter
ctmdbrst 131, 454 ctmvar utility 299
ctmdbspace 133 verifying
ctmdbtrans 134 database integrity 122
ctmdefine 136 User Daily jobs 290
ctmdiskspace 146 VIEW
ctmexdef 147 ctmgetcm utility 163
ctmfw 149, 151 View NodeID Details menu
ctmgetcm 162 description 348

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

VIEW parameter Watchdog exit 72


ctmnodegrp utility 200 WD_USEREXIT__SCRIPT_FILE
viewing Watchdog exit 72
statistics 277 WD_USEREXIT__SUSPEND_STATE
Watchdog exit 72
WD_USEREXIT__TIMEOUT parameter
W Watchdog exit 72
WD_USEREXIT_NUMBER parameter
Wait Condition job status 229 Watchdog facility 69
WAIT_ODAT job status 229 Western European Time 51
Watchdog facility WET time zone 51
configuration parameters 401 Windows service
description 69 CONTROL-M/Server 310
error handlers 72 workflow
parameters 401 New Day procedure 42
predefined exits 70 scheduling jobs 44
problem detection 64 User Daily jobs 37
user exits 71 write permission
Watcher utility 149 assigning 90
WD_ALIVE_MSG parameter
Watchdog facility 73
WD_CTMEXIT__CMD_LINE parameter
Watchdog exit 71
Y
WD_CTMEXIT__ERROR_MSG parameter Yearly Job Order
Watchdog exit 71 report 83
WD_CTMEXIT__INTERVAL parameter Yearly report
Watchdog exit 71 ctmpln utility 237
WD_CTMEXIT__RUN_STATE parameter
Watchdog exit 71
WD_CTMEXIT__SCRIPT_FILE parameter
Watchdog exit 71
WD_CTMEXIT__SUSPEND_STATE
Watchdog exit 71
WD_CTMEXIT__TIMEOUT parameter
Watchdog exit 71
WD_CTMEXIT_NUMBER parameter
Watchdog facility 69
WD_CTO_HOSTNAME parameter
Watchdog facility 73
WD_CTO_TIMEOUT parameter
Watchdog facility 73
WD_ERROR_HANDLER_SCRIPT_FILE
Watchdog facility 73
WD_ERROR_HANDLER_TIMEOUT
Watchdog facility 73
WD_HEARTBEAT_INTERVAL exit
Heartbeat check 70
WD_INTERVAL parameter
Watchdog facility 73
WD_USEREXIT_# _SUSPEND_ STATE parameter 405
WD_USEREXIT__CMD_LINE parameter
Watchdog exit 71
WD_USEREXIT__ERROR_MSG
Watchdog exit 71
WD_USEREXIT__INTERVAL parameter
Watchdog exit 72
WD_USEREXIT__RUN_STATE parameter

488 CONTROL-M/Server for UNIX and Microsoft Windows Administrator Guide


Notes
*70241*
*70241*
*70241*
*70241*
*70241*

You might also like