Control-M API v8 PDF

Control-M Workload Automation
8.0.00
API Guide
November 2012
www.bmc.com
Contacting BMC Software
You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain
information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada
Address BMC SOFTWARE INC Telephone  713 918 8800 Fax 713 918 8000
2101 CITYWEST BLVD  800 841 2031
HOUSTON TX
77042-2827
USA
Outside United States and Canada
Telephone (01) 713 918 8800 Fax (01) 713 918 8000
© Copyright 2012 BMC Software, Inc.

BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are
registered with the U.S. Patent and Trademark Office, and may be registered or pending registration 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. IT Infrastructure Library® is a registered trademark of the Office of Government
Commerce and is used here by BMC Software, Inc., under license from and with the permission of OGC.
ITIL® is a registered trademark, and a registered community trademark of the Office of Government
Commerce, and is registered in the U.S. Patent and Trademark Office, and is used here by BMC Software,
Inc., under license from and with the permission of OGC.
Linux is the registered trademark of Linus Torvalds.
Oracle is a registered trademark of Oracle Corporation.
UNIX is the registered trademark of The Open Group in the US and other countries.
BMC Software considers information included in this documentation to be proprietary and confidential. Your
use of this information is subject to the terms and conditions of the applicable End User License Agreement
for the product and the proprietary and restricted rights notices included in this documentation.
Restricted rights legend
U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE
COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer
software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14,
DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended
from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX
77042-2827, USA. Any contract notices should be sent to this address.
Customer support
You can obtain technical support by using the BMC Software Customer Support website or by contacting
Customer Support by telephone or e-mail. To expedite your inquiry, see “Before contacting BMC.”
2
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:
 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
3
• Messages from the operating system, such as file system full
• Messages from related software
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.
For the provisions described in the BMC License Agreement and Order related to third party products or
technologies included in the BMC Product, see the "ThirdParty" subdirectory in the installation directory of
this product.
4
Contents
Introduction to Control-M/EM API .................................................................................... 8
Related sections .............................................................................................................................9
Conventions ................................................................................................................................. 10
Syntax statements ........................................................................................................................ 10
How Control-M/EM API works ....................................................................................................... 11
Control-M/EM API sessions............................................................................................................ 12
Control-M/EM API Installation ........................................................................................ 15

Compatibility ................................................................................................................................ 15
Installing Control-M/EM API .......................................................................................................... 16
Control-M/EM API primary subdirectories ....................................................................................... 17
Configuring Control-M/EM API ....................................................................................................... 17
Configuration files ........................................................................................................................ 19
Control-M/EM API Upgrade ........................................................................................... 21

Upgrading Control-M/EM API......................................................................................................... 21
Control-M/EM API environment...................................................................................... 25

Preparing your project environment............................................................................................... 25
Writing your project...................................................................................................................... 25
Sample class ................................................................................................................................ 26
Running your project .................................................................................................................... 27
Issuing requests and handling responses........................................................................ 29

Request types .............................................................................................................................. 29
Response types ............................................................................................................................ 30
Control-M/EM API programming methods ...................................................................................... 33
Class reference ............................................................................................................ 46

ComponentType class ................................................................................................................... 47
EMBasicXMLInvoker class.............................................................................................................. 47
EMXMLInvoker class ..................................................................................................................... 49
GASComponent class .................................................................................................................... 54
GSRComponent class .................................................................................................................... 55
InvokeException class ................................................................................................................... 56
5
User Registration .......................................................................................................................... 57
Check user token validity .............................................................................................................. 61
Client Keep Alive .......................................................................................................................... 64
Introduction to Control-M/EM API requests ..................................................................... 68

Considerations ............................................................................................................................. 69
SOAP Envelope for Control-M/EM requests and responses............................................................... 69
Request ....................................................................................................................................... 69
Response ..................................................................................................................................... 70
Fault Response ............................................................................................................................. 70
Error XML parameters ................................................................................................................... 70
User Unregistration....................................................................................................................... 71
Create folder definitions ................................................................................................................ 74
Add jobs to folder definitions......................................................................................................... 85
Add folder to folder definitions ...................................................................................................... 90
Delete job definitions .................................................................................................................... 96
Upload folder ............................................................................................................................. 105
Order......................................................................................................................................... 110
Job creation ............................................................................................................................... 124
Add condition ............................................................................................................................. 163
Delete condition ......................................................................................................................... 170
Job actions in active jobs database .............................................................................................. 178
Job tracking ............................................................................................................................... 197
Retrieve jobs in the active jobs database ..................................................................................... 210
Change alert status .................................................................................................................... 228
Retrieve BIM Services list ............................................................................................................ 232
Fault Response ........................................................................................................................... 239
Advanced features and optimization ............................................................................. 241

Modifying initialization properties................................................................................................. 241
Getting and setting Control-M/EM API properties .......................................................................... 243
Polling interval timeout configuration ........................................................................................... 245
Diagnostics and troubleshooting .................................................................................. 247

Control-M/EM API logging ........................................................................................................... 247
Environment configuration troubleshooting .................................................................................. 249
Application runtime and communication troubleshooting ............................................................... 252
6
Uninstalling Control-M/EM API ..................................................................................... 256
Request format examples............................................................................................ 257

Add Condition or Delete Condition request ................................................................................... 257
Job Creation request .................................................................................................................. 258
Order or Force request ............................................................................................................... 268
Error codes and exceptions ......................................................................................... 272

Severity ..................................................................................................................................... 273
Error code reference ................................................................................................................... 274
7
1
Chapter
1
Introduction to Control-M/EM API
Control-M/EM API is an open interface for external applications that enables you to use the capabilities of
Control-M/EM and Control-M Workload Automation.
Control-M/EM API enables users of your application to perform the following functions in the Control-M
Business Integrated Scheduling environment:
 log a user in or out of Control-M Workload Automation.
 create jobs and SMART Folder in the Control-M Active Jobs database
 order jobs
 order SMART Folders
 track job execution
 add or delete Conditions
 change Alert status
 check the validity of user tokens
 create Job and SMART Folder Definitions
 delete Job Definitions
 upload Folders to Control-M/Server
 retrieve jobs from Control-M Active Jobs Database
 perform job actions such as Hold, Release, Rerun, Confirm, Kill and Set to OK
8
Control-M Workload Automation API Guide
Related sections
The following related publications/on-line help supplement this section:
Category Document Description
Installation Control-M Workload Automation Describes the installation processes for

Installation implementing Control-M/EM API databases
and Control-M/EM API product on Microsoft
Windows and UNIX® platforms.
Core section/ Control-M for z/OS User Manual Describes all Control-M concepts, features,
documents facilities and operating instructions in
detail. It can be used as a learning guide as
well as a reference guide.
Control-M Workload Automation Describes administrator responsibilities,

Administration customization, maintenance, and security
of Control-M/EM, Control-M/Server and
Control-M/Agent.
Using Control-M Workload Automation Describes all Control-M/EM concepts,

features, facilities, and operating
instructions. It can be used as a learning
guide as well as a reference guide.
Control-M Workload Automation Describes the parameters used for creating

Parameters job processing definitions.
Control-M Workload Automation Utilities Describes the utilities used for creating and
managing objects in the job production
environment and maintaining various
aspects of Control-M Workload
Automation.
Notices Release notes, flashes, technical bulletins Describes up-to-date information such as:
 Updates to the installation instructions
 Last-minute product information
9
Conventions
This book uses the following special conventions:
 All syntax, operating system terms, and literal examples are presented in this typeface.
 Variable text in path names, system messages, or syntax is displayed in italic text:
testsys/instance/fileName
 The symbol => connects items in a menu sequence. For example, Actions > Create Test instructs
you to choose the Create Test command from the Actions menu.
Syntax statements
The following example shows a sample syntax statement:
COMMAND KEYWORD1 [KEYWORD2 | KEYWORD3] KEYWORD4={YES | NO} fileName...
The following table explains conventions for syntax statements and provides examples:
Item Example
Items in italic type represent variables that alias

you must replace with a name or value. If a
databaseDirectory
variable is represented by two or more words,
initial capitals distinguish the second and serverHostName
subsequent words.
Brackets indicate a group of optional items. [tableName, columnName, field]

Do not type the brackets when you enter the
[-full, -incremental, -level] (UNIX)
option. A comma means that you can choose
one or more of the listed options. You must
use a comma to separate the options if you
choose more than one option.
Braces indicate that at least one of the {DBDName | tableName}

enclosed items is required. Do not type the
UNLOAD device={disk | tape,
braces when you enter the item.
fileName | deviceName}
{-a | -c} (UNIX)
A vertical bar means that you can choose only {commit | cancel}
one of the listed items. In the example, you
{-commit | -cancel} (UNIX)
would choose either commit or cancel.
An ellipsis indicates that you can repeat the columnName . . .

previous item or items as many times as
necessary.
10
How Control-M/EM API works

Control-M/EM API is a set of Java classes that enable Java developers to send requests to Control-M/EM
server components from their own applications. Before sending requests, Control-M/EM API must be
initialized. Initializing the API starts the CORBA layer that forwards requests from the client side of the API to
Control-M/EM GUI Server and the Global Alerts Server.
Initialization
Before sending requests, Control-M/EM API must be initialized. Initializing the API starts the CORBA layer
that forwards requests from the client side of the API to the Control-M/EM GUI Server and the Global Alerts
Server.
Connecting to Control-M/EM
In this version of the API, a developer can interact with two Control-M/EM server components:
 GUI Server
 Global Alerts Server
The developer initializes an instance of either EMXMLInvoker or EMBasicXMLInvoker, and chooses with
which component to communicate. An unlimited number of requests can be sent using the invoke method of
the EMXMLInvoker or EMBasicXMLInvoker that was instantiated. For more information about the difference
between the EMXMLInvoker and EMBasicXMLInvoker methods, see Control-M/EM API programming
methods (on page 33).
Authentication and user tokens

Each Control-M/EM API request must contain a user token. This token is obtained using a register request,
containing Control-M/EM user name and password. Upon successful authentication a new session is created
for this user. This session is identified by the returned user token. When the session is finished, send an
unregister request to log off and release resources allocated for this user session.
NOTE: A program can use multiple user tokens and issue several requests at once (for example, for a
multi-threaded program). However, you should not issue another request with the same user token if the
previous request is still in session.
11
Control-M/EM API sessions

Control-M/EM API enables users of your application to submit requests to a Control-M installation. The
following figure shows the Control-M/EM API process flow.
To illustrate this concept, an example of a Control-M/EM API session is presented in the following example.
The actions of the program user are shown together with the corresponding actions that your program must
perform to use Control-M/EM API.
Session example
The user logs in to a program, submits a Job Creation request to Control-M/EM, and logs off.
 To submit a Job Creation request:
1. The user logs on to the host computer of the program that uses Control-M/EM API.
2. The user starts the program that uses Control-M/EM API.
3. The user logs in to Control-M/EM (sends a Registration request).
4. The user performs an action that results in a Job Creation request, for example, being sent to
Control-M/EM.
5. The user receives confirmation that the request was submitted.
6. The user performs additional actions that result in other requests being sent to Control-M/EM.
7. The user logs out of Control-M/EM (sends an unregistration request).
12
Control-M/EM API (EMXMLInvoker) use flow

In reality, more actions are being performed by both the program that the user is using and by Control-M/EM.
The user is not aware of these actions, which are described in the following table.
Step User actions API actions
1 Log in None
End user logs on to a remote computer
to use a program that uses the
Control-M/EM API.
2 User starts Client-Side Application Program start

End user starts the application. Required action:
 Initialize the API using the init method of the
EMBasicXMLInvoker class.
Invoke an instance of the EMBasicXMLInvoker class with
the details of the EM GUI server that would respond to the
EM/API requests.
3 User Logs in to Control-M/EM API (client side) sends Register request

End user must supply a username and Required actions:
password.
 Call the BuildPasswordString() function immediately
before sending every API "Register" request because a
different string is used for each request in some modes.
Submit a register request using the invoke method of the
EMBasicXMLInvoker instance created in step 2.
4 None Control-M/EM returns response

Required action:
 This response contains a unique user token, which should
be used in calls for this user. If the Registration request
was unsuccessful, the response contains a list of errors.
5 Submit request API (client side) translates request

Required action: Required action:
 User requests that a job be  API translates user action into a Job Creation request that
submitted to Control-M/EM. is sent to Control-M/EM using the invoke method of the
EMBasicXMLInvoker instance created in step 2.

Required actions:
Control-M/EM automatically sends either a fault or success
response.
13
Step User actions API actions
7 None API (client side) processes response

Required actions:
 The program parses the reponse
If response is an error, notify user
 If response is actual outcome of the request, notify user
of outcome
8 User makes additional requests Additional requests can be sent and handled using the same
EMBasicXMLInvoker instance obtained in step 2 and the user
token obtained in step 4.
9 User Logs off of Control-M/EM API (client side) sends Unregister request
Required actions:
 Submit Unregister request. Use the invoke method,
supplying the Unregister request string as a parameter.
The request includes the user token obtained in Step 4.

Required action:
 Control-M/EM sends a response indicating either a
successful or failed unregister request.
11 None Program stop

Required action:
 Stop the API using the done method.
14
2
Chapter
2
Control-M/EM API Installation
The Control-M/Enterprise Manager API is supplied as a compressed file. When decompressed, this file
creates a directory structure containing the Control-M/EM API files.
NOTE: To upgrade from previous versions of the Control-M/EM API, follow the instructions in Control-M/EM
API Upgrade (on page 21).
Compatibility
This section provides information about software compatibility for the Control-M/EM API.
Control-M/EM API is fully compatible with the following version of Control-M/EM:
 Control-M/EM version 8.0.00
 Control-M/EM version 7.0.00
Control-M/EM API is fully compatible with the following versions of Control-M:
 Control-M/Server for UNIX and Windows version 8.0.00
 Control-M/Server for UNIX and Windows version 7.0.00x
 Control-M for z/OS version 8.0.00
 Control-M for z/OS version 7.0.00x
 Control-M for z/OS version 6.3.0x
 Control-M/Server for Windows version 6.2.0x
 Control-M/Server for UNIX version 6.2.0x
 Control-M for OS/390 and z/OS version 6.2.0x
15
Installing Control-M/EM API

This procedure describes how to install Control-M/EM API on Windows. Control-M/EM API can be installed in
any location using TCP/IP to the selected Control-M/EM installation.
NOTE: Due to Java limitations, BMC Software recommends that you do not install the Control-M/EM API in
a directory with a path that contains spaces or other special characters. If you install Control-M/EM API on an
account where an earlier version of Control-M/EM API is installed, review Control-M/EM API Upgrade (on
page 21) before continuing.
Before you begin

Ensure the following:
 Control-M/EM is installed on your network.
 Java Developer's Kit (JDK) version 1.6.x or later or Java Runtime Environment (JRE) version 1.6.x or later
is installed on the computer hosting your project's working directory.
 The JAVA_HOME environment variable points to the JDK (or JRE) directory/library on the computer.
JAVA_HOME refers to the directory where the Java 2 Runtime Environment (JRE) was installed. The Java
2 SDK (also called the JDK) contains the JRE, but at a different level in the file hierarchy. For example,
If the Java 2 SDK or JRE was installed in /ctm_em/user1, JAVA_HOME would be /ctm_em/user1/jre1.6.x
[JRE] or /ctm_em/user1/jdk1.6.x/jre [SDK]
 To Install Control-M/EM API:

1. Windows: Unzip the emapi-800-nt.zip file from the cdPath\tools\emapi\ directory on the
Control-M/EM installation CD to any location.
The emapi-800 directory tree is created. All Control-M/EM API files are located under this directory. The
primary subdirectories are created under the emapi-800 directory. See: Control-M/EM API primary
subdirectories (on page 17).
2. UNIX: Do one of the following:
• Solaris, AIX, HP-UX or HP-UX Itanium: Use the following command to open and uncompress
the emapi-800-UNIX.TAR.Z compressed tar file in the cdPath/TOOLS/EMAPI_FILES/
directory on the Control-M/EM installation CD to any directory:
uncompress -c cdPath/TOOLS/EMAPI_FILES/emapi-800-UNIX.TAR.Z | tar xvf-
The emapi-700 directory tree is created. All Control-M/EM API files are located under this directory.
Primary subdirectories are created under the emapi-800 directory, which is described in
Control-M/EM API primary subdirectories (on page 17).
• RedHat or Suse: Use the following command to open and uncompress the
emapi-800-UNIX.TAR.gz compressed tar file in the cdPath/TOOLS/EMAPI_FILES/ directory
on the Control-M/EM installation CD to any directory:
gunzip -c cdPath/TOOLS/EMAPI_FILES/emapi-800-UNIX.TAR.gz | tar xvf -
The emapi-800 directory tree is created. All Control-M/EM API files are located under this directory.
The primary subdirectories are created under the emapi-800 directory, which is described in
Control-M/EM API primary subdirectories (on page 17).
16
Control-M/EM API primary subdirectories

The following table describes the Control-M/EM API primary subdirectories
Directory Description
emapi-800\etc Contains the jacorb.properties file required for JacORB runtime

(CORBA Java client library).
emapi-800\keystore Contains the emapi.keystore demo file required for JacORB

runtime when using SSL. For more information, see Control-M
Workload Automation SSL Management..
emapi-800\classes Contains the EMAPI libraries and third-party libraries that include
the following files:
 jacorb.jar
Java implementation of CORBA (refer to the JacORB
copyright/license in this guide).
 NamingViewer.jar
Java library used by the NamingViewer utility.
 emapi.jar
The API implementation files.
 log4j-1.2.8.jar
Files used by the API logging facility.
emapi-800\xmldata Contains the schema files that validate the XML formatted request
strings sent and received using the API.
emapi-800\examples Contains sample implementations of the API.
Configuring Control-M/EM API

This procedure describes how to configure Control-M/EM API.
The processes for configuring Control-M/EM API on computers running Microsoft Windows and on computers
running UNIX are identical, except for differences in the names of some of the files used as described in
Configuration files (on page 19).
 To configure Control-M/EM API:

1. Locate Control-M/EM components and obtain the following information:
• The CORBA Naming Service host name and port
• Host names of the Control-M/EM GUI Server and Global Alerts Server
2. Change the current directory to the Control-M/EM API client’s home directory, emapi-700.
17
3. Run the emapi-configure.bat file (UNIX: emapi-configure).

At the prompt, the following text is displayed:
This script configures the Control-M/EM API library
Execute 'emapi-configure -h' for more details.
Press any key to begin. [continue]:
4. Press any key.
• If Control-M/EM is not installed on this computer, go to step 5.
• If Control-M/EM is installed on the computer, the following prompt is displayed:
Control-M/Enterprise Manager configuration detected
------------------------------------------
Control-M/Enterprise Manager configuration detected. Do you want to use
the same configuration? [y/n]
• Press y to use the current CORBA configuration properties.
• Press n to supply new CORBA configuration information.
5. At the following prompt, enter the name of the CORBA Naming Service host computer and press Enter.
Naming Service hostname
--------------------------------------------
Enter the Naming Service hostname (press Enter for default) [TLVW2K122]:
6. At the following prompt, enter the port number that the CORBA Naming Service uses and press Enter.
Naming Service port
--------------------------------------------
Enter the Naming Service port (press Enter for default) [3075]:
7. At the following prompt, enter the name of the Control-M/EM GUI Server host computer and press
Enter.
Control-M/Enterprise Manager - GUI Server hostname
--------------------------------------------
Enter the GUI Server hostname (press Enter for default) [TLVW2K122]:
8. At the following prompt, enter the name of the Control-M/EM Global Alerts Server host computer and
press Enter.
Control-M/Enterprise Manager - Global Alerts Server hostname
--------------------------------------------
Enter the Global Alerts Server hostname (press Enter for default)
[TLVW2K122]:
Installation is complete.
You are now ready to prepare your project and its environment to use the Control-M/EM API. These issues
are discussed in Control-M/EM API environment (on page 25).
18
Configuration files
These differences, and the names of other files that are used during configuration, are described in the
following table.
Name Description
emapi-configure.bat Creates configuration files and enables the API to access other key
(Windows) components.
emapi-configure These components include:
(UNIX)
 CORBA Naming Service
 Control-M/EM GUI Server
emapi_env.bat Automatically adds API directory pathnames to the CLASSPATH

(Windows) environment variable.
emapi_env.sh The emapi-configure(.bat) file creates this file when it is run.
(UNIX, users working in
Korn Shell environment)
emapi_env.csh
(UNIX, users working in C
Shell and TC Shell
environments)
ctmemapi.properties Contains the locations of:

 Control-M/EM GUI Server
 XMLDATAPATH property
This file is created by the emapi-configure(.bat) file when it is run.
19
Name Description
emapi-admin.bat Starts an interactive utility for changing the hostnames of the

(Windows) Control-M/EM GUI Server and Global Alerts Server.
emapi-admin
(UNIX)
NamingViewer.vbs Starts a Java GUI utility that displays the Naming Service repository
(Windows) graphically. For more information, see Control-M Workload
Automation Administration.
NamingViewer
(UNIX)
changePass.bat Encrypts the keystore password for demo certificates. This utility is
(Windows) located in the emapi_root directory. For more information, see
Control-M Workload Automation SSL Management.
changePass
(UNIX)
20
3
Chapter
3
Control-M/EM API Upgrade
This section describes how to upgrade to Control-M/EM API version 8.0.00.
Upgrading Control-M/EM API

This procedure describes how to upgrade Control-M/EM API, which enables users of previous versions to
work in version 8.0.00.
Before you begin

Ensure you complete the following:
 Installing Control-M/EM API (on page 16)
 Configuring Control-M/EM API (on page 17)
 To upgrade the Control-M/EM API:

1. Set your environment using the provided emapi_env.bat (emapi_env.sh on UNIX) script.
If you do not use the provided script, ensure that the startup script and the CLASSPATH point to the new
classes.
2. Update your applications and XML requests.
For information on the required changes see Upgrade considerations (on page 21).
3. (optional) Remove the emapi-6xx directory from the previous version.
Upgrade considerations
The Control-M/EM upgrade procedure (described in Control-M Workload Automation Installation and
Control-M Workload Automation Upgrade ) does not upgrade Control-M/EM API. Install and configure
Control-M/EM API separately after upgrade.
Do not copy the Control-M/EM API version 8.0.00 files directly over the previous installation This may cause
unpredictable behavior.
From version 7.0.00 to version 8.0.00

Code developed for Control-M/EM API 7.0.00 is compatible with version 8.0.00 with the following exceptions:
 Control-M/EM 8.0.00 supports a nested hierarchy of folders. As a result, Control-M/EM API 8.0.00
introduces the following requests to support the nested folder structure:
• request_def_create_folder: Create folder definitions (on page 74)
• request_def_add_folder: Add folder to folder definitions (on page 90)
21
• request_def_add_jobs: Add jobs to folder definitions (on page 85)

 Control-M/EM version 8.0.00 introduces new terminology: "folder" and "SMART Folder," which replaces
the terms "table" and "SMART table." The new terminology is reflected in requests/responses that are
described in the XML schema for version 8.0.00 (EMAPI_800.xsd).
The following table lists the elements that have been renamed in version 7.0.00 to reflect the new
terminology:
version 7.0.00 version 8.0.00
table folder
table_info folder_info
table_rba folder_rba
into_table into_folder
table_id folder_id
is_table is_folder
The following requests/responses are affected by these changes:

 request_def_upload_folder/response_def_upload_folder
 request_order_force/response_order_force
 request_def_delete_jobs/response_def_delete_jobs
 request_create_aj
 response_act_retrieve_jobs
To use the new parameters, set the namespace declaration to xmlns:ctmem.
From version 6.4.01 to version 7.0.00

Code developed for Control-M/EM API 6.4.01 is compatible with version 7.0.00 with the following exceptions:
 Control-M/EM 7.0.00 supports a nested hierarchy of tables. As a result, Control-M/EM API 7.0.00
introduces the following requests to support the nested table structure:
• request_def_create_table
• request_def_add_table
• request_def_add_jobs
The above requests replace "request_def_create_jobs" and "request_def_create_sched_group" that
were provided by Control-M/EM API for versions 6.3.00 and 6.4.00. The XML schema for version 7.0.00
does not support "request_def_create_jobs" and "request_def_create_sched_group."
22
 Control-M/EM version 7.0.00 introduces new terminology: "table" and "SMART Table," which replaces
the terms "scheduling table" and "group scheduling table." The new terminology is reflected in
requests/responses that are described in the XML schema for version 7.0.00 (EMAPI_700.xsd).
The following table lists the elements that have been renamed in version 7.0.00 to reflect the new
terminology:
earlier versions version 7.0.00
sched_table table
scheduling_group_info table_info
group_rba table_rba
into_group into_table
group_id table_id
is_group is_table
The following requests/responses are affected by these changes:

 request_def_upload_table/response_def_upload_table
 request_order_force/response_order_force
 request_def_delete_jobs/response_def_delete_jobs
 request_create_aj
 response_act_retrieve_jobs
From version 6.3.0x to version 6.4.01

Code developed for Control-M/EM API version 6.3.0x is compatible with version 6.4.01 except for the
following:
 The encodePassword method of EMXMLInvoker and EMBasicXMLInvoker is not supported in
Control-M/EM API version 6.4.01. Replace all calls to the encodePassword method with calls to the
BuildPasswordString method. For more information see BuildPasswordString (on page 50).
 Control-M/EM API version 6.4.01 includes the following new parameters that were added to
Control-M/Server version 6.4.01.
• cyclic_type
• interval_sequence
• specific_times
• tolerance
• attach_sysout
23

You can use these parameters when submitting the following requests:
• request_create_aj
• request_def_create_jobs
• request_create_sched_group
For more information on the parameters and requests, see Introduction to Control-M/EM API requests (on
page 68) and Job and SMART Folder XML parameters (on page 302).
24
4
Chapter
4
Control-M/EM API environment
You must perform a number of steps in your project to prepare it to use Control-M/EM API.
Preparing your project environment

This procedure describes how to prepare your project environment.
Prior to using Control-M/EM API, you must configure the API for use in your project development
environment.When you want to release your application for use, you must configure the Control-M/EM API
running environment.
Your project is in the development environment when you are creating and testing the project on your
development computer.The running environment is the project environment when your application is
released for use.
 To prepare your project environment:

1. Set the environment variables for the environment by running the emapi_env.bat (or emapi_env.sh)
file.
For emapi_env.sh on UNIX, run the following command:
. emapi_env.sh
Running the command with the above syntax ensures that the variables are valid after the command is
run.
2. Copy the emapi-700\ctmemapi.properties file to your project’s working directory.
Writing your project

This procedure describes how to use Control-M/EM API to write your project. You can use the Sample class
(on page 26) as a basis for building your project.
 To write your project:

1. Import the Control-M/EM API into your project with the following command:
import com.bmc.ctmem.emapi.*;
2. Create a class that uses the Control-M/EM API functionality that you want to employ in your project.
The first thing this class must do is call the init method. This method is described in Initializing and
stopping the Control-M/EM API services (on page 42).
EXAMPLE: EMXMLInvoker.init();
3. Select the CONTROL-M/EM component with which the project will communicate (the CONTROL-M/EM
GUI Server or the Global Alerts Server).
25
EXAMPLE: GUI Server

ComponentType gsr_comp = new GSRComponent();
For more information, see Submitting a request using the EMXMLInvoker class (on page 42).
4. Create an EMXMLInvoker instance and submit a request.
EXAMPLE: EMXMLInvoker my_invoker = new EMXMLInvoker(gsr_comp);
try {
XMLResponse = my_invoker.invoke(XMLRequest);
}
catch(InvokeException i) {
}
For more information, see Submitting a request using the EMXMLInvoker class (on page 42).
The class is now ready. You can use it in your project.
5. Compile your project.
To run your project, you must pass it the relevant Java Virtual Machine variables.
For more information, see Running your project (on page 27).
Sample class
A sample class is displayed:
EXAMPLE: import com.bmc.ctmem.emapi.*;
public class EMAPISample {
public EMAPISample() {
}
/** run once before submitting requests */
public void do_init(String[] args) {
EMXMLInvoker.init(args);
}
/** run once before exiting the program */
public void do_terminate() {
EMXMLInvoker.done();
}
/** This submits the XMLRequest received as a parameter
* and returns the response */
public String submit_request(String XMLRequest) {
String XMLResponse="";
26
// Creates a component
ComponentType gsr_comp = new GSRComponent();
// Creates a new EMXMLInvoker instance
EMXMLInvoker my_invoker = new EMXMLInvoker(gsr_comp);
try {
// Submits the request given as a parameter
XMLResponse = my_invoker.invoke(XMLRequest);
}
catch(InvokeException i) {
// must handle InvokeException
}
return XMLResponse;
}
}
Running your project

This procedure describes how to run your project.
 To run your project:

