Anda di halaman 1dari 190

CONTROL-M/Enterprise Manager

Utility Guide

Supporting
CONTROL-M/Enterprise Manager version 6.2.01

May 1, 2005
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 2005 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.
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/Enterprise Manager Utility Guide
Contents
About this book 9
How this book is organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Online and printed books. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Access online books. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Request additional printed books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Command line conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 1 Introduction 13
Utilities described in this book. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Utilities not described in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 2 Command Line Interface utility (cli) 17

Chapter 3 Job utilities 23


defjob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
copydefjob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
defjobconvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
deldefjob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
duplicatedefjob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
exportdefjob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
updatedef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Chapter 4 Calendar utilities 107


defcal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
copydefcal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
exportdefcal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Chapter 5 Scheduling table utilities 121


deftable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
exportdeftable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Contents 5
Chapter 6 Administration utilities 139
check_gtw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
cryptocli . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
ctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Chapter 7 Database maintenance utilities 155


db_check. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
db_check_space. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
util . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Chapter 8 Build database utility 167


build_db (build database) utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Dedicated server creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Dedicated server cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Creating a dedicated server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Existing server creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Existing server cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Verification of existing components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Creating a Sybase database on an existing database server . . . . . . . . . . . . . . . . . 170
Existing database cleanup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Configuring a Sybase client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
build_db parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
build_db log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Appendix A XML File Preparation 173


CONTROL-M/EM Utility Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Preparing an Input File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Index 181

6 CONTROL-M/Enterprise Manager Utility Guide


Tables
Utility types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Utilities not included in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
cli utility parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
cli utility Job Delete parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Job Definition utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
defjob parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
defjob switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
defjob input file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
copydefjob parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
copydefjob switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
copydefjob arguments file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
defjobconvert parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
deldefjob parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
deldefjob arguments file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
duplicatedefjob parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
duplicatedefjob switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
duplicatedefjob arguments file tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
exportdefjob parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
exportdefjob arguments file Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
updatedef parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
updatedef switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Arguments file parameters for scheduling tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Arguments file parameters for group scheduling tables . . . . . . . . . . . . . . . . . . . . . . . 85
Arguments file parameters for jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Calendar utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
defcal parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
defcal input file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
copydefcal parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
copydefcal arguments file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
exportdefcal parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
exportdefcal arguments file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Table utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
deftable parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
deftable switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
deftable input file parameters for scheduling tables . . . . . . . . . . . . . . . . . . . . . . . . . . 124
deftable input file parameters for group scheduling tables . . . . . . . . . . . . . . . . . . . . 125
exportdeftable parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
exportdeftable arguments file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Administration utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
check_gtw utility parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Tables 7
check_gtw_ue user exit parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
ctl parameters for the Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
ctl parameters for the Global Conditions Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
ctl parameters for the GUI Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
ctl parameters for the Global Alerts Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
ctl parameters for the Administration Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
ctl parameters for the BMC Batch Impact Manager Server . . . . . . . . . . . . . . . . . . . . . 153
Database maintenance utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
db_check utility parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
db_check_space utility parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
DB_ARGS database arguments fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
util utility – functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
util utility – function parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Build database modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Sybase database server parameters – minimum values . . . . . . . . . . . . . . . . . . . . . . . 169
build_db parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Utility Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
CONTROL-M/EM utility .dtd files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Reserved character codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

8 CONTROL-M/Enterprise Manager Utility Guide


About this book
This book contains information about batch utilities supplied with
CONTROL-M/Enterprise Manager (CONTROL-M/EM). Use this book with the
following guides:

■ CONTROL-M/EM User Guide (version 6.2.01)


■ CONTROL-M/EM Administrator Guide (version 6.2.01)
■ CONTROL-M Job Parameter and AutoEdit Variable Reference Guide (version 6.2.01)
■ CONTROL-M/Desktop User Guide (version 6.2.01)

How this book is organized


Chapter Description
Chapter 1 Introduction
Provides an overview of CONTROL-M/EM batch utilities.
Chapter 2 Command Line Interface utility (cli)
Describes the cli utility and the means for invoking it.
Chapter 3 Job utilities
Describes utilities for creation and manipulation of job processing definitions.
Chapter 4 Calendar utilities
Describes the utilities for creation and manipulation of Calendar definitions.
Chapter 5 Scheduling table utilities
Describes the utilities for creation and manipulation of Scheduling table and
Group Scheduling table definitions.
Chapter 6 Administration utilities
Describes various CONTROL-M/EM component administration utilities.
Chapter 7 Database maintenance utilities
Describes the database management utilities and the means for invoking them.
Chapter 8 Build database utility
Describes how to build a dedicated Sybase database server, define a
CONTROL-M/EM Sybase database, and configure a Sybase database
client.
Appendix A XML File Preparation
Procedures for creating input and argument files for XML-based utilities.
Index

About this book 9


Related documentation

Related documentation
The following BMC publications are relevant to CONTROL-M/EM.

■ CONTROL-M/Enterprise Manager User Guide describes CONTROL-M/EM


concepts, features, facilities, and operating instructions.

■ CONTROL-M/Desktop User Manual describes how to define and manage


CONTROL-M job processing definitions, Scheduling tables, and Calendars.

■ CONTROL-M/Enterprise Manager Administrator Guide describes how to define,


monitor, and maintain the CONTROL-M/EM environment.

■ CONTROL-M/Enterprise Manager Installation Guide describes the installation


processes for implementing an CONTROL-M/EM environment on Microsoft
Windows and Unix platforms.

■ CONTROL-M/Enterprise Manager API Developers Guide describes how to enable


your applications to submit requests to CONTROL-M/EM.

■ CONTROL-M Job Parameter and Variable Reference Guide describes the


parameters used for creating and manipulating job processing definitions.

■ CONTROL-M/Server Administrator Guide describes installation, setup, security,


and utilities on various CONTROL-M platforms (for example, Unix and Microsoft
Windows).

■ CONTROL-M for OS/390 and z/OS User Guide is a guide to the CONTROL-M
Production Control System in a mainframe environment.

Online and printed books


The books that accompany BMC Software products are available in online format and
printed format. You can view online books with Acrobat Reader from Adobe
Systems. The reader is provided at no cost, as explained in “Access online books.”
You can also obtain additional printed books from BMC Software, as explained in
“Request additional printed books.”

10 CONTROL-M/Enterprise Manager Utility Guide


Access online books

Access online books


Online books are provided as Portable Document Format (PDF) files. You can view
them, print them, or copy them to your computer by using Acrobat Reader 3.0 or
later. You can access online books from the documentation compact disc (CD) that
accompanies your product or from the World Wide Web.

In some cases, installation of Acrobat Reader and downloading the online books is an
optional part of the product-installation process. For information about downloading
the free reader from the Web, go to the Adobe Systems site at http://www.adobe.com.

To view any online book that BMC Software offers, visit the support page of the BMC
Software Web site at http://www.bmc.com/support.html. Log on and select a product
to access the related documentation. (To log on, first-time users can request a user
name and password by registering at the support page or by contacting a BMC
Software sales representative.)

Request additional printed books


BMC Software provides a core set of printed books with your product order. To
request additional books, go to http://www.bmc.com/support.html.

Conventions
The following abbreviations are used in this guide:

Abbreviation Description
Net CONTROL-M/EM Network
$HOME, home-directory Directory in which CONTROL-M/EM is installed

The following conventions are used in this guide:

key When describing keystrokes, the name of a key (for example, F1) is
in boldface type. When two keys are joined with “+” as in Shift+F1,
hold down Shift while pressing F1.
Menu => Option This represents an option selection sequence. For example,
Users and Groups => Groups => Add
means that you first select Users and Groups from the menu bar.
Select the Groups option from the submenu. Finally, select the Add
option from the Groups submenu.

About this book 11


Command line conventions

{Option A|Option B} The vertical bar is used to separate choices. For example:
{AND|OR}
means that you specify either AND or OR.
[Option] Square brackets are used to enclose parameters that are optional.
Code Samples Format syntax, operating system terms, examples,
and JCL scripts are presented in this typeface.
Boldface In instructions, boldface type highlights information that you enter.
File names, directory names and paths, and Web addresses also
appear in boldface type.
Italics Italic type is used to emphasize important terms. The titles of BMC
Software product documentation are also displayed in italic type.
Ellipsis An ellipsis ( . . . ) indicates that you can repeat the preceding item or
items as many times as necessary.
Option Symbol A vertical bar ( | ) separating items indicates that you must choose
one item. In the following example, you would choose a, b, or c:
a|b|c

Command line conventions


Parameters for running utilities from the command line can be specified in

■ short format, for example, -u user -p pass -s gui_server_name


■ long format, for example,
-USERNAME user, -PASSWORD pass, -HOST gui_server_name
■ uppercase or lowercase letters

The following table lists the parameters that can be specified in both short and long
formats.

Parameter Short Format Long Format


User name -u (or -U) -username (or -USERNAME)
User password -p (or -P) -password (or -PASSWORD)
Host computer -s (or -S) -host (or -HOST)
Source file -src (or -SRC) -src_file (or -SRC_FILE)
Argument file -arg (or -ARG) -arg_file (or -ARG_FILE)
Output file -out (or -OUT) -out_file (or -OUT_FILE)

Most of the examples in this book use the lowercase, short format.

12 CONTROL-M/Enterprise Manager Utility Guide


Chapter

1
1 Introduction
Utilities can be used to perform common CONTROL-M/Enterprise Manager
(CONTROL-M/EM) tasks from the command prompt of any computer where
CONTROL-M/EM client components are installed.

Although almost every task performed by these utilities can be performed using the
CONTROL-M/EM GUI or the Administration facility, the utilities enable you to work
at computers that do not have the GUI or the Administration facility installed on
them. By including a utility command in the command line of a job processing
definition, you can automatically run the utility at a predetermined time or under a
predetermined set of conditions.

NOTE
You can also create and run jobs for specified applications (for example SAP or Oracle
Applications), although you cannot do this using the utilities. For more information, see the
Administrator Guide for the appropriate CONTROL-M/Control Module.

Chapter 1 Introduction 13
Utilities described in this book

Utilities described in this book


The types of utilities described in this book are listed in Table 1.

Many CONTROL-M/EM utilities are implemented by using input and argument


files written in Extensible Markup Language (XML). Instructions for preparing these
XML files are presented in Appendix A, “XML File Preparation.”

NOTE
A valid CONTROL-M/EM user name and password are required to run CONTROL-M/EM
utilities. Additionally, you must have the appropriate authorization to either copy from or
modify entities in CONTROL-M/EM. For more information, see the Security chapter in the
CONTROL-M/Enterprise Manager Administrator Guide.

Types of utilities

Table 1 Utility types


Type of utilities Description
Command line The Command Line Interface (cli) is a batch utility that enables you to
interface perform the following operations (services) from the command line:
■ Upload or Download Scheduling tables
■ Order or Force Scheduling tables
■ Order or Force jobs
■ Force jobs in a Group Scheduling table
■ Upload or Download Calendars
■ Delete job processing definitions from Scheduling tables
For information about cli, see Chapter 2, “Command Line Interface
utility (cli).”
Job You can create, modify, and delete job processing definitions with the
utilities described in Chapter 3, “Job utilities.”
Calendar You can create and modify Calendar definitions with the utilities
described in Chapter 4, “Calendar utilities.”
Scheduling table You can create and modify scheduling table and group scheduling table
definitions with the utilities in Chapter 5, “Scheduling table utilities.”
Administration You can monitor and manage selected elements of CONTROL-M/EM
using the utilities described in Chapter 6, “Administration utilities.”
Database You can maintain the CONTROL-M/EM database using the utilities
maintenance described in Chapter 7, “Database maintenance utilities.”
Build database You can build a dedicated Sybase server, define a CONTROL-M/EM
utility database, and configure a Sybase database client using the build_db
utility described in Chapter 8, “Build database utility.”

14 CONTROL-M/Enterprise Manager Utility Guide


Utilities not described in this book

Utilities not described in this book


CONTROL-M/EM includes a number of utilities that are used infrequently, often
only under very specific conditions. These utilities are described below:

Table 2 Utilities not included in this book


Utility name Description
emenablepriv Opens the Windows Task Manager window with the privileges required to
stop CONTROL-M/EM processes. For more information, see the
CONTROL-M/Enterprise Manager Administrator Guide.
migrate_dc This utility is used for upgrading CONTROL-M/Enterprise Manager
installations to version 6.2.01. For more information, see the
CONTROL-M/Enterprise Manager Migration Guide.

Chapter 1 Introduction 15
Utilities not described in this book

16 CONTROL-M/Enterprise Manager Utility Guide


Chapter

2
2 Command Line Interface utility (cli)
The Command Line Interface (cli) utility is a batch utility that enables you to perform
the following operations (services) from the command line:

■ Upload or Download scheduling tables


■ Order or Force scheduling tables
■ Order or Force jobs
■ Force jobs in a group scheduling table
■ Upload or Download calendars
■ Delete job processing definitions from scheduling tables

The cli utility can be used on Unix and Microsoft Windows computers. The cli utility
is installed automatically on Microsoft Windows computers during installation of the
CONTROL-M/EM Gateway, GUI Server, and Administration Facility components.

Many of the tasks performed by the cli utility can also be performed using
CONTROL-M/EM and CONTROL-M/Desktop. However, by including a utility
command in the command line of a job processing definition, you can run the utility
at a predetermined time or under a predetermined set of conditions without being
present.

To invoke the cli utility:

1. Change the working directory to the CONTROL-M/EM home directory.

2. Specify the following command, depending on your operating system:

Microsoft Windows

cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name


[-t timeout] [-DDMM] [-BY_FORCE] -service service_parameters
[-service service_parameters ...]

Chapter 2 Command Line Interface utility (cli) 17


Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name


[-t timeout] [-DDMM] [-BY_FORCE] -service service_parameters
[-service service_parameters ...]

The parameters in the above commands are described in Table 3.

Table 3 cli utility parameters


Parameter Description
db_user CONTROL-M/EM database user name.
db_pass CONTROL-M/EM database user password.
password_ Flat file containing an unencrypted user name and password on separate
filename lines in the format:
user=username
password=password
Note: If both -U and -pf are specified, an error message is generated. If only
-U is specified, an online prompt is issued for the password. If neither is
specified, a prompt is issued for both the database user name and password.
host_name Host name of the workstation running CONTROL-M/EM Server.
Note: If you need to address a GUI Server and multiple GUI Servers exist, set
this parameter to the logical name of the relevant GUI Server.
timeout Time, in seconds, that the utility waits for a response. Timeout is used to
override the default waiting period (120 seconds).
Note: Do not use timeout with commands that do not return a response
(-JOB_DELETE and -MEM_DELETE).
-DDMM If specified, reverses the Odate format, as described below.
service Name of the service. See service_parameters below.
service_ Service parameters used in the utility:
parameters control-m Name of the CONTROL-M installation.
table Name of the scheduling table.
calendar Name of the Calendar.
job_name Name of the job.
Odate Order date. Default format is MMDD or YYYYMMDD. If the
-DDMM flag is used, the format is DDMM or DDMMYYYY.

Default when using CONTROL-M/Server version 6.0.0x or


later: ODAT. Default when using a CONTROL-M/Server
prior to version 6.0.0x: the current date.

Note: You can also specify ODAT in place of a specific date.


This feature is supported for CONTROL-M/Server version
6.0.0x jobs and later.
library [MVS only] Library containing the table.
-BY_FORCE Forces the specified table or calendar. Use this option during
upload only.

18 CONTROL-M/Enterprise Manager Utility Guide


You can make multiple requests in a single operation. Each service requires its own
service name and includes all the relevant service parameters that follow it.

NOTE
You must have proper security authorization for any of the actions you perform using cli.

Following are a series of commands that enable you to perform various tasks.

To upload a scheduling table:

On Microsoft Windows

cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout]


-TABLE_UPLOAD control-m_table [Odat] [library]

On Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout]
-TABLE_UPLOAD control-m_table [Odat] [library]

To download a scheduling table:

On Microsoft Windows

cli [{(-U db_user -P db_pass) | -pf password_file}]


-h host_name [-t timeout] -TABLE_DOWNLOAD control-m_table [library]

On Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}]


-h host_name [-t timeout] -TABLE_DOWNLOAD control-m_table [library]

To force a scheduling table:

On Microsoft Windows

cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout] [-DDMM]
-TABLE_FORCE control-m table [Odate] [library]

On Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout]
[-DDMM] -TABLE_FORCE control-m_table [Odate] [library]

Chapter 2 Command Line Interface utility (cli) 19


To order a scheduling table:

On Microsoft Windows

cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout] [-DDMM]
-TABLE_ORDER control-m_table [Odate] [library]

On Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout]
[-DDMM] -TABLE_ORDER control-m_table [Odate] [library]

To upload a calendar:

On Microsoft Windows

cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout]


-CAL_UPLOAD control-m_calendar

On Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout]
-CAL_UPLOAD control-m_calendar

To download a calendar:

On Microsoft Windows

cli [{-U db_user -P db_pass | -pf password_file}] -h host_name [-t timeout]


-CAL_DOWNLOAD control-m_calendar

On Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout]
-CAL_DOWNLOAD control-m_calendar

To force a job:

On Microsoft Windows

cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout] [-DDMM]
-JOB_FORCE control-m_table job_name [Odate] [library]

20 CONTROL-M/Enterprise Manager Utility Guide


On Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout]
[-DDMM] -JOB_FORCE control-m_table job_name [Odate] [library]

To force a job into a group scheduling table:

On Microsoft Windows

cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout] [-DDMM]
-JOB_FORCE_INTO control-m_table job_name sched_group [duplication]
[Odate] [library]

On Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout]
[-DDMM] -JOB_FORCE_INTO control-m_table job_name sched_group
[duplication] [Odate] [library]

sched_group Group scheduling table into which the job is forced. Valid values:
RECENT Forces the job into the group scheduling table that was
run most recently.
NEW Creates a new group scheduling table.
STAND Forces the job without adding it to a group scheduling
ALONE table.
GROUPID Group scheduling table into which the job is forced.
[duplication] Adds a job to a table, even if there is a job with that name in the table.
Valid values:
■ Y – Adds the job, if required.
■ N – Does not create a duplicate job if a job of the same name
already exists
Note: This setting can be used only when RECENT or GROUPID are
selected for sched_group.

To order a job:

On Microsoft Windows

cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout] [-DDMM]
-JOB_ORDER control-m_table job_name [Odate] [library]

On Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name [-t timeout]
[-DDMM] -JOB_ORDER control-m_table job_name [Odate] [library]

Chapter 2 Command Line Interface utility (cli) 21


NOTE
When forcing or ordering a job, the CONTROL-M/EM does not check if multiple jobs with
the same name exist in the table.

To delete a job definition by Job Name:

On Microsoft Windows

cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name -JOB_DELETE


control-m table job_name delete_type [library]

On Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name -JOB_DELETE


control-m table job_name delete_type [library]

To delete a job definition by Mem Name:

On Microsoft Windows

cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name -MEM_DELETE


control-m_table mem_name delete_type [library]

On Unix

ecs cli [{(-U db_user -P db_pass) | -pf password_file}] -h host_name -MEM_DELETE


control-m_table mem_name delete_type [library]

Table 4 describes the parameters of the above delete commands.

Table 4 cli utility Job Delete parameters


Parameter Description
delete_type Indicates the type of operation to be performed. Valid values:
ALL All occurrences of the job are deleted, if there is more than
one job with the same name.
NONE No jobs are deleted if there is more than one job with the
same name.
sequence_number Deletes the job with the specified sequence number of the duplicate
job (for example, if 5 is entered, the fifth occurrence of the Job Name
is deleted).
library Required for MVS job definitions.

22 CONTROL-M/Enterprise Manager Utility Guide


Chapter

3
3 Job utilities
The utilities described in this chapter are used to create, modify, and delete job
processing definitions.

Many of the tasks performed by the job utilities can also be performed in real-time
using the Job Editing and Group Editing forms in CONTROL-M/EM and
CONTROL-M/Desktop. However, by including a utility command in the command
line of a job processing definition, you can run the utility at a predetermined time or
under a predetermined set of conditions without being present.

The utilities described in this chapter are listed in Table 5.

Table 5 Job Definition utilities


Utility Description
defjob Imports a job processing definition directly into a scheduling table. (See
page 24.)
copydefjob Copies a specified job processing definition to a different data center or
scheduling table. (See page 38.)
defjobconvert Converts non-XML format defjob input files into XML-based input files
for use with the CONTROL-M/EM 6.1.03 version of defjob. (See page 54.)
deldefjob Deletes a specified job definition. (See page 57.)
duplicatedefjob Creates a copy of a job in the same datacenter and scheduling table. (See
page 61.)
exportdefjob Imports a job processing definition directly from a scheduling table to a
text file. (See page 78.)
updatedef Modifies existing job processing definitions, scheduling table definitions,
and group scheduling table definitions. (See page 82.)

NOTE
The cli utility uploads, downloads, orders, and forces jobs. It is described in Chapter 2,
“Command Line Interface utility (cli).”

Chapter 3 Job utilities 23


defjob

defjob
The defjob utility imports job processing definitions directly into a scheduling table
in the CONTROL-M/EM database.

defjob reads job processing definitions from a plain text input file written in XML
format.

Each job processing definition in the CONTROL-M/EM database has a JOBISN field
that contains a unique number. If a job that is being imported contains a JOBISN
number that already exists in the CONTROL-M/EM database, defjob overwrites the
existing job processing definition with the new job processing definition. If a JOBISN
value is not specified, defjob imports the job processing definition into the database
as a new job.

To invoke the defjob utility:

1 Log on to a CONTROL-M/EM account (Unix)


- or -
open a command prompt window (Microsoft Windows) where CONTROL-M/EM
is installed.

2 Enter either of the following commands:

defjob [-u user [-p password] | -pf password_file]


-s gui_server_name -src src_file_name [/a]

- or -
defjob [-USERNAME user [-PASSWORD password] | -PASSWORD_FILE
password_file] -HOST gui_server_name -SRC_FILE src_file_name [/a]

Parameters of the defjob utility are described in Table 6.

3 Press Enter.
The defjob input file is checked and processed. If there are any errors in the file, a
message is displayed specifying the lines with the errors.

24 CONTROL-M/Enterprise Manager Utility Guide


defjob

Parameters

Table 6 defjob parameters


Parameter Description
user CONTROL-M/EM user name.
password CONTROL-M/EM user password.
password_file Flat file containing an unencrypted user name and password on separate
lines in the format:
user=username
password=password
Note: If both -u and -pf are specified, an error message is generated. If
only -u is specified, an online prompt is issued for the password. If neither
is specified, a prompt is issued for the database user name and password.
gui_server_name CONTROL-M/EM GUI server logical name, host name, or IP address.
Note: If multiple GUI servers exist, set this parameter to the logical name
of the relevant GUI server.
src_file_name The path and name of the XML file containing the defjob specifications.
For how to prepare this file, see Appendix A, “XML File Preparation.”

An optional switch for the defjob utility is described in Table 7.

Table 7 defjob switch


Switch Description
/a Accept all. The /a switch directs the utility to automatically reset the Author
parameter to the current CONTROL-M/EM user when these two values do not
match. If not specified, the utility skips (i.e., does not process) job definitions whose
Author does not match the currently logged in user.
Note: The /a switch has no effect on Administrator users and is relevant only when
the AuthorSecurity system parameter is set to 2 or 3.

defjob input file


The job definitions that you create for use with the defjob utility are written in XML
format and saved in a text file.

When this file is invoked, its contents are passed to the CONTROL-M/EM database
and imported into the scheduling table specified in the job definition in the file.
Instructions for creating input files are in Appendix A, “XML File Preparation.”

Chapter 3 Job utilities 25


defjob

The following rules apply to the input file of the defjob utility:

■ More than one job can be specified in a defjob file.


■ The input file is case-sensitive.
■ Although many parameters in Table 8 are optional, certain parameters are
required depending on the option specified for the TASKTYPE parameter. For
more information, see the Task Type description in the CONTROL-M Job Parameter
and Variable Reference Guide.
■ All parameter values (such as strings or digits) must be enclosed in quotation
marks (for example, JOBNAME="Job1").
■ Condition dates must be specified in mmdd format. Time must be 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.
■ Each ON_STMT or ON_STEP parameter must be followed by at least one DO
parameter. DO parameters are dependent upon the last ON_STMT or ON_STEP
parameter preceding them.

■ TAG_NAME and TAG_RELATIONSHIP parameters are optional for jobs in a


group scheduling table and invalid for jobs that are not in a group scheduling
table. Values specified for TAG_NAME and TAG_RELATIONSHIP are ignored if
the job definition being created is not included in a group scheduling table.

Input file parameters for the defjob utility are described in Table 8.

Table 8 defjob input file parameters (Part 1 of 11)


Parameter Description
The first two lines of the arguments file specify the XML version, the text encoding format being used, and the
location of the .dtd file. These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE DEFJOB SYSTEM "defjob.dtd"
DEFJOB Indicates to CONTROL-M/EM the beginning and end of the defjob utility. Job
processing definitions are placed between the opening and closing DEFJOB tags. One or
more jobs can be specified. Each individual job is enclosed by JOB /JOB tags.
JOB Indicates the opening and closing tags of a single job definition. Parameters of the job
are listed between the tags.
DATACENTER Name of the CONTROL-M installation to which the job belongs. String. Mandatory.
Note: At least one of the following scheduling table parameters must be included in the
input file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

26 CONTROL-M/Enterprise Manager Utility Guide


defjob

Table 8 defjob input file parameters (Part 2 of 11)


Parameter Description
TABLE_NAME Name of the scheduling table to which the job belongs. String. Mandatory.
Note: At least one of the following scheduling table parameters must be included in the
input file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

TABLE_DSN [MVS only] Name of the library that contains the scheduling table. String. Mandatory.
Note: At least one of these scheduling table parameters must be included in the input
file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

JOBNAME Name of the job processing definition. String. Mandatory.


Note: On a Microsoft Windows platform, JOBNAME must comply with Microsoft
naming conventions (for example, it cannot contain / and \ characters).
MEMNAME Name of the file that contains the job script. String. Optional.
GROUP Name of the group to which the job belongs. Used as a descriptive name for related
groups of jobs. String. Mandatory.
APPLICATION Name of the application to which the job’s group belongs. Used as a descriptive name
for related groups of jobs. String. Mandatory.
TASKTYPE Type of job (task) to be performed by CONTROL-M. Mandatory.
Valid values:
■ Job
■ Detached
■ Command
■ Dummy
■ External
[MVS only] Valid values:
■ Job
■ Started_Task

Note: In CONTROL-M/EM versions earlier than 6.1.00, the TASKTYPE format


contained critical and cyclic information. CONTROL-M/EM version 6.2.01 can run jobs
with the old TASKTYPE format. However, BMC Software recommends that you use
CYCLIC and CRITICAL parameters to specify this type of information when creating
new job processing definitions.
TABLE String. Optional.
_USERDAILY
AUTHOR CONTROL-M/EM user who defined the job. String. Mandatory.
Note: This argument is used by the CONTROL-M/Server security mechanism and,
under certain circumstances, cannot be modified. For more information, see the Security
chapter and the description of the AuthorSecurity system parameter in the
CONTROL-M/Enterprise Manager Administrator Guide.
MEMLIB Name of the library/directory in which the job script resides. String. Optional.
CMDLINE Command string supplied when the job Task Type is Command. String. Optional.

Chapter 3 Job utilities 27


defjob

Table 8 defjob input file parameters (Part 3 of 11)


Parameter Description
NODEID Host name of an Agent platform or name of a node group to which the job is submitted.
String. Optional.
OWNER Owner (user ID) associated with the job. This parameter is used by the
CONTROL-M/Server security mechanism. String. Optional.
MAXRERUN Specifies the maximum number of reruns that can be performed for the job. Optional.
Valid values: 0-99. Default: 0.
TIMEFROM Indicates the earliest time for submitting the job. String. Optional.
TIMETO Indicates the latest time for submitting the job. String. Optional.
DUE_OUT Time that the job is expected to finish. String. Optional.
PRIORITY Indicates CONTROL-M job priority. String. Optional.
CRITICAL Indicates that the job is a critical-path job in CONTROL-M. Optional. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

CYCLIC Indicates whether the job is cyclic (to be run at regular intervals). Optional. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

CONFIRM Indicates whether the job must be manually confirmed by the CONTROL-M/EM user
before it runs. Optional. Valid values:
■ 0 (Default)
■ 1

AUTOARCH Determines whether SYSDATA is to be archived. Optional. Valid values:


■ 0 (No-Default)
■ 1 (Yes)

INTERVAL Specifies the length of time (in minutes) to wait between reruns of a job or between
cyclic runs of a job. Integer. Optional.
Default: 0.
OVERLIB Name of an alternate job script library/directory. String. Optional.
MAXWAIT Number of extra days (beyond the original scheduling date) that the job is allowed to
remain in the Active Jobs file awaiting execution. Integer. Optional.
DESCRIPTION Free text description of the job. String. Optional.
DOCMEM Name of the file containing job documentation. String. Optional.
DOCLIB Name of a library or directory containing the job documentation file. String. Optional.
DAYS Days of the month on which to order the job. String. Optional.
DAYS_AND_OR Indicates the relationship between specified Days values and Weekdays values.
Optional. Valid values:
■ AND
■ OR

WEEKDAYS Days of the week on which to order the job. String. Optional.
DATE Specific dates on which to order the job. String. mmdd format. Optional.
For example, January 10 is written as: DATE="0110"
DAYSCAL Name of a user-defined calendar used to specify a set of days. String. Optional.

28 CONTROL-M/Enterprise Manager Utility Guide


defjob

Table 8 defjob input file parameters (Part 4 of 11)


Parameter Description
WEEKSCAL Name of a calendar to be used to validate specified weekdays on which to order the job.
String. Optional.
CONFCAL Specifies a calendar that is used to validate all specified days and dates on which to
schedule the job. String. Optional.
RETRO Indicates whether the job is scheduled for possible execution after its original scheduling
date (odate) has passed. Optional. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

SHIFT Describes how to shift the scheduling date of the job. Optional. Valid values:
■ IGNOREJOB
■ PREVDAY
■ NEXTDAY
■ NOCONFCAL

SHIFTNUM Number of days to shift the scheduling date of the job. Optional. Valid values: -62 to 62.
MAXDAYS Maximum number of days to retain the SYSDATA archive dataset for jobs that ended
NOTOK. Subparameter of AUTOARCH. Optional. Valid values: 00 – 98, or 99 to
indicate that SYSDATA is retained for an unlimited number of days.
MAXRUNS Maximum number of job runs to retain the SYSDATA archive dataset for jobs that
ended NOTOK. Subparameter of AUTOARCH. Optional. Valid values: 000 – 998, or 999
to retain SYSDATA data for all runs.
RERUNMEM Name of the JCL member to use when the job is automatically rerun. String. 1 - 8
characters. Optional.
RETEN_DAYS [MVS only] Number of days to retain the job in the History Jobs file. String. Optional.
RETEN_GEN [MVS only] Maximum number of generations of a job to keep in the History Jobs file
String. Optional.
PREV_DAY Flag to indicate whether job scheduling is shifted to a previous working day in the
CONFCAL calendar. Optional. Valid values:
■ Y
■ N

IND_CYCLIC Indicates whether the interval between further runs of a cyclic job is counted from the
start or the end of the previous job run. Optional. Valid values:
■ START
■ END

TAG Relationship (AND|OR) between the specified Schedule Tag criteria and the job’s own
_RELATIONSHIP basic scheduling criteria. This parameter is relevant only for jobs in a group scheduling
table. Optional. Valid values:
■ AND
■ OR

SYSDB Determines whether one or multiple data sets are used to catalogue sysdata. Optional.
Valid values:
■ 0 (Multiple-Default)
■ 1 (Single)

PDSNAME Name of a partitioned dataset (PDS) to be checked for free space. String. Optional.

Chapter 3 Job utilities 29


defjob

Table 8 defjob input file parameters (Part 5 of 11)


Parameter Description
MINIMUM Minimum number of free partitioned dataset tracks required by the library specified for
the PDSNAME parameter. Integer. Optional.
CATEGORY Name of a CONTROL-D report decollating mission category that must be scheduled
under CONTROL-D when the job is scheduled under CONTROL-M. String. Optional.
PREVENTNCT2 [MVS only] Prevents dataset cleanup before the original job run Optional. Valid values:
■ Blank – Does not perform data set cleanup before the original job run. Default.
■ N – Does not prevent cleanup.
■ Y - Prevents data set cleanup. This value is not valid for started tasks.
■ L (List) – Do not perform data set cleanup before the original job run. Do generate
messages that would be required for CDG adjustment during restart.
■ F (Flush) – Halt processing of the job if any data set cleanup error is detected (even if
MVS would not have stopped processing the job).
JAN, FEB, MAR, Months when the job can run. Valid values:
APR, MAY, JUN, ■ 0 (Not run. Default)
JUL, AUG, SEP, ■ 1 (Run)
OCT, NOV, DEC
OPTION Job output (sysout) handling options. Optional. Valid values:
■ Release
■ Delete
■ Copy
■ Move
■ File
■ NewDest
■ ChangeClass

PAR Certain OPTION values (such as Release, NewDest) require additional information.
String. Optional.
FROM Limits the sysout handling operation to only sysouts from the specified class. String.
Optional.
ADJUST_COND Indicates whether to ignore prerequisite conditions normally set by predecessor jobs if
the relevant predecessor jobs are not scheduled. This parameter is relevant only for jobs
in a group scheduling table. Optional. Valid values:
■ 0 (Do not ignore. Default.)
■ 1 (Ignore relevant prerequisite conditions)

