CM Enterprise Manager Utility Guide

CONTROL-M /Enterprise Manager Utility Guide
Version 6.1.01
June 20, 2002
Copyright 2002 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 Corp. All other registered trademarks or trademarks belong to their respective companies.
THE USE AND CONTENTS OF THIS DOCUMENTATION ARE GOVERNED BY THE SOFTWARE LICENSE AGREEMENT ENCLOSED AT THE BACK OF THIS DOCUMENTATION.
Restricted Rights Legend

U.S. GOVERNMENT RESTRICTED RIGHTS. UNPUBLISHEDRIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure by the U.S. Government is subject to restrictions set forth in FAR Section 52.227-14 Alt. III (g)(3), FAR Section 52.227-19, DFARS 252.227-7014 (b), or DFARS 227.7202, as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.
Contacting BMC Software

You can access the BMC Software Web site at http://www.bmc.com. From this Web site, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada

Address BMC Software, Inc. 2101 CityWest Blvd. Houston TX 77042-2827 713 918 8800 or 800 841 2031 713 918 8000
Outside United States and Canada

Telephone Fax (01) 713 918 8800 (01) 713 918 8000
Telephone Fax
Customer Support
You can obtain technical support by using the Support page on the BMC Software Web site or by contacting Customer Support by telephone or e-mail. To expedite your inquiry, please see Before Contacting BMC Software.
Support Web Site

You can obtain technical support from BMC Software 24 hours a day, 7 days a week at http://www.bmc.com/support.html. From this Web site, you can read overviews about support services and programs that BMC Software offers find the most current information about BMC Software products search a database for problems similar to yours and possible solutions order or download product documentation report a problem or ask a question subscribe to receive e-mail notices when new product versions are released find worldwide BMC Software support center locations and contact information, including e-mail addresses, fax numbers, and telephone numbers
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. Outside the United States and Canada, please contact your local support center for assistance. To find telephone and e-mail contact information for the BMC Software support center that services your location, refer to the Contact Customer Support section of the Support page on the BMC Software Web site at www.bmc.com/support.html.
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
BMC Software, Inc., Confidential and Proprietary Information
iii
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
iv
CONTROL-M/Enterprise Manager Utility Guide
Contents
Contents
About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Chapter 1 Introduction
Utilities Described in this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Utilities Not Described in this Book . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Chapter 2 Chapter 3 Command Line Interface Utility (cli) Job Utilities
defjob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 copydefjob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24 Copy Jobs in a Scheduling Table to a Group Scheduling Table . 3-43 defjobconvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-45 deldefjob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-48 duplicatedefjob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-54 exportdefjob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-80 updatedef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-85
Chapter 4 Calendar Utilities
defcal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 copydefcal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8 exportdefcal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13

Chapter 5 Scheduling Table Utilities
deftable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 exportdeftable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22
Contents
Chapter 6
Database Maintenance Utilities
db_check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-2 util . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-4 Transferring Definition Tables between Database Systems . . . .6-13
Chapter 7 Administration Utilities
check_gtw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2 cryptocli . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-4 ctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-6

Appendix A XML File Preparation
CONTROL-M/EM Utility Commands . . . . . . . . . . . . . . . . . . . . . . A-1 Preparing an Input File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2

Index
Tables
Tables
Table 1-1 Table 1-2 Table 2-1 Table 2-2 Table 3-1 Table 3-2 Table 3-3 Table 3-4 Table 3-5 Table 3-6 Table 3-7 Table 3-8 Table 3-9 Table 3-10 Table 3-11 Table 3-12 Table 3-13 Table 3-14 Table 3-15 Table 3-16 Table 4-1 Table 4-2 Table 4-3 Table 4-4 Table 4-5 Table 4-6 Table 4-7 Table 5-1 Utility Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Utilities Not Included in this Book . . . . . . . . . . . . . . . . . . . . . . cli Utility Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cli Utility Job Deletion Parameters . . . . . . . . . . . . . . . . . . . . . . Job Definition Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . defjob Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . defjob Input File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . copydefjob Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . copydefjob Arguments File Parameters . . . . . . . . . . . . . . . . . . . defjobconvert Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deldefjob Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deldefjob Arguments File Parameters . . . . . . . . . . . . . . . . . . . . duplicatedefjob Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . duplicatedefjob Arguments File Parameters . . . . . . . . . . . . . . . exportdefjob Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . exportdefjob Arguments File Parameters . . . . . . . . . . . . . . . . . updatedef Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Arguments File Parameters for Scheduling Tables . . . . . . . . . . Arguments File Parameters for Group Scheduling Tables. . . . . Arguments File Parameters for Jobs . . . . . . . . . . . . . . . . . . . . . Table Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . defcal Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . defcal Input File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . copydefcal Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . copydefcal Arguments File Parameters . . . . . . . . . . . . . . . . . . . exportdefcal Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . exportdefcal Arguments File Parameters . . . . . . . . . . . . . . . . . . Table Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 1-4 2-2 2-9 3-2 3-4 3-5 3-25 3-27 3-46 3-49 3-50 3-55 3-57 3-81 3-82 3-86 3-88 3-89 3-96 4-1 4-2 4-4 4-9 4-10 4-14 4-15 5-1
Tables
Table 5-2 Table 5-3 Table 5-4 Table 5-5 Table 5-6 Table 6-1 Table 6-2 Table 6-3 Table 6-4 Table 6-5 Table 6-6 Table 7-1 Table 7-2 Table 7-3 Table 7-4 Table A-1 Table 1-2 Table A-3
deftable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deftable Input File Parameters for Scheduling Tables . . . . . . . . deftable Input File Parameters for Group Scheduling Tables. . . exportdeftable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . exportdeftable Arguments File Parameters . . . . . . . . . . . . . . . . Database Maintenance Utilities . . . . . . . . . . . . . . . . . . . . . . . . . db_check Utility parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . Fields of the Database Arguments Parameter <DB_ARGS>. . . util Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . util Utility Function Parameters . . . . . . . . . . . . . . . . . . . . . . . Date Format Specifications in Defaults.rsc . . . . . . . . . . . . . . . . Administration Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . check_gtw Utility Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . ctl Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ctl Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Utility Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONTROL-M/EM Utility .dtd Files . . . . . . . . . . . . . . . . . . . . . Reserved Character Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5-4 5-5 5-6 5-23 5-24 6-1 6-3 6-5 6-6 6-9 6-13 7-1 7-2 7-7 7-9 A-4 A-5 A-7
About . . .
About This Book

This book contains detailed information about the batch utilities supplied with CONTROL-M/Enterprise Manager (CONTROL-M/EM). Use this book with the CONTROL-M/Enterprise Manager User Guide (version 6.1.01), CONTROL-M/Enterprise Manager Administrator Guide (version 6.1.01), CONTROL-M/Enterprise Manager Installation Guide (version 6.1.01), CONTROL-M Job Parameter and AutoEdit Variable Reference Guide (version 6.1.01), and CONTROL-M/Desktop User Guide (version 6.1.01)
Note
It is assumed that you are familiar with your host operating system.
How This Book Is Organized

This book describes CONTROL-M/Enterprise Manager batch utilities. This book is organized as follows. In addition, an index appears at the end of the book.
About This Book
Chapter
Chapter 1
Description
Introduction Provides an overview of CONTROL-M/Enterprise Manager batch utilities. Command Line Interface Utility (cli) Describes the cli utility and the means for invoking it. Job Utilities Describes the utilities for creation and manipulation of job processing definitions. Calendar Utilities Describes the utilities for creation and manipulation of Calendar definitions. Scheduling Table Utilities Describes the utilities for creation and manipulation of Scheduling table and Group Scheduling table definitions. Database Maintenance Utilities Describes the database management utilities and the means for invoking them. Administration Utilities Describes various CONTROL-M/EM component administration utilities and the means for invoking them. XML File Preparation Describes the procedures for creating input and argument files for XML-based utilities.
Chapter 2 Chapter 3
Chapter 4
Chapter 5
Chapter 6
Chapter 7
Appendix A
Related Documentation
The following BMC publications are relevant to CONTROL-M/Enterprise Manager. CONTROL-M/Enterprise Manager User Guide describes CONTROL-M/Enterprise Manager 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 the tasks that the CONTROL-M/Enterprise Manager administrator must perform to define, monitor, and maintain the CONTROL-M/Enterprise Manager environment. CONTROL-M 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 Guides are supplied for various CONTROL-M platforms (for example, Unix and Microsoft Windows). These guides describe installation, setup, security, and utilities. CONTROL-M User Manual for OS/390 is a complete guide to the CONTROL-M Production Control System in a mainframe environment.
About This Book
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 To Access Online Books. You can also obtain additional printed books from BMC Software, as explained in To Request Additional Printed Books.
To 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.)
To 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
Net $HOME, <home-directory>
Description
CONTROL-M/Enterprise Manager Network Directory in which CONTROL-M/Enterprise Manager is installed
The following conventions are used in this guide:

<key> When describing keystrokes, angle brackets are used to enclose the name of a key (for example, <F1>). When two keys are joined with + as in <Shift>+<F1>, hold down <Shift> while pressing <F1>. 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. {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] Code Samples Square brackets are used to enclose parameters that are optional. Format syntax, operating system terms, examples, and JCL scripts are presented in this typeface. In instructions, boldface type highlights information that you enter. File names, directory names and paths, dialog box and window names, and Web addresses also appear in boldface type.
Menu => Option
Boldface
About This Book
Italics
Italic type is used to emphasize important terms. The titles of BMC Software product documentation are also displayed in italic type. The symbol
One-Step Procedures Ellipsis
denotes one-step instructions.
An ellipsis ( . . . ) indicates that you can repeat the preceding item or items as many times as necessary. 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
Option Symbol
Introduction
Utilities are programs that enable you 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. Furthermore, 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 User Guide for the appropriate CONTROL-M Control Module.
Introduction
1-1
Utilities Described in this Book

The types of utilities described in this book are listed in Table 1-1, Utility Types, on page 1-2. Many CONTROL-M/Enterprise Manager 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/Enterprise Manager user name and password are required to run all CONTROL-M/EM utilities. Additionally, you must have the appropriate authorization to either copy from or modify entities in CONTROL-M/Enterprise Manager. For more information about authorization, see the Security chapter in the CONTROL-M/Enterprise Manager Administrator Guide.
Table 1-1
Utility Types (Part 1 of 2)
Type
Command Line Interface Utility
Description
The Command Line Interface (cli) is a batch utility that enables you to perform the following operations (services) from the command line: Upload/Download Scheduling tables Order/Force Scheduling tables Order/Force jobs Force jobs in a Group Scheduling table Upload/Download Calendars Delete job processing definitions from Scheduling tables For information about cli, see Chapter 2, Command Line Interface Utility (cli). You can create, modify, and delete job processing definitions with the utilities described in Chapter 3, Job Utilities. You can create and modify Calendar definitions with the utilities described in Chapter 4, Calendar Utilities. You can create and modify Scheduling table and Group Scheduling table definitions with the utilities described in Chapter 5, Scheduling Table Utilities.
Job Utilities
Calendar Utilities Scheduling Table Utilities
1-2
Table 1-1
Utility Types (Part 2 of 2)
Type
Database Maintenance Utilities Administration Utilities
Description
You can maintain the CONTROL-M/Enterprise Manager database using the utilities described in Chapter 6, Database Maintenance Utilities. You can monitor and manage selected elements of CONTROL-M/EM operation using the utilities described in Chapter 7, Administration Utilities.
Utilities Not Described in this Book

CONTROL-M/Enterprise Manager includes a number of utilities that are used infrequently, often only under very specific conditions. These utilities are described briefly together with the procedures in which they are used
Introduction
1-3
Table 1-2
Utilities Not Included in this Book
Utility Name
convert_dc
Description
Enables CONTROL-M/Server for Unix installations that have not been upgraded to version 6.0.0x or 6.1.0x and non-Unix CONTROL-M installations to read and create conditions that can be recognized by upgraded CONTROL-M installations by converting the parentheses () characters in condition names and inglobal condition prefixes to a supported character. Note: This utility is used only when working in an environment where one or more CONTROL-M/Server for Unix installations has been upgraded to version 6.0.0x or 6.1.0x. CONTROL-M installations that have not been upgraded may have operations dependent on conditions distributed by the upgraded CONTROL-M installations. To synchronize the condition definition process in the two environments, the convert_dc utility must be run. For more information, see the CONTROL-M/Enterprise Manager Installation Guide. Opens the Windows Task Manager window with the privileges required to stop ENTERPRISE/CS processes. For more information, see the CONTROL-M/Enterprise Manager Administrator Guide. Migrates job processing definitions for CONTROL-M installations (on Unix computers) that have been upgraded to version 6.0.0x or later, in the CONTROL-M/EM database. Note: This utility is used only when you are upgrading on ore more of your CONTROL-M installations (on Unix computers) to version 6.0.0x or later. For more information, see the CONTROL-M/Enterprise Manager Installation Guide.
enablepriv
migrate_dc
1-4
Command Line Interface Utility (cli) 2

The Command Line Interface (cli) is a batch utility that enables you to perform the following operations (services) from the command line: Upload/Download Scheduling tables Order/Force Scheduling tables Order/Force jobs Force jobs in a Group Scheduling table Upload/Download Calendars Delete job processing definitions from Scheduling tables
The cli utility can be used on Unix and Microsoft Windows computers. The cli 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 cli can also be performed in real-time using the CONTROL-M/Enterprise Manager 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/Enterprise Manager home directory. 2. Specify the following command:
Command Line Interface Utility (cli)
2-1
Microsoft Windows cli -U <user id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] [-BY_FORCE] <-service> <service_parameters> [<-service> <service_parameters>...] Unix
ecs cli -U <user id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] [-BY_FORCE] <-service> <service_parameters> [<-service> <service_parameters>...]
The parameters in the above commands are described in Table 2-1.

Table 2-1 cli Utility Parameters (Part 1 of 2)
Parameter <user_id> <password> <host_name>