1. Set the environment variables for Control-M/EM API by running the emapi_env.bat (or
emapi_env.sh) file.
For emapi_env.sh on UNIX, run the following command:
. emapi_env.sh
Running the command with the above syntax ensures that the variables are valid after the command is
run.
2. Ensure that the environment variables are set for the Java environment and that the path includes the
Java installation location.
If they are not set, run the following command:
Microsoft Windows:
set JAVA_HOME=java_installation_location
set PATH=java_installation_location;%PATH%
UNIX:
setenv JAVA_HOME java_installation_location
setenv PATH java_installation_location:$PATH
3. Copy the emapi-700\ctmemapi.properties file to your project working directory.
27
4. Run the java command from the project working directory, using the following CORBA parameters:
These parameters are needed by Control-M/EM API. Pass them to your project as the first and second
runtime parameters. The command must be entered as a single line. It is divided here to fit on the page.
For Microsoft Windows
java.exe -Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB
-Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton -classpath
%CLASSPATH% projectMainClass
For UNIX
java -Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB
-Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton -classpath
$CLASSPATH projectMainClass
projectMainClass is your project main class.
Optionally, you can pass these parameters using one of the alternative methods described in Java virtual
machine parameters (on page 250).
28
5
Chapter
5
Issuing requests and handling responses
The Control-M/EM API is a set of Java classes that manipulate an existing set of functions in the server side
of the API. These classes enable Java developers to send requests to Control-M/EM server components from
within the developers’ applications.
Request types
The Control-M/EM API supports two types of requests:
 Synchronous requests are processed by Control-M/EM. Responses are received directly from
Control-M/EM.
 Asynchronous requests are sent through Control-M/EM to Control-M/Server. These requests receive a
tracking ID as a response. By sending a polling request that includes this tracking ID, the user can
retrieve feedback about what action Control-M/EM takes, or a notice that the request is still being
processed.
Client programs using the EMBasicXMLInvoker do not require the polling process, as polling is done by
the class itself. For more information, see Control-M/EM API programming methods (on page 33).
The following table describes the synchronous and asynchronous requests:
Request type Request name
Synchronous  polling requests

 user registration request
 check user token validity
 user unregistration request
 keep alive request
 alert status modification request
 job tracking request
 create job and SMART folder definitions
 delete job definitions
 retrieve jobs in the active jobs database
 retrieve BIM Services list
29
Request type Request name
Asynchronous  Order or Force request

 add or delete condition request
 job creation request
 upload folder
 job actions in active jobs database
Response types
Every time a request is made, Control-M/EM replies by sending one or more response strings. You can parse
the contents of these response strings for use in your project. Control-M/EM API responses are wrapped by
the SOAP envelope.For more information, see SOAP Envelope for Control-M/EM requests and responses (on
page 69).
The responses are divided into the following categories:
 Successful responses (on page 30)
 Fault responses (on page 30)
Successful responses
Successful responses appear directly below the SOAP-ENV:Body node. They contain the information
requested or indicate success. Every request has a specific ctmem response.
For example, ctmem:response_unregister is the response for a ctmem:request_unregister request.
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
. . .SPECIFIED_REQUEST_RESPONSE . . .
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Fault responses
Fault responses report failed requests. The fault node is located below the SOAP detail node. The fault node
contains information about the errors that caused the operation to fail. Every request has a specific fault
response.
For example, ctmem:fault_unregister is the fault response for the ctmem:request_unregister request.
<SOAP-ENV:Envelope
30
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode> … </faultcode>
<faultstring>…. </faultstring>
<detail>
. . . FAULT_RESPONSE_OF_THE_REQUEST . . .
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
When the Control-M/EM API is running a request that applies to multiple jobs, the request might succeed on
some jobs and fail on others. In this case, the general status field returned in a successful response, receives
a value of PARTIAL_SUCCESS instead of OK. Each individual job status is either OK or ERROR. A
PARTIAL_SUCCESS can only occur when the Control-M/EM API runs the following requests:
 track job
 order or force job
Response types received when using EMBasicXMLInvoker

The following table shows the types of responses you receive when using the EMBasicXMLInvoker:
Response type Description
response_operationName This response is the final result of a successful

synchronous request.
EXAMPLE: response_unregister
The first field is status and the value is OK except for
response_track_jobs where it can also be
PARTIAL_SUCCESS.
fault_operationName For synchronous requests, this indicates a failure.

EXAMPLE: fault_unregister For asynchronous requests, this response indicates a
failure in sending the request to the Control-M/Server. For
example, if the user is not authorized, Control-M/Server is
unavailable or does not have the right status, or the
request has invalid values.
31
response_poll_operationName This response is a final successful, or partially successful,

response for an asynchronous request.
EXAMPLE:
response_poll_add_condition
response_poll_order_force where it can also be
PARTIAL_SUCCESS.
fault_poll_operationName This response is the result of an error on an asynchronous

request that was sent to the Control-M/Server. This
EXAMPLE:
response can be an error returned from the
fault_poll_add_condition Control-M/Server itself (for example, an order request for
a nonexistent table), or an error from the communication
layer between Control-M/EM and Control-M/Server (for
example, a request timeout or communication loss).
Response types received when using EMXMLInvoker

The following table shows the types of responses you receive when using the EMXMLInvoker:
response_operationName This response is the final result of a successful

synchronous request.
EXAMPLE: response_unregister
response_track_jobs where it can also be
PARTIAL_SUCCESS.
For asynchronous requests, the response contains the
token ID that should be used to poll Control-M/EM for the
final result of the request.
fault_operationName For synchronous requests, this response indicates a

failure.
EXAMPLE: fault_unregister
For asynchronous requests, this response indicates a
failure in sending the request to the Control-M/Server.
For example, if the user is not authorized,
Control-M/Server is unavailable or does not have the
right status, or the request has invalid values.
32
response_poll_operationName This response is received as an answer to a polling

request.
EXAMPLE:
The first field is status.
response_poll_add_condition
A value of EXEC indicates that the request is still being
processed by the Control-M/Server and the response has
not yet arrived.
A value of either OK or PARTIAL_SUCCESS indicates the
final response of an asynchronous request.
The value PARTIAL_SUCCESS can appear only in
response_poll_order_force.
fault_poll_operationName This is an error response received from a polling request.

EXAMPLE: This response can be an error returned from the
Control-M/Server itself (for example, an order request for
fault_poll_add_condition
a nonexistent table), or an error from the communication
layer between Control-M/EM and Control-M/Server (for
example, a request timeout or communication loss).
Control-M/EM API programming methods

The Control-M/EM API supports two methods for creating, sending, and handling requests:
 EMXMLInvoker: Enables Control-M/EM API to send and receive XML requests using Control-M/EM API.
The init, done, invoke, getProperties, and setProperties methods are used with this
class.
 EMBasicXMLInvoker: Eliminates the effort of polling by not returning the response until either the
final response is available from the server, or the API times out.
33
Deciding which method to use

The EMXMLInvoker and EMBasicXMLInvoker classes can be used together in the same project, and even in
the same session. However, you must decide which class is most suitable for your purposes. Because the
EMBasicXMLInvoker class inherits from the EMXMLInvoker class you need to initialize the Control-M/EM API
only once.
The two classes differ as follows:
 The EMXMLInvoker requires you to poll manually for responses (see When to use the EMXMLInvoker
class (on page 40)). The EMBasicXMLInvoker polls automatically for responses (see When to use the
EMBasicXMLInvoker class (on page 35)).
 The EMBasicXMLInvoker uses an XML schema to validate XML-formatted requests and responses, but
the EMXMLInvoker class does not (see XML string validation (on page 45)).
34
The following figure illustrates the structural differences between the two request methods:
35
When to use the EMBasicXMLInvoker class

The EMBasicXMLInvoker class eliminates the need for polling by not returning the response until either the
final response is available from the server, or the API times out. The advantage is that the user does not have
to process the responses or place additional requests.
However, using only the EMBasicXMLInvoker class has the following disadvantages:
 The API call might be blocked for several seconds, generally until the final response is available or the call
times out. The time out period is configurable.
 After receiving the response, the EMBasicXMLInvoker class performs additional processing to determine
its course of action.
 Because the EMBasicXMLInvoker class performs XML parsing, this class makes it more resource intensive
than the EMXMLInvoker class.
36
EMBasicXMLInvoker request session Example
Using EMBasicXMLInvoker class calls

The init and done methods for the EMBasicXMLInvoker class are used for starting and stopping the API.
These methods are identical to those of the EMXMLInvoker class. For more information, see Initializing and
stopping the Control-M/EM API services (on page 42).
The invoke method returns a string that contains a text response from Control-M/EM in XML format.
37
Submit a request using the EMBasicXMLInvoker class

Invoke is the method of EMBasicXMLInvoker used to send requests to Control-M/EM. The invoke method
accepts one parameter (in String type), written in XML format. This parameter contains the request.
Specifying a component to process the request
Before invoking an object with an instance of the EMBasicXMLInvoker, you must assign to it a reference to
the Control-M/EM component that will process the request. An instance of EMBasicXMLInvoker must hold
either GSRComponent or GASComponent.
Examples
ComponentType myComponent = new GSRComponent();
EMBasicXMLInvoker gsrInvoker = new EMBasicXMLInvoker(myComponent);
The GSRComponent class represents the Control-M/EM GUI Server component in your
network. The GASComponent class represents the Control-M/EM Global Alerts Server
component in your network.
The component that you specify when you invoke the object (GSRComponent or
GASComponent) must be appropriate to the task that you want to perform. Request types and
the components that process those requests are listed in the table in Examples (on page 43).
Identifying information for these components was recorded in the ctmemapi.properties file
when you configured the API. This file contains the host name for each component.
In networks in which more than one GUI Server or GAS is installed, only one of each component
is listed in the ctmemapi.properties file. The API works only with the components listed in the
file. You cannot modify the file to include more than one GUI Server or GAS.
Using the invoke method
Prototype
public String invoke(String xmlRequest) throws InvokeException
In this statement, xmlRequest is a string that is formatted according to the XML request
specification that is presented in this book.
A request in XML format (xmlRequest), specifying the action that the Control-M installation is
to perform, is required for each call.
Invoking an object with the EMBasicXMLInvoker

This procedure deccribes how to invoke an object with the EMBasicXMLInvoker.
 To invoke an object with the EMBasicXMLInvoker:

1. Create an instance of the EMBasicXMLInvoker containing a reference to a Control-M/EM server
component type. This specified server component type component processes the request that you create
in the next step.
EXAMPLE: GSRComponent gsrComponent = new GSRComponent();
EMBasicXMLInvoker gsrInvoker = new
EMBasicXMLInvoker(gsrComponent);
38
2. Send a request to the specified Control-M/EM server component.

EXAMPLE: String xmlRequest = "<?xml?>..."; // xml request
String xmlResponse;
try{
xmlResponse = gsrInvoker.invoke(xmlRequest);
}
catch(InvokeException ex){
// handle invoke failures
}
// handle xml response
The invoke method can throw an exception if an application fails to process the invoke call (for
example, if communication between Control-M/EM and Control-M fails). For more information, see
Application runtime and communication troubleshooting (on page 252).
When to use the EMXMLInvoker class

The EMXMLInvoker class sends XML-formatted requests to Control-M/EM and returns responses to the
program that issued the requests. This class does not process the response data.Certain requests (such as
the Job Creation request) take time for Control-M to process. As a result, they indicate only if the request has
been submitted successfully.
An application using the EMXMLInvoker class might have to make several requests to check whether the
expected response is available. To facilitate this, the application sends a poll request. To identify the original
request (for which the polling is being performed) the poll request includes a tracking ID, which is supplied
in a response from Control-M/EM immediately after certain requests are submitted. These requests are as
follows:
 an Order or Force Request
 an Add or Delete Condition Request
 a Job Creation Request
The program can submit this tracking ID in a poll request several times, until the required response is
available.
39
EMXMLInvoker request session

The following figure describes the polling process in detail.
40
EMXMLInvoker polling request steps

The following figure illustrates the polling process in detail.
The advantage of the polling process is that the API always replies immediately to the request. No extra time
or resources are spent processing the responses.
Using EMXMLInvoker class calls

The EMXMLInvoker uses Control-M/EM API to send and receive XML requests. The init, done,
invoke, getProperties, and setProperties methods are used with this class.
41
Initializing and stopping the Control-M/EM API services

Before using the Control-M/EM API in your project, you must initialize the API. You start and stop the
Control-M/EM API by initializing the CORBA services. It stops when the Control-M/EM API stops using the
CORBA services.
When your application finishes using the API, you can stop the API.
The Control-M/EM API uses services that need to be initialized and terminated only once. There is no need
to initialize and stop for every new user session or call.
Starting the API services
The API services are started by using the EMXMLInvoker static method, init. The prototype described in
this section uses a default CORBA configuration and should be used in most circumstances.
There are two additional init prototypes, which are described in detail in Modifying initialization properties
(on page 241).
Prototype
public static void init()
init is a method of the EMXMLInvoker.
The init method should be called at program startup. It does not need to be run before every request or
before every interactive session.
Stopping the API services
When you finish using the Control-M/EM API in your application, the API must be stopped. The API services
are stopped using the EMXMLInvoker static method, done.
There is only one done method prototype:
Prototype
public static void done()
Submitting a request using the EMXMLInvoker class

Invoke is a method of EMXMLInvoker used to send requests to Control-M/EM.
The invoke method sends a request to a Control-M/EM component that is specified during invocation.
The invoke method accepts one parameter (a String), written in XML format. This parameter contains the
request that the user submits to Control-M/EM.
The invoke method returns a String, containing a text response from Control-M/EM in XML format.
Specifying a component to process the request
Before invoking an object with an instance of the EMXMLInvoker, you must assign to it a reference to the
Control-M/EM component that processes the request. An instance of EMXMLInvoker must hold either
GSRComponent or GASComponent.
42
Examples
ComponentType myComponent = new GSRComponent();
EMXMLInvoker gsrInvoker = new EMXMLInvoker(myComponent);
• The GSRComponent class represents the Control-M/EM GUI Server component in your
network.
• The GASComponent class represents the Control-M/EM Global Alerts Server
component in your network.
The component you specify when you invoke the object (GSRComponent or GASComponent)
must be appropriate to the task that you want to perform.Request types and the components
that process those requests are listed in the following table.
GUI Server Global Alerts

(GSRCompon Server
Request type ent) (GASComponent)
Job Creation X
Order/Force X
Add/Delete Condition X
Alert Status Modification X
Polling X
User Registration X X
User Unregistration X X
Time-out Reset X X
Job Tracking X
Identifying information for these components was recorded in the ctmemapi.properties file
when you configured the API. This file contains the hostname for each component.
In networks in which more than one GUI Server or GAS is installed, only one of each component
is listed in the ctmemapi.properties file. The API works only with the components listed in the
file. You cannot modify the file to include more than one GUI Server or GAS.
Using the invoke method
Prototype
public String invoke(String xmlRequest) throws InvokeException
In this statement, xmlRequest is a string that is formatted according to the XML request
specification that is presented in this book.
43
A request in XML format (xmlRequest), specifying the action that the Control-M installation is
to perform, is required for each call. The various types of requests that you can make are
described in Introduction to Control-M/EM API requests (on page 68).
Invoking an object with the EMXMLInvoker

This procedure describes how to invoke an object with the EMXMLInvoker.
 To invoke an object with the EMXMLInvoker:

1. Create an instance of the EMXMLInvoker containing a reference to a Control-M/EM server component
type. This specified server component type component processes the request that you create in the next
step.
EXAMPLE: GSRComponent gsrComponent = new GSRComponent();
EMXMLInvoker gsrInvoker = new EMXMLInvoker(gsrComponent);
2. Send a request to the specified Control-M/EM server component.
EXAMPLE: String xmlRequest = "<?xml?>..."; // xml request
String xmlResponse;
try{
xmlResponse = gsrComponent.invoke(xmlRequest);
}
catch(InvokeException ex){
// handle invoke failures
}
// handle xml response
The invoke method can throw an exception if the application fails to process the invoke call (for example,
if communication between Control-M/EM and Control-M fails). For more information, see Application
runtime and communication troubleshooting (on page 252).
44
XML string validation

The EMBasicXMLInvoker uses an XML schema to validate XML-formatted request and response strings. The
location of this schema is determined by the com.bmc.ctmem.emapi.XMLDATAPATH property. If this
path is not available to the class at run time, the operation fails.
The XMLDATAPATH property is defined in the ctmemapi.properties file.
The EMXMLInvoker class does not examine the XML-formatted data that it sends or receives, and it does not
depend on the presence of the XML schema.
An EMXMLInvoker request session adds a series of polling request steps to the EMBasicXMLInvoker request
session that is displayed in the figure in When to use the EMBasicXMLInvoker class (on page 35).
The XML standard does not include support for the following characters. If these characters are used, they
are translated in the XML file as listed in the following table:
Character Meaning Translated to
< less than <
> greater than >
& ampersand &
" quotation marks "
‘ apostrophe '
ASCII 10 line feed

ASCII 13 carriage return
For information about using the EMXMLInvoker, see Using EMXMLInvoker class calls (on page 41).
For information about using the EMBasicXMLInvoker, see Using EMBasicXMLInvoker class calls (on page 37).
45
6
Chapter
6
Class reference
This section describes reference information about all public functions that you, can access when using
Control-M/EM API in your project. References to additional material are listed in the See Also section
included under each function heading.
The information in this chapter provides you with the necessary information to create requests in the form of
XML strings.
Control-M/EM API classes
Class Description
ComponentType An abstract base class representing a Control-M/EM component

supported for use with the Control-M/EM API. For more information,
see ComponentType class (on page 47).
EMBasicXMLInvoker The EMBasicXMLInvoker class is inherited from the EMXMLInvoker

class. For more information, see EMBasicXMLInvoker class (on page
47) .
EMXMLInvoker The primary class of the API. For more information, see
EMXMLInvoker class (on page 49).
GASComponent The GASComponent class represents the Global Alerts Server (GAS).
For more information, see GASComponent class (on page 54).
GSRComponent The GSRComponent class represents the Control-M/EM GUI Server.

For more information, see GSRComponent class (on page 55).
InvokeException This class is used to process error feedback from Control-M/EM. For
more information, seeInvokeException class (on page 56).
46
ComponentType class
An abstract base class representing a Control-M/EM component supported for use with the Control-M/EM
API.
The Global Alerts Server (GAS) and the GUI Server are supported for use with the Control-M/EM API.
When you send a request (for example, to change the status of an Alert) the Control-M/EM component to
which this request is referred is not indicated in the request. Instead, the request is referred by the
ComponentType instance to the appropriate component.
The GSRComponent class and the GASComponent class are derived from the ComponentType class. These
classes are used when creating an instance of the EMXMLInvoker or the EMBasicXMLInvoker.
For more information, see GASComponent class (on page 54) and GSRComponent class (on page 55).
EMBasicXMLInvoker class
The EMBasicXMLInvoker class is inherited from the EMXMLInvoker class. It shares many of the methods of
that class.
The EMBasicXMLInvoker class uses the methods listed in the following table:
Method Description
BuildPasswordString (on page An EMXMLInvoker method that encodes a given text string for use in a
50) Registration request.
done (on page 51) An EMXMLInvoker static method that stops the Control-M/EM API services by
breaking the connection with the CORBA processes.
The done implementation is the same as it is under EMXMLInvoker.
encodePassword Use the BuildPasswordString method instead of the encodePassword

method to encode a given text string for use in a Registration request. The
encodePassword method is no longer supported in Control-M/EM API version
6.4.01. For more information, see BuildPasswordString (on page 50).
getProperties (on page 51) An EMXMLInvoker static method used to obtain the Control-M/EM Global Alerts
Server or GUI Server host names from the ctmem.properties file.
47
Method Description
Init (on page 51) An EMXMLInvoker static method that starts the Control-M/EM API services
and initializes CORBA with default values or with values specified with its
optional parameters.
The init implementation is the same as EMXMLInvoker.
Invoke (on page 53) Used to send a request to Control-M/EM. the request is sent as an XML text
string. When the invoke method is used with the EMBasicXMLInvoker class,
polling for responses from Control-M/EM is automatic.
setPollRequestIntervalMilli Determines the interval, in milliseconds, between automatic poll requests.

(on page 49)
setPollRequestTimeoutMilli Determines the total time, in milliseconds, allotted for polling following a
(on page 49) request.
setProperties (on page 53) An EMXMLInvoker static method used to specify the Control-M/EM Global Alerts
Server or GUI Server host names and a location from which to obtain them.
invoke
Enables you to send a request to Control-M/EM. The request is sent as an XML text string. When the invoke
method is used with the EMBasicXMLInvoker class, polling for responses from Control-M/EM is automatic.
 Syntax: Public String invoke(String xmlRequest) throws InvokeException
 Parameters: The xmlRequest string is a request that the user sends to Control-M/EM. The string is a
text file in an XML format that the Control-M/EM API can accept and interpret.
 Return Codes: Response in XML format. Response data that addresses the request that was sent. It is
returned as an XML formatted string.
 See setProperties (on page 53) and Getting and setting Control-M/EM API properties (on page 243)
48
setPollRequestIntervalMilli
Sets the interval between automatically-sent poll requests. This time is measured from the end of the
current poll request. This value must be less than or equal to the value specified with the
setPollRequestTimeoutMilli method.
 Syntax: Public void setPollRequestIntervalMilli (final long timeout)
 Parameters: timeout. Time, in milliseconds.
 Return codes: None
 See: Polling interval timeout configuration (on page 245) and setPollRequestTimeoutMilli below.
setPollRequestTimeoutMilli
Total time that is allotted for polling. This value must be greater than or equal to the value specified with the
setPollRequestIntervalMilli method.
 Public void setPollRequestTimeoutMilli(final long timeout)
 Parameters: timeout. Time, in milliseconds
 Return Codes:None
 See: Polling interval timeout configuration (on page 245) and setPollRequestIntervalMilli above.
EMXMLInvoker class
The EMXMLInvoker class is the primary class of the API. It methods are used to initiate and stop the API, get
and set API properties, and send requests to Control-M/EM.
The EMXMLInvoker class uses the methods listed in the following table:
Method Description
BuildPasswordString An EMXMLInvoker method that encodes a given text string for use in a Registration
(on page 50) request.
done (on page 51) An EMXMLInvoker static method that stops the Control-M/EM API services by
breaking the connection with the CORBA processes.
49
Method Description
encodePassword Use the BuildPasswordString method instead of the encodePassword method to

encode a given text string for use in a Registration request. The encodePassword
method is no longer supported in Control-M/EM API version 6.4.01. For more
information, see BuildPasswordString (on page 50).
getProperties (on An EMXMLInvoker static method used to obtain the Control-M/EM Global Alerts
page 51) Server or GUI Server host names from the ctmem.properties file.
Init (on page 51) An EMXMLInvoker static method that starts the Control-M/EM API services and
initializes CORBA with default values or with values specified with its optional
parameters.
Invoke (on page 53) Used to send a request to Control-M/EM. the request is sent as an XML text string.
When the invoke method is used with the EMXMLInvoker class, the user must
activate polling to receive a response from Control-M/EM.
setProperties (on page An EMXMLInvoker static method used to specify the Control-M/EM Global Alerts
53) Server or GUI Server host names and a location from which to obtain them.
BuildPasswordString
This EMXMLInvoker method prepares a text string for use as a user password in the User Registration
request.
The BuildPasswordString() function must be called immediately before sending every API Register
request because a different string is used for each request in some modes.
 Syntax: Public String BuildPasswordString(password_string) throws
InvokeException
 Parameters: password_string. Text string, subject to all limitations that apply to a Control-M/EM
password
 Return codes: The prepared string to be used in the password field of the registration request.
 See: User Registration (on page 57) and for information about acceptable passwords, see Control-M
Workload Automation Administration.
50
done
An EMXMLInvoker static method that stops the Control-M/EM API services by breaking the connection with
the CORBA processes.
 Syntax: Public static void done()
 Parameters: None
 See: Initializing and stopping the Control-M/EM API services (on page 42) and Init (on page 51)
getProperties
Used to obtain the Control-M/EM Global Alerts Server or GUI Server host names from the
ctmem.properties file
 Syntax: Public Properties getProperties();
 Parameters: The following table describes the parameters for getproperties:
Parameters:Parameter Description
host_of_the_GUI_Server Host name of the Control-M/EM GUI Server.

Default: com.bmc.ctmem.emapi.GSR.hostname
host_of_the_Alerts_Server Host name of the Global Alerts Server.

Default: com.bmc.ctmem.emapi.GAS.hostname
path_to_XML_data_files Location of the XML schema.

Default: com.bmc.ctmem.emapi.XMLDATAPATH
Init
An EMXMLInvoker static method that starts the Control-M/EM API services and initializes CORBA with
default values or with values specified with its optional parameters. There are three prototypes.
The init method must be run at program startup.
51
Prototype 1
This is the default implementation of init.
 Syntax: Public static void init()

 See: done (on page 51) and Initializing and stopping the Control-M/EM API services (on page 42)
Prototype 2
This init prototype enables you to include an array of strings representing a list of arguments.
 Syntax: Public static void init(String[] args)
 Parameters: For a list of CORBA parameters suitable for use in args, see the manufacturer’s
documentation.
 See: done (on page 51), Initializing and stopping the Control-M/EM API services (on page 42), and
Modifying initialization properties (on page 241)
Prototype 3
 Syntax: Public static void init(String[] args, Properties props)
 Parameters: For a list of CORBA parameters suitable for use in args, see the manufacturer’s
documentation. The props parameter (Properties) can contain CORBA parameters, using the same
options as in the command line that was passed as the first parameter (args).
The Properties class is part of the java.util package.
 Return codes:
 See: done (on page 51), Initializing and stopping the Control-M/EM API services (on page 42), and
Modifying initialization properties (on page 241)
52
Invoke
Invoke enables you to send a request to Control-M/EM. The request is sent as an XML text string. When the
invoke method is used with the EMXMLInvoker class, you must activate polling to receive a response from
Control-M/EM.
 Syntax: public String invoke(String xmlRequest) throws InvokeException
 Parameters: Xml request string. This string is a request that the user sends to Control-M/EM. The string
is a text file in an XML format that the Control-M/EM API can accept and interpret.
 Return codes: Response in XML format. Response data that addresses the request that was sent. It is
returned as an XML formatted string.
 See: Invoke (on page 48) and Introduction to Control-M/EM API requests (on page 68)
setProperties
Used to specify the Control-M/EM Global Alerts Server or GUI Server host names and the source from which
to obtain them.
 Syntax: Public void setProperties(Properties props);
 Parameters: The following table describes the parameters for SetProperties:
Parameter Description
host_of_the_GUI_Server Set to the hostname of the Control-M/EM GUI Server.

Default: com.bmc.ctmem.emapi.GSR.hostname
host_of_the_Alerts_Server Set to the hostname of the Global Alerts Server.

Default: com.bmc.ctmem.emapi.GAS.hostname
path_to_XML_data_files Location of the XML schema.

Default: com.bmc.ctmem.emapi.XMLDATAPATH

 See: getProperties (on page 51), and Getting and setting Control-M/EM API properties (on page 243)
53
GASComponent class
Represents the Global Alerts Server (GAS). When creating an instance of EMXMLInvoker (or
EMBasicXMLInvoker) with a reference to a GASComponent type, the request is sent to the specified
Control-M/EM Global Alerts Server.
The GASComponent class uses the constructors listed in the following table:
Constructor Description
GASComponent Using this constructor, the request is sent to the Global Alerts Server
(Prototype 1) (on hostname specified in the ctmemapi.properties file.
page 54)
For more information, see GASComponent (Prototype 1) (on page 54).
GASComponent Using this constructor, the request is sent to the Global Alerts Server
(Prototype 2) (on hostname specified with the hostname parameter.
page 54)
For more information, see GASComponent (Prototype 2) (on page 54).
GASComponent (Prototype 1)
Using this constructor, the request is sent to the Global Alerts Server hostname specified under
com.bmc.ctmem.emapi.GAS.hostname=host_name in the ctmemapi.properties file.
 Syntax: GASComponent();
 See: ComponentType class (on page 47), GASComponent (Prototype 2) (on page 54), and
GSRComponent class (on page 55)
GASComponent (Prototype 2)
Using this constructor, the request is sent to the Global Alerts Server hostname specified with the hostname
parameter.
 Syntax: GASComponent(String hostname);
 Parameters: Hostname. This is the Global Alerts Server hostname.

 See: ComponentType class (on page 47), GASComponent (Prototype 1) (on page 54), and
GSRComponent class (on page 55)
54
GSRComponent class
Represents the GUI Server. When creating an instance of EMXMLInvoker (or EMBasicXMLInvoker) with
a reference to a GSRComponent type, the request is sent to the specified Control-M/EM GUI Server.
The GASComponent class uses the constructors listed in the following table:
Constructor Description
GSRComponent Using this constructor, the request is sent to the GUI Server hostname
(Prototype 1) (on specified in the ctmemapi.properties file.
page 55)
GSRComponent Using this constructor, the request is sent to the GUI Server hostname
(Prototype 2) (on specified with the hostname parameter.
page 55)
GSRComponent (Prototype 1)
Using this constructor, the request is sent to the GUI Server hostname specified under
com.bmc.ctmem.emapi.GSR.hostname=host_name in the ctmemapi.properties file.
 Syntax: GSRComponent();
 See: ComponentType class (on page 47), GASComponent class (on page 54), and GSRComponent
(Prototype 2) (on page 55)
GSRComponent (Prototype 2)
Using this constructor, the request is sent to the GUI Server hostname specified with the hostname
parameter.
 Syntax: GSRComponent(String hostname);
 Parameters: Hostname. This is the GUI Server hostname.
 See: ComponentType class (on page 47), GSRComponent (Prototype 1) (on page 55), and