JOBS_IN_GROUP Number of jobs in the group scheduling table. String. Optional.


CREATION_USER Name of the user who created the job. String. Optional.
CREATION_DATE Date on which the job was created. String. Optional.
CREATION_TIME Time at which the job was created. String. Optional.
CHANGE_USERID Name of the user who last modified the job. String. Optional.
CHANGE_DATE Date on which the job was last modified. String. Optional.
CHANGE_TIME Time at which the job was last modified. String. Optional.
JOB_RELEASE For internal use. Do not include this parameter in your defjob input file.
JOB_VERSION For internal use. Do not include this parameter in your deftable input file.

30 CONTROL-M/Enterprise Manager Utility Guide


defjob

Table 8 defjob input file parameters (Part 6 of 11)


Parameter Description
APPL_TYPE Indicates the type of external application (for example, SAP or Oracle Applications) on
which the external application job runs. String. Up to 10 characters. Mandatory for
external application jobs.
APPL_VER Version of the external application (for example, SAP or Oracle) on which the external
application job runs. String. Up to 10 characters. Mandatory for external application
jobs.
APPL_FORM Predefined set of external application parameters that are displayed in the Job Editing
form. String. Up to 30 characters. Mandatory for external application jobs.
CM_VER Indicates the version of external application (for example, SAP or Oracle Applications)
Control Module that is installed in the CONTROL-M installation. String. Up to 10
characters. Mandatory for external application jobs.
MULTY_AGENT When selected, broadcasts job submission details to all Agents in a specified Node
Group. Optional. Valid values:
■ Y – run as multi-agent job
■ N – not run as multi-agent job. Default.

ACTIVE_FROM [MVS only] Indicates the start of a period of time during which the job or group
scheduling table can be ordered. Optional.
Date Format: YYYYMMDD
ACTIVE_TILL [MVS only] Indicates the end of the time interval during which the job or group
scheduling table can be ordered. Optional. Date Format: YYYYMMDD
TIMEZONE Indicates the global time zone used to calculate the interval for time-related conditions.
String. Optional.
SCHEDULING [MVS only] Indicates the JES2 workload management scheduling environment
_ENVIRONMENT associated with the job. String. Optional.
SYSTEM Identity of the system in which the job must be initiated and executed (in JES2).
_AFFINITY Identity of the processor on which the job must execute (in JES3). String. Optional.
REQUEST_NJE Specifies the node in the JES network on which the job is to execute. String. Optional.
_NODE
JOBISN For internal use. String. Optional.
TAG_NAMES Wrapper for the tags listed with the TAG_NAME parameter. Optional.
Example:
TAG_NAMES TAG_NAME="tag1" TAG_NAME="tag2"
TAG_NAME Name of the schedule tags that apply to the group scheduling
table. Mandatory.

Chapter 3 Job utilities 31


defjob

Table 8 defjob input file parameters (Part 7 of 11)


Parameter Description
INCOND In condition. Optional.
Example:
INCOND NAME="Cond1" ODATE="ODAT" AND_OR="AND" OP="("
NAME Name of the In condition. String. Mandatory. 1 - 255 characters,
case-sensitive.
ODATE Order date of the In condition. String. Mandatory. Valid values:
Default: ODAT
AND_OR Relationship between conditions. Optional. Valid values:
■ AND (default)
■ OR

OP Parentheses indicating parts of the condition that are interpreted


first. String. Optional.
OUTCOND Out condition. Optional.
Example:
OUTCOND NAME="Job1" ODATE="ODAT" SIGN="ADD"
NAME Name of the Out condition. String. Mandatory.
1 - 255 characters, case-sensitive.
ODATE Order date of the Out condition. String. Mandatory. Valid values:
Default: ODAT
SIGN Indicates whether to add or delete the condition. Mandatory.
Valid values:
■ ADD (default)
■ DEL

AUTOEDIT Wrapper for the AutoEdit expression. Optional.


Example:
AUTOEDIT EXP="%%PARM1=%%TIME"
EXP The AutoEdit expression. String. Mandatory.
Example: %%PARM1=%%TIME.
QUANTITATIVE Wrapper for the Quantitative resource. Optional.
Example:
QUANTITATIVE NAME="TAPEDRIVE" QUANT="1"
NAME Name of the quantitative resource. String. Mandatory.
1 - 20 characters, case-sensitive.
QUANT Quantity of the resource. String. Mandatory. Valid values:
0 – 9999. Default: 1
CONTROL Wrapper for the Control resource. Optional.
Example:
CONTROL NAME="Resc1" TYPE="E"
NAME Name of the Control resource. String. Mandatory.
Valid values: 1-20 characters, case-sensitive, trailing blanks only.
TYPE Type of resource. Valid values:
■ E (exclusive-default)
■ S (shared)

32 CONTROL-M/Enterprise Manager Utility Guide


defjob

Table 8 defjob input file parameters (Part 8 of 11)


Parameter Description
SHOUT Wrapper for the Shout message. Optional. Example:
SHOUT WHEN="EXECTIME" DEST="workstation1" URGENCY="R"
MESSAGE="Jobcompleted OK." TIME="1015“
WHEN Condition under which the Shout message is sent. Mandatory.
Valid values:
■ OK (default)
■ NOTOK
■ RERUN
■ LATESUB
■ LATETIME
■ EXECTIME

DEST Recipient of the shout message. String. Mandatory.


Valid values: 1-16 characters, case-sensitive. Mandatory.
URGENCY Indicates the urgency of the Shout message. Mandatory.
Valid values:
■ R (regular-default)
■ U (urgent)
■ V (very urgent)

MESSAGE Text of the message. String. Mandatory. Valid values: 1 - 255


characters, spaces allowed.
TIME Time that the message is sent. String. Mandatory.
STEP_RANGE Step range in the job that can be used in an ON PGMST statement. Optional.
Example:
STEP_RANGE NAME="cleanup" FPGMS="Defrag" TPGMS=""
NAME Name for the range. 1-7 character string. Mandatory.
Valid values: 1 - 7 characters. Only trailing blanks are allowed.
FPGMS Name of the program to be run. as the first program step in the
range. 1 - 8 character string. Mandatory.
FPROCS Name of the procedure to be run. as the first procedure step in the
range. 1-8 character string. Mandatory.
TPGMS Last program step in the range. 1-8 character string. Mandatory.
Note: Subparameter TO is optional. If blank, its value defaults to
the last step in the job.
TPROCS Last procedure step in the range. 1-8 character string. Mandatory.
Note: Subparameter TO is optional. If blank, its value defaults to
the last step in the job.

Chapter 3 Job utilities 33


defjob

Table 8 defjob input file parameters (Part 9 of 11)


Parameter Description
ON Optional.
Example:
ON STMT="CODE" CODE="rt5" AND_OR="AND"><ON
STMT A character string containing a statement from the job script file.
String. 1-132 characters. Mandatory for the On Statement/Code
parameter..
CODE Return codes or statuses that can satisfy the step or code event
criteria if returned upon termination of the specified job steps.
String. Optional. Valid values: 1-132 characters.
PGMS Step in the program. String. Optional. Valid value: 1-8 characters.
PROCS Step in the process. String. Optional. Valid values:1-8 characters.
AND_OR Relationship between On statements. Optional. Valid values:
■ AND
■ OR

DO Specifies a status for the job based on conditions specified in an On statement. Optional.
Example:
DO ACTION="OK"
ACTION Mandatory. Valid values:
■ OK (Changes the status of the job to OK)
■ NOTOK (Changes the status of the job to NOTOK)
■ RERUN (Reruns the job)
■ SPCYC (Prevents further runs of a cyclic job)

DOSHOUT Shout message wrapper. Optional.


Example:
DOSHOUT DEST="Wkstn2" URGENCY="R" MESSAGE="Job5 completed OK"
DEST Recipient of the Shout message. String. Mandatory.
Valid values: 1 - 16 characters, case-sensitive.
URGENCY Urgency of the Shout message. Valid values:
■ R (regular-default)
■ U (urgent)
■ V (very urgent)

MESSAGE Text of Shout message. String, 1 - 255 characters, spaces allowed.


Mandatory.
DOCOND Specifies prerequisite conditions to be added or deleted. Optional.
Example:
DOCOND NAME="Cond1" ODATE="ODAT" SIGN="ADD"
NAME Condition name. String, 1 - 20 characters, case-sensitive.
Mandatory.
ODATE Condition date. String. Mandatory. Default: ODAT
SIGN Specifies whether to add or delete the condition. Valid values:
■ ADD (default)
■ DEL

34 CONTROL-M/Enterprise Manager Utility Guide


defjob

Table 8 defjob input file parameters (Part 10 of 11)


Parameter Description
DOAUTOEDIT Wrapper for the AutoEdit expression. Optional.
Example:
DOAUTOEDIT EXP="%%PARM1=%%TIME"
EXP The AutoEdit expression. String. Required.
Example: %%PARM1=%%TIME
DOFORCEJOB Forces a specified job when the current job is performed. Optional.
Example:
DOFORCEJOB DSN="45446" TABLE_NAME="Table2" NAME="Job4"
ODATE="ODAT"
DSN [MVS only] Library for scheduling table. String. Mandatory.
TABLE_NAME Name of the scheduling table to which the job belongs. String, 1-10
characters. Mandatory.
NAME Name of the job. String. Mandatory.
ODATE Original scheduling date for the job. String. Default: ODAT
DOSYSOUT Handle job output (sysout) when the job is done. Optional.
Example:
DOSYSOUT OPTION="Release" PAR="F" FROM=""
OPTION Sysout handling options. Mandatory. Valid values:
[All platforms]
■ Release
■ Delete
[not used with MVS]
■ Copy
■ Move
[MVS only]
■ File
■ NewDest
■ ChangeClass

PAR Certain OPTION values require that you supply additional


information (such as Release, NewDest). String. Optional.
FROM Limits the job output (sysout) handling operation to only sysouts
from the specified class. String. Optional.

Chapter 3 Job utilities 35


defjob

Table 8 defjob input file parameters (Part 11 of 11)


Parameter Description
DOIFRERUN Job steps to be executed during restart of a job. Available only at sites using
CONTROL-M/Restart. Optional.
Example:
DOIFRERUN CONFIRM="0" FPGMS="step1" FPROCS="proc1" TPGMS="step5"
TPROCS="proc3"
CONFIRM Indicates if job must be confirmed by user to be rerun.Valid
values:
■ 0 (No confirmation. Default)
■ 1 (Confirmation)

FPGMS Step at which the job must be restarted. String. 1 - 8 characters.


Mandatory.
FPROCS Program step within the called procedure. String. 1 - 8 characters.
Mandatory.
TPGMS Step at which restarted job must terminate. String. 1 - 8 characters.
Mandatory.
TPROCS Program step within the called procedure. String. 1 - 8 characters.
Mandatory.
DOMAIL Sends mail when the job run is complete. Optional.
Example:
DOMAIL URGENCY="R" DEST="emuser@emuser.com" CC_DEST="barry@emuser.com"
SUBJECT="OK" MESSAGE="Task completed OK."
URGENCY Urgency of the message. Valid values:
■ R (regular - Default)
■ U (Urgent)

DEST Recipient of the message. String. Mandatory.


CC_DEST Additional recipient of the message. String. Optional.
SUBJECT Brief text description of the message contents. String. Optional.
MESSAGE Text of the message. String. Mandatory.
DOCTBRULE [MVS only] Invokes a CONTROL-M/Analyzer rule to be executed during the
processing of a specific program step. Optional.
Example:
DOCTBRULE NAME="GOVTBAL" PAR="DOREPORT,10,%%ODATE"
NAME Name of the CONTROL-M/Analyzer rule. String. Mandatory.
PAR Arguments that are passed to the CONTROL-M/Analyzer rule.
String. Optional. Maximum: 45 characters.

The following sample input file is used with the defjob utility.

36 CONTROL-M/Enterprise Manager Utility Guide


defjob

Example: Command job that requires confirmation before running

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE DEFJOB SYSTEM "defjob.dtd">
<DEFJOB>
<JOB
TABLE_NAME="Tbl1"
TABLE_DSN="2232"
JOBNAME="Job1"
MEMNAME="Job1"
GROUP="ACCT"
APPLICATION="App3"
DATACENTER="CTMNYC"
TASKTYPE="Command"
TABLE_USERDAILY=""
MEMLIB="JobLib1"
OWNER="Brad"
AUTHOR=”CTMEMUSER”
TIMEFROM="1210"
TIMETO="1310"
MAXRERUN="1"
INTERVAL="1"
PRIORITY="1"
CRITICAL="1"
CYCLIC="1"
CONFIRM="1"
DAYS="1,2,3"
DAYSCAL="Thurs">
<INCOND NAME="Cond1"/>
<OUTCOND NAME="Cond5"/>
<AUTOEDIT EXP="3"/>
<QUANTITATIVE NAME=""/>
<SHOUT WHEN="OK" DEST="COMP554" MESSAGE="Job
done." TIME="14:30"/>
<STEP_RANGE NAME="" FPGMS="1" FPROCS="1"
TPGMS="1" TPROCS="1"/>
<ON PGMS="" PROCS="" CODE="">
<DO ACTION="OK"/>
<DOAUTOEDIT EXP="2"/>
<DOSHOUT DEST="" MESSAGE=""/>
<DOFORCEJOB DSN="" TABLE_NAME="Tbl1"
NAME="Job4"/>
<DOCTBRULE NAME="DOCT"/>
<DOSYSOUT OPTION="Release"/>
<DOIFRERUN FPGMS="1" FPROCS="1" TPGMS="1"
TPROCS="1"/>
<DOCOND NAME="COND4"/>
<DOMAIL DEST="COMP667" MESSAGE="Job done."/>
</ON>
</JOB>
</DEFJOB>

Chapter 3 Job utilities 37


copydefjob

copydefjob
The copydefjob utility creates a new job definition in the CONTROL-M/EM
database that is similar to a specified existing definition. The original job and the copy
must be in different data centers or scheduling tables.

NOTE
Multiple jobs can be selected and copied using the * wildcard character. For an explanation of
how wildcards function in the XML-based utilities, see “Wildcards” on page 178.

When copydefjob is invoked, it processes a file of arguments that specifies criteria for
selecting one or more existing job processing definitions. The selected jobs are copied
to the existing scheduling table and/or data center specified in the arguments file.

To invoke the copydefjob utility:

1 Log on to a CONTROL-M/EM account (Unix)


- or -
open a command prompt window (Microsoft Windows) where CONTROL-M/EM
is installed.

2 Enter either of the following commands:

copydefjob [-u user [-p password] | -pf password_file]


-s gui_server_name -arg arg_file_name [/a]

- or -
copydefjob [-USERNAME user [-PASSWORD password] | -PASSWORD_FILE
password_file] -HOST gui_server_name -ARG_FILE arg_file_name [/a]

3 Press Enter. The copydefjob arguments file is checked and processed. If there are
any errors in the file, a message is displayed specifying the lines with the errors.

38 CONTROL-M/Enterprise Manager Utility Guide


copydefjob

Parameters
Parameters of the copydefjob utility are described in Table 9.

Table 9 copydefjob parameters


Parameter Description
user CONTROL-M/EM user name.
password The CONTROL-M/EM user password.
password_file Flat file containing an unencrypted username and password on separate
lines in the format:
user=username
password=password
Note: If both -u and -pf are specified, an error message is generated. If only
-u is specified, an online prompt is issued for the password. If neither is
specified, a prompt is issued for both the database user name and password.
gui_server_ CONTROL-M/EM GUI server logical name, host name, or IP address.
name Note: If multiple GUI servers exist, set this parameter to the logical name of
the relevant GUI server.
arg_file_name Full path name of the arguments file containing copydefjob specifications.
Instructions for making this file are in Appendix A, “XML File Preparation.”

An optional switch for the copydefjob utility is described in Table 10.

Table 10 copydefjob switch


Switch Description
/a The /a switch directs the utility to automatically reset the Author parameter to the
current CONTROL-M/EM user when these two values do not match. If not
specified, the utility skips (i.e., does not process) job definitions whose Author does
not match the currently logged in user.
Note: The /a switch has no effect on Administrator users and is relevant only when
the AuthorSecurity system parameter is set to 2 or 3.

copydefjob arguments file


Arguments are used as selection criteria to determine which jobs to copy. Arguments
are written to the copydefjob argument file. The arguments files that you create with
the copydefjob utility are written in XML format and saved in a text file. The format
in which this file must be written is described on the following pages.

When this file is invoked, job processing definitions are exported from the
CONTROL-M/EM database.

Each parameter that you specify must have a FROM value. This value is used as a
search criteria for selecting jobs to copy.

Chapter 3 Job utilities 39


copydefjob

NOTE
The copydefjob utility can use only simple job parameters as search and replace criteria.
Complex parameters, such as the name of an In Condition or the degree of urgency of a Do
Shout parameter, cannot be used as search criteria or modified with the copydefjob utility.

The following rules apply to the copydefjob utility arguments file:


■ More than one job can be specified in the arguments file.

■ The arguments file is case-sensitive.

■ All parameter values (such as strings or digits) must be enclosed in quotation


marks (for example, JOBNAME="Job1").
■ Only one COPYJOB parameter can be used in an arguments file.

■ The COPYJOB parameter must contain only one of each job parameter. Many job
parameters are optional.
■ Multiple values can be specified for TO and FROM by using the * wildcard
character. For an explanation of how wildcards function in the XML-based utilities,
see “Wildcards” on page 178.
■ If any FROM value contains a * and the corresponding TO value contains a *, the *
in the TO value represents the same information the * in the FROM value.
■ Changing the data center name or the scheduling table name imports the copy of
the job into a data center or scheduling table different from the one in which the
original job was located.
Most job definition parameters are optional. However,
■ if you specify any parameters, the FROM subparameter is mandatory and the TO
subparameter is optional.
■ if a FROM value is specified without a TO value, it is used as a filter criterion.

■ if a TO value is specified, it indicates the new value of the parameter.

Input file parameters for the copydefjob utility are described in Table 11.

Table 11 copydefjob arguments file parameters (Part 1 of 12)


Parameter Description
The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file. These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE COPYJOB SYSTEM "copyjob.dtd"
COPYJOB These tags indicate the start and end of the COPYJOB argument. Only criteria that are
located between the tags are considered to be part of the argument.

40 CONTROL-M/Enterprise Manager Utility Guide


copydefjob

Table 11 copydefjob arguments file parameters (Part 2 of 12)


Parameter Description
TABLE_NAME Name of the scheduling table to which the job belongs.
Note: At least one of the following scheduling table parameters must be included in
the arguments file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN
Example:
TABLE_NAME FROM=”Tbl5NYC” TO=”Tbl7NYC”
FROM Name of the scheduling table specified in the job processing definition that
is being copied. String. Mandatory.
TO The scheduling table name in the job processing definition copy. String.
Optional.
TABLE_DSN [MVS only] Name of the library that contains the scheduling table. Mandatory.
Note: At least one of the following scheduling table parameters must be included in
the arguments file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN
Example:
TABLE_DSN FROM=”Lib1” TO=”Lib1_COPY”
FROM Name of the library containing the scheduling table in the job processing
definition that is being copied. String. Mandatory.
TO Name of the library in the job processing definition copy. String. Optional.
DATACENTER Name of the CONTROL-M installation to which the job belongs.
Note: At least one of the following scheduling table parameters must be included in
the arguments file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN
Example:
DATACENTER FROM="EM_Montreal" TO="EM_Paris"
FROM Name of the CONTROL-M installation to which the job being copied
belongs. Mandatory.
TO Name of the CONTROL-M installation to which the job copy belongs.
Optional.
JOBNAME Name of the job processing definition.
Example:
JOBNAME FROM="Job3"
FROM String. Mandatory.
MEMNAME Name of the file that contains the job script.
Example:
MEMNAME FROM="Mem3"
FROM String. Mandatory.

Chapter 3 Job utilities 41


copydefjob

Table 11 copydefjob arguments file parameters (Part 3 of 12)


Parameter Description
GROUP Name of the group to which the job belongs. Used as a descriptive name for related
groups of jobs.
Example:
GROUP FROM="Grp_HR"
FROM String. Mandatory.
APPLICATION Name of the application to which the job’s group belongs. Used as a descriptive name
for related groups of jobs.
Example:
APPLICATION FROM="App3""
FROM String. Mandatory.
TASKTYPE Type of the job (task) to be performed by CONTROL-M.
Example:
TASKTYPE FROM="Detached"
FROM Mandatory. Valid values:
■ Job
■ Detached
■ Command
■ Dummy
[MVS only] Valid values:
■ Started_Task
■ Cyclic_Job
■ Cyclic_Task
■ Emergency_Job
■ Emergency_Cyclic_Job
■ Emergency_Task
■ Emergency_Cyclic_Task

TABLE Optional.
_USERDAILY Example:
TABLE_USERDAILY FROM="Job3"
FROM String. Mandatory.
AUTHOR CONTROL-M/EM user who defined the job. String. Optional.
Example:
AUTHOR FROM="emuser"
Note: This argument is used by the CONTROL-M/Server security mechanism and,
under certain circumstances, cannot be modified. For more information, see the
Security chapter and the description of the AuthorSecurity system parameter in the
CONTROL-M/Enterprise Manager Administrator Guide.
FROM String. Mandatory.
MEMLIB Name of the library/directory in which the job script resides. String. Optional.
Example:
MEMLIB FROM="Mem1"
FROM String. Mandatory.

42 CONTROL-M/Enterprise Manager Utility Guide


copydefjob

Table 11 copydefjob arguments file parameters (Part 4 of 12)


Parameter Description
CMDLINE Command string supplied when the job Task Type is Command. Optional.
Example:
CMDLINE FROM="C:\Format"
FROM String. Mandatory.
NODEID Host name of an Agent platform or name of a node group to which the job is
submitted. Optional.
Example:
NODEID FROM="Com3"
FROM String. Mandatory.
OWNER Owner (user ID) associated with the job. This parameter is used by the
CONTROL-M/Server security mechanism. Optional.
Example:
OWNER FROM="emuser"
FROM String. Mandatory.
MAXRERUN Specifies the maximum number of reruns that can be performed for the job.
Example:
MAXRERUN FROM="1"
Valid values: 0-99. Default: 0
FROM String. Mandatory.
TIMEFROM Indicates the earliest time for submitting the job.
Example:
TIMEFROM FROM="1430"
FROM String. Mandatory.
TIMETO Indicates the latest time for submitting the job.
Example:
TIMETO FROM="1600"
FROM String. Mandatory.
DUE_OUT Time that the job is expected to finish.
Example:
DUE_OUT FROM="1500"
FROM String. Mandatory.
PRIORITY Indicates CONTROL-M job priority.
Example:
PRIORITY FROM="AA"
FROM String. Mandatory.
CRITICAL Indicates that the job is a critical-path job in CONTROL-M.
Example:
CRITICAL FROM="0"
FROM Mandatory. Valid values:
■ 0 (Default)
■ 1

Chapter 3 Job utilities 43


copydefjob

Table 11 copydefjob arguments file parameters (Part 5 of 12)


Parameter Description
CYCLIC Indicates if the job is cyclic (to be rerun at regular intervals). Optional.
Example:
CYCLIC FROM="0"
FROM Mandatory. Valid values:
■ 0 (Default)
■ 1

CONFIRM Indicates that the job must be manually confirmed by the CONTROL-M/EM user
before it runs.
Example:
CONFIRM FROM="0"
FROM Mandatory. Valid values:
■ 0 (Default)
■ 1

AUTOARCH Determines whether or not SYSDATA is to be archived.


Example:
AUTOARCH FROM=0"
FROM Mandatory. Valid values:
■ 0 (Default)
■ 1

INTERVAL Specifies the length of time (in minutes) to wait between reruns of a job or between
cyclic runs of a job. Integer. Optional.
Example:
INTERVAL FROM="3"
FROM String. Mandatory.
OVERLIB Name of an alternate job script library/directory. String.
Example:
OVERLIB FROM="lib3"
FROM String. Mandatory.
MAXWAIT Number of extra days (beyond the original scheduling date) that the job is allowed to
remain in the Active Jobs file awaiting execution. Integer.
Example:
MAXWAIT FROM="4"
FROM String. Mandatory.
DESCRIPTION Free text description of the job. String.
Example:
DESCRIPTION FROM="data backup from 120399"
FROM String. Mandatory.
DOCMEM Name of the file containing job documentation. String.
Example:
DOCMEM FROM="mem4"
FROM String. Mandatory.

44 CONTROL-M/Enterprise Manager Utility Guide


copydefjob

Table 11 copydefjob arguments file parameters (Part 6 of 12)


Parameter Description
DOCLIB Name of a library or directory containing the job documentation file. String.
Mandatory.
Example:
DOCLIB FROM="AcctFiles"
FROM String. Mandatory.
DAYS Days of the month on which to order the job. String. Optional.
Example:
DAYS FROM="ALL"
FROM String. Mandatory.
DAYS_AND_OR Indicates the relationship between specified Days values and Weekdays values.
Optional.
Example:
DAYS_AND_OR FROM="AND"
FROM String. Mandatory.
WEEKDAYS Days of the week on which to order the job. String. Optional.
Example:
WEEKDAYS FROM="1,2,4"
FROM String. Mandatory.
DATE Specific dates on which to order the job. String. MMDD format. Optional.
Example:
DATE FROM="0312"
FROM String. Mandatory. Dates can be written in mmdd format. There is no
delimiter between dates. For example, January 10 is written in this manner:
DATE="0110"
DAYSCAL Name of a user-defined calendar used to specify a set of days. String. Optional.
Example:
DAYSCAL FROM="shipping"
FROM String. Mandatory.
WEEKSCAL Name of a calendar to be used to validate specified weekdays on which to order the
job. String. Optional.
Example:
WEEKSCAL FROM="2"
FROM String. Mandatory.
CONFCAL Specifies a calendar that is used to validate all specified days and dates on which to
schedule the job. String.
Example:
CONFCAL FROM="cal99" TO="cal00"
FROM String. Mandatory.

Chapter 3 Job utilities 45


copydefjob

Table 11 copydefjob arguments file parameters (Part 7 of 12)


Parameter Description
RETRO Indicates whether the job is scheduled for possible execution after its original
scheduling date (odate) has passed.
Example:
RETRO FROM="0"
FROM Mandatory. Valid values:
■ 0 (No. Default)
■ 1 (Yes.)

SHIFT Describes how to shift the scheduling date of the job.


Example:
SHIFT FROM="PREVDAY"
FROM Mandatory. Valid values:
■ IGNOREJOB
■ PREVDAY
■ NEXTDAY
■ NOCONFCAL

SHIFTNUM Number of days to shift the scheduling date of the job.


Example:
SHIFTNUM FROM="-10"
FROM String. Mandatory.
MAXDAYS Maximum number of days to retains the SYSDATA archive dataset for jobs that ended
NOTOK. Subparameter of AUTOARCH. String. Optional.
Example:
MAXDAYS FROM="07"
FROM Integer. Mandatory.
MAXRUNS Maximum number of job runs to retains the SYSDATA archive dataset for jobs that
ended NOTOK. Subparameter of AUTOARCH. String. Optional.
Example:
MAXRUNS FROM="100"
FROM String. Mandatory.
RERUNMEM Name of the JCL member to use when the job is automatically rerun. String. 1-8
characters. Optional.
Example:
RERUNMEM FROM="Mem45"
FROM String. Mandatory.
RETEN_DAYS [MVS only] Number of days to retain the job in the History Jobs file. String. Optional.
Example:
RETEN_DAYS FROM="5"
FROM String. Mandatory.
RETEN_GEN [MVS only] Maximum number of generations of the job to keep in the History Jobs
file. String.
Example:
RETEN_GEN FROM="3"
FROM String. Mandatory.

46 CONTROL-M/Enterprise Manager Utility Guide


copydefjob

Table 11 copydefjob arguments file parameters (Part 8 of 12)


Parameter Description
TASK_CLASS Job class for the task.
Example:
TASK_CLASS FROM="Distribution"
FROM Mandatory. Valid values:
■ Distribution
■ Decollation

PREV_DAY Flag to indicate whether job scheduling is shifted to a previous working day in the
CONFCAL calendar. Optional.
Example:
PREV_DAY FROM="N"
FROM Mandatory. Valid values:
■ Y
■ N

IND_CYCLIC Indicates whether the interval between further runs of a cyclic job is counted from the
start or the end of the previous job run. Optional.
Example:
IND_CYCLIC FROM="START"
FROM Mandatory. Valid values:
■ START
■ END

TAG Relationship (AND|OR) between the specified Schedule Tag criteria and the job’s
_RELATIONSHIP own basic scheduling criteria. This parameter is relevant only for jobs in a group
scheduling table. Optional.
Example:
TAG_RELATIONSHIP FROM="AND"
FROM Mandatory. Valid values:
■ AND
■ OR

SYSDB Determines whether one or multiple data sets are used to catalogue sysdata.
Example:
SYSDB FROM="1" TO="0"
FROM Mandatory. Valid values:
■ 0 (Multiple -Default)
■ 1 (Single)

PDSNAME Name of a partitioned dataset (PDS) to be checked for free space. String. Optional.
Example:
PDSNAME FROM="Lib_3"
FROM String. Mandatory.
MINIMUM Minimum number of free partitioned dataset tracks required by the library specified
for the PDSNAME parameter. Integer. Optional.
Example:
MINIMUM FROM="5"
FROM Integer. Mandatory.

Chapter 3 Job utilities 47


copydefjob

Table 11 copydefjob arguments file parameters (Part 9 of 12)


Parameter Description
CATEGORY Name of a CONTROL-D report decollating mission category that must be scheduled
under CONTROL-D when the job is scheduled under CONTROL-M. String. Optional.
Example:
CATEGORY FROM="DAILY"
FROM String. Mandatory.
PREVENTNCT2 [MVS only] Prevents dataset cleanup before the original job run. Optional.
Valid values:
■ Blank – Does not perform data set cleanup before the original job run. Default.
■ N – Does not prevent cleanup.
■ Y - Prevents data set cleanup. This value is not valid for started tasks.
■ L (List) – Do not perform data set cleanup before the original job run. Do generate
messages that would be required for CDG adjustment during restart.
■ F (Flush) – Halt processing of the job if any data set cleanup error is detected (even
if MVS would not have stopped processing the job).
Example:
PREVENTNCT2 FROM="1"
FROM Mandatory. Valid values:
■ 0
■ 1

JAN, FEB, MAR, Months when the job can run. Optional.
APR, MAY, JUN, Example:
JUL, AUG, SEP, JAN FROM="0"
OCT, NOV, DEC FROM Mandatory. Not including a month is the same as including a month
having the value 0. Valid values:
■ 0 (Default)
■ 1

OPTION Job output (sysout) handling options.


Example:
OPTION FROM="Copy"
FROM Mandatory. Valid values:
■ Release
■ Delete
■ Copy
■ Move
■ File
■ NewDest
■ ChangeClass

PAR Certain OPTION FROM values (such as Release, NewDest) require additional
information. The PAR parameter holds this information as a string.
Example:
PAR FROM="mem3.log"
FROM String. Mandatory.
FROM Limits the sysout handling operation to sysouts from the specified class. Optional.
Example:
FROM FROM="5"
FROM String. Mandatory.

48 CONTROL-M/Enterprise Manager Utility Guide


copydefjob

Table 11 copydefjob arguments file parameters (Part 10 of 12)


Parameter Description
ADJUST_COND Indicates whether to ignore prerequisite conditions normally set by predecessor jobs if
the relevant predecessor jobs are not scheduled. This parameter is relevant only for
jobs in a group scheduling table. Optional. Valid values:
■ 0 (Do not ignore. Default.)
■ 1 (Ignore relevant prerequisite conditions)

FROM String. Mandatory.


JOBS_IN_GROUP Number of jobs in the group scheduling table. Optional.
Example:
JOBS_IN_GROUP FROM="4"
FROM String. Mandatory.
APPL_TYPE Indicates the type of external application (for example, SAP or Oracle) on which the
external application job runs. Mandatory for external application jobs.
Example:
APPL_TYPE FROM=”SAP”
FROM Mandatory. String. Up to 10 characters.
APPL_VER Version of the external application (for example, SAP or Oracle) on which the external
application job runs. Mandatory for external application jobs.
Example:
APPL_VER FROM=”4.6”
FROM Mandatory. String. Up to 10 characters.
APPL_FORM Predefined set of external application parameters that are displayed in the Job Editing
form. Mandatory for external application jobs.
Example:
APPL_FORM FROM=”Default SAP 4.6”
FROM Mandatory. String. Up to 30 characters.
CM_VER Indicates the version of external application (for example, SAP or Oracle) Control
Module that is installed in the CONTROL-M installation. Mandatory for external
application jobs.
Example:
CM_VER FROM=”6.1.00”
FROM Mandatory. String. Up to 10 characters.
MULTY_AGENT When selected, broadcasts job submission details to all Agents in a specified Node
Group. Optional.
Example:
MULTY_AGENT FROM=”N”
FROM Mandatory. Valid values:
■ Y – run as multi-agent job
■ N – not run as multi-agent job. Default.

ACTIVE_FROM [MVS only] Indicates the start of a period of time during which the job or group
scheduling table can be ordered. Optional.
Example:
ACTIVE_FROM FROM=”20040315”
FROM Mandatory. Date Format: YYYYMMDD

Chapter 3 Job utilities 49


copydefjob

Table 11 copydefjob arguments file parameters (Part 11 of 12)


