BMC Control-M 9.0.00.500 Utilities Guide
Werbung
Werbung
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
2103 CITYWEST BLVD
HOUSTON TX
77042-2827
USA
Telephone 713 918 8800
800 841 2031
Fax 713 918 8000
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
6
7
8
9
1
Introduction to Utilities
1
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.
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 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 example:
> variable is the name of a file that contains the ctmcreate parameters. For
-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
o
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
ORACLE_BASE
ORACLE_HOME
ORACLE_SID
NLS_LANG
For PostgreSQL
DB_TYPE
PGHOME
PGDATA
PGPORT
PGHOST
PGDATABASE
PGUSER
PGSYSCONFDIR
PGSERVICE
LD_LIBRARY_PATH/LIBPATH/
SHLIBPATH
DBU_BIN
MIRROR_DSQUERY
14
Control-M Utilities Guide
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
AIX
HP-UX
Shared library environment variable name
LIBPATH
SHLIB_PATH
Solaris
Linux x86_64
LD_LIBRARY_PATH
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>
< opSysID >
The default full path name of the UNIX user account home directory under which Control-M/Server is installed.
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
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
( PGSQL only )
Read and write permissions for all files
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
< controlm-directory >/pgsql/etc/pg_service.conf
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" endi f 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.
_exit
_sleep ag_diag_ comm ag_ping ctmagcfg ctmunixcf g ctmwincf g set_agent
_mode ctm_agst at ctm_back up_bcp
Yes ctm_diag
_comm
Yes ctm_men u
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes Yes
Yes
Yes
No
22
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Control-M Utilities Guide
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes ctm_resto re_bcp ctmagcln Yes ctmcalc_d ate ctmcontb Yes ctmcreate Yes ctmdefine ctmdeffol der ctmdefsu bfolder ctmdisksp ace ctmexdef ctmfw ctmgetcm Yes ctmhostm ap ctmipc Yes ctmldnrs ctmloads et
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes Yes
23
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Control-M Utilities Guide ctmkeyge n ctmkeyst ore_ mng ctmkilljob Yes ctmhostgr p ctmorder Yes ctmordck ctmping Yes ctmpsm ctmrpln ctmruninf ctmshtb ctmshout Yes ctmspdia g ctmstvar ctmsuspe nd
Yes ctmsweep
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
24
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Control-M Utilities Guide
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes show_ca shut_ca shut_ctm shutdb start_ca start_ctm startdb bim_repo rt build_db ccmcli ctmudchk ctmudlst ctmudly Yes ctmvar ctmwhy db_check
_space dbversion shctm
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
25
Control-M Utilities Guide cli copydefca l
Yes copydefjo b ctl db_check defcal defjob deffolder deldefjob duplicate defjob ecactltb Yes ecaqrtab Yes em_data_ collector em_datab ase_ menu em_rebuil d_ database
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes Yes
26
Control-M Utilities Guide em_SQL emcrypto cli migrate_ dc emreport cli erase_au dit_ data exportdef cal exportdef job exportdef folder loader loopdetec ttool orbadmin purge_ru ninfo purge_xal erts sweep
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes Yes
Yes
Yes
(database owner)
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes Yes
27
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Control-M Utilities Guide updatede f util Yes Yes
Yes
Yes
Yes
Yes Yes
28
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
APPLFORM
APPLICATION
APPLTYPE
APPLVER
VARIABLE
CMDLINE
CMVER
CONFIRM
CONTROL
CRITICAL
CYCLIC
DESCRIPTION
DO REMEDY
DOVARIABLE
DOCLIB
DOCMEM
DOCOND
DOFORCEJOB
DOREMOTEFORCEJOB
DOMAIL
Adjust condition
Application Form
Application
Application Type
Application Version
Variable Assignments
Command Line
Application Plug-in Version
Confirm Submission
Control Resources
Critical
Cyclic
Description
Notify - Remedy
Set Variable
Doc Library
Doc Member
Add/Remove condition
Order Job
Remote Order Job
Notify - Mail
31
Control-M Utilities Guide
Utility parameters
DOOK
DORERUN
DOSHOUT
CAL_ANDOR
CONFCAL
CONFIRM
DATE
DATEFROM
DATEUNTIL
DAYS
DAYSCAL
INTERVAL_SEQUENCE
SPECIFIC_TIMES
TOLERANCE
EMBEDDED_SCRIPT
RBC
RELATIONSHIP
RETRO
SHIFT
WEEKCAL
WEEKDAYS
TIMEUNTIL
DOSTOPCYCLIC
Control-M parameter
Do OK
Rerun Job
Notify
AND/OR
Confirmation Calendar
Confirm Submission
Dates
Start Date
End Date
Days
Days Calendar
Rerun using the following Interval Sequence
Run at
Tolerance
Embedded Scripts/JCL
Rule-Based Calendar
Relationship
Retroactively order job that its scheduled date has passed
If day is not confirmed
Week days Calendar
Days of week
Time
Stop Cyclic Run
32
Control-M Utilities Guide
Utility parameters
DOOUTPUT
SUB_APPLICATION
INTERVAL
INCOND
INTERVALFROM
JOBNAME
MAXRERUN
MAXWAIT
HOSTGRP
MEMLIB
MEMNAME
ODATE
ON
OUTCOND
OVERRIDE_PATH
RUN_AS
PRIORITY
QUANTITATIVE
SHOUT
OUTPUT
FOLDER
TASKTYPE
TIMEFROM
Control-M parameter
Handle Output
Sub Application
Interval
In Conditions
All intervals are from job's
Job Name
Maximum reruns
Keep active for
Host (/Group)
Member Library
File Name
Order Date
On Statement/Code
Out Conditions
Override path
Run as
Priority
Quantitative Resources
Notification
Output Handling
Folder
What
Time from
33
Control-M Utilities Guide
Utility parameters
TIMEUNTIL
Control-M parameter
Time to
34
2
XML file rules
2
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
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
NEQ
LIKE
Equals. Select cases that include the specified value.
Not equal. Select cases that include any value different from the one specified.
Similar. Select cases that have an attribute common to the one specified.
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 copyjob.dtd defcal.dtd defjob.dtd deffolder.dtd
Validates the copydefcal input file.
Validates the copydefjob input file.
Validates the defcal input file.
Validates the defjob input file.
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
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
" (double-quote)
Replacement code
"
’ (single-quote, apostrophe) '
< (left-angle bracket) <
> (right-angle bracket)
& (ampersand)
>
&
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<6'run'" ODATE="ODAT" AND_OR="AND"
OP="("/
Wildcards
Multiple jobs can be selected and copied using the * (asterisk) wildcard character to represent multiple values. The asterisk is used to represent zero or more alphanumeric characters. An asterisk can 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
Control-M/EM utilities
Description
Enables you to make various modifications to job 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
emdef utility for services (on page
Enables you to make various modifications to BIM service definitions in the Control-M/EM database.
emwacli for promotion (on page
Enables you to run Promotion as a batch process.
41
Control-M Utilities Guide
Utility Type
Control-M/Server utilities
Description
Creates a job, which is added directly into the Active
Jobs database.
Adds a job processing definition to a folder, a SMART folder, and a subfolder in the Control-M/Server database.
Exports jobs from the Control-M/Server database to an
ASCII file for use with ctmcreate or ctmdefine.
Detects completion of file transfer activity.
ctmfw File Watcher utility (on page 217 )
Imports SMART Folders that were exported with the exportdeffolder utility.
Terminates a Control-M job and its associated processes.
Orders jobs from a SMART Folder in the
Control-M/Server database.
Interactively performs functions on jobs or conditions directly in the Active database.
Deletes non-active jobs from the Control-M/Server database.
Reports why a job waiting in the Active Jobs database is not submitted.
Control-M/Agent utilities
Sets the completion status for a job that runs from a
.bat file.
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
The emdef utility includes the following utilities:
Utility Type Description
Imports job processing definitions directly into Control-M/EM database.
Copies jobs from one folder to another in the Control-M/EM database that is similar to a specified existing definition.
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.
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.
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
Exports Site Standards into Control-M/EM database.
Imports Site Standards into Control-M/EM database
Exports Promotion Rules into Control-M/EM database.
exportpromotionrule (on page 162 )
Importpromotionrule (on page 172 )
Imports Promotion Rules into Control-M/EM database. For more information about the exportpromotionrule and
importpromotion rules see Export/import Promotion rules
43
Control-M Utilities Guide
emdef general parameters
The following table describes the parameters common to emdef utilities.
Parameter
<user>
<password> name>
<password file
Description
Defines the Control-M/EM user name.
Defines the Control-M/EM user password.
Includes an unencrypted user name and password on separate lines in a flat file in the following format: user=< userName> password= <password>
<GUI Server
Name>
<XML file name>
Defines the 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.
Defines the path and name of the XML file containing the defjob
specifications. For instructions about creating this file, see XML file rules
<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
? Displays utility's description and available options.
/a
/v
/c emdef utility
All (except loopdetecttool)
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.
The following utilities are supported:
defjob
NOTE: The /a switch has no effect on Administrator users and is relevant only when the AuthorSecurity system parameter is set to 2 or 3.
copydefjob
duplicatedefjob
exportdefjob
updatedef
defservice
exportdefservice
defcal
deffolder
exportdefcal
exportdeffolder
Used to receive verbose messages. The following utilities are supported:
defjob
copydefjob
deldefjob
duplicatedefjob
exportdefjob
updatedef
defservice
exportdefservice
deffolder
exportdeffolder
Operates on a chunk of jobs at any one time to reduce the process' memory defjob
45
Control-M Utilities Guide
Switch Description
-cs Set the number of jobs in a chunk.
Default: 100
/t
/o
/f emdef utility defjob
Operate on a single folder at a time, to reduce process memory. The following utilities are supported:
defjob
exportdefjob
deffolder
exportdeffolder
Overwrites an existing folder definition in Control-M/EM database or creates a new folder if it does not exist. deffolder
Forces folder definition with a site standard that does not exist, which sets the site standard to none. deffolder
defjob
The defjob utility imports job processing definitions directly into Control-M/EM database. To import the
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
) 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
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.
), 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
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
DATACENTER
PARENT_FOLDER
Indicates the opening and closing tags of a single job definition. Parameters of the job are listed between the tags.
Name of the Control-M installation to which the job belongs. String. Mandatory.
Name of the parent folder to which the job’s folder belongs. String. Mandatory.
FOLDER_NAME
FOLDER_DSN
JOBNAME
FILE_NAME
SUB_APPLICATION
APPLICATION
Name of the SMART Folder to which the job belongs. String. Mandatory.
( z/OS only ) Name of the library that contains the SMART Folder. String. Mandatory.
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).
Name of the file that contains the job script. String. Optional.
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.
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
TASKTYPE
CREATED_BY
FILE_PATH
CMDLINE
HOSTID
RUN_AS
MAXRERUN
TIMEFROM
TIMETO
DUE_OUT
PRIORITY
Description
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
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.
Name of the library/directory in which the job script resides. String. Optional.
Command string supplied when the job Task Type is Command. String. Optional.
Host name of an agent computer or name of a host group to which the job is submitted. String. Optional.
Identifies the user name with the authorization to execute the job. This parameter is used by the Control-M security mechanism. String. Mandatory.
Specifies the maximum number of reruns that can be performed for the job.
Optional.
Valid values: 0-99. Default: 0
Indicates the earliest time for submitting the job. Format is (hhmm). Optional.
Indicates the latest time for submitting the job. Format is (hhmm) or (>). Optional.
Time that the job is expected to finish. String. Optional.
Indicates Control-M job priority. 2 alphanumeric characters (AA-99). Optional.
50
Control-M Utilities Guide
Parameter
CRITICAL
CYCLIC
Description
Indicates that the job is a critical-path job in Control-M. Optional.
Valid values:
0 (No. Default)
1 (Yes)
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_
SEQUENCE
CYCLIC_TIMES_
SEQUENCE
A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up to
4000 characters including commas.
NOTE: Relevant for Control-M version 6.4.01 or later.
A list of times, separated by commas (for example 0800,1330,2300), which supports time synonym (for example 2730).
NOTE: Relevant for Control-M version 6.4.01 or later.
INSTREAM_JCL
( embedded script)
Defines a script exactly as it would be specified in a terminal for the specific computer and is part of the job definition.
For Control-M for Distributed System for 6.4.01 or later an embedded script is marked with a 
 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