GASComponent class (on page 54)
55
InvokeException class
The InvokeException class enables the Control-M/EM API user to obtain error information when an
exception is thrown.
The InvokeException class includes the methods listed in the following table:
Method Description
getMajorCode (on Used to obtain the Major Code that identifies the error family to which an
page 56) error belongs.
getMinorCode (on Used to obtain the Minor Code of an error. The Minor Code provides a
page 56) unique identifier for the error in the family to which it belongs.
getReason (on Used to obtain the text description of an error.

page 57)
getMajorCode
Used to obtain the Major Code that identifies the error family for an error.
 Syntax: Public int getMajorCode()
 Return codes: int. An integer that identifies the error family to which the error belongs.
 See: getMinorCode (on page 56), getReason (on page 57), and Error codes and exceptions (on page
272)
getMinorCode
Enables you to obtain the Minor Code of an error. The Minor Code provides a unique identifier for the error
in the family to which it belongs.
 Syntax: Public int getMinorCode()
 Return codes: int. An integer that provides a unique identifier for the error in its family.
 See: getMajorCode (on page 56), getReason (on page 57), and Error codes and exceptions (on page
272)
56
getReason
Used to obtain the text description of an error.
 Syntax: Public String getReason()
 Return codes: String. This string is a text description of the error.
 See: getMajorCode (on page 56), getMinorCode (on page 56), and Error codes and exceptions (on page
272)
User Registration
Sends the username and password of the user to the target server component. The server component
returns a unique token, which must accompany all subsequent requests made during the session.
Request parameters
The following figure describes the request_register XML parameters:
57
The following table describes the request_register XML parameters:
component This parameter is used only by Control-M Business Process Integration. For more
information, refer to the relevant product documentation.
user_name Control-M/EM username of the person making the request. String.
password Control-M/EM user password of the person making the request.

This password must be sent as an encrypted string. Therefore, you must use the
BuildPasswordString method to encrypt the password prior to making the User
Registration request. For more information see, BuildPasswordString (on page 50).
timeout Indicates a length of time, in seconds, until the user’s current user token is
automatically invalidated. Integer. Default: 720. Optional.
You should synchronize the value of this parameter with that of the
EM_REFRESH_INTERVAL environment variable in Control-M/Enterprise Manager.
For more information, refer to Preparing your project environment (on page 25).
Use the Timeout Reset Request to restart the count from 0.
Fault response
XML parameters for fault_register, as well as a sample fault response are described in Fault Response (on
page 70).
Response parameters
The following figure describes the response_register XML parameters:
58
The following table describes the response_register XML parameters:
status Description of message content (for example, Error). String.
user_token Unique ID that identifies the user. String.
authentication_message Free text message containing authentication information. String
Errors
See Authorization request errors (Major code 407) (on page 285).
Examples
Successful example
Request
<?xml version="1.0" encoding="ISO-8859-1"?>
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_register
xmlns:ctmem="http://www.bmc.com/ctmem/schema700">
<ctmem:user_name>emuser</ctmem:user_name>
<ctmem:password>empass</ctmem:password>
<ctmem:timeout>40</ctmem:timeout>
</ctmem:request_register>
</SOAP-ENV:Body>
Response
<?xml version="1.0" encoding="iso-8859-1"?>
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
59
<ctmem:response_register
<ctmem:status>OK</ctmem:status>
<ctmem:user_token>12345630</ctmem:user_token>
<ctmem:authentication_message/>
</ctmem:response_register>
</SOAP-ENV:Body>
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_register
<ctmem:user_name>emuser</ctmem:user_name>
<ctmem:password>failed</ctmem:password>
<ctmem:timeout>40</ctmem:timeout>
</ctmem:request_register>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>Error response from EM
Server.</faultstring>
<detail>
<ctmem:fault_register
60
<ctmem:error_list
ctmem:highest_severity="Error">
<ctmem:error ctmem:major="407"
ctmem:minor="3" ctmem:severity="Error">
<ctmem:error_message>Register
failed.</ctmem:error_message>
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_register>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Check user token validity

Checks if the specified user identification is still valid.
Request parameters
The following figure describes the request_check_user_token XML parameters:
The following table describes the request_check_user_token XML parameters:
user_token Serial identification number supplied to the user during registration. String.
61
Response parameters
The following figure describes the response_check_user_token XML parameters:
The following table describes the table response_check_user_token XML parameters:
status Description of status token validity. String.

Valid values:
 VALID
 INVALID
will_expire Amount of time, in seconds, remaining until the expiration of the user identification
token. If the status is INVALID this parameter is set to zero.
Fault response parameters

XML parameters for fault_check_user_token, as well as a sample fault response are described in Fault
Response (on page 70).
Errors
Examples
Successful example
Response
<SOAP-ENV:Envelope
62
<SOAP-ENV:Body>
<ctmem:response_check_user_token
<ctmem:will_expire>587</ctmem:will_expire>
</ctmem:response_check_user_token>
</SOAP-ENV:Body>
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_check_user_token
</ctmem:request_check_user_token>
</SOAP-ENV:Body>
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_check_user_token
</ctmem:request_check_user_token>
</SOAP-ENV:Body>
63
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultstring>Error response from EM Server.</faultstring>
<detail>
<ctmem:fault_check_user_token
<ctmem:error_list ctmem:highest_severity="Error">
<ctmem:error ctmem:major="407" ctmem:minor="1"
ctmem:severity="Error">
<ctmem:error_message>Invalid user
token.</ctmem:error_message>
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_check_user_token>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Client Keep Alive

When a Control-M/EM API user registers with Control-M/EM, the user receives a user token that is in effect
for a limited period of time.
The Timeout Reset request resets the registration timeout counter to zero. Timeout Reset requests can be
sent intermittently to keep a user’s registration valid during lengthy sessions.
64
Request parameters
The following figure describes the request_client_keep_alive XML parameters:
The following table describes the request_client_keep_alive XML parameters:
user_token Serial identification number supplied to the user during registration. The user
indicated by this number is the user. String.
Response parameters
The following table describes the response_client_keep_alive XML parameters:
status Describes the condition of the element that contains it.(for example, Error). String.

XML parameters for fault_client_keep_alive, as well as a sample fault response are described in Fault
Errors
65
Examples
Successful example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_client_keep_alive
</ctmem:request_client_keep_alive>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_client_keep_alive
</ctmem:response_client_keep_alive>
</SOAP-ENV:Body>
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_client_keep_alive
66
</ctmem:request_client_keep_alive>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_client_keep_alive
<ctmem:error_list
ctmem:highest_severity='Error' >
<ctmem:error ctmem:major='407'
ctmem:minor='1' ctmem:severity='Error' >
<ctmem:error_message>Invalid user
token.</ctmem:error_message>
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_client_keep_alive>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
67
7
Chapter
7
Introduction to Control-M/EM API requests
The requests described in this chapter are listed in the following table:
Description
User Unregistration (on page 71) Checks if the specified user identification is still valid.
Create folder definitions (on page Creates a regular or SMART Folder definitions.
74)
Add folder to folder definitions Adds sub-folder definitions into an existing outermost
(on page 90) SMART folder or sub-folder.
Add jobs to folder definitions (on Adds job definitions into an existing outermost folder or
page 85) sub-folder.
Delete job definitions (on page Deletes job definitions from the specified outermost or
96) sub-folder.
Upload folder (on page 105) Uploads a folder
Order (on page 110) Inserts a job or folder into Active Jobs immediately (force)
or subject to scheduling criteria (order).
Job creation (on page 124) Creates a job, SMART Folder, or sub-folder into the Active
Jobs database.
Add condition (on page 163) Adds conditions.
Delete condition (on page 170) Deletes conditions.
Job actions in active jobs Performs actions on jobs that are currently in the active
database (on page 178) jobs database.
Job tracking (on page 197) Polls the Response repository in the Control-M/EM GUI
Server to receive completion confirmation from earlier job
processing requests.
Retrieve jobs in the active jobs Retrieves jobs that are currently in the active jobs
database (on page 210) database.
Change alert status (on page Changes the status of an alert (for example, from
228) not_noticed to handled).
68
Description
Retrieve BIM Services list (on Retrieves the list of services active in the BMC Batch Impact
page 232) Manager server.
Considerations
Many XML elements in this section are Control-M job parameters. To create a successful request, particularly
a Job Creation request or an Order Job request, BMC Software recommends that you become familiar with
Control-M job parameters.
Control-M/EM API does not support non-English characters in request and response parameters.
For details about Control-M job parameters, see Control-M Workload Automation Parameters. The element
names in this chapter often differ from the names of the job parameters to which they correspond. Search
for parameters by name in Control-M Workload Automation Parameters.
SOAP Envelope for Control-M/EM requests and responses

SOAP ("Simple Object Access Protocol") is a simple XML-based protocol that allows applications to exchange
information. For more information, see http://www.w3.org.
Control-M/Enterprise Manager API uses SOAP envelopes to wrap the Control-M/EM requests and responses.
Additionally, FAULT responses are wrapped within a SOAPFAULT element.
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
. . . SPECIFIED_REQUEST . . .
</SOAP-ENV:Body>
69
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
. . .SPECIFIED_REQUEST_RESPONSE . . .
</SOAP-ENV:Body>
The fault responses are wrapped within a SOAP Fault envelope.
Fault Response
The following table describes the parameters for fault XML parameters of all requests:
error_list A sequence of error. For a list of the error_list sub parameters see:
Error XML parameters (on page 70).
Error XML parameters

The following table describes the Error XML Parameters:
error attributes Major: The error Major Code. An integer describing the family of
errors to which the error belongs. For more information, see Error
codes and exceptions (on page 272)
Minor: The error minor Code. An integer that is a unique ID for an
error of this type. For more information, see: Error codes and
exceptions (on page 272)
Severity: The priority level assigned to the error
error_message Text description of the error. For more information see: Error codes
and exceptions (on page 272).
70
User Unregistration
When the application finishes using the API, use the Unregister request to send the user token to the server
component. The server component erases the user from its active users list. The user token is invalidated
when the request is complete.
Request parameters
request_unregister XML parameters
The following figure describes the request_unregister XML parameters:
The following table describes the request_unregister XML parameters:
Response parameters
response_unregister XML parameter
The following figure describes the response_unregister XML parameters:
71
The following table describes the response_unregister XML parameters:

XML parameters for fault_unregister, as well as a sample fault response are described in Fault Response (on
page 70).
Errors
Examples
Successful example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_unregister
</ctmem:request_unregister>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_unregister
72
<ctmem:status>OK
</ctmem:status>
</ctmem:response_unregister>
</SOAP-ENV:Body>
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_unregister
</ctmem:request_unregister>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_unregister
<ctmem:error_list
<ctmem:error_message>Unregister
73
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_unregister>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Create folder definitions

Creates new outer-most folder (regular or SMART Folder) definitions. It is possible to create only one folder
per request. If the specified folder already exists, the request will fail. It is possible to create an empty folder
or a folder containing jobs or sub-folders (in the case of SMART Folders).
Request parameters
request_def_create_folder XML parameters
The following figure describes the request_def_create_folder XML parameters:
The following table describes the request_def_create_folder XML Parameters:
folder Folder wrapper. The folder is identified by the elements listed in the following
folder: folder XML parameters description
SMART_folder SMART Folder wrapper. The folder is identified by the elements listed in the
following folder: SMART_folder XML parameters description
74
folder_type XML parameters

The following figure describes the folder_type XML parameters:
The following table describes the folder XML parameters:
control_m Name of the Control-M installation that processes the request. String.
folder_name Name of the outermost folder. String.
folder_library Control-M for z/OS only:

Name of the library in which the table is located. String
user_daily Name of the user daily. String.
jobs A sequence of job elements. See Job and SMART Folder XML parameters (on page
302) for a list of the parameters that can be used/specified in job elements.
75
SMART_folder_type XML parameters

The following figure describes the SMART_folder_type XML parameters:
The following table describes the SMART_folder XML parameters:
folder_name Name of the folder. String.

user_daily Name of the user daily. String.
folder_attributes The SMART Folder’s attributes. See Job and SMART Folder XML parameters (on
page 302).
sub_folders A sequence of sub-folder elements. See Job and SMART Folder XML parameters
(on page 302) for a list of the parameters that can be used/specified in sub-folder
elements.
76
sub_folder_type XML parameters

The following figure describes the sub_folder_type XML parameters:
The following table describes the sub-folder XML parameters:
folder_name Name of the sub-folder. String.
folder_attributes The sub-folder’s user defined attributes. See Job and SMART Folder XML
parameters (on page 302)
sub_folders A sequence of sub-folder elements. See Job and SMART Folder XML parameters
(on page 302) for a list of the parameters that can be used/specified in sub-folder
elements.
Response parameters
response_def_create_folder XML parameters
The following figure describes the response_def_create_folder XML parameters:
77
The following table describes the response_def_create_folder XML Parameters:

Name of the library in which the table is located. String.

XML parameters for fault_def_create_smart_folder, as well as a sample fault response are described in Fault
Errors
See Create job/SMART Folder definitions request errors (Major code 412) (on page 288).
Examples
Successful example
Request
The following request is to create a outer-most SMART Folder with a job and a sub-folder in the first level
which also contains a job:
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_def_create_table
<ctmem:user_token>115B95A7FA4B787B924A2BEA8CE3121A</ctmem:user_tok
en>
<ctmem:SMART_table>
<ctmem:control_m>my700</ctmem:control_m>
<ctmem:table_name>apiTestSMARTTable</ctmem:table_name>
<ctmem:user_daily>SYSTEM</ctmem:user_daily>
78
<ctmem:table_attributes>
<ctmem:application>apiWinApp</ctmem:application>
<ctmem:group>apiGroup</ctmem:group>
<ctmem:author>emuser</ctmem:author>
<ctmem:smart_table_rule_based_cals>
<ctmem:rule_based_cal>
<ctmem:rule_based_cal_name>rule_based_cal1</ctmem:ru
le_based_cal_name>
<ctmem:month_days>ALL</ctmem:month_days>
<ctmem:MAR>yes</ctmem:MAR>
</ctmem:rule_based_cal>
</ctmem:smart_table_rule_based_cals>
</ctmem:table_attributes>
<ctmem:sub_tables>
<ctmem:sub_table>
<ctmem:table_name>subTable_1</ctmem:table_name>
<ctmem:owner>controlm</ctmem:owner>
<ctmem:sub_table_rule_based_cals>
<ctmem:sub_rule_based_cal>
<ctmem:rule_based_cal_name>rule_based_cal1</ctmem:rule_based_cal_n
ame>
</ctmem:sub_rule_based_cal>
</ctmem:sub_table_rule_based_cals>
<ctmem:jobs>
<ctmem:job>
<ctmem:job_name>In-SubTable_1</ctmem:job_name>
<ctmem:mem_name>In-SubTable_1</ctmem:mem_name>
<ctmem:task_type>command</ctmem:task_type>
79
<ctmem:command>ls -l</ctmem:command>
<ctmem:job_rule_based_cals>
<ctmem:job_rule_based_cal>
ame>
</ctmem:job_rule_based_cal>
</ctmem:job_rule_based_cals>
</ctmem:job>
</ctmem:jobs>
</ctmem:sub_table>
</ctmem:sub_tables>
<ctmem:jobs>
<ctmem:job>
<ctmem:job_name>In-Smart-Table</ctmem:job_name>
<ctmem:mem_name>INGROUP</ctmem:mem_name>
<ctmem:mem_lib>INGROUP</ctmem:mem_lib>
<ctmem:task_type>dummy</ctmem:task_type>
</ctmem:job>
</ctmem:jobs>
</ctmem:SMART_table>
</ctmem:request_def_create_table>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
80
<ctmem:response_def_create_table
</ctmem:response_def_create_table>
</SOAP-ENV:Body>
Request
The following request is to create a folder with a job:
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
en>
<ctmem:table>
<ctmem:table_name>apiTestTable</ctmem:table_name>
<ctmem:jobs>
<ctmem:job>
<ctmem:job_name>In-Table-1</ctmem:job_name>
<ctmem:mem_name>In-Table-1</ctmem:mem_name>
</ctmem:job>
</ctmem:jobs>
81
</ctmem:table>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_def_create_table
</ctmem:response_def_create_table>
</SOAP-ENV:Body>
Failure example
Request
The following request to create a folder contains invalid job definitions:
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
en>
<ctmem:table>
<ctmem:jobs>
<ctmem:job>
82
</ctmem:job>
</ctmem:jobs>
</ctmem:table>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_def_create_table
<ctmem:error_list ctmem:highest_severity='Error'>
<ctmem:error ctmem:major='412' ctmem:minor='1'
ctmem:severity='Error'>
<ctmem:error_message>Create jobs definitions failed,
inavlid
params.</ctmem:error_message>
</ctmem:error>
<ctmem:error_message>Create jobs definitions
validation error: Job[1]: Field: Owner -
Error: EM50011E: The field must have a
value.</ctmem:error_message>
83
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_def_create_table>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Request
The following request to create a folder fails because the folder already exists.
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
en>
<ctmem:table>
<ctmem:jobs>
<ctmem:job>
</ctmem:job>
</ctmem:jobs>
84
</ctmem:table>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_def_create_table
<ctmem:error_message>Table already
exist.</ctmem:error_message>
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_def_create_table>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Add jobs to folder definitions

This request adds jobs to an existing SMART folder or sub-folder.
85
Request parameters
request_def_add_jobs XML parameters
The following figure describes the request_def_add_jobs XML parameters:
The following table describes the request_def_add_jobs XML Parameters:

Full slash (/) separates the parent folder name. For example, to add job X to an
existing sub-folder C, that resides in sub-folder B, that resides in SMART outermost
folder A, specify "A/B/C" in the folder_name.

jobs A sequence of job. For a list of the parameters for job, refer to Job and SMART
Folder XML parameters (on page 302)
86
Response parameters
response_def_add_jobs XML parameters
The following figure describes the response_def_add_jobs XML parameters:
The following table describes the response_def_add_jobs XML Parameters:

number_of_jobs_adde The number of jobs added to the folder.

d

XML parameters for fault_def_add_jobs, as well as a sample fault response are described in Fault Response
(on page 70) .
Examples
Successful example
Request
The following request is to add a job to an existing sub-folder:
87
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_def_add_jobs
<ctmem:user_token>83FE7394E4D10220EF99C3D55B79EFB4</ctmem:user_tok
en>
<ctmem:table_name>apiTestSMARTTable/subTable_1</ctmem:table_name>
<ctmem:jobs>
<ctmem:job>
<ctmem:job_name>In-SubTable_job2</ctmem:job_name>
<ctmem:mem_name>In-SubTable_job2</ctmem:mem_name>
</ctmem:job>
<ctmem:job>
</ctmem:job>
</ctmem:jobs>
</ctmem:request_def_add_jobs>
</SOAP-ENV:Body>
88
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_def_add_jobs
<ctmem:folder_name>apiTestSMARTTable/subTable_1</ctmem:table_name>
<ctmem:number_of_jobs_added>2</ctmem:number_of_jobs_added>
</ctmem:response_def_add_jobs>
</SOAP-ENV:Body>
Failure example
Request
The following request is to add a job to a nonexistent sub-folder:
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
en>
<ctmem:table_name>apiTestSMARTTable/inexistent_subTable</ctmem:tab
le_name>
<ctmem:jobs>
<ctmem:job>
89
</ctmem:job>
</ctmem:jobs>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_def_add_jobs
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_def_add_jobs>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Add folder to folder definitions

This request adds a sub-folder to an existing SMART folder or sub-folder.
90
Request parameters
request_def_add_folder XML parameters
The following figure describes the request_def_add_folder XML parameters:
The following table describes the request_def_add_folder XML Parameters:
parent_table Table wrapper. The table is identified by the elements listed in the following table.
jobs A sequence of job. For a list of the parameters for job, refer to Job and SMART
Folder XML parameters (on page 302).
The following table describes the XML parameters:


91
Response parameters
response_def_add_folder XML parameters
The following table describes the response_def_add_folder XML parameters:
The following table describes the response_def_add_folder XML Parameters:
folder_name Full name of the outermost folder. String.


XML parameters for fault_def_add_folder, as well as a sample fault response are described in Fault Response
(on page 70).
Examples
Successful example
Request
The following request is to add a sub-folder with one job to an existing sub-folder:
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
92
<ctmem:request_def_add_table
<ctmem:user_token>D71B430E6A1B00071D4BE91A64E41AA4</ctmem:user_tok
en>
<ctmem:parent_table>
<ctmem:table_name>apiTestSMARTTable/subTable_1</ctmem:table_name>
</ctmem:parent_table>
<ctmem:sub_table>
<ctmem:table_name>subTable_2</ctmem:table_name>
<ctmem:sub_table_rule_based_cals>
<ctmem:sub_rule_based_cal>
ame>
</ctmem:sub_rule_based_cal>
</ctmem:sub_table_rule_based_cals>
<ctmem:jobs>
<ctmem:job>
<ctmem:job_name>In-SubTable_2_job1</ctmem:job_name>
<ctmem:mem_name>In-SubTable_2_job1</ctmem:mem_name>
<ctmem:job_rule_based_cals>
<ctmem:job_rule_based_cal>
93
ame>
</ctmem:job_rule_based_cal>
</ctmem:job_rule_based_cals>
</ctmem:job>
</ctmem:jobs>
</ctmem:sub_table>
</ctmem:request_def_add_table>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_def_add_table
<ctmem:table_name>apiTestSMARTTable/subTable_1/subTable_2</ctmem:t
able_name>
</ctmem:response_def_add_table>
</SOAP-ENV:Body>
Failure example
Request
The following request is to add a job to a nonexistent sub-folder:
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
94
en>
<ctmem:table_name>apiTestSMARTTable/inexistent_subTable</ctmem:tab
le_name>
<ctmem:jobs>
<ctmem:job>
</ctmem:job>
</ctmem:jobs>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_def_add_jobs
95

</ctmem:error>
</ctmem:error_list>
</ctmem:fault_def_add_jobs>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Delete job definitions

This request deletes one or more jobs from a folder according to the user defined deletion criteria. SMART
Folder or sub-folder entities are not deleted. Folder entities are not deleted.
If no jobs are deleted according to the specified deletion criteria, a fault response with the appropriate
message is returned.
Request parameters
request_def_delete_jobs XML parameters
The following figure describes the request_def_delete_jobs XML parameters:
96
The following table describes the request_def_delete_jobs XML parameters:
folder Folder wrapper. The folder is identified by the elements listed in the table XML
Parameters Description table.
delete_jobs_criterion Delete jobs criteria wrapper. String. Consists of include and exclude filters that
allow specifying items to include with or exclude from the deletion criteria, as
described in the delete_jobs_criterion XML parameters description table.
XML Parameters
The following table describes the XML Parameters:

Name of the folder. String.

delete_jobs_criterion XML parameters

The following figure describes the delete_jobs_criterion XML parameters:
97
The following table describes delete_jobs_criterion XML parameters:
include Mandatory. Filter that consists of a sequence of search_criterion elements. For

more information, refer to the include or exclude XML parameter (on page 98)
table.
exclude Optional. Filter that consists of a sequence of search_criterion elements. For more
information, refer to the include or exclude XML parameter (on page 98) table.
include or exclude XML parameter

The following the figure describes the include or exclude XML parameter:
The following table describes include or exclude XML parameters:
search_criterion Search criteria wrapper that consists of a sequence of param elements. At least
one search_criterion element must appear under the exclude element. The amount
of search_criterion elements is unbounded. The relationship between
search_criterion elements in one filter is OR. For more information about param,
see the search_criterion XML parameters description table.
The following table describes search_criterion XML parameters:
param Parameters used to build the search criteria. At least one param element should
appear under a search_criterion element. The amount of param elements is
unbounded. The relationship between param elements in the same
search_criterion is AND. Elements of param are listed in the param XML parameters
(on page 99). String.
98
param XML parameters

The following figure describes the param XML parameters:
The following table describes param XML parameters:
name Name of the table definition parameter used as a search criteria. String.
Mandatory. For a list of valid values for the name parameter, see the Valid Values
for name (on page 100) table.
operator Operator used in search criteria. String.

Valid values:
 EQ
 NE
 LT
 GT
 LIKE
value Value used in search criteria. Any valid value of a job parameter. Wildcards and
search patterns can be used in combination with LIKE operator. String. Mandatory.
99
Valid Values for name

The following table describes Valid values for name:
APPLICATION Name of the application to which the job’s group belongs.
GROUP_NAME Name of the group to which the job belongs.
FILE_NAME Name of the file that contains the job script.
JOB_NAME Name of the job.
DESCRIPTION Description of the job.
CREATED BY Control-M/EM user who defined the job.

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 Control-M Workload
Automation Administration.
HOST_ID Host ID of the host on which the job was most recently run.
This parameter is not available for MVS jobs.
FILE_PATH Name of the path that contains the job script file.
For more information about the parameters described in the table Valid values for name, refer to the
Control-M/Enterprise Manager documentation.
Response parameters
response_def_delete_jobs XML parameters
The following figure describes the response_def_delete_jobs XML parameters:
100
The following table describes the response_def_delete_jobs XML parameters:
deleted_jobs_number Number of jobs that were deleted. String.
The following table describes XML Parameters:

Name of the folder. String.


XML parameters for fault_def_delete_jobs, as well as a sample fault response are described in Fault
Errors
See Delete job definitions request errors (Major code 413) (on page 289).
Examples
Successful example
Request
<?xml version="1.0" encoding="ISO-8859-1" ?>
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
101
<ctmem:request_def_delete_jobs
en>
<ctmem:table>
able_name>
</ctmem:table>
<ctmem:delete_jobs_criterion>
<ctmem:include>
<ctmem:search_criterion>
<ctmem:param>
<ctmem:name>JOB_NAME</ctmem:name>
<ctmem:operator>LIKE</ctmem:operator>
<ctmem:value>*</ctmem:value>
</ctmem:param>
</ctmem:search_criterion>
</ctmem:include>
<ctmem:exclude>
<ctmem:param>
<ctmem:name>MEMNAME</ctmem:name>
<ctmem:operator>EQ</ctmem:operator>
<ctmem:value>apiMemName2</ctmem:value>
</ctmem:param>
</ctmem:exclude>
</ctmem:delete_jobs_criterion>
</ctmem:request_def_delete_jobs>
</SOAP-ENV:Body>
102
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_def_delete_jobs
<ctmem:table>
able_name>
</ctmem:table>
<ctmem:deleted_jobs_number>1</ctmem:deleted_jobs_number>
</ctmem:response_def_delete_jobs>
</SOAP-ENV:Body>
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_def_delete_jobs
en>
<ctmem:table>
able_name>
</ctmem:table>
<ctmem:delete_jobs_criterion>
<ctmem:include>
103
<ctmem:param>
<ctmem:name>UNKNOWN</ctmem:name>
</ctmem:param>
</ctmem:include>
</ctmem:delete_jobs_criterion>
</ctmem:request_def_delete_jobs>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_def_delete_jobs
<ctmem:error_message>Failed to delete jobs from
table.</ctmem:error_message>
</ctmem:error>
<ctmem:error_message>Delete jobs definitions
validation error: [UNKNOWN] is not valid
filter field.</ctmem:error_message>
</ctmem:error>
</ctmem:error_list>
104
</ctmem:fault_def_delete_jobs>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Upload folder
Uploads an outermost folder. Only one folder can be uploaded per request. It is possible to force upload a
folder using the optional force parameter.
Request parameters
request_def_upload_folder XML parameters
The following figure describes the request_def_upload_folder XML parameters:
The following table describes the request_def_upload_folder XML parameters:
force_it Forces the uploading of a folder. String. Optional.
105
The following table describes XML Parameters:

Response parameters
The following table describes the response_def_upload_table XML Parameters:
response_token Used in a polling request.
Polling request parameters

request_poll XML parameters
The following figure describes the request_poll XML parameters:
The following table describes the request_poll_def_upload_table XML parameters:
response_token Used in a polling request. This token is received in the immediate response of
response_def_upload_table.
106
Polling response parameters

response_poll_def_upload_table XML parameters
The following figure describes the response_poll_def_upload_table XML parameters:
The following table describes response_poll_def_upload_table XML parameters:
status Status of polling. String.

Valid values:
 OK
 EXEC

XML parameters for fault_def_upload_table and fault_poll_def_upload_table, as well as a sample fault
response are described in Fault Response (on page 70).
Errors
See Upload folder request errors (Major code 411) (on page 287).
Examples
Successful example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_def_upload_table
107
<ctmem:user_token>17C3BA2475FB34069257862D90FB2128</ctmem:user_tok
en>
<ctmem:force_it>no</ctmem:force_it>
<ctmem:table>
</ctmem:table>
</ctmem:request_def_upload_table>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_def_upload_table
<ctmem:response_token>6</ctmem:response_token>
</ctmem:response_def_upload_table>
</SOAP-ENV:Body>
Polling request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_poll_def_upload_table
en>
</ctmem:request_poll_def_upload_table>
108
</SOAP-ENV:Body>
Polling response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_poll_def_upload_table
</ctmem:response_poll_def_upload_table>
</SOAP-ENV:Body>
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_def_upload_table
en>
<ctmem:table>
<ctmem:table_name>inexistent_table</ctmem:table_name>
</ctmem:table>
</ctmem:request_def_upload_table>
</SOAP-ENV:Body>
109
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_def_upload_table
<ctmem:error_message>Cannot get Table from
database.</ctmem:error_message>
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_def_upload_table>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Order
The following operations can be performed with jobs and SMART Folders using Order:
 Order a job. The job is entered into Active Jobs only when its scheduling criteria are met.
 Order a job even if scheduling criteria are not met: The job is entered into Active Jobs database if its