Parameter Description
ACTIVE_TILL [MVS only] Indicates the end of a period of time during which the job or group
scheduling table can be ordered. Optional.
Example:
ACTIVE_TILL FROM=”20040315”
FROM Mandatory. Date Format: YYYYMMDD
TIMEZONE Indicates global time zone used to calculate the interval for time-related conditions.
Optional.
Example:
TIMEZONE FROM=”EST”
FROM Mandatory. String. Default: GMT
SYSTEM_AFFINITY Identity of the system in which the job must be initiated and executed (in JES2).
Identity of the processor on which the job must execute (in JES3). Optional. String.
FROM String. Mandatory.
Example:
SYSTEM_AFFINITY FROM=”SYS3”
REQUEST_NJE Specifies the node in the JES network on which the job is to execute.
_NODE FROM String. Mandatory.
Example:
REQUEST_NJE_NODE FROM=”OS5”
SCHEDULING [MVS only] Indicates the JES2 workload management scheduling environment that is
_ENVIRONMENT to be associated with the job.
FROM String. Mandatory.
Example:
SCHEDULING_ENVIRONMENT FROM=”SCHD2”
CREATION Name of the user who created the job. String.
_USER Example:
CREATION_USER FROM="emuser"
FROM String. Mandatory.
CREATION Date on which the job was created. String.
_DATE Example:
CREATION_DATE FROM="1212"
FROM String. Mandatory.
CREATION Time at which the job was created. String.
_TIME Example:
CREATION_TIME FROM="1230"
FROM String. Mandatory.
CHANGE Name of the user that last modified the job. String.
_USERID Example:
CHANGE_USERID FROM="emuser"
FROM String. Mandatory.

50 CONTROL-M/Enterprise Manager Utility Guide


copydefjob

Table 11 copydefjob arguments file parameters (Part 12 of 12)


Parameter Description
CHANGE Date that the job was last modified. String.
_DATE Example:
CHANGE_DATE FROM="1204"
FROM String. Mandatory.
CHANGE_TIME Time that the job was last modified. String.
Example:
CHANGE_TIME FROM="1650"
FROM String. Mandatory.

Following are sample input files used with the copydefjob utility:

Example 1: Copy selected jobs and change parameter values in the copies

This copydefjob arguments file copies job processing definitions in the Tbl5NYC
scheduling table if TABLE_DSN is Lib1 and JOBNAME is Job3. In the copy, the
TABLE_DSN value is changed to Lib1_COPY.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE COPYJOB SYSTEM "copyjob.dtd">
<COPYJOB>
<TABLE_NAME FROM="Tbl5NYC"/>
<TABLE_DSN FROM="Lib1" TO="Lib1_COPY"/>
<JOBNAME FROM="Job3"/>
</COPYJOB>

Example 2: Copy all jobs in one scheduling table to another scheduling table

Copies of all jobs in the Tbl5NYC scheduling table to the Tbl7LA scheduling table.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE COPYJOB SYSTEM "copyjob.dtd">
<COPYJOB>
<TABLE_NAME FROM="Tbl5NYC" TO="Tbl7LA"/>
</COPYJOB>

Chapter 3 Job utilities 51


copydefjob

Example 3: Copy all cyclic jobs with a similar jobname

Copies of all cyclic jobs in the GrpAcct group that have a jobname beginning with the
string Acct from TABLE_DSN 23Y to TABLE_DSN 14G.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE COPYJOB SYSTEM "copyjob.dtd">
<COPYJOB>
<TABLE_DSN FROM="23Y" TO="14G">
<GROUP FROM="GrpAcct"/>
<CYCLIC FROM="1"/>
<JOBNAME="Acct*" />
</COPYJOB>

Copy jobs in a scheduling table to a group scheduling table


You can copy the jobs in a scheduling table to a group scheduling table using the
copydefjob utility.

1 Using CONTROL-M/Desktop, define a group scheduling table containing no jobs.

2 Write the group scheduling table to the CONTROL-M/EM database.

3 Create a copydefjob arguments file in which jobs in a scheduling table are copied
to the group scheduling table that you created:

A Open a text editor. Format the file using the specifications in “copydefjob
arguments file” on page 39.

B Specify the CONTROL-M installation in which the jobs to be copied reside using
the DATACENTER parameter:

DATACENTER FROM=”CTM_Name”

C Specify that the Table Name value of the jobs changes from the name of the
scheduling table to the name of the group scheduling table with the following
tag:

TABLE_NAME FROM=”Sched_Tbl_Name” TO=”Grp_Sched_Tbl_Name>”

D Save and close the file.

4 At the command line, enter the copydefjob utility command that uses the file that
you created in the previous step:

copydefjob -u emuser -p empass -s gui_server_name


-arg arg_file_name

52 CONTROL-M/Enterprise Manager Utility Guide


copydefjob

5 Use the Scheduling Table Manager in CONTROL-M/Desktop to upload the group


scheduling table to the CONTROL-M/Server.

6 In the CONTROL-M/EM GUI, order the group scheduling table.

7 In the CONTROL-M/EM GUI, verify that the group scheduling table now contains
the jobs that were copied to it.

8 If you do not need the original Scheduling table, you can delete it.

Example

This arguments file copies all jobs in the RegTable scheduling table in the ctm600
data center to the GrpSTable group scheduling table.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE COPYJOB SYSTEM "copyjob.dtd">
<COPYJOB>
<DATACENTER FROM="ctm600"/>
<TABLE_NAME FROM="RegTable" TO="GrpSTable"/>
</COPYJOB>

Chapter 3 Job utilities 53


defjobconvert

defjobconvert
This utility converts defjob utility input files for versions before 6.0.01 to files that are
compatible with the defjob utility in CONTROL-M/EM version 6.2.01.

Migration and the defjobconvert utility


The defjobconvert utility is not a migration tool. To migrate job definitions from a
version prior to 6.2.01, use the migration toolkit provided for this purpose. For more
information, see the CONTROL-M/EM Migration Guide.

TIP
The defjobconvert utility does not check if the job definitions are valid. To verify that the data
is valid, import it to the ENTERPRISE/CS version 5.0.0x database and then select the
Validation option in the migration menu. This option generates the Readiness report. If there
are no errors or warnings in the report, you can run the defjobconvert utility on the input file.

defjob input file


The defjobconvert utility reads an existing defjob input file that was created by any
CONTROL-M/EM version prior to 6.0.01.

NOTE
Verify that the defjob input file contains valid commands before running the defjobconvert
utility.

defjobconvert output file


The defjobconvert utility produces a new file, containing all of the defjob source file
job definition information. The information in the output file is formatted in XML
format and can be used with the defjob utility described in “defjob” on page 24. The
output file is similar to the output file displayed in “Example: Command job that
requires confirmation before running” on page 37.

54 CONTROL-M/Enterprise Manager Utility Guide


defjobconvert

To invoke the defjobconvert utility:

1 Log on to a CONTROL-M/EM account (Unix)


- or -
open a command prompt window (Microsoft Windows) where CONTROL-M/EM
is installed.

2 Enter the following command:

defjobconvert -src src_file_name -out output_file_name

Parameters
Parameters of the defjobconvert utility are described in Table 12.

Table 12 defjobconvert parameters


Parameter Description
src_file_name Path and name of the source defjob input file.
output_file_name Path and name where the new defjob input file is saved. This utility
does not create the output directory automatically. It must already exist.

3 Press Enter.

NOTE
Each run of the defjobconvert utility converts only one input file. The utility must be run once
for each file that you want to convert.

Information display
The defjobconvert utility displays a counter and a number of messages to inform you
of the progress of the conversion process and to warn you of any potential errors.

Progress counter

After the defjobconvert utility is started, a counter on the command line indicates the
percentage of the file that has been converted.

Chapter 3 Job utilities 55


defjobconvert

Messages

Messages include:
■ Processing src_file_name.

■ Reading input file.

■ Parsing input file.

■ Conversion ended successfully.

■ Error: ignoring attributes "attribute_string"

Extra characters that were added to the source file to facilitate proper spacing or to
import notations are ignored. When such characters are encountered, defjobconvert
displays the Error: ignoring attributes message.

If a defjob input file has tabs and backslashes that indicate spacing and line breaks,
-USERNAME<CONTROL-M/EM log on name>\

-PASSWORD<CONTROL-M/EM logon password>\

-TABLE<Scheduling table name>\

then the Error: ignoring attributes message is displayed for each group of
characters that is not parsed by the utility. The presence of these characters in the
source file does not harm the output file.

Example 1: Convert file and save the output in a different directory

The defjob input file, jobs500.txt in the C:\utilfiles\500 directory, is processed by


the defjobconvert utility. The resulting new defjob input file, jobs600.xml, is saved
in the C:\utilfiles\600 directory.

defjobconvert -SRC_FILE C:\utilfiles\500\jobs500.txt -OUT_FILE


C:\utilfiles\600\jobs600.xml

Example 2: Convert file and save the output to the same directory

The defjob input file, jobs500.txt in the C:\utilfiles directory, is processed by the
defjobconvert utility. The resulting new defjob input file, jobs600.xml, is saved in
the same directory.

defjobconvert -SRC_FILE C:\utilfiles\jobs500.txt -OUT_FILE C:\utilfiles\jobs600.xml

56 CONTROL-M/Enterprise Manager Utility Guide


deldefjob

deldefjob
The deldefjob utility deletes specified job processing definitions from a scheduling
table in the CONTROL-M/EM database.

When deldefjob is invoked, it processes a specified file of arguments in XML format.


This file contains statements that identify existing job processing definitions. The
identified definitions are deleted from the CONTROL-M/EM database.

To invoke the deldefjob utility:

1 Log on to a CONTROL-M/EM account (Unix)


- or -
open a command prompt window (Microsoft Windows) where CONTROL-M/EM
is installed.

2 Enter either of the following commands:

deldefjob [-u user [-p password] | -pf password_file]


-s gui_server_name -arg arg_file_name [/a]

- or -
deldefjob [-USERNAME user [-PASSWORD password] | -PASSWORD_FILE
password_file] -HOST gui_server_name -ARG_FILE arg_file_name [/a]

Parameters of the deldefjob utility are described in Table 13.

3 Press Enter. The deldefjob arguments file is checked and processed. If there are
any errors in the file, a message is displayed specifying the lines with the errors.

Parameters

Table 13 deldefjob parameters


Parameter Description
user CONTROL-M/EM user name.
password User’s CONTROL-M/EM password.
password_file Flat file containing an unencrypted username and password on separate
lines in the format:
user=username
password=password
Note: If both -u and -pf are specified, an error message is generated. If only
-u is specified, an online prompt is issued for the password. If neither is
specified, a prompt is issued for the database user name and password.

Chapter 3 Job utilities 57


deldefjob

Table 13 deldefjob parameters


Parameter Description
gui_server_ CONTROL-M/EM GUI server logical name, host name, or IP address.
name Note: If multiple GUI servers exist, set this parameter to the logical name of
the relevant GUI server.
arg_file_name Path and name of the arguments file containing deldefjob specifications.
The format for this file is described in Table 14 on page 58. For
information about how to prepare this file, see Appendix A, “XML File
Preparation.”

deldefjob arguments file


The following rules apply to the deldefjob arguments file:
■ More than one job can be specified in a deldefjob file.

■ The arguments file is case-sensitive.

■ All parameter values must be enclosed in quotation marks (for example,


JOBNAME="Job1").
■ More than one PARAM parameter can be used in a TERM statement.

■ The relationship between PARAM parameters in a TERM statement is AND.

■ The default relationship between TERM statements is OR.

Table 14 deldefjob arguments file parameters (Part 1 of 2)


Parameter Description
The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file. These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE TERMS SYSTEM "terms.dtd"
TERMS These tags indicate the start and end of the TERM tags. Only criteria that are
located between these tags are considered to be part of the argument.
TERM The TERM tags indicate the start and end of a group of selection criteria for a job or
jobs that are to be deleted. Only PARAM tags that are located between the TERM
tags are considered to be part of the TERM argument.
REL Optional. Relationship between terms.
Valid values:
■ AND
■ OR (default)

58 CONTROL-M/Enterprise Manager Utility Guide


deldefjob

Table 14 deldefjob arguments file parameters (Part 2 of 2)


Parameter Description
PARAM The selection criteria parameter used to determine job definitions to be deleted.
More than one PARAM can be specified. Mandatory.
Example:
PARAM NAME="DATACENTER" OP="EQ" VALUE="Center1"
NAME String. Mandatory.
Name of any job processing parameter, using the format
shown in Table 6 on page 25.Table 8 on page 26
Note: At least one of the following scheduling table
parameters must be included in the arguments file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

OP Mandatory. Valid values:


■ EQ – Equal
■ NEQ – Not equal
■ NOTIN – Does not contain
■ LIKE – Mask or pattern using wildcards

VALUE String. Mandatory.


Valid value for the specified job processing parameter, using
the format in Table 6 on page 25.

Sample arguments files used with the deldefjob utility:

Example 1: Delete definitions with the same job name

Delete job processing definitions with the name Job5 from the EM5NY data center.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE TERMS SYSTEM "terms.dtd">
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="EM5NY"/>
<PARAM NAME="JOBNAME" OP="EQ" VALUE="Job5"/>
</TERM>
</TERMS>

Chapter 3 Job utilities 59


deldefjob

Example 2: Delete definitions that satisfy one or both of two criteria

Delete job processing definitions that satisfy either of the following criteria:
■ The data center name is Data1 and the jobname begins with the letter J.

- or -
■ The jobname is Job5 and the job is not cyclic.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE TERMS SYSTEM "terms.dtd">
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="Data1"/>
<PARAM NAME="JOBNAME" OP="LIKE" VALUE="J*"/>
</TERM>
<TERM>
<PARAM NAME="JOBNAME" OP="EQ" VALUE="Job5"/>
<PARAM NAME="CYCLIC" OP="EQ" VALUE="0"/>
</TERM>
</TERMS>

Example 3: Delete definitions that meet multiple criteria

Delete definitions for cyclic jobs in the EM5NY data center that are scheduled to run in
January, February, and March.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE TERMS SYSTEM "terms.dtd">
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="EM5NY"/>
<PARAM NAME="CYCLIC" OP="EQ"
VALUE="1"/>
<PARAM NAME="JAN" OP="EQ" VALUE="1"/>
<PARAM NAME="FEB" OP="EQ" VALUE="1"/>
<PARAM NAME="MAR" OP="EQ" VALUE="1"/>
</TERM>
</TERMS>

60 CONTROL-M/Enterprise Manager Utility Guide


duplicatedefjob

duplicatedefjob
The duplicatedefjob utility makes a copy of an existing job definition in the same
data center and scheduling table. Elements of the copy can be changed.

NOTE
Multiple jobs can be selected and copied using the * wildcard character. For an explanation of
how wildcards function in XML-based utilities, see “Wildcards” on page 178.

When duplicatedefjob is invoked, it processes a specified file of arguments in XML


format. This file contains statements that identify existing job processing definitions.
The identified definitions are copied, changes to the copy (if requested) are made, and
the copy is stored in the CONTROL-M/EM database.

To invoke the duplicatedefjob utility:

1 Log on to a CONTROL-M/EM account (Unix)


- or -
open a command prompt window (Microsoft Windows) where CONTROL-M/EM
is installed.

2 Enter either of the following commands:

duplicatedefjob [-u user [-p password] | -pf password_file]


-s gui_server_name -arg arg_file_name [/a]

- or -
duplicatedefjob [-USERNAME user [-PASSWORD password] | -PASSWORD_FILE
password_file] -HOST gui_server_name -ARG_FILE arg_file_name [/a]

Parameters of the duplicatedefjob utility are described in Table 15.

3 Press Enter. The duplicatedefjob arguments file is checked and processed. If the
file contains errors, a message is displayed specifying the lines with the errors.

Chapter 3 Job utilities 61


duplicatedefjob

Parameters

Table 15 duplicatedefjob parameters


Parameter Description
user CONTROL-M/EM user name.
password The CONTROL-M/EM user password.
password_file Flat file containing an unencrypted username and password on separate
lines in the format:
user=username
password=password
Note: If both -u and -pf are specified, an error message is generated. If only
-u is specified, an online prompt is issued for the password. If neither is
specified, a prompt is issued for the database user name and password.
gui_server_ CONTROL-M/EM GUI server logical name, host name, or IP address.
name Note: If multiple GUI servers exist, set this parameter to the logical name of
the relevant GUI server.
arg_file_name Path and name of the arguments file containing duplicatedefdefjob
specifications. The format for this file is described in Table 17 on
page 63. For information about how to prepare this file, see Appendix A,
“XML File Preparation.”

An optional switch for the duplicatedefjob utility is described in Table 16.

Table 16 duplicatedefjob switch


Switch Description
/a The /a switch directs the utility to automatically reset the Author parameter to the
current CONTROL-M/EM user when these two values do not match. If not
specified, the utility skips (i.e., does not process) job definitions whose Author
does not match the currently logged in user.
Note: The /a switch has no effect on Administrator users and is relevant only when
the AuthorSecurity system parameter is set to 2 or 3.

duplicatedefjob Arguments File


Each arguments file parameter that you specify must have a FROM subparameter.
The FROM value is used as a search criteria for selecting jobs to copy. For example,
JOBNAME FROM="Job2" copies all jobs with the JobName Job2.

The TO subparameter, which is optional, is used to change the value of the


parameter. For example, JOBNAME FROM="Job2" TO="Job2B" modifies all jobs
with JobName Job2 so that they now have JobName Job2B.

62 CONTROL-M/Enterprise Manager Utility Guide


duplicatedefjob

NOTE
Currently, the duplicatedefjob utility can use only simple job parameters as search and
replace criteria. Complex parameters, such as the name of an In Condition parameter or the
degree of urgency of a Do Shout parameter, cannot be used as search criteria or modified with
the duplicatedefjob utility.

The following rules apply to the arguments file for the duplicatedefjob utility:

■ More than one job can be specified in an duplicatedefjob file.

■ The arguments file is case-sensitive.

■ All parameter values must be enclosed in quotation marks (for example,


JOBNAME="Job1").

■ Only one DUPLICATEJOB parameter can be used in the arguments file. This
parameter must not contain more than one instance of each job parameter.

■ Multiple values can be specified for TO and FROM by using the * wildcard
character. For an explanation of how wildcards function in the XML-based utilities,
see “Wildcards” on page 178.

■ If any FROM value contains *, and the corresponding TO value contains *, the * in
the TO value expresses the same information as the * in the FROM value.

■ Changing the data center name or scheduling table name causes the copy of the job
scheduling definition to be imported into the specified data center or scheduling
table.

FROM and TO subparameters

Most job definition parameters in the arguments file are optional. However
■ For each parameter that is specified, the FROM subparameter is mandatory and
the TO subparameter is optional.
■ When FROM is specified without a TO, the FROM value is used as a filter criterion.

■ When TO is included, it specifies the value to which the parameter is set.

Table 17 duplicatedefjob arguments file tags (Part 1 of 14)


Tag Description
The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file. These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE DUPLICATEJOB SYSTEM "duplicatejob.dtd"
DUPLICATEJOB The DUPLICATEJOB tags indicate the start and end of a group of selection criteria for
a job or jobs that are to be copied. Only criteria that are located between the
DUPLICATEJOB tags are considered to be part of the duplicatedefjob parameters.

Chapter 3 Job utilities 63


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 2 of 14)


Tag Description
TABLE_NAME Name of the scheduling table to which the job belongs. Mandatory.
Note: At least one of the following scheduling table parameters must be included in
the arguments file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN
Example:
TABLE_NAME FROM=”Tbl5NYC”
FROM String. Mandatory.
TO String. Optional. Include only if the scheduling definition is to be
copied to a scheduling table with a different name.
TABLE_DSN [MVS only] Name of the library that contains the scheduling table.
Mandatory.
Notes:
A TO subparameter cannot be specified for this parameter.
At least one of the following scheduling table parameters must be included in the
arguments file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN
Example:
TABLE_DSN FROM=”Lib1”
FROM String. Mandatory.
DATACENTER Name of the CONTROL-M installation to which the job belongs. Mandatory.
Notes: A TO parameter cannot be specified for this parameter.
At least one of the following scheduling table parameters must be included in the
arguments file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN
Example:
DATACENTER FROM="CTMNYC"
FROM String. Mandatory.
TABLE_ String. Mandatory.
USERDAILY Note: A TO parameter cannot be specified for this parameter.
Example:
TABLE_USERDAILY FROM="Job3"
FROM String. Mandatory.
JOBNAME Name of the job processing definition. Optional.
Example:
JOBNAME FROM="Job3" TO="Job3_COPY"
FROM Mandatory.
TO Optional.

64 CONTROL-M/Enterprise Manager Utility Guide


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 3 of 14)


Tag Description
MEMNAME Name of the file that contains the job script. Optional.
Example:
MEMNAME FROM="Mem3" TO="Mem7"
FROM Mandatory.
TO Optional.
GROUP Name of the group to which the job belongs. Used as a descriptive name for related
jobs. Optional.
Example:
GROUP FROM="Grp_HR" TO="Grp_ACCT"
FROM Mandatory.
TO Optional.
APPLICATION Name of the application to which the job’s group belongs. Used as a descriptive name
for related jobs. Optional.
Example:
APPLICATION FROM="App3" TO="App1"
FROM String. Mandatory.
TO String Optional.
TASKTYPE Type of the job (task) to be performed by CONTROL-M. Optional.
Example:
TASKTYPE FROM="Detached" TO="Job"
FROM Mandatory.
Valid values:
■ Job
■ Detached
■ Command
■ Dummy
[MVS only] Valid values:
■ Started_Task
■ Cyclic_Job
■ Cyclic_Task
■ Emergency_Job
■ Emergency_Cyclic_Job
■ Emergency_Task
■ Emergency_Cyclic_Task

TO Optional. Valid values: Same as mandatory FROM values.


[MVS only] Valid values: Same as MVS FROM values.
AUTHOR CONTROL-M/EM user who defined the job. String. Optional.
Example:
AUTHOR FROM="emuser" TO="em5"
Note: This argument is used by the CONTROL-M/Server security mechanism. Under
certain circumstances, it cannot be modified. For more information, see the Security
chapter and the description of the AuthorSecurity system parameter in the
CONTROL-M/Enterprise Manager Administrator Guide.
FROM String. Mandatory.
TO String. Optional.

Chapter 3 Job utilities 65


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 4 of 14)


Tag Description
MEMLIB Name of the library/directory in which the job script resides. String. Optional.
Example:
MEMLIB FROM="Mem1" TO="Mem4"
FROM String. Mandatory.
TO String. Optional.
CMDLINE Command string supplied when the job Task Type is Command. Optional.
Example:
CMDLINE FROM="C:\Format" TO="C\:CD Emnt"
FROM String. Mandatory.
TO String. Optional.
NODEID Host name of an Agent platform or a node group to which the job is submitted.
Optional.
Example:
NODEID FROM="Com3" TO="Acct4"
FROM String. Mandatory.
TO Host name of the Agent platform on which the job copy is
running Optional.
OWNER Owner (user ID) associated with the job. This parameter is used by the
CONTROL-M/Server security mechanism. Optional.
Example:
OWNER FROM="emuser" TO="emhr"
FROM String. Mandatory.
TO String. Optional.
MAXRERUN Maximum number of reruns that can be performed for the job. Optional.
Example:
MAXRERUN FROM="1" TO="3"
FROM String. Mandatory.
TO String. Optional.
TIMEFROM Earliest time for submitting the job. Optional.
Example:
TIMEFROM FROM="1430" TO="1450"
FROM String. Mandatory.
TO String. Optional.
TIMETO Latest time for submitting the job. Optional.
Example:
TIMETO FROM="1600" TO="1620"
FROM String. Mandatory.
TO String. Optional.

66 CONTROL-M/Enterprise Manager Utility Guide


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 5 of 14)


Tag Description
DUE_OUT Time that the job is expected to finish. Optional.
Example:
DUE_OUT FROM="1500" TO="1530"
FROM String. Mandatory.
TO String. Optional.
PRIORITY CONTROL-M job priority. Optional.
Example:
PRIORITY FROM="AA" TO="1A"
FROM String. Mandatory.
TO String. Optional.
CRITICAL Indicates whether the job is a critical-path job in CONTROL-M. Optional.
Example:
CRITICAL FROM="0" TO="1"
FROM Mandatory. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

TO Optional. Valid values:


■ 0 (No. Default)
■ 1 (Yes)

CYCLIC Indicates whether the job is cyclic (to be run at regular intervals). Optional.
Example:
CYCLIC FROM="0" TO="1"
FROM Mandatory. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

TO Optional. Valid values:


■ 0 (No. Default)
■ 1 (Yes)

CONFIRM Indicates whether the job must be manually confirmed by the CONTROL-M/EM user
before it runs. Optional.
Example:
CONFIRM FROM="0" TO="1"
FROM Mandatory. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

TO Optional. Valid values:


■ 0 (No. Default)
■ 1 (Yes)

Chapter 3 Job utilities 67


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 6 of 14)


Tag Description
AUTOARCH Determines whether SYSDATA is to be archived. Optional.
Example:
AUTOARCH FROM=0" TO="1"
FROM Mandatory. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

TO Optional. Valid values:


■ 0 (No. Default)
■ 1 (Yes)

INTERVAL Length of time (in minutes) to wait between reruns or cyclic runs of a job. Integer.
Optional.
Example:
INTERVAL FROM="3" TO="4"
FROM String. Mandatory.
TO String. Optional.
OVERLIB Name of an alternate job script library/directory. String. Optional.
Example:
OVERLIB FROM="lib3" TO="lib4"
FROM String. Mandatory.
TO String. Optional.
MAXWAIT Number of extra days (after the original scheduling date) that the job is allowed to
remain in the Active Jobs file awaiting execution. Integer. Optional.
Example:
MAXWAIT FROM="4" TO="3"
FROM Integer. Mandatory.
TO Integer. Optional.
DESCRIPTION Free text description of the job. String. Optional.
Example:
DESCRIPTION FROM="data backup from 120399" TO="data backup from 021400"
FROM String. Mandatory.
TO String. Optional.
DOCMEM Name of the file containing job documentation. String. Optional.
Example:
DOCMEM FROM="mem4" TO="Mem67"
FROM String. Mandatory.
TO String. Optional.
DOCLIB Name of library or directory containing the job documentation file. String.
Optional.
Example:
DOCLIB FROM="AcctFiles" TO="HRFiles"
FROM String. Mandatory.
TO String. Optional.

68 CONTROL-M/Enterprise Manager Utility Guide


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 7 of 14)


Tag Description
DAYS Days of the month on which to order the job. String. Optional.
Example:
DAYS FROM="ALL" TO="159"
FROM String. Mandatory.
TO String. Optional.
DAYS_AND_OR Relationship between specified Days values and Weekdays values. Optional.
Example:
DAYS_AND_OR FROM="AND" TO="OR"
FROM String. Mandatory.
TO String. Optional.
WEEKDAYS Days of the week on which to order the job. String. Optional.
Example:
WEEKDAYS FROM="1,2,4" TO="ALL"
FROM String. Mandatory.
TO String. Optional.
DATE Specific dates on which to order the job. String. MMDD format. Optional.
Example:
DATE FROM="0312" TO="0319"
FROM String. Dates are written in mmdd format. Mandatory. There is
no delimiter between dates. For example, January 10 is written:
DATE="0110."
TO String. Dates are written in mmdd format. Optional. There is no
delimiter between dates. For example, January 10 is written:
DATE="0110."
DAYSCAL User-defined calendar used to specify a set of days. String. Optional.
Example:
DAYSCAL FROM="shipping" TO="receiving"
FROM String. Mandatory.
TO String. Optional.
WEEKSCAL Calendar to be used to validate specified weekdays on which to order the job. String.
Optional.
Example:
WEEKSCAL FROM="w5" TO="w6"
FROM String. Mandatory.
TO String. Optional.
CONFCAL Specifies a calendar that is used to validate all specified days and dates on which to
schedule the job. String. Optional.
Example:
CONFCAL FROM="cal99" TO="cal00"
FROM String. Mandatory.
TO String. Optional.

Chapter 3 Job utilities 69


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 8 of 14)


Tag Description
RETRO Indicates whether the job is scheduled for possible execution after its original
scheduling date (odate) has passed. Optional.
Example:
RETRO FROM="0" TO="1"
FROM Mandatory. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

TO Optional. Valid values:


■ 0 (No. Default)
■ 1 (Yes)

SHIFT Describes how to shift the scheduling date of the job. Optional.
Example:
SHIFT FROM="PREVDAY" TO="NEXTDAY"
FROM Mandatory. Valid values:
■ IGNOREJOB
■ PREVDAY
■ NEXTDAY
■ NOCONFCAL

TO Optional. Valid values: Same as mandatory FROM values.


SHIFTNUM Number of days to shift the scheduling date of the job. Optional.
Example:
SHIFTNUM FROM="-10" TO="5"
FROM String. Mandatory.
TO String. Optional.
MAXDAYS Maximum number of days to retain the SYSDATA archive dataset for jobs that ended
NOTOK. Subparameter of AUTOARCH. String. Optional.
Example:
MAXDAYS FROM="07" TO="14"
FROM String. Mandatory.
TO String. Optional.
MAXRUNS Maximum number of job runs to retain the SYSDATA archive dataset for jobs that
ended NOTOK. Subparameter of AUTOARCH. String. Optional.
Example:
MAXRUNS FROM="100" TO="250"
FROM String. Mandatory.
TO String. Optional.
RERUNMEM [MVS only] JCL member to use when the job is automatically rerun. String. 1 - 8
characters. Optional.
Example:
RERUNMEM FROM="Mem45" TO="Mem7"
FROM String. Mandatory.
TO String. Optional.

70 CONTROL-M/Enterprise Manager Utility Guide


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 9 of 14)


Tag Description
RETEN_DAYS [MVS only] Number of days to retain the job in the History Jobs file. String.
Optional.
Example:
RETEN_DAYS FROM="5" TO="7"
FROM String. Mandatory.
TO String. Optional.
RETEN_GEN [MVS only] Maximum number of generations to keep in the History Jobs file. String.
Optional.
Example:
RETEN_GEN FROM="3" TO="4"
FROM String. Mandatory.
TO String. Optional.
TASK_CLASS Task class. Optional.
Example:
TASK_CLASS FROM="Distribution" TO="Decollation"
FROM String. Mandatory.
TO String. Optional.
PREV_DAY Optional.
Example:
PREV_DAY FROM="N" TO="Y"
FROM Mandatory. Valid values:
■ Y
■ N

TO Optional. Valid values:


■ Y
■ N

IND_CYCLIC Indicates whether the time interval between runs of a cyclic job is counted from the
start or the end of the previous job run. Optional.
Example:
IND_CYCLIC FROM="Y" TO="N"
FROM Mandatory. Valid values:
■ START
■ END

TO Optional. Valid values:


■ START
■ END

Chapter 3 Job utilities 71


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 10 of 14)


Tag Description
TAG_ Relationship (AND|OR) between the specified Schedule Tag criteria and the job’s
RELATIONSHIP own basic scheduling criteria. This parameter is relevant only for jobs in a group
scheduling table. Optional.
Example:
TAG_RELATIONSHIP FROM="AND" TO="OR"
FROM Mandatory. Valid values:
■ AND
■ OR

TO Optional. Valid values:


■ AND
■ OR

SYSDB Determines whether single or multiple data sets are used to catalogue sysdata.
Optional.
Example:
SYSDB FROM="1" TO="0"
FROM Mandatory. Valid values:
■ 0 (Multiple. Default)
■ 1 (Single)

TO Optional. Valid values:


■ 0 (Multiple. Default)
■ 1 (Single)

PDSNAME Name of partitioned dataset (PDS) to be checked for free space. String. Optional.
Example:
PDSNAME FROM="Lib_3" TO="Lib_5"
FROM String. Mandatory.
TO String. Optional.
MINIMUM Minimum number of free partitioned dataset tracks required by the library specified
for the PDSNAME parameter. Integer. Optional.
Example:
MINIMUM FROM="5" TO="6"
FROM Integer. Mandatory.
TO Integer. Optional.
CATEGORY Name of a CONTROL-D report decollating mission category that must be scheduled
under CONTROL-D when the job is scheduled under CONTROL-M. String. Optional.
Example:
CATEGORY FROM="*" TO="DAILY"
FROM String. Mandatory.
TO String. Optional.

72 CONTROL-M/Enterprise Manager Utility Guide


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 11 of 14)


Tag Description
PREVENTNCT2 [MVS only] Prevents dataset cleanup before the original job run Optional. Valid
values:
■ Blank – Does not perform data set cleanup before the original job run. Default.
■ N – Does not prevent cleanup.
■ Y - Prevents data set cleanup. This value is not valid for started tasks.
■ L (List) – Do not perform data set cleanup before the original job run. Do generate
messages that would be required for CDG adjustment during restart.
■ F (Flush) – Halt processing of the job if any data set cleanup error is detected (even
if MVS would not have stopped processing the job).
Example:
PREVENTNC2 FROM="1" TO="0"
FROM Mandatory. Valid values:
■ 0 (Do not prevent)
■ 1 (Prevent)

TO Optional. Valid values:


■ 0 (Do not prevent. Default.)
■ 1 (Prevent)

JAN, FEB, MAR, Months when the job can run. Optional. Not including a month is the same as
APR, MAY, JUN, including that month with the value 0.
JUL, AUG, SEP, Example:
OCT, NOV, DEC JAN FROM="0" TO="1"
JUL FROM="0" TO="1"
FROM Mandatory. Valid values:
■ 0 (Do not run the job. Default)
■ 1 (Run the job.)

TO Optional. Valid values:


■ 0 (Do not run the job. Default)
■ 1 (Run the job.)

OPTION Job output (Sysout) handling options. Optional.


Example:
OPTION FROM="Copy" TO="Release"
FROM Mandatory. Valid values:
■ Release
■ Delete
■ Copy
■ Move
■ File
■ NewDest
■ ChangeClass

TO Optional. Valid values: same as mandatory FROM values.


PAR Certain OPTION values require that you supply additional information (such as
Release, NewDest). The PAR parameter holds that information as a string. Optional.
Example:
PAR FROM="mem3log" TO="mem5log"
FROM String. Mandatory.
TO String. Optional.

Chapter 3 Job utilities 73


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 12 of 14)


Tag Description
FROM Limits the sysout handling operation to sysouts from the specified class. Optional.
Example:
FROM FROM="1" TO="2"
FROM String. Mandatory.
TO String. Optional.
ADJUST_COND Indicates whether to ignore prerequisite conditions normally set by predecessor jobs if
the relevant predecessor jobs are not scheduled. This parameter is relevant only for
jobs in a group scheduling table. Optional. Valid values:
■ 0 (Do not ignore. Default.)
■ 1 (Ignore relevant prerequisite conditions.)
Example:
ADJUST_COND FROM="1" TO="0"
FROM String. Mandatory.
TO String. Optional.
APPL_TYPE Type of external application (for example, SAP or Oracle) on which the external
application job runs. Mandatory for external application jobs.
Example:
APPL_TYPE FROM=”SAP” TO=”OracleApps”
FROM Mandatory. String. Up to 10 characters.
TO Optional. String.
APPL_VER Version of the external application (for example, SAP or Oracle) on which the external
application job runs. Mandatory for external application jobs.
Example:
APPL_VER FROM=”4.5” TO=”4.6”
FROM Mandatory. String. Up to 10 characters.
TO Optional. String.
APPL_FORM Predefined set of external application parameters that are displayed in the Job Editing
form. Mandatory for external application jobs.
Example:
APPL_FORM FROM=”Default SAP 4.6” TO=”Default SAP 4.5”
FROM Mandatory. String. Up to 30 characters.
TO Optional. String.
CM_VER Version of external application (for example, SAP or Oracle) Control Module that is
installed in the CONTROL-M installation. Mandatory for external application jobs.
Example:
CM_VER FROM=”6.1.00” TO=”6.1.01”
FROM Mandatory. String. Up to 10 characters.
TO Optional. String.

74 CONTROL-M/Enterprise Manager Utility Guide


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 13 of 14)


Tag Description
MULTY_AGENT When selected, broadcasts job submission details to all Agents in a specified Node
Group. Optional.
Example:
MULTY_AGENT FROM=”N” TO=”Y”
FROM Mandatory. Valid values:
■ Y – Run as multi-agent job
■ N – Do not run as multi-agent job. Default.

TO Optional. String.
ACTIVE_FROM [MVS only] Start of a period of time during which the job or group scheduling table
can be ordered. Optional.
Example:
ACTIVE_FROM FROM=”20040315” TO=”20040601”
FROM Mandatory. Date Format: YYYYMMDD
TO Optional. String.
ACTIVE_TILL [MVS only] End of a period of time during which the job or group scheduling table
can be ordered. Optional.
Example:
ACTIVE_TILL FROM=”20040315” TO=”20040601”
FROM Mandatory. Date Format: YYYYMMDD
TO Optional. String.
TIMEZONE Global time zone used to calculate the interval for time-related conditions. Optional.
Example:
TIMEZONE FROM=”EST” TO=”GMT”
FROM Mandatory. String. Default: GMT
TO Optional. String.
SYSTEM_AFFINITY Identity of the system in which the job must be initiated and executed (in JES2).
Identity of the processor on which the job must execute (in JES3). Optional. String.
FROM String. Mandatory.
Example:
SYSTEM_AFFINITY FROM=”SYS3”
TO String. Optional.
Example:
SYSTEM_AFFINITY FROM=”SYS3” TO=”SYS6”
REQUEST_NJE_ Node in the JES network on which the job is to execute.
NODE FROM String. Mandatory.
Example:
REQUEST_NJE_NODE=”OS5”
TO String. Optional.
Example:
REQUEST_NJE_NODE FROM=”OS5” TO=”OS6”

Chapter 3 Job utilities 75


duplicatedefjob

Table 17 duplicatedefjob arguments file tags (Part 14 of 14)


Tag Description
SCHEDULING_ [MVS only] Indicates the JES2 workload management scheduling environment
ENVIRONMENT associated with the job.
FROM String. Mandatory. Example:
SCHEDULING_ENVIRONMENT FROM=”SCHD2”
TO String. Optional. Example:
SCHEDULING_ENVIRONMENT FROM=”SCHD2”
TO=”SCHD3”
JOBS_IN_GROUP Number of jobs in the group scheduling table. Optional.
Example:
JOBS_IN_GROUP FROM="4" TO="10"
FROM String. Mandatory.
TO String. Optional.
CREATION_USER Name of the user that created the job. String. Optional.
Example:
CREATION_USER FROM="emuser" TO="em1"
FROM String. Mandatory.
TO String. Optional.
CREATION_DATE Date that the job was created. String. Optional.
Example:
CREATION_DATE FROM="1212" TO="2012"
FROM String. Mandatory.
TO String. Optional.
CREATION_TIME Time that the job was created. String. Optional.
Example:
CREATION_TIME FROM="1230" TO="1430"
FROM String. Mandatory.
TO String. Optional.
CHANGE_USERID Name of the user that last modified the job. String. Optional.
Example:
CHANGE_USERID FROM="emuser" TO="emacct"
FROM String. Mandatory.
TO String. Optional.
CHANGE_DATE Date that the job was last modified. String. Optional.
Example:
CHANGE_DATE FROM="1204" TO="1304"
FROM String. Mandatory.
TO String. Optional.
CHANGE_TIME Time that the job was last modified. String. Optional.
Example:
CHANGE_TIME FROM="1650" TO="1700"
FROM String. Mandatory.
TO String. Optional.

76 CONTROL-M/Enterprise Manager Utility Guide


duplicatedefjob

Sample input files used with the duplicatedefjob utility:

Example 1: Copy and modify definitions

Copy job processing definitions from the Tbl5NYC scheduling table that have
TABLE_DSN Lib1 and JOBNAME Job3. Change TABLE_DSN to Lib1_COPY and
change JOBNAME to Job3_COPY. Store the changed definitions in the same
scheduling table.

?xml version=’1.0’ encoding=’UTF-8’?


<!DOCTYPE DUPLICATEJOB SYSTEM "duplicatejob.dtd">
<DUPLICATEJOB>
<TABLE_NAME FROM="Tbl5NYC"/>
<TABLE_DSN FROM="Lib1" TO="Lib1_COPY"/>
<JOBNAME FROM="Job3" TO="Job3_COPY"/>
</DUPLICATEJOB>

Example 2: Copy definitions from one scheduling table to another

Copy all the jobs in the Tbl5NYC scheduling table to the Tbl7LA scheduling table.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE DUPLICATEJOB SYSTEM "duplicatejob.dtd">
<DUPLICATEJOB>
<TABLE_NAME FROM="Tbl5NYC" TO="Tbl7LA"/>
</DUPLICATEJOB>

Example 3: Duplicate jobs based on several criteria

Copy all cyclic jobs in the GrpAcct group whose jobname begins with “Acct”.
Append “_COPY” to the job name of each copied job.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE DUPLICATEJOB SYSTEM "duplicatejob.dtd">
<DUPLICATEJOB>
<GROUP FROM="GrpAcct"/>
<CYCLIC FROM="1"/>
<JOBNAME FROM="Acct*" TO="Acct*_COPY"/>
</DUPLICATEJOB>

Chapter 3 Job utilities 77


exportdefjob

exportdefjob
The exportdefjob utility exports job processing definitions from a scheduling table in
the CONTROL-M/EM database to an output file.

When exportdefjob is invoked, it processes a specified file of arguments in XML


format. This file contains statements that identify existing job processing definitions.
The identified definitions are exported from the CONTROL-M/EM database to an
output file. You can modify the exported job processing definitions in the output file
and can import the modified definitions into the CONTROL-M/EM database using
either the defjob or updatedef utility.

To invoke the exportdefjob utility:

1 Log on to a CONTROL-M/EM account (Unix)


- or -
open a command prompt window (Microsoft Windows) where CONTROL-M/EM
is installed.

2 Enter either of the following commands:

exportdefjob [-u user [-p password] | -pf password_file]


-s gui_server_name -arg arg_file_name -out out_file_name

- or -
exportdefjob [-USERNAME user [-PASSWORD password] | -PASSWORD_FILE
password_file] -HOST gui_server_name -ARG_FILE arg_file_name
-OUT_FILE out_file_name

Parameters of the exportdefjob utility are described in Table 18.

3 Press Enter. The exportdefjob arguments file is checked and processed. If there are
any errors, a message is displayed specifying the lines with the errors. The
exported job processing definitions are saved to the output file whose name and
location is specified in the out_file_name parameter.

78 CONTROL-M/Enterprise Manager Utility Guide


exportdefjob

Parameters

Table 18 exportdefjob parameters


Parameter Description
user CONTROL-M/EM user name.
password The CONTROL-M/EM user password.
password_file Flat file containing an unencrypted username and password on separate
lines in the format:
user=username
password=password
Note: If both -u and -pf are specified, an error message is generated. If only
-u is specified, an online prompt is issued for the password. If neither is
specified, a prompt is issued for the database user name and password.
gui_server_ CONTROL-M/EM GUI server logical name, host name, or IP address.
name Note: If multiple GUI servers exist, set this parameter to the logical name of
the relevant GUI server.
arg_file_name Path and name of the arguments file containing exportdefjob specifications.
For information about this file, see Appendix A, “XML File Preparation.”
out_file_name Path and name of the file containing the exported job specifications.

exportdefjob arguments file


The following rules apply to the exportdefjob argument file:
■ More than one job can be specified in an exportdefjob file.

■ The arguments file is case-sensitive.

■ All parameter values must be enclosed in quotation marks (for example,


JOBNAME="Job1").
■ More than one PARAM parameter can be used in a TERM statement.

■ The relationship between PARAM parameters in a TERM statement is AND.

■ The default relationship between TERM statements is OR.

Chapter 3 Job utilities 79


exportdefjob

Table 19 exportdefjob arguments file Parameters


Parameter Description
The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file. These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE TERMS SYSTEM "terms.dtd"
TERMS These tags indicate the start and end of the TERMS file. Only criteria that are
located between the tags are considered to be part of the argument.
TERM The TERM tags indicate the start and the end of a group of selection criteria used
to specify a job or jobs that are to be exported. Only PARAM tags that are located
between the TERM tags are considered to be part of the TERM argument.
REL Relationship between terms. Optional. Valid values:
■ AND
■ OR

PARAM Selection criteria parameter used to determine the job definitions that are to be
exported. More than one PARAM can be specified. Mandatory.
Example:
PARAM NAME="DATACENTER" OP="EQ" VALUE="Center1"
NAME String. Mandatory. The parameter name of any job
processing definition parameter. Job processing parameters
are described in Table 8 on page 26.
Note: At least one of the following scheduling table
parameters must be included in the arguments file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

OP Relationship between the NAME and VALUE parameters of


the TERM. Mandatory. Valid values:
■ EQ – equal
■ NEQ – not equal
■ NOTIN – does not contain
■ LIKE – mask or pattern

VALUE String. Mandatory. Value of the parameter specified in the


NAME field. Job processing parameters are described in
Table 8 on page 26.

Example 1: Export job definitions based on one or more criteria

Export job processing definitions that either:

■ have data center name Data1 and a jobname that begins with the letter J.
- or -
■ have jobname Job5 and are not cyclic jobs.

80 CONTROL-M/Enterprise Manager Utility Guide


exportdefjob

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE TERMS SYSTEM "terms.dtd">
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="Data1"/>
<PARAM NAME="JOBNAME" OP="LIKE" VALUE="J*"/>
</TERM>
<TERM>
<PARAM NAME="JOBNAME" OP="EQ" VALUE="Job5"/>
<PARAM NAME="CYCLIC" OP="EQ" VALUE="0"/>
</TERM>
</TERMS>

Example 2: Export based on multiple criteria

Export all job processing definitions from either the Data1 or Data2 data center that
have a JobName that does not begin with the letter R.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE TERMS SYSTEM "terms.dtd">
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="Data1"/>
<PARAM NAME="JOBNAME" OP="NEQ" VALUE="R*"/>
</TERM>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="Data2"/>
<PARAM NAME="JOBNAME" OP="NEQ" VALUE="R*"/>
</TERM>
</TERM>
</TERMS>

Chapter 3 Job utilities 81


updatedef

updatedef
The updatedef utility updates (modifies) specified parameter values in the following
definitions in the CONTROL-M/EM database:

■ Job processing definitions


■ Scheduling table definitions
■ Group scheduling table definitions

NOTE
updatedef modifies the characteristics of existing job processing definitions. duplicatedefjob
creates new job processing definitions based on existing job processing definitions in the
“from” data center and scheduling tables.

The selected jobs, scheduling tables, and group scheduling tables are modified
according to specifications in the updatedef arguments file. The updatedef utility
does not create new jobs or scheduling tables.

To invoke the updatedef utility:

1 Log on to a CONTROL-M/EM account (Unix)


- or -
open a command prompt window (Microsoft Windows) where CONTROL-M/EM
is installed.

2 Enter either of the following commands:

updatedef [-u user [-p password] | -pf password_file]


-s gui_server_name -arg arg_file_name [/a]

- or -
updatedef [-USERNAME user [-PASSWORD password] | -PASSWORD_FILE
password_file] -HOST gui_server_name -ARG_FILE arg_file_name [/a]

Parameters of the updatedef utility are described in Table 20.

3 Press Enter. The updatedef arguments file is checked and processed. If there are
any errors in the file, a message is displayed specifying the lines with the errors.

82 CONTROL-M/Enterprise Manager Utility Guide


updatedef

Parameters

Table 20 updatedef parameters


Parameter Description
user CONTROL-M/EM user name.
password The CONTROL-M/EM user password.
password_ Flat file containing an unencrypted username and password on separate lines
file in the format:
user=username
password=password
Note: If both -u and -pf are specified, an error message is generated. If only -u
is specified, an online prompt is issued for the password. If neither is specified,
a prompt is issued for the database user name and password.
gui_server_ CONTROL-M/EM GUI server logical name, host name, or IP address.
name Note: If multiple GUI servers exist, set this parameter to the logical name of the
relevant GUI server.
arg_file_ Path and name of the arguments file containing updatedef specifications. For
name information about preparing this file, see Appendix A, “XML File Preparation.”

An optional switch for the updatedef utility is described in Table 21.

Table 21 updatedef switch


Switch Description
/a The /a switch directs the utility to automatically reset the Author parameter to the
current CONTROL-M/EM user when these two values do not match. If not
specified, the utility skips (i.e., does not process) job definitions whose Author does
not match the currently logged in user.
Note: The /a switch has no effect on Administrator users and is relevant only when
the AuthorSecurity system parameter is set to 2 or 3.

updatedef arguments file


The following rules apply to the updatedef arguments file:
■ More than one job, scheduling table, or group scheduling table can be specified in
the arguments file.
■ The arguments file is case-sensitive.

■ All parameter values must be enclosed in quotation marks (for example,


JOBNAME="Job1").
■ Multiple values can be specified by using the * wildcard character. For an
explanation of how wildcards function in the XML-based utilities, see “Wildcards”
on page 178.

Chapter 3 Job utilities 83


updatedef

Most parameters of the job, scheduling table, or group scheduling table definitions
are optional. However:
■ If you specify a parameter, its FROM subparameter is mandatory and its TO
subparameter is optional.
■ When a FROM value is specified without a TO value, the FROM value is used as a
filter criterion.
■ When a TO value is included, it indicates the new value to which the parameter is
set.

NOTE
Group scheduling table parameters are usually modified using the group scheduling table
criteria described in Table 23. However, you cannot use these criteria to change the name of a
group scheduling table.

The scheduling table name parameter of a job processing definition cannot be modified using
the job definition criteria described in Table 24. However, you can use the updatedef utility to
change the name of a group scheduling table or scheduling table by using the criteria for
scheduling tables (described in Table 22) and specifying a new value for the TABLE_NAME
parameter.

Three sets of parameters can be supplied in an arguments file – one each for
scheduling tables, group scheduling tables, and jobs. Each set of parameters is
described in a table below:

■ “Table 22Arguments file parameters for scheduling tables.”


■ “Table 23Arguments file parameters for group scheduling tables” on page 85
■ “Table 24Arguments file parameters for jobs” on page 90

Table 22 Arguments file parameters for scheduling tables (Part 1 of 2)


Parameter Description
The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file. These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE UPDATE SYSTEM "update.dtd"
UPDATE These tags indicate the start and end of the UPDATE argument. Only criteria located
between the tags are considered to be part of the argument. Mandatory.
SCHED_TABLE These tags indicate the start and end of the scheduling table specification. Criteria
identifying the scheduling tables to be modified and indicating the types of
modifications to be made are located between these tags. Optional.
TABLE_NAME Name of the scheduling table to which the job belongs. Optional.
Example:
TABLE_NAME FROM=”Tbl5NYC” TO=”Tbl_new”
FROM String. Mandatory.
TO String. Optional.

84 CONTROL-M/Enterprise Manager Utility Guide


updatedef

Table 22 Arguments file parameters for scheduling tables (Part 2 of 2)


Parameter Description
TABLE_DSN [MVS only] Name of the library that contains the scheduling table. Optional.
ABLE_DSN FROM=”Lib1” TO=”Lib2”
FROM String. Mandatory.
TO String. Optional.
DATACENTER Name of the CONTROL-M installation to which the job belongs. Optional.
Note: A TO parameter cannot be specified for this parameter.
Example:
DATACENTER FROM="CTMNYC"
FROM String. Mandatory.
TABLE_USERDAILY Optional.
Note: This parameter cannot be modified.
Example:
TABLE_USERDAILY FROM="Job3A"
FROM String. Mandatory.

Table 23 Arguments file parameters for group scheduling tables (Part 1 of 6)


Parameter Description
The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file. These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE UPDATE SYSTEM "update.dtd"
UPDATE These tags indicate the start and end of the UPDATE argument. Only criteria
located between the tags are considered to be part of the argument. Mandatory.
GROUP_SCHED These tags indicate the start and end of the group scheduling table specification.
Criteria identifying the group scheduling tables to be modified and indicating
the types of modifications to be made are located between these tags. Optional.
TABLE_NAME Name of the group scheduling table.
Notes:
This parameter cannot be modified.
At least one of the following scheduling table parameters must be included in
the input file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN
Example:
TABLE_NAME FROM="Tbl42"
FROM String. Mandatory

Chapter 3 Job utilities 85


updatedef

Table 23 Arguments file parameters for group scheduling tables (Part 2 of 6)


Parameter Description
DATACENTER Name of the CONTROL-M installation to which the job belongs. Optional.
Notes:
A TO subparameter cannot be specified for this parameter.
At least one of the following scheduling table parameters must be included in
the input file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN
Example:
DATACENTER FROM="CTMNYC"
FROM String. Mandatory
TABLE_DSN [MVS only] Name of the library that contains the group scheduling table.
Optional.
Notes:
A TO subparameter cannot be specified for this parameter.
At least one of the following scheduling table parameters must be included in
the input file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN
Example:
TABLE_DSN FROM="CTMNYC"
FROM String. Mandatory
TABLE_ Optional.
USERDAILY Note: A TO subparameter cannot be specified for this parameter.
Example:
TABLE_USERDAILY FROM="CTMNYC"
FROM String. Mandatory
GROUP Name of the group to which the group scheduling table belongs. Used as a
descriptive name for related tables. Optional.
Example:
GROUP FROM="Grp_HR" TO="Grp_ACCT"
FROM String. Mandatory.
TO String. Optional.
USED_BY Optional.
Example:
USED_BY FROM="fff" TO="ffg"
FROM String. Mandatory.
TO String. Optional.
USED_BY_CODE Optional.
Example:
USED_BY_CODE FROM="C***" TO="D***"
FROM String. Mandatory.
TO String. Optional.

86 CONTROL-M/Enterprise Manager Utility Guide


updatedef

Table 23 Arguments file parameters for group scheduling tables (Part 3 of 6)


Parameter Description
MODIFIED Optional.
Example:
MODIFIED FROM="1101" TO="1102"
FROM String. Mandatory.
TO String. Optional.
LAST_UPLOAD Date of the last table upload. String. Optional.
Example:
LAST_UPLOAD FROM="1101" TO="1102"
FROM String. Mandatory.
TO String. Optional.
CHECKSUM Optional.
Example:
CHECKSUM FROM="Y" TO="N"
FROM String. Mandatory.
TO String. Optional.
TABLE_ID Name of the scheduling table to which the job belongs. Optional.
Example:
TABLE_ID FROM="Tbl001" TO="Tbl002"
FROM String. Mandatory.
TO String. Optional.
REAL_TABLEID Optional.
Example:
REAL_TABLEID FROM="43556" TO="43557"
FROM String. Mandatory.
TO String. Optional.
JOBNAME Name of the job processing definition. Optional.
Example:
JOBNAME FROM="Job3"
FROM String. Mandatory.
TO String. Optional.
MEMNAME Name of the file that contains the job script. Optional.
Example:
MEMNAME FROM="Mem3" TO="Mem7"
FROM String. Mandatory.
TO String. Optional.
APPLICATION Name of the application to which the job’s group belongs. Used as a descriptive
name for related jobs. Optional.
Example:
APPLICATION FROM="App3""
FROM String. Mandatory.
TO String. Optional.

Chapter 3 Job utilities 87


updatedef

Table 23 Arguments file parameters for group scheduling tables (Part 4 of 6)


Parameter Description
OWNER Owner (user ID) associated with the job. This parameter is used by the
CONTROL-M/Server security mechanism. Optional.
Example:
OWNER FROM="emuser" TO="emhr"
FROM String. Mandatory.
TO String. Optional.
ADJUST_COND Indicates whether to ignore prerequisite conditions normally set by predecessor
jobs if the relevant predecessor jobs are not scheduled. Optional. Valid values:
■ 0 (Do not ignore. Default.)
■ 1 (Ignore relevant prerequisite conditions.)
Example:
ADJUST_COND FROM="1" TO="2"
FROM String. Mandatory.
TO String. Optional.
CONFIRM Indicates whether the job must be manually confirmed by the
CONTROL-M/EM user before it runs. Optional.
Example:
CONFIRM FROM="0" TO="1"
FROM Mandatory. Valid values:
■ 0 (Default)
■ 1

TO Optional. Valid values:


■ 0 (Default)
■ 1

PRIORITY Indicates CONTROL-M job priority. Optional. Two-character alphanumeric


from 00 to ZZ.
Example:
PRIORITY FROM="AA" TO="BB"
FROM String. Mandatory.
TO String. Optional.
TIMEFROM Indicates the earliest time for submitting the group scheduling table. Format:
hhmm. Optional.
Example:
TIMEFROM FROM="1430" TO="1450"
FROM String. Mandatory.
TO String. Optional.
TIMETO Indicates the latest time for submitting the group scheduling table. Format:
hhmm. Optional.
Example:
TIMETO FROM="1430" TO="1450"
FROM String. Mandatory.
TO String. Optional.

88 CONTROL-M/Enterprise Manager Utility Guide


updatedef

Table 23 Arguments file parameters for group scheduling tables (Part 5 of 6)


Parameter Description
DUE_OUT Time that the job is expected to finish. Optional.
Example:
DUE_OUT FROM="1500" TO="1750"
FROM String. Mandatory.
TO String. Optional.
DOCMEM Name of the file containing job documentation. String. Optional.
Example:
DOCMEM FROM="mem4" TO="Mem67"
FROM String. Mandatory.
TO String. Optional.
DOCLIB Name of a library or directory containing the job documentation file. String.
Optional.
Example:
DOCLIB FROM="AcctFiles" TO="HRFiles"
FROM String. Mandatory.
TO String. Optional.
DESCRIPTION Free text description of the job. String. Optional.
Example:
DESCRIPTION FROM="backup jobs from 120399" TO="backup jobs from 021400"
FROM String. Mandatory.
TO String. Optional.
AUTHOR CONTROL-M/EM user who defined the job. String. Optional. Example:
AUTHOR FROM="emuser" TO="emadmin"
Note: The New Day Procedure compares the Author and Owner for each job to
check if the job's user has authorization to submit the job. CONTROL-M/EM
security levels determine who can edit the Author value (any user or
administrators only). For more information, see the Security chapter and the
description of the AuthorSecurity system parameter in the
CONTROL-M/Enterprise Manager Administrator Guide.
FROM String. Mandatory.
TO String. Optional.
CREATION_USER Name of the user that created the job. String. Optional.
Example:
CREATION_USER FROM="emuser" TO="em1"
FROM String. Mandatory.
TO String. Optional.
CREATION_DATE Date that the group scheduling table was created. String. Format: ddmm.
Optional.
Example:
CREATION_DATE FROM="1212" TO="2012"
FROM String. Mandatory.
TO String. Optional.

Chapter 3 Job utilities 89


updatedef

Table 23 Arguments file parameters for group scheduling tables (Part 6 of 6)


Parameter Description
CREATION_TIME Time the group scheduling table was created. String. Format: hhmm. Optional.
Example:
CREATION_TIME FROM="1230" TO="1430"
FROM String. Mandatory.
TO String. Optional.
CHANGE_USERID Name of the user that last modified the group scheduling table. String. Optional.
Example:
CHANGE_USERID FROM="emuser" TO="emadmin"
FROM String. Mandatory.
TO String. Optional.
CHANGE_DATE Date that the group scheduling table was last modified. String. Format: ddmm.
Optional.
Example:
CHANGE_DATE FROM="1204" TO="1304"
FROM String. Mandatory.
TO String. Optional.
CHANGE_TIME Time that the group scheduling table was last modified. String. Format: hhmm.
Optional.
Example:
CHANGE_TIME FROM="1650" TO="1700"
FROM String. Mandatory.
TO String. Optional.

Table 24 Arguments file parameters for jobs (Part 1 of 14)


Parameter Description
The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file. These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE UPDATE SYSTEM "update.dtd"
UPDATE These tags indicate the start and end of the UPDATE argument. Only criteria
that are located between the tags are considered to be part of the argument.
Mandatory.
JOB These tags indicate the start and end of each job specification. Criteria
identifying the jobs to be modified and indicating the types of modifications to
be made are located between these tags. Optional.
TABLE_NAME Name of the scheduling table to which the job belongs. Mandatory.
Notes:
This parameter cannot be modified.
Example:
TABLE_NAME FROM=”Tbl5NYC”
FROM String. Mandatory.

90 CONTROL-M/Enterprise Manager Utility Guide


updatedef

Table 24 Arguments file parameters for jobs (Part 2 of 14)


Parameter Description
TABLE_DSN [MVS only] Name of the library that contains the scheduling table. Mandatory.
Notes:
This parameter cannot be modified.
Example:
TABLE_DSN FROM=”Lib1”
FROM String. Mandatory.
DATACENTER Name of the CONTROL-M installation to which the job belongs. Mandatory.
Notes:
This parameter cannot be modified.
Example:
DATACENTER FROM="CTMNYC"
FROM String. Mandatory.
TABLE_ Optional.
USERDAILY Note: This parameter cannot be modified.
Example:
TABLE_USERDAILY FROM="Job3"
FROM String. Mandatory.
JOBNAME Name of the job processing definition. Optional.
Example:
JOBNAME FROM="Job3" TO="Job3_COPY"
FROM Mandatory.
TO Optional.
MEMNAME Name of the file that contains the job script. Optional.
Example:
MEMNAME FROM="Mem3" TO="Mem7"
FROM Mandatory.
TO Optional.
GROUP Name of the group to which the job belongs. Optional.
Example:
GROUP FROM="Grp_HR"
FROM Mandatory.
APPLICATION Name of the application to which the job’s group belongs. Optional.
Example:
APPLICATION FROM="App3" TO="App1"
FROM String. Mandatory.
TO String Optional.

Chapter 3 Job utilities 91


updatedef

Table 24 Arguments file parameters for jobs (Part 3 of 14)


Parameter Description
TASKTYPE Type of the job (task) to be performed by CONTROL-M. Optional.
Example:
TASKTYPE FROM="Detached" TO="Dummy"
FROM Mandatory.
Valid values:
■ Job
■ Detached
■ Command
■ Dummy
■ External
[MVS only] Valid values:
■ Job
■ Started_Task
Note: In CONTROL-M/EM versions earlier than 6.1.00, the
format for TASKTYPE contained critical and cyclic
information. CONTROL-M/EM version 6.1.03 can run jobs
whose TASKTYPE is specified in the old format. However,
BMC Software recommends that you specify this type of
information using the CYCLIC and CRITICAL parameters
when creating new job processing definitions.
TO Optional. Valid values: Same as mandatory FROM values.
[MVS only] Valid values: Same as MVS FROM values.
AUTHOR CONTROL-M/EM user who defined the job. This parameter is used by the
CONTROL-M/Server security mechanism. String. Optional.
Note: This argument is used by the CONTROL-M/Server security mechanism
and, under certain circumstances, cannot be modified. For more information,
see the Security chapter and the description of the AuthorSecurity system
parameter in the CONTROL-M/Enterprise Manager Administrator Guide.
Example:
AUTHOR FROM="emuser" TO="em5"
FROM String. Mandatory.
TO String. Optional.
MEMLIB Name of the library/directory in which the job script resides. String. Optional.
Example:
MEMLIB FROM="Mem1" TO="Mem4"
FROM String. Mandatory.
TO String. Optional.
CMDLINE Command string supplied when the job Task Type is Command. Optional.
Example:
CMDLINE FROM="C:\Format" TO="C\:CD Emnt"
FROM String. Mandatory.
TO String. Optional.

92 CONTROL-M/Enterprise Manager Utility Guide


updatedef

Table 24 Arguments file parameters for jobs (Part 4 of 14)


Parameter Description
NODEID Host name of an Agent platform or node group to which the job is submitted.
Optional.
Example:
NODEID FROM="Com3" TO="Acct4"
FROM String. Mandatory.
TO Host name of the Agent platform on which the job copy is
running Optional.
OWNER Owner (user ID) associated with the job. This parameter is used by the
CONTROL-M/Server security mechanism. Optional.
Example:
OWNER FROM="emuser" TO="emhr"
FROM String. Mandatory.
TO String. Optional.
MAXRERUN Maximum number of reruns that can be performed for the job. Optional.
Example:
MAXRERUN FROM="1" TO="3"
FROM String. Mandatory.
TO String. Optional.
TIMEFROM Earliest time for submitting the job. Optional.
Example:
TIMEFROM FROM="1430" TO="1450"
FROM String. Mandatory.
TO String. Optional.
TIMETO Latest time for submitting the job. Optional.
Example:
TIMETO FROM="1600" TO="1620"
FROM String. Mandatory.
TO String. Optional.
DUE_OUT Time that the job is expected to finish. Optional.
Example:
DUE_OUT FROM="1500" TO="1530"
FROM String. Mandatory.
TO String. Optional.
PRIORITY Indicates CONTROL-M job priority. Optional.
Example:
PRIORITY FROM="AA" TO="1A"
FROM String. Mandatory.
TO String. Optional.

Chapter 3 Job utilities 93


updatedef

Table 24 Arguments file parameters for jobs (Part 5 of 14)


Parameter Description
CRITICAL Indicates whether the job is a critical-path job in CONTROL-M. Optional.
Example:
CRITICAL FROM="0" TO="1"
FROM Mandatory. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

TO Optional. Valid values:


■ 0 (No. Default)
■ 1 (Yes)

CYCLIC Indicates whether the job is cyclic (to be run at regular intervals). Optional.
Example:
CYCLIC FROM="0" TO="1"
FROM Mandatory. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

TO Optional. Valid values:


■ 0 (No. Default)
■ 1 (Yes)

CONFIRM Indicates that the job must be manually confirmed by the CONTROL-M/EM
user before it runs. Optional.
Example:
CONFIRM FROM="0" TO="1"
FROM Mandatory. Valid values:
■ 0 (Default)
■ 1

TO Optional. Valid values:


■ 0 (Default)
■ 1

AUTOARCH Determines whether SYSDATA is to be archived. Optional.


Example:
AUTOARCH FROM=0" TO="1"
FROM Mandatory. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

TO Optional. Valid values:


■ 0 (No. Default)
■ 1 (Yes)

INTERVAL Length of time (in minutes) to wait between reruns of a job or between cyclic
runs of a job. Integer. Optional.
Example:
INTERVAL FROM="3" TO="4"
FROM String. Mandatory.
TO String. Optional.

94 CONTROL-M/Enterprise Manager Utility Guide


updatedef

Table 24 Arguments file parameters for jobs (Part 6 of 14)