<timeout>
Description
CONTROL-M/Enterprise Manager user name. CONTROL-M/Enterprise Manager user password. Host name of the workstation running the CONTROL-M/Enterprise Manager Server. 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). If specified, reverses format of <Odate> as described below. Name of the service. See <service_parameters>.
-DDMM
<service>
2-2
Table 2-1
cli Utility Parameters (Part 2 of 2)
Parameter <service _parameters>
Description
Service parameters used in the utility:
<control-m> <table> <calendar> <job_name> <Odate>
Name of the CONTROL-M installation. Name of the Scheduling table. Name of the Calendar. Name of the job. 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 version 6.0.0x jobs and later. [OS/390 only] Library containing the table. Forces the specified table or calendar. Use this option during upload only.
<library>
-BY_FORCE
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.
2-3
Following are a series of commands that enable you to perform various tasks.
To upload a Scheduling table: Microsoft Windows cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] -TABLE_UPLOAD <control-m> <table> [<Odat>] [<library>] Unix
ecs cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] -TABLE_UPLOAD <control-m> <table> [<Odat>] [<library>] To download a Scheduling table: Microsoft Windows cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] -TABLE_DOWNLOAD <control-m> <table> [<library>] Unix
ecs cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] -TABLE_DOWNLOAD <control-m> <table> [<library>] To force a Scheduling table: Microsoft Windows cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] -TABLE_FORCE <control-m> <table> [<Odate>][<library>]
2-4
Unix ecs cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] -TABLE_FORCE <control-m> <table> [<Odate>][<library>] To order a Scheduling table: Microsoft Windows cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] -TABLE_ORDER <control-m> <table> [<Odate>][<library>] Unix
ecs cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] -TABLE_ORDER <control-m> <table> [<Odate>][<library>] To upload a Calendar: Microsoft Windows cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] -CAL_UPLOAD <control-m> <calendar> Unix
ecs cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] -CAL_UPLOAD <control-m> <calendar> To download a Calendar: Microsoft Windows cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] -CAL_DOWNLOAD <control-m> <calendar>
2-5
Unix ecs cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] -CAL_DOWNLOAD <control-m> <calendar> To force a job: Microsoft Windows cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] -JOB_FORCE <control-m> <table> <job_name> [<Odate>][<library>] Unix
ecs cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] -JOB_FORCE <control-m> <table> <job_name> [<Odate>][<library>] To force a job into a Group Scheduling table: Microsoft Windows cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] -JOB_FORCE_INTO <control-m> <table> <job_name> <sched_group> [<duplication>] [<Odate>][<library>] Unix
ecs cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] -JOB_FORCE_INTO <control-m> <table> <job_name> <sched_group> [<duplication>] [<Odate>][<library>]
2-6
<sched_group>
Group Scheduling table into which the job is forced. Possible tables are: RECENT Forces the job into the Group Scheduling table that was run most recently. Creates a new Group Scheduling table. Forces the job without adding it to a Group Scheduling table. Specific Group Scheduling table into which the job is forced.
NEW STANDALONE <GROUPID>
[<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: Microsoft Windows cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] -JOB_ORDER <control-m> <table> <job_name> [<Odate>][<library>] Unix
ecs cli -U <user_id> -P <password> -H <host_name> [-T <timeout>] [-DDMM] -JOB_ORDER <control-m> <table> <job_name> [<Odate>][<library>] 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.
2-7
To delete a job definition by Job Name: Microsoft Windows
cli -U <user_id> -P <password> -H <host_name> -JOB_DELETE <control-m> <table> <job_name> <delete_type> [<library>] Unix
ecs cli -U <user_id> -P <password> -H <host_name> -JOB_DELETE <control-m> <table> <job_name> <delete_type> [<library>] To delete a job definition by Mem Name: Microsoft Windows cli -U <user_id> -P <password> -H <host_name> -MEM_DELETE <control-m> <table> <mem_name> <delete_type> [<library>] Unix
ecs cli -U <user_id> -P <password> -H <host_name> -MEM_DELETE <control-m> <table> <mem_name> <delete_type> [<library>]
Table 2-2 describes the parameters of the above delete commands.
2-8
Table 2-2
cli Utility Job Deletion Parameters
Parameter <delete type>
Description
Indicates the type of operation to be performed for the service. Valid values:
ALL
All occurrences of the job are deleted, if there is more than one job with the same name. No jobs are deleted if there is more than one job with the same name.
NONE
<sequence number> <library>
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). Required for OS/390 job definitions.
2-9
2-10
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/Enterprise Manager 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 3-1.
Job Utilities
3-1
Table 3-1
Job Definition Utilities
Utility
defjob copydefjob
Description
Imports a job processing definition directly into a Scheduling table. (See page 3-3.) Copies a specified job processing definition to a different datacenter or Scheduling table. (See page 3-24.) Converts non-XML format defjob input files into XML-based input files for use with the CONTROL-M/Enterprise Manager 6.1.01 version of defjob. (See page 3-45.) Deletes a specified job definition. (See page 3-48.) Creates a copy of a job in the same datacenter and Scheduling table. (See page 3-54.) Imports a job processing definition directly from a Scheduling table to a text file. (See page 3-80.) Modifies the characteristics of existing job processing definitions, Scheduling table definitions, and Group Scheduling table definitions. (See page 3-85.)
defjobconvert
deldefjob duplicatedefjob exportdefjob updatedef
Note
The cli utility uploads, downloads, orders, and forces jobs. It is described in Chapter 2, Command Line Interface Utility (cli).
3-2
defjob
The defjob utility imports job processing definitions directly into a Scheduling table in the CONTROL-M/Enterprise Manager database. defjob reads job processing definitions from a plain text input file written in XML format. Each job processing definition in the CONTROL-M/Enterprise Manager database has a unique field, JOBISN. The value of JOBISN is a number that is unique to that job. If the JOBISN number of a job that is already in the CONTROL-M/Enterprise Manager database is included in a job definition that is being imported, defjob overwrites the existing job processing definition in the database with the new job. If a JOBISN value is not specified, defjob imports a new job processing definition into the database. To invoke the defjob utility: 1. Log on as a CONTROL-M/Enterprise Manager user. 2. Open a command prompt window (Microsoft Windows) or go to the command line (Unix). 3. Enter the following command:
defjob -HOST <host_name> -USERNAME <user> -PASSWORD <password> -SRC_FILE <XML_file_name>
Parameters of the defjob utility are described in Table 3-2, defjob Parameters, on page 3-4. 4. 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.
Job Utilities
3-3
Syntax
Table 3-2 defjob Parameters
Parameter
<host_name> <user> <password> <XML_file_name>
Description
CONTROL-M/EM host name or IP address. CONTROL-M/EM user name. The users CONTROL-M/EM password. The path and name of the XML file containing the defjob specifications. For instructions in preparing this file, see Appendix A, XML File Preparation.
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/Enterprise Manager database and imported into the scheduling table specified in the job definition in the file. For instructions for creating input files, see Appendix A, XML File Preparation. 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 Table 3-3, defjob Input File Parameters, on page 3-5 are listed as optional, certain parameters are required depending upon 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.
3-4
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. The TAG_NAME and TAG_RELATIONSHIP parameters are optional for jobs in a Group Scheduling table. These parameters are invalid for jobs that are not in a Group Scheduling table. Any values specified for the TAG_NAME and TAG_RELATIONSHIP parameters are ignored when the job definition being created is not included in a Group Scheduling table.
Table 3-3
defjob Input File Parameters (Part 1 of 18)
Parameter
Description
The first two lines of the XML request file for this API request contain information that specifies to the Short Product Name the version of XML and 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>... </DEFJOB> Indicates to CONTROL-M/Enterprise Manager 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 the <JOB></JOB> tags. Indicates the opening and closing tags of a single job definition. The parameters of the job are listed between the tags, in place of the ellipses displayed in the column on the left. 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
<JOB>...</JOB>
DATACENTER
Job Utilities
3-5
Table 3-3
Parameter
TABLE_NAME
Description
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 Name of the library that contains the scheduling table. [For OS/390 jobs, only.] String. Mandatory. Note: At least one of the following Scheduling table parameters must be included in the input file: DATACENTER TABLE_NAME TABLE_DSN Name of the job processing definition. String. Mandatory. Name of the file that contains the job script. String. Optional. Name of the group to which the job belongs. Used as a descriptive name for related groups of jobs. String. Mandatory. Name of the application to which the jobs group belongs. Used as a descriptive name for related groups of jobs. String. Mandatory. Type of the job (task) to be performed by CONTROL-M. Mandatory. Valid values: Job Detached Command Dummy Valid values [OS/390]: Started_Task Cyclic_Job Cyclic_Task Emergency_Job Emergency_Cyclic_Job Emergency_Task Emergency_Cyclic_Task String. Optional.
TABLE_DSN
JOBNAME MEMNAME GROUP
APPLICATION
TASKTYPE
TABLE_USERDAILY
3-6
Table 3-3
Parameter
AUTHOR
Description
CONTROL-M/EM user who defined the job. This parameter is used by the CONTROL-M security mechanism. String. Optional. Name of the library/directory in which the job script resides. String. Optional. Command string supplied when the job Task Type is Command. String. Optional. Host name of an Agent platform or name of a node group to which the job should be submitted. String. Optional. Owner (user ID) associated with the job. This parameter is used by the CONTROL-M security mechanism. String. Optional. Specifies the maximum number of reruns that can be performed for the job. Optional. Valid values: 0-99. Default: 0. Indicates the earliest time for submitting the job. String. Optional. Indicates the latest time for submitting the job. String. Optional. Time that the job is expected to finish. String. Optional. Indicates CONTROL-M job priority. String. Optional. Indicates that the job is a critical-path job in CONTROL-M. Optional. Valid values: 0 (No. Default) 1 (Yes) Indicates if the job is cyclic (to be rerun at regular intervals). Optional. Valid values: 0 (No. Default) 1 (Yes)
MEMLIB CMDLINE NODEID
OWNER
MAXRERUN
TIMEFROM TIMETO DUE_OUT PRIORITY CRITICAL
CYCLIC
Job Utilities
3-7
Table 3-3
Parameter
CONFIRM
Description
Indicates that the job must be manually confirmed by the CONTROL-M/EM user before it will run. Optional. Valid values: 0 (Default) 1 Determines whether or not SYSDATA is to be archived. Optional. Valid values: 0 (No-Default) 1 (Yes) 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. Name of an alternate job script library/directory. String. Optional. 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. Free text description of the job. String. Optional. Name of the file containing job documentation. String. Optional. Name of a library or directory containing the job documentation file. String. Optional. Days of the month on which to order the job. String. Optional. Indicates the relationship between specified Days values and Weekdays values. Optional. Valid values: AND OR Days of the week on which to order the job. String. Optional.
AUTOARCH
INTERVAL
OVERLIB MAXWAIT
DESCRIPTION DOCMEM DOCLIB DAYS DAYS_AND_OR
WEEKDAYS
3-8
Table 3-3
Parameter
DATE
Description
Specific dates on which to order the job. String. mmdd format. Optional. For example, January 10 is written as: DATE="0110" Name of a user-defined calendar used to specify a set of days. String. Optional. Name of a calendar to be used to validate specified weekdays on which to order the job. String. Optional. Specifies a calendar that will be used to validate all specified days and dates on which to schedule the job. String. Optional. Indicates whether the job should be scheduled for possible execution after its original scheduling date (odate) has passed. Optional. Valid values: 0 (No. Default) 1 (Yes) Describes how to shift the scheduling date of the job. Optional. Valid values: IGNOREJOB PREVDAY NEXTDAY NOCONFCAL Number of days to shift the scheduling date of the job. Optional. Valid values: -62 to 62. Maximum number of days to retains the SYSDATA archive dataset for jobs that ended NOTOK. Subparameter of AUTOARCH. Optional. Valid values: 00 98 or 99. Indicating 99 retains the SYSDATA data for an unlimited number of days. Optional. 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. Indicating 999 retains the SYSDATA data for all runs.
DAYSCAL WEEKSCAL
CONFCAL
RETRO
SHIFT
SHIFTNUM
MAXDAYS
MAXRUNS
Job Utilities
3-9
Table 3-3
Parameter
RERUNMEM
Description
Name of the JCL member to use when the job is automatically rerun. String. 1-8 characters. Optional. Number of days to retain the job in the History Jobs file. [OS/390, only]. String. Optional. Maximum number of generations of the job to keep in the History Jobs file.[OS/390, only]. String. Optional. Optional. Valid values: Y N 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 Relationship (And/Or) between the specified Schedule Tag criteria and the jobs own basic scheduling criteria. This parameter is relevant only for jobs in a Group Scheduling table. Optional. Valid values: AND OR Determines whether one or multiple data sets are used to catalogue sysdata. Optional. Valid values: 0 (Multiple-Default) 1 (Single) Name of a partitioned dataset (PDS) to be checked for free space. String. Optional. Minimum number of free partitioned dataset tracks required by the library specified for the PDSNAME parameter. Integer. Optional.
RETEN_DAYS
RETEN_GEN
PREV_DAY
IND_CYCLIC
TAG_RELATIONSHIP
SYSDB
PDSNAME MINIMUM
3-10
Table 3-3
Parameter
CATEGORY
Description
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. Prevents dataset cleanup before the original job run. [OS/390 only] Optional. Valid values: 0 Does not prevent cleanup. Default. 1 - Prevents cleanup. Months when the job can run. Valid values: 0 (Not run. Default) 1 (Run) Sysout Handling options. Optional. Valid values: Release Delete Copy Move File NewDest ChangeClass Certain OPTION values require that you supply additional information (such as Release, NewDest). String. Optional. Limits the sysout handling operation to only sysouts from the specified class. String. Optional. 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 (Dont ignore. Default.) 1 (Ignore relevant prerequisite conditions) Number of jobs in the Group Scheduling table. String. Optional. Username of the user who created the job. String. Optional.
PREVENTNCT2
JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC OPTION
PAR
FROM
ADJUST_COND
JOBS_IN_GROUP CREATION_USER
Job Utilities
3-11
Table 3-3
Parameter
CREATION_DATE CREATION_TIME CHANGE_USERID CHANGE_DATE CHANGE_TIME JOB_RELEASE JOB_VERSION APPL_TYPE
Description
Date on which the job was created. String. Optional. Time at which the job was created. String. Optional. Username of the user who last modified the job. String. Optional. Date on which the job was last modified. String. Optional. Time at which the job was last modified. String. Optional. For internal use. Do not include this parameter in your defjob input file. For internal use. Do not include this parameter in your deftable input file. Indicates the type of external application (for example, SAP or Oracle Applications) on which the external application job will run. String. Up to 10 characters. Mandatory for external application jobs. Indicates the version of the external application (for example, SAP or Oracle Applications) on which the external application job will run.Mandatory for external application jobs. String. Up to 10 characters. Mandatory for external application jobs. Specifies a predefined set of external application parameters that will be displayed in the External Application panel of the CONTROL-M/EM Job Editing form. String. Up to 30 characters. Mandatory for external application jobs. Indicates the version of external application (for example, SAP or Oracle Applications) Control Module (CM) that is installed in the CONTROL-M installation. String. Up to 10 characters. Mandatory for external application jobs. When selected, broadcasts job submission details to all Agents within a specified Node Group. Optional. Valid values: Y- run as multi-agent job N- not run as multi-agent job. Default.
APPL_VER
APPL_FORM
CM_VER
MULTY_AGENT
3-12
Table 3-3
Parameter
ACTIVE_FROM
Description
Indicates the start of a period of time during which the job or Group Scheduling table can be ordered. [For OS/390 jobs and Group Scheduling tables, only] Optional. Date Format: YYYYMMDD Indicates the end of a period of time during which the job or Group Scheduling table can be ordered. [For OS/390 jobs and Group Scheduling tables, only] Optional. Date Format: YYYYMMDD Indicates the global time zone used to calculate the interval for time-related conditions. String. Optional. Indicates the JES2 workload management scheduling environment that is to be associated with the job. OS/390, only. String. Optional. Indicates the identity of the system in which the job must be initiated and executed (in JES2). Indicates the identity of the processor on which the job must execute (in JES3). String. Optional. Specifies the node in the JES network on which the job is to execute. String. Optional. For internal use. String. Optional. 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.
ACTIVE_TILL
TIMEZONE
SCHEDULING_ENVIR ONMENT SYSTEM_AFFINITY
REQUEST_NJE_NODE JOBISN <TAG_NAMES/>
Job Utilities
3-13
Table 3-3
Parameter
<INCOND/>
Description
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. Order date of the In condition. String. Mandatory. Valid values: Default: ODAT Relationship between conditions. Optional. Valid values are AND (default) OR Parentheses indicating parts of the condition that are interpreted first. String. Optional.
ODATE
AND_OR
OP
<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. Order date of the Out condition. String. Mandatory. Valid values: Default: ODAT Indicates whether to add or delete the condition. Mandatory. Valid values: ADD (default) DEL
ODATE
SIGN
3-14
Table 3-3
Parameter
<AUTOEDIT/>
Description
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. Quantity of the resource. String. Mandatory. Valid values: 0 9999. Default: 1
QUANT
<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 of resource. Valid values: E (exclusive-default) S (shared)
TYPE
Job Utilities
3-15
Table 3-3
Parameter
<SHOUT/>
Description
Wrapper for the Shout message. Optional. Example: <SHOUT WHEN="EXECTIME" DEST="workstation1" URGENCY="R" MESSAGE="Job completed OK." TIME="1015>/> WHEN Condition under which the Shout message is sent. Mandatory. Valid values: OK (default) NOTOK RERUN LATESUB LATETIME EXECTIME Recipient of the shout message. String. Mandatory. Valid values: 1-16 characters, case-sensitive. Mandatory. Indicates the urgency of the Shout message. Mandatory. Valid values: R (regular-default) U (urgent) V (very urgent) Text of the message. String. Mandatory. Valid values: 1-255 characters, spaces allowed. Time that the message is sent. String. Mandatory.
DEST
URGENCY
MESSAGE
TIME
3-16
Table 3-3
Parameter
<STEP_RANGE/>
Description
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. Name of the program to be run. as the first program step in the range. 1-8 character string. Mandatory. Name of the procedure to be run. as the first procedure step in the range. 1-8 character string. Mandatory. 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. 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.
FPGMS
FPROCS
TPGMS
TPROCS
Job Utilities
3-17
Table 3-3
Parameter
<ON>...</ON>
Description
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.. 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. Step in the program. String. Optional. Valid value: 1-8 characters. Step in the process. String. Optional. Valid values:1-8 characters. Relationship between On statements. Optional. Valid values: AND OR
CODE
PGMS PROCS 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 f the job) SPCYC (Prevents further runs of a cyclic job)
3-18
Table 3-3
Parameter
<DOSHOUT/>
Description
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 of the Shout message. Valid values: R (regular-default) U (urgent) V (very urgent) Text of the Shout message. String, 1-255 characters, spaces allowed. Mandatory.
URGENCY
MESSAGE <DOCOND/>
Specifies prerequisite conditions to be added or deleted. Optional. Example: <DOCOND NAME="Cond1" ODATE="ODAT" SIGN="ADD"/> NAME ODATE Condition name. String, 1-20 characters, case-sensitive. Mandatory. Condition date. String. Mandatory. Default: ODAT Specifies whether to add or delete the condition. Valid values: ADD (default) DEL
SIGN
<DOAUTOEDIT/>
Wrapper for the AutoEdit expression. Optional. Example: <DOAUTOEDIT EXP="%%PARM1=%%TIME"/> EXP The AutoEdit expression. String. Required. Example: %%PARM1=%%TIME
Job Utilities
3-19
Table 3-3
Parameter
<DOFORCEJOB/>
Description
Forces a specified job when the current job is performed. Optional. Example: <DOFORCEJOB DSN="45446" TABLE_NAME="Table2" NAME="Job4" ODATE="ODAT"/> DSN TABLE_NAME Library for the Scheduling table [OS/390, only]. String. Mandatory. Name of the Scheduling table to which the job belongs. String, 1-10 characters. Mandatory. Name of the job. String. Mandatory. Original scheduling date for the job. String. Default: ODAT
NAME ODATE <DOSYSOUT/>
Handle sysout material when the job is done. Optional. Example: <DOSYSOUT OPTION="Release" PAR="F" FROM=""/> OPTION Sysout Handling options. Mandatory. Valid values: Release Delete Copy Move File NewDest ChangeClass Copy and Move are not used with OS/390. File, NewDest, and ChangeClass are used only with OS/390. Certain OPTION values require that you supply additional information (such as Release, NewDest). String. Optional. Limits the sysout handling operation to only sysouts from the specified class. String. Optional.
PAR
FROM
3-20
Table 3-3
Parameter
<DOIFRERUN/>
Description
Job steps to be executed during restart of a job. Available only at sites utilizing CONTROL-M/Restart. Optional. Example: <DOIFRERUN CONFIRM="0" FPGMS="step1" FPROCS="proc1" TPGMS="step5" TPROCS="proc3"/> CONFIRM Indicates if the job must be confirmed by the user to be rerun.Valid values: 0 (No confirmation. Default) 1 (Confirmation) Step at which the job must be restarted. String. 1-8 characters. Mandatory. Program step within the called procedure. String. 1-8 characters. Mandatory. Step at which the restarted job must terminate. String. 1-8 characters. Mandatory. Program step within the called procedure. String. 1-8 characters. Mandatory.
FPGMS
FPROCS
TPGMS
TPROCS
Job Utilities
3-21
Table 3-3
Parameter
<DOMAIL/>
Description
Sends mail when the job 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) Recipient of the message. String. Mandatory. Additional recipient of the message. String. Optional. Brief text description of the message contents. String. Optional. Text of the message. String. Mandatory.
DEST CC_DEST SUBJECT MESSAGE <DOCTBRULE/>
Invokes a CONTROL-M/Analyzer rule to be executed during the processing of a specific program step. [OS/390] Optional. Example: <DOCTBRULE NAME="GOVTBAL" PAR="DOREPORT,10,%%ODATE"/> NAME PAR Name of the CONTROL-M/Analyzer rule. String. Mandatory. Arguments that are passed to the CONTROL-M/Analyzer rule. String. Optional. Maximum: 45 characters.
3-22
Following is a sample input file used with the defjob utility.

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" 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>
Job Utilities
3-23
copydefjob
The copydefjob utility enables you to create a new job definition in the CONTROL-M/Enterprise Manager database similar to an existing definition that you specify. The original job and the copy differ in that they must be in different data centers and/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 A-7. When the copydefjob utility is invoked, a file of arguments that you have created is processed. This arguments file specifies selection criteria that select one or more existing job processing definitions. The selected jobs are copied to the Scheduling table and/or datacenter specified in the arguments file. To invoke the copydefjob utility: 1. Log on as a CONTROL-M/Enterprise Manager user. 2. Open a command prompt window (Windows users, only). You do not need to be in the CONTROL-M/EM home directory. 3. At the command prompt, enter the following command:
copydefjob -HOST <host_name> -USERNAME <user> -PASSWORD <password> -ARG_FILE <args_file_name>
Parameters of the copydefjob utility are described in Table 3-4, copydefjob Parameters, on page 3-25. 4. Press <Enter>.
3-24
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.
Syntax
The parameters of the copydefjob utility are described in Table 3-4.