scheduling criteria are met or not.
 Order a SMART Folder: All jobs in the folder are ordered only when its scheduling criteria are met.
 Order a SMART Folder even if scheduling criteria is not met: The SMART Folder is entered into Active
Jobs database even if its scheduling criteria is not met.
The mandatory parameters for ordering a job differ from the mandatory parameters that are specified when
ordering or forcing a SMART Folder. Optional parameters can be supplied for both jobs and SMART Folders.
110
Request parameters
request_order_force XML parameters
The following figure describes the request_order_force XML parameters:
111
The following table describes request_order_force XML parameters:
control_m Data center name.

Mandatory for both jobs and Folders.
String.
force_it Indicates whether the job is ordered or forced.

Mandatory for both jobs and Folders.
 no - orders job/folder
 yes - forces job/folder
job_id Occurrence number of the job within the folder. String. Optional
Used to identify a specific job, in case there are multiple occurrences of the
same job name in the folder. If the value of the job_id parameter is blank,
0, or 1, the first occurrence of the job is used.
job_name Name of the job.

Mandatory for jobs. Must be left empty for folders.
String.
order_date Enables you to order the job with a specific date.

Mandatory for both jobs and folders.
Valid values:
 Numerical date ( yyyymmdd format)
 ODAT
wait_for_order_date Indicates whether the job submission should wait for a specified order date
(order_date), or be submitted as soon as the execution criteria for the job
is satisfied.
Valid values:
 yes (wait for order_date)
 no (do not wait for order_date - default)
Relevant for Control-M versions 6.2.01 or later.
with_hold Holds all jobs immediately after they are ordered.
112

folder_name Name of the folder.

Mandatory for both jobs and folders.
String.
folder_info A sequence of folder_info. See the table_info XML parameters

description table.
variable_assignments A sequence of variable_assignment. See the variable_assignment

XML parameters description.
max_returned_nodes Limits the number of returned entities. Optional.

Should not exceed the value of the EMAPIActiveJobsLoadLimit system
parameter.
table_info_type XML parameters

The following figure describes the table_info_type XML parameters:
113
The following table describes info XML parameters:
into_folder Indicates into which SMART Folder the job is placed.

Optional for jobs. Not used for folders.
 recent
 new
 standalone
 selected
 order ID of a SMART Folder
folder_id Serial number identifying the SMART Folder. Optional for jobs. Must be
empty for folders. For more information on the folder_id parameter, see
Job tracking (on page 197). String.
allow_dup Allows duplicate jobs in a SMART Folder.

Optional for jobs. Must be left empty for folders (accepts default).
Valid values:
 no - Not allowed
 yes - Allowed (default)
variable_assignment XML parameters

The following figure describes the variable_assignment XML parameters:
114
The following table describes variable_assignment XML parameters:
name Name of the Variable variable.

Mandatory, if the variable_assignment element is specified.
String. Name sequence.
value Value of the Variable expression.

String.
Response parameters
response_order_force XML parameters
The following figure describes the response_order_force XML parameters:
The following table describes response_order_force XML parameters:
status Description of message content. String.
response_token Used in the polling request.
115

request_poll_order_force XML parameters
The following figure describes the request_poll_order_force XML parameters:
The following table describes request_poll_order_force XML parameters:
response_token Used in a polling request. This token is received in the immediate response of a
response_order_force.

job_data XML parameters
The following figure describes the job_data XML parameters
116
The following table describes job_data XML parameters
rba Relative block address. String.
order_id Serial number assigned to the job by Control-M Workload Automation installation.
String.
file_name Name of the file that contains the job script. String.
job_name Name of the job. String.
is_folder Indicates whether the job is a member of a SMART Folder.

Valid values:
 no (not a member of a SMART Folder)
 yes (member of a SMART Folder)
ret_text Text describing the job run. String.
117
response_poll_order_force XML parameters

The following figure describes the response_poll_order_force XML parameters:
The following table describes response_poll_order_force XML parameters:
jobs A sequence of job. See the job XML parameters description table below.
error_list A sequence of error. See Fault Response (on page 70)
error_list attribute: highest_severity Indicates the severity level of the most critical error
included in the error list. If only one error is included,
the severity for that error is displayed. String.
job XML parameters

The following figure describes the job XML parameters
118
The following table describes job XML parameters
job_data An element that contains other parameters that describe the job.
A sequence of job_data. See the job_data XML parameters description
table.

XML parameters for fault_order_force and fault_poll_order_force, as well as a sample fault response are
described in Fault Response (on page 70).
Errors
See Order or Force request errors (Major code 405) (on page 284).
Examples
Successful example
The following request is to order/force a SMART Folder with a sub-folder and a job.
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_order_force
en>
<ctmem:force_it>yes</ctmem:force_it>
119
<ctmem:odate>ODAT</ctmem:odate>
</ctmem:request_order_force>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_order_force
<ctmem:response_token>10u</ctmem:response_token>
</ctmem:response_order_force>
</SOAP-ENV:Body>
Polling request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_poll_order_force
en>
</ctmem:request_poll_order_force>
</SOAP-ENV:Body>
120
Polling response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_poll_order_force
<ctmem:jobs>
<ctmem:job>
<ctmem:job_data>
<ctmem:order_id>00000j</ctmem:order_id>
<ctmem:job_name>apiTestSMARTTable</ctmem:job_name>
<ctmem:ret_text>Job ordered</ctmem:ret_text>
</ctmem:job_data>
</ctmem:job>
<ctmem:job>
<ctmem:job_data>
<ctmem:order_id>00000k</ctmem:order_id>
<ctmem:job_name>subTable_1</ctmem:job_name>
</ctmem:job_data>
</ctmem:job>
<ctmem:job>
<ctmem:job_data>
<ctmem:order_id>00000l</ctmem:order_id>
<ctmem:mem_name>In-SubTable_1</ctmem:mem_name>
<ctmem:job_name>In-SubTable_1</ctmem:job_name>
</ctmem:job_data>
</ctmem:job>
</ctmem:jobs>
121
</ctmem:response_poll_order_force>
</SOAP-ENV:Body>
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
en>
<ctmem:job_name>subTable_1</ctmem:job_name>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_order_force
</ctmem:response_order_force>
</SOAP-ENV:Body>
122
Polling request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_poll_order_force
en>
</ctmem:request_poll_order_force>
</SOAP-ENV:Body>
Polling response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_poll_order_force
<ctmem:error_message>Entry not found 5778 Force
Sub-table subTable_1 alone is not
permitted</ctmem:error_message>
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_poll_order_force>
</detail>
</SOAP-ENV:Fault>
123
</SOAP-ENV:Body>
Job creation
This procedure describes how to to create a job or SMART Folder into Active Jobs database.
 To create a regular job:

 Specify all the parameters required for the job.
 Do not specify a value for the folder_id parameter.
 Do not specify SMART_folder as the value for the task_type parameter.
 To create a SMART Folder:

 Specify SMART_folder as the value for the task_type parameter.
 Specify a name for the SMART Folder in the folder parameter.
 Specify all other parameters required for the folder.
 After the SMART Folder has been created, note the value of the order_id parameter. This value must be
supplied for the folder_id parameter of jobs that are associated with the SMART Folder.
 To create a job in a SMART Folder:

 Indicate to which SMART Folder to associate the job by specifying:
• The folder name for the parent SMART Folder in the folder parameter of the job specification.
• The ID of the folder for the parent SMART Folder in the folder_id parameter of the job specification.
For Control-M/Server (on Non-z/OS Platforms)
The folder_id consists of the order_id of the existing SMART Folder preceded by a leading zero.
For Control-M for z/OS
The folder_id consists of the RBA of the existing SMART Folder.
If the folder is not already ordered, it can be created using a separate create_aj request before creating
the dependent job (see above). The folder name is specified when creating the new folder, and the
necessary information (folder name, order_id, and RBA) can be obtained from the response to this
request for use when populating the folder with jobs.
124
Request parameters
request_create_aj XML parameters
The following figure describes the request_create_aj XML parameters:
The following table describes request_create_aj XML parameters:
control-m Data center name. String.

Mandatory.
active_job Specification for a single job. The parameters of the job are included as elements
between the opening and closing active_job tags. Contains no attributes.
See the following table.
125
The following table describes active_job XML Parameters:
adjust_condition 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:
 no – (Do not ignore. Default.)
 yes – (Ignore relevant prerequisite conditions)
 dummy – [Control-M for z/OS as of version 6.2.xx only]. Order as a
PSEUDO job any job with scheduling criteria that are not satisfied on the
current ODATE, with the MEMLIB parameter of the job set to DUMMY.
application Name of the application to which the job’s group belongs. Used as a descriptive
name for related groups of jobs.
application_cm_version Indicates the version of external application (for example, SAP or Oracle
Applications) Control Module (CM) that is installed in the Control-M
installation. Specified together with the application_form,
application_type, and application_version elements.
application_form Specifies a predefined set of external application parameters that are displayed
in the External Application panel of the Control-M Workload Automation
Properties pane. Specified together with the application_cm_version,
application_type Indicates the type of external application (for example, SAP or Oracle
Applications) on which the external application job runs. Specified together with
the application_cm_version, application_form, and
application_version elements.
application_version Indicates the version of the external application (for example, SAP or Oracle
Applications) on which the external application job runs. Specified together with
the application_cm_version, application_form, and application_type
elements.
arch_max_days Maximum number of days to retains the SYSDATA archive data set for jobs that
ended NOTOK. [z/OS only]
arch_max_runs Maximum number of job runs to retain the SYSDATA archive data set for jobs
that ended NOTOK. [z/OS only]
126
auto_archive Determines whether or not SYSDATA is to be archived. [z/OS only]

Valid values:
 yes
 no
variable_assignments A sequence of variable_assignment.

See below the variable_assignment XML parameters description table .
command Command string supplied when the job Task Type (the task_type element) is
Command. Optional.
confirm_flag Specifies whether user confirmation is required before the job is submitted for
execution. String.
Valid values:
 no - Job needs no confirmation to run. Default.
 yes - Job must be confirmed to run.
control_resources A sequence of control_resource.

See the control_resources XML parameters description table.
count_cyclic_from Indicates whether the interval between successive runs of a cyclic job is
calculated from the start or the end of the previous job run. Specified only for
cyclic jobs (when the cyclic element is specified).
Valid values:
 start – Counts interval from the start of the previous job run
 end – Counts interval from the end of the previous job run
 target - Counts interval from the scheduling time of the current job run.
critical Indicates that the job is a critical-path job in Control-M.

Valid values:
 yes – a critical path job
 no – not a critical path job
ctb_steps A sequence of ctb_step.

See the ctb_step XML parameters description table.
127
cyclic Indicates if a job is cyclic.

Valid values:
 yes – Cyclic job
 no – Non-cyclic job
cyclic_type If job is cyclic (cyclic equal yes), indicates how the intervals for running the job
are specified. Valid values are:
 interval: Job is run at fixed interval. See the description for
rerun_interval.
 interval_sequence: Job is run according to a list of time periods. See the
description for interval_sequence.
 specific_times: Job is run according to a list of specific times. See the
description for specific_times.
This parameter is relevant only for jobs running in Control-M/Server version
6.4.01 and later and Control-M for z/OS version 7.0.01 and later.
description Text description of the job.
days_due_out_offset The number of days that job execution can be extended after the ODAT.
days_due_out_offset is relevant only for jobs running in Control-M for z/OS
version 6.2.00 and later.
doc_lib Name of the directory/library containing the job documentation file.
doc_member Name of the file containing job documentation.
folder_id Order ID of the parent SMART Folder preceded by a leading zero.
in_conditions A sequence of in_condition.

See in_condition XML parameters (on page 149)
128
instream_jcl JCL stream forming part of the job definition.
instream_jcl is relevant for jobs running in:

 Control-M for z/OS version 6.2.00 and later
 Control-M/Server version 6.4.01 and later
interval_sequence A sequence of interval_item.

See Table below interval_sequence XML parameters description
job_name Name of the job.
keep_active Number of extra days (beyond the original scheduling date) that the job is
allowed to remain in Active Jobs awaiting execution. Integer.
file_path Name of the library/directory in which the job script resides. String.
multiagent When selected, broadcasts job submission details to all Agents within a specified
Group. Not for z/OS. Optional.
Valid values:
 yes – Nodes run as multi-agent job
 no – not run as multi-agent job. Default.
host_group Host name of a host group to which the job is submitted. Not for z/OS.
order_date Original scheduling date of a job.
on_do_statements A sequence of on_do_statement.

See on_do_statement XML parameters (on page 135)
order_folder Default or dummy folder to which you indicate the job belongs.
A folder is not necessary because jobs that are created with the Control-M/EM
API are inserted directly into Active Jobs. However, you may want to include a
value for this parameter so that the job can be tracked during statistical analysis
that uses Folder as a criterion.
129
order_library Default or dummy folder library in which folder documentation is said to be

stored.
A folder (and, by extension, a folder library) are not necessary because jobs that
are created with the Control-M/EM API are inserted directly into Active Jobs.
However, you may want to include a value for this parameter so that the job can
be tracked during statistical analysis that uses Folder or Folder Library as
criteria. This parameter is specified only for z/OS jobs for which the
order_folder element was also specified.
out_conditions A sequence of out_condition.

See out_condition XML parameters (on page 152).
override_path Name of the alternate job script library/directory.
Run As User User (username) associated with the job.
pipes A sequence of pipe.

See pipe XML parameters (on page 151)
prevent_nct2 Prevents data set cleanup before the original job run. [z/OS only].
Optional.
Valid values:
 no – Does not prevent data set cleanup. Default.
 yes – Prevents data set cleanup.
 blank - Do not perform data set cleanup before the original job run.
 list - Do not perform data set cleanup before the original job run; but
generate the messages that would be required for GDG adjustment during
restart.
 flush - Halt processing of the job if any data set cleanup error is detected
(even if MVS would not have stopped processing the job).
priority Indicates Control-M job priority. String.
quantitative_resources A sequence of quantitative_resource.

See quantitative_resource XML parameters (on page 150).
130
request_nje Specifies the node in the JES network on which the job is to execute. [z/OS only]
String.
rerun_interval Specifies the length of time to wait between reruns of a job or between cyclic
runs of a job. The value is expressed as a number and a letter. The number
indicates the amount. The letter indicates the unit of measurement.
Valid values:
 0 - 64800M (minutes)
 0 - 1080H (hours)
 0 - 45D (days)
Default: 0.
rerun_max Specifies the maximum number of reruns that can be performed for the
job. Integer.
Valid values: 0-99.
rerun_member Name of the JCL member to use when the job is automatically rerun. [z/OS only]
String. Optional.
reten_days Number of days to retain the job in the History Jobs file. [z/OS, only]. String.
reten_gen Maximum number of generations of the job to keep in the History Jobs
file.[z/OS, only]. String.
schedule_environment Indicates the JES2 workload management scheduling environment that is to be

associated with the job.[z/OS, only]. String.
shouts A sequence of shout.

See shouts XML parameters (on page 154)
specific_times A sequence of specific_time.

See specific_times XML parameters (on page 156)
statistic_calendar Name of the Control-M periodic calendar within which statistics relating to the
job are collected.
statistic_calendar is relevant only for jobs running in Control-M for z/OS

131
step_ranges A sequence of step_range.

See step_range XML parameters (on page 153)
sys_db Indicates that a single data set is used for archiving the SYSDATA of all jobs until
it is full, when another data set is started. [z/OS only]
Valid values:
 yes – Single data set created for the SYSDATA of each job run.
 no – Separate data set created for the SYSDATA of each job run.
output_from_class Limits the output handling operation to only outputs from the specified class.
[z/OS only]
output_option Output Handling options.

Optional.
Valid values (non-z/OS):
 copy
 delete
 move
 release
Valid values (z/OS):
 copy
 delete
 move
 release
 change_class
output_parameter Certain output_option values require that you supply additional information
(such as Copy, NewDest):
 If the output_option element is change_class, the output_parameter value
corresponds to the new class name.
 If the output_option element is copy, the output_parameter value
corresponds to the destination file name.
 If the output_option element is move, the output_parameter value
corresponds to the new destination for the file.
132
system_affinity Indicates the identity of the system in which the job must be initiated and
executed (in JES2).
Indicates the identity of the processor on which the job must execute (in
JES3).
For z/OS jobs only.
task_class Control-D mission. Mandatory for Control-D jobs.

Valid values:
 distribution
 decollation
task_type Type of the job (task) to be performed by Control-M.

Microsoft Windows and UNIX:
 job
 command
 dummy
 detached
 external
 SMART_folder
 sub_folder
Control-M for z/OS:
 job
 task
 SMART_table
 cyclic_job
 emergency_job
 emergency_cyclic_job
 cyclic_task
 emergency_task
 emergency_cyclic_task
time_due_out Time that the job is expected to finish.
time_from Indicates the earliest time for submitting the job.
133
time_from_days_offset Number of days after the original scheduling date of the job during which
execution of the job can begin.
time_from_days_offset is relevant only for jobs running in Control-M for z/OS

time_reference Valid values:

 server
 adjust
time_until Indicates the latest time for submitting the job.
time_until_days_offset Number of days after the original scheduling date of the job during which
execution of the job can end.
time_until_days_offset is relevant only for jobs running in Control-M for z/OS

time_zone Indicates the global time zone used to calculate the interval for time-related
conditions.
tolerance Maximum delay in minutes permitted for late submission when selecting a
specific time.
use_instream_jcl Whether the job submits a JCL stream defined within the job scheduling
definition.
Valid values are:
 yes
 no
use_instream_jcl is relevant for jobs running in:

Control-M for z/OS version 6.2.00 and later
Control-M/Server version 6.4.01 and later
134
on_do_statement XML parameters

on_do_statement XML parameters
The following figure describes the on_do_statement XML parameters:
The following table describes on_do_statement XML parameters:
on_statements A sequence of on_statements.

See on_statements XML parameters (on page 135)
do_statements A sequence of do_statements.

See do_statements type XML parameters (on page 139)
on_statements XML parameters

on_statements XML parameters
The following figure describes On_statements XML parameters:
135
The following table describes on_statements XML parameters:
on_statement A sequence of on_statement.

OR See On_statement XML parameters (on page 136) table.
on_statement_output
A sequence of on_statement_output.
See on_statement_output XML parameters (on page 137).
On_statement XML parameters

The following figure describes on_statement XML parameters
136
The following table describes on_statement XML parameters:
and_or Specifies the relationship between two successive items in a series.

Optional.
code Code value for the On Statement/Code parameter.

Valid values:
 ok
 not_ok
procedure_step Step in the procedure that triggers the On statement. String.
program_step Step in the program that triggers the On statement. String.
statement statement can be:

 A character string containing a statement from the job script file (1-132
characters). The specified string can be a portion of the statement.
 An asterisk (*), when code is a completion status for a job.
on_statement_output XML parameters

The following figure describes the on_statement_output XML parameters:
137
The following table describes on_statement_output XML parameters:
find_output_pattern A string of up to 40 characters.
find_pattern_from A number from 001 through 132, indicating the column at which the search should
start. If this field is blank, the value 001 is assumed. The value in this field must be
lower than that in the To Column field.
find_pattern_to A number from 001 through 132, indicating the column at which the search should
end. If this field is blank, the value 132 is assumed. The value in this field must be
higher than that in the From Column field.
and_or Option buttons that set the logical relationship between multiple On statements.
138
do_statements type XML parameters

The following figure describes the do statements type XML parameters:
139
The following table describes do statements type XML parameters:
do A sequence of do_statements.
do_variable Assigns an Variable variable when the On criteria are met. See do_variable XML
do_cond Assigns an In or Out condition when the On criteria are met. See do_cond XML
do_ctbrule Invokes a Control-M/Analyzer rule to be executed during the processing of a

specific program step when an On condition is met. See do_ctbrule XML
do_forcejob Forces a specified job when the current job is performed.

The dsn element is for z/OS jobs only. See do_forcejob XML parameters (on page
142)
do_ifrerun Specifies job steps to be executed during rerun of a job. Only for networks using
Control-M/Restart. See do_ifrerun XML parameters (on page 143)
do_mail Sends e-mail.
do_remedy Creates a remedy ticket.
do_shout Sends a shout message when the On criteria are met.
do_output Determines what to do with the output documentation when On criteria are met.
do_variable XML parameters

The following figure describes the do_variable XML parameters:
140
The following table describes do_variable XML parameters:
name Name of the item in question (for example, when specified for request, name is
the name of the request; when specified for pipe, name is the name of the pipe)
do_cond XML parameters

The following figure describes the do_cond XML parameters:
The following table describes do_cond XML parameters description:
condition Condition name. When specified, it is be accompanied by the other condition

parameter element, date (and, optionally, by sign or and_or). It is wrapped in
the in_condition and out_condition elements.
date Specifies an order date for various condition formats.
sign Indicates whether to add or delete an Out condition

Valid values:
 add
 delete
141
do_ctbrule XML parameters

The following figure describes do-ctbrule XML parameters:
The following table describes do_ctbrule XML parameters:
name Name of the Control-M/Analyzer rule.
parameter Contains arguments that are passed to the Control-M/Analyzer rule.
do_forcejob XML parameters

The following figure describes do_forcejob XML parameters:
142
The following table describes do_forcejob XML parameters:
dsn Name of the directory/library containing Table file. [z/OS only]
job Specifies the job name of the job that is forced.
folder Name of the Folder with which the job specified in do_forcejob is associated.
do_ifrerun XML parameters

The following figure describes do_ifrerun XML parameters:
143
The following table describes do_ifrerun XML parameters:
confirm Indicates that a job rerun specified by the Do If Rerun parameter must be manually
confirmed before it is executed.
Valid values:
 yes – requires confirmation
 no – confirmation is not required
from_procedure_step Procedure step (EXEC statement) that invokes a procedure from which the
specified program step program is executed.
from_program_step Job step. The execution results of the program executed by the job step are
checked against the specified codes criteria.
to_procedure_step Last procedure step in a range.
to_program_step Last program step in a range.
do_mail XML parameters

The following figure describes do_mail XML parameters:
144
The following table describes do_mail XML parameters:
cc Optional additional address to which a Do Mail can be sent. Optional.
message Text of the message. String.
to Recipient of the do_mail message.
subject Subject of the do_mail message.
urgency Indicates the severity of a mail or shout message.

Valid values:
 regular (Default)
 urgent
 very_urgent
attach_output Specifies whether the output should be sent as an e-mail attachment. Valid values
are:
 yes - Send the job’s output as an attachment
 no - Do not send the job’s output as an attachment
 default - Use the settings configured for the relevant Control-M server to
determine whether the job’s output should be sent as an attachment.
This parameter is relevant only for jobs running in Control-M/Server version 6.4.01
and later and Control-M for z/OS version 7.0.01 and later.
do_shout XML parameters

The following figure describes do_shout XML parameters:
145
The following table describes do_shout XML parameters:
destination Recipient of a Shout message. Specified in both the Shout or the Notify
parameters.

Valid values:
 urgent
 very_urgent
do_output XML parameters

The following figure describes do_output XML parameters:
146
The following table describes the do_output XML parameters:
from_class Specifies the class of jobs with outputs that are handled using the Do Output
specifications of the job.
option Do Output parameter output handling options.

Valid values:
 Release
 Delete
 Copy
 Move
 File
 NewDest
 ChangeClass
Copy and Move are not used with z/OS. File, NewDest, and ChangeClass are used
only with z/OS.
parameter Contains additional output handling information. The type of information required
is dependent on the value of the option element.
 If the option element is ChangeClass, the parameter value corresponds to the
new class name.
 If the option element is Copy, the parameter value corresponds to the
destination file name.
 If the option element is Move, the parameter value corresponds to the new
destination for the file.

The following figure describes variable_assignment XML parameters:
147
name Name of the variable.
ctb_step XML parameters

The following table describes the ctb_step XML parameters:
ctb_arguments Control-M/Analyzer argument.
ctb_name Name of the Control-M/Analyzer entity. Must be a valid name of a

Control-M/Analyzer rule or mission.
ctb_step_position Indicates where to place the Control-M/Analyzer step in the job.
ctb_type Type of Control-M/Analyzer entity.
148
in_condition XML parameters

The following figure refers to variable_assignment XML parameters:
The following table describes in_condition XML parameters:

Optional.
Valid values:
 and
 or
condition Condition name.
control_resources XML parameters

149
The following table describes control_resources XML parameters:
resource Name of the specified resource.
type Indicates job access to a Control resource.

Valid values are:
 exclusive - default
 shared
on_fail Whether to keep a Control resource tied to a job if the job does not end OK. Valid
values:
 keep
 release - default
quantitative_resource XML parameters

150
The following table describes the quantitative_resource XML parameters:
quantity Amount of the specified quantitative resource.
on_ok Whether to keep a Quantitative resource tied to a job if the job ends OK.
Valid values are:
 release
 discard
on_ok is relevant only for jobs running in Control-M for z/OS version 6.2.00 and
later.
on_fail Whether to keep a Quantitative resource tied to a job if the job does not end OK.
Valid values are:
 keep
 release
on_fail is relevant only for jobs running in Control-M for z/OS version 6.2.00 and
later.
pipe XML parameters

The following figure described variable_assignment XML parameters:
151
The following table describes pipe XML parameters:
flag Valid values:

 yes
 no
out_condition XML parameters

The following table describes out_condition XML parameters:

parameter element, date (and, optionally, by sign or and_or).

Valid values:
 add
 delete
152
step_range XML parameters

The following table describes step_range XML parameters:
name Name of the item in question
from_procedure_ Procedure step (EXEC statement) that invokes a procedure from which the
specified program step program is executed
step
from_program Job step. The execution results of the program executed by the job step are
_step checked against the specified codes criteria
to_procedure Last procedure step in a range

_step
to_program_step Last program step in a range
153
shouts XML parameters

154
The following table describes shouts XML parameters:
destination Recipient of a Shout message. Specified in both the Shout or the Do Shout
parameters.
time Time that the message is sent.

Valid values:
 urgent
 very_urgent
when Time that the Shout message was sent.

Valid values:
 ok
 not_ok
 rerun (not valid for SMART Folder entities)
 late_submission
 late_time
 execution_time
shout_days_offset The number of days relative to the ODAT by which the sending of the Shout
message is offset.
Valid values are:
 a number from 0 through 254
 blank – no offset
shout_days_offset is relevant only for jobs running in Control-M for z/OS version
6.2.00 and later.
155
interval_sequence XML parameters

The following diagram describes the variable assignment XML parameters:
The following table describes Interval_sequence XML parameters:
interval_item Time interval to rerun a cyclic job such as +2H, +1D, or +30M. Limited to 4000
characters for all fields.
specific_times XML parameters

The following figure describes specific_times XML parameters:
specific_time Specific time for a cyclic job to run, such as 7:00 or 11:00. Limited to 4000 for all
fields.
Response parameters
156
The following table describes response_create_aj XML parameters:

The following table describes request_poll_create_aj XML parameters:
response_create_aj.
job XML parameters

157
The following table describes jobs XML Parameters:
job Tags that indicate a single job. A sequence of job. See the following table.
The following figure describes job XML parameters:
See job_data XML parameters (on page 158)

158
The following table describes job_data XML parameters:
rba Relative block address. String.
order_id Serial number assigned to the job by the Control-M installation. String.
job_name Name of the job. String.
is_folder Indicates whether the job is a member of a SMART Folder.

Valid values:
no (not a member of a SMART Folder)
yes (member of a SMART Folder)
ret_text Text describing the job run. String.

XML parameters for fault_create_aj and fault_poll_create_aj, as well as a sample fault response are

Responses to Job and SMART Folder creation requests are sent in a format conforming to the schema.
response_poll_create_aj XML parameters
159
The following table describes response_poll_create_aj XML parameters:
jobs A sequence of jobs. See job XML parameters (on page 157).
Errors
Job creation errors are described in Create active job request errors (Major code 409) (on page 286).
Examples
Successful example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_create_aj
<ctmem:control_m>ctm630</ctmem:control_m>
<ctmem:active_job>
<ctmem:job_name>MYJOB</ctmem:job_name>
<ctmem:application>MYAPP</ctmem:application>
<ctmem:group>MYGROUP1</ctmem:group>
<ctmem:command>ls</ctmem:command>
</ctmem:active_job>
</ctmem:request_create_aj>
</SOAP-ENV:Body>
160
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_create_aj
</ctmem:response_create_aj>
</SOAP-ENV:Body>
Polling request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_poll_create_aj
</ctmem:request_poll_create_aj>
</SOAP-ENV:Body>
Polling response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_poll_create_aj
<ctmem:jobs>
<ctmem:job>
161
<ctmem:job_data>
<ctmem:rba>000000</ctmem:rba>
<ctmem:order_id>0023e</ctmem:order_id>
<ctmem:file_name>
</ctmem:mem_name>
<ctmem:is_table>no</ctmem:is_table>
</ctmem:job_data>
</ctmem:job>
</ctmem:jobs>
</ctmem:response_poll_create_aj>
</SOAP-ENV:Body>
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:control_m>Failure_ctm_name</ctmem:control_m>
<ctmem:active_job>
<ctmem:command>ls</ctmem:command>
</ctmem:active_job>
</SOAP-ENV:Body>
162
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_create_aj
<ctmem:error_list
<ctmem:error_message>Invalid
Control-M.</ctmem:error_message>
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_create_aj>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Add condition
Adds prerequisite conditions.
163
Request parameters
The following table describes the request _add_condition XML Parameters:
control_m Name of the Control-M installation that processes the request.