Parameter Description
OVERLIB Name of an alternate job script library/directory. String. Optional.
Example:
OVERLIB FROM="lib3" TO="lib4"
FROM String. Mandatory.
TO String. Optional.
MAXWAIT Number of extra days (after the original scheduling date) that the job is allowed
to remain in the Active Jobs file awaiting execution. Integer. Optional.
Example:
MAXWAIT FROM="4" TO="3"
FROM Integer. Mandatory.
TO Integer. Optional.
DESCRIPTION Free text description of the job. String. Optional.
Example:
DESCRIPTION FROM="data backup from 120399" TO="data backup from 021400"
FROM String. Mandatory.
TO String. Optional.
DOCMEM Name of the file containing job documentation. String. Optional.
Example:
DOCMEM FROM="mem4" TO="Mem67"
FROM String. Mandatory.
TO String. Optional.
DOCLIB Name of a library or directory containing the job documentation file. String.
Optional.
Example:
DOCLIB FROM="AcctFiles" TO="HRFiles"
FROM String. Mandatory.
TO String. Optional.
DAYS Days of the month on which to order the job. String. Optional.
Example:
DAYS FROM="ALL" TO="159"
FROM String. Mandatory.
TO String. Optional.
DAYS_AND_OR Indicates the relationship between specified Days values and Weekdays values.
Optional.
Example:
DAYS_AND_OR FROM="AND" TO="OR"
FROM String. Mandatory.
TO String. Optional.

Chapter 3 Job utilities 95


updatedef

Table 24 Arguments file parameters for jobs (Part 7 of 14)


Parameter Description
WEEKDAYS Days of the week on which to order the job. String. Optional.
Example:
WEEKDAYS FROM="1,2,4" TO="ALL"
FROM String. Mandatory.
TO String. Optional.
DATE Specific dates on which to order the job. String. mmdd format. Optional.
Example:
DATE FROM="0312" TO="0319"
FROM String. Mandatory. Dates are written in mmdd format.
There is no delimiter between dates. For example, January
10 is written in this manner: DATE="0110"
TO String. Optional. Dates are written in mmdd format. There
is no delimiter between dates. For example, January 10 is
written in this manner: DATE="0110"
DAYSCAL Name of a user-defined calendar used to specify a set of days. String. Optional.
Example:
DAYSCAL FROM="shipping" TO="receiving"
FROM String. Mandatory.
TO String. Optional.
WEEKSCAL Name of a calendar to be used to validate specified weekdays on which to order
the job. String. Optional.
Example:
WEEKSCAL FROM="w5" TO="w6"
FROM String. Mandatory.
TO String. Optional.
CONFCAL Specifies a calendar that is used to validate all specified days and dates on which
to schedule the job. String. Optional.
Example:
CONFCAL FROM="cal99" TO="cal00"
FROM String. Mandatory.
TO String. Optional.
RETRO Indicates whether the job is scheduled for possible execution after its original
scheduling date (odate) has passed. Optional.
Example:
RETRO FROM="0" TO="1"
FROM Mandatory. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

TO Optional. Valid values:


■ 0 (No. Default)
■ 1 (Yes)

96 CONTROL-M/Enterprise Manager Utility Guide


updatedef

Table 24 Arguments file parameters for jobs (Part 8 of 14)


Parameter Description
SHIFT Describes how to shift the scheduling date of the job. Optional.
Example:
SHIFT FROM="PREVDAY" TO="NEXTDAY"
FROM Mandatory. Valid values:
■ IGNOREJOB
■ PREVDAY
■ NEXTDAY
■ NOCONFCAL

TO Optional. Valid values: Same values as mandatory FROM.


SHIFTNUM Number of days to shift the scheduling date of the job. Optional.
Example:
SHIFTNUM FROM="-10" TO="5"
FROM String. Mandatory.
TO String. Optional.
MAXDAYS Maximum number of days to retains the SYSDATA archive dataset for jobs that
ended NOTOK. Subparameter of AUTOARCH. String. Optional.
Example:
MAXDAYS FROM="07" TO="14"
FROM String. Mandatory.
TO String. Optional.
MAXRUNS Maximum number of job runs to retains the SYSDATA archive dataset for jobs
that ended NOTOK. Subparameter of AUTOARCH. String. Optional.
Example:
MAXRUNS FROM="100" TO="250"
FROM String. Mandatory.
TO String. Optional.
RERUNMEM Name of the JCL member to use when the job is automatically rerun. String. 1 - 8
characters. Optional.
Example:
RERUNMEM FROM="Mem45" TO="Mem7"
FROM String. Mandatory.
TO String. Optional.
RETEN_DAYS [MVS only] Number of days to retain the job in the History Jobs file. String.
Optional.
Example:
RETEN_DAYS FROM="5" TO="7"
FROM String. Mandatory.
TO String. Optional.

Chapter 3 Job utilities 97


updatedef

Table 24 Arguments file parameters for jobs (Part 9 of 14)


Parameter Description
RETEN_GEN [MVS only] Maximum number of generations of the job to keep in the History
Jobs file. String. Optional.
Example:
RETEN_GEN FROM="3" TO="4"
FROM String. Mandatory.
TO String. Optional.
TASK_CLASS Optional.
Example:
TASK_CLASS FROM="Distribution" TO="Decollation"
FROM String. Mandatory.
TO String. Optional.
PREV_DAY Optional.
Example:
PREV_DAY FROM="N" TO="Y"
FROM Mandatory. Valid values:
■ Y
■ N

TO Optional. Valid values:


■ Y
■ N

IND_CYCLIC Indicates whether the interval between further runs of a cyclic job is counted
from the start or the end of the previous job run. Optional.
Example:
IND_CYCLIC FROM="Y" TO="N"
FROM Mandatory. Valid values:
■ START
■ END

TO Optional. Valid values:


■ START
■ END

TAG_ Relationship (AND|OR) between the specified Schedule Tag criteria and the
RELATIONSHIP job’s own basic scheduling criteria. This parameter is relevant only for jobs in a
group scheduling table. Optional.
Example:
TAG_RELATIONSHIP FROM="AND" TO="OR"
FROM Mandatory. Valid values:
■ AND
■ OR

TO Optional. Valid values:


■ AND
■ OR

98 CONTROL-M/Enterprise Manager Utility Guide


updatedef

Table 24 Arguments file parameters for jobs (Part 10 of 14)


Parameter Description
SYSDB Determines whether one or multiple data sets are used to catalogue sysdata.
Optional.
Example:
SYSDB FROM="1" TO="0"
FROM Mandatory. Valid values:
■ 0 (Multiple-Default)
■ 1 (Single)

TO Optional. Valid values:


■ 0 (Multiple-Default)
■ 1 (Single)

PDSNAME Name of a partitioned dataset (PDS) to be checked for free space. String.
Optional.
Example:
PDSNAME FROM="Lib_3" TO="Lib_5"
FROM String. Mandatory.
TO String. Optional.
MINIMUM Minimum number of free partitioned dataset tracks required by the library
specified for the PDSNAME parameter. Integer. Optional.
Example:
MINIMUM FROM="5" TO="6"
FROM Integer. Mandatory.
TO Integer. Optional.
CATEGORY Name of a CONTROL-D report decollating mission category that must be
scheduled under CONTROL-D when the job is scheduled under CONTROL-M.
String. Optional.
Example:
CATEGORY FROM="*" TO="DAILY"
FROM String. Mandatory.
TO String. Optional.
PREVENTNC2 [MVS only] Performs dataset cleanup before the original job run. Optional.
Example:
PREVENTNC2 FROM="1" TO="0"
FROM Mandatory. Valid values:
■ 0 (Default)
■ 1

TO Optional. Valid values:


■ 0 (Default)
■ 1

Chapter 3 Job utilities 99


updatedef

Table 24 Arguments file parameters for jobs (Part 11 of 14)


Parameter Description
JAN, FEB, MAR, Months when the job can run. Optional. Not including a month is the same as
APR, MAY, JUN, including a month with value 0.
JUL, AUG, SEP, Example:
OCT, NOV, DEC JAN FROM="0" TO="1"
FROM Mandatory. Valid values:
■ 0 (Default)
■ 1

TO Optional. Valid values:


■ 0 (Default)
■ 1

OPTION Job output (sysout) handling options. Optional.


Example:
OPTION FROM="Copy" TO="Release"
FROM Mandatory. Valid values:
■ Release
■ Delete
■ Copy
■ Move
■ File
■ NewDest
■ ChangeClass

TO Optional. Valid values: Same as mandatory FROM.


PAR Certain OPTION values require that you supply additional information (such
as Release, NewDest). The PAR parameter holds that information as a string.
Optional.
Example:
PAR FROM="mem3log" TO="mem5log"
FROM String. Mandatory.
TO String. Optional.
FROM Limits the sysout handling operation to sysouts from the specified class.
Optional.
Example:
FROM FROM="1" TO="2"
FROM String. Mandatory.
TO String. Optional.
ADJUST_COND Indicates whether to ignore prerequisite conditions normally set by predecessor
jobs if the relevant predecessor jobs are not scheduled. This parameter is
relevant only for jobs in a group scheduling table. Optional.
Valid values:
■ 0 (Do not ignore. Default.)
■ 1 (Ignore relevant prerequisite conditions)
Example:
ADJUST_COND FROM="1" TO="0"
FROM String. Mandatory.
TO String. Optional.

100 CONTROL-M/Enterprise Manager Utility Guide


updatedef

Table 24 Arguments file parameters for jobs (Part 12 of 14)


Parameter Description
APPL_TYPE Type of external application (for example, SAP or Oracle) on which the external
application job runs. Mandatory for external application jobs.
Example:
APPL_TYPE FROM=”SAP” TO=”OracleApps”
FROM Mandatory. String. Up to 10 characters.
TO Optional. String.
APPL_VER Version of the external application (for example, SAP or Oracle) on which the
external application job runs. Mandatory for external application jobs.
Example:
APPL_VER FROM=”4.5” TO=”4.6”
FROM Mandatory. String. Up to 10 characters.
TO Optional. String.
APPL_FORM Predefined set of external application parameters that are displayed in the Job
Editing form. Mandatory for external application jobs.
Example:
APPL_FORM FROM=”Default SAP 4.6” TO=”Default SAP 4.5”
FROM Mandatory. String. Up to 30 characters.
TO Optional. String.
CM_VER Version of external application (for example, SAP or Oracle) Control Module
(CM) that is installed in the CONTROL-M installation. Mandatory for external
application jobs.
Example:
CM_VER FROM=”6.1.00” TO=”6.1.01”
FROM Mandatory. String. Up to 10 characters.
TO Optional. String.
MULTY_AGENT When selected, broadcasts job submission details to all Agents in a specified
Node Group. Optional.
Example:
MULTY_AGENT FROM=”N” TO=”Y”
FROM Mandatory. Valid values:
■ Y – run as multi-agent job.
■ N – do not run as multi-agent job. Default.

TO Optional. String.
ACTIVE_FROM [OS only] Start of a period of time during which the job or group scheduling
table can be ordered. Optional. Example:
ACTIVE_FROM FROM=”20040315” TO=”20040601”
FROM Mandatory. Date Format: YYYYMMDD
TO Optional. String.

Chapter 3 Job utilities 101


updatedef

Table 24 Arguments file parameters for jobs (Part 13 of 14)


Parameter Description
ACTIVE_TILL [MVS only] End of a period of time during which the job or group scheduling
table can be ordered. Optional.
Example:
ACTIVE_TILL FROM=”20040315” TO=”20040601”
FROM Mandatory. Date Format: YYYYMMDD
TO Optional. String.
TIMEZONE Global time zone used to calculate the interval for time-related conditions.
Optional.
Example:
TIMEZONE FROM=”EST” TO=”GMT”
FROM Mandatory. String.
Default: GMT
TO Optional. String.
JOBS_IN_GROUP Number of jobs in the group scheduling table. Optional.
Example:
JOBS_IN_GROUP FROM="4" TO="10"
FROM String. Mandatory.
TO String. Optional.
CREATION_USER Name of the user that created the job. Optional.
Example:
CREATION_USER FROM="emuser" TO="em1"
FROM String. Mandatory.
TO String. Optional.
CREATION_DATE Date that the job was created. Optional.
Example:
CREATION_DATE FROM="1212" TO="2012"
FROM String. Mandatory.
TO String. Optional.
CREATION_TIME Time that the job was created. Optional.
Example:
CREATION_TIME FROM="1230" TO="1430"
FROM String. Mandatory.
TO String. Optional.
CHANGE_USERID Name of the user that last modified the job. Optional.
Example:
CHANGE_USERID FROM="emuser" TO="emacct"
FROM String. Mandatory.
TO String. Optional.

102 CONTROL-M/Enterprise Manager Utility Guide


updatedef

Table 24 Arguments file parameters for jobs (Part 14 of 14)


Parameter Description
CHANGE_DATE Date that the job was last modified. Optional.
Example:
CHANGE_DATE FROM="1204" TO="1304"
FROM String. Mandatory.
TO String. Optional.
CHANGE_TIME Time that the job was last modified. Optional.
Example:
CHANGE_TIME FROM="1650" TO="1700"
FROM String. Mandatory.
TO String. Optional.

Example 1: Modify GROUP parameter

In the TEST data center, the group name of jobs with GROUP UnixJobs is changed to
GROUP TandemJobs.

?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE UPDATE SYSTEM "update.dtd">
<UPDATE>
<GROUP_SCHED>
<DATACENTER FROM="TEST"/>
<GROUP FROM="UnixJobs" TO="TandemJobs"/>
</GROUP_SCHED>
</UPDATE>

Example 2: Modify Scheduling Table Name parameter

In the TEST data center, for jobs with TABLE_ID 12202, the scheduling table name is
changed from Tbl_1 to Tbl_2.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE UPDATE SYSTEM "update.dtd">
<UPDATE>
<SCHED_TABLE>
<DATACENTER FROM="TEST"/>
<TABLE_ID FROM="12202"/>
<TABLE_NAME FROM="Tbl_1" TO="Tbl_2"/>
</SCHED_TABLE>
</UPDATE>

Chapter 3 Job utilities 103


updatedef

Example 3: Modify the Job name of a job

<UPDATE>
<JOB>
<TABLE_NAME FROM="SGMPM1"/>
<!-- <TABLE_DSN FROM=""/> -->
<DATACENTER FROM="snow"/>
<JOBNAME FROM="cnn*" TO="bbc*"/>
<!-- <MEMNAME FROM="Job2"/>-->
<!-- <GROUP FROM=""/> -->
<!-- <APPLICATION FROM=""/> -->
<!-- <TASKTYPE FROM=""/> -->
<!-- <AUTHOR FROM=""/> -->
<!-- <MEMLIB FROM=""/> -->
<!-- <CMDLINE FROM="*end" TO="THE END *"/>-->
<!-- <NODEID FROM=""/> -->
<!-- <OWNER FROM=""/> -->
<!-- <MAXRERUN FROM=""/> -->
<!-- <TIMEFROM FROM=""/> -->
<!-- <TIMETO FROM=""/> -->
<!-- <DUE_OUT FROM=""/> -->
<!-- <PRIORITY FROM=""/> -->
<!-- <CRITICAL FROM=""/> -->
<!-- <CYCLIC FROM=""/> -->
<!-- <CONFIRM FROM=""/> -->
<!-- <AUTOARCH FROM=""/> -->
<!-- <INTERVAL FROM=""/> -->
<!-- <OVERLIB FROM=""/> -->
<!-- <MAXWAIT FROM=""/> -->
<!-- <DESCRIPTION FROM=""/> -->
<!-- <DOCMEM FROM="docmem"/> -->
<!-- <DOCLIB FROM="doclib"/>-->
<!-- <DAYS FROM=""/> -->
<!-- <DAYS_AND_OR FROM=""/> -->
<!-- <WEEKDAYS FROM=""/> -->
<!-- <DATE FROM=""/> -->
<!-- <DAYSCAL FROM=""/> -->
<!-- <WEEKSCAL FROM=""/> -->
<!-- <CONFCAL FROM=""/> -->
<!-- <RETRO FROM=""/> -->
<!-- <SHIFT FROM=""/> -->
<!-- <SHIFTNUM FROM=""/> -->
<!-- <MAXDAYS FROM=""/> -->
<!-- <MAXRUNS FROM=""/> -->
<!-- <RERUNMEM FROM=""/> -->
<!-- <RETEN_DAYS FROM=""/> -->
<!-- <RETEN_GEN FROM=""/> -->
<!-- <TASK_CLASS FROM=""/> -->
<!-- <PREV_DAY FROM=""/> -->
<!-- <IND_CYCLIC FROM=""/> -->
<!-- <TAG_RELATIONSHIP FROM=""/> -->
<!-- <SYSDB FROM=""/> -->
<!-- <PDSNAME FROM=""/> -->
<!-- <MINIMUM FROM=""/> -->
<!-- <CATEGORY FROM=""/> -->
<!-- <PREVENTNCT2 FROM=""/> -->
<!-- <JAN FROM=""/> -->
<!-- <FEB FROM=""/> -->
<!-- <MAR FROM=""/> -->
<!-- <APR FROM=""/> -->
<!-- <MAY FROM=""/> -->

104 CONTROL-M/Enterprise Manager Utility Guide


updatedef

<!-- <JUN FROM=""/> -->


<!-- <JUL FROM=""/> -->
<!-- <AUG FROM=""/> -->
<!-- <SEP FROM=""/> -->
<!-- <OCT FROM=""/> -->
<!-- <NOV FROM=""/> -->
<!-- <DEC FROM=""/> -->
<!-- <OPTION FROM=""/> -->
<!-- <PAR FROM=""/> -->
<!-- <FROM FROM=""/> -->
<!-- <ADJUST_COND FROM=""/> -->
<!-- <JOBS_IN_GROUP FROM=""/> -->
<!-- <LARGE_SIZE FROM=""/> -->
<!-- <CREATION_USER FROM=""/> -->
<!-- <CREATION_DATE FROM=""/> -->
<!-- <CREATION_TIME FROM=""/> -->
<!-- <CHANGE_USERID FROM=""/> -->
<!-- <CHANGE_DATE FROM=""/> -->
<!-- <CHANGE_TIME FROM=""/> -->
<!-- <JOB_RELEASE FROM=""/> -->
<!-- <JOB_VERSION FROM=""/> -->
<!-- <TABLE_USERDAILY FROM=""/> -->
<!-- <SCHEDULING_ENVIRONMENT FROM=""/> -->
<!-- <SYSTEM_AFFINITY FROM=""/> -->
<!-- <REQUEST_NJE_NODE FROM=""/> -->
<!-- <APPL_TYPE FROM=""/> -->
<!-- <APPL_VER FROM=""/> -->
<!-- <APPL_FORM FROM=""/> -->
<!-- <CM_VER FROM=""/> -->
<!-- <MULTY_AGENT FROM=""/> -->
<!-- <ACTIVE_FROM FROM=""/> -->
<!-- <ACTIVE_TILL FROM=""/> -->
<!-- <TIMEZONE FROM=""/> -->
</JOB>
</UPDATE>

Chapter 3 Job utilities 105


updatedef

106 CONTROL-M/Enterprise Manager Utility Guide


Chapter

4
4 Calendar utilities
The utilities described in this chapter are used to create and modify calendar
definitions.

Many of the tasks performed by the calendar utilities can also be performed using the
Job and Group Editing forms in CONTROL-M/EM and CONTROL-M/Desktop and
the Calendar Manager in CONTROL-M/Desktop. However, by including a utility
command in the command line of a job processing definition, you can run the utility
at a predetermined time or under a predetermined set of conditions without being
present.

The utilities described in this chapter are listed in Table 25.

Table 25 Calendar utilities


Utility Description
defcal Imports a calendar directly into the CONTROL-M/EM database from a
text file. (See page 108.)
copydefcal Copies calendar definitions within the database. (See page 113.)
exportdefcal Exports calendar definitions to a text file. (See page 118.)

NOTE
The cli utility can upload and download calendars. It is described in Chapter 2, “Command
Line Interface utility (cli).”

Chapter 4 Calendar utilities 107


defcal

defcal
The defcal utility imports a calendar definition into the CONTROL-M/EM database.
defcal reads calendar definitions directly from a plain text input file (in XML format)
instead of reading them from the command line.

To invoke the defcal utility:

1 Log in as a CONTROL-M/EM user.

2 Open a command prompt window (Microsoft Windows).

3 Enter either of the following commands:

defcal [-u user [-p password] | -pf password_file]


-s gui_server_name -src src_file_name

- or -
defcal [-USERNAME user [-PASSWORD password] | -PASSWORD_FILE
password_file] -HOST gui_server_name -SRC_FILE src_file_name

4 Press Enter.

The defcal input file is checked and processed. If there are any errors in the file, a
message is displayed specifying the lines with the errors.

Parameters
The parameters of the defcal utility are described in Table 26.

Table 26 defcal parameters


Parameter Description
user CONTROL-M/EM user name.
password The CONTROL-M/EM user password.
password_file Flat file containing an unencrypted user name and password on separate
lines in the format:
user=username
password=password
Note: If both -u and -pf are specified, an error message is generated. If
only -u is specified, an online prompt is issued for the password. If neither
is specified, a prompt is issued for the database user name and password.

108 CONTROL-M/Enterprise Manager Utility Guide


defcal

Table 26 defcal parameters


Parameter Description
gui_server_ CONTROL-M/EM GUI server logical name, host name, or IP address.
name Note: If multiple GUI servers exist, set this parameter to the logical name
of the relevant GUI server.
src_file_name The path and name of the XML file containing the defcal specifications.

defcal input file


The calendars that you create for use with the defcal utility are written in XML
format and saved in a text file. When this file is invoked, its contents are passed to the
CONTROL-M/EM database.

Instructions for creating an XML format input file are in Appendix A, “XML File
Preparation.” The parameters of the defcal input file (SRC_file_name) are in Table 27
on page 109.

The following rules apply to the defcal utility input file:


■ More than one calendar can be specified in a defcal file.

■ The XML file is case-sensitive.

■ All parameter values (such as strings or digits) must be enclosed in quotation


marks (for example, JOBNAME="Job1").
■ The definition for a single calendar can cover a period of one or more years.

Table 27 defcal input file parameters (Part 1 of 2)


Parameter Description
The first two lines of the XML request file for this API request contain information that specifies the version
of XML, the text encoding format being used, and the location of the .dtd file.
These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE DEFCAL SYSTEM "defcal.dtd"
DEFCAL Indicates to CONTROL-M/EM that the defcal utility is being initiated. Calendar
definitions are placed between the opening and closing DEFCAL tags. One or more
calendars can be specified.
CALENDAR Indicates the opening and closing tags of a single calendar definition. The parameters of
the job are listed between the tags. Example:
CALENDAR DATACENTER="ECS5A" NAME="AcctJob1"
TYPE="Relative"></CALENDAR
DATACENTER Name of the CONTROL-M installation to which the calendar definition
belongs. String. Mandatory.
NAME Name of the calendar. String Mandatory.
TYPE Calendar type. Mandatory. Valid values:
■ Regular
■ Periodic
■ Relative

Chapter 4 Calendar utilities 109


defcal

Table 27 defcal input file parameters (Part 2 of 2)


Parameter Description
YEAR Year-specific definitions in the calendar. Mandatory.
Example:
YEAR NAME="2004"
DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYNNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
NYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNN
YYYYYYYYYYYYYYYYYYYYY" DESCRIPTION="This is the Accounting Jobs calendar for
2004."
NAME Year for which the calendar definition applies. String. Mandatory.
The year during which the calendar is active. Only one year can be
entered for this attribute, but more than one YEAR parameters can be
included in a calendar definition.
The value of this attribute is expressed as YYYY (for example, 2004).
DAYS Days on which the job is ordered. String. Mandatory.Valid values:
For a Relative calendar:
■ Y
■ N
■ +
■ -
For a Regular calendar:
■ Y
■ N
For a Periodic calendar:
any character other than Y, N, +, or -.
Note: Each Y and N represents a single day of the year. The value of the
DAYS parameter is 365 characters long (366 for a leap year). The first
letter of the DAYS value is January first. The last letter is December 31.
DESCRIPTION Text description of the calendar. String. Optional. For Regular and
periodic calendars, only.

110 CONTROL-M/Enterprise Manager Utility Guide


defcal

Example 1: Import a regular calendar

Regular calendar AcctCal3 is imported into the ECS5NY data center.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE DEFCAL SYSTEM "defcal.dtd">
<DEFCAL>
<CALENDAR
DATACENTER="ECS5NY"
NAME="AcctCal3"
TYPE="Regular">
<YEAR
NAME="2004"
DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNY
YYYYYYYYYYYYYYYYYYYY"
DESCRIPTION="Calendar for 2004."/>
</CALENDAR>
</DEFCAL>

Chapter 4 Calendar utilities 111


defcal

Example 2: Import two calendars into different data centers

Two calendars are imported, each into a different data center, with a single defcal
input file.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE DEFCAL SYSTEM "defcal.dtd">
<DEFCAL>
<CALENDAR
DATACENTER="ECS5NY"
NAME="AcctCal3"
TYPE="Regular">
<YEAR
NAME="2004"
DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNY
YYYYYYYYYYYYYYYYYYYY"
DESCRIPTION="Calendar for 200444"/>
<CALENDAR
DATACENTER="ECS2LA"
NAME="HRCal3"
TYPE="Regular">
<YEAR
NAME="2004"
DAYS="YYYYYYYYYYYYYYYYNNNYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYNNNNNYYYYYYYYYYYYYYYYNNNYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNY
YYYYYYYYYYYYYYYYYNNN"
DESCRIPTION="Calendar for 2004."/>
</CALENDAR>
</DEFCAL>

112 CONTROL-M/Enterprise Manager Utility Guide


copydefcal

copydefcal
The copydefcal utility creates a new calendar definition in the CONTROL-M/EM
database identical to an existing calendar definition. Calendars can be copied and
saved under different names in the same data center. Calendars in one data center can
be copied to a different data center and saved under the same or different names.

Multiple calendars can be selected and copied using the * wildcard character. For an
explanation of how wildcards function in XML-based utilities, see “Wildcards” on
page 178.

When copydefcal is invoked, a file of arguments that you created is processed. This
arguments file contains statements that specify an existing calendar or group of
calendars. The specified calendars are exported to an output file. copydefcal reads
arguments directly from a plain text arguments file (in XML format) instead of
reading them from the command line.

To invoke the copydefcal utility:

1 Log on as a CONTROL-M/EM user.

2 Open a command prompt window (Windows users, only). You do not need to be
in the CONTROL-M/EM directory.

3 Enter either of the following commands:

copydefcal [-u user [-p password] | -pf password_file]


-s gui_server_name -arg arg_file_name

- or -
copydefcal [-USERNAME user [-PASSWORD password] | -PASSWORD_FILE
password_file] -HOST gui_server_name -ARG_FILE arg_file_name

4 Press Enter. The copydefcal arguments file is checked and processed. If there are
any errors in the file, a message is displayed specifying the lines with the errors.

Chapter 4 Calendar utilities 113


copydefcal

Parameters

Table 28 copydefcal parameters


Parameter Description
user CONTROL-M/EM user name.
password The CONTROL-M/EM user password.
password_ Flat file containing an unencrypted username and password on separate lines in
file the format:
user=username
password=password
Note: If both -u and -pf are specified, an error message is generated. If only -u is
specified, an online prompt is issued for the password. If neither is specified, a
prompt is issued for the database user name and password.
gui_server_ CONTROL-M/EM GUI server logical name, host name, or IP address.
name Note: If multiple GUI servers exist, set this parameter to the logical name of the
relevant GUI server.
arg_file_ Path and name of the arguments file containing the copydefcal specifications.
name Instructions for preparing this file are in Appendix A, “XML File Preparation.”

copydefcal arguments file


Arguments are used as selection criteria to determine which calendars are exported.
Arguments are written to the copydefcal argument file. The arguments files created
for use with the copydefcal utility are written in XML format and saved in a text file.
The format in which this file must be written is described on the following pages.

When this file is invoked, calendar definitions are exported from the
CONTROL-M/EM database.

The following rules apply to the copydefcal arguments file:

■ More than one calendar can be specified in an arguments file.


■ The arguments file is case-sensitive.
■ All parameter values (such as strings or digits) must be enclosed in quotation
marks (for example, JOBNAME="Job1").
■ Only one COPYCAL parameter can be used in an arguments file.

114 CONTROL-M/Enterprise Manager Utility Guide


copydefcal

Using FROM and TO in the copydefcal input file:

■ If you do choose to specify a parameter, the FROM subparameter is mandatory,


and the TO subparameter is optional.
■ When a FROM value is specified without a TO value, it is used as a filter criterion.
■ When a TO value is included, it indicates the new value with which the parameter
is updated.
■ Multiple values can be specified for TO and FROM by using the * wildcard
character. For an explanation of how wildcards function in the XML-based utilities,
see “Wildcards” on page 178.
■ If any FROM value contains *, and the corresponding TO value contains *, the * in
the TO value expresses the same information the * in the FROM value.
■ The TO attribute of the DATACENTER parameter must be used to import the
copied calendar into a different data center if the copy has the same name as the
original calendar (the TO attribute is not used with the CALENDAR parameter).
Otherwise, the calendar copy overwrites the original in the same data center.

Chapter 4 Calendar utilities 115


copydefcal

Table 29 copydefcal arguments file parameters


Parameter Description
The first two lines of the XML request file for this API request contain information that specifies the version
of XML, the text encoding format being used, and the location of the .dtd file.
These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE COPYCAL SYSTEM "copycal.dtd"
COPYCAL These tags indicate the start and end of the COPYCAL argument. Only criteria that
are located between the tags are considered to be part of the argument.
DATACENTER CONTROL-M installation to which the calendar definition belongs.
Note: The COPYCAL element must contain only one DATACENTER parameter.
String.
Example:
DATACENTER FROM=”ECS5NYC” TO=”ECS7NYC”
FROM.Data center in which the source calendar is located. String. Mandatory.
TO. Data center in which a calendar can be created. String. Optional.
CALENDAR Name of the calendar.
Note: The COPYCAL element must contain only one CALENDAR parameter.
Example:
CALENDAR FROM=”Cal1” TO=”Cal1_COPY”
FROM. Name of the calendar from which a copy is made. String. Mandatory.
TO. Name of the calendar copy. The copy retains the name of the original calendar
if this attribute is not used. String. Optional.

Following are sample input files used with the copydefcal utility:

Example 1: Create and import a calendar

Creates a copy of calendar CAL_3 in the ECS10LA data center.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE COPYCAL SYSTEM "copycal.dtd">
<COPYCAL>
<DATACENTER FROM="ECS5NYC" TO="ECS10LA"/>
<CALENDAR FROM="CAL_3"/>
</COPYCAL>

116 CONTROL-M/Enterprise Manager Utility Guide


copydefcal

Example 2: Copy multiple calendars from the same data center

All calendars in the ECS5NYC data center with names beginning with the letter A are
copied to the ECS7NYC data center. The new calendar names are calendarname_COPY
(for example, the copy of the Alljobs calendar is named Alljobs_COPY).

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE COPYCAL SYSTEM "copycal.dtd">
<COPYCAL>
<DATACENTER FROM="ECS5NYC" TO="ECS7NYC"/>
<CALENDAR FROM="A*" TO="A*_COPY"/>
</COPYCAL>

Example 3: Copy a calendar and rename the copy

The calendar named CAL_NOV in the ECS5NYC data center is copied. The name of
the copy is CAL_NOV_REVISED.

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE COPYCAL SYSTEM "copycal.dtd">
<COPYCAL>
<DATACENTER FROM="ECS5NYC"/>
<CALENDAR FROM="CAL_NOV" TO="CAL_NOV_REVISED"/>
</COPYCAL>

Chapter 4 Calendar utilities 117


exportdefcal

exportdefcal
The exportdefcal utility exports calendar definitions in the CONTROL-M/EM
database to an output file for use as input to other utilities.

When the exportdefcal utility is invoked, an arguments file that you prepare is
processed. This arguments file contains statements that specify an existing calendar
or group of calendars. The calendars that you specified in the arguments file are
exported to an output file. You can modify the exported calendars in the output file
and re-import them into the CONTROL-M/EM database using the defcal utility.

NOTE
Output files from export utilities (such as exportdefcal) can be used as input files with the
import utilities (such as defcal).

exportdefcal reads arguments directly from a plain text arguments file (in XML
format) instead of reading them from the command line.

To invoke the exportdefcal utility:

1 Log on as an CONTROL-M/EM user.

2 Open a command prompt window (Windows users, only). You do not need to be
in the CONTROL-M/EM directory.

3 Enter either of the following commands:

exportdefcal [-u user [-p password] | -pf password_file]


-s gui_server_name -arg arg_file_name

- or -
exportdefcal [-USERNAME user [-PASSWORD password] | -PASSWORD_FILE
password_file] -HOST gui_server_name -ARG_FILE arg_file_name

Parameters of the exportdefcal utility are described in Table 30 on page 119.

4 Press Enter.

The exportdefcal arguments file is checked and processed. If there are any errors
in the file, a message is displayed specifying the lines with the errors.

The exported calendar definitions are saved to an output file, the name and
location of which you specified in parameter out_file_name.

118 CONTROL-M/Enterprise Manager Utility Guide


exportdefcal

Parameters
The parameters of the exportdefcal utility are described in Table 30 on page 119.

Table 30 exportdefcal parameters


Parameter Description
user CONTROL-M/EM user name.
password The CONTROL-M/EM user password.
password_file Flat file containing an unencrypted username and password on separate
lines in the format:
user=username
password=password
Note: If both -u and -pf are specified, an error message is generated. If only
-u is specified, an online prompt is issued for the password. If neither is
specified, a prompt is issued for the database user name and password.
gui_server_ CONTROL-M/EM GUI server logical name, host name, or IP address.
name Note: If multiple GUI servers exist, set this parameter to the logical name of
the relevant GUI server.
arg_file_name Path and name of the arguments file containing exportdefcal specifications.
Instructions for making this file are in Appendix A, “XML File Preparation.”
out_file_name Path and name of the file containing the specification of the exported job.

exportdefcal arguments file


Arguments are used as a selection criteria to determine which calendars to export.
Arguments are written to the exportdefcal argument file. The arguments files that
you create with the exportdefcal utility are written in XML format and saved in a text
file. The format in which this file must be written is described on the following pages.