Table 3-4 copydefjob Parameters
Parameter
<host_name> <user> <password> <arg_file_name>
Description
CONTROL-M/EM host name or IP address. CONTROL-M/EM user name. The CONTROL-M/EM user password. The full path name of the arguments file containing the copydefjob specifications. For instructions in preparing this file, see Appendix A, XML File Preparation.
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.
Job Utilities
3-25
Each parameter that you specify must have a FROM value. This value is used as a search criteria for selecting jobs to copy. Note
Currently, the copydefjob 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 copydefjob utility. The following rules apply to the input file for the copydefjob utility: More than one job can be specified in an copydefjob 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 A-7. If any FROM value contains a *, and the corresponding TO value contains a *, the * in the TO value expresses the same information the * represented 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 parameters of the job definition are optional. However: If you do choose to specify a parameter, the FROM subparameter is mandatory, and the TO subparameter is optional.
3-26
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 will be updated.
Table 3-5
copydefjob Arguments File Parameters (Part 1 of 15)
Parameter
Description
The first two lines of the XML request file for this API request contain information that specifies to the Short Product Name the version of XML and 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>... </COPYJOB> <TABLE_NAME/> 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. 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. The Scheduling table name in the job processing definition copy. String. Optional.
TO
Job Utilities
3-27
Table 3-5
Parameter
<TABLE_DSN/>
Description
Name of the library that contains the scheduling table. [For OS/390 jobs, only.] 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. Name of the library in the job processing definition copy. String. Optional.
TO <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="ECS_Montreal" TO="ECS_Paris"/> FROM TO Name of the CONTROL-M installation to which the job being copied belongs. Mandatory. 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.
3-28
Table 3-5
Parameter
<GROUP/>
Description
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 jobs 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 Valid values [OS/390]: Started_Task Cyclic_Job Cyclic_Task Emergency_Job Emergency_Cyclic_Job Emergency_Task Emergency_Cyclic_Task
<TABLE_USERDAILY />
Optional. Example: <TABLE_USERDAILY FROM="Job3"/> FROM String. Mandatory.
<AUTHOR/>
CONTROL-M/EM user who defined the job. This parameter is used by the CONTROL-M security mechanism. String. Optional. Example: <AUTHOR FROM="ecsuser"/> FROM String. Mandatory.
Job Utilities
3-29
Table 3-5
Parameter
<MEMLIB/>
Description
Name of the library/directory in which the job script resides. String. Optional. Example: <MEMLIB FROM="Mem1"/> FROM String. Mandatory.
<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 should be 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 security mechanism. Optional. Example: <OWNER FROM="ecsuser"/> 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. 0 is the default. 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.
3-30
Table 3-5
Parameter
<DUE_OUT/>
Description
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
<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 will run. 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
Job Utilities
3-31
Table 3-5
Parameter
<INTERVAL/>
Description
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.
<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.
3-32
Table 3-5
Parameter
<DAYS_AND_OR/>
Description
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 will be used to validate all specified days and dates on which to schedule the job. String. Example: <CONFCAL FROM="cal99" TO="cal00"/> FROM String. Mandatory.
Job Utilities
3-33
Table 3-5
Parameter
<RETRO/>
Description
Indicates whether the job should be 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.
3-34
Table 3-5
Parameter
<RERUNMEM/>
Description
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/>
Number of days to retain the job in the History Jobs file. [OS/390, only]. String. Optional. Example: <RETEN_DAYS FROM="5"/> FROM String. Mandatory.
<RETEN_GEN/>
Maximum number of generations of the job to keep in the History Jobs file.[OS/390, only]. String. Example: <RETEN_GEN FROM="3"/> FROM String. Mandatory.
<TASK_CLASS/>
Example: <TASK_CLASS FROM="Distribution"/> FROM Mandatory. Valid values: Distribution Decollation
<PREV_DAY/>
Optional. Example: <PREV_DAY FROM="N"/> FROM Mandatory. Valid values: Y N
Job Utilities
3-35
Table 3-5
Parameter
<IND_CYCLIC/>
Description
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_RELATIONSHI P/>
Relationship (And/Or) between the specified Schedule Tag criteria and the jobs 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.
3-36
Table 3-5
Parameter
<CATEGORY/>
Description
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/>
Prevents dataset cleanup before the original job run. [OS/390 only] Optional. Example: <PREVENTNCT2 FROM="1"/> FROM Mandatory. Valid values: 0 (Default) 1
<JAN/>, <FEB/>, <MAR/>, <APR/>, <MAY/>, <JUN/>, <JUL/>, <AUG/>, <SEP/>, <OCT/>, <NOV/>, <DEC/>
Months when the job can run. Optional. Example: <JAN FROM="0"/> FROM Mandatory. Not including a month is the same as including a month having the value, 0. Valid values: 0 (Default) 1
<OPTION/>
Sysout Handling options. Example: <OPTION FROM="Copy"/> FROM Mandatory. Valid values: Release Delete Copy Move File NewDest ChangeClass
Job Utilities
3-37
Table 3-5
Parameter
<PAR/>
Description
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="mem3.log"/> FROM String. Mandatory.
<FROM/>
Limits the sysout handling operation to only sysouts from the specified class. Optional. Example: <FROM FROM="5"/> FROM String. Mandatory.
<ADJUST_COND/>
Indicates whether or not 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 (Dont 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 Applications) on which the external application job will run.Mandatory for external application jobs. Mandatory for external application jobs. Example: <APPL_TYPE FROM=SAP/> FROM Mandatory. String. Up to 10 characters.
<APPL_VER/>
Indicates the version of the external application (for example, SAP or Oracle Applications) on which the external application job will run.Mandatory for external application jobs. Mandatory for external application jobs. Example: <APPL_VER FROM=4.6/> FROM Mandatory. String. Up to 10 characters.
3-38
Table 3-5
Parameter
<APPL_FORM/>
Description
Specifies a predefined set of external application parameters that will be displayed in the External Application panel of the CONTROL-M/EM 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 Applications) Control Module (CM) 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 within 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/>
Indicates the start of a period of time during which the job or Group Scheduling table can be ordered. [For OS/390 jobs and Group Scheduling tables, only] Optional. Example: <ACTIVE_FROM FROM=20020315/> FROM Mandatory. 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 OS/390 jobs and Group Scheduling tables, only] Optional. Example: <ACTIVE_TILL FROM=20020315/> FROM Mandatory. Date Format: YYYYMMDD
Job Utilities
3-39
Table 3-5
Parameter
<TIMEZONE/>
Description
Indicates the global time zone used to calculate the interval for time-related conditions. Optional. Example: <TIMEZONE FROM=EST (GMT +03:00)/> FROM Mandatory. String. Default: GMT.
SYSTEM_AFFINITY
Indicates the identity of the system in which the job must be initiated and executed (in JES2). Indicates the identity of the processor on which the job must execute (in JES3). Optional. String. FROM String. Mandatory. Example: <SYSTEM_AFFINITY FROM=SYS3/>
REQUEST_NJE_NO DE
Specifies the node in the JES network on which the job is to execute. FROM String. Mandatory. Example: <REQUEST_NJE_NODE FROM=OS5/>
SCHEDULING_ENVI RONMENT
Indicates the JES2 workload management scheduling environment that is to be associated with the job. OS/390, only. FROM String. Mandatory. Example: <SCHEDULING_ENVIRONMENT FROM=SCHD2/>
<CREATION_USER/>
Username of the user who created the job. String. Example: <CREATION_USER FROM="ecsuser"/> FROM String. Mandatory.
<CREATION_DATE/>
Date on which the job was created. String. Example: <CREATION_DATE FROM="1212"/> FROM String. Mandatory.
3-40
Table 3-5
Parameter
<CREATION_TIME/>
Description
Time at which the job was created. String. Example: <CREATION_TIME FROM="1230"/> FROM String. Mandatory.
<CHANGE_USERID/ >
Username of the user that last modified the job. String. Example: <CHANGE_USERID FROM="ecsuser"/> FROM String. Mandatory.
<CHANGE_DATE/>
Date that the job was last modified. String. 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.
Job Utilities
3-41
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 specifies job processing definitions from the Tbl5NYC Scheduling table that have the TABLE_DSN Lib1 and the JOBNAME Job3 and makes copies of those jobs where the TABLE_DSN has 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 a Scheduling table to another table
Copies of all jobs in the Tbl5NYC Scheduling written 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>
Example 3: Copy all cyclic jobs with 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>
3-42
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 3-25. 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 will change 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 -USERNAME <emuser> -PASSWORD <empass> -HOST <hostname> -ARG_FILE <arg_file_name> 5. Use the Scheduling Table Manager in CONTROL-M/Desktop to upload the Group Scheduling table to the CONTROL-M/Server.
Job Utilities
3-43
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. Delete the Scheduling table. It is no longer needed.
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>
3-44
defjobconvert
The defjobconvert utility converts defjob input files from versions of Enterprise Controlstation prior to 6.0.01 into files that are compatible with the defjob utility in CONTROL-M/Enterprise Manager version 6.1.0x. To invoke the defjobconvert utility: 1. Log on to the computer. 2. Open a command prompt window (Windows users, only). You do not need to be in the CONTROL-M/Enterprise Manager directory. 3. Enter the following command:
defjobconvert -SRC_FILE <src_file_name> -OUT_FILE <XML output file name>
Parameters of the defjobconvert utility are described in Table 3-6, defjobconvert Parameters, on page 3-46. 4. 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.
Syntax
The parameters of the defjobconvert utility are described in Table 3-6.
Job Utilities
3-45
Table 3-6
defjobconvert Parameters
Parameter
<src_file_name> <output_file_name>
Description
The path and name of the source defjob input file. The path and name where the new defjob input file is saved. This utility does not create the output directory automatically. It must already exist.
defjobconvert Files
The defjobconvert utility reads an existing defjob input file that was created for use with any CONTROL-M/Enterprise Manager version prior to 6.0.01, and produces a new file, containing all of the source files 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 3-3. The output file will look similar to the output file displayed in Example: Command job that requires confirmation before running on page 3-23.
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 is displayed on the command line, indicating the percentage of the file that has been converted.
Messages
Messages include:
Processing <src_file_name>. Reading input file.
Parsing input file.
3-46
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. For example, if a defjob input file contains tabs and back slashes that indicate spacing and line breaks,
-USERNAME<CONTROL-M/Enterprise -PASSWORD<CONTROL-M/Enterprise
Manager Manager
log on name>\ logon password>\
-TABLE<Scheduling table name>\
then the message, Error: ignoring attributes, 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.
Examples 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
Job Utilities
3-47
deldefjob
The deldefjob utility deletes specified job processing definitions from a scheduling table in the CONTROL-M/Enterprise Manager database. When deldefjob is invoked, a file of arguments that you have created is processed. This file, the arguments file, contains statements that specify an existing job processing definition or group of job processing definitions. The specified definitions are deleted from the CONTROL-M/Enterprise Manager database. deldefjob reads arguments directly from a plain text arguments file (in XML format) instead of reading them from the command line. To invoke the deldefjob utility: 1. Log on as a CONTROL-M/Enterprise Manager user. 2. Open a command prompt window (Microsoft Windows users, only). You do not need to be in the CONTROL-M/Enterprise Manager directory. 3. At the command prompt, enter the following command:
deldefjob -HOST <host_name> -USERNAME <user> -PASSWORD <password> -ARG_FILE <args_file_name>
Parameters of the deldefjob utility are described in Table 3-7, deldefjob Parameters, on page 3-49. 4. 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.
3-48
Syntax
The parameters of the deldefjob utility are described in Table 3-7, deldefjob Parameters, on page 3-49.
Table 3-7 deldefjob Parameters
Parameter
Description
CONTROL-M/EM host name or IP address. CONTROL-M/EM user name. The users CONTROL-M/EM password. The path and name of the arguments file containing the deldefjob specifications.For instructions in preparing this file, see Appendix A, XML File Preparation.
deldefjob Arguments File
Arguments are used as selection criteria to determine which job processing definitions are deleted. Arguments are written to the deldefjob argument file. The arguments files that you create with the deldefjob utility are written in XML format and saved in a text file. The format in which this file must be written is described in Table 3-8, deldefjob Arguments File Parameters, on page 3-50. When this file is invoked, job processing definitions are deleted from the CONTROL-M/Enterprise Manager database. For instructions for creating arguments files, see Appendix A, XML File Preparation. The following rules apply to the deldefjob arguments file: More than one job can be specified in an deldefjob 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.
Job Utilities
3-49
The relationship between PARAM parameters in a TERM statement is AND. The relationship between TERM statements is OR.
Table 3-8
deldefjob Arguments 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 to the Short Product Name the version of XML and 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>... </TERMS> <TERM>...</TERM> 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. The TERM tags indicate the start and 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 Optional. Relationship between terms. Valid values: AND OR
3-50
Table 3-8
deldefjob Arguments File Parameters (Part 2 of 2)
Parameter
<PARAM/>
Description
The selection criteria parameter used to determine those 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. Name of any job processing parameter, using the format shown in Table 3-2, defjob Parameters, on page 3-4. Note: At least one of the following Scheduling table parameters must be included in the arguments file: DATACENTER TABLE_NAME TABLE_DSN Mandatory. Valid values: EQ NEQ NOTIN LIKE String. Mandatory. Valid value of any job processing parameter, using the format shown in Table 3-2, defjob Parameters, on page 3-4.
OP
VALUE
Job Utilities
3-51
Following are sample arguments files used with the deldefjob utility:
Example 1: Delete definitions with the same job name
Job processing definitions that have the name, Job5, from the ECS5NY data center are deleted.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE TERMS SYSTEM "terms.dtd"> <TERMS> <TERM> <PARAM NAME="DATACENTER" OP="EQ" VALUE="ECS5NY"/> <PARAM NAME="JOBNAME" OP="EQ" VALUE="Job5"/> </TERM> </TERMS>
Example 2: Delete definitions that answer one or both of two criteria
Job processing definitions answering to the following criteria are deleted: That have the data center name, Data1, and a jobname that begins with the letter J. -or That have the jobname, Job5, and are not cyclic jobs.
<?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
Definitions for cyclic jobs in the ECS5NY data center that are scheduled to run in January, February, and March are deleted.
3-52
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE TERMS SYSTEM "terms.dtd"> <TERMS> <TERM> <PARAM NAME="DATACENTER" OP="EQ" VALUE="ECS5NY"/> <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>
Job Utilities
3-53
duplicatedefjob
duplicatedefjob is a utility that enables you to create a copy of an existing job definition in the same datacenter and Scheduling table. When you copy the definition, you can alter elements of that definition.
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 A-7. When the duplicatedefjob utility is invoked, a file of arguments that you have created is processed. This arguments file specifies selection criteria that select either an existing job processing definition or group of job processing definitions. duplicatedefjob reads arguments directly from a plain text arguments file (in XML format), instead of reading them from the command line. To invoke the duplicatedefjob utility: 1. Log on as an CONTROL-M/Enterprise Manager user. 2. Open a command prompt window (Microsoft Windows). You do not need to be in the CONTROL-M/Enterprise Manager directory. 3. At the command prompt, enter the following command:
duplicatedefjob -HOST <host_name> -USERNAME <user> -PASSWORD <password> -ARG_FILE <args_file_name>
Parameters of the duplicatedefjob utility are described in Table 3-9, duplicatedefjob Parameters, on page 3-55. 4. Press <Enter>. The duplicatedefjob arguments file is checked and processed. If there are any errors in the file, a message is displayed specifying the lines with the errors.
3-54
Syntax
The parameters of the duplicatedefjob utility are described in Table 3-10, duplicatedefjob Arguments File Parameters, on page 3-57.
Table 3-9 duplicatedefjob Parameters
Parameter
Description
CONTROL-M/Enterprise Manager host name or IP address. CONTROL-M/Enterprise Manager user name. The CONTROL-M/Enterprise Manager user password. The full path name of the arguments file containing the duplicatedefdefjob specifications. For instructions in preparing this file, see Appendix A, XML File Preparation.
duplicatedefjob Arguments File
Arguments are used as selection criteria to determine which jobs to copy. Arguments are written to the duplicatedefjob argument file. The arguments files that you create with the duplicatedefjob 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/Enterprise Manager database.
Job Utilities
3-55
Each parameter that you specify must have a FROM value. This 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 value, which is optional, is used to update the value of a parameter. For example, <JOBNAME FROM="Job2" TO="Job2B"/> modifies all jobs with the JobName Job2 so that they now have the JobName Job2B.
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 input 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 (such as strings or digits) must be enclosed in quotation marks (for example, JOBNAME="Job1"). Only one DUPLICATEJOB parameter can be used in an arguments file. The DUPLICATEJOB 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 A-7. 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.
3-56
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 original. These values cannot be changed with the duplicatedefjob utility.
Most parameters of the job definition are optional. However: 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 will be updated.
Table 3-10
duplicatedefjob Arguments File Parameters (Part 1 of 22)
Parameter
Description
The first two lines of the XML request file for this API request contain information that specifies to the Short Product Name the version of XML and 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"> <DUPLICATEDEFJOB>. .. </DUPLICATEDEFJOB> <TABLE_NAME/> These tags indicate the start and end of the DUPLICATEJOB argument. Only criteria that are located between the tags are considered to be part of the argument. Name of the Scheduling table to which the job belongs. Mandatory. Note: A TO parameter cannot be specified for this parameter. 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.
Job Utilities
3-57
Table 3-10
Parameter
<TABLE_DSN/>
Description
Name of the library that contains the scheduling table. [For OS/390 jobs, only.] Mandatory. Note: A TO parameter cannot be specified for this parameter. 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/> FROM String. Mandatory.
<DATACENTER/>
Name of the CONTROL-M installation to which the job belongs. Mandatory. Note: A TO parameter cannot be specified for this parameter. 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="CTMNYC"/> FROM String. Mandatory.
<TABLE_USERDAILY/>
String. Mandatory. 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 TO Mandatory. Optional.
3-58
Table 3-10
Parameter
<MEMNAME/>
Description
Name of the file that contains the job script. Optional. Example: <MEMNAME FROM="Mem3" TO="Mem7"/> FROM TO Mandatory. Optional.
<GROUP/>
Name of the group to which the job belongs. Used as a descriptive name for related groups of jobs. Optional. Example: <GROUP FROM="Grp_HR" TO="Grp_ACCT"/> FROM TO Mandatory. Optional.
<APPLICATION/>
Name of the application to which the jobs group belongs. Used as a descriptive name for related groups of jobs. Optional. Example: <APPLICATION FROM="App3" TO="App1"/> FROM TO String. Mandatory. String Optional.
Job Utilities
3-59
Table 3-10
Parameter
<TASKTYPE/>
Description
Type of the job (task) to be performed by CONTROL-M. Optional. Example: <TASKTYPE FROM="Detached" TO=""/> FROM Mandatory. Valid values: Job Detached Command Dummy Valid values [OS/390]: Started_Task Cyclic_Job Cyclic_Task Emergency_Job Emergency_Cyclic_Job Emergency_Task Emergency_Cyclic_Task Optional. Valid values: Job Detached Command Dummy Valid values [OS/390]: Started_Task Cyclic_Job Cyclic_Task Emergency_Job Emergency_Cyclic_Job Emergency_Task Emergency_Cyclic_Task
TO
<AUTHOR/>
CONTROL-M/EM user who defined the job. This parameter is used by the CONTROL-M security mechanism. String. Optional. Example: <AUTHOR FROM="ecsuser" TO="ecs5"/> FROM TO String. Mandatory. String. Optional.
3-60
Table 3-10
Parameter
<MEMLIB/>
Description
Name of the library/directory in which the job script resides. String. Optional. Example: <MEMLIB FROM="Mem1" TO="Mem4"/> FROM TO String. Mandatory. String. Optional.
<CMDLINE/>
Command string supplied when the job Task Type is Command. Optional. Example: <CMDLINE FROM="C:\Format" TO="C\:CD Ecsnt"/> FROM TO String. Mandatory. String. Optional.
<NODEID/>
Host name of an Agent platform or name of a node group to which the job should be submitted. Optional. Example: <NODEID FROM="Com3" TO="Acct4"/> FROM TO String. Mandatory. 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 security mechanism. Optional. Example: <OWNER FROM="ecsuser" TO="ecshr"/> FROM TO String. Mandatory. String. Optional.
<MAXRERUN/>
Specifies the maximum number of reruns that can be performed for the job. Optional. Example: <MAXRERUN FROM="1" TO="3"/> FROM TO String. Mandatory. String. Optional.
Job Utilities
3-61
Table 3-10
Parameter
<TIMEFROM/>
Description
Indicates the earliest time for submitting the job. Optional. Example: <TIMEFROM FROM="1430" TO="1450"/> FROM TO String. Mandatory. String. Optional.
<TIMETO/>
Indicates the latest time for submitting the job. Optional. Example: <TIMETO FROM="1600" TO="1620"/> FROM TO String. Mandatory. String. Optional.
<DUE_OUT/>
Time that the job is expected to finish. Optional. Example: <DUE_OUT FROM="1500" TO="1530"/> FROM TO String. Mandatory. String. Optional.
<PRIORITY/>
Indicates CONTROL-M job priority. Optional. Example: <PRIORITY FROM="AA" TO="1A"/> FROM TO String. Mandatory. String. Optional.
<CRITICAL/>
Indicates that the job is a critical-path job in CONTROL-M. Optional. Example: <CRITICAL FROM="0" TO="1"/> FROM Mandatory. Valid values: 0 (Default) 1 Optional. Valid values: 0 (Default) 1
TO
3-62
Table 3-10
Parameter
<CYCLIC/>
Description
Indicates if the job is cyclic (to be rerun at regular intervals). Optional. Example: <CYCLIC FROM="0" TO="1"/> FROM Mandatory. Valid values: 0 (Default) 1 Optional. Valid values: 0 (Default) 1
TO
<CONFIRM/>
Indicates that the job must be manually confirmed by the CONTROL-M/EM user before it will run. Optional. Example: <CONFIRM FROM="0" TO="1"/> FROM Mandatory. Valid values: 0 (Default) 1 Optional. Valid values: 0 (Default) 1
TO
<AUTOARCH/>
Determines whether or not SYSDATA is to be archived. Optional. Example: <AUTOARCH FROM=0" TO="1"/> FROM Mandatory. Valid values: 0 (Default) 1 Optional. Valid values: 0 (Default) 1
TO
Job Utilities
3-63
Table 3-10
Parameter
<INTERVAL/>
Description
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" TO="4"/> FROM TO String. Mandatory. String. Optional.
<OVERLIB/>
Name of an alternate job script library/directory. String. Optional. Example: <OVERLIB FROM="lib3" TO="lib4"/> FROM TO String. Mandatory. 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. Example: <MAXWAIT FROM="4" TO="3"/> FROM TO Integer. Mandatory. Integer. Optional.
<DESCRIPTION/>
Free text description of the job. String. Optional. Example: <DESCRIPTION FROM="data backup from 120399" TO="data backup from 021400"/> FROM TO String. Mandatory. String. Optional.
<DOCMEM/>
Name of the file containing job documentation. String. Optional. Example: <DOCMEM FROM="mem4" TO="Mem67"/> FROM TO String. Mandatory. String. Optional.
3-64
Table 3-10
Parameter
<DOCLIB/>
Description
Name of a library or directory containing the job documentation file. String. Optional. Example: <DOCLIB FROM="AcctFiles" TO="HRFiles"/> FROM TO String. Mandatory. String. Optional.
<DAYS/>
Days of the month on which to order the job. String. Optional. Example: <DAYS FROM="ALL" TO="159"/> FROM TO String. Mandatory. 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 TO String. Mandatory. String. Optional.
<WEEKDAYS/>
Days of the week on which to order the job. String. Optional. Example: <WEEKDAYS FROM="1,2,4" TO="ALL"/> FROM TO String. Mandatory. String. Optional.
Job Utilities
3-65
Table 3-10
Parameter
<DATE/>
Description
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. There is no delimiter between dates. For example, January 10 is written: DATE="0110." Mandatory. String. Dates are written in mmdd format. There is no delimiter between dates. For example, January 10 is written: DATE="0110." Optional.
TO
<DAYSCAL/>
Name of a user-defined calendar used to specify a set of days. String. Optional. Example: <DAYSCAL FROM="shipping" TO="receiving"/> FROM TO String. Mandatory. 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 TO String. Mandatory. String. Optional.
<CONFCAL/>
Specifies a calendar that will be used to validate all specified days and dates on which to schedule the job. String. Optional. Example: <CONFCAL FROM="cal99" TO="cal00"/> FROM TO String. Mandatory. String. Optional.
3-66
Table 3-10
Parameter
<RETRO/>
Description
Indicates whether the job should be 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) Optional. Valid values: 0 (Default) 1
TO
<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 Optional. Valid values: IGNOREJOB PREVDAY NEXTDAY NOCONFCAL
TO
<SHIFTNUM/>
Number of days to shift the scheduling date of the job. Optional. Example: <SHIFTNUM FROM="-10" TO="5"/> FROM TO String. Mandatory. String. Optional.
Job Utilities
3-67
Table 3-10
Parameter
<MAXDAYS/>
Description
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 TO String. Mandatory. 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 TO String. Mandatory. 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 TO String. Mandatory. String. Optional.
<RETEN_DAYS/>
Number of days to retain the job in the History Jobs file. [OS/390, only]. String. Optional. Example: <RETEN_DAYS FROM="5" TO="7"/> FROM TO String. Mandatory. String. Optional.
<RETEN_GEN/>
Maximum number of generations of the job to keep in the History Jobs file.[OS/390, only]. String. Optional. Example: <RETEN_GEN FROM="3" TO="4"/> FROM TO String. Mandatory. String. Optional.
3-68
Table 3-10
Parameter
<TASK_CLASS/>
Description
Optional. Example: <TASK_CLASS FROM="Distribution" TO="Decollation"/> FROM TO String. Mandatory. String. Optional.
<PREV_DAY/>
Optional. Example: <PREV_DAY FROM="N" TO="Y"/> FROM Mandatory. Valid values: Y N Optional. Valid values: Y N
TO
<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 Optional. Valid values: START END
TO
Job Utilities
3-69
Table 3-10
Parameter
<TAG_RELATIONSHIP/ >
Description
Relationship (And/Or) between the specified Schedule Tag criteria and the jobs 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 Optional. Valid values: AND OR
TO
<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) Optional. Valid values: 0 (No-Default) 1 (Yes)
TO
<PDSNAME/>
Name of a partitioned dataset (PDS) to be checked for free space. String. Optional. Example: <PDSNAME FROM="Lib_3" TO="Lib_5"/> FROM TO String. Mandatory. String. Optional.
3-70
Table 3-10
Parameter
<MINIMUM/>
Description
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 TO Integer. Mandatory. 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 TO String. Mandatory. String. Optional.
<PREVENTNCT2/>
Prevents dataset cleanup before the original job run. [OS/390 only] Optional. Example: <PREVENTNC2 FROM="1" TO="0"/> FROM Mandatory. Valid values: 0 (Default) 1 Optional. Valid values: 0 (Default) 1
TO
Job Utilities
3-71
Table 3-10
Parameter
Description
Months when the job can run. Optional. Not including a month is the same as including a month having the value, 0. Example: <JAN FROM="0" TO="1"/> FROM Mandatory. Valid values: 0 (Default) 1 Optional. Valid values: 0 (Default) 1
TO
<OPTION/>
Sysout Handling options. Optional. Example: <OPTION FROM="Copy" TO="Release"/> FROM Mandatory. Valid values: Release Delete Copy Move File NewDest ChangeClass Optional. Valid values: Release Delete Copy Move File NewDest ChangeClass
TO
3-72
Table 3-10
Parameter
<PAR/>
Description
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 TO String. Mandatory. String. Optional.
<FROM/>
Limits the sysout handling operation to only sysouts from the specified class. Optional. Example: <FROM FROM="1" TO="2"/> FROM TO String. Mandatory. String. Optional.
<ADJUST_COND/>
Indicates whether or not 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 (Dont ignore. Default.) 1 (Ignore relevant prerequisite conditions) Example: <ADJUST_COND FROM="1" TO="0"/> FROM TO String. Mandatory. String. Optional.
<APPL_TYPE/>
Indicates the type of external application (for example, SAP or Oracle Applications) on which the external application job will run.Mandatory for external application jobs. Mandatory for external application jobs. Example: <APPL_TYPE FROM=SAP TO=OracleApps/> FROM TO Mandatory. String. Up to 10 characters. Optional. String.
Job Utilities
3-73
Table 3-10
Parameter
<APPL_VER/>
Description
Indicates the version of the external application (for example, SAP or Oracle Applications) on which the external application job will run.Mandatory for external application jobs. Mandatory for external application jobs. Example: <APPL_VER FROM=4.5 TO=4.6/> FROM TO Mandatory. String. Up to 10 characters. Optional. String.
<APPL_FORM/>
Specifies a predefined set of external application parameters that will be displayed in the External Application panel of the CONTROL-M/EM Job Editing form. Mandatory for external application jobs. Example: <APPL_FORM FROM=Default SAP 4.6 TO=Default SAP 4.5/> FROM TO Mandatory. String. Up to 30 characters. Optional. String.
<CM_VER/>
Indicates the version of external application (for example, SAP or Oracle Applications) 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 TO Mandatory. String. Up to 10 characters. Optional. String.
<MULTY_AGENT/>
When selected, broadcasts job submission details to all Agents within a specified Node Group. Optional. Example: <MULTY_AGENT FROM=N TO=Y/> FROM Mandatory. Valid values: Y- run as multi-agent job N- not run as multi-agent job. Default. Optional. String.
TO
3-74
Table 3-10
Parameter
<ACTIVE_FROM/>
Description
Indicates the start of a period of time during which the job or Group Scheduling table can be ordered. [For OS/390 jobs and Group Scheduling tables, only] Optional. Example: <ACTIVE_FROM FROM=20020315 TO=20020601/> FROM TO Mandatory. Date Format: YYYYMMDD Optional. String.
<ACTIVE_TILL/>
Indicates the end of a period of time during which the job or Group Scheduling table can be ordered. [For OS/390 jobs and Group Scheduling tables, only] Optional. Example: <ACTIVE_TILL FROM=20020315 TO=20020601/> FROM TO Mandatory. Date Format: YYYYMMDD Optional. String.
<TIMEZONE/>
Indicates the global time zone used to calculate the interval for time-related conditions. Optional. Example: <TIMEZONE FROM=EST (GMT +03:00) TO=GMT/> FROM Mandatory. String. Default: GMT. Optional. String.
TO
Job Utilities
3-75
Table 3-10
Parameter
SYSTEM_AFFINITY
Description
Indicates the identity of the system in which the job must be initiated and executed (in JES2). Indicates the identity of the processor on which the job must execute (in JES3). Optional. String. FROM String. Mandatory. Example: <SYSTEM_AFFINITY FROM=SYS3/> String. Optional. Example: <SYSTEM_AFFINITY FROM=SYS3 TO=SYS6/>
TO
REQUEST_NJE_NODE
Specifies the node in the JES network on which the job is to execute. FROM String. Mandatory. Example: <REQUEST_NJE_NODE=OS5/> String. Optional. Example: <REQUEST_NJE_NODE FROM=OS5 TO=OS6/>
TO
SCHEDULING_ENVIR ONMENT
Indicates the JES2 workload management scheduling environment that is to be associated with the job. OS/390, only. FROM String. Mandatory. Example: <SCHEDULING_ENVIRONMENT FROM=SCHD2/> String. Optional. Example: <SCHEDULING_ENVIRONMENT FROM=SCHD2 TO=SCHD3/>
TO
<JOBS_IN_GROUP/>
Number of jobs in the Group Scheduling table. Optional. Example: <JOBS_IN_GROUP FROM="4" TO="10"/> FROM TO String. Mandatory. String. Optional.
3-76
Table 3-10
Parameter
<CREATION_USER/>
Description
Username of the user that created the job. String. Optional. Example: <CREATION_USER FROM="ecsuser" TO="ecs1"/> FROM TO String. Mandatory. String. Optional.
<CREATION_DATE/>
Date that the job was created. String. Optional. Example: <CREATION_DATE FROM="1212" TO="2012"/> FROM TO String. Mandatory. String. Optional.
<CREATION_TIME/>
Time that the job was created. String. Optional. Example: <CREATION_TIME FROM="1230" TO="1430"/> FROM TO String. Mandatory. String. Optional.
<CHANGE_USERID/>
Username of the user that last modified the job. String. Optional. Example: <CHANGE_USERID FROM="ecsuser" TO="ecsacct"/> FROM TO String. Mandatory. String. Optional.
<CHANGE_DATE/>
Date that the job was last modified. String. Optional. Example: <CHANGE_DATE FROM="1204" TO="1304"/> FROM TO String. Mandatory. String. Optional.
Job Utilities
3-77
Table 3-10
Parameter
<CHANGE_TIME/>
Description
Time that the job was last modified. String. Optional. Example: <CHANGE_TIME FROM="1650" TO="1700"/> FROM TO String. Mandatory. String. Optional.
Following are sample input files used with the duplicatedefjob utility:
Example 1: Copy and modify definitions
Specify job processing definitions from the Tbl5NYC Scheduling table that have the TABLE_DSN Lib1 and the JOBNAME Job3 and makes copies of those jobs where the TABLE_DSN has changed to Lib1_COPY and the JOBNAME has changed to Job3_COPY.
<?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
Copies of all jobs in the Tbl5NYC Scheduling written 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>
3-78
Example 3: Duplicate jobs based on several criteria
Copies of all cyclic jobs in the GrpAcct group that have a jobname beginning with the string, Acct. The copies have the string, _COPY, appended to their Job Names.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE DUPLICATEJOB SYSTEM "duplicatejob.dtd"> <DUPLICATEJOB> <GROUP FROM="GrpAcct"/> <CYCLIC FROM="1"/> <JOBNAME="Acct*" TO="Acct*_COPY"/> </DUPLICATEJOB>
Job Utilities
3-79
exportdefjob
The exportdefjob utility exports job processing definitions from a scheduling table in the CONTROL-M/Enterprise Manager database to an output file. When the exportdefjob utility is invoked, a file of arguments that you have created is processed. This arguments file contains statements that specify an existing job processing definition or group of job processing definitions that are exported to an output file. You can modify the exported job processing definitions in the output file and can import these definitions into the CONTROL-M/Enterprise Manager database using either the defjob or the updatedef utilities.
Note
Output files created by the export utilities in this chapter can be used as import files with the import the utilities described here. For example, you can export job processing definitions to an output file using exportdefjob, make modifications to the definitions and save the file, and use the same file as the input file when running defjob. exportdefjob reads arguments directly from a plain text arguments file (in XML format) instead of reading them from the command line. To invoke the exportdefjob utility: 1. Log on as a CONTROL-M/Enterprise Manager user. 2. Open a command prompt window (Microsoft Windows). You do not need to be in the CONTROL-M/Enterprise Manager directory. 3. At the command prompt, enter the following command:
exportdefjob -HOST <host_name> -USERNAME <user> -PASSWORD <password> -ARG_FILE <args_file_name> -OUT_FILE <out_file_name>
Parameters of the exportdefjob utility are described in Table 3-11, exportdefjob Parameters, on page 3-81.
3-80
4. Press <Enter>. The exportdefjob 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 job processing definitions are saved to an output file, the name and location of which you specified with the parameter <out_file_name>.
Syntax
The parameters of the exportdefjob utility are described in Table 3-11.