String.
condition Condition description wrapper.

Wrapper for the name and odate elements that identify the specific condition
being added or deleted. Condition. See condition XML parameters (on page 164).
condition XML parameters

The following table describes condition XML parameters:
name Name of the condition to be added or deleted.

String.
odate Order date of the condition. String. Valid values:

 mmdd
 STAT
164
Response parameters
response_add_condition XML parameters
The following table describes response_add_condition XML parameters:

request_poll_add_condition XML parameters
The following table describes request_poll_add_condition XML parameters:
response_add_condition.
165

response_poll_add_condition XML parameters
The following figure describes variable_assignment XML parameters
The following table describes response_poll_add_condition XML parameters
status Description of message content (OK or EXEC). String.
response_data See response_data_XML parameters (on page 173)
response_data XML parameters

The following table describes response_data XML parameters

XML parameters for fault_add_condition and fault_poll_add_condition, as well as a sample fault response
are described in Fault Response (on page 70).
Errors
See Add or Delete Condition request errors (Major code 404) (on page 283).
166
Examples
Successful example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_add_condition
<ctmem:condition>
<ctmem:name>MYJOBOUTCOND1</ctmem:name>
<ctmem:odate>STAT</ctmem:odate>
</ctmem:condition>
</ctmem:request_add_condition>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_add_condition
</ctmem:response_add_condition>
</SOAP-ENV:Body>
167
Polling request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_poll_add_condition
</ctmem:request_poll_add_condition>
</SOAP-ENV:Body>
Polling response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_poll_add_condition
</ctmem:response_poll_add_condition>
</SOAP-ENV:Body>
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:condition>
168
</ctmem:condition>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_add_condition
</ctmem:response_add_condition>
</SOAP-ENV:Body>
Polling request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_poll_add_condition
</ctmem:request_poll_add_condition>
</SOAP-ENV:Body>
169
Polling response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultstring>Error response from EM Server.
</faultstring>
<detail>
<ctmem:fault_poll_add_condition
<ctmem:error_list
<ctmem:error_message>Connot add
condition, already exist.
</ctmem:error_message>
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_poll_add_condition>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Delete condition
Deletes prerequisite conditions.
170
Request parameters
request_delete_condition XML parameters
The following table describes request_delete_condition XML parameters:
control_m Name of the Control-M installation that processes the request.

String.
condition Condition description wrapper. See condition XML parameters (on page 171).
condition XML parameters

The following figure describes the condition XML parameters:
171
The following table describes condition XML parameters:
name Name of the condition to be added or deleted. String.
order_date Order date of the condition. String.

Valid values:
 mmdd
 STAT
Response parameters
Response_delete_condition XML parameters
The following table describes response_delete_condition XML parameters:

request_poll_delete_condition XML parameters
172
The following table describes request_poll_delete_condition XML parameters:
response_delete_condition.

response_poll_delete_condition XML parameters
status Description of message content (OK or EXEC). String.
response_data See response_data_XML parameters (on page 173)
response_data_XML parameters
The following figure describes the response_data_XML parameters:
173
The following table describes response_data XML parameters:

XML parameters for fault_delete_condition and fault_poll_delete_condition, as well as a sample fault
response are described in Fault Response (on page 70).
Errors
See Add or Delete Condition request errors (Major code 404) (on page 283).
Examples
Successful example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_delete_condition
<ctmem:condition>
</ctmem:condition>
</ctmem:request_delete_condition>
</SOAP-ENV:Body>
174
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_delete_condition
</ctmem:response_delete_condition>
</SOAP-ENV:Body>
Polling request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_poll_delete_condition
</ctmem:request_poll_delete_condition>
</SOAP-ENV:Body>
Polling response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_poll_delete_condition
</ctmem:response_poll_delete_condition>
</SOAP-ENV:Body>
175
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:condition>
<ctmem:name>INEXISTENT_COND_NAME</ctmem:name>
</ctmem:condition>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_delete_condition
</ctmem:response_delete_condition>
</SOAP-ENV:Body>
176
Polling request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_poll_delete_condition
</ctmem:request_poll_delete_condition>
</SOAP-ENV:Body>
Polling response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_poll_delete_condition
<ctmem:error_list
<ctmem:error_message>Cannot delete
condition, does not exist.
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_poll_delete_condition>
</detail>
</SOAP-ENV:Fault>
177
</SOAP-ENV:Body>
Job actions in active jobs database

Performs actions on jobs that are currently in the active jobs database. This request type allows the following
job actions in active jobs for a single job:
 Hold (on page 178)
 Free (on page 181)
 Confirm (on page 184)
 Kill (on page 189)
 Kill (on page 189)
 Set to OK (on page 191)
These requests are asynchronous. The immediate response will indicate if the action request is sent (or not
sent to Control-M). In case the request is successfully sent to Control-M, the response will contain a response
token. The returned response token can be used to get the final response using the existing polling request.
Hold
Request parameters
request_aj_hold XML parameters
178
The following table describes request_aj_hold XML parameters:
control_m Control-M installation to which the job belongs. String. Mandatory.
order_id Order ID of the job. String. Mandatory.
Response parameters
response_aj_hold XML parameters
The following table describes the response_aj_hold XML parameters:
status The status of the response
response_token Used in a polling request
179

request_poll_aj_hold XML parameters
The following table describes request_poll_aj_hold XML parameters:
response_token Limits the number of returned entities.

response_poll_aj_hold XML parameters
180
The following table describes response_poll_aj_hold XML parameters:

Valid values:
 OK
 EXEC

XML parameters for fault_aj_hold and fault_poll_aj_hold, as well as a sample fault response are described in
Fault Response (on page 70).
Free
Request parameters
request_aj_free XML parameters
181
The following table describes request_aj_free XML parameters:
Response parameters
response_aj_free XML parameters
The following table describes response_aj_free XML parameters:
status The status of the response.

request_poll_aj_free XML parameters
182
The following table describes request_poll_aj_free XML parameters:

response_poll_aj_free XML parameters
The following table describes response_poll_aj_free XML parameters:

Valid values:
 OK
 EXEC

XML parameters for fault_aj_free and fault_poll_aj_free, as well as a sample fault response are described in
183
Confirm
Request parameters
request_aj_confirm XML parameters
The following figure describes autoedit_assignment XML parameters
The following table describes the request_aj_confirm XML parameters
Response parameters
184
The following table describes response_aj_confirm XML parameters

The following table describes the request_poll_aj_confirm XML parameters:

185
The following table describes response_poll_aj_confirm XML parameters:

Valid values:
 OK
 EXEC

XML parameters for fault_aj_confirm and fault_poll_aj_confirm, as well as a sample fault response are
Rerun
Request parameters
186
The following table describes request_aj_rerun XML parameters:
Response parameters
The following table describes response_aj_rerun XML parameters:

187
The following table describes request_poll_aj_rerun XML parameters:

The following table describes response_poll_aj_rerun XML parameters:

Valid values:
 OK
 EXEC

XML parameters for fault_aj_rerun and fault_poll_aj_rerun, as well as a sample fault response are described
in Fault Response (on page 70).
188
Kill
Request parameters
The following table describes request_aj_kill XML parameters:
Response parameters
189
The following figure describes response_aj_kill XML parameters:

The following figure describes request_poll_aj_kill XML parameters:
The following table describes request_poll_aj_kill XML parameters:

response_poll_aj_kill XML parameters
190
The following table describes response_poll_aj_kill XML parameters:

Valid values:
 OK
 EXEC

XML parameters for fault_aj_kill and fault_poll_aj_kill, as well as a sample fault response are described in
Set to OK
Request parameters
request_aj_force_ok XML parameters
191
The following table describes request_aj_force_ok XML parameters:
Response parameters
response_aj_force_ok XML parameters
The following table describes response_aj_force_ok XML parameters:
192

request_poll_aj_force_ok XML parameters
The following table describes request_poll_aj_force_ok XML parameters:

response_poll_aj_force_ok XML parameters
193
The following table describes response_poll_aj_force_ok XML parameters:

Valid values:
 OK
 EXEC

XML parameters for fault_aj_force_ok and fault_poll_aj_force_ok, as well as a sample fault response are
Errors
See Job actions request errors (Major code 450) (on page 290).
Examples
Successful example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_aj_free
</ctmem:request_aj_free>
</SOAP-ENV:Body>
194
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_aj_free
</ctmem:response_aj_free>
</SOAP-ENV:Body>
Polling request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_polling_aj_free
</ctmem:request_polling_aj_free>
</SOAP-ENV:Body>
Polling response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_polling_aj_free
195
</ctmem:response_polling_aj_free>
</SOAP-ENV:Body>
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_aj_hold
<ctmem:order_id>unknown</ctmem:order_id>
</ctmem:request_aj_hold>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_aj_hold
<ctmem:error_list
<ctmem:error_message>Internal Error:
Order ID not Found...
196
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_aj_hold>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Job tracking
Tracks the progress of existing jobs in the Control-M installation.
Request parameters
request_job_track XML parameters
The following table describes request_job_track XML parameters:
jobs A sequence of job. See condition job XML parameters (on page 198).
197
condition job XML parameters

The following table describes job XML parameters:
Response parameters
response_job_track XML parameters
198
The following table describes response_job_track XML parameters:
status Describes the condition of the element that contains it. String.
status is a descriptive element in the response and job elements.
jobs A sequence of job. See:job XML parameters (on page 199)
job XML parameters

job XML parameters
A sequence of job_data. See:job_data XML parameters (on page 200)
199

The following table describes job_data XML parameters:
control_m String.
order_id Serial number assigned to the job by the Control-M installation. String.
job_status Execution status of the job. String.

Valid values are:
 Ended OK
 Ended not OK
 Executing
 Wait Condition
 Wait Resource
 Wait User
 Not in AJF
 Unknown
state_digits Serial number identifying the current job state.
order_date Original Scheduling date of the job. String.
200

fault_job_track
The following table describes fault_job_track XML parameters:
jobs A sequence of job.
error_list A sequence of error. See:Fault Response (on page 70).
error_list attribute: highest_severity Indicates the severity level of the most

critical error included in the error list. If
only one error is included, the severity
for that error is displayed. String.
job XML parameters

201
job_data A sequence of job.
error_list A sequence of error. See:Fault Response (on page 70).
error_list attribute: highest_severity Indicates the severity level of the most

critical error included in the error list. If
only one error is included, the severity
for that error is displayed. String.
Errors
See Job tracking request errors (Major code 406) (on page 284).
Examples
Successful Example (tracking single job)
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_job_track
<ctmem:jobs>
<ctmem:job>
<ctmem:order_id>013ic</ctmem:order_id>
</ctmem:job>
</ctmem:jobs>
</ctmem:request_job_track>
</SOAP-ENV:Body>
202
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_job_track
<ctmem:jobs>
<ctmem:job>
<ctmem:job_data>
<ctmem:job_status>Ended
OK</ctmem:job_status>
<ctmem:state_digits>000030000000</ctmem:state_digits>
<ctmem:odate>050711</ctmem:odate>
</ctmem:job_data>
</ctmem:job>
</ctmem:jobs>
</ctmem:response_job_track>
</SOAP-ENV:Body>
Failure Example (tracking single job)
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
203
<ctmem:jobs>
<ctmem:job>
<ctmem:order_id>013xc</ctmem:order_id>
</ctmem:job>
</ctmem:jobs>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP:Server</faultcode>
<faultstring>Error response from EM Server</faultstring>
<detail>
<ctmem:fault_job_track
<ctmem:jobs>
<ctmem:job>
<ctmem:job_data>
</ctmem:job_data>
<ctmem:error_list
<ctmem:error_message>
Job was not found in the last
AJF.
</ctmem:error>
204
</ctmem:error_list>
</ctmem:job>
</ctmem:jobs>
<ctmem:error_message>Errors in
request.</ctmem:error_message>
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_job_track>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Successful Example (tracking multiple jobs)
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:jobs>
<ctmem:job>
</ctmem:job>
<ctmem:job>
<ctmem:order_id>006b2</ctmem:order_id>
</ctmem:job>
<ctmem:job>
205
</ctmem:job>
</ctmem:jobs>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:jobs>
<ctmem:job>
<ctmem:job_data>
</ctmem:job_data>
</ctmem:job>
<ctmem:job>
<ctmem:job_data>
<ctmem:job_status>Wait
Resource</ctmem:job_status>
206
</ctmem:job_data>
</ctmem:job>
<ctmem:job>
<ctmem:job_data>
<ctmem:order_id>012qh</ctmem:order_id>
</ctmem:job_data>
</ctmem:job>
</ctmem:jobs>
</SOAP-ENV:Body>
Failure Example (tracking multiple jobs)
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:jobs>
<ctmem:job>
</ctmem:job>
207
<ctmem:job>
</ctmem:job>
<ctmem:job>
</ctmem:job>
</ctmem:jobs>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:status>PARTIAL_SUCCESS</ctmem:status>
<ctmem:jobs>
<ctmem:job>
<ctmem:job_data>
</ctmem:job_data>
</ctmem:job>
<ctmem:job>
208
<ctmem:job_data>
<ctmem:job_status>Wait
Resource</ctmem:job_status>
</ctmem:job_data>
</ctmem:job>
<ctmem:job>
<ctmem:job_data>
</ctmem:job_data>
<ctmem:error_list
Job was not found in the last AJF.
</ctmem:error>
</ctmem:error_list>
</ctmem:job>
</ctmem:jobs>
</SOAP-ENV:Body>
209
Retrieve jobs in the active jobs database

The following section describes how to retrieve jobs in the active jobs database.Jobs are searched in the All
Jobs collection in GUI Server memory. If the PinAllJobsCollection system parameter is turned on, the All Jobs
collection is loaded into memory at the start up of the GUI Server. If the PinAllJobsCollection is turned off, the
request causes the All Jobs collection to be loaded into GUI Server memory, which may affect the
performance and response time.
The EMAPIActiveJobsLoadLimit system parameter controls the number of jobs in the active jobs database
that are checked by the GUI Server when processing the request_act_retrieve_jobs request, and included in
the request response. It is possible to limit the number of returned jobs on the client side by specifying the
max_returned_nodes parameter in the request. The value of the max_returned_nodes parameter should not
exceed the value of the EMAPIActiveJobsLoadLimit system parameter.
If the value of the max_returned_nodes parameter exceeds the value of the EMAPIActiveJobsLoadLimit
system parameter, a fault response is returned.
For more information about the PinAllJobsCollection and EMAPIActiveJobsLoadLimit system parameters, see
system parameters in Control-M Workload Automation Administration.
Request parameters
request_act_retrieve_jobs XML Parameters
210
The following table describes request_act_retrieve_jobs XML Parameters:
max_returned_nodes Limits the number of returned entities. Optional.

Should not exceed the value of the EMAPIActiveJobsLoadLimit system
parameter.
retrieve_jobs_criterion Retrieve jobs criteria wrapper. String. Consists of include and exclude filters that
allow specifying items to include with or exclude from the retrieve criteria, as
described in retrieve_jobs_criterion (on page 211).
retrieve_jobs_criterion
The following table describes retrieve_jobs_criterion XML parameter:s
include Mandatory. Include filter definitions criteria wrapper. For more information, refer
include and exclude XML parameters (on page 212)
exclude Optional. Exclude filter definitions criteria wrapper. For more information, refer
include and exclude XML parameters (on page 212)
211
include and exclude XML parameters

The following table describes include and exclude XML parameters:
search_criterion String. Search criteria wrapper that consists of a sequence of param elements. At
least one search_criterion element must appear under the include element. The
amount of search_criterion elements is unbounded. The relationship between
search_criterion elements in one filter is OR. For a description of param, see
Search_criterion XML parameter (on page 212) table.
Search_criterion XML parameter

The following table describes search_criterion XML parameter:
param Search criteria parameter wrapper. String. Parameters used to build the search
criteria. At least one param element should appear under a search_criterion
element. The amount of param elements is unbounded. The relationship between
param elements in the same search_criterion is AND.
212
param XML parameters

The following figure describes the param XML parameters:
The following table describes the param XML parameters:
name Mandatory. Name of the retrieve active job parameter used as a search criteria.
String. For a list of valid values for the name parameter, refer to Table 136.
operator Operator used in search criteria. String.

Valid values:
 EQ
 NE
 LT
 GT
 LIKE
value Value used in search criteria. Any valid value of a job parameter. Wildcards and
search patterns can be used in combination with LIKE operator. String. Mandatory.
213
Valid name parameter values

The following table describes Valid name parameter values:
ORDER_ID Order ID of the job to be retrieved. String. Mandatory
DATA_CENTER The data center to which the job belongs.
APPLICATION Name of the application to which the job’s group belongs.
APPL_TYPE The external application on which the job runs.
GROUP_NAME Name of the group to which the job belongs.
MEMNAME Name of the file that contains the job script.
JOB_NAME Name of the job.
TASK_TYPE Type of the job (task) to be performed by Control-M. Valid values:

 Job
 Command
 Dummy
 Detached
 External
 SMART Folder
 Sub-folder
Control-M for z/OS:
 Job
 Started Task
 SMART Folder
 Cyclic Job
 Emergency Job
 Emergency Cyclic Job
 Cyclic Task
 Emergency Task
 Emergency Cyclic Task
214
CRITICAL When selected, resources for the job are reserved exclusively for that job as they
become available. When all necessary resources are available, the job is executed.
CYCLIC If selected, indicates that the current job is cyclic (it should be rerun at specified
intervals).
Emergency Control-M for z/OS:

Indicates that the current job or started task is an emergency job or started task.
Part_of_BIM_service Indicates if the job is included in a Business Service.
STATUS The job execution status.
Ended Job ended. Valid values are:

 True
 False
Ended_Not_OK Job ended unsuccessfully.Valid values are:

 True
 False
Ended_OK Job ended successfully. Valid values are:

 True
 False
Late Job ended late.Valid values are:

 True
 False
Held Job was held. Valid values are:

 True
 False
DELETE_FLAG Job was deleted. Valid values are:

 True
 False
215
Requested Job was requested. Valid values are:

 True
 False
Run As User User (user ID) on whose behalf the job is executed. This parameter is used by the
Control-M security mechanism.
HOSTGROUP Name of the host or host group on which following iterations of a job is run.
This parameter does not apply to MVS jobs.
DESCRIPTION A description of the job.
Order_DATE The order date of the job.
AVG_RUNTIME The average runtime of the job.
START_TIME The start time of the job.
END_TIME The end time of the job.
Incond Name The name of the in-condition.
Incond Date The date of the in-condition.
Outcond Name The name of the out-condition.
Outcond Date The date of the out-condition.
Quant Res The name of the quantitative resource.
Control Res The name of the control resource.
RBA Relative block address (RBA). String.
216
Response parameters
response_act_retrieve_jobs XML parameters
retrieved_nodes_number Number of retrieved nodes.
jobs A sequence of job_data. For more information, refer to job_data XML

Parameters Description (on page 225)

XML parameters for fault_act_retrieve_jobs, as well as a sample fault response are described in Fault
Errors
See Retrieve active jobs request errors (Major code 440) (on page 289).
Examples
Successful example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_act_retrieve_jobs
217
<ctmem:max_returned_nodes>1000</ctmem:max_returned_nodes>
<ctmem:retrieve_jobs_criterion>
<ctmem:include>
<ctmem:param>
</ctmem:param>
<ctmem:param>
<ctmem:name>ODATE</ctmem:name>
<ctmem:value>060625</ctmem:value>
</ctmem:param>
</ctmem:include>
<ctmem:exclude>
<ctmem:param>
<ctmem:name>DATA_CENTER</ctmem:name>
<ctmem:operator>NE</ctmem:operator>
<ctmem:value>ctm630</ctmem:value>
</ctmem:param>
<ctmem:param>
<ctmem:name>APPLICATION</ctmem:name>
<ctmem:value>AJMN</ctmem:value>
</ctmem:param>
<ctmem:param>
<ctmem:name>APPLICATION</ctmem:name>
218
<ctmem:value>FullJobs</ctmem:value>
</ctmem:param>
</ctmem:exclude>
</ctmem:retrieve_jobs_criterion>
</ctmem:request_act_retrieve_jobs>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_act_retrieve_jobs
<ctmem:retrieved_nodes_number>3
</ctmem:retrieved_nodes_number>
<ctmem:jobs>
<ctmem:job>
<ctmem:job_data>
<ctmem:rba>00023e</ctmem:rba>
<ctmem:table_rba>000000</ctmem:table_rba>
<ctmem:application_type>OS</ctmem:application_type>
<ctmem:mem_name> </ctmem:mem_name>
<ctmem:mem_lib> </ctmem:mem_lib>
<ctmem:order_table> </ctmem:order_table>
219
<ctmem:description></ctmem:description>
<ctmem:task_type>Command</ctmem:task_type>
<ctmem:time_zone> </ctmem:time_zone>
<ctmem:in_BIM_service>0</ctmem:in_BIM_service>
<ctmem:job_status>Wait Resource
</ctmem:job_status>
<ctmem:job_state> </ctmem:job_state>
<ctmem:otime>20060625115417</ctmem:otime>
<ctmem:next_time> </ctmem:next_time>
<ctmem:rerun_counter>00000</ctmem:rerun_counter>
<ctmem:average_runtime>000000</ctmem:average_runtime>
<ctmem:start_time> </ctmem:start_time>
<ctmem:end_time> </ctmem:end_time>
<ctmem:critical>0</ctmem:critical>
<ctmem:cyclic>False</ctmem:cyclic>
<ctmem:emergency>False</ctmem:emergency>
</ctmem:job_data>
</ctmem:job>
<ctmem:job>
<ctmem:job_data>
<ctmem:order_id>0023d</ctmem:order_id>
<ctmem:rba>00023d</ctmem:rba>
<ctmem:application>apiWinApp2</ctmem:application>
<ctmem:application_type>
</ctmem:application_type>
<ctmem:group>apiGroup2</ctmem:group>
<ctmem:job_name>apitest2</ctmem:job_name>
220
<ctmem:mem_name>apiMemName2</ctmem:mem_name>
<ctmem:mem_lib>d:<OWNER>controlm</ctmem:mem_lib>
<ctmem:order_table>apitest</ctmem:order_table>
<ctmem:owner> </ctmem:owner>
<ctmem:description>
</ctmem:description>
<ctmem:task_type>Job </ctmem:task_type>
<ctmem:in_BIM_service>0
</ctmem:in_BIM_service>
<ctmem:job_status>Wait Resource
</ctmem:job_status>
<ctmem:job_state> </ctmem:job_state>
<ctmem:start_time> </ctmem:start_time>
<ctmem:end_time> </ctmem:end_time>
</ctmem:job_data>
</ctmem:job>
<ctmem:job>
<ctmem:job_data>
<ctmem:order_id>0023c</ctmem:order_id>
<ctmem:rba>00023c</ctmem:rba>
221
<ctmem:application>apiWinApp1</ctmem:application>
<ctmem:application_type>
</ctmem:application_type>
<ctmem:group>apiGroup1 </ctmem:group>
<ctmem:job_name>apitest1</ctmem:job_name>
<ctmem:mem_name>apiMemName1</ctmem:mem_name>
<ctmem:mem_lib> </ctmem:mem_lib>
<ctmem:order_table>apitest</ctmem:order_table>
<ctmem:description>
</ctmem:description>
<ctmem:task_type>Dummy </ctmem:task_type>
<ctmem:in_BIM_service>0</ctmem:in_BIM_service>
<ctmem:job_state>Run (2)</ctmem:job_state>
<ctmem:start_time>20060625113441</ctmem:start_time>
<ctmem:end_time>20060625113441</ctmem:end_time>
</ctmem:job_data>
</ctmem:job>
222
</ctmem:jobs>
</ctmem:response_act_retrieve_jobs>
</SOAP-ENV:Body>
Failure example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_act_retrieve_jobs
<ctmem:max_returned_nodes>1000</ctmem:max_returned_nodes>
<ctmem:retrieve_jobs_criterion>
<ctmem:include>
<ctmem:param>
</ctmem:param>
</ctmem:include>
</ctmem:retrieve_jobs_criterion>
</ctmem:request_act_retrieve_jobs>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
223
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_act_retrieve_jobs
<ctmem:error_list
Partial result.
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_act_retrieve_jobs>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
224
job_data XML Parameters Description

The following table describes job_data XML Parameters:
application Name of the application to which the job’s application belongs.
application_type Indicates the external application on which the job to be retrieved runs.
sub application The sub application to which the retrieved job belongs.
job_name The name of the job.
file_name The name of the file that contains the job script.
file_path The name of the path that contains the retrieved job file.
order_folder Default or dummy folder to which you indicate the job belongs. A folder is not
necessary because jobs that are created with Control-M/EM Web Services API are
inserted directly into Active Jobs database. However, you may want to include a
value for this parameter so that the job can be tracked during statistical analysis
that uses folder as a criterion.
order_library Default or dummy folder library in which folder documentation is said to be stored.
A folder (and, by extension, a folder library) are not necessary because jobs that
are created with the Control-M/EM Web Services API are inserted directly into
Active Jobs databse. However, you may want to include a value for this parameter
so that the job can be tracked during statistical analysis that uses Folder or Folder
Library as criteria. This parameter is specified only for z/OS jobs for which the
order_folder element was also specified.
Run As User User (user ID) on whose behalf the job is executed. This parameter is used by the
Control-M security mechanism.
description A description of the job.
225
task_type Type of the job (task) to be performed by Control-M. Valid values:

 Job
 Command
 Dummy
 Detached
 External
 SMART Folder
 Sub-folder
Control-M for z/OS:
 Job
 Started Task
 SMART Folder
 Cyclic Job
 Emergency Job
 Emergency Cyclic Job
 Cyclic Task
 Emergency Task
 Emergency Cyclic Task
time_zone Indicates the time zone according to which the job was scheduled.
in_BIM_service Indicates if the job is included in Business Service.
job_status Name of the job. String. Valid values are:

 Ended OK
 Ended not OK
 Executing
 Wait Condition
 Wait Resource
 Wait User
 Not in AJF
 Unknown
226
job_state Indicates the job state, such as Held, Deleted, or Restarted.
state_digits Serial number identifying the current job state.
otime Order time of the job. String.

This parameter only applies to jobs run on Control-M/Server for Distributed
Systems 6.3.0x or Control-M for z/OS 6.2.xx and above.
next_time Indicates the next expected submission time for the job. For reruns or cyclic jobs
that use the Interval option. For Control-M for z/OS jobs, only the time can be
specified. For all other jobs, the time and the date can be specified.
rerun_counter Number of times the job has been rerun.
average_runtime Average time (in minutes) for the job to run. The field displays the runtime statistic
generated by the latest run of the CTMJSA utility (which generates a statistic based
on the last successful runs of the job).
start_time Date and time the job began executing.
end_time Date and time the job finished executing.
critical When selected, resources for the job are reserved exclusively for that job as they
become available. When all necessary resources are available, the job is executed.
cyclic If selected, indicates that the current job is cyclic (it should be rerun at specified
intervals).
emergency Control-M for z/OS only:

Indicates that the current job or started task is an emergency job or started task.
rba Relative block address (RBA). String.
folder_rba RBA of job’s SMART Folder entity.
time_from Submit job from the defined time
time_until Submit job until the defined time.
227
Change alert status

Changes the status (for example, from not_noticed to handled) of an alert.
Request parameters
request_change_alert_status XML parameters
The following table describes request_change_alert_status XML parameters:
alert_id The ID number of the alert. String. For more information on monitoring and
handling alerts, see Using Control-M Workload Automation.
status Required status for the specified alert.

Valid values:
 notice
 unnotice
 handle
 unhandle
228
Response parameters
response_change_alert_status XML parameters
The following table describes response_change_alert_status XML parameters:

XML parameters for the fault_change_alert_status, as well as a sample fault response are described in Fault
Errors
See Alerts request errors (Major code 408) (on page 285).
Examples
Successful example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_change_alert_status
<ctmem:alert_id>359</ctmem:alert_id>
<ctmem:status>notice</ctmem:status>
</ctmem:request_change_alert_status>
</SOAP-ENV:Body>
229
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_change_alert_status
</ctmem:response_change_alert_status>
</SOAP-ENV:Body>
Failure Example 1
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
230

<detail>
<ctmem:fault_change_alert_status
<ctmem:error_list
Alert id is not valid.
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_change_alert_status>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Failure Example 2
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
</SOAP-ENV:Body>
231
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<detail>
<ctmem:fault_change_alert_status
<ctmem:error_list
ctmem:highest_severity="Warning">
ctmem:minor="7" ctmem:severity="Information">
Alert already in desired state.
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_change_alert_status>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Retrieve BIM Services list

Retrieves the list of services active in the Batch Impact Manager Server.
232
Request parameters
request_get_bim_services_info XML parameters
The following table describes request_get_bim_services_info XML parameters:
service_name The name of the service.
Response parameters
response_get_bim_services_info XML parameters
233
The following table describes response_get_bim_services_info XML parameters:
status The status of the BIM service.
services Information regarding the BIM service.
234
bim_services XML parameters