When this file is invoked, calendar definitions are exported from the
CONTROL-M/EM database. For instructions for creating arguments files, see
Appendix A, “XML File Preparation.”

The following rules apply to the exportdefcal arguments file:


■ More than one calendar can be specified in an exportdefcal file.

■ The arguments file is case-sensitive.

■ All parameter values (such as strings or digits) must be enclosed in quotation


marks (for example, JOBNAME="Job1").
■ More than one PARAM parameter can be used in a TERM statement.

■ The relationship between PARAM parameters in a TERM statement is AND. The


relationship between TERM statements is OR.

Chapter 4 Calendar utilities 119


exportdefcal

Table 31 exportdefcal arguments file parameters


Parameter Description
The first two lines of the XML request file for this API request contain information that specifies the version of
XML, the text encoding format being used, and the location of the .dtd file.
These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE TERMS SYSTEM "terms.dtd"
TERMS These tags indicate the start and end of the TERMS file. Only criteria that are
located between the tags are considered to be part of the argument.
TERM The TERM tags indicate the start and the end of a group of selection criteria used to
specify a calendar or calendars that are to be exported. Only PARAM tags that are
located between the TERM tags are considered to be part of the TERM argument.
REL Optional. Relationship between terms. Valid values:
■ AND
■ OR

PARAM The selection criteria parameter used to determine those calendars that are to be
exported. More than one PARAM can be specified. Mandatory. Example:
PARAM NAME="DATACENTER" OP="EQ" VALUE="Center1"
NAME String. Mandatory. The parameter name of any calendar parameter.
Valid values:
■ DATACENTER
■ CALENDAR

OP String. Mandatory. Describes the relationship between the NAME and


the VALUE parameters of the TERM. Valid values:
■ EQ
■ NEQ
■ NOTIN
■ LIKE

VALUE String. Mandatory. Value of the parameter specified in the NAME


field.
■ If the value of NAME is DATACENTER, enter the name of the
CONTROL-M installation for VALUE.
■ If the value of NAME is CALENDAR, enter a calendar name.

Following are sample arguments files used with the exportdefcal utility:

Example: Export all calendars in the data center named Cal1

The output file contains all calendars in data center Data1 that are named Cal1.
<?xml version=’1.0’ encoding=’UTF-8’?>
<!DOCTYPE TERMS SYSTEM "terms.dtd">
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="Data1"/>
<PARAM NAME="CALENDAR" OP="EQ" VALUE="CAL1"/>
</TERM>
</TERMS>

120 CONTROL-M/Enterprise Manager Utility Guide


Chapter

5
5 Scheduling table utilities
The utilities described in this chapter are used to create and modify scheduling table
and group scheduling table definitions.

You can use the Scheduling Table Manager and Group Editing form in
CONTROL-M/Desktop and CONTROL-M/Enterprise Manager (CONTROL-M/EM)
and the CONTROL-M utilities ctmdefine and ctmcreate for the same tasks. However,
if you perform these tasks by including a utility command in the command line of a
job processing definition, you can run the utility at a predetermined time or under a
predetermined set of conditions without being present. The utilities described in this
chapter are listed in Table 32.

Table 32 Table utilities


Utility Description
deftable Imports scheduling table and group scheduling table definitions
from a user-defined file. (See page 122.)
exportdeftable Exports scheduling table and group scheduling table definitions to a
text file. (See page 135.)

Two other utilities, described in other chapters in this book, are used with scheduling
tables and group scheduling tables:

■ The updatedef utility enables you to update (modify) specific parameter values in
the following definitions:
— scheduling table definitions
— group scheduling tables
— one or more job processing definitions in the CONTROL-M/EM database.
updatedef is described in “updatedef” on page 82.

■ The cli utility uploads, downloads, orders, and forces scheduling tables and group
scheduling tables. It is described in Chapter 2, “Command Line Interface utility
(cli).”

Chapter 5 Scheduling table utilities 121


deftable

deftable
The deftable utility imports scheduling tables and group scheduling tables into the
CONTROL-M/EM database.

When deftable is invoked, a file of arguments that you have created is processed. This
input file contains statements that specify:

■ an existing scheduling table or set of scheduling tables


■ An existing group scheduling table or set of group scheduling tables.

The specified tables are imported into the CONTROL-M/EM database.

If the tables do not exist in the CONTROL-M/EM database, the utility creates them. If
the tables do exist, a message is issued indicating that the tables already exist (unless
the /o switch is specified, in which case the tables are overwritten – the /o switch is
described below).

deftable reads scheduling table and group scheduling table definitions directly from
a plain text arguments file (in XML format) instead of reading them from the
command line.

A single deftable input file can contain specifications for both scheduling tables and
group scheduling tables.

To invoke the deftable utility:

1 Log in as a CONTROL-M/EM user.

2 Open a command prompt window (Windows users). You do not need to be in the
CONTROL-M/EM directory.

3 Enter either of the following commands:

deftable [-u user [-p password] | -pf password_file]


-s gui_server_name -src src_file_name [/a] [/o]

- or -
deftable [-USERNAME user [-PASSWORD password] | -PASSWORD_FILE
password_file] -HOST gui_server_name -SRC_FILE src_file_name [/a] [/o]

Parameters of the deftable command are described in Table 33 on page 123.

4 Press Enter. The deftable input file is checked and processed. If there are any errors
in the file, a message is displayed specifying the lines with the errors.

122 CONTROL-M/Enterprise Manager Utility Guide


deftable

Parameters

Table 33 deftable parameters


Parameter Description
user CONTROL-M/EM user name.
password The CONTROL-M/EM user password.
password_file Flat file containing an unencrypted user name and password on separate
lines in the format:
user=username
password=password
Note: If both -u and -pf are specified, an error message is generated. If only
-u is specified, an online prompt is issued for the password. If neither is
specified, a prompt is issued for the database user name and password.
gui_server_ CONTROL-M/EM GUI server logical name, host name, or IP address.
name Note: If multiple GUI servers exist, set this parameter to the logical name of
the relevant GUI server.
src_file_name Path and name of the file containing the specifications for the table that you
are importing. Instructions for preparing this file are in Appendix A, “XML
File Preparation.”

Optional switches for the deftable utility are described in Table 34.

Table 34 deftable switches


Switch Description
/a Accept all. The /a switch directs the utility to automatically reset the Author
parameter to the current CONTROL-M/EM user when these two values do not
match. If not specified, the utility skips (i.e., does not process) job definitions whose
Author does not match the currently logged in user.
Note: The /a switch has no effect on Administrator users and is relevant only when
system parameter AuthorSecurity is set to 2 or 3.
/o Overwrite. The /o switch directs the utility to overwrite any existing tables.

deftable input file


Input file src_file_name contains the definition of a scheduling table. The file is
written in XML format and saved in a text file. The format in which this file must be
written is described on the following pages.

When this file is invoked, scheduling table and/or group scheduling table definitions
are imported to the CONTROL-M/EM database. For instructions for creating input
files, see Appendix A, “XML File Preparation.”

Chapter 5 Scheduling table utilities 123


deftable

The following rules apply to the deftable input file:


■ Only one group scheduling table can be included in a scheduling table. However,
multiple scheduling tables can be included in a single input file. Each of these
scheduling tables can contain one group scheduling table.
■ Multiple group scheduling tables can be included in a file that does not contain
any scheduling tables.
■ More than one job can be specified in either type of table.

Table 35 deftable input file parameters for scheduling tables (Part 1 of 2)


Parameter Description
The first two lines of the XML request file for this API request contain information that specifies the version
of XML, the text encoding format being used, and the location of the .dtd file.
These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE DEFTABLE SYSTEM "deftable.dtd"
DEFTABLE Indicates to CONTROL-M/EM the beginning and end of the deftable utility.
Scheduling table definitions are placed between the opening and closing
DEFTABLE tags. One or more jobs can be specified. Each individual job is
enclosed by the TABLE</TABLE tags
SCHED_TABLE Indicate the opening and closing tags of a single scheduling table definition. The
parameters of the table are listed between the tags. In the case of the scheduling
table, the table parameters consist of parameters that describe the table directly
and a list of the jobs that are included in the table. In turn, each of the jobs that is
listed includes all of its own descriptive parameters.
TABLE_NAME Name of the scheduling table to which the job belongs. String. Mandatory.
Note: At least one of the following scheduling table parameters must be
included in the input file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

TABLE_DSN Name of the library that contains the scheduling table. [For MVS jobs, only.]
String. Optional.
Note: At least one of the following scheduling table parameters must be
included in the input file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

DATACENTER Name of the CONTROL-M installation to which the scheduling table belongs.
String. Mandatory.
Note: At least one of the following scheduling table parameters must be
included in the input file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

TABLE_USERDAILY For internal use. Do not include this parameter in your deftable input file.
USED_BY For internal use. Do not include this parameter in your deftable input file.
USED_BY_CODE For internal use. Do not include this parameter in your deftable input file.
MODIFIED For internal use. Do not include this parameter in your deftable input file.

124 CONTROL-M/Enterprise Manager Utility Guide


deftable

Table 35 deftable input file parameters for scheduling tables (Part 2 of 2)


Parameter Description
LAST_UPLOAD Date of the last table upload. String. Optional.
CHECKSUM For internal use. Do not include this parameter in your deftable input file.
TABLE_ID For internal use. Do not include this parameter in your deftable input file.
REAL_TABLEID For internal use. Do not include this parameter in your deftable input file.
JOB Opening and closing tags of a single job definition. Parameters of the job are
listed between the tags. For a complete listing of defjob parameters, see
“defjob” on page 24.

Table 36 deftable input file parameters for group scheduling tables (Part 1 of 7)
Parameter Description
The first two lines of the XML request file for this API request contain information that specifies the version of
XML, the text encoding format being used, and the location of the .dtd file.
These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE DEFTABLE SYSTEM "deftable.dtd"
DEFTABLE Indicates the beginning and end of the deftable utility. Scheduling table definitions
are placed between the opening and closing DEFTABLE tags. One or more jobs can
be specified. Each individual job is enclosed by the TABLE</TABLE tags
SCHED_GROUP Opening and closing tags of a group scheduling table definition.
TABLE_NAME Name of the group scheduling table to which the job belongs. String. Mandatory.
Note: At least one of the following scheduling table parameters must be included in
the input file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

GROUP Name of the group to which the jobs in the group scheduling table are assigned.
String. Mandatory.
DATACENTER Name of the CONTROL-M installation to which the group scheduling table belongs.
String. Mandatory.
Note: At least one of the following scheduling table parameters must be included in
the input file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

TABLE_DSN Library for the table. String. Optional.


Note: At least one of the following scheduling table parameters must be included in
the input file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

TABLE_USERDAILY String. Optional.


USED_BY For internal use. Do not include this parameter in your deftable input file.
USED_BY_CODE For internal use. Do not include this parameter in your deftable input file.

Chapter 5 Scheduling table utilities 125


deftable

Table 36 deftable input file parameters for group scheduling tables (Part 2 of 7)
Parameter Description
MODIFIED For internal use. Do not include this parameter in your deftable input file.
LAST_UPLOAD Date of the last table upload. String. Optional.
CHECKSUM For internal use. Do not include this parameter in your deftable input file.
TABLE_ID For internal use. Do not include this parameter in your deftable input file.
REAL_TABLEID For internal use. Do not include this parameter in your deftable input file.
JOBNAME Name of the job processing definition.String. Optional.
MEMNAME Name of the file that contains the job script. String. Optional.
APPLICATION Name of the application to which the group scheduling table belongs. Used as a
descriptive name for related groups of group scheduling tables. String. Mandatory.
OWNER Owner (user ID) associated with the group scheduling table. This parameter is used
by the CONTROL-M/Server security mechanism. String. Optional.
ADJUST_COND Indicates whether to ignore prerequisite conditions normally set by predecessor jobs
if the relevant predecessor jobs are not scheduled. This parameter is relevant only
for jobs in a group scheduling table. String. Optional.
CONFIRM Indicates that the group scheduling table must be manually confirmed by the
CONTROL-M/EM user before it runs. Valid values:
■ 0 (No confirmation. Default.)
■ 1 (Requires confirmation.)

PRIORITY Indicates CONTROL-M group scheduling table priority. String. Optional.


TIMEFROM Indicates the earliest time for submitting the group scheduling table. String.
Optional.
TIMETO Indicates the latest time for submitting the group scheduling table. String. Optional.
DUE_OUT Time that the jobs in the group scheduling table are expected to finish. String.
Optional.
DOCMEM Name of the file containing group scheduling table documentation. String. Optional.
DOCLIB Name of the DOCMEM library. String. Optional.
DESCRIPTION Brief text description of the group scheduling table. String. Optional.
AUTHOR CONTROL-M/EM user who defined the group scheduling table. String. Mandatory.
Note: This argument is used by the CONTROL-M security mechanism and, under
certain circumstances, cannot be modified. For more information, see the Security
chapter and the description of the AuthorSecurity system parameter in the
CONTROL-M/Enterprise Manager Administrator Guide.
CREATION_USER Name of the user who created the group scheduling table. String. Optional.
CREATION_DATE Date on which the group scheduling table was created. String. Optional.
CREATION_TIME Time at which the group scheduling table was created. String. Optional.
CHANGE_USERID Name of the user who last modified the group scheduling table. String. Optional.
CHANGE_DATE Date on which the group scheduling table was last modified. String. Optional.
CHANGE_TIME Time at which the group scheduling table was last modified. String. Optional.

126 CONTROL-M/Enterprise Manager Utility Guide


deftable

Table 36 deftable input file parameters for group scheduling tables (Part 3 of 7)
Parameter Description
MULTY_AGENT If set to Y, job submission details are broadcasted to all Agents within an Application
Group. The Agent with available resources runs the jobs in the group scheduling
table. Optional. Valid values:
■ Y - run as a multi-agent job
■ N - do not run as a multi-agent job. Default.

ACTIVE_FROM Indicates the start of a period of time during which the job or group scheduling table
can be ordered. [For MVS jobs and group scheduling tables, only.] Optional. Date
Format: YYYYMMDD
ACTIVE_TILL Indicates the end of a period of time during which the job or group scheduling table
can be ordered. [For MVS jobs and group scheduling tables, only.] Optional. Date
Format: YYYYMMDD
TAGs Collection of scheduling criteria organized unit with a unique name. Mandatory.
Example:
TAG TAG_NAME="tag1" DAYS="1,8,15,23" DAYS_AND_OR="AND"
WEEKDAYS="wcal_3" DATE="18" DAYSCAL="" CONFCAL="cal_4" RETRO="1"
SHIFT="PREVDAY" SHIFTNUM="5" MAXWAIT="5" MAXRUNS="2" JAN="1"
TAG_NAME Unique name of the tag. String. Mandatory.
DAYS Days of the month on which to order the jobs in the group
scheduling table. String. Optional.
DAYS_AND_OR Indicates the relationship between specified Days values and
Weekdays values. Optional. Valid values:
■ AND
■ OR

WEEKDAYS Days of the week on which to order the jobs in the group
scheduling table. String. Optional.
DATE Specific dates on which to order the jobs in the group scheduling
table. String. mmdd format. String. Optional.
DAYSCAL Name of a user-defined calendar used to specify a set of days.
String. Optional.
CONFCAL Specifies a calendar that is used to validate all specified days
and dates on which to schedule the jobs in the group scheduling
table. String. Optional.
RETRO Indicates whether the jobs in the group scheduling table is
scheduled for possible execution after their original scheduling
date (odate) has passed. Optional. Valid values:
■ 0 (No. Default)
■ 1 (Yes)

SHIFT Describes how to shift the scheduling date of the jobs in the
group scheduling table. Optional. Valid values:
■ IGNOREJOB
■ PREVDAY
■ NEXTDAY
■ NOCONFCAL

SHIFTNUM Number of days to shift the scheduling date of the jobs in the
group scheduling table. String. Optional.

Chapter 5 Scheduling table utilities 127


deftable

Table 36 deftable input file parameters for group scheduling tables (Part 4 of 7)
Parameter Description
TAG continued MAXWAIT Number of extra days (beyond the original scheduling date) that
the jobs in the group scheduling table are allowed to remain in
the Active Jobs file awaiting execution. Integer. Optional.
MAXRUNS Maximum number of job runs to retain the SYSDATA archive
data set for jobs that ended NOTOK. Subparameter of
AUTOARCH. String. Valid values: 000 – 998, or 999 to retain the
archived data for all runs. Optional.
JAN, FEB, MAR, Months when the jobs in the group scheduling table can run.
APR, MAY, JUN, Optional. Valid values:
JUL, AUG, SEP, ■ 0 (Default)
OCT, NOV, DEC ■ 1

TAG_NAMES Wrapper for specifying one or more scheduling tags for the group scheduling table.
Example:
TAG_NAMES TAG_NAME="TAG_1"
TAG_NAME String. Optional.
INCOND In condition. Optional.
Example:
INCOND NAME="Cond1" ODATE="ODAT" AND_OR="AND" OP="("
NAME Name of the In condition. String. Mandatory. 1 - 255 characters,
case-sensitive.
ODATE Order date of the In condition. String. Mandatory.
Default: ODAT
AND_OR Relationship between conditions. Valid values:
■ AND (default)
■ OR

OP Parentheses indicating parts of the condition that are interpreted


first. String. Optional.
OUTCOND Out condition. Optional.
Example:
OUTCOND NAME="Job1" ODATE="ODAT" SIGN="ADD"
NAME Name of the Out condition. String. Mandatory.
1 - 255 characters, case-sensitive.
ODATE Order date of the Out condition. String. Mandatory.
Default: ODAT
SIGN Indicates whether to add or delete the condition. Valid values:
■ ADD (default)
■ DEL

AUTOEDIT Wrapper for the AutoEdit expression. Optional.


Example:
AUTOEDIT EXP="%%PARM1=%%TIME"
EXP AutoEdit expression. String. Mandatory.
Example:
%%PARM1=%%TIME.

128 CONTROL-M/Enterprise Manager Utility Guide


deftable

Table 36 deftable input file parameters for group scheduling tables (Part 5 of 7)
Parameter Description
SHOUT Wrapper for the Shout message. Optional.
Example:
SHOUT WHEN="EXECTIME" DEST="workstation1" URGENCY="R"
MESSAGE="Job completed OK." TIME=">10"
WHEN Condition under which the Shout message is sent. Mandatory.
Valid values:
■ OK (default)
■ NOTOK
■ RERUN
■ LATESUB
■ LATETIME
■ EXECTIME

DEST Recipient of the shout message. String. Mandatory.


Valid values: 1 - 16 characters, case-sensitive.
URGENCY Indicates the urgency of the Shout message. Mandatory.
Valid values:
■ R (regular-default)
■ U (urgent)
■ V (very urgent)

MESSAGE Text of the message. String. Mandatory.


Valid values: 1 - 70 characters, spaces allowed.
TIME Time of the message. String. Mandatory.

Chapter 5 Scheduling table utilities 129


deftable

Table 36 deftable input file parameters for group scheduling tables (Part 6 of 7)
Parameter Description
ON_GROUP Table-processing termination status, for a group scheduling table, that determines
whether the accompanying DO statements are performed.
Example:
ON_GROUP CODE="OK"
CODE Indicates whether the DO statements are performed when the
group scheduling table ends OK or NOTOK. Mandatory.
Valid values:
■ OK
■ NOTOK

DO_GROUP Actions to perform when the ON_GROUP condition is fulfilled.


Example:
DO_GROUP ACTION="OK"
ACTION Mandatory. Valid values:
■ OK
■ NOTOK

DOAUTOEDIT Wrapper for the AutoEdit expression. Optional.


Example:
DOAUTOEDIT EXP="%%PARM1=%%TIME"
EXP The AutoEdit expression. String. Mandatory.
For example, %%PARM1=%%TIME
DOSHOUT Shout message wrapper. Optional.
Example:
DOSHOUT DEST="Wkstn2" URGENCY="R" MESSAGE="Job5 completed OK"
DEST Recipient of the Shout message.
String. Mandatory.
Valid values: 1-16 characters, case-sensitive.
URGENCY Urgency of the Shout message. Valid values:
■ R (regular-default)
■ U (urgent)
■ V (very urgent)

MESSAGE Text of the Shout message. String. Mandatory.


Valid values: 1 - 70 characters, spaces allowed.
DOFORCEJOB Forces a specified job when the current group scheduling table is complete.
Optional.
Example:
DOFORCEJOB DSN="45446" TABLE_NAME="Table2" NAME="Job4"
ODATE="ODAT"
DSN Library for the scheduling table [MVS only]. String. Mandatory.
TABLE_NAME Name of the scheduling table to which the job belongs. String.
Mandatory. Valid values: 1 - 10 characters.
NAME Name of the job. String. Mandatory.
ODATE Original scheduling date for the job. String. Default: ODAT

130 CONTROL-M/Enterprise Manager Utility Guide


deftable

Table 36 deftable input file parameters for group scheduling tables (Part 7 of 7)
Parameter Description
DOCOND Specifies prerequisite conditions to be added or deleted. Optional.
Example:
DOCOND NAME="Cond1" ODATE="ODAT" SIGN="ADD"
NAME Condition name. String. Mandatory.
Valid values: 1 - 20 characters, case-sensitive.
ODATE Condition date. String. Mandatory. Default: ODAT
SIGN Specifies whether to add or delete the condition. Valid values:
■ ADD (default)
■ DEL

DOMAIL Sends mail when the group scheduling table run is complete. Optional.
Example:
DOMAIL URGENCY="R" DEST="ecsuser@ecsuser.com"
CC_DEST="barry@emuser.com" SUBJECT="OK" MESSAGE="Task completed OK."
URGENCY Urgency of the message. Valid values:
■ R (regular - Default)
■ U (Urgent)

DEST Recipient of the message. String. Mandatory.


CC_DEST Additional recipient of the message. String. Optional.
SUBJECT Brief text description of the message contents. String. Optional.
MESSAGE Text of the message. String. Mandatory.
JOB Indicate the opening and closing tags of a single job definition. The parameters of the
job are listed between the tags. For a complete listing of defjob parameters, see
“defjob” on page 24.

Chapter 5 Scheduling table utilities 131


deftable

Sample input files used with the deftable utility.

Example 1: Scheduling table with two jobs

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE DEFTABLE SYSTEM "deftable.dtd">
<DEFTABLE>
<SCHED_TABLE
TABLE_NAME="2:35"
TABLE_DSN="KDSN"
DATACENTER="phantom">
<JOB
JOBNAME="KURT999"
MEMNAME="kurt_m"
GROUP="KGROUP"
APPLICATION="KAPP"
AUTHOR=”CTMEMUSER”
TASKTYPE="Command"
MAXRERUN="1"
INTERVAL="1"
PRIORITY="1"
CRITICAL="1"
CYCLIC="1"
CONFIRM="1"
DAYS="1,2,3"
DAYSCAL="">
<SHOUT WHEN="OK" DEST="NOWHERE" MESSAGE="Job is
OK" TIME="1045"/>
</JOB>
<JOB
JOBNAME="KURT901"
MEMNAME="kurt m"
GROUP="KGROUP"
APPLICATION="KAPP"
TASKTYPE="Command"
MAXRERUN="1"
INTERVAL="1"
PRIORITY="1"
CRITICAL="1"
CYCLIC="1"
CONFIRM="1"
DAYS="1,2,3"
DAYSCAL="123">
<SHOUT WHEN="OK" DEST="NOWHERE" MESSAGE="Job is
OK"
TIME="1045"/>
</JOB>
</SCHED_TABLE>
</DEFTABLE>

132 CONTROL-M/Enterprise Manager Utility Guide


deftable

Example 2: Group scheduling table with one job

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE DEFTABLE SYSTEM "deftable.dtd"><DEFTABLE>
<SCHED_GROUP
DATACENTER="MIG4"
TABLE_NAME="TABLE1"
TABLE_DSN="TABLELIB"
GROUP="GRP"
JOBNAME="TABLE1"
APPLICATION="APPL"
MEMNAME="MEMNAME"
OWNER="JACKH"
AUTHOR=”CTMEMUSER”
ADJUST_COND="1"
CONFIRM="1"
PRIORITY="AB"
TIMEFROM="0900"
TIMETO="1100"
DUE_OUT="0500"
DOCMEM="DOC"
DOCLIB="A.B.C"
DESCRIPTION="desc">
<TAG
TAG_NAME="TEST"
DAYS="ALL"
DAYS_AND_OR="OR"
WEEKDAYS="1,2"
RETRO="1"
SHIFT="NEXTDAY"
SHIFTNUM="+24"
DAYSCAL="EYALDCAL"
WEEKSCAL="EYALWCAL"
CONFCAL="EYALCCAL"
MAXWAIT="10"
JAN="1"/>
<TAG
TAG_NAME="TEST2"
DAYS="1,2,3,4"
DAYS_AND_OR="AND"
WEEKDAYS="1,2"
RETRO="0"
SHIFT="PREVDAY"
SHIFTNUM="+24"
MAXWAIT="10"
FEB="1"/>
<INCOND NAME="IN1" ODATE="$$$$"/>
<INCOND NAME="IN2" ODATE="$$$$"/>
<INCOND NAME="IN3" ODATE="****" AND_OR="OR
OP="O("/>
<INCOND NAME="IN4" ODATE="STAT" AND_OR="OR"
OP=")"/>
<OUTCOND NAME="OUT1" ODATE="STAT" SIGN="DEL"/>

Chapter 5 Scheduling table utilities 133


deftable

<OUTCOND NAME="OUT1" ODATE="STAT"/>


<AUTOEDIT EXP="DUMMY=ggg"/>
<ON_GROUP CODE="NOTOK">
<DOSHOUT DEST="ShoutDest" URGENCY="U" MESSAGE="msg"/>
<DO_GROUP ACTION="OK"/>
<DO_GROUP ACTION="NOTOK"/>
<DOFORCEJOB TABLE_NAME="A.B.C" NAME="MEMNAME" ODATE="1011"/>
<DOCONDNAME="condname" ODATE="0506"/>
<DOMAIL DEST="eyal@bmc.com" MESSAGE="hello"/>
<DOAUTOEDIT EXP="A=B"/>
</ON_GROUP>
<SHOUT WHEN="OK" DEST="DestTest" URGENCY="R" MESSAGE="Message test" TIME="1000"/>
<JOB JOBNAME="JOB_GRP" MEMNAME="JACK"
MEMLIB="JACKIB" OWNER="JACKH" APPLICATION="JACKAPP" TASKTYPE="Job" MAXRERUN="0"
INTERVAL="1" PRIORITY="1" CRITICAL="1" CYCLIC="1" CONFIRM="1" DAYS="1,2,3"
DAYSCAL="12_7" AUTHOR="JACKH">
<TAG_NAMES TAG_NAME="TEST"/>
<OUTCOND NAME="COND1" ODATE="STAT"/>
<OUTCOND NAME="COND2" ODATE="STAT"/>
</JOB>
</SCHED_GROUP>
</DEFTABLE>

134 CONTROL-M/Enterprise Manager Utility Guide


exportdeftable

exportdeftable
The exportdeftable utility exports scheduling tables from the CONTROL-M/EM
database to a file.

When the exportdeftable utility is invoked, a file of arguments that you have created
is processed. This arguments file contains statements that specify an existing
scheduling table or group of scheduling tables. The specified tables are exported to an
output file.

Output files created with the exportdeftable utility can be used as import files with
the deftable utility.

For example, you can export job processing definitions to an output file using
exportdeftable, make modifications to the definitions and save the file, and use the
same file as the input file when running deftable to import the modified table
definitions into CONTROL-M/EM database.

To invoke the exportdeftable utility:

1 Log in as a CONTROL-M/EM user.

2 Open a command prompt window (Microsoft Windows). You do not need to be in


the CONTROL-M/EM directory.

3 Enter either of the following commands:

exportdeftable [-u user [-p password] | -pf password_file]


-s gui_server_name -arg arg_file_name -out out_file_name

- or -
exportdeftable [-USERNAME user [-PASSWORD password] | -PASSWORD_FILE
password_file] -HOST gui_server_name -ARG_FILE arg_file_name
-OUT out_file_name

Parameters of the exportdeftable command are described in Table 37 on page 136.

4 Press Enter. The exportdeftable arguments file is checked and processed. If there
are any errors in the file, a message is displayed specifying the lines with errors.

The exported table definitions are saved to an output file, the name and location of
which is specified in parameter out_file_name.

Chapter 5 Scheduling table utilities 135


exportdeftable

Parameters

Table 37 exportdeftable parameters


Parameter Description
user CONTROL-M/EM user name.
password The CONTROL-M/EM user password.
password_file Flat file containing an unencrypted username and password on separate
lines in the format:
user=username
password=password
Note: If both -u and -pf are specified, an error message is generated. If only
-u is specified, an online prompt is issued for the password. If neither is
specified, a prompt is issued for the database user name and password.
gui_server_ CONTROL-M/EM GUI server logical name, host name, or IP address.
name Note: If multiple GUI servers exist, set this parameter to the logical name of
the relevant GUI server.
arg_file_name Path and name of the arguments file containing the exportdeftable
specifications. Instructions for preparing this file are in Appendix A, “XML
File Preparation.”
out_file_name Path and name of the file containing the specification of the exported job.

The exportdeftable arguments file


Arguments are used as a selection criteria to determine which scheduling tables to
export. Arguments are written to the exportdeftable argument file.

The arguments files that you create with the exportdeftable utility are written in
XML format and saved in a text file. The format in which this file must be written is
described on the following pages.

When this file is invoked, scheduling table definitions are exported from the
CONTROL-M/EM database. For instructions for creating arguments files, see
Appendix A, “XML File Preparation.”

The following rules apply to the exportdeftable arguments file:


■ More than one job can be specified in an exportdeftable file.

■ The arguments file is case-sensitive.

■ All parameter values (such as strings or digits) must be enclosed in quotation


marks (for example, JOBNAME="Job1").
■ More than one PARAM parameter can be used in a TERM statement.

■ The relationship between PARAM parameters in a TERM statement is AND. The


relationship between TERM statements is OR.

136 CONTROL-M/Enterprise Manager Utility Guide


exportdeftable

Table 38 exportdeftable arguments file parameters


Parameter Description
The first two lines of the XML request file for this API request contain information that specifies the version
of XML, the text encoding format being used, and the location of the .dtd file.
These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE TERMS SYSTEM "terms.dtd"
TERMS These tags indicate the start and end of the TERMS file. Only criteria that are
located between the tags are considered to be part of the argument.
TERM The TERM tags indicate the start and the end of a group of selection criteria used
to specify a table or tables that are to be exported. Only PARAM tags that are
located between the TERM tags are considered to be part of the TERM argument.
REL Optional. Relationship between terms. Valid values:
■ AND
■ OR

PARAM The selection criteria parameter used to determine those scheduling tables that are
to be exported. More than one PARAM can be specified. Mandatory.
Example:
PARAM NAME="DATACENTER" OP="EQ" VALUE="Center1"
NAME String. Mandatory. The parameter name of any scheduling table or
group scheduling table parameter. These parameters are described in
Table 33 on page 123.
Note: At least one of the following scheduling table parameters must be
included in the arguments file:
■ DATACENTER
■ TABLE_NAME
■ TABLE_DSN

OP Mandatory. Describes the relationship between the NAME and the


VALUE parameters of the TERM. Valid values:
■ EQ
■ NEQ
■ NOTIN
■ LIKE

VALUE String. Mandatory. The value of any scheduling table or group


scheduling table parameter. These parameters are described in Table 33
on page 123.
Note: Multiple values can be specified for VALUE by using the *
wildcard character in place of characters at the end of an expression.

Chapter 5 Scheduling table utilities 137


exportdeftable

Following are sample arguments files used with the exportdeftable utility:

Example 1: Export all scheduling tables in the Data1 data center

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE TERMS SYSTEM "terms.dtd">
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="Data1"/>
</TERM>
</TERMS>

Example 2: Export with multiple selection criteria

Group scheduling tables are exported that:


■ are located in data center Data1 and belong to the GRP_03 group scheduling table

- or -
■ are located in data center Data1 and belong to the GRP_04 group scheduling table

<?xml version=’1.0’ encoding=’UTF-8’?>


<!DOCTYPE TERMS SYSTEM "terms.dtd">
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="Data1"/>
<PARAM NAME="GROUP" OP="EQ" VALUE="GRP_03"/>
</TERM>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="Data1"/>
<PARAM NAME="GROUP" OP="EQ" VALUE="GRP_04"/>
</TERM>
</TERMS>

138 CONTROL-M/Enterprise Manager Utility Guide


Chapter

6
6 Administration utilities
Monitoring and maintaining your CONTROL-M/EM network is necessary to ensure
that your scheduling environment operates as planned. The utilities described in this
chapter address selected management and security topics.

NOTE
Many of the tasks performed by the check_gtw and ctl utilities can also be performed using
the Administration facility or the root menu. However, by including a utility command in the
command line of a job processing definition, you can run the utility at a predetermined time
or under a predetermined set of conditions without being present.

Table 39 Administration utilities


Utility Description
check_gtw Checks that the specified gateway is running. (See page 140.)
cryptocli Enables the CONTROL-M/EM administrator to encrypt a password for use as
the administrator password. The utility inserts the encrypted password in the
relevant places in the mcs.ini file. (See page 142.)
ctl The ctl command line utility enables you to send simple requests to networked
CONTROL-M/EM components. (See page 144.)

Chapter 6 Administration utilities 139


check_gtw