Table 3-11 exportdefjob Parameters
Parameter
Description
CONTROL-M/Enterprise Manager host name or IP address. CONTROL-M/Enterprise Manager user name. The CONTROL-M/Enterprise Manager user password. The path and name of the arguments file containing the exportdefjob specifications. For instructions in preparing this file, see Appendix A, XML File Preparation. The path and name of the file containing the exported job specifications.
<out_file_name>
exportdefjob Arguments File
Arguments are used as a selection criteria to determine which job processing definitions to export and are written to the exportdefjob argument file. The arguments files that you create with the exportdefjob 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/Enterprise Manager database. For instructions for creating arguments files, see Appendix A, XML File Preparation.
Job Utilities
3-81
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 (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.
Table 3-12
exportdefjob Arguments 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 to the Short Product Name the version of XML and 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>... </TERMS> <TERM>...</TERM> 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. 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. Valid values: AND OR Optional.
3-82
Table 3-12
exportdefjob Arguments File Parameters (Part 2 of 2)
Parameter
<PARAM/>
Description
The selection criteria parameter used to determine those 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. Mandatory. Job processing parameters are described in Table 3-3, defjob Input File Parameters, on page 3-5. Note: At least one of the following Scheduling table parameters must be included in the arguments file: DATACENTER TABLE_NAME TABLE_DSN Describes the relationship between the NAME and the VALUE parameters of the TERM.Valid values: Valid values: EQ NEQ NOTIN LIKE Mandatory. String. The value of the parameter specified in the NAME field. Job processing parameters are described in Table 3-3, defjob Input File Parameters, on page 3-5. Mandatory.
OP
VALUE
Job Utilities
3-83
Example 1: Exports definitions based on one or more criteria
The output file contains job processing definitions that either: Have the data center name, Data1, and a jobname that begins with the letter J. -or Have the jobname, Job5, and are not cyclic jobs.
<?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
The output file contains all job processing definitions from either the Data1 data center or the 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>
3-84
updatedef
The updatedef utility enables you to update (modify) specific parameter values in the following definitions in the CONTROL-M/EM database: Job processing definitions Scheduling table definitions Group Scheduling table definitions
Note
updatedef for job processing definitions modifies the characteristics of an existing job processing definition. It should not be confused with duplicatedefjob, which creates a new job based on an existing job processing definition in the same datacenter and Scheduling table. The selected jobs, Scheduling tables, and Group Scheduling tables are modified according to specifications in the updatedef arguments file that you create. The updatedef utility does not create new jobs or tables. To invoke the updatedef utility: 1. Log on as a CONTROL-M/Enterprise Manager user. 2. Open a command prompt window (Microsoft Windows). You do not need to be in the CONTROL-M/Enterprise Manager directory. 3. At the command prompt, enter the following command: updatedef -HOST <host_name> -USERNAME <user> -PASSWORD <password> -ARG_FILE <args_file_name> Parameters of the updatedef utility are described in Table 3-13, updatedef Parameters, on page 3-86. 4. Press <Enter>.
Job Utilities
3-85
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.
Syntax
The parameters of the updatedef utility are described in Table 3-13.

Table 3-13 updatedef Parameters
Parameter
Description
CONTROL-M/Enterprise Manager host name or IP address. CONTROL-M/Enterprise Manager user name. The CONTROL-M/Enterprise Manager user password. The path and name of the arguments file containing the updatedef specifications. For instructions in preparing this file, see Appendix A, XML File Preparation.
updatedef Arguments File
The updatedef utility uses the UPDATE 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 an UPDATE 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"). 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 A-7.
Most parameters of the job, Scheduling table, or Group Scheduling table definitions are optional. However:
3-86
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 will be updated.
Note
Group Scheduling table parameters are usually modified using the Group Scheduling table criteria described in Table 3-15. However, using these criteria, you cannot change the name of a Group Scheduling table. To change the name of a Group Scheduling table using the updatedef utility, use the criteria for Scheduling tables (described in Table 3-14) and specify a new value for the TABLE_NAME parameter.
Note
The Scheduling table name parameter of a job processing definition cannot be modified using the job definition criteria described in Table 3-16. However, you can change the name of a jobs Scheduling table using the updatedef utility by using the criteria for Scheduling tables (described in Table 3-14) and specifying a new value for the TABLE_NAME parameter. There are three sets of parameters that can be supplied in an arguments fileone each for jobs, Group Scheduling tables and Scheduling tables. Each group of parameters is described in a table, below: Table 3-14, Arguments File Parameters for Scheduling Tables, on page 3-88 Table 3-15, Arguments File Parameters for Group Scheduling Tables, on page 3-89 Table 3-16, Arguments File Parameters for Jobs, on page 3-96
Job Utilities 3-87
Table 3-14
Arguments File Parameters for Scheduling Tables
Parameter
Description
The first two lines of the XML request file for this API request contain information that specifies to the Short Product Name the version of XML and 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>... </UPDATE> <SCHED_TABLE>... </SCHED_TABLE> 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. 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. Name of the Scheduling table to which the job belongs.\ Optional. Example: <TABLE_NAME FROM=Tbl5NYC TO=Tbl_new/> FROM TO <TABLE_DSN/> String. Mandatory. String. Optional.
<TABLE_NAME/>
Name of the library that contains the scheduling table. [For OS/390 jobs, only.] Optional. <TABLE_DSN FROM=Lib1 TO=Lib2/> FROM TO String. Mandatory. 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: A TO parameter cannot be specified for this parameter. Example: <TABLE_USERDAILY FROM="Job3A"/> FROM TO String. Mandatory. String. Optional.
3-88
Table 3-15
Arguments File Parameters for Group Scheduling Tables (Part 1 of 8)
Parameter
Description
The first two lines of the XML request file for this API request contain information that specifies to the Short Product Name the version of XML and 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>... </UPDATE> <GROUP_SCHED>... </GROUP_SCHED> 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. 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. Name of the Scheduling table to which the job belongs. 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 <DATACENTER/> String. Mandatory
<TABLE_NAME/>
Name of the CONTROL-M installation to which the job belongs. Optional. 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: <DATACENTER FROM="CTMNYC"/> FROM String. Mandatory
Job Utilities
3-89
Table 3-15
Parameter
<TABLE_DSN/>
Description
Name of the library that contains the scheduling table. [For OS/390 jobs, only.] Optional. 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_DSN FROM="CTMNYC"/> FROM String. Mandatory
<TABLE_USERDAILY/>
Optional. Note: This parameter cannot be modified. Example: <TABLE_USERDAILY FROM="CTMNYC"/> FROM String. Mandatory
<GROUP/>
Name of the group to which the job belongs. Used as a descriptive name for related groups of jobs. Optional. Example: <GROUP FROM="Grp_HR" TO="Grp_ACCT"/> FROM TO String. Mandatory. String. Optional.
<USED_BY/>
Optional. Example: <USED_BY FROM="fff" TO="ffg"/> FROM TO String. Mandatory. String. Optional.
<USED_BY_CODE/>
Optional. Example: <USED_BY_CODE FROM="C***" TO="D***"/> FROM TO String. Mandatory. String. Optional.
3-90
Table 3-15
Parameter
<MODIFIED/>
Description
Optional. Example: <MODIFIED FROM="1101" TO="1102"/> FROM TO String. Mandatory. String. Optional.
<LAST_UPLOAD/>
Date of the last table upload. String. Optional. Example: <LAST_UPLOAD FROM="1101" TO="1102"/> FROM TO String. Mandatory. String. Optional.
<CHECKSUM/>
Optional. Example: <CHECKSUM FROM="Y" TO="N"/> FROM TO String. Mandatory. String. Optional.
<TABLE_ID/>
Optional. Example: <TABLE_ID FROM="Tbl001" TO="Tbl002"/> FROM TO String. Mandatory. String. Optional.
<REAL_TABLEID/>
Optional. Example: <REAL_TABLEID FROM="43556" TO="43557"/> FROM TO String. Mandatory. String. Optional.
<JOBNAME/>
Name of the job processing definition. Optional. Example: <JOBNAME FROM="Job3"/> FROM TO String. Mandatory. String. Optional.
Job Utilities
3-91
Table 3-15
Parameter
<MEMNAME/>
Description
Name of the file that contains the job script. Optional. Example: <MEMNAME FROM="Mem3" TO="Mem7"/> FROM TO String. Mandatory. String. Optional.
<APPLICATION/>
Name of the application to which the jobs group belongs. Used as a descriptive name for related groups of jobs. Optional. Example: <APPLICATION FROM="App3""/> FROM TO String. Mandatory. String. Optional.
<OWNER/>
<ADJUST_COND/>
3-92
Table 3-15
Parameter
<CONFIRM/>
Description
TO
<PRIORITY/>
Indicates CONTROL-M job priority. Optional. Example: <PRIORITY FROM="AA" TO="BB"/> FROM TO String. Mandatory. String. Optional.
<TIMEFROM/>
<TIMETO/>
Job Utilities
3-93
Table 3-15
Parameter
<DUE_OUT/>
Description
<DOCMEM/>
<DOCLIB/>
<DESCRIPTION/>
Free text description of the job. String. Optional. Example: <DESCRIPTION FROM="backup jobs from 120399" TO="backup jobs from 021400"/> FROM TO String. Mandatory. String. Optional.
<AUTHOR/>
CONTROL-M/EM user who defined the job. This parameter is used by the CONTROL-M security mechanism. String. Optional. Example: <AUTHOR FROM="ecsuser" TO="ecsadmin"/> FROM TO String. Mandatory. String. Optional.
3-94
Table 3-15
Parameter
<CREATION_USER/>
Description
Username of the user that created the job. String. Optional. Example: <CREATION_USER FROM="ecsuser" TO="ecs1"/> FROM TO String. Mandatory. String. Optional.
<CREATION_DATE/>
Date that the job was created. String. Optional. Example: <CREATION_DATE FROM="1212" TO="2012"/> FROM TO String. Mandatory. String. Optional.
<CREATION_TIME/>
Time that the job was created. String. Optional. Example: <CREATION_TIME FROM="1230" TO="1430"/> FROM TO String. Mandatory. String. Optional.
<CHANGE_USERID/>
Username of the user that last modified the job. String. Optional. Example: <CHANGE_USERID FROM="ecsuser" TO="ecsadmin"/> FROM TO String. Mandatory. String. Optional.
<CHANGE_DATE/>
Date that the job was last modified. String. Optional. Example: <CHANGE_DATE FROM="1204" TO="1304"/> FROM TO String. Mandatory. String. Optional.
Job Utilities
3-95
Table 3-15
Parameter
<CHANGE_TIME/>
Description
Time that the job was last modified. String. Optional. Example: <CHANGE_TIME FROM="1650" TO="1700"/> FROM TO String. Mandatory. String. Optional.
Table 3-16
Arguments File Parameters for Jobs (Part 1 of 21)
Parameter
Description
The first two lines of the XML request file for this API request contain information that specifies to the Short Product Name the version of XML and 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>... </UPDATE> <JOB>... </JOB> 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. These tags indicate the start and end of the job specification. Criteria identifying the jobs to be modified and indicating the types of modifications to be made are located between these tags. Optional. 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.
<TABLE_NAME/>
3-96
Table 3-16
Parameter
<TABLE_DSN/>
Description
Name of the library that contains the scheduling table. [For OS/390 jobs, only.] 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_USERDAILY/>
Mandatory. Notes: 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 TO Mandatory. Optional.
<MEMNAME/>
Name of the file that contains the job script. Optional. Example: <MEMNAME FROM="Mem3" TO="Mem7"/> FROM TO Mandatory. Optional.
Job Utilities
3-97
Table 3-16
Parameter
<GROUP/>
Description
Name of the group to which the job belongs. Used as a descriptive name for related groups of jobs. Optional. Example: <GROUP FROM="Grp_HR"/> FROM Mandatory.
<APPLICATION/>
Name of the application to which the jobs group belongs. Used as a descriptive name for related groups of jobs. Optional. Example: <APPLICATION FROM="App3" TO="App1"/> FROM TO String. Mandatory. String Optional.
3-98
Table 3-16
Parameter
<TASKTYPE/>
Description
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 Valid values [OS/390]: Started_Task Cyclic_Job Cyclic_Task Emergency_Job Emergency_Cyclic_Job Emergency_Task Emergency_Cyclic_Task Optional. Valid values: Job Detached Command Dummy Valid values [OS/390]: Started_Task Cyclic_Job Cyclic_Task Emergency_Job Emergency_Cyclic_Job Emergency_Task Emergency_Cyclic_Task
TO
<AUTHOR/>
CONTROL-M/EM user who defined the job. This parameter is used by the CONTROL-M security mechanism. String. Optional. Example: <AUTHOR FROM="ecsuser" TO="ecs5"/> FROM TO String. Mandatory. String. Optional.
Job Utilities
3-99
Table 3-16
Parameter
<MEMLIB/>
Description
Name of the library/directory in which the job script resides. String. Optional. Example: <MEMLIB FROM="Mem1" TO="Mem4"/> FROM TO String. Mandatory. String. Optional.
<CMDLINE/>
Command string supplied when the job Task Type is Command. Optional. Example: <CMDLINE FROM="C:\Format" TO="C\:CD Ecsnt"/> FROM TO String. Mandatory. String. Optional.
<NODEID/>
Host name of an Agent platform or name of a node group to which the job should be submitted. Optional. Example: <NODEID FROM="Com3" TO="Acct4"/> FROM TO String. Mandatory. Host name of the Agent platform on which the job copy is running Optional.
<OWNER/>
<MAXRERUN/>
Specifies the maximum number of reruns that can be performed for the job. Optional. Example: <MAXRERUN FROM="1" TO="3"/> FROM TO String. Mandatory. String. Optional.
3-100
Table 3-16
Parameter
<TIMEFROM/>
Description
<TIMETO/>
<DUE_OUT/>
<PRIORITY/>
Indicates CONTROL-M job priority. Optional. Example: <PRIORITY FROM="AA" TO="1A"/> FROM TO String. Mandatory. String. Optional.
<CRITICAL/>
Indicates that the job is a critical-path job in CONTROL-M. Optional. Example: <CRITICAL FROM="0" TO="1"/> FROM Mandatory. Valid values: 0 (Default) 1 Optional. Valid values: 0 (Default) 1
TO
Job Utilities
3-101
Table 3-16
Parameter
<CYCLIC/>
Description
Indicates if the job is cyclic (to be rerun at regular intervals). Optional. Example: <CYCLIC FROM="0" TO="1"/> FROM Mandatory. Valid values: 0 (Default) 1 Optional. Valid values: 0 (Default) 1
TO
<CONFIRM/>
TO
<AUTOARCH/>
Determines whether or not SYSDATA is to be archived. Optional. Example: <AUTOARCH FROM=0" TO="1"/> FROM Mandatory. Valid values: 0 (Default) 1 Optional. Valid values: 0 (Default) 1
TO
3-102
Table 3-16
Parameter
<INTERVAL/>
Description
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" TO="4"/> FROM TO String. Mandatory. String. Optional.
<OVERLIB/>
Name of an alternate job script library/directory. String. Optional. Example: <OVERLIB FROM="lib3" TO="lib4"/> FROM TO String. Mandatory. 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. Example: <MAXWAIT FROM="4" TO="3"/> FROM TO Integer. Mandatory. Integer. Optional.
<DESCRIPTION/>
Free text description of the job. String. Optional. Example: <DESCRIPTION FROM="data backup from 120399" TO="data backup from 021400"/> FROM TO String. Mandatory. String. Optional.
<DOCMEM/>
Job Utilities
3-103
Table 3-16
Parameter
<DOCLIB/>
Description
<DAYS/>
Days of the month on which to order the job. String. Optional. Example: <DAYS FROM="ALL" TO="159"/> FROM TO String. Mandatory. 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 TO String. Mandatory. String. Optional.
<WEEKDAYS/>
Days of the week on which to order the job. String. Optional. Example: <WEEKDAYS FROM="1,2,4" TO="ALL"/> FROM TO String. Mandatory. String. Optional.
3-104
Table 3-16
Parameter
<DATE/>
Description
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." 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."
TO
<DAYSCAL/>
Name of a user-defined calendar used to specify a set of days. String. Optional. Example: <DAYSCAL FROM="shipping" TO="receiving"/> FROM TO String. Mandatory. 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 TO String. Mandatory. String. Optional.
<CONFCAL/>
Specifies a calendar that will be used to validate all specified days and dates on which to schedule the job. String. Optional. Example: <CONFCAL FROM="cal99" TO="cal00"/> FROM TO String. Mandatory. String. Optional.
Job Utilities
3-105
Table 3-16
Parameter
<RETRO/>
Description
Indicates whether the job should be 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) Optional. Valid values: 0 (No. Default) 1 (Yes)
TO
<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 Optional. Valid values: IGNOREJOB PREVDAY NEXTDAY NOCONFCAL
TO
<SHIFTNUM/>
Number of days to shift the scheduling date of the job. Optional. Example: <SHIFTNUM FROM="-10" TO="5"/> FROM TO String. Mandatory. String. Optional.
3-106
Table 3-16
Parameter
<MAXDAYS/>
Description
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 TO String. Mandatory. 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 TO String. Mandatory. 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 TO String. Mandatory. String. Optional.
<RETEN_DAYS/>
Number of days to retain the job in the History Jobs file. [OS/390, only]. String. Optional. Example: <RETEN_DAYS FROM="5" TO="7"/> FROM TO String. Mandatory. String. Optional.
<RETEN_GEN/>
Maximum number of generations of the job to keep in the History Jobs file.[OS/390, only]. String. Optional. Example: <RETEN_GEN FROM="3" TO="4"/> FROM TO String. Mandatory. String. Optional.
Job Utilities
3-107
Table 3-16
Parameter
<TASK_CLASS/>
Description
Optional. Example: <TASK_CLASS FROM="Distribution" TO="Decollation"/> FROM TO String. Mandatory. String. Optional.
<PREV_DAY/>
Optional. Example: <PREV_DAY FROM="N" TO="Y"/> FROM Mandatory. Valid values: Y N Optional. Valid values: Y N
TO
<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 Optional. Valid values: START END
TO
3-108
Table 3-16
Parameter
<TAG_RELATIONSHIP/ >
Description
Relationship (And/Or) between the specified Schedule Tag criteria and the jobs 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 Optional. Valid values: AND OR
TO
<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) Optional. Valid values: 0 (Multiple-Default) 1 (Single)
TO
<PDSNAME/>
Name of a partitioned dataset (PDS) to be checked for free space. String. Optional. Example: <PDSNAME FROM="Lib_3" TO="Lib_5"/> FROM TO String. Mandatory. String. Optional.
Job Utilities
3-109
Table 3-16
Parameter
<MINIMUM/>
Description
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 TO Integer. Mandatory. 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 TO String. Mandatory. String. Optional.
<PREVENTNC2/>
Performs dataset cleanup before the original job run. [OS/390 only] Optional. Example: <PREVENTNC2 FROM="1" TO="0"/> FROM Mandatory. Valid values: 0 (Default) 1 Optional. Valid values: 0 (Default) 1
TO
3-110
Table 3-16
Parameter
Description
Months when the job can run. Optional. Not including a month is the same as including a month having the value, 0. Example: <JAN FROM="0" TO="1"/> FROM Mandatory. Valid values: 0 (Default) 1 Optional. Valid values: 0 (Default) 1
TO
<OPTION/>
Sysout Handling options. Optional. Example: <OPTION FROM="Copy" TO="Release"/> FROM Mandatory. Valid values: Release Delete Copy Move File NewDest ChangeClass Optional. Valid values: Release Delete Copy Move File NewDest ChangeClass
TO
Job Utilities
3-111
Table 3-16
Parameter
<PAR/>
Description
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 TO String. Mandatory. String. Optional.
<FROM/>
Limits the sysout handling operation to only sysouts from the specified class. Optional. Example: <FROM FROM="1" TO="2"/> FROM TO String. Mandatory. String. Optional.
<ADJUST_COND/>
<APPL_TYPE/>
Indicates the type of external application (for example, SAP or Oracle Applications) on which the external application job will run.Mandatory for external application jobs. Mandatory for external application jobs. Example: <APPL_TYPE FROM=SAP TO=OracleApps/> FROM TO Mandatory. String. Up to 10 characters. Optional. String.
3-112
Table 3-16
Parameter
<APPL_VER/>
Description
Indicates the version of the external application (for example, SAP or Oracle Applications) on which the external application job will run.Mandatory for external application jobs. Mandatory for external application jobs. Example: <APPL_VER FROM=4.5 TO=4.6/> FROM TO Mandatory. String. Up to 10 characters. Optional. String.
<APPL_FORM/>
Specifies a predefined set of external application parameters that will be displayed in the External Application panel of the CONTROL-M/EM Job Editing form. Mandatory for external application jobs. Example: <APPL_FORM FROM=Default SAP 4.6 TO=Default SAP 4.5/> FROM TO Mandatory. String. Up to 30 characters. Optional. String.
<CM_VER/>
Indicates the version of external application (for example, SAP or Oracle Applications) 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 TO Mandatory. String. Up to 10 characters. Optional. String.
<MULTY_AGENT/>
When selected, broadcasts job submission details to all Agents within a specified Node Group. Optional. Example: <MULTY_AGENT FROM=N TO=Y/> FROM Mandatory. Valid values: Y- run as multi-agent job N- not run as multi-agent job. Default. Optional. String.
TO
Job Utilities
3-113
Table 3-16
Parameter
<ACTIVE_FROM/>
Description
Indicates the start of a period of time during which the job or Group Scheduling table can be ordered. [For OS/390 jobs and Group Scheduling tables, only] Optional. Example: <ACTIVE_FROM FROM=20020315 TO=20020601/> FROM TO Mandatory. Date Format: YYYYMMDD Optional. String.
<ACTIVE_TILL/>
Indicates the end of a period of time during which the job or Group Scheduling table can be ordered. [For OS/390 jobs and Group Scheduling tables, only] Optional. Example: <ACTIVE_TILL FROM=20020315 TO=20020601/> FROM TO Mandatory. Date Format: YYYYMMDD Optional. String.
<TIMEZONE/>
Indicates the global time zone used to calculate the interval for time-related conditions. Optional. Example: <TIMEZONE FROM=EST (GMT +03:00) TO=GMT/> FROM Mandatory. String. Default: GMT. Optional. String.
TO <JOBS_IN_GROUP/>
Number of jobs in the Group Scheduling table. Optional. Example: <JOBS_IN_GROUP FROM="4" TO="10"/> FROM TO String. Mandatory. String. Optional.
3-114
Table 3-16
Parameter
<CREATION_USER/>
Description
Username of the user that created the job. Optional. Example: <CREATION_USER FROM="ecsuser" TO="ecs1"/> FROM TO String. Mandatory. String. Optional.
<CREATION_DATE/>
Date that the job was created. Optional. Example: <CREATION_DATE FROM="1212" TO="2012"/> FROM TO String. Mandatory. String. Optional.
<CREATION_TIME/>
Time that the job was created. Optional. Example: <CREATION_TIME FROM="1230" TO="1430"/> FROM TO String. Mandatory. String. Optional.
<CHANGE_USERID/>
Username of the user that last modified the job. Optional. Example: <CHANGE_USERID FROM="ecsuser" TO="ecsacct"/> FROM TO String. Mandatory. String. Optional.
<CHANGE_DATE/>
Date that the job was last modified. Optional. Example: <CHANGE_DATE FROM="1204" TO="1304"/> FROM TO String. Mandatory. String. Optional.
Job Utilities
3-115
Table 3-16
Parameter
<CHANGE_TIME/>
Description
Time that the job was last modified. Optional. Example: <CHANGE_TIME FROM="1650" TO="1700"/> FROM TO String. Mandatory. String. Optional.
Example 1: Modify GROUP parameter
Groups in the TEST data center that have the GROUP name UnixJobs are modified so that the GROUP name is now 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
The names of Scheduling tables in the TEST data center that have the TABLE_ID 12202 have now 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>
3-116
Example 3: Modify the Job name of a job