235
The following table describes bim_services XML parameters:
order_date The order date of the service.
service_name The name of the service.
status The status of the service.
due_time The due time of the service.
min_end_time The minimum time required for the service to complete.
description The description of the service
num_jobs The number of jobs contained in the service.
complete_percentage The percentage of jobs completed.
jobs_completed The number of jobs completed.
jobs_without_stats The number of jobs without statistic information.
time_zone Indicates the time zone according to which the job should be scheduled. When the
value of this parameter is not zero, all dates reported use this time zone.
data_center The data center where the service was ordered.
priority The priority of the service.
min_slack_time In case of a failure, this field indicates how long before the service is late.
status_color Indicates the color of the status. Valid values are:

 Service in process or completed
 Job delay or Job finished early
 Service delay or will not complete
 Service completed late

XML parameters for the get_bim_services_info parameter, as well as a sample fault response are described
in Fault Response (on page 70).
236
Examples
Successful example
Request
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:request_bim_services_info
</ctmem:request_bim_services_info>
</SOAP-ENV:Body>
Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:response_bim_services_info
<ctmem:services>
<ctmem:service>
<ctmem:odate>12:26:07 01/12/2006</ctmem:odate>
<ctmem:service_name>Bim
Service</ctmem:service_name>
<ctmem:status>Service completed</ctmem:status>
<ctmem:due_time>12:29:07
01/12/2006</ctmem:due_time>
<ctmem:min_end_time>12:26:07
01/12/2006</ctmem:min_end_time>
<ctmem:description/>
<ctmem:num_jobs>3</ctmem:num_jobs>
<ctmem:complete_percentage>100</ctmem:complete_percentage>
237
<ctmem:jobs_completed>3</ctmem:jobs_completed>
<ctmem:jobs_without_stats>2</ctmem:jobs_without_stats>
<ctmem:time_zone> GMT +2</ctmem:time_zone>
<ctmem:data_center>palace620</ctmem:data_center>
<ctmem:priority>5</ctmem:priority>
<ctmem:min_slack_time>0</ctmem:min_slack_time>
<ctmem:status_color>Service in process or
completed</ctmem:status_color>
</ctmem:service>
<ctmem:service>
<ctmem:odate>12:22:00 01/12/2006</ctmem:odate>
<ctmem:service_name>Bim
Service</ctmem:service_name>
<ctmem:status>Service is late</ctmem:status>
<ctmem:due_time>12:25:00
01/12/2006</ctmem:due_time>
<ctmem:min_end_time>13:52:08
01/12/2006</ctmem:min_end_time>
<ctmem:description>Job "Service4" should have
started by
12:25:00 GMT+02:00 and will not start on
time. The reason
is: Job is held.</ctmem:description>
<ctmem:num_jobs>3</ctmem:num_jobs>
<ctmem:complete_percentage>33</ctmem:complete_percentage>
<ctmem:jobs_completed>1</ctmem:jobs_completed>
<ctmem:jobs_without_stats>2</ctmem:jobs_without_stats>
<ctmem:time_zone> GMT +2</ctmem:time_zone>
<ctmem:data_center>palace620</ctmem:data_center>
<ctmem:priority>5</ctmem:priority>
<ctmem:min_slack_time>0</ctmem:min_slack_time>
<ctmem:status_color>Service delay or will not
complete</ctmem:status_color>
</ctmem:service>
238
</ctmem:services>
</ctmem:response_bim_services_info>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode> … </faultcode>
<faultstring>…. </faultstring>
<detail>
. . . FAULT_RESPONSE_OF_THE_REQUEST . . .
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
The fault parameters for all requests are described in Fault Response (on page 70).
Fault Response
The following table describes the parameters for fault XML parameters of all requests:
error_list A sequence of error. For a list of the error_list sub parameters see:
Error XML parameters (on page 70).
Fault Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
239
<detail>
<ctmem:fault_def_create_jobs
<ctmem:error_list
Create jobs definitions failed,
inavlid params.
</ctmem:error>
Create jobs definitions validation
error: 'Field: AuthorError: The
field must have a
value'.
</ctmem:error>
</ctmem:error_list>
</ctmem:fault_def_create_jobs>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
240
8
Chapter
8
Advanced features and optimization
Modifying initialization properties
Before using the Control-M/EM API in your project, the API must be initialized (started). The API services are
initialized using the EMXMLInvoker static method, init. This section shows you how to initialize
Control-M/EM API using non-default CORBA ORB properties.
If you intend to use the default initialization properties, you do not need to read Modifying initialization
properties.
CORBA is an architecture and specification for creating, distributing, and managing distributed program
objects in a network. In the Control-M/EM API, CORBA is implemented through the use of JacORB, a
third-party product that brokers requests among the components of distributed applications (acts as
middleware).
The Control-M/EM API init method initializes the CORBA Object Request Broker (ORB) in accordance with
instructions that you (the programmer) supply in the init call.
 The default init prototype, Prototype 1, is called without the need to supply additional parameters or
properties.
 The two additional init prototypes, Prototypes 2 and 3, enable you to specify alternate parameters and
properties for initializing CORBA.
Prototype 1
public static void init ()
Prototype 1 (the default prototype) initializes the CORBA services using a Control-M/EM API-specific CORBA
configuration that was created during the API post-installation configuration (using emapi-configure).
The default init prototype is described in Initializing and stopping the Control-M/EM API services (on page
42).
This CORBA configuration information is contained in the jacorb.properties file located under the
emapi-700\etc directory.
Prototype 2
public static void init(String[] args)
241
Arguments
The args parameter generally contains your command line arguments for the application’s main. This
enables you to control ORB initialization from outside the program.
For a list of CORBA parameters suitable for use in args, see the manufacturer’s documentation.
Code example
public class HelloWorld {
public static void main(String[] args) {
EMXMLInvoker.init(args);
...
}
}
Run example
java HelloWorld -jacorb.implname StandardNS
Prototype 3
public static void init(String[] args, Properties props)
Arguments
The args parameter generally contains your command line arguments for the application’s main. This
enables you to control ORB initialization from outside the program.
For a list of CORBA parameters suitable for use in args, see the manufacturer’s documentation.
Properties
The props parameter (Properties) can contain CORBA parameters, using the same options as in the
command line that was passed as the first parameter (args).
The Properties class is part of the java.util package.
Code example
public class HelloWorld {
public static void main(String[] args) {
Properties props = new Properties();
props.setProperty("jacorb.implname", "StandardNS");
242
EMXMLInvoker.init(args, props);
...
}
}
Run example
java HelloWorld
This run example is used for illustrative purposes. To run it, you must add Java virtual machine
(JVM) parameters and the Control-M/EM API CLASSPATH. These concepts are discussed in
Control-M/EM API Installation (on page 15).
This CORBA configuration information is contained in the jacorb.properties file located in the
emapi-700\etc directory.
By using both values for props and args, you can supply values for props that can be overridden
by values that are supplied for args.
Getting and setting Control-M/EM API properties

The Control-M/EM API properties generally contain the host names of the Control-M/EM GUI Server and the
Global Alert Server (GAS).
Using the getProperties and setProperties methods, you can supply alternate parameters for these
properties. These alternate parameters include, but are not limited to the host names of the Control-M/EM
GUI Server and the GAS.
getProperties
The getProperties method returns the properties object that you specified with the setProperties method.
If you have not set the Control-M/EM API properties using setProperties, using getProperties returns the
properties object containing the values in the ctmem.properties file under your project\application
working directory.
Each call to getProperties reads the ctmem.properties file. Any modifications made to this file while the
application is running affect subsequent calls to getProperties.
243
Prototype
public Properties getProperties();
The Control-M/EM API default parameter properties are described in the following table (these parameters
were specified in the ctmemapi.properties file during configuration of the Control-M/EM API):
com.bmc.ctmem.emapi.GSR.hostname Set to the hostname of the Control-M/EM GUI

Server.
com.bmc.ctmem.emapi.GAS.hostname Set to the hostname of the Global Alerts

Server.
com.bmc.ctmem.emapi.XMLDATAPATH Set to the location of the XML schema.
setProperties
Use setProperties to modify the values of the Control-M/EM API properties. All subsequent calls to
getProperties return the Properties object that you specified with setProperties.
Prototype
public void setProperties(Properties props);
If the Control-M/EM API receives Properties that do not contain the parameters described in Table 146, the
localhost value is used in their place. It is recommended that you supply parameter values for the
Control-M/EM servers that are being used.
Example
In this example, setProperties is called before the Control-M/EM API is used. As a result, the
Control-M/EM API does not read the properties from the ctmem.properties file.
{
props.setProperty("com.bmc.ctmem.emapi.GSR.hostname", "comp1");
props.setProperty("com.bmc.ctmem.emapi.GAS.hostname", "comp2");
EMXMLInvoker.setProperties(props);
...
// From this point forward, any new instance of EMXMLInvoker will work
with comp1 for the GUI Server and with comp2 for GAS
}
244
Polling interval timeout configuration

Requests that are sent using the EMBasicXMLInvoker class are polled automatically with default polling
values. Poll requests are sent every five seconds until a reply is received.
It may be desirable to tailor these polling values to your network capabilities.
You can modify the number and frequency of poll requests that are sent using the
setPollRequestIntervalMilli and setPollRequestTimeoutMilli methods.
setPollRequestIntervalMilli and setPollRequestTimeoutMilli are methods of the EMBasicXMLInvoker class.
They are not included in the EMXMLInvoker class.
If you do not intend to use the EMBasicXMLInvoker class, you do not need to read this section.
The total number of times that polling is conducted is a function of the values determined by the
setPollRequestIntervalMilli and setPollRequestTimeoutMilli methods and the amount of time that
each poll request takes.
Example
The total amount of time for polling is set at 10,000 milliseconds (10 seconds), using the
setPollRequestTimeoutMilli method.
The time between poll requests is set at 2000 milliseconds (2 seconds), using the
setPollRequestintervalMilli method.
Each polling request takes about 500 milliseconds (0.5 seconds).
10,000 / (2000 + 500) = 4 poll requests
setPollRequestIntervalMilli
The setPollRequestIntervalMilli method determines the time, in milliseconds, between poll requests.
This time is measured from the end of the current poll request. The actual time that it takes to carry out the
polling request is taken into account.
Prototype
public void setPollRequestIntervalMilli(final long timeout)
Default: 5000 milliseconds (5 seconds)
setPollRequestTimeoutMilli
The setPollRequestTimeoutMilli method determines the total time, in milliseconds, that is allotted for
polling for a response to a request.
245
Prototype
public void setPollRequestTimeoutMilli(final long timeout)
Default: -1 milliseconds. The -1 value indicates that polling is carried on until a response is received. There
is no timeout value.
246
9
Chapter
9
Diagnostics and troubleshooting
This chapter helps you to analyze the Control-M/EM API product’s performance and prevent conflicts before
they arise.
Control-M/EM API logging

The Control-M/EM API logs actions, exceptions, and warnings. The logging mechanism uses the Log4J library
from the Jakarta Java Solutions project. The manifest file located at
emapi-version\classes\log4j-1.2.8.jar indicates which version of Log4J is in use.
You can modify the logging procedures if you want to enable greater control over logging behavior. For more
information, see Modifying logging behavior (on page 247) and the Log4J documentation.
Default logging behavior

The Control-M/EM API logging default behavior has the following characteristics:
 The Control-M/EM API logs only errors (priority level: ERROR).
 The maximum log file size is 50 KB.
 The Control-M/EM API saves the last two completed logs.
 Log files are rolling, not cyclical.
Modifying logging behavior

Log default settings are coded into the Control-M/EM API product. These settings can be overridden by
values supplied from an outside source. You can supply additional parameters to extend logging capabilities.
You can modify the logging procedure in either of two ways:
 Create a file called emapi.log.cfg in the working directory of your application or project. When this file is
present, the Control-M/EM API automatically passes the information contained in the file to Log4J.
Sample log configuration file (on page 248) shows a sample configuration file.
 Use your own code to pass information to Log4J. The Control-M/EM API uses the
com.bmc.ctmem.emapi logging category to log data.
Logging parameters
Any logging configuration information that you enter in the emapi_log.cfg file or in your project code must
conform to Log4J specifications (as described in the Log4J documentation).
247
Log message priorities

If you are modifying logging behavior, you need to indicate the priority of messages recorded in the log in
your configuration file. The following table describes the message priority levels supported by Log4J. The
table orders the levels from the most critical to the least critical.
Each setting includes messages of that level plus the more critical levels.
The following table describes Priority levels for log messages:
Level Description
FATAL displays fatal error messages
ERROR displays messages for fatal and non-fatal errors
WARN displays warning messages and all error messages
INFO displays system information, warnings, and all errors
DEBUG displays debugging information and all other priority messages
Sample log configuration file

The following example shows a sample log configuration file that contains common attributes.
emapi_log.cfg file example with default parameters
log4j.rootLogger=ERROR
log4j.category.com.bmc.ctmem.emapi=ERROR, EMAPI_Appender
# set appender for EM/API
log4j.appender.EMAPI_Appender=org.apache.log4j.RollingFileAppender
log4j.appender.EMAPI_Appender.file=emapi_log_file
log4j.appender.EMAPI_Appender.append=true
log4j.appender.EMAPI_Appender.maxFileSize=10kb
log4j.appender.EMAPI_Appender.maxBackupIndex=2
log4j.appender.EMAPI_Appender.layout=org.apache.log4j.SimpleLayout
log4j.rootLogger=ERROR sets the priority of the root category to ERROR. If your project code
uses the Log4J library, the root category determines the highest overall priority of log messages.
The second line defines an appender for a specified category. The category can have multiple
appenders. The appender that is defined here is assigned a logging priority.
The appender is EMAPI_Appender.
The category is com.bmc.ctmem.emapi.
The logging priority is ERROR.
248
The remaining lines of the example define the properties of the appender, EMAPI_Appender.
The valid properties depend on the type of appender that is being defined.
This example illustrates a RollingFileAppender that has the properties discussed in the following
table.
RollingFileAppender example properties
Code Description
file=emapi.log Indicates that the log output file is named emapi.log
append=true Indicates that new information is added to the end of the log file
maxFileSize=50kb Indicates that the maximum file of the log file is 50 KB
maxBackupIndex=2 Indicates the number of backups made (that is, the number of old
log files saved)
layout=org.apache.log4j. indicates the format for entries to the log file

SimpleLayout
Environment configuration troubleshooting

Modifications or omissions in the environment configuration can cause the Control-M/EM API to malfunction.
This section discusses the following problems and their solutions:
 CLASSPATH: missing libraries or directories (on page 249)
 Java virtual machine parameters (on page 250)
 Incompatible object argument for a function call (on page 251)
CLASSPATH: missing libraries or directories

Problem
Null exception at some point during runtime.
Possible cause
Some Control-M/EM API directories, .jar libraries, or library locations might be missing from your application
class path (CLASSPATH).
249
Solution
Ensure that the following files and directories are in the class path:
 fullPath/emapi-700/classes/log4j-1.2.8.jar
 fullPath/emapi-700/classes/emapi.jar
 fullPath/emapi-700/classes/jbcl.jar
 fullPath/emapi-700/classes/jacorb.jar
 fullPath/emapi-700/classes/concurrent-1.3.2.jar
 fullPath/emapi-700/classes/logkit-1.2.jar
 fullPath/emapi-700/classes/commons-codec-1.3.jar
 fullPath/emapi-700/classes/avalon-framework-4.1.5.jar
 fullPath/emapi-700/classes/antlr-2.7.2.jar
 fullPath/emapi-700/classes/xercesImpl.jar
 fullPath/emapi-700/classes/xml-apis.jar
 fullPath/emapi-700/etc
 fullPath/emapi-700/etc/jacorb.properties
Java virtual machine parameters

Problem
Your application fails during init initialization or when the invoke method is first used.
Possible cause
There is an error in the virtual machine’s configuration parameters.
Solution
Check the log file for a message similar to the following message:
ERROR - resolve naming service failed during initial reference:
org.omg.CORBA.COMM_FAILURE: minor code: 1398079490 completed: No
at com.sun.corba.se.internal.iiop.IIOPConnection.writeLock(Unknown Source)
If you received an org.omg.CORBA.COMM_FAILURE exception, and the exception was thrown from the
com.sun.corba.se.internal.iiop package, you probably did not specify to the virtual machine that it must
use the JacORB (CORBA) implementation (in place of the Sun default implementation).
You must specify to the Java virtual machine that it must use the CORBA implementation.
Use one of the following methods:
250
Method 1
Run the java command from the project working directory, using the following parameters:
java -Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB
-Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton
projectAppName
projectAppName is the executable file of your project.
Method 2
1. Create a file containing the following text:
org.omg.CORBA.ORBClass=org.jacorb.orb.ORB
org.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton
2. Save the file with the name orb.properties in one of the following directories:
• If you are using JDK, use JDK_HOME/jre/lib
• If you are using JRE, use JRE_HOME/lib
Method 3
Call the init method by using the properties illustrated in the following code example (assuming that args is
your application command-line arguments).
props.setProperty("org.omg.CORBA.ORBClass",
"org.jacorb.orb.ORB");
props.setProperty("org.omg.CORBA.ORBSingletonClass",
"org.jacorb.orb.ORBSingleton");
EMXMLInvoker.init(args, props);
Alternatively, call the init method without any parameters.
Incompatible object argument for a function call

Problem
Calls fail when using EMBasicXMLInvoker, but succeed when using EMXMLInvoker.
Possible cause
Irrelevant libraries in the application class path (CLASSPATH) conflict with libraries that are required by the
Control-M/EM API. For example, a newer or older version of the APACHE Xerces Parser might be found in the
CLASSPATH.
251
Solution
Use one of the following solutions:
 Use the smallest set of classes possible when running the API. Doing so prevents your project from
finding irrelevant products and libraries in the CLASSPATH.
 Ensure that the you have listed the required libraries first in the CLASSPATH so that they are found first.
Application runtime and communication troubleshooting

Communication with Control-M/EM server components is essential to the operation of the Control-M/EM API.
A disruption in communication can cause an exception to be thrown.
This section discusses the following problems and their solutions:
 An exception is thrown by the invoke method (on page 252)
 An error occurs when an XML file is submitted. (on page 253)
 Application cannot be started (on page 254)
An exception is thrown by the invoke method

Problem
An exception is thrown when you use the invoke method.
Possible cause 1
The Control-M/EM API cannot communicate with the CORBA Naming Service for one of the following
reasons:
 The CORBA services are down.
 The Naming Service host name and port settings in the jacorb.properties file are incorrect. You can
find the corbaloc reference by searching for the following string: ORBInitRef.NameService.
Solution
Ensure that the following requirements are met:
 The CORBA Naming Service is running (started) on the CORBA Server host computer.
 The Naming Service host name and port settings in the jacorb.properties file point to the computer
that hosts the CORBA Server that you are using.
252
Possible cause 2
Communication cannot be established with the Control-M/EM GUI Server or Global Alerts Server for one of
the following reasons:
 Host names of the GUI Server or the Global Alerts Server are incorrect in the ctmemapi.properties file.
 Host names of the GUI Server or the Global Alerts Server were specified with incorrect values in the code.
Solution
Ensure that the following requirements are met:
 The Control-M/EM GUI Server is running.
 The host names and ports of the Control-M/EM server components (GUI Server and Global Alerts Server)
are registered correctly in the CORBA Naming Service.
 If you are using more than one CORBA Server, you are currently using the CORBA Server that serves the
Control-M/EM GUI Server and Global Alerts Server to which you are sending Control-M/EM API requests.
An error occurs when an XML file is submitted.

Problem
An error occurs when an XML file is submitted.
Possible cause
The XML file contains characters that the XML standard considers invalid. The following characters are
translated in the XML file as indicated in the following table:
Character Meaning Translate to
< less than <
> greater than >
& ampersand &
" quotation marks "
‘ apostrophe '
ASCII 10 line feed

ASCII 13 carriage return
253
Application cannot be started

Problem
Applications based on Control-M/EM API cannot be started.
Possible cause
Because of Java limitations, applications that use the Control-M/EM API cannot be started when the path of
the directory in which the Control-M/EM API is installed contains spaces or other special characters.
Solution 1
1. Move the Control-M/EM API directory structure to a path that does not contain spaces or special
characters.
2. Reconfigure the Control-M/EM API.
3. If needed, modify the JAVA_HOME and CLASSPATH environment variables.
JAVA_HOME refers to the directory where the Java 2 Runtime Environment (JRE) was installed. The Java
2 SDK (also called the JDK) contains the JRE, but at a different level in the file hierarchy.
EXAMPLE: If the Java 2 SDK or JRE was installed in /ctm_em/user1, JAVA_HOME would be as follows:
If you are using JRE, /ctm_em/user1/jre1.6.x
If you are using SDK, /ctm_em/user1/jdk1.6.x/jre
Solution 2: A workaround
This solution provides an alternate method (one for UNIX and one for Windows) for use with the
Control-M/EM API. If you implement this solution, use this method at all times.
UNIX:
1. Define an alias to bypass the path that contains spaces. The alias should point to the Control-M/EM API
emapi-700 root directory. By using this alias when calling the Control-M/EM API, you can avoid
referring to spaces and special characters that exist in the actual path.
2. After defining the alias, reconfigure the Control-M/EM API so that it uses the new path.
EXAMPLE: If the Control-M/EM API root directory is ctm_em/path with space/emapi-700, use the
following commands to create the alias:
cd ctm_em
ln -s "path with space" pathwithoutspace
cd ctm_em/pathwithoutspace/emapi-700
Reconfigure the Control-M/EM API to reflect the new path.
254
Microsoft Windows:
To avoid referring to spaces and special characters that exist in the actual path of the Control-M/EM API, call
the Control-M/EM API by using the MS-DOS-compatible (short) 8.3-format version of its name. Ensure that
you reconfigure the Control-M/EM API so that it uses the 8.3-format version of its path.
EXAMPLE: Open a new command prompt window.
Change the directory to the Control-M/EM API root directory, referring to the directory by using the
8.3-format version of its name.
If the Control-M/EM API root directory is d:\Program Files\BMC Software\emapi-700, use the
following command:
cd progra~1\bmcsof~1\emapi-700
Reconfigure the Control-M/EM API to reflect the new path.
255
10
Chapter
10
Uninstalling Control-M/EM API
The Control-M/EM API is a self-contained product provided in compressed formats (zip and tar) that can be
extracted to any directory. This chapter explains how to remove previous versions of the Control-M/EM API
from your system.
Every Control-M/EM installation has a directory named emapi under its home directory. This directory
contains dictionary and XML schema files necessary for the functioning of server components. Do not delete
this directory. If you remove this directory by mistake, restore it from a backup.
 To uninstall the Control-M/EM API:
• Delete the Control-M/EM API directory:
o For version 7.0.00: emapi-700
o For versions earlier than 6.1.03: emapi-610
256
11
Chapter
11
Request format examples
This appendix includes one or more examples for each of the more complex requests:
Requests are submitted to the Control-M/EM API as XML-formatted text strings. The text strings can be
saved as plain-text files.
For instructions for how to create request strings and examples of the less complex requests, see
Introduction to Control-M/EM API requests (on page 68).
Add Condition or Delete Condition request

Example 1: Add a condition to a Control-M
An Add Condition request that adds the Cond01 prerequisite condition to the CTM01 Control-M
installation.
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:user_token>$USER_TOKEN$</ctmem:user_token>
<ctmem:control_m>CTM01</ctmem:control_m>
<ctmem:condition>
<ctmem:name>Cond01</ctmem:name>
<ctmem:odate>ODATE</ctmem:odate>
</ctmem:condition>
</SOAP-ENV:Body>
Example 2: Delete a condition from a Control-M

A Delete Condition request that removes the Cond01 prerequisite condition from the CTM01
Control-M installation.
257
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:control_m>CTM01</ctmem:control_m>
<ctmem:condition>
<ctmem:name>Cond01</ctmem:name>
</ctmem:condition>
</SOAP-ENV:Body>
Job Creation request

Example 1: Create a job requiring confirmation
A Job Creation request that creates a single job that performs a command and requires
confirmation to run.
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:control_m>ctm3-omega</ctmem:control_m>
<ctmem:active_job>
<ctmem:job_name>Conf0</ctmem:job_name>
<ctmem:mem_name>Conf0</ctmem:mem_name>
<ctmem:application>Confirm</ctmem:application>
<ctmem:group>Confirm</ctmem:group>
<ctmem:max_wait>0</ctmem:max_wait>
<ctmem:prevent_nct2>no</ctmem:prevent_nct2>
258
<ctmem:time_from>0900</ctmem:time_from>
<ctmem:time_until>1100</ctmem:time_until>
<ctmem:critical>no</ctmem:critical>
<ctmem:cyclic>no</ctmem:cyclic>
<ctmem:confirm_flag>yes</ctmem:confirm_flag>
<ctmem:auto_archive>no</ctmem:auto_archive>
<ctmem:sys_db>no</ctmem:sys_db>
<ctmem:arch_max_days>0</ctmem:arch_max_days>
<ctmem:arch_max_runs>0</ctmem:arch_max_runs>
<ctmem:rerun_max>0</ctmem:rerun_max>
</ctmem:active_job>
</SOAP-ENV:Body>
Example 2: Create a cyclic Job

A Job Creation request that creates a single cyclic job that performs a command.
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:active_job>
<ctmem:job_name>Cyc0</ctmem:job_name>
<ctmem:mem_name>Cyc0</ctmem:mem_name>
<ctmem:application>Cyclic</ctmem:application>
<ctmem:group>Cyclic</ctmem:group>
259
<ctmem:rerun_interval>00060M</ctmem:rerun_interval>
<ctmem:cyclic>yes</ctmem:cyclic>
</ctmem:active_job>
</SOAP-ENV:Body>
Example 3: Create a job including In and Out conditions

A Job Creation request that creates a single job including In and Out conditions.
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:active_job>
<ctmem:job_name>InCond0</ctmem:job_name>
<ctmem:mem_name>InCond0</ctmem:mem_name>
<ctmem:application>InCond</ctmem:application>
<ctmem:group>InCond</ctmem:group>
260
<ctmem:in_conditions>
<ctmem:in_condition>
<ctmem:condition>ctm600a0</ctmem:condition>
<ctmem:date>ODAT</ctmem:date>
<ctmem:and_or>and</ctmem:and_or>
</ctmem:in_condition>
</ctmem:in_conditions>
<ctmem:out_conditions>
<ctmem:out_condition>
<ctmem:condition>ctm600a0</ctmem:condition>
<ctmem:date>ODAT</ctmem:date>
<ctmem:sign>delete</ctmem:sign>
</ctmem:out_condition>
</ctmem:out_conditions>
</ctmem:active_job>
</SOAP-ENV:Body>
Example 4: Create a job that requires resources

A Job Creation request that creates a single job requiring Control and Quantitative resources.
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
261
<ctmem:active_job>
<ctmem:job_name>Rsc0</ctmem:job_name>
<ctmem:mem_name>Rsc0</ctmem:mem_name>
<ctmem:application>Resource</ctmem:application>
<ctmem:group>Resource</ctmem:group>
<ctmem:description>Job requiring
resources.</ctmem:description>
<ctmem:over_lib>asds</ctmem:over_lib>
<ctmem:count_cyclic_from>end</ctmem:count_cyclic_from>
<ctmem:control_resources>
<ctmem:control_resource>
<ctmem:resource>Disks</ctmem:resource>
<ctmem:type>shared</ctmem:type>
</ctmem:control_resource>
<ctmem:resource>Time</ctmem:resource>
<ctmem:resource>JJ4</ctmem:resource>
<ctmem:resource>DE1a34</ctmem:resource>
262
<ctmem:type>exclusive</ctmem:type>
<ctmem:resource>CPU</ctmem:resource>
</ctmem:control_resources>
<ctmem:quantitative_resources>
<ctmem:quantitative_resource>
<ctmem:resource>DL</ctmem:resource>
<ctmem:quantity>30</ctmem:quantity>
</ctmem:quantitative_resource>
</ctmem:quantitative_resources>
</ctmem:active_job>
</SOAP-ENV:Body>
Example 5: Create a job that includes On-Do statements

A Job Creation request that creates a single job including multiple On-Do statements and a
variable.
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:active_job>
<ctmem:job_name>DoSys0</ctmem:job_name>
<ctmem:mem_name>DoSys0</ctmem:mem_name>
<ctmem:application>OnDo</ctmem:application>
<ctmem:group>DoSys</ctmem:group>
263
<ctmem:description>Job with On-Do
statements.</ctmem:description>
<ctmem:priority>Ab</ctmem:priority>
<ctmem:autoedit_assignments>
<ctmem:autoedit_assignment>
<ctmem:name>COPYTO</ctmem:name>
<ctmem:value>%%HOME.%%FILE</ctmem:value>
</ctmem:autoedit_assignment>
</ctmem:autoedit_assignments>
<ctmem:on_do_statements>
<ctmem:on_do_statement>
<ctmem:on_statements>
<ctmem:on_statement>
<ctmem:code>*</ctmem:code>
<ctmem:statement>*</ctmem:statement>
</ctmem:on_statement>
</ctmem:on_statements>
<ctmem:do_statements>
<ctmem:do_sysout>
<ctmem:option>copy</ctmem:option>
<ctmem:parameter>%%COPYTO</ctmem:parameter>
264
</ctmem:do_sysout>
</ctmem:do_statements>
</ctmem:on_do_statement>
</ctmem:on_do_statements>
</ctmem:active_job>
</SOAP-ENV:Body>
Example 6: Create a job that includes On-Do statements