check_gtw
The Gateway Verification utility (check_gtw) verifies the availability of the gateways.
The utility checks all currently enabled data centers to verify if their gateway is
running. If any check for a gateway fails, an Alert is sent to the specified e-mail
address(es). If a gateway whose check failed (not active) starts to run, another Alert is
sent by e-mail indicating that the gateway is now running.

NOTE
Alerts are sent only once, when a change in gateway status occurs.

To invoke the check_gtw utility, specify the following command:

check_gtw
-u|-U <DB_user>
-p|-P <DB_password>
[-m|-M <test_mode>]
[-t|-T <time_interval>]
[-w|-W <waiting_time>]
[-s ALL | <max_number_of_parallel_dc>]
-e <address> [-e <address> ... ]
|-f|-F <file>
|-e <address> [-e <address> ... ]-f|-F <file>

NOTE
An -e parameter, or an -f parameter, or both, must be specified.

The parameters are specified as described in Table 40.

Table 40 check_gtw utility parameters (Part 1 of 2)


Parameter Description
-u DB_user Database user name.
-p DB_password Database user password.
-m test_mode Mode of the utility. Valid values:
■ ps – Use the ps Unix command. This mode can only be used when all
gateways run on the local computer.
■ ctl – Use utility ecs ctl interactively.
■ ctlbg – Use utility ecs ctl by sending a background “chk” message to
all the gateways. This mode prevents the utility from hanging if a
gateway does not respond. Default.
-t time_interval Time interval (in seconds) between tests. Default: 200

140 CONTROL-M/Enterprise Manager Utility Guide


check_gtw

Table 40 check_gtw utility parameters (Part 2 of 2)


Parameter Description
-w waiting_time Time (in seconds) to wait for all gateways to respond. Use with ctlbg
only.
-s Maximum number of ecs ctl commands to be launched concurrently.
max_number_of_ Valid values:
dc | ALL ■ ALL – All enabled data centers. Default.
■ # # – Number of enabled data centers.

-e address E-mail addresses to which Alerts are sent. Additional -e parameters can
be specified, separated by blanks.
For example:
-e address1@mail.com -e address2@mail.com
-f file File that contains e-mail addresses to which Alerts are sent. The addresses
must be separated by a blank space.

If the Gateway Verification utility (check_gtw) determines that a gateway is


unavailable, a user-defined exit (check_gtw_ue) can be automatically executed.

A sample check_gtw_ue exit is supplied in the $HOME/scripts directory. Make a copy


of this sample exit and modify it. Table 41 lists the parameters passed to this user exit
by the check_gtw utility.

Table 41 check_gtw_ue user exit parameters


Parameter Description
$DATA_CENTER Data center name.
$UserName User name.
$Passwd User password.

Chapter 6 Administration utilities 141


cryptocli

cryptocli
The cryptocli utility creates an encrypted version of the password you submit.

If the CONTROL-M/EM administrator user name or password is changed in the


CONTROL-M/EM database, it must also be updated manually in all relevant mcs.ini
files. By default, the password is encrypted in the mcs.ini file. Use the cryptocli utility
to generate the encrypted version of your new password.

You can invoke cryptocli in either of the following modes.

■ Trial mode – You submit the new password and cryptocli creates an output text
file in the specified location containing the encrypted version of that password.
You can copy the encrypted text to appropriate places in the mcs.ini file manually.

■ Operational mode – When you submit your username and new password,
cryptocli creates an encrypted version of the password and inserts it in the
appropriate places in the text of the mcs.ini file. mcs.ini is saved automatically.

To invoke the cryptocli utility in trial mode:

1 Open a Command Prompt window.

2 Change the working directory to Ini under the CONTROL-M/EM home directory.

3 Specify the command:

cryptocli.exe new_password output_filename

where:

Item Description
new_password New CONTROL-M/EM administrator password.
output_filename Full path name of the output file created by cryptocli. The file contains
the encrypted version of the password that was submitted.

142 CONTROL-M/Enterprise Manager Utility Guide


cryptocli

To invoke the cryptocli utility in operation mode:

1 Open a Command Prompt window.

2 Change the working directory to Ini under the CONTROL-M/EM home directory.

3 Specify the following command:

cryptocli.exe user_name new_password mcs.ini_path_name

where:

Item Description
user_name CONTROL-M/EM administrator user name.
new_password New CONTROL-M/EM administrator password.
mcs.ini_path_name Full path name of the mcs.ini file (for example,
windir\system32\mcs.ini).

Chapter 6 Administration utilities 143


ctl

ctl
The ctl command line utility enables you to send simple requests to networked
CONTROL-M/EM components. The ctl utility can:

■ Check if networked CONTROL-M/EM components are operational.


■ Check if networked Batch Impact Manager Server components are operational (if
this product is installed at your site).
■ Set the Gateway and GCS debug level.
■ Send commands to CONTROL-M/EM components and component parameters
during runtime.

The ctl utility is automatically installed with the Gateway or Administration Facility
components. You can modify many attributes of the ctl command.

NOTE
ctl utility commands are case-sensitive.

To invoke ctl from Microsoft Windows:

1 Open a DOS command prompt window.

2 Change the working directory to the CONTROL-M/EM home directory.

3 Specify the ctl command line. For ctl syntax, see “ctl command syntax” on
page 144.

To invoke ctl from Unix:

1 Open an Xterm window.

2 Log in as the CONTROL-M/EM administrator.

3 Specify the ecs ctl command line. For syntax, see “ctl command syntax” on
page 144.

ctl command syntax


The command syntax for the ctl utility is a function of the component for which the
utility runs. The parameters of the ctl utility are described after the command syntax
for each component.

144 CONTROL-M/Enterprise Manager Utility Guide


ctl

NOTE
To run this utility on Unix platforms, issue the command ecs ctl. To run this utility on
Microsoft Windows, issue the command ctl.

Gateway

[ecs] ctl
[{-U em_user -P em_pass} |-pf password_file]
-C Gateway {-dc <Data_Center> |-all}
{-reg |
-cmd stop |
-cmd life_check |
{[-cmd dwl]
[-cmd change_log]
[-cmno_dbg]
[-cmd db{0-9}]
[-cmd gui{+|-}]
[-cmd host{+|-}]
[-cmd trunc{+|-}]
[-cmalive{+|-}]
[-cmd job{+|-}]
[-cmd dwl_debug{+|-}]
[-cmd hostlink{+|-}]
[-cmdguilink{+|-}]
[-cmd show_jcl]}}
[-timeout <Response_Timeout (seconds)>]
[-diagon]

Table 42 ctl parameters for the Gateway (Part 1 of 2)


Parameter Description
ecs Prefix to be specified when running this utility on a Unix operating system.
-U CONTROL-M/EM database user name.
-P CONTROL-M/EM database user password.
-pf Flat file containing an unencrypted username and password on separate lines
in the format:
user=username
password=password
Note: If both -U and -pf are specified, an error message is generated. If only
-U is specified, an online prompt is issued for the password. If neither is
specified, a prompt is issued for the database user name and password.
-C Gateway Indicates that the command is directed to the gateway. The gateway mediates
between CONTROL-M/EM components and the CONTROL-M installation.
-dc Name of a data center. This name identifies the gateway to which ctl is
sending a command or message. This parameter is used when a query or
command is directed to a specific gateway (as specified by the -C parameter).
-dc cannot be used with -all.
-all Directs a query or command to all networked components of the gateway (as
specified by the -C parameter). -all cannot be used with -dc.

Chapter 6 Administration utilities 145


ctl

Table 42 ctl parameters for the Gateway (Part 2 of 2)


Parameter Description
-reg Checks if the gateway is registered in the CommReg table. -reg cannot be
used with -cmd or -cmdstr.
-cmd Indicates a command to be performed by the gateway. -cmd cannot be used
with -reg. More than one instance of the -cmd parameter can be specified in
the command line.
stop Stops the gateway. This command cannot be specified with
other commands in the same run of the ctl utility.
life_check Checks if the gateway is active. This command cannot be
specified with other commands in the same run of ctl.
dwl Forces a new download from a CONTROL-M installation.
The following -cmd values are used for diagnostics and debugging, as
described in the “Diagnostics and Troubleshooting” chapter of the
CONTROL-M/Enterprise Manager Administrator Guide.
Note: Diagnostic and non-diagnostic commands can be specified on the same
ctl command line.
change_log Closes the current log file and creates a new log file.
no_dbg Stops all debug printing.
db# Debug level for database operations. Range: 0 - 9.
0 turns off debugging.
gui + | – Starts or stops a debug trace for the GUI.
host+ | – Starts or stops output of host debug messages.
trunc+ | – Starts or stops truncating messages. Only the message
header and one row of data remain after truncation.
alive+ | – Starts or stops debugging of “keep alive” messages.
job+ | – Starts or stops dumping job messages. During a debug
trace, job+ displays messages on the screen about active job
downloads, active job updates, and Scheduling table
uploads. This option is active by default.
dwl_debug+ | – Starts or stops a debug trace for the download procedure.
hostlink+ | – Starts or stops a debug trace for the host link.
guilink+ | – Starts or stops a debug trace for the GUI link.
show_jcl Shows active JCL.
-timeout Indicates the period of time (in seconds) that ctl waits for a response from the
gateway before declaring a communication failure. Default: 30. Optional.
-diagon Activates tracing of ctl workflow (diagnostics). The results are written to the
ctl_diag.machine.txt file located in the working directory. Optional.

146 CONTROL-M/Enterprise Manager Utility Guide


ctl

Global Conditions Server

[ecs] ctl
[{-U em_user -P em_pass} |-pf password_file]
-C GCS {-M <Computer_Name> | -all}
{ -reg |
-cmd stop |
-cmd life_check |
-cmd change_log |
-cmdstr "<Command_String>"}]
[-timeout <Response_Timeout (seconds)>]
[-diagon]

Table 43 ctl parameters for the Global Conditions Server (Part 1 of 2)


Parameter Description
ecs Prefix to be specified when running this utility on a Unix operating system.
-U CONTROL-M/EM database user name.
-P CONTROL-M/EM database user password.
-pf Flat file containing an unencrypted username and password on separate lines in
the format:
user=username
password=password
Note: If both -U and -pf are specified, an error message is generated. If only -U is
specified, an online prompt is issued for the password. If neither is specified, a
prompt is issued for the database user name and password.
-C GCS Global Conditions Server to which the command is directed. The Global
Conditions Server handles the distribution of conditions that affect jobs in more
than one data center.
-M Specifies a computer name. This name is used to identify the computer to which
the Global Conditions Server belongs. -M cannot be used with -all.
-all Directs a query or command to all networked Global Conditions Servers. -all
cannot be used with -M.
-reg Checks if the Global Conditions Server is registered in the CommReg table. -reg
cannot be used with -cmd or -cmdstr.

Chapter 6 Administration utilities 147


ctl

Table 43 ctl parameters for the Global Conditions Server (Part 2 of 2)


Parameter Description
-cmd Indicates a command to be performed by the Global Conditions Server. -cmd
cannot be used with -reg. More than one instance of the -cmd parameter can be
specified in the command line.
stop Stops the Global Conditions Server. This command cannot be
specified with other commands in the same run of the ctl utility.
life_check Checks if the Global Conditions Server is active. This command
cannot be specified with other commands in the same run of the
ctl utility.
The following -cmd value is used for diagnostic and debugging purposes, which
are described in more depth in the “Diagnostics and Troubleshooting” chapter
of the CONTROL-M/Enterprise Manager Administrator Guide.
Note: Diagnostic and non-diagnostic commands can be specified on the same ctl
command line.
change_log Closes the current log file and creates a new log file.
-cmdstr Specifies a text string to be sent to the Global Conditions Server. If the text string
contains spaces or tabs, it must be enclosed with double quotes (“ ”).
-cmdstr cannot be used with -reg or -cmd. The -cmdstr parameter is used for
diagnostic purposes only. It is discussed in the diagnostics and troubleshooting
chapter of the CONTROL-M/Enterprise Manager Administrator Guide.
-timeout Indicates the period of time (in seconds) that ctl waits for a response from the
Global Conditions Server before declaring that communication has failed.
Default: 30. Optional.
-diagon Activates tracing of ctl work flow (diagnostics). The results are written to the
ctl_diag.machine.txt file located in the working directory. Optional.

GUI Server

[ecs] ctl
[{-U em_user -P em_pass} |-pf password_file]
-C GUI_Server
{-M <Computer_Name> | -name <Logical_Name> | -all}
{-reg |
-cmd stop |
-cmd life_check |
-cmd do_measure |
-cmd get_measure |
-cmdstr "<Command_String>"}
[-timeout <Response_Timeout (seconds)>]
[-diagon]

Table 44 ctl parameters for the GUI Server (Part 1 of 3)


Parameter Description
ecs Specify this prefix when running this utility on Unix operating systems.
-U CONTROL-M/EM database user name.

148 CONTROL-M/Enterprise Manager Utility Guide


ctl

Table 44 ctl parameters for the GUI Server (Part 2 of 3)


Parameter Description
-P CONTROL-M/EM database user password.
-pf Flat file containing an unencrypted username and password on separate
lines in the format:
user=username
password=password
Note: If both -U and -pf are specified, an error message is generated. If only
-U is specified, an online prompt is issued for the password. If neither is
specified, a prompt is issued for the database user name and password.
-C GUI_Server Indicates the command is directed to one or more GUI Servers. GUI Servers
handle communications between CONTROL-M/EM GUI workstations and
other CONTROL-M/EM components.
-M Specifies a computer name. This name is used to identify the computer to
which the GUI Server belongs. -M cannot be used with -all. When -M is
specified, the request is sent to the GUI Server whose name is equal to the
value indicated with -M.
-name Logical name of the GUI Server. If the GUI Server is started without
specifying -name, the logical name of the GUI Server is equal to the host
name of the computer where the GUI Server is running.
-all Directs a query or command to all networked GUI Servers.
-all cannot be used with -M.
-reg Checks if the GUI Server is registered in the CommReg table.
-reg cannot be used with -cmd or -cmdstr.
-cmd Indicates a command to be performed by the GUI Server. -cmd cannot be
used with -reg. More than one instance of the -cmd parameter can be
specified in the command line.
stop Stops the GUI Server.
This command cannot be specified with other commands
in the same run of the ctl utility.
life_check Checks if the GUI Server is active.
This command cannot be specified with other commands
in the same run of the ctl utility.
do_measure Initiates collection of statistics about the GUI Server.
This command cannot be specified with other commands
in the same run of the ctl utility.
get_measure Retrieves statistics from the GUI Server and displays
them.
This command cannot be specified with other commands
in the same run of the ctl utility.
-cmdstr Specifies a text string to be sent to the GUI Server. If the text string contains
spaces or tabs, it must be enclosed with double quotes (“ ”).
-cmdstr cannot be used with -reg or -cmd.
The -cmdstr parameter is used for diagnostic purposes only. Its usage is
discussed in the diagnostics and troubleshooting chapter of the
CONTROL-M/Enterprise Manager Administrator Guide.

Chapter 6 Administration utilities 149


ctl

Table 44 ctl parameters for the GUI Server (Part 3 of 3)


Parameter Description
-timeout Period of time (in seconds) that ctl waits for a response from the GUI Server
before declaring that communication has failed. Default: 30. Optional.
-diagon Activates tracing of ctl work flow (diagnostics). Results are written to the
ctl_diag.machine.txt file located in the working directory. Optional.

Global Alerts Server

[ecs] ctl
[{-U em_user -P em_pass} |-pf password_file]
-C GAS
{-M <Computer_Name> |-name <Logical_Name> | -all}
{-reg |
-cmd stop |
-cmd life_check |
-cmdstr "<Command_String>"}
[-timeout <Response_Timeout (seconds)>]
[-diagon]

150 CONTROL-M/Enterprise Manager Utility Guide


ctl

Table 45 ctl parameters for the Global Alerts Server


Parameter Description
ecs This prefix must be specified when running this utility on Unix.
-U CONTROL-M/EM database user name.
-P CONTROL-M/EM database user password.
-pf Flat file containing an unencrypted username and password on separate lines in
the format:
user=username
password=password
Note: If both -U and -pf are specified, an error message is generated. If only -U
is specified, an online prompt is issued for the password. If neither is specified,
a prompt is issued for the database user name and password.
-C GAS Global Alerts Server. The Global Alerts Server identifies and distributes alerts
between CONTROL-M installations and CONTROL-M/EM workstations.
-M Specifies a computer name. This name is used to identify the computer to which
the Global Alerts Server belongs. -M cannot be used with -all. When -M is
specified, the request is sent to the Global Alerts Server whose name is equal to
the value indicated with -M.
-name Logical name of the Global Alerts Server. If the Global Alerts Server is started
without specifying -name, the logical name of the Global Alerts Server is equal
to the host name of the computer where the Global Alerts Server is running.
-all Directs a query or command to all networked Global Alerts Servers.
-all cannot be used with -M.
-reg Checks if the Global Alerts Server is registered in the CommReg table.
-reg cannot be used with -cmd or -cmdstr.
-cmd Indicates a command to be performed by the Global Alerts Server.
-cmd cannot be used with -reg. More than one -cmd parameter can be specified
in the command line.
stop Stops the Global Alerts Server. This command cannot be specified
with other commands in the same run of the ctl utility.
life_check Checks if the Global Alerts Server is active. This command cannot
be specified with other commands in the same run of utility ctl.
-cmdstr Specifies a text string to be sent to the Global Alerts Server. If the text string
contains spaces or tabs, it must be enclosed with double quotes (“ ”).
-cmdstr cannot be used with -reg or -cmd.
The -cmdstr parameter is used for diagnostic purposes only. Its usage is
discussed in the diagnostics and troubleshooting chapter of the
CONTROL-M/Enterprise Manager Administrator Guide.
-timeout Period of time (in seconds) that ctl waits for a response from the Global Alerts
Server before declaring a communication failure. Default: 30. Optional.
-diagon Activates tracing of ctl work flow (diagnostics). The results are written to the
ctl_diag.machine.txt file located in the working directory. Optional.

Chapter 6 Administration utilities 151


ctl

Administration Agent

[ecs] ctl
[{-U em_user -P em_pass} |-pf password_file]
-C Maint_Agent {-M <Computer_Name> | -all}
{-reg |
-cmd stop |
-cmd life_check |
-cmd shutdown} [-timeout <Response_Timeout (seconds)>]
[-diagon]

Table 46 ctl parameters for the Administration Agent


Parameter Description
ecs This prefix must be specified when running this utility on Unix.
-U CONTROL-M/EM database user name.
-P CONTROL-M/EM database user password.
-pf Flat file containing an unencrypted username and password on separate lines in
the format:
user=username
password=password
Note: If both -U and -pf are specified, an error message is generated. If only -U
is specified, an online prompt is issued for the password. If neither is specified,
a prompt is issued for the database user name and password.
-C Maint_ Administration Agent to which the command is directed. The Administration
Agent Agent controls CONTROL-M/EM components on the host computer.
-M Specifies a computer name. This name is used to identify the computer to which
the Administration Agent belongs. -M cannot be used with -all.
-all Directs a query or command to all networked Administration Agents.
-all cannot be used with -M.
-reg Checks if the Administration Agent is registered in the CommReg table. -reg
cannot be used with -cmd.
-cmd Indicates a command to be performed by the Administration Agent. -cmd
cannot be used with -reg. More than one instance of the -cmd parameter can be
specified in the command line.
stop Stops the Administration Agent. Cannot be specified with other
commands in the same run of the ctl utility.
life_check Checks if the Administration Agent is active.
This command cannot be specified with other commands in the
same run of the ctl utility.
shutdown Stops the Administration Agent, and all components that the
Administration Agent administers, without changing their
configurations. This command cannot be specified with other
commands in the same run of the ctl utility.
-timeout Period of time (in seconds) that ctl waits for a response from the specified
component before declaring a communication failure. Default: 30. Optional.
-diagon Activates tracing of ctl work flow (diagnostics). The results are written to the
ctl_diag.machine.txt file located in the working directory. Optional.

152 CONTROL-M/Enterprise Manager Utility Guide


ctl

BMC Batch Impact Manager Server