<UPDATE> <JOB> <TABLE_NAME FROM="SGMPM1"/>  <DATACENTER FROM="snow"/> <JOBNAME FROM="cnn*" TO="bbc*"/>                                                        
Job Utilities
3-117
                              </JOB> </UPDATE>
3-118
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 in real-time using the Job Editing and Group Editing forms in CONTROL-M/Enterprise Manager and CONTROL-M/Desktop and using 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 4-1.
Table 4-1 Table Utilities
Utility
defcal copydefcal exportdefcal
Description
Imports a Calendar directly into the CONTROL-M/Enterprise Manager database from a text file. (See page 4-2.) Copies Calendar definitions within the database. (See page 4-8.) Exports Calendar definitions to a text file. (See page 4-13.)
Note
The cli utility can upload and download Calendars. It is described in Chapter 2, Command Line Interface Utility (cli).
Calendar Utilities
4-1
defcal
The defcal utility imports a Calendar definition into the CONTROL-M/Enterprise Manager 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/Enterprise Manager user. 2. Open a command prompt window (Microsoft Windows). 3. At the command prompt, specify the following command:
defcal -HOST <host_name> -USERNAME <user> -PASSWORD <password> -SRC_FILE < XML_file_name>
Parameters of the defcal utility are described in Table 4-2, defcal Parameters, on page 4-2. 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.
Syntax
The parameters of the defcal utility are described in Table 4-2.

Table 4-2 defcal Parameters
Parameter
<host_name> <user>
Description
CONTROL-M/EM host name and address. CONTROL-M/EM user name.
4-2
Table 4-2
defcal Parameters
Parameter
<password> <SRC_file_name>
Description
The CONTROL-M/EM user password. 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/Enterprise Manager 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 4-3, defcal Input File Parameters, on page 4-4. 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.
Calendar Utilities
4-3
Table 4-3
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 to the Short Product Name the version of XML and 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>... </DEFCAL> <CALENDAR>... </CALENDAR> Indicates to CONTROL-M/Enterprise Manager 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. Indicates the opening and closing tags of a single Calendar definition. The parameters of the job are listed between the tags, where the ellipses are displayed. 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 of the Calendar. String Mandatory. Calendar type. Mandatory. Valid values: Regular Periodic Relative
NAME TYPE
4-4
Table 4-3
defcal Input File Parameters (Part 2 of 2)
Parameter
<YEAR/>
Description
Year-specific definitions in the Calendar. Mandatory. Example: <YEAR NAME="2001" DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYNNNYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNN YYYYYYYYYYYYYYYYYYYYY" DESCRIPTION="This is the Accounting Jobs calendar for 2001."/> NAME Year for which the Calendar definition applies. String. Mandatory. The value of this attribute is expressed as YYYY (for example, 2000). Days on which the job is ordered. String. Mandatory. 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, and the last letter is December 31. Text description of the Calendar. String. Optional.
DAYS
DESCRIPTION
Calendar Utilities
4-5
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="2001" DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNY YYYYYYYYYYYYYYYYYYYY" DESCRIPTION="Calendar for 2001."/> </CALENDAR> </DEFCAL>
Example 2: Import Two Calendars into Different Data Centers
Two Calendars are imported, each into different data centers, using 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="2001" DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNY YYYYYYYYYYYYYYYYYYYY" DESCRIPTION="Calendar for 2001."/> <CALENDAR DATACENTER="ECS2LA" NAME="HRCal3" TYPE="Regular"> <YEAR NAME="2000"
4-6
DAYS="YYYYYYYYYYYYYYYYNNNYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYNNNNNYYYYYYYYYYYYYYYYNNNYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNY YYYYYYYYYYYYYYYYYNNN" DESCRIPTION="Calendar for 2000."/> </CALENDAR> </DEFCAL>
Calendar Utilities
4-7
copydefcal
The copydefcal utility creates a new calendar definition in the CONTROL-M/Enterprise Manager database identical to any existing calendar definition. Calendars can be copied and saved under a different name in the same data center or a calendar in one data center can be copied to a different data center. The calendar in the new data center can retain the old Calendar name or the name can be changed. Multiple calendars 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 A-7. When the copydefcal utility is invoked, a file of arguments that you have 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 an CONTROL-M/Enterprise Manager user. 2. Open a command prompt window (Windows users, only). You do not need to be in the CONTROL-M/Enterprise Manager directory. 3. At the command prompt, enter the following command:
copydefcal -HOST <host_name> -USERNAME <user> -PASSWORD <password> -ARG_FILE <args_file_name>
Parameters of the copydefcal utility are described in Table 4-4, copydefcal Parameters, on page 4-9. 4. Press <Enter>.
4-8
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.
Syntax
The parameters of the copydefcal utility are described in Table 4-4.