A Job Creation request that creates a single job including multiple On-Do statements.
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:active_job>
<ctmem:job_name>DoVAr0</ctmem:job_name>
<ctmem:mem_name>DoVAr0</ctmem:mem_name>
<ctmem:application>OnDo</ctmem:application>
<ctmem:group>DoSetVar</ctmem:group>
<ctmem:description>Multiple
On-Dos</ctmem:description>
<ctmem:priority>Ab</ctmem:priority>
<ctmem:confirm_flag>no</ctmem:confirm_flag>
265
<ctmem:over_lib>JOBDOC</ctmem:over_lib>
<ctmem:command>echo %%ABC</ctmem:command>
<ctmem:on_do_statements>
<ctmem:on_do_statement>
<ctmem:on_statements>
<ctmem:on_statement>
<ctmem:code>*</ctmem:code>
<ctmem:statement>*</ctmem:statement>
</ctmem:on_statement>
</ctmem:on_statements>
<ctmem:do_statements>
<ctmem:do_autoedit>
<ctmem:name>Auto1</ctmem:name>
</ctmem:do_autoedit>
</ctmem:do_statements>
</ctmem:on_do_statement>
</ctmem:on_do_statements>
</ctmem:active_job>
</SOAP-ENV:Body>
Example 7: Create an active SMART Folder

<SOAP-ENV:Envelope
<SOAP-ENV:Body>
266
<ctmem:control_m>omega</ctmem:control_m>
<ctmem:active_job>
<ctmem:task_type>SMART_table</ctmem:task_type>
<ctmem:application>appl</ctmem:application>
<ctmem:group>grp1</ctmem:group>
</ctmem:active_job>
</SOAP-ENV:Body>
Example 8: Create an active job in an existing SMART Folder

<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:control_m>omega-ctm3</ctmem:control_m>
<ctmem:active_job>
<ctmem:job_name>pwJob3</ctmem:job_name>
<ctmem:mem_name>ajJob3</ctmem:mem_name>
<ctmem:owner>emuser</ctmem:owner>
<ctmem:application>UnixAppl</ctmem:application>
<ctmem:group>UnixJobs</ctmem:group>
<ctmem:table_id>0001l5</ctmem:table_id>
<ctmem:command>c:</ctmem:command>
</ctmem:active_job>
267
</SOAP-ENV:Body>
In the group ID element, you need to specify:
the RBA of the SMART Folder if the Control-M is running on z/OS.
the Order ID of the SMART Folder (with the addition of a leading zero) if the Control-M is running
on another operating system.
Order or Force request

Example 1: Order a UNIX job
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:control_m>UnixDc</ctmem:control_m><ctmem:job_id>2</ctmem:jo
b_id>
<ctmem:job_name>OrdSimJobU</ctmem:job_name>
<ctmem:table_name>OrdSimJobU</ctmem:table_name>
</SOAP-ENV:Body>
Example 2: Force a UNIX job

<SOAP-ENV:Envelope
<SOAP-ENV:Body>
268
<ctmem:control_m>UnixDc</ctmem:control_m>
<ctmem:job_id>2</ctmem:job_id>
<ctmem:job_name>ForSimJobU</ctmem:job_name>
<ctmem:table_name>ForSimJobU</ctmem:table_name>
</SOAP-ENV:Body>
Example 3: Force a UNIX job into a recent SMART Folder

<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:job_name>FoInRecent</ctmem:job_name>
<ctmem:table_name>FoInSGJobU</ctmem:table_name>
<ctmem:name>Recent</ctmem:name>
<ctmem:name>A</ctmem:name>
269
<ctmem:table_info>
<ctmem:into_table>recent</ctmem:into_table>
<ctmem:allow_dup>no</ctmem:allow_dup>
</ctmem:table_info>
</SOAP-ENV:Body>
Example 4: Force a UNIX job into a ‘recent’ SMART Folder allowing

duplication
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:job_name>FoInRecDup</ctmem:job_name>
<ctmem:table_name>FoInSGJobU</ctmem:table_name>
<ctmem:name>RecentDup</ctmem:name>
270
<ctmem:name>B</ctmem:name>
<ctmem:table_info>
<ctmem:allow_dup>yes</ctmem:allow_dup>
</ctmem:table_info>
</SOAP-ENV:Body>
Example 5: Force a sub-folder into a recent sub-folder

<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<ctmem:job_name>sub2</ctmem:job_name>
<ctmem:table_name>smart1/sub1</ctmem:table_name>
<ctmem:table_info>
<ctmem:allow_dup>yes</ctmem:allow_dup>
</ctmem:table_info>
</SOAP-ENV:Body>
271
12
Chapter
12
Error codes and exceptions
Errors and exceptions may occur when the Control-M/Enterprise Manager API is being used.
Errors and exceptions can be divided into the following groups:
 errors and exceptions that are caused by the Control-M/EM API
 errors and exceptions that are caused by faulty formatting in the XML request file
 errors and exceptions that are caused by the presence of incorrect data in the XML request file
 errors and exceptions that are caused by Control-M/EM or the Control-M installation
In addition to being described in this chapter, Control-M/EM API errors are listed in the EMAPIMessages.txt
file located in the home directory of the Control-M/EM installation.
Each error is composed of the following information:
 Major code
Integer that represents a family of related errors or exceptions.
 Minor code
ID code unique to each error.
 Severity
Indicates how critical the error is. Severity also determines the way that the Control-M/EM API handles
the error.
 Description
Text description of the error, returned as a string when an exception is thrown.
272
Severity
Every error that the Control-M/EM API displays has a severity level. This level indicates the priority of the
error and indicates how much information is written to the log file.
When using the Control-M/EM API, the most common severity level is ERROR. Using the default logging
configuration, the DEBUG error is never used. For information on how to modify the logging configuration,
see Control-M/EM API logging (on page 247).
The severity levels that are supported by the Control-M/EM API are listed in the following table:
Level Description
FATAL Displays fatal error messages.

When a FATAL error is generated, it is recommended that you stop using the
Control-M/EM API immediately, and that you investigate the cause of the
error.
If you continue to use Control-M/EM API despite receiving a FATAL error, stop
and restart Control-M/EM GUI Server and Global Alerts Server before
performing any more API actions.
ERROR Displays messages for fatal and non-fatal errors
WARN Displays warning messages and all error messages
INFO Displays system information, warnings, and all errors
DEBUG Displays debugging information and all other priority messages
273
Error code reference

All Control-M/EM API errors are arranged in logical groups. Each group is identified by a unique 3 - 5-digit
Major Code. Each error in the group is identified by a unique 1 - 3-digit Minor Code.
The following table lists all of the Major Code groups and includes a reference to the pages where the errors
in each group are described.
Individual errors are described in tables arranged by Major Code. The Minor Code, severity, and description
are listed for each error in the tables.
Error and exception major codes
Code Title Error descriptions
000 NULL Exception NULL exception errors (Major code 000) (on page 275)
100 Low-level API Exceptions Low-level API exceptions (Major code 100) (on page 276)
200 Parser Exceptions Parser exceptions (Major code 200) (on page 276)
300 Control-M Server Errors Category contains no individual errors.
300 Control-M Server Errors: Group1 Control-M/Server errors: Group 1 (Major code 300) (on page
277)
301 Control-M Server Errors: Group 2 Control-M/Server errors: Group 2 (Major code 301) (on page
280)
302 Control-M Server Errors: Group 3 Control-M/Server errors: Group 3 (Major code 302) (on page
281)
400 Control-M/EM API Request Category contains no individual errors.

Exceptions
401 Generic Request Exceptions Generic request exceptions (Major code 401) (on page 282)
403 Poll Request Poll request errors (Major code 403) (on page 282)
404 Add/Delete Condition Request Add or Delete Condition request errors (Major code 404) (on
page 283)
405 Order/Force Request Order or Force request errors (Major code 405) (on page 284)
406 Job Tracking Request Job tracking request errors (Major code 406) (on page 284)
407 Authorization Request Authorization request errors (Major code 407) (on page 285)
408 Alerts Request Alerts request errors (Major code 408) (on page 285)
274
Code Title Error descriptions
409 Create Active Job Request Create active job request errors (Major code 409) (on page
286)
411 Upload folders Upload folder request errors (Major code 411) (on page 287)
412 Create jobs or SMART Folder Create job/SMART Folder definitions request errors (Major
definitions code 412) (on page 288)
413 Delete job definitions Delete job definitions request errors (Major code 413) (on
page 289)
440 Retrieve active jobs Retrieve active jobs request errors (Major code 440) (on page
289)
450 Active job actions Job actions request errors (Major code 450) (on page 290)
500 Control-M/EM API Java Client Control-M/EM API Java client errors (Major code 500) (on
page 291)
600 Gateway Messages Gateway messages (Major code 600) (on page 292)
NULL exception errors (Major code 000)

Control-M/EM API has generated an undefined error.
The following table describes the NULL exceptions:
Minor
code Severity Description
0 ERROR Control-M/EM API has generated an undefined error
275
Low-level API exceptions (Major code 100)

Errors generated due to a Control-M/EM API initialization or request initialization failure.
The following table describes the Low level API exceptions:
Minor
1 ERROR Error on preliminary parsing of the XML
2 FATAL Catastrophic exception on server
3 ERROR Error: value Rule Based Calendar missing
4 ERROR Invalid Request. Request name: value
5 FATAL Could not obtain response from repository
6 ERROR Undefined exception on server
7 ERROR Deprecated request
Parser exceptions (Major code 200)

Error occurred when parsing an XML file.
The following table describes the Parser exceptions
Minor
1 FATAL Parser Initialization Failure
2 ERROR Error while parsing XML: value
3 FATAL Internal Parser Error: value
4 FATAL Internal Parser Error: Undefined Exception
276
Control-M/Server errors: Group 1 (Major code 300)

Errors generated by the Control-M installation.
The following table describes the Control-M/Server errors Group 1:
Minor
0 ERROR Internal Server Error on Control/M
3 ERROR Control/M Error: value
5 ERROR Storage allocation failed for CTM/EM Gateway
7 ERROR Cannot open conditions file
9 ERROR Loading of Control-M Parameters failed
18 ERROR Internal error on GETMEM
19 ERROR DSN not in catalog
20 ERROR DSN - dynamic allocation failed
21 ERROR Internal error. Invalid request to CTMMEM
22 ERROR Maximum number of members or lines in member exceeded
23 ERROR Invalid return code from CTMMEM
24 ERROR Error while processing directory of library
25 ERROR Library operation failed
40 ERROR Cannot open print file
42 ERROR Open of IOA log file failed
45 ERROR Internal Error on IOACND
46 ERROR Invalid date format
47 ERROR Cannot open synchronization file
48 ERROR Internal Server Error on Control-M
49 ERROR Internal Server Error on Control-M
51 ERROR Cannot add the condition because it already exists
277
Minor
52 ERROR Cannot add the condition because the condition file is full
53 ERROR Cannot add the control resource because it already exists
54 ERROR Cannot add the control resource because the resource file is full
55 ERROR Cannot delete the condition because it does not exist
56 ERROR Cannot delete the quantitative resource because it is in use
57 ERROR Cannot add the quantitative resource because the resource file is full
58 ERROR Cannot add the quantitative resource because it already exists
59 ERROR Cannot delete the quantitative resource because it does not exist
60 ERROR Change command can only be issued against quantitative resources
61 ERROR Invalid value in sign field
62 ERROR The value in a change command must be between 1-9999
63 ERROR Cannot load module (internal error)
64 ERROR The requested folder does not exist in the library
70 ERROR The requested job does not exist in the given folder
87 ERROR Invalid date
90 ERROR Folder or Member does not exist
91 ERROR Folder or Member already exists
93 ERROR Invalid Folder ID
94 ERROR The 'NEWG' order option is not supported in this version
95 ERROR The folder entity specified was not found in Active Jobs database
96 ERROR Failed to extract data from CTM/EM message
97 ERROR Failed to delete records from folder
98 ERROR Insert into folder failed
278
Minor
99 ERROR Update folder failed
100 ERROR Failed to commit transaction
101 ERROR The filed Sub Application is mandatory for a group entity
102 ERROR SUB APPLICATION and JOBNAME should be the same for group entity
103 ERROR SUB APPLICATION and SCHEDTAB should be the same for group entity
104 ERROR SUB APPLICATION and SCHEDTAB should be specified
105 ERROR The Sub Application specified does not exist in the database
106 ERROR FILE_PATH, CMDLINE, FILE_NAME AND OVERRIDE_PATH should not be specified
107 ERROR Failed to allocate ISN
108 ERROR No hosts found in host group
109 ERROR Failed to get next host in host group
110 ERROR Failed to setup application type for HOSTGRP, FILE_NAME and Override Path
should not be specified
111 ERROR Invalid Order_Date
279

The following table describes the Control-M Server errors Group 2:
Minor
501 INFO The job has been successfully ordered
502 ERROR Unable to open the specified scheduling library
506 ERROR Scheduling failed for member
510 ERROR Scheduling member contains invalid data
512 WARN Library should be compressed
514 ERROR Job was not ordered. Reason: Insufficient storage
515 ERROR Job contains too many cards
516 ERROR Table error: First card is not a D statement
517 ERROR The specified library is empty
524 ERROR Ordering process has entered with errors
525 ERROR Ordering process ended successfully
526 ERROR Invalid data format
528 INFO Job has been successfully ordered
531 ERROR Ordering process was canceled by an user exit
532 ERROR Cannot open Control-M/EM Active Jobs database
534 ERROR Cannot open Active Jobs database is corrupted, I/O error, or file is not really
Active Jobs
535 ERROR Cannot order a job while Active Jobs database is being formatted
536 ERROR Severe error in scheduling definition
537 ERROR The job order contains more information than what Control-M/EM can handle
548 ERROR The calendar specified in the job is either corrupted or invalid
280
Minor
549 WARN Control-R is not installed. IFRERUN statement ignored
550 WARN Control-R is not installed. SET statement ignored
166 ERROR The job contains a condition with a PREV/NEXT date that cannot be interpreted by
Control-M/EM
169 INFO Control-M/EM has finished handling the request. No jobs were scheduled

The following table describes the Control-M Server errors Group 3:
Minor
129 ERROR User exit not loaded
540 ERROR Security exit not loaded and security checking is bypassed
863 WARN Active Jobs database is nearly full
281
Generic request exceptions (Major code 401)

Errors generated when Control-M/EM cannot communicate with the Control-M installation.
The following table describes the Generic request exceptions:
Minor
1 ERROR Could not connect to Control-M
2 ERROR Invalid Control-M
3 ERROR Invalid response from Control-M
4 ERROR Internal Error: value
Poll request errors (Major code 403)

Errors generated when a Polling request fails.
The following table describes the Poll request errors:
Minor
1 ERROR Error: Invalid token supplied
282
Add or Delete Condition request errors (Major code 404)

Errors generated when an Add Condition or Delete Condition request fails.
The following table describes the Add or Delete Condition request
Minor
1 ERROR Add or Delete condition failed (code %d)
2 ERROR Add or Delete condition failed
3 ERROR Add or Delete condition aborted
4 ERROR Add or Delete condition timed out
5 ERROR Add condition failed
6 ERROR Add condition failed (code %d)
7 ERROR Add condition failed, invalid option
8 ERROR Delete condition failed
9 ERROR Delete condition failed (code %d)
10 ERROR Delete condition failed, invalid option
11 ERROR Condition's name is not valid
12 ERROR Condition's order date is not valid
13 ERROR Cannot Add or Delete condition, already in wanted state
283
Order or Force request errors (Major code 405)

Errors generated when an Order request or Force request fails.
The following table describes the Order/Force request errors:
Minor
1 ERROR Order request didn't pass validity checks. Error: value
2 ERROR Group RBA not found for Group ID value
3 ERROR Order request failed in the server
4 ERROR No jobs were ordered
Job tracking request errors (Major code 406)

Errors generated when a Job tracking request fails.
The following table describes the Job tracking request errors:
Minor
1 ERROR Job was not found in Active Jobs database
2 ERROR Required Job information does not exist in the database
3 ERROR Tracked Job failed in validity checks
284
Authorization request errors (Major code 407)

Errors generated when a registration or unregistration request fails.
The following table describes the Authorization request errors:
Minor
1 ERROR Invalid user token
2 ERROR Invalid user name
3 ERROR Register failed
4 ERROR Unregister failed
5 ERROR User not authorized
6 ERROR Account is locked
7 ERROR Password has expired
Alerts request errors (Major code 408)

Errors generated when a Change Alert Status request fails.
The following table describes the Alerts request errors:
Minor
1 ERROR Alert id is not valid
2 ERROR Invalid alert operation
285
Create active job request errors (Major code 409)

Errors generated when a Job Creation request fails.
The following table describes the Create active job request errors:
Minor
1 ERROR Create active job failed (code: %d)
2 ERROR Create active job failed
3 ERROR Create active job failed, object is in use
4 ERROR Create active job failed, object not found
5 ERROR Create active job failed, invalid option
6 ERROR Create active job validation error: value
7 ERROR SMART Folder is not valid for this data-center version
8 ERROR Failed to initialize job descriptor
9 ERROR Create active job, invalid order date
286
Upload folder request errors (Major code 411)

Errors generated when an Upload Folder request fails.
The following table describes the Upload folder request errors:
Minor
1 ERROR Upload folder failed, invalid parameters
2 ERROR Upload folder failed
3 ERROR Cannot get folder from database
4 ERROR Upload folder aborted
5 ERROR Upload folder timed-out
6 ERROR Upload folder failed with status
287
Create job/SMART Folder definitions request errors (Major code

412)
Errors generated when a Create job/SMART Folder definitions request fails.
The following table describes the Create job/SMART Folder definitions request errors:
Minor
1 ERROR Create job definitions failed, invalid parameters
2 ERROR Create folder failed
3 ERROR Create job definitions failed
4 ERROR Failed to add jobs to folder
5 ERROR Create jobs definitions failed, unknown reason
6 ERROR <TBD: Message text>
7 ERROR Folder already exists
8 ERROR SMART Folder is not valid for this data-center version
9 ERROR Failed to initialize job descriptor
10 ERROR Create definitions, API is not supported for CTM version '%s'
11 ERROR SMART Folder already contains a sub-folder
12 ERROR Illegal author in new job
13 ERROR Sub application name of a job or a SMART Folder differs from a SMART Folder or
folder
14 ERROR Create jobs definitions validation error: '%s'
288
Delete job definitions request errors (Major code 413)

Errors generated when a Delete job definitions request fails.
The following table describes the Delete job definitions request errors:
Minor
1 ERROR Folder does not exist
2 ERROR Many folders are found
3 ERROR Failed to delete jobs from folder
4 ERROR No jobs were deleted according to the specified criterion
5 ERROR Failed to update number of jobs in a SMART Folder
6 ERROR Delete jobs definitions validation error: [<filter name>] is not valid filter field
7 ERROR Delete jobs definitions, invalid parameters
Retrieve active jobs request errors (Major code 440)

Errors generated when a Retrieve active jobs request fails.
The following table describes the Retrieve active jobs request errors:
Minor
1 ERROR Retrieve active jobs failed
2 ERROR Request failed - internal error
3 ERROR No jobs were found according to the specified criterion
4 ERROR Partial result
5 ERROR The maximum of returned nodes, which is specified in request, exceeds

Control-M/EM server limit, which is specified by EMAPIActiveJobsLoadLimit
system parameter
6 ERROR Retrieve active jobs validation error: '%s' is not valid filter field
289
Job actions request errors (Major code 450)

Errors generated when a Job actions request fails.
The following table describes the Job actions request errors:
Minor
1 ERROR Unknown error occurred
2 ERROR Action request failed (code %d)
3 ERROR Action request failed
4 ERROR Action request aborted
5 ERROR Action request timed-out
304 ERROR Cannot hold job - not held
305 ERROR Active Jobs database is locked, try again later
306 ERROR Job does not exist
309 ERROR Cannot hold job - already held
310 ERROR Job is not waiting for confirmation
323 ERROR Security protection violation
328 ERROR Job is not in execution state
361 ERROR The selected job/folder cannot be deleted due to its current state
506 ERROR Operation not supported by agent
305 ERROR Job does not exist
305 ERROR Job actions, invalid order date
290
Control-M/EM API Java client errors (Major code 500)

Errors generated by the Java API.
The following table describes the Control-M/EM API Java client errors:
Minor
1 ERROR Fatal error
2 ERROR Null XML document - nothing to do
3 ERROR Failed to establish connection with server - no server registered under this
hostname
4 ERROR Failed to resolve server name - please check your hostname
5 ERROR Failed to establish connection with server - not a valid component type, check
your hostname
6 ERROR Failed resolving XMLInvoker interface
7 ERROR Failed to establish connection with server - check your connection with the
CORBA Naming Service
8 ERROR Failed to establish connection with - check your CORBA configuration
9 ERROR Properties file not found
10 ERROR Failed to read properties file
101 ERROR Invoke timeout - no response after
102 ERROR Invoke request exited because a InterruptedException occurred
111 ERROR Response format is not valid
112 ERROR Response format is not valid, cannot find rule based calendar
131 ERROR XML format is not valid
132 ERROR Request format is not valid
133 ERROR Cannot find user token
140 ERROR Error parsing the XML
141 ERROR Undefined Exception on Parser
291
Gateway messages (Major code 600)

Errors generated by the gateway.
The following table describes the Gateway messages:
Minor
1 ERROR User Request timed out
2 ERROR No network currently loaded
3 ERROR No nodes match the Show Net parameters
4 ERROR Net too large to be fully viewed. Some nodes are missing
5 ERROR Database login failed three times
6 ERROR At least one state must be chosen
7 ERROR At least one status must be chosen
8 ERROR At least one task type must be chosen
9 ERROR No events found for current net
10 ERROR Field value Wrong Format: value
11 ERROR Cannot load Active Network: No data center
12 ERROR Field value is required
13 ERROR Net Load aborted, probably not enough memory
14 ERROR No nodes match the Load Net Parameters
15 ERROR Error while reading job-record from database
16 ERROR Nothing changed since last save
17 ERROR Nothing changed
18 ERROR Cannot save file value
19 ERROR Confirm value for value
20 ERROR Do you really want to quit value?
21 ERROR In a critical job, parameter 'Priority' must begin with
292
Minor
22 ERROR Field value contains an invalid value
23 ERROR Field value must be between %d and %d
24 ERROR Field Rerun Mem Cannot be used if field Task Type is Cyclic
25 ERROR Field value has an invalid value starting at position: value
26 ERROR Field value may not contain embedded spaces
27 ERROR Cannot clear Demo Net value
28 ERROR Cannot create Demo Net value
29 ERROR Cannot copy Demo Net value
30 ERROR Couldn't open user view
31 ERROR Do you really want to erase the entire value Net value
32 ERROR Do you really want to clear the entire value Net value
33 ERROR Cannot append, Owner of value is value
34 ERROR Cannot open value
35 ERROR Missing file value
36 ERROR Unable un-mount diskette in value
37 ERROR Unable to mount diskette in value
38 ERROR Incorrect path value
39 ERROR Files downloaded from incompatible version value (should be value)
40 ERROR Cannot open file value
41 ERROR Missing value line
42 ERROR Unknown line: value
43 ERROR Cannot write to file value
44 ERROR File value exists. Ok to overwrite?
293
Minor
45 ERROR Net value does not exist
46 ERROR Copy from file to file not allowed
47 ERROR Database job update failed
48 ERROR Database select failed for resource events
49 ERROR Database select failed for override table, simulation stopped
50 ERROR No current net
51 ERROR No nodes were found
52 ERROR No more nodes were found Go Back?
53 ERROR No more nodes were found
54 ERROR You are not authorized to perform this action
55 ERROR If field value (Days/Week days Calendar) begins with ALL then the rest of the
parameter must be blank
56 ERROR Field Days Calender is required if field value contains the value: value
57 ERROR Field Week Calender is required if field value contains the value: value
58 ERROR Field Days has an invalid value starting at position: value; There should be a comma
there
59 ERROR Discard changes made in form?
60 ERROR Change of calendar type destroys existing data. Proceed?
61 ERROR Change of data center platform destroys existing data. Proceed?
62 ERROR Data center unknown, please re-enter value
63 ERROR Reading calendar failed - database problems
64 ERROR Calendar is already in use by user value, try later
65 ERROR Calendar write failed - database problems
66 ERROR Unknown platform. Verification of data defaults to MVS. Do you want to continue?
294
Minor
67 ERROR Calendar was modified. Proceed with download?
68 ERROR Calendar value was downloaded successfully from data center value
69 ERROR Calendar value was deleted successfully from data center value
70 ERROR Calendar is in use by user value, and cannot be deleted"
71 ERROR Confirm Calendar Delete"
72 ERROR Confirm Calendar Upload"
73 ERROR Forced Calendar Upload overrides calendar content in data center Proceed?
74 ERROR You are not authorized to access the Calendar List window
75 ERROR Filed value must be specified if field value is File, New Dest or Change Class
76 ERROR Attempt to enter conflicting conditions
77 ERROR Field value may only be used with the Change Class option
78 ERROR Field value is too long
79 ERROR Field Sign may not be + if the ODATE field value is **** or $$$$
80 ERROR Unknown or disabled Platform! Form is opened as MVS!
81 ERROR In a critical job, field Priority must begin with *
82 ERROR Field Command Line may be specified only if Task Type is Command
83 ERROR Field should be %d char(s) long for this Sysout option
84 ERROR Field value cannot be used if Task Type is value
85 ERROR Field value cannot specify GENREAL or USER=
86 ERROR Fields Parm and From Class must be specified if field Option is Change Class
87 ERROR Field Parm must be specified if field Option is New Dest or File
88 ERROR Field Confirmation Cal cannot be used with fields PDS Name or Minimum
89 ERROR Field Months cannot be used with fields PDS Name, Minimum or Dates
295
Minor
90 ERROR Field Dates cannot be used with parameters PDS Name, Minimum, Months, Days, or
Days Calendar
91 ERROR Field Dates cannot be used with fields Week Days, Weeks Days Calender Confirmation
Cal
92 ERROR If field PDS Name is specified then Minimum must be specified and vice versa
93 ERROR Field Priority must begin with * or an alphanumeric character
94 ERROR Field Priority must begin with an alphanumeric character
95 ERROR Field value is required if Task Type is: value
96 ERROR A job with the same name already exists in this folder
97 ERROR If field Retro is specified then PDS Name and Minimum cannot be used
98 ERROR The fields Days and Week Days Calendar cannot both be specified
99 ERROR The field value must contain a numeric value or 0
100 ERROR Fields Rerun Mem and Max Rerun cannot be used if field Task Type is Cyclic
101 ERROR Field Dates must be specified in format nnnn or nnnn,nnnn,...
102 ERROR Folder is already in use by user value, try later
103 ERROR Folder write failed - database problems
104 ERROR Folder should be uploaded before order/force
105 ERROR Field value is required
106 ERROR If field value is *???????, then field value must be blank
107 ERROR Folder was modified. Proceed with download?
108 ERROR Folder was modified. Proceed with order?
109 ERROR Folder was modified. Proceed with force?
110 ERROR Definition folder value was downloaded successfully from data center value
111 ERROR Definition folder value was deleted successfully from data center value
296
Minor
112 ERROR Confirm Folder Delete
113 ERROR Confirm Folder Upload
114 ERROR Forced Folder Upload overrides folder content in data center Proceed?
115 ERROR You are not authorized to access the Folders window
116 ERROR Folder is in use by user value, and cannot be deleted
117 ERROR Field value must be blank if field value is OK or NOTOK or RERUN
118 ERROR Communication with WS-Gateway stopped, all requests were canceled
119 ERROR System Error in value: Command value failed; value
120 ERROR No communication with WS-Gateway. Request cancelled
121 ERROR value not possible, no communication with Gateway
122 ERROR value not possible, Unknown data center value
123 ERROR value not possible, data center value not available
124 ERROR Communication with data center value down, all requests canceled
125 ERROR Data center value is suspended (Active jobs is being formatted)
126 ERROR Data center value is suspended (Download in Netgroup)
127 ERROR Data center value is suspended (Active jobs is being formatted), all requests canceled
128 ERROR Invalid event %c received from data center value. To ensure database integrity,
WS-GTW stop/restart is recommended
129 ERROR The host name be specified only for the TCP protocol
130 ERROR The host name may contain only Alphanumeric characters and periods
131 ERROR You must specify a communication protocol
132 ERROR Specified communication protocol not supported on platform
133 ERROR Control-R not supported on platform
297
Minor
134 ERROR The Net Group field must contain two alpha numeric characters
135 ERROR Control-M must be 300 or 400 for MVS
136 ERROR Incorrect Control-M version specified for this platform
137 ERROR Folder read failed - database problems
138 ERROR Please verify that all users have quit Control-M/EM and that the WS-Gateway is down.
139 ERROR Do you really want to quit Control-M/Enterprise Manager Administration?
140 ERROR No Net
141 ERROR Number of nodes in a row exceeds maximum of %d
142 ERROR Cannot generate report due to insufficient memory
143 ERROR Cannot print links: value
144 ERROR Cannot print index: value
145 ERROR Cannot do poster for routed net
146 ERROR Job Report fields saved. Please close and open the job report window
147 ERROR New field is empty
148 ERROR Confirm delete
149 ERROR No Loaded Networks Available
150 ERROR Control Resources with value value cannot be value
151 ERROR Quantitative Resources with value value cannot be value
152 ERROR Field Author must be entered
153 ERROR Order ID value not found
154 ERROR Pattern value not found in text
155 ERROR Pattern value appears only once in the text
156 ERROR Problems searching for pattern value
298
Minor
157 ERROR Alarm handling command ignored. User value is handling this alarm now
158 ERROR Alarm handling command ignored. Internal error
159 ERROR Download of calendar value canceled in gateway - calendar in use
160 ERROR Download of calendar value canceled in gateway - Another download is currently in
progress - Try later
161 ERROR Upload of calendar value canceled in gateway
162 ERROR Upload of calendar value canceled in gateway - calendar in use
163 ERROR Upload of definitions folder value canceled in gateway
164 ERROR Upload of definitions folder value canceled in gateway - folder in use
165 ERROR Download of definition folder value canceled in gateway - folder in use
166 ERROR Download of definition folder value canceled in gateway - Another download is
currently in progress - Try later
167 ERROR Definitions folder deleted on data center but delete failed on workstation (rc 1)
168 ERROR Definitions folder deleted on data center but delete failed on workstation (rc 2)
169 ERROR Calendar deleted on data center but delete failed on workstation (rc 2)
170 ERROR Delete of definitions folder value canceled in gateway - folder in use
171 ERROR Delete of calendar value canceled in gateway - calendar in use
172 ERROR User request canceled in gateway, no answer from data center (time-out)
173 ERROR Download of value canceled, no answer from data center (time-out)
174 ERROR Download of value canceled in gateway
173 ERROR Download canceled, no answer from data center (time-out)
174 ERROR Download canceled in gateway
175 ERROR Upload canceled in gateway
176 ERROR Upload canceled (file transfer error (rcp) in gateway), consult system administrator
299
Minor
177 ERROR Information request canceled in gateway, system error (fopen failed), consult system
administrator
178 ERROR Information request canceled (time-out) in gateway, no answer from data center
179 ERROR Upload of value canceled (time-out), no answer from data center
180 ERROR Upload of value canceled in gateway
179 ERROR Upload canceled (time-out), no answer from data center
180 ERROR Upload canceled in gateway
181 ERROR No fields defined
182 ERROR Field value not in folder
182 ERROR Field not in folder
183 ERROR Internal error on field value
183 ERROR Internal error on field
184 ERROR Cannot print %d characters; Maximum of %d allowed
185 ERROR Cannot print more than %d fields
186 ERROR You are not authorized to load an active network
187 ERROR value was not found in data center. Delete in workstation?
188 ERROR You are not authorized to access the Global Conditions window
189 ERROR Definition folder value was deleted only on workstation
190 ERROR Calendar value was deleted only on workstation
191 ERROR Internal error. Action failed
192 ERROR Insert failed. Record with same key already exists
193 ERROR Record deleted in the meantime
194 ERROR Error message value Received from data center value
300
Minor
194 ERROR Error message received from data center
195 ERROR Field value is required if field value is defined
195 ERROR Field required
196 ERROR Field value should be at most %d characters
197 ERROR Field value may not contain the characters value
198 ERROR Field value must be between value and value
199 ERROR Field value should be empty
200 ERROR Field value must be blank if field When is OK or NOTOK or RERUN
201 ERROR Field value must be value
202 ERROR No response to heartbeat check from data center: value
202 ERROR No response to heartbeat check from data center
203 ERROR Unsupported version value of data center value. Check Control-M installation
203 ERROR Unsupported version of data center, check Control-M installation
204 ERROR Not the smallest ISN for ordered/forced job
301
Job and SMART Folder XML parameters