AUTOARCH
INTERVAL
OVERRIDE_PATH
MAXWAIT
DESCRIPTION
DOCMEM
DOCLIB
DAYS
DAYS_AND_OR
WEEKDAYS
Indicates whether the job must be manually confirmed by the Control-M/EM user before it runs. Optional. Valid values:
0 (Default)
1
Determines whether SYSDATA is to be archived. Optional.
Valid values:
0 (No. Default)
1 (Yes)
Specifies the length of time (in minutes) to wait between reruns of a job or between cyclic runs of a job. Integer. Optional.
Default: 0.
Name of an alternate job script library/directory. String. Optional.
Number of extra days (beyond the original scheduling date) that the job is allowed to remain in the Active Jobs database awaiting execution. Integer. Optional.
Free text description of the job. String. Optional.
Name of the file containing job documentation. String. Optional.
Name of a library or directory containing the job documentation file. String.
Optional.
Days of the month on which to order the job. String. Optional.
Indicates the relationship between specified Days values and Weekdays values.
Optional.
Valid values:
AND
OR
Days of the week on which to order the job. String. Optional.
52
Control-M Utilities Guide
Parameter
DATE
DAYSCAL
WEEKSCAL
CONFCAL
RETRO
SHIFT
SHIFTNUM
MAXDAYS
MAXRUNS
RERUNMEM
RETEN_DAYS
RETEN_GEN
Description
Specific dates on which to order the job. String. mmdd format. Optional.
For example, January 10 is written as: DATE="0110"
Name of a user-defined calendar used to specify a set of days. String. Optional.
Name of a calendar to be used to validate specified weekdays on which to order the job. String. Optional.
Specifies a calendar that is used to validate all specified days and dates on which to schedule the job. String. Optional.
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)
Describes how to shift the scheduling date of the job. Optional.
Valid values:
IGNOREJOB
PREVDAY
NEXTDAY
NOCONFCAL
Number of days to shift the scheduling date of the job. Optional. Valid values: -62 to 62.
Maximum number of days to 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.
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.
Name of the JCL member to use when the job is automatically rerun. String. 1 - 8 characters. Optional.
( z/OS only
Optional.
) Number of days to retain the job in the History Jobs file. String.
( 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
PREV_DAY
IND_CYCLIC
Description
Flag to indicate whether job scheduling is shifted to a previous working day in the
CONFCAL calendar. Optional.
Valid values:
Y
N
Indicates whether the interval between further runs of a cyclic job is counted from the start or the end of the previous job run. Optional.
Valid values:
START
END
TARGET
RULE_BASED_CALEND
AR_RELATIONSHIP
Relationship (AND|OR) between the specified Rule-Based Calendars and the job’s 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
MINIMUM
Name of a partitioned dataset (PDS) to be checked for free space. String. Optional.
Minimum number of free partitioned dataset tracks required by the library specified for the PDSNAME parameter. Integer. Optional.
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
PREVENTNCT2
JAN, FEB, MAR, APR,
MAY, JUN, JUL, AUG,
SEP, OCT, NOV, DEC
OPTION
Description
( 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).
Months when the job can run.
Valid values:
0 (Not run. Default)
1 (Run)
Job output (OUTPUT) handling options. Optional.
Valid values:
Release
Delete
Copy
Move
File
NewDest
ChangeClass
PAR
FROM
Certain OPTION values (such as Release, NewDest) require additional information.
String. Optional.
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
CREATION_USER
CREATION_DATE
CREATION_TIME
CHANGE_USERID
CHANGE_DATE
CHANGE_TIME
JOB_RELEASE
JOB_VERSION
APPL_TYPE
APPL_VER
APPL_FORM
CM_VER
MULTY_AGENT
ACTIVE_FROM
ACTIVE_TILL
Description
Name of the user who created the job. String. Optional.
Date on which the job was created. String. Optional.
Time at which the job was created. String. Optional.
Name of the user who last modified the job. String. Optional.
Date on which the job was last modified. String. Optional.
Time at which the job was last modified. String. Optional.
For internal use. Do not include this parameter in your defjob input file.
For internal use. Do not include this parameter in your deffolder input file.
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.
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.
Predefined set of external application parameters that are displayed in the Job
Properties team. String. Up to 30 characters. Mandatory for external application jobs.
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.
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.
( 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
( 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
TIMEZONE
SCHEDULING_
ENVIRONMENT
SYSTEM_AFFINITY
Description
Indicates the global time zone used to calculate the interval for time-related conditions.
String. Optional.
( z/OS only ) Indicates the JES2 workload management scheduling environment associated with the job. String. Optional.
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
AR_NAMES
Wrapper for the Rule-Based Calendars listed with the RULE_BASED_
CALENDAR_NAME parameter. Optional.
RULE_BASED_CALENDAR_NAMES RULE_BASED_CALENDAR_NAME="rbc1"
RULE_BASED_CALENDAR_NAME="rbc2"
TAG_NAMES
RULE_BASED_CALE
NDAR_NAME
Name of the Rule-Based Calendars that apply to the SMART
Folder. Mandatory.
Wrapper for the tags listed with the TAG_NAME parameter. Optional.
TAG_NAMES TAG_NAME="tag1" TAG_NAME="tag2"
OUTCOND
TAG_NAME
Out condition. Optional.
OUTCOND NAME="Job1" ODATE="ODAT" SIGN="ADD"
NAME
Name of the schedule tags that apply to the SMART Folder.
Mandatory. This parameter is for backward compatibility.
ODATE
Name of the Out condition. String. Mandatory.
1 - 255 characters, case-sensitive.
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
VARIABLE
QUANTITATIVE
CONTROL
Description
Wrapper for the Variable expression. Optional.
VARIABLE EXP="%%PARM1=%%TIME"
EXP The Variable expression. String. Mandatory.
Example: %%PARM1=%%TIME.
Wrapper for the Quantitative resource. Optional.
QUANTITATIVE NAME="TAPEDRIVE" QUANT="1"
NAME
QUANT
Name of the quantitative resource. String. Mandatory.
1 - 20 characters, case-sensitive.
Quantity of the resource. String. Mandatory.
Valid values:
0 – 9999. Default: 1
Wrapper for the Control resource. Optional.
Control NAME="Resc1" TYPE="E"
NAME
TYPE
Name of the Control resource. String. Mandatory.
Valid values: 1-20 characters, case-sensitive, trailing blanks only.
Type of resource.
Valid values:
E (exclusive-default)
S (shared)
58
Control-M Utilities Guide
Parameter
SHOUT
STEP_RANGE
Description
Wrapper for the Shout message. Optional.
SHOUT WHEN="EXECTIME" DEST="workstation1" URGENCY="R"
MESSAGE="Jobcompleted OK." TIME="1015"
WHEN
DEST
Condition under which the Shout message is sent. Mandatory.
Valid values:
OK (default)
NOTOK
RERUN
LATESUB
LATETIME
EXECTIME
Recipient of the shout message. String. Mandatory.
Valid values: 1-16 characters, case-sensitive. Mandatory.
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 that the message is sent. String. Mandatory. TIME
Step range in the job that can be used in an ON PGMST statement. Optional.
STEP_RANGE NAME="cleanup" FPGMS="Defrag" TPGMS=""
NAME
FPGMS
FPROCS
Name for the range. 1-7 character string. Mandatory.
Valid values: 1 - 7 characters. Only trailing blanks are allowed.
Name of the program to be run. as the first program step in the range. 1 - 8 character string. Mandatory.
Name of the procedure to be run. as the first procedure step in the range. 1-8 character string. Mandatory.
59
Control-M Utilities Guide
Parameter
ON
Description
TPGMS
TPROCS
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.
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.
Optional.
ON STMT="CODE" CODE="rt5" AND_OR="AND"><ON
STMT
CODE
PGMS
PROCS
AND_OR
A character string containing a statement from the job script file. String. 1-132 characters. Mandatory for the
On Statement/Code parameter.
Return codes or statuses that can satisfy the step or code event criteria if returned upon termination of the specified job steps.
String. Optional. Valid values: 1-255 characters.
Step in the program. String. Optional.
Valid value: 1-8 characters.
Step in the process. String. Optional.
Valid values:1-8 characters.
Relationship between On statements. Optional.
Valid values:
AND
OR
60
Control-M Utilities Guide
Parameter
DO
DOSHOUT
DOCOND
Description
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)
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
MESSAGE
Urgency of the Shout message.
Valid values:
R (regular-default)
U (urgent)
V (very urgent)
Text of Shout message. String, 1 - 255 characters, spaces allowed. Mandatory.
Specifies prerequisite conditions to be added or deleted. Optional.
DOCOND NAME="Cond1" ODATE="ODAT" SIGN="ADD"
NAME
ODATE
SIGN
Condition name. String, 1 - 20 characters, case-sensitive.
Mandatory.
Condition date. String. Mandatory. Default: ODAT
Specifies whether to add or delete the condition.
Valid values:
ADD (default)
DEL
61
Control-M Utilities Guide
Parameter
DOVARIABLE
DOFORCEJOB
DOOUTPUT
Description
Wrapper for the Variable expression. Optional.
DOVARIABLE EXP="%%PARM1=%%TIME"
EXP The Variable expression. String. Required.
%%PARM1=%%TIME
Forces a specified job when the current job is performed. Optional.
DOFORCEJOB DSN="45446" FOLDER_NAME="Folder2" NAME="Job4"
ODATE="ODAT"
DSN
FOLDER_NAME
( z/OS only ) Library for SMART Folder. String. Mandatory.
NAME
ODATE
Name of the SMART Folder to which the job belongs. String,
1-10 characters. Mandatory.
Name of the job. String. Mandatory.
Original scheduling date for the job. String. Default: ODAT
Handle job output (OUTPUT) when the job is done. Optional.
DOOUTPUT OPTION="Release" PAR="F" FROM=""
OPTION
PAR
Output handling options. Mandatory.
Valid values:
[All platforms]
Release
Delete
[not used with z/OS]
Copy
Move
[ z/OS only ]
File
NewDest
ChangeClass
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
DOIFRERUN
DOMAIL
Description
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
FPGMS
Indicates if job must be confirmed by user to be rerun.
Valid values:
0 (No confirmation. Default)
1 (Confirmation)
Step at which the job must be restarted. String. 1 - 8 characters. Mandatory.
FPROCS
TPGMS
TPROCS
Program step within the called procedure. String. 1 - 8 characters. Mandatory.
Step at which restarted job must terminate. String. 1 - 8 characters. Mandatory.
Program step within the called procedure. String. 1 - 8 characters.
Mandatory.
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
CC_DEST
SUBJECT
Recipient of the message. String. Mandatory.
Additional recipient of the message. String. Optional.
Brief text description of the message contents. String.
Optional.
MESSAGE Text of the message. String. Mandatory.
63
Control-M Utilities Guide
Parameter
DOCTBRULE
DOREMEDY
Description
( 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
PAR
Name of the Control-M/Analyzer rule. String. Mandatory.
Arguments that are passed to the Control-M/Analyzer rule.
String. Optional. Maximum: 45 characters.
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
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
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
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
) 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
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
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.
), 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"
FOLDER_DSN
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.
( 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
DATACENTER
Description
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
JOBNAME
FILE_NAME
Description
Name of the job processing definition.
EXAMPLE: JOBNAME FROM="Job3"
FROM String. Mandatory.
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"
APPLICATION
FROM String. Mandatory.
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""
TASKTYPE
FROM String. Mandatory.
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
FOLDER
_ORDER_ METHOD
Description
Optional.
EXAMPLE: FOLDER_ORDER_ METHOD FROM="Job3"
FROM String. Mandatory.
CREATED_BY
FILE_PATH
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.
Name of the library/directory in which the job script resides. String. Optional.
EXAMPLE: FILE_PATH FROM="Mem1"
CMDLINE
FROM String. Mandatory.
Command string supplied when the job Task Type is Command. Optional.
EXAMPLE: CMDLINE FROM="C:\Format"
HOSTID
FROM String. Mandatory.
Host name of an agent computer or name of a host group to which the job is submitted. Optional.
EXAMPLE: HOSTID FROM="Com3"
RUN_AS
MAXRERUN
FROM String. Mandatory.
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.
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
TIMEFROM
TIMETO
DUE_OUT
Description
Indicates the earliest time for submitting the job.
EXAMPLE: TIMEFROM FROM="1430"
FROM String. Mandatory.
Indicates the latest time for submitting the job.
EXAMPLE: TIMETO FROM="1600"
FROM String. Mandatory.
Time that the job is expected to finish.
EXAMPLE: DUE_OUT FROM="1500"
FROM String. Mandatory.
72
Control-M Utilities Guide
Parameter
PRIORITY
CRITICAL
Description
Indicates Control-M job priority.
EXAMPLE: PRIORITY FROM="AA"
FROM String. Mandatory.
Indicates that the job is a critical-path job in Control-M.
EXAMPLE: CRITICAL FROM="0"
CYCLIC
FROM Mandatory. Valid values:
0 (Default)
1
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_
TOLERANCE
CYCLIC_TIMES_
SEQUENCE
Maximum delay in minutes permitted for a late submission when selecting a specific time (for example 5 minutes).
CYCLIC_INTERVAL_
SEQUENCE
A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up to
4000 characters including commas.
A list of times, separated by commas (for example 0800,1330,2300), which supports 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
AUTOARCH
INTERVAL
OVERRIDE_PATH
MAXWAIT
DESCRIPTION
DOCMEM
DOCLIB
DAYS
Description
Determines whether SYSDATA is to be archived.
EXAMPLE: AUTOARCH FROM=0"
FROM Mandatory. Valid values:
0 (Default)
1
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.
Name of an alternate job script library/directory. String.
EXAMPLE: OVERRIDE PATH FROM="lib3"
FROM String. Mandatory.
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.
Free text description of the job. String.
EXAMPLE: DESCRIPTION FROM="data backup from 120399"
FROM String. Mandatory.
Name of the file containing job documentation. String.
EXAMPLE: DOCMEM FROM="mem4"
FROM String. Mandatory.
Name of a library or directory containing the job documentation file. String.
Mandatory.
EXAMPLE: DOCLIB FROM="AcctFiles"
FROM String. Mandatory.
Days of the month on which to order the job. String. Optional.
EXAMPLE: DAYS FROM="ALL"
74
Control-M Utilities Guide
Parameter
DAYS_AND_OR
WEEKDAYS
DATE
DAYSCAL
WEEKSCAL
CONFCAL
RETRO
Description
FROM String. Mandatory.
Indicates the relationship between specified Days values and Weekdays values.
Optional.
EXAMPLE: DAYS_AND_OR FROM="AND"
FROM String. Mandatory.
Days of the week on which to order the job. String. Optional.
EXAMPLE: WEEKDAYS FROM="1,2,4"
FROM String. Mandatory.
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"
Name of a user-defined calendar used to specify a set of days. String. Optional.
EXAMPLE: DAYSCAL FROM="shipping"
FROM String. Mandatory.
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.
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.
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
SHIFT
SHIFTNUM
MAXDAYS
MAXRUNS
RERUNMEM
RETEN_DAYS
Description
FROM Mandatory. Valid values:
0 (No. Default)
1 (Yes)
Describes how to shift the scheduling date of the job.
EXAMPLE: SHIFT FROM="PREVDAY"
FROM Mandatory. Valid values:
IGNOREJOB
PREVDAY
NEXTDAY
NOCONFCAL
Number of days to shift the scheduling date of the job.
EXAMPLE: SHIFTNUM FROM="-10"
FROM String. Mandatory.
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.
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.
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.
( 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
RETEN_GEN
TASK_CLASS
PREV_DAY
IND_CYCLIC
Description
( 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.
Job class for the task.
EXAMPLE: TASK_CLASS FROM="Distribution"
FROM Mandatory. Valid values:
Distribution
Decollation
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
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_
CALENDAR_RELATIO
NSHIP
Relationship (AND|OR) between the specified Rule-Based Calendar and the job’s own basic scheduling criteria. Optional.
EXAMPLE: RULE_BASED_CALENDAR_RELATIONSHIP FROM="AND"
FROM Mandatory. Valid values:
AND
OR
77
Control-M Utilities Guide
Parameter
TAG
_RELATIONSHIP
SYSDB
PDSNAME
MINIMUM
CATEGORY
Description
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"
FROM Mandatory. Valid values:
AND
OR
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)
Name of a partitioned dataset (PDS) to be checked for free space. String. Optional.
EXAMPLE: PDSNAME FROM="Lib_3"
FROM String. Mandatory.
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.
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
PREVENTNCT2
Description
( 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,
MAY, JUN, JUL, AUG,
SEP,
OCT, NOV, DEC
Months when the job can run. Optional.
EXAMPLE: JAN FROM="0"
FROM Mandatory. Not including a month is the same as including a month having the value 0. Valid values:
0 (Default)
1
OPTION 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
PAR
FROM
ADJUST_COND
APPL_TYPE
APPL_VER
APPL_FORM
CM_VER
Description
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.
Limits the OUTPUT handling operation to OUTPUTs from the specified class.
Optional.
EXAMPLE: FROM FROM="5"
FROM String. Mandatory.
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.
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.
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.
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.
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
MULTY_AGENT
ACTIVE_FROM
Description
FROM Mandatory. String. Up to 10 characters.
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.
( 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"
ACTIVE_TILL
TIMEZONE
FROM Mandatory. Date Format: YYYYMMDD
( 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
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
_HOST
Specifies the host in the JES network on which the job is to execute.
FROM String. Mandatory.
EXAMPLE: REQUEST_NJE_HOST FROM="OS5"
81
Control-M Utilities Guide
Parameter
SCHEDULING
_ENVIRONMENT
CREATION
_USER
CREATION
_DATE
CREATION
_TIME
CHANGE
_USERID
CHANGE
_DATE
CHANGE_TIME
Description
( z/OS only ) Indicates the JES2 workload management scheduling environment that is to be associated with the job.
FROM String. Mandatory.
EXAMPLE: SCHEDULING_ENVIRONMENT FROM="SCHD2"
Name of the user who created the job. String.
EXAMPLE: CREATION_USER FROM="emuser"
FROM String. Mandatory.
Date on which the job was created. String.
EXAMPLE: CREATION_DATE FROM="1212"
FROM String. Mandatory.
Time at which the job was created. String.
EXAMPLE: CREATION_TIME FROM="1230"
FROM String. Mandatory.
Name of the user that last modified the job. String.
EXAMPLE: CHANGE_USERID FROM="emuser"
FROM String. Mandatory.
Date that the job was last modified. String.
EXAMPLE: CHANGE_DATE FROM="1204"
FROM String. Mandatory.
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.
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
), 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
PARAM
Description
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
OP
VALUE
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
Mandatory. Valid values:
EQ – Equal
NEQ – Not equal
NOTIN – Does not contain
LIKE – Mask or pattern using wildcards
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
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
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.
) 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
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.
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"
Folder_DSN
FROM String. Mandatory
(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"
FOLDER_
ORDER_ METHOD
FROM String. Mandatory.
String. Mandatory.
NOTE: A TO parameter can be specified and modified for this parameter.
FOLDER_ORDER_ METHOD FROM="Job3"
JOBNAME
FILE_NAME
FROM String. Mandatory.
Name of the job processing definition. Optional.
JOBNAME FROM="Job3" TO="Job3_COPY"
FROM
TO
Mandatory.
Optional.
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
TO
Mandatory.
Optional.
92
Control-M Utilities Guide
Parameter
APPLICATION
Description
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
TO
String. Mandatory.
String Optional.
93
Control-M Utilities Guide
Parameter
TASKTYPE
CREATED_BY
Description
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.
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
TO
String. Mandatory.
String. Optional.
94
Control-M Utilities Guide
Parameter
FILE_PATH
CMDLINE
HOSTID
RUN_AS
MAXRERUN
TIMEFROM
Description
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.
Command string supplied when the job Task Type is Command. Optional.
CMDLINE FROM="C:\Format" TO="C\:CD Emnt"
FROM
TO
String. Mandatory.
String. Optional.
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.
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
TO
String. Mandatory.
String. Optional.
Maximum number of reruns that can be performed for the job. Optional.
MAXRERUN FROM="1" TO="3"
FROM
TO
String. Mandatory.
String. Optional.
Earliest time for submitting the job. Optional.
TIMEFROM FROM="1430" TO="1450"
FROM
TO
String. Mandatory.
String. Optional.
95
Control-M Utilities Guide
Parameter
TIMETO
DUE_OUT
PRIORITY
Description
Latest time for submitting the job. Optional.
TIMETO FROM="1600" TO="1620"
FROM String. Mandatory.
TO String. Optional.
Time that the job is expected to finish. Optional.
DUE_OUT FROM="1500" TO="1530"
FROM
TO
String. Mandatory.
String. Optional.
Control-M job priority. Optional.
PRIORITY FROM="AA" TO="1A"
FROM
TO
String. Mandatory.
String. Optional.
96
Control-M Utilities Guide
Parameter
CRITICAL
CYCLIC
CYCLIC_TYPE
CYCLIC_
TOLERANCE
Description
Indicates whether the job is a critical-path job in Control-M. Optional.
CRITICAL FROM="0" TO="1"
FROM
TO
Mandatory. Valid values:
0 (No. Default)
1 (Yes)
Optional. Valid values:
0 (No. Default)
1 (Yes)
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)
Determines the type of cyclic job:
Interval
IntervalSequence
SpecificTimes
Maximum delay in minutes permitted for a late submission when selecting a specific time (for example 5 minutes).
CYCLIC_INTERVAL_
SEQUENCE
A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up to 4000 characters including commas.
CYCLIC_TIMES_
SEQUENCE
A list of times, separated by commas (for example 0800,1330,2300), which supports time synonym (for example 2730).
97
Control-M Utilities Guide
Parameter
CONFIRM
AUTOARCH
INTERVAL
OVERRIDE_PATH
Description
Indicates whether the job must be manually confirmed by the Control-M/EM user before it runs. Optional.
CONFIRM FROM="0" TO="1"
FROM
TO
Mandatory. Valid values:
0 (No. Default)
1 (Yes)
Optional. Valid values:
0 (No. Default)
1 (Yes)
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)
Length of time (in minutes) to wait between reruns or cyclic runs of a job.
Integer. Optional.
INTERVAL FROM="3" TO="4"
FROM
TO
String. Mandatory.
String. Optional.
Name of an alternate job script library/directory. String. Optional.
OVERRIDE PATH FROM="lib3" TO="lib4"
FROM
TO
String. Mandatory.
String. Optional.
98
Control-M Utilities Guide
Parameter
MAXWAIT
DESCRIPTION
DOCMEM
DOCLIB
DAYS
Description
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.
Free text description of the job. String. Optional.
DESCRIPTION FROM="data backup from 120399" TO="data backup from 021400"
FROM
TO
String. Mandatory.
String. Optional.
Name of the file containing job documentation. String. Optional.
DOCMEM FROM="mem4" TO="Mem67"
FROM String. Mandatory.
TO String. Optional.
Name of library or directory containing the job documentation file. String.
Optional.
DOCLIB FROM="AcctFiles" TO="HRFiles"
FROM
TO
String. Mandatory.
String. Optional.
Days of the month on which to order the job. String. Optional.
DAYS FROM="ALL" TO="159"
FROM
TO
String. Mandatory.
String. Optional.
99
Control-M Utilities Guide
Parameter
DAYS_AND_OR
WEEKDAYS
DATE
DAYSCAL
WEEKSCAL
Description
Relationship between specified Days values and Weekdays values. Optional.
DAYS_AND_OR FROM="AND" TO="OR"
FROM String. Mandatory.
TO String. Optional.
Days of the week on which to order the job. String. Optional.
WEEKDAYS FROM="1,2,4" TO="ALL"
FROM
TO
String. Mandatory.
String. Optional.
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."
User-defined calendar used to specify a set of days. String. Optional.
DAYSCAL FROM="shipping" TO="receiving"
FROM String. Mandatory.
TO String. Optional.
Calendar to be used to validate specified weekdays on which to order the job.
String. Optional.
WEEKSCAL FROM="w5" TO="w6"
FROM
TO
String. Mandatory.
String. Optional.
100
Control-M Utilities Guide
Parameter
CONFCAL
RETRO
SHIFT
SHIFTNUM
Description
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.
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)
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.
Number of days to shift the scheduling date of the job. Optional.
SHIFTNUM FROM="-10" TO="5"
FROM
TO
String. Mandatory.
String. Optional.
101
Control-M Utilities Guide
Parameter
MAXDAYS
MAXRUNS
RERUNMEM
RETEN_DAYS
RETEN_GEN
Description
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.
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
TO
String. Mandatory.
String. Optional.
( 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.
( 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.
( z/OS only ) Maximum number of generations to keep in the History Jobs file.
String. Optional.
RETEN_GEN FROM="3" TO="4"
FROM
TO
String. Mandatory.
String. Optional.
102
Control-M Utilities Guide
Parameter
PREV_DAY
IND_CYCLIC
RULE_BASED_
CALENDAR_
RELATIONSHIP
Description
Optional.
PREV_DAY FROM="N" TO="Y"
FROM
TO
Mandatory. Valid values:
Y
N
Optional. Valid values:
Y
N
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
Relationship (AND|OR) between the specified Rule-Based Calendar and the job’s own basic scheduling criteria. Optional.
RULE_BASED_CALENDAR_RELATIONSHIP FROM="AND" TO="OR"
FROM
TO
Mandatory. Valid values:
AND
OR
Optional. Valid values:
AND
OR
103
Control-M Utilities Guide
Parameter
TAG_
RELATIONSHIP
SYSDB
PDSNAME
MINIMUM
Description
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.
TAG_RELATIONSHIP FROM="AND" TO="OR"
FROM
TO
Mandatory. Valid values:
AND
OR
Optional. Valid values:
AND
OR
Determines whether single or multiple data sets are used to catalogue sysdata. Optional.
SYSDB FROM="1" TO="0"
FROM
TO
Mandatory. Valid values:
0 (Multiple. Default)
1 (Single)
Optional. Valid values:
0 (Multiple. Default)
1 (Single)
Name of partitioned dataset (PDS) to be checked for free space. String.
Optional.
PDSNAME FROM="Lib_3" TO="Lib_5"
FROM
TO
String. Mandatory.
String. Optional.
Minimum number of free partitioned dataset tracks required by the library specified for the PDSNAME parameter. Integer. Optional.
MINIMUM FROM="5" TO="6"
FROM
TO
Integer. Mandatory.
Integer. Optional.
104
Control-M Utilities Guide
Parameter
CATEGORY
Description
Name of a Control-D report decollating mission category that must be scheduled under Control-D when the job is scheduled under Control-M.
String. Optional.
CATEGORY FROM="*" TO="DAILY"
FROM
TO
String. Mandatory.
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,
MAY, JUN, JUL, AUG,
SEP,
OCT, NOV, DEC
Months when the job can run. Optional. Not including a month is the same as including that month with the value 0.
JAN FROM="0" TO="1"
JUL FROM="0" TO="1"
OPTION
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.)
Job output (Output) handling options. Optional.
OPTION FROM="Copy" TO="Release"
106
Control-M Utilities Guide
Parameter
PAR
FROM
ADJUST_COND
Description
FROM Mandatory. Valid values:
Release
Delete
Copy
Move
File
NewDest
ChangeClass
Optional. Valid values: same as mandatory FROM values. TO
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
TO
String. Mandatory.
String. Optional.
Limits the OUTPUT handling operation to OUTPUTs from the specified class.
Optional.
FROM FROM="1" TO="2"
FROM
TO
String. Mandatory.
String. Optional.
Indicates whether to ignore prerequisite conditions normally set by predecessor jobs if the relevant predecessor jobs are not scheduled. This parameter is relevant only for jobs in a SMART Folder. Optional. Valid values:
0 (Do not ignore. Default.)
1 (Ignore relevant prerequisite conditions.)
ADJUST_COND FROM="1" TO="0"
FROM
TO
String. Mandatory.
String. Optional.
107
Control-M Utilities Guide
Parameter
APPL_TYPE
APPL_VER
CM_VER
APPL_FORM
Description
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.
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
TO
Mandatory. String. Up to 10 characters.
Optional. String.
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
TO
Mandatory. String. Up to 30 characters.
Optional. String.
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
TO
Mandatory. String. Up to 10 characters.
Optional. String.
108
Control-M Utilities Guide
Parameter Description
MULTY_AGENT
ACTIVE_FROM
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.
( 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"
ACTIVE_TILL
TIMEZONE
FROM Mandatory. Date Format: YYYYMMDD
TO Optional. String.
( 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
TO
Mandatory. Date Format: YYYYMMDD
Optional. String.
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
REQUEST_NJE_
HOST
SCHEDULING_
ENVIRONMENT
CREATION_USER
CREATION_TIME
CREATION_DATE
Description
TO String. Optional.
SYSTEM_AFFINITY FROM="SYS3" TO="SYS6"
Host in the JES network on which the job is to execute.
FROM String. Mandatory.
REQUEST_NJE_HOST="OS5"
TO String. Optional.
REQUEST_NJE_HOST FROM="OS5" TO="OS6"
( z/OS only ) Indicates the JES2 workload management scheduling environment associated with the job.
FROM String. Mandatory.
SCHEDULING_ENVIRONMENT FROM="SCHD2"
TO String. Optional.
SCHEDULING_ENVIRONMENT FROM="SCHD2"
TO="SCHD3"
Name of the user that created the job. String. Optional.
CREATION_USER FROM="emuser" TO="em1"
FROM
TO
String. Mandatory.
String. Optional.
Date that the job was created. String. Optional.
CREATION_DATE FROM="1212" TO="2012"
FROM
TO
String. Mandatory.
String. Optional.
Time that the job was created. String. Optional.
CREATION_TIME FROM="1230" TO="1430"
FROM
TO
String. Mandatory.
String. Optional.
110
Control-M Utilities Guide
Parameter
CHANGE_USERID
CHANGE_DATE
CHANGE_TIME
Description
Name of the user that last modified the job. String. Optional.
CHANGE_USERID FROM="emuser" TO="emacct"
FROM String. Mandatory.
TO String. Optional.
Date that the job was last modified. String. Optional.
CHANGE_DATE FROM="1204" TO="1304"
FROM
TO
String. Mandatory.
String. Optional.
Time that the job was last modified. String. Optional.
CHANGE_TIME FROM="1650" TO="1700"
FROM
TO
String. Mandatory.
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
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
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
) 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.
) , 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
PARAM
Description
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
OP
VALUE
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
Relationship between the NAME and VALUE parameters of the TERM. Mandatory. Valid values:
EQ – equal
NEQ – not equal
LIKE – mask or pattern
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
ENCE
A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up to 4000 characters including commas.
CYCLIC_TIMES_SEQUEN
CE
A list of times, separated by commas (for example 0800,1330,2300), which 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.
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
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>
<password>
Control-M/EM database user name
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
Name>
<input args file name>
Control-M/EM GUI server logical name
Path and name of the arguments file that contains criteria for job and
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 file name>
Path and name of the output file that contains the summary of 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.
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
OP
VALUE
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
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
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 ctmem:loop ctmem:job
Between these tags, details about all found loops are listed.
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.
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.
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
) 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
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
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"
FOLDER_DSN
DATACENTER
FROM String. Mandatory
TO String. Optional
( z/OS only
Optional.
) Name of the library that contains the (scheduling) folder.
ABLE_DSN FROM="Lib1" TO="Lib2"
FROM
To
String. Mandatory
String. Optional
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
TO
String. Mandatory
String. Optional
126
Control-M Utilities Guide
Parameter
CYCLIC_TYPE
CYCLIC_
TOLERANCE
CYCLIC_INTERVAL_
SEQUENCE
CYCLIC_TIMES_
SEQUENCE
Description
Determines the type of cyclic job:
Interval
IntervalSequence
SpecificTimes
Maximum delay in minutes permitted for a late submission when selecting a specific time (for example 5 minutes).
A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up to 4000 characters including commas.
A list of times, separated by commas (for example 0800,1330,2300), which 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
JOB
These tags indicate the start and end of the UPDATE argument. Only criteria that are located between the tags are considered to be part of the argument.
Mandatory.
These tags indicate the start and end of 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"
FOLDER_DSN
DATACENTER
FOLDER_ORDER_
METHOD
JOBNAME
FROM String. Mandatory.
( 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.
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.
Optional.
NOTE: This parameter cannot be modified.
EXAMPLE: FOLDER_ORDER_ METHOD FROM="Job3"
FROM String. Mandatory.
Name of the job processing definition. Optional.
EXAMPLE: JOBNAME FROM="Job3" TO="Job3_COPY"
128
Control-M Utilities Guide
Parameter
FILE_NAME
SUB_APPLICATION
APPLICATION
Description
FROM Mandatory.
TO Optional.
Name of the file that contains the job script. Optional.
EXAMPLE: FILE_NAME FROM="File3" TO="File7"
FROM
TO
Mandatory.
Optional.
Name of the group to which the job belongs. Optional.
EXAMPLE: GROUP FROM="Grp_HR"
FROM Mandatory.
Name of the application to which the job’s group belongs. Optional.
EXAMPLE: APPLICATION FROM="App3" TO="App1"
FROM
TO
String. Mandatory.
String Optional.
129
Control-M Utilities Guide
Parameter
TASKTYPE
Description
Type of the job (task) to be performed by Control-M. Optional.
EXAMPLE: TASKTYPE FROM="Detached" TO="Dummy"
FROM Mandatory.
Valid values:
Job
Detached
Command
Dummy
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
CREATED_BY
FILE_PATH
CMDLINE
HOSTID
RUN_AS
Description
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
TO
String. Mandatory.
String. Optional.
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.
Command string supplied when the job Task Type is Command. Optional.
EXAMPLE: CMDLINE FROM="C:\Format" TO="C\:CD Emnt"
FROM
TO
String. Mandatory.
String. Optional.
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.
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
TO
String. Mandatory.
String. Optional.
131
Control-M Utilities Guide
Parameter
MAXRERUN
TIMEFROM
TIMETO
DUE_OUT
PRIORITY
Description
Maximum number of reruns that can be performed for the job. Optional.
EXAMPLE: MAXRERUN FROM="1" TO="3"
FROM String. Mandatory.
TO String. Optional.
Earliest time for submitting the job. Optional.
EXAMPLE: TIMEFROM FROM="1430" TO="1450"
FROM
TO
String. Mandatory.
String. Optional.
Latest time for submitting the job. Optional.
EXAMPLE: TIMETO FROM="1600" TO="1620"
FROM String. Mandatory.
TO String. Optional.
Time that the job is expected to finish. Optional.
EXAMPLE: DUE_OUT FROM="1500" TO="1530"
FROM
TO
String. Mandatory.
String. Optional.
Indicates Control-M job priority. Optional.
EXAMPLE: PRIORITY FROM="AA" TO="1A"
FROM
TO
String. Mandatory.
String. Optional.
132
Control-M Utilities Guide
Parameter
CRITICAL
CYCLIC
CONFIRM
AUTOARCH
Description
Indicates whether the job is a critical-path job in Control-M. Optional.
EXAMPLE: CRITICAL FROM="0" TO="1"
FROM
TO
Mandatory. Valid values:
0 (No. Default)
1 (Yes)
Optional. Valid values:
0 (No. Default)
1 (Yes)
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)
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
TO
Mandatory. Valid values:
0 (Default)
1
Optional. Valid values:
0 (Default)
1
Determines whether SYSDATA is to be archived. Optional.
EXAMPLE: AUTOARCH FROM=0" TO="1"
133
Control-M Utilities Guide
Parameter
INTERVAL
OVERRIDE_PATH
MAXWAIT
DESCRIPTION
Description
FROM Mandatory. Valid values:
0 (No. Default)
1 (Yes)
TO Optional. Valid values:
0 (No. Default)
1 (Yes)
Length of time (in minutes) to wait between reruns of a job or between cyclic runs of a job. Integer. Optional.
EXAMPLE: INTERVAL FROM="3" TO="4"
FROM
TO
String. Mandatory.
String. Optional.
Name of an alternate job script library/directory. String. Optional.
EXAMPLE: OVERRIDE PATH FROM="lib3" TO="lib4"
FROM String. Mandatory.
TO String. Optional.
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
TO
Integer. Mandatory.
Integer. Optional.
Free text description of the job. String. Optional.
EXAMPLE: DESCRIPTION FROM="data backup from 120399" TO="data backup from 021400"
FROM
TO
String. Mandatory.
String. Optional.
134
Control-M Utilities Guide
Parameter
DOCMEM
DOCLIB
DAYS
DAYS_AND_OR
WEEKDAYS
Description
Name of the file containing job documentation. String. Optional.
EXAMPLE: DOCMEM FROM="mem4" TO="Mem67"
FROM String. Mandatory.
TO String. Optional.
Name of a library or directory containing the job documentation file. String.
Optional.
EXAMPLE: DOCLIB FROM="AcctFiles" TO="HRFiles"
FROM
TO
String. Mandatory.
String. Optional.
Days of the month on which to order the job. String. Optional.
EXAMPLE: DAYS FROM="ALL" TO="159"
FROM String. Mandatory.
TO String. Optional.
Indicates the relationship between specified Days values and Weekdays values.
Optional.
EXAMPLE: DAYS_AND_OR FROM="AND" TO="OR"
FROM
TO
String. Mandatory.
String. Optional.
Days of the week on which to order the job. String. Optional.
EXAMPLE: WEEKDAYS FROM="1,2,4" TO="ALL"
FROM
TO
String. Mandatory.
String. Optional.
135
Control-M Utilities Guide
Parameter
DATE
DAYSCAL
WEEKSCAL
CONFCAL
Description
Specific dates on which to order the job. String. mmdd format. Optional.
EXAMPLE: DATE FROM="0312" TO="0319"
FROM
TO
String. Mandatory. Dates are written in mmdd format. There is no delimiter between dates. For example, January 10 is written in this manner: DATE="0110"
String. Optional. Dates are written in mmdd format. There is no delimiter between dates. For example, January 10 is written in this manner: DATE="0110"
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.
Name of a calendar to be used to validate specified weekdays on which to order the job. String. Optional.
EXAMPLE: WEEKSCAL FROM="w5" TO="w6"
FROM
TO
String. Mandatory.
String. Optional.
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
TO
String. Mandatory.
String. Optional.
136
Control-M Utilities Guide
Parameter
RETRO
SHIFT
SHIFTNUM
MAXDAYS
Description
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
TO
Mandatory. Valid values:
0 (No. Default)
1 (Yes)
Optional. Valid values:
0 (No. Default)
1 (Yes)
Describes how to shift the scheduling date of the job. Optional.
EXAMPLE: SHIFT FROM="PREVDAY" TO="NEXTDAY"
FROM Mandatory. Valid values:
IGNOREJOB
PREVDAY
NEXTDAY
NOCONFCAL
Optional. Valid values: Same values as mandatory FROM. TO
Number of days to shift the scheduling date of the job. Optional.
EXAMPLE: SHIFTNUM FROM="-10" TO="5"
FROM
TO
String. Mandatory.
String. Optional.
Maximum number of days to retains the SYSDATA archive dataset for jobs that ended NOTOK. Subparameter of AUTOARCH. String. Optional.
EXAMPLE: MAXDAYS FROM="07" TO="14"
FROM
TO
String. Mandatory.
String. Optional.
137
Control-M Utilities Guide
Parameter
MAXRUNS
RERUNMEM
RETEN_DAYS
RETEN_GEN
TASK_CLASS
Description
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.
Name of the JCL member to use when the job is automatically rerun. String. 1 - 8 characters. Optional.
EXAMPLE: RERUNMEM FROM="Mem45" TO="Mem7"
FROM
TO
String. Mandatory.
String. Optional.
( z/OS only
Optional.
) Number of days to retain the job in the History Jobs file. String.
EXAMPLE: RETEN_DAYS FROM="5" TO="7"
FROM String. Mandatory.
TO String. Optional.
( 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.
Optional.
EXAMPLE: TASK_CLASS FROM="Distribution" TO="Decollation"
FROM
TO
String. Mandatory.
String. Optional.
138
Control-M Utilities Guide
Parameter
PREV_DAY
IND_CYCLIC
RULE_BASED_
CALENDAR
_RELATIONSHIP
Description
Optional.
EXAMPLE: PREV_DAY FROM="N" TO="Y"
FROM
TO
Mandatory. Valid values:
Y
N
Optional. Valid values:
Y
N
Indicates whether the interval between further runs of a cyclic job is counted from the start or the end of the previous job run. Optional.
EXAMPLE: IND_CYCLIC FROM="Y" TO="N"
FROM
TO
Mandatory. Valid values:
START
END
Optional. Valid values:
START
END
Relationship (AND|OR) between the specified Rule-Based Calendar and the job’s own basic scheduling criteria. Optional.
EXAMPLE: RULE_BASED_CALENDAR_RELATIONSHIP FROM="AND"
TO="OR"
FROM
TO
Mandatory. Valid values:
AND
OR
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"
SYSDB
PDSNAME
MINIMUM
FROM
TO
Mandatory. Valid values:
AND
OR
Optional. Valid values:
AND
OR
Determines whether one or multiple data sets are used to catalogue sysdata.
Optional.
EXAMPLE: SYSDB FROM="1" TO="0"
FROM
TO
Mandatory. Valid values:
0 (Multiple-Default)
1 (Single)
Optional. Valid values:
0 (Multiple-Default)
1 (Single)
Name of a partitioned dataset (PDS) to be checked for free space. String. Optional.
EXAMPLE: PDSNAME FROM="Lib_3" TO="Lib_5"
FROM
TO
String. Mandatory.
String. Optional.
Minimum number of free partitioned dataset tracks required by the library specified for the PDSNAME parameter. Integer. Optional.
MINIMUM FROM="5" TO="6"
FROM
TO
Integer. Mandatory.
Integer. Optional.
140
Control-M Utilities Guide
Parameter
CATEGORY
Description
Name of a Control-D report decollating mission category that must be scheduled under Control-D when the job is scheduled under Control-M. String. Optional.
EXAMPLE: CATEGORY FROM="*" TO="DAILY"
FROM
TO
String. Mandatory.
String. Optional.
141
Control-M Utilities Guide
Parameter
PREVENTNC2
JAN, FEB, MAR,
APR, MAY, JUN,
JUL, AUG, SEP,
OCT, NOV, DEC
OPTION
Description
( z/OS only ) Performs dataset cleanup before the original job run. Optional.
EXAMPLE: PREVENTNC2 FROM="1" TO="0"
FROM
TO
Mandatory. Valid values:
0 (Default)
1
Optional. Valid values:
0 (Default)
1
Months when the job can run. Optional. Not including a month is the same as including a month with value 0.
EXAMPLE: JAN FROM="0" TO="1"
FROM Mandatory. Valid values:
0 (Default)
1
TO Optional. Valid values:
0 (Default)
1
Job output (output) handling options. Optional.
EXAMPLE: OPTION FROM="Copy" TO="Release"
FROM
TO
Mandatory. Valid values:
Release
Delete
Copy
Move
File
NewDest
ChangeClass
Optional. Valid values: Same as mandatory FROM.
142
Control-M Utilities Guide
Parameter
PAR
FROM
ADJUST_COND
APPL_TYPE
Description
Certain OPTION values require that you supply additional information (such as
Release, NewDest). The PAR parameter holds that information as a string.
Optional.
EXAMPLE: PAR FROM="mem3log" TO="mem5log"
FROM
TO
String. Mandatory.
String. Optional.
Limits the OUTPUT handling operation to OUTPUTs from the specified class.
Optional.
EXAMPLE: FROM FROM="1" TO="2"
FROM
TO
String. Mandatory.
String. Optional.
Indicates whether to ignore prerequisite conditions normally set by predecessor jobs if the relevant predecessor jobs are not scheduled. This parameter is relevant only for jobs in a 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.
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
TO
Mandatory. String. Up to 10 characters.
Optional. String.
143
Control-M Utilities Guide
Parameter
APPL_VER
APPL_FORM
CM_VER
MULTY_AGENT
ACTIVE_FROM
Description
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.
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
TO
Mandatory. String. Up to 30 characters.
Optional. String.
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.
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.
( 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
TO
Mandatory. Date Format: YYYYMMDD
Optional. String.
144
Control-M Utilities Guide
Parameter
ACTIVE_TILL
TIMEZONE
CREATION_USER
CREATION_DATE
CREATION_TIME
Description
( 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.
Global time zone used to calculate the interval for time-related conditions.
Optional.
EXAMPLE: TIMEZONE FROM="EST" TO="GMT"
FROM Mandatory. String.
Default: GMT
Optional. String. TO
Name of the user that created the job. Optional.
EXAMPLE: CREATION_USER FROM="emuser" TO="em1"
FROM
TO
String. Mandatory.
String. Optional.
Date that the job was created. Optional.
EXAMPLE: CREATION_DATE FROM="1212" TO="2012"
FROM
TO
String. Mandatory.
String. Optional.
Time that the job was created. Optional.
EXAMPLE: CREATION_TIME FROM="1230" TO="1430"
FROM
TO
String. Mandatory.
String. Optional.
145
Control-M Utilities Guide
Parameter
CHANGE_USERID
CHANGE_DATE
CHANGE_TIME
Description
Name of the user that last modified the job. Optional.
EXAMPLE: CHANGE_USERID FROM="emuser" TO="emacct"
FROM String. Mandatory.
TO String. Optional.
Date that the job was last modified. Optional.
EXAMPLE: CHANGE_DATE FROM="1204" TO="1304"
FROM
TO
String. Mandatory.
String. Optional.
Time that the job was last modified. Optional.
EXAMPLE: CHANGE_TIME FROM="1650" TO="1700"
FROM
TO
String. Mandatory.
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
SMART_FOLDER
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.
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"
DATACENTER
FROM String. Mandatory
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"
FOLDER_DSN
FROM String. Mandatory
( 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
FOLDER_ORDER_
METHOD
Description
Optional.
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"
USED_BY
USED_BY_CODE
FROM
TO
String. Mandatory.
String. Optional.
Optional.
EXAMPLE: USED_BY FROM="fff" TO="ffg"
FROM String. Mandatory.
TO String. Optional.
Optional.
EXAMPLE: USED_BY_CODE FROM="C***" TO="D***"
MODIFIED
LAST_UPLOAD
FROM
TO
String. Mandatory.
String. Optional.
Optional.
EXAMPLE: MODIFIED FROM="1101" TO="1102"
FROM String. Mandatory.
TO String. Optional.
Date of the last folder upload. String. Optional.
EXAMPLE: LAST_UPLOAD FROM="1101" TO="1102"
FROM
TO
String. Mandatory.
String. Optional.
148
Control-M Utilities Guide
Parameter
CHECKSUM
FOLDER_ID
REAL_FOLDERID
JOBNAME
FILE_NAME
APPLICATION
Description
Optional.
EXAMPLE: CHECKSUM FROM="Y" TO="N"
FROM String. Mandatory.
TO String. Optional.
Name of the folder to which the job belongs. Optional.
EXAMPLE: FOLDER_ID FROM="Tbl001" TO="Tbl002"
FROM
TO
String. Mandatory.
String. Optional.
Optional.
EXAMPLE: REAL_FOLDERID FROM="43556" TO="43557"
FROM String. Mandatory.
TO String. Optional.
Name of the job processing definition. Optional.
EXAMPLE: JOBNAME FROM="Job3"
FROM
TO
String. Mandatory.
String. Optional.
Name of the file that contains the job script. Optional.
EXAMPLE: FILE_NAME FROM="File3" TO="File7"
FROM String. Mandatory.
TO String. Optional.
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
TO
String. Mandatory.
String. Optional.
149
Control-M Utilities Guide
Parameter
RUN_AS
ADJUST_COND
CONFIRM
PRIORITY
Description
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.
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
TO
String. Mandatory.
String. Optional.
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
TO
Mandatory. Valid values:
0 (Default)
1
Optional. Valid values:
0 (Default)
1
Indicates Control-M job priority. Optional. Two-character alphanumeric from 00 to ZZ.
EXAMPLE: PRIORITY FROM="AA" TO="BB"
FROM
TO
String. Mandatory.
String. Optional.
150
Control-M Utilities Guide
Parameter
TIMEFROM
TIMETO
DUE_OUT
DOCMEM
DOCLIB
DESCRIPTION
Description
Indicates the earliest time for submitting the SMART Folder. Format: hhmm. Optional.
EXAMPLE: TIMEFROM FROM="1430" TO="1450"
FROM String. Mandatory.
TO String. Optional.
Indicates the latest time for submitting the SMART Folder. Format: hhmm. Optional.
EXAMPLE: TIMETO FROM="1430" TO="1450"
FROM
TO
String. Mandatory.
String. Optional.
Time that the job is expected to finish. Optional.
EXAMPLE: DUE_OUT FROM="1500" TO="1750"
FROM String. Mandatory.
TO String. Optional.
Name of the file containing job documentation. String. Optional.
EXAMPLE: DOCMEM FROM="mem4" TO="Mem67"
FROM
TO
String. Mandatory.
String. Optional.
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.
Free text description of the job. String. Optional.
EXAMPLE: DESCRIPTION FROM="backup jobs from 120399" TO="backup jobs from 021400"
FROM
TO
String. Mandatory.
String. Optional.
151
Control-M Utilities Guide
Parameter
CREATED_BY
Description
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"
CREATION_TIME
FROM String. Mandatory.
TO String. Optional.
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
TO
String. Mandatory.
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
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
Before you begin:
Ensure you create an arguments file, which contains the arguments that export the Site Standards from
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>
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
PARAM
Description
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
OP
VALUE
String. Mandatory. The name of the site standard
Relationship between the NAME and VALUE parameters of the TERM. Mandatory. Valid values:
EQ – equal
NEQ – not equal
LIKE – mask or pattern
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
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]
160
Control-M Utilities Guide
Export/import site standards parameters
The following table describes the exportsitestandards and importsitestandards utilities parameters:
Parameter Description
<user>
<password>
<password file name>
<GUI Server
Name>
<data file name>
<args file name>
<file name>
/o
Control-M/EM user name.
Control-M/EM user password.
Flat file containing an unencrypted user name and password on separate lines in the format: user=< userName> password= <password>
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.
( import only ) Defines the path and name of the XML file containing the Site Standards.
( 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.
( export only ) Path and name of the output file containing the exported site standards
( 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
(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
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>
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.
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.
PARAM
REL Relationship between terms. Optional. Valid values:
AND
OR
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
OP
VALUE
String. Mandatory. The name of the promotion rule.
Relationship between the NAME and VALUE parameters of the TERM. Mandatory. Valid values:
EQ – equal
NEQ – not equal
LIKE – mask or pattern
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:
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]
Export/import promotion rule parameters
The following table describes the parameters for exportpromotionrule and importpromotionrule utilities:
Parameter Description
<user>
<password>
<password file name>
<GUI Server Name>
<data file name>
<args file name>
<file name>
/o
Defines the Control-M/EM user name.
Defines the Control-M/EM user password.
Flat file containing an unencrypted user name and password on separate lines in the format: user=<userName> password=<password>
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.
(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
) and XML file rules (on page 35 ).
(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.
(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 ).
(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
Imports service processing definitions into the Control-M/EM database
Exports service definitions
For emdef parameters related to jobs, see emdef utility for jobs (on page 42 ).
defservice
The defservice utility imports service processing definitions into existing folders in the Control-M/EM
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
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
) 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
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.
) 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
-ctm
-folder
-app
-subapp
-service
/?
/a
exportdefservice parameters
The following table lists the exportdefservice parameters:
Parameter
<user>
<password>
<password file name>
Description
Control-M/EM database user name.
The Control-M/EM database user password.
Flat file containing an unencrypted user name and password on separate lines in the format: user=< userName > password=< password>
<GUI Server
Name>
<Args file name>
<file 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.
Path and name of the arguments file containing exportdefservice
specifications. For information about this file, see XML file rules (on page 35 )
Path and name of the file containing the exported service specifications.
Name of the Control-M installation that processes the job.
Name of folder.
Name of the Application to which the job's group belongs
Name of the Sub Application to which the job belongs.
Name of the service for export.
Displays utility's description and available options.
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.
), 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
PARAM
Description
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
OP
VALUE
String. Mandatory. The parameter name of any service processing definition parameter.
Relationship between the NAME and VALUE parameters of the TERM. Mandatory. Valid values:
EQ – equal
NEQ – not equal
LIKE – mask or pattern
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
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]
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
-s
-nshost
-nsport
-action promote
-param_file
-dbg
-promotion rule
Defines the file containing an unencrypted user name and password on separate lines in the format: user=< userName > password=< password>
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.
Defines the naming server host (mandatory).
Defines the Naming server port (mandatory).
Enables you to run promotion (mandatory).
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 ).
Sets the emwacli utility debug level. Default: 2
Values:
1: Warning
2: Information
3: Debug
4: Trace
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
-ignore warnings request_name
-request_ticket
-request_description
-email_notification
-overwrite
Descripton
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.
Defines the name of the promotion request (mandatory).
Defines an ID that can be associated with the request.
Defines the request description that appears in the request details.
Defines the email address for notifications. For more information, see Request Details parameters.
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
-folder_library
Defines the name of the SMART Folder where the job belongs
(mandatory)
(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
-rp
-rpf
Defines the user name in the target environment. Mandatory for defining a remote environment.
Defines the password associated with the user name in the target environment which is used only for promotion requests.
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.
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
ctmfw File Watcher utility (on page 217 )
Description
Enables a specific purpose job to be inserted directly into the Active Jobs database.
Adds a job processing definition to a folder, a SMART folder, and a subfolder in the Control-M/Server database.
The ctmexdef utility exports job processing definitions from the Control-M/Server database to a flat (ASCII) file.
The ctmfw (Control-M File Watcher) utility monitors file status and detects the following file processes:
Successful completion of a file transfer activity
Creation of a file
Deletion of a file
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.
The ctmkilljob utility terminates a specified Control-M job and all its processes. ctmkilljob terminates only jobs that are currently executing.
The ctmorder utility orders or forces one or more jobs from a SMART Folder in the Control-M/Server database.
The ctmpsm utility can be invoked interactively to display the Control-M Production Support menu.
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.
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
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>] ] ]
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
-CREATED_BY
-CYCLIC
-CYCLIC_TYPE
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.
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.
Indicates whether the job is cyclic (to be run at regular intervals).
Optional.
Valid values:
Y – Yes
N – No (Default)
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
-ODATE_OPTION
Description
ODAT yyyymmdd
The current working date of the computer on which Control-M/Server is running.
This is the default value.
A specific working day in format. yyyymmdd
NOTE: The interpretation of this parameter value is dependent on the value specified for the -odate_option parameter (described below).
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
-FOLDER_ORD
Description run_date
ALONE
LAST
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.
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.
The job is on its own (not in any folder).
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
-QUIET
-INPUT_FILE
Level of debug messages, 0 to 5.
Default: 0 (no debug messages).
Indicates, if specified, that no informational messages are displayed during the execution of the command.
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 cc
Recipient of the message. String.
Mandatory.
Additional recipient of the message. String.
Optional.
195
Control-M Utilities Guide
Parameter Description urgency subject message attach output
Urgency of the message.
Valid values:
R (regular - Default)
U (urgent)
V (very urgent)
Brief text description of the message contents. String. Optional.
Text of the message. String. Mandatory.
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
TOLERANCE
CAPTURE
Description
Maximum delay in minutes permitted for a late submission when selecting a specific time (for example 5 minutes).
Valid range: 0-9991
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 skiprows
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
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 ars
Defines the number of words or characters to 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
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.
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
-APPLICATION
Description
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
-input_file
If specified, no information messages are displayed during execution of the command.
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
~< txt controlmOwner >/ctm_server/data/ctmdefine_parms.
-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 search skiprows
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
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
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
-DOMAIL
Description delimiter take
( Only relevant for skipwords beginning/end of the string.
) Defines the character type that marks the
Values:
white space
space
tab
Default: white space
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
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 cc urgency subject message
Recipient of the message. String.
Mandatory.
Additional recipient of the message. String.
Optional.
Urgency of the message.
Valid values:
R (regular - Default)
U (urgent)
V (very urgent)
Brief text description of the message contents. String. Optional.
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
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
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> ]
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
-ACTION
-FILE
-JOBNAME
-FILE_NAME
-FOLDER
Description
DEFINE – The exported file will be in ctmdefine format. Default.
CREATE – The exported file will be in ctmcreate format.
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.
Name of the job.
File name of the job.
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
To allow other users to run ctmfw, they must have write permissions to $CONTROLM and the
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 mode
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.
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. mode
DELETE
CREATE
For more information about monitor file size when wildcard is
used, see below.
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.
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 minimum detected size
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 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). interval between file searches
Interval between successive attempts to detect the existence/deletion of a file (in seconds). Default: 60 interval between filesize comparison iterations
Interval between attempts to monitor the size of a file after it is detected (in seconds). This parameter is ignored when using wildcards in FILE or when using
DELETE mode. Default: 10 number of iterations while size is static
Number of attempts to monitor file size where the size remains static and greater than 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 process
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 Return codes (on page 228 ). Default: 0 (no time limit).
monitor file size when wildcard is used starting time for detecting files
Indicates whether file size should be monitored if the filename contains wildcards.
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 selects the first file that is detected, monitors its file size, and ignores all other matching files.
Indicates an absolute time at which the utility starts monitoring the file. For example,
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
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
CYCLIC_INTERVAL
FROM_TIME
INTERVAL
MAX_AGE
MIN_AGE
Description
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
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
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
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
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
MON_SIZE_
WILDCARD
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).
Indicates whether file size should be monitored if the filename contains wildcards.
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
STOP_TIME
WAIT_TIME
Description
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.
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>
<condition date> <+|->
Add (+) or delete (-) a condition.
DO_EXIT [exit code]
DO_NOTOK [exit code]
Terminate ctmfw with the user-defined 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
Run as
From Time
Command line
FileWatch
<control_m_user>
1900 ctmfw "\tmp\trans.dat" CREATE 100 60 10 5 180
On Statement/Code processing:
Stmt
Code
Do Cond
Stmt
Code
Do Shout
*
COMPSTAT=0 file_trans_dat_ok Date: ODAT Sign: +
*
COMPSTAT=1
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
0
1
7
Description
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).
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.
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
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
229
Control-M Utilities Guide
ctmimptb parameters
The following table lists the ctmpimptb utility parameters:
Parameter Description
-PATH
-OVERWRITE
-DEBUG
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. 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. 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
-H | -Help 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 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
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>
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
-HOSTID
-FILE_PATH
-FILE_NAME
-JOBNAME input_file
Control-M Order ID of the job to be terminated.
Host name of an agent computer, or name of a host group to which the job should be submitted.
Name of the library/directory in which the job script resides.
Name of the file that contains the job script statements.
Descriptive reference for a job processing definition.
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.
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>]
-orctmorder -input_file <fullPathToFileName>
on the ctmorder parameters, see ctmorder parameters (on page 235
) and ctmorder examples (on page
234
Control-M Utilities Guide
ctmorder parameters
The following table lists the ctmorder utility parameters:
Parameter Description
-FOLDER
UNIQUE
-NAME
-odate
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.
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
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.
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
-force
Description
NOTE: The interpretation of this parameter value depends on the value specified for the -odate_option parameter (described below).
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.
-hold
Y
N
N Order the specified jobs. Default.
Place the specified jobs in the Active Jobs database in Hold status.
Hold the specified jobs.
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_
ORDERID
NOTE: This parameter is relevant only for jobs in a SMART Folder. If the folder being ordered is not a SMART Folder, this parameter is ignored.
SMART
Folder order id
Order ID of an existing SMART Folder.
LAST
ALONE
Jobs are added to the last ordered instance of their
SMART Folder in the Active Jobs database.
Jobs are ordered individually. They are not associated with any SMART Folder.
236
Control-M Utilities Guide
Parameter
-noduplication
-debug level
-quiet
-variable
-odate_option
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.
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.
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.
Suppresses display of the utility output. If specified, no information messages are displayed during execution of the command.
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.
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
). For command line invocation, see ctmpsm utility command line parameters
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
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 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
8
9
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
1 List All
Description
Lists all jobs in the Active Jobs database and indicates if they are associated with a SMART Folder (TBL) or
Sub-folder (STB).
2
3
4
5
6
7
10
40
41
42
List All
(Show
Started/Ended)
List All
(Show Application)
List All
(Show File Name)
List Jobs That
Ended OK
List Jobs That
Ended NOTOK
Lists all jobs in the Active Jobs database. Indicates which jobs have started or ended execution.
Lists all jobs in the Active Jobs database. Indicates the application to which each job belongs.
Lists all jobs in the Active Jobs database. Indicates the File
Name for each job.
Lists jobs in the Active Jobs database with a completion
Ended OK status.
Lists jobs in the Active Jobs database that have a completion Ended NOTOK status.
List Submitted/
Executing Jobs
List Cyclic Jobs
Lists jobs in the Active Jobs database that are currently executing.
Lists jobs in the Active Jobs database that are cyclic.
List Jobs Waiting for
Time Window
Lists jobs in the Active Jobs database that are waiting to begin executing based on their Time From parameter.
List Jobs Waiting for
Confirmation
Lists jobs in the Active Jobs database that are waiting for confirmation.
List
Application/Sub-appli cation Tree
Displays a summarized list of the applications and sub-applications for all jobs currently contained in the
Active Jobs database.
List SMART Folders Displays a list of all SMART Folders in the Active Jobs database.
List Ordered SMART
Folders
Displays a list of all ordered SMART Folders in the Active
Jobs database.
242
Control-M Utilities Guide
J
A
LO
LJ
Cn
S1
U
R
ctmpsm active jobs database actions
Option Action
H Hold
F Free
Description
Hold a job.
Free a previously held job.
D
W
Z
S2
Delete Mark a job for deletion.
NOTE: Jobs with Executing or Submitted status cannot be deleted.
Undelete Undelete a job marked for deletion.
Rerun NOTE: Rerun a job. Rerun actions cannot be performed on a sub application.
Why
Details
LogOrd
LogJob
Confirm
Display why a job has not yet been submitted.
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.
List Control-M log entries for a specific Order ID.
List Control-M log entries for a specific Job Name.
Confirm submission of a job.
Sort (by
Order No.)
Sort jobs displayed by Order number.
Sort (by
Job Name)
Sort jobs displayed by Job Name.
Output Display the job OUTPUT.
Statistic Display the job statistics
243
Control-M Utilities Guide
K
I
Option Action
V View
Script/JCL
Description
View a job’s script or JCL.
NOTE: This option is available if Control-M/EM database is active.
GH
Set to OK
Dependenci es Jobs
Global
Action
(Hold)
Set the status of a job to OK.
Display all jobs that depend on the specified job.
Hold all jobs in the displayed list.
GF
GD
Global
Action
(Free)
Global
Action
(Delete)
Free all jobs in the displayed list.
Mark all jobs in the displayed list for deletion.
GU
GR
Global
Action
(Undelete)
Undelete all jobs marked for deletion.
Global
Action
(Rerun)
Rerun all jobs in the displayed list.
NOTE: Rerun actions cannot be performed on a group entity.
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
61
62
63
64
Option
Control
Resources
Description
Lists Control resources currently used in the Active jobs database.
Activates the ecactltb utility.
Quantitative
Resources
Allows you to list, add, modify, or delete Quantitative resources in the Active jobs database. Activates the ecaqrtab utility.
Prerequisite
Conditions
Allows you to view, add or delete prerequisite conditions in the
Active jobs database. Activates the ctmcontb utility.
Control
Resources
Usage
Shows current usage of Control resources by jobs in the Active
Jobs database.
65 Quantitative
Resources
Usage
Shows current usage of Quantitative resources by jobs in the
Active Jobs database.
Scheduling function options
The following table lists scheduling function options for the ctmpsm utility:
Code Option
71 Folders
Description
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
Folders/Job s
Allows you to order SMART Folders or jobs. You are prompted to specify:
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
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
A Add
Description
Adds a Order method to an existed folder. When selected, you are prompted for the Folder name and Order method name.
D# Delete
UserDaily
Folder #
Removes an instance of a 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 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
F# Force folder
#
Description
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
Folder
Deletes a specific Folder and all its associated jobs (for example, specify R RE_OUTPUT to delete folder RE_OUTPUT).
247
Control-M Utilities Guide
Code Option
U# Update folder #
Description
Updates the Order method name for a specific Folder (for example, 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#
M#
Y#
Force job # Forces a specific job (for example, specify F2 to force job
DAYS_30_FEB).
Month Schedule
Plan
Generates a monthly Job Order report for the folder. You are prompted to enter the year and month in format YYYYMM.
Year Schedule
Plan for job #
Generates a yearly Job Order report for a specific job. You are 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:
Description Value
STATUSES
OK The job completed okay.
NOTOK
STATES
Wait Sche
Wait Conf
Wait Reru
Wait Time
Wait Cond
Wait Reso
The job did not complete okay.
The job is waiting to be scheduled.
The job is waiting for user confirmation.
The job is waiting to be rerun.
The job is waiting for its time frame.
The job is waiting for a condition.
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
Retry Sub
The job was submitted (that is, the job was sent to an agent).
The job is waiting for a submission retry.
Executing
Ended
Analyzed
Disappear
Post proc
Wait ODAT
Post ODAT
The job is executing.
The job has ended.
The job is being analyzed.
The job has disappeared in the agent.
The job has performed its post processing activities.
The job is waiting for the appropriate ODAT.
The appropriate ODAT of the job already passed.
249
Control-M Utilities Guide
Value
Unknown
Description
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
CHILD
Description
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 tasktype
Identifies the parent job.
B: Batch job
D: Detached
C: Command
U: Dummy
X: External job
250
Control-M Utilities Guide
Parameter
IMPORT_CAL
LISTCAL
Description
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.
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
LISTALL
Description
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
LISTJOB
Description
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
ON
LISTAJFFLD
FOLDER
Lists jobs in the specified Sub Application that are associated with a Specified
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.
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.
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
LISTOUTPUT
Description
-ADD <folder name> <udaily name>|-DUDAILY <row number>|
-REMOVE <folder name>|-LISTJOBS <row number> [FULL]
-LISTFOLDER
-UPDATE
-ADD
-UDAILY_NAME
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.
Updates the User Daily name for a specific SMART Folder.
Adds a User Daily to an existing folder. The Folder name and
Order method name must be specified when this option is used.
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.
Deletes a specific SMART Folder and its associated jobs.
Lists jobs in a SMART Folder.
-REMOVE
-LISTJOBS
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
LISTDETAILS
LISTFULLDETAILS
UPDATEAJF
Description
Lists the details of the job associated with the specified order ID.
LISTDETAILS < orderID >
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 >
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
TION
Applies a specified command to jobs in the specified Sub Application that are 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
XML
Description
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
-Test
-H | -Help
-DEBUG
Sets the date selection criteria for obsolete jobs
The format of the -Date parameter is < two days before the current date. yyyymmddDate >. The default is
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
Displays the usage
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 sweep_obsolete. txt
U_CTMSWEEP.
<PID>.log
Location Description
< Control-M
ServerHomeDirectory > report of all jobs and folders that are candidates for deletion according to the date criteria
< Control-M
ServerHomeDirectory >
/ctm_server/proclog execution log
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
1
2
Success (All of the obsolete jobs were deleted.)
Failure
Run the ctmsweep utility again.
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
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.
261
Control-M Utilities Guide
ctmsweep delete a job criteria
The following table lists the criteria for deleting a job by the ctmsweep utility:
Relationship
AND
AND
AND
AND
Job (DateUntil/
DateFrom)
Rule-Based Calendar
(DateUntil/ DateFrom) Result obsolete obsolete active active obsolete active obsolete active
Deletes the job
Deletes the job
Deletes the job
The job is active
OR
OR
OR
OR
AND obsolete obsolete active active not defined obsolete active obsolete active obsolete
Deletes the job
The job is active
The job is active
The job is active
Deletes the job.
AND
OR not defined not defined active obsolete
The job is active
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
( Windows only ) Sets the completion status for a job that runs from a .bat file.
( 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
Folders and Calendars utilities
4
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
Control-M/EM
Description
emdef utility for folders and calendars (on page 266 )
Creates various modifications to folder and calendar definitions in the
Control-M/EM database.
Enables you to perform the following operations:
Orders and forces jobs and folders
Uploads and downloads calendars and folders
Deletes jobs from folders
Activates a Workload Policy definition
Control-M/Server
Calculate the date a job can be ordered, after adding or deducting a specified number of days.
Create a definition for a new SMART Folder.
ctmdefsubfolde r (on page 322 )
Create a definition for a new Sub-folder.
Creates a report that lists jobs in a folder and when they are scheduled to 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
Creates a new calendar definition in the Control-M/EM database identical to an existing calendar definition.
Imports a calendar definition into the Control-M database.
Imports Folders and SMART Folders into the Control-M/EM database
Exports calendar definitions in the Control-M/EM database to an output file for use as input to other utilities.
Exports folders from the Control-M/EM database to a text file.
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
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
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
) 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
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
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.
) 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"
CALENDAR
FROM: Data center in which the source calendar is located. String. Mandatory.
TO: Data center in which a calendar can be created. String. Optional.
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
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").
) 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
_CALENDAR
Indicates the opening and closing tags of a single Rule-Based 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
DAYS
Name of the calendar. String Mandatory.
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
DATE
DAYSCAL
WEEKSCAL
Days of the week on which to order the job. String.
Optional.
Valid values: Weekdays
0 - 6
ALL
blank
Specific dates on which to order the job. String.
MMDD format. Optional.
Name of a user-defined calendar used to specify a set of days. String. Optional.
Name of a calendar to be used to validate specified weekdays on which to order the job. String. Optional.
CONFCAL
SHIFT
Specifies a calendar that is used to validate all specified days and dates on which to schedule the job.
String.
Sub-parameter of CONFCAL. Describes how to shift the scheduling date of the job. Valid values:
IGNOREJOB
PREVDAY
NEXTDAY
NOCONFCAL
SHIFTNUM
MAXWAIT
Sub-parameter of CONFCAL. Number of days to shift the scheduling date of the job. Default: +00
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,
APR, MAY, JUN,
JUL, AUG, SEP,
OCT, NOV, DEC
Months when the job can run. Optional. Not including a month is the same as including a month having the value 0. Valid values:
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.
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
) 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
ENFORCE_VALIDATION
FOLDER_ORDER_
METHOD
FOLDER_NAME
Determines if validation is either an error or a warning.
Valid Values: Y or N
NOTE: Relevant for Control-M Workload Change Manager only.
Defines the Newday or User daily name. Optional.
FOLDER_DSN
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)
(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
DATACENTER
Description
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
JOB
Date of the last folder upload. String. Optional.
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
CYCLIC_TYPE Determines the type of cyclic job:
C: CYCLIC_TOLERANCE
V: CYCLIC_INTERVAL_SEQUENCE
S: CYCLIC_TIMES_SEQUENCE
Maximum delay in minutes permitted for a late submission when selecting a specific time (for example 5 minutes).
CYCLIC_
TOLERANCE
CYCLIC_INTERVAL_
SEQUENCE
CYCLIC_TIMES_
SEQUENCE
A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up to 4000 characters including commas.
A list of times, separated by commas (for example 0800,1330,2300), which 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
AME
Defines the name of the Business Parameter name 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.
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
SMART_FOLDER
ENFORCE_VALIDATIO
N
FOLDER_ORDER_
METHOD
FOLDER_NAME
Closing tags of a SMART Folder definition.
Determines if validation is either an error or a warning.
Valid Values: Y or N
NOTE: Relevant for Control-M Workload Change Manager only.
Defines the New day or User daily name. String. Optional.
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
QUENCE
A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up to
4000 characters including commas.
CYCLIC_TIMES_SEQUE
NCE
A list of times, separated by commas (for example 0800,1330,2300), which supports 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
JOBNAME
FILENAME
APPLICATION
SUB_APPLICATION
RUN_AS
Defines the name of the parent folder to which the job's SMART Folder belongs.
String. Mandatory.
Name of the job processing definition. String. Optional.
Name of the file that contains the job script. String. Optional.
Name of the application to which the SMART Folder belongs. Used as a descriptive name for related groups of SMART Folders. String. Mandatory.
Name of the group to which the jobs in the SMART Folder are assigned. String.
Mandatory.
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
CONFIRM
Description
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.)
Indicates Control-M SMART Folder priority. String. Optional. PRIORITY
TIMEFROM
TIMETO
DUE_OUT
DOCMEM
DOCLIB
DESCRIPTION
CREATED BY
Indicates the earliest time for submitting the SMART Folder. String. Optional.
Indicates the latest time for submitting the SMART Folder. String. Optional.
Time that the jobs in the SMART Folder are expected to finish. String. Optional.
Name of the file containing SMART Folder documentation. String. Optional.
Name of the DOCMEM library. String. Optional.
Brief text description of the SMART Folder. String. Optional.
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
CREATION_DATE
CREATION_TIME
Name of the user who created the SMART Folder. String. Optional.
Date on which the SMART Folder was created. String. Optional.
Time at which the SMART Folder was created. String. Optional.
CHANGE_USERID
CHANGE_DATE
CHANGE_TIME
Name of the user who last modified the SMART Folder. String. Optional.
Date on which the SMART Folder was last modified. String. Optional.
Time at which the SMART Folder was last modified. String. Optional.
283
Control-M Utilities Guide
Parameter
MULTY_AGENT
ACTIVE_FROM
ACTIVE_TILL
Description
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.
(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
(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
AR
Identifies a set of scheduling criteria defined for a folder. Mandatory.
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
DAYS_AND_OR
WEEKDAYS
DATE
Defines the days of the month on which to order the jobs in the SMART Folder. String. Optional.
Indicates the relationship between specified Days values and weekday values. Optional. Valid
Values:
A: AND
O: OR
Defines the days of the week on which to order the job in the SMART Folder. Optional.
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
CONFCAL
RETRO
SHIFT
SHIFTNUM
MAXWAIT
MAXRUNS
285
Name of a user-defined calendar used to specify a set of days. String. Optional.
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.
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)
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
Number of days to shift the scheduling date of the jobs in the SMART Folder. String. Optional.
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
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.
Control-M Utilities Guide
Parameter
TAG
Description
JAN, FEB, MAR, APR, MAY, JUN,
JUL, AUG, SEP, OCT, NOV, DEC
Months when the jobs in the SMART Folder can run. Optional. Valid values:
0 (Default)
1
(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"
VALUE
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
E
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_PARAMETE
R_NAME
Defines the name of the Business Parameter name 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.
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
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.
) 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.
) 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
PARAM
Description
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
OP
VALUE
String. Specify at least one of the following calendar parameter names.
Valid values:
DATACENTER
CALENDAR
TYPE
String. Mandatory. Describes the relationship between the NAME and the VALUE parameters of the TERM. Valid values:
EQ
NEQ
NOTIN
LIKE
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
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
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>
) 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.
) 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
PARAM
CYCLIC_TYPE
CYCLIC_
TOLERANCE
CYCLIC_INTERVAL_
SEQUENCE
Description
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
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
NOTE: Multiple values can be specified for VALUE by using the * wildcard character in place of characters at the end of an expression.
Determines the type of cyclic job:
Interval
IntervalSequence
SpecificTimes
Relevant for Control-M version 6.4.01 or later.
Maximum delay in minutes permitted for a late submission when selecting a specific time (for example 5 minutes).
Relevant for Control-M version 6.4.01 or later.
A list of time intervals, separated by commas, (for example +30M,+2H,+1D) up to 4000 characters including commas.
Relevant for Control-M version 6.4.01 or later.
300
Control-M Utilities Guide
Parameter
CYCLIC_TIMES_
SEQUENCE
MAXWAIT
REMOVEATONCE
DAYSKEEPINNOTOK
Description
A list of times, separated by commas (for example 0800,1330,2300), which supports time synonym (for example 2730).
Relevant for Control-M version 6.4.01 or later.
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.
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)
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 ).
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
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>
<password>
Defines the Control-M/EM database user name.
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 seconds>
Defines the time, in seconds, that the utility waits for a response.
Timeout is used to override the default waiting period (120 seconds).
NOTE: Do not use timeout with commands that do not return a response (-JOB_DELETE and -MEM_DELETE).
-DDMM
-BY_FORCE
If specified, reverses the Odate format, as described below.
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
<cmd>
<ctm_name>
<job_name>
A note saved in the audit report justifying the performance of the action.
The syntax for additional commands that are available for specifying with the cli utility.
Defines the Control-M name.
Defines the name of the job.
303
Control-M Utilities Guide
Parameter
<folder_name>
Description
Defines the name of the folder.
<sub_folder_name
>
Defines the name of sub folder.
<Control-M
Calendar>
<Odate>
Defines the name of the Control-M Calendar you want to upload or download.
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
<library>
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
(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.
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
[duplication]
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
ALONE
TableID
Forces the job without adding it to a folder.
Folder into which the job is forced.
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.
on the cli parameters, see the following:
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 folder duplication
Description
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.
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.
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.
on the cli parameters, see cli parameters (on page 303
) and Delete a job definition parameters (on page
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.
on the cli parameters, see cli parameters (on page 303
) and Delete a job definition parameters (on page
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
ALL
NONE
NUMBER library
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 occurrences of the job are deleted, if there is more than one job with the same name.
No jobs are deleted if there is more than one job with the same name.
Deletes the job with the specified sequence number of the duplicate job (for example, if 5 is entered, the fifth occurrence of the Job Name is deleted).
Required for 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>
<emPass>
<GSRHostName>
<request_xml_file>
<response_xml_file>
Defines the Control-M/EM administrator name.
Defines the Control-M/EM administrator password.
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.
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.
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
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
-FOLDER
Description path of the SMART folder or sub-folder
-NAME
-DATE
-SHIFT name of the job or sub-folder indicates the scheduling date (odate) to be associated with the job
Specify the date in yyyymmdd format. 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
_DAYS
OUTPUT_FORMAT indicates whether the scheduling day can be any day of the week or 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 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
-DEBUG
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 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
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 >
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
-DEBUG
-QUIET
-input_file
Description
Level of debug messages, 0 to 5. The default value is 0 (no debug messages.
If specified, no information messages are displayed during execution of the command.
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.
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
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
-DEBUG
-QUIET
-input_file
Description
Level of debug messages, 0 to 5. The default value is 0 (no debug messages).
If specified, no information messages are displayed during execution of the command.
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
ctmrpln report formats
The following table lists the ctmrpln report formats:
Format
Daily Report
Monthly Report
Yearly Report
Description
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.
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.
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.
.
-
Char
*
ctmrpln report characters
The following table lists the report characters that can be used with
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
< ReportType >
Description
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.
<calendar>
<Folder>
MJ
Y Creates a yearly report.
Specify one of the following values:
Y
Creates a monthly report, identifying each job by its
Job Name parameter.
N
Creates the report using the calendar specified in the job’s scheduling parameters.
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.
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
<Job Name>
<date>
<output>
Description
Job Name of the jobs to include in the report. The Job Name can include wildcard characters (see < Folder itself to include all jobs in the folder.
> above). Specify * by
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.
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
New day procedure and user dailies
5
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
Lists job processing definitions that can be ordered by a specific User Daily job.
Allows recovery from interruption of a User Daily.
Enables you to manually set the User Daily last run date.
Orders jobs for a specific User Daily name.
Enables you to define appropriate values for system parameters including 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).
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
<User Name>
Description
Owner of the Order method job.
<Daily name>
<Output>
Defines the name of the User Daily procedure. For more information, see User Daily name.
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
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
-DAILY
-ACTION
Description
Name of the User Daily to be checked. For more information, see User
Daily name.
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.
-odate
-odate_option
ORDER Orders the missing jobs.
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).
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
-FILE
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.
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
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
UPDATE
DELETE
<Daily name>
"*"
<Date>
Lists the name of the User Daily's last run date.
Updates the name of the User Daily's last run date.
Deletes the name of the User Daily's last run date.
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.
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
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
<user Daily>
-odate
-odate_option
Description
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.
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).
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
Scheduling issues
PARTIAL COPY message
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
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.
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
Active Jobs Database utilities
6
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
Parameter values: Refreshes recently updated parameters, as an alternative to restarting
Control-M/Server. For more information, see ctmipc
Quantitative Resources: Updates the resource usage of a Control-M/Agent. For more information, see ctmloadset
Variable values: Displays the current value of a variable. For more information see ctmstvar (on
Global variables: Manipulates Global variables for data centers, SMART Folders (excluding
Sub-folders), or jobs in SMART Folders. For more information, see ctmvar
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
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
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 o ctmcontb -LISTNOWILD <Condition Name> <Condition Date> [-OUTPUT
<output file name>][-FULLDETAILS] 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 o ctmcontb {-ADD|-XML|-DELETE|-DELETEONWILD} <Condition Name>
<Condition Date> ctmcontb -input_file <Full Path file name>
340
Control-M Utilities Guide
on the ctmcontb parameters, see ctmcontb utility parameters (on page 341 ).
ctmcontb utility parameters
The following table lists the ctmcontb utility parameters:
Variable
-FULLDETAILS
<Condition Name>
Description
Displays the prerequisite condition name without truncation.
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
<Condition Date>
<From Date> <To
Date>
<output file name>
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.
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.
For Deleting in a Date Range:
Displays the starting and ending dates for date range of prerequisite conditions to delete. Each date is in mmdd format.
If the To Date is less than the From Date, the range of condition dates will include the From Date up to the end of the year (1231) plus the beginning of the next year (0101) up to the To Date.
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
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
-MSGID
-DATA
-QUIET
-DEBUG
Indicates the destination of the message to be sent (either one specific process, or specify .DEST ALL for all processes).
Indicates the message to be sent.
Indicates additional data to be sent with the message ID (if any).
Indicates that the ctmipc utility will not generate any output message, upon success or a failure.
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
OTHERS
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.
Indicates that the load value provided specifies the units of the resource used by one or more non-Control-M jobs.
<Resource
Name>
Name of the Quantitative resource to update.
<loadValue> Number of units of the resource currently used.
-or-
When % is specified, the amount of the resource currently used, expressed as a percentage of the maximum available units defined for this Quantitative resource.
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:
Resource Max
Total used by
Control-M Total used by others Free
CPU@jacklin
CPU@ruby
200
200
120
150
80
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
CPU@diana
Type
L
Max-Avail
50
Reserved
0
Used
30
Free
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
CPU@diana
Type
L
Max-Avail
50
Reserved
0
Used
48
Free
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
<orderID>
<variableString>
Description
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.
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).
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
-ACTION
Description
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
DELETE
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.
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
-VAR
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.
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
-FILENAME
-QUIET
-DEBUG
-input_file
-POOL
Description
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.
Suppresses the display of the results.
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.
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
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
VIEW
Lists all named pools in the data center.
EXAMPLE: ctmvar -POOL list
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
Checks if Control-M/EM Server components are operational and send commands.
Manages the Naming Service process and the CORBA configuration file.
Lists or updates the status of a Control-M/Agent.
Generates a report on the connection details of a Control-M/Agent and its remote host computer.
Collects and displays Control-M/Agent application information.
Manages the mapping of remote hosts to Control-M/Agents and the conversion of Control-M/Agents to remote host computers.
Enables the maintenance and viewing of host groups.
Collects configuration information about Control-M/Agents and test communications.
Issues a Shout message to a specified destination.
357
Control-M Utilities Guide
Utility
Description
Sets the active Shout Destination folder.
Prints or erases diagnostics from stored procedures and set or show diagnostic request status of stored procedures.
Suspends Control-M/Server scheduling processes for mass uploads/downloads from Control M/EM.
Resets sleep times and trace levels for Control-M/Server processes.
shut_ca (on page 406 ) shut_ctm (on page 406 )
show_ca (on page 407 ) shutdb (on page 407 )
Shuts down the Control-M/Server Configuration Agent.
Shuts down Control-M/Server and its processes.
Displays the status of Control-M/Server Configuration Agent.
Shuts down the SQL database server.
start_ca (on page 408 ) start_ctm (on page 408 )
Starts up the Control-M/Server Configuration Agent.
Starts up Control-M/Server.
Starts up the SQL database server.
Stops Control-M/Server from submitting jobs.
Changes the shared directory path that is used for the PostgreSQL replication in a high availability environment.
Control-M/Agent
Verifies communication between Control-M/Agent and Control-M/Server.
Verifies that Control-M/Server is active on computer connected to a
Control-M/Agent.
358
Control-M Utilities Guide
Utility
Description
Shows if an agent and tracker are running.
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 ).
GUI Server, as described in Sending requests to the GUI server using the ctl utility (on page 366 ).
Configuration Management server, as described in Sending requests to the Configuration
Management server using the ctl utility (on page 370 ).
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
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.
•
•
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.
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 em
-U
-P
-pf
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
-reg
-cmd
-timeout
-diagon
Prefix to be specified when running this utility on a UNIX operating system.
Control-M/EM database user name.
Control-M/EM database user password.
Flat file containing an unencrypted username and password on separate lines in the format: user= username password= password
Checks if the Global Conditions Server is registered in the CommReg table.
-reg cannot be used with -cmd or -cmdstr.
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 k
Checks if the Global Conditions Server is active.
This command cannot be specified with other commands in the same run of the ctl utility.
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.
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 em ctl -U user01 -P pass01 -C GCS -M wip78
Direct the ctl command to all Global Conditions Servers.
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
SERDAILYO
RDER_
METHOD
Directs a request to Control-M for z/OS for updated Order method information to be sent to the Control-M/EM database.
-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
-all
-cmd
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.
Directs a query or command to all components of the gateway (as specified by the -C parameter).
-all cannot be used with -dc.
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
DIAG [on|off] no_dbg db# gui +| – host +| –
Closes the current log and diag files and creates new files.
Start and stop DIAG. Valid values:
on – enable diag facility
off – disable diag facility
Stops all debug printing.
Debug level for database operations. Range: 0 - 9
0 turns off debugging.
Starts or stops a debug trace for the GUI.
Starts or stops output of host debug messages.
363
Control-M Utilities Guide
Parameter Description trunc +| –
-cmdstr
Starts or stops truncating messages. Only the message header and one row of data remain after truncation. alive +| – job +| –
Starts or stops debugging of "keep alive" messages.
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 +| – show_jcl
Starts or stops a debug trace for the GUI link.
Shows active JCL.
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>
<level>
[ <buffer level>]
(sets the diagnostic level)
DIAGSTACKS [ on
| print ]
(enables the diagnostic stacks option, or prints the details of the current stacks)
(set GTW-Clients trace either on or off) TRACE_CLIENT
<on|off>
TRACE_CTM
<on|off>
(set GTW-CTM trace either on or off)
TRACE_DB
<0 - 8>
TRACE_KLIVE
<on|off>
(set database trace level)
(set keep alive trace either on or off)
364
Control-M Utilities Guide
Parameter Description
TRACE_LINK_
CLIENT <on|off>
(set GTW-Clients link level trace either on or off)
TRACE_LINK_
CTM <on|off>
(set GTW-CTM link level trace either on or off)
TRACE_DISABLE_
ALL
(turns off trace options when selected)
TRACE_SNMP
<on|off>
(set trace for SNMP traps either on or off)
TRACE_TRUNC
<on|off>
(set truncate trace messages either on or off)
TRACE_TRUNC_IN
FO <on|off>
(set truncate trace information messages either on or off)
(set job message trace either on or off) TRACE_JOB_
MESSAGE
<on|off>
TRACE_LEVEL_
REPORT
(displays the status of the trace)
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
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
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
-M
-all
-cmd
-cmdstr
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.
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.
Directs a query or command to all Global Conditions Servers. -all cannot be used with -M.
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.
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
-all
-cmd
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.
Directs a query or command to all GUI servers. -all cannot be used with -M.
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
-cmdstr
Description
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
Server
Indicates that the command is directed to a Forecast server (if
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
-all
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.
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
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
-M
-name
-all
-cmdstr
Configuration Management Server to which the command is directed.
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.
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.
Directs a query or command to all Configuration Management Servers.
-all cannot be used with -M.
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
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
-all
Specifies a computer name. This name is used to identify the computer to which the Configuration Agent belongs. -M cannot be used with -all.
Directs a query or command to all Configuration Agents.
-all cannot be used with -M.
-cmd
-cmdstr
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.
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
-C Config_HA
Description
Configuration High Availability Server to which the command is directed.
-M
-all
-cmd
-cmdstr
Specifies a computer name. This name is used to identify the computer to which the Configuration Agent belongs. -M cannot be used with -all.
Directs a query or command to all Configuration Agents.
-all cannot be used with -M.
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.
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
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
-M
-name
-cmdstr
Indicates that the command is directed to a Batch Impact Manager server (if this component is installed at your site).
Specifies a computer name. This name is used to identify the computer to which the Batch Impact Manager server belongs.
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.
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
Service
Server
-M
Indicates that the command is directed to a Self Service Server (if this component is installed at your site).
-name
-cmdstr
Specifies a computer name. This name is used to identify the computer to which the Self Service Server belongs.
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.
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
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 by the orbadmin utility (described here).
Administration ), and
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 domain show
Usage
Displays all parameters and values in the configuration file scope list scope create <name > scope remove <name > variable show -scope <scope>
<name >
Displays all the scopes in a configuration file
Creates a new scope in the configuration file
Removes a scope and its parameters from the file
Displays parameters and their values in the scope scope show <name > variable create -scope <scope>
-value < value> <name >
Creates a parameter (with or without a value) in the specified scope.
If that scope does not exist, it is created. If the value contains a blank, enclose the value in double quotes. variable modify [-scope
-value <
<scope> ] value> <name>
Modifies a parameter value (in the specified scope) of the 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>
<name >
Removes specified parameter from the XML configuration file.
If the scope is not specified, the parameter is removed from all the scopes that contain it.
Displays the specified parameter and its value in the specified (or default) scope.
If the parameter does not exist in the specified scope, the default scope is searched.
377
Control-M Utilities Guide
Command format ns register ns update ns remove ns start ns stop [-local] ns status ns probe ns resolve ns list [-ior]
Usage
( Windows only ) Specifies Naming Service values in the registry and installs the Naming Service as a Windows service.
Updates the Naming Service values in the registry.
( Windows only ) Removes Naming Service values from the registry and uninstalls the Windows service.
Starts the local Naming Service.
Stops the Naming Service. -local is required if a remote Naming
Service is running and you want to stop the local Naming Service.
Checks the status of the configured Naming Service process. Possible status values: Running, Stopped, and Not installed.
Checks if the local Naming Service is configured and registered.
Resolves the Naming Service IOR and prints it to the console.
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 ]
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
-LIST
-UPDATE
Description
Lists the current status of the specified agent.
NOTE: This parameter is mandatory if the -UPDATE parameter is not specified.
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
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
< agent >
<remoteHost>
Description
Host name of the computer where Control-M/Agent is installed
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 list help
Deletes the details of the specified remote host computer in the
Control-M/Server database.
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).
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
-host
-agent
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.
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>"
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
-sshalg
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
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
-EDIT
-DELETE
Displays a list of all existing host groups.
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.
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
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
LS
Generates a status report of the communication parameters of each specified agent or remote host. Where an agent is unavailable, the report displays the reason why the agent is unavailable. Where a remote host is available it displays the connection information.
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 -quie t
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>
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>
<message>
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.
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>
<hostID>
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.
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
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
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
CS
CA
init_prflag sleep time considerations
The following table lists the sleep time considerations for the init_prflag utility:
Process Task
Sleep Time
Initial
Settings Sleep Time Modification Considerations
SU
RT
Supervisor 60 Increase: Delay in startup, downloads, and New
Day procedure
No effect
WD
SL
Inter-process
Communication Router
Watchdog
Job Selector and job post processing
30
360
5
TR
NS
Job Tracking 5
30
No effect
Increase: Delay in Job Submission and Shout messages for late submission. Can be increased during period of minimal job processing.
Decrease: Additional CPU resources.
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.
No effect
LG
CO
CD
Communication with
Control-M/EM
Utilities
Agent invoker
Communication agents
New Day Procedure;
Database uploads and downloads
360
60
60
N/A
N/A
No effect
No effect
No effect
No effect
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
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 ).
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,
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
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.
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
RJX_CONN_TOUT
RJX_OUTPUT_DIR number of attempts made to restore the connection
The default is 15 time interval between attempts to restore the connection
The default is 120 seconds 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
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
Administration and configuration
8
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 rd (on page 417 )
Enables you to automate password changes of Application Plug-ins accounts
Create, apply, and restore keys for job owners credentials using a
Blowfish algorithm.
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).
Performs basic management operations and deletes old alerts.
Interactive menu that provides access to a variety of functions and utilities that are used to maintain Control-M/Server.
Agent Configuration utility that is used to maintain Control-M/Agent configuration parameters, and to view and modify most of the operating system parameters.
Interactively configures Control-M/Agents.
Sends requests to all available Control-M/Agents, or to a specified
Control-M/Agent, to remove all OUTPUT files and status files that are no longer needed.
Checks the amount of free disk space on a device.
Generates SSH private and public key pairs.
Creates, modifies, and deletes keys with secure information such as passwords.
415
Control-M Utilities Guide
Utility Description
Creates and loads the Manual Conditions file.
Performs a selective cleanup of the Control-M log or produces a report of Control-M log entries.
Maintains Control-M/Server system parameters and Shout Destination tables.
Running the ctmunixcfg utility
Enables you to view and modify most of the configuration parameters in the OS.dat file.
Enables you to view and modify the Application Add-on for Windows configuration parameters.
Performs operations on quantitative resources in the Resources table.
Enables you to search for file transfers in Control-M based on search and filter parameters from a command line.
Restores high availability data to the Control-M/EM primary or secondary host
Manually cleans up audit information from the Control-M/EM database.
Performs manual cleanup of run information that is retained by
Control-M/Forecast and Control-M Batch Impact Manager for the purposes of performing its calculations.
Deletes exception alerts from the Exception Alerts table in the
Control-M/EM database.
Handles the necessary changes to permissions of several agent files and directories in order to allow it to run jobs with any owner in non-root mode or revert back to the original state.
Scans and collects system information about the environment.
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
-user
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 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
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 key
Restore default key
The new key replaces the existing Blowfish encryption key in the
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.
Replaces the existing Blowfish encryption key entry in the agkeystore.kdb 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
-agent
-key
-action
-input
-replace
Description
( Windows only ) Specify the name of the agent whose Blowfish encryption of job owners credentials are being modified.
Specify the type of encryption key. Enter the value BLOWFISH
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.
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 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
NOTE: When uninstalling Control-M/Agent version 9.0.00 fix pack 3, the utility enables you revert to
BlowFish.
-r
-b
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.
Enables a roll back and restore action.
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
-pf
-s
-t
-n
-h
Control-M/EM database user password
Flat file containing an unencrypted username and password on separate lines in the format: user= username password= password
The name of the Control-M Configuration Server. It is mandatory to specify this parameter.
The type of component. Valid values are:
Gateway
GUI_Server
GCS
BIM
Forecast_Server
Self_Service_Server
Web_Server
CTM_Server
CTM_Agent
The logical name of the component.
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
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>]
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
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 amount path_name
-quiet
Description
Specifies the minimum amount (%, K, or M) of free space on the device as a whole number (integer).
For example: -limit 25%
Specifies the full path name of the device. Multiple devices can be specified on the command line (see the second example below).
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 o o ctmkeygen -action delete -name <logicalKeyName> -passphrase
<keyPassphrase> ctmkeygen -action list ctmkeygen -action export -filename <exportFileName> o ctmkeygen -action import -filename <importFileName> -data append|truncate ctmkeygen help o
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 list
Deletes the entry associated with the logical key name. The passphrase must match the one that was used to create the existing key.
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
-format
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.
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
-filename
-data
Specifies the location where the public key file is created.
Specifies the public key name. The format of the file depends on what is specified for the –format parameter, described above.
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 passphrase type bits key1 myphrase dsa
512 format path ssh2
/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
REMEDY Keystore Menu parameters
The following table lists the REMEDY keystore Menu parameters"
Parameter Description user password
Specifies a user name. Specify an alphanumeric value from 1 through 127 characters long.
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
). To access the BLOWFISH keystore menu, see Running the BLOWFISH
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:
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 key
Re-encrypts all data with a default 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
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
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
-LOAD
List prerequisite conditions from the Manual Conditions file
Load prerequisite conditions from the Manual Conditions file to the
Conditions/Resources table
Create the Manual Conditions file -CALCCOND
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
INPUT
Description
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
OUTPUT
<Filename>
IGNOREIN
IGNOREOUT
IGNORECODES
<condition-mask>
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 file to be created. If this parameter is not specified, the default file is < controlmUserDir >/ctmldnrs.dat.
Full path name of the output file to be created.
All conditions that satisfy the specified condition name are ignored when the file is created.
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.
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.
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
-INCLUDE_FUTURE_
ODATES
Description
Specifies the action to be taken with jobs that are in Wait ODATE state
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 dat
>/ctm_server/data/dbs_ignrcond.
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>
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 list listord listjob
Prints a report for a specific subsystem.
Prints a report of all entries.
Prints a report of entries for a specific Order ID.
<subsystem> Subsystem to include in the report.
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
<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.
<Order ID>
Prints a report including all entries for a specific job number.
<Job no.>
Order ID to include in the report.
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").
Job number to include in the report.
446
Control-M Utilities Guide
Action listmsg delete listjobname
Action option
Prints a report of messages with a specific message ID.
<msgid> Message ID to include in the report.
Deletes entries in a specified date and time range.
None.
Prints a report including all entries for the specified job name.
<jobName> The name of the job whose entries should be printed in the report.
ctmlog utility parameters
This table lists the parameters of the ctmlog utility:
Parameter Description
<From Date>
<From Time>
<To Date>
<To Time>
"*"
Starting and ending dates and times for the range of entries to be scanned by the specified action. Date is specified in yyyymmdd format. Time is specified in hhmm format.
<Output>
Asterisk enclosed in quotation marks. Scan all entries in the Control-M log (without regard to date or time).
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
#
Destination Type
Addr
Logical Name
Physical Name
Entry number in the table.
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.
One-letter code indicating whether the destination is on the server
(S) or agent (A) computer.
Name used in the Shout or Do Shout parameter of the job processing definition to identify the recipient of the Shout message.
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
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
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
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:
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 o ecaqrtab {LIST|ADD|DELETE|UPDATE}{<orName>|"*"}[<Max>][-OUTPUT
<output>] 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.
457
Control-M Utilities Guide
ecaqrtab utility parameters
The following table describes the ecaqrtab utility parameters:
Parameter
LIST
ADD
DELETE
UPDATE
Description
Displays the status of the specified Quantitative resources. This information is also available from Control-M/EM in the Quantitative
Resources window.
Defines a new Quantitative resource and sets the maximum availability for the resource.
Deletes an existing Quantitative resource.
Changes the maximum availability of an existing Quantitative resource.
<QR_Name>
<Max>
<Output>
<fullPathFile
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).
Maximum availability for the specified resource. Can only be specified with the ADD and UPDATE options.
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.
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/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>]
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
Type
Max Avail
Reserved
Used
Free
Quantitative resource name (with @<Host ID> where applicable).
For future use.
Maximum number of units of this resource in the computer.
Number of units of the resource reserved for critical-path jobs.
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.
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
-m
-f
-fl
-ap
-b
-j
Control-M Utilities Guide
-u
-p
-pf
emmftcli parameters
The following table describes emmftcli parameters. For search with special characters (non alpha numeric) use quotes.
Parameter Description
-s
-o
Control-M/EM user name
Control-M/EM user password
Defines a flat file containing an unencrypted username and password on separate lines in the format: user= username password= password
The name of the Control-M Configuration Server. It is mandatory to specify this parameter. out_file <output file>Mandatory. output file in csv format. The utility overrides the data in the output file, if it already exists.
-h
-search
-t
-timeout <timeout>timeout in seconds, to wait for search response.
Shows usage.
Search for File Transfer records according to the specified filter options
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.
Filters by Filename
Filters by Folder
Filters by Application
Filters by Sub Application
Filters by Job Name
463
-l
-tf
-src
-dst
-srcp
-dstp
-d
Control-M Utilities Guide
Parameter
-st
Description
Filters by one of the following statuses:
1: IN_PROGRESS
2: COMPLETED
3: FAILED
4: COMPLETED_WITH_ERRORS
Filters by source host
Filters by destination host
Filters by source path
Filters by destination path
Determines the number of days back to search for file transfers sent or received. (1 is current day)
Determines the number of hours back to search for file transfers sent or received. from the current time (1 is current hour)
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
Secondary
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.
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
erase_audit_data utility parameters
The following table describes the erase_audit_data parameters:
Parameter
-date
Description
A date in YYYYMMDD format (for example, 20070915), which sets the selection criteria for obsolete jobs. Default: two days before the current date
-U
-P
Name of the Control-M/EM database.
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
-P
Defines the Control-M/EM database user name.
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
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
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 non root uninstall returns the agent to the state it was in after the installation and 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
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 to read the password file, the value of location. dbo_password must be the actual database owner password. For the Health Check utility
-file argument needs to point to the exact password file
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 passwordInfo
Description
For Categories and Profiles that access a Control-M database, you need to specify following:
<dbo_user> and <dbo_pwd> , which means the
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
Categories
(optional) Products and applications for which the utility can gather data.
(optional) Information type groupings, for example, operating system,
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
M_TYPE >_< HOSTNAME >.log
>_< HHMMSS >_< PLATFOR
-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 and Control-M
Application plug ins
AG: Control-M/Agent
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
(Windows)
Collects the content of the following:
%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 parameter, you must also specify one or more component parameters. If you specify the INST Category parameter, do not after the file copying phase of the installation. If you specify the INST Category
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
OS
DB
Definition
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
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
SCH
TBL
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
Component scheduling entities measurement. This information includes the following:
Number of daily jobs per Control-M
Number of daily executions per Control-M
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
CNF
LOG
COM
Definition
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
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
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
MSR
Definition
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 directory).
<CTM_HOME>
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
LOG
TBL
FNC
MSR
Definition
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
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)
Component function diagnostic data collection. This information includes the following:
Agent list
Dump of CTMLOG
Count of CMR_DBLOG records
Check database schema integrity
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
LOG
UTL
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
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
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
MSR
Definition
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
LOG
TBL
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
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
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
LOG
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.)
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
EM
MSR
Collects environment data. This includes information from the following
Categories:
OS
DB
Collects Control-M data. This includes information from the following
Categories:
COM
LOG
DBT
SCH
TBL
CNF
Collects measurement data. This includes information from the following
Categories:
MSR_ENV
MSR_GSR
MSR_GTW
MSR_DB
490
Control-M Utilities Guide
Profile
LOG_CGF
Definition
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
ALL
Definition
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
CTM
MSR
Collects environment data. This includes information from the following Categories:
OS
DB
Collects Control-M/Server data. This includes information from the following Categories:
CNF
LOG
TBL
FNC
MSR_CTM
Collects measurement data. This includes information from the following Categories:
MSR_CTM
492
Control-M Utilities Guide
Profile
LOG_CFG
ALL
Definition
Collects environment data and Control-M/Server configuration data. This includes information from the following Categories:
OS
DB
CNF
LOG
TBL
FNC
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
AG
MSR
LOG_CFG
ALL
Collects environment data. This includes information from the following Categories:
OS
Collects Control-M/Agent data. This includes information from the following Categories:
CNF
LOG
UTL
MSR_AG
Collects measurement data. This includes information from the following Categories:
MSR_AG
Collects environment data and Control-M/Agent configuration data. This includes information from the following Categories:
OS
CNF
LOG
UTL
Collects data through all Control-M/Agent Profiles, as follows:
OS
CNF
LOG
UTL
MSR_AG
494
9
Database maintenance
9
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
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
The db_check_space utility provides the following information for Control-M/EM databases that use Oracle database servers.
Facilitates day-to-day maintenance and diagnostics of
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
NOTE: You can run many of the utilities interactively, as
described in Interactive database utilities (on page 570 ).
The arc_database_menu utility can be invoked interactively to facilitate day-to-day maintenance and diagnostics of
Control-M Workload Archiving running with a PostgreSQL database.
The em_rebuild_database utility can be invoked to rebuild the Control-M/EM database in the specified PostgreSQL server database.
The em_SQL utility enables you to connect to the database from the command line.
The loader utility is used to load default data to the
Control-M/EM database.
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
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.
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>
-n
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.
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> ] ]
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
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
DBUColdRestore
Cold Database Backup
Cold Database Restore
DBUBuild Build Database option in the Database Creation Menu
Report Menu options (on page 505 )
DBUStatus
DBUShow
DBUStorage
DBUVersion
DBUTransactions
Database Status
Database Parameters
Database Storage Report
Database Version
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
Statistics
(DBUUpdateStatistics
)
PostgreSQ
L
MSSQL
Oracle
Activates statistic procedures in the database server.
Build Database
(DBUBuild)
Cold Database
Backup
PostgreSQ
L
MSSQL
Oracle
Creates a Control-M/EM schema on the database server.
PostgreSQ
L
MSSQL
Exports the Control-M/EM database schema to the specified file.
The following Control-M/EM components must be shut down prior to activating this backup:
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
Restore
Extend database
PostgreSQ
L
MSSQL
Oracle
MSSQL
Imports the Control-M/EM database schema from the file specified in Backup Fil parameter of the Cold Database Backup option.
NOTE: This option is not enabled if Control-M database server is running.
Restore File: Value and location specified in the Backup File parameter of the
Cold Database Backup option.
Administrator password: Password of the database server administrator.
(Oracle and MSSQL only) Extends the database size. Contact your DBA for assistance in performing this action if you are not comfortable performing it yourself.
504
Control-M Utilities Guide
Report Menu options
The following table lists the Report Menu options.
Option Database Description
Database Status
( DBUStatus
PostgreSQL
MSSQL
Oracle
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
Database Parameters
PostgreSQL
MSSQL
Oracle
Control-M/EM: Displays the configuration parameters of the server database and the Control-M/EM database client.
Control-M/Server: Displays the configuration parameters of the Server database and the Control-M/Server database client.
NOTE: Configuration parameters are sorted alphabetically.
505
Control-M Utilities Guide
Option
Database Version
( Running the DBUVersion utility (on page 577 ))
List All Active
Transactions
DBUTransactions utility (on page 582 ))
Consistency Check
Database Description
Database Storage Report
( DBUStorage
PostgreSQL
MSSQL
Oracle
Control-M/EM: Displays the attributes of the Control-M/EM database in the server database.
Control-M/Server: Displays the attributes of the Control-M/Server 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)
PostgreSQL
MSSQL
Oracle
Displays the general description of the database server, and includes the version number.
PostgreSQL
MSSQL
Oracle
MSSQL
Oracle
List all active transactions of the Control-M/EM or Control-M/Server database for the database user.
Checks tables in the database. Run this option when you suspect that there is database corruption.
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
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
DBUBuild
Stop database)
Build Database option in the Database Creation Menu
DBUArchive Set database archive mode
Workload Archiving Maintenance Menu options (on page 511 )
DBUMaintain
DBUColdBackup
DBUHotBackup
DBUHotRestore
DBUVersion
DBUTransactions
Update database statistics
Cold Database Backup
Hot Database Backup
Hot Database Restore
DBUColdRestore Cold Database Restore
Workload Archiving Report Menu options (on page 514 )
DBUStatus
DBUShow
DBUStorage
Database Status
Database Parameters
Database Storage Report
Database Version
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
Archive Mode
Only enabled when Control-M Workload Archiving is running
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
statistics
Activates statistic procedures in the database server.
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
Cold Database
Restore
Description
Imports the Control-M Workload Archiving database schema from 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
Database Parameters
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
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
Transactions
List all active transactions of the Control-M Workload
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]:
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
Name of the host computer for the PostgreSQL database server on which
Control-M/EM is installed.
Port Number Communications port on which the PostgreSQL database server listens for queries.
Database
Administrator
Password
Password of the PostgreSQL database server administrator. The characters you enter are not echoed for security reasons.
Database
Owner Login
Database
Owner
Password
Database
Name
Database
Directory Full
Path
Encoding
Existing
Database
Name of the Control-M/EM database owner.
Password for the Control-M/EM database owner (6 to 30 characters, alphanumeric). The characters you enter are not echoed for security reasons.
Name for the Control-M/EM database. This name must be unique within the PostgreSQL database server.
Location of the Control-M/EM database owner.
NOTE: You must create this location prior to installing the Control-M/EM database.
Relevant only for the PostgreSQL database server on UNIX.
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.
Valid values:
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:
Description Field
-d <directory>
-f < fileName >
-u <userName>
-p <password>
db
<databaseName>
append
erase
-diagon
The directory in which the files with the default data is located.
The full path of the file in which the loaded data is saved.
Database user name. Optional
Database user password. Optional
The name of the database to which you want to load the data.
Optional
Append the data to the information that already exists.
Erase the data that already exists.
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.
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 passwordFile
Flat file that contains an unencrypted user name and password on 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
YYYYMMDD date
-Timeout maxSeconds
-Test
-Sync
A date in YYYYMMDD format (for example, 20080915), which sets the selection criteria for obsolete jobs. Default: two days before the current date
Maximum time in seconds to wait for pending callbacks to return with responses to UPLOAD and remote DELETE requests. Default: 900 seconds
(15 minutes).
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.
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
-H | -Help
-Force
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.
Displays the usage.
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 milliseconds
This flag sets the time to wait between executing the DELETE and
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
t
$HOME/sweep Report of all jobs and folders that are candidates for deletion according to the date criteria.
sweep_sync.txt
sweep_log.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.
$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 s
weep_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
0
1
Description
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.
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
OR
OR
OR
AND
AND
OR
OR
• it has RBCs and is considered as obsolete according to the following table:
Relationship
Job (ACTIVE_TILL/
ACTIVE_FROM)
RBC (ACTIVE_TILL/
ACTIVE_FROM) Result
AND
AND
AND
AND
OR
Obsolete
Obsolete
Active
Active
Obsolete
Obsolete
Active
Obsolete
Active
Obsolete
Delete job
Delete job
Delete job
Job is active
Delete job
Obsolete
Active
Active
Not defined
Not defined
Not defined
Not defined
Active
Obsolete
Active
Obsolete
Active
Obsolete
Active
Job is active
Job is active
Job is active
Delete job
Job is active
Job is 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 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 )
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
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:
Description Field
-U <user>
-P <password>
-T <level>
Database user name
Database user password
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.
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
-import
-delete
Description
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.
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.
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
-defexport
-defimport
Description
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 .
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 r
Description
-silent
-replace
Suppresses application messages.
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
-type
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.
Name of the Control-M/EM database component that is configured by one or more of the following: all def cal sys
All application data. Default.
Job processing definition data.
Calendar data, including Rule-Based Calendar entities.
System data of the application. dc user alert gc maint collect view filter report
Data center definition data.
Control-M/EM database user data and authorizations.
Alert data for the Control-M/EM database.
Global conditions – prerequisite conditions that are passed between Control-M installations by Control-M/EM database.
Maintenance folders
Collection definitions
ViewPoint definitions
Filter definitions
Report definitions
534
Control-M Utilities Guide
Paramete r
Description hier Hierarchy definitions audit history
Audit data
History data bim_forecast BMC Batch Impact Manager folders and forecast folders statistics Exceptions data workload active_nets mft wcm
Workload Policy definition data
Active jobs for all Control-M/Servers
Manage File Transfer data in Control-M/EM
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:
-file 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
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 r
Description
-dir Exports or imports from a specified directory.
-name 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
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
\x1B
\x1C
\x1D
\x1E
\n
\t
\x0B
\f 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
New line (if it is the only character in records delimiter)
Horizontal tab
Vertical tab
Form feed
Escape
File separator
Group separator
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 )
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
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 <
[-primary/secondary]] [[-password < old (Site A) host name >] or dbo password >] or [-password_file [< file_path >]]]
Windows: restore_host_config [-silent] -dr [[-old_host <
[-primary/secondary]] [[-password < old (Site A) host name >] or 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 <
[-rename_remote_main_data]][-remove_profile] [-db_host <
[[-password < dbo password >] or [-password_file [< file_path old host name
>]]]
>] or main installation host name >]
Windows: restore_host_config -rehost [-silent] [[-old_host <
[-rename_remote_main_data]] [-remove_profile] [-db_host <
[[-password < dbo password >] or [-password_file [< file_path old host name
>]]]
>] or main installation host name >]
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 secondary installations.
> parameter must be used when running on distributed or
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 <
[[-password < dbo password >] or [-password_file [< file_path >]]] new interface name >]
• Windows: restore_host_config –interface_name [-silent] [-name <
[[-password < dbo password >] or [-password_file [< file_path >]]] new interface name >]
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 <
[-internal_only [-host_port] [-ctm_name] [-sync_files] [-clients]] [[-password < or [-password_file [<file_path>]]] new profile name >] dbo password >]
Windows: restore_host_config –profile_name [-silent] [-name <
[-internal_only [-host_port] [-ctm_name] [-sync_files] [-clients]] [[-password < or [-password_file [< file_path >]]] new profile name >] dbo password >]
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 <n ew db host na me>] [-port < new db port number >] [ -service <new db service na me>] [-dbname <n ew db schema name >]
[-pg_existing_se rver <y/n
[-password_file [<
>] [-owner <new db owner name>] [[-password < file_path >]]] dbo password >] or
Windows: restore_host_config -reconf_db [-silent] [-host <n ew db host na me>] [-port < new db port number >] [ -service <new db service name >] [-dbname < new db schema name >]
[-pg_existing_se rver <y/n
[-password_file [<
>] [-owner < file_path >]]] new db owner name >] [[-password < dbo password >] or
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_ho st <old host name >] [-new_ host
<new host nam e>] [[-password <dbo password >] or [-password_file [ <file_path >]]]
• Windows: restore_host_config -rehost_ctm [-silent] [-old_ho st <old host name >] [-new_ host
<new host nam e>] [[-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] [-
[[-password < switch_primary_to_secondary ] db o password> ] or [-password_file [< file_path >]]]
Windows: restore_host_config -remove_secondary [-silent] [-
[[-password < switch_primary_to_secondary ] db o 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
The ctm_backup_bcp utility exports data from a
Control-M/Server database to the
~<controlm_owner>/ctm_server/backup_db directory.
ctmcheckmirror (on page 548 ) The ctmcheckmirror utility checks the mirroring of the
Control-M/Server database and displays the status.
The ctm_restore_bcp utility imports the Control-M/Server database from the bcp_backup directory.
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.
The ctmdbcheck utility displays information about the memory capacity and the status of the Control-M/Server database.
The ctmdbopt utility calculates database statistics.
544
Control-M Utilities Guide
Utility Type
ctmdbspace (on page 559 ) ctmdbtrans (on page 559 )
Description
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.
The ctmdbspace utility checks the data and log usage in the Control-M/Server database and displays the usage.
The ctmdbtrans utility lists the active transactions in the database.
The ctmdbused utility displays the size (in MB), amount, and percentage of current space usage in the
Control-M/Server database data and log.
The ctmreindex utility accesses the Control-M/Server database, reads the data dictionary, reads the index definitions, and then reorganizes indexes. ( UNIX only )
The dbversion utility retrieves the database server version and tests the connectivity of the Control-M/Server database in use.
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
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
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.
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.
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.
on the ctmdbcheck utility, see ctmdbcheck utility parameters (on page 554
553
Control-M Utilities Guide
ctmdbcheck utility parameters
The following table describes the ctmdbcheck parameters:
Parameter
<dbThreshold%>
Description
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 db total data
Description
Total amount of memory (in KB) allocated for the database.
Total amount of memory (in KB) allocated to the Data partition of the database. log
Data used
Log used
Total amount of memory (in KB) allocated to the Log partition of the database.
Total memory currently used in the Data partition.
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
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.
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 ( up the Control-M/Server database.
<backupDevice> ). This device was used to back
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
) 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
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.
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:
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.
Option
Database
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.
DBUStart utility (on page 575 ))
NOTE: If this option is invoked on Control-M/Server running with an existing database, an message is displayed.
Stop Database PostgreSQL Only enabled when Control-M Server is running with a dedicated database server.
DBUStop utility (on page 576 ))
Stops the PostgreSQL database server, and services involved.
NOTE: If this option is invoked on Control-M/Server running with an existing database, an message is displayed.
Set Database
Archive Mode
(DBUArchive)
PostgreSQL
Build
Database
(DBUBuild)
Only enabled when Control-M/Server is running with a dedicated PostgreSQL database ser the archive mode of the PostgreSQL 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 Ba is enabled.
PostgreSQ
L
MSSQL
Oracle
Creates a Control-M/Server database.
NOTE: This option is only enabled on Control-M/Server running with either an existing or database server.
564
Control-M Utilities Guide
Option
Extend
Database
Database
Server
Oracle
MSSQL
Description
Extends the size of the existing user database datafile, or adds a new datafile, to provide e for schema objects.
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
(DBUUpdateStatistics)
Database Consistency Check
PostgreSQL Updates statistic procedures in the database server.
MSSQL
Oracle
PostgreS
QL
MSSQL
MSSQL: Performs allocation checks and verifies the structural and logi integrity of all objects in the database
Oracle: Detects bad blocks and checks table and index schema consistency.
Hot Database Backup
(DBUHotBackup)
PostgreSQL Only enabled when:
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
( DBUColdbackup
PostgreSQL
MSSQL
Exports the Control-M/Server database schema to the specified file whe
Control-M/Server is shut down.
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
Hot Database Restore
(DBUHotRestore)
Database
PostgreSQL
Description
Only enabled when Control-M/Server is active and running with a dedicated PostgreSQL database server.
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
( DBUColdRestore
MSSQL
Imports the Control-M/Server database schema from the file specified
Backup File parameter of the Cold Database Backup option.
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 )
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 <n
[-dbname <n ew db schema name>] [[-password < name >] [ dbo password ew db host na me>] [-port <
-service <new db service na
>] [-pg_existing_se rver <y/n new db port number >] me>] [-owner <new db owner
>]
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
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 )
Running the DBUTransactions utility (on page 582 )
Running the DBUShow utility (on page 584 )
570
Control-M Utilities Guide
0
1
Return codes
The return codes listed in the following table are issued by the interactive database utilities.
Return code Description
The action completed successfully.
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
-TRACE_LEVEL
Description
Trace level. Valid values: error, log, info. Default: error. Optional.
Use this option only when instructed to do so performance and use extra disk space.
by BMC
Customer Support. Using this option can slow
-HELP
-BACKUP_FILE
Displays the usage, then exits with success status.
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
The following example describes a utility DBUColdRestore sample output: restore completed
DBUColdRestore utility parameters
The following table describes the DBUColdRestore utility parameters:
Parameter
-TRACE_LEVEL
Description
Trace level. Valid values: error, log, info. Default: error. Optional.
NOTE: Use this option only when instructed to do so
BMC Customer Support. Using this option can slow performance and use extra disk space.
by
-HELP
-RESTORE_FILE
-ADMINISTRATOR_PASSWORD
Displays the usage, then exits with success status.
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.
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
-TRACE_LEVEL
Description
Trace level. Valid values: error, log, info. Default: error. Optional.
Use this option only when instructed to do so performance and use extra disk space.
by BMC
Customer Support. Using this option can slow
-HELP
-BACKUP_DIRECTORY
Displays the usage, then exits with success status.
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
-HELP
-POSTGRES_DEBUG
Trace level. Valid values: error, log, info. Default: error. Optional.
Use this option disk space. only when instructed to do so by BMC Customer
Support. Using this option can slow performance and use extra
Displays the usage, then exits with success status.
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
-HELP
-FORCE
Trace level. Valid values: error, log, info. Default: error.
Optional.
NOTE: Use this option use extra disk space. only when instructed to do so by BMC
Customer Support. Using this option can slow performance and
Displays the usage, then exits with success status.
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
-HELP
Trace level. Valid values: error, log, info. Default: error.
Optional.
NOTE: Use this option use extra disk space. only when instructed to do so by BMC
Customer Support. Using this option can slow performance and
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> ]
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 use extra disk space. only when instructed to do so by BMC
Customer Support. Using this option can slow performance and
Displays the usage, then exits with success status. -HELP
-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
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
-HELP
Trace level. Valid values: error, log, info. Default: error.
Optional.
Use this option disk space. only when instructed to do so by BMC Customer
Support. Using this option can slow performance and use extra
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 ]
DBUtransactions utility example (on page 583 ).
DBUtransactions utility parameters
This table describes the DBUtransactions utility parameters:
Parameter Description
-TRACE_LEVEL
-HELP
Trace level. Valid values: error, log, info. Default: error.
Optional.
Use this option disk space. only when instructed to do so by BMC Customer
Support. Using this option can slow performance and use extra
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
-TRACE_LEVEL
-HELP
Description
Trace level. Valid values: error, log, info. Default: error.
Optional.
Use this option disk space. only when instructed to do so by BMC Customer
Support. Using this option can slow performance and use extra
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
Security
10
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.
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
< string to encrypt >
< output file name >
Description
Defines the new password string to encrypt.
<user name>
(Trial Mode only) Full path name of the output file created by emcryptocli. The file contains the encrypted version of the password that was submitted.
(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
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
Certain functions of the ctmsec utility can be activated directly from a command line. For more
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
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 o o o ctmsetown -action update -run_as <user name> -host <host name>
[-password <password> | -keyname <key name > [-passphrase <key passphrase>]] ctmsetown -action delete -run_as <user name> -host <host name> ctmsetown -action list [-run_as <user name>] [-host <host name>] ctmsetown -action export -filename <export file name> o o ctmsetown -action import -filename <import file name> -data append|truncate 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>
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 add
Description
Specifies the security details of a new owner entry (user). update delete list export import help
Modifies the security details of an existing owner entry (user).
Removes the security details of an owner entry. The owner name and host name must match an existing entry in the folder.
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
Exports the security details of the existing users to a text file. ctmsetown -action export -filename
$HOME/ctm_server/data/user_report.txt
Imports the details of the users stored in the specified import file.
Displays the usage of the ctmsetown utility.
599
Control-M Utilities Guide
ctmsetown utility parameters
The following table describes the ctmsetown utility parameters:
Parameter
-run as
Description
(Owner) Specifies the name of the user under whose name the job will run.
-host Specifies the name of the computer where the owner of the job is defined.
Specify <All> to include all hosts. 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
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 action user
Description
Function to be executed.
Valid values: add, update, delete, and list.
Name of the user.
When adding users, the user name must not exceed 20 characters. old_password password admin_password verify sub_application agent
Current password for the update function.
Current password for the delete function.
New password for the add and update functions.
Password for the Control-M/Agent administrator when executing the update or delete function if the old_password is not known.
Verifies that the user and password. Valid values are:
Y (default)
N - Does not verify that the user and password are correct.
Adds the group SID (instead of the user SID) to cmd.exe and the agent directories.
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
Statistics and reporting
11
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.
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>]
on the bim_report utility, see bim_report utility parameters (on page 607
) and bim_report utility example
bim_report utility parameters
The following table describes the bim_report utility parameters:
Parameter
-U username
Description
-P password
-O output file name
Name of the Control-M/EM user running the report, for security purposes.
Mandatory.
Password of the Control-M/EM user running the report, for security purposes. Mandatory.
Name and full path of the output file that will contain the generated 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.
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
User
Description
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 type
The report output file.
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
Param
Template
Attribute Description file path Specifies the full filename of the output file.
Specifies the name and value for each parameter in the form name=value. Wildcard can be used for text fields.
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
Source File
Attribute Description
The template used to generate the report templateName Specifies the name of the template
Output File
Parameters
Parameter
TemplatePath Specifies the folder where the template file is located
(Optional)
The report output file. type filepath
Specifies the type of the output file, such as EXCEL,
EXCEL_DO (for data only), PDF, DOC, HTML, TXT, or XML
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.
The parameter list. name value
An individual parameter, whose name and value is specified. name of the parameter as defined in the report template filter panel. 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
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
<fromDate>
Description
<toDate>
<delta1>
Starting date of statistical data to be compiled. The date is specified in yyyymmdd or yymmdd format.
Ending date of statistical data to be compiled. The date is specified in yyyymmdd or yymmdd format.
Unsigned number used to establish the starting date for statistical data to be compiled. This date is determined by subtracting starting date is 991210).
<delta1> from
<date> (for example, if <delta1> is 10 and <date> is 991220, the
<delta2>
<date>
"*"
-list
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 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.
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:
JOBNAME
FILE_N
AME FILE_PATH HOST
CPU
[sec] pgmacct1 prod.acct.pgm diana
0.19
ELAPSED
(sec)
233.15
FOLDER connection profileq1 pgmacct2 prod.acct.pgm verdi
0.12 pgmacct3 prod.acct.pgm diana
0.05 pgmacct4 prod.acct.pgm diana
0.34
6.12
170.45
145.23 connection profiletq2 connection profiletq3 connection 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
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
-list
-delete
<From Date>
Description
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).
Deletes data from the Statistical Details table in the range specified in the From Date and To Date parameters.
Start date of statistical data to be displayed or deleted. Format: yyyymmddhhmmss
<To Date>
"*"
<Filter
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.
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
-total
-purge
Description
Displays the total CPU and elapsed times for the jobs selected.
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 information records of a job are kept, where
RUNINF_PURGE_LIMIT (default 20). n n run
is the value of
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
CPU ELAPSED
FILE_NAME FILE_PATH
------------- ---------- -------- ---- ------------ ----------
-------------- ----- -------
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 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
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>
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
-list
-delete
< From Date >
Description
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).
Deletes data from the Statistical Summary table in the range specified by the From Date and To Date parameters.
Starting date of statistical data to be displayed/deleted. The date is specified in yyyymmddhhmmss format.
< To Date >
" ∗ "
<Filter>
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.
Specify one of the following options and its associated subparameter or leave blank to display the statistics for all jobs in the range.
-total
-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
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
Upgrade
12
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>]
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 version old_dc new_dc the Control-M/Server port number (range: 1024 – 65533) 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. the source Control-M/Server (data center) name, as defined in the COMM folder 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 lib the upgraded folder name 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 dataCenter
(Control-M/Server)
DBO Name
Name jupiter asteroid
DBO Password
Data Center hostname star2 saturn
623
Control-M Utilities Guide
Parameter
Data Center port number
Name
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
Forecast
13
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
[YYYYMMDD|+n] [Filter] [-scenario <
[-service_info_file <
> [[-p < password file_name
>] | -pf < name
>] [/hide_times] password_file >] -s < server_name > -odate
>] [-run_time [Min|Avg|Max]] -job_info_file < file_name >
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
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
-u <user>
Description
Indicates the user name of the Control-M client. Required.
-p <password>
-pf
<password_file>
/? or /h
Indicates the password of the Control-M client.
Indicates the password file name used instead of password.
-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
+n
A specific working day in YYYYMMDD format.
Indicates type of run time that is used for the forecast.
Valid values are:
Number of days from current date.
-scenario <name> Indicates the name of the forecast scenario that is applied to the forecast.
-run_time
-job_info_file
<file_name>
Avg
Min
Max
Average (Default)
Minimum
Maximum
Indicates the file name where the job information output is saved. The output is in CSV format. Required.
-service_info_file
<file_name>
-hide_times
Indicates the file name where the service information output is saved.
The output is in CSV format.
The estimated job start and end time will not be printed in the job information output file.
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
<name>
Sub application 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
Batch Discovery
14
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
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
-u
-p
Description
Control-M/EM administrator name.
Control-M/EM administrator password.
-gsr
-cms
-empf
Name of Control-M/EM GUI Server.
Optional. Name of Control-M Configuration Manager. Optional. (Default:
CMS)
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
0
1
Description
Success
Failure
2
255
Operating system not supported
Failure
629
15
Unsupported utilities
15
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
Herunterladen
Öffentlicher Link aktualisiert
Der öffentliche Link zu Ihrem Chat wurde aktualisiert. Sie können Ihre Chat-Links nach der Registrierung hier einsehen und verwalten.
Öffentlicher Dokumentenlink
Werbung
