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 ControlM/EM database
-
Delete, clear, and build the ControlM/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:
[-D <database>][{-U <user> -P <password>} |-pf <fileName>]
[-S <server>][-T <level>] [-dbms <system>][-dbtimeout <sec>]
[-dbfile <path>]
For more information about DB_ARGS database arguments, see
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
- util Utility Functions
- util Utility Function Parameters
-
To configure the util utility to recognize different delimiters, see Configure the util Utility to Recognize Different Delimiters
The util utility is automatically installed on Windows computers with the Control-M/EM Gateway component.
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.
Begin
-
Do one of the following:
-
UNIX: Log in 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.
-
-
Type one of the following commands:
-
UNIX: em util DB_ARGS function <functionParameters>
-
Windows: util DB_ARGS function functionParameters
-
DB_ARGS Database Arguments Fields
The following table describes the DB_ARGS database arguments fields:
Field |
Description |
---|---|
-U <user> |
Defines the database user name |
-P <password> |
Defines the database user password |
-T <level> |
Defines the database debug level. Valid values: 1 - 9 |
util Utility Functions
The following table describes the util utility functions:
Function |
Description |
---|---|
-export |
Exports job processing definitions, such as calendars, Control-M data, etc from the Control-M/EM database to an ASCII text file. The data in the mentioned file is separated by field and record delimiters. For more information, see Configure the util Utility to Recognize Different Delimiters. 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]
|
-import |
Imports job processing definitions, such as calendars, Control-M data, etc, from an ASCII text file to the Control-M/EM database. The data in the mentioned file is separated by field and record delimiters. For more information, see 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]
|
-delete |
Deletes the specified database folder. Specify the following command: util <DB_ARGS> -delete [-silent] [-cdbg {1-5}]{-name {<name>}} Stop all Control‑M/EM components before doing this operation. |
-clean_database |
Deletes all database folders. Specify the following command: util <DB_ARGS> -clean_database [-silent] [-cdbg <1-5>] 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/EM database. It defines the structure and the type of contents of each data element in the database. Specify the following command: util <DB_ARGS> -build_schema [-cdbg <1-5>] Stop all Control‑M/EM components before doing this operation. To load default data to the Control-M/EM database, run the loader utility. |
util Utility Function Parameters
The following table describes the util utility function parameters:
Parameter |
Description |
---|---|
-silent |
Suppresses application messages. |
-replace |
Overwrites existing data in the specified folder. 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 |
Determines the debug level. Valid values: 1 - 9 Use this option only when instructed to do so by BMC Customer Support. Using this option can slow performance and use extra disk space. |
-type |
Defines the name of the Control-M/EM database component that is configured by one or more of the following: More than one -type can be used.
|
- type net |
Defines the type of Control-M/EM database net. -name: Name of the Control-M/EM database net that is identified by the following parameter: name: Name of the net. You can use wildcards when specifying a name:
SSIMU: simulation net SIMU A??????23\*: all active nets of netgroup 23 |
-file |
Specifies the details of the source or destination file.
|
util Utility Examples
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
Importing Calendar Data
The following procedure describes how to import calendar data from the ASCII data file month_cal to the default Control-M/EM database.
Begin
-
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
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 -export -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 -import \
-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.
namevalue * util_exp_records_delimiter \x0B\t\x1B
namevalue * util_exp_fields_delimiter \f
The following table shows the characters you can use for the records delimiter and fields delimiter, respectively.
Character Code |
Description |
---|---|
\n |
New line (if it is the only character in records delimiter) |
\t |
Horizontal tab |
\x0B |
Vertical tab |
\f |
Form feed |
\x1B |
Escape |
\x1C |
File separator |
\x1D |
Group separator |
\x1E |
Record separator |
\x1F |
Unit separator |
The records and fields delimiters must follow these rules:
-
a value between 1 and 5 characters.
-
The records delimiter must not be a substring of the fields delimiter, and vice versa.
-
\0 and blank characters are not valid values. They are not identified and may cause unexpected delimiters to be used.