The following table describes the job and SMART_folder XML parameters:
active_from Indicates the start of a period of time during which the job or SMART Folder
can be ordered.
active_till Indicates the end of a period of time during which the job or SMART Folder
can be ordered.
adjust_condition 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:
 no (Do not ignore. Default.)
 yes (Ignore relevant prerequisite conditions)
 dummy [Control-M for z/OS as of version 6.2 only]. Order as a PSEUDO
job any job with scheduling criteria that are not satisfied on the current
Order DATE, with the MEMLIB parameter of the job set to DUMMY.
and_or Indicates the relationship between Month Days parameter values and Week
Days parameter values.
application Name of the application to which the job’s group belongs. Used as a
descriptive name for related groups of jobs.
application_cm_version Indicates the version of external application (for example, SAP or Oracle
Applications) Control Module (CM) that is installed in the Control-M
installation. Specified together with the application_form,
application_form Specifies a predefined set of external application parameters that are

displayed in the External Application panel of the Control-M Workload
Automation Properties pane. Specified together with the
application_cm_version, application_type, and
application_type Indicates the type of external application (for example, SAP or Oracle
Applications) on which the external application job runs. Specified together
with the application_cm_version, application_form, and
302
application_version Indicates the version of the external application (for example, SAP or Oracle
Applications) on which the external application job runs. Specified together
with the application_cm_version, application_form, and
application_type elements.
arch_max_days Maximum number of days to retains the SYSDATA archive data set for jobs
that ended NOTOK. [z/OS only]
arch_max_runs Maximum number of job runs to retain the SYSDATA archive data set for
jobs that ended NOTOK. [z/OS only]
Run As User Control-M/EM user who defined the job.

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 Control-M Workload Administration.
auto_archive Determines whether or not SYSDATA is to be archived. [z/OS only]

Valid values:
 yes
 no
variable_assignments A sequence of variable_assignment.

See variable_assignment XML parameters (on page 326)
command Command string supplied when the job Task Type (the task_type
element) is Command. Optional.
confirm_flag Specifies whether user confirmation is required before the job is submitted
for execution. String.
Valid values:
 no: Job needs no confirmation to run. Default.
 yes: Job must be confirmed to run.
control_resources A sequence of control_resource.

See control_resources XML parameters (on page 328)
303
count_cyclic_from Indicates whether the interval between successive runs of a cyclic job is
calculated from the start or the end of the previous job run. Specified only
for cyclic jobs (when the cyclic element is specified).
Valid values:
 start: Counts interval from the start of the previous job run
 end: Counts interval from the end of the previous job run
 target: Counts interval from the scheduling time of the current job run.
conf_cal Calendar used to confirm job scheduling dates.
critical Indicates that the job is a critical-path job in Control-M.

Valid values:
 yes – a critical path job
 no – not a critical path job
ctld_category Control-M for z/OS only: Name of a Control-D Report Decollating

Mission category to be scheduled whenever the job is run.
cyclic Indicates if a job is cyclic.

Valid values:
 yes – Cyclic job
 no – Non-cyclic job
cyclic_type If job is cyclic (cyclic equal yes), indicates how the intervals for running the
job are specified. Valid values are:
 interval: Job is run at fixed interval. See rerun_interval.
 interval_sequence: Job is run according to a list of time periods. See
interval_sequence.
 specific_times: Job is run according to a list of specific times. See
specific_times.
dates A sequence of date.

For more information, see date XML parameter description (on page 313)
Control-M for z/OS:
A maximum of 12 date elements can be specified.
304
days_cal Name of a user-defined calendar containing a list of days of the month, used
with Month Days, to determine a set of working days.
days_due_out_offset The number of days that job execution can be extended after the ODAT.
days_due_out_offset is relevant only for jobs running in Control-M for
z/OS version 6.2.00 and later.
description Text description of the job
doc_lib Name of the directory/library containing the job documentation file.
doc_member Name of the file containing job documentation.
Sub Application Name of the sub application to which the job belongs. Used as a descriptive
name for related groups of jobs.
in_conditions A sequence of in_condition.

See in_condition XML parameters (on page 327)
instream_jcl JCL stream forming part of the job definition.
instream_jcl is relevant for jobs running in:

interval_sequence A sequence of interval_item.

See interval_sequence XML parameters (on page 338)
job_name The name of the job
job_rule_based_cals A sequence of job_rule_based_cal. For more information, refer to

job_rule_based_cal XML parameters (on page 337)
keep_active Number of extra days (beyond the original scheduling date) that the job is
allowed to remain in Active Jobs awaiting execution. Integer.
file_path Name of the library/directory in which the job script resides. String.
min_pds_tracks Minimum number of free partitioned data set tracks required by the library
specified for the PDS parameter.
305
month_days Indicates the days of the month on which the job should be scheduled for
processing.
multiagent When selected, broadcasts job submission details to all Agents within a
specified Node Group. Not for z/OS. Optional.
Valid values:
 yes: Run as multi-agent job
 no: Not run as multi-agent job. Default.
host_id Host ID of the host on which the job was most recently run.
This parameter is not available for Control-M for z/OS jobs.
on_do_statements A sequence of on_do_statement. For more information, refer to

.on_do_statement XML Parameters Description (on page 313)
out_conditions A sequence of out_condition.

See out_condition XML parameters (on page 330)
override_path Name of the alternate job script library/directory.
Created by The name of the user.
pds Control-M for z/OS only:

Name of a partitioned data set (PDS) to be checked for free space. If the
PDS has fewer than the minimum number of required free tracks (as
specified for the Minimum parameter), the job is executed.
306
prevent_nct2 Prevents data set cleanup before the original job run. [z/OS only].
Optional.
Valid values:
 no: Does not prevent data set cleanup. Default.
 yes: Prevents data set cleanup.
 blank: Do not perform data set cleanup before the original job run.
 list: Do not perform data set cleanup before the original job run; but
generate the messages that would be required for GDG adjustment
during restart.
 flush: Halt processing of the job if any data set cleanup error is
detected (even if MVS would not have stopped processing the job).
priority Indicates Control-M job priority. String.
quantitative_resources A sequence of quantitative_resource.

See quantitative_resource XML parameter (on page 329)
request_nje Specifies the node in the JES network on which the job is to execute. [z/OS
only] String.
rerun_interval Specifies the length of time to wait between reruns of a job or between
cyclic runs of a job. The value is expressed as a number and a letter. The
number indicates the amount. The letter indicates the unit of measurement.
Valid values:
 0 - 64800M (minutes)
 0 - 1080H (hours)
 0 - 45D (days)
Default: 0.
rerun_max Specifies the maximum number of reruns that can be performed for the
job. Integer.
Valid values: 0-99.
rerun_member Name of the JCL member to use when the job is automatically rerun. [z/OS
only] String. Optional.
reten_days Number of days to retain the job in the History Jobs file. [z/OS, only]. String.
307
reten_gen Maximum number of generations of the job to keep in the History Jobs
file.[z/OS, only]. String.
retro Indicates whether the job should be scheduled for possible execution after
its original scheduled date has passed.
sac Control-M for z/OS, version 6.2xx and later

Indicates whether to adjust the logical date for a job converted from a
scheduling product other than Control-M. Optional. String. Valid values are:
 blank. Default.
 previous
 next
 plus (for group scheduling definitions only)
 minus (for group scheduling definitions only)
schedule_environment Indicates the JES2 workload policy management scheduling environment

that is to be associated with the job. z/OS, only. String.
smart_folder_rule_based_ca A sequence of rule_based_cal. For information about rule based calendar

ls XML parameters, refer to rule_based_cal XML parameters (on page 334)
shift When to schedule the job if the date is not confirmed. (Option) Valid values
are:
 ignore_job. Do not shift the job to a different date. The job is not
scheduled.
 next_day. Shift to the next working date.
 prev_day. Shift to the previous working date.
 no_confcal. Tentatively schedule the job for the current day (even if not
a working day). Additional shifting may or may not be performed,
depending on the value indicated in the shift_num parameter.
shift_num The number of working days that a job can be shifted. Values from -62 to 62
can be entered. This function is also called Extended Shift.
shouts A sequence of shout.

See shouts XML parameters (on page 332)
308
specific_times A sequence of specific_time.

See Specific_times XML parameters (on page 338)
statistic_calendar Name of the Control-M periodic calendar within which statistics relating to
the job are collected.
statistic_calendar is relevant only for jobs running in Control-M for z/OS

step_ranges A sequence of step_range.

See step_range XML parameters (on page 331)
sys_db Indicates that a single data set is used for archiving the SYSDATA of all jobs
until it is full, when another data set is started. [z/OS only]
Valid values:
 yes: Single data set created for the SYSDATA of each job run.
 no: Separate data set created for the SYSDATA of each job run.
Output_from_class Limits the output handling operation to only outputs from the specified
class. [z/OS only]
Output_option Output Handling options.

Optional.
Valid values (non-z/OS):
 copy
 delete
 move
 release
Valid values (z/OS):
 copy
 delete
 move
 release
 change_class
309
output_parameter Certain output_option values require that you supply additional

information (such as Copy, NewDest):
 If the output_option element is change_class, the output_parameter
value corresponds to the new class name.
 If the output_option element is copy, the output_parameter value
corresponds to the destination file name.
 If the output_option element is move, the output_parameter value
corresponds to the new destination for the file.
system_affinity Indicates the identity of the system in which the job must be initiated and
executed (in JES2).
Indicates the identity of the processor on which the job must execute (in
JES3).
For z/OS jobs only.
rule_based_cal_relationship Indicates the relationship (AND/OR) between Rule Based Calendar criteria
and basic scheduling criteria in the job processing definition (that is,
whether either set of criteria, or both sets of criteria, must be satisfied).
task_type Type of the job (task) to be performed by Control-M.

Microsoft Windows and UNIX
 job
 command
 dummy
 detached
 external
Control-M for z/OS
 job
 task
 cyclic_job
 emergency_job
 emergency_cyclic_job
 cyclic_task
 emergency_task
 emergency_cyclic_task
310
time_due_out Time that the job is expected to finish.
time_from Indicates the earliest time for submitting the job.
time_from_days_offset Number of days after the original scheduling date of the job during which
execution of the job can begin.
time_from_days_offset is relevant only for jobs running in Control-M for

time_until Indicates the latest time for submitting the job.
time_until_days_offset Number of days after the original scheduling date of the job during which
execution of the job can end.
time_until_days_offset is relevant only for jobs running in Control-M for

time_zone Indicates the global time zone used to calculate the interval for time-related
conditions.
tolerance Maximum delay in minutes permitted for late submission when selecting a
specific time.
use_instream_jcl Whether the job submits a JCL stream defined within the job scheduling
definition.
Valid values are:
 yes
 no
use_instream_jcl is relevant for jobs running in:

weeks_cal Name of a user-defined, week-based calendar used together with

parameter Week Days to specify a set of working days.
week_days Indicates the days of the week on which the job should be scheduled for
processing.
311
JAN Indicates whether to run the job in this month. Valid values are:
 yes
 no
FEB Indicates whether to run the job in this month. Valid values are:
 yes
 no
MAR Indicates whether to run the job in this month. Valid values are:
 yes
 no
APR Indicates whether to run the job in this month. Valid values are:
 yes
 no
MAY Indicates whether to run the job in this month. Valid values are:
 yes
 no
JUN Indicates whether to run the job in this month. Valid values are:
 yes
 no
JUL Indicates whether to run the job in this month. Valid values are:
 yes
 no
AUG Indicates whether to run the job in this month. Valid values are:
 yes
 no
SEP Indicates whether to run the job in this month. Valid values are:
 yes
 no
312
OCT Indicates whether to run the job in this month. Valid values are:
 yes
 no
NOV Indicates whether to run the job in this month. Valid values are:
 yes
 no
DEC Indicates whether to run the job in this month. Valid values are:
 yes
 no
date XML parameter description

The following table describes the date XML parameter:
date Indicates a specific date, in either mmdd or ddmm format (depending on the site
standard), on which the job should be scheduled.
on_do_statement XML Parameters Description

The following figure describes the on_do statement XML parameters:
313
The following table describes the on_do statement XML parameters:
on_statements A sequence of on_statements.

See on_statements XML parameters description (on page 314)
do_statements A sequence of do_statements.

See do statements type XML parameters (on page 317)
on_statements XML parameters description

The following figure describes the on_statements XML parameters:
The following table describes the on_statements XML parameters:
on_statement A sequence of on_statement.

OR See on_statement XML parameters (on page 315)
on_statement_output A sequence of on_statement_output.
See on_statement_output XML parameters (on page 316)
314
on_statement XML parameters

The following figure describes the on_statement XML parameters:
The following table describes the on_statement XML parameters:
and_or Indicates the relationship between Month Days parameter values and Week Days
parameter values.
code Code value for the On Statement/Code parameter.

Valid values:
 ok
 not_ok
procedure_step Step in the procedure that triggers the On statement. String.
program_step Step in the program that triggers the On statement. String.
statement statement can be:

 A character string containing a statement from the job script file (1-132
characters). The specified string can be a portion of the statement.
 An asterisk (*), when code is a completion status for a job.
315

The following figure describes the on_statement_output XML parameters:
The following table describes the on_statement_output XML parameters:
find_output_pattern A string of up to 40 characters.
find_pattern_from A number from 001 through 132, indicating the column at which the search should
start. If this field is blank, the value 001 is assumed. The value in this field must be
lower than that in the To Column field.
find_pattern_to A number from 001 through 132, indicating the column at which the search should
end. If this field is blank, the value 132 is assumed. The value in this field must be
higher than that in the From Column field.
and_or Option buttons that set the logical relationship between multiple On statements.
316
do statements type XML parameters

The following figure describes the do statements type XML parameters:
317
The following table describes the do statements type XML Parameters:
do A sequence of do_statements.
do_variable Assigns a variable when the On criteria are met. See .do_variable XML parameters
(on page 318)
do_cond Assigns an In or Out condition when the On criteria are met. See .do_cond XML
parameters description (on page 319)
do_ctbrule Invokes a Control-M/Analyzer rule to be executed during the processing of a

specific program step when an On condition is met. See do_ctbrule XML
parameters (on page 320).
do_forcejob Forces a specified job when the current job is performed.

The dsn element is for z/OS jobs only. See do_forcejob XML parameters (on page
320).
do_ifrerun Specifies job steps to be executed during rerun of a job. Only for networks using
Control-M/Restart. See do_ifrerun XML parameters (on page 321)
do_mail Sends email.
do_remedy Creates a Remedy ticket.
do_shout Sends a shout message when the On criteria are met.
do_output Determines what to do with the output documentation when On criteria are met.
do_variable XML parameters

The following figure describes the do_variable XML parameters:
318
The following table describes the do_variable XML parameters:
do_cond XML parameters description

The following figure describes the do_cond XML parameters:
The following table describes the d_cond XML parameters:

 Wrapped in the in_condition and out_condition elements.

Valid values:
 add
 delete
319
do_ctbrule XML parameters

The following figure describes the do_ctbrule XML parameters:
The following table describes the do_ctbrule XML parameters:
name Name of the Control-M/Analyzer rule.
parameter Contains arguments that are passed to the Control-M/Analyzer rule.
do_forcejob XML parameters

The following figure describes the do_forcejob XML parameters:
320
The following table describes the do_forcejob XML parameters:
dsn Name of the directory/library containing Table file. [z/OS only]
job Specifies the job name of the job that is forced.
odate Original scheduling date of a job.
folder Name of the Folder with which the job specified in do_forcejob is associated.
do_ifrerun XML parameters

The following figure describes the do_ifrerun XML parameters:
321
The following table describes the do_ifrerun XML parameters:
confirm Indicates that a job rerun specified by the Do If Rerun parameter must be manually
confirmed before it is executed.
Valid values:
 yes – requires confirmation
 no – no confirmation required
do_mail XML parameters

The following figure describes the do_mail XML parameters:
322
The following table describes the do_mail XML parameters:
cc Optional additional address to which a Do Mail can be sent. Optional.
to Recipient of the do_mail message.
subject Subject of the do_mail message.

Valid values:
 urgent
 very_urgent
attach_output Specifies whether the output should be sent as an email attachment. Valid values
are:
 yes - Send the job’s output as an attachment
 no - Do not send the job’s output as an attachment
 default - Use the settings configured for the relevant Control-M server to
determine whether the job’s output should be sent as an attachment.
This parameter is relevant only for jobs running in Control-M/Server version 6.4.01
and later and Control-M for z/OS version 7.0.01 and later.
do_shout XML parameters

The following figure describes the do_shout XML parameters:
323
The following table describes the do_shout XML parameters:
parameters.

Valid values:
 urgent
 very_urgent
do_output XML parameters

The following figure describes the do_output XML parameters:
324
The following table describes the do_output XML parameters:
from_class Specifies the class of jobs with outputs that are handled using the Do Output
specifications of the job.
option Do Output parameter output handling options.

Valid values:
 Release
 Delete
 Copy
 Move
 File
 NewDest
 ChangeClass
Copy and Move are not used with z/OS. File, NewDest, and ChangeClass are used
only with z/OS.
parameter Contains additional output handling information. The type of information required
is dependent on the value of the option element.
 If the option element is ChangeClass, the parameter value corresponds to the
new class name.
 If the option element is Copy, the parameter value corresponds to the
destination file name.
 If the option element is Move, the parameter value corresponds to the new
destination for the file.
325
do_remedy XML parameters

The following figure describes the do_remedy XML parameters:
The following table describes the do_remedy XML parameters:
urgency The urgency of the Remedy ticket. Valid values are:

 low
 medium
 high
 urgent
 clear
description The description of the problem for which you are opening up the ticket.
summary A summary of the problem for which you are opening up a ticket.

The following figure describes the variable_assignment XML parameters:
326
The following table describes the variable_assignment XML parameters:
name Name of the variable.
value Value of the variable expression.
in_condition XML parameters

The following figure describes the in_condition XML parameters:
The following table describes the in_condition XML parameters:

Optional.
Valid values:
 and
 or
condition Condition name.
327
control_resources XML parameters

The following figure describes the control_resources XML parameters:
The following table describes the control_resources XML parameters:
type Indicates job access to a Control resource.

Valid values are:
 exclusive - default
 shared
on_fail Whether to keep a Control resource tied to a job if the job does not end OK. Valid
values:
 keep
 release – default
328
quantitative_resource XML parameter

The following figure describes the quantitative_resource XML parameter:
The following table describes the quantitative_resource XML parameters:
quantity Amount of the specified quantitative resource.
on_ok Whether to keep a Quantitative resource tied to a job if the job ends OK.
Valid values are:
 release
 discard
on_ok is relevant only for jobs running in Control-M for z/OS version 6.2.00 and
later.
on_fail Whether to keep a Quantitative resource tied to a job if the job does not end OK.
Valid values are:
 keep
 release
on_fail is relevant only for jobs running in Control-M for z/OS version 6.2.00 and
later.
329
out_condition XML parameters

The following figure describes the out_condition XML parameters:
The following table describes the out_condition XML parameters:


Valid values:
 add
 delete
330
step_range XML parameters

The following figure describes the step_range XML parameters:
The following table describes the step_range XML parameters:
331
shouts XML parameters

The following figure describes the shouts XML parameters:
332
The following table describes the shouts XML parameters:
parameters.
time Time that the message is sent.

Valid values:
 urgent
 very_urgent
when Time that the Shout message was sent.

Valid values:
 ok
 not_ok
 rerun (not valid for SMART Folder entities)
 late_submission
 late_time
 execution_time
shout_days_offset The number of days relative to the ODAT by which the sending of the Shout
message is offset.
Valid values are:
 a number from 0 through 254
 blank – no offset
shout_days_offset is relevant only for jobs running in Control-M for z/OS version
6.2.00 and later.
333
rule_based_cal XML parameters

The following figure describes the rule_based_cal XML parameters:
334
The following table describes the rule_based_cal XML parameters:
rule_base_cal_name The name of the Rule-Based Calendar.
keep_active Maximum number of days that the job can wait to be executed after its original
scheduling date has passed.
and_or Indicates the relationship between Month Days parameter values and Week Days
parameter values.
Optional.
days_cal Name of a user-defined calendar containing a list of days of the month, used with
Month Days, to determine a set of working days.
weeks_cal Name of a user-defined, week-based calendar used together with parameter Week
Days to specify a set of working days.
conf_cal Calendar used to confirm job scheduling dates.
retro Indicates whether the job should be scheduled for possible execution after its
original scheduled date has passed.
shift When to schedule the job if the date is not confirmed. (Option) Valid values are:
 ignore_job. Do not shift the job to a different date. The job is not scheduled.
 next_day. Shift to the next working date.
 prev_day. Shift to the previous working date.
 no_confcal. Tentatively schedule the job for the current day (even if not a
working day). Additional shifting may or may not be performed, depending on
the value indicated in the shift_num parameter.
shift_num The number of working days that a job can be shifted. Values from -62 to 62 can
be entered. This function is also called Extended Shift.
active_from Indicates the start of a period of time during which the job or SMART Folder can be
ordered.
active_till Indicates the end of a period of time during which the job or SMART Folder can be
ordered.
month_days Indicates the days of the month on which the job should be scheduled for
processing.
week_days Indicates the days of the week on which the job should be scheduled for
processing.
335
dates A sequence of date.

For more information, refer to Table 173.
Control-M for z/OS:
A maximum of 12 date elements can be specified.
JAN Indicates whether to run the job in this month. Valid values are:
 yes
 no
FEB Indicates whether to run the job in this month. Valid values are:
 yes
 no
MAR Indicates whether to run the job in this month. Valid values are:
 yes
 no
APR Indicates whether to run the job in this month. Valid values are:
 yes
 no
MAY Indicates whether to run the job in this month. Valid values are:
 yes
 no
JUN Indicates whether to run the job in this month. Valid values are:
 yes
 no
JUL Indicates whether to run the job in this month. Valid values are:
 yes
 no
AUG Indicates whether to run the job in this month. Valid values are:
 yes
 no
336
SEP Indicates whether to run the job in this month. Valid values are:
 yes
 no
OCT Indicates whether to run the job in this month. Valid values are:
 yes
 no
NOV Indicates whether to run the job in this month. Valid values are:
 yes
 no
DEC Indicates whether to run the job in this month. Valid values are:
 yes
 no
date parameters description

The following table describes the date parameters:
date Indicates a specific date, in either mmdd or ddmm format (depending on the site
standard), on which the job should be scheduled.
job_rule_based_cal XML parameters

The following figure describes the job_rule_based_cal XML parameters:
337
The following table describes the job_rule_based_cal XML parameters:
rule_based_cal_name The name of the rule based calendar.
interval_sequence XML parameters

The following figure describes the interval_sequence XML parameters:
The following table describes the interval_sequence XML parameters:
interval_item Time interval to rerun a cyclic job such as +2H, +1D, or +30M. Limited to 4000
characters for all fields.
Specific_times XML parameters

The following figure describes the specific_times XML parameters:
The following table describes the specific_times XML parameters:
specific_time Specific time for a cyclic job to run, such as 7:00 or 11:00. Limited to 4000 for all
fields.
338

Control-M API v8 PDF

Uploaded by

Copyright:

Available Formats

Control-M API v8 PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Control-M API v8 PDF

Uploaded by

Copyright:

Available Formats

Control-M Workload Automation

Outside United States and Canada

© Copyright 2012 BMC Software, Inc.

Control-M/EM API Installation ........................................................................................ 15

Control-M/EM API Upgrade ........................................................................................... 21

Control-M/EM API environment...................................................................................... 25

Issuing requests and handling responses........................................................................ 29

Class reference ............................................................................................................ 46

Introduction to Control-M/EM API requests ..................................................................... 68

Advanced features and optimization ............................................................................. 241

Diagnostics and troubleshooting .................................................................................. 247

Request format examples............................................................................................ 257

Error codes and exceptions ......................................................................................... 272

Category Document Description

Installation Control-M Workload Automation Describes the installation processes for

Control-M Workload Automation Describes administrator responsibilities,

Using Control-M Workload Automation Describes all Control-M/EM concepts,

Control-M Workload Automation Describes the parameters used for creating

Items in italic type represent variables that alias

Brackets indicate a group of optional items. [tableName, columnName, field]

Braces indicate that at least one of the {DBDName | tableName}

An ellipsis indicates that you can repeat the columnName . . .

How Control-M/EM API works

Authentication and user tokens

Control-M/EM API sessions

Control-M/EM API (EMXMLInvoker) use flow

Step User actions API actions

2 User starts Client-Side Application Program start

3 User Logs in to Control-M/EM API (client side) sends Register request

4 None Control-M/EM returns response

5 Submit request API (client side) translates request

6 None Control-M/EM returns response

Step User actions API actions

7 None API (client side) processes response

10 None Control-M/EM returns response

11 None Program stop

Installing Control-M/EM API

Before you begin

 To Install Control-M/EM API:

Control-M/EM API primary subdirectories

emapi-800\etc Contains the jacorb.properties file required for JacORB runtime

emapi-800\keystore Contains the emapi.keystore demo file required for JacORB

emapi-800\examples Contains sample implementations of the API.

Configuring Control-M/EM API

 To configure Control-M/EM API:

3. Run the emapi-configure.bat file (UNIX: emapi-configure).

emapi_env.bat Automatically adds API directory pathnames to the CLASSPATH

ctmemapi.properties Contains the locations of:

emapi-admin.bat Starts an interactive utility for changing the hostnames of the

Upgrading Control-M/EM API

Before you begin

 To upgrade the Control-M/EM API:

From version 7.0.00 to version 8.0.00

• request_def_add_jobs: Add jobs to folder definitions (on page 85)

version 7.0.00 version 8.0.00

The following requests/responses are affected by these changes:

From version 6.4.01 to version 7.0.00

earlier versions version 7.0.00

The following requests/responses are affected by these changes:

< less than <

> greater than >

& ampersand &

" quotation marks "

ASCII 10 line feed

ASCII 13 carriage return