Table 4-4 copydefcal Parameters
Parameter
Description
CONTROL-M/EM host name or IP address. CONTROL-M/EM user name. The CONTROL-M/EM user password. The path and name of the arguments file containing the copydefcal specifications. 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/Enterprise Manager 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").
Calendar Utilities
4-9
Only one COPYCAL parameter can be used in an arguments file.
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 will be 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 A-7. 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.
Table 4-5
copydefcal Arguments 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 to the Short Product Name the version of XML and 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>... </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.
4-10
Table 4-5
copydefcal Arguments File Parameters (Part 2 of 2)
Parameter
<DATACENTER/>
Description
Name of the 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. The data center in which the source Calendar is located. String. Mandatory. TO. The 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. The name of the Calendar from which a copy is made. String. Mandatory. TO. The name of the Calendar copy. The copy retains the name of the original Calendar if this attribute is not used. String. Optional.
Calendar Utilities
4-11
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>
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: Calendar is copied and the copy renamed
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>
4-12
exportdefcal
The exportdefcal utility exports calendar definitions in the CONTROL-M/Enterprise Manager database. 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/Enterprise Manager database using the defcal utility. Output files created by the export utilities in this chapter can be used as import files with the import the utilities described here.
Example
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/Enterprise Manager user. 2. Open a command prompt window (Windows users, only). You do not need to be in the CONTROL-M/Enterprise Manager directory. 3. At the command prompt, enter the following command:
exportdefcal -HOST <host_name> -USERNAME <user> -PASSWORD <password> -ARG_FILE <args_file_name> -OUT_FILE <out_file_name>
Parameters of the copydefcal utility are described in Table 4-6, exportdefcal Parameters, on page 4-14. 4. Press <Enter>.
Calendar Utilities
4-13
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 with the parameter <out_file_name>.
Syntax
The parameters of the exportdefcal utility are described in Table 4-6, exportdefcal Parameters, on page 4-14.
Table 4-6 exportdefcal Parameters
Parameter
Description
CONTROL-M/EM host name and address. CONTROL-M/EM user name. The CONTROL-M/EM user password. The path and name of the arguments file containing the exportdefcal specifications. Instructions for preparing this file are in Appendix A, XML File Preparation. The path and name of the file containing the exported jobs specifications.
<out_file_name>
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/Enterprise Manager database. For instructions for creating arguments files, see Appendix A, XML File Preparation. The following rules apply to the exportdefcal arguments file:
4-14
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.
Table 4-7
exportdefcal Arguments 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 to the Short Product Name the version of XML and 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>... </TERMS> <TERM>...</TERM> 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. 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
Calendar Utilities
4-15
Table 4-7
exportdefcal Arguments File Parameters (Part 2 of 2)
Parameter
<PARAM/>
Description
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 String. Mandatory. Describes the relationship between the NAME and the VALUE parameters of the TERM. Valid values: EQ NEQ NOTIN LIKE String. Mandatory. The 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 for VALUE.
OP
VALUE
4-16
Following are sample arguments files used with the exportdefcal utility:
Example : Export all Calendars in the data center named Cal1
The output file would contain 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>
Calendar Utilities
4-17
4-18
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 and the CONTROL-M utilities ctmdefine and ctmcreate for the same tasks. However, you can also 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 you being present. The utilities described in this chapter are listed in Table 5-1.
Table 5-1 Table Utilities
Utility
deftable exportdeftable
Description
Imports Scheduling table and Group Scheduling table definitions from a user-defined file. (See page 5-3.) Exports Scheduling table and Group Scheduling table definitions to a text file. (See page 5-22.)
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:
5-1
Scheduling table definitions Group Scheduling tables one or more job processing definitions in the CONTROL-M/Enterprise Manager database. updatedef is described in updatedef on page 3-85. The cli utility, which uploads, downloads, orders and forces Scheduling tables and Group Scheduling tables. It is described in Chapter 2, Command Line Interface Utility (cli).
5-2
deftable
The deftable utility imports Scheduling tables and Group Scheduling tables into the CONTROL-M/Enterprise Manager 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/Enterprise Manager database. 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/Enterprise Manager user. 2. Open a command prompt window (Windows users). You do not need to be in the CONTROL-M/Enterprise Manager directory. 3. At the command prompt, enter the following command:
deftable -HOST <host_name> -USERNAME <user> -PASSWORD <password> -SRC_FILE <src_file_name>
Parameters of the deftable command are described in Table 5-2, deftable Parameters, on page 5-4. 4. Press <Enter>.
5-3
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.
Syntax
Table 5-2 deftable Parameters
Parameter
<host_name> <user> <password> <src_file_name>
Description
CONTROL-M/EM host name or IP address. CONTROL-M/EM user name. The CONTROL-M/EM user password. The 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..
deftable Input File
The input file (src_file_name) contains the data that comprises 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/Enterprise Manager database. For instructions for creating input files, see Appendix A, XML File Preparation. 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.
5-4
Table 5-3
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 to the Short Product Name the version of XML and 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>... </DEFTABLE> Indicates to CONTROL-M/Enterprise Manager 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 Indicate the opening and closing tags of a single Scheduling table definition. The parameters of the table are listed between the tags, in place of the ellipses displayed in the column at left. 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. 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 Name of the library that contains the scheduling table. [For OS/390 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 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
<SCHED_TABLE>... </SCHED_TABLE>
TABLE_NAME
TABLE_DSN
DATACENTER
5-5
Table 5-3
deftable Input File Parameters for Scheduling Tables (Part 2 of 2)
Parameter
TABLE_USERDAILY USED_BY USED_BY_CODE MODIFIED LAST_UPLOAD CHECKSUM TABLE_ID REAL_TABLEID <JOB>...</JOB>
Description
For internal use. Do not include this parameter in your deftable input file. For internal use. Do not include this parameter in your deftable input file. For internal use. Do not include this parameter in your deftable input file. For internal use. Do not include this parameter in your deftable input file. Date of the last table upload. String. Optional. For internal use. Do not include this parameter in your deftable input file. For internal use. Do not include this parameter in your deftable input file. For internal use. Do not include this parameter in your deftable input file. Indicate the opening and closing tags of a single job definition. The parameters of the job are listed between the tags, in place of the ellipses displayed in the column on the left. For a complete listing of defjob parameters, see defjob on page 3-3.
Table 5-4
deftable Input File Parameters for Group Scheduling Tables (Part 1 of 13)
Parameter
Description
The first two lines of the XML request file for this API request contain information that specifies to the Short Product Name the version of XML and 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>... </DEFTABLE> Indicates to CONTROL-M/Enterprise Manager 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 Opening and closing tags of a Group Scheduling table definition. 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
<SCHED_GROUP>... </SCHED_GROUP> TABLE_NAME
5-6
Table 5-4
Parameter
GROUP
Description
Name of the group to which the jobs in the Group Scheduling table are assigned. String. Mandatory. 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 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 String. Optional. For internal use. Do not include this parameter in your deftable input file. For internal use. Do not include this parameter in your deftable input file. For internal use. Do not include this parameter in your deftable input file. Date of the last table upload. String. String. Optional. For internal use. Do not include this parameter in your deftable input file. For internal use. Do not include this parameter in your deftable input file. For internal use. Do not include this parameter in your deftable input file. Name of the job processing definition. String. Optional. Name of the file that contains the job script. String. Optional. 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.
DATACENTER
TABLE_DSN
TABLE_USERDAILY USED_BY USED_BY_CODE MODIFIED LAST_UPLOAD CHECKSUM TABLE_ID REAL_TABLEID JOBNAME MEMNAME APPLICATION
5-7
Table 5-4
Parameter
OWNER
Description
Owner (user ID) associated with the Group Scheduling table. This parameter is used by the CONTROL-M security mechanism. String. Optional. 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. Indicates that the Group Scheduling table must be manually confirmed by the CONTROL-M/EM user before it will run. Valid values: 0 (No conformation. Default) 1 (Requires conformation. Default) Indicates CONTROL-M Group Scheduling table priority. String. Optional. Indicates the earliest time for submitting the Group Scheduling table. String. Optional. Indicates the latest time for submitting the Group Scheduling table. String. Optional. Time that the jobs in the Group Scheduling table are expected to finish. String. Optional. Name of the file containing Group Scheduling table documentation. String. Optional. Name of the DOCMEM library. String. Optional. Brief text description of the Group Scheduling table. String. Optional. CONTROL-M/EM user who defined the Group Scheduling table. This parameter is used by the CONTROL-M security mechanism. String. Optional. Username of the user who created the Group Scheduling table. String. Optional. Date on which the Group Scheduling table was created. String. Optional.
ADJUST_COND
CONFIRM
PRIORITY TIMEFROM TIMETO DUE_OUT DOCMEM DOCLIB DESCRIPTION AUTHOR
CREATION_USER
CREATION_DATE
5-8
Table 5-4
Parameter
CREATION_TIME
Description
Time at which the Group Scheduling table was created. String. Optional. Username of the user who last modified the Group Scheduling table. String. Optional. Date on which the Group Scheduling table was last modified. String. Optional. Time at which the Group Scheduling table was last modified. String. Optional. Specifies to broadcast job submission details 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 multi-agent job N- not run as multi-agent job. Default. Indicates the start of a period of time during which the job or Group Scheduling table can be ordered. [For OS/390 jobs and Group Scheduling tables, only] Optional. Date Format: YYYYMMDD Indicates the end of a period of time during which the job or Group Scheduling table can be ordered. [For OS/390 jobs and Group Scheduling tables, only] Optional. Date Format: YYYYMMDD
CHANGE_USERID
CHANGE_DATE
CHANGE_TIME
MULTY_AGENT
ACTIVE_FROM
ACTIVE_TILL
5-9
Table 5-4
Parameter
<TAG/>
Description
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 DAYS Unique name of the tag. String. Mandatory. Days of the month on which to order the jobs in the Group Scheduling table. String. Optional. Indicates the relationship between specified Days values and Weekdays values. Optional. Valid values: AND OR Days of the week on which to order the jobs in the Group Scheduling table. String. Optional. Specific dates on which to order the jobs in the Group Scheduling table. String. mmdd format. String. Optional. Name of a user-defined calendar used to specify a set of days. String. Optional. Specifies a calendar that will be used to validate all specified days and dates on which to schedule the jobs in the Group Scheduling table. String. Optional.
DAYS_AND_OR
WEEKDAYS DATE
DAYSCAL CONFCAL
5-10
Table 5-4
Parameter
<TAG/> continued
Description
RETRO Indicates whether the jobs in the Group Scheduling table should be scheduled for possible execution after their original scheduling date (odate) has passed. Optional. Valid values: 0 (No. Default) 1 (Yes) Describes how to shift the scheduling date of the jobs in the Group Scheduling table. Optional. Valid values: IGNOREJOB PREVDAY NEXTDAY NOCONFCAL Number of days to shift the scheduling date of the jobs in the Group Scheduling table. String. Optional. 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. Maximum number of job runs to retain the SYSDATA archive dataset for jobs that ended NOTOK. Subparameter of AUTOARCH. String. Valid values: 000 998 or 999. Indicating 999 retains the SYSDATA data for all runs. Optional. Months when the jobs in the Group Scheduling table can run. Optional. Valid values: 0 (Default) 1
SHIFT
SHIFTNUM
MAXWAIT
MAXRUNS
JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC
5-11
Table 5-4
Parameter
<TAG_NAMES/>
Description
Wrapper for specifying one or more Scheduling tags for the Group Scheduling table. Example: <TAG_NAMES TAG_NAME="TAG_1"/> TAG_NAME String. Optional.
5-12
Table 5-4
Parameter
<INCOND/>
Description
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. Order date of the In condition. String. Mandatory. Valid values: Default: ODAT Relationship between conditions. Valid values are AND (default) OR Parentheses indicating parts of the condition that are interpreted first. String. Optional.
ODATE
AND_OR
OP
<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. Order date of the Out condition. String. Mandatory. Valid values: Default: ODAT Indicates whether to add or delete the condition. Valid values: ADD (default) DEL
ODATE
SIGN
5-13
Table 5-4
Parameter
<AUTOEDIT/>
Description
Wrapper for the AutoEdit expression. Optional. Example: <AUTOEDIT EXP="%%PARM1=%%TIME"/> EXP The AutoEdit expression. String. Mandatory. Example: %%PARM1=%%TIME.
5-14
Table 5-4
Parameter
<SHOUT/>
Description
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 Recipient of the shout message. String. Mandatory. Valid values: 1-16 characters, case-sensitive. Mandatory. Indicates the urgency of the Shout message. Mandatory. Valid values: R (regular-default) U (urgent) V (very urgent) Text of the message. String. Mandatory. Valid values: 1-70 characters, spaces allowed. Time of the message. String. Mandatory.
DEST
URGENCY
MESSAGE
TIME
5-15
Table 5-4
Parameter
<ON_GROUP>... </ON_GROUP>
Description
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
5-16
Table 5-4
Parameter
<DOSHOUT/>
Description
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 of the Shout message. Valid values: R (regular-default) U (urgent) V (very urgent) Text of the Shout message. String. Mandatory. Valid values: 1-70 characters, spaces allowed. Mandatory.
URGENCY
MESSAGE
<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 TABLE_NAME Library for the Scheduling table [OS/390, only]. String. Mandatory. Name of the Scheduling table to which the job belongs. String. Mandatory. Valid values: 1-10 characters. Name of the job. String. Mandatory. Original scheduling date for the job. String. Default: ODAT
NAME ODATE
5-17
Table 5-4
Parameter
<DOCOND/>
Description
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. Mandatory. Condition date. String. Mandatory. Default: ODAT Specifies whether to add or delete the condition. Valid values: ADD (default) DEL
ODATE
SIGN
<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) Recipient of the message. String. Mandatory. Additional recipient of the message. String. Optional. Brief text description of the message contents. String. Optional. Text of the message. String. Mandatory.
DEST CC_DEST SUBJECT MESSAGE <JOB>...</JOB>
Indicate the opening and closing tags of a single job definition. The parameters of the job are listed between the tags, in place of the ellipses displayed in the column on the left. For a complete listing of defjob parameters, see defjob on page 3-3.
5-18
Following are a 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" 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>
5-19
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" 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"/> <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>
5-20
<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>
5-21
exportdeftable
The exportdeftable utility exports Scheduling tables from the CONTROL-M/Enterprise Manager 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/Enterprise Manager database. To invoke the exportdeftable utility: 1. Log in as a CONTROL-M/Enterprise Manager user. 2. Open a command prompt window (Microsoft Windows). You do not need to be in the CONTROL-M/Enterprise Manager directory. 3. At the command prompt, enter the following command:
exportdeftable -HOST <host_name> -USERNAME <user> -PASSWORD <password> -ARG_FILE <args_file_name> -OUT_FILE <out_file_name>
Parameters of the exportdeftable command are described in Table 5-5, exportdeftable Parameters, on page 5-23. 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 the errors.
5-22
The exported table definitions are saved to an output file, the name and location of which you specified with the parameter <out_file_name>.
Syntax
The parameters of the exportdeftable utility are described in Table 5-5.

Table 5-5 exportdeftable Parameters
Parameter
Description
CONTROL-M/EM host name or IP address. CONTROL-M/EM user name. The CONTROL-M/EM user password. The path and name of the arguments file containing the exportdeftable specifications. Instructions for preparing this file are in Appendix A, XML File Preparation. The path and name of the file containing the exported jobs specifications.
<out_file_name>
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/Enterprise Manager 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.
5-23
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.
Table 5-6
exportdeftable Arguments 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 to the Short Product Name the version of XML and 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>... </TERMS> <TERM>...</TERM> 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. 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
5-24
Table 5-6
exportdeftable Arguments File Parameters (Part 2 of 2)
Parameter
<PARAM/>
Description
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 5-2, deftable Parameters, on page 5-4. Note: At least one of the following Scheduling table parameters must be included in the arguments file: DATACENTER TABLE_NAME TABLE_DSN Mandatory. Describes the relationship between the NAME and the VALUE parameters of the TERM. Valid values: Valid values: EQ NEQ NOTIN LIKE String. Mandatory. The value of any Scheduling table or Group Scheduling table parameter. These parameters are described in Table 5-2, deftable Parameters, on page 5-4. Note: Multiple values can be specified for VALUE by using the * wildcard character in place of characters at the end of an expression.
OP
VALUE
5-25
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>
5-26
The utilities described in this chapter can be used to maintain the CONTROL-M/Enterprise Manager database and to import and export information to and from additional CONTROL-M/Enterprise Manager databases. Many of the tasks performed by the database maintenance utilities can also be performed in real-time 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 6-1 Database Maintenance Utilities
Utility
db_check util
Description
Provides general information about a database and its status. Provides CONTROL-M/EM database management functions from a command line.
6-1
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 the db_check utility 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 [-d<db threshold %>] [-l<log threshold %>] [-n] [-h]
6-2
Table 6-2
db_check Utility parameters
Parameter
<db_threshold %>
Description
Specifies a maximum percentage of database use. When this percentage is exceeded, a message is displayed alerting you to extend the database. Specifies a maximum percentage of transaction log use. When this percentage is exceeded, a message is displayed alerting you to extend the transaction log. When -n is specified, db_check is executed without verifying the total database integrity. When -h is specified, db_check displays the amount of database space that is in use.
<log_threshold %>
-n -h
Note
You will be prompted for the CONTROL-M/EM administrator password when using the db_check utility.
6-3
util
The util utility is a multi-purpose utility that is used to perform the following operations 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 on how to resolve this problem, see Transferring Definition Tables between Database Systems on page 6-13. The util utility is automatically installed on Microsoft Windows computers with the CONTROL-M/EM Gateway component.
To Invoke the util Utility:
Use the following steps to invoke the util utility from the command line:
Step 1
Open a Command Prompt window (Microsoft Windows) or go to the command line (Unix). Change the working directory to the CONTROL-M/Enterprise Manager home directory. Enter one of the following commands:
Microsoft Windows: util <DB_ARGS> <function> <function parameters>
Step 2
Step 3
6-4
Unix: ecs util <DB_ARGS> <function> <function parameters>
Table 6-3 describes the database arguments <DB_ARGS>. Table 6-4 describes the functions of the util utility. Table 6-5 describes the function parameters.
Database Arguments Parameter
All the functions utilize the database arguments parameter <DB_ARGS>. This parameter is entered in the following format:
[-D <database>][-U <user>][-P <password>] [-S <server>][-T <level>][-dbms <system>] [-dbtimeout <sec>][-dbfile <path>]
Table 6-3 Fields of the Database Arguments Parameter <DB_ARGS>
Fields
<database>
Description
Name of database on which to perform the operation. If not specified, the CONTROL-M/Enterprise Manager database defined during installation is used. Database user. Database user password. Name of the database server. If not specified, the server defined during installation is used. Database debug level (1-3). The database management system in use, valid values are either Sybase or Oracle. Note: If you are using an MSSQL database system, choose Sybase. Database timeout, in seconds. Full path name for the database debug report. If the file already exists, it will be overwritten. The default path and filename is: <home directory>/DB_<time/date>.log
<user> <password> <server> <level> <system>
<sec> <path>
6-5
Functions of the util Utility
The syntax of each function of the util utility under Microsoft Windows is as specified in the table below. For Unix, add ecs and a space before specifying util, for example, ecs util <DB_ARGS> -build_schema [-cdbg {1 - 5}]
Table 6-4 util Utility Functions (Part 1 of 3)
Function
-export
Description
Exports job processing definitions, Calendars, CONTROL-M data, and so on, from the CONTROL-M/Enterprise Manager database to a text (ASCII) 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>] Note: When 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. Imports job processing definitions, Calendars, CONTROL-M data, and so on, from a text (ASCII) file to the CONTROL-M/Enterprise Manager 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>] Note: When 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. Note: You must stop all CONTROL-M/EM components before performing this operation.
-import
6-6
Table 6-4
util Utility Functions (Part 2 of 3)
Function
-delete
Description
Deletes the specified database table. Syntax: util <DB_ARGS> -delete [-silent] [-cdbg {1 - 5}]{-name {<name>}} Note: You must stop all CONTROL-M/EM components before performing this operation. Deletes all database tables. Syntax: util <DB_ARGS> -clean_database [-silent] [-cdbg {1 - 5}] Note: This utility completely deletes the database tables. It should be used only with extreme caution. It is recommended to backup the database before issuing this command. Note: You must stop all CONTROL-M/EM components before performing this operation. Builds the CONTROL-M/Enterprise Manager database. It defines the structure and the type of contents of each data element within the database. Syntax: util <DB_ARGS> -build_schema [-cdbg {1 - 5}] Note: You must stop all CONTROL-M/EM components before performing this operation.
-clean_database
-build_schema
6-7
Table 6-4
util Utility Functions (Part 3 of 3)
Function
-defexport
Description
Exports the specified CONTROL-M/Enterprise Manager definition table to a text (ASCII) file. Syntax: util <DB_ARGS> -defexport [-cdbg {1 - 5}] -table <tablename> -dcname <dcname> [-library <library>] -file <file> Note: When 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. Imports the specified CONTROL-M/Enterprise Manager definition table from a text (ASCII) 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> Note: When 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. Note: You must stop all CONTROL-M/EM components before performing this operation.
-defimport
6-8
Parameters of the util Utility Functions
Table 6-5 describes the parameters of the util utility functions.

Table 6-5 util Utility Function Parameters (Part 1 of 3) Description Suppresses application messages. Overwrites existing data in the specified table. Note: -replace should be used 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. The debug level ranges from 1 to 5 (highest level). Use this option only when instructed to do so by Technical Support. Using this option can slow performance and use extra disk space.
Parameter
-silent -replace
-cdbg
6-9
Table 6-5
util Utility Function Parameters (Part 2 of 3) Description Name of the CONTROL-M/Enterprise Manager component that is configured by one or more of the following: all def cal sys dc user alert gc All application data. Default. Job processing definition data. Calendar data. The applications system data. Data center definition data. CONTROL-M/Enterprise Manager user data and authorizations. Alert data for the CONTROL-M/Enterprise Manager database. Global conditions prerequisite conditions that are passed between CONTROL-M installations by CONTROL-M/Enterprise Manager. Maintenance tables. Collection definitions. ViewPoint definitions. Filter definitions. Messages saved to a file. Hierarchy definitions.
Parameter
-type
maint collect view filter log hier
Note: More than one -type can be used. - type net Type of CONTROL-M/Enterprise Manager net. -name Name of the CONTROL-M/Enterprise Manager 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
6-10
Table 6-5
util Utility Function Parameters (Part 3 of 3) Description Specifies the details of the source or destination file. file -file Name of the source or destination file. Exports to standard output. Default: user monitor Imports from standard input. Default: user keyboard Exports or imports from a specified directory. dir Directory of the source or destination file if different from CONTROL-M/Enterprise Manager home directory. file-list List of text (ASCII) files to be exported or imported, in the format: <filename>... <filename>
Parameter
-file
-dir
-name
CONTROL-M/Enterprise Manager net identified by the following name: name Name of the ECONTROL-M/Enterprise Manager net.
-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/Enterprise Manager library identified by the following library type: library Type of CONTROL-M/Enterprise Manager 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 user ecsuser1, whose password is secure01:
util -U ecsuser1 -P secure01 -export -type def \
-file production
6-11
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/Enterprise Manager database: 1. Stop all CONTROL-M/Enterprise Manager gateways. 2. Specify the following command:
util -U ecsuser1 -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 -P ecsuser1 -U secure1 -delete \ -name A0301190CT_BJOB Example 4: Clean the database
The following command cleans database WAGE_RATES:

util -D WAGE_RATES -U ecsuser1 -P secure01 \ -clean_database Example 5: Build a database schema
The following command builds a new schema for database PAYROLL:

util -D PAYROLL -U ecsuser1 -P secure1 -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/Enterprise Manager database to the file wip_stores:
6-12
util -U ecsuser1 -P secure1 -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 ecsuser1 -P secure1 -defimport \ -replace -table WORK_IN_PROGRESS -file wip_stores
Transferring Definition Tables between Database Systems

Due to differing date formats between different database platforms, the transfer of definition tables from one database platform to another might fail. To resolve this problem, follow these steps:
Step 1
Copy the Defaults.rsc file to Defaults.old. The Defaults.rsc file is located in the path \gtwgcs\appl\ecs\resource for Microsoft Windows computers and in the site/resource/ directory on Unix computers. Modify (or add) the appropriate date format line in the Defaults.rsc file. Date format specifications for each data migration are listed in Table 6-6.
Table 6-6 Date Format Specifications in Defaults.rsc
Step 2
Exporting From
Sybase MSSQL
Importing To
Oracle Oracle
Date Format Specification

Database Oracle DefDateFormat 1 Database Oracle DefDateFormat 2
Note
If you are migrating data from one Oracle database to another, remove the Database Oracle DefDateFormat <number> line from the Defaults.rsc file before the upgrade (if it is in the file).
6-13
For more information about the Defaults.rsc file, see the CONTROL-M/Enterprise Manager Administrator Guide.
Step 3
Specify the following command from the command prompt where you intend to run the util utility to migrate data to a database on Oracle Server:
Microsoft Windows: set NLS_DATE_FORMAT=<Date Format> Unix (case-sensitive): setenv NLS_LANG AMERICAN_AMERICA.WE8ISO8859P1 setenv NLS_DATE_FORMAT "<Date Format>"
where the value of <Date Format> is mm dd yyyy hh:miAM.
Step 4
Run the util import utility. When the import has been completed successfully, restore the Defaults.rsc file by copying Defaults.old to Defaults.rsc.
6-14
Administration Utilities
Monitoring and maintaining your CONTROL-M/Enterprise Manager 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 t check_gtw and ctl can also be performed in real-time 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 7-1
Utility
check_gtw cryptocli
Description
Checks that the specified gateway is running. (See page 7-2) Enables the CONTROL-M/EM administrator to encrypt a text string for use as the administrator password. The utility inserts the encrypted password the relevant places in the mcs.ini file. (page 7-4) The ctl command line utility enables you to send simple requests to networked CONTROL-M/Enterprise Manager components. (page 7-6)
ctl
7-1
check_gtw
The Gateway Verification utility (check_gtw) is used to verify the availability of the gateways. The utility checks all currently enabled data centers to verify if their gateway is running. If any check fails, an Alert is sent to one or more e-mail addresses that you specify. To invoke the check_gtw utility:
Specify the following command:

check_gtw -u -p [-m [-t [-w [-s [-e [-f <db user> <db password> <test_mode> ] <time_interval> ] <waiting_time> ] <max_number_of_parallel_dc> ] <address> -e <address> ... ] <file>]
The parameters are described in Table 7-2).

Table 7-2 check_gtw Utility Parameters (Part 1 of 2)
Parameter
db_user db_password test_mode
Description
Database user name. Database user password. 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. Default. 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.
time_interval waiting_time
Time interval (in seconds) between tests. Default 200. Time (in seconds) to wait for all the gateways to respond. Use with ctlbg only.
7-2
Table 7-2
check_gtw Utility Parameters (Part 2 of 2)
Parameter
max_number _of_dc address file
Description
Maximum number of ecs.ctl commands to be launched concurrently. Default: Number of enabled data centers. E-mail addresses to which the Alerts are sent. Contains e-mail addresses to which the Alerts are sent. Addresses must be separated by a blank space or written on a separate line. If a check fails, the utility activates the user exit script $EM_HOME/check_gtw_ue, if it exists. This script receives three environment variables from check_gtw: $DATA_CENTER, $UserName, and $Passwd. An empty template for this script is supplied with CONTROL-M/Enterprise Manager. Note: The check_gtw_ue script need to be executable and in the user PATH.
7-3
cryptocli
The cryptocli utility creates an encrypted version of the password you submit. If the CONTROL-M/Enterprise Manager 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 the new password, Cryptocli creates an encrypted version of the password and inserts that encrypted version 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/Enterprise Manager home directory. 3. Specify the following command:
cryptocli.exe <string_to_encrypt> <output_filename>
Where:
7-4
Item
<string_to_ encrypt> <output_file_ name>
Description
New CONTROL-M/Enterprise Manager administrator password. Full path name of the output file created by cryptocli. The file contains the encrypted version of the password that was submitted.
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/Enterprise Manager home directory. 3. Specify the following command:
cryptocli.exe <user_name> <new_password> <mcs.ini_path_name>
Where:
Item
<user_name> <new_password> <mcs.ini_path _name>
Description
CONTROL-M/Enterprise Manager administrator user name. New CONTROL-M/Enterprise Manager administrator password. Full path name of the mcs.ini file (for example, windir\system32\mcs.ini).
7-5
ctl
The ctl command line utility enables you to send simple requests to networked CONTROL-M/Enterprise Manager components. The ctl utility can: Check if networked CONTROL-M/Enterprise Manager components are operational. Set the gateway debug level. Send commands to CONTROL-M/Enterprise Manager components and component parameters during runtime.
The ctl utility is automatically installed with the Gateway or Administration Facility components. You can modify ctl commands with many attributes.
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/Enterprise Manager home directory. 3. Specify the ctl command line. For ctl syntax, see ctl Command Syntax on page 7-7. To invoke ctl from Unix: 1. Open an Xterm window. 2. Log in as the CONTROL-M/Enterprise Manager administrator. 3. Specify the ctl command line. For ctl syntax, see ctl Command Syntax on page 7-7.
7-6
ctl Command Syntax ctl-U <user_name> -P <password> -C {Gateway | GCS | GUI_Server | GAS | License_Mngr | | maint_agent | Hostmon} { -dc <Data_Center> | -M <computer_name> | -all } { -reg | -cmd <command> [<command>] | -cmdstr <"Command string"> } [ -timeout <Response_Timeout <seconds>>] [ -diagon ]
The parameters of the ctl utility are described in Table 7-3.

Table 7-3 ctl Parameters (Part 1 of 3)
Parameter
-U -P -C Gateway GCS (Global Conditions Server) GUI_Server
Description
CONTROL-M/Enterprise Manager user name. CONTROL-M/Enterprise Manager password. Type of component to which the command is directed. Valid values: Mediates between CONTROL-M/Enterprise Manager components and the CONTROL-M installation. Handles the distribution of conditions that affect jobs in more than one data center. Handles communication between CONTROL-M/Enterprise Manager GUI workstations and other CONTROL-M/Enterprise Manager components. Identifies and distributes alerts between CONTROL-M installations and CONTROL-M/Enterprise Manager workstations. Controls CONTROL-M/Enterprise Manager components on the host computer. For BMC Software support use only.
GAS (Global Alerts Server) maint_agent Hostmon
7-7
Table 7-3
ctl Parameters (Part 2 of 3)
Parameter
-dc
Description
Specifies the name of a data center. This data center name is used to identify 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 using the -C parameter). -dc cannot be used with -M or -all. Specifies a computer name. This name is used to identify the computer to which the specific component belongs. This parameter is used when a query or command is directed to any component other than a gateway (as specified with the -C parameter). -M cannot be used with -dc or -all. Directs a query or command to all networked components of the type specified with the -C parameter. -all is used instead of the -dc and -M parameters. -all cannot be used with -M or -dc. Checks if the component is registered in the CommReg table. -reg cannot be used with -cmd or -cmdstr. Indicates a command to be performed by the selected component or components. See Table 7-4 for a list of the commands. -cmd cannot be used with -reg or -cmdstr. More than one instance of the -cmd parameter can be specified in the command line. Specifies a text string to be sent to the specified component. If the text string contains spaces or tabs, it must be enclosed with double quotes ( ). -cmdstr cannot be used with -reg or -cmd.
-M
-all
-reg
-cmd
-cmdstr
7-8
Table 7-3
ctl Parameters (Part 3 of 3)
Parameter
-timeout
Description
Indicates the period of time (in seconds) that ctl waits for a response from the specified component before declaring the communication a failure. Default: 30. Optional. Activates tracing of ctl work flow (diagnostics). The results are written to the diag.txt file located in the working directory. Place this parameter as the first argument to debug the following ctl arguments in the command, as well as other component functions. Place this parameter as the last argument to avoid parsing the other ctl arguments in the command. Optional.
-diagon
ctl Commands
Table 7-4 describes commands that can be specified using the -cmd parameter.
Table 7-4 ctl Commands (Part 1 of 2)
Command
shutdown
Description
Stops components and administration agents without changing their configurations. Stopping an administration agent with this command also stops all components that the agent administers.
Commands that apply to all components stop do_measure get_measure Stops the component. Initiates collection of statistics about the component.ctl commands: Retrieves statistics from the component and displays them. This command cannot be included in the same command line run of the ctl utility as do_measure. Checks if the component is active or not.
life_check
Commands that apply only to gateways dwl Forces a new download from the CONTROL-M installation.
7-9
Table 7-4
ctl Commands (Part 2 of 2)
Command
change_log no_dbg db1 host+ hosttrunc+ truncalive+ alivejob+
Description
Creates a new gateway log file. Stops all debug printing. Sets the debugging level. Values between 0-9 can be entered. 0 turns off debugging. Starts output of host debug messages. Stops output of host debug messages. Starts truncating messages. Only the message header and one row of data remain after truncation. Stops truncating messages. Starts debugging keep alive messages. Stops debugging keep alive messages. Starts 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. Stops dumping job messages. Starts a debug trace for the download procedure. Stops a debug trace for the download procedure. Starts a debug trace for the host link. Stops a debug trace for the host link. Starts a debug trace for the GUI link. Stops a debug trace for the GUI link. Starts a debug trace for the GUI. Stops a debug trace for the GUI. Shows active JCL.
jobdwl_debug+ dwl_debughostlink+ hostlinkguilink+ guilinkgui+ guishow_jcl
Limitations
Use of certain ctl utility parameters is subject to the following limitations:
7-10
All commands except stop, life_check, do_measure, and get_measure are relevant only when the component is a gateway (-C Gateway). The stop,shutdown, life_check, do_measure, and get_measure commands cannot be specified with other commands in the same run of the ctl utility. Use the data center switch (-dc) or the all switch (-all) with the -C Gateway parameter to specify gateway locations. Use the computer name parameter (-M) to specify the location of components other than gateways. When using -cmdstr, a string with two or more words must be enclosed in double quotation marks ( ). diagon must be the first argument in the debug statement to begin argument parsing. diagon must be the last argument to omit argument parsing.
7-11
7-12
XML File Preparation
Some CONTROL-M/Enterprise Manager 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.
CONTROL-M/EM Utility Commands

Each utility is composed of two parts: the utility command
A-1
input file containing either data to enter into the CONTROL-M/Enterprise Manager database or arguments for selecting specific data from the database. This file is passed to the database by the utility command.
In addition, the export utilities create an output file containing the data specified in the arguments file.
Preparing an Input File

The CONTROL-M/EM utilities read input text files that are used to enter information into the CONTROL-M/Enterprise Manager database. The 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 the job name Job5. The action that is performed on the selected jobs is determined by the type of utility that is calling the TERMS file. Using this TERMS file with deldefjob will delete all job processing definitions in the database for non-cyclic jobs with the job name Job5.
A-2
Example
This file contains one TERMS statement. The statement specifies that non-cyclic jobs with the 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 in enclosed 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 A-1. 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.
A-3
Table A-1
Utility Operators
Operator
EQ NEQ LIKE
Description
Equals. Select cases that include the specified value. Not equal. Select cases that include any value different from the one specified. 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. Not including. Exclude cases that include the specified value.
NOTIN
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 on 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 you submit by running the utility. The .dtd file includes the following information: The 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.
A-4
Whether the valid values for an element or attribute are mandatory or optional. The 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 all share the same .dtd file. The utility .dtd files are stored in the <CONTROL-M/EM_home>\ecscli\Resource directory (on Microsoft Windows).
Table 1-2 CONTROL-M/EM Utility .dtd Files
File Name
copycal.dtd copyjob.dtd defcal.dtd defjob.dtd deftable.dtd duplicatejob.dtd terms.dtd update.dtd
Description
Validates the copydefcal input file. Validates the copydefjob input file. Validates the defcal input file. Validates the defjob input file. Validates the deftable input file. Validates the duplicatedefjob input file. Validates the exportdefjob, exportdefcal, and exportdeftable arguments files. Validates the updatedef input file.
To create a file: 1. Open any text editor or an XML editor. 2. Enter the data specified for the utility that you are using according to the format described in the examples in the parameter description tables and in the file example. Each utility has tables describing the parameters and an example of a completed file.
A-5
3. Check the syntax of the file for errors. If errors remain, they will be 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 word YES in place of a 1.
Note
CONTROL-M/Enterprise Manager 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 with are listed in Table A-3. An example follows the table.
A-6
Table A-3
Reserved Character Codes
Character
" (double-quote) (single-quote, apostrophe) < (left-angle bracket) > (right-angle bracket) & (ampersand)
Replacement Code
" ' < > & Note: The ampersand character can be used in the character replacement codes.
Example: Using reserved character codes in an XML file.
Incorrect: <INCOND NAME="if5<6run" ODATE="ODAT" AND_OR="AND" OP="("/> Correct: <INCOND NAME="if5<6'run'" 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.
A-7
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 will 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 will select any other jobs with a Job Name that ends with the letters CCC.
<JOB_NAME FROM="*CCC"/> 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.
A-8
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.
A-9
A-10
Index
Index
util utility parameters 6-5 - type net util utility function parameters 6-10 as a wildcard in Find/Replace operations A-8 as a wildcard in search criteria A-8 using as a wildcard A-7 authorization 1-2
Symbols
* A-7 .dtd file CONTROL-M/EM Utility .dtd Files A-5 description A-4 validating XML files A-4
B
-build_schema util utility functions 6-7 building CONTROL-M/EM database 6-12 building a CONTROL-M/EM database util utility 6-4
A
administration agents shutdown using ctl 7-9 stopping using ctl 7-9 alert processing gateway check errors 7-2 -append util utility function parameters 6-11 application support Oracle Applications 1-1 SAP 1-1 AS/400. See iSeries (AS/400) asterisk
C
calendars cli utility 2-5 copying 4-8 downloading 2-5 exporting 4-13 handling using the cli utility 2-5 importing 4-2 uploading 2-5 -cdbg
Index
util utility function parameters 6-9 check_gtw utility description 7-2 invoking 7-2 parameters 7-2 test mode 7-2 -clean_database util utility functions 6-7 cleaning ENTERPRISE/CS database 6-12 clearing a database util utility 6-4 cli utility 2-1 invoking 2-1 job deletion parameters 2-9 parameters 2-2 command line interface batch utility 2-1 CONTROL-M/EM administrator password encryption 7-4 CONTROL-M/EM components shutdown using ctl 7-9 stopping using ctl 7-9 CONTROL-M/EM database building 6-12 check size with db_check 6-2 transaction log monitoring with db_check 6-2 verify integrity with db_check 6-2 convert_dc utility 1-4 converting Scheduling table to Group Scheduling table 3-43 copydefcal utility 4-8 arguments file 4-9 copycal.dtd A-5 copyjob.dtd A-5 examples 4-12 invoking 4-8 parameters 4-10
rules 4-9 copydefjob utility 3-24 arguments file 3-25 examples 3-42 invoking 3-24 rules 3-26 copying calendar definitions 4-8 job definitions 3-24, 3-54 jobs to a Group Scheduling table 3-43 creating calendar definitions 4-2, 4-8 job definitions 3-3, 3-24, 3-54 cryptocli operational mode 7-4 trial mode 7-4 ctl -cmd command switch 7-8 command descriptions 7-9 command syntax 7-7 description 7-6 gateway commands 7-9 Global Alerts Server 7-7 Global Conditions Server 7-7 GUI server 7-7 Hostmon 7-7 parameter descriptions 7-7 shutdown command 7-9 stop command description 7-9
D
databases arguments parameter (db_args) 6-5 db threshhold % parameter 6-3 db_args parameter util utility 6-5 db_check utility 6-2 db threshhold % parameter 6-3 log threshold % parameter 6-3
db_check utility functions check available database space 6-2 report database size 6-2 transaction log monitoring 6-2 verify database integrity 6-2 -dcname util utility function parameters 6-11 debugging ctl gateway commands 7-9 Keep Alive messages 7-10 util utility 6-9 Defaults.rsc file updating 6-14 defcal utility 4-2 defcal.dtd A-5 examples 4-6 input file 4-3 invoking 4-2 -defexport util utility functions 6-8 -defimport util utility functions 6-8 defining seealso creating defjob utility 3-3 defjob.dtd A-5 example 3-23 defjobconvert examples 3-47 defjobconvert utility 3-45 invoking 3-45 messages 3-46 deftable utility 5-3 deftable.dtd A-5 examples 5-19 input file 5-4 invoking 5-3 parameters 5-5, 5-6 rules 5-4 deldefjob utility 3-48
arguments file 3-49 examples 3-52 invoking 3-48 parameters 3-50 rules 3-49 -delete util utility functions 6-7 deleting from CONTROL-M/EM database 6-12 job definitions 2-8 jobs definitions (in batch) 3-48 parameters of the cli utility 2-9 deleting a database util utility 6-4 documentation accessing online 6 conventions 7 online 6 printed 6 related publications 5 downloading calendars 2-5 Scheduling tables 2-4 duplicatedefjob utility 3-54 arguments file 3-55 duplicatejob.dtd A-5 examples 3-78 invoking 3-54 parameters 3-57 rules 3-56
E
EnablePriv utility 1-4 EQ utility operator A-4 examples copydefcal utility 4-12 copydefjob 3-42 defcal utility 4-6
Index 3
defjob 3-23 defjobconvert 3-47 deftable utility 5-19 deldefjob 3-52 duplicatedefjob utility 3-78 exportdefcal utility 4-17 exportdeftable utility 5-26 util utility 6-11 -export util utility functions 6-6 exportdefcal utility 4-13 arguments file 4-14 examples 4-17 invoking 4-13 parameters 4-15 rules 4-14 terms.dtd A-5 exportdefjob utility 3-80 arguments file 3-81 invoking 3-80 parameters 3-82 rules 3-82 terms.dtd A-5 exportdeftable utility 5-22 arguments file 5-23 examples 5-26 invoking 5-22 parameters 5-24 exporting a definition table 6-12 calendars 4-13 from CONTROL-M/EM database 6-11 job processing definitions 3-80 Scheduling tables 5-22 exporting database data util utility 6-4 exporting database definition table util utility 6-4
F
-file util utility function parameters 6-11 forcing into a Group Scheduling table 2-6 job 2-6 using the cli utility 2-4, 2-6 format CONTROL-M/EM utilities A-1
G
gateways checking (check_gtw) 7-2 ctl commands 7-9 ctl utility 7-7 Global Alerts Server ctl utility 7-7 Global Conditions Server ctl utility 7-7 Group Scheduling table copying jobs from a Scheduling table 3-43 forcing a job into 2-6 Group Scheduling tables modifying with updatedef 3-85 updating 3-85 group scheduling tables importing 5-3 updating 3-85 GUI server ctl utility 7-7
I
-import util utility functions 6-6
importing calendar definitions 4-2 definition tables 6-13 job definitions 3-3 Scheduling tables 5-3 to CONTROL-M/EM database 6-12 importing database data util utility 6-4 importing database definition table util utility 6-4 invoking copydefcal utility 4-8 copydefjob 3-24 defcal 4-2 defjobconvert 3-45 deftable utility 5-3 deldefjob 3-48 duplicatedefjob 3-54 exportdefcal utility 4-13 exportdefjob 3-80 exportdeftable utility 5-22 updatedef 3-85 util utility 6-4
jobs copying 3-24, 3-54 creating 3-3
L
-library util utility function parameters 6-11 life check ctl 7-9 LIKE utility operator A-4 log threshold % parameter 6-3
M
mcs.ini cryptocli password modification 7-4, 7-5 password encryption 7-5 Mem Name parameter 2-8 migrate_dc utility 1-4 modifying see also creating password 7-4 updatedef 3-85 monitoring database log 6-2 transaction log 6-2 mySAP. See SAP
J
job forcing 2-6 ordering with the cli utility 2-7 job definition deleting by Mem Name 2-8 job definitions converting to version 6.1.0x 3-45 deleting 2-8 modifying with updatedef 3-85 job processing definitions deleting 3-48 exporting 3-80 updating 3-85 JOBISN value 3-3
N
-name util utility function parameters 6-11 NEQ utility operator A-4 NOTIN utility operator A-4
Index
O
Oracle Applications application support 1-1 ordering Scheduling tables 2-5 using the cli utility 2-7
P
parameters copydefcal utility 4-10 deftable utility 5-5, 5-6 deldefjob 3-50 duplicatedefjob 3-57 exportdefcal utility 4-15 exportdefjob 3-82 exportdeftable utility 5-24 updatedef 3-88, 3-89, 3-96 util utility 6-5 passwords encryption 7-4
R
R/3. See SAP -replace util utility function parameters 6-9 rules copydefcal utility 4-9 deftable utility 5-4 duplicatedefjob utility 3-56 exportdefcal utility 4-14 exportdefjob 3-82
application support 1-1 Scheduling table copying jobs to a Group Scheduling table 3-43 Scheduling tables downloading 2-4 exporting 5-22 forcing 2-4 importing 5-3 modifying with updatedef 3-85 ordering 2-5 updating 3-85 uploading 2-4 security cryptocli utility 7-4, 7-5 -silent util utility function parameters 6-9 starting gateway debug message truncation 7-10 gateway host debug messages 7-10 stopping administration agent using ctl 7-9 component using ctl 7-9 ctl shutdown command 7-9 ctl stop command 7-9 gateway debug message truncation 7-10 output of gateway host debug messages 7-10
T
-table util utility function parameters 6-11 transferring definition tables 6-13 truncating gateway debugging messages using ctl 7-10 -type util utility function parameters 6-10
S
SAP
6
U
updatedef utility 3-85 arguments file 3-86 invoking 3-85 parameters 3-88, 3-89, 3-96 update.dtd A-5 uploading calendars 2-5 Scheduling tables 2-4 util utility 6-4 debugging with 6-9 examples 6-11 invoking 6-4 parameters 6-5 util utility function parameters -append 6-11 -cdbg 6-9 -dcname 6-11 -file 6-11 -library 6-11 -name 6-11 -replace 6-9 -silent 6-9 -table 6-11 -type 6-10 -type net 6-10 util utility functions build_schema 6-7 building a CONTROL-M/EM database 6-4 -clean_database 6-7 clearing database data 6-4 -defexport 6-8 -defimport 6-8 -delete 6-7 deleting a database 6-4 -export 6-6 exporting database data 6-4 exporting database definition table 6-4
-import 6-6 importing database data 6-4 importing database definition table 6-4 util utility parameters 6-5, 6-5, 6-5, 6-5, 6-5, 6-5, 6-5, 6-5 utilities authorization 1-2 check_gtw 7-2 command line interface 2-1 convert_dc 1-4 copydefcal 4-8 copydefjob 3-24 cryptocli 7-4 ctl 7-6 db_check 6-2 defcal 4-2 defjob 3-3 defjobconvert 3-45 deftable 5-3 deldefjob 3-48 description 1-1 duplicatedefjob 3-54 EnablePriv 1-4 exportdefcal 4-13 exportdefjob 3-80 exportdeftable 5-22 file structure A-2 format A-1 migrate_dc 1-4 operators list A-4 preparing an XML input file A-2 updatedef 3-85 using XML input files 1-2, A-1 util 6-4 utility operators EQ A-4 LIKE A-4 NEQ A-4 NOTIN A-4
Index
V
validating .dtd file A-4 XML files A-4 verifying database integrity with db_check utility 6-2
W
wildcard asterisk A-7 in Find/Replace operations A-8 in search criteria A-8
X
XML creating a file A-5 examples A-3 file structure A-2 use in utilities 1-2, A-5 utility format A-1
END USER LICENSE AGREEMENT NOTICE