[ecs] ctl
[{-U em_user -P em_pass} |-pf password_file]
-C BIM
-M <Computer_Name>
{-reg |
-cmd stop |
-cmd life_check |
-cmdstr "<Command_String>"
[-timeout <Response_Timeout (seconds)>]
[-diagon]

Table 47 ctl parameters for the BMC Batch Impact Manager Server (Part 1 of 2)
Parameter Description
ecs Specify this prefix when running this utility on Unix operating systems.
-U CONTROL-M/EM database user name.
-P CONTROL-M/EM database user password.
-pf Flat file containing an unencrypted username and password on separate lines in
the format:
user=username
password=password
Note: If both -U and -pf are specified, an error message is generated. If only -U is
specified, an online prompt is issued for the password. If neither is specified, a
prompt is issued for the database user name and password.
-C BIM Indicates the command is directed to a Batch Impact Manager Server (if this
product is installed at your site).
-M Specifies a computer name. This name is used to identify the computer to which
the Batch Impact Manager Server belongs.
-reg Checks if the Batch Impact Manager Server is registered in the CommReg table.
-reg cannot be used with -cmd or -cmdstr.
-cmd Indicates a command to be performed by the Batch Impact Manager Server.
-cmd cannot be used with -reg.
stop Stops the Batch Impact Manager Server.
This command cannot be specified with other commands in
the same run of the ctl utility.
life_check Checks if the Batch Impact Manager Server is active.
This command cannot be specified with other commands in
the same run of the ctl utility.
-cmdstr Specifies a text string to be sent to the Batch Impact Manager Server. If the text
string contains spaces or tabs, it must be enclosed with double quotes (“ ”).
-cmdstr cannot be used with -reg or -cmd.
The -cmdstr parameter is used for diagnostic purposes only. Its usage is
discussed in the diagnostics and troubleshooting chapter of the
CONTROL-M/Enterprise Manager Administrator Guide.

Chapter 6 Administration utilities 153


ctl

Table 47 ctl parameters for the BMC Batch Impact Manager Server (Part 2 of 2)
Parameter Description
-timeout Period of time (in seconds) that ctl waits for a response from the Batch Impact
Manager Server before declaring that communication has failed. Default: 30.
Optional.
-diagon Activates tracing of ctl work flow (diagnostics). Results are written to the
ctl_diag.machine.txt file located in the working directory. Optional.

154 CONTROL-M/Enterprise Manager Utility Guide


Chapter

7
7 Database maintenance utilities
The utilities described in this chapter can be used to maintain the CONTROL-M/EM
database and to import and export information to and from additional
CONTROL-M/EM databases.

Many of the tasks performed by the database maintenance utilities can also be
performed using the Administration facility or the root menu. However, by including
a utility command in the command line of a job processing definition, you can run the
utility at a predetermined time or under a predetermined set of conditions without
being present.

Table 48 Database maintenance utilities


Utility Description
db_check Provides general information about a database and its status, including
verification of database integrity and automatic database and
transaction log monitoring.
db_check_space Provides general information about database size and available space.
util Provides CONTROL-M/EM database management functions from a
command line.

Chapter 7 Database maintenance utilities 155


db_check

db_check
The db_check utility provides the following information:
■ Size of the database

■ Availability of space in the database

■ Verification of database integrity.

■ Automatic database and transaction log monitoring

When db_check is invoked, 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...
Database is OK.

NOTE
The db_check utility works only with databases on a Sybase Adaptive Server. This utility is
not available for Oracle Server.

Syntax

db_check [-ddb_threshold_%] [-llog_threshold_%] [-ppassword] [-n]


[-h]

The user name is derived from the $ECS_USER environment variable.

Table 49 db_check utility parameters


Parameter Description
db_threshold_% Maximum percentage of database use. When this percentage is exceeded,
a message is displayed alerting you to extend the database.
Note: The -d must be lowercase.
log_threshold_% Maximum percentage of transaction log use. When this percentage is
exceeded, a message is displayed alerting you to extend the transaction
log. Note: The -l must be lowercase.
password Password for the CONTROL-M/EM administrator. If not specified, you
are prompted to supply this information when the utility runs.
Note: The -p must be lowercase.
-n When -n is specified, db_check is executed without verifying the total
database integrity. Note: The -n must be specified in lowercase.
-h When -h is specified, db_check displays the amount of database space
that is in use. Note: The -h must be specified in lowercase.

156 CONTROL-M/Enterprise Manager Utility Guide


db_check_space

db_check_space
The db_check_space utility provides the following information for Sybase Adaptive
and Oracle database servers.
■ Total size and availability of space in the /tmp directory

■ Total size and availability of space in the database

■ Total size and availability of space in the log (Sybase only)

■ Percentage of total space in the database that is currently available

NOTE
This utility cannot be used for Oracle database client installations.

To run the db_check_space utility, specify the appropriate CONTROL-M/EM Unix


user account and password using the -U and -P parameters in the command line of
db_check_space (see “Syntax”below) or when prompted by the utility interactively:
■ When working with Sybase, specify the database owner, any database user, or the
Sybase Adaptive server administrator as the user name.
■ When working with Oracle, specify the Oracle administrator as the user name.

When the db_check_space utility is invoked, information similar to the following is


displayed, depending on your database.

Sybase Adaptive Server

+------------------------------------------+
+ Space Information ( /tmp of the machine) +
+------------------------------------------+
Total Size: 524288 KB. Space Available: 401548 KB 23% Free
+------------------------------------+
| SYBASE Size Information: |
+------------------------------------+
Type Total Size Free Space % Free Space
----------------------------------------------------------
Data : 80 MB 72944 KB 89.043 %
Log : 23 MB 23458 KB 99 %

Oracle Server

+------------------------------------------+
+ Space Information ( /tmp of the machine) +
+------------------------------------------+
Total Size: 2048000 KB. Space Available: 366430 KB 17 % Free
+------------------------------------+
| ORACLE Size Information: |
+------------------------------------+
db total = 276480.0 KB
data used = 25296 KB (9%).

Chapter 7 Database maintenance utilities 157


db_check_space

Syntax

db_check_space [ -Uusername [ -Ppassword ] ]

Table 50 db_check_space utility parameters


Parameter Description
-U username User name. If not specified in the command line, you are prompted to
provide this information when the utility runs.
Notes:
■ The -U must be specified in uppercase.
■ If you intend to specify the -P parameter when running the utility, you
must also specify the -U parameter.
-P password Password. If not specified in the command line, you are prompted to
provide this information when the utility runs.
Notes:
■ The -P must be specified in uppercase.
■ If you intend to specify the -P parameter when running the utility, you
must also specify the -U parameter.

NOTE
This utility is also available from the root menu by selecting the 2 - Troubleshooting Menu
option and then the 1 - Database Troubleshooting option. For more information, see the
CONTROL-M/Enterprise Manager Administrator Guide.

158 CONTROL-M/Enterprise Manager Utility Guide


util

util
util is a multi-purpose utility that can perform the following functions from the
command line:
■ Export data from the CONTROL-M/EM database

■ Import data to the CONTROL-M/EM database

■ Delete the CONTROL-M/EM database

■ Clear the CONTROL-M/EM database

■ Build the CONTROL-M/EM database

■ Export a specified definition table

■ Import a specified definition table.

NOTE
When using the util utility to import a table, transferring definition tables between database
systems might fail. For information about resolving this problem, see “Transferring
CONTROL-M/EM data from CONTROL-M/EM installations with MSSQL to installations
with Oracle” on page 166.

The util utility is automatically installed on Microsoft Windows computers with the
CONTROL-M/EM Gateway component.

To invoke the util utility from the command line:

1 Open a Command Prompt window (Microsoft Windows) or go to the command


line (Unix).

2 Change the working directory to the CONTROL-M/EM home directory.

3 Enter one of the following commands:

On Microsoft Windows

util DB_ARGS function function_parameters

On Unix

ecs util DB_ARGS function function_parameters

■ Table 51 describes the database arguments DB_ARGS.


■ Table 52 describes the functions of the util utility.
■ Table 53 describes the function parameters.

Chapter 7 Database maintenance utilities 159


util

DB_ARGS database arguments

All the functions use DB_ARGS in the following format:

[-D database][{-U user -P password} |-pf password_file]


[-S db_server][-T level][-dbms system][-dbtimeout sec][-dbfile path]

Table 51 DB_ARGS database arguments fields


Field Description
database Name of database on which to perform the operation. Default: the
CONTROL-M/EM database defined during installation
user Database user name
password Database user password
password Flat file containing an unencrypted username and password on separate lines in
_file the format:
user=username
password=password
Note: If both -U and -pf are specified, an error message is generated. If only -U is
specified, an online prompt is issued for the password. If neither is specified, a
prompt is issued for the database user name and password.
db_server Name of database server. Default: database server defined during installation.
level Database debug level (Range: 1 - 3)
system Database management system type. Valid values: Sybase, Oracle
Note: If you are using an MSSQL database, specify Sybase.
sec Database timeout interval, in seconds
path Full path name for the database debug report. If the file already exists, it is
overwritten. Default path and filename: home_directory/DB_time/date.log

Functions and syntax of the util utility

NOTE
For Unix, add ecs and a space before specifying util. For example:
ecs util DB_ARGS -build_schema [-cdbg {1 - 5}]

160 CONTROL-M/Enterprise Manager Utility Guide


util

Table 52 util utility – functions (Part 1 of 2)


Function Description
-export Exports job processing definitions, Calendars, CONTROL-M data, and so
on, from the CONTROL-M/EM database to an ASCII text file.
Syntax:
util DB_ARGS -export [-silent] [-cdbg {1 - 5}] {-type
<all | def | cal | sys |dc | user | alert | gc | maint
| collect | view |filter | log | hier>} {-type net
{-name {name}}} [-file file | -file - | -dir dir]
Notes:
■ If the database is exported to a file, you are prompted for a filename.
The extension .Z is appended to the filename. When specifying the
name of the file to import, do not include the .Z extension.
■ If you use FTP to transfer the exported file, use binary mode.

-import Imports job processing definitions, Calendars, CONTROL-M data, and so


on, from an ASCII text file to the CONTROL-M/EM database.
Syntax:
util DB_ARGS -import [-silent] [-replace]
[-cdbg {1 - 5}] {-type <all | def | cal | sys |dc |
user | alert | gc | maint | collect | view |filter |
log | hier>} {-type net {-name {name}}} [-file file |
-file - | -dir dir | -dir file-list]
Notes:
■ If the database is exported to a file, you are prompted for a filename.
The extension .Z is appended to the filename. When specifying the
name of the file to import, do not include the .Z extension.
■ If you use FTP to transfer the imported file, use binary mode.
■ Stop all CONTROL-M/EM components before doing this operation.

-delete Deletes the specified database table.


Syntax:
util DB_ARGS -delete [-silent]
[-cdbg {1 - 5}]{-name {name}}
Note: Stop all CONTROL-M/EM components before doing this operation.
-clean_database Deletes all database tables.
Syntax:
util DB_ARGS -clean_database [-silent] [-cdbg {1 - 5}]
Notes:
■ This utility completely deletes database tables. Use it only with
extreme caution. BMC Software recommends that you backup the
database before issuing this command.
■ Stop all CONTROL-M/EM components before doing this operation.

-build_schema Builds the CONTROL-M/EM database. It defines the structure and the
type of contents of each data element in the database.
Syntax:
util DB_ARGS -build_schema [-cdbg {1 - 5}]
Note: Stop all CONTROL-M/EM components before doing this operation.

Chapter 7 Database maintenance utilities 161


util

Table 52 util utility – functions (Part 2 of 2)


Function Description
-defexport Exports the specified definition table to an ASCII text file.
Syntax:
util DB_ARGS -defexport [-cdbg {1 - 5}] -table
tablename -dcname dcname [-library library] -file file
Notes:
■ If the database is exported to a file, you are prompted for a filename.
The extension .Z is appended to the filename. When specifying the
name of the file to import, do not include the .Z extension.
■ If you use FTP to transfer the exported file, use binary mode.

-defimport Imports the specified CONTROL-M/EM definition table from an ASCII


text file to a specified database table.
Syntax:
util DB_ARGS -defimport [-replace | -append]
[-cdbg {1 - 5}] [-table new tablename]
[-dcname new dcname] [-library new library] -file file
Notes:
■ If the database is exported to a file, you are prompted for a filename.
The extension .Z is appended to the filename. When specifying the
name of the file to import, do not include the .Z extension.
■ If you use FTP to transfer the imported file, use binary mode.
■ Stop all CONTROL-M/EM components before doing this operation.

Parameters of the util utility functions

Table 53 util utility – function parameters (Part 1 of 3)


Parameter Description
-silent Suppresses application messages.
-replace Overwrites existing data in the specified table.
Note:
Use -replace with extreme caution. Any database element that is replaced is
overwritten with data that you supply in the input file. If -replace is not
specified and the database attempts to write data that already exists, the
utility terminates and a rollback is performed on data written during the
write operation.
-cdbg Debug level. Range from 1 to 5 (highest level).
Use this option only when instructed to do so by BMC Software Customer
Support. Using this option can slow performance and use extra disk space.

162 CONTROL-M/Enterprise Manager Utility Guide


util

Table 53 util utility – function parameters (Part 2 of 3)


Parameter Description
-type Name of the CONTROL-M/EM component that is configured by one or
more of the following:
all All application data. Default.
def Job processing definition data.
cal Calendar data.
sys System data of the application.
dc Data center definition data.
user CONTROL-M/EM user data and authorizations.
alert Alert data for the CONTROL-M/EM database.
gc Global conditions – prerequisite conditions that are passed
between CONTROL-M installations by CONTROL-M/EM.
maint Maintenance tables
collect Collection definitions
view ViewPoint definitions
filter Filter definitions
log Messages saved to a file
hier Hierarchy definitions
Note: More than one -type can be used.
- type net Type of CONTROL-M/EM net.
-name Name of the CONTROL-M/EM net that is identified by the
following parameter:
name – Name of the net. You can use wildcards when
specifying a name:
■ * – represents a string of any length
■ ? – represents one character
Examples:
■ SSIMU – simulation net SIMU
■ A??????23\* – all active nets of netgroup 23

-file Specifies the details of the source or destination file.


file Name of the source or destination file.
-file - ■ Exports to standard output. Default: user monitor
■ Imports from standard input. Default: user keyboard
-dir Exports or imports from a specified directory.
dir – Directory of the source or destination file if different from
CONTROL-M/EM home directory.
file-list – List of text (ASCII) files to be exported or imported,
in the format: filename... filename
-name CONTROL-M/EM net identified by the following name:
name Name of the CONTROL-M/EM net.

Chapter 7 Database maintenance utilities 163


util

Table 53 util utility – function parameters (Part 3 of 3)


Parameter Description
-table Scheduling table identified by the following tablename:
tablename Name of the scheduling table.
-dcname CONTROL-M identified by the following data center name:
dcname Name of the data center.
-library Type of CONTROL-M/EM library identified by the following library type:
library Type of CONTROL-M/EM library.
-append Append the data to the specified table.

Example 1: Export job processing definitions

The following command exports job processing definitions from the default
CONTROL-M/EM database to the ASCII data file production for database user
dbuser1, whose password is secure01:

util -U dbuser1 -P secure01 -export -type def -file production

Example 2: Import calendar data

The following steps are used to import calendar data from the ASCII data file
month_cal to the default CONTROL-M/EM database:

1. Stop all CONTROL-M/EM gateways.

2. Specify the following command:

util -U dbuser1 -P secure01 -import -type cal -file month_cal

Example 3: Delete database contents

The following command deletes the contents of the table A0301190CT_BJOB from
database CITIES:

util -D CITIES -U dbuser1 -P secure01 -delete -name A0301190CT_BJOB

Example 4: Clean the database

The following command cleans database WAGE_RATES:

util -D WAGE_RATES -U dbuser1 -P secure01 -clean_database

164 CONTROL-M/Enterprise Manager Utility Guide


util

Example 5: Build a database schema

The following command builds a new schema for database PAYROLL:

util -D PAYROLL -U dbuser1 -P secure01 -build_schema

Example 6: Export a database definition table

The following command exports the INVENTORY definition table for data center
WIP from the default CONTROL-M/EM database to the file wip_stores:

util -U dbuser1 -P secure01 -defexport -table INVENTORY \


-dcname WIP -file wip_stores

Example 7: Import a database definition table

The following command imports the WORK_IN_PROGRESS definition table


(replacing any data that may have been in this database table) from file wip_stores to
the PRODUCTION database:

util -D PRODUCTION -U dbuser1 -P secure01 -defimport \


-replace -table WORK_IN_PROGRESS -file wip_stores

Chapter 7 Database maintenance utilities 165


util

Transferring CONTROL-M/EM data from CONTROL-M/EM


installations with MSSQL to installations with Oracle
The transfer of CONTROL-M/EM data from an MSSQL database to an Oracle
database might fail, because date formats are not the same on different database
platforms. To resolve this problem, the following steps should be performed on
CONTROL-M/EM installations with an Oracle database, on which you will import
data from CONTROL-M/EM installations with MSSQL:

1 Copy the Defaults.rsc file to Defaults.old. This file is located in the following path:

■ For Unix: EMHome/ appl/ecs1.2/resource


■ For Microsoft Windows: EMHome\Gtwgcs\appl\ecs\resource

EMHome is the directory in which CONTROL-M/EM is installed.

2 To control the way date values are converted, modify, or add, the date format line
in the Defaults.rsc file so that it appears as follows:

Database Oracle DefDateFormat 2

3 Run the util import utility.

4 When the import has completed successfully, restore the Defaults.rsc file by
copying Defaults.old to Defaults.rsc or by removing the date format line added in
step 2.

166 CONTROL-M/Enterprise Manager Utility Guide


Chapter

8
8 Build database utility

build_db (build database) utility


The build_db utility enables you to create a dedicated Sybase database server, define
a CONTROL-M/EM Sybase database, or configure a Sybase database client if they
become corrupted or if you want to move the database to a different server.

The following "build database" modes are available:

Table 54 Build database modes


Default Builds a CONTROL-M Sybase database server, initiates an instance, and
defines a CONTROL-M/EM database on the instance. All build_db
parameters automatically receive the same values they had for the
previously installed CONTROL-M/EM database.
Custom Builds a CONTROL-M Sybase database server, initiates an instance, and
defines a CONTROL-M/EM database on the instance. You must accept the
current value or specify a new value for each build_db parameter.
Existing Defines a CONTROL-M/EM database on an existing Sybase database
server.
Client Configures a Sybase client so it can communicate with a remote Sybase
server. This mode can be used only after the CONTROL-M/EM database has
been defined on the Sybase database server.

Chapter 8 Build database utility 167


Dedicated server creation

Dedicated server creation


The CONTROL-M Sybase database server is designed to function as a database
server exclusively with CONTROL-M products. Ensure that asynchronous IO is
turned on. For more information, see the CONTROL-M Installation Guide.

Dedicated server cleanup


If a CONTROL-M/EM database becomes corrupted but the Sybase database server is
functional, drop the CONTROL-M/EM database and its devices and remove the
device files. If the Sybase database server is also corrupted, stop it and remove the
device files for the CONTROL-M/EM database, and the Sybase master, temporary
database, and sybsystemprocs databases.

Creating a dedicated server


1 If you use the Custom build database mode, determine a value for each build_db
parameter before you begin. These parameters are listed in Table 56 on page 172.
If you are using raw partitions, you must use the Custom mode. For information
about raw partitions see the CONTROL-M/Enterprise Manager Installation Guide.

2 From the command line of the account on which you want to build the Sybase
database server, enter the command: build_db/build_db.sh

3 When asked to select the "CONTROL-M component for which you want to build
the Sybase component", select CONTROL-M/Enterprise Manager.

4 Select one of the following build database modes:

■ Default – Builds a CONTROL-M Sybase database server on the local computer


using the most recently used values for build_db parameters. A CONTROL-M
Sybase client and an empty CONTROL-M/EM database are also created.

■ Custom – Builds a CONTROL-M Sybase database server on the local computer


and enables you to specify the values for build_db parameters. An empty
CONTROL-M/EM database is created.

5 Follow the instructions on the screen, filling in the prompts as necessary. Upon
completion, the following message is displayed:

Installation of CONTROL-M Sybase database component completed successfully.

168 CONTROL-M/Enterprise Manager Utility Guide


Existing server creation

Existing server creation


The Existing build database mode creates a new CONTROL-M Sybase database on
an existing Sybase database server. The existing Sybase database server must be
running during the creation of the CONTROL-M/EM database.

Existing server cleanup


If an existing Sybase database server becomes corrupted, stop it and remove the
device files for that server, the CONTROL-M/EM database, and the Sybase master,
temporary database, and subsystem processes databases.

Verification of existing components


1 Obtain the System Administrator password.

2 Obtain a database name, a System Administrator login name, and a System


Administrator password for the new CONTROL-M/EM database. Use the
sp_helpdb command on the remote server to verify that the database name is
unique for the Sybase database server.

NOTE
When creating more than one database on the same Sybase database server, the database
name and the database owner name must be unique for each database.

3 Verify that the device file you want to define does not exist by running the
command: ls filename on the remote server.

4 Use the following command on the remote server to check the values of the
parameters in Table 55: sp_configure ’parameter_name’. If you change any of these
parameters, the change is not implemented until you restart the database.

Table 55 Sybase database server parameters – minimum values


Small Medium Large
Parameter < 80 MB 80-200 MB > 200 MB
Number of locks 30,000 30,000 40,000
Number of User Connections 60 100 200
Total number of connections to the Sybase database server
required for all applications including CONTROL-M/EM
Max Memory 32, 768 40,000 100,000

Chapter 8 Build database utility 169


Existing server creation

Creating a Sybase database on an existing database server


1 Prepare the information you will need for running the build_db utility.
Parameters for this utility are listed in Table 56 on page 172.

2 From the command line of the account on which the existing Sybase database
server resides, enter the command: build_db/build_db.sh

3 When asked to select the "CONTROL-M component for which you want to install
the Sybase component", select CONTROL-M/Enterprise Manager.

4 Select the Existing build database mode to create an empty CONTROL-M/EM


database on an existing Sybase database server. The name and location of the
existing Sybase database server and the system administrator’s name and
password must be specified.

5 Follow the instructions on the screen, filling in the prompts as necessary. Upon
completion, the following message is displayed:

Installation of CONTROL-M Sybase database component completed successfully.

Existing database cleanup


1 Log in to the Sybase database server as the sa user.

2 Use the sp_helpdb command to determine if the database exists.

3 If the database exists, use the following command to drop (remove) it:

drop database database_name

4 Use the following command to check which devices were dropped from the server:

sp_helpdevice
go

5 If data or log devices associated with the CONTROL-M database are still listed,
drop them using the following command:

sp_dropdevice device_name
go

6 Delete the files, if any, that are associated with the dropped elements.

170 CONTROL-M/Enterprise Manager Utility Guide


Configuring a Sybase client

Configuring a Sybase client


Perform the following steps to configure a Sybase client:

1 Prepare the information you will need before running the build_db utility.
Parameters for this utility are listed in Table 56 on page 172.

2 From the command line of the account on which you want to create the Sybase
database client, enter the command: build_db/build_db.sh

3 When asked to select the "CONTROL-M component for which you want to install
the Sybase component", select CONTROL-M/Enterprise Manager.

4 Select the Client build database mode. This mode configures a CONTROL-M
Sybase database client on the local computer after verifying the existence of a
CONTROL-M/EM database on an existing database server.

5 Follow the instructions on the screen, filling in the prompts as necessary. Upon
completion, the following message is displayed:

Installation of CONTROL-M Sybase database component completed successfully.

Chapter 8 Build database utility 171


build_db parameters

build_db parameters
build_db parameters are described in Table 56. The most recently used value for each
parameter is its default. Determine the required values before running this utility.
Table 56 build_db parameters
Sybase Server Host Name Host name of the computer on which the Sybase Database server is created.
Database Server Password of the CONTROL-M Sybase database server administrator
Administrator Password
Database Name CONTROL-M/EM database name. Maximum length: 30 characters. The
name must begin with an alphabetic character. No spaces are allowed.
Database Owner Login Login name of the CONTROL-M/EM database owner.
Database Owner Password Login password of the CONTROL-M/EM database owner.
Sybase Server Query Port The port that the computer on which the CONTROL-M Sybase database
Number server is created uses for external communication.
Sybase Server Backup Port The port that the CONTROL-M Sybase database backup server
Number component uses for external communication
Master Device Full Path File Full path name of the CONTROL-M Sybase database server.
Name
Sybsystemprocs Device Full Full path name of the CONTROL-M Sybase database server system
Path File Name processes database.
Temporary Device Full Path Full path name of the CONTROL-M Sybase database server temporary
File Name database.
Data Device Full Path File Full path name, including the logical device name, of the CONTROL-M/EM
Name database. You must specify a new filename in an existing directory path on
the computer where the CONTROL-M Sybase database server is created.
Log Device Full Path File Full path name, including the logical device name, of the database log. You
Name must specify a new filename in an existing directory path on the computer
where the CONTROL-M Sybase database server is created.
Database Size Size of the CONTROL-M/EM database in megabytes.
Data Device Size Space in MB for the data portion of the CONTROL-M/EM database.
Log Device Size Space in MB for the transaction log. The recommended amount is 30% of the
space allocated for the CONTROL-M/EM database.
Temporary Device File Size Size of the temporary database in megabytes.

build_db log
After creating the Sybase database components, a build_db log is created in the home
directory of the CONTROL-M/EM account:
home_dir BMCINSTALL/log/DRXX.version_number_user.log
where home_dir is the path of the CONTROL-M/EM user and
version_number is the CONTROL-M/EM version number.

172 CONTROL-M/Enterprise Manager Utility Guide


Appendix

A
A XML File Preparation
Some CONTROL-M/EM utilities require input files written in XML.

XML files have the following characteristics:

■ XML is a structured format for organizing and specifying data.


■ Data in an XML file is classified by type.
■ Words enclosed in angle brackets (< >), called tags, are used to classify and
organize the data.

In the XML files used by the CONTROL-M/EM utilities, tags are used to classify job
processing definition, Calendar, and Scheduling table, and Group Scheduling table
parameters, and their values.

NOTE
You do not need to know XML to use these utilities. The instructions in this chapter provide
you with the information that you need to know to produce all utility files.

Appendix A XML File Preparation 173


CONTROL-M/EM Utility Commands

CONTROL-M/EM Utility Commands


Each utility is composed of a combination of at least two of the following parts:

■ an invocation command
■ an input file containing either data to enter into the CONTROL-M/EM database or
arguments for selecting specific data from the database
■ an output file containing data specified in the arguments file, if it was used
■ optional switches for controlling how the utility runs

For example, the defjob utility has three parts; the invocation command, a file of job
processing definitions that are imported into the CONTROL-M/EM database, and an
optional switch. You prepare the file containing the job processing definitions.

The exportdefjob utility uses an invocation command, a file containing arguments


for specifying the job processing definitions that are exported from the
CONTROL-M/EM database, an optional switch, and an output file containing the
exported job processing definitions. You prepare the arguments file. The output file is
created by the exportdefjob utility.

Preparing an Input File


CONTROL-M/EM utilities read input text files that are used to enter information into
the CONTROL-M/EM database. CONTROL-M/EM export utilities export data from
the database in text files. Both the input and the output files are formatted with XML.

For example, the defcal input file specifies new Calendar definitions to enter into the
database.

NOTE
The indentations used to format the input file help you understand the hierarchical
relationships between elements in the file. These indentations are not mandatory and do not
affect how the file is processed.

File Structure
The different parts of the input file are defined by tags composed of punctuation
marks. The TERMS input file displayed in the example selects all non-cyclic jobs with
job name Job5. The action performed on the selected jobs is determined by the type of
utility that is calling the TERMS file. Using this TERMS file with deldefjob deletes all
job processing definitions in the database for non-cyclic jobs with job name Job5.

174 CONTROL-M/Enterprise Manager Utility Guide


Preparing an Input File

Example

This file contains one TERMS statement. The statement specifies that non-cyclic jobs
with Job Name Job5 are to be selected.

<TERMS>
<TERM>
<PARAM NAME="JOBNAME" OP="EQ" VALUE="Job5"/>
<PARAM NAME="CYCLIC" OP="EQ" VALUE="0"/>
</TERM>
</TERMS>

The statement begins with the word TERMS enclosed in angle brackets (<TERMS>).
The end of the file is indicated by the closing TERMS tag. That this is the end of the
TERMS statement is indicated by the presence of the slash (/), so that the closing
statement looks like </TERMS>.

Between the <TERMS> tags is a search term for identifying and selecting specific job
processing definitions. It is indicated by the tags <TERM></TERM>. Between the
TERM tags are the parameters of the search, indicated by the <PARAM/> tag. All the
attributes of the tag are contained within the single set of brackets. No closing tag is
needed. As a result, the slash (/) is included in the single tag, preceding the closing
angle bracket, <PARAM/>.

As noted, the PARAM tag contains the search terms, NAME, OP, and VALUE.
■ NAME is the name of a job processing definition parameter.

■ OP is an operator. The most common operators are described in Table 57.

■ VALUE is the value of the parameter to which a comparison is being made.

EXAMPLE
NAME="JOBNAME" OP="EQ" VALUE="Job5" searches for job processing definitions
that have the Job Name, Job5.

Table 57 Utility Operators


Operator Description
EQ Equals. Select cases that include the specified value.
NEQ Not equal. Select cases that include any value different from the one specified.
LIKE Similar. Select cases that have an attribute common to the one specified.
Note: You must use a wildcard, such as * in the value that you specify.
For example:
JOBNAME LIKE="JOB1*"
selects all jobs with a job name that begins with JOB1. JOB13 would be selected,
but not JOB25.
NOTIN Not including. Exclude cases that include the specified value.

Appendix A XML File Preparation 175


Preparing an Input File

What to Include in the File


Each utility is described in this book with a table of elements (job, calendar, and table
parameters) and attributes (subparameters). Use the valid values described in the
tables, making sure to use the same case and spelling.

If the valid value is a string, see the description of the appropriate parameter in the
CONTROL-M Job Parameter and Variable Reference Guide for information about valid
values and their formats.

Validating Your File

The contents of an XML file are determined by a set of criteria that are contained in a
document definition type file. This file has a .dtd extension.

The .dtd file is used by CONTROL-M/EM to validate the input file (or arguments file)
when the utility runs.

The .dtd file includes the following information:


■ Names of all of the elements and attributes that can be entered in an input or
arguments file in XML format.
■ Valid values for an element or attribute.

■ Whether the valid values for an element or attribute are mandatory or optional.

■ Hierarchical relationship between the various elements and attributes in the file.

Formatting and value information for CONTROL-M parameters is described in the


CONTROL-M Job Parameter and Variable Reference Guide.

CONTROL-M/EM Utility .dtd Files

Each utility input file has its own .dtd file. The TERMS arguments files share the same
.dtd file. Utility .dtd files are stored in the CONTROL-M/EM_home\ecscli\Resource
directory (on Microsoft Windows).

Table 58 CONTROL-M/EM utility .dtd files


File Name Description
copycal.dtd Validates the copydefcal input file.
copyjob.dtd Validates the copydefjob input file.
defcal.dtd Validates the defcal input file.
defjob.dtd Validates the defjob input file.
deftable.dtd Validates the deftable input file.
duplicatejob.dtd Validates the duplicatedefjob input file.
terms.dtd Validates exportdefjob, exportdefcal, and exportdeftable argument files.
update.dtd Validates the updatedef input file.

176 CONTROL-M/Enterprise Manager Utility Guide


Preparing an Input File

To create a file:

1 Open any text editor or an XML editor.

2 Enter the data for the utility that you are using, the format described in the
parameter description tables, and examples that are provided with the utility.

3 Check the syntax of the file for errors. If errors remain, they are identified when the
file is submitted to the utility. Possible errors include:

■ Misplaced or missing tag.


■ Misplaced or missing part of a tag (for example, a missing slash /).
■ Parameter value that is not specified as a valid value for that parameter (for
example, the letter Y instead of a 1.
in

NOTE
CONTROL-M/EM validates every file you submit, rejecting those that have errors. When a
file is rejected, the lines containing errors are specified for you.

4 Save the file.

NOTE
The file must be saved as a text file. It can have any file extension you want, but .xml is
recommended.

Reserved Characters
Certain characters are reserved for formatting the XML file. These characters cannot
be used in job parameter values submitted with the XML-based utilities.

Instead, each reserved character must be replaced by a code. The reserved characters
and the codes they are replaced by are listed in Table 59.

Table 59 Reserved character codes


Character Replacement Code
" (double-quote) &quot;
’ (single-quote, apostrophe) &apos;
< (left-angle bracket) &lt;
> (right-angle bracket) &gt;
& (ampersand) &amp;
Note: The ampersand character can be used in the character
replacement codes.

Appendix A XML File Preparation 177


Preparing an Input File

Example: Using reserved character codes in an XML file.

Incorrect:

INCOND NAME="if5<6’run’" ODATE="ODAT" AND_OR="AND" OP="("/

Correct:

INCOND NAME="if5&lt;6&apos;run&apos;" ODATE="ODAT" AND_OR="AND"


OP="("/

Wildcards
Multiple jobs can be selected and copied using the * (asterisk) wildcard character to
represent multiple values. The asterisk is used to represent zero or more
alphanumeric characters. An asterisk can be used to replace characters in the middle
of an expression.

NOTE
Only one asterisk can be used in an expression.

The Asterisk in Search Criteria

Example 1

The job name of a specific job definition is AAABBB. If you include the any of the
following arguments in an updatedef utility argument file, you select job AAABBB:

<JOB_NAME FROM="AAABBB"/>
<JOB_NAME FROM="*BBB"/>
<JOB_NAME FROM="AAA*"/>

Example 2

There are three job processing definitions. Their Job Names are:

AAABBB, AAACCC, and BBBCCC

The following argument selects jobs AAACCC and BBBCCC, and selects any other
jobs with a Job Name that ends with the letters CCC.

<JOB_NAME FROM="*CCC"/>

178 CONTROL-M/Enterprise Manager Utility Guide


Preparing an Input File

The Asterisk in Find/Replace Operations

The asterisk has a special function when used in "find and replace" operations in
selected utilities. The following utilities use find and replace operations:
■ copydefcal

■ copydefjob

■ duplicatedefjob

■ updatedef

In the FROM (find) statement of an argument, an asterisk replaces a text string


(as shown in the example above). The asterisk in the TO statement of the argument
represents the same string as the asterisk in the FROM statement of the argument.
The placement of the asterisk can be changed.

Example 1

There are three job processing definitions. Their Job Names are:

AAABBB, AAACCC, BBBCCC

Modify the job names of some of these jobs using the following argument:

<JOB_NAME FROM="*CCC" TO="*DDD"/>

■ Job AAACCC becomes Job AAADDD


■ Job BBBCCC becomes Job BBBDDD
■ Job AAABBB is not modified.

Example 2

There are three job processing definitions. Their Job Names are:

AAABBB, DDDCCC, BBBCCC

<JOB_NAME FROM="*CCC" TO="DDD*"/>

■ Job DDDCCC becomes Job DDDDDD


■ Job BBBCCC becomes Job DDDBBB
■ Job AAABBB is not modified.

Appendix A XML File Preparation 179


Preparing an Input File

180 CONTROL-M/Enterprise Manager Utility 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
util utility parameters 160
- type net build_db utility 167
util utility function parameters 163 -build_schema
util utility functions 161
building
Symbols CONTROL-M/EM database 165
building a CONTROL-M/EM database
* 178 util utility 159
.dtd file
CONTROL-M/EM Utility .dtd Files 176
description 176
validating XML files 176
C
calendars
cli utility 20
A copying 113
downloading 20
administration agents exporting 118
shutdown using ctl 152 handling using the cli utility 20
stopping using ctl 146, 148, 149, 151, 152, 153 importing 108
alert processing uploading 20
gateway check errors 140 -cdbg
-append util utility function parameters 162
util utility function parameters 164 check_gtw utility
application support description 140
Oracle Applications 13 invoking 140
SAP 13 parameters 140, 141
AS/400. See iSeries (AS/400) test mode 140
asterisk check_gtw_ue user exit 141
as a wildcard in Find/Replace operations 179 -clean_database
as a wildcard in search criteria 178 util utility functions 161
using as a wildcard 178 cleaning
AUTHOR parameter ENTERPRISE/CS database 164
copydefjob utility 42 cleanup
defjob utility 27 corrupted database 168
deftable utility 126 clearing a database
duplicatedefjob utility 65 util utility 159
authorization 14 cli utility 17
invoking 17
job deletion parameters 22
B parameters 18
Client mode
Batch Impact Manager server build_db utility 167, 171
ctl utility 153 command line interface
BMC Software, contacting 2 batch utility 17
build database utility 167 parameter formats 12
build_db log 172 configuration
build_db parameters 172 Sybase client 171

Index 181
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/EM administrator
password encryption 142 D
CONTROL-M/EM components Data Device Full Path File Name parameter
shutdown using ctl 152 build_db utility 172
stopping using ctl 146, 148, 149, 151, 152, 153 Data Device Size parameter
CONTROL-M/EM database build_db utility 172
building 165 Database Name parameter
check size with db_check 156, 157 build_db utility 172
transaction log monitoring with db_check 156 Database Owner Login parameter
verify integrity with db_check 156 build_db utility 172
conventions 11 Database Owner Password parameter
converting build_db utility 172
Scheduling table to Group Scheduling table 52 Database Server Administrator Password parameter
copydefcal utility 113 build_db utility 172
arguments file 114 Database Size parameter
copycal.dtd 176 build_db utility 172
copyjob.dtd 176 databases
examples 116 arguments parameter (db_args) 160
invoking 113 db threshhold % parameter 156
parameters 116 db_args parameter
rules 114 util utility 160
copydefjob utility 38 db_check utility 156, 157
arguments file 39 db threshhold % parameter 156
AUTHOR parameter 42 log threshold % parameter 156
examples 51 db_check utility functions
invoking 38 check available database space 156
rules 40 report database size 156
copying transaction log monitoring 156
calendar definitions 113 verify database integrity 156
job definitions 38, 61 db_check_space utility 157
jobs to a Group Scheduling table 52 db_check_space utility functions
corrupted database check available database space 157
cleanup 168 check available database space as a percentage of total
creating database size 157
calendar definitions 108, 113 report database size 157
job definitions 24, 38, 61 -dcname
creation util utility function parameters 164
dedicated Sybase server 168 debugging
existing Sybase server 169 Keep Alive messages 146
Sybase database 170 util utility 162
cryptocli dedicated Sybase server
operational mode 142 creation 168
trial mode 142 Default mode
ctl build_db utility 167
-cmd command switch 146, 148, 149, 151, 152, 153 build_db utillity 168
command syntax 144 Defaults.rsc file
description 144 updating 166
Global Alerts Server 151 defcal utility 108
Global Conditions Server 147 defcal.dtd 176
GUI server 149, 153 examples 111
parameter descriptions 144 input file 109
shutdown command 152 invoking 108
stop command description 146, 148, 149, 151, 152, 153 -defexport
Custom mode util utility functions 162
build_db utility 167 -defimport
build_db utillity 168 util utility functions 162
customer support 3 defining

182 CONTROL-M/Enterprise Manager Utility 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

seealso creating
defjob utility 24 E
AUTHOR parameter 27 emenablepriv utility 15
defjob.dtd 176 EnableAuthorEdit 25, 39, 62, 83, 123
example 37 EQ
switches 25 utility operator 175
defjobconvert examples
examples 56 copydefcal utility 116
defjobconvert utility copydefjob 51
invoking 55 defcal utility 111
messages 55 defjob 37
deftable utility 122 defjobconvert 56
AUTHOR parameter 126 deftable utility 132
deftable.dtd 176 deldefjob 59
examples 132 duplicatedefjob utility 77
input file 123 exportdefcal utility 120
invoking 122 exportdeftable utility 138
parameters 123, 124, 125 util utility 164
rules 124 existing components
switches 123 verification 169
deldefjob utility 57 Existing mode
arguments file 58, 62 build_db utility 167, 169, 170
examples 59 existing Sybase server
invoking 57 creation 169
parameters 58 -export
rules 58 util utility functions 161
-delete exportdefcal utility 118
util utility functions 161 arguments file 119
deleting examples 120
from CONTROL-M/EM database 164 invoking 118
job definitions 22 parameters 120
jobs definitions (in batch) 57 rules 119
parameters of the cli utility 22 terms.dtd 176
deleting a database exportdefjob utility 78
util utility 159 invoking 78
documentation parameters 80
accessing online 11 rules 79
conventions 11 terms.dtd 176
online 10 exportdeftable utility 135
printed 10 arguments file 136
related publications 10 examples 138
downloading invoking 135
calendars 20 parameters 137
Scheduling tables 19 exporting
drop database command 170 a definition table 165
duplicatedefjob utility 61 calendars 118
arguments file 62 from CONTROL-M/EM database 164
AUTHOR parameter 65 job processing definitions 78
duplicatejob.dtd 176 Scheduling tables 135
examples 77 exporting database data
invoking 61 util utility 159
rules 63 exporting database definition table
switches 62 util utility 159

Index 183
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

F exportdefcal utility 118


exportdefjob 78
-file exportdeftable utility 135
util utility function parameters 163 updatedef 82
forcing util utility 159
into a Group Scheduling table 21
job 20
using the cli utility 19, 20
format
J
CONTROL-M/EM utilities 173 job
forcing 20
ordering with the cli utility 21

G job definition
deleting by Mem Name 22
Gateway job definitions
unavailable 141 deleting 22
gateways modifying with updatedef 82
checking (check_gtw) 140 job processing definitions
Global Alerts Server deleting 57
ctl utility 151 exporting 78
Global Conditions Server updating 82
ctl utility 147 JOBISN value 24
Group Scheduling table jobs
copying jobs from a Scheduling table 52 copying 38, 61
forcing a job into 21 creating 24
Group Scheduling tables
modifying with updatedef 82
updating 82
group scheduling tables
L
importing 122 -library
updating 82 util utility function parameters 164
GUI server life check
ctl utility 149 ctl 146, 148, 149, 151, 152, 153
LIKE
utility operator 175

I Log Device Full Path File Name parameter


build_db utility 172
-import Log Device Size parameter
util utility functions 161 build_db utility 172
importing log file
calendar definitions 108 build_db utility 172
definition tables 165 log threshold % parameter 156
job definitions 24 ls filename command 169
Scheduling tables 122
to CONTROL-M/EM database 164
importing database data
util utility 159
M
importing database definition table Master Device Full Path File Name parameter
util utility 159 build_db utility 172
invoking Max Memory parameter
copydefcal utility 113 minimum values 169
copydefjob 38 mcs.ini
defcal 108 cryptocli password modification 142, 143
defjobconvert 55 password encryption 143
deftable utility 122 Mem Name parameter 22
deldefjob 57 migrate_dc utility 15
duplicatedefjob 61 modes
build_db utility 167

184 CONTROL-M/Enterprise Manager Utility 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

modifying Custom mode 168


see also creating -replace
password 142 util utility function parameters 162
updatedef 82 rules
monitoring copydefcal utility 114
database log 156 deftable utility 124
transaction log 156 duplicatedefjob utility 63
mySAP. See SAP exportdefcal utility 119
exportdefjob 79

N
-name
S
util utility function parameters 163 SAP
NEQ application support 13
utility operator 175 Scheduling table
NOTIN copying jobs to a Group Scheduling table 52
utility operator 175 Scheduling tables
Number of locks parameter downloading 19
minimum values 169 exporting 135
Number of User Connections parameter forcing 19
minimum values 169 importing 122
modifying with updatedef 82
ordering 20
O updating 82
uploading 19
Oracle Applications security
application support 13 cryptocli utility 142, 143
ordering -silent
Scheduling tables 20 util utility function parameters 162
using the cli utility 21 sp_configure ’parameter_name’ command 169
sp_dropdevice device_name command 170
sp_helpdb command 169, 170
P sp_helpdevice command 170
starting
parameter formats gateway debug message truncation 146
command line interface 12 gateway host debug messages 146
long format 12 stopping
short format 12 administration agent using ctl 146, 148, 149, 151, 152,
parameters 153
buiold_db utility 172 component using ctl 146, 148, 149, 151, 152, 153
copydefcal utility 116 ctl shutdown command 152
deftable utility 124, 125 ctl stop command 146, 148, 149, 151, 152, 153
deldefjob 58 gateway debug message truncation 146
exportdefcal utility 120 support, customer 3
exportdefjob 80 Sybase client
exportdeftable utility 137 configuration 171
updatedef 84, 85, 90 Sybase database
util utility 160 creation 170
passwords Sybase database server
encryption 142 creation 168
product support 3 parameters 169
Sybase Server Backup Port Number parameter
build_db utility 172
R Sybase Server Host Name parameter
build_db utility 172
R/3. See SAP
Sybase Server Query Port Number parameter
raw partitions

Index 185
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

build_db utility 172 deleting a database 159


sybsystemprocs databases 168 -export 161
Sybsystemprocs Device Full Path File Name parameter exporting database data 159
build_db utility 172 exporting database definition table 159
-import 161
importing database data 159
T importing database definition table 159
util utility parameters
-table 160
util utility function parameters 164 utilities
technical support 3 authorization 14
Temporary Device File Size parameter check_gtw 140
build_db utility 172 command line interface 17
Temporary Device Full Path File Name parameter copydefcal 113
build_db utility 172 copydefjob 38
transferring definition tables 166 cryptocli 142
truncating ctl 144
gateway debugging messages using ctl 146 db_check 156
-type db_check_space 157
util utility function parameters 163 defcal 108
defjob 24
deftable 122
U deldefjob 57
description 13
updatedef utility 82 duplicatedefjob 61
invoking 82 emenablepriv 15
parameters 84, 85, 90 exportdefcal 118
switches 83 exportdefjob 78
update.dtd 176 exportdeftable 135
uploading file structure 174
calendars 20 format 173
Scheduling tables 19 migrate_dc 15
util utility 159 operators list 175
debugging with 162 preparing an XML input file 174
examples 164 updatedef 82
invoking 159 using XML input files 14, 173
parameters 160 util 159
util utility function parameters utility commands 174
-append 164 utility operators
-cdbg 162 EQ 175
-dcname 164 LIKE 175
-file 163 NEQ 175
-library 164 NOTIN 175
-name 163
-replace 162
-silent 162
-table 164 V
-type 163 validating
-type net 163 .dtd file 176
util utility functions XML files 176
build_schema 161 verification
building a CONTROL-M/EM database 159 existing components 169
-clean_database 161 verifying database integrity
clearing database data 159 with db_check utility 156
-defexport 162
-defimport 162
-delete 161

186 CONTROL-M/Enterprise Manager Utility 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

W
Western European language, special characters 41, 64, 85,
124, 125
wildcard
asterisk 178
in Find/Replace operations 179
in search criteria 178

X
XML
creating a file 177
examples 175
file structure 174
use in utilities 14, 177
utility format 173

Index 187
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

188 CONTROL-M/Enterprise Manager Utility Guide


Notes
*52302*
*52302*
*52302*
*52302*
*52302*