Control-M

9.0.00.500
Utilities Guide

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

Address BMC SOFTWARE INC Telephone  713 918 8800 Fax 713 918 8000
2103 CITYWEST BLVD  800 841 2031
HOUSTON TX
77042-2827
USA

Outside United States and Canada

Telephone (01) 713 918 8800 Fax (01) 713 918 8000

© Copyright 1999-2017 BMC Software, Inc.

Your use of this information is subject to the terms and conditions of the applicable End User License
Agreement for the product and the proprietary and restricted rights notices included in this
documentation. No part of this publication may be reproduced, stored in a retrieval system, or transmitted
in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the
prior written permission of BMC Software, Inc.
BMC, BMC Software, the BMC logo, the BMC Software logo, and other BMC marks, and the tagline “Bring
IT to Life” are the exclusive properties of BMC Software, Inc., or its affiliates or subsidiaries and are
registered or may be registered with the U.S. Patent and Trademark Office and in other countries. All
other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or
in other countries. All other trademarks or registered trademarks are the property of their respective
owners.
For BMC Control-M Products that are licensed on the “per CPU – Full Capacity” unit of measurement and
installed in an Amazon Web Services (“AWS”) or Microsoft Azure (“Azure”) cloud environment, a license is
required for the total number of CPUs in each AWS or Azure instance upon which the Product is installed
or which the Product manages, either remotely or locally. For AWS, one CPU is equivalent to one vCPU, as
defined by AWS. For Azure, one CPU is equivalent to up to four Virtual Cores (as defined by Azure),
rounded up to the closest multiple of four.
Server Endpoint Licensing
All machines upon which any Control-M component is installed or upon which Control-M managed
workload runs must be licensed. This includes Control-M Agent platforms onto which one or more
application plug-ins are installed but also includes Control-M Agent platforms where no application
plug-ins are installed.
The licensing guidelines for application plug-ins are as follows:

2
 ERP and BI/DI: The application server(s) upon which Control-M managed processes are executed
should be licensed in addition to the Control-M Agent machine(s) (in some cases, this may be the
same machine).
 Databases: Each database server upon which Control-M managed database related processes are
being executed should be counted in addition to the Control-M Agent machine(s).
 AFT and MFT: Only the machine(s) upon which the AFT or MFT plug-in is installed should be licensed.
 Web Services, Java & Messaging: Only the Control-M Agent machine(s) upon which the plug-in is
installed should be licensed.
 Backup: The Control-M Agent machine(s) where the Backup plug-in is installed and also the hosts
which are running the backup server software should be licensed (note that this excludes the client
machines for which the Backup Server software is managing actual backup processes except where a
backup takes place of the backup server machine itself).
 Cloud: Only the Control-M Agent machine(s) upon which the plug-in is installed should be licensed.
 Hadoop: All machines in each managed Hadoop Cluster should be licensed.
IBM® Tivoli® Business Service Manager, IBM Tivoli Workload Scheduler, IBM Cognos, IBM InfoSphere
DataStage, IBM iSeries, IBM Websphere, and AIX® are the trademarks or registered trademarks of
International Business Machines Corporation in the United States, other countries, or both.
UNIX® is the registered trademark of The Open Group in the US and other countries.
Linux is the registered trademark of Linus Torvalds.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks
of their respective owners.
SAP® R/2 and SAP R/3, SAP Business Objects, and SAP NetWeaver are trademarks or registered
trademarks of SAP AG in Germany and in several other countries.

Restricted rights legend

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

3
 Read overviews about support services and programs that BMC offers
 Find the most current information about BMC products
 Search a database for issues similar to yours and possible solutions
 Order or download product documentation
 Download products and maintenance
 Report an issue or ask a question
 Subscribe to receive proactive e-mail alerts when new product notices are released
 Find worldwide BMC support center locations and contact information, including e-mail addresses, fax
numbers, and telephone numbers
Support by telephone or e-mail
In the United States and Canada, if you need technical support and do not have access to the web, call
800 537 1813 or send an e-mail message to [email protected]. (In the subject line, enter
SupID:<yourSupportContractID>, such as SupID:12345). Outside the United States and Canada,
contact your local support center for assistance.
Before contacting BMC
Have the following information available so that Customer Support can begin working on your issue
immediately:
 Product information
• Product name
• Product version (release number)
• License number and password (trial or permanent)
 Operating system and environment information
• Machine type
• Operating system type, version, and service pack or other maintenance level such as PUT or PTF
• System hardware configuration
• Serial numbers
• Related software (database, application, and communication) including type, version, and service
pack or maintenance level
 Sequence of events leading to the issue
 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

4
License key and password information
If you have questions about your license key or password, contact BMC as follows:
 (USA or Canada) Contact the Order Services Password Team at 800 841 2031, or send an e-mail
message to [email protected].
 (Europe, the Middle East, and Africa) Fax your questions to EMEA Contracts Administration at +31 20
354 8702, or send an e-mail message to [email protected].
 (Asia-Pacific) Contact your BMC sales representative or your local BMC office.
Third party Software
For the provisions described in the BMC License Agreement and Order related to third party products or
technologies included in the BMC Product, see
https://docs.bmc.com/docs/display/workloadautomation/Control-M+Workload+Automation+Documentati
on and click Third-party software (TPS).

5
Contents
Introduction to Utilities ................................................................................................. 10
Methods for running utilities .......................................................................................................... 11
Utility reference table ................................................................................................................... 22
Utility workflow between Control-M/Server and Control-M/Agent ..................................................... 29
Control-M/EM requests and communication ................................................................................... 30
Parameter name cross references.................................................................................................. 31

XML file rules ............................................................................................................... 35

XML file example .......................................................................................................................... 36
XML file for I18N environment....................................................................................................... 37
XML file validation ........................................................................................................................ 37
Creating an XML file ..................................................................................................................... 38
Reserved character codes ............................................................................................................. 39
Wildcards ..................................................................................................................................... 39

Definition, ordering, and monitoring utilities ................................................................... 41

emdef utility for jobs .................................................................................................................... 42
emdef utility for services ............................................................................................................. 174
emwacli for promotion ................................................................................................................ 182
Control-M/Server utilities ............................................................................................................ 188
Control-M/Agent utilities ............................................................................................................. 263

Folders and Calendars utilities ..................................................................................... 265

emdef utility for folders and calendars ......................................................................................... 266
cli utility ..................................................................................................................................... 302
ctmcalc_date.............................................................................................................................. 315
ctmdeffolder .............................................................................................................................. 318
ctmdefsubfolder ......................................................................................................................... 322
ctmrpln ...................................................................................................................................... 324

New day procedure and user dailies ............................................................................. 328

ctmordck ................................................................................................................................... 328
ctmudchk ................................................................................................................................... 331
ctmudlst .................................................................................................................................... 333
ctmudly ..................................................................................................................................... 335

6
Active Jobs Database utilities....................................................................................... 339
ctmcontb ................................................................................................................................... 339
ctmipc ....................................................................................................................................... 344
ctmloadset ................................................................................................................................. 346
ctmstvar .................................................................................................................................... 349
ctmvar ....................................................................................................................................... 350
ecactltb ..................................................................................................................................... 356

Communication, start up, and troubleshooting .............................................................. 357

ctl ............................................................................................................................................. 359
orbadmin ................................................................................................................................... 376
ctm_agstat................................................................................................................................. 380
ctm_diag_comm ......................................................................................................................... 382
ctmgetcm .................................................................................................................................. 384
ctmhostmap ............................................................................................................................... 386
ctmhostgrp ................................................................................................................................ 392
ctmping ..................................................................................................................................... 394
ctmshout ................................................................................................................................... 399
ctmshtb ..................................................................................................................................... 401
ctmspdiag .................................................................................................................................. 402
ctmsuspend ............................................................................................................................... 403
init_prflag .................................................................................................................................. 403
shut_ca ..................................................................................................................................... 406
shut_ctm ................................................................................................................................... 406
show_ca .................................................................................................................................... 407
shutdb ....................................................................................................................................... 407
start_ca ..................................................................................................................................... 408
start_ctm ................................................................................................................................... 408
startdb....................................................................................................................................... 409
ctm_pause ................................................................................................................................. 409
ctmchangeshdir .......................................................................................................................... 410
ag_diag_comm........................................................................................................................... 410
ag_ping ..................................................................................................................................... 413
shagent ..................................................................................................................................... 414

Administration and configuration ................................................................................. 415

ag_change_password ................................................................................................................. 417
agkeystore ................................................................................................................................. 419
ctmagcpk ................................................................................................................................... 423

7
ccmcli ........................................................................................................................................ 424
ctm_menu ................................................................................................................................. 428
ctmag ........................................................................................................................................ 428
ctmagcln .................................................................................................................................... 429
ctmdiskspace ............................................................................................................................. 431
ctmkeygen ................................................................................................................................. 432
ctmkeystore_mng ....................................................................................................................... 438
ctmldnrs .................................................................................................................................... 442
ctmlog ....................................................................................................................................... 445
ctmsys ....................................................................................................................................... 448
ctmunixcfg ................................................................................................................................. 455
ctmwincfg .................................................................................................................................. 456
Running the ctmwincfg utility ...................................................................................................... 456
ecaqrtab .................................................................................................................................... 457
emmftcli .................................................................................................................................... 461
emcha -restore ........................................................................................................................... 465
erase_audit_data........................................................................................................................ 465
purge_xalerts ............................................................................................................................. 467
purge_runinfo ............................................................................................................................ 468
Loading prerequisite conditions from manual conditions file .......................................................... 469
Creating the manual conditions file .............................................................................................. 469
Manual conditions parameters ..................................................................................................... 470
Manual conditions file example .................................................................................................... 470
Running the ctm_remedy_configure utility ................................................................................... 471
set_agent_mode ........................................................................................................................ 471
Health Check utility .................................................................................................................... 473

Database maintenance ............................................................................................... 495

Control-M/EM utilities ................................................................................................................. 496
Control-M/Server utilities ............................................................................................................ 544
Interactive database utilities ....................................................................................................... 570

Security ..................................................................................................................... 586

emcryptocli ................................................................................................................................ 586
ctmsec ....................................................................................................................................... 588
ctmsetown ................................................................................................................................. 597
ctmpasswd................................................................................................................................. 602
ctmpwd ..................................................................................................................................... 603

8
Statistics and reporting ............................................................................................... 606
bim_report ................................................................................................................................. 606
emreportcli ................................................................................................................................ 608
ctmjsa ....................................................................................................................................... 612
ctmruninf ................................................................................................................................... 615
ctmstats .................................................................................................................................... 618

Upgrade .................................................................................................................... 621

migrate_dc ................................................................................................................................ 621

Forecast .................................................................................................................... 625

Running the forecastcli utility ...................................................................................................... 625
forecastcli parameters ................................................................................................................ 626
forecastcli filter options ............................................................................................................... 627
forecastcli examples ................................................................................................................... 627

Batch Discovery ......................................................................................................... 628

Running the Batch Discovery utility ............................................................................................. 628
Batch Discovery parameters ........................................................................................................ 629
Batch Discovery return codes ...................................................................................................... 629

Unsupported utilities ................................................................................................... 630

9
1
1
Introduction to Utilities
Utilities can be used to perform many common Control-M tasks from the command prompt of any
computer where Control-M components are installed.
Although many of the tasks performed by these utilities can be performed using Control-M or the
Control-M Configuration Manager, the utilities enable you to work at computers that do not have the GUI
or the Control-M Configuration Manager installed on them. By including a utility command in the
command line of a job processing definition, you can automatically run the utility at a predetermined time
or under a predetermined set of conditions. For more information about different methods for running
utilities, see Methods for running utilities (on page 11).
Utilities can be run from computers on Control-M/EM, Control-M/Server and Control-M/Agent and are
usually run as Administrator. For Control-M/Server and Control-M/Agent, if a user other than an
Administrator wants to run the utility, you need to follow the procedure as described in Running
Control-M/Server utilities as other users (on page 13) and Control-M/Agent utilities (on page 20).
For Control-M/EM utilities you must have the appropriate authorization to either copy from or modify
entities in Control-M/EM database. For more information, see Control-M/EM Authorizations. Some
Control-M/EM database utilities are implemented by using input and argument files written in XML, as
described in XML file rules (on page 35). A valid Control-M/EM database user name and password are
required to run Control-M/EM utilities.
The following sections describes the types of utilities:
 Definition, ordering, and monitoring utilities (on page 41): Creates, modifies, deletes, orders and
monitors job processing definitions.
 Folders and Calendars utilities (on page 265): Creates, and modifies calendar definitions, folders, and
SMART Folders and Sub Folders.
 New day procedure and user dailies (on page 328): Creates and modifies how the job ordering
processing is automated.
 Active Jobs Database utilities (on page 339): Monitors the jobs running in the active database.
 Communication, start up, and troubleshooting (on page 357): Starts up, shuts down, and
troubleshoots various Control-M components.
 Administration and configuration (on page 415): Monitors and manages selected elements of
Control-M.
 Database maintenance (on page 495): Maintains the Control-M/EM database.
 Security (on page 586): Implements various levels of security.
 Statistics and reporting (on page 606): Generates statistics and reports.

10
Control-M Utilities Guide

Chapter

Methods for running utilities

Utilities can be run using the following methods:
 Control-M Configuration Manager: Utilities can be run from the Control-M Configuration Manager
(CCM). For more information about using the CCM, see Introduction to Control-M Configuration
Manager in Administration.
 Defining a job in Control-M: Enables you to define a utility when defining a job in Control-M.
Many of the tasks performed by utilities can also be performed using the Job Properties pane in
Control-M. By including a utility command in the What field of a job processing definition, you can
run the utility at a predetermined time or under a predetermined set of conditions without being
present. For more information, see Creating a job in Using Control-M.
 Command line: Enables you to define a utility using the command line, as described in Command
line utilities (on page 11).

Command line utilities

Almost all Control-M utilities are specified using the command line. If a command invoked from the agent
computer contains embedded spaces, add \" after the first quote at the beginning of the command, and
add \" at the end of the command (but prior to any parameters).
EXAMPLE: "\"d:\program files\bmc software\control-m agent\exe\_sleep\" 200"
Agentless job submission is supported, so when submitting and executing jobs on computers, resident
Control-M/Agent does not need to be installed. These agentless computers are referred to as remote
hosts.
For UNIX, consider the following:
 When invoking Control-M/EM utilities from the command line, specify the em prefix before specifying
the utility:
em cli [-U <emUser> -P <emPass>) | -PF <password file>}] -H <Server Name>
[-T <timeout in seconds>] [-DDMM] [-BY_FORCE]
[ACTION_REASON <reason for taking an audit action> [ACTION_NOTE
<descriptive reason for audit action>] <cmd> <cmd> ...

11
Control-M Utilities Guide

 Some Control-M/Agent utilities require special formatting for transmission to the Server computer.
Commands invoked from UNIX agent computers are embedded in double quotes when sent to the
Server computer. Therefore, use single quotes for command elements that must be within quotation
marks.
EXAMPLE: ctmcreate ...-cmdline "ls -l ’$HOME’"ctmcreate ...-cmdline "ls -l
’$HOME’"
 Values for utility parameters must not contain the apostrophe or single quote character.
 When invoking these utilities from Control-M/Agent, the presence of a special character in the
argument values may cause problems. The following example contains a back-slash before the string
DELETEME:
ctmcreate -TASKTYPE COMMAND -jobname servertest -cmdline "ctmvar -action
set -var '%%#\DELETEME' -varexpr to_be_deleted"
When this command is invoked from Control-M/Agent, the back-slash before DELETEME may be
"eaten" by the shell. To avoid this problem, add a back-slash before the special character that causes
the problem (in this case, the original back-slash). When invoking the ctmcreate utility or ctmdefine
utility from Control-M/Agent with a date_ref of $$$$, put a back-slash before each $ as shown here:
ctmcreate -TASKTYPE COMMAND -cmdline ls -incond a '\$\$\$\$' AND ...

Input file (-input_file parameter)

An input file enables you to do the following:
 Prepare and save files of utility parameters that can be reused
 Specify utility input longer than the number of characters allowed in the command line (10,000)
To specify parameters whose characters exceed 10,000 characters, or to save commands that you use
often, specify the command in an input file and reference this file when you run the command for the
utility using the -input_file parameter. In this file, each parameter and its values (if any) are on a separate
line with the same syntax they would have on the command line.
EXAMPLE: assume that you have to specify the ctmcreate utility. In this case the parameters with their
values exceed the 10,000 character limit. You can specify the parameters and values in an
input file, as follows:
ctmcreate -input_file <file Name>
The <file Name> variable is the name of a file that contains the ctmcreate parameters. For
example:
-tasktype command
-cmdline ls
Utilities that support the input file, see Utility reference table (on page 22).

12
Control-M Utilities Guide

Utilities output
Certain Control-M/Server and Control-M/Agent utilities generate reports that can be directed to a file.
Each such utility is identified by the inclusion of <output> among the utility’s parameters.
 If output parameters are specified, output is routed to the specified file (for example, a file on the
Control-M/Server computer).
ctmordck SYSTEM SYSTEM <User Name>/ctm_server/user_a/udlist.txt
 If output parameters are not specified, the output is routed to the default output device (for example,
the logical name of a disk).
When directing output to a file, do one of the following:
 Specify the full path name of the file (for example,
<User Name>/ctm_server/user1/rprt.txt).
 Specify the relative name of the file to be placed in the <controlmUserDir>/ directory.
 Redirect to the Control-M/Agent computer by specifying a full path name of the file after the
redirection (>) character.

Running Control-M/Server utilities as other users

This procedure describes how to run Control-M/Server utilities as other users.

 To run Control-M/Server utilities as other users:

 Do one of the following:
• Windows: Change the permissions of the following directories:
o temp
o proclog
o prflag
The user requires the permission to write to these directories.
• UNIX: Change the user to other than the Control-M/Server account owner, the following
modifications must be made to the user environment:
o Define variables in the user environment, as described in User environment variable definition
(on page 14).
o Add an executable library to the user’s path, as described in Adding an executable library to
the path of the user (on page 19).
o Assign Read/Write permissions, as described in Assign Read/Write permissions (on page 20).

13
Control-M Utilities Guide

User environment variable definition

The following environment variables must be defined:
 CONTROLM_SERVER
 CONTROLM_USER
 CONTROLM_DATABASE
 CONTROLM_MIRROR_USER
 CONTROLM_MIRROR_DATABASE
 CTM_DATABASE_TYPE
 MIRROR_DB_SERVER
 machine
 LIBPATH, or LD_LIBRARY_PATH, or SHLIB_PATH
The following table lists additional environment variables that are required, according to the type of
database:

For ORACLE For PostgreSQL

ORACLE_BASE DB_TYPE

ORACLE_HOME PGHOME

ORACLE_SID PGDATA

NLS_LANG PGPORT

PGHOST

PGDATABASE

PGUSER

PGSYSCONFDIR

PGSERVICE

LD_LIBRARY_PATH/LIBPATH/
SHLIBPATH

DBU_BIN

MIRROR_DSQUERY

14
Control-M Utilities Guide

To ascertain the values to assign to variables, see Determining the values to assign to variables (on page
15).

Determining the values to assign to variables

This procedure describes how to determine the values to assign to variables in UNIX.

 To determine the values to assign to variables:

1. Specify the following command for each variable from the Control-M user:
echo $<variableName>
EXAMPLE: echo$ORACLE
Use the formats to define the shared library path variables for each database in the user environment,
depending on the server computer type, as described in Shared library variable name (on page 16).
2. Do one of the following:
• Oracle: Set the Shared library environment variable value to:
<user name>/ctm_server/oracle/lib:<user
name>/ctm_server/exe_<opSysID>
The variables in the library path are:
o <opSysID> is the identifier for the type of operating system
o <user name> is the user account home name
• PostgreSQL: Set the Shared library environment variable value to:
<user name>/ctm_server/exe_<opSysID>:~<user name>/pgsql/lib
The variables in the library path are:
o <opSysID> is the identifier for the type of operating system
o <user name> is the user account home name
For the shared library path variables, see Shared library path variables (on page 16).

15
Control-M Utilities Guide

Shared library variable name

Use the formats in the following table to define the shared library path variables for each database in the
user environment, depending on the server computer type:

Computer Shared library environment variable name

AIX LIBPATH

HP-UX SHLIB_PATH

Solaris LD_LIBRARY_PATH

Linux x86_64 LD_LIBRARY_PATH

Shared library path variables

The following table describes the shared library path variables for Oracle, and PostgreSQL:

Variable Description

<Control-M/ServerPath> The default full path name of the Windows home directory
under which Control-M/Server is installed.

<user name> The default full path name of the UNIX user account home
directory under which Control-M/Server is installed.

<opSysID> Identifier for the type of operating system on the server

computer (AIX, HP-UX-11, HP-UX-ia64, Solaris, Linux).

Setting environmental variables in UNIX

This procedure describes how to set environment variables in UNIX.

 To set environmental variables in UNIX:

 Do one of the following:
• If you use csh or tcsh, use the following syntax:
setenv <envVar> <value>
EXAMPLE: setenv DISPLAY myhost:0.0
• If you use sh or ksh, use the following syntax:
<envVar>=<value>
export <envVar>

16
Control-M Utilities Guide

For examples, see Example: Environment variables in UNIX using csh or tsch (on page 17) and Example:
Environmental variables in UNIX using other shells (on page 18).

Example: Environment variables in UNIX using csh or tsch

EXAMPLE Oracle:
setenv CONTROLM_SERVER /home/ora_ctm/ctm_server
setenv ORACLE_HOME /home/ora_ctm/ctm_server/oracle
setenv ORACLE_SID ctrlm
setenv ORACLE_BASE /home/ora_ctm/ctm_server/oracle
setenv NLS_LANG AMERICAN_AMERICA.WE8ISO8859P1
setenv CONTROLM_USER ctrlm
setenv CONTROLM_DATABASE ctrlm
setenv MIRROR_DB_SERVER ctrlm_mirror
setenv CTM_DATABASE_TYPE ORACLE
setenv CONTROLM_MIRROR_USER mirror_ctm
setenv CONTROLM_MIRROR_DATABASE mirror_ctm
setenv machine ${CONTROLM_SERVER}/scripts/sharch
setenv LD_LIBRARY_PATH /home/ora_ctm/ctm_server/exe_Linux-x86_64:
/home/ora_ctm/ctm_server/oracle/lib
EXAMPLE PostgreSQL:
setenv CONTROLM_SERVER /home1/ctm900pg/ctm_server
setenv CTM_DATABASE_TYPE PGSQL
setenv CONTROLM_DATABASE ctrlm900
setenv MIRROR_DSQUERY mirror
setenv CONTROLM_MIRROR_USER mirror2
setenv CONTROLM_MIRROR_DATABASE mirror2
setenv PRIMARY_DB_SERVER CTRLM
setenv MIRROR_DB_SERVER mirror
setenv BU_BIN /home1/ctm900pg/ctm_server/exe_Solaris
setenv PGPORT 5432
setenv PGDATABASE ctrlm900
setenv PGUSER ctmuser
setenv PGHOME /home1/ctm900pg/pgsql
setenv PGDATA /home1/ctm900pg/pgsql/data
setenv CONTROLM_USER ctmuser

17
Control-M Utilities Guide

setenv machine Solaris

setenv PG_HOST ctrlm900
setenv PG_SERVICE db
setenv LD_LIBRARY_PATH
/home1/ctm900pg/ctm_server/exe_Solaris:/home1/ctm900pg/pgsql/lib
setenv
:/home1/ctm900pg/pgsql/lib32:/home1/ctm900pg/ctm_server/exe_Solaris:/home1
/ctm900pg/pgsql/lib:/home1/ctm900pg/pgsql/lib32:/home1/ctm900pg/ctm_agent/
ctm/exe:/home1/ctm900pg/ctm_agent/ctm/exe
setenv DB_TYPE SERVER
setenv PGSYSCONFDIR /home1/ctm900pg/pgsql/etc

Example: Environmental variables in UNIX using other shells

Oracle example
CONTROLM_SERVER=/home/controlm/ctm_server; export CONTROLM_SERVER
CONTROLM_USER=ctrlm; export CONTROLM_USER
CONTROLM_DATABASE=ctrlm; export CONTROLM_DATABASE
LIBPATH=/home/controlm/ctm_server/exe_HP-UX-ia64:
/home/controlm/oracle/lib; export LIBPATH
PostgreSQL example
CONTROLM_SERVER=/home1/ctm900pg/ctm_server
CTM_DATABASE_TYPE=PGSQL
CONTROLM_DATABASE=ctrlm900
MIRROR_DSQUERY=mirror
CONTROLM_MIRROR_USER=mirror2
CONTROLM_MIRROR_DATABASE=mirror2
PRIMARY_DB_SERVER=CTRLM
MIRROR_DB_SERVER=mirror
DBU_BIN=/home1/ctm900pg/ctm_server/exe_Solaris
PGPORT=5432
PGDATABASE=ctrlm900
PGUSER=ctmuser
PGHOME=/home1/ctm900pg/pgsql
PGDATA=/home1/ctm900pg/pgsql/data
CONTROLM_USER=ctmuser

18
Control-M Utilities Guide

machine=Solaris
PG_HOST=ctrlm900
PG_SERVICE=db
LD_LIBRARY_PATH=/home1/ctm900pg/ctm_server/exe_Solaris:/home1/ctm900pg/pgs
ql/lib
:/home1/ctm900pg/pgsql/lib32:/home1/ctm900pg/ctm_server/exe_Solaris:/home1
/ctm900pg/pgsql/lib:/home1/ctm900pg/pgsql/lib32:/home1/ctm900pg/ctm_agent/
ctm/exe:/home1/ctm900pg/ctm_agent/ctm/exe
DB_TYPE=SERVER
PGSYSCONFDIR=/home1/ctm900pg/pgsql/etc

Adding an executable library to the path of the user

The executable directory of Control-M Server must be added to the path of the user. This path must
include:
<user name>/ctm_server/scripts
 To add an executable library to the path of the user:
 Do one of the following:
• csh or tcsh: Use the following command to modify the path when using csh or tcsh:
o Oracle
set path=($path ${ORACLE_HOME}/bin
~<controlm_owner>/ctm_server/exe_<OS_ID>)
EXAMPLE: set path=($path
${ORACLE_HOME}/bin~<controlm_owner>/ctm_server/exe_Solaris)
• Other shells: Use the following command to modify the path when using other shells (for
example, sh, ksh):
PATH="$PATH: <user name>/ctm_server/exe_<OS_ID>"
EXAMPLE: PATH="$PATH: <user name>/ctm_server/exe_HP-UX-ia64"

19
Control-M Utilities Guide

Assign Read/Write permissions

The user must have the following read/write permissions:

Permission type Directory

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

Read and Write permission for all files in directory <controlm_owner>/ctm_server/prflag

If mirroring is enabled, Read permission for file <controlm-directory>/.controlm_mirror

(PGSQL only) <controlm-directory>/pgsql/etc/pg_service.conf

Read and write permissions for all files

You must provide security access to these files as follows:

 Give group controlm read permission for the files.
 All users who require access to Control-M utilities should belong to the same group as the
Control-M/Server account as their primary group.

Control-M/Agent utilities
Agent utilities that run on a Windows computer by a user other than the administrator may not have
access to certain data or functions. Agent utilities that run on a UNIX computer can be run by users other
than the agent account owner, after the user has loaded the agent account environment. For more
information, see Running Control-M/Agent utilities as other users (on page 21).
All Control-M/Agent utilities support the -agent <agent name> parameter. The variable <agent name>
represents the name of the Control-M/Agent specified during the installation procedure.
Where multiple Control-M/Agents reside on a computer, the -agent parameter determines which
Control-M/Agent will manage the utility. If the ctmagcfg or ag_diag_comm utilities are run without
specifying the -agent parameter, the user is prompted to select the Control-M/Agent. For all other utilities,
if the -agent parameter is not specified, the default Control-M/Agent is used.
EXAMPLE: Assume a computer has two Agents, Default and Saturn. To add a user to Default, use the
following command:
ctmpwd -action add -user user2 -password 123456 -agent Default
-or-
ctmpwd -action add -user user2 -password 123456
EXAMPLE: To add a user to Saturn, use the following command:
ctmpwd -action add -user saturn_user2 -password 123456 -agent Saturn

20
Control-M Utilities Guide

Running Control-M/Agent utilities as other users

This procedure describes how to run Control-M/Agent utilities as other users.

 To run the Control-M/Agent utilities as other users:

 Do one of the following:
• Windows: Invoke Agent utilities from Control-M/Agent.
NOTE: Not all the features and data are available if running other than Administrator.
• UNIX: Add one of the following environment variables:
o Add to .cshrc
set path = ( ${path} <agent Home>/ctm/scripts <agent Home>/ctm/exe )
setenv CONTROLM "<agent Home>/ctm"
if ( ${?LD_LIBRARY_PATH} ) then
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:<agent Home>/ctm/exe
else
setenv LD_LIBRARY_PATH "<agent Home>/ctm/exe"
endif
o Add to .profile
CONTROLM=<agent Home>/ctm
export CONTROLM
PATH=$PATH:<agent Home>/ctm/exe:<agent Home>/ctm/scripts
export PATH
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<agent Home>/ctm/exe
export LD_LIBRARY_PATH
<agent Home> stands for the Control-M/Agent account home directory.
NOTE: Use this procedure for agent utilities other than agent configuration utilities. BMC recommends
that only the Control-M/Agent user be enabled to change the agent configuration.

21
 Control-M Utilities Guide

Utility reference table

Use the following table as a handy reference as to what can be specified with the utility you are working
with. You can determine, for example, if variables can be specified in the utility or if the utility supports
the submission of parameter information in an input file.
Utility

Requires Control-M active

SQL Access

can run utility

Only Administrator

Run as a batch job

Supports Variables

Creates reports

Supports input file

Run interactively

computer
Run from a remote host
Run from agent computer
_exit Yes

_sleep Yes

ag_diag_ Yes
comm

ag_ping Yes

ctmagcfg Yes

ctmunixcf Yes
g

ctmwincf Yes
g

set_agent Yes
_mode

ctm_agst Yes Yes

at

ctm_back Yes Yes Yes

up_bcp

ctm_diag Yes Yes Yes Yes

_comm

ctm_men Yes Yes Yes No Yes Yes

u

22
 Control-M Utilities Guide
Utility

Requires Control-M active

SQL Access

can run utility

Only Administrator

Run as a batch job

Supports Variables

Creates reports

Supports input file

Run interactively

computer
Run from a remote host
Run from agent computer
ctm_resto Yes Yes Yes
re_bcp

ctmagcln Yes Yes Yes Yes

ctmcalc_d Yes Yes

ate

ctmcontb Yes Yes Yes Yes Yes Yes

ctmcreate Yes Yes Yes Yes Yes Yes

ctmdefine Yes Yes Yes Yes

ctmdeffol Yes Yes Yes Yes Yes

der

ctmdefsu Yes Yes Yes Yes Yes

bfolder

ctmdisksp Yes
ace

ctmexdef Yes Yes

ctmfw Yes Yes

ctmgetcm Yes Yes Yes

ctmhostm Yes Yes Yes

ap

ctmipc Yes Yes

ctmldnrs Yes Yes Yes Yes

ctmloads Yes Yes Yes Yes Yes

et

23
 Control-M Utilities Guide
Utility

Requires Control-M active

SQL Access

can run utility

Only Administrator

Run as a batch job

Supports Variables

Creates reports

Supports input file

Run interactively

computer
Run from a remote host
Run from agent computer
ctmkeyge Yes Yes
n

ctmkeyst Yes
ore_
mng

ctmkilljob Yes Yes Yes Yes Yes

ctmhostgr Yes Yes Yes

p

ctmorder Yes Yes Yes Yes Yes

ctmordck Yes Yes

ctmping Yes Yes Yes

ctmpsm Yes Yes

ctmrpln Yes Yes

ctmruninf

ctmshtb Yes Yes Yes

ctmshout Yes Yes Yes Yes

ctmspdia Yes Yes Yes

g

ctmstvar Yes Yes Yes

ctmsuspe Yes Yes Yes

nd

ctmsweep Yes Yes

24
 Control-M Utilities Guide
Utility

Requires Control-M active

SQL Access

can run utility

Only Administrator

Run as a batch job

Supports Variables

Creates reports

Supports input file

Run interactively

computer
Run from a remote host
Run from agent computer
ctmudchk Yes Yes

ctmudlst Yes Yes Yes

ctmudly Yes Yes Yes Yes Yes Yes

ctmvar Yes Yes Yes Yes Yes

ctmwhy Yes Yes

db_check Yes Yes Yes Yes

_space

dbversion Yes Yes

shctm Yes Yes

show_ca Yes Yes

shut_ca Yes Yes

shut_ctm Yes Yes

shutdb Yes

start_ca Yes Yes

start_ctm Yes Yes

startdb Yes

bim_repo Yes Yes Yes Yes

rt

build_db Yes Yes

ccmcli Yes Yes

25
 Control-M Utilities Guide
Utility

Requires Control-M active

SQL Access

can run utility

Only Administrator

Run as a batch job

Supports Variables

Creates reports

Supports input file

Run interactively

computer
Run from a remote host
Run from agent computer
cli Yes Yes

copydefca Yes Yes

l

copydefjo Yes Yes

b

ctl Yes Yes Yes Yes

db_check Yes Yes Yes Yes

defcal Yes Yes

defjob Yes Yes

deffolder Yes Yes

deldefjob Yes Yes

duplicate Yes Yes

defjob

ecactltb Yes Yes Yes Yes Yes Yes

ecaqrtab Yes Yes Yes Yes Yes Yes Yes

em_data_ Yes Yes Yes Yes Yes

collector

em_datab Yes Yes Yes

ase_
menu

em_rebuil Yes Yes Yes Yes

d_
database

26
 Control-M Utilities Guide
Utility

Requires Control-M active

SQL Access

can run utility

Only Administrator

Run as a batch job

Supports Variables

Creates reports

Supports input file

Run interactively

computer
Run from a remote host
Run from agent computer
em_SQL Yes Yes Yes

emcrypto Yes Yes

cli

migrate_ Yes Yes Yes Yes

dc

emreport Yes Yes Yes Yes

cli

erase_au Yes Yes Yes

dit_ (database
data owner)

exportdef Yes Yes

cal

exportdef Yes Yes

job

exportdef Yes Yes

folder

loader Yes Yes Yes Yes

loopdetec Yes Yes Yes

ttool

orbadmin Yes

purge_ru Yes Yes Yes Yes

ninfo

purge_xal Yes Yes Yes Yes

erts

sweep Yes Yes Yes Yes Yes

27
 Run from a remote host
computer
Run from agent computer
Run interactively
Yes

Supports input file

Yes

Yes

Creates reports

28
Supports Variables
Run as a batch job
Yes

Yes
Only Administrator
can run utility

Yes
Control-M Utilities Guide

SQL Access

Yes
Requires Control-M active

updatede
Utility

util
f
Control-M Utilities Guide

Utility workflow between Control-M/Server and

Control-M/Agent
Some of these utilities are executed by Control-M/Server. Their output is sent to the agent computer. The
processing workflow is illustrated below.
Most utilities that create a job in the Control-M/Server Active Jobs database are interactive when invoked
from the server computer, but not interactive when invoked from the agent computer. When invoked
from the agent, they must be invoked with all the required parameters.

NOTE: If the primary Control-M/Server does not respond to a Control-M/Agent request to execute a
utility (other than ag_ping), the request is automatically redirected to the first non-primary Server listed in
the Authorized Control-M/Server Hosts parameter. If the redirection is successful, that agent continues to
work with the replacement server.
Some Control-M/Server utilities can be invoked from Control-M/Agent using the same command line
syntax. When such a utility is invoked by the agent, the agent sends the command line, by way of a
message, to the server for execution.
The Agent-to-Server communication timeout intervals are described in Defining a Control-M/Agent
component. If the agent requests a utility that runs on the server and there is no response within the
timeout interval, the requested action will fail. You can modify this timeout interval by using the
Control-M/Agent System Parameters window in the Control-M Configuration Manager. However,
increasing this timeout interval tends to reduce Control-M/Agent performance.

29
Control-M Utilities Guide

Control-M/EM requests and communication

You can set the Control-M/EM Gateway (GTW) parameters to optimize requests and communication
between Control-M/EM and Control-M/Server.
Parameters in the Defaults.rsc file that affect timeout values are discussed below. For more information,
see Defining a Control-M/EM component.
The following modifications to timeout values can be made:
 You can modify the following parameters in the Defaults.rsc file to set timeout values:
• download_timeout
• upload_timeout
• usreq_timeout (affects user requests like hold, free, kill, delete, and save)
• inforeq_timeout (affects information requests timeout like output, documentation, and log)
• keep_alive_timeout
• sync_timeout
 You can optimize the SSL synchronization timeout by modifying the SSLSyncTime system parameter.
For more information about modifying the Defaults.rsc file, see System configuration.
 Setting a timeout value for a GUI Server affects only requests that the GUI Server invokes as a
CORBA client. Examples of such requests are:
• updating the GUI with Viewpoint information
• sending results of a callback action, such as Upload Folder or Holding an active job
To prevent disconnections from slow clients, set the GSR AddJobsChunkSize system parameter to 100
(the default chunk size is 1000). BMC recommends decreasing the chunk size instead of increasing
the timeout value.

30
Control-M Utilities Guide

Parameter name cross references

This table lists the utility parameter and the name by which the parameter appears in the Job/Folder
Properties pane in Control-M and Control-M Parameters.

Utility parameters Control-M parameter

ADJUST_COND Adjust condition

APPLFORM Application Form

APPLICATION Application

APPLTYPE Application Type

APPLVER Application Version

VARIABLE Variable Assignments

CMDLINE Command Line

CMVER Application Plug-in Version

CONFIRM Confirm Submission

CONTROL Control Resources

CRITICAL Critical

CYCLIC Cyclic

DESCRIPTION Description

DO REMEDY Notify - Remedy

DOVARIABLE Set Variable

DOCLIB Doc Library

DOCMEM Doc Member

DOCOND Add/Remove condition

DOFORCEJOB Order Job

DOREMOTEFORCEJOB Remote Order Job

DOMAIL Notify - Mail

31
Control-M Utilities Guide

Utility parameters Control-M parameter

DOOK Do OK

DORERUN Rerun Job

DOSHOUT Notify

CAL_ANDOR AND/OR

CONFCAL Confirmation Calendar

CONFIRM Confirm Submission

DATE Dates

DATEFROM Start Date

DATEUNTIL End Date

DAYS Days

DAYSCAL Days Calendar

INTERVAL_SEQUENCE Rerun using the following Interval Sequence

SPECIFIC_TIMES Run at

TOLERANCE Tolerance

EMBEDDED_SCRIPT Embedded Scripts/JCL

RBC Rule-Based Calendar

RELATIONSHIP Relationship

RETRO Retroactively order job that its scheduled date has passed

SHIFT If day is not confirmed

WEEKCAL Week days Calendar

WEEKDAYS Days of week

TIMEUNTIL Time

DOSTOPCYCLIC Stop Cyclic Run

32
Control-M Utilities Guide

Utility parameters Control-M parameter

DOOUTPUT Handle Output

SUB_APPLICATION Sub Application

INTERVAL Interval

INCOND In Conditions

INTERVALFROM All intervals are from job's

JOBNAME Job Name

MAXRERUN Maximum reruns

MAXWAIT Keep active for

HOSTGRP Host (/Group)

MEMLIB Member Library

MEMNAME File Name

ODATE Order Date

ON On Statement/Code

OUTCOND Out Conditions

OVERRIDE_PATH Override path

RUN_AS Run as

PRIORITY Priority

QUANTITATIVE Quantitative Resources

SHOUT Notification

OUTPUT Output Handling

FOLDER Folder

TASKTYPE What

TIMEFROM Time from

33
Control-M Utilities Guide

Utility parameters Control-M parameter

TIMEUNTIL Time to

34
2
2
XML file rules
Control-M/EM utilities read input text files that are used to enter information into the Control-M/EM
database. Control-M/EM export utilities export data from the database in text files. Both the input and the
output files are formatted with XML. For example, the defcal input file specifies new Calendar definitions
to enter into the database. Different parts of the input file are defined by tags composed of punctuation
marks. For an example, see XML file example (on page 36).
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 definitions,
Calendar, folder, and SMART Folder parameters, and values. Each Control-M/EM utility is composed of a
combination of at least two of the following parts:
 An invocation command.
 An input file containing either data to enter into the Control-M/EM database or arguments for
selecting specific data from the database.
 An output file containing data specified in the arguments file, if it was used.
 Optional switches for controlling how the utility runs.
For example, the defjob utility has three parts; the invocation command, a file of job processing
definitions that are imported into the Control-M/EM database, and an optional switch. You prepare the file
containing the job processing definitions.
The exportdefjob utility uses an invocation command, a file containing arguments for specifying the job
processing definitions that are exported from the Control-M/EM database, an optional switch, and an
output file containing the exported job processing definitions. You prepare the arguments file. The output
file is created by the exportdefjob utility.
Each utility contains a table of elements (job, calendar, and folder parameters) and attributes (sub
parameters). If the valid value is a string, see the description of the appropriate parameter in Control-M
Parameters for information about valid values and their formats. If working in an I18N environment, a
header must be placed at the top of the arguments file, as described in XML file for I18N environment (on
page 37).
Some of the parameter names changed for Control-M version 8.0.00 and above, terminology from
previous versions is still supported. For a complete list of the parameter names, see Abbreviations and
conventions.

35
Control-M Utilities Guide

XML file example

In this example, the TERMS input file displayed all non-cyclic jobs with job name Job5. The action
performed on the selected jobs is determined by the type of utility that is calling the TERMS file. Using
this TERMS file with deldefjob deletes all job processing definitions in the database for non-cyclic jobs
with job name Job5.
This file contains one TERMS statement. The statement specifies that non-cyclic jobs with Job Name Job5
are to be selected.
<TERMS>
<TERM>
<PARAM NAME="JOBNAME" OP="EQ" VALUE="Job5"/>
<PARAM NAME="CYCLIC" OP="EQ" VALUE="0"/>
</TERM>
</TERMS>
The statement begins with the word TERMS enclosed in angle brackets (<TERMS>). The end of the file is
indicated by the closing TERMS tag. That this is the end of the TERMS statement is indicated by the
presence of the slash (/), so that the closing statement looks like </TERMS>.
Between the <TERMS> tags is a search term for identifying and selecting specific job processing
definitions. It is indicated by the tags <TERM></TERM>. Between the TERM tags are the parameters of
the search, indicated by the <PARAM/> tag. All the attributes of the tag are contained within the single
set of brackets. No closing tag is needed. As a result, the slash (/) is included in the single tag, preceding
the closing angle bracket, <PARAM/>.
As noted, the PARAM tag contains the search terms, NAME, OP, and VALUE.
 NAME is the name of a job processing definition parameter.
 OP is an operator. The most common operators are described in the following table.
 VALUE is the value of the parameter to which a comparison is being made.
NOTE: In this example, NAME="JOBNAME" OP="EQ" VALUE="Job5" searches for job processing
definitions that have the Job Name, Job5.

Operator Description

EQ Equals. Select cases that include the specified value.

NEQ Not equal. Select cases that include any value different from the one specified.

LIKE Similar. Select cases that have an attribute common to the one specified.
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.

36
Control-M Utilities Guide

XML file for I18N environment

When working in an I18N environment, the following header must be placed at the top of the argument
file:
<?xml version=’1.0’ encoding=’UTF-8’?>
EXAMPLE:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE TERMS SYSTEM "terms.dtd">
<TERMS>
<TERM>
<PARAM NAME="JOBNAME" OP="EQ" VALUE="Job5"/>
<PARAM NAME="CYCLIC" OP="EQ" VALUE="0"/>
</TERM>
</TERMS>

XML file validation

The contents of an XML file are determined by a set of criteria that are contained in a document type
definition (dtd) file. The .dtd file is used by Control-M/EM to validate the input file (or arguments file)
when the utility runs. The .dtd file includes the following information:
 Names of all of the elements and attributes that can be entered in an input or arguments file in XML
format.
 Valid values for an element or attribute.
 Whether the valid values for an element or attribute are mandatory or optional.
 Hierarchical relationship between the various elements and attributes in the file.
Formatting and value information for Control-M parameters is described in Control-M Parameters.

37
Control-M Utilities Guide

Each utility input file has its own .dtd file. The arguments files share the same .dtd file. Utility .dtd files
are stored in the Control-M EM <9.0.00>\Default\data\Resource directory (on Windows).

File name Description

copycal.dtd Validates the copydefcal input file.

copyjob.dtd Validates the copydefjob input file.

defcal.dtd Validates the defcal input file.

defjob.dtd Validates the defjob input file.

deffolder.dtd Validates the deffolder input file.

duplicatejob.dtd Validates the duplicatedefjob input file.

terms.dtd Validates exportdefjob, exportdefcal, and exportdeffolder argument files.

update.dtd Validates the updatedef input file.

Creating an XML file

This procedure describes how to create an input file.
 To create a file:
1. Open any text editor or an XML editor.
2. Enter the data for the utility that you are using, the format described in the parameter description
tables, and examples that are provided with the utility.
3. Check the syntax of the file for errors. If errors remain, they are identified when the file is submitted
to the utility. Possible errors include:
• Misplaced or missing tag.
• Misplaced or missing part of a tag (for example, a missing slash /).
• Parameter value that is not specified as a valid value for that parameter (for example, the letter Y
instead of a 1.
NOTE: Control-M/EM database 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. However, BMC
recommends that you use .xml
For reserved character codes and wildcard rules, see Reserved character codes (on page 39) and
Wildcards (on page 39).

38
Control-M Utilities Guide

Reserved character codes

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 are replaced and are listed in the following
table:

Character Replacement code

" (double-quote) &quot;

’ (single-quote, apostrophe) &apos;

< (left-angle bracket) &lt;

> (right-angle bracket) &gt;

& (ampersand) &amp;

NOTE: The ampersand character can be used in the
character replacement codes.

EXAMPLE: Using reserved character codes in an XML file.

Incorrect:
INCOND NAME="if5<6’run’" ODATE="ODAT" AND_OR="AND" OP="("/
Correct:
INCOND NAME="if5&lt;6&apos;run&apos;" ODATE="ODAT" AND_OR="AND"
OP="("/

Wildcards
Multiple jobs can be selected and copied using the * (asterisk) wildcard character to represent multiple
values. The asterisk is used to represent zero or more alphanumeric characters. An asterisk can also be
used to replace characters in the middle of an expression.
NOTE: Only one asterisk can be used in an expression.
EXAMPLE 1:
The job name of a specific job definition is AAABBB. If you include the any of the following
arguments in an updatedef utility argument file, you select job AAABBB:
<JOB_NAME FROM="AAABBB"/>
<JOB_NAME FROM="*BBB"/>
<JOB_NAME FROM="AAA*"/>

39
Control-M Utilities Guide

EXAMPLE 2:
There are three job processing definitions. Their Job Names are:
AAABBB, AAACCC, and BBBCCC
The following argument selects jobs AAACCC and BBBCCC, and selects any other jobs with a
Job Name that ends with the letters CCC.
<JOB_NAME FROM="*CCC"/>
The asterisk has a special function when used in find and replace operations in selected utilities. The
following utilities use find and replace operations:
 copydefcal
 copydefjob
 duplicatedefjob
 updatedef
In the FROM (find) statement of an argument, an asterisk replaces a text string (as shown in the example
above). The asterisk in the TO statement of the argument represents the same string as the asterisk in
the FROM statement of the argument. The placement of the asterisk can be changed.
EXAMPLE 1:
There are three job processing definitions:
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:
AAABBB, DDDCCC, BBBCCC
<JOB_NAME FROM="*CCC" TO="DDD*"/>
• Job DDDCCC becomes Job DDDDDD
• Job BBBCCC becomes Job DDDBBB
• Job AAABBB is not modified.

40
3
3
Definition, ordering, and monitoring utilities
The definition, ordering, and monitoring utilities are used to create and define job processing definitions:
Some of the parameter names changed for Control-M version 8.0.00 and above, terminology from
previous versions is still supported. For a complete list of the parameter names, see Abbreviations and
conventions.
The following table describes the utilities for various utilities for job processing definitions.

Utility Type Description

Control-M/EM utilities

emdef utility for jobs (on page Enables you to make various modifications to job
42) definitions, rules and site standards in the Control-M/EM
database.
To use the emdef utility for folders and calendars, see
emdef utility for folders and calendars (on page 266).
NOTE: To order and force jobs using the cli utility, see
cli utility (on page 302).

emdef utility for services (on page Enables you to make various modifications to BIM
174) service definitions in the Control-M/EM database.

emwacli for promotion (on page Enables you to run Promotion as a batch process.
182)

41
Control-M Utilities Guide

Utility Type Description

Control-M/Server utilities

ctmcreate (on page 189) Creates a job, which is added directly into the Active
Jobs database.

ctmdefine (on page 202) Adds a job processing definition to a folder, a SMART
folder, and a subfolder in the Control-M/Server
database.

ctmexdef (on page 215) Exports jobs from the Control-M/Server database to an
ASCII file for use with ctmcreate or ctmdefine.

ctmfw File Watcher utility (on Detects completion of file transfer activity.
page 217)

ctmimptb (on page 228) Imports SMART Folders that were exported with the
exportdeffolder utility.

ctmkilljob (on page 231) Terminates a Control-M job and its associated
processes.

ctmorder (on page 232) Orders jobs from a SMART Folder in the
Control-M/Server database.

ctmpsm (on page 240) Interactively performs functions on jobs or conditions

directly in the Active database.

ctmsweep (on page 258) Deletes non-active jobs from the Control-M/Server
database.

ctmwhy (on page 262) Reports why a job waiting in the Active Jobs database is
not submitted.

Control-M/Agent utilities

_exit (on page 264) Sets the completion status for a job that runs from a
.bat file.

_sleep (on page 264) Sets the sleep time for Control-M/Server processes.

emdef utility for jobs

The emdef is a command line utility used to make various modifications to job definitions in the
Control-M/EM database.

42
Control-M Utilities Guide

NOTE: For information about using the emdef utility for folders and calendars, see emdef utility for folders
and calendars (on page 266).
The emdef utility includes the following utilities:

Utility Type Description

defjob (on page 46) Imports job processing definitions directly into Control-M/EM
database.

copydefjob (on page 66) Copies jobs from one folder to another in the Control-M/EM
database that is similar to a specified existing definition.

deldefjob (on page 85) Deletes specified job processing definitions from a SMART
Folder in the Control-M/EM database.

duplicatedefjob (on page 89) Copies an existing job definition in the same data center and
SMART Folder.

exportdefjob (on page 112) Exports job processing definitions from a folder in the
Control-M/EM database to an output file.

loopdetecttool (on page 117) Checks job processing definitions to determine if conditions
are defined in a way that would cause loops.

updatedef (on page 124) Updates specified parameter values in the following
definitions in the Control-M/EM database:
 Job processing definitions
 Folder definitions
 SMART Folder definitions
 Sub Folder definitions

exportsitestandards (on page Exports Site Standards into Control-M/EM database.

157)

importsitestandards (on page Imports Site Standards into Control-M/EM database

160)

exportpromotionrule (on Exports Promotion Rules into Control-M/EM database.

page 162)

Importpromotionrule (on Imports Promotion Rules into Control-M/EM database. For

page 172) more information about the exportpromotionrule and
importpromotion rules see Export/import Promotion rules
(on page 162).

43
Control-M Utilities Guide

emdef general parameters

The following table describes the parameters common to emdef utilities.

Parameter Description

<user> Defines the Control-M/EM user name.

<password> Defines the Control-M/EM user password.

<password file Includes an unencrypted user name and password on separate lines in
name> a flat file in the following format:
user=<userName>
password=<password>

<GUI Server Defines the Control-M/EM GUI server logical name, host name, or IP
Name> address.
NOTE: If multiple GUI servers exist, set this parameter to the logical
name of the relevant GUI server.

<XML file Defines the path and name of the XML file containing the defjob
name> specifications. For instructions about creating this file, see XML file rules
(on page 35).

<out file name> Defines the path and name of the file containing the exported job
specifications.

44
Control-M Utilities Guide

emdef switches
The following table describes switches for the emdef utilities:

Switch Description emdef utility

? Displays utility's description and available options. All (except loopdetecttool)

/a The /a switch directs the utility to automatically reset the Created By The following utilities are
parameter to the current Control-M/EM user when these two values do not supported:
match. If not specified, the utility skips (that is, does not process) job
definitions whose Author does not match the currently logged in user.
 defjob
NOTE: The /a switch has no effect on Administrator users and is relevant  copydefjob
only when the AuthorSecurity system parameter is set to 2 or 3.  duplicatedefjob
 exportdefjob
 updatedef
 defservice
 exportdefservice
 defcal
 deffolder
 exportdefcal
 exportdeffolder

/v Used to receive verbose messages. The following utilities are

supported:
 defjob
 copydefjob
 deldefjob
 duplicatedefjob
 exportdefjob
 updatedef
 defservice
 exportdefservice
 deffolder
 exportdeffolder

/c Operates on a chunk of jobs at any one time to reduce the process' defjob
memory

45
Control-M Utilities Guide

Switch Description emdef utility

-cs Set the number of jobs in a chunk. defjob

Default: 100

/t Operate on a single folder at a time, to reduce process memory. The following utilities are
supported:
 defjob
 exportdefjob
 deffolder
 exportdeffolder

/o Overwrites an existing folder definition in Control-M/EM database or deffolder

creates a new folder if it does not exist.

/f Forces folder definition with a site standard that does not exist, which sets deffolder
the site standard to none.

defjob
The defjob utility imports job processing definitions directly into Control-M/EM database. To import the
job using the defjob utility, see Importing jobs into existing folders using the defjob utility (on page 47).
defjob reads job processing definitions from a plain text input file written in XML format, see defjob XML
file rules (on page 47).
Each job processing definition in the Control-M/EM database has a JOBISN field that contains a job ID
number. JOBISN is the JOB_ID field in the def_job folder. Many jobs can have the same JOBISN number.
However, the JOBISN number is unique in each Folder. Use Control-M Control-M Monitoring Domain to
determine the job ID. Select the job in the Monitoring domain to see jobs IDs.
If a job that is being imported contains a JOBISN number that already exists in the Control-M/EM
database, defjob overwrites the existing job processing definition with the new job processing definition.
If a JOBISN value is not specified, defjob imports the job processing definition into the database as a new
job.

46
Control-M Utilities Guide

Importing jobs into existing folders using the defjob utility

This procedure describes how to import jobs into existing folders into Control-M/EM database by using the
defjob utility.
 To import jobs using the defjob utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type one of the following commands:
• emdef defjob [-USERNAME <user> [-PASSWORD <password>] | -PASSWORD_FILE
<password file>] -HOST <GUI Server Name> -SRC_FILE <XML file name> [/a]
• emdef defjob [-u <user> [-p <password>] | -pf <password file>] -s <GUI
Server Name> -src <XML file name> [/a]
NOTE: For Windows, you do not need to use the emdef prefix.
For more information about defjob parameters and switches, see emdef general parameters (on page
44) and emdef switches (on page 45).
For information about the XML file name, see defjob XML file rules (on page 47).
If there are any errors in the file, a message is displayed specifying the lines with the errors.

defjob XML file rules

The job definitions that you create for use with the defjob utility are written in XML format, saved in a
text file, and when invoked, its contents are passed to the Control-M/EM databases database. For
information about creating XML files, see XML file rules (on page 35).
The following rules apply to the defjob utility XML file:
 More than one job can be specified in a defjob file.
 The file is case-sensitive.
 Although many parameters are optional, certain parameters are required depending on the option
specified for the TASKTYPE parameter. For more information, see What in Control-M Parameters.
 All parameter values (such as strings or digits) must be enclosed in quotation marks (for example,
JOBNAME="Job1").
 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 39).
 Condition dates must be specified in mmdd format. Time must be specified in hhmm format.
 A parameter requiring more than one entry can be repeated as many times as necessary. For
example, if a job must wait for several prerequisite conditions, specify a separate INCOND parameter
for each prerequisite condition.

47
Control-M Utilities Guide

 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.
 XML is comprised of elements and attributes. Each element can contain attributes and sub-elements.
For more information on the XML file parameters for the defjob utility, see defjob XML file parameters
(on page 49), and defjob XML file example (on page 65).
The following values can have more than one line of text:
 Do Mail Message
 Do Remedy Summary
 Do Remedy Description
 Instream JCL (for z/OS)
The multi line value is formatted in the following manner:
 A four digit number that indicates the length of the line
 Text following the number
EXAMPLE: "0011hello world0012just kidding"--
If the UseMultiLineNewFormatDisplay system parameter is set to 1, then all the values appear with
&#13;&#10; as line delimiters. If set to 0, or not set at all, then the following values
appear as described in the above format.

48
Control-M Utilities Guide

defjob XML file parameters

The following table lists the defjob file parameters:

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file.

DEFJOB Indicates the XML root element. Job processing definitions are placed between the
opening and closing DEFJOB tags. One or more jobs can be specified. Each
individual job is enclosed by JOB /JOB tags.

JOB Indicates the opening and closing tags of a single job definition. Parameters of the
job are listed between the tags.

DATACENTER Name of the Control-M installation to which the job belongs. String. Mandatory.

PARENT_FOLDER Name of the parent folder to which the job’s folder belongs. String. Mandatory.

FOLDER_NAME Name of the SMART Folder to which the job belongs. String. Mandatory.

FOLDER_DSN (z/OS only) Name of the library that contains the SMART Folder. String. Mandatory.

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

NOTE: On a Windows computer, JOBNAME must comply with Microsoft naming
conventions (for example, it cannot contain / and \ characters).

FILE_NAME Name of the file that contains the job script. String. Optional.

SUB_APPLICATION Indicates the name of the Sub Application where the job belongs logically. It is a
sub-category of the Application parameter. For example, the Application is Finances,
and the Sub Application is Payroll. String. Mandatory.

APPLICATION Provides a logical name for sorting groups of jobs. This parameter is used to supply
a common descriptive name to a set of related job groups. The jobs do not
necessarily have to run at the same time. String. Mandatory.

49
Control-M Utilities Guide

Parameter Description

TASKTYPE Type of job (task) to be performed by Control-M. Mandatory.

Valid values:
 Job
 Detached
 Command
 Dummy
 External
(z/OS only) Valid values:
 Job
 Started_Task

CREATED_BY Control-M/EM user who defined the job. String. Mandatory.

NOTE: This argument is used by the Control-M/Server security mechanism and,
under certain circumstances, cannot be modified. For more information, see the
Security chapter and the description of the AuthorSecurity system parameter in GUI
Server parameters.

FILE_PATH Name of the library/directory in which the job script resides. String. Optional.

CMDLINE Command string supplied when the job Task Type is Command. String. Optional.

HOSTID Host name of an agent computer or name of a host group to which the job is
submitted. String. Optional.

RUN_AS Identifies the user name with the authorization to execute the job. This parameter
is used by the Control-M security mechanism. String. Mandatory.

MAXRERUN Specifies the maximum number of reruns that can be performed for the job.
Optional.
Valid values: 0-99. Default: 0

TIMEFROM Indicates the earliest time for submitting the job. Format is (hhmm). Optional.

TIMETO Indicates the latest time for submitting the job. Format is (hhmm) or (>). Optional.

DUE_OUT Time that the job is expected to finish. String. Optional.

PRIORITY Indicates Control-M job priority. 2 alphanumeric characters (AA-99). Optional.

50
Control-M Utilities Guide

Parameter Description

CRITICAL Indicates that the job is a critical-path job in Control-M. Optional.

Valid values:
 0 (No. Default)
 1 (Yes)

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

CYCLIC_TYPE Determines the type of cyclic job:

 Interval
 IntervalSequence
 SpecificTimes
NOTE: Relevant for Control-M version 6.4.01 or later.

CYCLIC_TOLERANCE Maximum delay in minutes permitted for a late submission when selecting a specific
time (for example 5 minutes).
NOTE: Relevant for Control-M version 6.4.01 or later.

CYCLIC_INTERVAL_ A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up to

SEQUENCE 4000 characters including commas.
NOTE: Relevant for Control-M version 6.4.01 or later.

CYCLIC_TIMES_ A list of times, separated by commas (for example 0800,1330,2300), which

SEQUENCE supports time synonym (for example 2730).
NOTE: Relevant for Control-M version 6.4.01 or later.

INSTREAM_JCL Defines a script exactly as it would be specified in a terminal for the specific
computer and is part of the job definition.
(embedded script)
For Control-M for Distributed System for 6.4.01 or later an embedded script is
marked with a &#10 indicator.
For Control-M for z/OS version 6.2.00 or later, the XML file is formatted with
multi\-ple lines which contain four digit numbers which state the length of the line,
fol\-lowed by the line’s text.

51
Control-M Utilities Guide

Parameter Description

USE_INSTREAM_JCL Indicates whether the job should use the INSTREAM_JCL.

Valid values: Y or N
NOTE: Relevant for jobs running in Control-M for z/OS version 6.2.00 or later and
Control-M for Distributed System for 6.4.01 or later.

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

AUTOARCH Determines whether SYSDATA is to be archived. Optional.

Valid values:
 0 (No. Default)
 1 (Yes)

INTERVAL Specifies the length of time (in minutes) to wait between reruns of a job or between
cyclic runs of a job. Integer. Optional.
Default: 0.

OVERRIDE_PATH Name of an alternate job script library/directory. String. Optional.

MAXWAIT Number of extra days (beyond the original scheduling date) that the job is allowed
to remain in the Active Jobs database awaiting execution. Integer. Optional.

DESCRIPTION Free text description of the job. String. Optional.

DOCMEM Name of the file containing job documentation. String. Optional.

DOCLIB Name of a library or directory containing the job documentation file. String.
Optional.

DAYS Days of the month on which to order the job. String. Optional.

DAYS_AND_OR Indicates the relationship between specified Days values and Weekdays values.
Optional.
Valid values:
 AND
 OR

WEEKDAYS Days of the week on which to order the job. String. Optional.

52
Control-M Utilities Guide

Parameter Description

DATE Specific dates on which to order the job. String. mmdd format. Optional.
For example, January 10 is written as: DATE="0110"

DAYSCAL Name of a user-defined calendar used to specify a set of days. String. Optional.

WEEKSCAL Name of a calendar to be used to validate specified weekdays on which to order the
job. String. Optional.

CONFCAL Specifies a calendar that is used to validate all specified days and dates on which to
schedule the job. String. Optional.

RETRO Indicates whether the job is scheduled for possible execution after its original
scheduling date (odate) has passed. Optional.
Valid values:
 0 (No. Default)
 1 (Yes)

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

SHIFTNUM Number of days to shift the scheduling date of the job. Optional. Valid values: -62
to 62.

MAXDAYS Maximum number of days to retain the SYSDATA archive dataset for jobs that
ended NOTOK. Subparameter of AUTOARCH. Optional. Valid values: 00 – 98, or 99
to indicate that SYSDATA is retained for an unlimited number of days.

MAXRUNS Maximum number of job runs to retain the SYSDATA archive dataset for jobs that
ended NOTOK. Subparameter of AUTOARCH. Optional. Valid values: 000 – 998, or
999 to retain SYSDATA data for all runs.

RERUNMEM Name of the JCL member to use when the job is automatically rerun. String. 1 - 8
characters. Optional.

RETEN_DAYS (z/OS only) Number of days to retain the job in the History Jobs file. String.
Optional.

RETEN_GEN (z/OS only) Maximum number of generations of a job to keep in the History Jobs
file String. Optional.

53
Control-M Utilities Guide

Parameter Description

PREV_DAY Flag to indicate whether job scheduling is shifted to a previous working day in the
CONFCAL calendar. Optional.
Valid values:
 Y
 N

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

RULE_BASED_CALEND Relationship (AND|OR) between the specified Rule-Based Calendars and the job’s
AR_RELATIONSHIP own basic scheduling criteria. Optional.
Valid values:
 AND
 OR

TAG_RELATIONSHIP Relationship (AND|OR) between the specified Schedule Tag criteria and the job’s
own basic scheduling criteria. This parameter is relevant only for jobs in a SMART
Folder. Optional. This parameter is for backward compatibility.
Valid values:
 AND
 OR

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

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

MINIMUM Minimum number of free partitioned dataset tracks required by the library specified
for the PDSNAME parameter. Integer. Optional.

CATEGORY Name of a Control-D report decollating mission category that must be scheduled
under Control-D when the job is scheduled under Control-M. String. Optional.

54
Control-M Utilities Guide

Parameter Description

PREVENTNCT2 (z/OS only) Prevents dataset cleanup before the original job run Optional.
Valid values:
 Blank – Does not perform data set cleanup before the original job run. Default.
 N – Does not prevent cleanup.
 Y - Prevents data set cleanup. This value is not valid for started tasks.
 L (List) – Do not perform data set cleanup before the original job run. Do
generate messages that would be required for CDG adjustment
during restart.
 F (Flush) – Halt processing of the job if any data set cleanup error is detected
(even if z/OS would not have stopped processing the job).

JAN, FEB, MAR, APR, Months when the job can run.
MAY, JUN, JUL, AUG, Valid values:
SEP, OCT, NOV, DEC
 0 (Not run. Default)
 1 (Run)

OPTION Job output (OUTPUT) handling options. Optional.

Valid values:
 Release
 Delete
 Copy
 Move
 File
 NewDest
 ChangeClass

PAR Certain OPTION values (such as Release, NewDest) require additional information.
String. Optional.

FROM Limits the OUTPUT handling operation to only OUTPUTs from the specified class.
String. Optional.

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

55
Control-M Utilities Guide

Parameter Description

CREATION_USER Name of the user who created the job. String. Optional.

CREATION_DATE Date on which the job was created. String. Optional.

CREATION_TIME Time at which the job was created. String. Optional.

CHANGE_USERID Name of the user who last modified the job. String. Optional.

CHANGE_DATE Date on which the job was last modified. String. Optional.

CHANGE_TIME Time at which the job was last modified. String. Optional.

JOB_RELEASE For internal use. Do not include this parameter in your defjob input file.

JOB_VERSION For internal use. Do not include this parameter in your deffolder input file.

APPL_TYPE Indicates the type of external application (for example, SAP or Oracle Applications)
on which the external application job runs. String. Up to 10 characters. Mandatory
for external application jobs.

APPL_VER Version of the external application (for example, SAP or Oracle) on which the
external application job runs. String. Up to 10 characters. Mandatory for external
application jobs.

APPL_FORM Predefined set of external application parameters that are displayed in the Job
Properties team. String. Up to 30 characters. Mandatory for external application
jobs.

CM_VER Indicates the version of external Application Add-on (for example, SAP or Oracle
Applications) that is installed in the Control-M installation. String. Up to 10
characters. Mandatory for external application jobs.

MULTY_AGENT When selected, broadcasts job submission details to all agents in a specified Host
Group. Optional.
Valid values:
 Y – run as multi-agent job
 N – not run as multi-agent job. Default.

ACTIVE_FROM (z/OS only) Indicates the start of a period of time during which the job or SMART
Folder can be ordered. Optional.
Date Format: YYYYMMDD

ACTIVE_TILL (z/OS only) Indicates the end of the time interval during which the job or SMART
Folder can be ordered. Optional. Date Format: YYYYMMDD

56
Control-M Utilities Guide

Parameter Description

TIMEZONE Indicates the global time zone used to calculate the interval for time-related
conditions.
String. Optional.

SCHEDULING_ (z/OS only) Indicates the JES2 workload management scheduling environment
ENVIRONMENT associated with the job. String. Optional.

SYSTEM_AFFINITY Identity of the system in which the job must be initiated and executed (in JES2).
Identity of the processor on which the job must execute (in JES3). String. Optional.

REQUEST_NJE_HOST Specifies the host in the JES network on which the job is to execute. String.
Optional.

JOBISN For internal use. String. Optional.

RULE_BASED_CALEND Wrapper for the Rule-Based Calendars listed with the RULE_BASED_
AR_NAMES CALENDAR_NAME parameter. Optional.
RULE_BASED_CALENDAR_NAMES RULE_BASED_CALENDAR_NAME="rbc1"
RULE_BASED_CALENDAR_NAME="rbc2"

RULE_BASED_CALE Name of the Rule-Based Calendars that apply to the SMART

NDAR_NAME Folder. Mandatory.

TAG_NAMES Wrapper for the tags listed with the TAG_NAME parameter. Optional.
TAG_NAMES TAG_NAME="tag1" TAG_NAME="tag2"

TAG_NAME Name of the schedule tags that apply to the SMART Folder.
Mandatory. This parameter is for backward compatibility.

OUTCOND Out condition. Optional.

OUTCOND NAME="Job1" ODATE="ODAT" SIGN="ADD"

NAME Name of the Out condition. String. Mandatory.

1 - 255 characters, case-sensitive.

ODATE Order date of the Out condition. String. Mandatory.

Valid values:
Default: ODAT

SIGN Indicates whether to add or delete the condition. Mandatory.

Valid values:
 ADD (default)
 DEL

57
Control-M Utilities Guide

Parameter Description

VARIABLE Wrapper for the Variable expression. Optional.

VARIABLE EXP="%%PARM1=%%TIME"

EXP The Variable expression. String. Mandatory.

Example: %%PARM1=%%TIME.

QUANTITATIVE Wrapper for the Quantitative resource. Optional.

QUANTITATIVE NAME="TAPEDRIVE" QUANT="1"

NAME Name of the quantitative resource. String. Mandatory.

1 - 20 characters, case-sensitive.

QUANT Quantity of the resource. String. Mandatory.

Valid values:
0 – 9999. Default: 1

CONTROL Wrapper for the Control resource. Optional.

Control NAME="Resc1" TYPE="E"

NAME Name of the Control resource. String. Mandatory.

Valid values: 1-20 characters, case-sensitive, trailing blanks
only.

TYPE Type of resource.

Valid values:
 E (exclusive-default)
 S (shared)

58
Control-M Utilities Guide

Parameter Description

SHOUT Wrapper for the Shout message. Optional.

SHOUT WHEN="EXECTIME" DEST="workstation1" URGENCY="R"
MESSAGE="Jobcompleted OK." TIME="1015"

WHEN Condition under which the Shout message is sent. Mandatory.

Valid values:
 OK (default)
 NOTOK
 RERUN
 LATESUB
 LATETIME
 EXECTIME

DEST Recipient of the shout message. String. Mandatory.

Valid values: 1-16 characters, case-sensitive. Mandatory.

URGENCY Indicates the urgency of the Shout message. Mandatory.

Valid values:
 R (regular-default)
 U (urgent)
 V (very urgent)

MESSAGE Text of the message. String. Mandatory.

Valid values: 1 - 255 characters, spaces allowed.

TIME Time that the message is sent. String. Mandatory.

STEP_RANGE Step range in the job that can be used in an ON PGMST statement. Optional.
STEP_RANGE NAME="cleanup" FPGMS="Defrag" TPGMS=""

NAME Name for the range. 1-7 character string. Mandatory.

Valid values: 1 - 7 characters. Only trailing blanks are
allowed.

FPGMS Name of the program to be run. as the first program step in

the range. 1 - 8 character string. Mandatory.

FPROCS Name of the procedure to be run. as the first procedure step

in the range. 1-8 character string. Mandatory.

59
Control-M Utilities Guide

Parameter Description

TPGMS Last program step in the range. 1-8 character string.

Mandatory.
Subparameter TO is optional. If blank, its value defaults to
the last step in the job.

TPROCS Last procedure step in the range. 1-8 character string.

Mandatory.
Subparameter TO is optional. If blank, its value defaults to
the last step in the job.

ON Optional.
ON STMT="CODE" CODE="rt5" AND_OR="AND"><ON

STMT A character string containing a statement from the job script

file. String. 1-132 characters. Mandatory for the
On Statement/Code parameter.

CODE Return codes or statuses that can satisfy the step or code
event criteria if returned upon termination of the specified job
steps.
String. Optional. Valid values: 1-255 characters.

PGMS Step in the program. String. Optional.

Valid value: 1-8 characters.

PROCS Step in the process. String. Optional.

Valid values:1-8 characters.

AND_OR Relationship between On statements. Optional.

Valid values:
 AND
 OR

60
Control-M Utilities Guide

Parameter Description

DO Specifies a status for the job based on conditions specified in an On statement.

Optional.
DO ACTION="OK"

ACTION Mandatory. Valid values:

 OK (Changes the status of the job to OK)
 NOTOK (Changes the status of the job to NOTOK)
 RERUN (Reruns the job)
 SPCYC (Prevents further runs of a cyclic job)

DOSHOUT Shout message wrapper. Optional.

DOSHOUT DEST="Wkstn2" URGENCY="R" MESSAGE="Job5 completed OK"

DEST Recipient of the Shout message. String. Mandatory.

Valid values: 1 - 16 characters, case-sensitive.

URGENCY Urgency of the Shout message.

Valid values:
 R (regular-default)
 U (urgent)
 V (very urgent)

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

allowed. Mandatory.

DOCOND Specifies prerequisite conditions to be added or deleted. Optional.

DOCOND NAME="Cond1" ODATE="ODAT" SIGN="ADD"

NAME Condition name. String, 1 - 20 characters, case-sensitive.

Mandatory.

ODATE Condition date. String. Mandatory. Default: ODAT

SIGN Specifies whether to add or delete the condition.

Valid values:
 ADD (default)
 DEL

61
Control-M Utilities Guide

Parameter Description

DOVARIABLE Wrapper for the Variable expression. Optional.

DOVARIABLE EXP="%%PARM1=%%TIME"

EXP The Variable expression. String. Required.

%%PARM1=%%TIME

DOFORCEJOB Forces a specified job when the current job is performed. Optional.
DOFORCEJOB DSN="45446" FOLDER_NAME="Folder2" NAME="Job4"
ODATE="ODAT"

DSN (z/OS only) Library for SMART Folder. String. Mandatory.

FOLDER_NAME Name of the SMART Folder to which the job belongs. String,
1-10 characters. Mandatory.

NAME Name of the job. String. Mandatory.

ODATE Original scheduling date for the job. String. Default: ODAT

DOOUTPUT Handle job output (OUTPUT) when the job is done. Optional.
DOOUTPUT OPTION="Release" PAR="F" FROM=""

OPTION Output handling options. Mandatory.

Valid values:
[All platforms]
 Release
 Delete
[not used with z/OS]
 Copy
 Move
[z/OS only]
 File
 NewDest
 ChangeClass

PAR Certain OPTION values require that you supply additional

information (such as Release, NewDest). String. Optional.

FROM Limits the job output (OUTPUT) handling operation to only

OUTPUTs from the specified class. String. Optional.

62
Control-M Utilities Guide

Parameter Description

DOIFRERUN Job steps to be executed during restart of a job. Available only at sites using
Control-M/Restart. Optional.
DOIFRERUN CONFIRM="0" FPGMS="step1" FPROCS="proc1"
TPGMS="step5" TPROCS="proc3"

CONFIRM Indicates if job must be confirmed by user to be rerun.

Valid values:
 0 (No confirmation. Default)
 1 (Confirmation)

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

characters. Mandatory.

FPROCS Program step within the called procedure. String. 1 - 8

characters. Mandatory.

TPGMS Step at which restarted job must terminate. String. 1 - 8

characters. Mandatory.

TPROCS Program step within the called procedure. String. 1 - 8

characters.
Mandatory.

DOMAIL Sends mail when the job run is complete. Optional.

DOMAIL URGENCY="R" DEST="[email protected]"
CC_DEST="[email protected]" SUBJECT="OK"
MESSAGE="Task completed OK."

ATTACH_OUTPUT Specifies at the job level whether the OUTPUT should be sent
as an email attachment.

URGENCY Urgency of the message.

Valid values:
 R (regular - Default)
 U (Urgent)

DEST Recipient of the message. String. Mandatory.

CC_DEST Additional recipient of the message. String. Optional.

SUBJECT Brief text description of the message contents. String.

Optional.

MESSAGE Text of the message. String. Mandatory.

63
Control-M Utilities Guide

Parameter Description

DOCTBRULE (z/OS only) Invokes a Control-M/Analyzer rule to be executed during the processing
of a specific program step. Optional.
DOCTBRULE NAME="GOVTBAL" PAR="DOREPORT,10,%%ODATE"

NAME Name of the Control-M/Analyzer rule. String. Mandatory.

PAR Arguments that are passed to the Control-M/Analyzer rule.

String. Optional. Maximum: 45 characters.

DOREMEDY Opens a ticket in the Remedy Help Desk regarding the critical service.

URGENCY The urgency level of the ticket that is opened in Remedy.

Mandatory. Valid values are:
 L = Low (Default)
 M = Medium
 H = High
 U= Urgent
 C = Clear

SUMMARY A brief summary is displayed in Remedy. By default, a

summary of the problem appears using variables. For more
information on the field's characteristics, see Remedy
documentation.

DESCRIPTION A detailed description is displayed in Remedy. By default, a

description of the problem appears using variables. For more
information on the field's characteristics, see Remedy
documentation.

64
Control-M Utilities Guide

defjob XML file example

The following is an example of a defjob XML file:
<DEFJOB>
<JOB>
FOLDER_NAME="Tbl1"
FOLDER_DSN="2232"
JOBNAME="Job1"
FILE_NAME="Job1"
SUBAPPLICATION="ACCT"
APPLICATION="App3"
DATACENTER="CTMNYC"
TASKTYPE="Command"
FOLDER_ORDER_ METHOD=""
FILE_PATH="JobLib1"
RUN_AS="Brad"
CREATED_BY="CTMEMUSER"
TIMEFROM="1210"
TIMETO="1310"
MAXRERUN="1"
INTERVAL="1"
PRIORITY="1"
CRITICAL="1"
CYCLIC="1"
CONFIRM="1"
DAYS="1,2,3"
DAYSCAL="Thurs">
<INCOND NAME="Cond1"/>
<OUTCOND NAME="Cond5"/>
<VARIABLE EXP="%%def=123"/>
<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="">

65
Control-M Utilities Guide

<DO ACTION="OK"/>
<DOVARIABLE EXP="%%def=123"/>
<DOSHOUT DEST="" MESSAGE=""/>
<DOFORCEJOB DSN="" FOLDER_NAME="Tbl1"
NAME="Job4"/>
<DOCTBRULE NAME="DOCT"/>
<DOOUTPUT OPTION="Release"/>
<DOIFRERUN FPGMS="1" FPROCS="1" TPGMS="1"
TPROCS="1"/>
<DOCOND NAME="COND4"/>
<DOMAIL DEST="COMP667" MESSAGE="Job done."/>
</ON>
</JOB>
</DEFJOB>

copydefjob
The copydefjob utility copies jobs from one folder to another in the Control-M/EM database that is similar
to a specified existing definition. The original job and the copy must be in different data centers or SMART
Folders. To create a new job using run the defjob utility, see Copying jobs to and from folders using the
copydefjob utility (on page 66).
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 39).
When copydefjob is invoked, it processes a file of arguments that specifies criteria for selecting one or
more existing job processing definitions. The selected jobs are copied to the existing SMART Folder
and/or data center specified in the arguments file. For more information, see copydefjob XML file rules
(on page 67).

Copying jobs to and from folders using the copydefjob utility

This procedure describes how to copy job definitions from one folder to another folder using the
copydefjob utility.

 To copy jobs to and from folders using the copydefjob utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type one of the following commands:

66
Control-M Utilities Guide

• emdef copydefjob [-USERNAME <user> [-PASSWORD <password>] |

-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <XML
file name> [/a]
• emdef copydefjob [-u <user> [-p <password>] | -pf <password file>] -s
<GUI Server Name> -arg <XML file name> [/a]
NOTE: For Windows, you do not need to use the emdef prefix.
For details about the copydefjob parameters and switches, see emdef general parameters (on page
44) and emdef switches (on page 45).
For more information about XML file, see copydefjob XML file rules (on page 67).

copydefjob XML file rules

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. Instructions for preparing this file are in XML file rules (on page 35).
When this file is invoked, job processing definitions are exported from the Control-M/EM database.
Each parameter that you specify must have a FROM value. This value is used as a search criteria for
selecting jobs to copy.
NOTE: The copydefjob utility can use only simple job parameters as search and replace criteria. Complex
parameters, such as the name of an In Condition or the degree of urgency of a Do Shout parameter,
cannot be used as search criteria or modified with the copydefjob utility.
The following rules apply to the copydefjob utility arguments file:
 More than one job can be specified in the arguments file.
 The arguments file is case-sensitive.
 All parameter values (such as strings or digits) must be enclosed in quotation marks (for example,
JOBNAME="Job1").
 Only one COPYJOB parameter can be used in an arguments file.
 The COPYJOB parameter must contain only one of each job parameter. Many job parameters are
optional.
 Multiple values can be specified for TO and FROM by using the * wildcard character. For an
explanation of how wildcards function in the XML-based utilities, see Wildcards (on page 39).
 If any FROM value contains a * and the corresponding TO value contains a *, the * in the TO value
represents the same information the * in the FROM value.
 Changing the data center name or the SMART Folder name imports the copy of the job into a data
center or SMART Folder different from the one in which the original job was located.
Most job definition parameters are optional. However note the following:

67
Control-M Utilities Guide

 If you specify any parameters, the FROM subparameter is mandatory and the TO subparameter is
optional.
 If a FROM value is specified without a TO value, it is used as a filter criterion.
 If a TO value is specified, it indicates the new value of the parameter.
For more information on the arguments file parameters for the copydefjob utility, see copydefjob XML file
parameters (on page 68), and copydefjob XML file examples (on page 83).

copydefjob XML file parameters

The following table lists input file parameters for the copydefjob utility:

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file.

COPYJOB These tags indicate the start and end of the COPYJOB argument. Only criteria that
are located between the tags are considered to be part of the argument.

FOLDER_NAME Name of the SMART Folder to which the job belongs.

NOTE: At least one of the following SMART Folder parameters must be included in
the arguments file: DATACENTER, FOLDER_NAME, FOLDER_DSN
EXAMPLE: FOLDER_NAME FROM="Tbl5NYC" TO="Tbl7NYC"

FROM Name of the SMART Folder specified in the job processing definition that is
being copied. String. Mandatory.

TO The folder name in the job processing definition copy. String. Optional.

FOLDER_DSN (z/OS® only) Name of the library that contains the SMART Folder. Mandatory.
NOTE: At least one of the following SMART Folder parameters must be included in
the arguments file: DATACENTER, FOLDER_NAME, FOLDER_DSN
EXAMPLE: FOLDER_DSN FROM="Lib1" TO="Lib1_COPY"

FROM Name of the library containing the SMART Folder in the job processing
definition that is being copied. String. Mandatory.

TO Name of the library in the job processing definition copy. String. Optional.

68
Control-M Utilities Guide

Parameter Description

DATACENTER Name of the Control-M installation to which the job belongs.

NOTE: At least one of the following SMART Folder parameters must be included in
the arguments file: DATACENTER, FOLDER_NAME, FOLDER_DSN
EXAMPLE: DATACENTER FROM="EM_Montreal" TO="EM_Paris"

FROM Name of the Control-M installation to which the job being copied belongs.
Mandatory.

TO Name of the Control-M installation to which the job copy belongs.

Optional.

69
Control-M Utilities Guide

Parameter Description

JOBNAME Name of the job processing definition.

EXAMPLE: JOBNAME FROM="Job3"

FROM String. Mandatory.

FILE_NAME Name of the file that contains the job script.

EXAMPLE: FILE_NAME FROM="Mem3"

FROM String. Mandatory.

SUB_APPLICATION Name of the group to which the job belongs. Used as a descriptive name for related
groups of jobs.
EXAMPLE: SUB_APPLICATION FROM="Grp_HR"

FROM String. Mandatory.

APPLICATION Name of the application to which the job’s group belongs. Used as a descriptive
name for related groups of jobs.
EXAMPLE: APPLICATION FROM="App3""

FROM String. Mandatory.

TASKTYPE Type of the job (task) to be performed by Control-M.

EXAMPLE: TASKTYPE FROM="Detached"

FROM Mandatory. Valid values:

 Job
 Detached
 Command
 Dummy
(z/OS only) Valid values:
 Started_Task
 Cyclic_Job
 Cyclic_Task
 Emergency_Job
 Emergency_Cyclic_Job
 Emergency_Task
 Emergency_Cyclic_Task

70
Control-M Utilities Guide

Parameter Description

FOLDER Optional.
_ORDER_ METHOD
EXAMPLE: FOLDER_ORDER_ METHOD FROM="Job3"

FROM String. Mandatory.

CREATED_BY Control-M/EM user who defined the job. String. Optional.

EXAMPLE: CREATED_BY FROM="emuser"
NOTE: This argument is used by the Control-M/Server security mechanism and,
under certain circumstances, cannot be modified. For more information, see the
Security chapter and the description of the AuthorSecurity system parameter in GUI
Server parameters.

FROM String. Mandatory.

FILE_PATH Name of the library/directory in which the job script resides. String. Optional.
EXAMPLE: FILE_PATH 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.

HOSTID Host name of an agent computer or name of a host group to which the job is
submitted. Optional.
EXAMPLE: HOSTID FROM="Com3"

FROM String. Mandatory.

RUN_AS Run_As name associated with the job. This parameter is used by the
Control-M/Server security mechanism. Optional.
EXAMPLE: RUN_AS FROM="emuser"

FROM String. Mandatory.

MAXRERUN Specifies the maximum number of reruns that can be performed for the job.
EXAMPLE: MAXRERUN FROM="1"
Valid values: 0-99. Default: 0

FROM String. Mandatory.

71
Control-M Utilities Guide

Parameter Description

TIMEFROM Indicates the earliest time for submitting the job.

EXAMPLE: TIMEFROM FROM="1430"

FROM String. Mandatory.

TIMETO Indicates the latest time for submitting the job.

EXAMPLE: TIMETO FROM="1600"

FROM String. Mandatory.

DUE_OUT Time that the job is expected to finish.

EXAMPLE: DUE_OUT FROM="1500"

FROM String. Mandatory.

72
Control-M Utilities Guide

Parameter Description

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

CYCLIC_TYPE Determines the type of cyclic job:

 Interval
 IntervalSequence
 SpecificTimes

CYCLIC_ Maximum delay in minutes permitted for a late submission when selecting a specific
TOLERANCE time (for example 5 minutes).

CYCLIC_INTERVAL_ A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up to

SEQUENCE 4000 characters including commas.

CYCLIC_TIMES_ A list of times, separated by commas (for example 0800,1330,2300), which supports
SEQUENCE time synonym (for example 2730).

CONFIRM Indicates that the job must be manually confirmed by the Control-M/EM user before
it runs.
EXAMPLE: CONFIRM FROM="0"

FROM Mandatory. Valid values:

 0 (Default)
 1

73
Control-M Utilities Guide

Parameter Description

AUTOARCH Determines whether SYSDATA is to be archived.

EXAMPLE: AUTOARCH FROM=0"

FROM Mandatory. Valid values:

 0 (Default)
 1

INTERVAL Specifies the length of time (in minutes) to wait between reruns of a job or between
cyclic runs of a job. Integer. Optional.
EXAMPLE: INTERVAL FROM="3"

FROM String. Mandatory.

OVERRIDE_PATH Name of an alternate job script library/directory. String.

EXAMPLE: OVERRIDE PATH 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 database 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"

74
Control-M Utilities Guide

Parameter Description

FROM String. Mandatory.

DAYS_AND_OR Indicates the relationship between specified Days values and Weekdays values.
Optional.
EXAMPLE: DAYS_AND_OR FROM="AND"

FROM String. Mandatory.

WEEKDAYS Days of the week on which to order the job. String. Optional.
EXAMPLE: WEEKDAYS FROM="1,2,4"

FROM String. Mandatory.

DATE Specific dates on which to order the job. String. MMDD format. Optional.
EXAMPLE: DATE FROM="0312"

FROM String. Mandatory. Dates can be written in mmdd format. There is no

delimiter between dates. For example, January 10 is written in this
manner: DATE="0110"

DAYSCAL Name of a user-defined calendar used to specify a set of days. String. Optional.
EXAMPLE: DAYSCAL FROM="shipping"

FROM String. Mandatory.

WEEKSCAL Name of a calendar to be used to validate specified weekdays on which to order the
job. String. Optional.
EXAMPLE: WEEKSCAL FROM="2"

FROM String. Mandatory.

CONFCAL Specifies a calendar that is used to validate all specified days and dates on which to
schedule the job. String.
EXAMPLE: CONFCAL FROM="cal99" TO="cal00"

FROM String. Mandatory.

RETRO Indicates whether the job is scheduled for possible execution after its original
scheduling date (odate) has passed.
EXAMPLE: RETRO FROM="0"

75
Control-M Utilities Guide

Parameter Description

FROM Mandatory. Valid values:

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

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

EXAMPLE: SHIFT FROM="PREVDAY"

FROM Mandatory. Valid values:

 IGNOREJOB
 PREVDAY
 NEXTDAY
 NOCONFCAL

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

EXAMPLE: SHIFTNUM FROM="-10"

FROM String. Mandatory.

MAXDAYS Maximum number of days to retains the SYSDATA archive dataset for jobs that
ended NOTOK. Subparameter of AUTOARCH. String. Optional.
EXAMPLE: MAXDAYS FROM="07"

FROM Integer. Mandatory.

MAXRUNS Maximum number of job runs to retains the SYSDATA archive dataset for jobs that
ended NOTOK. Subparameter of AUTOARCH. String. Optional.
EXAMPLE: MAXRUNS FROM="100"

FROM String. Mandatory.

RERUNMEM Name of the JCL member to use when the job is automatically rerun. String. 1-8
characters. Optional.
EXAMPLE: RERUNMEM FROM="Mem45"

FROM String. Mandatory.

RETEN_DAYS (z/OS only) Number of days to retain the job in the History Jobs file. String. Optional.
EXAMPLE: RETEN_DAYS FROM="5"

FROM String. Mandatory.

76
Control-M Utilities Guide

Parameter Description

RETEN_GEN (z/OS only) Maximum number of generations of the job to keep in the History Jobs
file. String.
EXAMPLE: RETEN_GEN FROM="3"

FROM String. Mandatory.

TASK_CLASS Job class for the task.

EXAMPLE: TASK_CLASS FROM="Distribution"

FROM Mandatory. Valid values:

 Distribution
 Decollation

PREV_DAY Flag to indicate whether job scheduling is shifted to a previous working day in the
CONFCAL calendar. Optional.
EXAMPLE: PREV_DAY FROM="N"

FROM Mandatory. Valid values:

 Y
 N

IND_CYCLIC Indicates whether the interval between further runs of a cyclic job is counted from
the start or the end of the previous job run. Optional.
EXAMPLE: IND_CYCLIC FROM="START"

FROM Mandatory. Valid values:

 START
 END

RULE_BASED_ Relationship (AND|OR) between the specified Rule-Based Calendar and the job’s own
CALENDAR_RELATIO basic scheduling criteria. Optional.
NSHIP
EXAMPLE: RULE_BASED_CALENDAR_RELATIONSHIP FROM="AND"

FROM Mandatory. Valid values:

 AND
 OR

77
Control-M Utilities Guide

Parameter Description

TAG Relationship (AND|OR) between the specified Schedule Tag criteria and the job’s own
_RELATIONSHIP basic scheduling criteria. This parameter is relevant only for jobs in a SMART Folder.
Optional. This parameter is for backward compatibility.
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.

CATEGORY Name of a Control-D report decollating mission category that must be scheduled
under Control-D when the job is scheduled under Control-M. String. Optional.
EXAMPLE: CATEGORY FROM="DAILY"

FROM String. Mandatory.

78
Control-M Utilities Guide

Parameter Description

PREVENTNCT2 (z/OS only) Prevents dataset cleanup before the original job run. Optional.
Valid values:
 Blank – Does not perform data set cleanup before the original job run. Default.
 N – Does not prevent cleanup.
 Y - Prevents data set cleanup. This value is not valid for started tasks.
 L (List) – Do not perform data set cleanup before the original job run. Do
generate messages that would be required for CDG adjustment during restart.
 F (Flush) – Halt processing of the job if any data set cleanup error is detected
(even if z/OS would not have stopped processing the job).
EXAMPLE: PREVENTNCT2 FROM="1"

FROM Mandatory. Valid values:

 0
 1

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

OPTION Job output (OUTPUT) handling options.

EXAMPLE: OPTION FROM="Copy"

FROM Mandatory. Valid values:

 Release
 Delete
 Copy
 Move
 File
 NewDest
 ChangeClass

79
Control-M Utilities Guide

Parameter Description

PAR Certain OPTION FROM values (such as Release, NewDest) require additional
information. The PAR parameter holds this information as a string.
EXAMPLE: PAR FROM="mem3.log"

FROM String. Mandatory.

FROM Limits the OUTPUT handling operation to OUTPUTs from the specified class.
Optional.
EXAMPLE: FROM FROM="5"

FROM String. Mandatory.

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

FROM String. Mandatory.

APPL_TYPE Indicates the type of external application (for example, SAP or Oracle) on which the
external application job runs. Mandatory for external application jobs.
EXAMPLE: APPL_TYPE FROM="SAP"

FROM Mandatory. String. Up to 10 characters.

APPL_VER Version of the external application (for example, SAP or Oracle) on which the
external application job runs. Mandatory for external application jobs.
EXAMPLE: APPL_VER FROM="4.6"

FROM Mandatory. String. Up to 10 characters.

APPL_FORM Predefined set of external application parameters that are displayed in the Job
Properties team. 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 Add-on (for example, SAP or Oracle)
that is installed in the Control-M installation. Mandatory for external application jobs.
EXAMPLE: CM_VER FROM="6.1.00"

80
Control-M Utilities Guide

Parameter Description

FROM Mandatory. String. Up to 10 characters.

MULTY_AGENT When selected, broadcasts job submission details to all agents in a specified Host
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 (z/OS only) Indicates the start of a period of time during which the job or SMART
Folder can be ordered. Optional.
EXAMPLE: ACTIVE_FROM FROM="20070315"

FROM Mandatory. Date Format: YYYYMMDD

ACTIVE_TILL (z/OS only) Indicates the end of a period of time during which the job or SMART
Folder can be ordered. Optional.
EXAMPLE: ACTIVE_TILL FROM="20070315"

FROM Mandatory. Date Format: YYYYMMDD

TIMEZONE Indicates global time zone used to calculate the interval for time-related conditions.
Optional.
EXAMPLE: TIMEZONE FROM="EST"

FROM Mandatory. String. Default: GMT

SYSTEM_AFFINITY Identity of the system in which the job must be initiated and executed (in JES2).
Identity of the processor on which the job must execute (in JES3). Optional. String.

FROM String. Mandatory.

EXAMPLE: SYSTEM_AFFINITY FROM="SYS3"

REQUEST_NJE Specifies the host in the JES network on which the job is to execute.
_HOST
FROM String. Mandatory.
EXAMPLE: REQUEST_NJE_HOST FROM="OS5"

81
Control-M Utilities Guide

Parameter Description

SCHEDULING (z/OS only) Indicates the JES2 workload management scheduling environment that is
_ENVIRONMENT to be associated with the job.

FROM String. Mandatory.

EXAMPLE: SCHEDULING_ENVIRONMENT FROM="SCHD2"

CREATION Name of the user who created the job. String.

_USER
EXAMPLE: CREATION_USER FROM="emuser"

FROM String. Mandatory.

CREATION Date on which the job was created. String.

_DATE
EXAMPLE: CREATION_DATE FROM="1212"

FROM String. Mandatory.

CREATION Time at which the job was created. String.

_TIME
EXAMPLE: CREATION_TIME FROM="1230"

FROM String. Mandatory.

CHANGE Name of the user that last modified the job. String.
_USERID
EXAMPLE: CHANGE_USERID FROM="emuser"

FROM String. Mandatory.

CHANGE Date that the job was last modified. String.

_DATE
EXAMPLE: CHANGE_DATE FROM="1204"

FROM String. Mandatory.

CHANGE_TIME Time that the job was last modified. String.

EXAMPLE: CHANGE_TIME FROM="1650"

FROM String. Mandatory.

82
Control-M Utilities Guide

copydefjob XML file examples

The following are examples of the copydefjob XML files:
 Copy jobs and parameter values XML file example (on page 83)
 Copy all jobs in one folder to another folder XML file example (on page 83)
 Copy all cyclic jobs with similar job name XML file example (on page 83)
 Copy jobs in a Regular Folder to a SMART Folder XML file example (on page 84)
 Copying jobs in a folder to a SMART Folder using the copydefjob utility (on page 84)

Copy jobs and parameter values XML file example

In the copydefjob arguments file, copy job processing definitions in the F15NYC folder if FOLDER_DSN is
Lib1 and JOBNAME is Job3. In the copy, the FOLDER_DSN value is changed to Lib1_COPY.
<COPYJOB>
<FOLDER_NAME FROM="F15NYC"/>
<FOLDER_DSN FROM="Lib1" TO="Lib1_COPY"/>
<JOBNAME FROM="Job3"/>
</COPYJOB>

Copy all jobs in one folder to another folder XML file example
In the copydefjob XML file, copy all jobs in the F15NYC folder to the F17LA folder.
<COPYJOB>
<FOLDER_NAME FROM="F15NYC" TO="F17LA"/>
</COPYJOB>

Copy all cyclic jobs with similar job name XML file example
In the copydefjob XML file, copy all cyclic jobs in the GrpAcct Sub Application that have a JobName
beginning with the string Acct from FOLDER_DSN 23Y to FOLDER_DSN 14G.
<COPYJOB>
<FOLDER_DSN FROM="23Y" TO="14G">
<SUBAPPLICATION FROM="GrpAcct"/>
<CYCLIC FROM="1"/>
<JOBNAME="Acct*" />
</COPYJOB>

83
Control-M Utilities Guide

Copy jobs in a Regular Folder to a SMART Folder XML file example

In the copydefjob XML file, copy all jobs in the RegFolder folder in the ctm900 data center to the
GrpSFolder SMART Folder.
<COPYJOB>
<DATACENTER FROM="ctm900"/>
<FOLDER_NAME FROM="RegFolder" TO="GrpSFolder"/>
</COPYJOB>

Copying jobs in a folder to a SMART Folder using the copydefjob utility

This procedure describes how to copy the jobs in a folder to a SMART Folder using the copydefjob utility.

 To copy jobs in a folder to a SMART folder:

1. From Control-M, define a SMART Folder containing no jobs and then Check In the SMART Folder.
2. Create a copydefjob arguments file in which jobs in a folder are copied to the SMART Folder that you
created by doing the following:
a. Open a text editor and format the file using the specifications referred to in copydefjob XML file
parameters (on page 68).
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 Folder Name value of the jobs changes from the name of the folder to the name
of the SMART Folder.
EXAMPLE: FOLDER_NAME FROM="Sched_Fl_Name" TO="Grp_Sched_Fl_Name"
d. Save and close the file.
3. At the command line, enter the copydefjob utility command that uses the file that you created in the
previous step:
copydefjob -u <user> [-p <password>] -s <GUI Server Name> -arg <XML file
name>
4. In Control-M do the following:
a. Click Load to upload the SMART Folder to the Control-M/Server.
b. Order the SMART Folder.
c. Verify that the SMART Folder now contains the jobs that were copied to it.
If you do not need the original folder, you can delete it.

84
Control-M Utilities Guide

deldefjob
The deldefjob utility deletes specified job processing definitions in the Control-M/EM database. To delete
jobs using the deldefjob utility, see Deleting jobs using the deldefjob utility (on page 85).
When deldefjob is invoked, it processes a specified file of arguments in XML format. This file contains
statements that identify existing job processing definitions. The identified definitions are deleted from the
Control-M/EM database. For more information, see deldefjob XML file rules (on page 85).

Deleting jobs using the deldefjob utility

This procedure describes how to delete specified job processing definitions in the Control-M/EM database
by using the deldefjob utility.

 To delete jobs using the deldefjob utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter either of the following commands:
• emdef deldefjob [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <XML
file name> [/a]
• emdef deldefjob [-u <user> [-p <password>] | -pf <password file>] -s <GUI
Server Name> -arg <XML file name> [/a]
NOTE: For Windows, you do not need to use the emdef prefix.
For details about the deldefjob parameters and switches, see emdef general parameters (on page 44)
and emdef switches (on page 45).
For more information about the XML file, see deldefjob XML file rules (on page 85).

deldefjob XML file rules

The following rules apply to the deldefjob arguments file:
 More than one job can be specified in a deldefjob file.
 The arguments file is case-sensitive.
 More than one PARAM parameter can be used in a TERM statement.
 The relationship between PARAM parameters in a TERM statement is AND.
 The default relationship between TERM statements is OR.
 All parameter values must be enclosed in quotation marks (for example, JOBNAME="Job1").
For instructions about preparing this file, see XML file rules (on page 35).

85
Control-M Utilities Guide

For more information about the deldefjob XML file parameters, see deldefjob XML file parameters (on
page 86), and deldefjob XML file example (on page 87).

deldefjob XML file parameters

The following table lists the XML file parameters for the deldefjob utility:

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file.

TERMS These tags indicate the start and end of the TERM tags. Only criteria that are
located between these tags are considered to be part of the argument.

TERM The TERM tags indicate the start and end of a group of selection criteria for a job
or jobs that are to be deleted. Only PARAM tags that are located between the
TERM tags are considered to be part of the TERM argument.

REL Optional. Relationship between terms.

Valid values:
 AND
 OR (default)

86
Control-M Utilities Guide

Parameter Description

PARAM The selection criteria parameter used to determine job definitions to be deleted.
More than one PARAM can be specified. Mandatory.
PARAM NAME="DATACENTER" OP="EQ" VALUE="Center1"

NAME String. Mandatory.

Name of any job processing parameter.
NOTE: At least one of the following SMART Folder parameters must
be included in the arguments file:
 DATACENTER
 FOLDER_NAME
 FOLDER_DSN

OP Mandatory. Valid values:

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

VALUE String. Mandatory.

Valid value for the specified job processing parameter.

deldefjob XML file example

The following example argument files are used with the deldefjob utility:
 Delete definitions with the same job name XML file example (on page 87)
 Delete definitions that satisfy one or both of two criteria XML file example (on page 88)
 Delete definitions that meet multiple criteria XML file example (on page 88)

Delete definitions with the same job name XML file example
In the deldefjob XML file, delete job processing definitions with the name Job5 from the EM5NY data
center.
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="EM5NY"/>

87
Control-M Utilities Guide

<PARAM NAME="JOBNAME" OP="EQ" VALUE="Job5"/>

</TERM>
</TERMS>

Delete definitions that satisfy one or both of two criteria XML file example
In the deldefjob XML file, delete job processing definitions that satisfy either the data center name is
Data1 and the jobname begins with the letter J, or the jobname is Job5 and the job is not cyclic.
<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>

Delete definitions that meet multiple criteria XML file example

In the deldefjob XML file, delete definitions for cyclic jobs in the EM5NY data center that are scheduled
to run in January, February, and March.
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="EM5NY"/>
<PARAM NAME="CYCLIC" OP="EQ"
VALUE="1"/>
<PARAM NAME="JAN" OP="EQ" VALUE="1"/>
<PARAM NAME="FEB" OP="EQ" VALUE="1"/>
<PARAM NAME="MAR" OP="EQ" VALUE="1"/>
</TERM>
</TERMS>

88
Control-M Utilities Guide

duplicatedefjob
The duplicatedefjob utility makes a copy of an existing job definition in the same data center and SMART
Folder. Elements of the copy can be changed. To copy jobs using the duplicatedefjob utility, see Copying
existing jobs using the duplicatedefjob utility (on page 89).
NOTE: Multiple jobs can be selected and copied using the * wildcard character. For an explanation of
how wildcards function in XML-based utilities, see Wildcards (on page 39).
When duplicatedefjob is invoked, it processes a specified file of arguments in XML format. This file
contains statements that identify existing job processing definitions. The identified definitions are copied,
changes to the copy (if requested) are made, and the copy is stored in the Control-M/EM database. For
more information, see duplicatedefjob XML file rules (on page 90).

Copying existing jobs using the duplicatedefjob utility

The following procedure describes how to copy an existing job definition in the same data center and
SMART Folder using the duplicatedefjob utility.
 To copy existing jobs using the duplicatedefjob utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter either of the following commands:
• emdef duplicatedefjob [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <XML
file name> [/a]
• emdef duplicatedefjob [-u <user> [-p <password>] | -pf <password file>]
-s <GUI Server Name> -arg <XML file name> [/a]
NOTE: For Windows, you do not need to use the emdef prefix.
For details about the duplicatedefjob parameters and switches, see emdef general parameters (on
page 44) and emdef switches (on page 45).
For more information about the XML file name, see duplicatedefjob XML file rules (on page 90).

89
Control-M Utilities Guide

duplicatedefjob XML file rules

The duplicatedefjob utility can use 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.
For instructions about preparing this file, see XML file rules (on page 35).
The following rules apply to the arguments file for the duplicatedefjob utility:
 More than one job can be specified in a duplicatedefjob file.
 The arguments file is case-sensitive.
 All parameter values must be enclosed in quotation marks (for example, JOBNAME="Job1").
 Only one DUPLICATEJOB parameter can be used in the arguments file. This parameter must not
contain more than one instance of each job parameter.
 Multiple values can be specified for TO and FROM by using the * wildcard character. For an
explanation of how wildcards function in the XML-based utilities, see Wildcards (on page 39).
 If any FROM value contains *, and the corresponding TO value contains *, the * in the TO value
expresses the same information as the * in the FROM value.
 Changing the data center name or SMART Folder name causes the copy of the job scheduling
definition to be imported into the specified data center or SMART Folder.
Most job definition parameters in the arguments file are optional. However note the following:
 For each parameter that is specified, the FROM subparameter is mandatory and the TO subparameter
is optional.
 When FROM is specified without a TO, the FROM value is used as a filter criterion.
The FROM value is used as a search criteria for selecting jobs to copy. For example, JOBNAME
FROM="Job2" copies all jobs with the JobName Job2
 When TO is included, it specifies the value to which the parameter is set. For example, JOBNAME
FROM="Job2" TO="Job2B" modifies all jobs with JobName Job2 so that they now have JobName
Job2B.
The duplicatedefjob arguments file is checked and processed. If the file contains errors, a message is
displayed specifying the lines with the errors.
For more information on the arguments file parameters for the duplicatedefjob utility, see duplicatedefjob
XML file parameters (on page 91), and duplicatedefjob XML file examples (on page 112).

90
Control-M Utilities Guide

duplicatedefjob XML file parameters

The following table describes the duplicateddefjob arguments XML file parameters:

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being
used, and the location of the .dtd file.

DUPLICATEJOB The DUPLICATEJOB tags indicate the start and end of a group of selection
criteria for a job or jobs that are to be copied. Only criteria that are located
between the DUPLICATEJOB tags are considered to be part of the
duplicatedefjob parameters.

FOLDER_NAME Name of the SMART Folder to which the job belongs. Mandatory.
NOTE: At least one of the following SMART Folder parameters must be
included in the arguments file: DATACENTER, FOLDER_NAME, FOLDER_DSN
FOLDER_NAME FROM="Tbl5NYC"

FROM String. Mandatory

Folder_DSN (z/OS only). Name of the library that contains the SMART Folder. Mandatory.
NOTE:
 A TO subparameter cannot be specified for this parameter.
 At least one of the following SMART Folder parameters must be included
in the arguments file: DATACENTER, FOLDER_NAME, FOLDER_DSN
FOLDER_DSN FROM="Lib1"

FROM String. Mandatory

91
Control-M Utilities Guide

Parameter Description

DATACENTER Name of the Control-M installation to which the job belongs. Mandatory.
NOTE:
 A TO parameter cannot be specified for this parameter.
 At least one of the following SMART Folder parameters must be included
in the arguments file: DATACENTER, FOLDER_NAME,FOLDER_DSN
DATACENTER FROM="CTMNYC"

FROM String. Mandatory.

FOLDER_ String. Mandatory.

ORDER_ METHOD
NOTE: A TO parameter can be specified and modified for this parameter.
FOLDER_ORDER_ METHOD FROM="Job3"

FROM String. Mandatory.

JOBNAME Name of the job processing definition. Optional.

JOBNAME FROM="Job3" TO="Job3_COPY"

FROM Mandatory.

TO Optional.

FILE_NAME Name of the file that contains the job script. Optional.
FILE_NAME FROM="Mem3" TO="Mem7"

FROM Mandatory.

TO Optional.

SUB_APPLICATION Name of the group to which the job belongs. Used as a descriptive name for
related jobs. Optional.
SUB_APPLICATION FROM="Grp_HR" TO="Grp_ACCT"

FROM Mandatory.

TO Optional.

92
Control-M Utilities Guide

Parameter Description

APPLICATION Name of the application to which the job’s group belongs. Used as a
descriptive name for related jobs. Optional.
APPLICATION FROM="App3" TO="App1"

FROM String. Mandatory.

TO String Optional.

93
Control-M Utilities Guide

Parameter Description

TASKTYPE Type of the job (task) to be performed by Control-M. Optional.

TASKTYPE FROM="Detached" TO="Job"

FROM Mandatory.
Valid values:
 Job
 Detached
 Command
 Dummy
(z/OS only) Valid values:
 Started_Task
 Cyclic_Job
 Cyclic_Task
 Emergency_Job
 Emergency_Cyclic_Job
 Emergency_Task
 Emergency_Cyclic_Task

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

(z/OS only) Valid values: Same as z/OS FROM values.

CREATED_BY Control-M/EM user who defined the job. String. Optional.

CREATED_BY FROM="emuser" TO="em5"
NOTE: This argument is used by the Control-M/Server security mechanism.
Under certain circumstances, it cannot be modified. For more information,
see the Security chapter and the description of the AuthorSecurity system
parameter in GUI Server parameters.

FROM String. Mandatory.

TO String. Optional.

94
Control-M Utilities Guide

Parameter Description

FILE_PATH Name of the library/directory in which the job script resides. String. Optional.
FILE_PATH FROM="File1" TO="File4"

FROM String. Mandatory.

TO String. Optional.

CMDLINE Command string supplied when the job Task Type is Command. Optional.
CMDLINE FROM="C:\Format" TO="C\:CD Emnt"

FROM String. Mandatory.

TO String. Optional.

HOSTID Host name of an agent computer or a host group to which the job is
submitted. Optional.
HOSTID FROM="Com3" TO="Acct4"

FROM String. Mandatory.

TO Host name of the agent computer on which the job copy

is running Optional.

RUN_AS Owner (user ID) associated with the job. This parameter is used by the
Control-M/Server security mechanism. Optional.
OWNER FROM="emuser" TO="emhr"

FROM String. Mandatory.

TO String. Optional.

MAXRERUN Maximum number of reruns that can be performed for the job. Optional.
MAXRERUN FROM="1" TO="3"

FROM String. Mandatory.

TO String. Optional.

TIMEFROM Earliest time for submitting the job. Optional.

TIMEFROM FROM="1430" TO="1450"

FROM String. Mandatory.

TO String. Optional.

95
Control-M Utilities Guide

Parameter Description

TIMETO Latest time for submitting the job. Optional.

TIMETO FROM="1600" TO="1620"

FROM String. Mandatory.

TO String. Optional.

DUE_OUT Time that the job is expected to finish. Optional.

DUE_OUT FROM="1500" TO="1530"

FROM String. Mandatory.

TO String. Optional.

PRIORITY Control-M job priority. Optional.

PRIORITY FROM="AA" TO="1A"

FROM String. Mandatory.

TO String. Optional.

96
Control-M Utilities Guide

Parameter Description

CRITICAL Indicates whether the job is a critical-path job in Control-M. Optional.

CRITICAL FROM="0" TO="1"

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

CYCLIC Indicates whether the job is cyclic (to be run at regular intervals). Optional.
CYCLIC FROM="0" TO="1"

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

CYCLIC_TYPE Determines the type of cyclic job:

 Interval
 IntervalSequence
 SpecificTimes

CYCLIC_ Maximum delay in minutes permitted for a late submission when selecting a
TOLERANCE specific time (for example 5 minutes).

CYCLIC_INTERVAL_ A list of time intervals, separated by commas, (for example +30M,+2H,+1D)

SEQUENCE up to 4000 characters including commas.

CYCLIC_TIMES_ A list of times, separated by commas (for example 0800,1330,2300), which

SEQUENCE supports time synonym (for example 2730).

97
Control-M Utilities Guide

Parameter Description

CONFIRM Indicates whether the job must be manually confirmed by the Control-M/EM
user before it runs. Optional.
CONFIRM FROM="0" TO="1"

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

AUTOARCH Determines whether SYSDATA is to be archived. Optional.

AUTOARCH FROM=0" TO="1"

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

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

FROM String. Mandatory.

TO String. Optional.

OVERRIDE_PATH Name of an alternate job script library/directory. String. Optional.

OVERRIDE PATH FROM="lib3" TO="lib4"

FROM String. Mandatory.

TO String. Optional.

98
Control-M Utilities Guide

Parameter Description

MAXWAIT Number of extra days (after the original scheduling date) that the job is
allowed to remain in the Active Jobs database awaiting execution. Integer.
Optional.
MAXWAIT FROM="4" TO="3"

FROM Integer. Mandatory.

TO Integer. Optional.

DESCRIPTION Free text description of the job. String. Optional.

DESCRIPTION FROM="data backup from 120399" TO="data
backup from 021400"

FROM String. Mandatory.

TO String. Optional.

DOCMEM Name of the file containing job documentation. String. Optional.

DOCMEM FROM="mem4" TO="Mem67"

FROM String. Mandatory.

TO String. Optional.

DOCLIB Name of library or directory containing the job documentation file. String.
Optional.
DOCLIB FROM="AcctFiles" TO="HRFiles"

FROM String. Mandatory.

TO String. Optional.

DAYS Days of the month on which to order the job. String. Optional.
DAYS FROM="ALL" TO="159"

FROM String. Mandatory.

TO String. Optional.

99
Control-M Utilities Guide

Parameter Description

DAYS_AND_OR Relationship between specified Days values and Weekdays values. Optional.
DAYS_AND_OR FROM="AND" TO="OR"

FROM String. Mandatory.

TO String. Optional.

WEEKDAYS Days of the week on which to order the job. String. Optional.
WEEKDAYS FROM="1,2,4" TO="ALL"

FROM String. Mandatory.

TO String. Optional.

DATE Specific dates on which to order the job. String. MMDD format. Optional.
DATE FROM="0312" TO="0319"

FROM String. Dates are written in mmdd format. Mandatory.

There is no delimiter between dates. For example,
January 10 is written: DATE="0110."

TO String. Dates are written in mmdd format. Optional.

There is no delimiter between dates. For example,
January 10 is written: DATE="0110."

DAYSCAL User-defined calendar used to specify a set of days. String. Optional.

DAYSCAL FROM="shipping" TO="receiving"

FROM String. Mandatory.

TO String. Optional.

WEEKSCAL Calendar to be used to validate specified weekdays on which to order the job.
String. Optional.
WEEKSCAL FROM="w5" TO="w6"

FROM String. Mandatory.

TO String. Optional.

100
Control-M Utilities Guide

Parameter Description

CONFCAL Specifies a calendar that is used to validate all specified days and dates on
which to schedule the job. String. Optional.
CONFCAL FROM="cal99" TO="cal00"

FROM String. Mandatory.

TO String. Optional.

RETRO Indicates whether the job is scheduled for possible execution after its original
scheduling date (odate) has passed. Optional.
RETRO FROM="0" TO="1"

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

SHIFT Describes how to shift the scheduling date of the job. Optional.
SHIFT FROM="PREVDAY" TO="NEXTDAY"

FROM Mandatory. Valid values:

 IGNOREJOB
 PREVDAY
 NEXTDAY
 NOCONFCAL

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

SHIFTNUM Number of days to shift the scheduling date of the job. Optional.
SHIFTNUM FROM="-10" TO="5"

FROM String. Mandatory.

TO String. Optional.

101
Control-M Utilities Guide

Parameter Description

MAXDAYS Maximum number of days to retain the SYSDATA archive dataset for jobs that
ended NOTOK. Subparameter of AUTOARCH. String. Optional.
MAXDAYS FROM="07" TO="14"

FROM String. Mandatory.

TO String. Optional.

MAXRUNS Maximum number of job runs to retain the SYSDATA archive dataset for jobs
that ended NOTOK. Subparameter of AUTOARCH. String. Optional.
MAXRUNS FROM="100" TO="250"

FROM String. Mandatory.

TO String. Optional.

RERUNMEM (z/OS only) JCL member to use when the job is automatically rerun. String. 1
- 8 characters. Optional.
RERUNMEM FROM="Mem45" TO="Mem7"

FROM String. Mandatory.

TO String. Optional.

RETEN_DAYS (z/OS only) Number of days to retain the job in the History Jobs file. String.
Optional.
RETEN_DAYS FROM="5" TO="7"

FROM String. Mandatory.

TO String. Optional.

RETEN_GEN (z/OS only) Maximum number of generations to keep in the History Jobs file.
String. Optional.
RETEN_GEN FROM="3" TO="4"

FROM String. Mandatory.

TO String. Optional.

102
Control-M Utilities Guide

Parameter Description

PREV_DAY Optional.
PREV_DAY FROM="N" TO="Y"

FROM Mandatory. Valid values:

 Y
 N

TO Optional. Valid values:

 Y
 N

IND_CYCLIC Indicates whether the time interval between runs of a cyclic job is counted
from the start or the end of the previous job run. Optional.
IND_CYCLIC FROM="Y" TO="N"

FROM Mandatory. Valid values:

 START
 END

TO Optional. Valid values:

 START
 END

RULE_BASED_ Relationship (AND|OR) between the specified Rule-Based Calendar and the
CALENDAR_ job’s own basic scheduling criteria. Optional.
RELATIONSHIP RULE_BASED_CALENDAR_RELATIONSHIP FROM="AND" TO="OR"

FROM Mandatory. Valid values:

 AND
 OR

TO Optional. Valid values:

 AND
 OR

103
Control-M Utilities Guide

Parameter Description

TAG_ Relationship (AND|OR) between the specified Schedule Tag criteria and the
RELATIONSHIP job’s own basic scheduling criteria. This parameter is relevant only for jobs in
a SMART Folder. Optional. This parameter is for backward compatibility.
TAG_RELATIONSHIP FROM="AND" TO="OR"

FROM Mandatory. Valid values:

 AND
 OR

TO Optional. Valid values:

 AND
 OR

SYSDB Determines whether single or multiple data sets are used to catalogue
sysdata. Optional.
SYSDB FROM="1" TO="0"

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

PDSNAME Name of partitioned dataset (PDS) to be checked for free space. String.
Optional.
PDSNAME FROM="Lib_3" TO="Lib_5"

FROM String. Mandatory.

TO String. Optional.

MINIMUM Minimum number of free partitioned dataset tracks required by the library
specified for the PDSNAME parameter. Integer. Optional.
MINIMUM FROM="5" TO="6"

FROM Integer. Mandatory.

TO Integer. Optional.

104
Control-M Utilities Guide

Parameter Description

CATEGORY Name of a Control-D report decollating mission category that must be

scheduled under Control-D when the job is scheduled under Control-M.
String. Optional.
CATEGORY FROM="*" TO="DAILY"

FROM String. Mandatory.

TO String. Optional.

105
Control-M Utilities Guide

Parameter Description

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

FROM Mandatory. Valid values:

 0 (Do not prevent)
 1 (Prevent)

TO Optional. Valid values:

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

JAN, FEB, MAR, APR, Months when the job can run. Optional. Not including a month is the same as
MAY, JUN, JUL, AUG, including that month with the value 0.
SEP, JAN FROM="0" TO="1"
OCT, NOV, DEC
JUL FROM="0" TO="1"

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

OPTION Job output (Output) handling options. Optional.

OPTION FROM="Copy" TO="Release"

106
Control-M Utilities Guide

Parameter Description

FROM Mandatory. Valid values:

 Release
 Delete
 Copy
 Move
 File
 NewDest
 ChangeClass

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

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

FROM String. Mandatory.

TO String. Optional.

FROM Limits the OUTPUT handling operation to OUTPUTs from the specified class.
Optional.
FROM FROM="1" TO="2"

FROM String. Mandatory.

TO String. Optional.

ADJUST_COND Indicates whether to ignore prerequisite conditions normally set by

predecessor jobs if the relevant predecessor jobs are not scheduled. This
parameter is relevant only for jobs in a SMART Folder. Optional. Valid values:
 0 (Do not ignore. Default.)
 1 (Ignore relevant prerequisite conditions.)
ADJUST_COND FROM="1" TO="0"

FROM String. Mandatory.

TO String. Optional.

107
Control-M Utilities Guide

Parameter Description

APPL_TYPE Type of external application (for example, SAP or Oracle) on which the
external application job runs. Mandatory for external application jobs.
APPL_TYPE FROM="SAP" TO="OracleApps"

FROM Mandatory. String. Up to 10 characters.

TO Optional. String.

APPL_VER Version of the external application (for example, SAP or Oracle) on which the
external application job runs. Mandatory for external application jobs.
APPL_VER FROM="4.5" TO="4.6"

FROM Mandatory. String. Up to 10 characters.

TO Optional. String.

APPL_FORM Predefined set of external application parameters that are displayed in the
Job Properties team. Mandatory for external application jobs.
APPL_FORM FROM="Default SAP 4.6" TO="Default SAP 4.5"

FROM Mandatory. String. Up to 30 characters.

TO Optional. String.

CM_VER Version of external Application Add-on (for example, SAP or Oracle) that is
installed in the Control-M installation. Mandatory for external application jobs.
CM_VER FROM="6.1.00" TO="6.1.01"

FROM Mandatory. String. Up to 10 characters.

TO Optional. String.

108
Control-M Utilities Guide

Parameter Description

MULTY_AGENT When selected, broadcasts job submission details to all agents in a specified
Host Group. Optional.
MULTY_AGENT FROM="N" TO="Y"

FROM Mandatory. Valid values:

 Y – Run as multi-agent job
 N – Do not run as multi-agent job. Default.

TO Optional. String.

ACTIVE_FROM (z/OS only) Start of a period of time during which the job or SMART Folder
can be ordered. Optional.
ACTIVE_FROM FROM="20070315" TO="20070601"

FROM Mandatory. Date Format: YYYYMMDD

TO Optional. String.

ACTIVE_TILL (z/OS only) End of a period of time during which the job or SMART Folder can
be ordered. Optional.
ACTIVE_TILL FROM="20070315" TO="20070601"

FROM Mandatory. Date Format: YYYYMMDD

TO Optional. String.

TIMEZONE Global time zone used to calculate the interval for time-related conditions.
Optional.
TIMEZONE FROM="EST" TO="GMT"

FROM Mandatory. String. Default: GMT

TO Optional. String.

SYSTEM_AFFINITY Identity of the system in which the job must be initiated and executed (in
JES2). Identity of the processor on which the job must execute (in JES3).
Optional. String.

FROM String. Mandatory.

SYSTEM_AFFINITY FROM="SYS3"

109
Control-M Utilities Guide

Parameter Description

TO String. Optional.
SYSTEM_AFFINITY FROM="SYS3" TO="SYS6"

REQUEST_NJE_ Host in the JES network on which the job is to execute.

HOST
FROM String. Mandatory.
REQUEST_NJE_HOST="OS5"

TO String. Optional.
REQUEST_NJE_HOST FROM="OS5" TO="OS6"

SCHEDULING_ (z/OS only) Indicates the JES2 workload management scheduling

ENVIRONMENT environment associated with the job.

FROM String. Mandatory.

SCHEDULING_ENVIRONMENT FROM="SCHD2"

TO String. Optional.
SCHEDULING_ENVIRONMENT FROM="SCHD2"
TO="SCHD3"

CREATION_USER Name of the user that created the job. String. Optional.
CREATION_USER FROM="emuser" TO="em1"

FROM String. Mandatory.

TO String. Optional.

CREATION_DATE Date that the job was created. String. Optional.

CREATION_DATE FROM="1212" TO="2012"

FROM String. Mandatory.

TO String. Optional.

CREATION_TIME Time that the job was created. String. Optional.

CREATION_TIME FROM="1230" TO="1430"

FROM String. Mandatory.

TO String. Optional.

110
Control-M Utilities Guide

Parameter Description

CHANGE_USERID Name of the user that last modified the job. String. Optional.
CHANGE_USERID FROM="emuser" TO="emacct"

FROM String. Mandatory.

TO String. Optional.

CHANGE_DATE Date that the job was last modified. String. Optional.
CHANGE_DATE FROM="1204" TO="1304"

FROM String. Mandatory.

TO String. Optional.

CHANGE_TIME Time that the job was last modified. String. Optional.
CHANGE_TIME FROM="1650" TO="1700"

FROM String. Mandatory.

TO String. Optional.

111
Control-M Utilities Guide

duplicatedefjob XML file examples

The following example describes argument files that are used with the duplicatedefjob utility:
 Copy and modify definitions XML file example (on page 112)
 Duplicate jobs based on several criteria duplicatedefjob XML file example (on page 112)

Copy and modify definitions XML file example

In the duplicatedefjob XML file, copy job processing definitions from the Tbl5NYC SMART Folder that has
FOLDER_DSN Lib1 and JOBNAME Job3. Change FOLDER_DSN to Lib1_COPY and change
JOBNAME Job3 to Job3_COPY. Store the changed definitions in the same SMART Folder.
<DUPLICATEJOB>
<FOLDER_NAME FROM="Tbl5NYC"/>
<FOLDER_DSN FROM="Lib1" TO="Lib1_COPY"/>
<JOBNAME FROM="Job3" TO="Job3_COPY"/>
</DUPLICATEJOB>

Duplicate jobs based on several criteria duplicatedefjob XML file example

Copy all cyclic jobs in the GrpAcct group whose jobname begins with "Acct". Append "_COPY" to the job
name of each copied job.
<DUPLICATEJOB>
<SUBAPPLICATION FROM="GrpAcct"/>
<CYCLIC FROM="1"/>
<JOBNAME FROM="Acct*" TO="Acct*_COPY"/>
</DUPLICATEJOB>

exportdefjob
The exportdefjob utility exports job processing definitions from a folder in the Control-M/EM database to
an output file. To export jobs using the utility, see Exporting a job from a folder using the exportdefjob
utility (on page 113).
When exportdefjob is invoked, it processes a specified file of arguments in XML format. This file contains
statements that identify existing job processing definitions. The identified definitions are exported from
the Control-M/EM database to an output file. You can modify the exported job processing definitions in
the output file and can import the modified definitions into the Control-M/EM database using either the
defjob or updatedef utility. For more information, see exportdefjob arguments file rules (on page 113).

112
Control-M Utilities Guide

Exporting a job from a folder using the exportdefjob utility

This procedure describes how to export job processing definitions from a folder in the Control-M/EM
database to an output file using the exportdefjob utility.
 To export a job using the exportdefjob utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter one of the following commands:
• emdef exportdefjob [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <args
file name> -OUT_FILE <file name>
• emdef exportdefjob [-u <user> [-p <password>] | -pf <password file>] -s
<GUI Server Name> -arg <arg file name> -out <file name>
NOTE: For Windows, you do not need to use the emdef prefix.
For details about the exportdefjob parameters and switches, see emdef general parameters (on page
44) and emdef switches (on page 45).
For more information about args file name, see exportdefjob arguments file rules (on page 113).

exportdefjob arguments file rules

The following rules apply to the exportdefjob argument file:
 More than one job can be specified in an exportdefjob file.
 The arguments file is case-sensitive.
 All parameter values must be enclosed in quotation marks (for example, JOBNAME="Job1").
 More than one PARAM parameter can be used in a TERM statement.
 The relationship between PARAM parameters in a TERM statement is AND.
For instructions about preparing this file, see XML file rules (on page 35).
The exportdefjob arguments file is checked and processed. If there are any errors, a message is displayed
specifying the lines with the errors. The exported job processing definitions are saved to the output file
whose name and location is specified in the -out <file name> parameter.
For more information on the arguments file parameters for the exportdefjob utility, see exportdefjob
arguments file parameters (on page 114) , and exportdefjob arguments file examples (on page 115).

113
Control-M Utilities Guide

exportdefjob arguments file parameters

The following table describes exportdefjob arguments file parameters:

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file.

TERMS These tags indicate the start and end of the TERMS file. Only criteria that are
located between the tags are considered to be part of the argument.

TERM The TERM tags indicate the start and the end of a group of selection criteria
used to specify a job or jobs that are to be exported. Only PARAM tags that are
located between the TERM tags are considered to be part of the TERM
argument.

REL Relationship between terms. Optional. Valid values:

 AND
 OR

114
Control-M Utilities Guide

Parameter Description

PARAM Selection criteria parameter used to determine the job definitions that are to be
exported. More than one PARAM can be specified. Mandatory.
PARAM NAME="DATACENTER" OP="E" VALUE="Center1"

NAME String. Mandatory. The parameter name of any job

processing definition parameter.
NOTE: At least one of the following SMART Folder
parameters must be included in the arguments file:
DATACENTER, OLDER_NAME, FOLDER_DSN

OP Relationship between the NAME and VALUE parameters of

the TERM. Mandatory. Valid values:
 EQ – equal
 NEQ – not equal
 LIKE – mask or pattern

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

NAME field.

CYCLIC_TYPE Determines the type of cyclic job:

 C: CYCLIC_TOLERANCE
 V: CYCLIC_INTERVAL_SEQUENCE
 S: CYCLIC_TIMES_SEQUENCE

CYCLIC_TOLERANCE Maximum delay in minutes permitted for a late submission when selecting a
specific time (for example 5 minutes).

CYCLIC_INTERVAL_SEQU A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up

ENCE to 4000 characters including commas.

CYCLIC_TIMES_SEQUEN A list of times, separated by commas (for example 0800,1330,2300), which

CE supports time synonym (for example 2730).

exportdefjob arguments file examples

The following example argument files are used with the exportdefjob utility:
 Export job definitions based on one or more criteria XML file example (on page 116)
 Export based on multiple criteria XML file example (on page 116)

115
Control-M Utilities Guide

Export job definitions based on one or more criteria XML file example
In the exportdefjob XML file, export job processing definitions that either have data center name Data1
and a jobname that begins with the letter J, or have jobname Job5 and are not cyclic jobs.
<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>

Export based on multiple criteria XML file example

In the exportdefjob XML file, export all job processing definitions from either the Data1 or Data2 data
center that have a JobName that does not begin with the letter R.
<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>

116
Control-M Utilities Guide

loopdetecttool
The loopdetecttool utility checks job processing definitions to determine if conditions are defined in a way
that would cause loops. A loop in this context means:
 A chain of jobs that will never run because the IN condition needed to start the first job in the chain
will be created only by the last job in the chain.
 Any combination of jobs, groups, and conditions between them, because it is not clear which job in
the group will run first or last, creating or deleting the relevant conditions.
To check for loops in a number of jobs, see Detecting loops in jobs using the loopdetecttool utility (on
page 117).
The loopdetecttool parameter of the emdef utility reads an argument file (in XML format) that contains
criteria that determine which job processing definitions and SMART Folder the utility should analyze. For
more information, see loopdetecttool arguments file rules (on page 118). The utility checks for definitions
whose conditions could potentially cause a loop. After the utility runs, it summarizes the problematic jobs
and conditions in an XML format file.

Detecting loops in jobs using the loopdetecttool utility

The following procedure describes how to check job processing definitions to determine if conditions are
defined in a way that would cause loops using the loopdetecttool utility,
 To detect loops using the loopdetecttool utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type the following:
emdef loopdetecttool [-U <user> [-P <password>] | -pf <password file>] -s
<GUI Server Name> -arg <input args file name> -out <output result file name>
NOTE: For Windows, you do not need to use the emdef prefix.
For more details on the loopdetecttool parameters, see loopdetecttool parameters (on page 118).

117
Control-M Utilities Guide

loopdetecttool parameters
The following table describes the loopdetecttool parameters:

Parameter Description

<user> Control-M/EM database user name

<password> Control-M/EM database user password

<password file> Flat file that contains an unencrypted user name and password on
separate lines in the following format:
user=<userName>
password=<password>

<GUI Server Control-M/EM GUI server logical name

Name>

<input args file Path and name of the arguments file that contains criteria for job and
name> SMART Folder specifications. The format for this file is described in
loopdetecttool arguments file rules (on page 118).
For information about this file, see the Arguments file rules section
below and XML file rules (on page 35).

<output result Path and name of the output file that contains the summary of
file name> problematic jobs and conditions (loops).

loopdetecttool arguments file rules

The arguments file is processed. Corresponding definitions in the Control-M/EM database are checked. A
summary that lists problematic definitions and conditions (loops) is produced in the output file whose
name and location is specified in the out file name parameter.
The following rules apply to the loopdetecttool argument file:
 The arguments file is case-sensitive.
 More than one PARAM parameter can be used in a TERM statement.
 The relationship between PARAM parameters in a TERM statement is AND.
 The default relationship between TERM statements is OR.
 All parameter values must be enclosed in quotation marks (for example, JOBNAME="Job1").
The output file is in XML format and is structured as follows:

118
Control-M Utilities Guide

 All loops are listed between ctmem:loops tags.

 For each loop found, problematic jobs and conditions are listed.
For more information on the arguments file parameters for the loopdetecttool utility, see loopdetecttool
arguments file parameters (on page 119).

loopdetecttool arguments file parameters

The following table describes arguments file parameters for the loopdetecttool utiltity:

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file. These lines must appear exactly as follows:
?xml version=’1.0’ encoding=’UTF-8’?
!DOCTYPE TERMS SYSTEM "terms.dtd"

TERMS These tags indicate the start and end of the TERMS file. Only criteria that are located between
the tags are considered part of the argument.

TERM The TERM tags indicate the start and the end of a group of selection criteria used to specify a
job or jobs that are to be analyzed. Only PARAM tags that are located between the TERM tags
are considered part of the TERM argument.

REL The relationship between the terms (optional). Valid values are:
 AND
 OR

119
Control-M Utilities Guide

Parameter Description

PARAM Selection criteria parameter used to determine the job definitions that are to be analyzed. You
can specify more than one PARAM. This parameter is required.
PARAM NAME="DATACENTER" OP="EQ" VALUE="Center1"

NAME The parameter name of any job processing definition parameter. This parameter
is required.
NOTE: At least one of the following SMART Folder parameters must be included
in the arguments file: DATACENTER, FOLDER_NAME, FOLDER_DSN

OP The relationship between the NAME and VALUE parameters of the TERM. This
relationship is required. Valid values are:
 EQ – equal
 NEQ – not equal
 NOTIN – does not contain
 LIKE – mask or pattern

VALUE The value of the parameter specified in the NAME field. This value is required.

120
Control-M Utilities Guide

loopdetecttool output
The following table lists the summary of the problematic jobs and conditions in an XML format file after
the utility runs.

Parameter Description

The beginning of the arguments file specifies the location of the .dtd file as follows:
!DOCTYPE "ctmem:loop_cond_detect" SYSTEM "path\filename.dtd"

ctmem:message Between these tags, relevant messages are listed, such as the number of loops
detected, how many jobs were found in each loop, and other remarks.

ctmem:loops Between these tags, details about all found loops are listed.

ctmem:loop Between these tags, details about each found loop is listed. Each ctmem:loop tag
contains pairs of the following tags: ctmem:job and ctmem:condition.

ctmem:job Between these tags, information about the job that is part of a potential loop is
displayed. This information includes the job’s data center, SMART Folder, group,
application, and job name. Pairs of jobs and conditions are grouped by In and Out
conditions.

ctmem:condition Between these tags, information about the conditions that were found to cause a
potential loop is displayed. This information includes the condition’s name, date, and
type. Pairs of jobs and conditions are grouped by In and Out conditions.

loopdetecttool output example

The following are examples of the loopdetecttool output:
 loopdetecttool output (on page 121)
 Analyze job definitions for loops based on one or more criteria XML file example (on page 123)
 Analyze job definitions for loops based on multiple criteria XML file example (on page 123)

loopdetecttool output
<!DOCTYPE ctmem:loop_cond_detect SYSTEM "C:\Program Files\Altova\XML Spy
Suite\Examples\LoopDetectOut.dtd">
<ctmem:loop_cond_detect>
<ctmem:message>1 Loop was detected.</ctmem:message>
<ctmem:loops>
<ctmem:message>2 Jobs were found in the loop</ctmem:message>

121
Control-M Utilities Guide

<ctmem:loop>
<ctmem:job>
<ctmem:control_m>PROD_DC1</ctmem:control_m>
<ctmem:order_folder>Daily_Prod1</ctmem:order_folder>
<ctmem:application>WinDcProd1</ctmem:application>
<ctmem:group>BackupDaily</ctmem:group>
<ctmem:job_name>Job1</ctmem:job_name>
</ctmem:job>
<ctmem:condition>
<ctmem:cond_name>Job1-Ended-OK</ctmem:cond_name>
<ctmem:cond_date>ODAT</ctmem:cond_date>
<ctmem:message>regular condition</ctmem:message>
</ctmem:condition>
<ctmem:job>
<ctmem:control_m>PROD_DC1</ctmem:control_m>
<ctmem:order_folder>Daily_Prod1</ctmem:order_folder>
<ctmem:application>WinDcProd1</ctmem:application>
<ctmem:group>BackupDaily</ctmem:group>
<ctmem:job_name>Job2</ctmem:job_name>
</ctmem:job>
<ctmem:condition>
<ctmem:cond_name>Job2-Ended-OK</ctmem:cond_name>
<ctmem:cond_date>ODAT</ctmem:cond_date>
<ctmem:message>regular condition</ctmem:message>
</ctmem:condition>
</ctmem:loop>
</ctmem:loops>
</ctmem:loop_cond_detect>

122
Control-M Utilities Guide

Analyze job definitions for loops based on one or more criteria XML file
example
In the loopdetecttool XML file, analyzes job processing definitions that either the data center name is
Data1, and a job name begins with the letter J or the job name is Job5, and the job is not cyclic.
<?xml version=’1.0’ encoding=’UTF-8’?>
<!DOCTYPE TERMS SYSTEM "terms.dtd">
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ" VALUE="Data1"/>
<PARAM NAME="JOBNAME" OP="LIKE" VALUE="J*"/>
</TERM>
<TERM>
<PARAM NAME="JOBNAME" OP="EQ" VALUE="Job5"/>
<PARAM NAME="CYCLIC" OP="EQ" VALUE="0"/>
</TERM>
</TERMS>

Analyze job definitions for loops based on multiple criteria XML file example
In the loopdetecttool XML file analyze all job processing definitions from either Data1 or Data2 data
center that has a job name 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>
</TERMS>

123
Control-M Utilities Guide

updatedef
The updatedef utility updates (modifies) specified parameter values in the following definitions in the
Control-M/EM database:
 Job processing definitions
 Folder definitions
 SMART Folder definitions
 Sub-folder definitions
NOTE: updatedef modifies the characteristics of existing job processing definitions. duplicatedefjob
creates new job processing definitions based on existing job processing definitions in the "from" data
center and folders.
To update parameter values using the updatedef utility, see Updating parameter values using the
updatedef utility (on page 124).
The selected jobs, folders, SMART Folders and Sub-folders are modified according to specifications in the
updatedef arguments file. For more information, see updatedef XML file rules (on page 125).
The updatedef utility does not create new jobs or folders.

Updating parameter values using the updatedef utility

This procedure describes how to update specified parameter values in the Control-M/EM database using
the updatedef utility.
 To update parameter values:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter either of the following commands:
• emdef updatedef [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <XML
file name> [/a]
• emdef updatedef [-u <user> [-p <password>] | -pf <password file>] -s <GUI
Server Name> -arg <XML file name> [/a]
NOTE: For Windows you do not need to use the emdef prefix.
For details about the updatedef parameters and switches, see emdef general parameters (on page
44) and emdef switches (on page 45).
For more information about the XML file name, see updatedef XML file rules (on page 125).

124
Control-M Utilities Guide

updatedef XML file rules

The following rules apply to the updatedef arguments file:
 Only one block of criteria can be specified for updating in each arguments file. This criteria block can
update many jobs or folders.
 Text in the arguments file is case-sensitive.
 All parameter values must be enclosed in quotation marks (for example, JOBNAME="Job1").
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 39).
For instructions about preparing this file, see XML file rules (on page 35).
Most parameters of the job, folder, SMART Folder or Sub-folder definitions are optional. However:
 If you specify a parameter, the FROM subparameter is mandatory and the TO subparameter is
optional.
 When a FROM value is specified without a TO value, the FROM value is used as a filter criterion.
 When a TO value is included, the new value parameter is set.
 NOTE: SMART Folder parameters are usually modified using the SMART Folder criteria described in
updatedef XML file parameters for SMART folders (on page 147). However, you cannot use these
criteria to change the name of a SMART Folder.
 NOTE: The folder name parameter of a job processing definition cannot be modified using the job
definition criteria described in updatedef XML file parameters for jobs (on page 128). However, you
can use the updatedef utility to change the name of a SMART Folder or folder by using the criteria
for folders (described in updatedef XML file parameters for folders (on page 126) ) and specifying a
new value for the FOLDER_NAME parameter.
Three sets of parameters can be supplied in an arguments file – one each for folders, SMART Folders, and
jobs. Each set of parameters is described in:
 updatedef XML file parameters for folders (on page 126)
 updatedef XML file parameters for SMART folders (on page 147)
 updatedef XML file parameters for jobs (on page 128)
 loopdetecttool output example (on page 121).

125
Control-M Utilities Guide

updatedef XML file parameters for folders

The following table lists the updatedef XML input file parameters for folders:

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being
used, and the location of the .dtd file.

UPDATE These tags indicate the start and end of the UPDATE argument. Only criteria
located between the tags are considered to be part of the argument.
Mandatory.

FOLDER These tags indicate the start and end of the folder specification. Criteria
identifying the folders to be modified and indicating the types of
modifications to be made are located between these tags. Optional.

FOLDER_NAME Name of the folder to which the job belongs. Optional.

EXAMPLE: FOLDER_NAME FROM="Tbl5NYC" TO="Tbl_new"

FROM String. Mandatory

TO String. Optional

FOLDER_DSN (z/OS only) Name of the library that contains the (scheduling) folder.
Optional.
ABLE_DSN FROM="Lib1" TO="Lib2"

FROM String. Mandatory

To String. Optional

DATACENTER Name of the Control-M installation to which the job belongs. Optional.
NOTE: A TO parameter cannot be specified for this parameter.
EXAMPLE: DATACENTER FROM="CTMNYC"

FROM String. Mandatory

TO String. Optional

126
Control-M Utilities Guide

Parameter Description

CYCLIC_TYPE Determines the type of cyclic job:

 Interval
 IntervalSequence
 SpecificTimes

CYCLIC_ Maximum delay in minutes permitted for a late submission when selecting a
TOLERANCE specific time (for example 5 minutes).

CYCLIC_INTERVAL_ A list of time intervals, separated by commas, (for example +30M,+2H,+1D)

SEQUENCE up to 4000 characters including commas.

CYCLIC_TIMES_ A list of times, separated by commas (for example 0800,1330,2300), which

SEQUENCE supports time synonym (for example 2730).

127
Control-M Utilities Guide

updatedef XML file parameters for jobs

The following table lists the arguments file parameters for jobs:

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file.

UPDATE These tags indicate the start and end of the UPDATE argument. Only criteria that
are located between the tags are considered to be part of the argument.
Mandatory.

JOB These tags indicate the start and end of each job specification. Criteria identifying
the jobs to be modified and indicating the types of modifications to be made are
located between these tags. Optional.

FOLDER_NAME Name of the folder to which the job belongs. Mandatory.

NOTE: This parameter cannot be modified.
EXAMPLE: FOLDER_NAME FROM="Tbl5NYC"

FROM String. Mandatory.

FOLDER_DSN (z/OS only) Name of the library that contains the (scheduling) folder. Mandatory.
NOTE: This parameter cannot be modified.
EXAMPLE: FOLDER_DSN FROM="Lib1"

FROM String. Mandatory.

DATACENTER Name of the Control-M installation to which the job belongs. Mandatory.
NOTE: This parameter cannot be modified.
EXAMPLE: DATACENTER FROM="CTMNYC"

FROM String. Mandatory.

FOLDER_ORDER_ Optional.
METHOD
NOTE: This parameter cannot be modified.
EXAMPLE: FOLDER_ORDER_ METHOD FROM="Job3"

FROM String. Mandatory.

JOBNAME Name of the job processing definition. Optional.

EXAMPLE: JOBNAME FROM="Job3" TO="Job3_COPY"

128
Control-M Utilities Guide

Parameter Description

FROM Mandatory.

TO Optional.

FILE_NAME Name of the file that contains the job script. Optional.
EXAMPLE: FILE_NAME FROM="File3" TO="File7"

FROM Mandatory.

TO Optional.

SUB_APPLICATION Name of the group to which the job belongs. Optional.

EXAMPLE: GROUP FROM="Grp_HR"

FROM Mandatory.

APPLICATION Name of the application to which the job’s group belongs. Optional.
EXAMPLE: APPLICATION FROM="App3" TO="App1"

FROM String. Mandatory.

TO String Optional.

129
Control-M Utilities Guide

Parameter Description

TASKTYPE Type of the job (task) to be performed by Control-M. Optional.

EXAMPLE: TASKTYPE FROM="Detached" TO="Dummy"

FROM Mandatory.
Valid values:
 Job
 Detached
 Command
 Dummy
 External
(z/OS only) Valid values:
 Job
 Started_Task
NOTE: In Control-M/EM versions earlier than 6.1.00, the TASKTYPE
format contained:
 for z/OS, emergency and cyclic information
 for other operating systems, critical and cyclic information
Control-M/EM version 6.2.01 and higher can run jobs with the old
TASKTYPE format. However, BMC recommends that, to specify this
type of information when creating new job processing definitions, you
use CRITICAL and CYCLIC parameters.
[for z/OS]
BMC recommends that, to specify this type of information when
creating new job processing definitions, you use CRITICAL (a value of
"1" indicates that the job is an Emergency job) and CYCLIC parameters.
NOTE: Critical path jobs are indicated by coding an * as the first
character in the Priority parameter. There is no connection between
critical path jobs and the Critical parameter.

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

(z/OS only) Valid values: Same as z/OS FROM values.

130
Control-M Utilities Guide

Parameter Description

CREATED_BY Control-M/EM user who defined the job. This parameter is used by the
Control-M/Server security mechanism. String. Optional.
NOTE: This argument is used by the Control-M/Server security mechanism and,
under certain circumstances, cannot be modified. For more information, see the
Security chapter and the description of the AuthorSecurity system parameter in
GUI Server parameters.
EXAMPLE: CREATED_BY FROM="emuser" TO="em5"

FROM String. Mandatory.

TO String. Optional.

FILE_PATH Name of the library/directory in which the job script resides. String. Optional.
EXAMPLE: FILE_PATH FROM="File1" TO="File4"

FROM String. Mandatory.

TO String. Optional.

CMDLINE Command string supplied when the job Task Type is Command. Optional.
EXAMPLE: CMDLINE FROM="C:\Format" TO="C\:CD Emnt"

FROM String. Mandatory.

TO String. Optional.

HOSTID Host name of an agent computer or host group to which the job is submitted.
Optional.
EXAMPLE: HOSTID FROM="Com3" TO="Acct4"

FROM String. Mandatory.

TO Host name of the agent computer on which the job copy is running
Optional.

RUN_AS Owner (user ID) associated with the job. This parameter is used by the
Control-M/Server security mechanism. Optional.
EXAMPLE: OWNER FROM="emuser" TO="emhr"

FROM String. Mandatory.

TO String. Optional.

131
Control-M Utilities Guide

Parameter Description

MAXRERUN Maximum number of reruns that can be performed for the job. Optional.
EXAMPLE: MAXRERUN FROM="1" TO="3"

FROM String. Mandatory.

TO String. Optional.

TIMEFROM Earliest time for submitting the job. Optional.

EXAMPLE: TIMEFROM FROM="1430" TO="1450"

FROM String. Mandatory.

TO String. Optional.

TIMETO Latest time for submitting the job. Optional.

EXAMPLE: TIMETO FROM="1600" TO="1620"

FROM String. Mandatory.

TO String. Optional.

DUE_OUT Time that the job is expected to finish. Optional.

EXAMPLE: DUE_OUT FROM="1500" TO="1530"

FROM String. Mandatory.

TO String. Optional.

PRIORITY Indicates Control-M job priority. Optional.

EXAMPLE: PRIORITY FROM="AA" TO="1A"

FROM String. Mandatory.

TO String. Optional.

132
Control-M Utilities Guide

Parameter Description

CRITICAL Indicates whether the job is a critical-path job in Control-M. Optional.

EXAMPLE: CRITICAL FROM="0" TO="1"

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

CYCLIC Indicates whether the job is cyclic (to be run at regular intervals). Optional.
EXAMPLE: CYCLIC FROM="0" TO="1"

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

CONFIRM Indicates that the job must be manually confirmed by the Control-M/EM user
before it runs. Optional.
EXAMPLE: CONFIRM FROM="0" TO="1"

FROM Mandatory. Valid values:

 0 (Default)
 1

TO Optional. Valid values:

 0 (Default)
 1

AUTOARCH Determines whether SYSDATA is to be archived. Optional.

EXAMPLE: AUTOARCH FROM=0" TO="1"

133
Control-M Utilities Guide

Parameter Description

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

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

FROM String. Mandatory.

TO String. Optional.

OVERRIDE_PATH Name of an alternate job script library/directory. String. Optional.

EXAMPLE: OVERRIDE PATH FROM="lib3" TO="lib4"

FROM String. Mandatory.

TO String. Optional.

MAXWAIT Number of extra days (after the original scheduling date) that the job is allowed to
remain in the Active Jobs database awaiting execution. Integer. Optional.
EXAMPLE: MAXWAIT FROM="4" TO="3"

FROM Integer. Mandatory.

TO Integer. Optional.

DESCRIPTION Free text description of the job. String. Optional.

EXAMPLE: DESCRIPTION FROM="data backup from 120399" TO="data
backup from 021400"

FROM String. Mandatory.

TO String. Optional.

134
Control-M Utilities Guide

Parameter Description

DOCMEM Name of the file containing job documentation. String. Optional.

EXAMPLE: DOCMEM FROM="mem4" TO="Mem67"

FROM String. Mandatory.

TO String. Optional.

DOCLIB Name of a library or directory containing the job documentation file. String.
Optional.
EXAMPLE: DOCLIB FROM="AcctFiles" TO="HRFiles"

FROM String. Mandatory.

TO String. Optional.

DAYS Days of the month on which to order the job. String. Optional.
EXAMPLE: DAYS FROM="ALL" TO="159"

FROM String. Mandatory.

TO String. Optional.

DAYS_AND_OR Indicates the relationship between specified Days values and Weekdays values.
Optional.
EXAMPLE: DAYS_AND_OR FROM="AND" TO="OR"

FROM String. Mandatory.

TO String. Optional.

WEEKDAYS Days of the week on which to order the job. String. Optional.
EXAMPLE: WEEKDAYS FROM="1,2,4" TO="ALL"

FROM String. Mandatory.

TO String. Optional.

135
Control-M Utilities Guide

Parameter Description

DATE Specific dates on which to order the job. String. mmdd format. Optional.
EXAMPLE: DATE FROM="0312" TO="0319"

FROM String. Mandatory. Dates are written in mmdd format. There is no

delimiter between dates. For example, January 10 is written in this
manner: DATE="0110"

TO String. Optional. Dates are written in mmdd format. There is no

delimiter between dates. For example, January 10 is written in this
manner: DATE="0110"

DAYSCAL Name of a user-defined calendar used to specify a set of days. String. Optional.
EXAMPLE: DAYSCAL FROM="shipping" TO="receiving"

FROM String. Mandatory.

TO String. Optional.

WEEKSCAL Name of a calendar to be used to validate specified weekdays on which to order

the job. String. Optional.
EXAMPLE: WEEKSCAL FROM="w5" TO="w6"

FROM String. Mandatory.

TO String. Optional.

CONFCAL Specifies a calendar that is used to validate all specified days and dates on which
to schedule the job. String. Optional.
EXAMPLE: CONFCAL FROM="cal99" TO="cal00"

FROM String. Mandatory.

TO String. Optional.

136
Control-M Utilities Guide

Parameter Description

RETRO Indicates whether the job is scheduled for possible execution after its original
scheduling date (odate) has passed. Optional.
EXAMPLE: RETRO FROM="0" TO="1"

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

SHIFT Describes how to shift the scheduling date of the job. Optional.
EXAMPLE: SHIFT FROM="PREVDAY" TO="NEXTDAY"

FROM Mandatory. Valid values:

 IGNOREJOB
 PREVDAY
 NEXTDAY
 NOCONFCAL

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

SHIFTNUM Number of days to shift the scheduling date of the job. Optional.
EXAMPLE: SHIFTNUM FROM="-10" TO="5"

FROM String. Mandatory.

TO String. Optional.

MAXDAYS Maximum number of days to retains the SYSDATA archive dataset for jobs that
ended NOTOK. Subparameter of AUTOARCH. String. Optional.
EXAMPLE: MAXDAYS FROM="07" TO="14"

FROM String. Mandatory.

TO String. Optional.

137
Control-M Utilities Guide

Parameter Description

MAXRUNS Maximum number of job runs to retains the SYSDATA archive dataset for jobs that
ended NOTOK. Subparameter of AUTOARCH. String. Optional.
EXAMPLE: MAXRUNS FROM="100" TO="250"

FROM String. Mandatory.

TO String. Optional.

RERUNMEM Name of the JCL member to use when the job is automatically rerun. String. 1 - 8
characters. Optional.
EXAMPLE: RERUNMEM FROM="Mem45" TO="Mem7"

FROM String. Mandatory.

TO String. Optional.

RETEN_DAYS (z/OS only) Number of days to retain the job in the History Jobs file. String.
Optional.
EXAMPLE: RETEN_DAYS FROM="5" TO="7"

FROM String. Mandatory.

TO String. Optional.

RETEN_GEN (z/OS only) Maximum number of generations of the job to keep in the History Jobs
file. String. Optional.
EXAMPLE: RETEN_GEN FROM="3" TO="4"

FROM String. Mandatory.

TO String. Optional.

TASK_CLASS Optional.
EXAMPLE: TASK_CLASS FROM="Distribution" TO="Decollation"

FROM String. Mandatory.

TO String. Optional.

138
Control-M Utilities Guide

Parameter Description

PREV_DAY Optional.
EXAMPLE: PREV_DAY FROM="N" TO="Y"

FROM Mandatory. Valid values:

 Y
 N

TO Optional. Valid values:

 Y
 N

IND_CYCLIC Indicates whether the interval between further runs of a cyclic job is counted from
the start or the end of the previous job run. Optional.
EXAMPLE: IND_CYCLIC FROM="Y" TO="N"

FROM Mandatory. Valid values:

 START
 END

TO Optional. Valid values:

 START
 END

RULE_BASED_ Relationship (AND|OR) between the specified Rule-Based Calendar and the job’s
CALENDAR own basic scheduling criteria. Optional.
_RELATIONSHIP EXAMPLE: RULE_BASED_CALENDAR_RELATIONSHIP FROM="AND"
TO="OR"

FROM Mandatory. Valid values:

 AND
 OR

TO Optional. Valid values:

 AND
 OR

139
Control-M Utilities Guide

Parameter Description

TAG_RELATIONSHIP Relationship (AND|OR) between the specified Schedule Tag criteria and the job’s
own basic scheduling criteria. This parameter is relevant only for jobs in a SMART
Folder. Optional. This parameter is for backward compatibility.
EXAMPLE: TAG_RELATIONSHIP FROM="AND" TO="OR"

FROM Mandatory. Valid values:

 AND
 OR

TO Optional. Valid values:

 AND
 OR

SYSDB Determines whether one or multiple data sets are used to catalogue sysdata.
Optional.
EXAMPLE: SYSDB FROM="1" TO="0"

FROM Mandatory. Valid values:

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

TO Optional. Valid values:

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

PDSNAME Name of a partitioned dataset (PDS) to be checked for free space. String. Optional.
EXAMPLE: PDSNAME FROM="Lib_3" TO="Lib_5"

FROM String. Mandatory.

TO String. Optional.

MINIMUM Minimum number of free partitioned dataset tracks required by the library specified
for the PDSNAME parameter. Integer. Optional.
MINIMUM FROM="5" TO="6"

FROM Integer. Mandatory.

TO Integer. Optional.

140
Control-M Utilities Guide

Parameter Description

CATEGORY Name of a Control-D report decollating mission category that must be scheduled
under Control-D when the job is scheduled under Control-M. String. Optional.
EXAMPLE: CATEGORY FROM="*" TO="DAILY"

FROM String. Mandatory.

TO String. Optional.

141
Control-M Utilities Guide

Parameter Description

PREVENTNC2 (z/OS only) Performs dataset cleanup before the original job run. Optional.
EXAMPLE: PREVENTNC2 FROM="1" TO="0"

FROM Mandatory. Valid values:

 0 (Default)
 1

TO Optional. Valid values:

 0 (Default)
 1

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

TO Optional. Valid values:

 0 (Default)
 1

OPTION Job output (output) handling options. Optional.

EXAMPLE: OPTION FROM="Copy" TO="Release"

FROM Mandatory. Valid values:

 Release
 Delete
 Copy
 Move
 File
 NewDest
 ChangeClass

TO Optional. Valid values: Same as mandatory FROM.

142
Control-M Utilities Guide

Parameter Description

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

FROM String. Mandatory.

TO String. Optional.

FROM Limits the OUTPUT handling operation to OUTPUTs from the specified class.
Optional.
EXAMPLE: FROM FROM="1" TO="2"

FROM String. Mandatory.

TO String. Optional.

ADJUST_COND Indicates whether to ignore prerequisite conditions normally set by predecessor

jobs if the relevant predecessor jobs are not scheduled. This parameter is relevant
only for jobs in a SMART Folder. Optional.
Valid values:
 0 (Do not ignore. Default.)
 1 (Ignore relevant prerequisite conditions)
EXAMPLE: ADJUST_COND FROM="1" TO="0"

FROM String. Mandatory.

TO String. Optional.

APPL_TYPE Type of external application (for example, SAP or Oracle) on which the external
application job runs. Mandatory for external application jobs.
EXAMPLE: APPL_TYPE FROM="SAP" TO="OracleApps"

FROM Mandatory. String. Up to 10 characters.

TO Optional. String.

143
Control-M Utilities Guide

Parameter Description

APPL_VER Version of the external application (for example, SAP or Oracle) on which the
external application job runs. Mandatory for external application jobs.
EXAMPLE: APPL_VER FROM="4.5" TO="4.6"

FROM Mandatory. String. Up to 10 characters.

TO Optional. String.

APPL_FORM Predefined set of external application parameters that are displayed in the Job
Properties team. Mandatory for external application jobs.
EXAMPLE: APPL_FORM FROM="Default SAP 4.6" TO="Default SAP
4.5"

FROM Mandatory. String. Up to 30 characters.

TO Optional. String.

CM_VER Version of external Application Add-on(for example, SAP or Oracle) that is installed
in the Control-M installation. Mandatory for external application jobs.
EXAMPLE: CM_VER FROM="6.1.00" TO="6.1.01"

FROM Mandatory. String. Up to 10 characters.

TO Optional. String.

MULTY_AGENT When selected, broadcasts job submission details to all agents in a specified Host
Group. Optional.
EXAMPLE: MULTY_AGENT FROM="N" TO="Y"

FROM Mandatory. Valid values:

 Y – run as multi-agent job.
 N – do not run as multi-agent job. Default.

TO Optional. String.

ACTIVE_FROM (z/OS only) Start of a period of time during which the job or SMART Folder can be
ordered. Optional.
EXAMPLE: ACTIVE_FROM FROM="20080315" TO="20080601"

FROM Mandatory. Date Format: YYYYMMDD

TO Optional. String.

144
Control-M Utilities Guide

Parameter Description

ACTIVE_TILL (z/OS only) End of a period of time during which the job or SMART Folder can be
ordered. Optional.
EXAMPLE: ACTIVE_TILL FROM="20080315" TO="20080601"

FROM Mandatory. Date Format: YYYYMMDD

TO Optional. String.

TIMEZONE Global time zone used to calculate the interval for time-related conditions.
Optional.
EXAMPLE: TIMEZONE FROM="EST" TO="GMT"

FROM Mandatory. String.

Default: GMT

TO Optional. String.

CREATION_USER Name of the user that created the job. Optional.

EXAMPLE: CREATION_USER FROM="emuser" TO="em1"

FROM String. Mandatory.

TO String. Optional.

CREATION_DATE Date that the job was created. Optional.

EXAMPLE: CREATION_DATE FROM="1212" TO="2012"

FROM String. Mandatory.

TO String. Optional.

CREATION_TIME Time that the job was created. Optional.

EXAMPLE: CREATION_TIME FROM="1230" TO="1430"

FROM String. Mandatory.

TO String. Optional.

145
Control-M Utilities Guide

Parameter Description

CHANGE_USERID Name of the user that last modified the job. Optional.
EXAMPLE: CHANGE_USERID FROM="emuser" TO="emacct"

FROM String. Mandatory.

TO String. Optional.

CHANGE_DATE Date that the job was last modified. Optional.

EXAMPLE: CHANGE_DATE FROM="1204" TO="1304"

FROM String. Mandatory.

TO String. Optional.

CHANGE_TIME Time that the job was last modified. Optional.

EXAMPLE: CHANGE_TIME FROM="1650" TO="1700"

FROM String. Mandatory.

TO String. Optional.

146
Control-M Utilities Guide

updatedef XML file parameters for SMART folders

The following table lists the arguments file parameters for SMART folders:

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file.

UPDATE These tags indicate the start and end of the UPDATE argument. Only criteria located
between the tags are considered to be part of the argument. Mandatory.

SMART_FOLDER These tags indicate the start and end of the SMART Folder specification. Criteria
identifying the SMART Folders to be modified and indicating the types of modifications
to be made are located between these tags. Optional.

FOLDER_NAME Name of the SMART Folder.

NOTE:
 This parameter cannot be modified.
 At least one of the following folder parameters must be included in the input file:
DATACENTER, FOLDER_NAME, FOLDER_DSN
EXAMPLE: FOLDER_NAME FROM="Tbl42"

FROM String. Mandatory

DATACENTER Name of the Control-M installation to which the job belongs. Optional.
NOTE:
A TO subparameter cannot be specified for this parameter.
 At least one of the following folder parameters must be included in the input file:
DATACENTER, FOLDER_NAME, FOLDER_DSN
EXAMPLE: DATACENTER FROM="CTMNYC"

FROM String. Mandatory

FOLDER_DSN (z/OS only) Name of the library that contains the SMART Folder. Optional.
NOTE:
 A TO subparameter cannot be specified for this parameter.
 At least one of the following folder parameters must be included in the input file:
DATACENTER, FOLDER_NAME, FOLDER_DSN
EXAMPLE: FOLDER_DSN FROM="CTMNYC"

FROM String. Mandatory

147
Control-M Utilities Guide

Parameter Description

FOLDER_ORDER_ Optional.
METHOD
NOTE: A TO subparameter cannot be specified for this parameter.
EXAMPLE: FOLDER_ORDER_ METHOD FROM="CTMNYC"

FROM String. Mandatory

SUB_APPLICATION Name of the group to which the SMART Folder belongs. Used as a descriptive name
for related folders. Optional.
EXAMPLE: GROUP FROM="Grp_HR" TO="Grp_ACCT"

FROM String. Mandatory.

TO String. Optional.

USED_BY Optional.
EXAMPLE: USED_BY FROM="fff" TO="ffg"

FROM String. Mandatory.

TO String. Optional.

USED_BY_CODE Optional.
EXAMPLE: USED_BY_CODE FROM="C***" TO="D***"

FROM String. Mandatory.

TO String. Optional.

MODIFIED Optional.
EXAMPLE: MODIFIED FROM="1101" TO="1102"

FROM String. Mandatory.

TO String. Optional.

LAST_UPLOAD Date of the last folder upload. String. Optional.

EXAMPLE: LAST_UPLOAD FROM="1101" TO="1102"

FROM String. Mandatory.

TO String. Optional.

148
Control-M Utilities Guide

Parameter Description

CHECKSUM Optional.
EXAMPLE: CHECKSUM FROM="Y" TO="N"

FROM String. Mandatory.

TO String. Optional.

FOLDER_ID Name of the folder to which the job belongs. Optional.

EXAMPLE: FOLDER_ID FROM="Tbl001" TO="Tbl002"

FROM String. Mandatory.

TO String. Optional.

REAL_FOLDERID Optional.
EXAMPLE: REAL_FOLDERID FROM="43556" TO="43557"

FROM String. Mandatory.

TO String. Optional.

JOBNAME Name of the job processing definition. Optional.

EXAMPLE: JOBNAME FROM="Job3"

FROM String. Mandatory.

TO String. Optional.

FILE_NAME Name of the file that contains the job script. Optional.
EXAMPLE: FILE_NAME FROM="File3" TO="File7"

FROM String. Mandatory.

TO String. Optional.

APPLICATION Name of the application to which the job’s group belongs. Used as a descriptive name
for related jobs. Optional.
EXAMPLE: APPLICATION FROM="App3""

FROM String. Mandatory.

TO String. Optional.

149
Control-M Utilities Guide

Parameter Description

RUN_AS Owner (user ID) associated with the job. This parameter is used by the
Control-M/Server security mechanism. Optional.
EXAMPLE: OWNER FROM="emuser" TO="emhr"

FROM String. Mandatory.

TO String. Optional.

ADJUST_COND Indicates whether to ignore prerequisite conditions normally set by predecessor jobs if
the relevant predecessor jobs are not scheduled. Optional. Valid values:
 0 (Do not ignore. Default.)
 1 (Ignore relevant prerequisite conditions.)
EXAMPLE: ADJUST_COND FROM="1" TO="2"

FROM String. Mandatory.

TO String. Optional.

CONFIRM Indicates whether the job must be manually confirmed by the Control-M/EM user
before it runs. Optional.
EXAMPLE: CONFIRM FROM="0" TO="1"

FROM Mandatory. Valid values:

 0 (Default)
 1

TO Optional. Valid values:

 0 (Default)
 1

PRIORITY Indicates Control-M job priority. Optional. Two-character alphanumeric from 00 to ZZ.
EXAMPLE: PRIORITY FROM="AA" TO="BB"

FROM String. Mandatory.

TO String. Optional.

150
Control-M Utilities Guide

Parameter Description

TIMEFROM Indicates the earliest time for submitting the SMART Folder. Format: hhmm. Optional.
EXAMPLE: TIMEFROM FROM="1430" TO="1450"

FROM String. Mandatory.

TO String. Optional.

TIMETO Indicates the latest time for submitting the SMART Folder. Format: hhmm. Optional.
EXAMPLE: TIMETO FROM="1430" TO="1450"

FROM String. Mandatory.

TO String. Optional.

DUE_OUT Time that the job is expected to finish. Optional.

EXAMPLE: DUE_OUT FROM="1500" TO="1750"

FROM String. Mandatory.

TO String. Optional.

DOCMEM Name of the file containing job documentation. String. Optional.

EXAMPLE: DOCMEM FROM="mem4" TO="Mem67"

FROM String. Mandatory.

TO String. Optional.

DOCLIB Name of a library or directory containing the job documentation file. String. Optional.
EXAMPLE: DOCLIB FROM="AcctFiles" TO="HRFiles"

FROM String. Mandatory.

TO String. Optional.

DESCRIPTION Free text description of the job. String. Optional.

EXAMPLE: DESCRIPTION FROM="backup jobs from 120399" TO="backup
jobs from 021400"

FROM String. Mandatory.

TO String. Optional.

151
Control-M Utilities Guide

Parameter Description

CREATED_BY Control-M/EM user who defined the job. String. Optional. Example:
EXAMPLE: CREATED_BY FROM="emuser" TO="emadmin"
NOTE: The New Day Procedure compares the Author and Owner for each job to
check if the job’s user has authorization to submit the job. Control-M/EM security
levels determine who can edit the Author value (any user or administrators only). For
more information, see the Security chapter and the description of the
AuthorSecurity system parameter in GUI Server parameters.

FROM String. Mandatory.

TO String. Optional.

CREATION_USER Name of the user that created the job. String. Optional.
EXAMPLE: CREATION_USER FROM="emuser" TO="em1"

FROM String. Mandatory.

TO String. Optional.

CREATION_DATE Date that the SMART Folder was created. String. Format: ddmm. Optional.
EXAMPLE: CREATION_DATE FROM="1212" TO="2012"

FROM String. Mandatory.

TO String. Optional.

CREATION_TIME Time the SMART Folder was created. String. Format: hhmm. Optional.
EXAMPLE: CREATION_TIME FROM="1230" TO="1430"

FROM String. Mandatory.

TO String. Optional.

CHANGE_USERID Name of the user that last modified the SMART Folder. String. Optional.
EXAMPLE: CHANGE_USERID FROM="emuser" TO="emadmin"

FROM String. Mandatory.

TO String. Optional.

152
Control-M Utilities Guide

updatedef XML file examples

The following example argument files are used with the updatedef utility:
 Modify SMART_FOLDER parameter XML file example (on page 153)
 Modify Folder Name parameter XML file example (on page 153)
 Modify the Job name of a job XML file example (on page 153)

Modify SMART_FOLDER parameter XML file example

From the updatedef XML file, in the TEST data center, the SMART Folder name FOLDER UNIXJobs is
changed to FOLDER TandemJobs.
<UPDATE>
<SMART_FOLDER>
<DATACENTER FROM="TEST"/>
<FOLDER FROM="UNIXJobs" TO="TandemJobs"/>
</SMART_FOLDER>
</UPDATE>

Modify Folder Name parameter XML file example

From the updatedef XML file, in the TEST data center, for jobs with FOLDER_ID 12202, the folder
name is changed from Tbl_1 to Tbl_2.
<UPDATE>
<FOLDER>
<DATACENTER FROM="TEST"/>
<FOLDER_ID FROM="12202"/>
<FOLDER_NAME FROM="Tbl_1" TO="Tbl_2"/>
</FOLDER>
</UPDATE>

Modify the Job name of a job XML file example

In the updatedef XML file:
<UPDATE>
<JOB>
<FOLDER_NAME FROM="SGMPM1"/>
<!-- <FOLDER_DSN FROM=""/> -->
<DATACENTER FROM="snow"/>
<JOBNAME FROM="cnn*" TO="bbc*"/>

153
Control-M Utilities Guide

<!-- <FILE_NAME FROM="Job2"/>-->

<!-- <SUBAPPLICATION FROM=""/> -->
<!-- <APPLICATION FROM=""/> -->
<!-- <TASKTYPE FROM=""/> -->
<!-- <CREATED_BY FROM=""/> -->
<!-- <MEMLIB FROM=""/> -->
<!-- <CMDLINE FROM="*end" TO="THE END *"/>-->
<!-- <HOSTID FROM=""/> -->
<!-- <RUN_AS FROM=""/> -->
<!-- <MAXRERUN FROM=""/> -->
<!-- <TIMEFROM FROM=""/> -->
<!-- <TIMETO FROM=""/> -->
<!-- <DUE_OUT FROM=""/> -->
<!-- <PRIORITY FROM=""/> -->
<!-- <CRITICAL FROM=""/> -->
<!-- <CYCLIC FROM=""/> -->
<!-- <CONFIRM FROM=""/> -->
<!-- <AUTOARCH FROM=""/> -->
<!-- <INTERVAL FROM=""/> -->
<!-- <OVERRIDE_PATH FROM=""/> -->
<!-- <MAXWAIT FROM=""/> -->
<!-- <DESCRIPTION FROM=""/> -->
<!-- <DOCMEM FROM="docmem"/> -->
<!-- <DOCLIB FROM="doclib"/>-->
<!-- <DAYS FROM=""/> -->
<!-- <DAYS_AND_OR FROM=""/> -->
<!-- <WEEKDAYS FROM=""/> -->
<!-- <DATE FROM=""/> -->
<!-- <DAYSCAL FROM=""/> -->
<!-- <WEEKSCAL FROM=""/> -->
<!-- <CONFCAL FROM=""/> -->
<!-- <RETRO FROM=""/> -->
<!-- <SHIFT FROM=""/> -->
<!-- <SHIFTNUM FROM=""/> -->
<!-- <MAXDAYS FROM=""/> -->

154
Control-M Utilities Guide

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

<!-- <RERUNMEM FROM=""/> -->
<!-- <RETEN_DAYS FROM=""/> -->
<!-- <RETEN_GEN FROM=""/> -->
<!-- <TASK_CLASS FROM=""/> -->
<!-- <PREV_DAY FROM=""/> -->
<!-- <IND_CYCLIC FROM=""/> -->
<!-- <RULE_BASED_CALENDAR_RELATIONSHIP FROM=""/> -->
<!-- <SYSDB FROM=""/> -->
<!-- <PDSNAME FROM=""/> -->
<!-- <MINIMUM FROM=""/> -->
<!-- <CATEGORY FROM=""/> -->
<!-- <PREVENTNCT2 FROM=""/> -->
<!-- <JAN FROM=""/> -->
<!-- <FEB FROM=""/> -->
<!-- <MAR FROM=""/> -->
<!-- <APR FROM=""/> -->
<!-- <MAY FROM=""/> -->
<!-- <JUN FROM=""/> -->
<!-- <JUL FROM=""/> -->
<!-- <AUG FROM=""/> -->
<!-- <SEP FROM=""/> -->
<!-- <OCT FROM=""/> -->
<!-- <NOV FROM=""/> -->
<!-- <DEC FROM=""/> -->
<!-- <OPTION FROM=""/> -->
<!-- <PAR FROM=""/> -->
<!-- <FROM FROM=""/> -->
<!-- <ADJUST_COND FROM=""/> -->
<!-- <JOBS_IN_GROUP FROM=""/> -->
<!-- <LARGE_SIZE FROM=""/> -->
<!-- <CREATION_USER FROM=""/> -->
<!-- <CREATION_DATE FROM=""/> -->
<!-- <CREATION_TIME FROM=""/> -->
<!-- <CHANGE_USERID FROM=""/> -->

155
Control-M Utilities Guide

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

<!-- <CHANGE_TIME FROM=""/> -->
<!-- <JOB_RELEASE FROM=""/> -->
<!-- <JOB_VERSION FROM=""/> -->
<!-- <FOLDER_ORDER_ METHOD FROM=""/> -->
<!-- <SCHEDULING_ENVIRONMENT FROM=""/> -->
<!-- <SYSTEM_AFFINITY FROM=""/> -->
<!-- <REQUEST_NJE_HOST FROM=""/> -->
<!-- <APPL_TYPE FROM=""/> -->
<!-- <APPL_VER FROM=""/> -->
<!-- <APPL_FORM FROM=""/> -->
<!-- <CM_VER FROM=""/> -->
<!-- <MULTY_AGENT FROM=""/> -->
<!-- <ACTIVE_FROM FROM=""/> -->
<!-- <ACTIVE_TILL FROM=""/> -->
<!-- <TIMEZONE FROM=""/> -->
</JOB>
</UPDATE>

156
Control-M Utilities Guide

exportsitestandards
The exportsitestandards utility enables you to do the following:
Note: It is recommended that you back up your Workload Change Manager entities before performing
any changes, by running the util (on page 527) utility (-wcm type).
 Export site standards, and perform a mass update on multiple Site Standards, where you can
add/update a Site Standard rule in a large number of existing Site Standards, and import them into
Control-M. For more information on importing site standards, see importsitestandards (on page 160).
 Export one or multiple Site Standards from one environment to another, between two environments
on different Control-M/Enterprise Managers.
For more information on importing/exporting site standards, see Exporting/importing Site Standards.
To run the utility, see Running the exportsitestandards utility (on page 157).

Running the exportsitestandards utility

This procedure describes how to run the exportsitestandards utility, which enables you to export site
standards that are defined in Control-M. For more information, see exportsitestandards (on page 157).

Before you begin:

Ensure you create an arguments file, which contains the arguments that export the Site Standards from
the Control-M/EM database. For more information, see exportsitestandards arguments file rules (on page
158).
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter either of the following commands:
• emdef exportsitestandards [-u <user> [-p <password>] | -pf <password
file>] -s <GUI Server Name> -arg <args file name> -out <file name>
• emdef exportsitestandards [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <args
file name> -OUT_FILE <file name>
For more details on the exportsitestandards parameters, see Export/import site standards parameters (on
page 161).

157
Control-M Utilities Guide

exportsitestandards arguments file rules

The following rules apply to the exportsitestandards argument file:
 More than one site standard can be specified in an exportsitestandards file.
 The arguments file is case-sensitive.
 All parameter values must be enclosed in quotation marks (for example, JOBNAME="Job1").
 More than one PARAM parameter can be used in a TERM statement.
 The relationship between PARAM parameters in a TERM statement is AND.
 The exportsitestandards arguments file is checked and processed. If there are any errors, a message
is displayed specifying the lines with the errors. The exported site standards are saved to the output
file that is specified in the -out<file name> parameter.

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file.

TERMS These tags indicate the start and end of the TERMS file. Only criteria that are
located between the tags are considered to be part of the argument.

TERM The TERM tags indicate the start and the end of a group of selection criteria
used to specify a Site Standard or Site Standards that are to be exported. Only
PARAM tags that are located between the TERM tags are considered to be part
of the TERM argument.

REL Relationship between terms. Optional. Valid values:

 AND
 OR

158
Control-M Utilities Guide

Parameter Description

PARAM Selection criteria parameter used to determine the job definitions that are to be
exported. More than one PARAM can be specified. Mandatory.
PARAM VALUE="*" OP="LIKE" NAME="NAME"

NAME String. Mandatory. The name of the site standard

OP Relationship between the NAME and VALUE parameters of

the TERM. Mandatory. Valid values:
 EQ – equal
 NEQ – not equal
 LIKE – mask or pattern

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

NAME field.

EXAMPLE:
<?xml version="1.0"?>
-<TERMS>
-<TERM>
<PARAM VALUE="*" OP="LIKE" NAME="NAME"/>
<PARAM VALUE="MySiteStandard*" OP="LIKE" NAME="DESCRIPTION"/>
<PARAM VALUE="myUser*" OP="LIKE" NAME="CREATE_UID"/>
</TERM>
</TERMS>

159
Control-M Utilities Guide

importsitestandards
The importsitestandard utility enables you to do the following:
 After you have completed exportsitestandards (on page 157), you can perform a mass update on
multiple Site Standards, where you can add/update a Site Standard rule in a large number of existing
Site Standards, and import them into Control-M.
 Import one or multiple Site Standards from one environment to another, between two environments
on different Control-M/Enterprise Managers.
If you are importing Site Standards that already exist in the database, you can use the overwrite flag
in the utility command. In this case, the existing Site Standards are replaced. If you do not use the
overwrite flag, only new Site Standards are imported.
For more information on importing/exporting site standards, see Exporting/importing Site Standards.
To run the utility, see Running the importsitestandard utility (on page 160).

Running the importsitestandard utility

This procedure describes how to run the importsitestandards utility, which enables you to export site
standards that are defined in Control-M. For more information, see importsitestandards (on page 160).
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter either of the following commands:
• emdef importsitestandards [-u <user> [-p <password>] | -pf <password
file>] -s <GUI Server Name> -src <data file name> [/o]
• emdef importsitestandards [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -SRC_FILE <data
file name> [/o]
For more details on the importsitestandards parameters, see Export/import site standards parameters (on
page 161).

160
Control-M Utilities Guide

Export/import site standards parameters

The following table describes the exportsitestandards and importsitestandards utilities parameters:

Parameter Description

<user> Control-M/EM user name.

<password> Control-M/EM user password.

<password file name> Flat file containing an unencrypted user name and password on
separate lines in the format:
user=<userName>
password=<password>

<GUI Server Control-M/EM GUI server logical name, host name, or IP address.
Name>
NOTE: If multiple GUI servers exist, set this parameter to the
logical name of the relevant GUI server.

<data file (import only) Defines the path and name of the XML file
name> containing the Site Standards.

<args file name> (export only) Defines the path and name of the arguments file
containing arguments that are used as selection criteria to
determine which site standards to export.

<file name> (export only) Path and name of the output file containing the
exported site standards

/o (import only) Overwrite. The /o switch directs the utility to

overwrite any existing site standards.

161
Control-M Utilities Guide

Export/import Promotion rules

Exporting and importing Promotion rules enable you to perform a mass update on Promotion rules where
you can add and/or update a Promotion rule in large number of existing Promotion rules by using the
following utilities:
 exportpromotionrule (on page 162)
 Importpromotionrule (on page 172)
After you export the Promotion rule using the exportpromotionrule utility, an output file is created. You
can update and/or add the promotion rules to the output file, as described in Promotion rules output file
(on page 165). You can then import the Promotion rules into Control-M/EM, using the
importpromotionrule utility.
Once you have successfully imported your Promotion rules, it is best to validate the changes and ensure
that there are no errors.
NOTE: Promotion rules need to comply with site standards of the target environment, as promoted
folders and jobs are validated according to the assigned site standard before they are sent to the target
environment. For more information, see Site customizations management in Using Control-M.

exportpromotionrule
The exportpromotionrule utility enables you to do the following:
 Export promotion rules and perform a mass update of multiple promotion rules, where you can
add/update a Promotion rule for a large number of existing Promotion rules, and import them into
Control-M.
When adding a new rule, it is best to add the rule in the Tools section in Control-M, as described in
Promotion Rules in the Control-M User Guide. This serves as a template in which you export using this
utility.
 Export one or more promotion rules from one environment to another, between two environments on
different Control-M/Enterprise Managers. In this case, you may want to make small changes to the
rules before importing them into the destination environment. For example, some values might
change between a test environment and a production environment.
To run the utility, see Running the exportpromotion utility (on page 162).

Running the exportpromotion utility

This procedure describes how to run the exportpromotionrule utility, which enables you to export
promotion rules that are defined in Control-M.
Before you begin
Create an arguments file, which contains the arguments that export the promotion rules from the
Control-M/EM database. For more information, see exportpromotionrule arguments file rules (on page
163).

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.

162
Control-M Utilities Guide

• Windows: Open a command prompt window where Control-M/EM is installed.

NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type one of the following commands:
• emdef exportpromotionrule [-u <user> [-p <password>] | -pf <password
file>] -s <GUI Server Name> -arg <args file name> -out <file name>
• emdef exportpromotionrule [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <args
file name> -OUT_FILE <file name>
For more details about the exportpromotionrule parameters, see Export/import promotion rule
parameters (on page 173).

exportpromotionrule arguments file rules

The following rules apply to the exportpromotionrule arguments file:
 More than one promotion rule can be specified in an exportpromotionrule file.
 The arguments file is case-sensitive.
 All parameter values must be enclosed in quotation marks (for example, JOBNAME="Job1").
 More than one PARAM parameter can be used in a TERM statement.
 The relationship between PARAM parameters in a TERM statement is AND.
 The exportpromotionrule arguments file is checked and processed. If there are any errors, a
message is displayed specifying the lines with the errors. The exported promotion rules are saved to
the output file that is specified in the -out<file name> parameter.
For more information about the exportpromotionrule argument parameters, see exportpromotionrule
arguments file parameters (on page 164).

163
Control-M Utilities Guide

exportpromotionrule arguments file parameters

The following table describes the exportpromotionrule arguments file parameters.

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being
used, and the location of the .dtd file.

TERMS These tags indicate the start and end of the TERMS file. Only
criteria that are located between the tags are considered to be
part of the argument.

TERM The TERM tags indicate the start and the end of a group of
selection criteria used to specify a job or jobs that are to be
exported. Only PARAM tags that are located between the TERM
tags are considered to be part of the TERM argument.

REL Relationship between terms. Optional. Valid

values:
 AND
 OR

PARAM Selection criteria parameter used to determine the job definitions

that are to be exported. More than one PARAM can be specified.
Mandatory.
PARAM NAME="PROMOTIONSRULENAME" OP="LIKE"
VALUE="*"

NAME String. Mandatory. The name of the promotion

rule.

OP Relationship between the NAME and VALUE

parameters of the TERM. Mandatory. Valid
values:
 EQ – equal
 NEQ – not equal
 LIKE – mask or pattern

VALUE String. Mandatory. Value of the parameter

specified in the NAME field.

164
Control-M Utilities Guide

Promotion rules output file

After you run the exportpromotionrule utility, an output file is created in the destination you have
specified in the utility command. The output file is an XML file, that contains the extracted Promotion
Rules data. This file has a specific structure that must be adhered to, or else import fails.
Consider the following when making changes to the output file:
 When creating a new rule that you want to apply to multiple Promotion rules, it is recommended that
you add the Promotion rule in the Tools section, as described in Promotion rules in Using Control-M.
This serves as a template in which you export using the utility. You can then copy the rule to the
Promotion rules output file which you have exported. This ensures that you have the right structure of
the rule, and prevents errors.
 After exporting the promotion rule, check the SourceName and TargetName to ensure they are
correct. The SourceName and TargetName cannot exceed 100 characters.
 The description must not exceed the limit of 4000 characters.

exportpromotionrule output file examples

The following examples describe the generated output files:
 Updating the Application field - output file (on page 165)
 Updating the Description field - output file (on page 167)
 Updating the Run as User field and Set the Priority to High - output file (on page 169)

Updating the Application field - output file

You need to create a Promotion rule to update the Application field to 123 from the source environment
ENV1 to the target environment ENV2.
The following figure shows how the Promotion Rule appears in Control-M.

165
Control-M Utilities Guide

After running the exportpromotionrule utility, the following output file is generated:
<PromotionEnvItem>
<SourceName>ENV1</SourceName>
<TargetName>ENV2</TargetName>
<Name>ENV1-TO-ENV2</Name>
<Description>env1 to env 2 rule updates Application field to be
'123'</Description>
<PromotionRule>
<UpdateRows>
<FindAndUpdateItem>
<Type>Update</Type>
<IsParent>false</IsParent>
<Children/>
<Operator>
<OperatorName>Like</OperatorName>
<OperatorValue>Like</OperatorValue>
<OperatorEnumValue>LikeOperator</OperatorEnumValue>

166
Control-M Utilities Guide

</Operator>
<IsVisible>true</IsVisible>
<IsChildrenVisible>true</IsChildrenVisible>
<LegacyId>F_Application</LegacyId>
<Level>0</Level>
<IsSelected>true</IsSelected>
<UpdateValue>123</UpdateValue>
<Command>
<OperatorName>assign</OperatorName>
<OperatorEnumValue>AssignCommand</OperatorEnumValue>
</Command>
<UpdateOperator>
<OperatorName>Update</OperatorName>
<OperatorEnumValue>UpdateAction</OperatorEnumValue>
</UpdateOperator>
</FindAndUpdateItem>
</UpdateRows>
<CanMoveUpdateItemUp>false</CanMoveUpdateItemUp>
<CanMoveUpdateItemDown>false</CanMoveUpdateItemDown>
</PromotionRule>
</PromotionEnvItem>

Updating the Description field - output file

You need to create a Promotion rule that updates the Description field to Nightly job from source
environment ENV1 to the target environment ENV3.
The following figure shows how the Promotion Rule appears in Control-M.

167
Control-M Utilities Guide

After running the exportpromotionrule utility, the following output file is generated:
<PromotionEnvItem>
<SourceName>ENV1</SourceName>
<TargetName>ENV3</TargetName>
<Name>ENV1-TO-ENV3</Name>
<Description>env1 to env 3 rule updates Description field to be 'Nightly
Job'</Description>
<PromotionRule>
<UpdateRows>
<FindAndUpdateItem>
<Type>Update</Type>
<IsParent>false</IsParent>
<Children/>
<Operator>
<OperatorName>Like</OperatorName>
<OperatorValue>Like</OperatorValue>
<OperatorEnumValue>LikeOperator</OperatorEnumValue>

168
Control-M Utilities Guide

</Operator>
<IsVisible>true</IsVisible>
<IsChildrenVisible>true</IsChildrenVisible>
<LegacyId>F_Description</LegacyId>
<Level>0</Level>
<IsSelected>true</IsSelected>
<UpdateValue>Nightly Job</UpdateValue>
<Command>
<OperatorName>assign</OperatorName>
<OperatorEnumValue>AssignCommand</OperatorEnumValue>
</Command>
<UpdateOperator>
<OperatorName>Update</OperatorName>
<OperatorEnumValue>UpdateAction</OperatorEnumValue>
</UpdateOperator>
</FindAndUpdateItem>
</UpdateRows>
<CanMoveUpdateItemUp>false</CanMoveUpdateItemUp>
<CanMoveUpdateItemDown>false</CanMoveUpdateItemDown>
</PromotionRule>
</PromotionEnvItem>

Updating the Run as User field and Set the Priority to High - output file
In the following example, you need to create two Promotion Rules from source environment ENV4 to
target environment ENV2:
 Update the Run as User field to adminuser
 Set the Priority to High
The following figure shows how the Promotion Rule appears in Control-M.

169
Control-M Utilities Guide

After running the exportpromotionrule utility, the following output file is generated:
<PromotionEnvItem>
<SourceName>ENV4</SourceName>
<TargetName>ENV2</TargetName>
<Name>ENV4-TO-ENV2</Name>
<Description>env4 to env 2 rule updates 2 field: 1. Run As to be 'adminuser'.
2. Priority to 'High'</Description>
<PromotionRule>
<UpdateRows>
<FindAndUpdateItem>
<Type>Update</Type>
<IsParent>false</IsParent>
<Children/>
<Operator>
<OperatorName>Like</OperatorName>
<OperatorValue>Like</OperatorValue>
<OperatorEnumValue>LikeOperator</OperatorEnumValue>

170
Control-M Utilities Guide

</Operator>
<IsVisible>true</IsVisible>
<IsChildrenVisible>true</IsChildrenVisible>
<LegacyId>F_Owner</LegacyId>
<Level>0</Level>
<IsSelected>false</IsSelected>
<UpdateValue>adminuser</UpdateValue>
<Command>
<OperatorName>assign</OperatorName>
<OperatorEnumValue>AssignCommand</OperatorEnumValue>
</Command>
<UpdateOperator>
<OperatorName>Update</OperatorName>
<OperatorEnumValue>UpdateAction</OperatorEnumValue>
</UpdateOperator>
</FindAndUpdateItem>
<FindAndUpdateItem>
<Type>Update</Type>
<IsParent>false</IsParent>
<Children/>
<Operator>
<OperatorName>Like</OperatorName>
<OperatorValue>Like</OperatorValue>
<OperatorEnumValue>LikeOperator</OperatorEnumValue>
</Operator>
<IsVisible>true</IsVisible>
<IsChildrenVisible>true</IsChildrenVisible>
<LegacyId>F_Priority</LegacyId>
<Level>0</Level>
<IsSelected>true</IsSelected>
<UpdateValue>High</UpdateValue>
<Command>
<OperatorName>assign</OperatorName>
<OperatorEnumValue>AssignCommand</OperatorEnumValue>
</Command>

171
Control-M Utilities Guide

<UpdateOperator>
<OperatorName>Update</OperatorName>
<OperatorEnumValue>UpdateAction</OperatorEnumValue>
</UpdateOperator>
</FindAndUpdateItem>
</UpdateRows>
<CanMoveUpdateItemUp>true</CanMoveUpdateItemUp>
<CanMoveUpdateItemDown>false</CanMoveUpdateItemDown>
</PromotionRule>
</PromotionEnvItem>

Importpromotionrule
The importpromotionrule utility enables you to do the following:
 Perform a mass update on multiple Promotion rules (after Running the exportsitestandards utility (on
page 157)) where you can add/update a Promotion rule in a large number of existing Promotion
rules, and import them into Control-M.
 Import one or multiple Promotion rules from one environment to another, between two environments
on different Control-M/Enterprise Managers. If you import Promotion rules that already exist in the
database, you can use the overwrite flag (/o) in the utility command, so existing Promotion rules are
replaced. If you do not use the overwrite flag, Promotion rules are not imported and a message is
issued that Promotion rules already exist.
Before using the importpromotionrule utility, note the following:
 The Source/Target name must be defined in the Environment Name field in the Promotion Rules
tab in Control-M.
 Only one rule for each Source and Target combination is permitted. If the file contains two rules with
the same Source and Target, an error message is issued when importing the rule.
To run the utility, see Running the importpromotionrule utility (on page 172).

Running the importpromotionrule utility

This procedure describes how to run the importpromotionrule utility, which enables you to import
specified promotion rule values in the Control-M/EM database.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.

172
Control-M Utilities Guide

2. Type one of the following commands:

• emdef importpromotionrule [-u <user> [-p <password>] | -pf <password
file>] -s <GUI Server Name> -src <data file name> [/o]
• emdef importpromotionrule [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -SRC_FILE <data
file name> [/o]
For more details about the importpromotionrule parameters, see Export/import promotion rule
parameters (on page 173).

Export/import promotion rule parameters

The following table describes the parameters for exportpromotionrule and importpromotionrule
utilities:

Parameter Description

<user> Defines the Control-M/EM user name.

<password> Defines the Control-M/EM user password.

<password file name> Flat file containing an unencrypted user name and password on
separate lines in the format:
user=<userName>
password=<password>

<GUI Server Name> Control-M/EM GUI server logical name, host name, or IP address.
NOTE: If multiple GUI servers exist, set this parameter to the
logical name of the relevant GUI server.

<data file name> (import only) Defines the path and name of the XML file
containing the promotion rules. For more information about the
XML file, see exportpromotionrule arguments file rules (on page
163) and XML file rules (on page 35).

<args file name> (export only) Defines the path and name of the arguments file
containing arguments that are used as selection criteria to
determine which promotion rules to export.

<file name> (export only) Path and name of the output file containing the
exported promotion rules. For more information, see Promotion
rules output file (on page 165).

/o (import only) Overwrite. The /o switch directs the utility to

overwrite any existing Promotion rule.

173
Control-M Utilities Guide

emdef utility for services

The emdef is a command line utility used to make various modifications to service definitions in the
Control-M/EM database. The emdef uses the following parameters:

Utility Type Description

defservice (on page 174) Imports service processing definitions into the Control-M/EM
database

exportdefservice (on page Exports service definitions

179)

For emdef parameters related to jobs, see emdef utility for jobs (on page 42).
For emdef parameters related to folders and calendars see emdef utility for folders and calendars (on
page 266).

defservice
The defservice utility imports service processing definitions into existing folders in the Control-M/EM
database. To import service processing definitions using the defservice utility, see Importing BIM service
processing definitions using the defservice utility (on page 174).
defservice reads service processing definitions from a plain text input file written in XML format.
The defservice input file is checked and processed. If there are any errors in the file, a message is
displayed specifying the lines with the errors. For more information, see defservice XML input file example
(on page 175).

Importing BIM service processing definitions using the defservice utility

This procedure describes how to import BIM service processing definitions into existing folders in the
Control-M/EM database using the defservice utility.
 To import service definitions:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter either of the following commands:
• emdef defservice [-u <user> [-p <password>] | -pf <password file>] -s
<GUI Server Name> -src <xml File Name> [/a]

174
Control-M Utilities Guide

• emdef defservice [-USERNAME <user> [-PASSWORD <password>] |

-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -SRC_FILE <xml
File Name> [/a]
For details about the defservice parameters and switches, see emdef general parameters (on page
44) and emdef switches (on page 45).

defservice XML input file example

The following example input file is used with the defservice utility:
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE DEFSERVICE SYSTEM "defservice.dtd">
<DEFSERVICE >
<SERVICE CREATED_BY="emuser" CREATE_TIME="20100819224237UTC"
INSTANTIATION_TYPE="Filter" LAST_UPDATE_TIME="20100822055018UTC"
NAME="example" ORDERABLE="0" SERVICE_ID="8">
<FILTER >
<INCLUDING_TERMS >
<TERM >
<PARAM NAME="CONTROL-M Name" OP="NEQ" VALUE="isvm-w23-ctmDS9"/>
</TERM>
</INCLUDING_TERMS>
</FILTER>
</SERVICE>
<SERVICE CREATED_BY="emuser" CREATE_TIME="20100818093723UTC"
INSTANTIATION_TYPE="Filter" LAST_UPDATE_TIME="20100822055952UTC"
NAME="filter service" ORDERABLE="0" SERVICE_ID="1">
<FILTER >
<INCLUDING_TERMS >
<TERM >
<PARAM NAME="CONTROL-M Name" OP="LIKE" VALUE="isvm-w23-ctmDS9"/>
<PARAM NAME="ORDER_FOLDER" OP="LIKE" VALUE="TestCon, TestCon2"/>
</TERM>
</INCLUDING_TERMS>
</FILTER>
</SERVICE>
<SERVICE CREATED_BY="emuser" CREATE_TIME="20100818093756UTC"
INSTANTIATION_TYPE="FilterODAT" LAST_UPDATE_TIME="20100822055018UTC"
NAME="odat service" ORDERABLE="0" SERVICE_ID="2">
<FILTER >

175
Control-M Utilities Guide

<INCLUDING_TERMS >
<TERM >
<PARAM NAME="CONTROL-M Name" OP="LIKE" VALUE="isvm-w23-ctmDS9"/>
<PARAM NAME="ORDER_FOLDER" OP="LIKE" VALUE="TestCon, TestCon2"/>
</TERM>
</INCLUDING_TERMS>
</FILTER>
</SERVICE>
<SERVICE CREATED_BY="emuser" CREATE_TIME="20100818094142UTC"
INSTANTIATION_TYPE="Job" LAST_UPDATE_TIME="20100822055018UTC" NAME="order
(job) service" ORDERABLE="1" SERVICE_ID="4">
<FILTER >
<INCLUDING_TERMS >
<TERM >
<PARAM NAME="CONTROL-M Name" OP="EQ" VALUE="isvm-w23-ctmDS9"/>
<PARAM NAME="ORDER_FOLDER" OP="EQ" VALUE="TestCon_"/>
<PARAM NAME="JOBNAME" OP="EQ" />
</TERM>
</INCLUDING_TERMS>
</FILTER>
<ORDERABLE_PARAM DISPLAY_NAME="p1" PARAM_NAME="p1" PARAM_TYPE="String"
REQUIRED="1" VALIDATION=","/>
</SERVICE>
<SERVICE CREATED_BY="emuser" CREATE_TIME="20100819211228UTC"
INSTANTIATION_TYPE="SMARTFolder" LAST_UPDATE_TIME="20100822055018UTC"
NAME="tzahi" ORDERABLE="1" SERVICE_ID="6">
<FILTER >
<INCLUDING_TERMS >
<TERM >
<PARAM NAME="CONTROL-M Name" OP="EQ" VALUE="isvm-w23-ctmDS9"/>
<PARAM NAME="ORDER_FOLDER" OP="EQ" VALUE="aaa22"/>
</TERM>
</INCLUDING_TERMS>
</FILTER>
</SERVICE>

176
Control-M Utilities Guide

<SERVICE CREATED_BY="emuser" CREATE_TIME="20100822045059UTC"

INSTANTIATION_TYPE="Filter" LAST_UPDATE_TIME="20100822055018UTC"
NAME="tzahi10" ORDERABLE="0" SERVICE_ID="10">
<FILTER >
<INCLUDING_TERMS >
<TERM >
<PARAM NAME="CONTROL-M Name" OP="LIKE" VALUE="isvm-w23-ctmDS9"/>
<PARAM NAME="APPLICATION" OP="LIKE" VALUE="DailyAppl"/>
<PARAM NAME="GROUP" OP="LIKE" VALUE="DailyJobs"/>
<PARAM NAME="ORDER_FOLDER" OP="LIKE" VALUE="Con2Folder"/>
<PARAM NAME="ORDER_LIB" OP="LIKE" VALUE="folder"/>
<PARAM NAME="MEMLIB" OP="LIKE" VALUE="memlib"/>
<PARAM NAME="MEMNAME" OP="LIKE" VALUE="memname"/>
<PARAM NAME="JOBNAME" OP="LIKE" VALUE="jobname"/>
<PARAM NAME="TASKTYPE" OP="LIKE" VALUE="*Job*, *Task*, Command, Detached,
Dummy, External"/>
<PARAM NAME="OWNER" OP="LIKE" VALUE="owner"/>
<PARAM NAME="DEF_HOSTGROUP" OP="LIKE" VALUE="hostgroup"/>
<PARAM NAME="APPL_TYPE" OP="LIKE" VALUE="OS"/>
</TERM>
</INCLUDING_TERMS>
</FILTER>
</SERVICE>
<SERVICE CREATED_BY="emuser" CREATE_TIME="20100819223946UTC"
INSTANTIATION_TYPE="Job" LAST_UPDATE_TIME="20100822055018UTC" NAME="tzahi2"
ORDERABLE="1" SERVICE_ID="7">
<FILTER >
<INCLUDING_TERMS >
<TERM >
<PARAM NAME="CONTROL-M Name" OP="EQ" VALUE="isvm-w23-ctmDS9"/>
<PARAM NAME="ORDER_FOLDER" OP="EQ" VALUE="DailySchedule"/>
<PARAM NAME="JOBNAME" OP="EQ" VALUE="SuadCommand0"/>
</TERM>
</INCLUDING_TERMS>
</FILTER>
<ORDERABLE_PARAM DISPLAY_NAME="param" PARAM_NAME="My Param"
PARAM_TYPE="String" REQUIRED="0" VALIDATION=","/>

177
Control-M Utilities Guide

</SERVICE>
<SERVICE CREATED_BY="emuser" CREATE_TIME="20100821140755UTC"
INSTANTIATION_TYPE="Filter" LAST_UPDATE_TIME="20100822055018UTC"
NAME="tzahi3" ORDERABLE="0" SERVICE_ID="9">
<FILTER >
<INCLUDING_TERMS >
<TERM >
<PARAM NAME="CONTROL-M Name" OP="LIKE" VALUE="isvm-w23-ctmDS9, THID0106"/>
<PARAM NAME="APPLICATION" OP="LIKE" VALUE="SuadDailyAppl*"/>
<PARAM NAME="GROUP" OP="LIKE" VALUE="DailyJobs, TestCon*"/>
<PARAM NAME="MEMLIB" OP="LIKE" VALUE="memlib"/>
<PARAM NAME="TASKTYPE" OP="LIKE" VALUE="*Job*, Command"/>
<PARAM NAME="DEF_HOSTGROUP" OP="LIKE" VALUE="hostgroup"/>
</TERM>
</INCLUDING_TERMS>
</FILTER>
</SERVICE>
<SERVICE CREATED_BY="emuser" CREATE_TIME="20100822060917UTC"
INSTANTIATION_TYPE="Filter" LAST_UPDATE_TIME="20100822060917UTC"
NAME="ServiceFilter" ORDERABLE="0" SERVICE_ID="11">
<FILTER >
<INCLUDING_TERMS >
<TERM >
<PARAM NAME="CONTROL-M Name" OP="LIKE" VALUE="controlm"/>
<PARAM NAME="APPLICATION" OP="LIKE" VALUE="application"/>
<PARAM NAME="GROUP" OP="LIKE" VALUE="group"/>
<PARAM NAME="ORDER_FOLDER" OP="LIKE" VALUE="folder"/>
<PARAM NAME="ORDER_LIB" OP="LIKE" VALUE="folderlin"/>
<PARAM NAME="MEMLIB" OP="LIKE" VALUE="memlib"/>
<PARAM NAME="MEMNAME" OP="LIKE" VALUE="memname"/>
<PARAM NAME="JOBNAME" OP="LIKE" VALUE="jobname"/>
<PARAM NAME="TASKTYPE" OP="LIKE" VALUE="*Job*, *Task*, Command, Detached,
Dummy, External"/>
<PARAM NAME="OWNER" OP="LIKE" VALUE="owner"/>
<PARAM NAME="DEF_HOSTGROUP" OP="LIKE" VALUE="hostgroup"/>
<PARAM NAME="APPL_TYPE" OP="LIKE" VALUE="OS"/>

178
Control-M Utilities Guide

<PARAM NAME="DESCRIPTION" OP="LIKE" VALUE="description"/>

</TERM>
</INCLUDING_TERMS>
</FILTER>
</SERVICE>
</DEFSERVICE>

exportdefservice
The exportdefservice parameter of the emdef utility exports BIM service processing definitions from the
Control-M/EM database to an output file. To export service processing definitions using the utility, see
Exporting BIM service processing definitions using the exportdefservice utility (on page 179).
When exportdefservice is invoked, it processes a specified file of arguments in XML format. For more
information, see exportdefservice arguments file (on page 181). This file contains statements that identify
existing service processing definitions. The identified definitions are exported from the Control-M/EM
database to an output file. You can modify the exported service processing definitions in the output file
and can import the modified definitions into the Control-M/EM database using the defservice (on page
174) utility.

Exporting BIM service processing definitions using the exportdefservice

utility
This procedure describes how to export BIM service processing definitions from the Control-M/EM
database to an output file, using the exportdefservice utility.
 To export service processing definitions:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter one of the following commands:
• emdef exportdefservice [-u <user> [-p <password>] | -pf <password File>]
-s <GUI Server Name> -arg <args file name> -out <file name>
• emdef exportdefservice [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <args
file name> -OUT_FILE <file name>
NOTE: For Windows you do not need to use the emdef prefix.
For details about the exportdefservice parameters and options, see exportdefservice parameters (on
page 180) and emdef switches (on page 45).
For more information about the args file name, see exportdefservice arguments file (on page 181).

179
Control-M Utilities Guide

exportdefservice parameters
The following table lists the exportdefservice parameters:

Parameter Description

<user> Control-M/EM database user name.

<password> The Control-M/EM database user password.

<password file Flat file containing an unencrypted user name and password on
name> separate lines in the format:
user=<userName >
password=<password>

<GUI Server Control-M/EM GUI server logical name, host name, or IP address.
Name>
NOTE: If multiple GUI servers exist, set this parameter to the logical
name of the relevant GUI server.

<Args file name> Path and name of the arguments file containing exportdefservice
specifications. For information about this file, see XML file rules (on
page 35)

<file name> Path and name of the file containing the exported service
specifications.

-ctm Name of the Control-M installation that processes the job.

-folder Name of folder.

-app Name of the Application to which the job's group belongs

-subapp Name of the Sub Application to which the job belongs.

-service Name of the service for export.

/? Displays utility's description and available options.

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

180
Control-M Utilities Guide

exportdefservice arguments file

The following rules apply to the exportdefservice argument file:
 More than one service can be specified in an exportdefservice file.
 The arguments file is case-sensitive.
 All parameter values must be enclosed in quotation marks.
 More than one PARAM parameter can be used in a TERM statement.
 The relationship between PARAM parameters in a TERM statement is AND.
For instructions about preparing this file, see XML file rules (on page 35).
The exportdefservice arguments file is checked and processed. If there are any errors, a message is
displayed specifying the lines with the errors. The exported service processing definitions are saved to the
output file whose name and location is specified in the -out <out file name> parameter.
For more information on the input file parameters for the exportdefservice utility, see exportdefservice
arguments file parameters (on page 181), and exportdefservice arguments file example (on page 182).

exportdefservice arguments file parameters

The following table describes the exportdefservice arguments file parameters:

Parameter Description

The first two lines of the arguments file specify the XML version, the text encoding format being used, and
the location of the .dtd file.

TERMS These tags indicate the start and end of the TERMS file. Only criteria that are
located between the tags are considered to be part of the argument.

TERM The TERM tags indicate the start and the end of a group of selection criteria
used to specify a service or services that are to be exported. Only PARAM tags
that are located between the TERM tags are considered to be part of the TERM
argument.

REL Relationship between terms. Optional. Valid values:

 AND
 OR

181
Control-M Utilities Guide

Parameter Description

PARAM Selection criteria parameter used to determine the service definitions that are to
be exported. More than one PARAM can be specified. Mandatory.
PARAM NAME="DATACENTER" OP="E" VALUE="Center1"

NAME String. Mandatory. The parameter name of any service

processing definition parameter.

OP Relationship between the NAME and VALUE parameters of

the TERM. Mandatory. Valid values:
 EQ – equal
 NEQ – not equal
 LIKE – mask or pattern

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

NAME field.

exportdefservice arguments file example

The following example arguments file is used with the exportdefservice utility:
<TERMS>
<TERM>
<PARAM NAME="NAME" OP="LIKE" VALUE="*"/>
</TERM>
</TERMS>

emwacli for promotion

The emwacli utility enables you to run Promotion as a batch process.
Control-M Workload Change Manager's Promotion feature enables you to automatically transfer folders
and jobs between environments. Once you have finished working on job definitions in a source
environment, you can move folders and jobs to the target environment, while the data is automatically
transferred according to your predefined promotion rules. For more information about Promotion, see
Promotion.
By using the emwacli utiliy, batch promotion is performed automatically, which includes promotion
modifications, validations and activation of all Control-M Workload Change Manager user exits.
Automation occurs up to check in into the target environment.
NOTE: You must activate Control-M Workload Change Manager before using the utility.

182
Control-M Utilities Guide

Promotion can only be run from a Windows environment where Control-M client is installed. The utility
uses Promotion rules which have been defined by the Administrator in Control-M. Running the utility
invokes the same promotion user exits and email notifications for all actions if defining Promotion in
Control-M client.
To run the emwacli utilty, see Running the emwacli utility (on page 183).
You can type the emwacli parameters in the command line or define the parameters in a param_file
(text file). For more information see param_file (on page 187).
For more information about emwacli parameters, see emwacli utility Promotion parameters (on page
184).

Running the emwacli utility

This procedure describes how to run the emwacli utility which enables you to run promotion as a batch
process.
Before you begin
Ensure the following:
 You have created a promotion rule, as described in Promotion rules.
 If the target environment is in a different Control-M/EM, do the following on both the source and
target environments:
• Activate Control-M Workload Change Manager
• Match the SSL configuration
• Match the CJK parameters (if applicable)
 (Optional) Create a param_file, as described in param_file (on page 187).
 To run the emwacli utility:
1. Open a command prompt window where Control-M/EM is installed. You do not need to be in the
Control-M/EM database directory.
2. Type one of the following commands:
• emwacli -action promote [-nshost <naming server> -nsport <naming server
port> -s <GSR name> -u <user> [-p <password>] | -pf <password File>]
-promotion rule <name of promotion rule> -ru <remote EM user> -rp <remote
EM password> -rpf <target user name and password> -ignore warnings <Y/N>
-controlm <the name of the server> -folder name <name of the folder>
-folder library <name of the folder library> -request name <name of
promotion request> -request_ticket <request ticket> -email notification
<name of email address> -overwrite <y/n> dbg <debug level> -accept_all
<y/n>]
• If you have created a param-file: emwacli -param_file [name]
NOTE: Some parameters are mandatory. For more information, see emwacli utility Promotion
parameters (on page 184).
If any folders in the source environment, which are defined in -controlm, -folder_name,
-folder library do not match the promotion rule, the utility exits with an error message.

183
Control-M Utilities Guide

emwacli utility Promotion parameters

The following table describes the emwacli utility Promotion parameters.

Parameter Descripton

General Promotion parameters

-u Defines the Control-M/EM user name (mandatory).

-p Defines the Control-M/EM password (mandatory).

-pf Defines the file containing an unencrypted user name and

password on separate lines in the format:
user=<userName >
password=<password>

-s Defines the Control-M/EM GUI server logical name, host name, or

IP address (mandatory).
NOTE: If multiple GUI servers exist, set this parameter to the
logical name of the relevant GUI server.

-nshost Defines the naming server host (mandatory).

-nsport Defines the Naming server port (mandatory).

-action promote Enables you to run promotion (mandatory).

-param_file Enables you to define a file containing parameters for the utility,
instead of typing each parameter in the command line. For more
information, see param_file (on page 187).

-dbg Sets the emwacli utility debug level. Default: 2

Values:
 1: Warning
 2: Information
 3: Debug
 4: Trace

-promotion rule Defines the name of the defined promotion rule (mandatory). For
more information about defining promotion rules see Creating a
promotion rule.

184
Control-M Utilities Guide

Parameter Descripton

-ignore warnings Determines if a promote action stops where there are validation
warnings or integrity warnings.
Values:
 Y: If any validation or integrity warnings are issued, promotion
continues.
 N: If any validation or integrity warnings are issued,
promotion exits.
Default: Y
NOTE: Integrity and validation warnings appear in the command
window regardless of the value.

request_name Defines the name of the promotion request (mandatory).

-request_ticket Defines an ID that can be associated with the request.

-request_description Defines the request description that appears in the request details.

-email_notification Defines the email address for notifications. For more information,
see Request Details parameters.

-overwrite Determines if the existing folders on the target environment are

overridden.
Values:
 Y: If a folder already exists in the target environment, all
promoted files overwrite existing folders.
 N: Promotion terminates if the folder already exists.
Default: N

185
Control-M Utilities Guide

Parameter Descripton

-accept_all Enables you to consolidate jobs and SMART folders into the
current logged in user if the Created_by parameter and the
Control-M/EM user do not match.
Values:
 Y: Jobs and SMART folders in the Created_by parameter are
consolidated into the current logged in user, if the Created by
parameter and Control-M/EM user do not match.
 N: The utility exits with an error message, if the Created by
parameter and Control-M/EM user do not match.

Default: N
NOTE: Relevant only when the AuthorSecurity system parameter
is set to 2 or 3.

Filter parameters (Specifies where you want to promote)

-controlm Defines the name of the Control-M Server. (Mandatory)

EXAMPLE: * includes all Control-M Servers.

-folder_name Defines the name of the SMART Folder where the job belongs
(mandatory)

-folder_library (Control-M for z/OS only) Defines the name of the library where
the folder is located.

Target Environment parameters (Target environment is on a different Control-M/EM)

-ru Defines the user name in the target environment. Mandatory for
defining a remote environment.

-rp Defines the password associated with the user name in the target
environment which is used only for promotion requests.

-rpf Defines the file containing an unencrypted user name and

password on separate lines in the format where the target
environment is in a different Control-M/EM:
user=<userName >
password=<password>

186
Control-M Utilities Guide

param_file
param_file enables you to define a file containing parameters for the utility. The utility reads promotion
definitions from a plain text input file, which is checked and processed. If there are any errors in the file,
a message is displayed specifying the lines with the errors. In this file, each parameter and its values (if
any) are on a separate line with the same syntax they would have on the command line. Using the
params_file enables you to prepare and save files of the emwacli parameter that can be reused.
If a mandatory parameter is omitted from the param_file the utility exits with an error message. If an
optional parameter is omitted, the default is used.
All keywords must be entered in lowercase. For an example, see emwacli utility param_file example (on
page 187).

emwacli utility param_file example

The following example describes a param_file.
-u emuser
-p empass
-nshost vw-tlv-em-dv162
-s vw-tlv-em-dv162
-nsport 13075
-request_name WorkspaceTest11
-folder_name *
-controlm *
-dbg 2
-action promote
-promotion_rule dev-TO-remote
-ru emuser
-rp empass
-overwrite n
-ignore_warnings n

187
Control-M Utilities Guide

Control-M/Server utilities
This table lists the Control-M/Server utilities that are used for definition, ordering, and monitoring.

Utility Type Description

ctmcreate (on page 189) Enables a specific purpose job to be inserted directly
into the Active Jobs database.

ctmdefine (on page 202) Adds a job processing definition to a folder, a SMART
folder, and a subfolder in the Control-M/Server
database.

ctmexdef (on page 215) The ctmexdef utility exports job processing definitions
from the Control-M/Server database to a flat (ASCII)
file.

ctmfw File Watcher utility (on The ctmfw (Control-M File Watcher) utility monitors file
page 217) status and detects the following file processes:
 Successful completion of a file transfer activity
 Creation of a file
 Deletion of a file

ctmimptb (on page 228) The ctmimptb utility imports job definition folders
(including SMART Folders and Rule-Based Calendars)
that were exported from Control-M/EM by the
exportdeffolder utility.

ctmkilljob (on page 231) The ctmkilljob utility terminates a specified Control-M
job and all its processes. ctmkilljob terminates only jobs
that are currently executing.

ctmorder (on page 232) The ctmorder utility orders or forces one or more jobs
from a SMART Folder in the Control-M/Server database.

ctmpsm (on page 240) The ctmpsm utility can be invoked interactively to
display the Control-M Production Support menu.

ctmsweep (on page 258) The ctmsweep utility deletes job definitions from the
Control-M/Server database that become obsolete due to
the Start date (Active From Date) and End date (Active
To Date) parameters in the job definitions.

ctmwhy (on page 262) The ctmwhy utility displays a report stating why a
SMART Folder, Sub-folder, or job waiting in the Active
Jobs database is not being submitted for execution.

188
Control-M Utilities Guide

ctmcreate
The ctmcreate utility is an API (Application Program Interface) that allows a specific purpose job to be
inserted directly into the Active Jobs database. The job does not have to be defined in the
Control-M/Server database. The function performed by this utility is equivalent to the Force function in
Control-M/EM. To run the ctmcreate utility, see Creating a job using ctmcreate utility (on page 189).
The ctmcreate utility can be invoked using the -input_file parameter:
ctmcreate -input_file <fullPathFileName>
The referenced file contains all the required parameters. Most of the parameters are described in
Control-M Parameters and ctmcreate parameters (on page 192).
For more information on syntax rules, see ctmcreate syntax rules (on page 199).
You can create a job within the given folder or Sub-folder name. The ctmcreate utility can be used to
create a specific purpose (non-permanent) folder that is not defined in the Control-M/Server database by
specifying:
-TASKTYPE FOLDER|SUBFOLDER -folder <folderName|folderPath>
EXAMPLE: Control-M/Server ctmcreate utility
ctmcreate -tasktype job -application SAP -hostgrp chef1 -appltype SAP -file_path ddd
-file_name fff -variable %%SAPR3-ACCOUNT DV1 -variable %%SAPR3-JOBNAME SAPCM
-variable %%SAPR3-JOBCOUNT 09495501 -variable %%SAPR3-JOB_MODE EXTERNAL
-applver 46C/46D -applform "SAP R3" -cmver 900 -jobname xxxx.

Creating a job using ctmcreate utility

This procedure describes how to run the ctmcreate utility, which enables you to insert a specific purpose
job directly into the Active Jobs database.
 To create a job using the ctmcreate utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Type the following command:
ctmcreate
-TASKTYPE
<JOB|EXTERNAL|DETACHED|COMMAND|DUMMY|FOLDER|SUBFOLDER>
[ -SUB_APPLICATION <sub_application name> ]
[ -APPLICATION <applic name> ]
[ -DEBUG <debug level 0-5> ]
[ -QUIET ]

189
Control-M Utilities Guide

[ -FOLDER_ORD <SMART folder or Sub folder orderno|ALONE|LAST> ]

[ -ADJUST_COND Y|N ]
[ -MULTIAGENT Y|N ]
[ -HOSTGRP <name> ]
[ -FILE_PATH <path> ]
[ -FILE_NAME <filename> ]
[ -CMDLINE <string> ]
[ -EMBEDDED_SCRIPT <file name> ]
[ -JOBNAME <name> ]
[ -FOLDER <name> ]
[ -RUN_AS <username> ]
[ -CREATED_BY <username> ]
[ -ODATE <date>|ODAT ]
[ -ODATE_OPTION VALUE_DATE|RUN_DATE ]
[ -MAXRERUN <value> ]
[ -TIMEZONE <xxx> ]
[ -TIMEFROM <earliest submission time> ]
[ -TIMEUNTIL <latest submission time> | '>' ]
[ -PRIORITY <job priority> ]
[ -CRITICAL Y|N ]
[ -CYCLIC Y|N ]
[ -CYCLIC_TYPE INTERVAL|INTERVAL_SEQUENCE|SPECIFIC_TIMES ]
[ -SPECIFIC_TIMES <specific times string (HHMM,HHMM)> ]
[ -INTERVAL_SEQUENCE <interval sequence string e.g(+1H,+2M)> ]
[ -TOLERANCE <maximum delay allowed (minutes)> ]
[ -CONFIRM Y|N ]
[ -TASKCLASS DISTRIBUTION_|DECOLLATION
[ -APPLTYPE <agent_application> ]
[ -APPLVER <application version> ]
[ -CMVER <CM version> ]
[ -APPLFORM <application form> ]
[ -INTERVAL <45d(days) | 1080h(hours) | 64800m (minutes)> ]
[ -INTERVALFROM START | END | TARGET ]
[ -OVERRIDE_PATH <alternative directory> ]
[ -MAXWAIT <days> ]
[ -DESCRIPTION <string> ]

190
Control-M Utilities Guide

[ -DOCMEM <filename> ]
[ -DOCLIB <directory name> ]
[ -INCOND <condition> <dateref>|ODAT AND|OR ]
[ -OUTCOND <condition> <dateref>|ODAT ADD|DEL ]
[ -VARIABLE <variable name as %%local, %%\global, %%\\smart or
%%\\pool\variable> <expression> ]
[ -QUANTITATIVE <name> <quantity> ]
[ -OUTPUT RELEASE|DELETE|COPY|MOVE [<parameter>]]
[ -CONTROL <name> E|S ]
[ -SHOUT OK|NOTOK|RERUN|LATESUB|LATETIME|EXECTIME <destination>
<urgency R|U|V> <message> [<time>] ]
[ -REMOVEATONCE Y:N ]
[ -DAYSKEEPINNOTOK <days> ]
[ -ON <statement> <code>
[ -DOOK ]
[ -DONOTOK ]
[ -DORERUN ]
[ -DOSHOUT <destination> <urgency R|U|V> <message> ]
[ -DOCOND <condname> <dateref>|ODAT ADD|DEL ]
[ -DOVARIABLE <variable name as %%local, %%\global, %%\\smart or
%%\\pool\variable> <expression> ]
[ -DOFORCEJOB <foldername> <jobname> <odate>|ODAT ]
[ -DOREMOTEFORCEJOB <foldername> <jobname> <odate>|ODAT ]
[ -ORDERVARIABLE <variable name as %%local, %%\global, %%\\smart or
%%\\pool\variable> <expression> ]
[ -DOOUTPUT RELEASE|DELETE|COPY|MOVE [<parameter>] ] ]
[ -DOSTOPCYCLIC ]
[ -DOMAIL <destination> <cc> <urgency R|U|V> <subject> <message> [<attach
output>] ]
[ -DOREMEDY <summary> <description> <urgency L|M|H|U|C>
[ -CAPTURE INTO <variable name as %%local, %%\global, %%\\smart or
%%\\pool\variable>
SEARCH <Search string>
[SKIPROWS <Number rows>]
[SKIPWORDS <Number words> [DELIMITER <Character delimiter> TAKE <Number
words | 0 until end>] | SKIPCHARS <Number characters> [TAKE <Number chars | 0 until
end>] ] ]
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmcreate parameters, see ctmcreate parameters (on page 192).

191
Control-M Utilities Guide

ctmcreate parameters
The following table describes ctmcreate utility parameters. Most of the parameters are also described in
Control-M Parameters.

Parameter Description

-APPLICATION Provides a logical name for sorting groups of jobs. This parameter
is used to supply a common descriptive name to a set of related
groups of jobs.

-CREATED_BY Control-M/EM user who defined the job. String up to 64

characters. Optional.
NOTE: This argument is used by the Control-M/Server security
mechanism and, under certain circumstances, cannot be modified.
For more information, see the Security chapter and the description
of the AuthorSecurity system parameter in GUI Server parameters.

-CYCLIC Indicates whether the job is cyclic (to be run at regular intervals).
Optional.
Valid values:
 Y – Yes
 N – No (Default)

-CYCLIC_TYPE Determines the type of cyclic job:

 Interval
 Interval Sequence
 Specific Times

-INTERVAL SEQUENCE A list of time intervals (for example +30M,+2H,+1D) up to 4000

characters including commas. Value range:
 Minutes: 0-64,800
 Hours: 0-1080
 Days: 0-45

-SPECIFIC_TIMES A list of times, separated by commas (for example

0800,1330,2300), which supports time synonym (for example
2730).

-ODATE Indicates the scheduling date (odate) to be associated with job(s).

Valid values are:

192
Control-M Utilities Guide

Parameter Description

ODAT The current working date of the computer

on which Control-M/Server is running.
This is the default value.

yyyymmdd A specific working day in yyyymmdd

format.

NOTE: The interpretation of this parameter value is dependent on

the value specified for the -odate_option parameter (described
below).

-ODATE_OPTION Indicates how the specified -odate value should be used.

Valid values are:

value_date The specified odate is the odate value for

the job. However, the job should be run
during the current working day.
This is the default value for
the -odate_option parameter.
NOTE: If a time zone is specified in the
job processing definition, then the job is
run according to those time zones.

193
Control-M Utilities Guide

Parameter Description

run_date The jobs that are ordered by this run of

the ctmcreate utility should be run only
when the specified odate begins.
If the specified odate is the current
working day, this job will work in the same
way as value_date (described above).
If the specified odate has not begun (for
example, due to time zone specifications),
then the job will wait in the Active Jobs
database (with WAIT_ODAT status) until
the start of the specified working day.
NOTE: If the specified odate has already
passed, the ctmcreate utility will not run,
and an error message will be displayed.

-FOLDER_ORD Specifies in which order of a SMART Folder to put the job. Valid
values are:

<order-no> A specific order number of the SMART

Folder.
If the specified order number does not
exist the command is not executed and an
error message is displayed.

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

LAST The last order of the specified SMART

Folder.

194
Control-M Utilities Guide

Parameter Description

NOTE: When an order ID or LAST is specified for this parameter,

the -folder parameter is mandatory and must contain the name of
a SMART Folder that is currently in the Active Jobs database.
If more than one folder already exists while creating a sub-folder
in the Active Jobs database and the -FOLDER_ORD option is not
specified, the folder with highest order number is chosen.

-EMBEDDED_SCRIPT The Embedded script parameter contains the name of the file and
path, which enables the embedded script to be copied from a file.

-DEBUG Level of debug messages, 0 to 5.

Default: 0 (no debug messages).

-QUIET Indicates, if specified, that no informational messages are

displayed during the execution of the command.

-INPUT_FILE Name and full path of a file containing parameters for the utility.
In this file, each parameter and its values (if any) are on a
separate line with the same syntax they would have on the
command line. Using the -input_file parameter enables you to:
 Prepare and save files of utility parameters that can be
reused.
 Specify utility input longer than the number of characters
allowed in the command line.
-input_file
<controlm_owner>/ctm_server/data/ctmcr
eate_parms.txt

DOMAIL Sends mail when the job run is complete. Optional.

DOMAIL urgency="R"
destination="[email protected]"
cc="[email protected]" subject="OK"
message="Task completed OK."

destination Recipient of the message. String.

Mandatory.

cc Additional recipient of the message. String.

Optional.

195
Control-M Utilities Guide

Parameter Description

urgency Urgency of the message.

Valid values:
 R (regular - Default)
 U (urgent)
 V (very urgent)

subject Brief text description of the message

contents. String. Optional.

message Text of the message. String. Mandatory.

attach output Specifies at the job level whether the

OUTPUT should be sent as an email
attachment.
Valid values:
 Y – Yes
 N – No
 D – default (this means take the value
from the Control-M/Server
configuration file)

196
Control-M Utilities Guide

Parameter Description

TOLERANCE Maximum delay in minutes permitted for a late submission when

selecting a specific time (for example 5 minutes).
Valid range: 0-9991

CAPTURE Defines the job capture definitions. This parameter can be used to
search the output of a job for specified text and based on the
capture parameters, extract words or characters from the output.
The destination of the capture is a variable that can be set to any
of the following types:
 local
 global
 named pool
 smart folder

into Defines the target variable of the CAPTURE

action. Use one of the following variable types
to enter the variable name:
 %%varname - local variable
 %%\varname - global variable
 %%\\poolname\varname - named pool
 %%\\varname - smart folder
Maximum characters in variable name allowed:
38
Maximum characters in pool name allowed: 40
Default: No default, a value must be specified

search Defines the string in the output file to begin

the capture process.
Maximum characters in string allowed: 64
Default: No default, string must be specified

skiprows Defines the number of lines to skip from the

search string in the output file.
Maximum skip rows allowed: 99999999
Default: 0

197
Control-M Utilities Guide

Parameter Description

skipwords/skipch Defines the number of words or characters to

ars skip from the search string in the output file.
Select skipwords or skipchars.
Maximum skipwords/skipchars allowed:
99999999
Default: 0

delimiter (Only relevant for skipwords) Defines the

character type that marks the beginning/end of
the string.
Values:
 white space
 space
 tab
Default: white space

take Defines the string to capture.

Values:
 <number of characters>/<number of
words>
 0 - indicates until end of line
Maximum take words/characters: 4000
Default: (skipchars) 0
Default: (skipwords) 1

198
Control-M Utilities Guide

ctmcreate syntax rules

The following rules apply when using this utility:
 More than one parameter can be specified on a line.
 The odate parameter specifies the date to use as the job’s scheduling date. Specify a date in
yyyymmdd format, or specify ODAT to accept the Control-M system date.
 The %%NEXT, %%$NEXT, %%PREV, and %%$PREV variables cannot be specified for the ctmcreate
utility. These variables refer to the next or previous scheduling date and are not relevant for a utility
that places jobs directly in Active Jobs.
 The length of the command line, after decoding, must not exceed 999 characters.
 Although most parameters are optional, certain parameters are required depending on the value
specified for -tasktype.
 On computers that support Disk Clustering, the -hostgrp parameter is required (including either a host
group name, or the virtual name of the Control-M/Agent).
 All parameter fields (as specified in the syntax) must contain values. If no value is required, specify a
null string "" in the relevant position in the parameter specification.
EXAMPLE: The -domail parameter has the following syntax:
-domail <destination> <cc> <severity> <subject> <message>
To specify this command without a value for the cc field, include a null string in the appropriate
location.
EXAMPLE: -domail [email protected] "" R "subject line" "My message"
For more information, see information about setting Control-M/Server e-mail configuration parameters
in Email parameters.
 JOB and DETACHED require file name and file path parameters.
 COMMAND requires the cmdline parameter.
 Strings containing blanks must be enclosed in quotation (for example, -cmdline "ctmudlst list
payroll").
 A UNIX metasymbol (that must be enclosed in quotation marks) appearing in a command line string
should be enclosed in single quotation (for example, -cmdline "ctmcontb list ‘*’ ").
 If a parameter value begins with a $ sign, the operating system will try to replace the value. For
example, -jobname $USER will cause the shell to substitute the current user. If a parameter value
should contain a $ sign, enclose the value in single quotation marks. For example, -jobname ‘test$’
will set the jobname parameter to test$.
 A variable that does not contain a $ sign can be enclosed in single or double quotation marks. A
variable that does contain a $ sign should be enclosed in single quotation marks. A variable containing
a $ sign cannot be resolved if it is enclosed in double quotation marks.
 Condition dates are specified in mmdd format. Time is specified in hhmm format.

199
Control-M Utilities Guide

 A parameter requiring more than one entry can be repeated as many times as necessary (for
example, if a job must wait for several prerequisite conditions, specify a separate -incond parameter
for each prerequisite condition).
The following special characters are disabled when they occur in prerequisite condition names: ( ) |
[blanks]
 An -on parameter must be followed by at least one -do... parameter. -do... parameters are dependent
upon the last -on parameter preceding them. Normally, when a -dorerun parameter is implemented,
the current run of the job ends with NOTOK status. To ensure that the job will have OK status even
though it is rerun, specify a -do ok parameter immediately after the -dorerun parameter.
 The -dorerun parameter cannot be specified for a cyclic job.
 The order of the parameters does not affect the outcome of the job, with the exception of -on
and -do... parameters.
 When using -doforcejob to force an entire folder, <job name> must be specified as a blank enclosed
in quotation marks (that is, " ").
 When the ctmcreate utility is invoked from a script, to use the **** option for a -incond date
parameter, specify the parameter as \"****\"
 If a single character is specified for the priority parameter, the first character is assumed to be A. For
example, priority 1 is interpreted as priority A1.
 A maximum of 99 prerequisite conditions can be specified for docond parameters.
-incond pk_oly_ok "****"
 When the UNIX symbol ~ is used in parameter -filepath, -override path, or -doclib to represent the
user’s home directory, the entire parameter should be enclosed in double quotation marks. The
quotation marks ensure that the ~ symbol will be translated by the agent before submission, and not
by the server before transmission to the agent computer.
-file_path "~/controlm/scripts/"
For more information on ctmcreate parameters , see ctmcreate parameters (on page 192) , and
ctmcreate example.

ctmcreate - create a job in Active Jobs (simple) example

The following command contains the minimum parameters required to create a job in Active Jobs:
ctmcreate -TASKTYPE command -subapplication em\
-application test -cmdline "ls -l /etc/passwd"
You can get the same result by using the -input_file parameter as follows:
ctmcreate -input_file ~<controlm_owner>/ctm_server/data/ctmcreate_delfr.txt
The referenced file contains the following lines:
-tasktype command
-subapplication em
-application test
-cmdline "ls -l /etc/passwd"

200
Control-M Utilities Guide

ctmcreate - create a job in active jobs (advanced) example

The following command includes examples of most of the parameters that can be used to create a job in
Active Jobs:
ctmcreate -TASKTYPE JOB \
-cyclic N \
-description "Daily Summary" \
-subapplication SUPPLY -application SUPPLIES \
-file_path /users/ctm_server/ -file_name PROLYPAR -hostgrp UNIXGRP \
-jobname PROLYPAR \
-run_as suppman \
-odate 19981130 \
-timeuntil 1800 \
-priority AA -critical N \
-confirm Y \
-doclib /users/supply/doc/ -docmem prolypardoc \
-incond pk_oly_ok ODAT AND \
-incond pk_olp_ok ODAT AND \
-outcond pk_oly_ok ODAT DEL \
-outcond pk_olp_ok ODAT DEL \
-outcond pk_olypar ODAT ADD \
-variable %%PARM1 "%%CALCDATE %%ODATE -2" \
-quantitative tape 2 -quantitative cpu 50 \
-output MOVE /test/logs/ \
-control disk2 E \
-shout OK oper2 U "Daily summary completed" \
-on "COPY JWINFO_2507" "%COPY-E-OPENIN, error" \
-dooutput MOVE /oper/openerr

201
Control-M Utilities Guide

ctmcreate - create an empty SMART Folder

The following command creates an empty SMART Folder called myfolder:
ctmcreate -TASKTYPE FOLDER -FOLDER myfolder
The response is:
new ORDER created, orderid:00000b(11) for JOBNAME=myfolder.
The following command creates an empty Sub-folder called mysubfolder within the SMART folder called
myfolder:
ctmcreate -TASKTYPE SUBFOLDER -FOLDER myfolder/mysubfolder
The response is:
Attached to the SMART folder 'myfolder': 00000b(11)
new ORDER created, orderid:00000c(12) for JOBNAME=mysubfolder.

ctmdefine
The ctmdefine utility is an API (Application Program Interface) that adds a job processing definition to one
of the following in the Control-M/Server database:
 A Folder
 A SMART Folder
 A Sub-Folder
To run the ctmdefine utility, see Adding a job to a folder using the ctmdefine utility (on page 203).
This utility can be used when converting job scheduling information from other job control components to
Control-M/Server. The function performed by this utility is equivalent to the manual process of creating
job processing definitions, described in Job definition.
The ctmdefine utility can be invoked using the -input_file parameter:
-ctmdefine -input_file <fullPathFileName>
The referenced file contains all the required parameters. Most of the parameters are described in
Control-M Parameters and ctmdefine parameters (on page 207).
For more information on ctmdefine syntax rules, see ctmdefine syntax rules (on page 210).
The ctmdefine utility can also be used to define jobs for specific applications, for example, SAP and Oracle
Applications (OAP).
When creating new SMART folders or job processing definitions, the following considerations are
applicable:

202
Control-M Utilities Guide

 If the job name specified when using this utility already exists in a job processing definition in the
SMART Folder, the new job processing definition does not overwrite the existing one. Both job
processing definitions will appear in the folder, each with a different internal job number.
 If the SMART Folder specified when using this utility does not exist, the utility creates it.
 After using this utility to create one or more job processing definitions, download the modified SMART
Folders to the Control-M/EM database.
 A newly created SMART folder can be assigned a Order method parameter using the Control-M after
the folder is downloaded to the Control-M/EM database or by using the ctmpsm utility.
 Values for a creation/modification timestamp and the user ID of the user who created or modified the
job processing definition are automatically added to the communication protocol between
Control-M/EM and Control-M/Server and are stored in the Control-M/EM database. These values are
initialized by the ctmdefine utility and are sent to Control-M/EM when the SMART Folder is
downloaded. When the SMART Folder is uploaded, Control-M/EM sends these values to
Control-M/Server.
 When defining a job in a nested folder, a folder path to the intended nested folder must be specified
(-FOLDER option). The folder path starts from the outermost folder name and is similar to operating
system files and directories path. When a folder name is used and the folder does not exist, a folder is
created.
 If you define a new Rule-based calendar with the ! character at the beginning of the Rule-based
calendar name, the Rule-based calendar is excluded. If this feature is disabled, an error message is
displayed that you cannot define a Rule-based calendar with the ! character. For more information,
see DefaultCTMExcludeRBC in General parameters.

Adding a job to a folder using the ctmdefine utility

This procedure describes how to run the ctmdefine utility, which enables you to add a job processing
definition to a folder, a SMART folder, and a subfolder in the Control-M/Server database.
 To add a job using the ctmdefine utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Type the following command:
ctmdefine
-FOLDER <name>
-JOBNAME <name>
-TASKTYPE <JOB|EXTERNAL|DETACHED|COMMAND|DUMMY>
-SUB_APPLICATION <sub_application name>
-APPLICATION <applic name>
[ -CMDLINE <string> ]

203
Control-M Utilities Guide

[ -EMBEDDED_SCRIPT <file name> ]

[ -MAXRERUN <value> ]
[ -CRITICAL Y|N ]
[ -CYCLIC Y|N ]
[ -CYCLIC_TYPE INTERVAL|INTERVAL_SEQUENCE|SPECIFIC_TIMES ]
[ -INTERVAL <45d(days) | 1080h(hours) | 64800m (minutes)> ]
[ -SPECIFIC_TIMES <specific times string (HHMM,HHMM)> ]
[ -INTERVAL_SEQUENCE <interval sequence string e.g(+1H,+2M)> ]
[ -TOLERANCE <maximum delay allowed (minutes)> ]
[ -INTERVALFROM START | END | TARGET ]
[ -OVERRIDE_PATH <alternative directory> ]
[ -RELATIONSHIP AND|OR ]
[ -MAXWAIT <days> ]
[ -HOSTGRP <name> ]
[ -FILE_PATH <path> ]
[ -FILE_NAME <filename> ]
[ -MULTIAGENT Y|N ]
[ -ADJUST_COND Y|N ]
[ -RUN_AS <username> ]
[ -CREATED BY <username> ]
[ -DEBUG <debug level 0-5> ]
[ -QUIET ]
[ -TIMEZONE <xxx> ]
[ -TIMEFROM <earliest submission time> ]
[ -TIMEUNTIL <latest submission time> | '>' ]
[ -PRIORITY <job priority> ]
[ -CONFIRM Y|N ]
[ -TASKCLASS DISTRIBUTION_|DECOLLATION
[ -APPLTYPE <agent_application> ]
[ -APPLVER <application version> ]
[ -CMVER <CM version> ]
[ -APPLFORM <application form> ]
[ -DESCRIPTION <string> ]
[ -DOCMEM <filename> ]
[ -DOCLIB <directory name> ]
[ -INCOND <condition> <dateref>|ODAT AND|OR ]

204
Control-M Utilities Guide

[ -OUTCOND <condition> <dateref>|ODAT ADD|DEL ]

[ -VARIABLE <variable name as %%local, %%\global, %%\\smart or
%%\\pool\variable> <expression> ]
[ -QUANTITATIVE <name> <quantity> ]
[ -OUTPUT RELEASE|DELETE|COPY|MOVE [<parameter>]]
[ -CONTROL <name> E|S ]
[ -SHOUT OK|NOTOK|RERUN|LATESUB|LATETIME|EXECTIME <destination>
<urgency R|U|V> <message> [<time>] ]
[ -ON <statement> <code>
[ -DOOK ]
[ -DONOTOK ]
[ -DORERUN ]
[ -DOOUTPUT RELEASE|DELETE|COPY|MOVE [<parameter>] ] ]
[ -DOSTOPCYCLIC ]
[ -DOSHOUT <destination> <urgency R|U|V> <message> ]
[ -DOCOND <condname> <dateref>|ODAT ADD|DEL ]
[ -DOVARIABLE <variable name as %%local, %%\global, %%\\smart or
%%\\pool\variable> <expression> ]
[ -DOFORCEJOB <foldername> <jobname> <odate>|ODAT ]
[ -DOREMOTEFORCEJOB <foldername> <jobname> <odate>|ODAT ]
[ -ORDERVARIABLE <variable name as %%local, %%\global, %%\\smart or
%%\\pool\variable> <expression> ]
[ -DOMAIL <destination> <cc> <urgency R|U|V> <subject> <message> [<attach
output>] ]
[ -DOREMEDY <summary> <description> <urgency L|M|H|U|C> ]
[ -CAPTURE INTO <variable name as %%local,%%global,%%\\smart or
%%\\pool\variable>
SEARCH <Search string>
[ SKIPROWS <Number rows>]
[ SKIPWORDS <Number words> [DELIMITER <Character delimiter> TAKE <Number
words|0 until end>]|SKIPCHARS <Number characters> [TAKE <Number chars|0 until
end>]]]
[ -DAYS <daystr> ]
[ -WEEKDAYS <weekdaystr> ]
[ -MONTH ALL|JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC Y|N ]
[ -DATE <MMDD> ]
[ -DATEFROM <YYYYMMDD> ]
[ -DATEUNTIL <YYYYMMDD> ]
[ -DAYSCAL <calendar> ]

205
Control-M Utilities Guide

[ -WEEKCAL <calendar> ]
[ -CAL_ANDOR AND|OR ]
[ -SHIFT [</>/@][+/-]nn ]
[ -CONFCAL <calendar> ]
[ -RETRO Y|N ]
[ -RBC <rule_based_calendar> ]
If you define a new Rule-based calendar with the ! character at the beginning of the Rule-based calendar
name, the Rule-based calendar is excluded. If this feature is disabled, an error message is displayed that
you cannot define a Rule-based calendar with the ! character. For more information, see
DefaultCTMExcludeRBC in General parameters.
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmdefine parameters, see ctmdefine parameters (on page 207).

Defining application-specific Jobs

The ctmdefine utility can be used to define jobs for specific applications, for example, SAP and Oracle
Applications. These jobs are defined by setting the -appltype parameter to, for example, SAP or OAP.
The -file_name and -file_path parameters must also be specified for the ctmdefine utility when defining
application-specific jobs.
In addition to these parameters, you can specify application-specific parameters as variables. These
variables are described in detail in the SAP and Oracle Applications user guides.
ctmdefine -tasktype job -jobname sap1 -File_Name test -File_Path sap -VARIABLE %%SAPR3-JOB_MODE
CREATE -VARIABLE %%SAPR3-ACCOUNT DV2 -VARIABLE %%SAPR3-STEP-S01-PROGRAM
ZQA_SIMPLE -run_as sapr3 -VARIABLE %%SAPR3-STEP-S01-STEP_TYPE A -APPLTYPE SAP
-hostgrp nord -VARIABLE %%SAPR3-JOBNAME sap1 -folder SAP1 -application SAP1
-sub_application SAP1

206
Control-M Utilities Guide

ctmdefine parameters
The following table describes debug, quiet, and input_file parameters. For more details about the
parameters (for example, cyclic job parameters) are described in Control-M Parameters.

Parameter Description

-APPLICATION Provides a logical name for sorting groups of jobs. This parameter is
used to supply a common descriptive name to a set of related
groups of jobs.

-CREATED_BY Control-M/EM user who defined the job. String up to 64 characters.

Optional.
NOTE: This argument is used by the Control-M/Server security
mechanism and, under certain circumstances, cannot be modified.
For more information, see the Security chapter and the description
of the AuthorSecurity system parameter in GUI Server parameters.

-CAPTURE_SEARCH The search string from the capture output.

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

-quiet If specified, no information messages are displayed during execution

of the command.

-input_file Name and full path of a file containing parameters for the utility. In
this file, each parameter and its values (if any) are on a separate
line with the same syntax they would have on the command line.
Using the -input_file parameter enables you to:
 Prepare and save files of utility parameters that can be reused.
 Specify utility input longer than the number of characters
allowed in the command line.
EXAMPLE: -input_file
~<controlmOwner>/ctm_server/data/ctmdefine_parms.
txt

-CAPTURE Defines the job capture definitions. This parameter can be used to
search the output of a job for specified text and based on the
capture parameters, extract words or characters from the output.
The destination of the capture is a variable that can be set to any of
the following types:
 local
 global
 named pool
 smart folder

207
Control-M Utilities Guide

Parameter Description

into Defines the target variable of the CAPTURE

action. Use one of the following variable
types to enter the variable name:
 %%varname - local variable
 %%\varname - global variable
 %%\\poolname\varname - named pool
 %%\\varname - smart folder
Maximum characters in variable name
allowed: 38
Maximum characters in pool name allowed:
40
Default: No default, a value must be
specified

search Defines the string in the output file to begin

the capture process.
Maximum characters in string allowed: 64
Default: No default, string must be specified

skiprows Defines the number of lines to skip from the

search string in the output file.
Maximum skip rows allowed: 99999999
Default: 0

skipwords/skipchars Defines the number of words or characters

to skip from the search string in the output
file.
Maximum skipwords/skipchars allowed:
99999999
Default: 0

208
Control-M Utilities Guide

Parameter Description

delimiter (Only relevant for skipwords) Defines the

character type that marks the
beginning/end of the string.
Values:
 white space
 space
 tab
Default: white space

take Defines the string to capture.

Values:
 <number of characters>
 0 - indicates until end of line
Maximum take words/characters: 4000
Default: (skipchars) 0
Default: (skipwords) 1

-DOMAIL Sends mail when the job run is complete. Optional.

DOMAIL urgency="R"
destination="[email protected]"
cc="[email protected]" subject="OK"
message="Task completed OK."

destination Recipient of the message. String.

Mandatory.

cc Additional recipient of the message. String.

Optional.

urgency Urgency of the message.

Valid values:
 R (regular - Default)
 U (urgent)
 V (very urgent)

subject Brief text description of the message

contents. String. Optional.

message Text of the message. String. Mandatory.

209
Control-M Utilities Guide

Parameter Description

attach output Specifies at the job level whether the

OUTPUT should be sent as an email
attachment.
Valid values:
 Y – Yes
 N – No
 D – default (this means take the value
from the Control-M/Server configuration
file)

ctmdefine syntax rules

The following syntax rules apply for this utility:
 More than one parameter can be specified on a line.
 Keywords can be written in either uppercase or lowercase, but parameter values are case sensitive.
EXAMPLE: -sub_application ACCGROUP and -SUB_APPLICATION ACCGROUP
specify the same sub application ACCGROUP.
-sub_application accgroup
specifies a different sub application accgroup.
 For the -month parameter, specify the first three letters of a month (for example, JAN) or ALL for all
months (the default is none). To specify two or more individual months, use a separate -month
parameter for each month.
 If a single character is specified for the priority parameter, the first character is assumed to be A. For
example, priority 1 is interpreted as priority A1.
 The length of the command line, after decoding, must not exceed 999 characters.
 Although most parameters are listed as optional, certain parameters may be required, depending on
the option specified for parameter -tasktype.
 All task types require the sub application and application parameters.
• TASKTYPE JOB and DETACHED require parameters file name and file path.
• TASKTYPE COMMAND requires parameter cmdline.
• FOLDER requires the RBC (Rule-based calendar) parameters. Each RBC definition is followed by
its scheduling parameters. If a Rule-based calendar is defined with the ! character at the
beginning of the Rule-based calendar name, the Rule-based calendar is excluded. If this feature is
disabled, an error message is displayed that you cannot define a Rule-based calendar with the !
character. For more information, see DefaultCTMExcludeRBC in General parameters.
EXAMPLE:

210
Control-M Utilities Guide

-rbc myrbc1
-maxwait 1
-days 0,2,3
-dayscal cal1
 Strings containing blanks must be enclosed in quotation marks (for example, -cmdline "ctmudlst list
payroll").
 A UNIX metasymbol (that must be enclosed in quotation marks) in a command line string should be
enclosed in single quotation (for example, -cmdline "ctmcontb list ‘*’ ").
 If a parameter value begins with a $ sign, the operating system will try to replace the value. For
example, -jobname $USER will cause the shell to substitute the current user. If a parameter value
should contain a $ sign, enclose the value in single quotation marks. For example, -jobname ‘test$’
will set the jobname parameter to test$.
 A variable that does not contain a $ sign can be enclosed in single or double quotation marks. A
variable that does contain a $ sign should be enclosed in single quotation marks. A variable containing
a $ sign cannot be resolved if it is enclosed in double quotation marks.
 Condition dates are specified in mmdd format. Time is specified in hhmm format.
 On computers that support Disk Clustering, the -hostgrp parameter is required (including either a host
group name, or the virtual name of the Control-M/Agent).
 A parameter requiring more than one entry can be repeated as needed:
• If a job is dependent upon several prerequisite conditions, specify a separate -incond parameter
for each prerequisite condition.
• If a job can run only in January and July, specify a separate -month parameter for each month.
(For example, -month ALL N -month JAN Y -month JUL Y.)
• If a job should run every month except July, specify -month ALL Y and -month JUL N.
• If a job is in a SMART Folder and is scheduled according to the FIRSTDAY and SALARY1
Rule-Based Calendars, specify –RBC FIRSTDAY –RBC SALARY1.
 The default for the -month parameter is ALL Y, which means that if you want to define a job that
should run only in one specific month, you must first indicate that it should not run on any month. For
example: -month ALL N -month NOV Y
 An -on parameter must be followed by at least one -do parameter.
 Additional post-processing conditions can be set by using -on <statement> <code>.
EXAMPLE: On statement: *
Code: RUNCOUNT>4
Do Shout: To: Control-M/EM
Text: "Job ran more than four times"

211
Control-M Utilities Guide

 -do parameters are dependent upon the last -on parameter preceding them.
 The order of parameters does not affect the outcome of the job, with the exception of -on and -do...
parameters.
 All fields of each parameter (as specified in the syntax section) must contain values. If no value is
required for a parameter field, a null string "" must be specified in the relevant position in the
parameter specification.
EXAMPLE: The -domail parameter has the following syntax:
-domail <destination> <cc> <severity> <subject> <message>
EXAMPLE: To specify this command without a value for the cc field, include a null string in the
appropriate location. For example:
-domail [email protected] "" R "subject line" "My message"
 Normally, when a -dorerun parameter is implemented, the current run of the job ends with NOTOK
status. To ensure that the job will have an OK status, even though it is rerun, specify a -dook
parameter immediately after the -dorerun parameter.
 The -dorerun parameter cannot be specified for a cyclic job.
 When using -doforcejob to force an entire folder, <job name> must be specified as a blank enclosed
in quotation marks (that is, " ").
 IN condition statements that use complex boolean logic can be specified.
For more information, see the description of the In Condition parameter in Control-M Parameters.
 When ctmdefine is invoked from a script: To use the **** option for a -incond date parameter,
specify this parameter as "****"
-incond pk_oly_ok "****"
 When the UNIX symbol ~ is used in a -memlib, -override path, or -doclib parameter to represent the
user’s home directory, the entire parameter should be enclosed in double quotation marks, which
ensures that the ~ will be translated by the agent before submission, and not by Control-M/Server
before transmission to the agent computer.
-memlib "~/controlm/scripts/"
 A maximum of 99 prerequisite conditions can be specified for docond parameters.
 Condition names using both open and closed square brackets ([ and ]) must be enclosed in quotation
marks (for example, "RATE[A1]").
The following special characters are disabled when they occur in prerequisite condition names:
• ( open parenthesis
• ) close parenthesis
• | vertical bar
• space

212
Control-M Utilities Guide

 The -shift parameter has been extended to four characters (xyyy). The first character (x) indicates
how to shift scheduling of the job if the original scheduling day of the job is not a working day in the
CONFCAL calendar. Valid values are:
• "" (Blank) – No shifting occurs. The job is not scheduled. Default.
• > – Job scheduling is shifted to the next working day in the CONFCAL calendar. Additional
shifting may be performed, depending on the yyy value, described below.
• < – Job scheduling is shifted to the previous working day in the CONFCAL calendar. Additional
shifting may or may not be performed, depending on the yyy value, described below.
• @ – Tentatively schedule the job for the current day, even if the current day is not a working
day in the CONFCAL calendar. Additional shifting may or may not be performed, depending on the
yyy value, described below.
The remaining three characters (yyy) shift scheduling of the job forward or backward the specified
number of working days, as defined in the CONFCAL calendar. Valid values are:
o Blank - no shifting occurs
o -nn or +nn shifts the job forward or backward nn working days in the CONFCAL calendar. nn
can be any value from 0 to 62.
NOTE:
 If the result of shifting by yyy days is a day that is not allowed (-n was entered for that day in the
DAYS parameter), the job is shifted to the next working day (for a forward shift), or to the
previous working day (for a backward shift).
 If the original scheduling day of the job is a working day in the CONFCAL calendar, the x value is
ignored and the yyy value determines when the job is scheduled.
 If the original scheduling day of the job is not a working day in the CONFCAL calendar, job
scheduling is shifted according to the x value and then shifted again according to the yyy value (if
specified) to determine when the job is scheduled.
 If the original scheduling day of the job is not a working day in the CONFCAL calendar, and no
value (blank) is specified for the x value, the job is not scheduled, and the yyy value (if specified)
is ignored.
 Confcal and Shift parameters are applied to a scheduling date only if that date already satisfies
the Basic Scheduling criteria as specified in the Days, Months, Dates, and Weekdays parameters.
For more information on the parameters for the ctmdefine utility, see ctmdefine parameters (on page
207).

ctmdefine examples
The following command contains the minimum parameters required to define a job:
ctmdefine -folder cmmnds -jobname cmls13 \
-tasktype command -sub_application em -application test \
-date 0101 -cmdline "ls -l /etc/passwd"
You can get the same result by using the -input_file parameter as follows:
ctmdefine -input_file ~<controlm_owner>/ctm_server/data/ctmdefine_cmmnds.txt

213
Control-M Utilities Guide

The referenced file (ctmdefine_cmmnds.txt) contains the following lines:

-folder cmmnds
-jobname cmls13
-tasktype command
-sub_application em
-application test
-date 0101
-cmdline "ls -l \etc\passwd"
The following command includes examples of most of the parameters that be used to define a job:
ctmdefine -tasktype JOB -cyclic N\
-folder djsales -jobname dj102\
-description “Daily Summary"\
-sub_application SUPPLY -application SUPPLIES\
-file_path /users/ctm_server/ -file_name PROLYPAR -nodegrp UNIXGRP\
-run_as suppman\
-month ALL N\
-month MAR Y -month JUN Y -month SEP Y -month DEC Y\
-timeuntil 1800\
-priority AA -critical N\
-confirm Y\
-doclib /users/supply/doc/ -docmem prolypardoc\
-incond pk_oly_ok ODAT AND\
-incond pk_olp_ok ODAT AND\
-outcond pk_oly_ok ODAT DEL\
-outcond pk_olp_ok ODAT DEL\
-outcond pk_olypar ODAT ADD\
-variable %%PARM1 “%%CALCDATE %%ODATE -2"\
-quantitative tape 2 -quantitative cpu 50 \
-output MOVE /test/logs/\
-control disk2 E\
-shout OK oper2 U “Daily summary completed"\
-on “COPY JWINFO_2507” “%COPY-E-OPENIN, error"\
-dooutput MOVE /oper/openerr/\
-on “*” notok\
-dorerun\
-doshout em v “Daily summary failed. Attempting rerun"

214
Control-M Utilities Guide

ctmexdef
The ctmexdef utility exports job processing definitions from the Control-M/Server database to a flat
(ASCII) file. This file can then be used as input for either the ctmcreate utility or the ctmdefine utility.
The ctmexdef utility can be used to:
 Modify existing job processing definitions in batch mode (together with the ctmdefine utility). The job
processing definitions in the file exported by ctmexdef can be edited offline and then returned to the
Control-M/Server database by using ctmdefine. For more information, see ctmdefine (on page 202).
 Creating specific purpose jobs to be inserted in the Active Jobs database based on previously defined
jobs. Together with the ctmcreate utility, the ctmexdef utility can copy and modify job processing
definitions in batch mode that can then be sent directly to the Active Jobs database by using
ctmcreate. See ctmcreate (on page 189) for a complete description of the utility.
To run the ctmexdef utility, see Exporting jobs using the ctmexdef utility (on page 215).
When working on UNIX, the utf8 file stores the script. No translation is performed by the utility when
being read into memory. In Windows, that store the script is native. Translation to utf8 needs to be
performed by either the ctmcreate or ctmdefine when being read into memory.
The output of ctmexdef on Windows cannot be used as input on UNIX installations and the other way
around.
For more information on ctmexdef syntax rules, see ctmexdef syntax rules (on page 216).

Exporting jobs using the ctmexdef utility

This procedure describes how to run the ctmexdef utility, which enables you to export job processing
definitions from the Control-M/Server database to a flat (ASCII) file
 To export jobs using the ctmexdef utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctmexdef
-FOLDER <name>
-JOBNAME|-FILE_NAME <name>
[ -ACTION <DEFINE|CREATE> ]
[ -FILE <filename> ]
[ -WORKING_DIR <working directory> ]
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmexdef parameters, see ctmexdef parameters (on page 216) .

215
Control-M Utilities Guide

ctmexdef parameters
The following table lists debug, quiet, and input_file parameters for the ctmexdef utility. All other
parameters (for example, cyclic job parameters) are described in Control-M Parameters.

Parameter Description

-ACTION DEFINE – The exported file will be in ctmdefine format. Default.

CREATE – The exported file will be in ctmcreate format.

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

-JOBNAME Name of the job.

-FILE_NAME File name of the job.

-FOLDER Name of the SMART Folder or of the job. Either the JOBNAME or
FILE_NAME parameter is required.

-WORKING_DIR Contains embedded script files. The name of each file consists of a
SMART Folder name, job name, and time stamp. The embedded script
only appears for jobs that have the in-line script turned on.

ctmexdef syntax rules

The <name> and <file_name> parameters can include the following wildcard characters:
 Represents any number of characters (including none). Any parameter including ∗ should be enclosed
in quotation marks (see example below).
 Represents any single character.
To export all job processing definitions from SMART Folder PROD to file tabprod, specify the following
command:
ctmexdef -FILE /tmp/tabprod -FOLDER PROD -JOBNAME "*"

216
Control-M Utilities Guide

ctmfw File Watcher utility

The ctmfw (Control-M File Watcher) utility, enables you to detect the successful completion of a file
transfer activity and to create or delete a file. You can use it before activating a job or before performing
another activity, such as sending a shout message or adding/deleting conditions, which is dependent
upon a created file.
The ctmfw utility runs as a process on a client platform. The process waits for the creation or deletion of a
specified file. For file transfer activity, when the file is detected, the job continues to monitor the size of
the file. When the file reaches a specified minimum size and does not increase in size for a specified
period of time, the File Watcher utility either finishes with a status of OK or executes a specified DO
action. DO actions can consist of adding or deleting conditions or executing a command. For file creation,
the file size is ignored if a wildcard is specified as part of the file name unless the mon_size_wildcard
parameter is set to Y. For file deletion, ctmfw must first detect the existence of the file before it can
detect its deletion.
The ctmfw utility can be run from the command line or be invoked to detect a single file or multiple files.
For more information, see Watching a single file (on page 217) and Watching multiple files (on page 221).
NOTE: You can create a File Watcher job, as described in Creating a job, by using the File Watcher job
parameters. Variables can be used in parameter fields.
There are two usages for this utility:
 Service: ctmfw takes its parameters (rules) during startup from the rull.dat file whose full path
name is specified in <Control-M/Agent>\data\ctmfw.cfg. To change one or more rules, change
the contents of the rull.dat file. The rull.dat file provided with Control-M/Agent is a sample file and
must be changed to reflect your requirements. For more information, see File Watcher job
parameters.
If you want the FileWatcher to detect network resources, configure the FileWatcher service to run
under a regular user account instead of Local System Account. The execution log file
U_CTMFW_<process_id>.log is saved in the Control-M/Agent proclog directory.
 When running as a utility, ctmfw is invoked from the command line. Rules can be provided in the
command line or by a rule file. For more information about the rules file, see ctmfw rule file (on page
221).
 To allow other users to run ctmfw, they must have write permissions to $CONTROLM and the
CONTROLM environment variable must be set. For more information, see Running Control-M/Agent
utilities as other users (on page 21).
For details about ctmfw processing and return codes issued after detecting if a file is created or deleted in
the specified time frame, see ctmfw utility processing (on page 223) and Return codes (on page 228).
To view a detailed File Watcher overview video, see (https://www.youtube.com/watch?v=iZZCUWOQt-E).

Watching a single file

This procedure describes how to watch a single file with the ctmfw File Watcher utility. Rules can be
provided in the command line or by a rule file.
 To watch a single file:
 Open a command prompt and type the following command:
ctmfw FILE (absolute path)

217
Control-M Utilities Guide

< mode (CREATE|DELETE)> Default: CREATE

< minimum detected size <number>
[' '|Bytes(B)|Kilo(K)|Mega(M)|Giga(G)] >Default:0
< interval between file search (seconds) > Default: 60sec
< interval between filesize comparison iterations (seconds) >
Default: 10sec
< number of iterations while the size is static > Default: 3
iterations
< time limit for the process (minutes).> Default: 0 (no time limit)
Effective while the file does not exists or,
the file size is static and the minimum size
was not reached >
< monitor file size , minimal and maximal age, when wildcard is used
> Default: N
< starting time for detecting files (HHMM or YYYYMMDDHHMM > Default:
NOW
< absolute stop time (HHMM or YYYYMMDDHHMM > Default: +0000 ( No stop
time )
< minimal age of file (modified time)
format:xxxxYxxxxMxxxxDxxxxHxxxxMin > Default: NO_MIN_AGE
< maximal age of file ( timestamp monitoring )
format:xxxxYxxxxMxxxxDxxxxHxxxxMin > Default: NO_MAX_AGE
For more information about the ctmfw parameters, see ctmfw parameters (on page 219).
NOTE: All parameters must be assigned a value, even if that value is zero. If only six values are
specified, the default value for mon_size_wildcard is used. If five parameters are specified, default
values for wait_time and mon_size_wildcard are used.
EXAMPLE: ctmfw /home/watchedfile.txt CREATE 100 10
is resolved by using default values for mon_int, min_detect, wait_time, and
mon_size_wildcard as follows:
ctmfw /home/samplefile.txt CREATE 100 10 10 3 0 N

218
Control-M Utilities Guide

ctmfw parameters
The following table lists the ctmfw utility rules file parameters:

Parameter Description

FILE Path of the file to be detected. The file name can include wildcard character * to
represent any number of characters (including no characters) or ? to represent any
one character.
NOTE: The path and file name must not exceed 214 characters.

mode CREATE Detects creation of a file. Default. File size is ignored if the filename
parameter contains wildcards (unless the monitor file size when
wildcard is used parameter is set to Y).

NOTE: If a mask is specified for the filename, and the monitor file size
when wildcard is used parameter is set to:
 N, the ctmfw utility will end OK after detection of the first file that
matches the specified mask.
 Y, the ctmfw utility will end OK after detection of the first file that
matches the filename and file size.

For more information about monitor file size when wildcard is

used, see below.

DELETE Detects deletion of a file. When the ctmfw utility is run in this mode, it
first checks for files that match the specified name. After a specified file
is detected, the ctmfw utility checks at the specified interval for deletion
of that file.

NOTE: If a mask is specified as the filename, the ctmfw utility will end
successfully only after all detected files that match the specified mask
have been deleted.

mode CREATE Detects creation of a file. Default. File size is ignored if the filename
parameter contains wildcards (unless the monitor file size when
wildcard is used parameter is set to Y).

NOTE: If a mask is specified for the filename, and the monitor file size
when wildcard is used parameter is set to:
 N, the ctmfw utility will end OK after detection of the first file that
matches the specified mask.
 Y, the ctmfw utility will end OK after detection of the first file that
matches the filename and file size.

For more information about monitor file size when wildcard is

used, see below.

219
Control-M Utilities Guide

Parameter Description

DELETE Detects deletion of a file. When the ctmfw utility is run in this mode, it
first checks for files that match the specified name. After a specified file
is detected, the ctmfw utility checks at the specified interval for deletion
of that file.

NOTE: If a mask is specified as the filename, the ctmfw utility will end
successfully only after all detected files that match the specified mask
have been deleted.

minimum detected Minimum file size in bytes. This parameter is ignored if the FILE parameter contains
size wildcards (unless the monitor file size when wildcard is used parameter is set to
Y) or if the mode parameter is set to DELETE. Default: 0 (any size detected).

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

interval between Interval between attempts to monitor the size of a file after it is detected (in
filesize comparison seconds). This parameter is ignored when using wildcards in FILE or when using
iterations DELETE mode. Default: 10

number of iterations Number of attempts to monitor file size where the size remains static and greater than
while size is static or equal to minimum detected size (indicating successful creation of the file). This
parameter is ignored when using wildcards in FILE or when using DELETE mode.
Default: 3

time limit for the Maximum time (in minutes) to run the process without detecting the file at its
process minimum size (CREATE) or detecting its deletion (DELETE). If the file is not
detected/deleted in this specified time frame, the process terminates with an error
return code, as described in Return codes (on page 228). Default: 0 (no time limit).

monitor file size Indicates whether file size should be monitored if the filename contains wildcards.
when wildcard is This parameter is ignored if the filename does not contain a wildcard. Valid values:
used
 N – do not monitor file size (Default)
 Y – monitor the file size
If this parameter is set to Y and more than one file matches the specified mask, the
ctmfw utility selects the first file that is detected, monitors its file size, and ignores all
other matching files.

starting time for Indicates an absolute time at which the utility starts monitoring the file. For example,
detecting files 200712061400, means that at 2 PM on December 6th, 2007 the FileWatcher utility will
start watching the file.
Alternatively, you can use the HHMM format, in which case the current date is used.

220
Control-M Utilities Guide

Parameter Description

absolute stop time Indicates an absolute time at which the file is no longer watched. For example,
200702061400, would mean that at 2 PM on February 6th, 2007 the FileWatcher
utility will stop watching the file.
Alternatively, you can use the HHMM format, in which case the current date is used.

maximal age of file Indicates the maximum amount of time that can pass since the file you want to watch
was last modified. For example, 2y3d5h means that after 2years, 3 days, and 5 hours
has passed, the file will no longer be watched. Entering a value of 2H10Min, means
that after 2 hours and 10 minutes has passed, the file will no longer be detected.
This parameter is ignored if the mode parameter is set to DELETE. Default: 0

minimal age of file Indicates the minimum amount of time that must have passed since the file you want
to watch was last modified. For example, 2y3d5h means that 2years, 3 days, and 5
hours must pass before the file will be watched. Entering a value of 2H10Min, means
that 2 hours and 10 minutes must pass before the file will be detected.
This parameter is ignored if the mode parameter is set to DELETE. Default: 0

Watching multiple files

This procedure describes how to watch multiple files with the ctmfw File Watcher utility.

 To watch multiple files:

 Type the following command to invoke the ctmfw utility for multiple files:
ctmfw -input <ruleFileName>
The variable <ruleFileName> is the complete path name of the file containing the definitions for each
file to be detected. For more information about Rule files see ctmfw rule file (on page 221).

ctmfw rule file

The Rules file contains the following sections:
 Global parameters, whose default values apply to all the files in the rule file. For more information,
see ctmfw rules file global parameters (on page 222).
 ON_FILEWATCH statements identifying which files to detect, specific criteria for each file, and the
action to take upon detection or non-detection. Any number of ON_FILEWATCH statements can
appear in a Rules file. For more information about ON_FILEWATCH parameters, see ctmfw
parameters (on page 219).
If any mandatory parameter is omitted from a Rules file, the default value for that parameter is used.
Parameters entered for ON_FILEWATCH statements override the default values. If entered, they must
appear in the order shown in Example rule file (on page 224).

221
Control-M Utilities Guide

ctmfw rules file global parameters

The following table lists the ctmfw rules file global parameters:

Parameter Description

CYCLIC_INTERVAL Indicates the interval between multiple operations of detecting the file (in minutes).
This interval must be greater than the value for WAIT_TIME. If the cyclic_interval is
0, only one attempt to detect the file will be performed. Default: 0

FROM_TIME Starting time for detecting all the files (default FROM_TIME). Used with WAIT_TIME
to identify the time frame for detecting and monitoring the files. This parameter is
expressed in 24-hour, hhmm format. Default: 0000 or Now

INTERVAL Sleep interval (in seconds) between successive scans for all the files. This parameter
replaces individual sleep_int and mon_int parameters for each file. Default: 10

MAX_AGE Indicates the maximum amount of time that can pass since the file you want to
watch was last modified.
 If MAX_AGE = 0, any change to the file timestamp means that the condition is
met.
 IF MAX_AGE = 10 Min and if the amount of time of the watched file that has
passed is less than 10 minutes, then the condition is met.
This parameter is ignored if the mode parameter is set to DELETE.
Default: 0

MIN_AGE Indicates the minimum amount of time that must have passed since the file you
want to watch was last modified. For example, 2y3d5h means that 2years, 3 days,
and 5 hours must pass before the file will be watched.
This parameter is ignored if the mode parameter is set to DELETE. Default: 0

MIN_SIZE Minimum file size in bytes. This parameter is ignored if the FILE parameter contains
wildcards (unless the monitor file size when wildcard is used parameter is set to Y)
or if the mode parameter is set to DELETE. Default: 0 (any size detected).

MON_SIZE_ Indicates whether file size should be monitored if the filename contains wildcards.
WILDCARD This parameter is ignored if the filename does not contain a wildcard.
Valid values:
 N – do not monitor file size (Default)
 Y – monitor the file size
If this parameter is set to Y and more than one file matches the specified mask, the
ctmfw utility randomly selects one matching file, monitors its file size, and ignores all
other matching files.

222
Control-M Utilities Guide

Parameter Description

STOP_TIME Indicates an absolute time at which the file is no longer watched. For example,
200702061400, means that at 2 PM on February 6th, 2007 the FileWatcher utility will
stop watching the file.
You can also use the HHMM format, which uses the current date, plus the HHMM
entered. Default: 0 (meaning, no stop time)
NOTE: STOP_TIME can only be used as a global parameter.

WAIT_TIME Maximum time (in minutes) to run the process without detecting the file at its
minimum size (CREATE) or detecting its deletion (DELETE). If the file is not
detected/deleted in this specified time frame, the process terminates with an error
return code, as described in ctmfw- return codes table below.. Default: 0 (no time
limit).

ctmfw utility processing

If the file is detected and the size remains static within the time frame (CREATE) or the file has been
deleted (DELETE), the DO commands in the THEN block are executed. If the file is not detected/deleted
within the time frame, the statements following the ELSE block are executed.
CTMFW terminates when either all the files in the Rules file have been processed or a DO_OK/DO-NOTOK
action is executed. If any ON_FILEWATCH statement contains a cyclic_interval, CTMFW only terminates
on a DO_OK/DO-NOTOK action.
EXAMPLE: CTMFW detects the creation of the specified file, prerequisite condition DATAFILE with an
ODAT of 0101 is added, and the created file is moved to the DAILYBK3 subvolume.
Otherwise, the same condition is deleted and a file with the same name is created with a
record length of 132. If CTMFW detects the deletion of the specified file, the same
prerequisite condition is deleted.
#*****************************************************************
*
INTERVAL 10
WAIT_TIME 1
ON_FILEWATCH $DATA02.DAILYBK.DATAFILE CREATE
THEN
DO_COND DATAFILE 0101 +
DO_CMD FUP RENAME DAILYBK.DATAFILE, DAILYBK3.DATAFILE, PURGE
ELSE
DO_COND DATAFILE 0101 -
DO_CMD FUP CREATE DAILYBK3.DATAFILE, REC 132
END_ON

223
Control-M Utilities Guide

ON_FILEWATCH $DATA02.FTPLIB.TEMPFILE DELETE

THEN
DO_COND TEMPFILE 0101 -
END_ON
#*****************************************************************
**

Example rule file

The following displays an example rule file. In this sample:
 # indicates comments.
 Default values are shown for all global parameters.
 <action> refers to any of the actions described in ctmfw-valid actions below. For more information
about ctmfw actions, see ctmfw – valid actions (on page 226).
#******************************************************************
# Global Parameters
INTERVAL <60> # Sleep interval (seconds)
MIN_SIZE 4Kilo
MIN_AGE 3M24D4h5min
FROM_TIME <0000> # Starting time for all files (hhmm)
MIN_SIZE <0> # Minimum size for all files (bytes)
MIN_DETECT <3> # Number of iterations for all files
WAIT_TIME <0> # Time limit for all files (minutes)
# ON_FILEWATCH statements
ON_FILEWATCH <fileName>(absolute path) [CREATE/DELETE] [min_size]
[min_detect] [wait_time]
[start_time] [cyclic_interval] [wildcards] [minimal_file_age]
THEN
<action>
ELSE
<action>
END_ON
#******************************************************************
If a wildcard is used in the file name, the found file can be referenced as %FILENAME%.

224
Control-M Utilities Guide

EXAMPLE:
INTERVAL 10
ON_FILEWATCH /controlm/datafile*.txt CREATE
THEN
DO_COND %FILENAME% 0101 +
NOTE: All global parameters must be delimited by the new line character.

Example - watching multiple conditions contained in rule file

The ctmfw utility is invoked to watch multiple conditions. The definitions the ctmfw utility uses for
watching each file contained in a rule file.
The following instructions are defined in the Rules file:
 The sleep interval between succeeding scans must be 10 seconds.
 If the ctmfw utility detects that the datafile.txt file in the /home/controlm directory is created in
the specified time interval, then:
• the datafile condition dated 1 January must be added.
• the command interpreter must execute the command to move the contents of the
~<controlm_owner>/ctm_server/datafile.txt file to
~<controlm_owner>/ctm_server/workfile.txt.
 If the ctmfw utility detects that the datafile.txt file in the ~<controlm_owner>/controlm
directory is not created in the specified time interval, then condition datafile dated 1 January must be
deleted.
 When the ctmfw utility detects that the ~<controlm_owner>/ctm_server/tempfile.txt file
is deleted, condition tempfile dated 1 January must be deleted.
#******************************************************************
INTERVAL 10
ON_FILEWATCH ~<controlm_owner>\ctm_server\datafile.txt CREATE
THEN
DO_COND datafile 0101 +
DO_CMD move \ctm\datafile.txt \ctm\workfile.txt
ELSE
DO_COND datafile 0101 -
END_ON
ON_FILEWATCH \ctm\tempfile.txt DELETE
THEN
DO_COND tempfile 0101 -
END_ON
#****************************************************************

225
Control-M Utilities Guide

ctmfw – valid actions

The following table lists the ctmfw valid actions:

Action Description

DO_CMD <command> Execute a valid command under the command interpreter.

Full path names are required for files.

DO_COND <condition name> Add (+) or delete (-) a condition.

<condition date> <+|->

DO_EXIT [exit code] Terminate ctmfw with the user-defined exit code.

DO_NOTOK [exit code] Terminate an ON_FILEWATCH statement with status

NOTOK. Exit code is optional and replaces the standard
return code, as described in the ctmfw-return codes table
below.

DO_OK Terminate an ON_FILEWATCH statement with status OK. If

there is more than one file in the Rule file, the result
displayed is that of an AND algorithm.

NOTE: If the file is detected and the size remains static within the time frame (CREATE) or the file has
been deleted (DELETE), the DO commands in the THEN block are executed. If the file is not detected or
deleted within the time frame, the statements following the ELSE block are executed. ctmfw terminates
when all the files in the Rules file have been processed.
If an ON_FILEWATCH statement contains a cyclic_interval parameter, ctmfw will only stop monitoring a
file on a DO_OK or DO_NOTOK action.

Example -job processing definition for ctmfw utility

A job processing definition is created to implement a FileWatcher job. The file must arrive between 19:00
and 22:00, and be created in the /tmp directory under the name trans.dat. The minimum file size is
100 bytes. The detection process should be performed each minute. The file size is monitored every
10 seconds, and the number of intervals where the file size remains static is 5. If the file is not detected
by 22:00, an alert should be sent to Control-M/EM.

226
Control-M Utilities Guide

The following table describes the ctmfw parameters:

Parameter Value

Job Name FileWatch

File Name FileWatch

Run as <control_m_user>

From Time 1900

Command line ctmfw "\tmp\trans.dat" CREATE 100 60 10 5 180

On Statement/Code processing:

Stmt *

Code COMPSTAT=0

Do Cond file_trans_dat_ok Date: ODAT Sign: +

Stmt *

Code COMPSTAT=1

Do Shout To: Control-M/EM

Text: "File trans.dat did not arrive on time"

227
Control-M Utilities Guide

Return codes
The return codes listed in the following table are issued by the ctmfw utility after detecting if a file is
created or deleted in the specified time frame.

Return code Description

0 File was successfully created or deleted (file arrived in the specified

time frame and file size is above or equal to the minimum specified
size).

1  Utility failed, for example, because of a syntax error.

 A DO_NOTOK statement occurred, but no user-defined exit code
was provided for the DO_NOTOK statement.

7 Indicates that the ctmfw request timed out. That is, the file was not
detected in the specified time frame.

FileWatcher silent mode registry key

The FileWatcher service does not open an additional window during execution. If you want visual
feedback while running the service, the following registry key setting must be changed to N.
HKEY_LOCAL_MACHINE\SOFTWARE\BMC_Software\
Control-M\FileWatcher\SYSPRM\Silent_Mode

ctmimptb
The ctmimptb utility imports folders (including SMART Folders and Rule-Based Calendars) containing job
definitions that were exported from Control-M/EM by the exportdeffolder utility. To run the ctmimptb
utility, see Importing folders using the ctmimptb utility (on page 229).
The ctmimptb utility gets the exported XML file that was created by exportdeffolder (on page 298) in
Control-M/EM, and imports the folders into the Control-M/Server database. This utility can overwrite
existing folders when overwrite mode is specified.
The ctmimptb utility works at the folder level only and cannot import a specific job or jobs from a folder.
The utility can import Sub-folder entities and Sub-folders jobs, but cannot import Sub-folders individually.
The Sub-folders must be imported as part of SMART folders.
The Control-M/EM exportdeffolder utility cannot define an empty folder. Therefore, the ctmimptb utility
cannot perform an action that will cause folders to become empty. If you duplicate SMART Folders in the
XML input file, when overwrite mode is specified, the last SMART Folder is considered and overwrite mode
is not specified and the SMART Folder does not exist in the database, the first defined SMART Folder is
considered.

228
Control-M Utilities Guide

When a job definition folder in the input XML file is large, importing this folder is performed by a few
transactions. The number of jobs within each transaction is specified by the CTMIMPTB_ENT_IN_TRANS
parameter that is defined in the
~controlm/ctm_server/data/config.dat file. If the CTMIMPTB_ENT_IN_TRANS parameter is not
specified in the config.dat file. The value range is 5–10,000 jobs and the default value 1,000 jobs.
The following describes the results of the import procedure:
 In the event of a successful import, the utility exits with a success return value. If the utility was
invoked without overwrite mode and the utility encounters rejected folders during the import process,
an appropriate message is issued for the partial import.
 In the event of a failure, the utility exits with an error return value and a partial import might occur. If
a commit was already made, an appropriate message is issued for the partial import.
The ctmimptb utility is run by using the Control-M/Server security authorization of the invoking user.
The permissions that are required to run the ctmimptb utility on Control-M/Server SMART Folders are
Read, Write, and Delete.
If permission is denied for a specific SMART Folder, the ctmimptb utility ignores the folder, continues
processing the input XML file, and (if no other errors are encountered) exits with a success return value.
BMC recommends that you avoid updating job definition folders while the ctmimptb utility is running.

Importing folders using the ctmimptb utility

This procedure describes how to run the ctmimptb utility, which enables you to import folders (including
SMART Folders and Rule-Based Calendars) containing job definitions that were exported from
Control-M/EM by the exportdeffolder utility.

 To import folders using the ctmimptb utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctmimptb
-PATH <full path to the output XML file exported by exportdeffolder EM utility>
[ -OVERWRITE ]
[ -DEBUG <debug level 0-5 ]
[ -MODULE <debug module 0-3 ]
[ -H | -Help ]
For more details about the ctmimptb utility, see ctmimptb (on page 228) and ctmimptb parameters
(on page 230).

229
Control-M Utilities Guide

ctmimptb parameters
The following table lists the ctmpimptb utility parameters:

Parameter Description

-PATH Indicates the full path to the file that holds the job definition folders
to be imported. This file is in XML and is generated by the
exportdeffolder utility in Control-M/EM.

-OVERWRITE determines how the utility responds when a folder that already exists
in Control-M/Server is imported:
 When this parameter is specified, the current folder in the
Control-M/Server database is replaced with the imported folder,
and a message similar to the following message is issued:
"Schedule folder already exists in the database and overwrite was
specified. Overwriting this folder"
 When this parameter is not specified, the imported folder is
rejected, leaving the current folder in the Control-M/Server
database unchanged, and a message similar to the following
message is issued:
"Schedule folder already exists in the database and overwrite was
not specified. Skip importing this folder."
After either using the imported folder to replace the current folder in
the Control-M/Server database or rejecting the imported folder, the
ctmimptb utility continues processing the file.

-DEBUG activates a debug trace at the specified level

Valid levels are 0-5. The default is 0.
NOTE: Performance is slower when Control-M/Server is operating in
debug mode. BMC recommends that you activate debug mode only
when requested by Customer Support.

-MODULE indicates which components are to be traced for diagnostic purposes

Valid values are as follows:
 0 – all components
 1 – common functionality flow (default)
 2 – event manager
 3 – database layer

-H | -Help displays the usage of the utility

230
Control-M Utilities Guide

ctmkilljob
The ctmkilljob utility terminates a specified Control-M job and all its processes. ctmkilljob terminates only
jobs that are currently executing. This utility can only be run interactively. To run the utility, see Ending a
job using the ctmkilljob utility (on page 231).
NOTE: The ctmkilljob utility fails if the agent is upgrading.
The ctmkilljob utility can be invoked using the -input_file parameter:
ctmkilljob -input_file <fullPathFileName>
The referenced file contains all the required parameters. Most of the parameters are described in
Control-M Parameters and ctmkilljob parameters (on page 232).
If the action performed by the ctmkilljob utility was successful, the utility responds with the statement:
Job was killed
The specified job is ended with NOTOK status.
NOTE: The parameters specified for ctmkilljob must indicate one unique job. If more than one job fits the
description specified in the command, you are informed that a unique name must be entered to carry out
the action. Reenter the command with parameters that specify one unique job.

Ending a job using the ctmkilljob utility

This procedure describes how to terminate a specified Control-M job and all its processes using the
ctmkilljob utility.
 To kill a job using the ctmkilljob utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Type one of the following commands:
• ctmkilljob
[ -ORDERID <uniqueOrderID> ]
[ -HOSTID <hostID> ]
[ -FILE_PATH <path> ]
[ -FILE_NAME <filename> ]
[ -JOBNAME <jobName> ]
• ctmkilljob -input_file <fullPathFileName>
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmkilljob parameters, see ctmkilljob parameters (on page 232).

231
Control-M Utilities Guide

ctmkilljob parameters
The following table lists the ctmkilljob utility parameters:

Parameter Description

-ORDERID Control-M Order ID of the job to be terminated.

-HOSTID Host name of an agent computer, or name of a host group to which

the job should be submitted.

-FILE_PATH Name of the library/directory in which the job script resides.

-FILE_NAME Name of the file that contains the job script statements.

-JOBNAME Descriptive reference for a job processing definition.

input_file Name and full path of a file containing parameters for the utility. In
this file, each parameter and its values (if any) are on a separate line
with the same syntax they would have on the command line. Using the
-input_file parameter enables you to:
prepare and save files of utility parameters that can be reused.
specify utility input longer than the number of characters allowed in
the command line.
-input_file
~<controlm_owner>/ctm_server/data/ctmkill
job_parms.txt

ctmorder
The ctmorder utility orders or forces one or more jobs from a SMART Folder in the Control-M/Server
database.
NOTE: Ordered jobs are placed in the Active Jobs database if their scheduling criteria are met. Forced
jobs are placed in the Active Jobs database regardless of their scheduling criteria.
To run the ctmorder utility, see Ordering or forcing a job using the ctmorder utility (on page 233).
If two jobs with the same name exist in a SMART Folder and you use the ctmorder utility to order or force
a job with that name, only the first job is added to the Active Jobs database.
NOTE: If the ctmorder utility is running when the New Day procedure begins, it is automatically
suspended until New Day procedure is ended.
When ordering a SMART Folder, folder-level Rule-Based Calendars are calculated and joined so that if the
scheduling criteria are met, the folder will be ordered. As a result of ordering the folder:

232
Control-M Utilities Guide

 A row in the Active Jobs database is added for this folder.

 All folder contents must pass the order procedure. Each field in the folder is inspected as follows:
• For regular jobs, the job scheduling criteria is calculated and either Or (default) or And with
folder or Sub-folder-level Rule-Based Calendars associated to it, according to the relationship
parameter in the job definition. If the scheduling criteria are satisfied the job is inserted into the
Active Jobs database. If the scheduling criteria are not satisfied, the job is ignored.
• For Sub-folders, Rule-Based Calendars of the Sub-folder are calculated and joined. When * is
defined, Rule-Based Calendars of the parent folder are fetched. If the result of the Rule-Based
Calendars calculation is satisfied, a row for the Sub-folder is added in the Active Jobs database
and the Sub-folder content will be ordered. If the result of the Rule-Based Calendars calculation is
not satisfied, the Sub-folder is ignored.
 Ordered SMART Folder, jobs and Sub-folders status are set to WAIT_SCHEDULING.
 INTO_FOLDER_ORDERID will be used to force (Ordering Sub-folders will not be valid) a job or
Sub-folder into already ordered folder or Sub-folder. The ordered job or Sub-folder should belong to
the same folder or Sub-folder of the job or Sub-folder we are ordering into. Force a Sub-folder ALONE
will not be applicable, for jobs it will be applicable.
The ctmorder utility can be invoked using the -input_file parameter:
ctmorder -input_file <fullPathFileName>
The referenced file contains all the required parameters. Most of the parameters are described in
Control-M Parameters and ctmorder parameters (on page 235).

Ordering or forcing a job using the ctmorder utility

This procedure describes how to order or force one or more jobs from a SMART Folder in the
Control-M/Server database using the ctmorder utility.
 To order or force a job using the ctmorder utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Type one of the following commands:
• The first format contains only a few parameters in a specific order:
ctmorder <SMART Folder name> <jobName> <odate>\ [{order|force}]
This first format cannot be used if the ctmorder utility is invoked from a Control-M/Agent
computer.
• The second format allows specification of all optional parameters in any order but requires each
specified parameter to be named. Format:
ctmorder -FOLDER <Folder|SMART Folder|Folder Path> -NAME <job
name|sub folder name> -ODATE <scheduling date>

233
Control-M Utilities Guide

[-FORCE <y|n>]
[-HOLD <y|n>]
[-UNIQUE <y|n>]
[-SEQNO <job sequence number>]
[-INTO_FOLDER_ORDERID <{SMART folder order id}|LAST|ALONE|NEWT]>
[-NODUPLICATION]
[-DEBUG <debug level 0-5> ]
[-QUIET ]
[-VARIABLE <varname> <expression> ]
[-ODATE_OPTION <VALUE_DATE|RUN_DATE>]
-or-
ctmorder -input_file <fullPathToFileName>
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmorder parameters, see ctmorder parameters (on page 235) and ctmorder examples (on page
238).

234
Control-M Utilities Guide

ctmorder parameters
The following table lists the ctmorder utility parameters:

Parameter Description

-FOLDER Either a folder name, SMART folder name (name of the SMART Folder
containing the jobs) or the path (including the folder name) to the
folder. This value might contain wild characters within the folder path.
Wild characters in the outermost folder name are also valid.

UNIQUE Adds a unique suffix to every conditional name.

 Y Add a unique suffix to every condition name.
 N Do not add a unique suffix to every condition name. Default

-NAME Job name (or mask) of the job(s) to order or force. Mandatory.
You can order a SMART Folder, but you cannot order an individual job,
or selection of jobs, from a SMART Folder.
The job name can include the following wildcard characters:
 * — represents any number of characters (or none). Specify * by
itself to include all jobs in the folder.
NOTE: Any parameter including * must be enclosed in double quotation
(see Example below).
 ? — represents any single character.
 $ — represents any single character.
NOTE: Whether the *, ?, and $ characters act as wildcards or as
ordinary characters in a job name is determined by the presence or
absence of a -seqno parameter:
The *, ?, and $ characters will only act as wildcards in the -jobname
parameter if no -seqno parameter is specified.
The *, ?, and $ characters will only act as ordinary characters in the
-jobname parameter if a -seqno parameter is specified. In this case, the
specified job name must exactly match the name of the job in the
indicated sequence, or the job will not be ordered.

-odate Indicates the scheduling date (odate) to be associated with job(s). Valid
values:

ODAT The current working date of the computer on which

Control-M/Server is running.
This is the default value.

yyyymmdd A specific working day in yyyymmdd format.

235
Control-M Utilities Guide

Parameter Description

NOTE: The interpretation of this parameter value depends on the value

specified for the -odate_option parameter (described below).

-force Add the specified jobs to the Active Jobs database regardless of
scheduling criteria. If -force is not specified, jobs are added to the Active
Jobs database only if their scheduling criteria are satisfied (known as
order). Use -INTO_FOLDER_ORDERID to force a job or sub-folder into a
folder or sub-folder that has already been ordered.

Y Force the specified jobs.

N Order the specified jobs. Default.

-hold Place the specified jobs in the Active Jobs database in Hold status.

Y Hold the specified jobs.

N The specified jobs are not held. Default.

-seqno A counter identifying the row number of the job in the SMART Folder.
The first job in each SMART Folder is numbered 1 and each subsequent
job increments the counter by one. If this parameter is not specified, the
first job in the specified folder is ordered. Optional.
NOTE: If this parameter is specified, any *, ?, and $ characters in the
-jobname parameter are assumed to be ordinary characters rather than
wildcards. Therefore:
Do not specify a -seqno parameter if you are specifying wildcards in the
-jobname parameter.
If you are specifying *, ?, or $ characters as ordinary characters (not
wildcards) in the -jobname, you must specify the appropriate -seqno
parameter (and the specified job name must exactly match the actual
job name).

-INTO_FOLDER_ NOTE: This parameter is relevant only for jobs in a SMART Folder. If the
ORDERID folder being ordered is not a SMART Folder, this parameter is ignored.

SMART Order ID of an existing SMART Folder.

Folder order
id

LAST Jobs are added to the last ordered instance of their

SMART Folder in the Active Jobs database.

ALONE Jobs are ordered individually. They are not associated

with any SMART Folder.

236
Control-M Utilities Guide

Parameter Description

NEWT A new folder is created and the specified jobs are ordered
to that SMART Folder. Default.

NOTE: The SMART Folder order id, last, alone and newt options can
only be used when the -force parameter is set to Y.

-noduplication Allow jobs to be ordered and added to an existing ordered SMART Folder
only if those jobs have not already been ordered in that instance of the
SMART Folder.
This parameter can be specified only if last or <SMART Folder order id>
is specified for the -INTO_FOLDER_ORDERID parameter.
NOTE: This parameter is relevant only for jobs in a SMART Folder.

-debug level Activates a debug trace at the specified level.

Valid levels: 0 – 5. Default: 0
Performance is somewhat slower when operating in debug mode. BMC
recommends that you activate debug mode only when requested by
Technical Support.

-quiet Suppresses display of the utility output. If specified, no information

messages are displayed during execution of the command.

-variable Adds an Variable expression to each job, SMART Folder, or SMART

Folder that is ordered by the utility.
For more information, see Control-M Variable facility . The following
information must be specified for each new variable.

<varName> Name of the variable.

<expression Value assigned to the variable.

>

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

Valid values, specify one of the following:

value_date The specified odate is the odate value for the job(s). The
jobs should be run during the current working day.
Default.
NOTE: If a time zone is specified in a job processing
definition, the job is run according to the specified time
zone.

237
Control-M Utilities Guide

Parameter Description

run_date Jobs ordered by this run of the ctmorder utility should be

run only when the specified odate begins.
If the specified odate is the current working day, the job
will run as described in value_date above.
If the specified odate has not begun (for example, due to
time zone specifications), then the job will wait in the
Active Jobs database (with WAIT_ODAT status) until the
start of the specified working day.
NOTE: If the specified odate has already passed, the
ctmorder utility will not run and an error message will be
displayed.

-input_file Name and full path of a file containing parameters for the utility. In this
file, each parameter and its values (if any) are on a separate line with
the same syntax they would have on the command line. Using the
-input_file parameter enables you to:
 Prepare and save files of utility parameters that can be reused.
 Specify utility input longer than the number of characters allowed in
the command line.
-input_file ~<controlm_run_as
name>/ctm_server/data/ctmorder_parms.txt

NOTE: If neither ORDER nor FORCE is included in the command, the specified jobs are ordered.

ctmorder examples
The following are examples of ctmorder utility:
The following command orders jobs named acct_job contained in SMART Folder ACCT100. Any jobs
placed in the Active Jobs database will have the current Control-M date as their original scheduling date:
ctmorder -FOLDER ACCT100 -NAME acct_job -ODATE odat
The same results can be achieved using the -input_file parameter as follows:
ctmorder -input_file ~<controlm_run_as
name>/ctm_server/data/ctmorder_acct100.txt
The referenced file contains the following lines:
-FOLDER ACCT100
-NAME acct_job
-ODATE odat
The following command orders all jobs contained in the SMART Folder ACCT100 whose job name begins
with ga. Any jobs placed in the Active Jobs database will have the date March 15, 2016 as their original
scheduling date:

238
Control-M Utilities Guide

ctmorder -FOLDER ACCT100 -NAME "ga*" \

-ODATE 20160315 -FORCE y
The following command forces all jobs contained in the ACCT100 sub-folder. Any jobs placed in the Active
Jobs database will have the date December 31, 2016 as their original scheduling date:
ctmorder -FOLDER ACCT100 -NAME ACCT101 \
-ODATE 20161231 -FORCE y
The following command forces the third job contained in the SMART Folder ACCT200 whose job name
parameter consists of prodyjob. This job is placed in the Active Jobs database and will have the date
December 31, 2016 as its original scheduling date. This job is added to a folder whose orderid is B2.
ctmorder -FOLDER ACCT200 -NAME prodyjob \
-ODATE 20161231 -FORCE y -SEQNO 3 -INTO_FOLDER_ORDERID B2
The following command assigns the variable %%PRDNDATE with the value of %%ODATE, and orders
every job in the PRODUCTION SMART Folder whose job name has a prefix of PRDN. These jobs are
placed in the Active Jobs database in a folder and are assigned the date December 31, 2016 as their
original scheduling date.
ctmorder -FOLDER PRODUCTION -NAME "PRDN*" \
-ODATE 20161231 -ORDER y -INTO_FOLDER_ORDERID newt\
-VARIABLE %%PRDNDATE %%ODATE
The following command orders every job in the INVENTORY SMART Folder whose job name has a prefix
in the range BIN_A1 to BIN_A9. These jobs are placed in the Active Jobs database in a new SMART
Folder, and are assigned December 31, 2016 as their original scheduling date. The APPLICATION and
RUN_AS parameters of these jobs are modified to STOCK_COUNT and STOREMAN, respectively.
ctmorder -FOLDER INVENTORY -NAME "BIN_A?" \
-ODATE 20161231 -FORCE n -INTO_FOLDER_ORDERID newt \
-VARIABLE %%PRDNDATE %%ODATE \
-VARIABLE %%APPLIC STOCK_COUNT \
-VARIABLE %%RUN_AS STOREMAN

239
Control-M Utilities Guide

ctmpsm
The ctmpsm utility performs functions affecting jobs or conditions in the active jobs database of the data
center. It provides an alternative to using the Control-M and enables you to perform many of the GUI
functions directly in the data center. To run the ctmpsm utility, see Running the ctmpsm utility
interactively (on page 240). For command line invocation, see ctmpsm utility command line parameters
(on page 250).
The functions in this menu are divided into the following categories:
 Active Jobs database functions provide various views of the Active Jobs database. Each view displays
information about the jobs and provides options to perform such actions on the jobs as Hold, Free,
Delete, Rerun, Why, Confirm, View or modify job details, and view the Control-M log.
 Resource Map functions enable you to view and modify Quantitative resources, Control resources, and
prerequisite conditions. The first three of these functions activate the ecactltb, ecaqrtab, and
ctmcontb utilities respectively.
 Scheduling Functions enable you to order or force SMART Folders or specific jobs in SMART Folders.
You can also generate monthly or yearly scheduling plans using the ctmrpln utility.
NOTE: If long names have been used for the In condition, jobname, override path, file_name, and doclib
parameters, these values will be truncated in the output of the ctmpsm utility. To view the complete
values for these parameters, use Control-M. The following special characters are disabled when they
occur in prerequisite condition names: ( ) | [blanks]
All Active Jobs database options display the following menu at the bottom of the screen:
H) Hold, F) Free, D) Delete, U) Undelete, R) Rerun, W) Why, Z) Details
LO) LogOrd, LJ) LogJob, Cn) Confirm, Sx)Sort[x: 1.ORDERNO 2.JOBNAME]
J) Output A) Statistic V) View Script/JCL K) Force OK I)Dependencies JobsGx)
Global action x [x: H(Hold), F(Free), D(Delete), U(Undelete), R(Rerun)]
Q)Quit
Enter Option:
These actions are described in ctmpsm active jobs database actions (on page 243).

Running the ctmpsm utility interactively

This procedure describes how to run the ctmpsm utility, which enables you to display the Control-M
Production Support menu.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: In Control-M/Agent you can invoke the utility from the Control-M/Agent home directory.
2. To run the utility interactively, type ctmpsm.
The Production Support Menu appears.

240
Control-M Utilities Guide

NOTE: If you want to invoke the utility through the command line, type ctmpsm -<parameter>. For
more information about the command line parameters, see ctmpsm utility command line parameters
(on page 250).
For the Control-M parameter name, see Parameter name cross references (on page 31).
For more details about the ctmpsm options and actions, see the following:
• ctmpsm active jobs database options (on page 242)
• ctmpsm active jobs database actions (on page 243)
• Resource map options (on page 245)
• Scheduling function options (on page 245)
• ctmpsm folder option output example (on page 246)
• ctmpsm options for scheduling functions (on page 246)
• ctmpsm options in the SMART Folder List Jobs menu (on page 248)
• Values in STATE and STATUS ctmpsm fields (on page 249)

241
Control-M Utilities Guide

ctmpsm active jobs database options

The following table lists options that are used to perform various tasks using information in the Active
Jobs database:

Code Option Description

1 List All Lists all jobs in the Active Jobs database and indicates if
they are associated with a SMART Folder (TBL) or
Sub-folder (STB).

2 List All Lists all jobs in the Active Jobs database. Indicates which
(Show jobs have started or ended execution.
Started/Ended)

3 List All Lists all jobs in the Active Jobs database. Indicates the
(Show Application) application to which each job belongs.

4 List All Lists all jobs in the Active Jobs database. Indicates the File
(Show File Name) Name for each job.

5 List Jobs That Lists jobs in the Active Jobs database with a completion
Ended OK Ended OK status.

6 List Jobs That Lists jobs in the Active Jobs database that have a
Ended NOTOK completion Ended NOTOK status.

7 List Submitted/ Lists jobs in the Active Jobs database that are currently
Executing Jobs executing.

8 List Cyclic Jobs Lists jobs in the Active Jobs database that are cyclic.

9 List Jobs Waiting for Lists jobs in the Active Jobs database that are waiting to
Time Window begin executing based on their Time From parameter.

10 List Jobs Waiting for Lists jobs in the Active Jobs database that are waiting for
Confirmation confirmation.

40 List Displays a summarized list of the applications and

Application/Sub-appli sub-applications for all jobs currently contained in the
cation Tree Active Jobs database.

41 List SMART Folders Displays a list of all SMART Folders in the Active Jobs
database.

42 List Ordered SMART Displays a list of all ordered SMART Folders in the Active
Folders Jobs database.

242
Control-M Utilities Guide

ctmpsm active jobs database actions

The following table lists actions you can perform on ctmpsm active jobs database options (on page 242):

Option Action Description

H Hold Hold a job.

F Free Free a previously held job.

D Delete Mark a job for deletion.

NOTE: Jobs with Executing or Submitted status cannot be deleted.

U Undelete Undelete a job marked for deletion.

R Rerun NOTE: Rerun a job. Rerun actions cannot be performed on a sub

application.

W Why Display why a job has not yet been submitted.

Z Details View or modify (zoom and save) a job’s parameters.

NOTE: When a job is being viewed, it is automatically held. After
changes are made and saved, the job is freed.
If prerequisite conditions are added to or deleted from a job in the
Active Jobs database using the Z option, the changes are
automatically saved when you quit.
If a cyclic job is terminated by a Do Stop Cyclic,
-dostopcyclic, or DO ACTION="SPCYC" parameter, the view will
contain Cyclic:T where T indicates Terminated.

LO LogOrd List Control-M log entries for a specific Order ID.

LJ LogJob List Control-M log entries for a specific Job Name.

Cn Confirm Confirm submission of a job.

S1 Sort (by Sort jobs displayed by Order number.

Order No.)

S2 Sort (by Sort jobs displayed by Job Name.

Job Name)

J Output Display the job OUTPUT.

A Statistic Display the job statistics

243
Control-M Utilities Guide

Option Action Description

V View View a job’s script or JCL.

Script/JCL
NOTE: This option is available if Control-M/EM database is active.

K Set to OK Set the status of a job to OK.

I Dependenci Display all jobs that depend on the specified job.

es Jobs

GH Global Hold all jobs in the displayed list.

Action
(Hold)

GF Global Free all jobs in the displayed list.

Action
(Free)

GD Global Mark all jobs in the displayed list for deletion.

Action
(Delete)

GU Global Undelete all jobs marked for deletion.

Action
(Undelete)

GR Global Rerun all jobs in the displayed list.

Action
NOTE: Rerun actions cannot be performed on a group entity.
(Rerun)

NOTE: The R (Rerun) option and the Global options (GH, GF, GD, GU, and GR) affect only
jobs and not SMART Folders.

244
Control-M Utilities Guide

Resource map options

The following table lists resource map options for the ctmpsm utility:

Code Option Description

61 Control Lists Control resources currently used in the Active jobs database.
Resources Activates the ecactltb utility.

62 Quantitative Allows you to list, add, modify, or delete Quantitative resources in

Resources the Active jobs database. Activates the ecaqrtab utility.

63 Prerequisite Allows you to view, add or delete prerequisite conditions in the

Conditions Active jobs database. Activates the ctmcontb utility.

64 Control Shows current usage of Control resources by jobs in the Active

Resources Jobs database.
Usage

65 Quantitative Shows current usage of Quantitative resources by jobs in the

Resources Active Jobs database.
Usage

Scheduling function options

The following table lists scheduling function options for the ctmpsm utility:

Code Option Description

71 Folders Lists SMART Folders and jobs defined in the Control-M/Server

database. Allows you to force SMART Folders or jobs, add or delete
SMART Folders and generate scheduling reports.

72 Order Allows you to order SMART Folders or jobs. You are prompted to
Folders/Job specify:
s
 SMART Folder
 Job Name (optional)
 Odate (YYYYMMDD/ODAT)
 Odate_option (VALUE_DATE|RUN_DATE) [VALUE_DATE]
 Hold Option (Y|N)
For more information about ordering jobs and SMART Folders, see
ctmorder (on page 232)

245
Control-M Utilities Guide

ctmpsm folder option output example

When the Folders option is selected, output similar to the following is displayed:
Folders
----------------------
Folder name Daily name Folder type Remove at once
Days keep in NOTOK
1) tab_1 SMART FOLDER N
0
2) temp REGULAR
3) inventory SMART FOLDER N
0
4) Payroll Monthly REGULAR
5) inventory SYSTEM SMART FOLDER N
0
6) RE_OUTPUT output REGULAR
D#) Delete UserDaily Folder # U#) Update folder #
F#) Force folder # J#) List jobs #
A) Add. R) Remove Folder Q) Quit.
Option []:

ctmpsm options for scheduling functions

The following table lists options for the scheduling functions:
If a folder that is associated with more than one Order method is modified using Control-M/EM and then
uploaded to Control-M/Server, that folder is removed from all User dailies except the one that is
associated with it in Control-M/EM.

Code Option Description

A Add Adds a Order method to an existed folder. When selected, you are
prompted for the Folder name and Order method name.

D# Delete Removes an instance of a Folder from the Control-M/Server

UserDaily database.
Folder #
If the specified instance is the only instance of the folder (that is,
that folder is ordered by only one order method), the Folder and all
its associated jobs are deleted.
If the specified instance is not the only instance of the folder, then
only the specified instance is removed from the Control-M/Server
database.

246
Control-M Utilities Guide

Code Option Description

F# Force folder Forces a specific Folder (for example, specify F6 to force folder
# RE_OUTPUT).
The following prompt is displayed:
Odate (YYYYMMDD/ODAT) [ODAT]:
Enter the odate for the job to be forced in YYYYMMDD format, or
enter the value ODAT to indicate that the job should use the current
working date as its odate.
The following prompt is displayed:
ODATE option (VALUE_DATE|RUN_DATE) [VALUE_DATE]:
To run jobs now with the specified odate, specify, VALUE_DATE
To wait until the specified odate begins before running the jobs,
specify RUN_DATE.
If the specified folder is a SMART Folder, the following prompt is
displayed:
Please choose one of the following:
A) Alone.
N) New sub application.
L) Last.
B) Bind to existing group Orderno.
These options are described below:
 A – Forces each job in the folder separately as a non-sub
application job.
 N – Forces the jobs in the folder as a new sub application in the
Active Jobs database.
 L – Forces the jobs in the folder, and adds them to the most
recently ordered sub application in the Active Jobs database.
 B – Forces the jobs in the folder, and adds them to a specified
application in the Active Jobs database.

J# List jobs # Lists content of a folder and provides options to force a specific job
or sub-folder or generate a report (for example, specify J1 to list the
jobs in folder supply).

R Remove Deletes a specific Folder and all its associated jobs (for example,
Folder specify R RE_OUTPUT to delete folder RE_OUTPUT).

247
Control-M Utilities Guide

Code Option Description

U# Update Updates the Order method name for a specific Folder (for example,
folder # specify U6 to update the Order method name for folder
RE_OUTPUT).

ctmpsm options in the SMART Folder List Jobs menu

The following table lists options in the SMART Folder List Jobs menu:

Code Option Description

F# Force job # Forces a specific job (for example, specify F2 to force job
DAYS_30_FEB).

M# Month Schedule Generates a monthly Job Order report for the folder. You are
Plan prompted to enter the year and month in format YYYYMM.

Y# Year Schedule Generates a yearly Job Order report for a specific job. You are
Plan for job # prompted to enter the year in format YYYY.

248
Control-M Utilities Guide

Values in STATE and STATUS ctmpsm fields

The following table displays the values that are listed in the STATE and STATUS fields when ctmpsm is
executed:

Value Description

STATUSES

OK The job completed okay.

NOTOK The job did not complete okay.

STATES

Wait Sche The job is waiting to be scheduled.

Wait Conf The job is waiting for user confirmation.

Wait Reru The job is waiting to be rerun.

Wait Time The job is waiting for its time frame.

Wait Cond The job is waiting for a condition.

Wait Reso The job is waiting for a resource.

Wait Host The host(s) to which the job is being submitted is unavailable, either
because of host's restriction, or because of network availability.

Wait Workload One or more of the workloads with which the job is associated has
reached its maximum jobs limit policy.

Submitted The job was submitted (that is, the job was sent to an agent).

Retry Sub The job is waiting for a submission retry.

Executing The job is executing.

Ended The job has ended.

Analyzed The job is being analyzed.

Disappear The job has disappeared in the agent.

Post proc The job has performed its post processing activities.

Wait ODAT The job is waiting for the appropriate ODAT.

Post ODAT The appropriate ODAT of the job already passed.

249
Control-M Utilities Guide

Value Description

Unknown The status of the job is unknown.

ctmpsm utility command line parameters

The following table lists the valid values for each parameter of the ctmpsm utility command line interface:

Parameter Description

CHILD Lists dependent jobs with IN conditions that are created by the job whose order ID is
specified in this command.
ctmpsm -CHILD <order_ID> [<tasktype>]

order_ID Identifies the parent job.

tasktype  B: Batch job

 D: Detached
 C: Command
 U: Dummy
 X: External job

250
Control-M Utilities Guide

Parameter Description

IMPORT_CAL Imports a calendar from the Control-M/EM.

ctmpsm -IMPORT_CAL <ECS exported file name> [overwrite]
<ECS exported file Name> is the full path name of the calendars file to be imported
from Control-M/EM.
NOTE: The file must be imported from Control-M/EM in XML mode only.
If overwrite is specified, when the specified calendar to be imported from
Control-M/EM already exists in the Control-M/Server database, the import action will
overwrite it. Default: overwrite is not specified.
NOTE: There is a line of output for every calendar handled by the import_cal option.
EXAMPLE: After a successful import of a calendar, the following message is
displayed:
Calendar <x>, for year <y>, has been imported.
EXAMPLE: Assume calendar <x>, that is being imported, already exists in the
Control-M/Server database, and that the overwrite option has not been
specified. The following message is displayed:
Calendar <x>, for year <y>, that already exists, has not
been imported.

LISTCAL Lists available calendars. The list can be restricted by calendar name and year.
ctmpsm -LISTCAL [<calendar name>][<calendar year>]

<calendar name> Restricts the list to calendars with the specified name or prefix
(indicated by * at the end).

<calendar year> Restricts the list to calendars for the specified year.

251
Control-M Utilities Guide

Parameter Description

LISTALL Lists jobs in the Active Jobs database. The list can be filtered by time, application, and
member name. The list can be sorted by order ID or job name.
ctmpsm -LISTALL
[<ODAT|TIME|APPLICATION|FILENAME|ALL|ALLFIELDS_ALLFIELDS_FUL
L]
[-SORT {ORDERID|JOBNAME>]
In addition to the order ID and the job name, one of the following fields must also be
included in the LISTALL output:
 ODAT: Order date.
 TIME: Time execution started and ended.
 APPLICATION: Application to which the job belongs.
 FILENAME: File name for the job.
 ALL: – Includes ODAT, FROMTIME and UNTIL fields.
 ALLFIELDS: Includes ODAT, FILENAME, and APPLICATION fields.
 ALLFIELDS_FULL: Includes ODAT,FILENAME, APPLICATION fields and full size for
the JOBNAME column.
 –SORT: Indicates the order in which the jobs should be listed. Valid values:
ORDERID and JOBNAME.
Note for other job statuses:
The following additional job statuses are visible only when using the LISTALL option:
 WAIT_ODAT The Job’s Odate is later than the Control-M/Server working date for
the relevant timezone. The job is waiting for the relevant day (Odate) to begin.
 POST_ODAT The job’s Odate is earlier than the Control-M/Server working date
for the relevant timezone. The job will be deleted during the next run of the New
Day procedure.
These job statuses are used in the Control-M/Server Active Jobs database. However,
in Control-M/EM, jobs with these statuses will appear with Wait Condition status. In
non-interactive mode, WAIT_Condition and WAIT_CONFIRM are both displayed as
Wait Con.

252
Control-M Utilities Guide

Parameter Description

LISTJOB Lists jobs that are cyclic, as well as jobs in the Active Jobs database with a specified
status. Jobs can be filtered by status: OK, NOTOK, executing, waiting for the end of a
time interval, waiting for confirmation.
ctmpsm -LISTJOB
<OK|NOTOK|EXECUTING|CYCLIC| WAITTIME|WAITCONFIRM}
[-SORT {ORDERID|JOBNAME>]
 OK: Jobs with a completion Ended OK status.
 NOTOK: Jobs with a completion Ended NOTOK status.
 EXECUTING: Jobs that are currently executing.
 CYCLIC: Jobs that are cyclic.
 WAITTIME: Jobs waiting to begin executing based on the time specified in their
Time From parameter.
 WAITCONFIRM: Jobs waiting for confirmation.
 –SORT: Indicates the order in which the jobs should be listed. Valid values:
ORDERID and JOBNAME.

LISTSUB_APPLICATI Lists jobs in the specified Sub Application that are associated with a Specified
ON Application.
ctmpsm -LISTSUB_APPLICATION <application> <sub application>>
[<scheduling date>]
Wildcard characters can be used as part of the specified application or sub-application
names, as follows:
 * represents any number of characters.
 ? represents any single character.

LISTAJFFLD Lists jobs in the Active Jobs database that were ordered from the specified SMART
Folder.
ctmpsm -LISTAJFFLD <folder name>
Wildcard characters can be used as part of the specified application or sub-application
names, as follows:
 * represents any number of characters.
 ? represents any single character.

FOLDER Lists SMART Folders and jobs defined in the Control-M/Server database, and allows
you to add or delete SMART Folders.
ctmpsm -FOLDER
<LISTFOLDER <folder name>|-UPDATE <row number> <udaily name>|

253
Control-M Utilities Guide

Parameter Description
-ADD <folder name> <udaily name>|-DUDAILY <row number>|
-REMOVE <folder name>|-LISTJOBS <row number> [FULL]

-LISTFOLDER Lists all instances of SMART Folders that match the specified
name or mask. For example, if a SMART Folder is ordered by two
different user dailies, that folder will appear twice in the output of
this option.
Wildcards can used as part of the folder name for this option.
 * Represents any number of characters.
 ? Represents any single character.

-UPDATE Updates the User Daily name for a specific SMART Folder.

-ADD Adds a User Daily to an existing folder. The Folder name and
Order method name must be specified when this option is used.

-UDAILY_NAME Removes an instance of a SMART Folder from the

Control-M/Server database.
If the specified instance is the only instance of the folder (that is,
that folder is ordered by only one order method), the SMART
Folder and all its associated jobs are deleted.
If the specified instance is not the only instance of the folder,
then only the specified instance is removed from the
Control-M/Server database.

-REMOVE Deletes a specific SMART Folder and its associated jobs.

-LISTJOBS Lists jobs in a SMART Folder.

LISTOUTPUT List the OUTPUTs for an order ID. The list can be restricted by runcount number.
ctmpsm -LISTOUTPUT <orderID> [OUTPUTNUMBER {<number>|ALL}]
These parameters are described below.
To define a viewer to which the display of the OUTPUT of a job is redirected, specify
the CTMPSM_VIEWER parameter in the
~<controlm_owner>/ctm_server/data/config.dat file. For more information
about the CTMPSM_VIEWER parameter, see System configuration.
order_ID: Identifies the job whose OUTPUTs are listed.
number: Restricts the list to the OUTPUT whose runcount is specified. If ALL is
specified, the output will contain only a list of all OUTPUTs related to the specified
order ID.

254
Control-M Utilities Guide

Parameter Description

LISTDETAILS Lists the details of the job associated with the specified order ID.
LISTDETAILS <orderID>

LISTFULLDETAILS Lists the parameters of a specified job in the Active Jobs database. In addition to the
data provided by LISTDETAILS (above), LISTFULLDETAILS provides data about In
conditions, Out conditions, and Variable values. (LISTFULLDETAILS was added for use
with the "Zoom and Save" option in WebAccess.)
ctmpsm -LISTFULLDETAILS <orderID>

UPDATEAJF Performs a specified command or updates conditions for a job in the Active Jobs
database that is associated with a specified order ID.
ctmpsm -UPDATEAJF <orderID> <command>
command is one of the following:
 HOLD _ Set the status of a job to HELD.
 FREE _ Free a previously held job.
 DELETE _ Mark a job for deletion.
NOTE: Jobs with Executing or Submitted status cannot be deleted.
 UNDELETE _ Undelete a job marked for deletion.
 RERUN _ Rerun a job.
 CONFIRM _ Confirm submission of a job.
 SET TO OK _ Set the status a job to be OK.
NOTE: SET TO OK can only be applied to inactive jobs (that is, jobs that are not
running).
 STATISTICS – Display a job’s statistics.
 CONDADDIN <cond> <date> <AND|OR> _ Add the specified IN condition with
the specified date reference. You can include one or more additional IN conditions
by using the AND or OR conjunctional parameter.
 CONDADDOUT <cond> <date> <+|-> _ Add the specified OUT condition with
the specified date reference. Use + to indicate that the condition must be
present. Use - to indicate that the condition must not be present.
 CONDDELIN <cond> _ Delete the specified IN condition.
 CONDDELOUT <cond> _ Delete the specified OUT condition.
NOTE: Conditions specified using this mode apply only to the specified instance
of the job in the Active Jobs database. Subsequent orders of that job are not
affected.

255
Control-M Utilities Guide

Parameter Description

UPDATESUBAPPLICA Applies a specified command to jobs in the specified Sub Application that are
TION associated with the specified Application.
ctmpsm -UPDATESUB_APPLICATION <application> <sub application> <command>
<command> is one of the following:
 HOLD _ Set the status of a job to HELD.
 FREE _ Free previously held jobs.
 DELETE _ Mark the jobs for deletion.
 UNDELETE _ Undelete the jobs marked for deletion.
 CONFIRM _ Confirm submission of the jobs.

UPDATEFOLDER Applies a specified command to jobs in the Active Jobs database that were ordered
from the specified folder.
ctmpsm -UPDATEFOLDER <folder> <command>
<command> is one of the following:
 HOLD _ Set the status of a job to HELD.
 FREE _ Free previously held jobs.
 DELETE _ Mark the jobs for deletion.
 UNDELETE _ Undelete the jobs marked for deletion.
 RERUN _ Rerun the jobs.
 CONFIRM _ Confirm submission of the jobs.

256
Control-M Utilities Guide

Parameter Description

XML Lists jobs in the Active Jobs database in XML format. The job output formats can be
changed according to the specified parameter, such as order date, time, application,
or member name can be added to the output.
ctmpsm -XML [{ODAT|TIME|APPLICATION|MEMNAME|ALL|ALLFIELDS}]
[-SORT <ORDERID|JOBNAME>]
To list jobs in the Active Jobs database in XML format, specify ctmpsm -XML plus at
least one of the following fields:
 ODAT: Order date.
 TIME: Time execution started and ended.
 APPLICATION: Application to which the job belongs.
 FILENAME: File name for the job.
 ALL: Includes ODAT and TIME fields.
 ALLFIELDS: Includes ODAT, FILENAME, and APPLICATION fields.
In addition, you can specify the following:
–SORT indicates the order in which the jobs should be listed.
Valid values: ORDERID and JOBNAME.
EXAMPLE: To change the output format in the Active Jobs database according to the
file name of the job, specify the following:
ctmpsm -XML FILENAME
EXAMPLE: To sort the list in Example 1 above according to job name, specify the
following:
ctmpsm -XML FILENAME -SORT JOBNAME

EXAMPLE: To display the most recent OUTPUT of the job whose order ID is 1234, specify the following
command:
ctmpsm -listoutput 1234
EXAMPLE: To display the second OUTPUT of the job whose order ID is 1234, specify the
following command:
ctmpsm -listoutput 1234 -outputnumber 2

257
Control-M Utilities Guide

ctmsweep
The ctmsweep utility deletes job definitions from the Control-M/Server database that become obsolete
due to the Start date (Active From Date) and End date (Active To Date) parameters in the job definitions.
To run the ctmsweep utility, see Running the ctmsweep utility (on page 258).
In a typical production situation, you can use ctmsweep as follows:
 Run the ctmsweep utility with the –Test parameter to generate the sweep_obsolete.txt file, which
is essentially a report listing the obsolete jobs and folders.
 Check the sweep_obsolete.txt file and decide if you want to delete the jobs and folders that are
displayed in the report.
 Activate the ctmsweep utility without the –Test parameter to delete the obsolete jobs and folders
from the Control-M/Server database.
If the utility failed or partially succeeded, check the U_CTMSWEEP.<PID>.log file for the reason for
the failure. Perform the necessary corrections. Activate the ctmsweep utility again to delete the obsolete
folders and jobs that were not deleted successfully in the previous run.
NOTE: Avoid updating job or folder definitions when the ctmsweep utility is running.
The ctmsweep utility can be invoked using the -input_file parameter:
ctmsweep -input_file <fullPathFileName>
The referenced file contains all the required parameters. Most of the parameters are described in
Control-M Parameters and ctmsweep parameters (on page 259).

Running the ctmsweep utility

This procedure describes how to run the ctmsweep utility, which enables you to delete job definitions
from the Control-M/Server database that become obsolete due to the Start date (Active From Date) and
End date (Active To Date) parameters in the job definitions

 To run the utility:

 Open a command prompt and type the following command:
ctmsweep [-Date <yyyymmddDate>]
[-Test ]
[-H | -Help]
[-DEBUG <debugLevel 0-5>]
[-MODULE <moduleNumber 0-3>]
For more details on the ctmsweep parameters, see ctmsweep parameters (on page 259).

258
Control-M Utilities Guide

ctmsweep parameters
The following table lists the ctmsweep utility parameters.

Parameter Description

-Date Sets the date selection criteria for obsolete jobs

The format of the -Date parameter is <yyyymmddDate>. The default is
two days before the current date.

-Test Causes the ctmsweep utility to scan all job definitions and generate the
sweep_obsolete.txt file, which consists of a report of the current
obsolete jobs and folders, without actually deleting the jobs

-H | -Help Displays the usage

-DEBUG Activates a debug trace at the specified level

Valid debug trace levels are 0–5. The default is 0.
NOTE: Performance is slower when Control-M/Server is operating in
debug mode. BMC recommends that you activate debug mode only when
requested by Customer Support.

-MODULE Indicates which components are to be traced for diagnostic purposes

Valid values are as follows:
 0 – all components
 1 – common functionality flow (default)
 2 – event manager
 3 – database layer

259
Control-M Utilities Guide

Utility reports
The following table lists the files created by the ctmsweep utility for each obsolete folder or job that is
deleted:

File name Location Description

sweep_obsolete. <Control-M report of all jobs and folders that are

txt ServerHomeDirectory> candidates for deletion according to the date
criteria

U_CTMSWEEP. <Control-M execution log

<PID>.log ServerHomeDirectory>
/ctm_server/proclog

Report formats
The report for obsolete jobs has the following format:
Obsolete folders/jobs [on 03/18/2016 09:56:32] for date: 20100316
Command Folder/Job No File Name Name Folder Name
The report is relevant for jobs, Sub-folders and SMART Folders.
Only the most recent version of the sweep_obsolete.txt report is saved.

ctmsweep return codes

The following table lists the ctmsweep return codes:

Return
code Description

0 Success (All of the obsolete jobs were deleted.)

1 Failure
Run the ctmsweep utility again.

2 Partial success (Some obsolete jobs were not deleted.)

Run ctmsweep again to delete the remaining jobs or folders.

The CTM_MAX_OBSOLETE_JOBS parameter, in the Control-M/Server config.dat file, determines the

maximum number of obsolete jobs that the ctmsweep utility processes when running. Valid values are
from 1 to 500,000 jobs. The default is 100,000 jobs.

260
Control-M Utilities Guide

ctmsweep obsolete criteria

The following lists the criteria that ctmsweep uses to determine whether a job or folder is obsolete.
If the DateUntil parameter is specified, the following elements are considered as obsolete:
A regular job, which is not part of a SMART Folder, is considered as obsolete if one of the following
conditions is true:
 The job has no Rule-Based Calendars and its own DateUntil/DateFrom satisfies the following criteria:
DateFrom <= DateUntil and DateUntil < obsolete date
 The job has Rule-Based Calendars and is considered obsolete according to ctmsweep delete a job
criteria (on page 262).
 A Rule-Based Calendar is considered obsolete if the following criteria is true:
DateFrom <= DateUntil and DateUntil < obsolete date
 A SMART Folder is considered obsolete if all of its Rule-Based Calendars are obsolete (the relationship
between the Rule-Based Calendars is always OR).
 A folder is considered obsolete if all of the jobs in the folder are obsolete.
 A job that is part of a SMART Folder is defined as obsolete if one of the following conditions is true:
 The SMART Folder is obsolete.
 The job satisfies the obsolete criteria according to its own DateUntil/DateFrom and has no Rule-Based
Calendars.
 The job has Rule-Based Calendars and is considered obsolete according to ctmsweep delete a job
criteria (on page 262).

261
Control-M Utilities Guide

ctmsweep delete a job criteria

The following table lists the criteria for deleting a job by the ctmsweep utility:

Job (DateUntil/ Rule-Based Calendar

Relationship DateFrom) (DateUntil/ DateFrom) Result

AND obsolete obsolete Deletes the job

AND obsolete active Deletes the job

AND active obsolete Deletes the job

AND active active The job is active

OR obsolete obsolete Deletes the job

OR obsolete active The job is active

OR active obsolete The job is active

OR active active The job is active

AND not defined obsolete Deletes the job.

AND not defined active The job is active

OR not defined obsolete The job is active

OR not defined active The job is active

NOTE: To delete obsolete folders or jobs, you need both Delete and Update permissions for the specific
folder. If permission is denied for a specific folder, the ctmsweep utility ignores the folder, continues
processing other folders in the database, and (if no other errors are encountered) exits with a success
return value.

ctmwhy
The ctmwhy utility displays a report stating why a SMART Folder, Sub-folder, or job waiting in the Active
Jobs database is not being submitted for execution. This utility is equivalent to the Why option available
when right-clicking a SMART Folder, Sub-folder, or job in the Tree View pane of the Control-M/EM
window. To run the ctmwhy utility, see Running the ctmwhy utility (on page 263).
The ctmwhy utility can be invoked using the -input_file parameter:
ctmwhy -input_file <fullPathFileName>
The referenced file contains all the required parameters. Most of the parameters are described in
Control-M Parameters.

262
Control-M Utilities Guide

Running the ctmwhy utility

This procedure describes how to run the ctmwhy utility, which enables you to display a report stating why
a SMART Folder, Sub-folder, or job waiting in the Active Jobs database is not being submitted for
execution.

 To run the utility:

 Open a command prompt and type the following command:
ctmwhy <orderID>
For more details on the ctmsweep parameters, see ctmwhy example (on page 263).
If the host is upgrading, and the job is in state wait host, the following message will appear:
No agent hosts available for job's host-group.
The variable <orderID> is the Order ID of a job waiting in the Active Jobs database (as displayed in the
Job Details window of Control-M/EM).
NOTE: The Order ID as displayed in the Job Details window is a base 36 number. If you wish to specify
the Order ID here as a base 10 number, prefix the number with an asterisk, and enclose the result in
quotation marks (for example, " ∗1234").

ctmwhy example
Specify the following command to determine why the job with Order ID A4X is not being submitted for
execution:
ctmwhy A4X
A typical response might be QR: ‘TAPE4’ : needed 2. None reserved. This response indicates
that the job is not being submitted because it requires two of the Quantitative resource
TAPE4 and none is available.
Specify the following command to determine why the job with Order ID 11 is not being submitted for
execution. The Order ID in this example is expressed as a base 10 number:
ctmwhy "*37"

Control-M/Agent utilities
This table lists the Control-M/Agent utilities that are used for definition, ordering, and monitoring.

Utility Type Description

_exit (on page 264) (Windows only) Sets the completion status for a job
that runs from a .bat file.

_sleep (on page 264) (Windows only) The _sleep utility is similar to the sleep
built-in shell function in UNIX.

263
Control-M Utilities Guide

_exit
(Windows only) Sets the completion status for a job that runs from a .bat file.
The _exit utility is similar to the exit built-in shell function in UNIX.
To run the _exit utility, see Running the _exit utility (on page 264).

Running the _exit utility

This procedure describes how to run the _exit utility.

 To run the utility:

 From the <Control-M/Agent>/Default/exe directory, type the following command:
_exit [<exitCode>]
The <exitCode> variable is any whole integer number n Default: 0
The program exits with %errorlevel% = <exitCode>.
EXAMPLE: Specify _exit 0 in a script to cause the job to end with %errorlevel% 0.
ctmcreate -what command -cmdline "_exit 0"
Specify _exit 1 in a script to cause the job to end with %errorlevel% 1.
ctmcreate -what command -cmdline "_exit 1"

_sleep
(Windows only) Sets the sleep time for Control-M/Server processes.
The _sleep utility is similar to the sleep built-in shell function in UNIX.
To run the _sleep utility, see Running the _sleep utility (on page 264).

Running the _sleep utility

This procedure describes how to run the _sleep utility.

 To run the utility:

1. From the <Control-M/Agent>/Default/exe directory, type the following command:
"... _sleep" <seconds>
The <seconds> variable is any whole integer number n.
EXAMPLE: Run the following command to suspend execution of the script for 5 seconds.
ctmcreate -what command -cmdline "_sleep 5"

264
4
4
Folders and Calendars utilities
The folders and calendars utilities are used to folder, SMART folder, and Calendar definitions. You can use
the Folder Manager, Job Properties team, and Folder Properties team in Control-M and
Control-M/Enterprise Manager (Control-M/EM) for the same tasks. However, if you perform these tasks by
including a utility command in the command line of a job processing definition, you can run the utility at a
predetermined time or under a predetermined set of conditions without being present.
Some of the parameter names changed for Control-M version 8.0.00 and above, terminology from
previous versions is still supported. For a complete list of the parameter names, see Abbreviations and
conventions.
The following table describes the utilities for various utilities for folders and calendars definitions.

Utility Description

Control-M/EM

emdef utility for Creates various modifications to folder and calendar definitions in the
folders and Control-M/EM database.
calendars (on
page 266)

cli utility (on Enables you to perform the following operations:

page 302)
 Orders and forces jobs and folders
 Uploads and downloads calendars and folders
 Deletes jobs from folders
 Activates a Workload Policy definition

Control-M/Server

ctmcalc_date Calculate the date a job can be ordered, after adding or deducting a
(on page 315) specified number of days.

ctmdeffolder Create a definition for a new SMART Folder.

(on page 318)

ctmdefsubfolde Create a definition for a new Sub-folder.

r (on page 322)

ctmrpln (on Creates a report that lists jobs in a folder and when they are scheduled to
page 324) run.

265
Control-M Utilities Guide

emdef utility for folders and calendars

The emdef is a command line utility used to make various modifications to folder and calendar definitions
in the Control-M/EM database. The emdef uses the following parameters:

Parameter Description

copydefcal (on page 266) Creates a new calendar definition in the Control-M/EM
database identical to an existing calendar definition.

defcal (on page 270) Imports a calendar definition into the Control-M database.

deffolder (on page 277) Imports Folders and SMART Folders into the Control-M/EM
database

exportdefcal (on page 292) Exports calendar definitions in the Control-M/EM database to
an output file for use as input to other utilities.

exportdeffolder (on page Exports folders from the Control-M/EM database to a text
298) file.

updatedef (on page 124) Modifies jobs, folders, and group attributes.

The emdef utility manages Rule-Base Calendars similar to other calendar types. The Rule-Base Calendar
parameters are specified in the arguments file.
For emdef job utilities, see emdef utility for jobs (on page 42).

copydefcal
The copydefcal utility creates a new calendar definition in the Control-M/EM database identical to an
existing calendar definition. Calendars can be copied and saved under different names in the same data
center. Calendars in one data center can be copied to a different data center and saved under the same
or different names. To copy existing calendar definitions using the copydefcal utility, see Copying an
existing calendar using the copydefcal utility (on page 267).
Multiple calendars can be selected and copied using the * wildcard character. For an explanation of how
wildcards function in XML-based utilities, see Terminology.
When copydefcal is invoked, a file of arguments that you created is processed. This arguments file
contains statements that specify an existing calendar or group of calendars. The specified calendars are
exported to an output file. copydefcal reads arguments directly from a plain text arguments file (in XML
format) instead of reading them from the command line. For more information, see copydefcal arguments
file rules (on page 267).

266
Control-M Utilities Guide

Copying an existing calendar using the copydefcal utility

This procedure describes how to create a new calendar definition in the Control-M/EM database identical
to an existing calendar definition using the copydefcal utility.
 To copy an existing calendar:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter either of the following commands:
• emdef copydefcal [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <args
file name>
• emdef copydefcal [-u <user> [-p <password>] | -pf <password file>] -s
<GUI Server Name> -arg <args file name>
NOTE: For Windows you do not need to use emdef prefix.
For more details on the copydefcal parameters and options, see emdef general parameters (on page
44) and emdef switches (on page 45).
For information about the args file name, see copydefcal arguments file rules (on page 267).
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.

copydefcal arguments file rules

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. Instructions for preparing this file are in XML file rules (on
page 35).
When this file is invoked, calendar definitions are exported from the Control-M/EM database.
The following rules apply to the copydefcal arguments file:
 More than one calendar can be specified in an arguments file.
 The arguments file is case-sensitive.
 Only one COPYCAL parameter can be used in an arguments file.
 All parameter values (such as strings or digits) must be enclosed in quotation marks (for example,
JOBNAME="Job1").
Using FROM and TO in the copydefcal input file:

267
Control-M Utilities Guide

 If you choose to specify a parameter, the FROM subparameter is mandatory, and the TO
subparameter is optional.
 When a FROM value is specified without a TO value, it is used as a filter criterion.
 When a TO value is included, it indicates the new value with which the parameter is updated.
 Multiple values can be specified for TO and FROM by using the * wildcard character. For an
explanation of how wildcards function in the XML-based utilities, see Wildcards (on page 39).
 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.
 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.
For more information on the arguments file parameters for the copydefcal utility, see copydefcal
arguments file parameters (on page 268) and copydefcal arguments file examples (on page 269).

copydefcal arguments file parameters

The following table lists the copydefcal utility arguments file parameters:

Parameter Description

The first two lines of the XML request file for this API request contain information that specifies the version
of XML, the text encoding format being used, and the location of the .dtd file.

COPYCAL These tags indicate the start and end of the COPYCAL argument. Only criteria that are
located between the tags are considered to be part of the argument.

DATACENTER Control-M installation to which the calendar definition belongs.

NOTE: The COPYCAL element must contain only one DATACENTER parameter. String.
DATACENTER FROM="EM5NYC" TO="EM7NYC"

FROM: Data center in which the source calendar is located. String. Mandatory.

TO: Data center in which a calendar can be created. String. Optional.

CALENDAR Defines the name of the calendar.

NOTE: The COPYCAL element must contain only one CALENDAR parameter.
CALENDAR FROM="Cal1" TO="Cal1_COPY"

FROM: Defines the name of the calendar from which a copy is made. String. Mandatory.

TO: Defines the name of the calendar copy. The copy retains the name of the original
calendar if this attribute is not used. String. Optional.

268
Control-M Utilities Guide

copydefcal arguments file examples

The following are examples of argument files used with the copydefcal utility:
 Create and import a calendar XML file example (on page 269)
 Copy multiple calendars from the same data center XML file example (on page 269)
 Copy a calendar and rename the copy XML file example (on page 269)

Create and import a calendar XML file example

In the copydefcal XML file, create a copy of the calendar named CAL_3 in the EM10LA data center.
<COPYCAL>
<DATACENTER FROM="EM5NYC" TO="EM10LA"/>
<CALENDAR FROM="CAL_3"/>
</COPYCAL>

Copy multiple calendars from the same data center XML file example
In the copydefcal XML file, all calendars in the EM5NYC data center with names beginning with the letter
A are copied to the EM7NYC data center. The new calendar names are calendarname_COPY (for
example, the copy of the Alljobs calendar is named Alljobs_COPY).
<COPYCAL>
<DATACENTER FROM="EM5NYC" TO="EM7NYC"/>
<CALENDAR FROM="A*" TO="A*_COPY"/>
</COPYCAL>

Copy a calendar and rename the copy XML file example

In the copydefcal XML file, the calendar named CAL_NOV in the EM5NYC data center is copied. The
name of the copy is CAL_NOV_REVISED.
<COPYCAL>
<DATACENTER FROM="EM5NYC"/>
<CALENDAR FROM="CAL_NOV" TO="CAL_NOV_REVISED"/>
</COPYCAL>

269
Control-M Utilities Guide

defcal
The defcal utility imports a calendar definition into the Control-M/EM database.
defcal reads calendar definitions directly from a plain text input file (in XML format) instead of reading
them from the command line. To import a calendar definition using the defcal utility, see Importing a
calendar using the defcal utility (on page 270).

Importing a calendar using the defcal utility

This procedure describes how to import a calendar definition into the Control-M/EM database using the
defcal utility.
 To import a calendar:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window. You do not need to be in the Control-M/EM
database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter either of the following commands:
• emdef defcal [-USERNAME <user> [-PASSWORD <password>] | -PASSWORD_FILE
<password file>] -HOST <GUI Server Name> -SRC_FILE <XML File name>
• emdef defcal [-u <user> [-p <password>] | -pf <password file>] -s <GUI
Server Name> -src <XML file name>
NOTE: For Windows, you do not need to use the emdef prefix.
For more details on the defcal parameters and options, see emdef general parameters (on page 44)
and emdef switches (on page 45).
For information about the XML file name, see defcal XML file rules (on page 270).
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.

defcal XML file rules

The calendars that you create for use with the defcal utility are written in XML format and saved in a text
file. When this file is invoked, its contents are passed to the Control-M/EM database.
Instructions for creating an XML format input file are in XML file rules (on page 35).
The following rules apply to the defcal utility input file:

270
Control-M Utilities Guide

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

 The XML file is case-sensitive.
 The definition for a single calendar can cover a period of one or more years.
 All parameter values (such as strings or digits) must be enclosed in quotation marks (for example,
JOBNAME="Job1").
For more information on the input file parameters for the defcal utility, see defcal XML file parameters (on
page 271) and defcal XML file examples (on page 275).

defcal XML file parameters

The following table lists the defcal utility input file parameters:

Parameter Description

The first two lines of the XML request file for this API request contain information that
specifies the version of XML, the text encoding format being used, and the location of
the .dtd file.

DEFCAL Indicates to Control-M/EM database that the defcal utility is being

initiated. Calendar definitions are placed between the opening and
closing DEFCAL tags. One or more calendars can be specified.

CALENDAR Indicates the opening and closing tags of a single calendar definition.
The parameters of the job are listed between the tags.
<CALENDAR DATACENTER="EM5A" NAME="AcctJob1"
TYPE="Relative"></CALENDAR>

DATACENTER Name of the Control-M installation to which the

calendar definition belongs. String. Mandatory.

NAME Name of the calendar. String Mandatory.

TYPE Calendar type. Mandatory. Valid values:

 Regular
 Periodic
 Relative

271
Control-M Utilities Guide

Parameter Description

YEAR Year-specific definitions in the calendar. Mandatory.

EXAMPLE: YEAR NAME="2016"
DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYY
YYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNYYYYYYY
YY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YY
YYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYY
YY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNN
YY YYYYYYYYYYYYYYYYYYY"
DESCRIPTION="This is the Accounting Jobs calendar for
2016."

NAME Year for which the calendar definition applies. String.

Mandatory.
The year during which the calendar is active. Only one
year can be entered for this attribute, but more than
one YEAR parameters can be included in a calendar
definition.
The value of this attribute is expressed as YYYY (for
example, 2016).

272
Control-M Utilities Guide

Parameter Description

DAYS Days on which the job is ordered. String.

Mandatory.Valid values:
For a Relative calendar:
 Y
 N
 +
 -
For a Regular calendar:
 Y
 N
For a Periodic calendar:
any character other than Y, N, +, or -.
NOTE: Each Y and N represents a single day of the
year. The value of the DAYS parameter is 365
characters long (366 for a leap year). The first letter
of the DAYS value is January first. The last letter is
December 31.

DESCRIPTION Text description of the calendar. String. Optional. For

Regular and periodic calendars, only.

RULE_BASED Indicates the opening and closing tags of a single Rule-Based Calendar
_CALENDAR definition. The parameters of the job are listed between the tags.
<RULE_BASED_CALENDAR DATACENTER="EM5A"
NAME="AcctJob1"></RULE_BASED_CALENDAR>

DATACENTER Name of the Control-M installation to which the

calendar definition belongs. String. Mandatory.

NAME Name of the calendar. String Mandatory.

DAYS Days of the month on which the job is ordered. String.

Mandatory.

DAYS_AND_OR Indicates the relationship between specified Days

values and Weekdays values. Optional. Valid values:
 OR
 AND
Default: OR

273
Control-M Utilities Guide

Parameter Description

WEEKDAYS Days of the week on which to order the job. String.

Optional.
Valid values: Weekdays
 0-6
 ALL
 blank

DATE Specific dates on which to order the job. String.

MMDD format. Optional.

DAYSCAL Name of a user-defined calendar used to specify a set

of days. String. Optional.

WEEKSCAL Name of a calendar to be used to validate specified

weekdays on which to order the job. String. Optional.

CONFCAL Specifies a calendar that is used to validate all

specified days and dates on which to schedule the job.
String.

SHIFT Sub-parameter of CONFCAL. Describes how to shift

the scheduling date of the job. Valid values:
 IGNOREJOB
 PREVDAY
 NEXTDAY
 NOCONFCAL

SHIFTNUM Sub-parameter of CONFCAL. Number of days to shift

the scheduling date of the job. Default: +00

MAXWAIT Number of extra days (beyond the original scheduling

date) that the job is allowed to remain in the Active
Jobs database awaiting execution. Integer. Default: 00

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

274
Control-M Utilities Guide

Parameter Description

ACTIVE_FROM Starting date of the Rule-Based Calendar. Format:

YYYYMMDD

ACTIVE_TILL Ending date of the Rule-Based Calendar. Format:

YYYYMMDD

defcal XML file examples

The following are examples of argument files used with the defcal utility:
 Importing a regular calendar XML file example (on page 275)
 Import two calendars into different data centers XML file example (on page 276)

Importing a regular calendar XML file example

In the defcal XML file, a regular calendar, AcctCal3, is imported into the EM5NY data center.
<DEFCAL>
<CALENDAR
DATACENTER="EM5NY"
NAME="AcctCal3"
TYPE="Regular">
<YEAR
NAME="2016"
DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNY
YYYYYYYYYYYYYYYYYYYY"
DESCRIPTION="Calendar for 2016."/>
</CALENDAR>
</DEFCAL>

275
Control-M Utilities Guide

Import two calendars into different data centers XML file example
Two calendars are imported, each into a different data center, with a single defcal XML file.
<DEFCAL>
<CALENDAR
DATACENTER="EM5NY"
NAME="AcctCal3"
TYPE="Regular">
<YEAR
NAME="2016"
DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNY
YYYYYYYYYYYYYYYYYYYY"
DESCRIPTION="Calendar for 2016."/>
<CALENDAR
DATACENTER="EM2LA"
NAME="HRCal3"
TYPE="Regular">
<YEAR
NAME="2016"
DAYS="YYYYYYYYYYYYYYYYNNNYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYNNNNNYYYYYYYYYYYYYYYYNNNYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNY
YYYYYYYYYYYYYYYYYNNN"
DESCRIPTION="Calendar for 2016."/>
</CALENDAR>
</DEFCAL>

276
Control-M Utilities Guide

deffolder
The deffolder utility imports Folders and SMART Folders into the Control-M/EM database. To run the
deffolder utility, see Running the deffolder utility (on page 277).
When deffolder is invoked, a file of arguments that you have created is processed. This input file contains
statements that specify:
 an existing folder or set of folders
 an existing SMART Folder or set of SMART Folders.
For more information, see deffolder XML file rules (on page 278). The specified folders are imported into
the Control-M/EM database.
If the folders do not exist in the Control-M/EM database, the utility creates them. If the folders do exist, a
message is issued indicating that the folders already exist (unless the /o switch is specified, in which case
the folders are overwritten – the /o switch is described below).
The deffolder utility reads folder and SMART Folder definitions directly from a plain text arguments file (in
XML format) instead of reading them from the command line.
A single deffolder input file can contain specifications for both folders and SMART Folders.
NOTE: XML is comprised of elements and attributes. Each element can contain attributes and
sub-elements. In the folder that follows, elements are bolded and attributes are italicized.

Running the deffolder utility

This procedure describes how to run the deffolder utility, which enables you to import folders and SMART
Folders into the Control-M/EM database.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter either of the following commands:
• emdef deffolder [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -SRC_FILE <XML
file name> [/a] [/o] [/f]
• emdef deffolder [-u <user> [-p <password>] | -pf <password file>] -s <GUI
Server Name> -src <XML file name> [/a] [/o] [/f]
For more details on the defflolder parameters and switches, see emdef general parameters (on page
44) and emdef switches (on page 45).
For information about the XML file name, see deffolder XML file rules (on page 278).

277
Control-M Utilities Guide

deffolder XML file rules

The deffolder XML file contains the definition of a folder. 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, Folder and/or SMART Folder definitions are imported to the Control-M/EM
database. For instructions for creating input files, see XML file rules (on page 35).
The following rules apply to the deffolder XML file:
 Only one SMART Folder can be included in a folder. However, multiple folders can be included in a
single input file. Each of these folders can contain one SMART Folder.
 Multiple SMART Folders can be included in a file if the file only contains SMART Folders.
 More than one job can be specified in either type of folder.
 A single XML file can contain both Folders and SMART Folder parameters.
For more information on the input file parameters for the deffolder utility, see the following:
 deffolder XML file parameters for folders (on page 279)
 deffolder XML file parameters for SMART folders (on page 281)
 Folder with two jobs XML file (on page 287)
 SMART Folder with one job XML file (on page 289)
 Control-M Workload Change Manager XML file (on page 290)

278
Control-M Utilities Guide

deffolder XML file parameters for folders

The following table lists the deffolder XML file parameters for folders:

Parameter Description

The first two lines of the XML request file for this API request contain information that specifies the version
of XML, the text encoding format being used, and the location of the .xsd file.

DEFFOLDER Indicates to Control-M/EM database the beginning and end of the deffolder
utility. Folder definitions are placed between the opening and closing
DEFFOLDER tags. One or more folders can be specified. Each individual folder
is enclosed by the <FOLDER ENFORCE_VALIDATION><FOLDER> tags.

FOLDER Indicates the closing tags of a single folder definition. In the case of the folder,
the folder parameters consist of parameters that describe the folder directly
and a list of the jobs that are included in the folder. In turn, each of the jobs
that is listed includes all of its own descriptive parameters.

FOLDER Determines if validation is either an error or a warning.

ENFORCE_VALIDATION
Valid Values: Y or N
NOTE: Relevant for Control-M Workload Change Manager only.

FOLDER_ORDER_ Defines the Newday or User daily name. Optional.

METHOD

FOLDER_NAME Defines the name of the folder to which the job belongs. String. Mandatory.
NOTE: The following folder parameters must be specified for each folder:
 DATACENTER
 FOLDER_NAME
 FOLDER_DSN (z/OS only)

FOLDER_DSN (z/OS only) Defines the name of the library that contains the folder. String.
Optional.
NOTE: The following folder parameters must be specified for each folder:
 DATACENTER
 FOLDER_NAME
 FOLDER_DSN (z/OS only)

279
Control-M Utilities Guide

Parameter Description

DATACENTER Defines the name of the Control-M installation to which the folder belongs.
String. Mandatory.
NOTE: The following folder parameters must be specified for each folder:
 DATACENTER
 FOLDER_NAME
 FOLDER_DSN (z/OS only)

LAST_UPLOAD Date of the last folder upload. String. Optional.

JOB Opening and closing tags of a single job definition. Parameters of the job are
listed between the tags. For a complete listing of defjob parameters, see defjob
(on page 46).

CYCLIC_TYPE Determines the type of cyclic job:

 C: CYCLIC_TOLERANCE
 V: CYCLIC_INTERVAL_SEQUENCE
 S: CYCLIC_TIMES_SEQUENCE

CYCLIC_ Maximum delay in minutes permitted for a late submission when selecting a
TOLERANCE specific time (for example 5 minutes).

CYCLIC_INTERVAL_ A list of time intervals, separated by commas, (for example +30M,+2H,+1D)

SEQUENCE up to 4000 characters including commas.

CYCLIC_TIMES_ A list of times, separated by commas (for example 0800,1330,2300), which

SEQUENCE supports time synonym (for example 2730).

SITE_STANDARD_NAME Defines the name of the site standard that is applied to the folder and all of its
entities. For more information see Site standards management
NOTE: Relevant for Control-M Workload Change Manager only.

BUSINESS_PARAMETER_N Defines the name of the Business Parameter name that is applied to the folder
AME and all of its entities. For more information, see Site standards management
NOTE: Relevant for Control-M Workload Change Manager only.

VALUE Defines the value of a customer defined business field. String.

NOTE: Relevant for Control-M Workload Change Manager only.

280
Control-M Utilities Guide

deffolder XML file parameters for SMART folders

The following table lists the deffolder input file parameters for SMART folders:

Parameter Description

The first two lines of the XML request file for this API request contain information that specifies the version of
XML, the text encoding format being used, and the location of the .xsd file.

DEFFOLDER Indicates the beginning and end of the deffolder utility. Folder definitions are placed
between the opening and closing DEFFOLDER tags. One or more jobs can be
specified. Each individual job is enclosed by the <SMART_FOLDER
ENFORCE_VALIDATION></SMART_FOLDER> tag.

SMART_FOLDER Closing tags of a SMART Folder definition.

SMART_FOLDER Determines if validation is either an error or a warning.

ENFORCE_VALIDATIO
Valid Values: Y or N
N
NOTE: Relevant for Control-M Workload Change Manager only.

FOLDER_ORDER_ Defines the New day or User daily name. String. Optional.
METHOD

FOLDER_NAME Defines the name of the SMART Folder to which the job belongs. String. Mandatory.
NOTE:
 The following SMART Folder parameters must be specified for each folder:
DATACENTER
 FOLDER_NAME
 FOLDER_DSN (z/OS only)

DATACENTER Name of the Control-M installation to which the SMART Folder belongs. String.
Mandatory.
NOTE: The following folder parameters must be specified for each folder:
 DATACENTER
 FOLDER_NAME
 FOLDER_DSN (z/OS only)

FOLDER_DSN (z/OS only) Library for the folder. String. Optional.

NOTE: The following folder parameters must be specified for each folder:
 DATACENTER
 FOLDER_NAME
 FOLDER_DSN (z/OS only)

281
Control-M Utilities Guide

Parameter Description

CYCLIC_TYPE Determines the type of cyclic job:

 C: CYCLIC_TOLERANCE
 V: CYCLIC_INTERVAL_SEQUENCE
 S: CYCLIC_TIMES_SEQUENCE

CYCLIC_TOLERANCE Maximum delay in minutes permitted for a late submission when selecting a specific
time (for example 5 minutes).

CYCLIC_INTERVAL_SE A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up to

QUENCE 4000 characters including commas.

CYCLIC_TIMES_SEQUE A list of times, separated by commas (for example 0800,1330,2300), which supports
NCE time synonym (for example 2730).

LAST_UPLOAD Date of the last folder upload. String. Optional.

DAYSKEEPINNOTOK Enables you to specify a minimum period to keep the SMART folder (and jobs) in the
Active Jobs database after the folder is set to NOT OK.

REMOVEATONCE Indicates that all jobs in the folder are not removed automatically from the Active
Jobs database. Instead jobs wait for the folder to complete and are removed at the
same time as the folder. Relevant for all jobs in the SMART folder including jobs that
complete ok. Jobs are not automatically removed, but wait for the folder to
complete.

PARENT_FOLDER Defines the name of the parent folder to which the job's SMART Folder belongs.
String. Mandatory.

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

FILENAME Name of the file that contains the job script. String. Optional.

APPLICATION Name of the application to which the SMART Folder belongs. Used as a descriptive
name for related groups of SMART Folders. String. Mandatory.

SUB_APPLICATION Name of the group to which the jobs in the SMART Folder are assigned. String.
Mandatory.

RUN_AS Owner (user ID) associated with the SMART Folder. This parameter is used by the
Control-M/Server security mechanism. String. Optional.

ADJUST_COND Indicates whether to ignore prerequisite conditions normally set by predecessor jobs
if the relevant predecessor jobs are not scheduled. This parameter is relevant only
for jobs in a SMART Folder. String. Optional.

282
Control-M Utilities Guide

Parameter Description

CONFIRM Indicates that the SMART Folder must be manually confirmed by the Control-M/EM
user before it runs. Valid values:
 0 (No confirmation. Default.)
 1 (Requires confirmation.)

PRIORITY Indicates Control-M SMART Folder priority. String. Optional.

TIMEFROM Indicates the earliest time for submitting the SMART Folder. String. Optional.

TIMETO Indicates the latest time for submitting the SMART Folder. String. Optional.

DUE_OUT Time that the jobs in the SMART Folder are expected to finish. String. Optional.

DOCMEM Name of the file containing SMART Folder documentation. String. Optional.

DOCLIB Name of the DOCMEM library. String. Optional.

DESCRIPTION Brief text description of the SMART Folder. String. Optional.

CREATED BY Control-M/EM user who defined the SMART Folder. String. Mandatory.
NOTE: This argument is used by the Control-M security mechanism and, under
certain circumstances, cannot be modified. For more information, see the Security
chapter and the description of the AuthorSecurity system parameter in GUI Server
parameters.

USE_INSTREAM_JCL Indicates whether the job should use the INSTREAM_JCL.

Valid values: Y or N

CREATION_USER Name of the user who created the SMART Folder. String. Optional.

CREATION_DATE Date on which the SMART Folder was created. String. Optional.

CREATION_TIME Time at which the SMART Folder was created. String. Optional.

CHANGE_USERID Name of the user who last modified the SMART Folder. String. Optional.

CHANGE_DATE Date on which the SMART Folder was last modified. String. Optional.

CHANGE_TIME Time at which the SMART Folder was last modified. String. Optional.

283
Control-M Utilities Guide

Parameter Description

MULTY_AGENT If set to Y, job submission details are broadcasted to all agents within an Application
Group. The agent with available resources runs the jobs in the SMART Folder.
Optional.
Valid values:
 Y - run as a multi-agent job
 N - do not run as a multi-agent job. Default.

ACTIVE_FROM (z/OS jobs and SMART Folders, only) Indicates the start of a period of time during
which the job or SMART Folder can be ordered. Optional. Date Format: YYYYMMDD

ACTIVE_TILL (z/OS jobs and SMART Folders, only) Indicates the end of a period of time during
which the job or SMART Folder can be ordered. Optional. Date Format: YYYYMMDD

RULE_BASED_CALEND Identifies a set of scheduling criteria defined for a folder. Mandatory.

AR
EXAMPLE: RULE_BASED_CALENDAR
RULE_BASED_CALENDAR_NAME="RULE_BASED_CALENDAR1"
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"

RULE_BASED CALENDAR_NAME Defines the name of the Rule_Based_Calendar.

String. Mandatory.

DAYS Defines the days of the month on which to order

the jobs in the SMART Folder. String. Optional.

DAYS_AND_OR Indicates the relationship between specified Days

values and weekday values. Optional. Valid
Values:
 A: AND
 O: OR

WEEKDAYS Defines the days of the week on which to order

the job in the SMART Folder. Optional.

DATE Specific dates on which to order the jobs in the

SMART Folder. String. mmdd format. String.
Optional.

284
Control-M Utilities Guide

Parameter Description

DAYSCAL Name of a user-defined calendar used to specify a

set of days. String. Optional.

CONFCAL Specifies a calendar that is used to validate all

specified days and dates on which to schedule the
jobs in the SMART Folder. String. Optional.

RETRO Indicates whether the jobs in the SMART Folder is

scheduled for possible execution after their
original scheduling date (odate) has passed.
Optional. Applies only to Rule_Based_Calendars.
Valid values:
 0 (No. Default)
 1 (Yes)

SHIFT Describes how to shift the scheduling date of the

jobs in the SMART Folder. Optional. Valid values:
 Ignore Job
 Prev Day
 Next Day
 No confcal

SHIFTNUM Number of days to shift the scheduling date of the

jobs in the SMART Folder. String. Optional.

MAXWAIT Number of extra days (beyond the original

scheduling date) that the jobs in the SMART
Folder are allowed to remain in the Active Jobs
database awaiting execution.
The value of MAXWAIT in the
Rule_Based_Calendar is the value of the
MAXWAIT for the jobs that use this
Rule_Based_Calendar.
Integer. Optional

MAXRUNS Maximum number of job runs to retain the

SYSDATA archive data set for jobs that ended
NOTOK. Subparameter of AUTOARCH. String.
Valid values: 000 – 998, or 999 to retain the
archived data for all runs. Optional.

285
Control-M Utilities Guide

Parameter Description

JAN, FEB, MAR, APR, MAY, JUN, Months when the jobs in the SMART Folder can
JUL, AUG, SEP, OCT, NOV, DEC run. Optional. Valid values:
 0 (Default)
 1

TAG (SMART Folders only) Collection of scheduling criteria organized unit with a unique
name. Mandatory. This parameter is for backward compatibility.
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_NAMES Wrapper for specifying one or more TAGs for the SMART Folder. For backward
compatibility. This parameter is for backward compatibility.
EXAMPLE: TAG_NAMES TAG_NAME="TAG_1"

TAG_NAME Defines the unique name of the tag. String.

Mandatory.

JOB Indicates the opening and closing tags of a single job definition. The parameters of
the job are listed between the tags. For a complete listing of defjob parameters, see
defjob XML file parameters (on page 49).

SITE_STANDARD_NAM Defines the name of the site standard that is applied to the folder and all of its
E entities. For more information see Site standards management
NOTE: Relevant for Control-M Workload Change Manager only.

BUSINESS_PARAMETE Defines the name of the Business Parameter name that is applied to the folder and
R_NAME all of its entities. For more information, see Site standards management
NOTE: Relevant for Control-M Workload Change Manager only.

VALUE Defines the value of a customer defined business field. String.

NOTE: Relevant for Control-M Workload Change Manager only.

286
Control-M Utilities Guide

Folder with two jobs XML file

In the following example, in the deffolder XML file, specify a folder with two jobs:
<FOLDER ENFORCE_VALIDATION="N" TYPE="1"
FOLDER_ORDER_METHOD="SYSTEM"
FOLDER_NAME="Folder#2"
PLATFORM="UNIX"
VERSION="900"
DATACENTER="bmc-user">
<JOB PARENT_FOLDER="Folder#2"
CYCLIC_TYPE="C"
CYCLIC_TOLERANCE="3"
CYCLIC_INTERVAL_SEQUENCE="+5M"
USE_INSTREAM_JCL="N"
ACTIVE_TILL="20170226"
ACTIVE_FROM="20170201"
MULTY_AGENT="N"
APPL_TYPE="OS"
TIMEZONE="GMT"
RULE_BASED_CALENDAR_RELATIONSHIP="O"
IND_CYCLIC="S"
SYSDB="1"
SHIFTNUM="+00"
SHIFT="Next Day"
DAYS_AND_OR="O"
DEC="1" NOV="1" OCT="1" SEP="1" AUG="1" JUL="1" JUN="1" MAY="1" APR="1" MAR="1"
FEB="1" JAN="1"
DAYS="ALL"
MAXRUNS="0"
MAXDAYS="0"
AUTOARCH="1"
MAXRERUN="1"
MAXWAIT="98"
RETRO="1"
CONFCAL="Calendar1"
CONFIRM="0"

287
Control-M Utilities Guide

CMDLINE="echo_33"
INTERVAL="00001M"
CYCLIC="1"
TASKTYPE="Command"
CRITICAL="0"
RUN_AS="emuser"
CREATED_BY="emuser"
JOBNAME="OS_Job#1"/>
<JOB PARENT_FOLDER="Folder#2"
CYCLIC_TYPE="C"
CYCLIC_TOLERANCE="0"
USE_INSTREAM_JCL="N"
MULTY_AGENT="N"
APPL_TYPE="OS"
RULE_BASED_CALENDAR_RELATIONSHIP="O"
IND_CYCLIC="S"
SYSDB="1"
SHIFTNUM="+00"
SHIFT="Ignore Job"
DAYS_AND_OR="O"
DEC="1" NOV="1" OCT="1" SEP="1" AUG="1" JUL="1" JUN="1" MAY="1" APR="1" MAR="1"
FEB="1" JAN="1"
DAYS="ALL"
MAXRUNS="0"
MAXDAYS="0"
AUTOARCH="1"
MAXRERUN="0"
MAXWAIT="0"
RETRO="0"
CONFIRM="0"
CMDLINE="echo_30"
INTERVAL="00001M"
CYCLIC="0"
TASKTYPE="Command"
CRITICAL="0"

288
Control-M Utilities Guide

RUN_AS="emuser"
CREATED_BY="emuser"
JOBNAME="OS_Job#3"/>
</FOLDER>
</DEFTABLE>

SMART Folder with one job XML file

In the following example, in the deffolder XML file, define a SMART Folder with one job:
<SMART_FOLDER ENFORCE_VALIDATION="N"
TYPE="2" REAL_FOLDER_ID="0" FOLDER_ORDER_METHOD="SYSTEM"
FOLDER_NAME="EX_Monthly" PLATFORM="MPM" VERSION="900"
DATACENTER="vw-tlv-idd-dv03"
DAYSKEEPINNOTOK="5" REMOVEATONCE="Y"
PARENT_FOLDER="EX_Monthly"
CYCLIC_TYPE="C" CYCLIC_TOLERANCE="0" USE_INSTREAM_JCL="N"
APPL_TYPE="OS" IND_CYCLIC="S" ADJUST_COND="N" SYSDB="1" SHIFT="Ignore Job"
DAYS_AND_OR="O"
DEC="1" NOV="1" OCT="1" SEP="1" AUG="1" JUL="1" JUN="1" MAY="1" APR="1" MAR="1"
FEB="1" JAN="1" DAYS="ALL"
MAXRUNS="0" MAXDAYS="0" AUTOARCH="1" MAXRERUN="0" MAXWAIT="5" RETRO="0"
CONFIRM="0" INTERVAL="00001M" CYCLIC="0"
TASKTYPE="SMART Table"
CRITICAL="0"
RUN_AS="emuser"
CREATED_BY="emuser"
DESCRIPTION="Monthly expenses"
JOBNAME="EX_Monthly"
SUB_APPLICATION="Global"
APPLICATION="Control-M_Housekeeping" JOBISN="0">
<JOB PARENT_FOLDER="EX_Monthly"
CYCLIC_TYPE="C" CYCLIC_TOLERANCE="0" USE_INSTREAM_JCL="N" APPL_TYPE="OS"
IND_CYCLIC="S" SYSDB="0" SHIFT="Ignore Job" DAYS_AND_OR="O"
DEC="1" NOV="1" OCT="1" SEP="1" AUG="1" JUL="1" JUN="1" MAY="1" APR="1" MAR="1"
FEB="1" JAN="1" DAYS="1"
MAXRUNS="0" MAXDAYS="0" AUTOARCH="0" MAXRERUN="0" MAXWAIT="0" RETRO="0"
CONFIRM="0" INTERVAL="00000M" CYCLIC="0"
TASKTYPE="Job" CRITICAL="0" RUN_AS="emuser" CREATED_BY="emuser"

289
Control-M Utilities Guide

DESCRIPTION="Calculate the salaries and taxes per employee"

JOBNAME="CalcSalaries"
SUB_APPLICATION="Global" APPLICATION="Control-M_Housekeeping"
JOBISN="0" MULTY_AGENT="N" RULE_BASED_CALENDAR_RELATIONSHIP="O"
CREATION_TIME="135959" CREATION_DATE="20060315" CREATION_USER="emuser"
PAR="%%HOSTID:\Output\CheckPrintingOutput.txt"
OPTION="Copy" SHIFTNUM="+00" TIMETO="0300" TIMEFROM="0100"
MEMLIB="C:\Program Files\BMC Software\CONTROL-M EM 9.0.00\Default\Samples"
DOCMEM="CalcSalaries.txt"
DOCLIB="C:\Program Files\BMC Software\CONTROL-M EM 9.0.00\Default\Samples"
MEMNAME="CalcSalaries.bat">
<SHOUT MESSAGE="Pay checks can now be printed." DEST="[email protected]"
URGENCY="V" WHEN="OK"/>
<INCOND AND_OR="A" ODATE="ODAT" NAME="EX_TimeSheetsSubmitted"/>
<OUTCOND ODATE="ODAT" NAME="EX_CalcSalariesOK" SIGN="+"/>
</JOB>
<RULE_BASED_CALENDAR SHIFT="Ignore Job" DAYS_AND_OR="O" DEC="1" NOV="1"
OCT="1" SEP="1" AUG="1" JUL="1" JUN="1" MAY="1" APR="1" MAR="1" FEB="1" JAN="1"
DAYS="ALL" MAXWAIT="00" RETRO="0" NAME="EVERYDAY" LEVEL="N"/>
</SMART_FOLDER>

Control-M Workload Change Manager XML file

The following example describes the Control-M Workload Change Manager for the defolder utility input
file.
<DEFTABLE xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="Folder.xsd">
<FOLDER DATACENTER="vw-tlv-em-dv131"
VERSION="800"
PLATFORM="UNIX"
FOLDER_NAME="rt"
FOLDER_ORDER_METHOD="SYSTEM" REAL_FOLDER_ID="153" TYPE="1"
ENFORCE_VALIDATION="N" SITE_STANDARD_NAME="st_acc">
<JOB JOBISN="1"
JOBNAME="OS_Job#1"
CREATED_BY="emuser"
RUN_AS="a"
CRITICAL="0"

290
Control-M Utilities Guide

TASKTYPE="Command"
CYCLIC="0"
INTERVAL="00001M"
CMDLINE="a"
CONFIRM="0"
RETRO="0"
MAXWAIT="0"
MAXRERUN="0"
AUTOARCH="1"
MAXDAYS="0"
MAXRUNS="0"
DAYS="ALL"
JAN="1"
FEB="1"
MAR="1"
APR="1"
MAY="1"
JUN="1"
JUL="1"
AUG="1"
SEP="1"
OCT="1"
NOV="1"
DEC="1"
DAYS_AND_OR="O"
SHIFT="Ignore Job"
SHIFTNUM="+00"
SYSDB="1"
IND_CYCLIC="S"
CREATION_USER="emuser"
CREATION_DATE="20130728"
CREATION_TIME="215511"
RULE_BASED_CALENDAR_RELATIONSHIP="O"
APPL_TYPE="OS"
MULTY_AGENT="N"

291
Control-M Utilities Guide

USE_INSTREAM_JCL="N"
VERSION_OPCODE="N"
IS_CURRENT_VERSION="Y"
VERSION_SERIAL="1"
VERSION_HOST="BMC-HSD2GV1"
CYCLIC_TOLERANCE="0"
CYCLIC_TYPE="C"
PARENT_FOLDER="rt" />
<ADDITIONAL_FOLDER_DETAILS>
<BUSINESS_PARAMETER NAME="Dept" VALUE="Finance" />
</ADDITIONAL_FOLDER_DETAILS>
</FOLDER>
</DEFTABLE>

exportdefcal
The exportdefcal utility exports calendar definitions in the Control-M/EM database to an output file for use
as input to other utilities. To export calendar definition using the exportdefcal utility, see Exporting
calendar definitions using exportdefcal utility (on page 293).
When the exportdefcal utility is invoked, an arguments file that you prepare is processed. This arguments
file contains statements that specify an existing calendar or group of calendars. The calendars that you
specified in the arguments file are exported to an output file. You can modify the exported calendars in
the output file and re-import them into the Control-M/EM database using the defcal utility. For more
information, see exportdefcal arguments file rules (on page 293).
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.
NOTE: The exportdefcal utility only exports Control-M level Rule-Based Calendars. To export Folder level
Rule-Based Calendars, use the exportdeffolder utility (as TAGs were previously exported).

292
Control-M Utilities Guide

Exporting calendar definitions using exportdefcal utility

This procedure describes how export calendar definitions in the Control-M/EM database to a text file using
the exportdefcal utility.
 To export calendar definitions:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter one of the following commands:
• emdef exportdefcal [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <args
file name> -OUT_FILE <File Name>
• emdef exportdefcal [-u <user> [-p <password>] | -pf <password file>] -s
<GUI Server Name> -arg <args file name> -out <File name>
NOTE: For Windows, you do not need to use the emdef prefix.
For more details on the exportdeffolder parameters and options, see emdef general parameters (on
page 44) and emdef switches (on page 45).
For information about args file name, see exportdefcal arguments file rules (on page 293).

exportdefcal arguments file rules

Arguments are used as a selection criteria to determine which calendars to export. Arguments are written
to the exportdefcal argument file. The arguments files that you create with the exportdefcal utility are
written in XML format and saved in a text file. The format in which this file must be written is described
on the following pages.
When this file is invoked, calendar definitions are exported from the Control-M/EM database. For
instructions for creating arguments files, see XML file rules (on page 35).
The following rules apply to the exportdefcal arguments file:
 More than one calendar can be specified in an exportdefcal file.
 The arguments file is case-sensitive.
 All parameter values (such as strings or digits) must be enclosed in quotation marks (for example,
JOBNAME="Job1").
 More than one PARAM parameter can be used in a TERM statement.
 The relationship between PARAM parameters in a TERM statement is AND. The relationship between
TERM statements is OR.
For more information on the input file parameters for the exportdefcal utility, see exportdefcal arguments
file parameters (on page 294) and exportdefcal arguments file examples (on page 296).

293
Control-M Utilities Guide

exportdefcal arguments file parameters

The following table lists the exportdefcal arguments file parameters:

Parameter Description

The first two lines of the XML request file for this API request contain information that specifies the version
of XML, the text encoding format being used, and the location of the .dtd file.

TERMS These tags indicate the start and end of the TERMS file. Only criteria that are
located between the tags are considered to be part of the argument.

TERM The TERM tags indicate the start and the end of a group of selection criteria used
to specify a calendar or calendars that are to be exported. Only PARAM tags that
are located between the TERM tags are considered to be part of the TERM
argument.

REL Optional. Relationship between terms. Valid values:

 AND
 OR

294
Control-M Utilities Guide

Parameter Description

PARAM The selection criteria parameter used to determine those calendars that are to be
exported. More than one PARAM can be specified. Mandatory.
PARAM NAME="DATACENTER" OP="EQ" VALUE="Center1"

NAME String. Specify at least one of the following calendar parameter

names.
Valid values:
 DATACENTER
 CALENDAR
 TYPE

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

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

VALUE String. Mandatory. Value of the parameter specified in the NAME field.
 If the value of NAME is DATACENTER, enter the name of the
Control-M installation for VALUE.
 If the value of NAME is CALENDAR, enter a calendar name.
 If the value of NAME is TYPE, enter one of the following calendar
types: Relative, Regular, Periodic, Rule_Based

295
Control-M Utilities Guide

exportdefcal arguments file examples

The following are examples of argument files used with the exportdefcal utility:
 Exporting calendars XML file example (on page 296)
 Exporting and importing a Rule-Based Calendar XML file example (on page 296)

Exporting calendars XML file example

In this example, all calendars are exported in the data center named Data1. The output file contains all
calendars in data center Data1 that are named Cal1.
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="Data1"/>
<PARAM NAME="CALENDAR" OP="EQ" VALUE="CAL1"/>
</TERM>
</TERMS>

Exporting and importing a Rule-Based Calendar XML file example

In this example, an arguments file, export_def_cal.arg (shown in export_def_cal.arg exportdefcal
arguments file), is used to export, all the Rule-Based Calendars that contain the "RuleBased" string in
their names. The exportdefcal command (shown in export command is used to export the Rule-Based
Calendar definition, RuleBasedCal, from the emdevA Control-M/EM GUI server to the RuleBaseC.txt
export file. This export file is then used with the defcal command to import RuleBasedCal to the emdevB
Control-M/EM GUI server.
export_def_cal.arg exportdefcal arguments file
<TERMS>
<TERM>
<PARAM NAME="CALENDAR" OP="LIKE" VALUE="RuleBased*"/>
<PARAM NAME="TYPE" OP="LIKE" VALUE="Rule_Based"/>
</TERM>
</TERMS>
export command
emdef exportdefcal -u userA -p passA -s emdevA -arg
\\netA\devpub\xargs\Arg\export_def_cal.arg -out
\\netA\devpub\xargs\Arg\RuleBaseC.txt

296
Control-M Utilities Guide

The RuleBaseC.txt XML output file

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE DEFCAL SYSTEM "defcal.dtd">
<DEFCAL >
<RULE_BASED_CALENDAR
ACTIVE_FROM="20101024"
ACTIVE_TILL="20101021"
APR="0"
AUG="0"
DATACENTER="dcDist_700"
DAYS="1,2"
DAYS_AND_OR="OR"
DEC="0"
FEB="0"
JAN="0"
JUL="0"
JUN="0"
MAR="0"
MAXWAIT="00"
MAY="0"
NAME="RuleBasedCal"
NOV="1"
OCT="0"
SEP="0"
SHIFT="IGNOREJOB"
SHIFTNUM="+00"
WEEKDAYS="0"
/>
</DEFCAL>
import command
emdef defcal -u useB -p passB -s emdevB -src
\\netA\devpub\xargs\Arg\RuleBaseC.txt /o

297
Control-M Utilities Guide

exportdeffolder
The exportdeffolder utility exports folders from the Control-M/EM database to a text file. To export folders
using the exportdeffolder utility, see Exporting folders using the exportdeffolder utility (on page 298).
When the exportdeffolder utility is invoked, a file of arguments that you have created is processed. This
arguments file contains statements that specify an existing folder, SMART Folders and Sub-folders. The
specified folders are exported to an output file. For more information, see exportdeffolder arguments file
(on page 298).
Output files created with the exportdeffolder utility can be used as import files with the deffolder utility.
For example, you can export job processing definitions to an output file using exportdeffolder, make
modifications to the definitions and save the file, and use the same file as the input file when running
deffolder to import the modified folder definitions into Control-M/EM database.

Exporting folders using the exportdeffolder utility

This procedure describes how to export folder definitions in the Control-M/EM database to an output file
for use as input to other utilities using the exportdeffolder utility

 To export folders:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Enter one of the following commands:
• emdef exportdeffolder [-USERNAME <user> [-PASSWORD <password>] |
-PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <args
file name> -OUT_FILE <File Name>
• emdef exportdeffolder [-u <user> [-p <password>] | -pf <password file>]
-s <GUI Server Name> -arg <args file name> -out <File name>
For more details on the exportdeffolder parameters and options, see emdef general parameters (on
page 44) and emdef switches (on page 45).
For details about the args file name, see exportdeffolder arguments file (on page 298).

exportdeffolder arguments file

Arguments are used as a s election criteria to determine which folders to export. Arguments are written to
the exportdeffolder argument file.
The arguments files that you create with the exportdeffolder 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, folder definitions are exported from the Control-M/EM database. For instructions
for creating arguments files, see XML file rules (on page 35).

298
Control-M Utilities Guide

The following rules apply to the exportdeffolder arguments file:

 More than one job can be specified in an exportdeffolder 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.
The exportdeffolder arguments file is checked and processed. If there are any errors in the file, a
message is displayed specifying the lines with errors.
The exported folder definitions are saved to an output file, the name and location of which is specified in
the outFileName parameter.
For more information on the arguments file parameters for the exportdeffolder utility, see exportdeffolder
arguments file parameters (on page 299) and exportdeffolder examples (on page 301).

exportdeffolder arguments file parameters

The following table lists the exportdeffolder arguments file parameters:

Parameter Description

The first two lines of the XML request file for this API request contain information that specifies the version
of XML, the text encoding format being used, and the location of the .dtd file.

TERMS These tags indicate the start and end of the TERMS file. Only criteria that are
located between the tags are considered to be part of the argument.

TERM The TERM tags indicate the start and the end of a group of selection criteria used
to specify a folder or folders 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

299
Control-M Utilities Guide

Parameter Description

PARAM The selection criteria parameter used to determine those folders that are to be
exported. More than one PARAM can be specified. Mandatory.
PARAM NAME="DATACENTER" OP="EQ" VALUE="Center1"

NAME String. Mandatory.

The parameter name of any folder or SMART Folder parameter. These
parameters are described in deffolder (on page 277).
NOTE: At least one of the following folder parameters must be
included in the arguments file: DATACENTER, FOLDER_NAME,
FOLDER_DSN

OP Mandatory.
Describes the relationship between the NAME and the VALUE
parameters of the TERM. Valid values:
 EQ
 NEQ
 NOTIN
 LIKE

VALUE String. Mandatory.

The value of any folder, SMART Folder or Sub-folder parameter. These
parameters are described in deffolder (on page 277).
NOTE: Multiple values can be specified for VALUE by using the *
wildcard character in place of characters at the end of an expression.

CYCLIC_TYPE Determines the type of cyclic job:

 Interval
 IntervalSequence
 SpecificTimes
Relevant for Control-M version 6.4.01 or later.

CYCLIC_ Maximum delay in minutes permitted for a late submission when selecting a
TOLERANCE specific time (for example 5 minutes).
Relevant for Control-M version 6.4.01 or later.

CYCLIC_INTERVAL_ A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up

SEQUENCE to 4000 characters including commas.
Relevant for Control-M version 6.4.01 or later.

300
Control-M Utilities Guide

Parameter Description

CYCLIC_TIMES_ A list of times, separated by commas (for example 0800,1330,2300), which

SEQUENCE supports time synonym (for example 2730).
Relevant for Control-M version 6.4.01 or later.

MAXWAIT Number of extra days (beyond the original scheduling date) that the jobs in the
SMART Folder are allowed to remain in the Active Jobs database awaiting
execution.
The value of MAXWAIT in the Rule_Based_Calendar is the value of the MAXWAIT
for the jobs that use this Rule_Based_Calendar.
Integer. Optional.

REMOVEATONCE Indicates that all jobs in the folder are not removed automatically from the Active
Jobs database. Instead jobs wait for the folder to complete and are removed at
the same time as the folder.
Valid values:
 Y: Yes
 N: No (default)

DAYSKEEPINNOTOK Enables you to specify a minimum period to keep the SMART folder (and jobs) in
the Active Jobs database after the folder is set to NOT OK.
Valid values:
 0-98 (default 0)
 99: Forever

exportdeffolder examples
Following are examples of arguments files used with the exportdeffolder utility:
Export all folders in the Data1 data center
<TERMS>
<TERM>
<PARAM NAME="DATACENTER" OP="EQ"
VALUE="Data1"/>
</TERM>
</TERMS>
Export with multiple selection criteria
Exported SMART Folders that are located in data center Data1 and belong to the GRP_03 SMART
Folder, or located in data center Data1 and belong to the GRP_04 SMART Folder:

301
Control-M Utilities Guide

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

cli utility
The Command Line Interface (cli) utility is a batch utility that enables you to perform the following
operations (services) from the command line:
 Order jobs, as described in Ordering jobs using the cli utility (on page 305).
 Force jobs, as described in Forcing a job using the cli utility (on page 306).
 Force jobs in a folder, as described in Forcing a job into a folder (on page 306).
 Upload folders and download folders, as described in Uploading and downloading folders using the cli
utility (on page 307).
 Order Folders, as described in Ordering folders (on page 310).
 Force jobs, as described in Forcing folders using the cli utility (on page 308).
 Upload or download calendars, as described in Uploading and downloading calendars (on page 308).
 Delete job processing definitions from folders, as described in Deleting job definitions by Job Name
(on page 311).
 Activate a Workload Policy Definition, as described in Activating a workload policy definition using the
cli utility (on page 313).
The cli utility can be used on UNIX and Windows computers. The cli utility is installed automatically on
Windows computers during installation of the Control-M/EM Gateway, GUI server, and Control-M
Configuration Manager components.
Many of the tasks performed by the cli utility can also be performed using Control-M. 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.
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.

302
Control-M Utilities Guide

Some of the parameter names changed for Control-M version 8.0.00 and above, terminology from
previous versions is still supported. For a complete list of the parameter names, see Abbreviations and
conventions.

cli parameters
The following table lists the cli utility parameters:

Parameter Description

<user_name> Defines the Control-M/EM database user name.

<password> Defines the Control-M/EM database user password.

<password file> Flat file containing an unencrypted user name and password on
separate lines in the format:
user=<emUser>
password=<emPass>

<Server Name> Defines the host name of the workstation running Control-M/EM
database Server.
NOTE: If you need to address a GUI server and multiple GUI servers
exist, set this parameter to the logical name of the relevant GUI
server.

<timeout in Defines the time, in seconds, that the utility waits for a response.
seconds> Timeout is used to override the default waiting period (120 seconds).
NOTE: Do not use timeout with commands that do not return a
response (-JOB_DELETE and -MEM_DELETE).

-DDMM If specified, reverses the Odate format, as described below.

-BY_FORCE Forces the specified folder or calendar. Use this option during upload
only.

-ACTION_REASON A note saved in the audit report explaining the purpose for performing
the action.

-ACTION_NOTE A note saved in the audit report justifying the performance of the
action.

<cmd> The syntax for additional commands that are available for specifying
with the cli utility.

<ctm_name> Defines the Control-M name.

<job_name> Defines the name of the job.

303
Control-M Utilities Guide

Parameter Description

<folder_name> Defines the name of the folder.

<sub_folder_name Defines the name of sub folder.

>

<Control-M Defines the name of the Control-M Calendar you want to upload or
Calendar> download.

<Odate> Specify either as: MMDD or YYYYMMDD.

<Odate> may also be ODAT for Control-M version 6.0.00 or later
(Order or Force Folder in the Original Scheduling Date)
If the -DDMM is specified, <Odate> can be specified as DDMM or
DDMMYYYY

<folder> Valid values are:

 RECENT: Orders/forces a job into the recent SMART Folder that
was previously ordered
 NEW: Orders/forces a job into a new folder
 STANDALONE: Orders/Forces a job as a standalone job
 <TableID>: Orders/forces a job/subfolder into a specified folder

<Duplication> Specify if <folder> is RECENT or <TableID>, otherwise do not

specify.
Specify one of the following values:
 N - Do not allow duplication of the job.
 Y - Allow duplication of the job.

<Wait_Odate> Determines whether you should wait for the Order date to run the job.
 For Control-M for Z/OS this field is Mandatory. Valid values are:
Y - Wait for Order date to run job.
N - Run the job immediately.
For Control-M for Distributed Systems this field is optional. If omitted,
the job runs immediately. If not omitted, the only valid value is
Wait_Odate, which means wait for Order date to run the job.

<With_Hold> Enables you to hold all jobs immediately after they are ordered.
Specify one of the following values:
 N - Order/Force the job in a free state.
 Y or With_Hold - Order/Force the job in a Hold state.

304
Control-M Utilities Guide

Parameter Description

<UNIQUE_FLOW> Determines if a flow in a folder is ordered uniquely. This is only

relevant if you are ordering a single folder created in Control-M/EM
version 8.0.00 and above. A unique suffix is added to every condition
name.
Valid values:
 Yes
 No

<library> (Control-M for z/OS only) Defines the name of the library in which the
folder is located.

<RBC> Indicates whether the calendar is a Rule Based Calendar (RBC).

Values:
 N: Not an RBC (default)
 Y: Is an RBC

Ordering jobs using the cli utility

The following procedure describes how to order jobs using the cli utility.

 To order jobs:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
[-T <timeout in seconds>] [-DDMM] [-BY_FORCE] -JOB_ORDER <CTM_name>
<folder_name> <job_name> <Odate> <Wait_Odate> [<With_Hold>] [<library>]
NOTE: UNIX: Add the em prefix before cli.
When forcing or ordering a job, Control-M/EM does not check if multiple jobs with the same name
exist in the folder.
For more details about the cli parameters, see cli parameters (on page 303). For the Control-M parameter
name, see Parameter name cross references (on page 31).

305
Control-M Utilities Guide

Forcing a job using the cli utility

The following procedure describe how to force jobs using the cli utility.

 To force a job:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
[-t timeout in seconds] [-DDMM] -JOB_FORCE <CTM_name> <folder_name>
<job_name> [<Odate>] [<library>]
NOTE: UNIX: Add the em prefix before cli.
For more information on the forcing a job parameters, see cli parameters (on page 303) and Force a job
parameters (on page 307).

Forcing a job into a folder

The following procedure describes how to force a job into a folder.

 To force a job into a folder:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
[-t timeout in seconds] [-DDMM] -JOB_FORCE_INTO <CTM_name> <folder_name>
<job_name> <folder> [<duplication>] [<Odate>] [<library>]
NOTE: For UNIX, type the em prefix before cli.
For more information on the forcing a job parameters, see cli parameters (on page 303) and Force a
job parameters (on page 307).

306
Control-M Utilities Guide

Force a job parameters

The following table lists the parameters for forcing a job commands:

Parameters Description

folder Folder into which the job is forced. Valid values:

RECENT Forces the job into the folder that was run most
recently.

NEW Creates a new folder.

STAND Forces the job without adding it to a folder.

ALONE

TableID Folder into which the job is forced.

[duplication] Adds a job to a folder, even if there is a job with that name in the
folder. 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 TableID are
selected for folder.

Uploading and downloading folders using the cli utility

This procedure describes a series of commands that enable you to perform various tasks. Sub-folders
cannot be uploaded or downloaded independently.

 To upload and download folders:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Do one of the following:
• Upload a folder: Type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server
Name> [-t timeout in seconds] -FOLDER_UPLOAD <CTM_name> <folder_name>
[<Odat>] [<library>]

307
Control-M Utilities Guide

NOTE: UNIX: Add the em prefix before cli.

• Download a folder: Type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server
Name> [-t timeout in seconds] -FOLDER_DOWNLOAD <CTM_name> <folder_name>
[<library>]
NOTE: UNIX: Add the em prefix before cli.
For more details about the cli parameters, see cli parameters (on page 303).

Forcing folders using the cli utility

This procedure describes how to force a folder. Sub-folders cannot be forced, except into a SMART
Folder.

 To force folders:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
[-t timeout in seconds] [-DDMM] -FOLDER_FORCE <CTM_name> <folder_name>
[<Odate>] [<library>]
NOTE: UNIX: Add the em prefix before cli.
For more details on the cli parameters, see cli parameters (on page 303).

Uploading and downloading calendars

This procedure describes how to upload and download calendars using the cli utility.
 To upload and download calendars using the cli utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. To upload a calendar, type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
[-t timeout in seconds] -CAL_UPLOAD <Control-M Calendar>

308
Control-M Utilities Guide

NOTE: UNIX: Add the em prefix before cli.

3. To download a calendar, type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
[-t timeout in seconds] -CAL_DOWNLOAD <Control-M Calendar>
NOTE: UNIX: Add the em prefix before cli.

Forcing Sub-folders into a SMART folder

The following procedure describes how to force a Sub-folder into a SMART Folder.

 To force Sub-folders into a SMART folder:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
[-t timeout in seconds] [-DDMM] -SUB-FOLDER_FORCE_INTO <CTM_name>
<sub_folder_name> <folder> [<Duplication>]<Odate> <Wait_Odate>
[<With_Hold>]
NOTE: UNIX: Add the em prefix before cli.
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the cli parameters, see the following:
 cli parameters (on page 303)
 Force Sub-folder into SMART Folder parameters (on page 310)

309
Control-M Utilities Guide

Force Sub-folder into SMART Folder parameters

The following table lists the parameters for the force Sub-folder into SMART folder commands:

Parameters Description

folder SMART Folder into which the Sub Folder is forced. Values:
 RECENT: Forces the Sub Folder into the SMART
Folder that was run most recently.
 NEW: Creates a new folder

smart_folderID Defines the SMART Folder ID.

duplication Adds a Sub-folder to a SMART Folder, even if there is a Sub-folder

with that name in the SMART Folder. Valid values:
 Y – Adds the Sub-folder, if required.
 N – Does not create a duplicate Sub-folder if a Sub-folder of the
same name already exists
NOTE: This setting can be used only when RECENT or
smart_folderID are selected for folder.

Ordering folders
This procedure describes how to order folders using the cli utility.
 To order folders:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
[-T timeout in seconds] [-DDMM] -FOLDER_ORDER <CTM_name> <folder_name>
[<Odate>] [<library>]
NOTE: UNIX: Add the em prefix before cli.
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the cli parameters, see cli parameters (on page 303) and cli additional parameters.

310
Control-M Utilities Guide

Deleting Sub-folders
This procedure describes how to delete Sub-folders using the cli utility which enables you to delete the
Sub-folder from the Control-M/EM database only. Sub-folders in the Control-M/Server database are not
affected.

 To delete Sub-folders:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
-SUB-FOLDER_DELETE <CTM_name> <sub_folder_Name>
NOTE: UNIX: Add the em prefix before cli.
Deleting Sub-folders using the cli utility will delete all of the Sub-folders contents. If you only want to
delete a job use the -JOB_DELETE command.

Deleting job definitions by Job Name

The following procedure describes how to delete a job definitions using the cli utility. This deletes the job
definitions from the Control-M/EM database only. Job definitions in the Control-M/Server database are not
affected.
 To delete job definitions by Job Name:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type the following command:
cli [[-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
-JOB_DELETE <CTM_name> <folder_name> <job_name> ALL/NONE/NUMBER
[<library>]
NOTE: UNIX: Add the em prefix before cli.
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the cli parameters, see cli parameters (on page 303) and Delete a job definition parameters (on page
313).

311
Control-M Utilities Guide

Deleting job definition by File Name

The following procedure describes how to delete a job definitions using the cli utility. This deletes the job
definitions from the Control-M/EM database only. Job definitions in the Control-M/Server database are not
affected.

 To delete a job definition by File Name:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type the following command:
cli [[-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
-MEM_DELETE <CTM_name> <folder_name> <mem_name> ALL/NONE/NUMBER
[<library>]
NOTE: UNIX: Add the em prefix before cli.
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the cli parameters, see cli parameters (on page 303) and Delete a job definition parameters (on page
313).

312
Control-M Utilities Guide

Delete a job definition parameters

The following table lists the parameters for deleting a job definition commands:

Parameter Description

mem_name Indicates the name of the file that contains the job script, or for z/OS jobs,
the name of a member that contains one of the following in relation to the
job to be executed:
 The JCL of the job
 The started task procedure
 Warning messages

ALL All occurrences of the job are deleted, if there is more than one job with the
same name.

NONE No jobs are deleted if there is more than one job with the same name.

NUMBER Deletes the job with the specified sequence number of the duplicate job (for
example, if 5 is entered, the fifth occurrence of the Job Name is deleted).

library Required for z/OS job definitions.

Activating a workload policy definition using the cli utility

This procedure describes how to activate a Workload Policy definition using the cli utility, which enforces
all the rules of the Workload Policy definition on the associated jobs.

 To upload and download calendars using the cli utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
2. To upload activate a Workload Policy Definition, type the following command:
cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name>
[-t timeout in seconds] -WORKLOAD_ACTIVATE <Workload_name> Y/N
NOTE: UNIX: Add the em prefix before cli.

313
Control-M Utilities Guide

Running the Control-M/EM API

This procedure describes how to run the Control-M/EM API with a CLI command. You can run a command
that calls the Control-M/EM API XML request and response files. These files include the request/response
XML parameters related to the specified operation such as Create folder definition, User registration and
Job creation.

 To run the Control-M/EM API:

 Type the following command:
emapi_cli [{(-U <emUser> -P <emPass>) | -pf <passwordFile>}] -s
<GSRHostName> -arg <request_xml_file> -out <response_xml_file>
NOTE: In the command line, you can use (-U <emUser> -P <emPAss>) OR -pf
<passwordFile>.The name service host <hostname> is taken from the config.xml file on the
server from where you are running the command line. To configure CLI to work in SSL mode, you
must configure the jacorb.properties file as described in Configuring Control-M/EM API JacORB.

Control-M/EM API CLI parameters

The following table describes the CLI command parameters for Control-M/EM API.

Parameter Description

<emUser> Defines the Control-M/EM administrator name.

<emPass> Defines the Control-M/EM administrator password.

<GSRHostName> Defines the host name of the computer running Control-M/EM

database.
NOTE: You can set this parameter to the GUI server by using its
logical name.

<request_xml_file> Defines the path and name of the XML file that includes the
Control-M/EM request parameters. For more information, see
Introduction to Control-M/EM API.

<response_xml_file> Defines the path and name of the XML file that includes the
Control-M/EM response parameters. For more information, see
Introduction to Control-M/EM API.

314
Control-M Utilities Guide

ctmcalc_date
The ctmcalc_date utility calculates the date that a job can be ordered after adding or deducting a
specified number of days. You can specify whether the calculated date can be any day of the week or
must be a work day. To run the ctmcalc_date utility, see Calculating the date a job can run using the
ctmcalc_date utility (on page 315).

Calculating the date a job can run using the ctmcalc_date utility
This procedure describes how to run the ctmcalc_date utility, which enables you to calculate the date that
a job can be ordered after adding or deducting a specified number of days.
 To calculate the date using the utility:
 Open a command prompt and type the following command:
ctmcalc_date -FOLDER <Folder Path name>
-NAME <job or sub folder name>
-DATE <scheduling date>
-SHIFT <+/-n>
-OUTPUT_FORMAT DATE | EXTENDED (Date and flag) | FLAG
[ -ONLY_WORKING_DAYS <Y/N> ]
[ -DEBUG <debug level 0-5> ]
For more details on the ctmcalc_date parameters, see ctmcalc_date parameters (on page 316) and
ctmcalc_date examples (on page 317).

315
Control-M Utilities Guide

ctmcalc_date parameters
The following table describes the parameters in the ctmcalc_date utility:

Parameter Description

-FOLDER path of the SMART folder or sub-folder

-NAME name of the job or sub-folder

-DATE indicates the scheduling date (odate) to be associated with the job
Specify the date in yyyymmdd format.

-SHIFT indicates how many days to shift the scheduling criteria of the job
Valid values are +n or -n. n is the number of days to be shifted.
Specify +n to shift the job forward n number of days, or specify -n
to shift the job backward n number of days. The scheduling criteria
of the job are shifted either by work days or any day, according to
the value specified for the -ONLY_WORKING_DAYS parameter.

-ONLY_WORKING indicates whether the scheduling day can be any day of the week or
_DAYS must be a work day
Valid values are Y and N.
 Y – the job can be scheduled to run only on a work day
 N – the job can be scheduled to run on any day of the week

OUTPUT_FORMAT displays the following information:

DATE when specified, displays the calculated date

EXTENDED when specified, displays the calculated date and

indicates if the job will be scheduled
Valid values are Y and N.
 Y – scheduled to run on the calculated date
 N – not scheduled to run on the calculated date

316
Control-M Utilities Guide

Parameter Description

FLAG when specified, indicates if the job will be scheduled

Valid values are Y and N.
 Y – scheduled to run on the calculated date
 N – not scheduled to run on the calculated date

-DEBUG activates a debug trace at the specified level

Valid levels are 0–5. The default is 0
NOTE: Performance is somewhat slower when operating in debug
mode. BMC recommends that you activate debug mode only when
requested by Customer Support.

ctmcalc_date examples
The following are ctmcalc_date examples:
Issue the following command to display the calculated scheduling date that the prodyjob job in the
Production folder will be ordered if its scheduling criteria are met, if two days are added to the original
scheduling date of the job, August 02, 2016:
ctmcalc_date -FOLDER Production -NAME prodyjob -date 20160802 \
-shift +2 -ONLY_WORKING_DAYS Y -OUTPUT_FORMAT DATE
20160804
As in the first example, displaying the calculated scheduling date and indicating if the job will be
scheduled:
ctmcalc_date -FOLDER Production -NAME prodyjob -date 20160802 \
-shift +2 -ONLY_WORKING_DAYS Y -OUTPUT_FORMAT EXTENDED
20160804 Y
As in the first example, indicating if the job will be scheduled without displaying the calculated scheduling
date:
ctmcalc_date -FOLDER Production -MAME prodyjob -date 20160802 \
-shift +2 -ONLY_WORKING_DAYS Y -OUTPUT_FORMAT FLAG
Y

317
Control-M Utilities Guide

ctmdeffolder
Use the ctmdeffolder utility to create a job definition for a new SMART Folder. SMART Folders are used for
jobs whose processing can be treated as a single unit. The definition created using this utility contains
values for parameters that affect handling of the entire collection of jobs in the SMART Folder. A SMART
Folder can be empty, or it can contain jobs and also Sub-folders, see ctmdefsubfolder (on page 322). To
run the ctmdeffolder utility, see Creating SMART Folders with definitions using the ctmdeffolder utility (on
page 318).
For more information about parameters of SMART Folders, see Job definition.
NOTE: When a Sub-folder is defined using ctmdeffolder without any Rule-Based Calendar being specified,
the Sub-folder inherits all Rule-Based Calendars.
The following are the ctmdeffolder utility syntax rules:
 When using variables in cmtdeffolder parameters, a variable that does not contain a $ sign can be
enclosed in single (‘ ’) or double (" ") quotation marks.
 A variable that does contain a $ sign must be enclosed in single quotation marks.
 A variable containing a $ sign cannot be resolved if it is enclosed in double quotation marks.
 If you define a new Rule-based calendar with the ! character at the beginning of the Rule-based
calendar name, the Rule-based calendar is excluded. If this feature is disabled, an error message is
displayed that you cannot define a Rule-based calendar with the ! character. For more information,
see DefaultCTMExcludeRBC in General parameters.

Creating SMART Folders with definitions using the ctmdeffolder

utility
This procedure describes how to run the ctmdeffolder utility, which enables you to create a definition for
a new SMART Folder.

 To create SMART Folders using the ctmdeffolder utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Type the following command to invoke the ctmdeffolder utility:
ctmdeffolder
-FOLDER <name>
[ -SUBAPPLICATION <subapplication name> ]
[ -APPLICATION <application name> ]

318
Control-M Utilities Guide

[ -MAXWAIT <days> ]
[ -ADJUST_COND Y|N ]
[ -RUN_AS <username> ]
[ -CREATED BY <username> ]
[ -DEBUG <debug level 0-5> ]
[ -QUIET ]
[ -TIMEZONE <xxx> ]
[ -TIMEFROM <earliest submission time> ]
[ -TIMEUNTIL <latest submission time> | '>' ]
[ -PRIORITY <job priority> ]
[ -CONFIRM Y|N ]
[ -APPLTYPE <agent_application> ]
[ -APPLVER <application version> ]
[ -CMVER <CM version> ]
[ -APPLFORM <application form> ]
[ -DESCRIPTION <string> ]
[ -DOCMEM <filename> ]
[ -DOCLIB <directory name> ]
[ -INCOND <condition> <dateref>|ODAT AND|OR ]
[ -OUTCOND <condition> <dateref>|ODAT ADD|DEL ]
[ -VARIABLE <varname> <expression> ]
[ -SHOUT OK|NOTOK|LATESUB|LATETIME|EXECTIME
<destination> <urgency R|U|V> <message> [<time>] ]
[ -USERDAILY <user daily name>
[ -REMOVEATONCE Y:N ]
[ -DAYSKEEPINNOTOK <days> ]
[ -ON <OK|NOTOK>
[ -DOOK ]
[ -DONOTOK ]
[ -DOSHOUT <destination> <urgency R|U|V> <message> ]
[ -DOCOND <condname> <dateref>|ODAT ADD|DEL ]
[ -DOVARIABLE <varname> <expression> ]
[ -DOFORCEJOB <foldername> <jobname> <odate>|ODAT ]
[ -DOREMOTEFORCEJOB <foldername> <jobname> <odate>|ODAT ]

319
Control-M Utilities Guide

[ -DOMAIL <destination> <cc> <urgency R|U|V> <subject> <message>

]
[ -DOREMEDY <summary> <description> <urgency L|M|H|U|C> ]
-RBC <rbcname>
[ -MAXWAIT <maxwait> ]
[ -DAYS <daystr> ]
[ -WEEKDAYS <weekdaystr> ]
[ -MONTH ALL|JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC
Y|N ]
[ -DATE <MMDD> ]
[ -DATEFROM <YYYYMMDD> ]
[ -DATEUNTIL <YYYYMMDD> ]
[ -DAYSCAL <days calendar> ]
[ -WEEKCAL <week calendar> ]
[ -CONFCAL <conf calendar> ]
[ -CAL_ANDOR AND|OR ]
[ -SHIFT [</>/@][+/-]nn ]
NOTE: You can use the following -input_file parameter to run the utility:
ctmdeffolder -input_file <fullPathFileName>
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmdeffolder parameters , see the following:
 ctmdeffolder parameters (on page 321)
 ctmdeffolder example (on page 321)

320
Control-M Utilities Guide

ctmdeffolder parameters
The following table lists the ctmdeffolder utility parameters:

Parameter Description

-DEBUG Level of debug messages, 0 to 5. The default value is 0 (no debug

messages.

-QUIET If specified, no information messages are displayed during execution of

the command.

-input_file Name and full path of a file containing parameters for the utility. In
this file, each parameter and its values (if any) are on a separate line
with the same syntax they would have on the command line. Using the
-input_file parameter enables you to:
prepare and save files of utility parameters that can be reused.
specify utility input longer than the number of characters allowed in
the command line.
EXAMPLE:-input_file
~<controlmOwner>/ctm_server/data/ctmdeffo
lder_parms.txt

-USER DAILY Name of a order method job that is associated with the created SMART
Folder. This parameter is case-sensitive.
NOTE: The specified name must not be longer than 10 characters. If a
longer name is specified, an error message is issued.
EXAMPLE: ctmdeffolder -folder ss -application a -group
g -rbc r -order_ method verylongnamespecified
The response is:
RULE-BASED CALENDAR 'r' added
The value length for -ORDER_ METHOD exceeds maximum
allowed length 10

ctmdeffolder example
The following is an ctmdeffolder command example:
Use the following command to create a SMART Folder named job:
ctmdeffolder -FOLDER job -SUBAPPLICATION supply -APPLICATION supplies -RBC jobRbc -DAYS
ALL -MONTH ALL Y
Control-M/Server issues a message, similar to the following:
RULE-BASED CALENDAR 'jobRbc' added
new SMART Folder ENTITY defined, SMART Folder='job', ACTIVEFOLDERNO = 00000j(19)

321
Control-M Utilities Guide

ctmdefsubfolder
The ctmdefsubfolder utility creates a definition for a new Sub-folder. Sub-folders are used for jobs whose
processing can be treated as a single unit. A Sub-folder can only be defined within a SMART folder, see
ctmdeffolder (on page 318). A Sub-folder can be empty, or it can contain jobs and also other Sub-folders.
To run the ctmdefsubfolder utility, see Creating a Sub-Folder using the ctmdefsubfolder utility (on page
322).
For more information about parameters of Sub-folders, see Sub Folder parameters.
When using variables in ctmdefsubfolder parameters, a variable that does not contain a $ sign can be
enclosed in single (‘ ’) or double (" ") quotation marks. A variable that does contain a $ sign must be
enclosed in single quotation marks. A variable containing a $ sign cannot be resolved if it is enclosed in
double quotation marks.
The RBC option associates Rule-Based Calendars to be used by the Sub-folder and it may appear more
than once. Specified Rule-Based Calendars must be defined by the direct parent folder. The '*' means that
the Sub-folder inherits all the Rule-Based Calendars from the direct parent folder. When a Sub-folder is
defined without a Rule-based calendar, the Sub-folder inherits the Rule-based calendars of the direct
parent. To define a Sub-folder without any Rule-based calendar associations, use the NONE option. If a
Rule-based calendar is defined with the ! character at the beginning of the Rule-based calendar name, the
Rule-based calendar is excluded. If this feature is disabled, an error message is displayed that you cannot
define a Rule-based calendar with the ! character. For more information, see DefaultCTMExcludeRBC
in General parameters.
The Created by field will be set automatically with the default logged in account name if it's not specified.

Creating a Sub-Folder using the ctmdefsubfolder utility

This procedure describes how to run the ctmdefsubfolder utility, which enables you to create a definition
for a new Sub-folder.

 To create a Sub Folder using the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Type the following command:
ctmdefsubapplication
-FOLDER <name>
-SUBAPPLICATION <sub_application name>
-APPLICATION <applic name>
[ -ADJUST_COND Y|N ]
[ -RUN_AS <username> ]
[ -CREATED BY <username> ]

322
Control-M Utilities Guide

[ -DEBUG <debug level 0-5> ]

[ -QUIET ]
[ -TIMEZONE <xxx> ]
[ -TIMEFROM <earliest submission time> ]
[ -TIMEUNTIL <latest submission time> | '>' ]
[ -PRIORITY <job priority> ]
[ -CONFIRM Y|N ]
[ -APPLTYPE <agent_application> ]
[ -APPLVER <application version> ]
[ -CMVER <CM version> ]
[ -APPLFORM <application form> ]
[ -DESCRIPTION <string> ]
[ -DOCMEM <filename> ]
[ -DOCLIB <directory name> ]
[ -INCOND <condition> <dateref>|ODAT AND|OR ]
[ -OUTCOND <condition> <dateref>|ODAT ADD|DEL ]
[ -VARIABLE <variable name as %%local, %%\global, %%\\smart or
%%\\pool\variable> <expression> ]
[ -SHOUT OK|NOTOK|LATESUB|LATETIME|EXECTIME
<destination> <urgency R|U|V> <message> [<time>] ]
[ -ON <OK|NOTOK>
[ -DOOK ]
[ -DONOTOK ]
[ -DOSHOUT <destination> <urgency R|U|V> <message> ]
[ -DOCOND <condname> <dateref>|ODAT ADD|DEL ]
[ -DOVARIABLE <variable name as %%local, %%\global, %%\\smart or
%%\\pool\variable> <expression> ]
[ -DOFORCEJOB <foldername> <jobname> <odate>|ODAT ]
[ -DOMAIL <destination> <cc> <urgency R|U|V> <subject> <message>
]
[ -DOREMEDY <summary> <description> <urgency L|M|H|U|C> ]
[ -RBC <rule_based_calendar_name|NONE|"*"> ]
NOTE: You can also Use the following -input_file parameter to run the utility:
ctmdefsubfolder -input_file <fullPathFileName>

323
Control-M Utilities Guide

For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmdefsubfolder parameters, see ctmdefsubfolder parameters (on page 324) and ctmdefsubfolder
syntax rules.

ctmdefsubfolder parameters
The following table lists the ctmdefsubfolder utility parameters:

Parameter Description

-DEBUG Level of debug messages, 0 to 5. The default value is 0 (no debug

messages).

-QUIET If specified, no information messages are displayed during execution of

the command.

-input_file Name and full path of a file containing parameters for the utility. In
this file, each parameter and its values (if any) are on a separate line
with the same syntax they would have on the command line. Using the
-input_file parameter enables you to:
prepare and save files of utility parameters that can be reused.
specify utility input longer than the number of characters allowed in
the command line.
-input_file
~<controlmOwner>/ctm_server/data/ctmdefsu
btab_parms.txt

ctmrpln
The ctmrpln utility creates a report that lists selected jobs in selected folders, and indicates when the jobs
are scheduled to run. It enables you to test the effect of different calendars on job scheduling. To run the
ctmrpln utility, see Creating a job report using the ctmrpln utility (on page 324).
Each report can be created in one of the formats described in ctmrpln report formats (on page 325).
The characters described in ctmrpln report characters (on page 325) can appear in this report. The
characters indicate whether a job is scheduled to run (that is, whether the job is placed in the Active Jobs
database.)

Creating a job report using the ctmrpln utility

This procedure describes how to run the ctmrpln utility, which enables you to create a report that lists
selected jobs in selected folders, and indicate when the jobs are scheduled to run.

324
Control-M Utilities Guide

 To create a job report run the utility:

 Open a command prompt and type one of the following commands:
• ctmrpln (and answer the prompts)
• ctmrpln <Report type> <calendar> <Folder> <jobName> <date> [<output>]
For more details on the ctmrpln parameters, see ctmrpln parameters (on page 326) and ctmrpln examples
(on page 327).

ctmrpln report formats

The following table lists the ctmrpln report formats:

Format Description

Daily Report Displays jobs in the specified folder that are scheduled to run on a
specific day. Each job’s Mem Name (or Job Name), Group, and
Description parameters are displayed.

Monthly Report Displays a folder of all days in a specified month and marks (with an
asterisk "*") the days of the month on which jobs in the specified
folder are scheduled to run. Jobs can be identified either by their
Mem Name or Job Name parameters.

Yearly Report Displays the year, the two years before, and the two years after the
year specified in the <Date> parameter. Marks each day with
various characters (described in the next folder) that indicate if jobs
in the specified folders are scheduled to run.

ctmrpln report characters

The following table lists the report characters that can be used with

Char Description

* The job is scheduled to run on this day.

. The job is not scheduled to run on this day.

- The job is scheduled to not run on this day. For example, if DAYS=-3, the job is
scheduled to not run on the 3rd day of the month.

325
Control-M Utilities Guide

ctmrpln parameters
The following table lists the ctmrpln utility parameters:

Parameter Description

<ReportType> Specify one of the following values:

DM (or D) Creates a daily report, identifying each job according

to its File Name parameter.

DJ Creates a daily report, identifying each job according

to its Job Name parameter.

MM (or M) Creates a monthly report, identifying each job

according to its File Name parameter.

MJ Creates a monthly report, identifying each job by its

Job Name parameter.

Y Creates a yearly report.

<calendar> Specify one of the following values:

Y Creates the report using the calendar specified in the

job’s scheduling parameters.

N Creates the report ignoring the calendar specified in

the job’s scheduling parameters.

<Name> Creates the report using a calendar you specify

(ignoring calendars specified in the job scheduling
parameters). Use this option to see how another
calendar affects scheduling.

<Folder> Name of the folder on which to base the report. The folder name
can include the following wildcard characters:

* represents any number of characters (including no characters).

Specify * by itself to include all folders. Any parameter including *
should be enclosed in quotation marks.

? represents any single character.

326
Control-M Utilities Guide

Parameter Description

<Job Name> Job Name of the jobs to include in the report. The Job Name can
include wildcard characters (see <Folder> above). Specify * by
itself to include all jobs in the folder.

<date> Date for the report:

For daily reports: A date in yyyymmdd format.
For monthly reports: A month in yyyymm format.
For yearly reports: A year in yyyy or yy format.
NOTE: The ctmrpln utility supports years from 1972 to 2035,
inclusive.

<output> Full path name to which the report should be sent (optional). If this
parameter is not specified, the output is routed to the default output
device.
NOTE: To print the Monthly Report, specify a device that can print
132-column reports.

ctmrpln examples
The following are examples of the ctmrpln utility:
The following command causes the utility to generate a report for folder PROD1. The report will include
all jobs whose Job Name parameter begins with "jn" and that will run on January 1, 2017 based on the
calendar work_days. The job is identified by its File Name. (To identify jobs by Job Name, specify
Report_type DJ.) The output is directed to the user’s display.
ctmrpln D work_days PROD1 "jn*" 20170101
The following command causes the utility to generate a folder of days on which job PRDJ02 in folder
PROD1 will run during the month of April, 2016, based on the calendar work_days. The job is identified by
File Name. (To identify jobs by Job Name, specify Report_type MJ.) The output is directed to printer lp1.
ctmrpln M work_days PROD1 PRDJ02 201604 lp1
The following command causes the utility to generate a five-year report encompassing the period January
2003 through December 2008. This indicates on which days each job in folder PROD1 runs, based on the
calendar work_days. The output is directed to printer lp1.
ctmrpln Y work_days PROD1 "*" 2005 lp1

327
5
5
New day procedure and user dailies
The new day procedure and order methods utilities:
 Obtain information regarding the user daily procedure, such as the last time it ran or the jobs that it
ordered and their security authorizations
 Actually run a specific user daily to order jobs whose folders are associated with it (ctmudly)
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.
Some of the parameter names changed for Control-M version 8.0.00 and above, terminology from
previous versions is still supported. For a complete list of the parameter names, see Abbreviations and
conventions.

Utility Description

ctmordck (on Lists job processing definitions that can be ordered by a specific User Daily
page 328) job.

ctmudchk (on Allows recovery from interruption of a User Daily.

page 331)

ctmudlst (on Enables you to manually set the User Daily last run date.
page 333)

ctmudly (on Orders jobs for a specific User Daily name.

page 335)

ctmsys (on Enables you to define appropriate values for system parameters including
page 448) customizing the New day procedure.

ctmordck
The ctmordck utility lists job processing definitions associated with a specific User Daily name and
indicates the security status of each job with regard to the User Daily name job (that is, whether or not
the Control-M security mechanism will allow jobs associated with a User Daily name to run with the
authorizations currently assigned to it).
To run the ctmordck utility, see Viewing jobs with User Daily name using the ctmordck utility (on page
329).
This utility displays the following fields:

328
Control-M Utilities Guide

 Name of the job.

 Number of the job in the Control-M/Server database.
 Who Defined the job (Created by).
 The user name with the authorization to execute the job (Run As).
The following information is displayed for each job processing definition:
 FD: Whether or not the user is authorized to order from the folder.
 FN: Whether or not the user is authorized to execute the Filename.
 UA: Whether or not the user is authorized to order jobs for the Run_As user.
This utility can be used non-interactively for non-terminal destinations, see the description of the
<Output> parameter in ctmordck parameters (on page 330).

Viewing jobs with User Daily name using the ctmordck utility
This procedure describes how to run the ctmordck utility, which enables you to list job processing
definitions associated with the User Daily name and indicates the security status of each job.

 To view jobs with User Daily Name using the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type one of the following commands:
• ctmordck <User Name> <Daily name> [<Output>]
• ctmordck
When the command ctmordck is invoked, prompts are displayed on screen to assist you to specify
the parameters of this utility.
For more information on the ctmordck parameters, see ctmordck parameters (on page 330).

329
Control-M Utilities Guide

ctmordck parameters
The following table lists the ctmordck utility parameters:

Parameter Description

<User Name> Owner of the Order method job.

<Daily name> Defines the name of the User Daily procedure. For more information,
see User Daily name.

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

ctmordck examples
The following are examples of ctmordck utility command and output:
The following command generates a list for user SYSTEM and the User Daily name SYSTEM. The list is
directed to the specified file called udlist.
ctmordck SYSTEM <user name> SYSTEM <Daily
name>/ctm_server/user1/udlist
The following is sample output from the above command:
Date: 18-Feb-2017. Page: 1
User SYSTEM , Daily SYSTEM Ordering list
--------------------------------------------------------------------------------------
JOBNAME No. CREATED_BY RUN_AS FD FN UA
------------------------------------------------
CTMLOG HAN 2066 root root Y N Y
PURGE JOB 2067 root root Y N Y
user3-DAIL 2033 BARRY user3 Y N Y
user2-DAIL 2032 STEVE user2 Y N Y
user1-DAIL 2031 STEVE user1 Y N Y
JEAN-UD 2000 jean jean Y N Y
JOB-STATUS 2068 root root Y N Y
GD-TEST1 20 jean user1 Y N Y
GD-TEST2 21 jean user2 Y N Y
GD-TEST3 22 jean user3 Y N Y
GD-user4 2008 jean user4 Y N Y
GD-user5 2009 jean user5 Y N Y

330
Control-M Utilities Guide

ctmudchk
The ctmudchk utility checks if all jobs that should have been ordered by a User Daily name job are in the
Active Jobs database. This utility facilitates recovery from the interruption of a User Daily job. If a User
Daily job is interrupted for any reason (for example, operating system crashes, User Daily job errors), the
ctmudchk utility can determine which jobs in the affected user daily ended okay, which jobs had
interruptions, and which jobs had not yet run. You can examine the outputs and logs related to the jobs
that were in process to decide what to do, but the utility can reorder the jobs that did not yet run.
Before ordering the job, ctmudchk verifies that a job is not already present in the Active Jobs database.
When using the ctmudchk utility, the New Day procedure must not be running.
To handle an interruption in User Daily processing, run the ctmudchk utility for the affected User Daily to
order jobs that were not ordered because of the interruption. To run the ctmudchk utility, see Checking
and ordering jobs using the ctmudchk utility (on page 331).

Checking and ordering jobs using the ctmudchk utility

This procedure describes how to run the ctmudchk utility, which enables you to check and/or order jobs
that should have been ordered by the User Daily name are in the Active Jobs database.

 To check jobs using the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctmudchk
-DAILY <user daily name>
-ACTION <LIST|ORDER>
[ -ODATE <scheduling date> ]
[ -ODATE_OPTION <VALUE_DATE|RUN_DATE> ]
[ -FILE <file name> ]
3. Check return codes.
The utility returns code 1 status (NOTOK) if it attempts to order a job, but fails to do so. Otherwise,
the utility returns code 0 status (OK).
For more information on ctmudchk parameters, see ctmudchk parameters (on page 332).

331
Control-M Utilities Guide

ctmudchk parameters
The following table lists the ctmudchk utility parameters:

Parameter Description

-DAILY Name of the User Daily to be checked. For more information, see User
Daily name.

-ACTION Indicates whether jobs that are missing from the Active Jobs database
should be listed or ordered.
The following values can be specified for this parameter:

LIST Lists the job name and the name of the folder for
each missing job.

ORDER Orders the missing jobs.

-odate Indicates the scheduling date (odate) to be associated with jobs that
are ordered by this user daily job.
Valid values are:

ODAT The current working date of the computer on which

Control-M/Server is running.
This is the default value.

yyyymmdd A specific working day in yyyymmdd format.

NOTE: The interpretation of this parameter value is dependent on the

value specified for the -odate_option parameter (described below).

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

Valid values are:

value_date The specified odate is the odate value for the jobs.
However, the jobs ordered by the user daily job
should be run during the current working day.
This is the default value for the -odate_option
parameter.
If time zones specified in specific job processing
definitions in the folders, then the jobs are run
according to those time zones.

332
Control-M Utilities Guide

Parameter Description

run_date The jobs ordered by the user daily job should be run
only when the specified odate begins.
If the specified odate is the current working day,
then this will work in the same way as value_date
(described above).
If the specified odate has not begun (for example,
due to time zone specifications), then the job will
wait in the Active Jobs database (with WAIT_ODAT
status) until the start of the specified working day.
If the specified odate has already passed, the
ctmudchk utility will not run, and an error message
will be displayed.

-FILE Indicates the path name for the output of the ctmudchk utility. This
parameter is required only if LIST is specified for the ACTION
parameter.

ctmudchk examples
The following are examples of ctmudchk utility commands:
Use the following command to check Active Jobs database for jobs that are ordered by the User Daily
name, payroll. The Job Name and Folder are listed for each job that is not in the Active Jobs database.
ctmudchk -DAILY payroll -ACTION LIST
Use the following command to check the Active Jobs database for jobs that are ordered by the User Daily
name, admin1. The utility orders each job that is not in the Active Jobs database.
ctmudchk -DAILY admin1 -ACTION ORDER

ctmudlst
The ctmudlst utility is used to display or modify UDLAST (the User Daily last run date). To run the
ctmudlst utility, see Modifying the User daily's last run date using the ctmudlst utility (on page 333).
When using the ctmudlst utility, the New Day procedure must not be running.

Modifying the User daily's last run date using the ctmudlst utility
This procedure describes how to run the ctmudlst utility, which enables you to display or modify UDLAST
(the User Daily's last run date).

333
Control-M Utilities Guide

 To modify the user daily's last run date using the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type one of the following commands:
• ctmudlst LIST <daily name>
• ctmudlst LIST "*"
• ctmudlst UPDATE <daily name> <date>
• ctmudlst DELETE <daily name>
For more information on the ctmudlst utility parameters, see ctmudlst parameters (on page 334).

ctmudlst parameters
The following table lists the ctmudlst utility parameters:

Parameter Description

LIST Lists the name of the User Daily's last run date.

UPDATE Updates the name of the User Daily's last run date.

DELETE Deletes the name of the User Daily's last run date.

<Daily name> Defines the user daily name. For more information, see User Daily
name.

"*" Asterisk enclosed in quotation marks. Displays a list of all User Daily
names and corresponding last run dates.

<Date> Requested value for the last running date in yyyymmdd format.

ctmudlst examples
The following are examples of the ctmudlst utility commands:
The following command lists the last run date for User Daily name, payroll:
ctmudlst LIST payroll
The following command changes the last run date for User Daily name, inventory, to August 10, 2008:
ctmudlst UPDATE inventory 20080810

334
Control-M Utilities Guide

ctmudly
The ctmudly utility orders jobs whose folders are associated with a specific User Daily name. To run the
ctmudly utility, see Ordering jobs with a specific user daily name using the ctmudly utility (on page 335).
Each job in the ordered Folders whose Scheduling criteria are satisfied is placed in the Active Jobs
database.
The exit code of the ctmudly utility is determined by Control-M configuration parameter
UDLY_PARTCOPY_ERR. For more information about this parameter, see Configuration parameters.

Ordering jobs with a specific user daily name using the ctmudly
utility
This procedure describes how to run the ctmudly utility, which enables you to order jobs whose folders
are associated with a specific User Daily name.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Type the following command:
ctmudly -DAILY_NAME <User_Daily>
[-odate {ODAT|<yyyymmdd>}]
[-odate_option {value_date|run_date}]
3. Check for messages issued when a job is not ordered.
For more information about these messages, see ctmudly messages (on page 337).
For more information on ctmudly parameters, see ctmudly parameters (on page 336).

335
Control-M Utilities Guide

ctmudly parameters
The following table lists the ctmudly utility parameters:

Parameter Description

<user Daily> Name of a user daily job that is associated with one or more folders.
This parameter is case-sensitive.
NOTE:
 The specified name must be no longer than 10 characters. If a
longer name is specified, it will be truncated to 10 characters.
 If the ctmudly utility command is issued from a Control-M/Agent, it
must include the -DAILY_NAME keyword (as shown above).
 For more information, see User Daily name.

-odate Indicates the scheduling date (odate) to be associated with jobs that
are ordered by this order method job.
Valid values are:

ODAT The current working date of the computer on which

Control-M/Server is running.
This is the default value.

yyyymmdd A specific working day in yyyymmdd format.

The interpretation of this parameter value is dependent on the value

specified for the -odate_option parameter (described below).

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

Valid values are:

value_date The specified odate should be used as the odate

value for the job. However, the jobs ordered by the
user daily name job should be run during the current
working day.
This is the default value for the -odate_option
parameter.
If time zones specified in specific job processing
definitions in the folders, then the jobs are run
according to those time zones.

336
Control-M Utilities Guide

Parameter Description

run_date The jobs ordered by the User daily name job should
be run only when the specified odate begins.
If the specified odate is the current working day,
then this will work in the same way as value_date
(described above).
If the specified odate has not begun (for example,
due to time zone specifications), then the job will
wait in the Active Jobs database (with WAIT_ODAT
status) until the start of the specified working day.

ctmudly messages
The following table describes the ctmudly utility issued messages:

Message Description

Security Issues When a job is not scheduled due to security protection, the
following Alert is sent to Control-M/EM:
DAILY <userdaily name> FAILED TO ORDER JOBNAME
<jobName> - Security

Scheduling issues If one or more jobs in a folder is not ordered by a User Daily job
due to scheduling criteria, the type of Alert sent to Control-M/EM
is determined by the value of the Control-M configuration
parameter NOT_ORDERED_JOB_ALERT. For more information
about this parameter, see Configuration parameters.

PARTIAL COPY message If one or more jobs in a folder was not ordered by the User Daily
job due to scheduling criteria or security settings, the Order
method (ctmudly) ended with the following error message in the
job output (OUTPUT).

ctmudly examples
The following are examples of the ctmudly utility commands:
Ordering a specific User Daily
The following command orders all Folders that are associated with the User Daily name, prod:
ctmudly prod

337
Control-M Utilities Guide

Ordering a User Daily for a specific time zone

The following command orders all Folders that are associated with the User daily name, Japan, with an
order date of March 31, 2016. These jobs will not be run until that working day begins.
ctmudly -DAILY_NAME Japan -odate 20160331 -odate_option run_date
ctmudlst LIST "*"
ctmudlst UPDATE <user_daily> <date>
Ordering a User Daily that has a future date specified by using ctmudlst
To specify an ordering date for User Daily name, UD_ex1, at a future date, run the following command:
ctmudlst update UD_ex1 20170919
The following message is displayed:
success in updating the user daily name 'UD_ex1'
To order UD_ex1, issue the following command:
ctmudly UD_ex1
The following message is displayed:
User Daily: dates mixedup (LASTRUN, new odate)

338
6
6
Active Jobs Database utilities
The following utilities, when run, affect the active jobs database. These utilities have an immediate impact
on the jobs as they run.
 Prerequisite conditions: Performs operations on the Prerequisite Conditions folder. The existence
or deletion of these conditions can determine if jobs run. For more information, see ctmcontb (on
page 339).
 Parameter values: Refreshes recently updated parameters, as an alternative to restarting
Control-M/Server. For more information, see ctmipc (on page 344).
 Quantitative Resources: Updates the resource usage of a Control-M/Agent. For more information,
see ctmloadset (on page 346).
 Variable values: Displays the current value of a variable. For more information see ctmstvar (on
page 349).
 Global variables: Manipulates Global variables for data centers, SMART Folders (excluding
Sub-folders), or jobs in SMART Folders. For more information, see ctmvar (on page 350)
 Control Resources: Displays a list of Control resources and the status of each resource, after which
the user might decide to modify the status of a resource. For more information, see ecactltb (on page
356).
Some of the parameter names changed for Control-M version 8.0.00 and above, terminology from
previous versions is still supported. For a complete list of the parameter names, see Abbreviations and
conventions.

ctmcontb
The ctmcontb utility performs the following operations on prerequisite conditions in the Control-M/Server
database:
 Lists existing prerequisite conditions while treating an asterisk in a condition name as a wildcard.
(-LIST)
 Lists existing prerequisite conditions while treating an asterisk in a condition name as a regular
character. (-LISTNOWILD)
 Adds a prerequisite condition. (-ADD)
 Generates a prerequisite condition in XML format. (-XML)
 Deletes a prerequisite condition while treating an asterisk in a condition name as a wildcard.
(-DELETE)
 Deletes a prerequisite condition while treating an asterisk in a condition name as a regular character.
(-DELETENOWILD)
 Deletes conditions within a specified range of dates. (-DELETEFROM)

339
Control-M Utilities Guide

 Cleans and excludes a condition (-CLEAN) (-EXCLUDE)

The following special characters are disabled when they occur in prerequisite condition names:
• ( open parenthesis
• ) close parenthesis
• | vertical bar
• space
To run the utility, see Viewing and modifying Prerequisite Conditions using the ctmcontb utility (on page
340).

Viewing and modifying Prerequisite Conditions using the ctmcontb

utility
This procedure describes how to run the ctmcontb utility, which enables you to perform operations on
prerequisite conditions in the Control-M/Server database.
 To view and/or modify Prerequisite Conditions using the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Do one or more of the following:
• Run one of the following commands to list conditions:
o ctmcontb -LIST <Condition Name> <Condition Date> [-OUTPUT <Output file
name>][-FULLDETAILS]
o ctmcontb -LISTNOWILD <Condition Name> <Condition Date> [-OUTPUT
<output file name>][-FULLDETAILS]
o ctmcontb -input_file <Full path file name>
• Run one of the following commands to delete a range of conditions:
o ctmcontb -DELETEFROM <Condition Name> <From Date> <To Date>
o ctmcontb -input_file <Full Path file name>
• Run the following command to clean and exclude a condition:
o ctmcontb -CLEAN <Condition Name> -EXCLUDE <Condition Name> <From Date>
<To Date>
• Run one of the following commands for all other operations:
o ctmcontb {-ADD|-XML|-DELETE|-DELETEONWILD} <Condition Name>
<Condition Date>
o ctmcontb -input_file <Full Path file name>

340
Control-M Utilities Guide

For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmcontb parameters, see ctmcontb utility parameters (on page 341).

ctmcontb utility parameters

The following table lists the ctmcontb utility parameters:

Variable Description

-FULLDETAILS Displays the prerequisite condition name without truncation.

<Condition Name> For LIST, DELETE and DELETEFROM

The condition name can include wildcard character * to indicate
any number of characters (including none).
When using an *, the condition name must be enclosed in
quotation marks (for example, "LVL*").
Specify "*" by itself to include all existing conditions.
When using both open and closed square brackets ([ and ]), the
condition name must be enclosed in quotation marks (for
example, "RATE[A1]").
Maximum length for a condition name is 255 characters.

For LISTNOWILD and DELETENOWILD

The character * in condition name is referred to as a regular
character.
When using an *, the condition name must be enclosed in
quotation marks (for example, "LVL*").
When using both open and closed square brackets ([ and ]), the
condition name must be enclosed in quotation marks (for
example, "RATE[A1]").
Maximum length for a condition name is 255 characters.
For Adding or Generating in XML Format
When using both open and closed square brackets ([ and ]), the
condition name must be enclosed in quotation marks (for
example, "RATE[A1]").
Maximum length for a condition name is 255 characters

341
Control-M Utilities Guide

Variable Description

For CLEAN and EXCLUDE:

 CLEAN: Condition to be cleaned regardless of its date. Can
contain wildcard characters.
 EXCLUDE: Condition which is excluded from cleanup. Can
contain wildcard characters.
NOTE: You can have multiple exclude parameters within the
same command.

<Condition Date> Displays the date of the prerequisite condition in mmdd format.
For Listing and Deleting:
The condition date can include wildcard character * to indicate
any number of characters (including none). When using an *,
enclose the date in quotation marks (for example, "12* ").
 Specify "*" by itself to include all dates.
 Specify ODAT to accept the Control-M date.
 Specify STAT if a date is not relevant.
For Adding or Generating in XML Format:
 Specify ODAT to use the Control-M working date.
 Specify STAT if a date is not relevant.

<From Date> <To For Deleting in a Date Range:

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

<output file name> For Listing:

Displays the full path name to which the report should be sent
(optional). If this parameter is not specified, the output is routed
to the default output device (the terminal).

342
Control-M Utilities Guide

Variable Description

<Full Path file name> Displays the name and full path of a file containing parameters for
the utility. In this file, each parameter and its values (if any) are
on a separate line with the same syntax they would have on the
command line. Using the -input_file parameter enables you to:
 Prepare, save, and reuse files of utility parameters.
 Specify utility input longer than the number of characters
allowed in the command line.
-input_file /ctm_server/data/ctmcontb_list.txt

ctmcontb examples
The following command deletes prerequisite condition bckp_end with condition dates in December:
ctmcontb -DELETE bckp_end "12*"
The following command deletes all prerequisite conditions with prefix a and condition dates between
December 1 and December 15 inclusive:
ctmcontb -DELETEFROM "a*" 1201 1215
The following command deletes the prerequisite condition aa* with condition date ODAT:
ctmcontb -DELETENOWILD "aa*" ODAT
You can implement the second example with the -input_file parameter as follows:
ctmcontb -input_file ~<controlm_owner>/ctm_server/data/ctmcontb_delfr.txt
Where the referenced file contains the line:
-DELETEFROM "a*" 1201 1215
The following command lists the prerequisite condition named aa* with all its dates:
Ctmcontb -LISTNOWILD "aa*" "*"
The following command lists all existing prerequisite conditions:
ctmcontb -LIST "*" "*"
A report similar to the following example is generated:
Date: 30-JUN-2016. Page 1
Conditions list
CONDNAME CONDDATE
APR01-L20 0629
APR01-L20 0630
ARD01-L30K 0630
LVL11-LVL22 0628

343
Control-M Utilities Guide

LVL11-LVL22 0629
LVL11-LVL22 0630
PKR11-LVL01 0630
This example demonstrates the advantage of defining a Control-M job to run a utility. The following job
processing definition causes Control-M to run ctmcontb each work day, each time deleting all prerequisite
conditions that are between five and ten days old:
Week Days 2,3,4,5,6
Variable Assignment
%%A=%%CALCDATE %%DATE -10
%%B=%%CALCDATE %%DATE -5
%%A=%%SUBSTR %%A 3 4
%%B=%%SUBSTR %%B 3 4
Command Line ctmcontb -DELETEFROM "*" %%A %%B
This example illustrates ctmcontb input and output when using the -XML option. ODAT automatically
generates the Control-M/Server system date that, in this example, was March 15th.
D:\>ctmcontb -XML cond1 ODAT
<?xml version="1.0" encoding="utf-8" ?>
<CTMCONTB
CONDNAME="cond1"
CONDDATE="0315">
<COND
CONDNAME="cond1"
CONDDATE=" 0315">
</COND>
</CTMCONTB>
This example cleans all conditions and excludes conditions that start with "A" between May and June,
and excludes conditions that start with A between August 10th and August 20th:
ctmcontb -clean "*" -exclude A* 0501 0630 -exclude B* 0810 0820

ctmipc
The ctmipc utility sends a message to Control-M/Server processes, which instructs the processes to
perform a specific action. To run the ctmipc utility, see Refreshing parameters using the ctmipc utility (on
page 345).
The ctmipc utility can only be used to refresh recently updated parameters, as an alternative to restarting
Control-M/Server.

344
Control-M Utilities Guide

Refreshing parameters using the ctmipc utility

This procedure describes how to run the ctmipc utility, which enables you to send a message to
Control-M/Server processes, which instructs the processes to perform a specific action. The ctmipc utility
can only be used to refresh recently updated parameters as an alternative to restarting Control-M/Server.
EXAMPLE: Specify the following command to send the message "CFG" to all Control-M/Server processes:
ctmipc -dest ALL -msgid CFG
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctmipc
-DEST <CE|CS|SU|TR|WD|RT|ALL>
-MSGID <CFG>
{ -DATA <message data>]
[ -QUIET ]
[ -DEBUG <debug level> ]
For more details on the ctmipc parameters, see ctmipc parameters (on page 345).

ctmipc parameters
The following table lists the parameters for the ctmipc utility:

Parameter Description

-DEST Indicates the destination of the message to be sent (either one

specific process, or specify .DEST ALL for all processes).

-MSGID Indicates the message to be sent.

-DATA Indicates additional data to be sent with the message ID (if any).

-QUIET Indicates that the ctmipc utility will not generate any output
message, upon success or a failure.

-DEBUG Indicates that the utility will run in debug mode, and will therefore
generate a debug log in the proclog sub-directory of
Control-M/Server.

345
Control-M Utilities Guide

ctmloadset
The ctmloadset utility records current resource usage on an agent computer in the Quantitative Resources
table. This utility is typically invoked by a cyclic job that runs on the agent computer and measures usage
of a certain resource on the computer. Usage data is then used to update the Quantitative Resources
table on the Control-M/Server computer. To run the ctmloadset utility, see Updating a Quantitative
Resource using the ctmloadset utility (on page 346).
ctmloadset is used when load balancing is implemented. The load-balancing algorithm uses the data
recorded in the Quantitative Resources table to determine to which agent computer a job should be
submitted.
Control-M maintains the following information about usage of each Quantitative resource:
 Total Used: Units of the resource currently in use. This parameter represents the sum of the values
specified in the other two rows of this table.
 Used by Control-M: Units of the resource currently in use by jobs submitted by Control-M/EM
database.
 Used by Others: Units of the resource currently in use by non-Control-M jobs.
Update resource usage values in the Quantitative Resources table in either of two ways:
 Specify the value for Total Used for a resource. ctmloadset subtracts the value for Used by Control-M
from the value you specify and places the remainder in the field Used by Others.
 Specify the value for Used by Others for a resource. This value is added to the value Used by
Control-M to calculate the value Total Used for the resource.
Values for the utility can be expressed as an absolute number of units or as a percentage of the total
number of units defined (Max value).
The utility’s output is displayed as type Q rows in the Quantitative Resources window. However, the Mem
Name field remains blank since this represents usage by one or more non-Control-M jobs.

Updating a Quantitative Resource using the ctmloadset utility

This procedure describes how to run the ctmloadset utility, which enables you to record current resource
usage on an agent computer in the Quantitative Resources table.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Type the following command to invoke the ctmloadset utility:
ctmloadset {TOTAL|OTHERS} <Resource name> <loadValue>[%]
For more details on the ctmloadset parameters, see ctmloadset parameters (on page 347).

346
Control-M Utilities Guide

ctmloadset parameters
The following utility lists the ctmloadset parameters:

Parameter Description

TOTAL Indicates that the load value provided specifies the total usage of the
resource by all jobs (both Control-M jobs and non-Control-M jobs).
When this option is specified, the utility calculates the usage of the
resource by non-Control-M jobs and updates the table accordingly.

OTHERS Indicates that the load value provided specifies the units of the resource
used by one or more non-Control-M jobs.

<Resource Name of the Quantitative resource to update.

Name>

<loadValue> Number of units of the resource currently used.

-or-
When % is specified, the amount of the resource currently used,
expressed as a percentage of the maximum available units defined for
this Quantitative resource.

ctmloadset example
A host group contains three agent computers: diana, jacklin and ruby. Each computer is defined in the
Quantitative Resource table as having 200 units of resource CPU_load, representing the load on the
computer’s CPU.
 computer jacklin is used exclusively to run jobs submitted by Control-M. The computer is currently
executing a job that uses 120 units of resource CPU_load.
 computer ruby is used exclusively to run jobs submitted by Control-M. The computer is currently
executing a job that uses 150 units of resource CPU_load.
 computer diana is used both for Control-M and non-Control-M jobs. The computer is currently
executing a job submitted by Control-M that uses 75 units of resource CPU_load.
A cyclic job is defined to run periodically on diana to measure the total load on the CPU. The job updates
the Quantitative Resources table using the ctmloadset utility to indicate to Control-M exactly what the
load is on that computer. The last run of this job determined that the load on the CPU is 80% of total
capacity. The job invokes ctmloadset as follows:
ctmloadset TOTAL CPU@diana 80%
The Total Used for diana is set to 80% of 200, or 160. Since the usage by Control-M jobs is currently 75
units, ctmloadset calculates that the "Other" (non-Control-M usage) is 160 - 75, or 85.

347
Control-M Utilities Guide

As a result, the Quantitative Resources table now contains the following values:

Total used by
Resource Max Control-M Total used by others Free

CPU@jacklin 200 120 80

CPU@ruby 200 150 50

CPU@diana 200 75 85 40

The Control-M load-balancing algorithm uses these values when determining where to submit the next
job.

ctmloadset example represented by the ecaqrtab utility

The following examples demonstrate the effect of ctmloadset on the Quantitative Resources table, as
represented by the display generated by the ecaqrtab utility. All examples below are based on the
following premise:
For agent computer diana, 30 units of resource CPU@diana are currently used by Control-M jobs.
The output from the ecaqrtab utility is as follows:

Resource Name Type Max-Avail Reserved Used Free

CPU@diana L 50 0 30 20

The following command specifies that the current usage of the Quantitative resource CPU@diana by
non-Control-M jobs is 12 units:
ctmloadset OTHERS CPU@diana 12
As a result, the output from the ecaqrtab utility is now as follows:

Resource Name Type Max-Avail Reserved Used Free

CPU@diana L 50 0 42 8

The following command specifies that the current usage of the Quantitative resource CPU@diana by
non-Control-M jobs is 12%:
ctmloadset OTHERS CPU@diana 12%

348
Control-M Utilities Guide

The non-Control-M usage of the resource is calculated as 12% of 50, or 6 units. As a result, the output
from the ecaqrtab utility is now as follows:

Resource Name Type Max-Avail Reserved Used Free

CPU@diana L 50 0 36 14

The following command specifies that the current total usage of the Quantitative resource CPU@diana by
all jobs is 48 units:
ctmloadset TOTAL CPU@diana 48
As a result, the output from the ecaqrtab utility is now as follows:

Resource Name Type Max-Avail Reserved Used Free

CPU@diana L 50 0 48 2

ctmstvar
The ctmstvar utility displays the current value of a variable or function. To run the ctmstvar utility, see
Viewing a variable value using the ctmstvar utility (on page 349).
 UNIX only:
• A variable that does not contain a $ sign can be enclosed in single or double quotation marks.
• A variable that does contain a $ sign must be enclosed in single quotation marks.
• A variable that contains a $ sign cannot be resolved if it is enclosed in double quotation marks.
 Windows only: Variables must be enclosed with double quotation marks.
NOTE: The $WCALC variable is not supported with the ctmstvar utility.

Viewing a variable value using the ctmstvar utility

This procedure describes how to run the ctmstvar utility, which enables you to display the current value of
a variable or function.

 To view a variable value using the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Type the following command:
ctmstvar <orderID> <variableString>

349
Control-M Utilities Guide

For more details on the ctmstvar parameters, see ctmstvar parameters (on page 350).

ctmstvar parameters
The following table lists the ctmstvar utility parameters:

Variable Description

<orderID> Order ID of a job waiting in the Active Jobs database (as displayed
in the Job Details window of Control-M/EM). The Order ID displayed
in Control-M/EM is a base 36 number. If you want to specify the
Order ID here as a base 10 number, prefix the number with an
asterisk, and enclose it in quotation marks (for example,"*1234").
Use "0" to indicate no specific Order ID.

<variableString> The variable or string enclosed in quotation.

ctmstvar examples
The following are examples of the ctmstvar utility commands:
ctmstvar a1 ‘%%$CALCDATE %%ODATE -2’
ctmstvar 0 "%%ODATE"

ctmvar
The ctmvar utility defines, deletes, modifies and displays variables. This utility can be applied to variables
that are in a specific job processing definition in a SMART Folder, common to all jobs in a SMART Folder,
and global for an entire data center (a Control-M/EM database and all associated agents).
To run the ctmvar utility, see running the Creating and editing variables using the ctmvar utility (on page
351).
Consider the following:
 If a SMART Folder specified in the ctmvar utility has been ordered more than once, the utility updates
every instance of that SMART Folder in the Active Jobs database.
 Variables in jobs that are not part of a SMART Folder cannot be modified using the ctmvar utility.
 A value specified for a Global variable is overridden if a local variable with the same name is defined
in a job processing definition, Sub-folder or SMART Folder.
 Sub-folders cannot be modified using the ctmvar utility.

350
Control-M Utilities Guide

Creating and editing variables using the ctmvar utility

This procedure describes how to run the ctmvar utility, which enables you to define, delete, modify and
display variables.
 To edit variables using the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Type one of the following commands:
• ctmvar
-ACTION <LOAD|SET|DELETE|LIST>
[ -VAR <Variable> ]
[ -VAREXPR <Variable Expression> ]
[ -FILENAME <Filename> ]
-POOL
[ -LOAD -POOLNAME <Pool Name> -FROM <File Name> ]
[ -SETVAR -POOLNAME <Pool Name> -VAR <Variable Name>
-VALUE <Variable Expression> ]
[ -DELETE -POOLNAME <Pool Name> ]
[ -LIST ]
[ -VIEW -POOLNAME <Pool Name> ]
[-QUIET ]
[-DEBUG <debug level> ]
]
• ctmvar - input_file <fullPathFileName>
The ctmvar utility must always start with %%
For more details on the ctmvar parameters, see ctmvar parameters (on page 352).

351
Control-M Utilities Guide

ctmvar parameters
The following table lists the ctmvar utility parameters:

Parameter Description

-ACTION Indicates the action to be performed on the specified variable. The

possible actions are:

LOAD Loads variables from a file. When this option is used,

parameter -filename is required. The format for each
variable in the specified file is:
%%[\<SMARTflder>[\<job>]]\<varName>=<expression>
If the variable does not exist in the data center or the
specified SMART Folder or job, it is created.
If the variable already exists, it is updated with the
specified value.

SET Defines a new variable. When this option is used,

parameters -var and -varexpr are required.
If the variable does not exist in the data center or the
specified SMART Folder or job, it is created.
If the variable already exists, it is updated with the
specified value.

DELETE Deletes a Global variable. When this option is used, the

-var parameter is mandatory.
This action cannot be used for variables that have been
defined for a specific job or SMART Folder.

352
Control-M Utilities Guide

Parameter Description

LIST Displays all Global variables for the data center or all
variables for the specified SMART Folder specified in the
-var parameter.
ctmvar -action LIST
Displays all Global variables for the data
center.
ctmvar -action LIST -var "%%\PAYROLL"
Displays all variables that are global for the
PAYROLL SMART Folder.
Variable values can also be displayed using the ctmstvar
utility. However, the ctmstvar utility resolves the current
value of only a specified variable or function. The ctmvar
utility displays all variables in the data center or the
specified SMART Folder.

-VAR Name and location of the variable that the specified action should be
applied to.
The valid format for this parameter depends on the type of variable being
handled.
For a variable that is global for an entire data center, valid format is:
-var "%%\<var_name>"
For a variable that is global for all jobs in a SMART Folder, valid format is:
-var "%%\<SMART_folder_name>\<var_name>"
For variable in a specific job in a SMART Folder, valid format is:
-var "%%\<folder_name>\<jobName>\<var_name>"
This parameter cannot be specified together with -action LOAD.
For more information about variables, see Control-M Variable facility .

-VAREXPR Value to be assigned to the specified variable. The specified value can be:
a string (embedded in quotation)
an integer (a numeric value)
an Variable expression (for example, with an Variable function)
another (existing) global variable.
This parameter cannot be specified together with
-action LOAD.For more information, see Control-M Variable facility .

353
Control-M Utilities Guide

Parameter Description

-FILENAME Path and name of the file containing the list of variables. The file must be
accessible to Control-M/Server. This parameter is only valid when
specified together with -action LOAD.
The syntax for each line in the specified file is
%%[\<ctmvar>[\<job>]]\<varName>=<expression>
Specify the entire pathname in this parameter.

-QUIET Suppresses the display of the results.

-DEBUG Sets a debug level for the utility. This parameter is used for maintenance
and troubleshooting purposes. The level, a numeric value from 0 to 5,
must be used only if requested and specified by Technical Support.
Performance is somewhat slower and requires a larger number of
resources when operating in debug mode. BMC recommends that you
activate debug mode only when absolutely necessary and revert to
normal mode as soon as possible.

-input_file Name and full path of a file containing parameters for the utility. In this
file, each parameter and its values (if any) are on a separate line with the
same syntax they would have on the command line. Using the -input_file
parameter enables you to:
 prepare and save files of utility parameters that can be reused.
 specify utility input longer than the number of characters allowed in
the command line.
-input_file ~<controlm_owner>/ctm_server/data/ctmvar_parms.txt

-POOL Indicates the variable action to be performed in the specified named pool.
The following are possible actions:

LOAD Loads variable values from a specified file to pool. The file
name is the path name of a text file containing the variable
assignment statements.
This file must be accessible to Control-M. The file must
contain a single assignment on each line.
EXAMPLE:
ctmvar -POOL load -POOLNAME <pool name> - FROM
<file name>

354
Control-M Utilities Guide

Parameter Description

SETVAR Defines a new or updates an existing variable in the

specified pool.
If the variable does not exist in the data center, it is
created.
If the variable already exists, it is updated with the
specified value.
EXAMPLE:
ctmvar -POOL setvar -POOLNAME <pool name> -VAR
<variable name> -VALUE <variable value>

DELETE Deletes a named pool from the data center.

EXAMPLE:
ctmvar - POOL - delete -POOLNAME <pool name>

LIST Lists all named pools in the data center.

EXAMPLE:
ctmvar -POOL list

VIEW Displays the list of variables in the named pool.

EXAMPLE:
ctmvar - POOL - view -POOLNAME <pool name>

ctmvar examples
The following command assigns the value UP to variable %%CTMSTATUS:
ctmvar -action set -var "%%\CTMSTATUS" -varexpr "UP"
The following command assigns the value 31 to variable %%MONTHDAYS in the folder called
PAYROLL:
ctmvar -action set -var "%%\PAYROLL\MONTHDAYS"
-varexpr 31
The following command assigns the current value of system variable %%TIME to variable %%AAA:
ctmvar -action set -var "%%\AAA" -varexpr %%TIME
You can get the same result using the -input_file parameter as follows:
ctmvar -input_file ~<controlm_owner>/ctm_server/data/var_expr_parms.txt
The referenced file contains the following lines:
-action set

355
Control-M Utilities Guide

-var "%%\AAA"
-varexpr %%TIME
The format variable %%@varname indicates that the variable should contain a value to be resolved by
each job that uses it. In the following example, the command assigns the value %%@TIME to variable
%%AAA:
ctmvar -action set -var "%%\AAA" -varexpr %%@TIME
The following command sets the name of the POOL to "test" and assigns the value %%ODATE to the
variable A:
ctmvar -POOL SETVAR -POOLNAME "test" -VAR "A" -VALUE "%%ODATE"

ecactltb
The ecactltb utility displays a list of Control resources and the status of each resource. To run the ecactltb
utility, see Viewing Control Resources using the ecactltb utility (on page 356).
If the name of an output file is specified, but no path is specified for this file, the output file is placed in
the Control-M/Server home directory.

Viewing Control Resources using the ecactltb utility

This procedure describes how to run the ecactltb utility, which enables you to display a list of Control
resources and the status of each resource.

 To view Control Resources using the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is
installed.
2. Type the following command:
ecactltb [<output>]
<output> is the full path name to which the report should be sent (optional). If this parameter is not
specified, the output is routed to the default output device.
The following command generates a list of Control resources in the file rprt.txt.
ecactltb ~<controlm_owner>/ctm_server/user1/rprt.txt

356
7
7
Communication, start up, and troubleshooting
The communication, startup, and troubleshooting utilities are used to set up communication between
Control-M components, start up/shut down Control-M components and entities, and determine if
communication between the components is occurring effectively. Various troubleshooting utilities are also
included here.
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.
Some of the parameter names changed for Control-M version 8.0.00 and above, terminology from
previous versions is still supported. For a complete list of the parameter names, see Abbreviations and
conventions.

Utility Description

Control-M/Server

ctl (on page Checks if Control-M/EM Server components are operational and send
359) commands.

orbadmin (on Manages the Naming Service process and the CORBA configuration file.
page 376)

ctm_agstat (on Lists or updates the status of a Control-M/Agent.

page 380)

ctm_diag_com Generates a report on the connection details of a Control-M/Agent and its

m (on page remote host computer.
382)

ctmgetcm (on Collects and displays Control-M/Agent application information.

page 384)

ctmhostmap Manages the mapping of remote hosts to Control-M/Agents and the

(on page 386) conversion of Control-M/Agents to remote host computers.

ctmhostgrp (on Enables the maintenance and viewing of host groups.

page 392)

ctmping (on Collects configuration information about Control-M/Agents and test

page 394) communications.

ctmshout (on Issues a Shout message to a specified destination.

page 399)

357
Control-M Utilities Guide

Utility Description

ctmshtb (on Sets the active Shout Destination folder.

page 401)

ctmspdiag (on Prints or erases diagnostics from stored procedures and set or show
page 402) diagnostic request status of stored procedures.

ctmsuspend Suspends Control-M/Server scheduling processes for mass

(on page 403) uploads/downloads from Control M/EM.

init_prflag (on Resets sleep times and trace levels for Control-M/Server processes.
page 403)

shut_ca (on Shuts down the Control-M/Server Configuration Agent.

page 406)

shut_ctm (on Shuts down Control-M/Server and its processes.

page 406)

show_ca (on Displays the status of Control-M/Server Configuration Agent.

page 407)

shutdb (on Shuts down the SQL database server.

page 407)

start_ca (on Starts up the Control-M/Server Configuration Agent.

page 408)

start_ctm (on Starts up Control-M/Server.

page 408)

startdb (on Starts up the SQL database server.

page 409)

ctm_pause (on Stops Control-M/Server from submitting jobs.

page 409)

ctmchangeshdir Changes the shared directory path that is used for the PostgreSQL
(on page 410) replication in a high availability environment.

Control-M/Agent

ag_diag_comm Verifies communication between Control-M/Agent and Control-M/Server.

(on page 410)

ag_ping (on Verifies that Control-M/Server is active on computer connected to a

page 413) Control-M/Agent.

358
Control-M Utilities Guide

Utility Description

shagent (on Shows if an agent and tracker are running.

page 414)

ctl
The ctl command line utility enables you to send simple requests to Control-M/EM server components.
The ctl utility can:
 Check if Control-M/EM server components are operational.
 Check if Batch Impact Manager and Control-M/Forecast (Forecast) server components are operational
(if they are installed at your site).
 Send commands to Control-M/EM components during runtime, for example, setting Gateway debug
level.
The ctl utility is automatically installed with a full Control-M/EM installation.
To run the utility, you can select one of the following:
 Sending requests to Control-M/EM Server using the ctl utility (on page 360)
 Sending requests from the Control Shell using the ctl utility (on page 360)
The ctl utility can send request to the following:
 Gateway, as described in Sending requests to the Gateway using the ctl utility (on page 362).
 Global Conditions Server, as described in Sending requests to the Global Conditions server using the
ctl utility (on page 365).
 GUI Server, as described in Sending requests to the GUI server using the ctl utility (on page 366).
 Forecast Server, as described in Sending requests to the Forecast server using the ctl utility (on page
368).
 Configuration Management server, as described in Sending requests to the Configuration
Management server using the ctl utility (on page 370).
 Configuration Agent, as described in Sending requests to the Configuration Agent using the ctl utility
(on page 372).
 High Availability Server, as described in Sending requests to the High Availability Server using the ctl
utility (on page 373).
 BIM Server, as described in Sending requests to the BMC Batch Impact Manager server using the ctl
utility (on page 374).
 Self Service server, as described in Sending requests to the Control-M Self Service server using the ctl
utility (on page 375).

359
Control-M Utilities Guide

Sending requests to Control-M/EM Server using the ctl utility

This procedure describes how send requests to Control-M/EM Server using the ctl utility. For more
information, see ctl (on page 359).
 To run the utility:
1. Do one of the following:
• UNIX: Open an Xterm window and log in as the Control-M/EM installation account user.
• NOTE: To send requests from the Control Shell, see Sending requests from the Control Shell
using the ctl utility (on page 360).
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
2. Type ctl and add parameters as required. For more information, see Parameters common to all ctl
commands (on page 361).

Sending requests from the Control Shell using the ctl utility
This procedure describes how to run the ctl utility from the Control Shell, which enables you to send
commands to the Control-M/EM server components. These commands are the same as those that you can
run under the -cmdstr parameter, in the ctl command line utility.
 To run the ctl utility from the Control Shell:
1. Right-click the required Control-M/EM server component, and select Control Shell.
The Control Shell dialog box is displayed.
2. Click Usage to populate the Result field of the Control Shell dialog box with the commands and
requests available for the specific component.
3. Select the required command, and copy it into the Specify... field of the Control Shell dialog box. You
can also manually enter a specific command.
4. Click Apply.

360
Control-M Utilities Guide

Parameters common to all ctl commands

The following table lists the parameters that are present in the syntax of all variations of the ctl
command. The parameters specific to each server component are discussed separately in the relevant
sections, as follows:

Paramete
r Description

em Prefix to be specified when running this utility on a UNIX operating system.

-U Control-M/EM database user name.

-P Control-M/EM database user password.

-pf Flat file containing an unencrypted username and password on separate lines
in the format:
user=username
password=password

-reg Checks if the Global Conditions Server is registered in the CommReg table.
-reg cannot be used with -cmd or -cmdstr.

-cmd Indicates a command to be performed by the Global Conditions Server.

-cmd cannot be used with -reg.

stop Stops the Global Conditions Server.

This command cannot be specified with other commands in the
same run of the ctl utility.

life_chec Checks if the Global Conditions Server is active.

k
This command cannot be specified with other commands in the
same run of the ctl utility.

-timeout Indicates the period of time (in seconds) that ctl waits for a response from the
GUI Server before declaring that communication has failed.
Default: 30. Optional.

-diagon Activates tracing of ctl work flow (diagnostics). The results are written to the
ctl_diag.machine.txt file located in the working directory. Optional.

361
Control-M Utilities Guide

ctl example
This example describes specifying a specific server component and computer.
The following table lists examples showing how you can ensure that only specific server components and
computers are selected. In the examples, only the relevant section of the code is displayed.

Command Description

em ctl -U user01 -P pass01 -C Gateway -dc ctm_main Direct the ctl command to the Gateway for data center
ctm_main.

em ctl -U user01 -P pass01 -C GCS -all Direct the ctl command to all Global Conditions Servers.

em ctl -U user01 -P pass01 -C GCS -M wip78 Direct the ctl command to the Global Conditions Server
of the computer named wip78.

em ctl -U user01 -P pass01 -C GUI_Server -name gsr01 Direct the ctl command to the GUI Server on the
computer with the logical name of gsr01.

Sending requests to the Gateway using the ctl utility

This procedure describes how to send requests to the Gateway using the ctl utility.

 To send requests to the Gateway using the ctl utility:

 Type the following command:
[em] ctl -U <em dbo user> -P <em dbo pass> -C Gateway {-dc <Data_Center>
|-all}
{-reg |-cmd stop | -cmd life_check |{[-cmd dwl][-cmd change_log][-cmd
no_dbg][-cmd db{0-9}]
[-cmd gui{+|-}][-cmd host{+|-}][-cmd trunc{+|-}] [-cmd alive{+|-}][-cmd
job{+|-}] [-cmd dwl_debug{+|-}][-cmd hostlink{+|-}]
[-cmd guilink{+|-}] [-cmd show_jcl]}}[-cmdstr "<commandString>"]
[-timeout <<responseTimeout> (seconds)>][-diagon]
NOTE: You can use a password file name <-pf> instead of using -U and -P.
For more information, see Parameters common to all ctl commands (on page 361) and ctl Gateway
parameters (on page 363).

362
Control-M Utilities Guide

ctl Gateway parameters

The following table describes the ctl parameters specific to the Gateway.

Parameter Description

RETRIVE_U Directs a request to Control-M for z/OS for updated Order method information
SERDAILYO to be sent to the Control-M/EM database.
RDER_
METHOD

-C Gateway Indicates that the command is directed to the gateway. The gateway
mediates between Control-M/EM components and the Control-M installation.

-dc Name of a data center. This name identifies the gateway to which ctl is
sending a command or message. This parameter is used when a query or
command is directed to a specific gateway (as specified by the -C parameter).
-dc cannot be used with -all.

-all Directs a query or command to all components of the gateway (as specified
by the -C parameter).
-all cannot be used with -dc.

-cmd Indicates a command to be performed by the gateway.

-cmd cannot be used with -reg.

dwl Forces a new download from a Control-M installation.

The following -cmd values are used for diagnostics and debugging, as
described in Control-M diagnostics.
Diagnostic and non-diagnostic commands can be specified on the same ctl
command line.

change_file Closes the current log and diag files and creates new files.

DIAG [on|off] Start and stop DIAG. Valid values:

 on – enable diag facility
 off – disable diag facility

no_dbg Stops all debug printing.

db# Debug level for database operations. Range: 0 - 9

0 turns off debugging.

gui +| – Starts or stops a debug trace for the GUI.

host +| – Starts or stops output of host debug messages.

363
Control-M Utilities Guide

Parameter Description

trunc +| – Starts or stops truncating messages. Only the message

header and one row of data remain after truncation.

alive +| – Starts or stops debugging of "keep alive" messages.

job +| – Starts or stops dumping job messages. During a debug

trace, job+ displays messages on the screen about active
job downloads, active job updates, and Folder uploads.
This option can also be set by specifying the
trace_job_message [on | off] parameter at the command
prompt.

dwl_debug +| – Starts or stops a debug trace for the download procedure.

hostlink +| – Starts or stops a debug trace for the host link.

guilink +| – Starts or stops a debug trace for the GUI link.

show_jcl Shows active JCL.

-cmdstr Specifies a text string to be sent to the gateway. If the text string contains
spaces or tabs, it must be enclosed with double quotation marks (" ").
-cmdstr cannot be used with -reg or -cmd.
Valid values include:

DIAG [ on | off ] (either enable or disable the diagnostic facility)

DIAGL <context> (sets the diagnostic level)

<level>
[ <buffer level>]

DIAGSTACKS [ on (enables the diagnostic stacks option, or prints the details

| print ] of the current stacks)

TRACE_CLIENT (set GTW-Clients trace either on or off)

<on|off>

TRACE_CTM (set GTW-CTM trace either on or off)

<on|off>

TRACE_DB (set database trace level)

<0 - 8>

TRACE_KLIVE (set keep alive trace either on or off)

<on|off>

364
Control-M Utilities Guide

Parameter Description

TRACE_LINK_ (set GTW-Clients link level trace either on or off)

CLIENT <on|off>

TRACE_LINK_ (set GTW-CTM link level trace either on or off)

CTM <on|off>

TRACE_DISABLE_ (turns off trace options when selected)

ALL

TRACE_SNMP (set trace for SNMP traps either on or off)

<on|off>

TRACE_TRUNC (set truncate trace messages either on or off)

<on|off>

TRACE_TRUNC_IN (set truncate trace information messages either on or off)

FO <on|off>

TRACE_JOB_ (set job message trace either on or off)

MESSAGE
<on|off>

TRACE_LEVEL_ (displays the status of the trace)

REPORT

The -cmdstr parameter is used for diagnostic purposes only. For more
information about the -cmdstr parameter, see System configuration.
The ctl utility can be run from the Control Shell. For more information, see To
perform commands using the Control Shell section in ctl (on page 359).

Sending requests to the Global Conditions server using the ctl

utility
This procedure describes how to send simple requests to the Global Conditions server using the ctl utility.

 To send requests to the Global Conditions server using the ctl utility:
 Type the following command:
[em] ctl -U <em dbo user> -P <em dbo pass> -C GCS {-M <computerName> | -all}
{-reg |-cmd stop |-cmd life_check | -cmd change_file | -cmdstr
"<commandString>"}]
[-timeout <<responseTimeout> (seconds)>] [-diagon]

365
Control-M Utilities Guide

NOTE: You can use a password file name <-pf> instead of using -U and -P.
For more information, see Parameters common to all ctl commands (on page 361) and ctl Global
Conditions server parameters (on page 366).

ctl Global Conditions server parameters

The following table describes the ctl parameters specific to the Global Conditions Server.

Paramete
r Description

-C GCS Global Conditions Server to which the command is directed. The Global
Conditions Server handles the distribution of conditions that affect jobs in
more than one data center.

-M Specifies a computer name. This name is used to identify the computer to

which the Global Conditions Server belongs. -M cannot be used with -all.

-all Directs a query or command to all Global Conditions Servers. -all cannot be
used with -M.

-cmd Indicates a command to be performed by the Global Conditions Server. -cmd

cannot be used with -reg.

The following -cmd value is used for diagnostic and debugging purposes,
which is described in Control-M diagnostics.
Diagnostic and non-diagnostic commands can be specified on the same ctl
command line.

change_file Closes the current log and diag files and creates new files.

-cmdstr Specifies a text string to be sent to the Global Conditions Server. If the text
string contains spaces or tabs, it must be enclosed with double quotation
marks (" ").
-cmdstr cannot be used with -reg or -cmd.
The -cmdstr parameter is used for diagnostic purposes only. For more
information about the -cmdstr parameter, see System configuration.

Sending requests to the GUI server using the ctl utility

This procedure describes how to send requests to the GUI server using the ctl utility.

 To send requests to the GUI server using the ctl utility:

 Type the following command:
[em] ctl -U <em dbo user> -P <em dbo pass> -C GUI_Server

366
Control-M Utilities Guide

{-M <computerName> | -name <logicalName> | -all}

{-reg |-cmd stop | -cmd life_check |-cmd do_measure | -cmd get_measure
|-cmdstr "<commandString>"}
[-timeout <<responseTimeout> (seconds)>] [-diagon]
NOTE: You can use a password file name <-pf> instead of using -U and -P.
EXAMPLE: To manually refresh version management system parameters without restarting the GUI
server, issue the following command:
ctl -u <user> -p <password> -C GUI_Server -name <GSRName> -cmdstr
REFRESH_HISTORY
For more information, see Parameters common to all ctl commands (on page 361) and ctl GUI server
parameters (on page 367).

ctl GUI server parameters

The following table describes the ctl parameters specific to the GUI server.

Parameter Description

-C GUI_Server Indicates that the command is directed to one or more GUI servers. GUI
servers handle communications between Control-M/EM GUI workstations
and other Control-M/EM components.

-M Specifies a computer name. This name is used to identify the computer to

which the GUI server belongs. -M cannot be used with -all. When -M is
specified, the request is sent to the GUI server whose name is equal to the
value indicated by -M.

-name Logical name of the GUI server. If the GUI server is started without
specifying -name, the logical name of the GUI server is equal to the host
name of the computer where the GUI server is running.

-all Directs a query or command to all GUI servers. -all cannot be used with -M.

-cmd Indicates a command to be performed by the GUI server. -cmd cannot be

used with -reg.

do_measure Initiates collection of statistics about the GUI server.

This command cannot be specified with other commands
in the same run of the ctl utility.

get_measure Retrieves statistics from the GUI server and displays them.
This command cannot be specified with other commands
in the same run of the ctl utility.

367
Control-M Utilities Guide

Parameter Description

-cmdstr Specifies a text string to be sent to the GUI server. If the text string
contains spaces or tabs, it must be enclosed with double quotation marks ("
").
NOTE: -cmdstr cannot be used with -reg or -cmd.
Valid values include:
REFRESH_LDAP
REFRESH_HISTORY
For more information about the -cmdstr parameter, see System
configuration.

Sending requests to the Forecast server using the ctl utility

This procedure describes how to send requests to the Forecast server using the ctl utility.

 To access the Forecast server from the ctl utility:

 Type the following command:
ctl -U <em dbo User> -P <em dbo Pass>} -C <forecastServer>
{-M <computerName> | -name <logicalName> | -all}
{-reg |-cmd stop |-cmd life_check | -cmdstr "<Command_String>"}
[-timeout <<responseTimeout> (seconds)>][-diagon]
NOTE: You can use a password file name <-pf> instead of using -U and -P.
For more information, see Parameters common to all ctl commands (on page 361) and ctl Forecast server
parameters (on page 369).

368
Control-M Utilities Guide

ctl Forecast server parameters

The following table describes the ctl parameters specific to the Forecast server.

Paramete
r Description

-C forecast Indicates that the command is directed to a Forecast server (if

Server Control-M/Forecast is installed at your site).

-M Specifies a computer name. This name is used to identify the computer to

which the Forecast server belongs.

-name Logical name of the Forecast server. If the Forecast server is started without
specifying -name, the logical name of the Forecast server is equal to the host
name of the computer where the Forecast server is running.

-all Directs a query or command to all Forecast servers. -all cannot be used with
-M.

369
Control-M Utilities Guide

Paramete
r Description

-cmdstr Specifies a text string to be sent to the Forecast server. If the text string
contains spaces or tabs, it must be enclosed with double quotation marks (" ").
NOTE: -cmdstr cannot be used with -reg or -cmd.
The usage of -cmdstr is discussed in System configuration.
The following commands are available:
 USERDAILY_CLEAN - clean all the info or just the info for one job key in
the USER_DAILY_ZOS folder
Syntax: USERDAILY_CLEAN <CTM name> [dsn] [folder] [file name]
USERDAILY_DATA - The user daily definitions (job ordered, folder list or
user daily list) information gathered in the Control-M/EM database can be
exported to a CSV file. The file can contain the following data:
 Data center name
 Lib name of job
 Folder name of job
 Job name
 Order type
 Target type
 Lib name of folder
 Folder name
 Task mask
 RBC mask
 ODAT
 Force
 Order method

Sending requests to the Configuration Management server using

the ctl utility
This procedure describes how to send simple requests to the Configuration Management server using the
ctl utility.

370
Control-M Utilities Guide

 To send requests to the Configuration Management server using the ctl utility:
 Type the following command:
ctl -U <em dbo User> -P <em dbo Pass> -C CMS |
{-M <computerName> |-name <logicalName> | -all}
{-reg |-cmd stop |-cmd life_check |-cmdstr "<commandString>"}
[-timeout <<responseTimeout> (seconds)>][-diagon]
NOTE: You can use a password file name <-pf> instead of using -U and -P.
For more information, see Parameters common to all ctl commands (on page 361) and ctl Configuration
Management server parameters (on page 371).

ctl Configuration Management server parameters

The following table describes the ctl parameters specific to the Configuration Management Server.

Paramete
r Description

-C CMS Configuration Management Server to which the command is directed.

-M Specifies a computer name. This name is used to identify the computer to

which the Configuration Management Server belongs. -M cannot be used with
-all. When -M is specified, the request is sent to the GUI Server whose name is
equal to the value indicated with -M.

-name Logical name of the Configuration Management Server. If the Configuration

Management Server is started without specifying -name, the logical name of
the Configuration Management Server is equal to the host name of the
computer where the Configuration Management Server is running.

-all Directs a query or command to all Configuration Management Servers.

-all cannot be used with -M.

-cmdstr Specifies a text string to be sent to the Configuration Management Server. If

the text string contains spaces or tabs, it must be enclosed with double
quotation marks (" ").
NOTE: -cmdstr cannot be used with -reg or -cmd.
For more information about the -cmdstr parameter, see the System
configuration.

371
Control-M Utilities Guide

Sending requests to the Configuration Agent using the ctl utility

This procedure describes how to send requests to the Configuration Agent using the ctl utility.

 To send requests using the Configuration Agent from the ctl utility:
 Type the following command:
ctl -U <emUser> -P <emPass> -C Config_Agent
{-M <Computer_Name> | -all}
{-reg |-cmd stop | -cmd life_check | -cmd shutdown} | -cmdstr
"<commandString>"}]
[-timeout <<responseTimeout> (seconds)>] [-diagon]
NOTE: You can use a password file name <-pf> instead of using -U and -P.
For more information, see Parameters common to all ctl commands (on page 361) and ctl Configuration
Agent parameters (on page 373).

372
Control-M Utilities Guide

ctl Configuration Agent parameters

The following table describes the ctl parameters specific to the Configuration Agent.

Parameter Description

-C Config_Agent Configuration Agent to which the command is directed. The

Configuration Agent controls Control-M/EM components on the host
computer.

-M Specifies a computer name. This name is used to identify the computer

to which the Configuration Agent belongs. -M cannot be used with -all.

-all Directs a query or command to all Configuration Agents.

-all cannot be used with -M.

-cmd Indicates a command to be performed by the Configuration Agent. -cmd

cannot be used with -reg.

shutdown Stops the Configuration Agent, and all components that the
Configuration Agent administers, without changing their
configurations. This command cannot be specified with
other commands in the same run of the ctl utility.

-cmdstr Specifies a text string to be sent to the Configuration Agent. If the text
string contains spaces or tabs, it must be enclosed with double
quotation marks (" ").
-cmdstr cannot be used with -reg or -cmd.
For more information about the -cmdstr parameter, System
configuration.

Sending requests to the High Availability Server using the ctl utility
This procedure describes how to send simple requests to the High Availability Server using the ctl utility.

 To send requests to the High Availability Server using the ctl utility:
 Type the following command
ctl -U <em dbo User> -P <em dbo Pass> -C Config_HA
{-M <Computer_Name> | -all}
{-reg |-cmd stop | -cmd life_check | -cmd shutdown} | -cmdstr
"<commandString>"}]
[-timeout <<response Timeout> (seconds)>] [-diagon]
NOTE: You can use a password file name <-pf> instead of using -U and -P.
For more information, see Parameters common to all ctl commands (on page 361).

373
Control-M Utilities Guide

ctl High Availability Server parameters

The following table describes the ctl parameters specific to High Availability Server.

Parameter Description

-C Config_HA Configuration High Availability Server to which the command is directed.

-M Specifies a computer name. This name is used to identify the computer

to which the Configuration Agent belongs. -M cannot be used with -all.

-all Directs a query or command to all Configuration Agents.

-all cannot be used with -M.

-cmd Indicates a command to be performed by the High Availability Server.

-cmd cannot be used with -reg.

shutdown Stops the High Availability Server, and all components that
the High Availability Server administers, without changing
their configurations. This command cannot be specified
with other commands in the same run of the ctl utility.

-cmdstr Specifies a text string to be sent to the High Availability Server. If the
text string contains spaces or tabs, it must be enclosed with double
quotation marks (" ").
NOTE: -cmdstr cannot be used with -reg or -cmd.
For more information about the -cmdstr parameter, System
configuration.

Sending requests to the BMC Batch Impact Manager server using

the ctl utility
This procedure describes how to access the BMC Batch Impact Manager server using the ctl utility.
 To send requests to the BMC Batch Impact Manager server using the ctl utility:
 Type the following command:
ctl -U <emUser> -P <emPass> -C BIM
{-M <computerName> -name <logicalName>}
{-reg |-cmd stop | -cmd life_check | -cmdstr "<Command_String>"}
[-timeout <<responseTimeout> (seconds)>]
[-diagon]
NOTE: You can use a password file name <-pf> instead of using -U and -P.

374
Control-M Utilities Guide

For more information, see Parameters common to all ctl commands (on page 361) and ctl BMC Batch
Impact Manager server parameters (on page 375).

ctl BMC Batch Impact Manager server parameters

The following table describes ctl parameters specific to the BMC Batch Impact Manager server.

Paramete
r Description

-C BIM Indicates that the command is directed to a Batch Impact Manager server (if
this component is installed at your site).

-M Specifies a computer name. This name is used to identify the computer to

which the Batch Impact Manager server belongs.

-name Logical name of the Batch Impact Manager server. If the Batch Impact
Manager server is started without specifying -name, the logical name of the
Batch Impact Manager server is equal to the host name of the computer where
the Batch Impact Manager server is running.

-cmdstr Specifies a text string to be sent to the Batch Impact Manager server. If the
text string contains spaces or tabs, it must be enclosed with double quotation
marks (" ").
NOTE: -cmdstr cannot be used with -reg or -cmd.
Its usage is discussed in System configuration.

Sending requests to the Control-M Self Service server using the ctl
utility
This procedure describes how to send requests to the Control-M Self Service server using the ctl utility.
 To send requests to the Control-M Self Service server using the ctl utility:
 Type the following command:
ctl -U <emUser> -P <emPass> -C Self Service Server
{-M <computerName> | -name <logicalName>}
{-reg |-cmd stop |-cmd life_check | -cmdstr "<Command_String>"}
[-timeout <<responseTimeout> (seconds)>] [-diagon]
NOTE: You can use a password file name <-pf> instead of using -U and -P.
For more information, see Parameters common to all ctl commands (on page 361) and ctl Self Service
server parameters (on page 376).

375
Control-M Utilities Guide

ctl Self Service server parameters

The following table describes ctl parameters specific to the Self Service Server.

Parameter Description

-C Self Indicates that the command is directed to a Self Service Server (if this
Service component is installed at your site).
Server

-M Specifies a computer name. This name is used to identify the computer to

which the Self Service Server belongs.

-name Logical name of the Self Service Server. If the Self Service Server is started
without specifying -name, the logical name of the Self Service Server is equal
to the host name of the computer where the Self Service Server is running.

-cmdstr Specifies a text string to be sent to the Self Service Server. If the text string
contains spaces or tabs, it must be enclosed with double quotation marks
(" ").
NOTE: -cmdstr cannot be used with -reg or -cmd.
Its usage is discussed in System configuration.

orbadmin
The orbadmin (CORBA administration) utility can be used to manage the Naming Service process and the
CORBA configuration file. To run the orbadmin utility, see Running the orbadmin utility (on page 376).
Control-M/EM uses an XML CORBA configuration file that defines CORBA parameters for CORBA
components. The parameters and values in this file can be initialized and modified by the orbconfigure
GUI (see the description of the orbconfigure CORBA configuration GUI in Control-M Administration), and
by the orbadmin utility (described here).

Running the orbadmin utility

This procedure describes how to run the obadmin utility, which enables you to manage the Naming
Service process and the CORBA configuration file.

 To run the orbadmin utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.

376
Control-M Utilities Guide

2. Type one of the following commands to invoke the orbadmin utility:

• orbadmin domain <domainCommand>
• orbadmin ns <namingServiceCommand> [<option>]
• orbadmin scope <scopeCommand> [<scopeName>]
• orbadmin variable <variableCommand> [-scope <scopeName>] -value <value>
| <varName>
For details about the orbadmin parameters, see orbadmin parameters (on page 377).

orbadmin parameters
The following table lists the orbadmin parameters:

Command format Usage

domain show Displays all parameters and values in the configuration file

scope list Displays all the scopes in a configuration file

scope create <name> Creates a new scope in the configuration file

scope remove <name> Removes a scope and its parameters from the file

scope show <name> Displays parameters and their values in the scope

variable create -scope <scope> Creates a parameter (with or without a value) in the specified scope.
-value <value> <name>
If that scope does not exist, it is created. If the value contains a blank,
enclose the value in double quotes.

variable modify [-scope <scope>] Modifies a parameter value (in the specified scope) of the
-value <value> <name> configuration domain. If the parameter does not exist, it is added
automatically.
If the scope is not specified, the parameter is modified in every scope
that contains it. If the specified value contains a blank, enclose the
value in double quotes.

variable remove -scope <scope> Removes specified parameter from the XML configuration file.
<name>
If the scope is not specified, the parameter is removed from all the
scopes that contain it.

variable show -scope <scope> Displays the specified parameter and its value in the specified (or
<name> default) scope.
If the parameter does not exist in the specified scope, the default
scope is searched.

377
Control-M Utilities Guide

Command format Usage

ns register (Windows only) Specifies Naming Service values in the registry and
installs the Naming Service as a Windows service.

ns update Updates the Naming Service values in the registry.

ns remove (Windows only) Removes Naming Service values from the registry and
uninstalls the Windows service.

ns start Starts the local Naming Service.

ns stop [-local] Stops the Naming Service. -local is required if a remote Naming
Service is running and you want to stop the local Naming Service.

ns status Checks the status of the configured Naming Service process. Possible
status values: Running, Stopped, and Not installed.

ns probe Checks if the local Naming Service is configured and registered.

ns resolve Resolves the Naming Service IOR and prints it to the console.

ns list [-ior] Lists all registered objects in the Naming Service with endpoint
information. If -ior is specified, IOR references of the registered
objects are printed to the console.

orbadmin examples
The following are examples of outputs and examples for some of the orbadmin utility commands:
ns status sample output:
Naming service status: Running on remote machine, vered:13075
ns resolve sample output:
IOR:010000000100000000000000010000000000000024000000010102cd06000000766572
65640013330b0000004e616d6553657276696365cd00000000
ns list sample output:
BMC Software: naming context
EM: naming context
vered: naming context
GSR: naming context
XMLInvoker: object reference:Protocol: IIOP, Endpoint:
172.16.131.242:59020

378
Control-M Utilities Guide

EMSystemParameters: object reference: Protocol: IIOP, Endpoint:

172.16.131.242:59020
CollectionRepository: object reference: Protocol: IIOP, Endpoint:
172.16.131.242:59020
SchedEntityFieldsDesc: object reference: Protocol: IIOP, Endpoint:
172.16.131.242:59020
DefDB: object reference: Protocol: IIOP, Endpoint: 172.16.131.242:59020
ViewRepository: object reference: Protocol: IIOP, Endpoint:
172.16.131.242:59020
CTMRepository: object reference: Protocol: IIOP, Endpoint:
172.16.131.242:59020
BimProxy: object reference: Protocol: IIOP, Endpoint:
172.16.131.242:59020
FilterRepository: object reference: Protocol: IIOP, Endpoint:
172.16.131.242:59020
HierarchyRepository: object reference: Protocol: IIOP, Endpoint:
172.16.131.242:59020
PlayerControl: object reference: Protocol: IIOP, Endpoint:
172.16.131.242:59020
CommAdminDB: object reference: Protocol: IIOP, Endpoint:
172.16.131.242:59020
UsersManager: object reference: Protocol: IIOP, Endpoint:
172.16.131.242:59020
ns list -ior sample output:
BMC Software: naming context
EM: naming context
vered: naming context
GSR: naming context
XMLInvoker:<IOR:010000001a00000049444c3a4543534150492f584d4c496e766f6b657
23a312e30000000010000000000000074000000010102cd0f0000003137322e31362e31333
12e32343200658ce672762300000014010f004e535442301d69000952f9000000010000000
10000000a000000010000000bcd0200000000000000080000000000000054414f000100000
0140000000000000000010001000000000001010900000000>
scope create
The following command creates a scope named test:
orbadmin scope create test
After creating a new scope, use the orbadmin variable create command to add parameters to the
new scope.
scope list
To display all the scopes in the XML configuration file:

379
Control-M Utilities Guide

orbadmin scope list

default
GSR
GUI
XmlUtils
ns
scope show
This command displays the contents of the default configuration scope:
orbadmin scope show default
-ORBInitRef = NameService=corbaloc::1.2@host:12345/Name Service
-ThreadPoolSize = 10
variable create
This example creates a variable named -PreferIPMask in the scope Default.
orbadmin variable create -scope default -value 172.16.0.0 -PreferIPMask
variable modify
This example modifies the filename for the pid of the naming service.
orbadmin variable modify -scope ns -value ns2.pid -p
variable show
This example displays a parameter in the default configuration scope:
orbadmin variable show orb -ThreadPoolSize
-ThreadPoolSize = 10
This example shows the same parameter as it is set for the GUI Server in the configuration scope GSR:
orbadmin variable show -scope GSR -ThreadPoolSize
-ThreadPoolSize = 15
This example shows the same parameter as it is set for the CLI, although the configuration scope CLI
does not contain it:
orbadmin variable show -scope CLI -ThreadPoolSize
-ThreadPoolSize = 10

ctm_agstat
The ctm_agstat utility enables you to list or update the status of an agent. For more information, see
communication status of agents and remote hosts in Component management. To run the ctm_agstat
utility, see Running the ctm_agstat utility (on page 381).

380
Control-M Utilities Guide

Running the ctm_agstat utility

This procedure describes how to run the ctm_agstat utility, which enables you to list or update the status
of an agent.
 To run the ctm_agstat utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctm_agstat
{ -LIST <agentName> | -UPDATE <agentName> {AVAILABLE | DISABLED} }
[ -DEBUG <debug level 1-5> ]
[ -QUIET ]
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctm_agstat parameters, see ctm_agstat parameters (on page 381).

ctm_agstat parameters
The following table describes the parameters of the ctm_agstat utility:

Parameter Description

-LIST Lists the current status of the specified agent.

NOTE: This parameter is mandatory if the -UPDATE parameter is
not specified.

-UPDATE Changes the status of the specified agent to the specified status.
This parameter is mandatory if the -LIST parameter is not
specified
The permissions of the AGSTAT directory must be modified to
allow access to users who will run the ctm_agstat utility with the
-UPDATE parameter.

<agentName> Host name of the agent to be listed or updated.

This name must be specified for -LIST and
-UPDATE parameters.

AVAILABLE Status where Control-M/Server is able to

communicate with the specified
Control-M/Agent.

381
Control-M Utilities Guide

Parameter Description

DISABLED Status where Control-M/Server ignores (does

not attempt to communicate with) the specified
Control-M/Agent.

-DEBUG <debug level> Set the required diagnostic level. Valid values: 0 (no diagnostics)
to 5 (highest level of diagnostics).

-QUIET If this parameter is specified, the utility runs without displaying

output messages.

ctm_agstat examples
The following are examples of the ctm_agstat utility commands:
To display the current status of agent CMAGENT, type:
ctm_agstat -LIST CMAGENT
To change the status of agent CMAGENT to DISABLED, type:
ctm_agstat -UPDATE CMAGENT DISABLED

ctm_diag_comm
The ctm_diag_comm utility generates a report about the connection details between the specified
Control-M/Agent or remote host and Control-M/Server. You can either specify the host name of a
computer where Control-M/Agent is installed, or the host name of a computer with which you want
Control-M/Server to communicate. To run the ctm_diag_comm utility, see Running the ctm_diag_comm
utility (on page 382).

Running the ctm_diag_comm utility

This procedure describes how to generate a report about the connection details between the specified
Control-M/Agent or remote host and Control-M/Server.

 To running the ctm_diag_comm utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type one of the following commands:
• To run the utility interactively:
ctm_diag_comm

382
Control-M Utilities Guide

You are prompted for the host name of the Control-M/Agent or remote host.
• To run the utility as a single command:
ctm_diag_comm <agent> | <remoteHost>
For more details on the ctm_diag_comm parameters, see ctm_diag_comm parameters (on page 383).

ctm_diag_comm parameters
The following table lists the ctm_diag_comm utility parameters:

Parameter Description

<agent> Host name of the computer where Control-M/Agent is installed

<remoteHost> Name of the specified remote host with which Control-M/Server

should attempt to communicate.

ctm_diag_comm example
The following is an example of ctm_diag_comm report:
Assume that Control-M/Server is installed on the UNIX computer with host name taurus. Control-M/Agent
has not yet been defined in the Control-M/Server database, so when ctm_diag_comm is invoked, it will try
to generate a report connecting it as an agent or remote host. The report below is displayed after
invoking the following command:
Control-M/Server to Control-M/Agent Communication Diagnostic Report
-------------------------------------------------------------------
CTMS User Name : ctm900sd
CTMS Directory : /home1/ctm900sd/ctm
CTMS Platform Architecture : Solaris
CTMS Installed Version :
CTMS Local IP Host Interface Name : taurus
Server-to-Agent Port Number : 12666
Agent-to-Server Port Number : 7420
Server-Agent Comm. Protocol : TCP
Server-Agent Protocol Version : 07
Server-Agent Connection mode : Transient
Agent Platform Name : mars
Agent Status : Unknown
Agent known Type : Undefined

383
Control-M Utilities Guide

UNIX ping to Agent or Remote host : Succeeded

CTMS ping to Agent or Remote host : Succeeded
CTMS Ping mars as Regular Agent
==============================
Agent [mars] responded with "Agent not available."
CTMS Ping mars as Remote Host
============================
Remote host [mars] is available through Agent [nova]
Connection protocol : SSH
Port number : 22
Encryption method : BLOWFISH
Compression : No

ctmgetcm
The ctmgetcm utility is used to collect, store and display application server information from
Control-M/Agents. To run the ctmgercm utility, see Running the ctmgetcm utility (on page 384).
 When the action parameter is set to GET, application server information is collected, stored in a folder
in the Control-M/Server database, and displayed.
 When the action parameter is set to VIEW, previously stored application server information is
displayed.
Control-M information is updated only after ctmgetcm is run, or each time ctmgetcm is reconfigured.

Running the ctmgetcm utility

This procedure describes how to collect, store and display application server information from
Control-M/Agents using the ctmgetcm utility.
 To run the ctmgetcm utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type one of the following commands
• To run the utility interactively:
ctmgetcm
You are prompted for the required parameters as if you had selected the View Host ID Details
option of the Control-M Main Menu.
• To run the utility as a single prompt:

384
Control-M Utilities Guide

ctmgetcm -HOST agent -APPLTYPE OS -ACTION <get|view>

For more details on the ctmgetcm parameters, see ctmgetcm parameters (on page 385).

ctmgetcm parameters
The following table lists the ctmgetcm utility parameters:

Parameters Description

-HOST Host name of the agent computer.

-APPLTYPE Name of the application server (for example, SAP).

A wildcard character can be used to specify more than one application:
Specify * to retrieve information for all applications.
Specify O* to retrieve information for all applications beginning with O (for
example, ORA or OS).
OS can be specified to return information about the Application Add-on for
the current operating system.

-ACTION Indicates the action that the ctmgetcm utility should perform. Valid values
are:

GET Collect and display updated application information from the

specified Control-M/Agent. The information collected is stored in
the Control-M/Server database.

VIEW Display application server information that was previously

collected from the specified agent computer.
This action will display only information that was retrieved
previously using a GET action.

ctmgetcm example
The following are examples of the ctmgetcm utility commands:
Specify the following command to view existing information for all applications on the Control-M/Agent
sahara computer:
ctmgetcm -host sahara -appltype "*" -action VIEW
Output similar to the following is displayed:
HOST APPLTYPE APPLVER CMVER
------- --------- -------- ------

385
Control-M Utilities Guide

sahara ORA 7 2.0.00

sahara SAP 4.5 2.0.01
sahara OS SOLARIS 1.0.00
Specify the following command to view existing information for all applications with prefix O on the
Control-M/Agent sahara computer:
ctmgetcm -host sahara -appltype O* -action VIEW
Output similar to the following is displayed:
HOST APPLTYPE APPLVER CMVER
------- --------- -------- ------
sahara ORA 7 2.0.00
sahara OS SOLARIS 1.0.00
Specify the following command to update the Control-M/Server database with new information for all
applications with prefix O on the Control-M/Agent sahara computer:
ctmgetcm -host sahara -appltype O* -action GET
The Control-M/Server database is updated and output similar to the following is displayed:
HOST APPLTYPE APPLVER CMVER
------- --------- -------- ------
sahara ORA 7 2.0.00
sahara ORA 8 2.0.00
sahara OS SOLARIS 1.0.00

ctmhostmap
The ctmhostmap utility manages the mapping of remote host computers to agents and the conversion of
Control-M/Agents to remote host computers. This utility can be run from the command line, or by using
the Control-M Configuration Manager. For more information about using the Control-M Configuration
Manager, see Introduction to Control-M Configuration Manager. To run the ctmhostmap utility, see
Running the ctmhostmap utility (on page 386).
Each computer that is defined as a remote host is listed in the Control-M/Server database. The
ctmhostmap utility enables you to manage the entries in the database.

Running the ctmhostmap utility

This procedure describes how to run the ctmhostmap utility, which enables you to manage the mapping
of remote host computers to agents and the conversion of Control-M/Agents to remote host computers.

 To run the ctmhostmap utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account

386
Control-M Utilities Guide

• Windows: Open a command prompt window where Control-M/Server is installed.

2. Type one of the following commands:
• ctmhostmap -action add [-force] -host <remoteHost>
-agent <agentsList>
-protocol SSH|WMI [-sshport <SSHportNumber>
-sshalg BLOWFISH|AES|DES|3DES
-compression <SSH compression Y/N>] [-outputdir <WMIoutputDirectory>]
• ctmhostmap -action update -host <remoteHost> [-agent <agentsList>]
[-protocol SSH|WMI]
[[-sshport <SSHportNumber>
-sshalg BLOWFISH|AES|DES|3DES
-compression <SSH compression Y/N>] [-outputdir <WMIoutputDirectory>]]
• ctmhostmap -action delete -host <remoteHost>
• ctmhostmap -action list [-host <remoteHost>]
• ctmhostmap help
For more details on the ctmhostmap parameters, see ctmhostmap parameters (on page 389).

387
Control-M Utilities Guide

ctmhostmap Actions
The following table describes the actions in the ctmhostmap utility:

Action Description

add Specifies the details of the remote host computer that is being defined in the
Control-M/Server database.
Control-M/Server discovers the specified computer using default remote host
map settings if the following is specified without further parameters:
ctmhostmap -action add -host <remoteHost>
Separate the agent names with a semicolon (;) when adding more than one
agent.
For UNIX: If more than one Control-M/Agent is being added, the entire list must
be enclosed in quotation marks, for example "jupiter;andromeda;taurus".

update Modifies the details of the specified remote host computer in the
Control-M/Server database.
Separate the agent names with a semicolon when adding more than one agent.
For UNIX: If more than one Control-M/Agents are being added, the entire list
must be enclosed in quotation marks, for example "jupiter;andromeda;taurus".
Control-M/Server replaces the existing settings of a remote host with the
settings of Default if the following command is specified:
ctmhostmap -action update -host "<Default>"

delete Deletes the details of the specified remote host computer in the
Control-M/Server database.

list Lists the details of the specified remote host computer in the Control-M/Server
database. The resultant list includes all remote host computers and their
statuses, except when list is specified with -host (see description below).

help Displays the usage of the ctmhostmap utility.

388
Control-M Utilities Guide

ctmhostmap parameters
The following table lists the ctmhostmap utility parameters:

Paramete
r Description

-force Override a regular agent computer that has the same name as the specified
computer. Optional.
This option is used in order to convert regular agent to remote host. For more
information, see the appendix in the in Defining a remote host.

-host Specifies the name of the remote host computer or <Default>. The name of
the host cannot exceed 50 characters.
This parameter is:
 mandatory when specified with add, update, and delete
 optional when specified with list
<Default > is not applicable if the delete action is specified.
If -host is specified with -list, the remote host is not <Default>, and the status
is not Discovering, then the details of the specified remote host are displayed.
The output includes the following:
 all the remote host definition parameter values
 remote host status
 status of each agent, showing which remote host is defined to be available
through it
To view the "Default Remote Settings", specify the following command:
ctmhostmap -action list -host "<Default>"

-agent List of agent names, separated by semi-colons (;). For UNIX: Enclose the
entire list in quotation marks.
This parameter is:
 mandatory when specified with add
 optional when specified with update
For example, to list more than one Control-M/Agent, the entire list must be
separated by semi-colons, for example pluto;mars;saturn. For UNIX, the list
would be: "pluto;mars;saturn".

389
Control-M Utilities Guide

Paramete
r Description

-protocol Indicates which protocol is used by the agent to execute jobs on the remote
host computer. Mandatory. Valid values are:
 SSH – Secure Shell (SSH) for UNIX or Windows computers
 WMI – Windows Management Instrumentation (WMI) for Windows
computers
If SSH is specified, then the following parameters must be specified:

-sshport Specifies the SSH port number that the SSH daemon is
listening to on the remote host computer. Valid value: 22 or
an integer from 1024 through 65535

-sshalg Indicates which SSH encryption algorithm is being used.

Valid values are:
 BLOWFISH
 AES
 DES
 3DES

-compression Valid values are:

 Y – compression is used
 N – compression is not used

If WMI is specified, then the outputdir parameter must be specified.

NOTE: The outputdir must either be prefaced with double back-slashes (for
example d:\\output_dir), or be enclosed with quotation marks (for example
"d:\output_dir").

-outputdir Indicates the directory used for the OUTPUT files created by
jobs that have been submitted. The name of the outputdir
cannot exceed 1,024 characters.
NOTE: Configure the specified directory on the remote host
as a shared directory, with the shared name of OUTPUT.

ctmhostmap examples
The following are examples of the ctmhostmap utility commands:
To add remote host mars to the Control-M/Server database, mapped through Control-M/Agents pluto,
neptune, and venus, using SSH protocol, run the following command:

390
Control-M Utilities Guide

ctmhostmap -action add -host mars -agent "pluto;neptune;venus" -protocol ssh -sshport 54 -sshalg des
-compression N
The following message is displayed:
Remote host added successfully.
To add remote host saturn, mapped through Control-M/Agent jupiter, using WMI protocol, run the
following command:
ctmhostmap -action add -host saturn -agent jupiter -protocol wmi -outputdir
d:\\ctm\\data
The following message is displayed:
Remote host added successfully.
As described above, but the OUTPUT directory contains spaces. Run the following command:
ctmhostmap -action add -host saturn -agent jupiter -protocol wmi -outputdir
"c:\ctm eur\data"
The following message is displayed:
Remote host added successfully.
To add remote host saturn, mapped through Control-M/Agents jupiter, andromeda, and taurus using SSH
protocol, run the following command:
ctmhostmap -action add -host mars -agent "jupiter;andromeda;taurus" -protocol
ssh -sshport 22 -sshalg blowfish -compression N
The following message is displayed:
Remote host added successfully.
When modifying an existing entry, only the parameters that are being updated are mandatory. To change
the SSH port number of remote host mars from 54 to 48, and to change the SSH algorithm from DES to
3DES, run the following command:
ctmhostmap -action update -host mars -sshport 48 -sshalg 3des
The following message is displayed:
Remote host updated successfully.
To delete remote host mars from the Control-M/Server database, specify the following command:
ctmhostmap -action delete -host mars
The following message is displayed:
Action ‘delete’ ended successfully.
To display a list of remote hosts, run the following command:
ctmhostmap -action list
The following report is displayed:
Remote Host Status
orion Available
taurus Unavailable

391
Control-M Utilities Guide

pegasus Unavailable
Action ‘list’ ended successfully.
To display the details of remote host orion, run the following command:
ctmhostmap -action list -host orion
The following report is displayed:
Remote host ‘orion’ settings:
Protocol : SSH
Port Number : 22
Encryption : BLOWFISH
Compression : NO
Agents : (comet) (meteor) (cyborg)
Remote Host Status : Available
Agents Statuses : (comet: Available) (meteor: Available) (cyborg:
Available)
Action ‘list’ ended successfully.

ctmhostgrp
The ctmhostgrp utility is used to maintain and view host groups. This utility provides the command line
facility for running the options available from the Host Group Menu. To run the ctmhostgrp utility, see
Running the ctmhostgrp utility (on page 392).
The Host Group menu is used to maintain and view host groups. Host groups are used by the
Control-M/Server load-balancing function. For additional instructions, see Host group management.

Running the ctmhostgrp utility

This procedure describes how to run the ctmhostgrp utility, which enables you to maintain and view host
groups.
 To run the ctmhostgrp utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctmhostgrp
[ -LIST |
-EDIT -HOSTGRP <hostGroup>
-APPLTYPE <applicationType>

392
Control-M Utilities Guide

[ -VIEW |
-ADD <hostid> |
-DELETE <hostid> ] |
For more details on the ctmhostgrp parameters, see ctmhostgrp parameters (on page 393).

ctmhostgrp parameters
The following table lists the ctmhostgrp utility parameters:

Variable Description

-LIST Displays a list of all existing host groups.

-EDIT Views, creates, or modifies a host group.

-HOSTGRP Specifies which host group to be viewed, created, or

modified.

-APPLTYPE Specify the application with which the host group is

associated.
Valid values are:
 OS – None Application Add-on (Default)
 SAP – SAP Applications
 OAP – Oracle Applications
 Any other application type defined by the user. For
more information, see the Software Development
Guide for Application Add-ons.

-VIEW Displays the host IDs in the specified

host group.

-ADD Prompts for the name of a host ID to

add to the specified group.
NOTE: The selected host ID must be
able to run jobs associated with the
application type specified for this host
group.

-DELETE Prompts for the name of a host ID to

delete from the specified group.

-DELETE Prompts for the name of the host group to delete from the specified
group.

393
Control-M Utilities Guide

ctmping
The ctmping utility tests, configures, and reports on the connection and availability between
Control-M/Server and Control-M/Agents or remote host computers. To run the ctmping utility, see
Running the ctmping utility (on page 394).
ctmping can be included in the Watchdog process. For more information, see Watchdog process
parameters.
This utility can check if an agent or remote host is down and, if required, register it in the database as
unavailable. When the agent or remote host again becomes available, the state is changed and
information about it is gathered by a Control-M/Server process.
You cannot ping the agent if the agent is upgrading. When the agent becomes available again, then you
can ping the agent. The following error message appears:
Cannot ping the agent. Agent is upgrading.

Running the ctmping utility

This procedure describes how to run the ctmping utility, which enables you to test, configure, and report
on the connection and availability between Control-M/Server and Control-M/Agents or remote host
computers.
 To run the ctmping utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctmping -HOSTID <hostName> [ -HOSTTYPE <REGULAR|REMOTE> ]
[ -HOSTID <hostName> [ -HOSTTYPE <REGULAR|REMOTE> ] ]
[ -FILE <inputFile> ]
[ -DISCOVER <y|n>]
[ -DEBUG <debugLevel> ]
[ -QUIET ]
[ -FULLDETAILS ]
For more details on the ctmping parameters, see ctmping parameters (on page 395).

394
Control-M Utilities Guide

ctmping parameters
The following table lists the ctmping utility parameters:

Parameter Description

-HOSTID Host name of the agent or remote host computer to be pinged (tested).
At least one Host ID must be specified for each run of the ctmping utility.
Additional Host IDs can optionally be specified to enable a single run of this
utility to test communication with more than one agent computer.

-HOSTTYPE Describes the type of computer that is being pinged.

REGULAR – A computer that is registered as an agent in the Control-M/Server
database. Control-M/Agent is installed on this computer.
REMOTE – A computer that is registered as a remote host in the
Control-M/Server database. It is not necessary for a Control-M/Agent to be
installed on this computer. A computer that has a Control-M/Agent installed
on it, can also be registered as a remote host.
If you do not specify a HOSTTYPE:
 if the host ID of the computer is already defined, the HOSTTYPE that was
defined is used again
 if the host ID of the computer was not used previously, then REGULAR is
used as the default
 in the event that the type is unknown, that is, still in host discovery state,
the utility is unable to complete the request. Wait for the discovery
process to complete, then run the utility again.
If you specify a HOSTTYPE:
 if the host ID is already defined in Control-M/Server and it conflicts with
the earlier definition (for example, it was defined earlier as REGULAR and
you are now specifying REMOTE), then the utility will not be able to
complete the request. If the intention was to convert the defined host
type, then for more information about how to convert a computer from
one type to another, see ctmhostmap (on page 386) and Defining a
remote host.
 if the host ID is already defined in Control-M/Server and the HOSTTYPE
being specified now is same as that of the earlier definition, then the
utility will use the specified HOSTTYPE for the host ID.
 if the host ID has not been previously defined in Control-M/Server, then
the utility will use the specified HOSTTYPE for the host ID.

395
Control-M Utilities Guide

Parameter Description

-FILE Full path and name of a file containing a list of host computers to be pinged.
Each line in the specified file contains:
 the name (host ID) of the agent or remote host (mandatory)
 the HOSTTYPE (optional)
The delimiter between the name and the HOSTTYPE is a blank or any number
of blank spaces.
Where the computer type is not specified, a discovery process attempts to
determine the type to be used. See -HOSTTYPE above.
EXAMPLE: Assume the following computers must be pinged:
Name Type
dime not specified
comet Control-M/Agent
mars remote host computer
EXAMPLE: The text below specifies the above details in a file:
dime
(HOSTTYPE is not specified)
comet REGULAR
mars REMOTE

-DISCOVER Indicates whether to update the database.

 Y – Update the database with information gathered by the utility
 N – Do not update the database
NOTE: If -DISCOVER is not specified, ctmping performs an automatic
discovery, as follows:
If an agent is
 available – the Control-M/Server database is updated with the details of
the agent or remote host
 unavailable, for a new agent or remote host in the Control-M/Server
database, a message is displayed, asking if you want to add the
discovered agent to the Control-M/Server database
Default: automatic discovery

-DEBUG Activates a debug trace at the specified level. Valid levels: 0 through 5.
Default: 0. Performance is slower when operating in debug mode. BMC
recommends that you activate debug mode only when requested by Technical
Support and use the specified level.

396
Control-M Utilities Guide

Parameter Description

-QUIET Suppresses display of utility output.

-FULLDETAI Generates a status report of the communication parameters of each specified

LS agent or remote host. Where an agent is unavailable, the report displays the
reason why the agent is unavailable. Where a remote host is available it
displays the connection information.

ctmping examples
To connect and perform a communication test with the agent jacklin, specify the following command:
ctmping -hostid jacklin
The response is:
Agent: jacklin is alive
To attempt to connect and test communication with agent diana (that is currently down), specify the
following command:
ctmping -hostid diana
The response is:
Agent: diana, Msg: Agent not available.
Add it to the database? y/n:
To connect and test communication with the agent jacklin and collect configuration information needed
for the discovery process, specify the following command:
ctmping -hostid jacklin -discover y
The response is:
Agent: jacklin is alive
To connect and test communication with the agent jacklin and generate a debug trace without displaying
the results on screen, specify the following command:
ctmping -hostid jacklin -debug 1 -quiet
Only the return code of the utility indicates if it was successful. The debug trace information is saved to
the following file:
~<controlm_owner>/ctm_server/proclog/ping<PID>_<PID>.log
PID is the Process Identity number.
The agents, comet and mars, have been configured to connect to remote host dime. To generate a report
showing the result of the test and the connection details, specify the following command:
ctmping -hostid dime -hosttype remote -fulldetails

397
Control-M Utilities Guide

The following response is displayed:

Remote host [dime] is available through Agent [comet]
Connection protocol : SSH
Port number : 22
Encryption method : Blowfish
Compression : No
Remote host [dime] is available through Agent [mars]
Connection protocol : SSH
Port number : 22
Encryption method : Blowfish
Compression : No
Assume the hostid_list.txt text file contains the full path to the following host IDs:
local agent jacklin
remote host dime
regular agent diana
To generate a report showing the result of pinging the host IDs specified in hostid_list.txt, specify the
following command:
ctmping -file ~<controlm_owner>/ctm_server/hostid_list.txt
The response is:
Agent : jacklin is alive
Remote host : dime is alive
Agent: diana Msg: Agent not available

398
Control-M Utilities Guide

ctmshout
The ctmshout utility sends a message to the specified user or destination using the specified severity
level. For information about Shout message destinations, see Shout destination management. For
information about attaching the OUTPUT of a job to Shout messages, see the E-mail configuration
parameters. To run the ctmshout utility, see Running the ctmshout utility (on page 399).
Each parameter name can be shortened to the minimum number of letters required to uniquely identify
the parameter. For example: -ORDERID can be shortened to -O.
Shout messages can be sent to multiple destinations or users in the same command

Running the ctmshout utility

This procedure describes how to run the ctmshout utility, which enables you to send a message to the
specified user or destination using the specified severity level.
 To run the ctmshout utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type one of the following commands:
• ctmshout
-USER <userName> or -DEST <destinationName>
-MESSAGE "<messageText>"
[ -ORDERID <orderID>]
[ -HOSTID <hostID>]
[ -SEVERITY <severityLevel>]
• ctmshout -input_file <fullPathFileName>
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmshout parameters, see ctmshout parameters (on page 400).

399
Control-M Utilities Guide

ctmshout parameters
The following table lists the ctmshout utility parameters:

Parameter Description

<username> User ID that should receive the message. DEST and USER can be
specified in the same ctmshout command.

<destinationName> Logical destination device name or a valid destination name in the

Shout Destination folder. DEST and USER can be specified in the
same ctmshout command.

<message> Free text to be sent to the destination (1 - 255 characters). If the text
is more than one word, it must be enclosed in quotation marks.

<orderID> Order ID of a job, as displayed in the Job Details window in

Control-M/EM. Associates the message with a specific job in the
Active Network.

<hostID> Host ID of the agent computer. Used for messages whose destination
is either a user in the data center or a user defined in the Shout
Destination folder.
NOTE: If -ORDERID is also specified, this Host_ID overrides the Host
ID specified in the job with that Order ID.

<severityLevel> One letter character indicating the urgency of the message. Valid
values:
 R – Regular (Default)
 U – Urgent
 V – Very urgent

<fullPathFileName> Name and full path of a file containing the utility parameters. In this
file, each parameter and its values (if any) are on a separate line with
the same syntax they would have on the command line. The
-input_file parameter enables you to:
 Prepare and save files of utility parameters that can be reused.
 Specify utility input longer than the number of characters allowed
in the command line.
-input_file~<controlm_owner>/ctm_server/data/ctms
hout_parms.txt

400
Control-M Utilities Guide

ctmshout examples
The following are examples of the ctmshout utility commands:
The following command sends the message "File not found" to the Alerts window in Control-M/EM and
associates it with a job whose Order ID is 1234:
ctmshout -ORDERID 1234 -USER EM \
-MESSAGE "File not found" -SEVERITY V
The same result is achieved by using the -input_file parameter as follows:
ctmshout -input_file ~<controlm_owner>/ctm_server/data/ctmshout_payroll.txt
The referenced file contains the following lines:
-ORDERID 1234
-USER EM
-MESSAGE "File not found"
-SEVERITY V
The following command sends the message "The weekly paycheck job has abended" to user John on
agent computer diana:
ctmshout -HOSTID diana -USER John -MESSAGE
"The weekly paycheck job\ has abended" -SEVERITY V
The following illustrates the use of the ctmshout utility in a job script command to send the Shout
message "Job started" to the Alerts window in Control-M/EM.
The job processing definition for a certain job contains the following Variable Assignment parameter:
%%PARM1 = %%ORDERID
The script used to execute the job contains the following command:
ctmshout -O $1 -USER EM -MESSAGE "Job started" \
-SEVERITY R

ctmshtb
The ctmshtb utility specifies the active Shout Destination folder. To run the ctmshtb utility, see Running
the ctmshtb utility (on page 402).
You can add, delete, and modify Shout Destination folders using the ctmsys utility, described in ctmsys
(on page 448) . The ctmsys utility can also be used to specify the active Shout Destination folder
interactively.
The Shout Destination folder associates physical output destinations with logical destination names. The
names are specified in Shout and Do Shout statements in job processing definitions and in the ctmshout
utility. For more information, see Shout destination management.
By defining Control-M jobs that execute this utility at specified times, the active Shout Destination folder
designation can be changed automatically according to the schedule that suits your installation.

401
Control-M Utilities Guide

Running the ctmshtb utility

This procedure describes how to run the ctmshtb utility, which enables you to specify the active Shout
Destination folder.
 To run the ctmshtb utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command to invoke the ctmshtb utility:
ctmshtb <folder>
<folder>:New Shout Destination folder name.
EXAMPLE: The following command sets the current active Shout Destination folder designation to
SHIFTMAN:
ctmshtb SHIFTMAN

ctmspdiag
The ctmspdiag utility is a tool to print or erase diagnostic messages recorded from stored procedures
(SPs) in the Control-M/Server database. ctmspdiag can also set or show the diagnostic request status of
SPs. To run the ctmspdiag utility, see Running the ctmspdiag utility (on page 402).

Running the ctmspdiag utility

This procedure describes how to run the ctmspdiag utility, which enables you to print or erase diagnostic
messages recorded from stored procedures (SPs) in the Control-M/Server database.

 To run the ctmspdiag utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type one of the following commands to invoke the ctmspdiag utility:
• ctmspdiag -SET -SPNAME <storeProcedureName> -MODE <Y/N>
• ctmspdiag -PRINT -SPNAME <storeProcedureName>
• [-FROM_DATE<timeStamp>] [-TO_DATE <timeStamp>]
• ctmspdiag -DEL -TO_DATE <timeStamp>[-SPNAME <storeProcedureName>]
• ctmspdiag -SHOW [-SPNAME <storeProcedureName>]
• ctmspdiag -TRUNCATE
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmspdiag parameters, see ctmspdiag parameters.

402
Control-M Utilities Guide

ctmsuspend
The ctmsuspend utility suspends and restores Control-M/Server communication process for mass uploads
and downloads from Control-M/EM. During suspension mode, Control-M deactivates its job processing
functions by suspending the TR, SL, NS, LG, and WD processes. To run the ctmsuspend utility, see
Running the ctmsuspend utility (on page 403).
This utility should be invoked before executing the Mass Upload or Mass Download features on the
Control-M.

Running the ctmsuspend utility

This procedure describes how to run the ctmsuspend utility, which enables you to suspend and restore
Control-M/Server communication process for mass uploads and downloads from Control-M/EM.
 To run the ctmsuspend utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command to invoke the ctmsuspend utility:
ctmsuspend {-s|-r}
-s: Suspends Control-M/Server communication process, but leaves the gateway to Control-M/EM
open.
-r: Restores Control-M/Server communication process, but resumes normal operating mode.
The following command causes Control-M/Server communication processes to be restored.
ctmsuspend -r

init_prflag
The init_prflag utility resets sleep times and trace levels for Control-M/Server processes. To run the
init_prflag utility, see Running the init_prflag utility (on page 404).
This utility performs the following actions:
 The sleep times for all Control-M/Server processes are reset to their initial (installation) values. See
the table below.
 The trace level for all Control-M/Server processes is reset to zero.
The sleep time setting for Control-M/Server processes can affect the functionality of Control-M/Server and
the performance of your data center. Sleep time is the length of time that a process lies dormant before
"waking up" to check if any request to perform an action was received. When modifying certain
Control-M/Server process sleep time settings, it is important to consider the number of jobs that are
processing, the job schedule plan, and the overall load on the computer.

403
Control-M Utilities Guide

Running the init_prflag utility

This procedure describes how to run the init_prflag utility, which enables you to reset sleep times and
trace levels for Control-M/Server processes.
 To run the init_prflag utility:
1. Shut down Control-M/Server.
2. Type the following command at the command prompt:
init_prflag

404
Control-M Utilities Guide

init_prflag sleep time considerations

The following table lists the sleep time considerations for the init_prflag utility:

Sleep Time
Initial
Process Task Settings Sleep Time Modification Considerations

SU Supervisor 60 Increase: Delay in startup, downloads, and New

Day procedure

RT Inter-process 30 No effect
Communication Router

WD Watchdog 360 No effect

SL Job Selector and job post 5 Increase: Delay in Job Submission and Shout
processing messages for late submission. Can be increased
during period of minimal job processing.
Decrease: Additional CPU resources.

TR Job Tracking 5 Increase: Delay in freeing resources after job

ends and delay in Shout messages. Can be
increased during period of minimal job
processing.
Decrease: Additional CPU resources.

NS Communication with 30 No effect

Control-M/EM

LG Utilities 360 No effect

Agent
invoker

CO Communication agents 60 No effect

CD New Day Procedure; 60 No effect

Database uploads and
downloads

CS N/A No effect

CA N/A No effect

405
Control-M Utilities Guide

shut_ca
The shut_ca utility shuts down the Control-M/Server Configuration Agent. To shut down the
Control-M/Server Configuration Agent, see Shutting down Control-M/Server Configuration Agent using the
shut_ca utility (on page 406).

Shutting down Control-M/Server Configuration Agent using the

shut_ca utility
This procedure describes how to shut down the Control-M/Server Configuration Agent using the shut_ca
utility.
 To shut down Control-M/Server Configuration Agent:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
shut_ca
The following messages are displayed:
---------------------------------------------------
Shutting down Control-M/Server Configuration Agent
---------------------------------------------------
Waiting .....
Control-M/Server Configuration Agent is down

shut_ctm
The shut_ctm utility shuts down Control-M/Server and its processes. To run the shut_ctm utility, see
Shutting down Control-M/Server using the shut_ctm utility (on page 406).

Shutting down Control-M/Server using the shut_ctm utility

This procedure describes how to shut down Control-M/Server and its processes using the shut_ctm utility.

 To shut down Control-M/Server:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:

406
Control-M Utilities Guide

shut_ctm

show_ca
The show_ca utility displays the status of Control-M/Server Configuration Agent. To view the status of the
Control-M/Server Configuration Agent, using the show_ca utility, see Viewing Control-M/Server
Configuration Agent status using the show_ca utility (on page 407).

Viewing Control-M/Server Configuration Agent status using the

show_ca utility
This procedure describes how to view the status of the Control-M/Server Configuration Agent, using the
show_ca utility.
 To view the Control-M/Server Configuration Agent status:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
show_ca

shutdb
The shutdb utility shuts down the SQL database server.
The SQL database server can also be shut down using ctm_menu and then selecting Control-M
Manager menu. For more information about the ctm_menu, see ctm_menu (on page 428).
To shut down the SQL database server, using the shutdb utility, see Shutting down the SQL database
server using the shutdb utility (on page 407).

Shutting down the SQL database server using the shutdb utility
This procedure describes how shut down the SQL database server, using the shutdb utility.

Before you begin

 (Mandatory) The SQL Database Server must be started before Control-M/Server is started and must
be active as long as Control-M/Server is active.
 To shut down the SQL database Server:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account

407
Control-M Utilities Guide

• Windows: Open a command prompt window where Control-M/Server is installed.

2. Type the following command:
shutdb

start_ca
The start_ca utility starts the Control-M/Server Configuration Agent. To run the start_ca utility, see
Starting Control-M/Server Configuration Agent using the start_ca utility (on page 408).

Starting Control-M/Server Configuration Agent using the start_ca

utility
This procedure describes how to start up the Control-M/Server Configuration Agent, using the start_ca
utility.

 To start Control-M/Server Configuration Agent:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
start_ca
A message similar to the following is displayed:
Starting Control-M/Server Configuration Agent at Fri Jun 4 14:31:27 IDT 2016

start_ctm
The start_ctm utility starts Control-M/Server. To start Control-M/Server using the start_ctm utility, see
Starting Control-M/Server using the start_ctm utility (on page 408).

Starting Control-M/Server using the start_ctm utility

This procedure describes how to start the Control-M/Server using the start_ctm utility

 To start Control-M/Server:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
start_ctm

408
Control-M Utilities Guide

startdb
The startdb utility starts the SQL database server. The SQL database can also be started using the
ctm_menu and then selecting Control-M Manager menu. For more information about the ctm_menu,
see ctm_menu (on page 428).
To start the SQL database server using the startdb, Starting the SQL database server using the startdb
utility (on page 409).

Starting the SQL database server using the startdb utility

This procedure describes how to start the SQL database server using the startdb utility.
The SQL database server can also be started using the Control-M/Server menu options.

Before you begin:

 The SQL Database Server must be started before Control-M/Server is started and must be active as
long as Control-M/Server is active. Mandatory.
 To start the SQL database server:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
startdb

ctm_pause
The ctm_pause utility stops Control-M/Server from submitting jobs. To stop Control-M/Server from
submitting jobs using the ctm_pause utility, see Stopping Control-M/Server from submitting jobs using the
ctm_pause utility (on page 409).

Stopping Control-M/Server from submitting jobs using the

ctm_pause utility
This procedure describes how to pause Control-M/Server, which stops Control-M/Server from submitting
jobs using the ctm_pause utility.
EXAMPLE: You might want to pause submitting new jobs when you want to investigate abnormal
behavior in Control-M/Server, without shutting it down, or if you want to start it up after its
upgraded.

 To stop Control-M/Server from submitting jobs:

 From a command line, do one of the following:
• To pause Control-M/Server, type ctm_pause Y.

409
Control-M Utilities Guide

• To resume Control-M/Server job submission, type ctm_pause N.

ctmchangeshdir
The ctmchangeshdir changes the shared directory path that is used for the PostgreSQL replication in a
high availability environment. It is also used for Control M/Server to share information between the two
computers.
To run the ctmchangeshdir utility, see Running the ctmchangeshdir utility (on page 410).

Running the ctmchangeshdir utility

This procedure describes how to change the shared directory path that is used for the PostgreSQL
replication in a high availability environment. It is also used for Control M/Server to share information
between the two computers.
For more information see High availability installation.

 To run the ctmchangeshdir utility:

1. From a command line, type the following:
ctmchangeshdir
The current shared directory path appears.
2. Type the new shared directory path and press Enter.
A test file is written to the new location. If it writes successfully, the new location is saved.
3. Restart the Control-M/Server Configuration Agent (see Starting Control-M/Server Configuration Agent
using the start_ca utility (on page 408)) and restart database replication (see Starting database
replication).

ag_diag_comm
BMC recommends that you verify the ability of the agent computer to communicate with the primary
Server computer and with all other authorized Server host computers.
Control-M/Agent includes a diagnostic program that checks parameters and environmental conditions
relevant to communication between the agent and server computers. This program is typically used at the
request of Technical Support to determine the cause of a communication problem.

Running the ag_diag_comm utility

This procedure describes how to run the ag_diag_comm utility, which enables you to generate a
diagnostic report on the Control-M/Agent communication.

 To run the utility:

1. Navigate to the directory in which Control-M/Agent is installed.
2. Enter the following command:

410
Control-M Utilities Guide

ag_diag_comm
The Control-M/Agent Communication Diagnostic Report is displayed. See check output below.
If the user is not the administrator, the ag_diag_comm command cannot display all the details.

Modifying recovery settings for network disconnections

This procedure describes how to modify recovery settings for network disconnections.

 TO modify recovery settings for network disconnections:

1. In the computer where Control-M/Agent is installed, modify the registry keys (for Windows), or modify
the parameters in the OS.dat file (for UNIX), as needed.
Use the following table for reference. The path to the registry keys is
HKEY_LOCAL_MACHINE\SOFTWARE\BMC Software\Control-M/Agent\WIN, and the path
to the OS.dat file is agentInstallDir/ctm/data.
2. Restart the Control-M/Agent services on Windows, or the processes on UNIX, to make these changes
take effect.

ag_diag_comm output example

The output of the utility is similar to the following:
Control-M/Agent Communication Diagnostic Report
-----------------------------------------------
Agent User Name : ag900
Agent Directory : c:\Program Files\BMC Software\Control-M
Agent\Default
Agent Platform Architecture : Windows-NT 6.2 (Build:9200)
Agent Version : 9.0.00
Agent Host Name : appsrv002
Server Host Name : sunsrv001
Authorized Servers Host Names : sunsrv001
Server-to-Agent Port Number : 7006
Agent-to-Server Port Number : 7005
Server-Agent Protocol Version : 11
Server-Agent Comm. Protocol : TCP
Server-Agent Connection mode : Transient
System Ping to Server Platform : Succeeded
Agent Ping to Control-M/Server : Succeeded
Agent processes status:
======================

411
Control-M Utilities Guide

Agent Listener : Running (42762)

Agent Tracker : Running (51208)
Agent Tracker-Worker : Running (ATW000)

Network disconnections
Control-M/Agent requires an open connection to a remote host from the time of job submission until the
end of the job. If a network disconnection occurs, Control-M/Agent attempts to restore the connection.
During the reconnection attempts, jobs running on the remote host, through the specified
Control-M/Agent, remain in executing status.
If the connection is restored, the status of jobs is updated to reflect their current status, either completed
or still running. If the connection is not restored after the specified number of attempts, the jobs end with
NOTOK status.
The handling of network disconnections to remote hosts is supported when you use remote hosts on
UNIX, Linux, and z/OS USS (using SSH) and when you use remote hosts on Windows (using WMI).
The OUTPUT and exit code for jobs are stored in files on the remote host. The files reside in the user
home directory of the job’s owner, in the directory specified by RJX_OUTPUT_DIR. (For more information
about RJX_OUTPUT_DIR, see the table below.) If network connections were restored, these files are
deleted when the jobs end. If network connections were not restored, you can check these files to see if
the jobs completed successfully or failed.
The following section describes how to use configuration parameters to modify recovery settings when a
network disconnection occurs.

412
Control-M Utilities Guide

Network disconnection parameters and registry keys

The following table lists the ag_diag_comm utility network disconnection parameters and registry keys.

Parameter name (UNIX) or

registry key (Windows) Description

RJX_CONN_TRY number of attempts made to restore the connection

The default is 15

RJX_CONN_TOUT time interval between attempts to restore the connection

The default is 120 seconds

RJX_OUTPUT_DIR directory to store temporary files

These files are automatically removed to Control-M/Agent
when the jobs end and the network connection is
available or restored.
The default is blank. Blank means that the files are stored
in the user home directory of the job’s owner in the
remote host.

RJX_KEEP_OUTPUT to prevent deletion of the OUTPUT file from the remote

host

RJX_COPY_OUTPUT_REMOTE to determine where the OUTPUT handling operations of

copy, move, or delete are performed, either on the Agent
or the remote host

RJX_CONN_RECONNECT whether the network reconnection feature is enabled

The default is Y

RJX_CONN_SFTP protocol used to upload and download files:

When Y is specified, the agent uses SFTP (secured FTP)
protocol to retrieve, upload, and download files.
When N is specified, the agent uses the SSH protocol to
retrieve, upload, and download files.
The default is Y

ag_ping
The ag_ping utility verifies Control-M/Server is active on the Server computer connected to the agent
computer. To run the utility, see Running the ag_ping utility (on page 414).

413
Control-M Utilities Guide

Running the ag_ping utility

This procedure describes how to run the ag_ping utility, which enables you to verify that Control-M/Server
is active on the Server computer connected to the agent computer.

 To run the utility:

 From the Control-M/Agent home directory, specify the following command:
ag_ping
The utility attempts to communicate with Control-M/Server and indicates whether the attempt
succeeded or failed.
If the attempt succeeds, a message similar to the following is displayed:
Output:
Server is alive.
Result: Success.

shagent
(UNIX only) The shagent utility checks that the p_ctmag and p_ctmat processes are running. It can be
invoked only from the Control-M/Agent computer. To run the utility, see Running the shagent utility (on
page 414).

Running the shagent utility

This procedure describes how to run the shagent utility (UNIX only), which enables you to check that the
p_ctmag and p_ctmat processes are running. It can be invoked only from the Control-M/Agent computer.

 To run the utility:

1. From the operating system prompt, specify the following command:
shagent
The shagent utility has no parameters.
If the ctmag advanced utility parameter Persistent Connection is set to Y, the utility verifies that the
p_ctmar process is running.
2. To check that the p_ctmag and p_ctmat processes are running, specify the following command:
shagent
If the Router process is running, output similar to the following is displayed:
root 7660 0:00 p_ctmag
root 7644 0:00 p_ctmar
root 7745 0:29 p_ctmat

414
8
8
Administration and configuration
The administration and configuration utilities perform various administration and configuration tasks. By
including a utility command in the command line of a job processing definition, you can run the utility at a
predetermined time or under a predetermined set of conditions without being present.
The following table describes the utilities used for administration and configuration tasks.

Utility Description

ag_change_passwo Enables you to automate password changes of Application Plug-ins

rd (on page 417) accounts

agkeystore (on Create, apply, and restore keys for job owners credentials using a
page 419) Blowfish algorithm.

ctmagcpk (on page Enables you to change a key's password and apply the new key to job
423) owners credentials for all installed Application Plug-ins (that support
the AES algorithm).

ccmcli (on page Performs basic management operations and deletes old alerts.
424)

ctm_menu (on Interactive menu that provides access to a variety of functions and
page 428) utilities that are used to maintain Control-M/Server.

ctmag (on page Agent Configuration utility that is used to maintain Control-M/Agent
428) configuration parameters, and to view and modify most of the
operating system parameters.

ctmagcfg (on page Interactively configures Control-M/Agents.

429)

ctmagcln (on page Sends requests to all available Control-M/Agents, or to a specified

429) Control-M/Agent, to remove all OUTPUT files and status files that are
no longer needed.

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

page 431)

ctmkeygen (on Generates SSH private and public key pairs.

page 432)

ctmkeystore_mng Creates, modifies, and deletes keys with secure information such as
(on page 438) passwords.

415
Control-M Utilities Guide

Utility Description

ctmldnrs (on page Creates and loads the Manual Conditions file.
442)

ctmlog (on page Performs a selective cleanup of the Control-M log or produces a report
445) of Control-M log entries.

ctmsys (on page Maintains Control-M/Server system parameters and Shout Destination
448) tables.

Running the Enables you to view and modify most of the configuration parameters
ctmunixcfg utility in the OS.dat file.
(on page 456)

ctmwincfg (on page Enables you to view and modify the Application Add-on for Windows
456) configuration parameters.

ecaqrtab (on page Performs operations on quantitative resources in the Resources table.
457)

emmftcli (on page Enables you to search for file transfers in Control-M based on search
461) and filter parameters from a command line.

emcha -restore (on Restores high availability data to the Control-M/EM primary or
page 465) secondary host

erase_audit_data Manually cleans up audit information from the Control-M/EM

(on page 465) database.

purge_runinfo (on Performs manual cleanup of run information that is retained by

page 468) Control-M/Forecast and Control-M Batch Impact Manager for the
purposes of performing its calculations.

purge_xalerts (on Deletes exception alerts from the Exception Alerts table in the
page 467) Control-M/EM database.

set_agent_mode Handles the necessary changes to permissions of several agent files

(on page 471) and directories in order to allow it to run jobs with any owner in
non-root mode or revert back to the original state.

Health Check utility Scans and collects system information about the environment.
(on page 473)

416
Control-M Utilities Guide

ag_change_password
The ag_change_password utility, enables you to automate password changes of Application Plug-ins
accounts. To run the utility, see Running the ag_change_password utility (on page 417).
NOTE: Control-M MFT is not supported.

Running the ag_change_password utility

This procedure describes how to run the ag_change_password utility, which enables you to automate
password changes of Application Plug-ins accounts.

 To run the utility:

1. Open a command prompt window where Control-M/Agent is installed.
2. Type the following command:
ag_change_password -application_type <application_type>
[-account <connection_profile_name>]
[-host <host_name>]
-user <user_name>
-old_password <old_password>
-new_password <new_password>
[-agent <agent_instance_name>]
For more information on the parameters, see ag_change_password parameters (on page 418).

417
Control-M Utilities Guide

ag_change_password parameters
The following table describes the parameters in the ag_change_password utility:

Parameter Description

-application_type The type of Application Add-on installed on this agent. Valid values are:
 CLOUD – Control-M for Cloud
 DATABASE – Control-M/EM database
 ETL_INFA – Control-M for Informatica
 FILE_TRANS – Control-M for Advanced File Transfer
 PS8 – Control-M for PeopleSoft
 SAP (Only from 7.0.00) – Control-M for SAP
 SAP_BO – Control-M for SAP Business Objects
 ORACLE_BI: Control-M for Oracle Business Intelligence
 BACKUP: Control-M for Backup
 DATASTAGE: Control-M for Datastage
 JAVA MSG WS: Control-M for Web Services, Java and Messaging

-account The Application Add-on changes the password in the

connection_profile_name connection profile. Optional.
If no account is specified, all accounts are checked. The * wildcard is
supported. See the note below this table.

-host Match an account where host field is applicable. This parameter is

relevant only when -application FILE_TRANS is specified. Optional.
The * wildcard is supported. See the note below this table.

-user User account name.

The * wildcard is supported. See the note below this table.
When the value for the -application parameter is CLOUD and the
application is Amazon Elastic Compute Cloud (Amazon EC2), then use
Amazon Access Key instead of the user name.

-old_password User password.

-new_password New user password.

-agent (Windows only) Name of the Control-M/Agent. If not specified, the

default agent is used. Optional.

418
Control-M Utilities Guide

Wildcards must be enclosed with single quotations (' ') or with double quotations " " according to the
requirements of the UNIX shell in which the ag_change_password utility is activated.

agkeystore
The agkeystore utility enables you to create, apply, and restore keys to encrypt job owners credentials
using a Blowfish algorithm. To run the agkeystore utility, see Running the agkeystore utility (on page
419).
Changes to the Blowfish encryption key made using the agkeystore utility must also be made in
Control-M/Server using the ctmkeystore_mng utility.

Running the agkeystore utility

This procedure describes how to run the agkeystore utility, which enables you to create, apply, and
restore keys to encrypt job owners credentials using a Blowfish alogorithm.

 To run the utility:

 Do one of the following:
• To run the utility interactively, type the following command:
agkeystore
The following menu is displayed:
Select agent from the list:
1) Default
2) agent-host1
3) agent-host4
q) Quit
Please enter your choice:
The options in this menu and in all other menus provided by this utility are selected by typing
the option number or command letter and pressing <Enter>.
Assuming that the default agent is chosen, the following menu is displayed:
Control-M/Agent Key Store Management Utility
Agent Name: default
1) Add new key
2) Apply new key
3) Restore default key
q) Quit
Enter your choice:
• To run the utility silently, type the following command depending on your operating system:

419
Control-M Utilities Guide

o For UNIX: Specify the following command:

agkeystore -key <key type> -action <action_name> -input
<input_file_full_path> [-replace <Y/N>]
[-key key type <BLOWFISH>]
[-action <add> <apply> <restore>]
[-input full path of input file containing new blowfish key]
[-replace replace existing new blowfish key if exists <Y|N>]
o For Windows: Specify the following command:
agkeystore -agent <agent_name> -key <key type> -action <action_name>
-input <input_file_full_path> [-replace <Y/N>]
[-key key type <BLOWFISH>]
[-action <add> <apply> <restore>]
[-input full path of input file containing new blowfish key]
[-replace replace existing new blowfish key if exists <Y|N>]
For agkeystore options and actions, see agkeystore options (on page 421) and agkeystore actions (on
page 422).

420
Control-M Utilities Guide

agkeystore options
The following table describes the options in the agkeystore utility:

Option Description

Add new key Creates a new Blowfish encryption key in the agkeystore.kdb file.
After selecting the Add new key option, you are prompted to enter an
input file name to the file that contains the key. Ensure that you specify the
full path to this file.
If a new Blowfish key was added earlier but was not yet applied by
completing the Apply new key procedure, you are prompted to either
overwrite the earlier Blowfish key with a newer Blowfish key or leave the
Blowfish key that was created earlier intact and not create a subsequent
newer Blowfish key.
When Control-M/Agent is running on Windows computers and configured
with LOGON_AS_USER logon option, a new PASSWRDS file containing all
the job owners and their passwords encrypted with the new key is created.
The original PASSWRDS file is not changed.
After adding a new key, only use ctmpwd to create and modify
Control-M/Agent users and passwords when you have completed the Apply
new key procedure.

Apply new The new key replaces the existing Blowfish encryption key in the
key agkeystore.kdb file used by Control-M/Agent and the PASSWRDS file is
replaced with the new PASSWRDS file that is created in the Add new key
option when Control-M/Agent is running on Windows computers and
configured with LOGON_AS_USER logon option.
Immediately after applying the new key, restart Control-M/Agent for the
new Blowfish encryption key to be used.

Restore Replaces the existing Blowfish encryption key entry in the agkeystore.kdb
default key file with the default Blowfish encryption key that is used by Control-M.
When Control-M/Agent is running on Windows computers and configured
with LOGON_AS_USER logon option, the PASSWRDS file is saved with the
job owners and their passwords encrypted with the default key.
Immediately after restoring the default key, restart Control-M/Agent for the
new Blowfish encryption key to be used.

421
Control-M Utilities Guide

agkeystore actions
The following table describes the actions in the agkeystore utility:

Action Description

-agent (Windows only) Specify the name of the agent whose Blowfish encryption of
job owners credentials are being modified.

-key Specify the type of encryption key. Enter the value BLOWFISH

-action Specify the action that the utility must take on the agkeystore.kdb file. The
valid values are:
add – creates a new Blowfish encryption key in the agkeystore.kdb file
If a new Blowfish key was added earlier but was not yet applied by completing
the Apply new key procedure, you can either overwrite the earlier Blowfish
key with a newer key or leave the Blowfish key that was created earlier intact
and not create a subsequent newer Blowfish key.
apply – the updated Blowfish encryption key replaces the existing Blowfish
encryption key in the agkeystore.kdb file
The Control-M/Agent must be restarted for this action to take effect.
restore – replaces the existing Blowfish encryption key in the agkeystore.kdb
file with the Blowfish encryption key that is used by Control-M
The Control-M/Agent must be restarted for this action to take effect.

-input Specify the full path to the file that contains the Blowfish encryption key.
The maximum length of the key is 32 characters (256 bits) long.

-replace Replace a new Blowfish encryption key that was created but that has not yet
been applied by completing the Apply new key procedure.
-replace is relevant only when -action add is specified and another Blowfish
encryption key was added but has not yet been applied. In this case use
-replace to overwrite the existing Blowfish encryption key entry with the new
Blowfish key. The valid values are:
 Y – replace existing new Blowfish encryption key if it exists
 N – do not replace the Blowfish encryption key

422
Control-M Utilities Guide

ctmagcpk
The ctmagcpk utility enables you to change a key's password and apply the new key to job owners
credentials for all installed Application Plug-ins (that support the AES algorithm). When this utility runs for
the first time, it migrates the credentials from BlowFish to a new AES-256 key. In case of failure, the
utility can be used to restore previous credentials and key. To run the ctmagcpk utility, see Running the
ctmagcpk utility (on page 423).
NOTE: When uninstalling Control-M/Agent version 9.0.00 fix pack 3, the utility enables you revert to
BlowFish.

Running the ctmagcpk utility

This procedure describes how to run the ctmagcpk utility, which enables you to change the password key
for Application Plug-ins accounts.
This utility cannot be executed while Control-M/Agent is running.

 To run the utility:

1. Open a command prompt window where Control-M/Agent is installed.
2. Type the following command:
ctmagcpk [-f]_|[-r]|[-b]
For information about ctmagcpk options, see ctmagcpk options (on page 423).
NOTE: The utility cannot be used to encrypt/decrypt Blowfish passwords (or using -f option) when
FIPS state is ON.

ctmagcpk options
The following table describes the options for the ctmagcpk utility:

Options Description

-f Forces FIPS compliant algorithms for key and password

generation.

-r Enables a roll back and restore action.

-b Reverts to Blowfish in case of uninstall.

423
Control-M Utilities Guide

ccmcli
The ccmcli utility enables you to interactively perform basic administrative tasks on Control-M components
on the Control-M/EM, Control-M/Server and Control-M/Agent, including the following tasks:
 Starting
 Stopping
 Ignoring
 Recycling
 Viewing details about the component or server
 Removing old alerts
 Deleting history of job or group definitions
 Deleting Control-M/Agent or remote host component
To run the ccmcli utility, see Running the ccmcli utility (on page 424).

Running the ccmcli utility

This procedure describes how to run the ccmcli utility, which enables you to perform basic administrative
tasks on Control-M components.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<EM Home>\Default\bin directory.
2. Type the following command:
• ccmcli [-u <user> [-p <password>] | -pf <password file>][-s
<Configuration Server Name>] [-t <component Type>]
[-n <component name>] [-h <component host>] [-cmd <command>]|[-date
<YYYYMMDD>] | [-keep_days <number>] | [-force Y|N] | [-node_id <Node ID>]
| [-ctlcmd <command>] ]
For the Control-M parameter name, see Parameter name cross references (on page 31). For the
ccmcli parameters, see ccmcli parameters (on page 425).

424
Control-M Utilities Guide

ccmcli parameters
The following table lists the ccmcli utility parameters:

Parameter Description

-u Control-M/EM database user name

-p Control-M/EM database user password

-pf Flat file containing an unencrypted username and password on separate lines
in the format:
user=username
password=password

-s The name of the Control-M Configuration Server. It is mandatory to specify

this parameter.

-t The type of component. Valid values are:

 Gateway
 GUI_Server
 GCS
 BIM
 Forecast_Server
 Self_Service_Server
 Web_Server
 CTM_Server
 CTM_Agent

-n The logical name of the component.

-h The host on which the component is running.

425
Control-M Utilities Guide

Parameter Description

-cmd The command you want to run on the agent configuration server or
component. Valid values are:
 start
 stop
 ignore
 recycle
 details
 remove_old_alerts
 erase_jobs_history
 delete_agent
 delete_remote_host
 deploy
If the component type is -t CTM_Agent, only -cmd recycle is supported.
When you specify the -force flag, and the recycle command for a
Control-M/Agent, you can force recycling of a Control-M/Agent, even if jobs
are running on it or on a remote host computer.
You must specify the -date flag, when you specify the remove_old_alerts
command.
You must specify the -node_id flag, when you specify the delete_agent and
delete_remote_host commands.
You must specify the Control-M/Server where the Control-M/Agent and
Remote Host are defined, when you specify the command type, name , and
host for the delete_agent and delete_remote_host commands.
You must specify the -keep_days flag, when you specify the
erase_jobs_history command. All jobs above the specified number are
deleted.
Deploy: The following flags must be specified:
 -action <install|transfer|transfer_and_install>
 -agent
 -ctm_server
 -package
NOTE: If the action is install, you must specify -activity_id. If the action is
transfer or transfer and install, you must specify-activity_name.

426
Control-M Utilities Guide

Parameter Description

-date The date from which alerts must be kept. Alerts older than the specified date
are removed. Enter the date in the format YYYYMMDD. Use this parameter
when specifying -cmd remove_old_alerts. All alerts received up to and
including the specified date are deleted.

-keep_days The number of days to keep job or group definition history. Use this
parameter when specifying -cmd erase_jobs_history. All versions older
than the specified number of days will be deleted.

-force The command to force the component to recycle. Valid values are:
 Y
 N
When -cmd recycle is specified for an agent (-t CTM_Agent), you can
specify the -force to force Control-M/Agent to recycle even if jobs are
running on the agent or remote host computer through the agent.

-node_id The name of a Control-M/Agent computer, remote host computer, or host

group where the job is submitted.

-ctlcmd A control shell command sent to one of the Control-M/EM components.

ccmcli example
Use the following command to perform the administrative task of starting Control-M/Server on the alpine
host computer from the command prompt.
ccmcli -pf dailyuser -s alpha -t CTM_Server -n alpha_server -h alpine -cmd start
The following command keeps the last 15 days of job definition history for user user014 and deletes the
older versions of the job definition history. The output of the utility shows the number of versions before
and after the deletion. However, jobs can be running while the utility is executing so the difference
between them is not necessarily the number of versions that were deleted.
ccmcli -u user014 -p pass104 -cmd erase_jobs_history -keep_days 15 -s server04
Utility output:
Number of old versions before deletion: 8512.
Number of old versions after deletion: 3478.

427
Control-M Utilities Guide

ctm_menu
ctm_menu (Control-M Main Menu) is a utility that invokes an interactive menu that provides access to a
variety of functions and utilities that are used to maintain Control-M/Server. To run the ctm_menu utility,
see Running the ctm_menu utility (on page 428).
 Control-M Manager: Enables you to check, start and stop Control-M/Server, Control-M/Server
database, and Control-M/Server Configuration Agent.
 Database Menu: Facilitates day-to-day maintenance and diagnostics of Control-M/Server database.
You can also access the Database Menu directly, as described in dbu_menu (on page 563).
 Security Authorization: Enables you to adds delete users/groups and backup and restore security
definition tables in the Control-M Security database.
 Parameter Customization: Enables you to view and edit communication parameters.
 Host Group: List, edit and delete host groups. For more information, see ctmhostgrp (on page 392)
 View HostID details: Enables you to view HostID details
 Agent Status: View and edit Control-M/Agent details
 Troubleshooting: Enables you to set diagnostics and various restart procedures.

Running the ctm_menu utility

This procedure describes how to run the ctm_menu utility, which invokes an interactive menu that
provides access to a variety of functions and utilities that are used to maintain Control-M/Server.
 To run the ctm_menu utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctm_menu
For the Control-M parameter name, see Parameter name cross references (on page 31).

ctmag
The Agent Configuration (ctmag) utility is a Java application used to maintain Control-M/Agent
configuration parameters, and to view and modify most of the operating system parameters. If the user
running the utility is not an administrator, changes made to agent configuration parameters will not be
saved. Running the ctmag utility interactively is described in Control-M/Agent parameters. To run the
ctmag utility, see Running the ctmag utility (on page 429).

428
Control-M Utilities Guide

Running the ctmag utility

This procedure describes how to run the ctmag utility, which enables you to maintain Control-M/Agent
configuration parameters, and to view and modify most of the operating system parameters.
 To run the utility:
 Open a command prompt window where Control-M/Agent is installed and type one of the following
commands:
• ctmag
• ctmag <agentName> (if more than one Control-M/Agent is installed)

ctmagcfg
The ctmagcfg interactively configures Control-M/Agents. This utility can also be accessed as a Java
application. For more information, see Control-M/Agent parameters.
To run the ctmagcfg utility, see Running the ctmagcfg utility (on page 429).

Running the ctmagcfg utility

This procedure describes how to run the ctmagcfg utility, which enables you to interactively configure
Control-M/Agents.

 To run the utility:

 Open a command prompt window where Control-M/Agent is installed and type the following
command:
ctmagcfg

ctmagcln
The ctmagcln utility sends a request to all available Control-M/Agents, or to a specified Control-M/Agent,
to remove all output files and exit status files that are no longer needed. This utility should run while
Control-M/Server is up and running. The files that are no longer needed are determined according to the
Maximum Days to Retain Output Files parameter. For more information, see the description of the Output
parameters parameter. To run the ctmagcln utility, see Running the ctmagcln utility (on page 430).
The New Day procedure can request that Agents remove OUTPUT files and exit status files that are no
longer needed. In an environment with multiple Agents, it can take a long time to send the cleanup
request to the Agents during New Day. BMC recommends that you use the
AGENTS_CLEANUP_IN_NEWDAY configuration parameter to disable this action during the New Day
procedure, and instead use the ctmagcln utility. For more information, see the description of the
Configuration parameters configuration parameter.
The ctmagcln utility can be run as a daily job. A message is added to the IOALOG when the cleanup of
the Agents has ended.

429
Control-M Utilities Guide

Running the ctmagcln utility

This procedure describes how to run the ctmagcln utility, which ends a request to all available
Control-M/Agents, or to a specified Control-M/Agent, to remove all OUTPUT files and exit status files that
are no longer needed

 To run the utility:

1. Log in to the Control-M/Server computer as the Control-M/Server owner.
2. Enter the following command:
ctmagcln -agent <"*" | agentName> [-days <outputRetainDays>]
For more details about the ctmagcln utility, see ctmagcln utility parameters (on page 430) and ctmagcln
utility example (on page 430).

ctmagcln utility parameters

The following table describes the parameters of this command:

Parameter Description

* Specifies that all Agents remove OUTPUT files and exit status files that
are no longer needed.

agentName Specifies that the specified agent must remove OUTPUT files and exit
status files that are no longer needed.

outputRetainDays Specifies the number of days that OUTPUT files must be retained before
being removed. Default: 1

NOTE: BMC recommends running ctmagcln as soon as possible after the New Day procedure is complete.

ctmagcln utility example

The following are examples of the ctmagcln utility commands:
The following command requests that all Agents remove OUTPUT files and exit status files that are no
longer needed.
ctmagcln -agent "*"
The following command requests that the specified agent, saturn, removes OUTPUT files that have
already been retained for two days, and removes all exit status files that are no longer needed.
ctmagcln -agent saturn -days 2

430
Control-M Utilities Guide

ctmdiskspace
The ctmdiskspace utility checks the amount of free disk space on a device and displays the result. The
utility returns a "failed" status if the current free space is below the specified limit.
The ctmdiskspace utility can be included in the Control-M Watchdog process. For more information, see
Watchdog process parameters. To run the ctmdiskspace utility, see Running the ctmdiskspace utility (on
page 431).

Running the ctmdiskspace utility

This procedure describes how to run the ctmdiskspace utility, which checks the amount of free disk space
on a device and displays the result.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctmdiskspace -limit <amount>{%|K|M} -path <pathName> [-quiet]
For more details about the ctmdiskspace utility, see ctmdiskspace parameters (on page 431) and
ctmdiskspace utility example (on page 432).

ctmdiskspace parameters
The following table describes the parameters of this command:

Parameter Description

amount Specifies the minimum amount (%, K, or M) of free space on the device
as a whole number (integer).
For example: -limit 25%

path_name Specifies the full path name of the device. Multiple devices can be
specified on the command line (see the second example below).

-quiet Suppresses informational messages from being displayed during the

execution of the command.

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

431
Control-M Utilities Guide

ctmdiskspace utility example

The following are ctmdiskspace utility examples:
The following command returns a "failed" status if the amount of free disk space in the Control-M user
directory is below 25%:
ctmdiskspace -limit 25% -path /ctm_server/ctmuser
The following command returns a "failed" status if the amount of free disk in the Control-M user directory
is below 20M:
ctmdiskspace -limit 20M -path /ctm_server/ctmuser -path /ctm/tmp

ctmkeygen
The ctmkeygen utility generates SSH private and public key pairs. To run the ctmkeygen utility, see
Running the ctmkeygen utility (on page 432).
When creating or modifying the job owner definition, you can choose to use either public or private key
authentication instead of password authentication. For more information about using the Control-M
Configuration Manager, see Introduction to Control-M Configuration Manager.
The ctmkeygen utility manages the key table that contains the logical key name as the unique table key,
the private key, and the key passphrase (encrypted). The generated public key (unencrypted) is stored in
a file.

Running the ctmkeygen utility

This procedure describes how to run the ctmkeygen utility, which generate SSH private and public key
pairs. The ctmkeygen utility can be run either in interactive mode or batch invocation.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type one of the following commands:
• Interactive mode:
ctmkeygen
The Control-M Key Generator Utility menu is displayed. The options in this menu and in all other
menus provided by this utility can be selected by typing the option number or command letter
and pressing <Enter>.
• Batch mode: Specify one of the following commands:
o ctmkeygen -action add -name <logicalKeyName> -passphrase
<keyPassphrase> -type rsa|dsa -bits 512|768|1024|2048|3076 -format
openssh|ssh2 -path <publicKeyPath>

432
Control-M Utilities Guide

o ctmkeygen -action update -name <logicalKeyName> -passphrase

<keyPassphrase> [-type rsa|dsa] [-bits 512|768|1024|2048|3076]
[-format openssh|ssh2] -path <publicKeyPath>
o ctmkeygen -action delete -name <logicalKeyName> -passphrase
<keyPassphrase>
o ctmkeygen -action list
o ctmkeygen -action export -filename <exportFileName>
o ctmkeygen -action import -filename <importFileName> -data
append|truncate
o ctmkeygen help
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmkeygen utility see ctmkeygen utility actions (on page 434), ctmkeygen utility parameters (on
page 435) and Copying public keys to the SSH server (on page 436).

433
Control-M Utilities Guide

ctmkeygen utility actions

The following table describes the actions in the ctmkeygen utility:

Action Description

add Creates a new entry in the key table. It also verifies that a key with the same
name does not exist. All the parameters are mandatory.

update Modifies the details of an existing entry in the key table. The entry includes the
same fields as used to create a new key pair. The updated entry replaces the
existing entry in the key table in the database and the public key file. The
passphrase must match the one that was used to create the existing key.
For the optional parameters, if a value not specified, the value stored in the
Control-M/Server database is used.

delete Deletes the entry associated with the logical key name. The passphrase must
match the one that was used to create the existing key.

list Returns a list of lines, each containing: the logical key name, type, bits, and
format.

export Exports the details of the keys stored in the key table to a text file.
ctmkeygen -action export -filename
$HOME/ctm_server/data/key_details.txt

import Imports the details of the keys stored in the key table. Using the import
parameter enables you to:
prepare and save files of keys that can be reused
specify utility input longer than the number of characters allowed in the
command line
ctmkeygen -action import -filename
$HOME/ctm_server/data/key_details.txt

help Displays the usage of the ctmkeygen utility.

434
Control-M Utilities Guide

ctmkeygen utility parameters

The following table describes the parameters in the ctmkeygen utility:

Parameter Description

-name Logical name of the key that is used as a unique identifier. It also determines
the name of the public key file. The name is comprised of letters, numbers,
and underscores.

-passphrase Phrase used as a key to encrypt the key itself.

-type Specifies the standard used for the key. Mandatory when used with add,
optional when used with update. Valid values are:
 RSA
 DSA

-bits Specifies the strength of the encryption key in bits. Mandatory when used
with add, optional when used with update. Valid values are:
 512
 768
 1024
 2048
 3076
The minimum value of the bits must be at least equal to the minimum value
of bits specified for the SSH server.

-format Specifies the public key file format. It must match the format used by the
SSH server. Mandatory when used with add, optional when used with
update. Valid values are:
 openssh – for OpenSSH servers
 ssh2 – for ssh2 servers

-path Specifies the location where the public key file is created.

-filename Specifies the public key name. The format of the file depends on what is
specified for the –format parameter, described above.

-data Describes what action to take with the imported data from the text file.
Specify one of the following:

append the details of the SSH keys from the imported text file are added
to the existing SSH keys

435
Control-M Utilities Guide

Parameter Description

truncate the details of the SSH keys from the imported text file replace
the existing SSH keys

Copying public keys to the SSH server

This procedure describes how to copy public keys to the SSH server. The public key must be copied to the
SSH server. If such a file already exists on the SSH server, you must choose to either append or truncate
the new file to the existing one.

 To copy public keys to the SSH server:

 Copy the public key to the SSH server according to the SSH server requirements:
• For OpenSSH on UNIX, the public keys file is:
<jobOwnerHomeDirectory>/.ssh/authorized_keys
• For SSH Tectia on UNIX, the public keys file is:
<jobOwnerHomeDirectory>/.ssh2/authorization
• For SSH Tectia on WINDOWS, the public keys file is:
<jobOwnerHomeDirectory>\.ssh2\authorization

Copy public keys to SSH server example

Create an entry in the key table with the following specifications:

Parameter Value

key name key1

passphrase myphrase

type dsa

bits 512

format ssh2

path /home/ctm900

Specify the following command:

ctmkeygen -action add -name key1 -passphrase myphrase -type dsa -bits 512
-format ssh2 -path /home/ctm900
The following message is displayed:

436
Control-M Utilities Guide

Creating SSH key. Please wait...

SSH key created successfully.
Assume that modifications are required to the key created in Example 1. To change the type to rsa, the
number of bits to 1024 and the format to openssh, specify the following command:
ctmkeygen -action update -name key1 -passphrase myphrase -type rsa -bits 1024
-format openssh -path /home/ctm900
The following message is displayed:
Updating SSH key. Please wait...
SSH key update ended successfully.
To delete the key entry created in Example 1, specify the following command:
ctmkeygen -action delete -name key1 -passphrase myphrase
The following message is displayed:
Entry deleted successfully.
To display a list of SSH keys in the key table, specify the following command:
ctmkeygen -action list
The following is displayed:
Name Type Bits Format
---- ---- ---- ------
first RSA 512 OPENSSH
mykey RSA 1024 OPENSSH
2 keys were found.
To create an export text file containing the details of the SSH keys, specify the following command:
ctmkeygen -action export -filename /home/ctm900/my.exp
The following is displayed:
Exporting data, please wait...
Export ended successfully.
Check report file
~<controlm_owner>/ctm_server/proclog/export_report_5020.txt’ for details.
To import the my.exp text file, which contains the details of the SSH keys that replaces the current
information, specify the following command:
ctmkeygen -action import -filename /home/ctm900oe/my.exp -data truncate
The following message is displayed:
Importing data, please wait...
Import ended successfully.
Check report file
~<controlm_owner>/ctm_server/proclog/import_report_535a.txt’ for details.

437
Control-M Utilities Guide

ctmkeystore_mng
The ctmkeystore_mng utility enables you to do the following actions:
 For Remedy – create, modify, and delete user names and passwords.
 For Blowfish – add, apply, and restore encrypted keys for user authorizations (job owners
credentials).
To work with Do Remedy, first activate this utility.
To run the ctmkeystpre_mng utility, see Running the ctmkeystore_mng utility (on page 438).
The options in this menu and in all other menus provided by this utility can be selected by typing the
option number or command letter and pressing <Enter>.

Running the ctmkeystore_mng utility

This procedure describes how to run the ctmkeystore_mng utility, which enables you to do various actions
in Remedy and Blowfish.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctmkeystore_mng
The following menu is displayed:
+------------------------------------------------------+
| Control-M/Server Keystore Management Utility |
| Main Menu |
+------------------------------------------------------+
1) REMEDY Keystore
2) BLOWFISH Keystore
q) Quit
Enter option:

REMEDY Keystore
Specify the ctmkeystore_mng utility to create, modify, and delete Remedy user names and passwords.
To access the Remedy Keystore menu, see Running the REMEDY Keystore menu (on page 439). To
create, delete or modify the user and passwords, see the following:

438
Control-M Utilities Guide

 Creating a REMEDY user and password (on page 439)

 Deleting a Remedy user (on page 440)
 Modifying the password of a REMEDY user (on page 440)

Running the REMEDY Keystore menu

This procedure describes how to access the REMEDY Keystore menu.

 To run the REMEDY Keystore menu:

1. Follow the steps referred to in Running the ctmkeystore_mng utility (on page 438).
2. Select option 1 from the Control-M/Server Keystore Management Utility Main Menu.
The following menu is displayed:
+--------------------------------------+
REMEDY Keystore Menu
+--------------------------------------+
1) Add User
2) Delete User
3) Update User password
q) Quit
Enter option:
For more information on the REMEDY Keystore utility, see REMEDY Keystore Menu parameters (on page
439).

REMEDY Keystore Menu parameters

The following table lists the REMEDY keystore Menu parameters"

Parameter Description

user Specifies a user name. Specify an alphanumeric value from 1 through 127
characters long.

password Specifies the password for the user defined above.

Creating a REMEDY user and password

This procedure describes how to create a REMEDY user and password.

 To ceate a REMEDY user and password:

1. Follow the steps referred to in Running the ctmkeystore_mng utility (on page 438).

439
Control-M Utilities Guide

2. Select Option 1 from the REMEDY Keystore Menu.

You are prompted to specify a username and password.
After confirming the password, a message is displayed stating that the user name was successfully
added.
3. Press Enter to continue.
The REMEDY Keystore Menu is again displayed.

Deleting a Remedy user

This procedure describes how to to delete a REMEDY user.

 To delete a Remedy user:

1. Follow the steps referred to in Running the ctmkeystore_mng utility (on page 438).
2. Select Option 2 from the REMEDY Keystore Menu.
You are prompted to specify a username.
3. Press Enter to continue.
A message is displayed stating that the user name was successfully deleted.
4. Press Enter to continue.
The REMEDY Keystore Menu is again displayed.

Modifying the password of a REMEDY user

This procedure describes how to modify the password of a REMEDY user.

 To modify the password of a REMEDY user:

1. Follow the steps referred to in Running the ctmkeystore_mng utility (on page 438).
2. Select Option 3 from the REMEDY Keystore Menu.
You are prompted to specify a username.
3. Press Enter to continue.
You are prompted to enter new password and then confirm it.
4. Press Enter to continue.
The REMEDY Keystore Menu is again displayed

BLOWFISH Keystore
Specify the ctmkeystore_mng utility to add, apply, and restore encrypted keys for user authorizations (job
owners credentials). For information about changes to the Blowfish key in Control-M/Agent, see
agkeystore (on page 419). To access the BLOWFISH keystore menu, see Running the BLOWFISH
Keystore Menu (on page 441).

440
Control-M Utilities Guide

Running the BLOWFISH Keystore Menu

This procedure describes how to access the BLOWFISH Keystore menu.

 To run the BLOWFISH Keystore Menu:

1. Follow the steps in Running the ctmkeystore_mng utility (on page 438)
2. Select option 2 from the Control-M/Server Keystore Management Utility Main Menu.
The following menu is displayed:
+--------------------------------------+
BLOWFISH Keystore Menu
+--------------------------------------+
1) Add new key
2) Apply new key
3) Restore default key
q) Quit
Enter option:
For more detail on the BLOWFISH Keystore utility, see BLOWFISH Keystore Menu parameters (on
page 441).

BLOWFISH Keystore Menu parameters

The following table describes the BLOWFISH Keystore Menu parameters:

Parameter Description

Add new key Changes the encryption key

The new key is read from a file and stored. After the key has been stored,
all encrypted stored data is decrypted with the old key and then
re-encrypted with the new key in a new location, leaving the old data
untouched.

Apply new key Replaces the old data with the re-encrypted data
This option requires Control-M/Server to be down to replace the old
passwords with the new encrypted passwords.
NOTE: New users that were added after the Add new key procedure but
before the Apply new key procedure was carried out, must be
re-encrypted with new Blowfish key.

Restore default Re-encrypts all data with a default key

key
This option requires Control-M/Server to be down to replace the new
passwords with the old passwords.

441
Control-M Utilities Guide

ctmldnrs
The ctmldnrs utility creates and loads the Manual Conditions file. This file contains prerequisite conditions
that are required by jobs in the Active Jobs database but will not be added to the Conditions/Resources
table without manual intervention. These conditions fall into two categories:
 Conditions that are never added automatically by scheduled jobs because manual confirmation is
always desired.
 Conditions that are normally added automatically by scheduled jobs but the jobs that add them are
not scheduled for the day.
Prerequisite conditions in the Manual Conditions file can be made available to the system using the load
option of ctmldnrs (see below), using the ctmcontb utility (see ctmcontb (on page 339)), using the Job
prerequisites window, or using the WHY option in the job menu. To run the ctmldnrs, see Running the
ctmldnrs utility (on page 442).
The ctmldnrs utility identifies conditions that should be in the Manual Conditions file by searching for all
prerequisite conditions required for submission of jobs on the particular day. The search for prerequisite
conditions is performed by checking the In Conditions parameters of the job processing definitions for all
jobs in the Active Jobs database. Then, the utility eliminates any "non-manual" conditions that satisfy
either of the following criteria:
 The prerequisite condition already exists in the Conditions/Resources table.
 The prerequisite condition is added to the Conditions/Resources table by an Out Conditions or
DO COND job processing parameter in a job scheduled to run that day.
Prerequisite conditions that do not meet the above criteria are assumed to be manual conditions and are
placed in the Manual Conditions file. To load and create manual conditions file, see Loading prerequisite
conditions from manual conditions file (on page 469) and Creating the manual conditions file (on page
469).

Running the ctmldnrs utility

This procedure describes how to run the ctmldnrs utility, which creates and loads the Manual Conditions
file.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type one of the following commands:
• ctmldnrs -LIST <condition-mask> [-INPUT <filename>]
• ctmldnrs -LOAD <condition-mask> [-INPUT <filename>]
• ctmldnrs -CALCCOND [-ADDMODE {YES | NO} ]
[-OUTPUT <filename> ]
[-IGNOREIN <condition-mask>]

442
Control-M Utilities Guide

[-IGNOREOUT <condition-mask>]
[-IGNORECODES <condition-mask>]
[-INCLUDE_FUTURE_ODATES ]
For more information on the ctmldnrs utility, see ctmldnrs utility options (on page 443) and ctmldnrs
utility parameters (on page 444).

ctmldnrs utility options

The following options are available for using this utility:

Parameter Description

-LIST List prerequisite conditions from the Manual Conditions file

-LOAD Load prerequisite conditions from the Manual Conditions file to the
Conditions/Resources table

-CALCCOND Create the Manual Conditions file

By specifying ctmldnrs -CALCCOND with the -INCLUDE_FUTURE_ODATES parameter the ctmldnrs

utility can process jobs in Wait ODATE (WAIT_ODAT) status and add the appropriate conditions, with the
appropriate odate, as if the jobs were in Wait Condition status.
The following special characters are disabled when they occur in prerequisite condition names:
 ( open parenthesis
 ) close parenthesis
 | vertical bar
 space

443
Control-M Utilities Guide

ctmldnrs utility parameters

The following table describes the ctmldnrs utility parameters:

Parameter Description

INPUT Name and full path of a file containing parameters for the utility.
In this file, each parameter and its values (if any) are on a separate
line with the same syntax they would have on the command line.
Using the -input_file parameter enables you to do the following:
 prepare and save files of utility parameters that can be reused
 specify utility input longer than the number of characters
allowed in the command line

ADDMODE YES – When the new Manual Conditions file is created, conditions
from the previous file are retained in the new file.
NO – The Manual Conditions file is recreated and all previous
conditions are deleted. Default.

OUTPUT Output file to be created. If this parameter is not specified, the

default file is <controlmUserDir>/ctmldnrs.dat.

<Filename> Full path name of the output file to be created.

IGNOREIN All conditions that satisfy the specified condition name are ignored
when the file is created.

IGNOREOUT References to conditions that satisfy a condition name that is

specified in OUT COND job processing parameters are ignored by
the algorithm that builds the file.

IGNORECODES References to conditions that satisfy a condition name that is

specified in DO COND job processing parameters are ignored by the
algorithm that builds the file.

<condition-mask> Name of the prerequisite condition.

The condition name can include the wildcard character * to
represent any number of characters (including no characters). In
this instance, the condition name must be enclosed in quotation
marks (for example, "LVL *"). Specify "*" by itself to include all
existing conditions.
When using both open and closed square brackets ([ and ]), the
condition name must be enclosed in quotation marks (for example,
"RATE[A1]").

444
Control-M Utilities Guide

Parameter Description

-INCLUDE_FUTURE_ Specifies the action to be taken with jobs that are in Wait ODATE state
ODATES When this parameter is specified, jobs in Wait ODATE state are included in
the utility processing.
When this parameter is not specified, jobs in Wait ODATE state are
excluded from the processing of the ctmldnrs utility (default).
Conditions added by ctmldnrs with a date reference (month and day) that is
later than the current Control-M/Server date (ODATE) are deleted by the
Control-M/Server New Day processing a day before that date arrives. If this
action is not the intended action, set New Day processing to not perform old
conditions cleanup. You can manually delete the old conditions a few days
after they are no longer required.
EXAMPLE: Set the Ignore New Day Conditions parameter to Y by using the
ctmsys utility.
Specify * in the
<Control-MServerHomeDir>/ctm_server/data/dbs_ignrcond.
dat
file (all the conditions are ignored).

ctmlog
The ctmlog utility creates a report from entries in the Control-M log or deletes entries in the Control-M
log. To run the ctmlog utility, see Running the ctmlog utility (on page 445).

Running the ctmlog utility

This procedure describes how to run the ctmlog utility, which creates a report from entries in the
Control-M log or deletes entries in the Control-M log.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type one of the following commands:
• ctmlog <action> <actionOption> \
<fromDate> <fromTime> <toDate> <toTime> \
[<output> [<reportWidth>] ]
• ctmlog <action> <actionOption> "*" \
[<output> [<reportWidth>] ]
For valid values for <action> and <actionOption> see ctmlog utility actions (on page 446). All other
parameters of this utility, see ctmlog utility parameters (on page 447).

445
Control-M Utilities Guide

ctmlog utility actions

The following table lists all actions are limited to log entries in the range specified using the time and date
parameters:

Action Action option

listss Prints a report for a specific <subsystem> Subsystem to include in the report.
subsystem. Specify one of the following:
 SU Supervisor
 TR Tracker
 SL Selector
 CD Download, Database update
 NS Communication with agent
computers
 LG Agent utilities
 UT Utilities
 WD Watchdog

list Prints a report of all entries. <hours> When running ctmlog in the list mode
and there is a number between 1 to
48 following the list action, then
ctmlog treats this number as the
number of hours earlier than when
the log was specified to be
generated.
If this number is not within the range
between 1 to 48, then the ctmlog
utility expects the number to be
either in the format yyyymmdd or
yymmdd.

listord Prints a report of entries for a <Order ID> Order ID to include in the report.
specific Order ID.
The Order ID as displayed in the Job
Details window of Control-M/EM is a
base 36 number. If you want to
specify the Order ID here as a base
10 number, precede the number with
an asterisk and enclose the result in
quotation marks (for example,
"*1234").

listjob Prints a report including all entries <Job no.> Job number to include in the report.
for a specific job number.

446
Control-M Utilities Guide

Action Action option

listmsg Prints a report of messages with a <msgid> Message ID to include in the report.
specific message ID.

delete Deletes entries in a specified date None.

and time range.

listjobname Prints a report including all entries <jobName> The name of the job whose entries
for the specified job name. should be printed in the report.

ctmlog utility parameters

This table lists the parameters of the ctmlog utility:

Parameter Description

<From Date> Starting and ending dates and times for the range of entries to be scanned by the
<From Time> specified action. Date is specified in yyyymmdd format. Time is specified in hhmm
<To Date> format.
<To Time>

"*" Asterisk enclosed in quotation marks. Scan all entries in the Control-M log (without
regard to date or time).

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

<Report Width> Width (in columns) of the report to generate. Specify a number in the range of 80 – 132
(default is 80). This parameter can only be specified if the Output parameter is
specified.

ctmlog utility example

The following are examples of ctmlog utility commands:
The following command produces a report of all entries in the Control-M log between 10:00 A.M. March
12, 2008 and 8:00 A.M. March 14, 2008. The report is output to the rprt.txt file in
80-column format:
ctmlog list 20080312 1000 20080314 0800
~<controlm_owner>/ctm_server/user1/rprt.txt

447
Control-M Utilities Guide

The following command produces a report of all entries in the Control-M log relating to downloads to the
Control-M/EM database and to Control-M/Server database updates, without regard to date or
time. The report is output to file gdrprt.txt in 132-column format:
ctmlog listss CD "*" ~<controlm_owner>/ctm_server/user1/gdrprt.txt
132

ctmsys
The ctmsys utility is an interactive utility for maintaining:
 Shout Destination tables (for directing Shout messages).
 Control-M system parameters. For more information, see System configuration.
To run the ctmsys utility, see Running the ctmsys utility (on page 448).
Shout Destination tables associate logical output destinations (specified in Shout and Do Shout statements
in job processing definitions) with physical destination names. For more information, see the description
of the Shout facility in Shout destination management.
You can do the following from the ctmsys utility:
 Creating/Updating a shout destination table (on page 450)
 Shout Destination table parameters (on page 451)
 Creating a new entry in a shout destination table (on page 452)
 Modifying an existing entry in a shout destination table (on page 452)
 Deleting an existing entry in a shout destination table (on page 453)
 Editing an active shout destination table (on page 453)
 Listing existing shout destination tables (on page 453)
 Deleting an existing shout destination table by name (on page 454)
 Accessing the Control-M system parameters from the ctmsys utility (on page 454)
 Customizing the New Day procedure (on page 455)

Running the ctmsys utility

This procedure describes how to run the ctmsys utility, which enables you to maintain Shout Destination
tables and system parameters.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Specify the command:

448
Control-M Utilities Guide

ctmsys
The following menu is displayed:
+------------------------------------------------+
| Control-M SYSTEM MAINTENANCE UTILITY |
| Main Menu |
+------------------------------------------------+

1) Shout Destination Tables

2) System Parameters

q) Quit
Enter option:
The options in this menu and in all other menus provided by this utility can be selected by typing the
option number or command letter and pressing <Enter>.

Accessing the shout destination tables menu

This procedure describes how to access the shout destinations table menu, which enables you to create,
modify, list, and delete shout destination tables.

 To access the shout destination tables menu:

1. Select Option 1 from the Main Menu.
The following menu is displayed:
Shout Destination Tables Menu
-----------------------------
Active Shout Destination Table: <tableName>

1) Create/Modify a Table
2) Set SMART Folder
3) List Tables
4) Delete Table

q) Quit and return to main menu

Enter option:
The name of the currently-active Shout Destination table is displayed in the <tableName> field on the
menu.
2. Modify or view parameters as follows:
• To switch between the two pages of parameters, type n (next page) or p (previous page) as
required.
• To modify a parameter, type the number preceding the parameter.
If the parameter has a Y/N value, typing the parameter’s option number toggles the value
between Y and N and redisplays the page.
• If the parameter requires any other value, you are prompted to type the value. After you supply
the value, the page is redisplayed.

449
Control-M Utilities Guide

3. To exit the utility, do one of the following:

• Type s to save your changes and exit to the Main Menu. Modifications are not saved until you
perform this action.
• Type c to cancel all changes and exit to the Main Menu.

Creating/Updating a shout destination table

This procedure describes how to create/update a shout destination table from the ctmsys utility.

 To create/Update a shout destination table:

1. Select Option 1 from the Shout Destination Tables menu.
A list of available tables, similar to the following, is displayed:
Shout Destination Tables
------------------------
SYSTEM
NIGHT_SHIFT
Table to create/modify or ‘q’ to quit [SYSTEM]:
2. Specify the name of the table to be created or modified (or press <Enter> to accept the default).
If the name you specify is not the name of an existing Shout Destination table, a new table will be
created with the specified name.
A display similar to the following is displayed. For an existing table, the display lists the defined
destinations.
Shout Destination Table ‘SYSTEM’
--------------------------------
# Destination Type Addr Logical Name Physical Name
- ---------------- ---- ------------ -------------
1 E S EM
2 T S Term_B $TTB.#B
q) Quit e#) Edit entry # n) New entry d#) Delete entry #
Enter option:
For more information, see Shout Destination table parameters (on page 451).

450
Control-M Utilities Guide

Shout Destination table parameters

The following table lists the parameters for creating.updating a shout destination table from the ctmsys
utility:

Item Description

# Entry number in the table.

Destination Type One-letter code indicating the type of recipient:

U—Specific user. If the user is not logged onto the data center
when the Shout message is sent, the message is placed in the
user’s mail.

M – User’s mail.

T – Destination is a specific terminal or file known to the operating

system from which the shout was invoked.

O – System console.

L – Control-M/Server log.

E – Alert window of Control-M/EM.

P – Sends the shout message to a specific program.

Addr One-letter code indicating whether the destination is on the server

(S) or agent (A) computer.

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

Physical Name For Destination Type U, name of a user in the data center.
For Destination Type M, e-mail address of the user (for example,
[email protected]).
For Destination Type T, terminal ID or full path name (max. 96
characters) of a file. If the file exists, the message will be
appended to the end of the file.
For Destination Type P, the full path name of the program
file/script that will perform the Shout operation.
For Destination Types O, L, and E, no physical name is specified
because each of these is a unique destination.

451
Control-M Utilities Guide

Creating a new entry in a shout destination table

This procedure describes how to create a new entry in a shout destination table from the ctmsys utility.

 To create a new entry in a shout destination table:

1. Type n.
The following prompts appear:
Dest. Type: (U)ser (M)ail (T)erminal c(O)nsole (L)og (P)rogram Control-M/(E)M:
2. Specify the letter corresponding to the desired destination type.
The following prompt is displayed:
Address Type (S)erver or (A)gent:
3. For Destination types U, M, P, T, or O, specify whether the destination is on the server (S) or agent
(A). For Destination type E, specify S.
The following prompt is displayed:
Logical Name:
4. Specify the logical name for this destination.
The following prompt is displayed:
Physical Name:
5. For Destination types U, M, P, or T, specify the physical name. For Destination types O and E, leave
this field blank.
The new entry is added to the table.

Modifying an existing entry in a shout destination table

This procedure describes how to modify an existing entry in a shout destination table from the ctmsys
utility.

 To modify an existing entry in a shout destination table:

1. Type e<entry_number>. For example, to modify entry number 2, specify e2.
The following prompt is displayed:
Dest Type:
Address Type:
Physical Name:
This option cannot be used to modify a logical name.
2. Specify a new physical name for the entry.
The table is redisplayed with the modified entry.

452
Control-M Utilities Guide

Deleting an existing entry in a shout destination table

This procedure describes how to delete an existing entry in a shout destination table from the ctmsys
utility.
 To delete an existing entry in a shout destination table:
1. Specify d<entry #>. For example, to delete entry # 2, specify d2.
The entry is deleted.
2. Specify q to return to the Shout Destination Tables menu.
The Shout Destination Tables menu is redisplayed.

Editing an active shout destination table

This procedure describes how to edit an active shout destination table from the ctmsys utility.

 To edit an active shout destination table:

1. Select Option 2 from the Shout Destination Tables menu.
A list similar to the following is displayed:
Existing Shout Destination Tables
---------------------------------
SYSTEM
NIGHT_SHIFT
Enter name of table to make active or q to quit [SYSTEM]:
2. Specify the name of the table to set as the active Shout Destination table.
The following message is displayed:
Table <table name> is now active.
Press ENTER to continue.
3. Press <Enter> to return to the Shout Destination Tables menu.
The active Shout Destination table is changed immediately, affecting Shout and Do Shout operations
performed by Control-M.
To specify the active Shout Destination table using a job, run the ctmshtb utility, described in ctmshtb (on
page 401)

Listing existing shout destination tables

This procedure describes how to list existing shout destination tables from the ctmsys utility.

 To list existing shout destination tables:

1. Select Option 3 from the Shout Destination Tables menu.
A list similar to the following is displayed:

453
Control-M Utilities Guide

Shout Destination Tables

------------------------
SYSTEM
NIGHT_SHIFT
Press ENTER to continue
2. Press <Enter> to return to the Shout Destination Tables menu.
The Shout Destination Tables menu is redisplayed.

Deleting an existing shout destination table by name

This procedure describes how to delete an existing shout destination table by name.
 To delete an existing shout destination table by name:
1. Select Option 4 from the Shout Destination Tables menu.
A list of existing Shout Destination Tables is displayed.
2. Specify the name of the table to delete.
The following message is displayed:
Delete completed successfully.
Press ENTER to continue.
3. Press <Enter> to return to the Shout Destination Tables menu.
It is not possible to delete the active Shout Destination table.

Accessing the Control-M system parameters from the ctmsys

utility
This procedure describes how to access the Control-M system parameters from the ctmsys utility, which
enables you to view or edit Control-M system parameters.
 To access the Control-M system parameters from the ctmsys utility:
1. Choose Option 2 from the Main Menu.
The first group of parameters (and their current values) is displayed.
2. When you specify n, the second page of parameters is displayed.
3. Enter command, or item number you wish to change.

454
Control-M Utilities Guide

Customizing the New Day procedure

This procedure describes how to customize the New Day procedure using the ctmsys utility.

 To Customize the New day procedure:

1. From the Control-M System Maintenance Utility Main Menu, set the New day time by typing 1
(Day Time) and then type the value of the New Day Time, preceded by a + (for example, +0800).
2. Set the retention period for Control-M/Server logs, by typing 6 (Maximum Days Retained by Control-M
Log) and then typing the value required.
3. To define that the New Day procedure should ignore (not cleanup) conditions, type 8 to toggle the
Ignore New Day Conditions system parameter to Y.
NOTE: BMC Software recommends that you not change the default. Changing the value to Y, would
only be useful if your site has jobs that are triggered by prerequisite jobs that ran the year before.
4. Type S to save the changes and return to the main menu.
5. Set the configuration parameter values in the Control-M/Server configuration parameter file
(~<controlm_owner>/ctm_server/data/config.dat on the server computer), as follows:
• Define whether the New Day procedure should cleanup (delete) job runtime statistics, by running
the ctmruninf utility. (You can also run this utility manually, and use the utility to display runtime
statistics summaries.)
By default, the New Day procedure cleans up statistics (the
STATISTICS_CLEANUP_IN_NEWDAY configuration parameter is set to Y). To speed up the
New Day procedure, set the STATISTICS_CLEANUP_IN_NEWDAY configuration parameter to
N, but periodically run ctmruninf - PURGE manually. For information, see ctmruninf (on page
615).
• Define whether the New Day procedure should cleanup (delete) Output files and unneeded user
exit status files from Control-M/Agent computers (using the ctmagcln utility.)
By default, the New Day procedure cleans up the Output and User exit status file (the
AGENTS_CLEANUP_IN_NEWDAY configuration parameter is set to Y). To speed up the New Day
procedure, set the AGENTS_CLEANUP_IN_NEWDAY configuration parameter to N, but to
periodically run the ctmagcln utility manually. For information, see ctmagcln (on page 429).
NOTE: If any folders need to be ordered by the New Day procedure (instead of User daily jobs),
associate them with the Order Method, Specific User Daily and SYSTEM User daily Name in
Control-M.

ctmunixcfg
The ctmunixcfg enables you to interactively view and modify most of the configuration parameters in the
OS.dat file. This utility can also be accessed as a Java application. For more information, see
Control-M/Agent parameters.
To run the ctmunixcfg utility, see Running the ctmunixcfg utility (on page 456).

455
Control-M Utilities Guide

Running the ctmunixcfg utility

This procedure describes how to run the ctmunixcfg utility, which enables you to interactively view and
modify most of the configuration parameters in the OS.dat file.
This utility can also be accessed as a Java application. For more information, see System configuration.

 To run the utility:

 Type the following command:
ctmunixcfg
For a description of the parameters in the ctmunixcfg utility, see the descriptions of the configuration
parameters in System configuration.

ctmwincfg
The ctmwincfg utility enables you to view and modify application support for Windows. For a description
of the parameters in the ctmwincfg utility, Control-M application support configuration.
This utility can also be accessed as a Java application. For more information, see System configuration.

Running the ctmwincfg utility

This procedure describes how to run the ctmwincfg utility.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctmwincfg

456
Control-M Utilities Guide

ecaqrtab
The ecaqrtab utility performs operations on the Quantitative Resources table. These operations include:
 Listing quantitative resources. To list quantitative resources, see Listing quantitative resources (on
page 459)
 Adding/deleting a quantitative resource. To add and delete quantitative resources, see Adding a
Quantitative resource (on page 460) and Deleting a quantitative resource (on page 460)
 Manually changing availability of a quantitative resource. To manually change the availability of a
quantitative resource, see Altering the availability of a quantitative resource (on page 460)
To run the ecaqrtab, see Running the ecaqrtab utility (on page 457)

Running the ecaqrtab utility

This procedure describes how to run the ecaqrtab utility, which performs operations on the Quantitative
Resources table.
 To run the utility:
 Do one of the following:
• From a Control-M/Server computer, type one of the following commands:
o ecaqrtab {LIST|ADD|DELETE|UPDATE}{<orName>|"*"}[<Max>][-OUTPUT
<output>]
o ecaqrtab -input_file <fullPathFileName>
• From a Control-M/Agent computer, to invoke the LIST option type one of the following
commands:
o ecaqrtab LIST "*" [-OUTPUT <output>]
o ecaqrtab -input_file <fullPathFileName>
NOTE: If a resource name is longer than 20 characters, the resource is not added.
For information about the ecaqrtab utility parameters, see ecaqrtab utility parameters (on page 458).

457
Control-M Utilities Guide

ecaqrtab utility parameters

The following table describes the ecaqrtab utility parameters:

Parameter Description

LIST Displays the status of the specified Quantitative resources. This

information is also available from Control-M/EM in the Quantitative
Resources window.

ADD Defines a new Quantitative resource and sets the maximum availability
for the resource.

DELETE Deletes an existing Quantitative resource.

UPDATE Changes the maximum availability of an existing Quantitative resource.

<QR_Name> Name of the Quantitative resource. For the LIST option, QR_Name can
include wildcard character * to indicate any number of characters
(including none). If * is specified, enclose the name in quotation marks,
for example, "LVL*". When invoked by the server or agent, specify "*"
(including the quotation marks) to include all existing Quantitative
resources (default when invoked by the server).

<Max> Maximum availability for the specified resource. Can only be specified
with the ADD and UPDATE options.

<Output> Full path name to which the report should be sent (optional). If not
specified, output is routed to the default output device. This parameter
can only be specified with the LIST option.

<fullPathFile Name and full path of a file containing parameters for the utility. In this
Name> file, each parameter and its values (if any) are on a separate line with
the same syntax they would have on the command line. Using the
-input_file parameter enables you to:
Prepare and save files of utility parameters that can be reused.
Specify utility input longer than the number of characters allowed in the
command line.
-input_file
~<controlmOwner>/ctm_server/data/ecaqrtab_p
arms.txt
The path that is specified for this parameter must be accessible by the
Control-M/Server account (even if this utility is requested by
Control-M/Agent.

458
Control-M Utilities Guide

Listing quantitative resources

This procedure describes how to list the quantitative resources.

 To list quantitative resources:

 Do one of the following:
• From a Control-M/Server computer, type the following command:
o ecaqrtab LIST {<QR_Name>|"*"} [-OUTPUT <Output>]
• From a Control-M/Agent computer, type the following command:
o ecaqrtab LIST "*" [-OUTPUT <Output>]
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details,
see Quantitative Resource parameters (on page 459).

Quantitative Resource parameters

The following table describes the fields that are displayed for each Quantitative resource that matches the
specified resource name or mask.

Parameter Description

QR name Quantitative resource name (with @<Host ID> where applicable).

Type For future use.

Max Avail Maximum number of units of this resource in the computer.

Reserved Number of units of the resource reserved for critical-path jobs.

Used Number of units of the resource currently in use or reserved. If the

ctmloadset utility is used in the data center, this number can include
usage of the resource by non-Control-M jobs.

Free Number of units of the resource currently available for use. This
represents the difference between Max Avail and Used.

Quantitative Resource example

The following command can be invoked by the server or the agent to list the current status of all
Quantitative resources in the Quantitative Resource table:
ecaqrtab LIST "*" -OUTPUT D:\ctm_server\QR.txt
A report similar to the following is displayed:
+--------------------------------------------------------------+
Resource Name Type Max-Avail Reserved Used Free

459
Control-M Utilities Guide

+--------------------------------------------------------------+
CPU@linda L 10 0 10 0
CPU@linda L 20 0 15 5
MEM@diana L 10 0 0 10
Tape2 L 12 2 2 10

Adding a Quantitative resource

This procedure describes how to add a Quantitative Resource.

 To add a Quantitative resource:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the following command:
ecaqrtab ADD <QR name> <Max>
EXAMPLE: The following command specifies that the new Quantitative resource tape2 is to be added
to the Quantitative Resource table, with a maximum availability of 12 units:
ecaqrtab ADD tape2 12

Deleting a quantitative resource

This procedure describes how to delete a quantitative resource.

 To delete a quantitative resource:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the following command:
ecaqrtab DELETE <QR name>
The following command specifies that the Quantitative resource tape3 is to be deleted from the table:
ecaqrtab DELETE tape3

Altering the availability of a quantitative resource

This procedure describes how to alter the availability of a quantitative resource.

 To alter the availability of a quantitative resource:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.

460
Control-M Utilities Guide

• Windows: Open a command prompt window where Control-M/Server is installed.

2. Type the following command:
ecaqrtab UPDATE <QR name> <Max>
The following command specifies that the new maximum availability for the existing Quantitative
resource linerje2 on computer diana is 12 units:
ecaqrtab UPDATE linerje2@diana 12
You can get the same result using the -input_file parameter as follows:
ecaqrtab -input_file ~<controlm_owner>/ctm_server/data/ecaqrtab_lines.txt
The referenced file contains the following lines:
UPDATE
linerje2@diana
12
e.

emmftcli
The emmftcli utility enables you to search for file transfers in Control-M based on search and filter
parameters from a command line. The utility creates a csv file according to the parameters defined. You
must run this utility from the Control-M/EM server computer.

Running the emmftcli utility

This procedure describes how to run the emmftcli utility which enables you to search for file transfers in
Control-M based on search and filter parameters from a command line.

 To run the emmftcli utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
2. Type the following command:
emmftcli [-u <emuser> -p <password> | -pf <password file>] -s <GUI server
name> -o <output file> [-m <timeout>] [-h] -search [ -t <free text> | [-f
<filename>] [-fl <folder>] [-ap <application>] [-b <sub application>] [-j
<jobname>] [-st <status>] [-src <source>] [-dst <destination>] [-srcp
<path>] [-dstp <path>] ] [-d <n days>] [-dt <yyyy/mm/dd-yyyy/mm/dd>] [-l
<last n hours>] [-tf <transfered at
yyyy/mm/ddThh:mm:ss-yyyy/mm/ddThh:mm:ss>]

461
Control-M Utilities Guide

EXAMPLE: Search all file transfers in the current day for application APPL1 and jobname job001 to the
file out.csv
emmftcli -u <emuser> -p <pass> -s GUI-server-name -o out.csv -search -ap APPL1 -j job001
-d 1
EXAMPLE: Search all file transfers in the last 24 hours that contain the text file in the filename to the file
out.csv
emmftcli -u <emuser> -p <pass> -s GUI-server-name -o c:\mft\out.csv -search -filename
"*file*" -l 24
EXAMPLE:Search all file transfers that contain the text free text to the file out.csv
emmftcli -u <emuser> -p <pass> -s GUI-server-name -o out.csv -search -t free text
For information about the parameters, see emmftcli parameters (on page 463).

462
Control-M Utilities Guide

emmftcli parameters
The following table describes emmftcli parameters. For search with special characters (non alpha
numeric) use quotes.

Parameter Description

-u Control-M/EM user name

-p Control-M/EM user password

-pf Defines a flat file containing an unencrypted username and

password on separate lines in the format:
user=username
password=password

-s The name of the Control-M Configuration Server. It is mandatory

to specify this parameter.

-o out_file <output file>Mandatory. output file in csv format. The

utility overrides the data in the output file, if it already exists.

-m -timeout <timeout>timeout in seconds, to wait for search

response.

-h Shows usage.

-search Search for File Transfer records according to the specified filter
options

-t Defines free text to search, search for all File Transfer records that
contain the specified text in the pre-defined fields (* are treated
as any other character). If specified, all other search filter
parameters are ignored.

-f Filters by Filename

-fl Filters by Folder

-ap Filters by Application

-b Filters by Sub Application

-j Filters by Job Name

463
Control-M Utilities Guide

Parameter Description

-st Filters by one of the following statuses:

 1: IN_PROGRESS
 2: COMPLETED
 3: FAILED
 4: COMPLETED_WITH_ERRORS

-src Filters by source host

-dst Filters by destination host

-srcp Filters by source path

-dstp Filters by destination path

-d Determines the number of days back to search for file transfers

sent or received. (1 is current day)

-l Determines the number of hours back to search for file transfers

sent or received. from the current time (1 is current hour)

-tf Determines the period to search for file transfers by date and time
according to the following format:
yyyy/mm/ddThh:mm:ss-yyyy/mm/ddThh:mm:ss
NOTE: The date and times must be in UTC (GMT+00:00).

464
Control-M Utilities Guide

emcha -restore
The emcha -restore utility restores high availability data to the Control-M/EM primary or secondary host.
The following table describes emcha parameters.

Parameter Description

Primary  Sets the primary host to active and the secondary to stand-by.
 Sets the primary host components desired state to Up and the
secondary host components to Down.

Secondary  Sets the secondary host to active and the primary to stand-by.
 Sets the secondary host components desired state to Up and
the primary host components to Down..

Running the emcha -restore utility

This procedure describes how to run the emcha -restore utility that restores high availability data to the
Control-M/EM primary or secondary host.

 To run the emcha -restore utility:

 Do one the one of the following:
• UNIX: em cha –restore primary|secondary
• Windows: emcha.exe –restore primary|secondary

erase_audit_data
The erase_audit_data utility deletes records written prior to the specified date.
When erase_audit_data is invoked, it uses a script to delete records written before a specified date. If the
-U and -P parameters are not specified, the Control-M/EM database owner (DBO) user name and
password are prompted for. The erase_audit_data utility can delete large numbers of audit records. To
run the erase_audit_data utility, see Running the erase_audit_data utility (on page 465).

Running the erase_audit_data utility

This procedure describes how to run the erase_audit_data utility, which deletes records written prior to
the specified date.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.

465
Control-M Utilities Guide

• Windows: Open a command prompt window where Control-M/EM is installed.

2. Enter the following command:
erase_audit_data [-date YYYYMMDD] [-U emDboName]
[-P emDboPassword]
Records written prior to the specified date are deleted.
For more detail on the erase_audit_data utility, see erase_audit_data utility parameters (on page
466).

erase_audit_data utility parameters

The following table describes the erase_audit_data parameters:

Parameter Description

-date A date in YYYYMMDD format (for example, 20070915), which sets the
selection criteria for obsolete jobs. Default: two days before the current
date

-U Name of the Control-M/EM database.

-P Password of the Control-M/EM database.

When cleanup of audit information from the Control-M/EM database is automatic, the MaxAuditsToDelete
parameter specifies the maximum number of audit records to delete during each automatic cleanup
operation. If the number of audit records to clean is higher than this number, no records are deleted. The
default is 400000 records. If the number of audit records to clean is higher than the MaxAuditsToDelete
parameter, a message is issued to the GUI Server diagnostic log asking you to clean audit records
manually using the erase_audit_data utility. You can use the Control-M/EM Administration facility to
change the automatic cleanup of audit information settings.

466
Control-M Utilities Guide

purge_xalerts
The purge_xalerts utility deletes exception alerts from the Exception Alerts table in the Control-M/EM
database. To run the purge_xalerts utility, see Running the purge_xalerts utility (on page 467).
The deleted exception alerts are no longer displayed in the XAlerts window either within an hour or after
you restart the CMS, whichever occurs first.
For more information about exception alerts, see Managing exception alerts.

Running the purge_xalerts utility

This procedure describes the purge_xalerts utility, which deletes exception alerts from the Exception
Alerts table in the Control-M/EM database.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
2. Enter the following command:
purge_xalerts [-U <emDBO>] [-P <emDBOPassword>] [-keep_days <number>]
The utility has finished when the message Ended successfully is displayed.
For the Control-M parameter name, see Parameter name cross references (on page 31). For more detail
on the purge_xalerts utility, see purge_xalerts utility parameters (on page 467).

purge_xalerts utility parameters

The following table describes the purge_xalerts utility parameters:

Parameter Description

-U Defines the Control-M/EM database user name.

-P Defines the Control-M/EM database user password.

keep_days Defines the number of days for which exception alerts are kept in the
Control-M/EM database.

467
Control-M Utilities Guide

purge_runinfo
There are two main tables in Control-M/Forecast:
 AVG_RUN_INFO: Calculates job run times. This table migrates by default, even if you choose not
to migrate Forecast data.
 RUNINFO_HISTORY: Generates Forecast reports using the Reporting facility. The
RUNINFO_HISTORY table is a larger table than the AVG_RUN_INFO table and it contains run
information used by the Control-M/Forecast Server.
In the last 90 days, for each job execution, a record is entered in the RUNINFO_HISTORY table. The
RunTimeHistoryDays system parameter determines how many days the data is kept in the
RUNINFO_HISTORY table. The parameter can be set for fewer days, or it can be set to zero (0).
Forecast reports (Reporting Facility) keeps only one day of data and no other forecast features are
affected. The purge_runinfo maintenance utility needs to run periodically to maintain this table and to
clean out Control-M/Forecast run information. The settings are site-specific. The utility is located in one of
the following directories, depending on your operating system:
 EMHome\bin (on Windows)
 EMHome/scripts (on UNIX)
The log files of the purge_runinfo utility are located in the installation log directory both in UNIX and in
Windows. The log file that shows the run flow of the utility is called purge_runinfo_run.log.

Running the purge_runinfo utility

This procedure describes how to run the purge_info utility, which enables you to clean out run
information retained by Control-M/Forecast for the purposes of performing its calculations.
 To run the utility:
 Do one of the following
• To run the utility interactively, type the following commands depending on your operating system:
o On Windows
<emHome>\bin\purge_runinfo.bat
o On UNIX
<emHome>/scripts/purge_runinfo shell script
• Answer the prompts when they are displayed. You are prompted for the following information:
o The number of days to retain the information about the run of the jobs
o The Control-M/EM database owner (DBO) password user name and password
The utility has finished when the message Ended successfully is displayed.
 To run the utility silently, type the following command:
purge_runinfo –U <emUser> -P <emPass> -keep_days <numDaysRetain>
On UNIX, you can hide the password using the file method (in this example, X is the name of the file
that contains the password):

468
Control-M Utilities Guide

cat X | purge_runinfo –U <emUser> -P <emPass> -keep_days

<numDaysRetain>
<numDaysRetain> is the number of days to retain the statistics. If <numDaysRetain> is 2, all
statistics prior to two days before the current date will be deleted. For example:
purge_runinfo –U myuser -P mypassword -keep_days 2
The DeleteChunkSize system parameter determines the number of records deleted in one transaction by
the purge_runinfo utility when removing run information from the RUNINFO_HISTORY table in the
Control-M/EM database. If the DeleteChunkSize value is smaller than the parameter value, no data is
deleted.

Loading prerequisite conditions from manual conditions file

This procedure describes how to run the load prerequisite conditions from the Manual Conditions file.
 To load prerequisite conditions from manual conditions file:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctmldnrs -LOAD <Condition Name> [-INPUT <Filename>]
For parameters, see Manual conditions parameters (on page 470)

Creating the manual conditions file

This procedure describes how to run the create the manual conditions file.
 To create the manual conditions file:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctmldnrs -CALCCOND [-ADDMODE {YES | NO} ]
[-OUTPUT <filename> ]
[-IGNOREIN <condition-mask>]
[-IGNOREOUT <condition-mask>]
[-IGNORECODES <condition-mask>]
[-INCLUDE_FUTURE_ODATES ]

469
Control-M Utilities Guide

Manual conditions parameters

The following table describes the conditions from the Manual Conditions file to the Conditions/Resources
table:
ctmldnrs -LOAD <Condition Name> [-INPUT <Filename>]

Parameter Description

<Condition Name> All conditions in the input file that satisfy the specified characters are
loaded or listed.
Specify "*" by itself to load/list all conditions.
When using both open and closed square brackets ([ and ]), the
condition name must be enclosed in quotation marks (for example,
"RATE[A1]").

<Filename> Path name of the input Manual Conditions file. If this parameter is
not specified, the default input file is:
UNIX
<Control-M Server Home
dir>/ctm_server/tmp/ctmldnrs.dat
Windows
<Control-M Server Home
dir>\ctm_server\temp\ctmldnrs.dat

Manual conditions file example

The following are examples of the manual conditions file;
The following command re-creates the default Manual Conditions file in the user’s directory:
ctmldnrs -CALCCOND -ADDMODE NO
The following command creates a Manual Conditions file /h/mcond/data/output.dat that ignores
conditions with prefix "a":
ctmldnrs -CALCCOND -ADDMODE NO -OUTPUT /h/mcond/data/output.dat \
-IGNOREIN "a*" \
The following command loads all conditions from the default input Manual Conditions file to the
Conditions/Resources table:
ctmldnrs -LOAD "*"

470
Control-M Utilities Guide

Running the ctm_remedy_configure utility

This procedure describes how to run the ctm_remedy_configure utility, which enables you to change and
test the Do Remedy action settings.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type the following command:
ctm_remedy_configure
The following interactive menu is displayed:
1> Basic Parameters
2> Reset user password
3> Test configuration
4> Quit
3. Do one or more of the following:
a. Press 1 to change basic settings:
o Remedy server name
o Remedy server port
o Remedy user name
o Login user
o First user name
o Last user name
b. Press 2 to enter a new user password
c. Press 3 to test the changes that were made to the configuration
d. Press 4 to exit the utility

set_agent_mode
Use the set_agent_mode utility to enable or disable the non-root mode of Control-M/Agent on UNIX. The
utility changes the permissions of several agent files and directories to allow the agent to work in the
mode that is selected. This utility must be run by the root user and only needs to be run once to set a
mode. Each time the agent is started (or restarted) it will continue to use the mode that was set until
such time that the mode is changed. To run the set_agent_mode utility, see Running the set_agent_mode
utility (on page 472).

471
Control-M Utilities Guide

When Control-M/Agent is started by the agent owner user, only jobs where the agent owner is the job
owner can be run. To run jobs with different owners, define the passwords of the owners and then use
the set_agent_mode utility to enable non-root mode. Both actions must be performed to allow jobs to be
submitted. For more information about how to define the passwords of the owners, see Control-M/Agent
security or ctmsetown (on page 597).

Running the set_agent_mode utility

This procedure describes how to run the set_agent_mode utility, which enables you to enable/disable the
non-root mode of Control-M/Agent on UNIX.

 To run the utility:

 Do one of the following:
• Type the following command to run the utility interactively:
set_agent_mode
For more information on the options, see set_agent_mode interactive options (on page 472).
• Type the following command to run the utility silently:
set_agent_mode –u <agentOwner> -o <Option>
The valid values for <Option> are described below:
o 1 - enable non-root mode
o 2 - enable root mode
o 3 - enable sudo mode
o 4 - prepare for non root uninstall
o 3 - quit

set_agent_mode interactive options

The following table lists the set_agent_mode interactive options:

Option Description

Enable non root mode enables the agent to run jobs by any job owner and registers it in
the /etc/ctm.conf file

Disable non root mode returns the agent to the state it was in after the installation

Prepare the agent for returns the agent to the state it was in after the installation and
non root uninstall removes it from the /etc/ctm.conf file

472
Control-M Utilities Guide

Health Check utility

Control-M Health Check utility scans and collects system information about the Control-M environment,
which is used by BMC Support to help troubleshoot and correct problems. The information is maintained
in a compressed hierarchical format that enables a detailed analysis of the collected data.
The following Health Check utilities are available with the following data collectors:
 Control-M: em_data_collector
 Control-M/Server: ctms_data_collector
 Control-M/Agent and Control-M Application plug ins: ctma_data_collector
 Control-M/Archive: arc_data_collector
The Health Check utility uses the following parameter types, which enables you to filter the relevant data
for BMC Support:
 Components: Enables you to collect data from all products by running the Health Check utility with
default settings.
 Category: Enables you to collect data from Information type groupings. For example, operating
system, database, or scheduling. For more information, see Standard Category parameters in Health
Check utility parameters (on page 477).
 Profile: Enables you to collect data from a predefined combination of Components and Categories.
For more information, see Profile parameters in Health Check utility parameters (on page 477).
You can run the Health Check Utility from one of the following options:
 Command line, as described in Running Health Check utility from the command line (on page 473).
 Batch file, as described in Running Health Check utility from a batch file (on page 474).
 Control-M Configuration Manager, as described in Generating diagnostic data in Administration.

Running Health Check utility from the command line

This procedure describes how to run the Health Check utility with default parameters, which enables you
to collect and package the data generally required by BMC Support.

 To run Health Check utility from the command line:

 Type one or more of the following commands:
• Control-M/EM: em_data_collector -U <em_dbo_user> -P <em_dbo_pwd>
• Control-M/Server: ctms_data_collector -U <ctm_dbo_user> -P <ctm_dbo_pwd>
• Control-M/Agent and Control-M Application plug ins: ctma_data_collector
• Control-M/Archive: arc_data_collector
For examples of running the Health Check Utility from the command line, see Health Check utility
command line examples (on page 475).

473
Control-M Utilities Guide

Running Health Check utility from a batch file

This procedure describes how to run the Health Check utility from a batch file.

 To run Health Check utility from a batch file:

1. Do one of the following:
• From the command line, type the following:
-batch
• From one of the following directories, set batch_mode=y.
o Windows: <HOME>\ini\config\ini
o UNIX: $HOME/ini/config.ini
2. (Optional) Create a password text file with the following string:
dbo=<dbo_password>
NOTE: The dbo_password must be the actual database owner password. For the Health Check utility
to read the password file, the value of -file argument needs to point to the exact password file
location.
EXAMPLE: em_data_collector –U <em_dbo_user> -file <password_file_path>
3. Schedule or run the batch file.
EXAMPLE: em_data_collector –U <em_dbo_user> -file pwd_file.txt –batch
NOTE: Running in batch mode requires providing the user name and password as part of the
command.

Packages and log locations

Running a Health Check utility creates a log file that specifies what processes ran and what information
was written to the package file. The contents of the log file indicate what proprietary information is
included in the package file. The Health Check utility writes log files to the following directories:
 Control-M: <EM_HOME>/log

 Control-M/Server: <SERVER_HOME>/ctm_server/health_check/log
 Control-M/Agent: <AGENT_HOME>/ctm/proclog

 Control-M/Archive: <EM_HOME>/ctm_em/archive/health_check/log
The log file name is constructed as follows:
<your_data_collector>_<TIME_STAMP>_<OS_TYPE>_<HOSTNAME>_display.log
where <your_data_collector> is the relevant of the following:

474
Control-M Utilities Guide

 em_data_collector
 ctms_data_collector
 ctma_data_collector
 arc_data_collector
The Health Check utility package files are saved to the following directories:
 Control-M: <EM_HOME>/hcu_package

 Control-M/Server: <SERVER_HOME>/health_check/hcu_package
 Control-M/Agent: <AGENT_HOME>/hcu_package

 Control-M/Archive: <EM_HOME>/archive/health_check/hcu_package
The package files names are constructed as follows:
 Control-M: em_data_<TIME_STAMP>_<OS_TYPE>_<HOSTNAME>.zip
 Control-M/Server: ctms_data_<TIME_STAMP>_<OS_TYPE>_<HOSTNAME>.zip

 Control-M/Agent: ctma_data_<TIME_STAMP>_<OS_TYPE>_<HOSTNAME>.zip
 Control-M/Archive: arc_data_<TIME_STAMP>_<OS_TYPE>_<HOSTNAME>.zip
In UNIX, substitute tar.z instead of zip.

Health Check utility command line examples

The following examples describe the commands for running the Health Check utility:
 Control-M command line examples (on page 475)
 Control-M/Server command line examples (on page 476)
 Control-M/Agent and Control-M Application plug ins examples (on page 476)

Control-M command line examples

The following examples describe the commands for running the Health Check utility for Control-M:
 Collects information of all Profiles for the last seven days:
em_data_collector -U <dbo_user> -P <dbo_pwd> -days=7 -F ALL
 Collects information of OS and DB Categories:
em_data_collector -U <dbo_user> -P <dbo_pwd> -C OS DB -D EM
 Collects the logs from past 5 days:
em_data_collector -U <dbo_user> -P <dbo_pwd> -C LOG -D EM -days=5

475
Control-M Utilities Guide

 Collects the performance measurements, send the package to shared location and assign issue
number to the package:
em_data_collector -U <dbo_user> -P <dbo_pwd> -F MSR -out=/home/issues
-issue=ISS112233

Control-M/Server command line examples

The following examples describe the commands for running the Health Check utility for Control-M/Server.
 Collects information of all Profiles for the last seven days:
ctms_data_collector -U <dbo_user> -P <dbo_pwd> -days=7 -F ALL
 Collects information of OS and DB Categories:
ctms_data_collector -U <dbo_user> -P <dbo_pwd> -C OS DB -D CTM
 Collects the logs from past 5 days:
ctms_data_collector -U <dbo_user> -P <dbo_pwd> -C LOG -D CTM -days=5
 Collects the performance measurements:
ctms_data_collector -U <dbo_user> -P <dbo_pwd> -F MSR

Control-M/Agent and Control-M Application plug ins examples

The following examples describe the commands for running the Health Check utility for Control-M/Agent
and Control-M Application plug ins.
 Collects information of all Profiles for the last seven days:
ctma_data_collector -U <dbo_user> -P <dbo_pwd> -days=7 -F ALL
 Collects information of OS and LOG Categories:
ctma_data_collector -U <dbo_user> -P <dbo_pwd> -C OS LOG -D AG
 Collects the configuration and logs of Control-M for SAP:
ctma_data_collector -U <dbo_user> -P <dbo_pwd> -F CMSAP

Control-M/Archive
The following examples describe the commands for running the Health Check utility for
Control-M/Archive:
 Collects information of all Profiles for the last seven days:
arc_data_collector -U <dbo_user> -P <dbo_pwd> -days=7 -F ALL
 Collects information of the CNF category :
arc_data_collector -U archive -P empass -D ARC -C CNF
 Collects logs from the past 5 days:
arc_data_collector -U <dbo_user> -P <dbo_pwd> -days=5

476
Control-M Utilities Guide

Health Check utility parameters

The following table lists the Health Check utility parameters:

Parameter Description

passwordInfo For Categories and Profiles that access a Control-M database, you
need to specify <dbo_user> and <dbo_pwd>, which means the
following:
 Running the Health Check utility with default parameters:
• Control-M: Requires dbo parameters.
• Control-M/Server: Requires dbo parameters
• Control-M/Archive: Requires dbo parameters
 Running the Health Check utility with non-default parameters:
• Control-M:
o Categories that do not require dbo parameters: OS, CNF,
LOG
o Categories that require dbo parameters: DB, DBT, SCH,
TBL, COM, MSR_GSR, MSR_GTW, MSR_DB
NOTE: All Profiles require dbo parameters.
• Control-M/Server:
o Categories that do not require dbo parameters: CNF, OS,
LOG, TBL, INST, FNC
o Categories that require dbo parameters: DB, MSR_CTM
NOTE: All Profiles require dbo parameters.
• Control-M/Archive:
o Categories that do not require dbo parameters: CNF, LOG,
o Categories that require dbo parameters: DB, TBL
NOTE: All Profiles require dbo parameters.
Control-M/Agent and Control-M Application plug ins: Do not
require dbo parameters.

Components (optional) Products and applications for which the utility can gather
data.

Categories (optional) Information type groupings, for example, operating system,

database, and scheduling. For more information, see Health Check
utility standard category parameters (on page 481).

477
Control-M Utilities Guide

Parameter Description

Profiles (optional) In general, a Profile is a predefined combination of

Components and Categories. If you specify one or more Profiles, do
not specify Components or Categories.
For more information, see Control-M specific profile parameters (on
page 490), Control-M/Server specific profile parameters (on page 492)
and Control-M/Agent specific profile parameters (on page 494).

runConfiguration You can optionally specify one or more of the following:

 -simulate: Simulates execution of a Health Check utility. This
allows the user to verify that specified parameter values are
appropriate.
 -days: (default: 2) The maximum number of days in the past for
which the utility gathers the information. This option only affects
log files relevant to BMC Software components.
 -max_size: (default: 300) In megabytes, the maximum size of
the compressed file packed by a Health Check utility.
 -trace: Run a trace on the Health Check utility run. This
generates the following log file:
ctm_data_collector_<YYYYMMDD>_<HHMMSS>_<PLATFOR
M_TYPE>_<HOSTNAME>.log
 -verbose: Outputs the utility processes to your display. By
default, only processed categories are displayed.
 -help or -h: Displays the utility’s usage.
 -file <password_file_path>: The path to a file that you
created that contains the Control-M/EM database owner (DBO)
password.
 -batch: Run in batch mode. For more information, see Running
Health Check utility from a batch file referred to in Health Check
utility (on page 473).

478
Control-M Utilities Guide

Health Check utility component parameters

The following table lists the valid component parameters:

Utility Component Parameter

Control-M  EM: Control-M

 BIM: BMC Batch Impact Manager
 FOR: Control-M/Forecast

Control-M/Server CTM: Control-M/Server

Control-M/Agent  AG: Control-M/Agent

and Control-M
Application plug ins  CMAFT: Control-M for AFT
 CMSAP: Control-M for SAP
 CMPSFT: Control-M for PeopleSoft
 CMOAP: Control-M for Oracle Applications
 CMWJM: Control-M Web Services, Java and Messaging

Control-M/Archive ARC: Control-M/Archive

479
Control-M Utilities Guide

Health Check utility installation category parameters

The following table lists Installation Category parameters. These parameters group information from
various parts of your system.

Category Definition

INST (UNIX) For all components handled, collects the content of the following:
 BMCINSTALL/installed/
 BMCINSTALL/log/
 BMCINSTALL/uninstall/
Collects all files with user ownership from the /tmp directory.
Lists all directories and folders under the component installation path.

INST Collects the content of the following:

(Windows)
 %temp%\PG*.txt
 %ALLUSERSPROFILE%\Application Data\PG*.txt
 <EM_HOME>\bin\DBUtils\DBUData\log\
 %temp%\*_log.txt
 %temp%\*_win.txt
Lists all directories and folders under the component installation path.

NOTE: Running Health Check utility with INST will gather significant information only if the error
situation occurred after the file copying phase of the installation. If you specify the INST Category
parameter, you must also specify one or more component parameters. If you specify the INST Category
parameter, do not specify any of the following:
 Categories other than INST
 Profiles

480
Control-M Utilities Guide

Health Check utility standard category parameters

The following table lists the standard category parameters:

Category Definition

OS Defines the Operating System related physical resource. This information includes the
following:

 Operating System version

 Hardware configuration

 Software, hotfixes and patches installed

 Environment variables and files

 System resources limits

 Kernel parameters

 Swap space

 System and application logs

 Scheduled tasks

 Start up files

 File system information

 ini files (Windows)

 Resource consumption

 List of running processes

 Network settings

 Locate and timezone information

DB Defines the database environment. This information includes the following:

 Database configuration files

 Database size information

 Database logs

 Database check scripts (oracle_check_req, DBUCheck, DBUShow, DBUStatus and

DBUVersion)

NOTE: If you do not specify any Category parameter, the Health Check utility collects data for all Categories.
In general, if you specify a Category, you must also specify one or more components. However, for the following
Categories, do not specify a component:

 OS

 DB
You can also specify multiple Categories. In such a case, for each Category the utility gathers data by each relevant
component specified.

481
Control-M Utilities Guide

Control-M specific categories

The following table describes Control-M Automation specific categories for the Health Check utility.

Category Definition

DBT Collects information from the following Control-M/EM database

folders:
 comm, global_cond, gcs_gtw_recov, gcs_msgs, gcs_dsts,
gcs_admin, confreg, commreg, logreg, params, name_value,
exception_alerts, download
BIM specific additional tables:
 stat_ex_period, stat_ex, dictionary
Forecast specific additional tables:
 time_index, date_index, sim_exception_conditions,
sim_sysstate_ud, sim_sysstate_udtbl, scenario, user_daily_zos

SCH Component scheduling entities measurement. This information

includes the following:
 Number of daily jobs per Control-M
 Number of daily executions per Control-M

TBL Component infrastructure entities measurement. This information

includes sizes of the following tables:
 alarm, comm, global_cond, gcs_gtw_recov gcs_msgs
gcs_dsts, gcs_admin, confreg, commreg, logreg, def_job,
def_folder, download, name_value, audit_activity,
exception_alerts, audit_operations, audit_atributes,
password_history
BIM specific additional tables:
 bim_log, service_log, bim_alert, dictionary

482
Control-M Utilities Guide

Category Definition

CNF Component configuration files. This information includes the

following configuration files:
 Component version (collects the information from
installed-version.txt file located in the <EM_HOME>
directory).
 The list of files under the <EM_HOME> directory.
 Installation_Paramaeters.txt
 CORBA configuration files
 Control-M/EM registry hives export (Windows only)
 LDAP configuration files
 File under <EM_HOME>/ini
 Resource files under <EM_HOME> (*.rsc)
 Self-Service configuration files
 Reporting Facility connection details and templates
 SSL configuration files
 Web-Server version

LOG Component general diagnostic data collection. This information

includes the following:
 All component logs with respect of given days limit (default 2
days)
 A list of the core files created

COM Component functionality, communication, and connectivity. This

information includes the following:
 GUI Server: life check, ping database and check database
 GCS: life check
 Gateway: life check
 Configuration Agent: life check
 BIM: life check
 Forecast: life check
 Self Service: life check

483
Control-M Utilities Guide

Category Definition

MSR Component and environment measurements stored in the

database. This information includes the following:
 MSR_DB – Database performance measurements
 MSR_ENV – Environment measurements (hostname, IP
address, OS Type, OS Version, CPU Type, Number of CPU,
CPU Speed, Total Memory, Swap Space and Timezone).
 MSR_GTW – Gateway measurements (Update Level, Backlog
level, Average Long Update Time, Average Job Update Time
and Average General Update Time).
 MSR_GSR – GUI Server measurements (Pending Updates,
Total Updates, Archive Jobs, Active Jobs, Old Jobs and User
count).

Control-M/Server specific categories

The following table describes the Control-M/Server specific categories for the Health Check utility.

Category Definition

CNF Component configuration files. This information includes the

following configuration files:
 Component version (collects the information from
installed-version.txt file located in the <CTM_HOME>
directory).
 Control-M/Server registry hives export (Windows only)
 Configuration files under <CTM_HOME>/data (*.dat)
 Temporary files under <CTM_HOME>/tmp
 SSL configuration files
 Agent information (CMR_NODES, CMS_AGPRM,
AGENT_DISCOVERY and AGENT_DISCOVERY_ACTIVE)

484
Control-M Utilities Guide

Category Definition

LOG Component general diagnostic data collection. This information

includes the following:
 All component logs (proclog and proclog.save) with respect of
given days limit (default 2 days)
 Memory dump of TR process
 Migration temporary files and logs

TBL Component infrastructure entities measurement. This information

includes sizes of the following tables:
 Database tables size (count)
 Database check
 Database version
 Database recovery information (MSSQL)
 Oracle readiness report (Oracle)

FNC Component function diagnostic data collection. This information

includes the following:
 Agent list
 Dump of CTMLOG
 Count of CMR_DBLOG records
 Check database schema integrity

MSR Component and environment measurements stored in the

database. This information includes the following:
 Primary database performance
 Mirror database performance
 Number of database updates
 Java memory
 Jobs count
 New Day information
 Download information
 System parameters (SYSPRM)

485
Control-M Utilities Guide

Control-M/Agent specific categories

The following table describes Control-M/Agent specific categories for the Health Check utility.

Category Definition

CNF Component configuration files. This information includes the

following configuration files:
 Component version (collects the information from
installed-version.txt file located in the <AG_HOME> directory).
 Control-M/Agent registry hives export (Windows only)
 Configuration files under <AG_HOME>/data
 List of files under home directory

LOG Component general diagnostic data collection. This information

includes the following:
 All component logs (proclog) with respect of given days limit
(default 2 days)
 Content of directories:
BACKUP, ONSTMT, PID, PROCID, SYSOUT, TEMP and
DAILYLOG

UTL Component utilities. This information includes sizes of the

following tables:
 Agent and Application plug in versions
 Agent communication diagnostics
 Java version

486
Control-M Utilities Guide

Category Definition

MSR Component and environment measurements stored in the

database. This information includes the following:
 Number of Jobs ended OK
 Number of Jobs ended Not OK
 Number of “On statement” processing less than 5 seconds
 Number of “On statement” processing 5 to 60 seconds
 Number of “On statement” processing 60 seconds to 10
minutes
 Number of “On statement” processing longer than 10 minutes
 Number of running jobs
 Number of submitted jobs
 Average submit time in seconds
 Average track time in seconds

487
Control-M Utilities Guide

Control-M/Archive specific categories

The following table describes Control-M/Archive specific categories for the Health Check utility.

Category Definition

CNF Component configuration files. This information includes the

following configuration files:
 Component version (collects the information from
installed-version.txt file located in the <EM_HOME>
directory).
 The list of files under the <EM_HOME> directory.
 Installation_Paramaeters.txt
 CORBA configuration files
 Control-M/EM registry hives export (Windows only)
 File under <EM_HOME>/ini
 Resource files under <EM_HOME> (*.rsc)
 SSL configuration files

LOG Component general diagnostic data collection. This information

includes the following:
 All component logs with respect of given days limit (default 2
days)
 A list of the core files created

TBL Component infrastructure entities measurement. This information

includes sizes of the following tables:
 alarm, comm, global_cond, gcs_gtw_recov gcs_msgs
gcs_dsts, gcs_admin, confreg, commreg, logreg, def_job,
def_folder, download, name_value, audit_activity,
exception_alerts, audit_operations, audit_atributes,
password_history

488
Control-M Utilities Guide

Control-M Application plug in categories

The following table describes the Control-M Application plug in categories for the Health Check utility. For
every Application plug in, the configuration and log files are collected.

Category Definition

CNF Component configuration files. This information includes the

following configuration files:
 Component version (collects the information from
installed-version.txt file located in the <AG_HOME> directory).
 Application plug in files from <AG_HOME>/data/<Application
plug in>.dat (for example, e.g. <AG_HOME>/data/OAP*.dat)
 Application plug in registry hives export (Windows only)
 Application plug in specific files (For example OAP collects the
Oracle client version, SAP collects LIBRFC version, etc.)

LOG Component general diagnostic data collection. This information

includes the content of the following directory:
Data files located at <AG_HOME>/cm/<ADD-ON>/data (for
example, <AG_HOME>/cm/OAP/data/*)

489
Control-M Utilities Guide

Control-M specific profile parameters

The following table lists the profile parameters, which is a predefined combination of Components and
Categories.
NOTE: If you specify one or more Profiles, do not specify Components or Categories.

Profile Definition

ENV Collects environment data. This includes information from the following
Categories:
 OS
 DB

EM Collects Control-M data. This includes information from the following

Categories:
 COM
 LOG
 DBT
 SCH
 TBL
 CNF

MSR Collects measurement data. This includes information from the following
Categories:
 MSR_ENV
 MSR_GSR
 MSR_GTW
 MSR_DB

490
Control-M Utilities Guide

Profile Definition

LOG_CGF Collects environment data and Control-M configuration data. This includes
information from the following Categories:
 OS
 DB
 COM
 LOG
 DBT
 SCH
 TBL
 CNF

BIM Collects BMC Batch Impact Manager data. This includes information from the
following Categories:
 COM
 LOG
 DBT
 SCH
 TBL
 CNF

EXPORT_BIM Collects Batch Impact Manager (BIM) data by exporting the active net,
statistics, calendars, global conditions and datacenter relationship.
NOTE: This profile is not included by default and needs to be specifically
included in the command line.

FOR Collects Control-M/Forecast data. This includes information from the

following Categories:
 COM
 LOG
 DBT
 SCH
 TBL
 CNF

491
Control-M Utilities Guide

Profile Definition

ALL Collects data through all Control-M Profiles, as follows:

 ENV
 EM
 BIM
 FOR
 MSR

Control-M/Server specific profile parameters

The following table describes the profile parameters which are a predefined combination of Components
and Categories.
NOTE: If you specify one or more Profiles, do not specify Components or Categories.

Profile Definition

ENV Collects environment data. This includes information from the

following Categories:
 OS
 DB

CTM Collects Control-M/Server data. This includes information from the

following Categories:
 CNF
 LOG
 TBL
 FNC
 MSR_CTM

MSR Collects measurement data. This includes information from the

following Categories:
MSR_CTM

492
Control-M Utilities Guide

Profile Definition

LOG_CFG Collects environment data and Control-M/Server configuration

data. This includes information from the following Categories:
 OS
 DB
 CNF
 LOG
 TBL
 FNC

ALL Collects data through all Control-M/Server Profiles, as follows:

 ENV
 CTM
 MSR
 LOG_CFG
 INST_CTM

493
Control-M Utilities Guide

Control-M/Agent specific profile parameters

The following table describes the profile parameters, which are a predefined combination of Components
and Categories.
NOTE: If you specify one or more Profiles, do not specify Components or Categories.

Profile Definition

ENV Collects environment data. This includes information from the

following Categories:
OS

AG Collects Control-M/Agent data. This includes information from the

following Categories:
 CNF
 LOG
 UTL
 MSR_AG

MSR Collects measurement data. This includes information from the

following Categories:
MSR_AG

LOG_CFG Collects environment data and Control-M/Agent configuration

data. This includes information from the following Categories:
 OS
 CNF
 LOG
 UTL

ALL Collects data through all Control-M/Agent Profiles, as follows:

 OS
 CNF
 LOG
 UTL
 MSR_AG

494
9
9
Database maintenance
The database maintenance utilities can be used to maintain the various Control-M databases and to
import and export information to and from additional databases.
Many of the tasks performed by the database maintenance utilities can also be performed using the
Control-M Configuration Manager 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.
Some of the parameter names changed for Control-M version 8.0.00 and above, terminology from
previous versions is still supported. For a complete list of the parameter names, see Abbreviations and
conventions.
The following sections describe the Control-M/EM and Control-M/Server database and interactive utilities:
 Control-M/EM utilities (on page 496)
 Control-M/Server utilities (on page 544)
 Interactive database utilities (on page 570)

495
Control-M Utilities Guide

Control-M/EM utilities
This table lists the Control-M/EM utilities for database maintenance.

Utility Type Description

db_check (on page 497) The db_check utility provides the following information
about Control-M/EM databases:
 Size of the database
 Availability of space in the database
 Verification of database integrity.
 Automatic database and transaction log monitoring

db_check_space (on page The db_check_space utility provides the following

499) information for Control-M/EM databases that use Oracle
database servers.

em_database_menu (on page Facilitates day-to-day maintenance and diagnostics of

501) Control-M/EM running with PostgreSQL, Oracle and MSSQL
databases.
For maintenance and diagnostics of Control-M/Server
database running with PostgreSQL, Oracle and MSSQL see
dbu_menu (on page 563).

NOTE: You can run many of the utilities interactively, as

described in Interactive database utilities (on page 570).

arc_database_menu (on page The arc_database_menu utility can be invoked interactively

506) to facilitate day-to-day maintenance and diagnostics of
Control-M Workload Archiving running with a PostgreSQL
database.

em_rebuild_database (on page The em_rebuild_database utility can be invoked to rebuild

515) the Control-M/EM database in the specified PostgreSQL
server database.

em_SQL (on page 518) The em_SQL utility enables you to connect to the database
from the command line.

loader (on page 519) The loader utility is used to load default data to the
Control-M/EM database.

sweep (on page 520) The sweep utility deletes jobs that are no longer active
from the Control-M/EM and Control-M/Server databases.

496
Control-M Utilities Guide

Utility Type Description

util (on page 527) Performs the following functions from the command line:
 Export data from the Control-M/EM database
 Import data to the Control-M/EM database
 Delete the Control-M/EM database
 Clear the Control-M/EM database
 Build the Control-M/EM database
 Export a specified definition folder
 Import a specified definition folder
 Import Control-M/Forecast data
 Export Control-M/Forecast data
 Remove Control-M/Forecast data (to save disk space)

db_check
The db_check utility provides the following information about Control-M/EM databases:
 Size of the database
 Availability of space in the database
 Verification of database integrity
 Automatic database and transaction log monitoring
To run the db_check utility, see Running the db_check utility (on page 497).
NOTE: The db_check utility can only be invoked in Control-M/Enterprise Manager. The db_check utility is
not relevant for Windows. It is not available for an Oracle Server.

Running the db_check utility

This procedure describes how to run the db_check utility, which provides information about Control-M/EM
databases.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed.
2. Enter the following command:

497
Control-M Utilities Guide

db_check [-d <dbThreshold%>] [-l <logThreshold%>] [-p <password>] [-n] [-h]

NOTE: The user name is derived from the $EM_USER environment variable.
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on db_check utility, see db check utility parameters (on page 498) and db_check utility example (on page
498).

db check utility parameters

The following table describes the db_check utility parameters:

Parameter Description

-d <dbThreshold%> Maximum percentage of database use. When this percentage is

exceeded, a message is displayed alerting you to extend the
database.
NOTE: The -d must be lowercase.

-l <logThreshold%> Maximum percentage of transaction log use. When this percentage

is exceeded, a message is displayed alerting you to extend the
transaction log.
NOTE: The -l must be lowercase.

-p <password> Password for the Control-M/EM administrator. If not specified, you

are prompted to supply this information when the utility runs.
NOTE: The -p must be lowercase.

-n When -n is specified, db_check is executed without verifying the

total database integrity.
NOTE: The -n must be specified in lowercase.

-h When -h is specified, db_check displays the amount of database

space that is in use.
NOTE: The -h must be specified in lowercase.

db_check utility example

The following is an example of the db_check utility:
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.

498
Control-M Utilities Guide

The db_check utility is not relevant for Windows and works only with databases on a Sybase Adaptive
server. This utility is not available for Oracle server.

db_check_space
The db_check_space utility provides the following information for Control-M/EM databases that use Oracle
database servers.
 Total size and availability of space in the /tmp directory
 Total size and availability of space in the database
 Percentage of total space in the database that is currently available
NOTE: The db_check_space utility cannot be used for Oracle database client installations and is not
relevant for Windows. The db_check_space utility can only be invoked in Control-M/Enterprise Manager.
To run the db_check space utility, see Running the db_check_space_utility (on page 499).

Running the db_check_space_utility

This procedure describes how to run the db_check_space utility, which provides information for
Control-M/EM databases that use Oracle database servers.

 To run the utility:

1. Log on to a Control-M/EM account.
2. Do the following:
• When prompted by the utility interactively, specify the Oracle administrator as the user name.
• Enter the following command to specify the appropriate Control-M/EM UNIX user account and
password using the -U and -P parameters in the command line:
db_check_space [ -U <userName> [ -P <password> ] ]
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the db_check_space utility, see db_check_space utility parameters (on page 500) and db_check_space
utility example (on page 500).

499
Control-M Utilities Guide

db_check_space utility parameters

The following table describes the db_check_space utility parameters:

Parameter Description

-U <userName> User name. If not specified in the command line, you are prompted to
provide this information when the utility runs.

 The -U must be specified in uppercase.

 If you intend to specify the -P parameter when running the utility,
you must also specify the -U parameter.

-P <password> Password. If not specified in the command line, you are prompted to
provide this information when the utility runs.

 The -P must be specified in uppercase.

 If you intend to specify the -P parameter when running the utility,
you must also specify the -U parameter.

This utility is also available from the root menu by selecting the 2 - Troubleshooting Menu option and then
the 1 - Database Troubleshooting option. For more information, see Control-M diagnostics.

db_check_space utility example

The following is an example of db_check_space utility output:
Oracle server
+------------------------------------------+
+ Space Information ( /tmp of the machine) +
+------------------------------------------+
Total Size: 2048000 KB. Space Available: 366430 KB 17 % Free
+------------------------------------+
| ORACLE Size Information: |
+------------------------------------+
db total = 276480.0 KB
data used = 25296 KB (9%).\

500
Control-M Utilities Guide

em_database_menu
The em_database_menu utility can be invoked interactively to facilitate day-to-day maintenance and
diagnostics of Control-M/EM database running with PostgreSQL, Oracle and MSSQL databases. On
Windows, the utility is called em_database_menu.bat.
NOTE: The Database Utilities Menu is only relevant for PostgreSQL, Oracle and MSSQL database
functionality.
To facilitate day-to-day maintenance and diagnostics of Control-M/Server database running with
PostgreSQL, Oracle and MSSQL databases, use the dbu_menu utility, as described in dbu_menu (on page
563).
The Database Utilities menu and the resulting sub-menus are described in the following:
 Accessing the Database Utilities Menu (on page 503)
 Database Utilities Menu using Oracle
 Database Utilities Menu using MSSQL
The sub-menus and certain options from the em_database_menu utility can be invoked from the
command line. For database menu options see em_database_menu options (on page 502).

501
Control-M Utilities Guide

em_database_menu options
The following table describes the utilities with the related options from the em_database_menu:

Utility em_database_menu sub-menu or option

Database Utilities Menu

dbu_menu Database Utilities Menu

Maintenance Menu options (on page 504)

DBUUpdateStatistics Update database Statistics

DBUColdBackup Cold Database Backup

DBUColdRestore Cold Database Restore

DBUBuild Build Database option in the Database Creation Menu

Report Menu options (on page 505)

DBUStatus Database Status

DBUShow Database Parameters

DBUStorage Database Storage Report

DBUVersion Database Version

DBUTransactions List All Active Transactions

502
Control-M Utilities Guide

Accessing the Database Utilities Menu

This procedure describes how to access the Database Utilities menu.

 To access the Database Utilities Menu:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
2. Open a command prompt as an Administrator and type the following command:
em_database_menu
The Database Utilities Menu is displayed:
Select one of the following options:
1 - Maintenance
2 - Report
q - quit
Enter option number ---> [q]:
The options available in the Database Utilities Menu enable you to access the following sub-menus:
• Maintenance Menu options (on page 504)
• Report Menu options (on page 505)
Within these sub-menus are a variety of functions used to maintain the Control-M database.

503
Control-M Utilities Guide

Maintenance Menu options

The following table lists the Maintenance Menu options:

Option Database Description

Update Database  PostgreSQ Activates statistic procedures in the database server.

Statistics L
(DBUUpdateStatistics  MSSQL
)
 Oracle

Build Database  PostgreSQ Creates a Control-M/EM schema on the database server.

L
(DBUBuild)
 MSSQL
 Oracle

Cold Database  PostgreSQ Exports the Control-M/EM database schema to the specified file.
Backup L
The following Control-M/EM components must be shut down prior to activating
(Running the  MSSQL this backup:
DBUColdBackup utility
(on page 571))
 Gateway
 GUI server
 BMC Batch Impact Manager
 Control-M/Forecast
 Global Conditions Server
 Control-M Configuration Management Server
 Control-M Configuration Agent
Backup File: Full path to the file into which the database should be backed up.
Administrator password: Password of the database server administrator.

Cold Database  PostgreSQ Imports the Control-M/EM database schema from the file specified in Backup Fil
Restore L parameter of the Cold Database Backup option.
(Running the  MSSQL NOTE: This option is not enabled if Control-M database server is running.
DBUColdRestore utility
Restore File: Value and location specified in the Backup File parameter of the
(on page 572))
Cold Database Backup option.
Administrator password: Password of the database server administrator.

Extend database Oracle (Oracle and MSSQL only) Extends the database size. Contact your DBA for
assistance in performing this action if you are not comfortable performing it
MSSQL
yourself.

504
Control-M Utilities Guide

Report Menu options

The following table lists the Report Menu options.

Option Database Description

Database Status  PostgreSQL Displays various server and client details.

(DBUStatus (on page 578))  MSSQL  DB Type
 Oracle  Is Up
 Is Remote DB
 Last Startup Time
 DB Server OS Version
 DB Server Host Name
 DB Server OS Type
 DB Server Archive Directory
 DB Server Port
 DB Client OS Version
 DB Client Host Name
 DB Client OS Type
 DB Server Version
 DB Client Version

Database Parameters  PostgreSQL Control-M/EM: Displays the configuration parameters of the server
(Running the DBUShow utility database and the Control-M/EM database client.
(on page 584))  MSSQL
Control-M/Server: Displays the configuration parameters of the Server
 Oracle database and the Control-M/Server database client.
NOTE: Configuration parameters are sorted alphabetically.

505
Control-M Utilities Guide

Option Database Description

Database Storage Report  PostgreSQL Control-M/EM: Displays the attributes of the Control-M/EM database in
the server database.
(DBUStorage (on page 581))  MSSQL
Control-M/Server: Displays the attributes of the Control-M/Server
 Oracle database in the Server database
 DB Name
 Type
 Size (refers to the operating system disk space)
 Free
 Used
 Used percentage
 Message (Warns the user when there is diminished disk space
capacity within the Control-M/EM database server)

Database Version  PostgreSQL Displays the general description of the database server, and includes the
version number.
(Running the DBUVersion  MSSQL
utility (on page 577))
 Oracle

List All Active  PostgreSQL List all active transactions of the Control-M/EM or Control-M/Server
Transactions database for the database user.
 MSSQL
(Running the
DBUTransactions utility (on  Oracle
page 582))

Consistency Check  MSSQL Checks tables in the database. Run this option when you suspect that
there is database corruption.
 Oracle

arc_database_menu
The arc_database_menu utility can be invoked interactively to facilitate day-to-day maintenance and
diagnostics of Control-M Workload Archiving running with PostgreSQL database.
NOTE: On Windows, the utility is called arc_database_menu.bat.
The Database Utilities menu and the resulting sub-menus are described in arc_database_menu options
(on page 507).

506
Control-M Utilities Guide

arc_database_menu options
The following table describes the utilities with the related options from the arc_database_menu:

Utility arc_database_menu sub-menu or option

Database Utilities Menu

arc_database_menu Workload Archiving database Utilities Menu

Workload Archiving Management Menu options (on page 509)

DBUStart Start database

DBUStop Stop database)

DBUBuild Build Database option in the Database Creation Menu

DBUArchive Set database archive mode

Workload Archiving Maintenance Menu options (on page 511)

DBUMaintain Update database statistics

DBUColdBackup Cold Database Backup

DBUHotBackup Hot Database Backup

DBUHotRestore Hot Database Restore

DBUColdRestore Cold Database Restore

Workload Archiving Report Menu options (on page 514)

DBUStatus Database Status

DBUShow Database Parameters

DBUStorage Database Storage Report

DBUVersion Database Version

DBUTransactions List All Active Transactions

507
Control-M Utilities Guide

Accessing the Database Utilities Menu using PostgreSQL

This procedure describes how to access the Database Utilities menu.

 To access the Database Utilities Menu:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window as Administrator where Control-M/EM is installed.
You do not need to be in the Control-M/EM database directory.
2. Type the following command:
arc_database_menu
The Database Utilities Menu appears:
3. Press one of the following options and then press Enter:
• 1 - Management
• 2 - Maintenance
• 3 - Report
• q - quit
Enter option number ---> [q]:
The options available in the Database Utilities Menu enable you to access the following sub-menus:
• Workload Archiving Management Menu options (on page 509)
• Workload Archiving Maintenance Menu options (on page 511)
• Workload Archiving Report Menu options (on page 514)
Within these sub-menus are a variety of functions used to maintain the Control-M Workload Archiving
database.

508
Control-M Utilities Guide

Workload Archiving Management Menu options

The following table lists the options in the Management Menu.

Option Description

Start Database Only enabled when Control-M Workload Archiving is running

with a dedicated database server.
Starts the database server, and services involved. This option is only
enabled on Control-M Workload Archiving running with a dedicated
PostgreSQL database server.
NOTE: If this option is invoked on Control-M Workload Archiving running
with an existing database, an error message is displayed.

Stop Database Only enabled when Control-M Workload Archiving is running

with a dedicated database server.
Stops the database server, and services involved. This utility is only
enabled on Control-M Workload Archiving running with a dedicated
PostgreSQL database server.
Force: A parameter that enables you to abort the database server
processes and listener.
Valid values:
 Y
 N (default).
NOTE: If this option is invoked on Control-M Workload Archiving running
with an existing database, an error message is displayed.

Set Database Only enabled when Control-M Workload Archiving is running

Archive Mode with a dedicated database server.
Changes the archive mode of the database server.
Parameters available:
Mode
 On
 Off (default)
Archive Directory (only available when Mode is ON)
Full directory path to which the database server logs are archived.
NOTE: This directory should be empty. When Archive mode is On, the
Hot Database Backup option is enabled.
Passwords: Database Owner, Database server administrator

509
Control-M Utilities Guide

Option Description

Build Database Creates a Control-M Workload Archiving schema on the database server.
NOTE: This option is only enabled on Control-M Workload Archiving
running with either an existing or a dedicated database server.
Passwords: Database Owner, Database server administrator

510
Control-M Utilities Guide

Workload Archiving Maintenance Menu options

The following table lists the Maintenance Menu options:

Option Description

Update database Activates statistic procedures in the database server.

statistics
Passwords: Database Owner, Database server administrator

Hot Database Backup Only enabled when:

 Database Archive Mode is set to On
 Control-M Workload Archiving is running with a
dedicated database server.
Online backup of the database server file system, and the
Control-M Workload Archiving database. This can be used to
restore the database up to and including the last completed
transaction.
Parameters available:
Backup Directory
Full path to the directory into which the server file system and
Control-M Workload Archiving database must be backed up.
This directory must be empty.
Passwords: Database Owner, Database server administrator

Cold Database Backup Exports the Control-M Workload Archiving database schema to
the specified file.
Parameters available:
Backup File
Full path to the file into which the database must be backed up.
Passwords: Database Owner, Database server administrator
NOTE: This option is not enabled if Control-M Workload
Archiving server is running.

511
Control-M Utilities Guide

Option Description

Hot Database Restore NOTE: Only enabled when Control-M Workload Archiving is
running with a dedicated database server.
Online restore of the PostgreSQL database server file system and
the Control-M Workload Archiving database. When this option
completes successfully, the previous PostgreSQL database server
file system is saved to the following location:
<pghome_directory/old_pgsql_<date of operation>
If Control-M Workload Archiving database does not exist in the
<pghome_directory> it is saved in the following location:
<db location>/<db name>_old_<date of operation>
NOTE: This option is not enabled if the Control-M Workload
Archiving database server is running.
Parameters available:
Restore Directory
Full path to the directory from which the server file system and
Control-M Workload Archiving databases must be restored.
Archive Directory
Value and location specified in the Archive Directory parameter of
the Set Database Archive Mode option.
NOTE: When this action is finished successfully, the PosgreSQL
database server archive mode switches to off, and the
PosgreSQL database server shuts down.
NOTE: The specified directory must be exported from the
PostgreSQL database server with the same parameter values as
the destination PostgreSQL database server.

512
Control-M Utilities Guide

Option Description

Cold Database Imports the Control-M Workload Archiving database schema from
Restore the file specified in Backup File parameter of the Cold Database
Backup option.
NOTE: This option is not enabled if Control-M Workload
Archiving server is running.
Parameters available:
Restore File
Value and location specified in the Backup File parameter of the
Cold Database Backup option.
Passwords: Database Owner, Database server administrator

513
Control-M Utilities Guide

Workload Archiving Report Menu options

The following table lists the Report Menu options:

Option Description

Database Status Displays various server and client details.

 DB Type
 Is Up
 Is Remote DB
 Last Startup Time
 DB Server OS Version
 DB Server Host Name
 DB Server OS Type
 DB Server Archive Directory
 DB Server Port
 DB Client OS Version
 DB Client Host Name
 DB Client OS Type
 DB Server Version
 DB Client Version
Passwords: Database Owner, Database server
administrator

Database Parameters Displays the configuration parameters of the server database

and the Control-M Workload Archiving database client.
Configuration parameters are sorted alphabetically.
Passwords: Database Owner, Database server
administrator

514
Control-M Utilities Guide

Option Description

Database Storage Report Displays the following attributes of the Control-M Workload
Archiving database in the server database:
 DB Name
 Type
 Size (refers to the operating system disk space)
 Free
 Used
 Used percentage
 Message (Warns the user when there is diminished disk
space capacity within the Control-M Workload Archiving
database server)
Passwords: Database Owner, Database server
administrator

Database Version Displays the general description of the database server. This
includes the version number.
Passwords: Database Owner, Database server
administrator

List All Active List all active transactions of the Control-M Workload
Transactions Archiving database for the database user.
Passwords: Database Owner, Database server
administrator

em_rebuild_database
The em_rebuild_database utility can be invoked to rebuild the Control-M/EM database in the specified
PostgreSQL server database.
On Windows, the utility is called em_rebuild_database.bat.
If the new DBO is different than the original DBO, you need to use the original DBO to log into
Control-M/EM client components until the new DBO is added to the Authorizations list with all required
permissions.
To run the em_rebuild database utility, see Running the em_rebuild_database utility (on page 515)

Running the em_rebuild_database utility

This procedure describes how to run the em_rebuild_database utility, which can be invoked to rebuild the
Control-M/EM database in the specified PostgreSQL server database.

515
Control-M Utilities Guide

 To run the em_rebuild_database utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window as Administrator where Control-M/EM is installed.
You do not need to be in the Control-M/EM database directory.
2. Type the following command:
em_rebuild_database
3. Follow the prompts in the interactive menu that is displayed.
Host Interface Name []:
Port Number []:
Database Administrator Password:
Database Owner Login []:
Database Owner Password:
Database Name []:
Database Directory Full Path []:
Encoding [LATIN1]:
Existing Database [N]:
Building the database.
Please confirm [Y/N]:
For more information on the em_rebuild_database utility, see em_rebuild_database utility parameters (on
page 517).

516
Control-M Utilities Guide

em_rebuild_database utility parameters

The following table describes the em_rebuild_database utility parameters.

Parameters Description

Host Interface Name of the host computer for the PostgreSQL database server on which
Name Control-M/EM is installed.

Port Number Communications port on which the PostgreSQL database server listens
for queries.

Database Password of the PostgreSQL database server administrator. The

Administrator characters you enter are not echoed for security reasons.
Password

Database Name of the Control-M/EM database owner.

Owner Login

Database Password for the Control-M/EM database owner (6 to 30 characters,

Owner alphanumeric). The characters you enter are not echoed for security
Password reasons.

Database Name for the Control-M/EM database. This name must be unique within
Name the PostgreSQL database server.

Database Location of the Control-M/EM database owner.

Directory Full
NOTE: You must create this location prior to installing the Control-M/EM
Path
database.
Relevant only for the PostgreSQL database server on UNIX.

Encoding Language encoding of the Control-M/EM database.

Valid values:
 LATIN1 (default)
 UTF8
NOTE: If you select UTF8, you need to manually configure the
environment settings to enable Control-M/EM components to support this
encoding.

Existing Valid values:

Database
 Y —This value indicates that the Control-M/EM database is defined
on a remote PostgreSQL database server.
 N —This value indicates that the Control-M/EM database is defined
on the local PostgreSQL database server.

517
Control-M Utilities Guide

em_SQL
The em_SQL utility enables you to connect to the database from the command line. This utility is
automatically installed on Windows computers during installation of the GUI Server component. To run
the em_SQL parameter, see Running the em_SQL utility (on page 518).

Running the em_SQL utility

This procedure describes how to run the em_SQL utility, which enables you to connect to the database
from the command line.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window as Administrator where Control-M/EM is installed.
You do not need to be in the Control-M/EM database directory.
2. Type the following command:
em_SQL -U <userName> -P <password>
NOTE: SQL, U, and P must be specified in uppercase.
For more details on the em_SQL utility see em_SQL utility parameters (on page 518).

em_SQL utility parameters

The following table describes the em_SQL utility parameters:

Parameter Description

-U <userName> User name.

NOTE: The U must be specified in uppercase.

-P <password> Password.
NOTE: The P must be specified in uppercase.

518
Control-M Utilities Guide

loader
The loader utility is used to load default data to the Control-M/EM database. This utility should only be
used if you ran a clean database operation and want to restore default data to the folders. To run the
loader utility see Running the loader utility (on page 519).

Running the loader utility

This procedure describes how to run the loader utility, which is used to load default data to the
Control-M/EM database.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
2. Type one of the following commands:
o UNIX
em loader [-d <directory> | -f <fileName>] [-u <userName> [-p
<password>] [-db <databaseName>] [-append] [-erase] [-diagon] [-h]
o Windows
loader [-d <directory> | -f <fileName>] [-u <userName> [-p <password>]
[-db <databaseName>] [-append] [-erase] [-diagon] [-h]
For more details on the loader utility, see loader utility parameters (on page 520).

519
Control-M Utilities Guide

loader utility parameters

The following table describes the loader utility parameters:

Field Description

-d <directory> The directory in which the files with the default data is located.

-f <fileName> The full path of the file in which the loaded data is saved.

-u <userName> Database user name. Optional

-p <password> Database user password. Optional

-db The name of the database to which you want to load the data.
<databaseName> Optional

-append Append the data to the information that already exists.

-erase Erase the data that already exists.

-diagon Displays the loader utility information on your screen.

-h Displays the loader utility usage.

sweep
The sweep utility deletes jobs that are no longer active from the Control-M/EM and Control-M/Server
databases. These jobs are referred to as obsolete jobs and are defined in Obsolete criteria (see
below).The sweep utility is available in Control-M/EM installations only. To run the sweep utility, see
Running the sweep utility (on page 520).
For reports that are generated by the sweep utility, see Utility reports (on page 523).
For return codes see Return codes (on page 525)
To see the criteria used by the sweep utility to determine whether a job or folder is obsolete, see
Obsolete criteria (on page 525).

Running the sweep utility

This procedure describes the sweep utility, which deletes jobs that are no longer active from the
Control-M/EM and Control-M/Server databases.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.

520
Control-M Utilities Guide

• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
2. Type the following command:
o (Windows)
sweep [-U <userName> -P <password> | -PF <passwordFile>]
-S <serverName> [-Local] [-Date <YYYYMMDD>]
[-Test | -Sync] [-Timeout <maxSeconds>]
[-Cyclic <maxFiles>] [-H | -Help] [-Force]
[-Interval <milliseconds>]
o (UNIX)
em sweep [-U <userName> -P <password> | -PF <passwordFile>] -S
<serverName> [-Local] [-Date <YYYYMMDD>] [-Test | -Sync] [-Timeout
<maxSeconds>] [-Cyclic <maxFiles>] [-H | -Help] [-Force] [-Interval
<milliseconds>]
The parameters are described in the following table. The flags are not case sensitive.
3. Press Enter.
The parameters are processed and several reports are generated.
Avoid updating of the job or folder definitions when the sweep utility is running.
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the sweep utility, see sweep utility parameters (on page 522).

521
Control-M Utilities Guide

sweep utility parameters

The following table describes the sweep parameters:

Parameter Description

-U userName Control-M/EM database user name

Log on is achieved by providing either a user name and password
combination or a password file name.

-P password Control-M/EM database user password

-PF Flat file that contains an unencrypted user name and password on
passwordFile separate lines in the following format:
user=user_name
password=password

-S serverName Control-M/EM GUI server logical name

-Local Deletes all obsolete jobs and folders from the Control-M/EM database
only.
 You cannot use the -Sync and -Test flags when using -Local.
 You can use -Local and -Force to delete obsolete jobs and folders
from modified or locked folders in the Control-M/EM database.
Log sweep_sync.txt is not updated when the utility is activated with
-Local.
If -Local is not used, the sweep utility behaves as it did before version
6.3.01, deleting jobs from both the Control-M/EM and Control-M/Server
databases.

-Date A date in YYYYMMDD format (for example, 20080915), which sets the
YYYYMMDD selection criteria for obsolete jobs. Default: two days before the current
date date

-Timeout Maximum time in seconds to wait for pending callbacks to return with
maxSeconds responses to UPLOAD and remote DELETE requests. Default: 900 seconds
(15 minutes).

-Test This flag causes the sweep utility to scan all job definitions and generate
the sweep_obsolete.txt file, which consists of a report of the current
obsolete jobs and folders, without actually deleting the jobs.

-Sync A flag for synchronizing all non-synchronized folders, listed in the

sweep_sync.txt file, by rerunning the commands that previously failed,
in order to synchronize the Control-M and EM databases.

522
Control-M Utilities Guide

Parameter Description

-Cyclic maxFiles The maximum number of cyclic files for sweep execution log (up to 500
messages each). Default: The execution log is written to one sequential
log file without a timestamp.

-H | -Help Displays the usage.

-Force This flag causes the sweep utility to scan all folders, including those that
are modified or locked, for obsolete jobs. Use -Force only when you are
certain there are no definitions in the Control-M/Server database that were
not previously downloaded into the Control-M/EM database.

-Interval This flag sets the time to wait between executing the DELETE and
milliseconds UPLOAD commands (in milliseconds).
It may be required to avoid time-out problems in Gateway or Control-M.
By default, there is no interval.

Utility reports
The reports that are generated by the sweep utility are described in the following table:

File Name Location Description

sweep_obsolete.tx $HOME/sweep Report of all jobs and folders that are

t candidates for deletion according to the
date criteria.

sweep_sync.txt $HOME/sweep Report of all folders that could not be

uploaded to or deleted from the
Control-M/Server (either because of a
failure or a time-out) and therefore are
not currently synchronized.

sweep_log.txt $HOME/log Execution log (which is cyclic and

configurable).

In the sweep_obsolete.txt file, the report for obsolete jobs has the following format:
delete job folder_id job_id ctm_name folder_name job_name mem_name
In the sweep_obsolete.txt file, the report for obsolete folders has the following format:
delete folder folder_id ctm_name folder_name folder_lib

523
Control-M Utilities Guide

The MaxObsoleteJobs system parameter controls the size of the GUI Server memory by limiting the
number of obsolete jobs stored in the GUI Server. The default value is 100000.This parameter should only
be changed after consulting with BMC Customer Support.
In the sweep_sync.txt file, the report for non-synchronized folders has the following format:
upload folder folder_id ctm_name folder_name folder_lib
Only the last versions of the sweep_obsolete.txt and sweep_sync.txt reports are saved.

sweep utility work flow example

The following example describes typical work flow for the sweep utility:
1. Activate the sweep utility with the –Test parameter to generate the sweep_obsolete.txt file, which
is essentially a report listing the obsolete jobs and folders.
2. Check the sweep_obsolete.txt file and decide if you want to delete the jobs and folders displayed
in the report.
3. Activate the sweep utility without the –Test parameter to delete the obsolete jobs and folders from
the Control-M/EM and Control-M/Server databases.
4. Check the sweep_sync.txt file to find failures that occurred while the sweep utility was attempting
to upload or delete folders.
5. Check the sweep_log.txt file to understand the reason for the failures and perform the necessary
corrections.
6. Activate the sweep utility with the –Sync parameter to upload or delete the folders that were not
successfully uploaded or deleted in the previous run.
7. Check the sweep_sync.txt file to check that there are no more failures.

Prepare a report of obsolete jobs example

The following command specifies that the sweep_obsolete.txt file, containing a list of obsolete jobs, is
generated according to the obsolete date of September 15, 2016:
sweep.exe -U emuser -P empass -S TLVW2K366 -Test -Date 20160915

Delete obsolete jobs from the database example

The following command specifies that any job from two days ago is considered obsolete and is being
deleted from the database:
sweep.exe -U emuser -P empass -S TLVW2K366

524
Control-M Utilities Guide

Return codes
The following table describes Sweep utility return codes:

Return
code Description

0 Success (all of the obsolete jobs were deleted, however there may be
commands in the sync file that must be run later). If necessary, run the
sweep utility again.

1 Failure. Run the sweep utility again.

2 Partial success (some obsolete jobs were not deleted). Run the sweep utility
again to delete the remaining jobs or folders.

Obsolete criteria
The following describes the criteria used by the sweep utility to determine whether a job or folder is
obsolete.
If the ACTIVE_TILL parameter is specified the following elements are considered as obsolete:
 A regular job, which is not part of a SMART Folder, is considered as obsolete if the following is true:
ACTIVE_FROM < ACTIVE_TILL and ACTIVE_TILL < obsolete date.
 A RBC is considered as obsolete if:
ACTIVE_FROM < ACTIVE_TILL and ACTIVE_TILL < obsolete date.
 A SMART Folder is considered as obsolete if:
All of its RBCs are obsolete (the relationship between the RBCs is always OR).
 A regular folder is considered obsolete if:
All the jobs in the folder are obsolete.
 A job that is part of a SMART Folder is defined as obsolete if one of the following conditions is true:
• the SMART Folder is obsolete
• it satisfies the obsolete criteria according to it own ACTIVE_TILL/ACTIVE_FROM and has no RBCs

525
Control-M Utilities Guide

• it has RBCs and is considered as obsolete according to the following table:

Job (ACTIVE_TILL/ RBC (ACTIVE_TILL/

Relationship ACTIVE_FROM) ACTIVE_FROM) Result

AND Obsolete Obsolete Delete job

AND Obsolete Active Delete job

AND Active Obsolete Delete job

AND Active Active Job is active

OR Obsolete Obsolete Delete job

OR Obsolete Active Job is active

OR Active Obsolete Job is active

OR Active Active Job is active

AND Not defined Obsolete Delete job

AND Not defined Active Job is active

OR Not defined Obsolete Job is active

OR Not defined Active Job is active

Obsolete criteria examples

This following are examples of how the sweep utility applies the obsolete criteria to determine whether
various jobs are obsolete.
The following values apply to all examples in this section:
 SMART Folder G has the following two RBCs:
• RBC A: ACTIVE_FROM Not defined; ACTIVE_TILL September 12, 2016
• RBC B: ACTIVE_FROM September 11, 2008; ACTIVE_TILL October 28, 2016
 The obsolete day of the user is September 20, 2016.
For the obsolete day of the user, RBC A is obsolete and RBC B is active, according to the above.
EXAMPLE 2:
Job 1 belongs to SMART Folder G and has RBC A. ACTIVE_FROM is not defined for Job 1.
ACTIVE_TILL is defined for Job 1 for October 1, 2016. The relationship between Job 1 and its RBCs is
AND.

526
Control-M Utilities Guide

Result: Job 1 is obsolete.

EXAMPLE 3:
Job 2 belongs to SMART Folder G and has RBC B.
ACTIVE_FROM and ACTIVE_TILL are not defined.
The relationship between Job 2 and its RBCs is OR.
Result: Job 2 is active.
EXAMPLE 4:
Job 3 belongs to SMART Folder G and has RBCs A, B, and C.
RBC C was deleted from SMART Folder G, but Job 4 still has it.
ACTIVE_FROM and ACTIVE_TILL are not defined.
The relationship between Job 3 and its RBCs is AND.
Result: Job 3 is active, while RBC C is ignored.
General notes
The following notes may be applicable to the features described in this section:
 The sweep utility searches for obsolete jobs and folders on the Control-M/EM side only. It does this by
scanning the Control-M/EM database. Any obsolete jobs or folders that are found are deleted from
both the Control-M/EM and the Control-M/Server databases. It is therefore recommended that the
folders are synchronized in the Control-M/EM and Control-M/Server databases before activating the
sweep utility.
 The sweep utility supports only Control-M for z/OS versions 6.1.00 and 6.2.00.
 To delete obsolete folders or jobs a user requires FULL permissions for the specific folder.
 If you want to override any CORBA default parameters for the sweep utility, make the changes under
"Sweep" in the CORBA configuration file ($HOME/etc/domains/config.xml).

util
util is a multi-purpose utility that can perform the following functions from the command line:
 Import and export data to and from the Control-M/EM database
 Delete, clear, and build the Control-M/EM database
 Import and export a specified definition folder
 Import, export, and remove (to save disk space) Control-M/Forecast data
When version management mode is selected (default), the following additional functions are available
from the command line:
 Export or import of scheduling definitions, either with or without the history of changes made
 Export or import of a specified definition folder, either with or without the history of changes made
All the functions use DB_ARGS in the following format:

527
Control-M Utilities Guide

[-D <database>][{-U <user> -P <password>} |-pf <fileName>]

[-S <server>][-T <level>] [-dbms <system>][-dbtimeout <sec>]
[-dbfile <path>]
For more information about DB_ARGS database arguments, see DB_ARGS database arguments fields (on
page 529).
For Functions and syntax of the util utility (UNIX), add em and a space before specifying util. For
example: em util <DB_ARGS> <buildSchema> [-cdbg {1 - 5}][-T 3]
The following topics describe how to run the utility, functions, configuration and parameters:
 Running the util utility (on page 528).
 util utility functions (on page 530)
 util utility function parameters (on page 534)
 To configure the util utility to recognize different delimiters, see Configure the util utility to recognize
different delimiters (on page 537)
NOTE: The util utility is automatically installed on Windows computers with the Control-M/EM Gateway
component. For more information about version management, see Using Control-M.

Running the util utility

This procedure describes how to run the util utility, which enables you to perform various function on the
Control-M/EM database. for more information, see util (on page 527).

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed. You do not need
to be in the Control-M/EM database directory.
2. Type one of the following commands:
• On Windows
util DB_ARGS function functionParameters
• On UNIX
em util DB_ARGS function <functionParameters>
For the Control-M parameter name, see Parameter name cross references (on page 31).

528
Control-M Utilities Guide

DB_ARGS database arguments fields

The following table describes the DB_ARGS database arguments fields:

Field Description

-U <user> Database user name

-P <password> Database user password

-T <level> Database debug level (Valid values are in the range: 1 - 9).

529
Control-M Utilities Guide

util utility functions

The following table describes the util utility functions:

Function Description

-export Exports job processing definitions, such as calendars, Control-M data, etc
from the Control-M/EM database to an ASCII text file.
The data in the mentioned file is separated by field and record delimiters.
For more information, see Configure the util utility to recognize different
delimiters (on page 537).
Usage: Specify the following command:
util <DB_ARGS> -export [-silent] [-cdbg <1 - 5>] {-type
<all | def | cal | sys |dc | user | alert | gc | maint
| collect | view |filter | report | hier | audit |
history | bim_forecast | statistics | workload |
active_nets | mft | [wcm]>} {-type net {-name
{<name>}}} [-file <file> | -file - | -dir <dir>]
[-without_def_history]
NOTE: If the database is exported to a file, you are prompted for a
filename. The file that is created is a flat file.
 If you use FTP to transfer the exported file, use binary mode.
 If -type all is specified, the job’s running information history is not
returned. Specify -type history separately if it is required.
 -type def includes site standard and site customization definitions.
 If -without_def_history is specified, only the current version of the
job’s definition is exported. This option is relevant when version
management mode is selected (default). For more information, see
Using Control-M.

530
Control-M Utilities Guide

Function Description

-import Imports job processing definitions, such as calendars, Control-M data,

etc, from an ASCII text file to the Control-M/EM database.
The data in the mentioned file is separated by field and record delimiters.
For more information, see Configure the util utility to recognize different
delimiters (on page 537).
Usage: Specify the following command:
util <DB_ARGS> -import [-silent] [-replace] [-cdbg
{1-5l}] {-type <all | def | cal | sys |dc | user | alert
|gc | maint | collect | view |filter | report | hier
| audit |history | bim_forecast | statistics | workload
| active_nets | mft | wcm>>} {-type net {-name
{<name>}}} [-file <file> | -file - | -dir <dir> | -dir
<fileList>] [-without_def_history]
NOTE:
 If the database is imported from a file, you are prompted for a
filename. Only .exp files are accepted.
 If you use FTP to transfer the imported file, use binary mode.
 Stop all Control-M/EM components before doing this operation.
 If -type all is specified, the job’s running information history is not
returned. Specify -type history separately if it is required.
 -type def includes site standard and site customization definitions.
 If -without_def_history is specified, only the current version of the
job’s definition is imported. This option is relevant when version
management mode is selected (default). For more information, see
Version management
Gateway(s) should not be running.
If -replace is specified, your data may be destroyed. Use -replace with
extreme caution. Any database element that is replaced is overwritten
with data that you supply in the input file. If -replace is not specified and
the database attempts to write data that already exists, the utility
terminates and a rollback is performed on data written during the write
operation.

-delete Deletes the specified database folder.

Usage: Specify the following command:
util <DB_ARGS> -delete [-silent] [-cdbg {1-5}]{-name
{<name>}}
NOTE: Stop all Control-M/EM components before doing this operation.

531
Control-M Utilities Guide

Function Description

-clean_database Deletes all database folders.

Usage: Specify the following command:
util <DB_ARGS> -clean_database [-silent] [-cdbg <1-5>]
NOTE:
 Stop all Control-M/EM components before doing this operation.
 This utility completely deletes database folders. Use it only with
extreme caution. BMC recommends that you backup the database
before issuing this command.

-build_schema Builds the Control-M/EMdatabase. It defines the structure and the type of
contents of each data element in the database.
Usage: Specify the following command:
util <DB_ARGS> -build_schema [-cdbg <1-5>]
NOTE:
 Stop all Control-M/EM components before doing this operation.
 To load default data to the Control-M/EM database, run the loader
utility.

532
Control-M Utilities Guide

Function Description

-defexport Exports the specified definition folder to an ASCII text file.

The data in the mentioned file is separated by field and record delimiters.
For more information, see Configuring the util utility to recognize different
delimiters below.
Usage: Specify the following command:
util <DB_ARGS> -defexport [-cdbg <1-5>] -table
<outermost folder name> -dcname <newDc> [-library
<newLibrary>] -file <file> [-without_def_history]
NOTE:
 If the database is exported to a file, you are prompted for a file
name.
 If you use FTP to transfer the exported file, use binary mode.
 -type def includes site standard and site customization definitions.
 If -without_def_history is specified, only the current version of the
definition folder is exported. This option is relevant when version
management mode is enabled (default). For more information, see
the Using Control-M.

-defimport Imports the specified Control-M/EM database definition folder from an

ASCII text file to a specified database folder.
The data in the mentioned file is separated by field and record delimiters.
For more information, see Configuring the util utility to recognize different
delimiters below.
Usage: Specify the following command:
util <DB_ARGS> -defimport -replace [-cdbg <1-5>]
[-table <outermost folder name>] [-dcname <newDc>]
[-library <newLibrary>] -file <file>
[-without_def_history]

 If you use FTP to transfer the imported file, use binary mode.
 -type def includes site standard and site customization definitions.
 If -without_def_history is specified, only the current version of the
definition folder is imported. This option is relevant when version
management mode is enabled (default). For more information, see
the Using Control-M.

533
Control-M Utilities Guide

util utility function parameters

The following table describes the util utility function parameters:

Paramete Description
r

-silent Suppresses application messages.

-replace Overwrites existing data in the specified folder.

NOTE: Use -replace with extreme caution. Any database element that is
replaced is overwritten with data that you supply in the input file. If -replace is
not specified and the database attempts to write data that already exists, the
utility terminates and a rollback is performed on data written during the write
operation.

-cdbg Debug level. Range from 1 to 5 (highest level).

Use this option only when instructed to do so by BMC Customer Support.
Using this option can slow performance and use extra disk space.

-type Name of the Control-M/EM database component that is configured by one or

more of the following:

all All application data. Default.

def Job processing definition data.

cal Calendar data, including Rule-Based Calendar entities.

sys System data of the application.

dc Data center definition data.

user Control-M/EM database user data and authorizations.

alert Alert data for the Control-M/EM database.

gc Global conditions – prerequisite conditions that are passed

between Control-M installations by Control-M/EM database.

maint Maintenance folders

collect Collection definitions

view ViewPoint definitions

filter Filter definitions

report Report definitions

534
Control-M Utilities Guide

Paramete Description
r

hier Hierarchy definitions

audit Audit data

history History data

bim_forecast BMC Batch Impact Manager folders and forecast folders

statistics Exceptions data

workload Workload Policy definition data

active_nets Active jobs for all Control-M/Servers

mft Manage File Transfer data in Control-M/EM

wcm Workload Change Manager site standard

NOTE: You cannot use -type wcm in the same command line
as -type def.

NOTE: More than one -type can be used.

- type net Type of Control-M/EM database net.

-name Name of the Control-M/EM database 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
EXAMPLE: SSIMU – simulation net SIMU
A??????23\* – all active nets of netgroup 23

-file Specifies the details of the source or destination file.

file Name of the source or destination file.

-file -  Exports to standard output. Default: user monitor

 Imports from standard input. Default: user keyboard

535
Control-M Utilities Guide

Paramete Description
r

-dir Exports or imports from a specified directory.

dir – Directory of the source or destination file if different from

Control-M/EM database home directory.

file-list – List of text (ASCII) files to be exported or imported,

in the format: filename... filename

-name Defines the name of the Control-M/EM database net.

-table Defines the folder name.

-dcname Control-M identified by the data center name.

-library Type of Control-M/EM database library.

-append Appends the data to the specified folder.

util utility example

The following are examples of the util utility:
Export job processing definitions
The following command exports job processing definitions from the default Control-M/EM database to the
ASCII data file production for database user dbuser1, whose password is secure01:
util -U dbuser1 -P secure01 -export -type def -file production
Import calendar data
The following steps are used to import calendar data from the ASCII data file month_cal to the default
Control-M/EM database:
Stop all Control-M/EM database gateways.
Specify the following command:
util -U dbuser1 -P secure01 -import -type cal -file month_cal
Delete database contents
The following command deletes the contents of the folder A0301190CT_BJOB from database CITIES:
util -D CITIES -U dbuser1 -P secure01 -delete -name A0301190CT_BJOB

536
Control-M Utilities Guide

Clean the database

The following command cleans database WAGE_RATES:
util -D WAGE_RATES -U dbuser1 -P secure01 -clean_database
Build a database schema
The following command builds a new schema for database PAYROLL:
util -D PAYROLL -U dbuser1 -P secure01 -build_schema
Export a database definition folder
The following command exports the INVENTORY definition folder for data center WIP from the default
Control-M/EM database to the file wip_stores:
util -U dbuser1 -P secure01 -defexport -folder INVENTORY \
-dcname WIP -file wip_stores
Import a database definition folder
The following command imports the WORK_IN_PROGRESS definition folder (replacing any data that may
have been in this database folder) from file wip_stores to the PRODUCTION database:
util -D PRODUCTION -U dbuser1 -P secure01 -defimport \
-replace -folder WORK_IN_PROGRESS -file wip_stores

Configure the util utility to recognize different delimiters

During the export process, the util utility reads the fields and records delimiters from the Defaults.rsc
configuration file or uses default values, if nothing is defined in Defaults.rsc. The delimiters are stored in
the created export file.
During the import process, the util utility reads the delimiter values from the export file and does not refer
to the configuration file.
The default values for the records and fields delimiters are as follows:
 \x1E\x1B\x1F - records delimiter
 \x1C\x1B\x1D - fields delimiter
If you are using either of these sequences in your data, add or modify the following lines in the
Defaults.rsc file using different values:
namevalue * util_exp_records_delimiter <recordsDelimiter>
namevalue * util_exp_fields_delimiter <fieldsDelimiter>
In the following example, the definitions in Defaults.rsc are set so that the records delimiter is a
sequence of vertical tab, horizontal tab, and escape, and the fields delimiter is defined as the form feed
character.

537
Control-M Utilities Guide

namevalue * util_exp_records_delimiter \x0B\t\x1B

namevalue * util_exp_fields_delimiter \f
The following table shows the characters you can use for the records delimiter and fields delimiter,
respectively.

Character code Description

\n New line (if it is the only character in records delimiter)

\t Horizontal tab

\x0B Vertical tab

\f Form feed

\x1B Escape

\x1C File separator

\x1D Group separator

\x1E Record separator

\x1F Unit separator

The records and fields delimiters must follow these rules:

 a value between 1 and 5 characters.
 The records delimiter must not be a substring of the fields delimiter, and vice versa.
 \0 and blank characters are not valid values. They are not identified and may cause unexpected
delimiters to be used.

restore_host_config
The Control-M/EM restore_host_config utility automates the recovery process to perform updates in the
host name configuration in the following situations:

538
Control-M Utilities Guide

 Host name data restore in Disaster Recovery sites

 Local host name changes
 Interface name (public host name) definition in cloud computers
 Alternative host name (profile name) utilization
 Database server communication parameter property updates
 Control-M/Server host name updates
 Removing the high-availability secondary host data
 Update the Gateway datacenter hostname
The following procedures describe how to use the restore_host_config utility:
 Restoring hostname and configuration data during Disaster Recovery (on page 539)
 Replacing the local hostname in the database and configuration files (on page 540)
 Setting the interface name in the database and configuration files for cloud computers (on page 540)
 Setting the profile name in the database and configuration files for an alternative/virtual host name
(on page 541)
 Reconfiguring the database server connection data (on page 542)
 Renaming a Control-M/Server hostname in Control-M/EM database (on page 542)
 Removing the secondary high-availability installation component data in the Control-M/EM database
(on page 543)

Restoring hostname and configuration data during Disaster Recovery

This procedure describes how to restore the hostname and configuration data in the database during
disaster recovery when moving to the stand-by environment.
 To restore the hostname and configuration data:
 From a command line type one of the following:
• UNIX: em restore_host_config [-silent] -dr [[-old_host <old (Site A) host name>] or
[-primary/secondary]] [[-password <dbo password>] or [-password_file [<file_path>]]]
• Windows: restore_host_config [-silent] -dr [[-old_host <old (Site A) host name>] or
[-primary/secondary]] [[-password <dbo password>] or [-password_file [<file_path>]]]
NOTE:
 <old (Site A) host name> is the host name of the disaster site. (Multiple distributed
environments)
 If the script cannot detect the old configuration in the template file, the -primary or -secondary
flags can be used alternatively (instead of <-old_host>).
 If the -silent flag is not specified and optional parameters are not defined in the command line,
the script asks for the relevant input interactively.

539
Control-M Utilities Guide

Replacing the local hostname in the database and configuration files

This procedure describes how to replace the local hostname in the database and configuration files when
the Control-M/EM installation host name is modified.
 To replace the local hostname:
 From a command line type one of the following:
• UNIX: em restore_host_config -rehost [-silent] [[-old_host <old host name>] or
[-rename_remote_main_data]][-remove_profile] [-db_host <main installation host name>]
[[-password <dbo password>] or [-password_file [<file_path>]]]
• Windows: restore_host_config -rehost [-silent] [[-old_host <old host name>] or
[-rename_remote_main_data]] [-remove_profile] [-db_host <main installation host name>]
[[-password <dbo password>] or [-password_file [<file_path>]]]
NOTE:
 <old host name> is the original host name of the modified site (If there is more than one
Control-M/ EM environment.
 The -rename_remote_main_data flag updates the main installation parameters, such as
Naming Server host data, on a distributed or secondary installation environment's configuration
files, after moving the main installation to a different host.
 If the –remove_profile flag is defined, the BMC_EM_PROFILE_NAME environment variable
is removed.
 If the database server is local to the main installation host (such as a dedicated PostgreSQL) the
<main installation host name> parameter must be used when running on distributed or
secondary installations.
 If the -silent flag is not specified and optional parameters are not defined in the command line,
the script asks for the relevant input interactively.

Setting the interface name in the database and configuration files for cloud
computers
This procedure describes how to set the interface name in the database and configuration files when
Control-M/EM is running on a cloud environment.
 To set the interface name:
 From a command line type one of the following:
• UNIX: em restore_host_config –interface_name [-silent] [-name <new interface name>]
[[-password <dbo password>] or [-password_file [<file_path>]]]
• Windows: restore_host_config –interface_name [-silent] [-name <new interface name>]
[[-password <dbo password>] or [-password_file [<file_path>]]]
NOTE:
 <new interface name> is the new interface name to publish. This parameter cannot be defined
on AWS computers.

540
Control-M Utilities Guide

 If the -silent flag is not specified and optional parameters are not defined in the command line,
the script asks for the relevant input interactively.

Setting the profile name in the database and configuration files for an
alternative/virtual host name
This procedure describes how to set the profile name in the database and configuration files with the
utilization of the BMC_EM_PROFILE_NAME environment variable.
 To set the profile name:
 From a command line type one of the following:
• UNIX: em restore_host_config –profile_name [-silent] [-name <new profile name>]
[-internal_only [-host_port] [-ctm_name] [-sync_files] [-clients]] [[-password <dbo password>]
or [-password_file [<file_path>]]]
• Windows: restore_host_config –profile_name [-silent] [-name <new profile name>]
[-internal_only [-host_port] [-ctm_name] [-sync_files] [-clients]] [[-password <dbo password>]
or [-password_file [<file_path>]]]
NOTE:
 <new profile name> is the new profile name to configure. This parameter cannot be specified if
the BMC_EM_PROFILE_NAME environment variable is already defined with the required name.
 If the -silent flag is not specified and optional parameters are not defined in the command line,
the script asks for the relevant input interactively.
 If the environment is running with a local (dedicated) PostgreSQL database server, that requires
modification to the database server host name, define the -reconf_db parameter and then
define the -profile_name parameter.
 If the setting is for the computer's internal communication processes only,then the -internal_only
flag must be specified. Otherwise all communication configuration is affected by the new profile
name. This might occur if the profile name is not configured with the DNS name of the computer.
The following exception flags refer to rare usage cases where the -internal only flag is defined:
 Use the –host_port flag when the CTL communication parameters, configured by the HostPort
system parameter, need to be customized with the new profile name.
 Use the –ctm_name flag when the Control-M/Server running on the specific host needs to be
customized with the new profile name.
 Use the –sync_files flag when there are distributed Control-M/EM installations on other hosts
where the file synchronization needs to be customized with the new profile name.
 To see specific details on the exception flag, define the -profile_name -internal_only -help
flag.

541
Control-M Utilities Guide

Reconfiguring the database server connection data

This procedure describes how to reconfigure the database server connection data in the configuration files
and the database, when the database server connection parameters are changed.
 To reconfigure the database server connection data:
 From a command line type one of the following:
• UNIX: em restore_host_config -reconf_db [-silent] [-host <new db host name>] [-port <new db
port number>] [-service <new db service name>] [-dbname <new db schema name>]
[-pg_existing_server <y/n>] [-owner <new db owner name>] [[-password <dbo password>] or
[-password_file [<file_path>]]]
• Windows: restore_host_config -reconf_db [-silent] [-host <new db host name>] [-port <new db
port number>] [-service <new db service name>] [-dbname <new db schema name>]
[-pg_existing_server <y/n>] [-owner <new db owner name>] [[-password <dbo password>] or
[-password_file [<file_path>]]]
NOTE:
 The-pg_existing_server must be used for PostgreSQL databases.
 The y value defines that the database server cannot be administered by the installation (Existing
mode).
 The n value defines that the database server can be administered by the installation (Dedicated
mode).
 If the -silent flag is not specified and optional parameters are not defined in the command line,
the script asks for the relevant input interactively.

Renaming a Control-M/Server hostname in Control-M/EM database

This procedure describes how to rename a Control-M/Server hostname in Control-M/EM database, when
the Control-M/Server hostname is changed.
 To rename a Control-M/Server hostname:
 From a command line type one of the following:
• UNIX: em restore_host_config -rehost_ctm [-silent] [-old_host <old host name>] [-new_host
<new host name>] [[-password <dbo password>] or [-password_file [<file_path>]]]
• Windows: restore_host_config -rehost_ctm [-silent] [-old_host <old host name>] [-new_host
<new host name>] [[-password <dbo password>] or [-password_file [<file_path>]]]
NOTE: If the -silent flag is not specified and optional parameters are not defined in the command
line, the script asks for the relevant input interactively.

542
Control-M Utilities Guide

Removing the secondary high-availability installation component data in the

Control-M/EM database
This procedure describes how to remove the secondary (inactive) high-availability installation component
data in Control-M/EM database.
 To remove the secondary high-availability installation component data in
Control-M/EM database:
 From a command line type one of the following:
• UNIX: em restore_host_config -remove_secondary [-silent] [-switch_primary_to_secondary]
[[-password <dbo password>] or [-password_file [<file_path>]]]
• Windows: restore_host_config -remove_secondary [-silent] [-switch_primary_to_secondary]
[[-password <dbo password>] or [-password_file [<file_path>]]]
NOTE:
 The -switch_primary_to_secondary flag must be defined if the secondary environment is
active.
 If the primary environment is not active and the -switch_primary_to_secondary is not used,
the script exits without removing,and an error message appears.
 If the -silent flag is not specified and optional parameters are not defined in the command line,
the script asks for the relevant input interactively.

543
Control-M Utilities Guide

Control-M/Server utilities
This table lists the Control-M/Server utilities for database maintenance.

Utility Type Description

ctm_backup_bcp (on page The ctm_backup_bcp utility exports data from a

546) Control-M/Server database to the
~<controlm_owner>/ctm_server/backup_db
directory.

ctm_restore_bcp (on page The ctm_restore_bcp utility imports the Control-M/Server

547) database from the bcp_backup directory.

ctmcheckmirror (on page 548) The ctmcheckmirror utility checks the mirroring of the
Control-M/Server database and displays the status.

ctmdbbck (on page 549) The ctmdbbck utility backs up the Control-M/Server
database in the following cases:
 Control-M/Server was installed by using a dedicated
PostgreSQL database server. Do not use this utility if
Control-M/Server was installed with an Oracle database
(either existing or dedicated) or an existing PostgreSQL
database.
 To back up an existing Oracle database or an existing
PostgreSQL database, use the ctm_backup_bcp utility
(described on ctm_backup_bcp (on page 546)).
 Control-M/Server was installed by using an MSSQL
database server.

ctmdbcheck (on page 552) The ctmdbcheck utility displays information about the
memory capacity and the status of the Control-M/Server
database.

ctmdbopt (on page 556) The ctmdbopt utility calculates database statistics.

544
Control-M Utilities Guide

Utility Type Description

ctmdbrst (on page 557) The ctmdbrst utility restores the Control-M/Server database
in the following cases:
 Control-M/Server was installed by using a dedicated
PostgreSQL database server. Do not use this utility if
Control-M/Server was installed with an Oracle database
(either existing or dedicated) or an existing PostgreSQL
database.
 To restore an existing Oracle database or a PostgreSQL
database, use the ctm_restore_bcp utility (described on
ctm_restore_bcp (on page 547)).
 Control-M/Server was installed by using an MSSQL
database server.

ctmdbspace (on page 559) The ctmdbspace utility checks the data and log usage in
the Control-M/Server database and displays the usage.

ctmdbtrans (on page 559) The ctmdbtrans utility lists the active transactions in the
database.

ctmdbused (on page 560) The ctmdbused utility displays the size (in MB), amount,
and percentage of current space usage in the
Control-M/Server database data and log.

ctmreindex (on page 561) The ctmreindex utility accesses the Control-M/Server
database, reads the data dictionary, reads the index
definitions, and then reorganizes indexes. (UNIX only)

dbversion (on page 562) The dbversion utility retrieves the database server version
and tests the connectivity of the Control-M/Server database
in use.

dbu_menu (on page 563) Facilitates day-to-day maintenance and diagnostics of

Control-M/Server running with PostgreSQL, Oracle and
MSSQL databases.
For maintenance and diagnostics of Control-M/EM database
running with PostgreSQL, Oracle and MSSQL see
em_database_menu (on page 501).
NOTE: You can run many of the utilities interactively, as
described in Interactive database utilities (on page 570).

545
Control-M Utilities Guide

ctm_backup_bcp
The ctm_backup_bcp utility exports data from a Control-M/Server database to the
~<controlm_owner>/ctm_server/backup_db directory. Each database folder is backed up as a
separate ASCII file. To run the ctm_backup_bcp utility see Running the ctm_backup_bcp utility (on page
546).
The user running the ctm_backup_bcp utility must have access permission to create the directory
~<controlm_owner>/ctm_server/backup_db.
The time taken to backup the Control-M/Server database using the ctm_backup_bcp utility can be
shortened by choosing not to backup the Control-M log information (the IOALOG table).
Differences between the ctm_backup_bcp and ctmdbbck utilities
 ctm_backup_bcp exports the data in the Control-M/Server database. The ctmdbbck utility backs up an
image of the database for later restoration using ctmdbrst.
 When using ctm_backup_bcp, you cannot specify the backup directory.
 ctm_backup_bcp backs up each database folder to a separate ASCII file. ctmdbbck backs up the
entire database to a single binary file.
 For all databases, except PostgreSQL, when using ctmdbbck and ctmdbrst, the restored database
must be the same size as the original database. When using ctm_backup_bcp and ctm_restore_bcp,
the original and restored databases do not need to be the same size.
The ctmdbbck and ctmdbrst utilities are not relevant for Oracle databases, whether dedicated or existing.

Running the ctm_backup_bcp utility

This procedure describes how to run the ctm_backup_bcp utility, which exports data from a
Control-M/Server database to the ~<controlm_owner>/ctm_server/backup_db directory.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Shut down Control-M/Server by using the following commands:
• shut_ca
• shut_ctm
3. Type the following command:
ctm_backup_bcp [-n]
-n runs the utility in silent mode. In this mode, confirmation prompt and "backing up contents"
messages are not displayed.
For more details on the ctm_backup_bcp utility, see ctm_backup_bcp example (on page 547).

546
Control-M Utilities Guide

ctm_backup_bcp example
Messages similar to the following examples are displayed:
backing up contents of CMS_NODGRP
backing up contents of CMR_AGSTAT
backing up contents of CMS_AGCOMM
backing up contents of CMS_AGSRVTIM
backing up contents of CMR_AJF
backing up contents of CMS_JOBDEF
backing up contents of CMS_USERS
…
Database backup ended successfully.
ctm_backup_bcp -n
In this case, Control-M/Server does not display the confirmation prompt and does not issue messages.
Only progress dots are displayed.

ctm_restore_bcp
The ctm_restore_bcp utility imports the Control-M/Server database from the
~<controlm_owner>/ctm_server/backup_db directory. The content of this directory was created
by the ctm_backup_bcp utility. To run the ctm_backup_bcp utility, see Running the ctm_restore_bcp
utility (on page 548).
Differences between the ctm_restore_bcp and ctmdbrst utilities:
 ctm_restore_bcp imports files created by ctm_backup_bcp. ctmdbrst restores a backup created by
ctmdbbck.
 When using ctm_restore_bcp, you cannot specify the directory containing the exported files.
 You can only use ctm_restore_bcp if Control-M/Server is down.
 ctm_restore_bcp imports ASCII files. ctmdbrst restores from a binary file.
ctm_restore_bcp
Restoring contents of database.
This procedure DELETES any information in main database
Please confirm [y/n]: y

547
Control-M Utilities Guide

Running the ctm_restore_bcp utility

This procedure describes how to run the ctm_restore_bcp utility, which imports the Control-M/Server
database from the ~<controlm_owner>/ctm_server/backup_db directory.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Shut down Control-M/Server by using the shut_ctm command. Make sure no other users or processes
are connected to the SQL Server.
3. Enter the following the command:
ctm_restore_bcp [-n]
For more detail on the ctm_restore_bcp utility see ctm_restore_bcp utility example (on page 548).

ctm_restore_bcp utility example

Messages similar to the following examples are displayed:
restoring contents of CMS_NODGRP
restoring contents of CMR_AGSTAT
restoring contents of CMS_AGCOMM
restoring contents of CMS_AGSRVTIM
restoring contents of CMR_AJF
restoring contents of CMS_JOBDEF
restoring contents of CMS_USERS
…
Database restore ended successfully.
ctm_restore_bcp -n
In this case, Control-M/Server does not display the confirmation prompt and the "restoring contents"
messages. Only progress dots are displayed.

ctmcheckmirror
The ctmcheckmirror utility checks the mirroring of the Control-M/Server database and displays the status.
To run the ctmcheckmirror utility, see Running the ctmcheckmirror utility (on page 549).
For more information about database mirroring, see Mirroring parameters.

548
Control-M Utilities Guide

Running the ctmcheckmirror utility

This procedure describes how to run the ctmcheckmirror, which checks the mirroring of the
Control-M/Server database and displays the status.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the following command:
ctmcheckmirror
3. The ctmcheckmirror utility returns one of the following statuses:
• Mirroring is enabled.
• Mirroring is disabled.
• Mirroring is damaged.
For the Control-M parameter name, see Parameter name cross references (on page 31)

ctmdbbck
The ctmdbbck utility backs up the Control-M/Server database in the following cases:
 Control-M/Server was installed by using a dedicated PostgreSQL database server. Do not use this
utility if Control-M/Server was installed with an Oracle database (either existing or dedicated) or an
existing PostgreSQL database.
To back up an existing Oracle database or an existing PostgreSQL database, use the ctm_backup_bcp
utility (described on ctm_backup_bcp (on page 546)).
 Control-M/Server was installed by using an MSSQL database server.
For information about Archive mode, see Set Database Archive Mode referred to in the table in Accessing
the Database Utilities Menu (on page 503).
NOTE: When using PostgreSQL, after specifying this utility you are prompted to enter the DBA password
to access the Control-M/Server database.
The following describe how to run the utility, backing up the Control-M/Server database and running in
silent mode together with an example:
 Running the ctmdbbck utility (on page 550)
 Backing up the Control-M/Server database (on page 550)
 Backing up the Control-M/Server database (PostgreSQL) (on page 551)
 Running the ctmdbbck in silent mode (on page 552)
 ctmdbbck utility example (on page 552)

549
Control-M Utilities Guide

Running the ctmdbbck utility

This procedure describes how to run the ctmdbbck utility, which backs up the Control-M/Server database.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the following the command prompt to use the interactive menu to back up the Control-M/Server
database (for both UNIX and Windows):
ctmdbbck
3. To run the ctmdbbck utility not in an interactive mode, run ctmdbbck and specify the following
parameters:
• For UNIX
ctmdbbck [ -p<administrator password>]
[ -f<administrator password file>]
[ -d<full path of backup directory/file>]
[ -m<backup mode H/C>]
• For Windows
ctmdbbck [ -p<administrator password>]
[ -f<administrator password file>]
[ -d<full path of backup directory/file>]
For the Control-M parameter name, see Parameter name cross references (on page 31).

Backing up the Control-M/Server database

This procedure describes how to back up the Control-M/Server database (not PostgreSQL)

 To back up the Control-M/Server database:

1. Shut-down Control-M/Server and Control-M/Server Configuration Agent before running this utility.
2. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<Server Home>\ctm_server\directory.
3. Enter the following command:
ctmdbbck
4. Continue the backup by following the prompts.
For MSSQL – You are prompted for the backup device (<backupDevice>).

550
Control-M Utilities Guide

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

 a valid device defined in an existing MSSQL
 the full path name of a file to be created by the backup procedure for MSSQL
5. If no backup devices exist, or you want to use a new backup device, choose 6 - Add Backup Device
from the Database Maintenance menu.

Backing up the Control-M/Server database (PostgreSQL)

This procedure describes how to back up the Control-M/Server database when using PostgreSQL.
 To back up the Control-M/Server database (PostgreSQL):
1. Shut-down Control-M/Server and Control-M/Server Configuration Agent before running this utility.
2. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: For Windows client installations, open a command prompt window and navigate to the
<Server Home>\ctm_server\directory.
3. Enter the following command:
ctmdbbck
For MSSQL – You are prompted for the backup device (<backupDevice>).
4. Continue the backup by following the prompts.
Prompts and messages similar to the following are displayed:
Please Enter Postgres Administrator Password:*******
Detecting current archive mode ...
Archive Mode=off
Done.
Enter full path destination file name:c:\bckup
Performing Cold backup into c:\bckup ...
backup succeeded. It is recommended to check backup file by restoring it
to test
environment.
You can start Control-M/Server.
The back up is complete.

551
Control-M Utilities Guide

Running the ctmdbbck in silent mode

This procedure describes how to run the ctmdbbck utility in silent mode.

 To run the ctmdbbck in silent mode:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the following command:
ctmdbbck -pmanager / -f<passwordFile> -d<backupDirectory> - m<H/C>
NOTE: When using PostgreSQL, silent mode is available only on UNIX.

ctmdbbck utility example

The following are examples of the ctmdbbck utility:
Specify the following command to backup the Control-M/Server database where Control-M/Server was
installed using an existing MSSQL database server and the backup device is
controlm_data_bkp:
ctmdbbck controlm_data_bkp
Specify the following command to back up the Control-M/Server database where Control-M/Server was
installed by using a dedicated PostgreSQL database server:
ctmdbbck
You are prompted for the required parameters.

ctmdbcheck
The ctmdbcheck utility displays information about the memory capacity and the status of the
Control-M/Server database.
The ctmdbcheck utility can be run as a cyclic job. To run the ctmdb check utility, see Running the
ctmdbcheck utility (on page 553).
NOTE: If the -n switch is specified in the ctmdbcheck command, only database capacity information is
returned, and database thresholds and integrity are not checked.
For performance reasons, run the ctmdbcheck utility during non-peak hours or when Control-M/Server is
down. If you need to determine database sizes frequently, use the ctmdbused command. This command
displays the size (in MB) of the data and log components of the database plus the amount and percentage
of space currently that is used in each component.

552
Control-M Utilities Guide

Running the ctmdbcheck utility

This procedure describes how to run the ctmdbcheck utility, which displays information about the memory
capacity and the status of the Control-M/Server database.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter one of the following the commands:
• ctmdbcheck
Monitor the database and the transaction log using the ctmdbcheck utility with the following
syntax according to the database in use.
• For Oracle specify the following command:
ctmdbcheck <generalThreshold%>
Only data usage may be checked for existing Oracle databases.
• For PostgreSQL, enter the following command:
ctmdbcheck <generalThreshold%>
• For MSSQL enter the following command:
ctmdbcheck [-d <dbThreshold%>] [-l <logThreshold%>][-n]
ctmdbcheck 20
db total = 47757170 KB
data used = 6633 KB (0.01%)
Checking database...
Database is OK
These commands trigger a Shout message to Control-M/Server if more than the specified
percentage of the database or the database transaction log are full. This message can then
be used to trigger actions that will extend the appropriate Control-M/Server database
component.
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmdbcheck utility, see ctmdbcheck utility parameters (on page 554), ctmdbcheck utility output
parameters (on page 555), and ctmdbcheck utility examples (on page 555).

553
Control-M Utilities Guide

ctmdbcheck utility parameters

The following table describes the ctmdbcheck parameters:

Parameter Description

<dbThreshold%> Threshold for usage of the Control-M/Server database.

If more than the specified percentage of the database is full, a
Shout message to Control-M/EM warns that the database should be
extended. This variable must be preceded by the -d switch. For
example, -d80 indicates that a shout message should be issued if
the database is more than 80% full.

<logThreshold%> Threshold for usage of the transaction log of the Control-M/Server

database.
If more than the specified percentage of the database is full, a
Shout message to Control-M/EM warns that the transaction log
should be extended. This variable must be preceded by the -l switch.
For example, -l80 indicates that a shout message should be issued if
the transaction log is more than 80% full.

<generalThreshold% Checks data and log partitions of the Control-M/Server database by

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

554
Control-M Utilities Guide

ctmdbcheck utility output parameters

The ctmdbcheck utility returns information about the Control-M/Server database. The following table
describes the fields that are returned by this utility:

Field Description

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

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

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

Data used Total memory currently used in the Data partition.

Log used Total memory currently used in the Log partition.

In addition to the above fields, ctmdbcheck also returns one of the following messages describing the
current database status:
 Database is OK.
 WARNING: Database is more than half full.
 ATTENTION: Database log segment is more than 90% full.
 ATTENTION: Database is more than 80% full.

ctmdbcheck utility examples

These examples use the ctmdbcheck utility to check database status without specifying any parameters
(that is, no Shout messages will be issued for this run on the utility, even if the database is over the
desired threshold).
Utility input
ctmdbcheck 50
The general threshold % option specifies the same percentage for both the database and the
log. In this example, if either the database or log exceeds 50%, ctmdbcheck 50 will trigger a
shout message.
Utility input
ctmdbcheck -d10
Oracle 817 database – utility output
Folderspace Size % Free
-------------------- ------- -------
RBS 200M 85%
WIN613O 150M 95%

555
Control-M Utilities Guide

WIN613O_INDX 50M 98%

Utility input
ctmdbcheck -d10
Oracle 92 Database – Utility Output
Folderspace Size % Free
-------------------- ------- -------
CTRLM 250M 96%
TEMP 100M 90%
RBS 300M 99%

ctmdbmused utility example

The following example describes a sample output:
db master total = 20000.0 KB
data used = 4334 KB (21%)
If the data used is more than 80% of the size of the Control-M/Server Master database, the utility output
contains the message:
CAUTION - DB near capacity. Increase master DB size.
If the data used is more than 90%, the utility output contains the message:
URGENT - Not enough Master DB free space.
BMC recommends running this utility as a cyclic job that automatically generates an appropriate Shout
message if the utility output (OUTPUT) contains the phrase "DB near capacity" or "DB free space".

ctmdbopt
The ctmdbopt utility calculates database statistics. This utility wraps the relevant database packages that
collect statistics on all Control-M/Server database folders. You can run this utility while Control-M/Server is
running.
The ctmdbopt utility collects folder and index statistics on the Control-M schema by using the
DBMS_STATS package. It affects all Control-M/Server for UNIX and Microsoft Windows database folders.
The statistics helps the optimizer to choose the fastest way to retrieve data (full folder scan, index scan,
or any other way).
Gathering statistics improves database performance. BMC recommends that you run this utility on a daily
basis, so that the database optimizer has updated statistics. To run the ctmdbopt command, see Running
the ctmdbopt utility (on page 557).

556
Control-M Utilities Guide

Running the ctmdbopt utility

This procedure describes how to run the ctmdbopt utility, which calculates database statistics.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter one of the following the command:
ctmdbopt

ctmdbrst
The ctmdbrst utility restores the Control-M/Server database in the following cases:
 Control-M/Server was installed by using a dedicated PostgreSQL database server. Do not use this
utility if Control-M/Server was installed with an Oracle database (either existing or dedicated) or an
existing PostgreSQL database.
To restore an existing Oracle database or a PostgreSQL database, use the ctm_restore_bcp utility
(described on ctm_restore_bcp (on page 547)).
 Control-M/Server was installed by using an MSSQL database server.
For more information about backup types, see Database operation and maintenance.
To run the ctmbrst utility, see Running the ctmbrst utility (on page 557) and to run in silent mode see
Running the ctmdbrst in silent mode (on page 558). To restore the Control-M/Server database, see
Restoring the Control-M/Server database (on page 558).

Running the ctmbrst utility

This procedure describes how to run the ctmdbrst utility, which restores the Control-M/Server database.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Do one of the following:
• To invoke the ctmdbrst utility for Control-M/Server installed with MSSQL, enter the following
command:
ctmdbrst
[ -f<administrator password file>]
[ -d<full path of backup directory/file>]
[ -m H/C]

557
Control-M Utilities Guide

• To invoke the ctmdbrst utility for Control-M/Server installed with PostgreSQL, run the following
command (this mode is UNIX only):
ctmdbrst [ -p<administrator password>]
[ -f<administrator password file>]
[ -d<full path of backup directory/file>]
[ -a<full path of archive directory>]
[ -m<restore mode H/C>]

• Enter the following command at the command prompt to use the interactive menu (this mode is
Windows only):
ctmdbrst

For the Control-M parameter name, see Parameter name cross references (on page 31).

Restoring the Control-M/Server database

This procedure explains how to restore the Control-M/Server database by using the ctmdbrst utility.

 To restore the Control-M/Server database:

1. Shut down Control-M/Server and the Configuration Agent before invoking this utility. Make sure that
no other users or processes are connected to the SQL server.
2. Do one of the following:
• Log on to a Control-M/EM database account (UNIX)
• Open a command prompt window (Windows) where Control-M/EM is installed.
3. Enter the following:
ctmdbrst

Continue the restore procedure by following the prompts.

For MSSQL – you are prompted for the backup device (<backupDevice>). This device was used to back
up the Control-M/Server database.

Running the ctmdbrst in silent mode

This procedure describes how to run the ctmdbrst utility in silent mode.

 To run ctmdbrst in silent mode:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the following command:
ctmdbrst -pmanager –d<restoreDirector> -m<H/C> -a<archive Director>

The following command causes the Control-M/Server database to be restored from the default backup
device:
ctmdbrst

558
Control-M Utilities Guide

ctmdbspace
The ctmdbspace utility checks the data and log usage in the Control-M/Server database and displays the
usage. The utility returns a "failed" status if the usage exceeds the specified limit. To run the ctmdbspace,
see Running the ctmdbspace utility (on page 559).
ctmdbspace can be included in the Control-M Watchdog process. For more information, see Watchdog
process parameters.

Running the ctmdbspace utility

This procedure describes how to run the ctmdspace utility, which checks the data and log usage in the
Control-M/Server database and displays the usage.
 To run the ctmdbspace utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the following command:
ctmdbspace -limit <amount> [-quiet]
The <amount> variable is the maximum amount (percentage) of data and log usage in the database.
Use the optional -quiet parameter to suppress the display.
The following command returns a "failed" status if Control-M/Server database usage is more than
50%:
ctmdbspace -limit 50%
For the Control-M parameter name, see Parameter name cross references (on page 31).

ctmdbtrans
The ctmdbtrans utility lists the active transactions in the database. A transaction is defined as the unit of
work performed by Control-M in the database. Each transaction is assigned a unique name identifying
that specific unit of work.
You may be asked by technical support to run this utility and to provide them with the output for
debugging purposes.
Another way to list active transactions in the database, is to select "List Active Transactions" from the
Troubleshooting menu. To run the ctmdbtrans utility and to run in silent mode, see Running the
ctmdbtrans utility (on page 559) and Running the ctmdbtrans utility in batch mode (on page 560).

Running the ctmdbtrans utility

This procedure describes the ctmdbtrans utility, which lists the active transactions in the database.

559
Control-M Utilities Guide

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the following command to see which transactions are active in the database:
ctmdbtrans
For the Control-M parameter name, see Parameter name cross references (on page 31).

Running the ctmdbtrans utility in batch mode

This procedure describes how to run the ctmdbtrans utility in batch mode.

 To run the utility in batch mode:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Do one of the following:
• For PostgreSQL, Oracle and MSSQL databases, enter the following command:
ctmdbtrans
• For UNIX machines you can refresh transactions every given amount of time by specifying the
sleep time parameter by entering the following command:
ctmdbtrans
ctmdbtrans n (number in seconds)

ctmdbused
The ctmdbused utility displays the size (in MB), amount, and percentage of current space usage in the
Control-M/Server database data and log. To run a ctmbused utility see Running the ctmbused utility (on
page 560).

Running the ctmbused utility

This procedure describes how to run the ctmdbused utility displays the size (in MB), amount, and
percentage of current space usage in the Control-M/Server database data and log.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the following command:

560
Control-M Utilities Guide

ctmdbused
Use this utility if you need to determine Control-M/Server database sizes frequently.
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on running the ctmbused utility, see ctmbused utility example (on page 561).

ctmbused utility example

These examples use the ctmdbused utility to display Control-M/Server database data and log size, amount
of current usage and percentage of space, using MSSQL databases.
Utility input
ctmdbused
Utility output
db total = 45000.0 MB (data= 3000.00 , log= 15000.00)
data used = 4174 MB (13%).
log used = 40.00 MB (0%)
This example uses the ctmdbused utility to display Control-M/Server database data and log size, amount
of current usage and percentage of space, using Oracle 11.
Utility input
ctmdbused
Oracle 11 database – utility output
db total = 563200.0 MB
data used = 10048 MB (4%).
This example uses the ctmdbused utility to display Control-M/Server database data, amount of current
usage and percentage of space, using a PostgreSQL database.
Utility input
ctmdbused
Utility output
db total = 50404551 MB
data used = 863570 KB (1.71%)

ctmreindex
The ctmreindex utility accesses the Control-M/Server database, reads the data dictionary, reads the index
definitions, and then reorganizes indexes. (UNIX only)
This utility is relevant only on Control-M/Server with a Sybase database.
The Control-M/Server Sybase database must be running so that the required index operations can be
performed. However, this utility should be run only when database activity is low.

561
Control-M Utilities Guide

This utility enables Control-M/Server database queries to execute faster by ensuring that indexes are
well-balanced. For more information about indexes, refer to Sybase manuals. To run the ctmreindex
utility, see Running the ctmreindex utility (on page 562).

Running the ctmreindex utility

This procedure describes how to run the ctmreindex, which accesses the Control-M/Server database,
reads the data dictionary, reads the index definitions, and then reorganizes indexes (UNIX only).

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account.
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the following command:
ctmreindex
The following command causes the ctmreindex utility to reorganize indexes in the Control-M/Server
Sybase database:
ctmreindex
For the Control-M parameter name, see Parameter name cross references (on page 31).

dbversion
The dbversion utility retrieves the database server version and tests the connectivity of the
Control-M/Server database in use. The database can be any one of the following database servers:
Oracle, MSSQL, or PostgreSQL. To run the dbversion utility, see Running the dbversion utility (on page
562).

Running the dbversion utility

This procedure describes how to run the dbversion utility, which retrieves the database server version and
tests the connectivity of the Control-M/Server database in use.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the following command:
dbversion
For the Control-M parameter name, see Parameter name cross references (on page 31).

562
Control-M Utilities Guide

dbu_menu
The dbu_menu utility can be invoked interactively to facilitate day-to-day maintenance and diagnostics of
Control-M/Server database running with PostgreSQL, Oracle and MSSQL databases. On Windows, the
utility is called dbu_menu.bat.
NOTE: The Database Utilities Menu is only relevant for PostgreSQL, Oracle and MSSQL database
functionality. You can also access the database menu from the ctm_menu utility and select Database
Menu.
To facilitate day-to-day maintenance and diagnostics of Control-M/EM database use the
em_database_menu utility, as described in em_database_menu options (on page 502).

Running the dbu_menu utility

This procedure describes how to access the Database Utilities menu for Control-M/Server.

 To access the Database Utilities Menu:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window and go to
Control-M/Server>\ctm_server\exe\DBUtils.
NOTE: You can also access the Database Utilities Menu from the ctm_menu and selecting
Database Menu.
2. Open a command prompt as an Administrator and type the following command:
dbu_menu
The Database Utilities Menu is displayed:
Select one of the following options:
1 - Management
2 - Maintenance
3 - Report
q - quit
Enter option number ---> [q]:
The options available in the Database Utilities Menu enable you to access the following sub-menus:
• Management Menu options (on page 564)
• Maintenance Menu Options (on page 566)
• Report Menu options (on page 505)

563
Control-M Utilities Guide

Management Menu options

The following table lists the options in the Management Menu.

Database
Option Server Description

Start Database PostgreSQL Only enabled when Control-M/Server is running with a dedicated database server. Starts t
database server, and services involved.
(Running the
DBUStart NOTE: If this option is invoked on Control-M/Server running with an existing database, an
utility (on message is displayed.
page 575))

Stop Database PostgreSQL Only enabled when Control-M Server is running with a dedicated database server.
(Running the Stops the PostgreSQL database server, and services involved.
DBUStop
NOTE: If this option is invoked on Control-M/Server running with an existing database, an
utility (on
message is displayed.
page 576))

Set Database PostgreSQL Only enabled when Control-M/Server is running with a dedicated PostgreSQL database ser
Archive Mode the archive mode of the PostgreSQL database server.
(DBUArchive) Parameters available:
Mode
 On
 Off (default)
Archive Directory (only available when Mode is ON)
Full directory path to which the database server logs are archived.
NOTE: This directory should be empty. When Archive mode is On, the Hot Database Ba
is enabled.

Build  PostgreSQ Creates a Control-M/Server database.

Database L
NOTE: This option is only enabled on Control-M/Server running with either an existing or
(DBUBuild)  MSSQL database server.

 Oracle

564
Control-M Utilities Guide

Database
Option Server Description

Extend  Oracle Extends the size of the existing user database datafile, or adds a new datafile, to provide e
Database for schema objects.
 MSSQL
Parameters:
 Mode: Current or New
 Current – a current data file is extended
 New – an additional data file will be added to the database
 Directory Path: the full directory path to the new datafile if parameter mode is set to N
 Administrator Password: DBA password (for Oracle only)
 Size: specified in MB
 (MSSQL only) Type: Data or Log

565
Control-M Utilities Guide

Maintenance Menu Options

The following table describes the Maintenance Menu options for Control-M/Sever.

Options Database Description

Update Database Statistics  PostgreSQL Updates statistic procedures in the database server.
(DBUUpdateStatistics)  MSSQL
 Oracle

Database Consistency Check  PostgreS MSSQL: Performs allocation checks and verifies the structural and logi
QL integrity of all objects in the database
 MSSQL Oracle: Detects bad blocks and checks table and index schema
consistency.

Hot Database Backup PostgreSQL Only enabled when:

(DBUHotBackup)  Database Archive Mode is set to On
 Control-M/Server is active and running with a dedicated database
server.
Online backup of a dedicated PostgreSQL database server file system a
the Control-M/Server databases. This backup can be used to restore th
database up to and including the last completed transaction.
Parameters:
 Backup Directory: Full path to the directory into which the serve
file system and Control-M/Server databases should be backed up.
NOTE: This directory should be empty.
 Administrator password: Password of the PostgreSQL database
server administrator.

Cold Database Backup  PostgreSQL Exports the Control-M/Server database schema to the specified file whe
Control-M/Server is shut down.
(DBUColdbackup (on page 571))  MSSQL
The following Control-M/Server components must be shut down prior t
activating this backup:
 Control-M/Server Configuration Agent (shut_ca)
 Control-M/Server (shut_ctm)
Parameters:
 Backup File: Full path to the file into which the database should b
backed up.
 Administrator password: Password of the PostgreSQL database
server administrator

566
Control-M Utilities Guide

Options Database Description

Hot Database Restore PostgreSQL Only enabled when Control-M/Server is active and running with a
dedicated PostgreSQL database server.
(DBUHotRestore)
Online restore of the PostgreSQL database server file system and the
Control-M/Server databases. When this option completes successfully,
previous PostgreSQL database server file system is saved to the follow
location:
<pghome_directory/old_pgsql_<date of operation>
If Control-M/Server databases do not exist in the <pghome_directory>
is saved in the following location:
<db location>/<db name>_old_<date of operation>
The PostgreSQL database server and the following Control-M/Server
components must be shut down for this option to be enabled:
 Control-M/Server Configuration Agent (shut_ca)
 Control-M/Server (shut_ctm)
Parameters:
 Restore Directory: Full path to the directory from which the server
system and Control-M/Server databases should be restored.
 Archive Directory: Value and location specified in the Archive Direc
parameter of the Set Database Archive Mode option.
NOTE: When this action is finished successfully, the PosgreSQL
database server archive mode switches to off, and the PosgreSQL
database server shuts down.
The specified directory should be exported from the PostgreSQL
database server with the same parameter values as the destination
PostgreSQL database server.

567
Control-M Utilities Guide

Options Database Description

Cold Database Restore  PostgreSQL Imports the Control-M/Server database schema from the file specified
Backup File parameter of the Cold Database Backup option.
(DBUColdRestore (on page 572))  MSSQL
NOTE: The following Control-M/Server components must be shut down
for this option to be enabled:
 Control-M/Server Configuration Agent (shut_ca)
 Control-M/Server (shut_ctm)
Parameters:
 Restore File: Value and location specified in the Backup File param
of the Cold Database Backup option.
 Administrator password: Password of the PostgreSQL database ser
administrator.

restore_host_config
The Control-M/Server restore_host_config utility automates the recovery process to perform updates in
the host name configuration in the following situations:
 Host name data restore in Disaster Recovery sites
 Database server communication parameter property updates
 Removing the high-availability secondary host data
The following procedures describe how to use the restore_host_config utility:
 Restoring Control-M/Server hostname and configuration data during Disaster Recovery (on page 568)
 Reconfiguring the database server connection data (on page 569)
 Removing the secondary high-availability installation component data in the Control-M/Server
database (on page 569)

Restoring Control-M/Server hostname and configuration data during

Disaster Recovery
This procedure describes how to restore the Control-M/Server hostname and configuration data in the
database during disaster recovery when moving to the stand-by environment.
Before you begin
 Shut down Control-M/Server and Control-M/Server Configuration Agent

 To restore the hostname and configuration data:

1. Navigate to the following directory:

568
Control-M Utilities Guide

<Control-M/Server_home>\ctm_server\scripts\
2. Type the following command:
restore_host_config -dr [-primary/secondary]

Reconfiguring the database server connection data

This procedure describes how to reconfigure the database server connection data in the configuration files
and the database, when the database server connection parameters are changed.

Before you begin

 Shut down Control-M/Server and Control-M/Server Configuration Agent
 To reconfigure the database server connection data:
1. Navigate to the following directory:
<Control-M/Server_home>\ctm_server\scripts\
2. Type the following command:
restore_host_config -reconf_db [-host <new db host name>] [-port <new db port number>]
[-dbname <new db schema name>] [-service <new db service name>] [-owner <new db owner
name>] [[-password <dbo password>] [-pg_existing_server <y/n>]
NOTE:
 The-pg_existing_server must be used for PostgreSQL databases.
 The y value defines that the database server cannot be administered by the installation (Existing
mode).
 The n value defines that the database server can be administered by the installation (Dedicated
mode).

Removing the secondary high-availability installation component data in the

Control-M/Server database
This procedure describes how to remove the secondary (inactive) high-availability installation component
data in Control-M/Server database.
Before you begin
 Shut down Control-M/Server and Control-M/Server Configuration Agent

 To remove the secondary high-availability installation component data in

Control-M/Server database:
1. Navigate to the following directory:
<Control-M/Server_home>\ctm_server\scripts\
2. Type the following command:
restore_host_config -remove_secondary

569
Control-M Utilities Guide

Interactive database utilities

The utilities discussed in this section can be invoked interactively to facilitate day-to-day maintenance and
diagnostics of Control-M/Server databases and Control-M/EM databases running with either PostgreSQL,
MSSQL or Oracle.
The interactive database utilities are located at the following path for Windows:
 Control-M/EM: <Control-M EM home>\Default\bin\DBUtils
 Control-M/Server: <Control-M/Server>\ctm_server\exe\DBUtils
For details about Return codes, see Return codes (on page 571).
You can also run most of the DBU utilities in Control-M/EM using the em_database_menu, as described in
em_database_menu (on page 501) and in Control-M/Server using the dbu_menu, as described in
dbu_menu (on page 563).
The following interactive database utilities are listed:
 Running the DBUColdBackup utility (on page 571)
 Running the DBUColdRestore utility (on page 572)
 Running the DBUStart utility (on page 575)
 Running the DBUStop utility (on page 576)
 Running the DBUVersion utility (on page 577)
 DBUStatus (on page 578)
 DBUStorage (on page 581)
 Running the DBUTransactions utility (on page 582)
 Running the DBUShow utility (on page 584)

570
Control-M Utilities Guide

Return codes
The return codes listed in the following table are issued by the interactive database utilities.

Return
code Description

0 The action completed successfully.

1 The action failed and an error message is issued.

NOTE: Error messages have the following format:
<Module number> – <Module name>: <Error Code (numerical)>
– <Error description>
EXAMPLE: AP-7 - Permission Module: 2 - This utility could not be used with
the existing PostgreSQL database.

2 The action completed successfully. A warning message was displayed,

although this warning had no effect on the action itself.

Running the DBUColdBackup utility

This procedure describes how to run the DBUColdBackup utility, which enables you to export the
Control-M/EM database schema or the Control-M/Server database schema to the specified file after the
database is shut down.
 To run the utility:
1. Do one of the following:
• Control-M/EM: Do one of the following:
o UNIX: Log on to a Control-M/EM account.
o Windows: Open a command prompt window and go to <Control-M EM
home>\Default\bin\DBUtils.
• Control-M/Server: Do one of the following:
o UNIX: Log on to a Control-M/Server account.
o Windows: Open a command prompt window and go to
<Control-M/Server>\ctm_server\exe\DBUtils.
2. Type the following command:
DBUColdBackup
[ -TRACE_LEVEL <error|log|info> ]
[ -HELP ]
[ -BACKUP_FILE <Full Path of Backup File Name> ]

571
Control-M Utilities Guide

[ -ADMINISTRATOR_PASSWORD <Administrator Password> ]

For more details on DBUColdBackup, see DBUColdBackup utility parameters (on page 572).
EXAMPLE: The following example describes a DBUColdBackup utility sample output:
database was backup to /home1/ctm900pg/Backup.bck

DBUColdBackup utility parameters

The following table describes the DBUColdBackup utility parameters:

Parameter Description

-TRACE_LEVEL Trace level. Valid values: error, log, info. Default:

error. Optional.
Use this option only when instructed to do so by BMC
Customer Support. Using this option can slow
performance and use extra disk space.

-HELP Displays the usage, then exits with success status.

-BACKUP_FILE Full path to the file into which the database should be
backed up. Mandatory.

-ADMINISTRATOR_PASSWORD Password of the database server administrator.

Mandatory.

Running the DBUColdRestore utility

This procedure describes how to run the DBUColdRestore utility, which imports the Control-M/EM
database schema or Control-M/Server database schema from the file specified in the BACKUP_FILE
parameter of the DBUColdBackup utility.

 To run the utility:

1. Do one of the following:
• Control-M/EM: Do one of the following:
o UNIX: Log on to a Control-M/EM account.
o Windows: Open a command prompt window and go to <Control-M EM
home>\Default\bin\DBUtils.
• Control-M/Server: Do one of the following:
o UNIX: Log on to a Control-M/Server account.
o Windows: Open a command prompt window and go to
<Control-M/Server>\ctm_server\exe\DBUtils.
2. Type the following command:

572
Control-M Utilities Guide

DBUColdRestore
[ -TRACE_LEVEL <error|log|info> ]
[ -HELP ]
[ -RESTORE_FILE <Full Path of Restore File Name> ]
[ -ADMINISTRATOR_PASSWORD <Administrator Password> ]
For more details about the DBUColdRestore utility, see DBUColdRestore utility parameters (on page
573).
The following example describes a utility DBUColdRestore sample output:
restore completed

DBUColdRestore utility parameters

The following table describes the DBUColdRestore utility parameters:

Parameter Description

-TRACE_LEVEL Trace level. Valid values: error, log, info. Default:

error. Optional.
NOTE: Use this option only when instructed to do so by
BMC Customer Support. Using this option can slow
performance and use extra disk space.

-HELP Displays the usage, then exits with success status.

-RESTORE_FILE Value and location specified in the BACKUP_FILE

parameter of the DBUColdBackup utility. Mandatory.
NOTE: The source and destination databases should
have the same encoding settings configured.

-ADMINISTRATOR_PASSWORD Password of the database server administrator.

Mandatory.

Running the DBUHotBackup utility

This procedure describes how to run the DBUHotBackup utility, which enables you to export the
Control-M/EM database schema or the Control-M/Server database schema to the specified file, while the
database is active.
 To run the utility:
1. Do one of the following:
• Control-M/EM: Do one of the following:

573
Control-M Utilities Guide

o UNIX: Log on to a Control-M/EM account.

o Windows: Open a command prompt window and go to <Control-M EM
home>\Default\bin\DBUtils.
• Control-M/Server: Do one of the following:
o UNIX: Log on to a Control-M/Server account.
o Windows: Open a command prompt window and go to
<Control-M/Server>\ctm_server\exe\DBUtils.
2. Type the following command:
DBUHotBackup
[ -TRACE_LEVEL <error|log|info> ]
[ -HELP ]
[ -BACKUP_DIRECTORY <Full Path of Backup File Name> ]
[ -ADMINISTRATOR_PASSWORD <Administrator Password> ]
[-REMOVE_UNNECESSARY_LOGS <Remove unnecessary logs? <Y/N>]
For more details on DBUHotBackup, see DBUHotBackup utility parameters (on page 574).

DBUHotBackup utility parameters

The following table describes the DBUHotBackup utility parameters:

Parameter Description

-TRACE_LEVEL Trace level. Valid values: error, log, info. Default:

error. Optional.
Use this option only when instructed to do so by BMC
Customer Support. Using this option can slow
performance and use extra disk space.

-HELP Displays the usage, then exits with success status.

-BACKUP_DIRECTORY Full path to the directory into which the database should
be backed up. Mandatory.

-ADMINISTRATOR_PASSWORD Password of the database server administrator.

Mandatory.

-REMOVE_UNNECESSARY_LOGS Removes any unnecessary logs in the back up database.

574
Control-M Utilities Guide

Running the DBUStart utility

This procedure describes how to run the DBUStart utility, which enables you to start the database server
and the related services. Relevant only for a PostgreSQL database. When invoking this utility with a
PostgreSQL database, the utility is only enabled on Control-M/EM or Control-M/server running with a
dedicated PostgreSQL database server.
NOTE: If this option is invoked on Control-M/EM or Control-M/Server running with an existing PostgreSQL
database, an error message is displayed.

 To run the utility:

1. Do one of the following:
• Control-M/EM: Do one of the following:
o UNIX: Log on to a Control-M/EM account.
o Windows: Open a command prompt window and go to <Control-M EM
home>\Default\bin\DBUtils.
• Control-M/Server: Do one of the following:
o UNIX: Log on to a Control-M/Server account.
o Windows: Open a command prompt window and go to
<Control-M/Server>\ctm_server\exe\DBUtils.
2. Type the following command:
DBUStart
[ -TRACE_LEVEL <error|log|info> ]
[ -HELP ]
[ -POSTGRES_DEBUG <Y|N> ]
For more information about the DBUStart utility, see DBUStart utility parameters (on page 576) and
DBUStart utility example.
NOTE: If the database server has already been started, the utility returns a "failed" status and a
message similar to the following is issued:
sh-500 - sh-500 module : 500 - Server is already up
The following example describes a DBUStart utility sample output:
PostgreSQL server started

575
Control-M Utilities Guide

DBUStart utility parameters

The following table describes the DBUStart utility parameters:

Parameter Description

-TRACE_LEVEL Trace level. Valid values: error, log, info. Default: error. Optional.
Use this option only when instructed to do so by BMC Customer
Support. Using this option can slow performance and use extra
disk space.

-HELP Displays the usage, then exits with success status.

-POSTGRES_DEBUG Enables you to view the PostgreSQL debug log.

Running the DBUStop utility

This procedure describes how to run the DBUStop utility, which enables you to stop the database server
and the related services. When invoking this utility with a PostgreSQL database, the utility is only enabled
on Control-M/EM or Control-M/server running with a dedicated PostgreSQL database server.
NOTE: If this option is invoked on Control-M/EM or Control-M/Server running with an existing PostgreSQL
database, an error message is displayed.
 To run the DBUStop utility:
1. Do one of the following:
• Control-M/EM: Do one of the following:
o UNIX: Log on to a Control-M/EM account.
o Windows: Open a command prompt window and go to <Control-M EM
home>\Default\bin\DBUtils.
• Control-M/Server: Do one of the following:
o UNIX: Log on to a Control-M/Server account.
o Windows: Open a command prompt window and go to
<Control-M/Server>\ctm_server\exe\DBUtils.
2. Type the following command:
DBUStop
[ -TRACE_LEVEL <error|log|info> ]
[ -HELP ]
[ -FORCE <Y|N> ]
For more information on DBUStop utility, see DBUStop utility parameters (on page 577).

576
Control-M Utilities Guide

DBUStop utility parameters

The following table describes the DBUStop utility parameters:

Parameter Description

-TRACE_LEVEL Trace level. Valid values: error, log, info. Default: error.
Optional.
NOTE: Use this option only when instructed to do so by BMC
Customer Support. Using this option can slow performance and
use extra disk space.

-HELP Displays the usage, then exits with success status.

-FORCE Enables the database server processes and listener to abort.

Valid values:
 Y
 N (default)

Running the DBUVersion utility

This procedure describes how to run the DBUVersion utility, which enables you to displays the general
description of the database server, including the version number.

 To run the utility:

1. Do one of the following:
• Control-M/EM: Do one of the following:
o UNIX: Log on to a Control-M/EM account.
o Windows: Open a command prompt window and go to <Control-M EM
home>\Default\bin\DBUtils.
• Control-M/Server: Do one of the following:
o UNIX: Log on to a Control-M/Server account.
o Windows: Open a command prompt window and go to
<Control-M/Server>\ctm_server\exe\DBUtils.
2. Type the following command:
DBUVersion
[ -TRACE_LEVEL <error|log|info> ]
[ -HELP ]
For more detail about the DBUVersion utility, see DBUVersion utility parameters (on page 578).

577
Control-M Utilities Guide

The following example describes a DBUVersion utility sample output:

PostgreSQL 9.2.8 compiled by Visual C++ build 1600, 64-bit

DBUVersion utility parameters

The following table describes the DBUVersion utility parameters:

Parameter Description

-TRACE_LEVEL Trace level. Valid values: error, log, info. Default: error.
Optional.
NOTE: Use this option only when instructed to do so by BMC
Customer Support. Using this option can slow performance and
use extra disk space.

-HELP Displays the usage, then exits with success status.

DBUStatus
The DBUStatus utility displays database client details for all supported databases.
Control-M/Server: Displays various PostgreSQL server and client details.
Control-M/EM: Displays various server and client details.
 DB Type
 Is Up
 Is Remote DB
Last Startup Time
 DB Server OS Version
 DB Server Host Name
 DB Server OS Type
 DB Server Archive Directory
 DB Server Port
 DB Client OS Version
 DB Client Host Name

578
Control-M Utilities Guide

 DB Client OS Type
 Number of Connections
 Number of Backend Processes
 DB Server Version
 DB Client Version
To run the DBUStatus utility, see Running the DBUStatus utility (on page 579).

Running the DBUStatus utility

This procedure describes how to run the DBUStatus utility, which enables you to display database client or
Server details for all supported databases.

 To run the utility:

1. Do one of the following:
• Control-M/EM: Do one of the following:
o UNIX: Log on to a Control-M/EM account.
o Windows: Open a command prompt window and go to <Control-M EM
home>\Default\bin\DBUtils.
• Control-M/Server: Do one of the following:
o UNIX: Log on to a Control-M/Server account.
o Windows: Open a command prompt window and go to
<Control-M/Server>\ctm_server\exe\DBUtils.
2. Type the following command:
DBUStatus
[ -TRACE_LEVEL <error|log|info> ]
[ -HELP ]
[ -PRIMARY <Y|N> ]
[ -CONNECTION_DETAILS <Y|N> ]
For more details on the DBUStatus utility, see DBUStatus utility parameters (on page 580) and DBUStatus
utility for Control-M/Server example (on page 580).

579
Control-M Utilities Guide

DBUStatus utility parameters

This table describes the DBUStatus utility parameters:

Parameter Description

-TRACE_LEVEL Trace level. Valid values: error, log, info. Default: error.
Optional.
NOTE: Use this option only when instructed to do so by BMC
Customer Support. Using this option can slow performance and
use extra disk space.

-HELP Displays the usage, then exits with success status.

-PRIMARY Displays the mirror database.

-CONNECTION_DETAILS Displays the number of connections to the database.

DBUStatus utility for Control-M/Server example

The following example describes a DBUStatus utility sample output:
DB=PostgreSQL
Current DB status=Up
Up Time= 2017-03-06 02:57:07.327+02
Is DB Remote=false
Server Host Name=cyborg
Server Host Version=6.2.9200 Microsoft Windows Server 2012 Server Standard
Client Host Name=cyborg
Client Host Version=6.2.9200 Microsoft Windows Server 2012 Server Standard
DB Server Version=9.2.8
DB Server Version=PostgreSQL 9.2.8
Port=5432
Archive Mode for Hot Backup =off
Archive Mode for Replication=off

580
Control-M Utilities Guide

DBUStorage
The DBUStorage utility displays the following attributes of Control-M/EM or Control-M/Server for all
supported databases:
 DB Name
 Type
 Size - refers to the operating system disk space
 Free
 Used
 Used percentage
 Location
 Message - Warns the user when there is diminished disk space capacity within the Control-M/EM
database server
 Recommendation

Running the DBUStorage utility

This procedure describes how to run the DBUStorage utility, which enable you to display various
attributes of Control-M/EM for all supported databases. For more information, see DBUStorage (on page
581).

 To run the utility:

1. Do one of the following:
• Control-M/EM: Do one of the following:
o UNIX: Log on to a Control-M/EM account.
o Windows: Open a command prompt window and go to <Control-M EM
home>\Default\bin\DBUtils.
• Control-M/Server: Do one of the following:
o UNIX: Log on to a Control-M/Server account.
o Windows: Open a command prompt window and go to
<Control-M/Server>\ctm_server\exe\DBUtils.
2. Type the following command:
DBUstorage
[ -TRACE_LEVEL <error|log|info> ]
[ -HELP ]
For more details about the DBUStorage utility, see DBUStorage utility parameters (on page 582) and
DBUStorage utility example (on page 582)

581
Control-M Utilities Guide

DBUStorage utility parameters

This table describes the DBUStorage utility parameters:

Parameter Description

-TRACE_LEVEL Trace level. Valid values: error, log, info. Default: error.
Optional.
Use this option only when instructed to do so by BMC Customer
Support. Using this option can slow performance and use extra
disk space.

-HELP Displays the usage, then exits with success status.

DBUStorage utility example

The following example describes a DBUStorage utility sample output:
DB name = ctrlm900
Type = data+log
Size = 17171 MB
Free = 17163 MB
Used = 7 MB
Used_percentage = 0.05%
Location = <Control-M Installation Device>
Message = none
Recommendation = none

Running the DBUTransactions utility

This procedure describes how to run DBUTransactions utility, which enables you to list all active
transactions of the Control-M/EM database or Control-M/Server databases.
 To run the utility:
1. Do one of the following:
• Control-M/EM: Do one of the following:
o UNIX: Log on to a Control-M/EM account.
o Windows: Open a command prompt window and go to <Control-M EM
home>\Default\bin\DBUtils.
• Control-M/Server: Do one of the following:
o UNIX: Log on to a Control-M/Server account.

582
Control-M Utilities Guide

o Windows: Open a command prompt window and go to

<Control-M/Server>\ctm_server\exe\DBUtils.
2. Type the following command
DBUTransactions
[ -TRACE_LEVEL <error|log|info> ]
[ -HELP ]
For details about the DBUTransactions utility, see DBUtransactions utility parameters (on page 583) and
DBUtransactions utility example (on page 583).

DBUtransactions utility parameters

This table describes the DBUtransactions utility parameters:

Parameter Description

-TRACE_LEVEL Trace level. Valid values: error, log, info. Default: error.
Optional.
Use this option only when instructed to do so by BMC Customer
Support. Using this option can slow performance and use extra
disk space.

-HELP Displays the usage, then exits with success status.

DBUtransactions utility example

The following example describes a DBUtransactions utility sample output:
Sample output
number of connections = 2
connection 1 db_name=ctrlm900 os_proc=1024172 user_name=ctmuser
query_start_time=2016-07-09 07:03:59.125859 client_ip=137.72.205.101
connection 2 db_name=ctrlm900 os_proc=639076 user_name=ctmuser
query_start_time=2016-07-09 07:27:53.37908 client_ip=137.72.205.101
number of transactions = 1
transactions 1 db_name=ctrlm900 os_proc=1011810 user_name=ctmuser
query_start_time=2016-07-09 07:28:09.797397 client_ip=137.72.205.101
current_transaction=select dbu_transactions('1215577688620000000000')
number of locks = 0

583
Control-M Utilities Guide

Running the DBUShow utility

This procedure describes how to run the DBUShow utility, which enables you to display the configuration
parameters of all supported databases and the Control-M/EM database client or Control-M/Server
NOTE: Configuration parameters are sorted alphabetically.

 To run the utility:

1. Do one of the following:
• Control-M/EM: Do one of the following:
o UNIX: Log on to a Control-M/EM account.
o Windows: Open a command prompt window and go to <Control-M EM
home>\Default\bin\DBUtils.
• Control-M/Server: Do one of the following:
o UNIX: Log on to a Control-M/Server account.
o Windows: Open a command prompt window and go to
<Control-M/Server>\ctm_server\exe\DBUtils.
2. Type the following command:
DBUShow
[ -TRACE_LEVEL <error|log|info> ]
[ -HELP ]
For more details about the DBUShow utility, see DBUShow utility parameters (on page 584) and
DBUShow utility example (on page 585).

DBUShow utility parameters

This table describes the DBUShow utility parameters:

Parameter Description

-TRACE_LEVEL Trace level. Valid values: error, log, info. Default: error.
Optional.
Use this option only when instructed to do so by BMC Customer
Support. Using this option can slow performance and use extra
disk space.

-HELP Displays the usage, then exits with success status.

584
Control-M Utilities Guide

DBUShow utility example

The following example describes a DBUShow utility sample output:
Following configuration parameters are issued and more:
add_missing_from=off source=default
allow_system_folder_mods=off source=default
archive_command= source=configuration file
archive_timeout=0 source=default
array_nulls=on source=default
authentication_timeout=60 source=default
autovacuum=on source=configuration file
autovacuum_analyze_scale_factor=0.1 source=default
autovacuum_analyze_threshold=250 source=default
autovacuum_freeze_max_age=200000000 source=default
autovacuum_naptime=60 source=default
autovacuum_vacuum_cost_delay=-1 source=default
autovacuum_vacuum_cost_limit=-1 source=default
autovacuum_vacuum_scale_factor=0.2 source=default
autovacuum_vacuum_threshold=500 source=default

585
10
10
Security
The security utilities define the security authorizations for various users and Control-M components,
including:
 User registration and password changes
 Access to databases and other components
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.
Some of the parameter names changed for Control-M version 8.0.00 and above, terminology from
previous versions is still supported. For a complete list of the parameter names, see Abbreviations and
conventions.
The following utilities are used to define security authorizations for various users and Control-M
components:
 emcryptocli (on page 586): Creates an encrypted version of the password you submit.
 ctmsec (on page 588): Protects Control-M against unauthorized usage or modification.
 ctmsetown (on page 597): Manages the details of Control-M/Agent and remote host users.
 ctmpasswd (on page 602): Enables you to change the Control-M/Server User’s password for accessing
the database.
 ctmpwd (on page 603): (Windows only) Create and modify Control-M/Agent users and passwords.

emcryptocli
The emcryptocli utility creates an encrypted version of the password you submit. To run the emcryptocli
utility, see Creating an encrypted password using the emcryptocli utility (on page 587).
If the Control-M/EM database 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 emcryptocli utility to generate the encrypted version of your new
password.
Usage: You can invoke emcryptocli in either of the following modes:
 Trial mode: You submit the new password and emcryptocli creates an output text file in the
specified location containing the encrypted version of that password. You can copy the encrypted text
to appropriate places in the mcs.ini file manually.
 Operational mode: When you submit your username and new password, emcryptocli creates an
encrypted version of the password and inserts it in the appropriate places in the text of the mcs.ini
file. mcs.ini is saved automatically.

586
Control-M Utilities Guide

Creating an encrypted password using the emcryptocli utility

This procedure describes how to run the emcryptocli utility in trial or operation mode, which creates an
encrypted version of the password you submit.
 To create an encrypted password using the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM database account.
• Windows: Open a command prompt window where Control-M/EM is installed.
2. Type one of the following commands:
• For trial mode: emcryptocli <string to encrypt> <output file name>
• For Operation mode: emcryptocli <user name> <user password> <path to mcs.ini>
For the Control-M parameter name, see Parameter name cross references (on page 31). For more
information, see emcryptocli utility parameters (on page 587).

emcryptocli utility parameters

The following table describes the emcryptocli utility trial and operation mode parameters:

Item Description

<string to Defines the new password string to encrypt.

encrypt>

<output file (Trial Mode only) Full path name of the output file created by
name> emcryptocli. The file contains the encrypted version of the password
that was submitted.

<user name> (Operation Mode only) Control-M/EM database administrator user

name.

<user password> (Operation Mode only) Control-M/EM database administrator password.

<path to mcs.ini> (Operation Mode only) Full path name of the mcs.ini file (for example,
windir\system32\mcs.ini).

587
Control-M Utilities Guide

ctmsec
The ctmsec utility can be invoked in interactive or batch mode. For more information about Control-M
security concepts, see Control-M security .
The ctmsec utility is used to:
 Add, delete, or modify specific users in the Control-M Security database
 Add, delete, or modify specific groups in the Control-M Security database
 Assign authorizations to a user or group to perform actions on a Folder
 Assigns authorizations to a user or group to perform actions relating to Control-M entities
The following topics are discussed in this section:
 Security considerations (on page 588)
 Security maintenance utility (Interactive mode) (on page 589)
 Security maintenance utility (Batch mode) (on page 594)
 Exporting security definition folders (on page 596)
 Importing security definition folders (on page 597)
For the Control-M parameter name, see Parameter name cross references (on page 31).

Security considerations
Control-M/Server includes security features that protect Control-M against unauthorized usage or
modification. These features enhance the standard UNIX and Windows security, and provides an
additional application-level security layer. Using Control-M security, you can specify actions that each
Control-M/EM user or Control-M/Server user is authorized to perform. These authorizations are used to
perform security checks each time one of the following actions is attempted:
 Accessing a Folder (to add, delete, or modify a job definition)
 Ordering, selecting and submitting a job.
 Commands affecting jobs in Active Jobs database (for example, Hold, Confirm, Rerun).
 Maintenance of Control-M entities (for example, calendars, prerequisite conditions).
Security verifications for the above actions are implemented according to the specifications in a database
of authorizations. This database can be modified by the security officer or systems manager to meet the
needs of the enterprise. For more information, see Security maintenance utility (Interactive mode) (on
page 589)
Control-M provides the following levels of application security for users not explicitly defined in the
Control-M Security database:

588
Control-M Utilities Guide

 Restricted: A user not defined in the Control-M Security database is regarded as having no
authorizations and cannot perform any function requiring security authorization.
 Unrestricted: A user not defined in the Control-M Security database is regarded as having all
Control-M application authorizations.
The security level is determined by the value of the Control-M system parameter Full Security. If SSL is
installed, Secure Sockets Layer encryption and compression provide security for Control-M/Server
communication with Control-M/EM and Control-M/Agents. For more information, see the SSL
Management.
Regardless of which level is implemented, a user, for whom one or more authorizations have been
assigned in the Security database, can only perform those actions. The user of each job processing
definition must be defined as a user on the agent computer, otherwise, Control-M/Agent will not execute
the job.
When working with the Control-M/Server Security facility, wildcard characters are available for all options.
Wildcard characters * and $ are translated during runtime security checking. (For example, if User1 is
granted full Folder authorization for folder ACC*, Control-M allows User1 to update or order any folder
whose name starts with ACC).
Valid wildcard characters:
* represents any number of characters (including none).
$ represents a single character.
Wildcard character authorizations do not override full name authorizations. (For example, if User1 from
the example above is also defined to have only Read privileges for ACC999, Control-M will not allow User1
to update or order folder ACC999).

Security maintenance utility (Interactive mode)

The ctmsec Control-M Security Maintenance utility defines users in the Control-M Security database and
assigns authorizations required for working with Control-M using the Control-M Configuration Manager.
ctmsec runs on the Control-M/Server computer.
Changes made by this utility are implemented only after you exit the utility.
Users can be defined as part of a group. Authorizations can be specified for a specific user, for a group, or
for both. See Security maintenance utility (Batch mode) (on page 594).
When assigning a user to a group, the following rules apply:

589
Control-M Utilities Guide

 If there are no authorizations defined for the user, the user inherits the authorizations for the group.
 If there are authorizations defined for a user, these authorizations take precedence.
 When defining an authorization for a user (for example, Folder), use of the (D)efault setting enables
the specific authorization (for example, Read) defined for the group.
 If all of a user’s authorizations for a specific Control-M element (for example, Folder) are defined with
a (D)efault setting, the user’s authorizations for that element can be deleted more efficiently.
 Authorizations not specifically defined for a group, or for a user not belonging to a group, revert to
the Full Security parameter setting. See ctmsys (on page 448)
Certain functions of the ctmsec utility can be activated directly from a command line. For more
information, see Security maintenance utility (Batch mode) (on page 594). In addition, certain functions
of the ctmsec utility can be activated using the Control-M Configuration Manager. For more information,
see Control-M security.
The security of Sub-folders and jobs within Sub-folders is determined according the security that is set for
SMART folders.

User maintenance
The User Maintenance option of the ctmsec utility is used to add, delete, or modify specific users in the
Control-M Security database.
Each Control-M/EM user who performs actions affecting the Control-M/Server database or jobs in the
Active Jobs database must be defined in the Control-M Security database when full security is on. In
addition, all other users who invoke Control-M Security utilities must be defined in the Security database
and assigned appropriate privileges.
If the user in the commands listed below is a Control-M/Agent user, then the <user> format is
<username@HOST_ID>.

Configuring users in the Control-M Security database using ctmsec utility

This procedure describes how to add, delete, or modify specific users in the Control-M Security database.
 To configure users in the Control-M Security database:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type ctmsec command and then the select the User Maintenance Menu option.
3. Select one or more of the following options:
• List all existing users.
• Add a new user by doing the following:
a. Type Y to add the new user
b. Add a description and a value for the group.

590
Control-M Utilities Guide

• Delete an existing user by specifying the user name to delete which is deleted from the Security
database.
• Modify an existing user by doing the following:
c. Type the name of the user.
d. Select the information that you want to modify.
• Copy an existing user by doing the following:
e. In the FROM user field, type the exact name of the user to be copied.
f. In the TO user field, type a new user name for the Control-M/EM user (maximum 30
characters, case-sensitive).
g. Enter Y to add the new user.
NOTE: Description (maximum length 50 characters) is optional and for documentation purposes only.
Group (maximum length 32 characters) is optional and if used the user inherits all authorizations
defined for the group that are not specifically defined for the user.

Group maintenance
Each user who has a user account on the Control-M/Server computer and who is defined in the Control-M
Security database, can be defined as part of a group. Belonging to a group is optional. All users belonging
to a group inherit the authorizations defined for the group.
Select Option 2 from the Security Maintenance Main Menu to display the Group Maintenance menu.
Group Maintenance Menu
-----------------------
1) List Groups
2) Add Group
3) Delete Group
4) Modify Group Information
q) Quit
Enter option:

Configuring groups in the Control-M Security database

This procedure describes how to view, add, delete or modify existing groups in the Control-M Security
database.

 To configure groups in the Control-M Security database:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type ctmsec command and then the select the Group Maintenance Menu option.

591
Control-M Utilities Guide

3. Select one or more of the following options:

• List existing groups
• Add a new group by typing a group name and description.
NOTE: Group Name (maximum length 32 characters) must be unique and cannot be an existing
user or group name.
• Delete an existing group by typing group name to delete.
• Modify the description field by typing the group name and description.
NOTE: Description (maximum length 50 characters) is optional and for documentation purposes
only.

Folder authorization
This option is used to assign authorizations to a user or group to perform actions on a Folder.
Select Option 3 from the Security Maintenance Main Menu to display the Folder Authorization menu.
For more information about the types of authorization that can be granted using this option, see Folder
Authorization options in Security maintenance utility (Batch mode) (on page 594).

Configuring folder authorizations in Control-M Security database

This procedure describes how to view, create, modify or delete folder authorizations in the Control-M
Security database.

 To configure folder authorizations in Control-M Security database:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type ctmsec command and then the select the Folder Authorization option.
3. In the User/Group field, type the user or group that you want to configure.
4. Select one or more of the following options:
• View a list of folder authorizations
• Create or modify folder authorizations by doing the following:
a. Type the name of the folder.
NOTE: Maximum 20 characters, case-sensitive. The folder does not have to exist at the time
you specify authorizations for it.
A folder definition menu appears.

592
Control-M Utilities Guide

The Y setting enables authorization for the action (for example, Read), N disables the
authorization, and (D)efault uses the authorization defined for the user’s group. If the user
was previously authorized for this folder, the user’s current authorizations are displayed;
otherwise, all authorizations are set to N.
b. Type s to save your changes.
• Delete folder authorization by typing the folder name you want to delete.

Active Jobs authorization option

This option is used to assign authorizations to a user or group for actions on jobs in the Active Jobs
database. The authorizations assigned are with regard to specific job owners (the user appearing in the
Owner parameter for each job).
When creating or modifying a job, working in full security mode and ordering SMART Folders where Y has
been specified for Order, BMC recommends to specify Y also for Hold. The SMART Folder remains in
Hold status if the user has only ORDER/FORCE permissions. In addition, if you did not specify an asterisk
(*) for the Host Group prompt, you need to create another Active Jobs database authorizations for the
specified user for the SMART folder and Sub-folder entities, in which in the Host Group prompt, you
must specify the local hostname of the Control-M/Server. Do this by running ctm_menu and then from the
Control-M Main Menu select option 5 - Parameter Customization, then option 1 - Basic
Communication and Operational Parameters and then 1 - Local IP Host Interface Name.
For more information about the types of authorization that can be granted using this option, see Active
Jobs Authorization in Security maintenance utility (Batch mode) (on page 594).

Configuring Active Jobs authorizations

This procedure describes how to view, create, modify of delete Active Jobs authorizations.

 To configure Active Jobs authorizations:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type ctmsec command and then the select the Active Jobs File Authorization option.
3. In the User/Group field, type the user or group that you want to configure.
4. Select one or more of the following options:
• View Run As Names for whom the user has Active Jobs authorizations.
• Create or modify Active Jobs authorizations by doing the following:
a. Type the Run As and Host Group fields.
NOTE: The host group of the Agents where the job can be scheduled to run (maximum 30
characters, case-sensitive). A value must be specified for the Host Group prompt. To indicate
all host groups, specify an asterisk (*). The Y setting enables authorization for the action (for
example, Read), N disables the authorization, and (D)default uses the authorization defined
for the user’s group. If the user was previous authorized for this owner and host, the user’s
current authorizations are displayed; otherwise, all authorizations are set to N.

593
Control-M Utilities Guide

b. Type s to save your changes.

• Delete Active jobs authorizations by typing the Run As name and then the Host group of the Run
As Name.

Entities authorization
This option assigns authorizations to a user or group to perform actions relating to Control-M entities.
For more information about the types of authorization that can be granted using this option, see Entities
Authorization Option in Security maintenance utility (Batch mode) (on page 594).

Configuring Entities authorizations

a. This procedure describes how to maintain Entities authorizations.

 To maintain Entities authorizations:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type ctmsec command and then the select the Entities Authorization option.
3. In the User/Group field, type the user or group that you want to configure.
4. Select one or more of the following options:
• View entity categories
• Create or modifying entity authorizations by doing the following:
a. Type option you want to create or modify authorizations.
The Y setting enables the specific authorization (for example, Read), N disables the
authorization, and (D)efault uses the authorization defined for the group with which the user
is associated. If the user was previous authorized for this category, the user’s current
authorizations are displayed; otherwise, all authorizations are set to N.
b. Type s to save your changes and return to the previous menu. Modifications are not saved
until you perform this action.
• Delete entity authorizations by typing the relevant category.

Security maintenance utility (Batch mode)

Certain ctmsec Security Maintenance utility functions can be activated in batch mode. These functions
include listing, updating, and deleting entries in the Control-M Security database. These functions are
described in Security maintenance utility (Interactive mode) (on page 589) .
User authorization
The user authorization options of the ctmsec command are used to list, update, delete, and copy users in
the Control-M Security database.

594
Control-M Utilities Guide

 Use the following command to list user authorizations:

ctmsec -USER_LIST <user>
 Use the following command to update user authorizations:
ctmsec -USER_UPDATE <user> <description> <group>
 Use the following command to delete user authorizations:
ctmsec -USER_DELETE <user>
 Use the following command to copy user authorizations from one user to another:
ctmsec -USER_COPY <from_user> <to_user>
NOTE: If the user in the commands listed above is a Control-M/Agent user, then the <user> format is
<username@host_id>.
Group authorization
Group authorization options of the ctmsec command are used to list, modify, and delete groups in the
Control-M Security database.
 Use the following command to list group authorizations:
ctmsec -GROUP_LIST <group>
 Use the following command to update group authorizations:
ctmsec -GROUP_UPDATE <group> <description>
 Use the following command to delete group authorizations:
ctmsec -GROUP_DELETE <group>
Folder authorization option
The Folder authorization options of the ctmsec command are used to assign authorizations to users and
groups to perform actions on Folders.
 Use the following command to list Folder authorizations:
ctmsec -SCHED_LIST {<user>|<group>}
 Use the following command to update Folder authorizations:
ctmsec -SCHED_UPDATE {<user>|<group>} <folder> [-DELETE {Y|N|D}]
[ -READ {Y|N|D}]
[ -ORDER {Y|N|D}] [ -UPDATE {Y|N|D}]
 Use the following command to deleteFolder authorizations:
ctmsec -SCHED_DELETE {<user>|<group>} <folder>
NOTE: If the user in the commands listed above is a Control-M/Agent user, then the <user> format is
<username@host_id>.
Active Jobs database authorization
The Active Jobs database authorization options of the ctmsec command are used to assign authorizations
to users and groups to perform actions on jobs in the Active Jobs database.
 Use the following command to list Active Jobs database authorizations:
ctmsec -ACT_LIST {<user>|<group>}
 Use the following command to update Active Jobs database authorizations:
ctmsec -ACT_UPDATE {<user>|<group>} <owner> <host>
[-HOLD {Y|N|D}]

595
Control-M Utilities Guide

[-FORCE {Y|N|D}]
[-ORDER {Y|N|D}]
[-CONFIRM {Y|N|D}]
[-DELETE {Y|N|D}]
[-WHY {Y|N|D}]
[-RERUN {Y|N|D}]
[-OUTPUT {Y|N|D}]
[-LOG {Y|N|D}]
[-STATISTICS {Y|N|D}]
[-ZOOM_AND_SAVE {Y|N|D}]
[-KILL_JOB {Y|N|D}]
 Use the following command to delete Active Jobs database authorizations:
ctmsec -ACT_DELETE {<user>|<group>} <owner> <host>
NOTE: If the user in the commands listed above is a Control-M/Agent user, then the <user> format is
<username@host_id>.
Entities authorization options
The entity authorization options of the ctmsec command are used to assign authorizations to users and
groups to perform actions relating to Control-M entities.
 Use the following command to list entity authorizations:
ctmsec -ENTITY_LIST {<user>|<group>}
 Use the following command to update entity authorizations:
ctmsec -ENTITY_UPDATE {<user>|<group>}
{LOG|QR|Control|CALENDAR|CONDITION}
[-ADD {Y|N|D}] [-DELETE {Y|N|D}] [-CHANGE {Y|N|D}]
 Use the following command to delete entity authorizations:
ctmsec -ENTITY_DELETE {<user>|<group>}
{LOG|QR|Control|CALENDAR|CONDITION}
NOTE: If the user in the commands listed above is a Control-M/Agent user, then the <user> format is
<username@host_id>.

Exporting security definition folders

The EXPORT option of the ctmsec command is used to export Control-M Security Definition folders. The
file that is generated by the ctmsec command is an execufolder file containing API functions that will
redefine all the security entries when the script is run. The generated file can be modified and imported to
any Control-M installation.

596
Control-M Utilities Guide

The file created by the EXPORT option of the ctmsec utility can be modified before security definitions are
imported back to the same (or a different) Control-M/Server installation. This is different from the file that
is created using the Backup Security Definition Folders option of the Security Authorization Menu (which
cannot be modified).
Use the following command to export Control-M Security Definition folders:
ctmsec -EXPORT <fileName>
<fileName> is the full path name of the file to be exported.
ctmsec -EXPORT /home/controlm/securedata

Importing security definition folders

The file created using the -EXPORT option of the ctmsec utility contains multiple ctmsec commands that
describe the various security definitions in your Control-M installation. If necessary, these ctmsec
commands can be modified before the security definitions are imported back to the same or a different
Control-M installation.
Importing updates the security definitions in your Control-M installation. Use the restore security
procedure to replace security definitions.
 To import definition folders:
 Execute the script file that was created using the ctmsec utility.
/home/controlm/securedata
NOTE: This procedure will work only with a file that was created using the -EXPORT option of the ctmsec
utility. If your input is a file created using the Backup Security Definition Folders option of the Security
Authorization menu, then you must import using the Restore option in that same menu.

ctmsetown
The ctmsetown command line utility manages the authentication credentials of job owners for both local
and agentless jobs. In addition, the ctmsetown utility also enables the authentication details of users to
be imported or exported from different Control-M environments. To run the ctmsetown utility see Running
the ctmsetown utility (on page 598).
When a job is submitted, Control-M/Server attempts to find the owner and hostname authentication
details.
 If the owner and hostname are found, Control-M/Server uses these credentials.
 If the specified hostname is not found, Control-M/Server tries to find the owner on host <All>.
 If the run_as is found on host <All>, Control-M/Server uses these credentials.
 If the run_as is not found on the specified hostname or on host <All>, Control-M/Server uses empty
credentials.
Using ctmsetown through Control-M/Agent, the functionality of the ctmsetown utility (when invoked from
Control-M/Agent), is limited to updating passwords of existing owners. Using the utility, job owner
passwords can be updated through Control-M/Agent for:

597
Control-M Utilities Guide

 Jobs running on agentless hosts

 Jobs running on Control-M/Agent for Windows that is configured to work in 'logon as user' mode"
 Jobs running on Control-M/Agent for UNIX that is running in non-root mode

Running the ctmsetown utility

This procedure descrbies how to run the ctmsetown utility, which manages the authentication credentials
of job owners for both local and agentless jobs.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this command where Control-M/Agent is installed.
2. Type one of the following commands:
o ctmsetown -action add -run_as <user name> -host <host name>
[-password <password> | -keyname <key name> [-passphrase <key
passphrase>]]
o ctmsetown -action update -run_as <user name> -host <host name>
[-password <password> | -keyname <key name > [-passphrase <key
passphrase>]]
o ctmsetown -action delete -run_as <user name> -host <host name>
o ctmsetown -action list [-run_as <user name>] [-host <host name>]
o ctmsetown -action export -filename <export file name>
o ctmsetown -action import -filename <import file name> -data
append|truncate
o ctmsetown help
3. Specify the following command to invoke the ctmsetown utility from Control-M/Agent:
ctmsetown -action update -owner <user name> -host <host name> -password <new
password> -oldpassword <old password>
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on ctmsetown utility, see ctmsetown utility action parameters (on page 599), ctmsetown utility
parameters (on page 600) and ctmsetown utility examples (on page 600).

598
Control-M Utilities Guide

ctmsetown utility action parameters

The following table describes the actions in the ctmsetown utility:

Action Description

add Specifies the security details of a new owner entry (user).

update Modifies the security details of an existing owner entry (user).

delete Removes the security details of an owner entry. The owner name and host
name must match an existing entry in the folder.

list Lists the details of the user.

Wildcards can be used to specify -owner and -host parameters, as follows:
 * represents any number of characters
 ? represents any single character

export Exports the security details of the existing users to a text file.
ctmsetown -action export -filename
$HOME/ctm_server/data/user_report.txt

import Imports the details of the users stored in the specified import file.

help Displays the usage of the ctmsetown utility.

599
Control-M Utilities Guide

ctmsetown utility parameters

The following table describes the ctmsetown utility parameters:

Parameter Description

-run as (Owner) Specifies the name of the user under whose name the job will run.

-host Specifies the name of the computer where the owner of the job is defined.
Specify <All> to include all hosts.
ctmsetown -action delete -run_as s -host "<All>"

-password Specifies the password of the owner. The password cannot exceed 120
characters.

-old password Specifies the existing password that the user is changing. This parameter is
mandatory only when the ctmsetown utility is executed from the agent.

-key name The logical name of the key. The key itself is kept in a separate folder with
its passphrase. For more information about generating and maintaining the
key, see ctmkeygen. The same key can be used for multiple users.

-pass phrase (Used if -keyname is defined) Specifies the phrase used to encrypt the key
itself.

-file name Specifies the name of the file that contains the security details of the users.
The filename cannot exceed 1024 characters.
This parameter is used only when either -action export or -action import is
specified.

-data Describes what action to take with the data from the imported text file.
Valid actions are:

append details of the users from the imported text file are added
to the existing users

truncate details of the users from the imported text file replace the
details of the existing users

ctmsetown utility examples

The following are examples of the ctmsetown utility commands that are run from Control-M/Server, apart
from the last example which is run from Control-M/Agent.
To create an entry with the security details of a user whose name is username1, the name of the host
computer is saturn and the user password is pass01, specify the following command:

600
Control-M Utilities Guide

ctmsetown -action add -run_as username1 -host saturn -password pass01

The following message is displayed:
Entry created successfully.
Create a user entry as in the first example, however, use the keyname k1 and passphrase BMC user.
Specify the following command:
ctmsetown -action add -run_as username1 -host saturn -keyname k1 -passphrase
"BMC user"
The following message is displayed:
Entry created successfully.
Assume that the security details of the run_as, described in the first example, already exists. To change
the password from pass01 to newpass, specify the following command:
ctmsetown -action update -run_as username1 -host saturn -password newpass
The following message is displayed:
Entry updated successfully.
To delete the user entry created in the first example, specify the following command:
ctmsetown -action delete -run_as username1 -host saturn
The following message is displayed:
Entry deleted successfully.
To list the security details of user entries, specify the following command:
ctmsetown -action list
Run_as Host Password/Key Flag Key value
----- ---- -----------------
---------
jupiter saturn Key Key1
jupiter venus Password Not
Applicable
2 entries were found.
To create an export text file containing a list of security details of user entries, specify the following
command:
ctmsetown -action export -filename /home/ctm900oe/sec.exp
The following is displayed:
Exporting data, please wait...
Export ended successfully.
Check report file
~<controlm_run_as>/ctm_server/proclog/export_report_53d1.txt’ for details.
To import the /home/ctm900oe/sec.exp text file created in the sixth example, containing a list of
security user entries, and to replace the current security user information, specify the following command:

601
Control-M Utilities Guide

ctmsetown -action import -filename /home/ctm900oe/sec.exp -data truncate

The following is displayed:
Importing data, please wait...
Import ended successfully.
Check report file
~<controlm_run_as>/ctm_server/proclog/import_report_53d9.txt’ for details.
Example to show ctmsetown run from an agent computer to update the password of a user.
Assume that the old password of user agentuser1 is agntpass01. To change the password to newpass,
specify the following command:
ctmsetown -action update -run_as agentuser1 -host saturn -password newpass
The following message is displayed:
Entry updated successfully.

ctmpasswd
The ctmpasswd utility enables the administrator to change the Control-M/Server User’s password for
accessing the database. Only an administrator can change the password. To run the ctmpassword utility,
see Running the ctmpasswd utility (on page 602).

Running the ctmpasswd utility

This procedure describes how to run the ctmpasswd utility, which enables the administrator to change the
Control-M/Server User’s password for accessing the database.
 To run the utility:
1. Log in as a Control-M/Server user.
NOTE: If you are working in a high availability environment, you need to log into the inactive host,
shut down the CA, and then log into the active host and shut down the CA and Control-M/Server.
2. Shut down the Control-M/Server and the Control-M/Server Configuration Agent, by typing the
following commands:
• shut_ca
• shut_ctm
3. Type the following command:
ctmpasswd
NOTE: If you are working in a high availability environment, you need to change the password on the
active host and then on the inactive host.
4. Type the old password for the Control-M/Server account.
5. Type the new password.
The password must contain at least 6 characters.

602
Control-M Utilities Guide

6. Re-type the new password.

7. Start up the Control-M/Server and the Control-M/Server Configuration Agent, by typing the following
commands:
• start_ca
• start_ctm
NOTE: If you are working in a high availability environment, you need to start up the CA and
Control-M/Server on the active host, and then start up the CA on the inactive host.
For the Control-M parameter name, see Parameter name cross references (on page 31).

ctmpwd
The ctmpwd utility (Windows only) adds, updates, and deletes Control-M/Agent users and passwords. In
addition, it changes security settings for the agent directories and cmd.exe. It also lists all users in the
Control-M/Agent password file. (This utility replaces the ctmcpt utility in earlier versions.)
To run ctmpwd, you must be an administrator on the computer.
NOTE: You must manually give Logon as a Batch job rights to a new user.

Running the ctmpwd utility

This procedure describes how to run the ctmpwd utility, which enables you to add, update, and delete
Control-M/Agent users and passwords.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
NOTE: You can also run this command where Control-M/Agent is installed.
2. Run the following commands:
• CTMPWD -ACTION ADD|UPDATE|DELETE|LIST [-USER <user name>]
[[-OLD_PASSWORD <value>] -PASSWORD <value>] [-ADMIN_PASSWORD
<value>]]-GROUP <value> -AGENT <agent name> [-VERIFY <Y/N -default Y>]

603
Control-M Utilities Guide

EXAMPLE : Add a user and password

ctmpwd -action add -user user1 -password 12345
Add the administrator user
ctmpwd -action add -user admin -password abcde
Update a password
ctmpwd -action update -user user1 -old_password 12345 -password 67890
or
ctmpwd -action update -user user1 -admin_password abcde -password 67890
Delete a user
ctmpwd -action delete -user user1 -password 12345
or
ctmpwd -action delete -user user1 -admin_password abcde
List all users
ctmpwd -action list
Add a user to agent Saturn
ctmpwd -action add -user user3 -password 654321 -agent Saturn
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on ctmpwd utility, see ctmpwd parameters (on page 605) and ctmpwd examples (on page 605).

604
Control-M Utilities Guide

ctmpwd parameters
The following table describes the ctmpwd utility parameters:

Parameter Description

action Function to be executed.

Valid values: add, update, delete, and list.

user Name of the user.

When adding users, the user name must not exceed 20 characters.

old_password Current password for the update function.

password Current password for the delete function.

New password for the add and update functions.

admin_password Password for the Control-M/Agent administrator when executing the

update or delete function if the old_password is not known.

verify Verifies that the user and password. Valid values are:
 Y (default)
 N - Does not verify that the user and password are correct.

sub_application Adds the group SID (instead of the user SID) to cmd.exe and the
agent directories.

agent Name of the agent that the utility is designated to run on. For more
information, see Considerations for running utilities.

ctmpwd examples
In the following example, the ctmpwd utility enables the Control-M/Agent administrator to modify
passwords for users who have forgotten their password.
-admin_password
BMC recommends that the administrator first use the following command to establish a password for user
ADMIN:
ctmpwd -action add -user ADMIN -password <user_admin_password>
In the following example, the user is added but the group’s SID is registered.
ctmpwd –action add –user user1 –password user1 –group Everyone

605
11
11
Statistics and reporting
The statistics and reporting utilities generate and display various statistics.
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.
Some of the parameter names changed for Control-M version 8.0.00 and above, terminology from
previous versions is still supported. For a complete list of the parameter names, see Abbreviations and
conventions.
The following utilities generate and display various statistics:
 bim_report (on page 606): Generates reports for services that have completed execution.
 emreportcli (on page 608): Enables for the automation of the batch report execution process in a
selected format.
 ctmjsa (on page 612): Compiles and records runtime data from the Statistical Details table.
 ctmruninf (on page 615): Displays runtime data from the Statistical Details table of the
Control-M/Server database.
 ctmstats (on page 618): Displays and deletes statistical data from the Statistical Summary table of the
Control-M/Server database.

bim_report
Generates reports for services that have completed execution.
The bim_report utility can be run both on Microsoft Windows and UNIX operating systems from their
respective command lines. To run the utility see Running the bim_report utility (on page 606).

Running the bim_report utility

This procedure describes how to run the bim report utility, which enables you to generates reports for
services that have completed execution.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/EM database account.
• Windows: Open a command prompt window where Control-M/EM is installed.
NOTE: For Windows client installations, open a command prompt window and navigate to the <EM
Home>\Default\bin directory.
2. Type the following command:
bim_report -U <username>

606
Control-M Utilities Guide

-P <password>
[-O <output file name>]
[-N <service name>]
[-F <from date>]
[-T <to date>]
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the bim_report utility, see bim_report utility parameters (on page 607) and bim_report utility example
(on page 608).

bim_report utility parameters

The following table describes the bim_report utility parameters:

Parameter Description

-U username Name of the Control-M/EM user running the report, for security purposes.
Mandatory.

-P password Password of the Control-M/EM user running the report, for security
purposes. Mandatory.

-O output file Name and full path of the output file that will contain the generated
name report. Optional. If not specified, the report is displayed on the screen but
is not saved in a file.

-N service name Name of the service that should be listed in the report. Optional. If not
specified, the report runs for all services.

-F from date Services whose order date (Odate) is the same as, or later than, this from
date value are included in the report. The date and time format is
DD/MM/YYYY_HH:MI:SS or MM/DD/YYYY_HH:MI:SS format (depending
on the value of the DateFormat system parameter). Optional.
If not specified, services whose order date was on the previous day
or later are included in the report.

-T to date Services whose order date (Odate) is the same as, or earlier than, this to
date value are included in the report. The date and time format is
DD/MM/YYYY_HH:MI:SS or MM/DD/YYYY_HH:MI:SS format (depending
on the value of the DateFormat system parameter). Optional.
If not specified, services whose order date is the current date and
time or earlier are included in the report.

607
Control-M Utilities Guide

bim_report utility example

The following example describes running the bim_report utility parameters in Windows:
bim_report
-U emuser
-P empass
-O D:\Temp\my_report.txt
-N CD_service
-F 26/02/2016_08:34:00
-T 28/02/2016_23:34:00

emreportcli
The emreportcli utility enables the automation of the batch report execution process in a selected format.
This utility runs only on Windows in batch mode. To run the emreportcli utility, see Running the
emreportcli utility (on page 608).
You must specify Control-M/EM server login information when you invoke this utility.
Usage: Either of the following two options can be used to activate the emreportcli utility:
 Parameters can be entered as command line parameters
 An input arguments file can be generated with XML specifications. For more information, see
emreportcli input arguments file (on page 610)

Running the emreportcli utility

This procedure describes how to run the emportcli utility, which enables the automation of the batch
report execution process in a selected format.

 To run the utility:

1. Open a command prompt window where Control-M/EM is installed.
NOTE: For Windows client installations, open a command prompt window and navigate to the <EM
Home>\Default\bin32 directory.
2. Enter one of the following command and press Enter.
• emreportcli {-U <user> -P <password>) | -pf passwordFilename} -s <server
host name> -arg <xml file name>
• emreportcli {-u <user> -p <password> | -pf <password file>} -s <server
host name>
-template <templateName>
[-template_path <template path>]
-output_file_type EXCEL | EXCEL_DO | DOC | PDF | HTML | XML | CSV | TABBED
| CONSOLE

608
Control-M Utilities Guide

-output_file_path <output file path>

[-param <name>=<value>]…
The XML file name is the full path name of the input arguments file.
You can specify the user name and password on the command line, in a password file. For more details
on the emreportcli utility see the following:
 emreportcli report generation utility parameters (on page 609)
 emreportcli utility output argument file parameters (on page 609)
 emreportcli utility input arguments file parameters (on page 611)

emreportcli report generation utility parameters

The following table describes the emreportcli report generation utility parameters

Parameter Description

User Control-M/Enterprise Manager user name.

Password Control-M/Enterprise Manager user password.

Password File name Flat file containing an unencrypted username and password in the following
format: user=username password=password.
If both -U and -pf are specified, an error message is generated. If neither is
specified, an online prompt is issued for the Control-M/EM database owner
name and password.

Server Host Name Host name of the Control-M/EM Server.

To address a GUI Server when multiple GUI Servers exist, set this
parameter to the logical name of the relevant GUI Server.

emreportcli utility output argument file parameters

The following table describes the emreportcli utility output argument file parameters:

Parameter Attribute Description

Output File The report output file.

type Specifies the type of the output file, such as EXCEL,

EXCEL_DO (for data only), PDF, DOC, HTML, TXT, or XML.

609
Control-M Utilities Guide

Parameter Attribute Description

file path Specifies the full filename of the output file.

Param Specifies the name and value for each parameter in the form
name=value. Wildcard can be used for text fields.

Template Specifies the name of the template.

path Specifies the folder in which the template file is located.

emreportcli input arguments file

Input for the utility is an arguments file containing the XML specifications for the report to be generated,
including all required parameters. The following sample XML arguments file is provided at
em_home\Data\Reporting\sample_args.xml. A list of required elements and values for the arguments is
provided in the DTD file: em_home\Data\Reporting\emreportcli.dtd.
emreportcli {-u <user> -p <password> | -pf <password file>} -s
<server name> -arg <XML file name>
If you are using only a client installation you must include the ‘bin’ directory in the file path. For example:
c:\Program Files\<Instance Name>\bin\emreportcli.exe {-u <user> -p <password> | -pf <password
file>} -s <GUI Server Name> -arg <arguments file>.xml}
<!DOCTYPE ReportDefinitions SYSTEM "emreportcli.dtd">
<ReportDefinitions>
<ReportDefinition>
<SourceFile templateName="alerts3"/>
<OutputFile type="PDF" filepath="D:\MyAlerts3.pdf"/>
<Parameters>
<Parameter name="MY_PARAM" value="job*"/>
<Parameter name="Application" value="a*"/>
</Parameters>
</ReportDefinition>
</ReportDefinitions>
With the input arguments file in the above example, the emreportcli generates a PDF report based on the
"alerts3" report template and saves it in the D:\ folder with the filename called MyAlerts3.pdf.
If the report template filter is defined as shown in ZBlueXrefparanum, the output of the report will contain
all alerts with a

610
Control-M Utilities Guide

 Control-M name of "ctm900" or that starts with "mvs"

 Job Name that starts with "job"
 Application name that starts with "a"

emreportcli utility input arguments file parameters

The following table describes the emreportcli utility input arguments file parameters:

Parameter Attribute Description

Source File The template used to generate the report

templateName Specifies the name of the template

TemplatePath Specifies the folder where the template file is located

(Optional)

Output File The report output file.

type Specifies the type of the output file, such as EXCEL,

EXCEL_DO (for data only), PDF, DOC, HTML, TXT, or XML

filepath Specifies the full filename of the output file (which will be
overwritten if it previously existed)
Dynamically resolved keys can be included when specifying
the filepath attribute: {date}, {time}, and {counter}.
For filepath=D:\Test.doc (that is, no key), the output file
is: D:\Test.doc.
For filepath=D:\Test-{date}.doc, the output
file is D:\Test-May22, 2008.doc.
For filepath=D:\Test{counter}.doc, the first
output file is D:\Test1.doc, and the next output
file is D:\Test2.doc.

Parameters The parameter list.

Parameter An individual parameter, whose name and value is

specified.

name name of the parameter as defined in the report template

filter panel.

value value of the report parameter (wildcard characters can be

used for text fields when the field operator in the filter
panel is set to "LIKE" for the fields).

611
Control-M Utilities Guide

ctmjsa
The ctmjsa utility compiles runtime data from the Statistical Details table and records it in the Statistics
Summary table of the Control-M/Server database. This utility must be run by a Control-M/Server user.
Each time it is run, this utility:
 Scans the statistical data for jobs that terminated with OK status. The jobs scanned can be limited to
a range of dates as described below.
 Computes the average run time and standard deviation for each job for which data was found.
 Records the statistical data in a summary table in the Control-M/Server database (from which the
data is made available to Control-M/EM).
 No other output is generated by this utility.
 Display the summary data filtered according to specified parameters.
Statistical data is only accumulated when the Control-M system parameter Statistics is set to Y.
Operational parameter Statistics Mode determines the mode to be used to compile summary statistics:
JOBNAME or MEMNAME. The default is MEMNAME.
If the Statistics Mode parameter was changed from File name to JOBNAME or back since the last run of
the ctmjsa utility, you can cleanup the statistics from the previous mode by running the following
command: ctmstats –delete. The Statistics Mode parameter can be changed through ctm_menu by
choosing Parameter Customization Menu =>Advanced Communication and Operational
Parameters =>Statistics Mode.
For more information about runtime statistical data, see the information about runtime statistics in
Control-M Forecast parameters. To run the ctmjsa utility, see Running the ctmjsa utility (on page 612).

Running the ctmjsa utility

This procedure describes how to run the ctmjsa utility, which compiles runtime data from the Statistical
Details table and records it in the Statistics Summary table of the Control-M/Server database.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type one of the following commands:
• ctmjsa <fromDate> <toDate>
• ctmjsa -<delta1> -<delta2> <date>
• ctmjsa -list [ -JOBNAME <jobname> ]
[ -FILE_PATH <path> ]
[ -HOST <hostname> ]

612
Control-M Utilities Guide

NOTE: If the Statistics Mode parameter is JOBNAME, FILE_NAME and FILE_PATH fields in the Statistical
Summary table are blank. If the Statistics Mode parameter is FILENAME, the Job Name field is blank.
For the Control-M parameter name, see Parameter name cross references (on page 31). For more
information, see ctmjsa utility parameters (on page 613) and ctmjsa utility example (on page 614).

ctmjsa utility parameters

This table describes the ctmjsa utility parameters:

Parameter Description

<fromDate> Starting date of statistical data to be compiled. The date is specified in

yyyymmdd or yymmdd format.

<toDate> Ending date of statistical data to be compiled. The date is specified in

yyyymmdd or yymmdd format.

-<delta1> Unsigned number used to establish the starting date for statistical data to
be compiled. This date is determined by subtracting <delta1> from
<date> (for example, if <delta1> is 10 and <date> is 991220, the
starting date is 991210).

-<delta2> Unsigned number used to establish the ending date for statistical data to
be compiled. This date is determined by adding <Delta2> to <Date> (for
example, if <Delta2> is 5 and <Date> is 991220, the ending date is
991225).

<date> Date used together with <Delta1> and <Delta2> to determine the range
of dates used for compiling statistical data. The date is expressed in
yyyymmdd or yymmdd format.

"*" Asterisk enclosed in quotation marks. Specifies that the utility collects all
statistical data available without regard to date.

-list Display data from the Statistical Summary table filtered according to
specified sub parameters. Use this option after you have updated the
summary table. Output includes the Folder name for each job. This
information is also available from Control-M/EM in the Statistics window.

Filter Specify one of the following options and its sub parameter, or specify the
null character " " to display statistics for all jobs. This works the same
way as "*", which should be enclosed in quotation marks. ? Represents
any single character.

-JOBNAME <jobname> Identify the job by Job name parameter.

-FILE_PATH <path> Identify jobs by their file_path parameter.

613
Control-M Utilities Guide

Parameter Description

-HOST <hostname> Identify jobs by their host group parameter

(agent computer).

ctmjsa utility example

The following example describes commands compile statistical data for the 5-day period from June 21,
2016 through June 25, 2016 (assuming this data is available). In the second command, the hyphens
indicate the beginning of unsigned parameter values; they are not minus signs.
ctmjsa 160621 160625
ctmjsa -3 -1 160624
The following command compiles statistical data using all data currently available:
ctmjsa "*"
This command displays summary data for all jobs whose FILE_NAME parameter starts with "pgmac":
ctmjsa -list -FILE_NAME "pgmac*"
A report similar to the following is displayed:

FILE_N CPU ELAPSED

JOBNAME AME FILE_PATH HOST [sec] (sec) FOLDER

pgmacct1 prod.acct.pgm diana 233.15 connection

0.19 profileq1

pgmacct2 prod.acct.pgm verdi 6.12 connection

0.12 profiletq2

pgmacct3 prod.acct.pgm diana 170.45 connection

0.05 profiletq3

pgmacct4 prod.acct.pgm diana 145.23 connection

0.34 profileq4

614
Control-M Utilities Guide

ctmruninf
The ctmruninf utility displays runtime data from the Statistical Details table of the Control-M/Server
database. An option is available to delete data from this table. The jobs scanned for both options can be
limited to a range of dates as described below. To run the ctmruninf utiilty. see Running the ctmruninf
utility (on page 615).
Statistical data is only accumulated when the Control-M/Server system parameter Statistics is set to Y.
For more information about runtime statistical data, see the information about runtime statistics in
Control-M Forecast parameters.

Running the ctmruninf utility

This procedure describes how to run the ctmruninf utility, which enables you to display runtime data from
the Statistical Details table of the Control-M/Server database.
 To run the utility:
1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Type one of the following commands:
• ctmruninf -list <fromDate> <toDate> [<filter>] [-total]
• ctmruninf -list "*" [<filter>] [-total]
• ctmruninf -delete <fromDate> <toDate>
• ctmruninf -PURGE
For more information on the ctmruninf utility, see ctmruninf utility parameters (on page 616) and
ctmruninf utility example (on page 617).

615
Control-M Utilities Guide

ctmruninf utility parameters

The following table describes the ctmruninf utility parameters:

Parameter Description

-list Displays data from the Statistical Details table within the dates
specified in the From Date and To Date parameters. The data listed
can be limited by using the Filter subparameter (described in this
table).

-delete Deletes data from the Statistical Details table in the range specified in
the From Date and To Date parameters.

<From Date> Start date of statistical data to be displayed or deleted. Format:

yyyymmddhhmmss

<To Date> End date of statistical data to be displayed or deleted. Format:

yyyymmddhhmmss

"*" Asterisk enclosed in quotation marks. Specifies that the utility should
list all statistical data currently available, without regard to date.

<Filter Specify one of the following options and its associated subparameter
or leave blank to display the statistics for all jobs in the range.
 -JOBNAME <jobName>
Identify the job by the first 10 characters in its Job Name
parameter.
 -FILE_NAME <file name>
Identify the job by its file name parameter.
 -FILE_PATH <path>
Identify jobs by their file path parameter specifications.
 -HOSTID <hostid>
Identify jobs by their Host ID parameter (agent computer).
 -ORDERID <orderid>
Identify jobs by their Order ID parameter.
Each of the sub parameters in the filter can include the following
wildcard characters:
* represents any number of characters (including none). Any
parameter including * should be enclosed in quotation marks (see the
third example below).
? represents any single character

616
Control-M Utilities Guide

Parameter Description

-total Displays the total CPU and elapsed times for the jobs selected.

-purge Purge data from the Statistical Details table based on the number of
job executions.
Running the ctmruninf utility with the -PURGE option performs the
statistics cleanup as if it was done during New Day with the
RUNINF_PURGE_MODE set to 0 (default).
The Statistics algorithm (JOBNAME or MEMNAME) and the
RUNINF_PURGE_LIMIT parameter are taken from the config.dat
table, if configured.
NOTE: You can speed up the New Day procedure by specifying N for
the STATISTICS_CLEANUP_IN_NEWDAY parameter and running
ctmruninf -PURGE in a job that is run daily. Only the last n run
information records of a job are kept, where n is the value of
RUNINF_PURGE_LIMIT (default 20).

ctmruninf utility example

The following example describes command displays runtime data for the period January 21, 2017 through
January 25, 2017 (assuming that this data is available):
ctmruninf -list 20170121000000 20170125235959
The following command deletes the statistical data for January 31, 2017:
ctmruninf -delete 20170131000000 20170131235959
The following command causes the utility to display and total runtime data for all jobs on agent computer
diana.
ctmruninf -list "*" -HOSTID "diana" -total
A report similar to the following is displayed:
TIMESTAMP JOBNAME ORDERID RUN# HOST FILE_NAME FILE_PATH
CPU ELAPSED
------------- ---------- -------- ---- ------------ ----------
-------------- ----- -------
2017012160524 acct12 00000007 1 diana pgmacct
prod.acct.pgm 0.19 233.15
2017012161205 gen786 0000000b 1 diana genx prod.general
0.12 6.12
2017012162311 acct14 00000011 1 diana pgmacct
prod.acct.pgm 0.05 170.45

617
Control-M Utilities Guide

2017012164512 acct15 00000012 1 diana pgmacct

prod.acct.pgm 0.14 145.23
------------- ---------- -------- ---- ------------ ----------
-------------- ----- -------
Total records printed :
4 0.50 555.35

ctmstats
The ctmstats utility displays and deletes statistical data from the Statistical Summary table of the
Control-M/Server database. The data scanned for both options can be limited to a range of dates. The
Statistical Summary table is created using the ctmjsa utility. To run the ctmstats utility see Running the
ctmstats utility (on page 618).
Statistical data is only accumulated when the Control-M system parameter Statistics is set to Y. For more
information, see System Parameters referred to in ctmsys (on page 448).

Running the ctmstats utility

This procedure describes the ctmstats utility, which displays and deletes statistical data from the
Statistical Summary table of the Control-M/Server database.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/Server account
• Windows: Open a command prompt window where Control-M/Server is installed.
2. Enter the one of the following commands:
• ctmstats -list <fromDate> <toDate> [<filter>] [-total]
• ctmstats -list "*" [<filter>] [-total]
• ctmstats -delete <fromDate> <toDate>
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the ctmstats utility, see ctmstats utility parameters (on page 619) and ctmstats utility example (on
page 620).

618
Control-M Utilities Guide

ctmstats utility parameters

The following table describes the ctmstats utility parameters:

Parameter Description

-list Displays data from the Statistical Summary table within the dates
specified by the From Date and To Date parameters. The data listed
can be limited with use of the Filter sub-parameter (see below).

-delete Deletes data from the Statistical Summary table in the range specified
by the From Date and To Date parameters.

<From Date> Starting date of statistical data to be displayed/deleted. The date is

specified in yyyymmddhhmmss format.

<To Date> Ending date of statistical data to be displayed/deleted. The date is

specified in yyyymmddhhmmss format.

"∗" Asterisk enclosed in quotation marks. Specifies that the utility should
list all statistical data currently available, without regard to date.

<Filter> Specify one of the following options and its associated subparameter
or leave blank to display the statistics for all jobs in the range.

-JOBNAME <jobName>
Identify the job by its Job Name parameter.

-FILE_NAME <file name>

Identify the job by its File Name parameter.

-FILE_PATH <file path>

Identify jobs by their File Path parameter.

-HOSTID <hostid>
Identify jobs by their host id parameter (agent computer).

Each of the subparameters in the filter can include the following

wildcard characters:
 * – Represents any number of characters (including no
characters). Any parameter including ∗ should be enclosed in
quotation marks (see example below).
 ? – Represents any single character

-total Displays a line that contains the total CPU and elapsed times for the
jobs selected.

619
Control-M Utilities Guide

ctmstats utility example

The following example describes the command displays statistical data for the period January 21, 2017
through January 25, 2017 (assuming that this data is available):
ctmstats -list 20170121000000 20170125235959
A report similar to the following is displayed:
TIMESTAMP JOBNAME HOST FILE_NAME FILE_PATH AVG CPU AVG
ELAPSED
-------------- ------ ------ ------- ------------- ------- --------
---
20170122141214 acct12 diana pgmacct prod.acct.pgm 0.19 233.15
20170122032025 gen786 diana genx prod.general 0.12 6.12
20170121123111 acct14 diana pgmacct prod.acct.pgm 0.05 170.45
20170121113512 acct15 diana pgmacct prod.acct.pgm 0.14 145.23
The following command displays statistical data for all jobs on agent computer diana:
ctmstats -list "*" -HOSTID diana -total
The following command deletes the statistical data for January 31, 2017:
ctmstats -delete 20170131000000 20170131235959

620
12
12
Upgrade
The migrate_dc utility promotes Control-M/Server job processing definition formats from earlier versions
of Control-M.
The migrate_dc utility is part of the Control-M upgrade process. The migrate_dc utility converts
Control-M/Server job processing definition formats within the Control-M/EM database. The
Control-M/Server job processing definition formats are converted from the Control-M/Server data formats
in the earlier version to the data formats in the new version. For more information about upgrade, see
Control-M Upgrade.
NOTE: Do not use this utility if you have not yet installed and upgraded to a new version of Control-M/EM
and Control-M/Server.
The upgrade process was previously called Migration. Control-M/Server is sometimes called Data Center.

migrate_dc
Use the migrate_dc utility to promote the job processing definition formats in Control-M/EM from an
earlier versions to Control-M/Server to the format of the current version. To promote using Control-M
Configuration Manager, see Promoting Control-M/Server data formats on Control-M/EM. To run the utility,
see Running the migrate_dc utility (on page 621).
NOTE: There is no rollback procedure from changes made by the migrate_dc utility. Before using the
migrate_dc utility, backup all your data
The destination Control-M/Server must be defined in COMM folder before executing the migrate_dc utility.
By default, all job definitions are converted to a format that is consistent with the standards for the
current version.
If you upgraded Control-M/Server on UNIX or on Windows to a version earlier than 6.4.01, or if you
upgraded Control-M for OS/390 to a version earlier than 6.4.01, and then want to run the migrate_dc
utility in Control-M/EM database for the upgraded Control-M definitions, you must specify -version
{700|800|900} in the migrate_dc command line to prevent the current version format from being
applied to the jobs for this Control-M.

Running the migrate_dc utility

This procedure describes how to run the migrate_dc utility, which enables you to migrate job processing
definition formats in Control-M/EM from an earlier versions to Control-M/Server to the format of the
current version.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed.

621
Control-M Utilities Guide

2. Enter either of the following commands:

• To migrate Control-M/Server job processing definition formats from all database folders:
migrate_dc -u <DBO name> -p <DBO password>
-dc <data center>
[-hostname <data center hostname>]
[-port <data center port number>]
-version {640|700|800|900}
• To migrate Control-M/Server job processing definition formats from folder-to-folder:
migrate_dc -u <DBO name> -p <DBO password>
[-version {640|700|800|900}]
[-old_dc <name1>]
[-new_dc <name2>]
[-folder <Folder Name>]
[-lib <Library Name>]
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the migrate_dc utility, see migrate_dc utility parameters (on page 623).

622
Control-M Utilities Guide

migrate_dc utility parameters

The following table describes the parameters of the migrate_dc utility:

Parameter Description

hostname the Control-M/Server host name (maximum length: 255 characters)

port the Control-M/Server port number (range: 1024 – 65533)

version the newly upgraded Control-M/Server version number

This indicates to Control-M/EM that Control-M/Server was upgraded and
accordingly adjusts it to the new Control-M/Server version.

old_dc the source Control-M/Server (data center) name, as defined in the COMM
folder

new_dc the destination Control-M/Server name

If the Control-M/Server <name2> is not defined in COMM folder, the
following error message is displayed:
The target Control-M/Server is not defined

folder the upgraded folder name

lib optional parameter for specifying or identifying an z/OS-folder

migrate_dc example
The following is an example of migrate_dc usage:
Use the migrate_dc utility to promote Control-M/Server job processing definition formats in the
Control-M/EM database on computer saturn from version 6.3.01 Control-M/Server data formats to version
9.0.00 Control-M/Server data formats.
The following table lists the names and definitions used in this example:

Parameter Name

dataCenter jupiter
(Control-M/Server)

DBO Name asteroid

DBO Password star2

Data Center hostname saturn

623
Control-M Utilities Guide

Parameter Name

Data Center port number 7530

Upgrading from earlier versions to version 9.0.00 example

This procedure describes how to promote from earlier versions to version 9.0.00 using the migrate_dc
utility.
 To promote from earlier versions to version 9.0.00:
1. Log on to computer saturn where version 9.0.00 of Control-M/EM or where Control-M Configuration
Manager is installed.
2. If Control-M/Server jupiter's host and port have changed during the Control-M/Server upgrade and
the correct host and port are not specified in the -hostname and -port options of migrate_dc, select
the relevant Control-M/Server in the Control-M Configuration Manager (CCM) and update the
host and port definitions.
3. Verify that the version 7.0.00 Control-M/Server being upgraded is disconnected from Control-M/EM
and that the corresponding gateway is down.
4. In the CCM, if the Control-M/Server version 9.0.00 on either a UNIX computer or a Windows
computer, or version 62A or later (Control-M for OS/390), is in Managed mode, change the status to
Unmanaged.
5. Open a command prompt window on Windows, or log on to the account where Control-M/EM
database is installed on UNIX.
6. To upgrade the data formats for Control-M/Server jupiter, run one of the following commands:
• to promote from all version 7.0.00 database folders to version 9.0.00
migrate_dc -u asteroid -p star2 -dc jupiter
-hostname saturn
-port 7530
-version 900
• to promote Control-M/Server job processing definitions from folder-to-folder
migrate_dc -u asteroid -p star2
-version 900
-old_dc jupiter1
-new_dc jupiter2
-folder starFolder
-lib starLibrary

624
13
13
Forecast
The forecastcli utility enables you to perform a Load Forecast operation in batch mode. The main outputs
are, for the specified date:
 Service information (only available if you have the Control-M Batch Impact Manager Add-on installed)
Service information includes a summary of the business services identified by Control-M/Forecast. If
at least one service is identified as late, a warning is indicated in the output.
 Job information (always available)
Job information is ordered for a specific future date. You can specify whether or not the estimated
run times are included in the output.
To run the forecastcli utility, see Running the forecastcli utility (on page 625)

Running the forecastcli utility

This procedure describes how to run the forecastcli utility, which enables you to perform a Load Forecast
operation in batch mode.
Before you begin
 To run the forecastcli utility, the Control-M/Forecast server must be up and running.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed.
2. Type the following command;
forecastcli -u <user> [[-p <password>] | -pf <password_file>] -s <server_name> -odate
[YYYYMMDD|+n] [Filter] [-scenario <name>] [-run_time [Min|Avg|Max]] -job_info_file <file_name>
[-service_info_file <file_name>] [/hide_times]
For UNIX, add em and a space before specifying forecastcli. For example:
em forecastcli -u emuser -p empass -s emserv1 -odate 20090217 -job_info_file
out.csv
For the Control-M parameter name, see Parameter name cross references (on page 31). For more details
on the forecastcli utility, see the following:
 forecastcli parameters (on page 626)
 forecastcli filter options (on page 627)
 forecastcli examples (on page 627)

625
Control-M Utilities Guide

forecastcli parameters
The following table describes the parameters of the forecastcli commands:

Parameter Description

-u <user> Indicates the user name of the Control-M client. Required.

-p <password> Indicates the password of the Control-M client.

-pf Indicates the password file name used instead of password.

<password_file>

-s <server_name> Indicates the name of the Control-M/Enterprise Manager server.

Required.

-odate Indicates the forecast report date (or number of days from current
date). Required.
Valid values are:

YYYYMMDD A specific working day in YYYYMMDD format.

+n Number of days from current date.

-scenario <name> Indicates the name of the forecast scenario that is applied to the
forecast.

-run_time Indicates type of run time that is used for the forecast.
Valid values are:

Avg Average (Default)

Min Minimum

Max Maximum

-job_info_file Indicates the file name where the job information output is saved. The
<file_name> output is in CSV format. Required.

-service_info_file Indicates the file name where the service information output is saved.
<file_name> The output is in CSV format.

-hide_times The estimated job start and end time will not be printed in the job
information output file.

/? or /h Displays usage.

626
Control-M Utilities Guide

forecastcli filter options

The following table describes the forecastcli Filter options.

Parameter Filter results with

-ctm_name <name> Control-M name

-folder_name <name> Folder name

-appl_name <name> Application name

-subappl_name Sub application name

<name>

-mem_lib <name> file path

-mem_name <name> file name

-job_name <name> job name

-service_name <name> service name

forecastcli examples
The following are forecastcli examples:
To know, on a daily basis, which services or jobs will be ordered on the following day, run the following
command. The output files, services.csv and jobs.csv, list the services and jobs, indicating their run times
and statuses.
forecastcli -u emuser -p empass -s emserv1 -odate +1 -job_info_file jobs.csv
-service_info_file services.csv
The following command generates a forecast for February 17, 2009. The job information is written to the
out.csv file.
forecastcli -u emuser -p empass -s emserv1 -odate 20090217 -job_info_file
out.csv
The following command generates a forecast to obtain a list of the jobs that will run on all data centers
with names beginning with "A" for February 17, 2009. The run times are not included in the output file in
order to compare it to another job list forecasted for another date.
forecastcli -u emuser -p empass -s emserv1 -odate 20090217 -dc_name A*
-job_info_file out.csv /hide_times

627
14
14
Batch Discovery
Using Batch Discovery, critical batch services defined and monitored with Control-M/EM and Control-M
Batch Impact Manager can be output in CSV files and imported into the BMC Atrium CMDB to enhance
control over change processes and system failures, and provide a view of the critical batch processes in
the IT environment. To run the Batch Discovery utility, see Running the Batch Discovery utility (on page
628).

Running the Batch Discovery utility

This procedure describes how to run the Batch Discovery utility.

 To run the utility:

1. Do one of the following:
• UNIX: Log on to a Control-M/EM account.
• Windows: Open a command prompt window where Control-M/EM is installed.
2. Type one of the following commands:
• Windows:
embatchdiscovery -u <EM admin username> {-p <EM admin password> -gsr <EM
sever name>[-cms <cms server name>][-empf <file name>]
• UNIX:
em batchdiscovery -u <EM admin username> {-p <EM admin password> -gsr
<EM server name> [-cms <cms server name>] [-pf <file name>]
For more information on the parameters, see Batch Discovery parameters (on page 629).
3. Press Enter.
The Batch Discovery ended successfully message indicates that Batch Discovery completed the
creation of csv files containing information from the Control M/EM database.
The CSV files can be found in Control-M/EM home directory.
If Batch Discovery does not end successfully, a return code is displayed, as described in Batch
Discovery return codes (on page 629). The code can be used to detect how the application failed.

628
Control-M Utilities Guide

Batch Discovery parameters

The following table describes the Batch Discovery parameters:

Parameter Description

-u Control-M/EM administrator name.

-p Control-M/EM administrator password.

-gsr Name of Control-M/EM GUI Server.

-cms Optional. Name of Control-M Configuration Manager. Optional. (Default:

CMS)

-empf Optional. Name of flat file containing a list of unencrypted passwords, on

separate lines, in the following format:
EM password
NOTE: To use the password file, specify the -empf parameter instead of
-p. If only -u is specified, online prompts are issued for the passwords. If
the -empf parameter is specified with -p, the -p parameter is ignored.

Batch Discovery return codes

The following table describes the Batch Discovery return codes:

Return
code Description

0 Success

1 Failure

2 Operating system not supported

255 Failure

629
15
15
Unsupported utilities
The following utilities are provided "as is."
BMC does not support these utilities and assumes no responsibility for problems that may occur as a
result from using these utilities. BMC advises users not to use these utilities:
 addevice
 addto_interfaces_file
 ags
 ajf
 ctm_backup_aut
 ctm_grj
 ctm_jcl
 ctm_mirrordb_bck
 ctm_newday
 ctm_shout
 ctm_sysout_down
 ctm_sysout_hndl
 ctm2snmp
 ctmdbcount
 ctmeditjcl
 ctmgtsch
 ctmjckdl
 ctmjcopy
 ctmlbsel
 ctmmksch
 ctmshdst
 ctmsnmp
 ctmtunnelreq
 ctmweb

630
Control-M Utilities Guide

 CtoSrvDa
 dbbackupora
 dbbackupsyb
 dbcheckora
 dbchecksyb
 dbloadora
 dbloadsyb
 dbrestoreora
 dbrestoresyb
 dbunloadora
 dbunloadsyb
 dbupstatora
 dbupstatsyb
 dsdisp
 dsmk
 ecacontb
 shdest
 upg_ping

631