BY OPENING THE PACKAGE, INSTALLING, PRESSING "AGREE" OR "YES" OR USING THE PRODUCT, THE ENTITY OR INDIVIDUAL ENTERING INTO THIS AGREEMENT AGREES TO BE BOUND BY THE FOLLOWING TERMS. IF YOU DO NOT AGREE WITH ANY OF THESE TERMS, DO NOT INSTALL OR USE THE PRODUCT, PROMPTLY RETURN THE PRODUCT TO BMC OR YOUR BMC RESELLER, AND IF YOU ACQUIRED THE LICENSE WITHIN 30 DAYS OF THE DATE OF YOUR ORDER CONTACT BMC OR YOUR BMC RESELLER FOR A REFUND OF LICENSE FEES PAID. IF YOU REJECT THIS AGREEMENT, YOU WILL NOT ACQUIRE ANY LICENSE TO USE THE PRODUCT. This Agreement ("Agreement") is between the entity or individual entering into this Agreement ("You") and BMC Software Distribution, Inc., a Delaware corporation located at 2101 CityWest Blvd., Houston, Texas, 77042, USA or its affiliated local licensing entity ("BMC"). "You" includes you and your Affiliates. "Affiliate" is defined as an entity which controls, is controlled by or shares common control with a party. THIS AGREEMENT WILL APPLY TO THE PRODUCT, UNLESS (1) YOU AGREED TO A WEB BASED LICENSE AGREEMENT WITH BMC WHEN ORDERING THE PRODUCT, IN WHICH CASE THAT WEB BASED LICENSE AGREEMENT GOVERNS THE USE OF THE PRODUCT, OR (2) IF YOU DID NOT AGREE TO A WEB BASED LICENSE AGREEMENT WITH BMC WHEN ORDERING THE PRODUCT AND YOU HAVE A WRITTEN LICENSE AGREEMENT WITH BMC, THEN THAT WRITTEN AGREEMENT GOVERNS THE USE OF THE PRODUCT. THE ELECTRONIC AGREEMENT PROVIDED WITH THE PRODUCT AS PART OF THE INSTALLATION OF THE PRODUCT WILL NOT APPLY. In addition to the restrictions imposed under this Agreement, any other usage restrictions contained in the Product installation instructions or release notes shall apply to Your use of the Product. PRODUCT AND CAPACITY. "Software" means the object code version of the computer programs provided, via delivery or electronic transmission, to You. Software includes computer files, enhancements, maintenance modifications, upgrades, updates, bug fixes, and error corrections. "Documentation" means all written or graphical material provided by BMC in any medium, including any technical specifications, relating to the functionality or operation of the Software. "Product" means the Software and Documentation. "License Capacity" means the licensed capacity for the Software with the pricing and other license defining terms, including capacity restrictions, such as tier limit, total allowed users, gigabyte limit, quantity of Software, and/or other capacity limitations regarding the Software. For licenses based on the power of a computer, You agree to use BMCs current computer classification scheme, which is available at http://www.bmc.com or can be provided to You upon request. ACCEPTANCE. The Product is deemed accepted by You, on the date that You received the Product from BMC. LICENSE. Subject to the terms of this Agreement, as well as Your payment of applicable fees, BMC grants You a non-exclusive, non-transferable, perpetual (unless a term license is provided on an order) license for each copy of the Software, up to the License Capacity, to do the following: (a) install the Software on Your owned or leased hardware located at a facility owned or controlled by You in the country where You acquired the license; (b) operate the Software solely for processing Your own data in Your business operations; and (c) make one copy of the Software for backup and archival purposes only (collectively a "License"). If the Software is designed by BMC to permit you to modify such Software, then you agree to only use such modifications or new software programs for Your internal purposes or otherwise consistent with the License. BMC grants You a license to use the Documentation solely for Your internal use in Your operations. LICENSE UPGRADES. You may expand the scope of the License Capacity only pursuant to a separate agreement with BMC for such expanded usage and Your payment of applicable fees. There is no additional warranty period or free support period for license upgrades. RESTRICTIONS: You agree to NOT: (a) disassemble, reverse engineer, decompile or otherwise attempt to derive any Software from executable code; (b) distribute or provide the Software to any third party (including without limitation, use in a service bureau, outsourcing environment, or processing the data of third parties, or for rental, lease, or sublicense); or (c) provide a third party with the results of any functional evaluation or benchmarking or performance tests, without BMCs prior written approval, unless prohibited by local law.
TRIAL LICENSE. If, as part of the ordering process, the Product is provided on a trial basis, then these terms apply: (i) this license consists solely of a non-exclusive, non-transferable evaluation license to operate the Software for the period of time specified from BMC or, if not specified, a 30 day time period ("Trial Period") only for evaluating whether You desire to acquire a capacity-based license to the Product for a fee; and (ii) Your use of the Product is on an AS IS basis without any warranty, and BMC, ITS AFFILIATES AND RESELLERS, AND LICENSORS DISCLAIM ANY AND ALL WARRANTIES (INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT) AND HAVE NO LIABILITY WHATSOEVER RESULTING FROM THE USE OF THIS PRODUCT UNDER THIS TRIAL LICENSE ("Trial License"). BMC may terminate for its convenience a Trial License upon notice to You. When the Trial Period ends, Your right to use this Product automatically expires. If You want to continue Your use of the Product beyond the Trial Period, contact BMC to acquire a capacity-based license to the Product for a fee. TERMINATION. This Agreement shall immediately terminate if You breach any of its terms. Upon termination, for any reason, You must uninstall the Software, and either certify the destruction of the Product or return it to BMC. OWNERSHIP OF THE PRODUCT. BMC or its Affiliates or licensors retain all right, title and interest to and in the BMC Product and all intellectual property, informational, industrial property and proprietary rights therein. BMC neither grants nor otherwise transfers any rights of ownership in the BMC Product to You. BMC Products are protected by applicable copyright, trade secret, and industrial and intellectual property laws. BMC reserves any rights not expressly granted to You herein. CONFIDENTIAL AND PROPRIETARY INFORMATION. The BMC Products are and contain valuable confidential information of BMC ("Confidential Information"). Confidential Information means non-public technical and non-technical information relating to the BMC Products and Support, including, without limitation, trade secret and proprietary information, and the structure and organization of the Software. You may not disclose the Confidential Information to third parties. You agree to use all reasonable efforts to prevent the unauthorized use, copying, publication or dissemination of the Product. WARRANTY. Except for a Trial License, BMC warrants that the Software will perform in substantial accordance with the Documentation for a period of one year from the date of the order. This warranty shall not apply to any problems caused by software or hardware not supplied by BMC or to any misuse of the Software. EXCLUSIVE REMEDY. BMCs entire liability, and Your exclusive remedy, for any defect in the Software during the warranty period or breach of the warranty above shall be limited to the following: BMC shall use reasonable efforts to remedy defects covered by the warranty or replace the defective Software within a reasonable period of time, or if BMC cannot remedy or replace such defective copy of the Software, then BMC shall refund the amount paid by You for the License for that Software. BMCs obligations in this section are conditioned upon Your providing BMC prompt access to the affected Software and full cooperation in resolving the claim. DISCLAIMER. EXCEPT FOR THE EXPRESS WARRANTIES ABOVE, THE PRODUCT IS PROVIDED "AS IS." BMC, ITS AFFILIATES AND LICENSORS SPECIFICALLY DISCLAIM ALL OTHER WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. BMC DOES NOT WARRANT THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR FREE, OR THAT ALL DEFECTS CAN BE CORRECTED. DISCLAIMER OF DAMAGES. IN NO EVENT IS BMC, ITS AFFILIATES OR LICENSORS LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES RELATING TO OR ARISING OUT OF THIS AGREEMENT, SUPPORT, AND/OR THE PRODUCT (INCLUDING, WITHOUT LIMITATION, LOST PROFITS, LOST COMPUTER USAGE TIME, AND DAMAGE OR LOSS OF USE OF DATA), EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, AND IRRESPECTIVE OF ANY NEGLIGENCE OF BMC OR WHETHER SUCH DAMAGES RESULT FROM A CLAIM ARISING UNDER TORT OR CONTRACT LAW. LIMITS ON LIABILITY. BMCS AGGREGATE LIABILITY FOR DAMAGES IS LIMITED TO THE AMOUNT PAID BY YOU FOR THE LICENSE TO THE PRODUCT. SUPPORT. If Your order includes support for the Software, then BMC agrees to provide support (24 hours a day/7 days a week) ("Support"). You will be automatically re-enrolled in Support on an annual basis unless BMC receives notice of termination from You as provided below. There is a free support period during the one year warranty period. (a) Support Terms. BMC agrees to make commercially reasonable efforts to provide the following Support: (i) For malfunctions of supported versions of the Software, BMC provides bug fixes, patches or workarounds in order to cause that copy of the Software to operate in substantial conformity with its then-current operating specifications; and (ii) BMC provides new releases or versions, so long as such new releases or versions are furnished by BMC to all other enrolled Support customers without additional charge. BMC may refuse to provide Support for any versions or releases of the Software other than the most recent version or release of such Software made available by BMC. Either party may terminate Your enrollment in Support upon providing notice to the other at least 30 days prior to the next applicable Support anniversary date. If You re-enroll in Support, BMC may charge You a reinstatement fee of 1.5 times what You would have paid if You were enrolled in Support during that time period. (b) Fees. The annual fee for Support is 20% of the Softwares list price less the applicable discount or a flat capacity based annual fee. BMC may change its prices for the Software and/or Support upon at least 30 days notice prior to Your support anniversary date.
VERIFICATION. If requested by BMC, You agree to deliver to BMC periodic written reports, whether generated manually or electronically, detailing Your use of the Software in accordance with this Agreement, including, without limitation, the License Capacity. BMC may, at its expense, audit Your use of the Software to confirm Your compliance with the Agreement. If an audit reveals that You have underpaid fees, You agree to pay such underpaid fees. If the underpaid fees exceed 5% of the fees paid, then You agree to also pay BMCs reasonable costs of conducting the audit. EXPORT CONTROLS. You agree not to import, export, re-export, or transfer, directly or indirectly, any part of the Product or any underlying information or technology except in full compliance with all United States, foreign and other applicable laws and regulations. GOVERNING LAW. This Agreement is governed by the substantive laws in force, without regard to conflict of laws principles: (a) in the State of New York, if you acquired the License in the United States, Puerto Rico, or any country in Central or South America; (b) in the Province of Ontario, if you acquired the License in Canada (subsections (a) and (b) collectively referred to as the "Americas Region"); (c) in Singapore, if you acquired the License in Japan, South Korea, Peoples Republic of China, Special Administrative Region of Hong Kong, Republic of China, Philippines, Indonesia, Malaysia, Singapore, India, Australia, New Zealand, or Thailand (collectively, "Asia Pacific Region"); or (d) in the Netherlands, if you acquired the License in any other country not described above. The United Nations Convention on Contracts for the International Sale of Goods is specifically disclaimed in its entirety. ARBITRATION. ANY DISPUTE BETWEEN YOU AND BMC ARISING OUT OF THIS AGREEMENT OR THE BREACH OR ALLEGED BREACH, SHALL BE DETERMINED BY BINDING ARBITRATION CONDUCTED IN ENGLISH. IF THE DISPUTE IS INITIATED IN THE AMERICAS REGION, THE ARBITRATION SHALL BE HELD IN NEW YORK, U.S.A., UNDER THE CURRENT COMMERCIAL OR INTERNATIONAL, AS APPLICABLE, RULES OF THE AMERICAN ARBITRATION ASSOCIATION. IF THE DISPUTE IS INITIATED IN A COUNTRY IN THE ASIA PACIFIC REGION, THE ARBITRATION SHALL BE HELD IN SINGAPORE, SINGAPORE UNDER THE CURRENT UNCITRAL ARBITRATION RULES. IF THE DISPUTE IS INITIATED IN A COUNTRY OUTSIDE OF THE AMERICAS REGION OR ASIA PACIFIC REGION, THE ARBITRATION SHALL BE HELD IN AMSTERDAM, NETHERLANDS UNDER THE CURRENT UNCITRAL ARBITRATION RULES. THE COSTS OF THE ARBITRATION SHALL BE BORNE EQUALLY PENDING THE ARBITRATORS AWARD. THE AWARD RENDERED SHALL BE FINAL AND BINDING UPON THE PARTIES AND SHALL NOT BE SUBJECT TO APPEAL TO ANY COURT, AND MAY BE ENFORCED IN ANY COURT OF COMPETENT JURISDICTION. NOTHING IN THIS AGREEMENT SHALL BE DEEMED AS PREVENTING EITHER PARTY FROM SEEKING INJUNCTIVE RELIEF FROM ANY COURT HAVING JURISDICTION OVER THE PARTIES AND THE SUBJECT MATTER OF THE DISPUTE AS NECESSARY TO PROTECT EITHER PARTYS CONFIDENTIAL INFORMATION, OWNERSHIP, OR ANY OTHER PROPRIETARY RIGHTS. ALL ARBITRATION PROCEEDINGS SHALL BE CONDUCTED IN CONFIDENCE, AND THE PARTY PREVAILING IN ARBITRATION SHALL BE ENTITLED TO RECOVER ITS REASONABLE ATTORNEYS FEES AND NECESSARY COSTS INCURRED RELATED THERETO FROM THE OTHER PARTY. U.S. GOVERNMENT RESTRICTED RIGHTS. The Software under this Agreement is "commercial computer software" as that term is described in 48 C.F.R. 252.227-7014(a)(1). If acquired by or on behalf of a civilian agency, the U.S. Government acquires this commercial computer software and/or commercial computer software documentation subject to the terms of this Agreement as specified in 48 C.F.R. 12.212 (Computer Software) and 12.211 (Technical Data) of the Federal Acquisition Regulations ("FAR") and its successors. If acquired by or on behalf of any agency within the Department of Defense ("DOD"), the U.S. Government acquires this commercial computer software and/or commercial computer software documentation subject to the terms of this Agreement as specified in 48 C.F.R. 227.7202 of the DOD FAR Supplement and its successors. MISCELLANEOUS TERMS. You agree to pay BMC all amounts owed no later than 30 days from the date of the applicable invoice, unless otherwise provided on the order for the License to the Products. You will pay, or reimburse BMC, for taxes of any kind, including sales, use, duty, tariffs, customs, withholding, property, value-added (VAT), and other similar federal, state or local taxes (other than taxes based on BMCs net income) imposed in connection with the Product and/or the Support. This Agreement constitutes the entire agreement between You and BMC and supersedes any prior or contemporaneous negotiations or agreements, whether oral, written or displayed electronically, concerning the Product and related subject matter. No modification or waiver of any provision hereof will be effective unless made in a writing signed by both BMC and You. You may not assign or transfer this Agreement or a License to a third party without BMCs prior written consent. Should any provision of this Agreement be invalid or unenforceable, the remainder of the provisions will remain in effect. The parties have agreed that this Agreement and the documents related thereto be drawn up in the English language. Les parties exigent que la prsente convention ainsi que les documents qui sy rattachent soient rdigs en anglais.
SW EULA Int 030102
Notes
*16985* *16985* *16985* *16985*

*16985*

CM Enterprise Manager Utility Guide

Enviado por

Dados do documento

Descrição original:

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

CM Enterprise Manager Utility Guide

Enviado por

Direitos autorais:

Formatos disponíveis

CONTROL-M /Enterprise Manager Utility Guide

June 20, 2002

Restricted Rights Legend

Contacting BMC Software

United States and Canada

Outside United States and Canada

Support Web Site

Support by Telephone or E-mail

Before Contacting BMC Software

BMC Software, Inc., Confidential and Proprietary Information

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Utility Guide

deftable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 exportdeftable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22

BMC Software, Inc., Confidential and Proprietary Information

Database Maintenance Utilities

CONTROL-M/EM Utility Commands . . . . . . . . . . . . . . . . . . . . . . A-1 Preparing an Input File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Utility Guide

BMC Software, Inc., Confidential and Proprietary Information

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Utility Guide

About This Book

How This Book Is Organized

BMC Software, Inc., Confidential and Proprietary Information

About This Book

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Utility Guide

BMC Software, Inc., Confidential and Proprietary Information

About This Book

Online and Printed Books

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Utility Guide

The following conventions are used in this guide:

Menu => Option

BMC Software, Inc., Confidential and Proprietary Information

About This Book

One-Step Procedures Ellipsis

denotes one-step instructions.

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Utility Guide

BMC Software, Inc., Confidential and Proprietary Information

Utilities Described in this Book

Utility Types (Part 1 of 2)

Calendar Utilities Scheduling Table Utilities

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Utility Guide

Utility Types (Part 2 of 2)

Utilities Not Described in this Book

BMC Software, Inc., Confidential and Proprietary Information

Utilities Not Included in this Book

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Utility Guide

Command Line Interface Utility (cli) 2

Command Line Interface Utility (cli)

The parameters in the above commands are described in Table 2-1.

Parameter <user_id> <password> <host_name>

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Utility Guide

cli Utility Parameters (Part 2 of 2)

Parameter <service _parameters>

<control-m> <table> <calendar> <job_name> <Odate>

BMC Software, Inc., Confidential and Proprietary Information

Command Line Interface Utility (cli)