CM Enterprise Manager API Developers Guide

CONTROL-M/Enterprise Manager API Developers Guide
Version 6.1.01
June 20, 2002
Copyright 2002 BMC Software, Inc., as an unpublished work. All rights reserved. BMC Software, the BMC Software logos, and all other BMC Software product or service names are registered trademarks or trademarks of BMC Software, Inc. Oracle is a registered trademark, and the Oracle product names are registered trademarks or trademarks of Oracle Corp. All other registered trademarks or trademarks belong to their respective companies.
THE USE AND CONTENTS OF THIS DOCUMENTATION ARE GOVERNED BY THE SOFTWARE LICENSE AGREEMENT ENCLOSED AT THE BACK OF THIS DOCUMENTATION.
Restricted Rights Legend

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

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

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

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

You can obtain technical support from BMC Software 24 hours a day, 7 days a week at http://www.bmc.com/support.html. From this Web site, you can read overviews about support services and programs that BMC Software offers find the most current information about BMC Software products search a database for problems similar to yours and possible solutions order or download product documentation report a problem or ask a question subscribe to receive e-mail notices when new product versions are released find worldwide BMC Software support center locations and contact information, including e-mail addresses, fax numbers, and telephone numbers
Support by Telephone or E-mail

In the United States and Canada, if you need technical support and do not have access to the Web, call 800 537 1813. Outside the United States and Canada, please contact your local support center for assistance. To find telephone and e-mail contact information for the BMC Software support center that services your location, refer to the Contact Customer Support section of the Support page on the BMC Software Web site at www.bmc.com/support.html.
Before Contacting BMC Software

Before you contact BMC Software, have the following information available so that Customer Support can begin working on your problem immediately: product information product name product version (release number) license number and password (trial or permanent)
operating system and environment information machine type operating system type, version, and service pack or other maintenance level such as PUT or PTF system hardware configuration serial numbers related software (database, application, and communication) including type, version, and service pack or maintenance level
BMC Software, Inc., Confidential and Proprietary Information
iii
sequence of events leading to the problem commands and options that you used messages received (and the time and date that you received them) product error messages messages from the operating system, such as file system full messages from related software
iv
CONTROL-M/Enterprise Manager Application Program Interface Developers Guide
Contents
Contents
About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Chapter 1 Overview
How the CONTROL-M/EM API Works . . . . . . . . . . . . . . . . . . . . . . 1-2 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 The APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Who Should Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Chapter 2 Installation
Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 CONTROL-M Product Support . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 Platform and Operating System Support . . . . . . . . . . . . . . . . . . 2-2 Additional Software Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Chapter 3 Configure the CONTROL-M/EM API
Preparing Your Project Environment . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 Writing Your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Running Your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Chapter 4 Creating Request Calls
CONTROL-M/EM API Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Session Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 Deciding Which Class to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 Response Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 XML String Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14 Using EMXMLInvoker Class Calls . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 Initializing and Stopping the CONTROL-M/EM API Services . 4-15
Contents
Submitting a Request Using the EMXMLInvoker class . . . . . . .4-16 Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20 Using EMBasicXMLInvoker Class Calls . . . . . . . . . . . . . . . . . . . . .4-21 Submit a Request Using the EMBasicXMLInvoker class . . . . . .4-21
Chapter 5 Response Handling
Response Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-2 Response String Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-2 EMAPI_tokenResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-3 EMAPI_PollResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-7 EMAPI_errorResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-7 EMAPI_<Requestname>Response . . . . . . . . . . . . . . . . . . . . .5-11 Interpreting Response Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-12 Parts of a Response String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-12 Analyzing a Response String . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-13
Chapter 6 Advanced Features and Optimization
Modifying Initialization Properties . . . . . . . . . . . . . . . . . . . . . . . . . .6-1 Prototype 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-2 Prototype 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-3 Prototype 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-4 Getting and Setting CONTROL-M/EM API Properties . . . . . . . . . .6-6 getProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-6 setProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-7 Polling Interval Timeout Configuration . . . . . . . . . . . . . . . . . . . . . . .6-8 setPollRequestIntervalMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-9 setPollRequestTimeoutMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-9
Chapter 7 Diagnostics and Troubleshooting
CONTROL-M/EM API Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1 Default Logging Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2 Modifying Logging Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2 Environment Configuration Troubleshooting . . . . . . . . . . . . . . . . . .7-6 CLASSPATH: Missing Libraries or Directories . . . . . . . . . . . . .7-6 Java Virtual Machine Parameters . . . . . . . . . . . . . . . . . . . . . . . .7-7 Orbix Domain Initialization Failure . . . . . . . . . . . . . . . . . . . . . .7-10 Application Runtime and Communication Troubleshooting . . . . . . .7-11
Chapter 8 Call Reference
ComponentType Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3

vi
EMBasicXMLInvoker Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 invoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6 setPollRequestIntervalMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7 setPollRequestTimeoutMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8 EMXMLInvoker Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9 done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10 encodePassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11 getProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12 init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13 invoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16 setProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17 GASComponent Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18 GASComponent (Prototype 1) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19 GASComponent (Prototype 2) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20 GSRComponent Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21 GSRComponent (Prototype 1) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22 GSRComponent (Prototype 2) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23 InvokeException Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24 getMajorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-25 getMinorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26 getReason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27
Chapter 9 Request Reference
Add/Delete Condition Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10 Change Alert Status Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11 Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16 Job Creation Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17 Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-53 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-58 Order/Force Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-59 Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-59 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-64 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-76 Polling Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-77
Contents
vii
Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-77 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-79 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-82 Timeout Reset Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-83 Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-83 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-85 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-88 Tracking Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-89 Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-89 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-92 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-97 User Registration Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-98 Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-98 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-101 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-104 User Unregistration Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-105 Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-105 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-108 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-111
Appendix A Request Format Examples
Add Condition/Delete Condition Request . . . . . . . . . . . . . . . . . . . . A-2 Example 1: Add a Condition to a CONTROL-M . . . . . . . . . . . A-2 Example 2: Delete a Condition from a CONTROL-M . . . . . . . A-2 Job Creation Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 Example 1: Create a Job Requiring Confirmation . . . . . . . . . . A-3 Example 2: Create a Cyclic Job . . . . . . . . . . . . . . . . . . . . . . . . . A-4 Example 3: Create a Job Including In and Out Conditions . . . . A-5 Example 4: Create a Job that Requires Resources . . . . . . . . . . A-6 Example 5: Create a Job that Includes On-Do Statements . . . . A-7 Example 6: Create a Job that Includes On-Do Statements . . . . A-8 Order/Force Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9 Example 1: Order a Unix Job . . . . . . . . . . . . . . . . . . . . . . . . . . A-9 Example 2: Force a Unix Job . . . . . . . . . . . . . . . . . . . . . . . . . . A-9 Example 3: Force a Unix Job into a Recent Group Scheduling Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10 Example 4: Force a Unix Job into a Recent Group Scheduling Table while Allowing for Duplication . . . . . . . . . . . . . . . . . . A-11 Example 5: Force a Scheduling Table that Contains a Group Scheduling Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12
viii
Appendix B
Error Codes and Exceptions
Severity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-2 Error Code Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-4 NULL Exception Errors (Major Code 000) . . . . . . . . . . . . . . . .B-6 Low-level API Exceptions (Major Code 100) . . . . . . . . . . . . . .B-7 Parser Exceptions (Major Code 200) . . . . . . . . . . . . . . . . . . . . .B-8 CONTROL-M/Server Errors: Group 1 (Major Code 300) . . . . .B-9 CONTROL-M/Server Errors: Group 2 (Major Code 301) . . . . .B-12 CONTROL-M/Server Errors: Group 3 (Major Code 302) . . . . .B-14 Generic Request Exceptions (Major Code 401) . . . . . . . . . . . . .B-15 Poll Request Errors (Major Code 403) . . . . . . . . . . . . . . . . . . . .B-16 Add/Delete Condition Request Errors (Major Code 404) . . . . .B-17 Order/Force Request Errors (Major Code 405) . . . . . . . . . . . . .B-18 Tracking Request Errors (Major Code 406) . . . . . . . . . . . . . . . .B-19 Authorization Request Errors (Major Code 407) . . . . . . . . . . . .B-20 Alerts Request Errors (Major Code 408) . . . . . . . . . . . . . . . . . .B-21 Create Active Job Request Errors (Major Code 409) . . . . . . . . .B-22 CONTROL-M/EM API Java Client Errors (Major Code 500) . .B-23 Gateway Messages (Major Code 600) . . . . . . . . . . . . . . . . . . . .B-24
Glossary Index
Contents
ix
Figures
Figures
Figure 1-1 Figure 3-1 Figure 4-1 Figure 4-2 Figure 4-3 Figure 4-4 Figure 5-1 Figure 7-1 Figure 7-2 CONTROL-M/EM API Flow Diagram . . . . . . . . . . . . . . . . . . . Sample Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comparison of Request Methods. . . . . . . . . . . . . . . . . . . . . . . . EMBasicXMLInvoker Request Session . . . . . . . . . . . . . . . . . . EMXMLInvoker Request Session . . . . . . . . . . . . . . . . . . . . . . . EMXMLInvoker Polling Request Steps . . . . . . . . . . . . . . . . . . Order/Force Response Example . . . . . . . . . . . . . . . . . . . . . . . . emapi_log.cfg File Example with Default Parameters . . . . . . . RollingFileAppender Example Properties . . . . . . . . . . . . . . . . . 1-3 3-3 4-8 4-10 4-12 4-13 5-15 7-3 7-5
Figures
xi
xii
Tables
Tables
Table 2-1 Table 2-2 Table 2-3 Table 2-4 Table 2-5 Table 4-1 Table 4-2 Table 4-3 Table 4-4 Table 5-1 Table 5-2 Table 5-3 Table 6-1 Table 7-1 Table 8-1 Table 8-2 Table 8-3 Table 8-4 Table 8-5 Table 8-6 Table 9-1 Table 9-2 Table 9-3 Table 9-4 Table 9-5 Table 9-6 Table 9-7 Table 9-8 Supported Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . Supported Database Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . CONTROL-M/EM API Compressed File Names . . . . . . . . . . . CONTROL-M/EM API Primary Subdirectories . . . . . . . . . . . . Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONTROL-M/EM API (EMXMLInvoker) Use Flow . . . . . . . Request Types Listed by Component Type . . . . . . . . . . . . . . . . Polling Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Types Listed by Component Type . . . . . . . . . . . . . . . . Response String Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Token Response XML Parameters Description . . . . . . . . . . . . . Error Response XML Parameters Description . . . . . . . . . . . . . CONTROL-M/EM API Properties Parameters . . . . . . . . . . . . . Log Message Priority Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . CONTROL-M/EM API Classes . . . . . . . . . . . . . . . . . . . . . . . . EMBasicXMLInvoker Methods. . . . . . . . . . . . . . . . . . . . . . . . . EMXMLInvoker Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GASComponent Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . GASComponent Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . InvokeException Class Methods . . . . . . . . . . . . . . . . . . . . . . . . Requests Listed in this Chapter . . . . . . . . . . . . . . . . . . . . . . . . . Request Reference Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Add/Delete Condition XML Parameters Description . . . . . . . . Add/Delete Condition Response XML Parameters Description Change Alert Status XML Parameters Description . . . . . . . . . . Change Alert Status Response XML Parameters Description. . Job Creation Request XML Parameters Description . . . . . . . . . Order/Force XML Parameters Description . . . . . . . . . . . . . . . . 2-2 2-2 2-4 2-5 2-6 4-3 4-18 4-20 4-22 5-2 5-4 5-8 6-7 7-3 8-1 8-4 8-9 8-18 8-21 8-24 9-1 9-2 9-5 9-8 9-11 9-14 9-22 9-61
Tables
xiii
Table 9-9 Table 9-10 Table 9-11 Table 9-12 Table 9-13 Table 9-14 Table 9-15 Table 9-16 Table 9-17 Table 9-18 Table 9-19 Table 9-20 Table B-1 Table B-2 Table B-3 Table B-4 Table B-5 Table B-6 Table B-7 Table B-8 Table B-9 Table B-10 Table B-11 Table B-12 Table B-13 Table B-14 Table B-15 Table B-16 Table B-17 Table B-18
Order/Force Response XML Parameters Description (Native API) 9-66 Order/Force Response XML Parameters Description (Basic API) 9-72 Polling Request XML Parameters Description . . . . . . . . . . . . . 9-78 Poll Response XML Parameters Description . . . . . . . . . . . . . . . 9-80 Timeout Reset Request XML Parameters Description. . . . . . . . 9-84 Timeout Reset Response XML Parameters Description . . . . . . 9-86 Tracking Request XML Parameters Description . . . . . . . . . . . . 9-90 Tracking Request Response XML Parameters Description . . . . 9-93 Registration Request XML Parameters Description . . . . . . . . . 9-99 User registration Response XML Parameters Description. . . . . 9-101 Unregistration Request XML Parameters Description . . . . . . . . 9-105 User Unregistration Response XML Parameters Description . . 9-109 Log Message Priority Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 Error and Exception Major Codes . . . . . . . . . . . . . . . . . . . . . . . B-4 NULL Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-6 Low Level API Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7 Parser Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-8 CONTROL-M/Server Errors: Group 1. . . . . . . . . . . . . . . . . . . . B-9 CONTROL-M Server Errors: Group 2. . . . . . . . . . . . . . . . . . . . B-12 CONTROL-M Server Errors: Group 3. . . . . . . . . . . . . . . . . . . . B-14 Generic Request Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . B-15 Poll Request Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-16 Add/Delete Condition Request. . . . . . . . . . . . . . . . . . . . . . . . . . B-17 Order/Force Request Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-18 Job Tracking Request Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . B-19 Authorization Request Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . B-20 Alerts Request Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-21 Create Active Job Request Errors. . . . . . . . . . . . . . . . . . . . . . . . B-22 CONTROL-M/EM API Java Client Errors . . . . . . . . . . . . . . . . B-23 Gateway Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-24
xiv
About . . .
About This Book

This book contains detailed information about the CONTROL-M/Enterprise Manager API and is intended for programmers who want to access the capabilities of the CONTROL-M job scheduling environment from their own applications. Use this book with the CONTROL-M/Enterprise Manager documentation set and the CONTROL-M Administrator Guide for your version of CONTROL-M.
Note
To get the most benefit from this book, you should be familiar with your host operating system.
This book is organized as follows. In addition, a glossary of terms and an index appear at the end of the book.
Chapter /Appendix
Chapter 1
Description
Overview Describes what the CONTROL-M/EM API can do and how it works. Installation Describes thow to install the API fileson your computer. Configure the CONTROL-M/EM API Describes the how to configure the CONTROL-M/EM API for use in your projects.
Chapter 2 Chapter 3
About This Book
xv
Chapter /Appendix
Chapter 4
Description
Creating Request Calls Describes how to initialize the API and create requests to CONTROL-M/EM. Response Handling Describes the types of responses that are sent by CONTROL-M/EM and how to handle them in your project. Advanced Features and Optimization Describes advanced, optional procedures for further configuring use of the CONTROL-M/EM API. Diagnostics and Troubleshooting Describes methods for identifying and resolving problems that may occur when using the CONTROL-M/EM API. Call Reference Describes the classes and methods of the CONTROL-M/EM API calls. Request Reference Describes how to format the XML request strings that are sent to CONTROL-M/EM. Request Format Examples Presents sample request files. Error Codes and Exceptions Describes the various return codes that can be displayed when using the CONTROL-M/EM API.
Chapter 5
Chapter 6
Chapter 7
Chapter 8
Chapter 9
Appendix A Appendix B
Related Documentation
BMC Software products offer several types of documentation: online and printed books online Help release notes
In addition to this book, you can find useful information in the publications listed in the following table.
xvi
CONTROL-M User Manual (OS/390) describes all CONTROL-M concepts, features, facilities and operating instructions in detail. It can be used as a learning guide as well as a reference guide. CONTROL-M Administrator Guides are supplied based on the type of computer(s) in each sites CONTROL-M installation(s). These guides describe installation, setup, security and utilities that apply to CONTROL-M for OpenVMS, and AS/400 platforms. CONTROL-M/Agent Administrator Guide describes installation and maintenance of CONTROL-M/Agent on the various types of supported platforms. CONTROL-M/Server Administrator Guide describes installation and maintenance of CONTROL-M/Server on the various types of supported platforms. CONTROL-M/Enterprise Manager User Guide describes all CONTROL-M/EM concepts, features, facilities and operating instructions in detail. It can be used as a learning guide as well as a reference guide. CONTROL-M/Enterprise Manager Administrator Guide describes administrator responsibilities, customization, maintenance and security of CONTROL-M/EM. CONTROL-M/Desktop User Guide describes components used to define and manage CONTROL-M job processing definitions, Scheduling tables, and Calendars in CONTROL-M/EM. CONTROL-M Installation Guide describes the installation processes for implementing CONTROL-M/EM and CONTROL-M/Server environments on Microsoft Windows and Unix platforms. CONTROL-M Job Parameter and Variable Reference Guide describes the parameters used for creating job processing definitions.
About This Book
xvii
CONTROL-M/Enterprise Manager Utilities Reference Guide describes the utilities used for creating and managing objects in the job production environment and maintaining various aspects of CONTROL-M/Enterprise Manager.
Online and Printed Books

The books that accompany BMC Software products are available in online format and printed format. You can view online books with Acrobat Reader from Adobe Systems. The reader is provided at no cost, as explained in To Access Online Books. You can also obtain additional printed books from BMC Software, as explained in To Request Additional Printed Books.
To Access Online Books
Online books are formatted as Portable Document Format (PDF) files. You can view them, print them, or copy them to your computer by using Acrobat Reader 3.0 or later.You can access online books from the documentation compact disc (CD) that accompanies your product or from the World Wide Web. In some cases, installation of Acrobat Reader and downloading the online books is an optional part of the product-installation process. For information about downloading the free reader from the Web, go to the Adobe Systems site at http://www.adobe.com. To view any online book that BMC Software offers, visit the support page of the BMC Software Web site at http://www.bmc.com/support.html. Log on and select a product to access the related documentation. (To log on, first-time users can request a user name and password by registering at the support page or by contacting a BMC Software sales representative.)
To Request Additional Printed Books
BMC Software provides a core set of printed books with your product order. To request additional books, go to http://www.bmc.com/support.html.
xviii
Release Notes
Printed release notes accompany each BMC Software product. Release notes provide up-to-date information such as updates to the installation instructions last-minute product information
The latest versions of the release notes are also available on the Web at http://www.bmc.com/support.
Conventions
The following abbreviations are used in this guide:
Abbreviation
CONTROL-M/EM Net <home-directory>
Description
CONTROL-M/Enterprise Manager CONTROL-M/EM Network Directory in which CONTROL-M/EM is installed
The following conventions are used in this guide:

<key> When describing keystrokes, angle brackets are used to enclose the name of a key (for example, <F1>). When two keys are joined with + as in <Shift>+<F1>, hold down <Shift> while pressing <F1>. This represents an option selection sequence. For example, Users and Groups => Groups => Add means that you first select Users and Groups from the menu bar. Select the Groups option from the submenu. Finally, select the Add option from the Groups submenu.
Menu => Option
About This Book
xix
{Option A|Option B}
The vertical bar is used to separate choices. For example: {AND|OR} means that you specify either AND or OR.
[Option] Code Samples
Square brackets are used to enclose parameters that are optional. Format syntax, operating system terms, literal examples, and JCL scripts are presented in this typeface. In instructions, boldface type highlights information that you enter. File names, directory names and paths, dialog box names, and Web addresses also appear in boldface type. Italic type is used to emphasize important terms. The titles of BMC Software product documentation are also displayed in italic type. The symbol
Boldface
Italics
One-Step Procedures Ellipsis
denotes one-step instructions.
An ellipsis ( . . . ) indicates that you can repeat the preceding item or items as many times as necessary. A vertical bar ( | ) separating items indicates that you must choose one item. In the following example, you would choose a, b, or c: a|b|c
Option Symbol
xx
Overview
The CONTROL-M/Enterprise Manager API is an open interface for external applications that enables you to exploit the capabilities of CONTROL-M/EM and CONTROL-M. The 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/EM Create jobs and Group Scheduling tables in the CONTROL-M Active Jobs file Order and force jobs Order and force Scheduling tables Track job execution Manipulate Conditions Manipulate Alerts
Overview
1-1
How the CONTROL-M/EM API Works

The CONTROL-M/EM API is a set of Java classes that expose an existing set of functions in the server side. These classes enable Java developers to send requests to CONTROL-M/EM server components from within their own applications. Requests can be sent after the API has been initialized.
Initialization
Before sending requests, the CONTROL-M/EM API must be initialized. To initialize the API is to initialize the CORBA processes that forward requests from the client side of the API to the CONTROL-M/EM GUI Server and the Global Alerts Server.
The APIs
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 the EMXMLInvoker or EMBasicXMLInvoker, chooses which component to communicate with, and authenticates him or herself with the API. From them on, an unlimited number of requests can be sent. Each API request has a pre-determined syntax and a set of parameters. There are two distinct invocation methods: Native (EMXMLInvoker class) Basic (EMBasicXMLInvoker class)
1-2
The differences between the two classes is described in Deciding Which Class to Use on page 4-7. When the user is finished sending requests, the CONTROL-M/EM API can be stopped or can be left running for the next user.
Figure 1-1 CONTROL-M/EM API Flow Diagram
Who Should Use This Guide

The CONTROL-M/Enterprise Manager Application Program Interface Developers Guide is intended for application developers who are creating applications from which job scheduling requests will be sent to a CONTROL-M/EM installation for processing. To get the most out of this Guide, it is recommended that you familiarize yourself with CONTROL-M/EM features and job processing parameters. To learn more, see the books in the CONTROL-M documentation set. These books are listed in Related Documentation in About This Book.
Overview
1-3
1-4
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. The following topics are described: Software Requirements Installation
Software Requirements
For the CONTROL-M/EM API to operate properly, supported software and hardware must be installed.
CONTROL-M Product Support

The CONTROL-M/EM API is compatible with the following version of CONTROL-M/EM:
CONTROL-M/EM version 6.1.0x.
Installation
2-1
The CONTROL-M/EM API is compatible with the following versions of CONTROL-M:
CONTROL-M/Server for Windows NT version 6.1.0x CONTROL-M/Server for Unix version 6.1.0x CONTROL-M for OS/390 version 6.1.0x
Platform and Operating System Support

The CONTROL-M/EM API is compatible with the operating systems listed in Table 2-1 and the database servers listed in Table 2-2.
Table 2-1 Supported Operating Systems
Component
API Client Component
Microsoft Windows Versions

Windows NT 4.0 with service pack 6a Windows 2000 Professional Windows 2000 Server Windows 2000 Advanced Server
Unix Platforms
IBM AIX 4.3.3 Sun Solaris 2.6, 2.7, and 2.8 HP-UX 11.0 and 11.11, using the long filenames option
Table 2-2
Supported Database Servers
Microsoft Windows
Oracle Server versions 8.1.7, 9i Sybase Adaptive Server versions 12, 12.5 MSSQL versions 7.0 and 2000
Unix Platforms
Oracle Server versions 8.1.7, 9i Sybase Adaptive Server versions 12, 12.5
2-2
Additional Software Support

Before installing the CONTROL-M/EM API, ensure that the following requirements are met: CONTROL-M/EM is installed on your network. Either the Java Developers Kit (JDK) version 1.3 or the Java Runtime Environment (JRE) version 1.3 is installed on the computer hosting your projects working directory. The JAVA_HOME environment variable points to the JDK (or JRE) directory/library on the computer hosting your projects working directory.
Note
The CONTROL-M/EM API uses the Orbix 2000 version 1.2 CORBA implementation as the carrier for API requests. Orbix 2000 version 1.2 Server is installed together with CONTROL-M/EM. An Orbix client is installed together with the API.
Installation
2-3
Installation
The CONTROL-M/EM API can be installed on either Microsoft Windows or Unix computers. For more detailed compatibility information, see CONTROL-M Product Support on page 2-1.
Step 1
Install the CONTROL-M/EM API to a Unix or Microsoft Windows computer. Unzip or untar the appropriate compressed file. Use one of the following procedures:
Microsoft Windows
Using Microsoft Windows Explorer, navigate to the <CD>:\emapi_files\emapi-610-nt.zip file on the CONTROL-M/EM installation CD. Double-click on the filename.
Unix
Enter the following command for AIX and HP-UX: uncompress -c <CD_path>/emapi_files/<filename>.Z | tar xvf Enter the following command for Solaris:
uncompress -c <CD_path>/EMAPI_FILES/<filename>.Z | tar xvf -
The appropriate file is located on your CONTROL-M/EM installation CD in the <CD>\emapi_files directory.Filenames are listed in Table 2-3.
Table 2-3 CONTROL-M/EM API Compressed File Names
Platform
Microsoft Windows Solaris HP-UX AIX
Compressed File Name

emapi-610-nt.zip emapi-610-sparc.tar emapi-610-hp11.tar emapi-610-aix.tar
2-4
The emapi-610 directory tree is created. All CONTROL-M/EM API files are located under this directory. Four primary subdirectories are created under the emapi-610 directory. They are described in Table 2-4.
Table 2-4 CONTROL-M/EM API Primary Subdirectories
Directory
emapi-610\iona
Description
Contains files for running the Orbix Java Client, used for communication between the API and the CONTROL-M/EM GUI Server and the Global Alerts Server. Includes: omg.jar orbix2000.jar Contains the .dtd files that validate the xml-formatted request strings sent and received using the API. Contains sample implementations of the API. Contains the API .jar files, including: emapi.jar The API implementation files. log4j.jar Files used by the API logging facility.
emapi-610\xmldata
emapi-610\examples emapi-610\classes
The processes for configuring the 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. These differences, and the names of other files that are used during configuration are described in Table 2-5.
Installation
2-5
Table 2-5
Configuration Files
Name
emapi-configure.exe (on Microsoft Windows) emapi-configure (on Unix) emapi-env.bat (on Microsoft Windows) emapi-env.sh (on Unix) ctmemapi.properties
Description
Creates files used in later stages of configuration and enables the API with access other key components. These components include: The Orbix Locator The CONTROL-M/EM GUI Server The Global Alerts Server. Automatically adds API directory pathnames into the CLASSPATH environment variable. Note: This file is created by the emapi-configure(.exe) file when it is run. Contains the locations of: CONTROL-M/EM GUI Server Global Alerts Server XMLDATAPATH property Note: This file is created by the emapi-configure(.exe) file when it is run. Starts an interactive utility for changing the hostnames of the CONTROL-M/EM GUI Server and Global Alerts Server.
emapi-admin.bat (on Microsoft Windows) emapi-admin.sh (on Unix)
Step 2
Locate CONTROL-M/EM components.

2.A
Obtain the following information: The Orbix Locator hostname and port Hostnames of the CONTROL-M/EM GUI Server and Global Alerts Server
2.B
Run the emapi-610\emapi-configure.exe file (Unix: emapi-610\emapi-configure). At the prompt, the following text is displayed:
This script will configure EM/API library Execute configure -? for more details. Press any key to begin. [continue]:
2-6
2.C
Press any key. If CONTROL-M/EM is not installed on this computer, go to Step 2.D on page 2-7. If CONTROL-M/EM is installed on the computer, the following prompt is displayed:
CONTROL-M/Enterprise Manager detected. -----------------------------------------CONTROL-M/Enterprise Manager configuration detected. Do you want to use the same Orbix configuration? Press Y to use the current Orbix configuration properties. Go to Step 2.F on page 2-7. Press N to supply new Orbix configuration information. Continue with Step 2.D
2.D
Press any key. The following prompt is displayed: Orbix 2000 - Locator hostname -------------------------------------------Enter the Orbix 2000 - Locator hostname (press Enter if local) [nt-tlv357]:
2.E
Enter the name of the Orbix 2000 Locator host computer and press Enter. The following prompt is displayed: Orbix 2000 - Locator port number -------------------------------------------Enter the Orbix 2000 - Locator port (press Enter to accept the default) [3075]:
2.F
Enter the port number that the Orbix 2000 Locator uses and press Enter. The following prompt is displayed:
Installation
2-7
Control-M/Enterprise Manager - GUI Server hostname -------------------------------------------Enter the GUI Server hostname (press Enter if local) [nt-tlv357]:
2.G
Enter the name of the CONTROL-M/EM GUI Server host computer and press Enter. The following prompt is displayed: Control-M/Enterprise Manager - Global Alerts Server hostname -------------------------------------------Enter the Global Alerts Server hostname (press Enter if local) [apihost]:
2.H
Enter the name of the CONTROL-M/EM Global Alerts Server host computer and press Enter.
Installation is complete. You must now prepare your project and its environment to use the CONTROL-M/EM API. These issues are discussed in Chapter 3, Configure the CONTROL-M/EM API.
2-8
Configure the CONTROL-M/EM API 3

You must perform a number of steps in your project to prepare it to use the CONTROL-M/EM API. This chapter describes the following topics: Preparing Your Project Environment Writing Your Project Running Your Project
Preparing Your Project Environment

Prior to using the CONTROL-M/EM API, you must configure the API for use in your project development environment. When you want to release your project for use, you must configure the CONTROL-M/EM API running environment.
Note
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 program is released for use.
Configure the CONTROL-M/EM API
3-1
Follow these steps for both the development environment and the running environment.
Step 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.
Step 2
Copy the emapi-610\ctmemapi.properties file to your projects working directory.
3-2
Writing Your Project

Certain steps must be performed in your project to enable it to make use of the CONTROL-M/EM API. The following steps describe a class that uses the CONTROL-M/EM API. You may use this class as a basis for building your project. A sample class is displayed in Figure 3-1.
Figure 3-1 Sample Class
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=""; // 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; } }
Step 1
Import the CONTROL-M/EM API into your project with the following command:
import com.bmc.ctmem.emapi.*;
3-3
Step 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 4-15.
Example EMXMLInvoker.init();
Step 3
Select the CONTROL-M/EM component with which the project will communicate (the CONTROL-M/EM GUI Server or the Global Alerts Server).
Example: GUI Server ComponentType gsr_comp = new GSRComponent();
For more information, see Submitting a Request Using the EMXMLInvoker class on page 4-16.
Step 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 4-16. The class is now ready. You can use it in your project.
Step 5
Compile your project.
3-4
To run your project, you must pass it the relevant Java Virtual Machine variables. This is discussed in Running Your Project on page 3-6.
3-5
Running Your Project

Step 1
Set the environment variables for the 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.
Step 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 commands:
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
Step 3
Copy the emapi-610\ctmemapi.properties file to your projects working directory. Run the java command from the project working directory, using the following CORBA parameters: These parameters are needed by the CONTROL-M/EM API. Pass them to your project as the first and second runtime parameters.
For Microsoft Windows
java.exe -Dorg.omg.CORBA.ORBClass=com.iona.corba.art.artimpl.ORBImpl -Dorg.omg.CORBA.ORBSingletonClass=com.iona.corba.art.artimpl.ORBSingleton -classpath %CLASSPATH% <project_main_class>
Step 4
3-6
For Unix
java -Dorg.omg.CORBA.ORBClass=com.iona.corba.art.artimpl.ORBImpl -Dorg.omg.CORBA.ORBSingletonClass=com.iona.corba.art.artimpl.ORBSingleton -classpath $CLASSPATH <project_main_class>
where <project_main_class> is your project main class.

Note
The command must be entered as a single line. It is divided here to fit on the page.
Note
Optionally, you can pass these parameters using one of the alternative methods are described in Java Virtual Machine Parameters on page 7-7.
3-7
3-8
Creating Request Calls
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 their own applications. This chapter discusses the following topics: CONTROL-M/EM API Sessions Deciding Which Class to Use Using EMXMLInvoker Class Calls Using EMBasicXMLInvoker Class Calls
CONTROL-M/EM API Sessions

The CONTROL-M/EM API enables users of your program to submit requests to a CONTROL-M installation. For your program to use the CONTROL-M/EM API, your program must be able to perform the following mandatory actions: Initialize the CONTROL-M/EM API at program startup. Mandatory. Stop the CONTROL-M/EM API at program shutdown. Mandatory. Enable users to send a Register request to log on to CONTROL-M/EM and an Unregister request to log off. Mandatory.
Creating Request Calls 4-1
Encode the password string that is used in the register request. Mandatory. Extract the user token supplied in the EMAPI_registerResponse response. Include this token in future communications using the API. Mandatory. When the EMXMLInvoker class is used, automate the sending of Polling requests to monitor the outcome of requests that require polling. The EMBasicXMLInvoker automates polling internally. Translate user actions into requests that the CONTROL-M/EM API can send and receive those requests. Mandatory. Parse the XML-formatted responses that the server side of the CONTROL-M/EM API returns to extract relevant data for use in your program. Mandatory.
These mandatory actions must be performed in a specific order. To illustrate this concept, an example of a CONTROL-M/EM API session is presented below. In the example, the actions of the program user are shown together with the corresponding actions that your program must perform to use the CONTROL-M/EM API.
4-2
Session Example
The user logs on to a program, submits a Job Creation request to CONTROL-M/EM, and logs off. To do so, the user performs the following actions: 1. The user logs on to the host computer of the program that uses the CONTROL-M/EM API. 2. The user starts the program that uses the 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). In reality, far 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. these actions are described in Table 4-1.
Table 4-1 CONTROL-M/EM API (EMXMLInvoker) Use Flow (Part 1 of 4)
Step
1
User Actions
Log in End user logs on to a remote computer to use a program that uses the CONTROL-M/EM API. User starts Client-Side Program End user starts the program.
API Actions
None.
Program start Required action: Initialize the API using the init method of the EMBasicXMLInvoker class. Usage: Mandatory.
4-3
Table 4-1
CONTROL-M/EM API (EMXMLInvoker) Use Flow (Part 2 of 4)
Step
3
User Actions
User Logs in to CONTROL-M/EM End user must supply a username and password.
API Actions API (client side) sends Register request

Required actions: Encode password. Use the encodePassword method. Usage: Mandatory, if the password was not already encoded. Encoded strings can be reused. Submit Register request. Use the invoke method of the EMBasicXMLInvoker class, supplying the Register request string as a parameter. Usage: Mandatory. CONTROL-M/EM returns response Required action: CONTROL-M/EM returns an EMAPI_registerResponse response. This response containing a unique user token. If the Registration request was unsuccessful, the response will contain a list of errors. Usage: Mandatory.
None.
Submit request Required action: User makes request that results in a job being submitted to CONTROL-M/EM. Usage: Mandatory. None.
API (client side) translates request Required action: API translates user action into a Job Creation request that is sent to CONTROL-M/EM using the invoke method of the EMXMLInvoker class. Usage: Mandatory.
CONTROL-M/EM returns response Required actions: CONTROL-M/EM sends one of the following responses: EMAPI_AsyncResponse returns Tracking ID EMAPI_errorResponse returns errors EMAPI_<Async_Request_Name>Response returns the actual response API (client side) polls for answer Required actions: Parse Tracking ID from response Program initiates polling by sending a Poll request using the invoke method. Poll request includes Tracking ID. Usage: Mandatory.
None.
4-4
Table 4-1
Step
8
User Actions
None.
API Actions
CONTROL-M/EM returns response Required actions: CONTROL-M/EM automatically sends a response that can be one of the following: EMAPI_errorResponse returns errors EMAPI_PollResponse returned when request being executed EMAPI_<Async_Request_Name>Response returns the actual outcome of the request Usage: Mandatory. API (client side) processes response Required actions: The program parses the reponse. Usage: Mandatory. If response is an error, notify user If response is actual outcome of the request, notify user of outcome If request still being processed, send additional poll request Usage: Mandatory. Continue Polling from API (client side) Required actions: Program initiates polling by sending a Poll request using the invoke method. Poll request includes Tracking ID. Usage: Mandatory. Note: Continue polling and processing responses until receiving an EMAPI_<Async_Request_Name>Response reponse, which returns the actual outcome of the request. Note: If an error severe enough to stop the request process is received instead, the program should be examined and the user session ended. API (client side) processes response Required actions: The program parses the response and notifies the user of the outcome of the request. Usage: Mandatory.
None.
10
None.
11
None.
4-5
Table 4-1
Step
12
User Actions
Submit request Required action: User makes request. Usage: Optional. User Logs off of CONTROL-M/EM
API Actions
Repeat steps 5-11 for each request that requires polling.
13
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 supplied in step 4. Usage: Mandatory.
14
None.
CONTROL-M/EM returns response Required action: CONTROL-M/EM send an EMAPI_unregisterResponse response. This response notifies the user that he has been logged off. If the Unregistration request was unsuccessful, the response will contain a list of errors. Usage: Mandatory. Program stop (Optional) Required action: Stop the API using the done method. Usage: Mandatory, when the program is stopped.
15
None.
4-6
Deciding Which Class to Use

The EMXMLInvoker and EMBasicXMLInvoker classes can be used together in the same project. However, you must decide which class is most suitable for your purposes.
Note
The EMBasicXMLInvoker and EMXMLInvoker classes may be used interchangeably, even in the same session. Since the EMBasicXMLInvoker class inherits from the EMXMLInvoker class you need to initialize the API only once. The two classes differ in only two respects. They are that: The EMXMLInvoker requires you to poll manually for responses. The EMBasicXMLInvoker polls automatically for responses. This is discussed in Response Handling on page 4-7. The EMBasicXMLInvoker uses .dtd files to validate XML-formatted requests/responses, but the EMXMLInvoker class does not. This is discussed in XML String Validation on page 4-14.
Response Handling
The EMXMLInvoker requires you to poll manually for responses. The EMBasicXMLInvoker polls automatically for responses. The EMBasicXMLInvoker behavior is described in When to Use the EMBasicXMLInvoker class on page 4-9. The EMXMLInvoker behavior is described in When to Use the EMXMLInvoker Class on page 4-11.
Figure 4-1 illustrated the structural differences between the two request methods.
4-7
Figure 4-1
Comparison of Request Methods
4-8
When to Use the EMBasicXMLInvoker class
The EMBasicXMLInvoker class 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. The advantage is that the user does not have to process the responses or place additional requests. There are, however, some disadvantages to using only the EMBasicXMLInvoker class: The API call may be blocked for several seconds, generally until the final response is available or the call times out. The time-out period is configurable. The EMBasicXMLInvoker class performs additional processing after receiving the response so it can determine its course of action. The EMBasicXMLInvoker class performs XML parsing. This makes it more resource-intensive than the EMXMLInvoker class.
4-9
EMBasicXMLInvoker Request Session Diagram
Figure 4-2
EMBasicXMLInvoker Request Session
4-10
When to Use the EMXMLInvoker Class
The EMXMLInvoker class communicates XML-formatted requests to CONTROL-M/EM and returns responses to the program that issued the requests. It does not do any post processing of the response data. Certain requests (such as the Job Creation request) take time for CONTROL-M to process. As a result, they do not return a response that contains the outcome of the request (because that outcome has not yet been determined). A user of the EMXMLInvoker class may have to make several requests to check whether the expected response is available. To facilitate this, the user 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: Order/Force Request Add/Delete Condition Request Job Creation Request
The program must submit this tracking ID in a poll request several times, until the required response is available.
4-11
EMXMLInvoker Request Session Diagrams
Figure 4-3
EMXMLInvoker Request Session
The polling process (indicated by the black box in Figure 4-3 on page 4-12 above) is illustrated in Figure 4-4 on page 4-13.
4-12
Figure 4-4
EMXMLInvoker Polling Request Steps
The advantage of this approach is that the API always replies immediately to the request. No extra time or resources are spent processing the responses.
4-13
XML String Validation

The EMBasicXMLInvoker uses .dtd files to validate XML-formatted request and response strings. The location of these .dtd files is determined by the com.bmc.ctmem.emapi.XMLDATAPATH property. If this path is not available to the class at run-time the operation will fail.
Note
The XMLDATAPATH property is defined in the ctmemapi.properties file. The EMXMLInvoker class does not examine the XML-formatted data it sends or receives, and it does not depend on the presence of .dtd files. An EMXMLInvoker request session adds a series of polling request steps to the EMBasicXMLInvoker request session displayed on Figure 4-2. How to use the EMXMLInvoker is described in Using EMXMLInvoker Class Calls on page 4-15. How to use the EMBasicXMLInvoker is described in Using EMBasicXMLInvoker Class Calls on page 4-21.
4-14
Using EMXMLInvoker Class Calls

The EMXMLInvoker is used to send and receive XML requests using the CONTROL-M/EM API. The init, done, invoke, getProperties, and setProperties methods are used to with this class.
Initializing and Stopping the CONTROL-M/EM API Services

Before using the CONTROL-M/EM API in your project, the API must be initialized. The CONTROL-M/EM API is started and stopped by initializing the Orbix services. It is stopped when the CONTROL-M/EM API stops using the Orbix services. When your project has finished using the API, you can stop the API.
Note
The CONTROL-M/EM API makes use of 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 using the EMXMLInvoker static method, init. The prototype described below uses a default CORBA configuration and should be used in most circumstances.
Note
There are two additional init prototypes. They are described in Modifying Initialization Properties on page 6-1.
Prototype
public static void init()
4-15
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 prior to every interactive session.
Stopping the API Services
When you have finished using the CONTROL-M/EM API in your project, 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 in during invocation. The invoke method accepts one parameter (a String), written in XML format. This parameter contains the request that the user is submitting 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 it a reference to the CONTROL-M/EM component that will process the request. An instance of EMXMLInvoker must hold either GSRComponent or GASComponent.
4-16
Example
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 Table 4-2.
4-17
Table 4-2
Request Types Listed by Component Type
Request Type
Job Creation Order/Force Add/Delete Condition Alert Status Modification Polling User Registration User Unregistration Time-out Reset Job Tracking
GUI Server (GSRComponent)

X X X
Global Alerts Server (GASComponent)
X X X X X X X X X
Note
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 will be 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 Where 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.
4-18
The various types of requests that you can make are described in Chapter 9, Request Reference. To invoke an object with the EMXMLInvoker:
Step 1
Create an instance of the EMXMLInvoker containing a reference to a CONTROL-M/EM server component type. This specified server component type component will process the request that you create in Step 2.
Example
GSRComponent gsrComponent = new GSRComponent(); EMXMLInvoker gsrInvoker = new EMXMLInvoker(gsrComponent);
Step 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
Note
The invoke method can throw an exception if the application failed 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 7-11.
4-19
Polling
There are two types of requests: Requests that receive direct feedback about action taken by CONTROL-M/EM regarding the request. Requests that do not receive direct feedback. These requests receive a tracking ID as a response. By sending a polling request including this tracking ID, the user can retrieve feedback about action taken by CONTROL-M/EM when it becomes available or a notice that the request is still being processed. Only certain requests types require polling, as described in Table 4-3.
Table 4-3 Polling Requirements
Polling
Required
Request Type
Order/Force Request Add/Delete Condition Request Job Creation Request Polling Request User Registration Request User Unregistration Request Time-out Reset Request Alert Status Modification Request Job Tracking Request
Not Required
For more information about the polling request, see page 9-77.
4-20
Using EMBasicXMLInvoker Class Calls

The init and done methods for the EMBasicXMLInvoker class, used for starting and stopping the API, are identical to those of the EMXMLInvoker class. For more information, see Initializing and Stopping the CONTROL-M/EM API Services on page 4-15. invoke returns a String, containing a text response from CONTROL-M/EM in XML format.
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 it a reference to the CONTROL-M/EM component that will process the request. An instance of EMBasicXMLInvoker must hold either GSRComponent or GASComponent.
Example
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.
4-21
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 Table 4-2.
Table 4-4 Request Types Listed by Component Type
Request Type
Job Creation Order/Force Add/Delete Condition Alert Status Modification Polling User Registration User Unregistration Time-out Reset Job Tracking
GUI Server (GSRComponent)

X X X
Global Alerts Server (GASComponent)
X X X X X X X X X
Note
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 will be 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

4-22
Where 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. To invoke an object with the EMBasicXMLInvoker:
Step 1
Create an instance of the EMBasicXMLInvoker containing a reference to a CONTROL-M/EM server component type. This specified server component type component will process the request that you create in Step 2.
Example
GSRComponent gsrComponent = new GSRComponent(); EMBasicXMLInvoker gsrInvoker = new EMBasicXMLInvoker(gsrComponent);
Step 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
Note
The invoke method can throw an exception if the application failed 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 7-11.
4-23
4-24
Response Handling
Every time a request is made, CONTROL-M/EM replies by sending one or more response strings (in XML format) to the person who submitted the request. Responses can inform the CONTROL-M/EM API user about the following information: The status of the request that was made The status of any jobs in CONTROL-M that were affected by the request The status of polling (if it was performed) Errors that were generated by the request and polling
You can parse the contents of these response strings for use in your project. The following topics are included in this chapter: Response Types Response String Formats Interpreting Response Strings
Response Handling
5-1
Response Types
All responses from CONTROL-M/EM are sent as XML-formatted text strings. There are four response types. The response types are described in Table 5-1.
Table 5-1 Response String Types
Response Type
EMAPI_TokenResponse EMAPI_PollResponse EMAPI_<Requestname>Response EMAPI_errorResponse
Description
This response is sent following all requests that require polling. Informs you that your original request is being processed (status: EXEC). The response that informs you of the outcome of your initial request. Used when any request you place returns an error.
Response String Formats

The CONTROL-M/EM API returns different responses, depending on various factors: The type of request sent The class and method used to send the request (which determines whether polling is required) The current status of the request (Executing, Completed successfully, and so on)
Each response type is described below. Included in each description are the circumstances in which such a response is sent.
5-2
EMAPI_tokenResponse
The EMAPI_tokenResponse response contains a unique response token that identifies the request for the purpose of polling for the result of the request. This response is returned by CONTROL-M/EM after a request, such as Job Creation, is sent successfully.
dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:error (#PCDATA)> <!ATTLIST ctmem:error ctmem:major CDATA #REQUIRED ctmem:minor CDATA #REQUIRED ctmem:severity CDATA #REQUIRED> <!ELEMENT ctmem:error-list (ctmem:error)> <!ELEMENT ctmem:status (#PCDATA)> <!ELEMENT ctmem:response_token (#PCDATA)> <!ELEMENT ctmem:response_data (ctmem:response_token)> <!ATTLIST ctmem:response_data ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:response ( ctmem:status, ctmem:response_data )> <!ATTLIST ctmem:response ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:message_package (ctmem:response )> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED>
Response Handling
5-3
Parameters
Table 5-2 Token Response XML Parameters Description (Part 1 of 3)
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_tokenResponse.dtd"> message_package Identifies the beggining and end of the response data package. Contains the xmlns:ctmem and version attributes. Is a wrapper for the response element. xmlns:ctmem=URL version (1.0) Location of the schema. version (1.0)
Example <ctmem:message_package xmlns:ctmem=http://www.bmc.com/ctmem/schema ctmem:version=1.0> </ctmem:message_package> response Type of response contained documented in the XML file. Contains the request_name attribute. Wrapper for the status and response_data elements. request_name Request type for which the response was generated. Valid values: register
Example <ctmem:response ctmem:name=poll> <ctmem:status>Error</ctmem:status> <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=403 ctmem:minor=1 ctmem:severity=Error> <ctmem:error_message>Error: Invalid token supplied. </ctmem:error_message> </ctmem:error> </ctmem:error_list> </ctmem:response> status Description of message content (for example, Error). String. Contained in the response element. Example <ctmem:status>ERROR</ctmem:status>
5-4
Table 5-2
Token Response XML Parameters Description (Part 2 of 3)
Parameter
response_data
Description
Valid Values
Describes the response and the jobs to which the response refers. String. Contained in the response element. Contains the request_name attribute and the response_token element. Example <ctmem:response_data request_name="register"> <ctmem:response_token>1234</ctmem:response_token> </ctmem:response_data>
response_token
Tracking ID assigned by the API. String. Contained in the response_data element. Example <ctmem:response_token>1234</ctmem:response_token>
error-list
Begins and ends the list of all erors included in the XML file. Contained in the response element. Contains the highest_severity attribute. Wrapper for the one or more error elements. 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.
Example <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=404 ctmem:minor=2 ctmem:severity=Error> <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message> </ctmem:error> </ctmem:error_list>
Response Handling
5-5
Table 5-2
Token Response XML Parameters Description (Part 3 of 3)
Parameter
error
Description
Valid Values
Describes the error. Contains the major, minor, and severity attributes. Wrapper for the error_message element. major The error Major Code. An integer describing the family of errors to which the error belongs. For more information, see Appendix B, Error Codes and Exceptions. The error minor Code. An integer that is a unique ID for an error of this type. For more information, see Appendix B, Error Codes and Exceptions. The priority level assigned to the error by the CONTROL-M/EM API. String. For more information, see Appendix B, Error Codes and Exceptions.
minor
severity
Example <ctmem:error ctmem:major=404 ctmem:minor=2 ctmem:severity=Error> <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message> </ctmem:error> error_message Text description of the error. For more information, see Appendix B, Error Codes and Exceptions. String. <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message>
5-6
EMAPI_PollResponse
The EMAPI_pollResponse response is returned in response to a poll request. It indicates that the initial request (the outcome of which you are polling for) is still being processed (status: EXEC). The poll response is described under Polling Request on page 9-77.
EMAPI_errorResponse
CONTROL-M/EM returns the The EMAPI_errorResponse response when an error has occured. The error can result from any of a number of sources, including: Incorrect XML formatting of the request string The request being sent cannot be processed by CONTROL-M/EM CONTROL-M/EM component malfunction Communication difficulties between components
The response can contain one or more errors, arranged in a list that notes the highest degree of severity among the errors in the group. Each error is listed. For every error, a major code that indicates the class of error, a minor code that identifies the specific error type, the severity rating of the error, and a text message that briefly describes the problem are included. All errors are described in Appendix B, Error Codes and Exceptions.
Response Handling
5-7
dtd
<?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:error_message (#PCDATA)> <!ELEMENT ctmem:error (ctmem:error_message)> <!ATTLIST ctmem:error ctmem:major CDATA #REQUIRED ctmem:minor CDATA #REQUIRED ctmem:severity CDATA #REQUIRED> <!ELEMENT ctmem:error_list (ctmem:error+)> <!ATTLIST ctmem:error_list ctmem:highest_severity CDATA #REQUIRED> <!ELEMENT ctmem:status (#PCDATA)> <!ELEMENT ctmem:response (ctmem:status, ctmem:error_list?)> <!ATTLIST ctmem:response ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:message_package (ctmem:response)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED>
Parameters
Table 5-3 Error Response XML Parameters Description (Part 1 of 3)
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_errorResponse.dtd">
5-8
Table 5-3
Error Response XML Parameters Description (Part 2 of 3)
Parameter
message_package
Description
Valid Values
Identifies the beggining and end of the response data package. Contains the xmlns:ctmem and version attributes. Is a wrapper for the response element. xmlns:ctmem=URL version (1.0) Location of the schema. version (1.0)
Example <ctmem:message_package xmlns:ctmem=http://www.bmc.com/ctmem/schema ctmem:version=1.0> </ctmem:message_package> response Type of response contained documented in the XML file. Contains the request_name attribute. Is a wrapper for the status and error-list elements. request_name Request type for which the response was generated. Valid values: poll
Example <ctmem:response ctmem:name=poll> <ctmem:status>Error</ctmem:status> <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=403 ctmem:minor=1 ctmem:severity=Error> <ctmem:error_message>Error: Invalid token supplied. </ctmem:error_message> </ctmem:error> </ctmem:error_list> </ctmem:response> status Description of message content (for example, Error). String.
Example <ctmem:status>Error</ctmem:status>
Response Handling
5-9
Table 5-3
Error Response XML Parameters Description (Part 3 of 3)
Parameter
error-list
Description
Valid Values
Example <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=404 ctmem:minor=2 ctmem:severity=Error> <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message> </ctmem:error> </ctmem:error_list> error Describes the error. Contains the major, minor, and severity attributes. Wrapper for the error_message element. major The error Major Code. An integer describing the family of errors to which the error belongs. For more information, see Appendix B, Error Codes and Exceptions. The error minor Code. An integer that is a unique ID for an error of this type. For more information, see Appendix B, Error Codes and Exceptions. The priority level assigned to the error by the CONTROL-M/EM API. String. For more information, see Appendix B, Error Codes and Exceptions.
minor
severity
5-10
EMAPI_<Requestname>Response
The EMAPI_<Requestname>Response response contains the outcome of the initial request. The name of the request for which the response is returned is contained in the .dtd filename for this response type. For example, EMAPI_job_trackResponse.dtd is the validation file for the response to the Job Tracking request. When EMAPI_<Requestname>Response is returned following request that requires polling (Job Creation, Order/Force, or Add/Delete Condition) that was sent using the init method of the EMXMLInvoker (Native API) class, the response will also contain information about the status of polling. Each EMAPI_<Requestname>Response string is described in Chapter 9, Request Reference, together with the appropriate request.
Response Handling
5-11
Interpreting Response Strings

A response string is generally not a single response but a number of discrete, hierarchically arranged responses contained in a single message package wrapper. This collection of responses is required because the response, as a whole, may be answering a number of related requests simultaneously. Each unit is a response to one of the various operations that were conducted by CONTROL-M/EM as a result of the initial request. Your application must be able to parse the response string to identify each discrete response unit and identify the information that you want to use elsewhere in your code or display to the application user.
Note
Some responses have more units than others, depending on how may separate answers are providing being provided.
Parts of a Response String

Units are nested in a hierarchy: 1. Status of the poll request (if polling with the Native API was initiated). If polling was not initiated, this layer of the response is not present. 2. Status of the initial request (for example, to order jobs) 3. If multiple jobs were affected (ordered, created, forced), the status of each job is reported. In addition to presenting the status of each operation, the following descriptive information can be included: If the subject of the operation was a job, details describing the job are listed.
5-12
If one or more errors occurred, a list of errors is included. Each error is described with its major and minor codes and a text description.
Analyzing a Response String

A response string must be broken down into separate units to be parsed. A response string is composed of a number of nested responses. Each response is in answer to a different part of the overall request. Your program must identify the separate responses contained in the response string and make use of them as required. Requests made using a method from the EMXMLInvoker class require polling. Therefore, responses to these requests contain both a response to the poll request and a response to the initial request (such as the request to order a job or create a job) Response to a request made using the EMXMLInvoker class:
<!DOCTYPE ctmem:message_package SYSTEM "EMAPI_any_requestResponse.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:response ctmem:request_name="poll"> <ctmem:status>OK</ctmem:status> <ctmem:response_data ctmem:request_name="any_request_name> <ctmem:status>OK</ctmem:status> ...request-specific info.... </ctmem:response_data> </ctmem:response> </ctmem:message_package>
In regular type: Identifying data required for XML validation and the outer message package In Bold: Poll response envelope and Poll request status
Response Handling
5-13
In Italics: Request-specific envelope, request-specific status, and request-specific information Requests made using a method from the EMBasicXMLInvoker class do not require polling. Therefore, responses to these requests contain only a response to the initial request (such as the request to register the user) Response to a request made using the EMBasicXMLInvoker class:
<!DOCTYPE ctmem:message_package SYSTEM "EMAPI_any_requestResponse.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:response ctmem:request_name="any_request_name"> <ctmem:status>OK</ctmem:status> ...request specific info... </ctmem:response> </ctmem:message_package>
In regular type: Identifying data required for XML validation and the outer message package In Italics: Request-specific envelope, request-specific status, and request-specific information
Example
In this example, an Order request to order two jobs was sent using a method of the Native API (EMXMLInvoker). Polling for the response was conducted The Order/Force reponse was returned. It contained the following information: The status of the poll request for which the response was returned. The status of the order (or force) request The status of each individual job that was ordered
5-14
The entire response string is displayed in Figure 5-1. Following the figure, the response is broken down and explained, unit by unit.
Figure 5-1 Order/Force Response Example
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_OrderForceResponse.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema"> <ctmem:response name="poll"> <ctmem:status>OK</ctmem:status> <ctmem:response_data request_name = "order_force"> <ctmem:status>OK</ctmem:status> <ctmem:jobs> <ctmem:job> <status>OK</status> <job_data> <ctmem:order_id>aa123</ctmem:order_id> <ctmem:mem_name>Mem0</ctmem:mem_name> <ctmem:job_name>Job0</ctmem:job_name> <ctmem:is_group>yes</ctmem:is_group> <ctmem:ret_text>"Job was ordered"</ctmem:ret_text> </job_data> </ctmem:job> <ctmem:job> <status>ERROR</status> <ctmem:error-list ctmem:highest_severity="Error" > <ctmem:error ctmem:major="32000" ctmem:minor="00001" ctmem:severity="Error" > <ctmem:error_message> Job "Job1". Security violation </ctmem:error_message> </ctmem:error> </ctmem:error-list> </ctmem:job> </ctmem:jobs> </ctmem:response_data> </ctmem:response> </ctmem:message_package>
Poll Response <ctmem:response name="poll"> <ctmem:status>OK</ctmem:status> ... </ctmem:response>
The poll response unit identifies the type of request to which it corresponds ("poll") and the status of the request (OK). If an error had occurred in processing the poll request (status="ERROR"), a list of errors would have been included.
Response Handling
5-15
Order Request Response
<ctmem:response_data request_name = "order_force">

<ctmem:status>OK</ctmem:status> ...
</ctmem:status>
The initial request response unit identifies the type of request to which it corresponds ("order_force") and the status of the request (OK). The status indicated here describes the overall success of the Order request. It does not address whether individual jobs could be ordered. If an error had occurred in processing the Order/Force request (status="ERROR"), a list of errors would have been included.
Jobs List
<ctmem:jobs> <ctmem:job> <status>OK</status> <job_data> <ctmem:order_id>aa123</ctmem:order_id> <ctmem:mem_name>Mem0</ctmem:mem_name> <ctmem:job_name>Job0</ctmem:job_name> <ctmem:is_group>yes</ctmem:is_group> <ctmem:ret_text>"Job was ordered"</ctmem:ret_text> </job_data> </ctmem:job> <ctmem:job> <status>ERROR</status> <ctmem:error-list ctmem:highest_severity="Error"> <ctmem:error ctmem:major="32000" ctmem:minor="00001" ctmem:severity="Error"> <ctmem:error_message>Job "Job1". Security violation </ctmem:error_message> </ctmem:error> </ctmem:error-list> </ctmem:job> </ctmem:jobs>
This response unit returns the Order request results for each individual job: The first job was ordered successfully (status="OK"). The status is accompanied by information that describes the job that was ordered.
5-16
An error occurred when the second job was ordered. As a result, the job was not ordered. An error list containing one error is included.
Response Handling
5-17
5-18
Advanced Features and Optimization6

This following topics are included: Modifying Initialization Properties Getting and Setting CONTROL-M/EM API Properties Polling Interval Timeout Configuration
Modifying Initialization Properties

Before using of 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. Modifying Initialization Properties shows you how to initialize the CONTROL-M/EM API using non-default CORBA ORB properties.
Note
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 Orbix, a third-party product that brokers requests among the components of distributed applications (acts as middleware).
Advanced Features and Optimization
6-1
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 the Orbix ORB.
Prototype 1
public static void init ()
Prototype 1 (the default prototype) initializes the CORBA services using a CONTROL-M/EM API-specific Orbix 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 4-15. This Orbix configuration information is contained in the emapi.cfg file located under the emapi-610\iona\etc\domains directory.
6-2
Prototype 2
public static void init(String[] args)
This init prototype enables you to include an array of strings representing a list of arguments.
Arguments
The args parameter generally contains your command line arguments for the applications main. This enables you to control ORB initialization from outside the program.
Note
For a list of Orbix parameters suitable for use in args, see the manufacturers documentation.
Code Example
public class HelloWorld { public static void main(String[] args) { EMXMLInvoker.init(args); ... } }
Run Example
java HelloWorld -ORBdomain_name orbix2000 The application will configure Orbix ORB with configuration information from the orbix2000.cfg file. For Orbix ORB initialization to succeed, one of the following must be true: The location of the orbix2000.cfg file directory is included in the CLASSPATH environment variable.
6-3
The ORBconfig_domains_dir parameter must point to the directory in which the orbix2000.cfg file is located.
Prototype 3
public static void init(String[] args, Properties props)
Arguments
The args parameter generally contains your command line arguments for the applications main. This enables you to control ORB initialization from outside the program.
Note
Properties
The props parameter (Properties) can contain Orbix ORB parameters, using the same options as in the command line that was passed as the first parameter (args).
Note
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("ORBdomain_name", "orbix2000"); EMXMLInvoker.init(args, props);
6-4
... } }
Run Example
java HelloWorld The application will configure Orbix ORB with configuration information from the orbix2000.cfg file (referred to in the example without a file extension).
Note
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 Chapter 2, Installation. For Orbix ORB initialization to succeed, one of the following must be true: The location of the orbix2000.cfg file directory is included in the CLASSPATH environment variable. The ORBconfig_domains_dir parameter must point to the directory in which the orbix2000.cfg file is located.
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.
6-5
Getting and Setting CONTROL-M/EM API Properties

The CONTROL-M/EM API properties generally contain the hostnames of the CONTROL-M/EM GUI Server and the Global Alerts 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 hostnames of the CONTROL-M/EM GUI Server and the GAS.
getProperties
The getProperties method will return 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 will return 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 will affect subsequent calls to getProperties.
Prototype public Properties getProperties();
The CONTROL-M/EM API default parameter properties are described in Table 6-1. These parameters were specified in the ctmemapi.properties file during configuration of the CONTROL-M/EM API.
6-6
Table 6-1
CONTROL-M/EM API Properties Parameters
Parameter
com.bmc.ctmem.emapi.GSR.hostname com.bmc.ctmem.emapi.GAS.hostname com.bmc.ctmem.emapi.XMLDATAPATH
Description
Set to the hostname of the CONTROL-M/EM GUI Server. Set to the hostname of the Global Alerts Server. Set to the location of the XML .dtd (validation) files.
setProperties
Use setProperties to modify the CONTROL-M/EM API properties values. All subsequent calls to getProperties will 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 6-1, 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.
{ Properties props = new Properties(); 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 }
6-7
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.
Note
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
6-8
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.
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.
6-9
6-10
Diagnostics and Troubleshooting
The topics discussed in this chapter can help you, the developer, to analyze the performance of the CONTROL-M/EM API and prevent conflicts before they arise. The topics included in this chapter are: CONTROL-M/EM API Logging Environment Configuration Troubleshooting Application Runtime and Communication Troubleshooting
CONTROL-M/EM API Logging

The CONTROL-M/EM API has a logging mechanism for recording CONTROL-M/EM API actions, exceptions, and warnings. The logging mechanism uses the Log4J library from the Jakarta Java Solutions project. The version of Log4J used in the CONTROL-M/EM API is listed in the manifest file located in the log4J.jar file in the emapi-<version>\classes directory. The default behavior of the logging mechanism is suitable for most CONTROL-M/EM API applications. However, you can modify the logging procedures, to enable greater control over logging behavior.
7-1
Introductory information about modifying logging mechanism behavior is described in Modifying Logging Behavior on page 7-2. However, to make effective changes, you must consult the Log4J documentation.
Default Logging Behavior

The CONTROL-M/EM API logging default behavior has the following characteristics: Only errors (priority level: ERROR) are logged. Maximum log file size is 50k. The last two completed logs are saved. 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, as well. 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 information contained in it is passed automatically to the Log4J mechanism. A sample file is displayed in Figure 7-1 on page 7-3. Use your own code to pass information to the Log4J mechanism. The CONTROL-M/EM API logs using the com.bmc.ctmem.emapi logging category.
Logging Parameters
Whether you are placing logging configuration information in the emapi_log.cfg file or in your project code, this information must be in accordance with Log4J specifications (described in the Log4J documentation).
7-2
Log Message Priorities
If you are modifying logging behavior, the priority of messages that are recorded in the log must be indicated in your configuration file. Message priority levels supported by Log4J are described in Table 7-1. The levels described in the table are ordered from the most critical to the least critical.
Note
Each setting includes messages of that level and more critical levels.
Table 7-1
Log Message Priority Levels
Level
FATAL ERROR WARN INFO DEBUG
Description
Displays fatal error messages. Displays messages for fatal and non-fatal errors. Displays warning messages and all error messages. Displays system information, warnings, and all errors. Displays debugging information and all other priority messages.
Sample Log Configuration File
A sample log configuration file, containing common attributes, is displayed in Figure 7-1.
Figure 7-1
emapi_log.cfg File Example with Default Parameters
log4j.rootCategory=ERROR log4j.category.com.bmc.ctmem.emapi=ERROR, EMAPI_Appender # set appender for EMAPI log4j.appender.EMAPI_Appender=org.apache.log4j.Rolling FileAppender log4j.appender.EMAPI_Appender.file=emapi.log log4j.appender.EMAPI_Appender.append=true log4j.appender.EMAPI_Appender.maxFileSize=50kb
7-3
log4j.appender.EMAPI_Appender.maxBackupIndex=2 log4j.appender.EMAPI_Appender.layout=org.apache.log4j. SimpleLayout
In the first line in Figure 7-1:

log4j.rootCategory=ERROR
the priority of the root category is set to ERROR. If your project code uses the Log4J library (in addition to its use by the CONTROL-M/EM API), the root category determines the highest overall priority of log messages. In the second line of the example:
log4j.category.com.bmc.ctmem.emapi=ERROR, EMAPI_Appender
An appender is defined 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.
The remaining lines of the example define the properties of the appender,
EMAPI_Appender. The properties that are assigned in the file are
dependent on the type of appender that is being defined. This example illustrates a RollingFileAppender with the following properties:
7-4
Figure 7-2
RollingFileAppender Example Properties
Code
file=emapi.log append=true maxFileSize=50kb maxBackupIndex=2 layout=org.apache.log4j. SimpleLayout
Description
Indicates that the log output file is named emapi.log. Indicates that new information is added to the end of the log file. Indicates that the maximum file of the log file is 50kb. Indicates the number of backups made (number of old log files saved). Indicates the format for entries to the log file.
7-5
Environment Configuration Troubleshooting

Modifications or omissions in the environment configuration can cause the CONTROL-M/EM API to malfunction. However these problems can be solved easily. Common problems and their solutions are described below.
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 may be missing from your application class path (CLASSPATH).
Solution
Ensure that the following files and directories are in the class path:
<full_path>/emapi-610/iona/orbix_art/1.2/classes/omg.jar <full_path>/emapi-610/iona/orbix_art/1.2/classes/orbix2000.jar <full_path>/emapi-610/iona/etc <full_path>/emapi-610/iona/etc/domains <full_path>/emapi-610/classes/log4j.jar <full_path>/emapi-610/classes/xerces.jar <full_path>/emapi-610/classes/emapi.jar <full_path>/emapi-610/classes/jbcl.jar
7-6
Java Virtual Machine Parameters

Problem
Your application fails during init initialization or when the invoke method is first used.
Possible Cause
Virtual machine parameter configuration error.

Solution
Check the log file to see if a message similar to the following has been written:
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 com.sun.corba.se.internal.iiop package,
You probably did not specify to the virtual machine that it must use the Iona (Orbix) implementation (in place of the Sun default implementation). You must specify to the Java virtual machine that it must use the Orbix implementation. Use one of the following methods.:
7-7
Method 1
Run the java command from the project working directory, using the
following parameters: java -Dorg.omg.CORBA.ORBClass=com.iona.corba. art.artimpl.ORBImpl -Dorg.omg.CORBA.ORBSingletonClass=com.iona.corba. art.artimpl.ORBSingleton <project_app_name> where <project_app_name> is your projects executable file.
Method 2
1. Create a file containing the following text: org.omg.CORBA.ORBClass=com.iona.corba.art.arti mpl.ORBImpl org.omg.CORBA.ORBSingletonClass=com.iona.corba .art.artimpl.ORBSingleton 2. Save the file with the name orb.properties in one of the following directories: If you are using JDK: <JDK_home>/jre/lib If you are using JRE: <JRE_home>/lib
Method 3
Call the init method using the properties illustrated in the code
example (assuming that args is your application command line arguments):
Properties props = new Properties(); props.setProperty("org.omg.CORBA.ORBClass", "com.iona.corba.art.artimpl.ORBImpl");
7-8
props.setProperty("org.omg.CORBA.ORBSingletonClass", "com.iona.corba.art.artimpl.ORBSingleton"); EMXMLInvoker.init(args, props);
-orCall the init method without any parameters.
7-9
Orbix Domain Initialization Failure

Problem
Initializing the CONTROL-M/EM API by invoking the init method failed.

Note
This can happen when you switch Orbix ORB domains.
Possible Cause
The Orbix domain configuration file (<ORBdomain_name>.cfg) pathname in your application class path may not be correct. If you changed to a different Orbix ORB domain (by initializing the API using the init ORBdomain_name property, you may have neglected to change the Orbix domain configuration file (<ORBdomain_name>.cfg) pathname in your application class path.
Solution
Modify the Orbix domain configuration file (<ORBdomain_name>.cfg) pathname in your application class path to point to the ORB domain that you want to use.
7-10
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.
Problem
An exception is thrown each time you use the invoke method.

Possible Cause 1
The CONTROL-M/EM API cannot communicate with the Orbix Locator or Naming Services services because: The Orbix services are down. The Locator hostname and Locator port settings in the emapi.cfg file (Orbix domain configuration file) are incorrect.
Solutions
Ensure that: The Orbix services (IT Naming and Locator) are running (started) on the Orbix Server host computer. The Locator hostname and Locator port settings in the emapi.cfg file point to the computer that hosts the Orbix Server that you are using.
Possible Cause 2
Communication cannot be established with the CONTROL-M/EM GUI Server or Global Alerts Server because: Hostnames of the GUI Server and/or the Global Alerts Server are incorrect in the ctmemapi.properties file.
7-11
Hostnames of the GUI Server and/or the Global Alerts Server were specified (with incorrect values) in the code.
Solutions
Ensure that: The CONTROL-M/EM GUI Server is running. The hostnames and ports of the CONTROL-M/EM server components (GUI Server and Global Alerts Servers) are registered correctly in the Orbix services (IT Naming and Locator). If you are using more than one Orbix Server, you are currently using the Orbix Server that serves the CONTROL-M/EM GUI Server and Global Alerts Server to which you are sending API requests.
7-12
Call Reference
This chapter provides reference information about all public functions that you, the developer, can access when using the CONTROL-M/EM API in your project. Detailed information for implementing these functions is located in other parts of this Guide. References to this material are listed in the See Also section included under each function heading.
Note
The information in this chapter provides you with the necessary information to create requests in the form of XML strings.
Table 8-1
CONTROL-M/EM API Classes
Class
ComponentType
Description
An abstract base class representing a CONTROL-M/EM component supported for use with the CONTROL-M/EM API. See page 8-3. The EMBasicXMLInvoker class is inherited from the EMXMLInvoker class. See page 8-4. The primary class of the API. See page 8-9. The GASComponent class represents the Global Alerts Server (GAS). See page 8-18.
EMBasicXMLInvoker EMXMLInvoker GASComponent
Call Reference
8-1
Table 8-1
CONTROL-M/EM API Classes
Class
GSRComponent InvokeException
Description
The GASComponent class represents the CONTROL-M/EM GUI Server. See page 8-21. This class is used to process error feedback from CONTROL-M/EM. See page 8-24.
8-2
ComponentType Class
An abstract base class representing a CONTROL-M/EM component supported for use with the CONTROL-M/EM API.
Note
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 8-18 and GSRComponent Class on page 8-21.
Call Reference
8-3
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 Table 8-2.
Table 8-2 EMBasicXMLInvoker Methods (Part 1 of 2)
Method
done
Description
An EMXMLInvoker static method that stops the CONTROL-M/EM API services by breaking the connection with the Orbix CORBA processes. The done implementation is the as it is under EMXMLInvoker. For more information, see done on page 8-10. An EMXMLInvoker static method that encodes a given text string for use in a Registration request. For more information, see encodePassword on page 8-11. An EMXMLInvoker static method used to obtain the CONTROL-M/EM Global Alerts Server or GUI Server hostnames from the ctmem.properties file. For more information, see getProperties on page 8-12. An EMXMLInvoker static method that starts the CONTROL-M/EM API services and initializes the Orbix Object Request Broker (ORB) with default values or with values specified with its optional parameters. The init implementation is the as it is under EMXMLInvoker. For more information, see init on page 8-13. 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. For more information, see invoke on page 8-6.
encodePassword
getProperties
init
invoke
8-4
Table 8-2
EMBasicXMLInvoker Methods (Part 2 of 2)
Method
setPollRequestInter valMilli
Description
Determines the interval, in milliseconds, between automatic poll requests. For more information, see setPollRequestIntervalMilli on page 8-7. Determines the total time, in milliseconds, allotted for polling following a request. For more information, see setPollRequestTimeoutMilli on page 8-8. An EMXMLInvoker static method used to specify the CONTROL-M/EM Global Alerts Server or GUI Server hostnames and a location from which to obtain them. For more information, see setProperties on page 8-17.
setPollRequestTime outMilli
setProperties
Call Reference
8-5
invoke Summary:
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.
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 Also
invoke on page 8-16 Chapter 9, Request Reference
8-6
setPollRequestIntervalMilli Summary:
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 Also
Polling Interval Timeout Configuration on page 6-8 setPollRequestTimeoutMilli on page 8-8
Call Reference
8-7
setPollRequestTimeoutMilli Summary:
Total time that is allotted for polling. This value must be greater than or equal to the value specified with the setPollRequestIntervalMilli method.
Syntax public void setPollRequestTimeoutMilli(final long timeout) Parameters
timeout. Time, in milliseconds.

Return Codes
None.
See Also
Polling Interval Timeout Configuration on page 6-8 setPollRequestIntervalMilli on page 8-7
8-8
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 Table 8-3.
Table 8-3 EMXMLInvoker Methods
Method
done
Description
An EMXMLInvoker static method that stops the CONTROL-M/EM API services by breaking the connection with the Orbix CORBA processes. For more information, see done on page 8-10. An EMXMLInvoker static method that encodes a given text string for use in a Registration request. For more information, see encodePassword on page 8-11. An EMXMLInvoker static method used to obtain the CONTROL-M/EM Global Alerts Server or GUI Server hostnames from the ctmem.properties file. For more information, see getProperties on page 8-12. An EMXMLInvoker static method that starts the CONTROL-M/EM API services and initializes the Orbix Object Request Broker (ORB) with default values or with values specified with its optional parameters. For more information, see init on page 8-13. 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. For more information, see invoke on page 8-16. An EMXMLInvoker static method used to specify the CONTROL-M/EM Global Alerts Server or GUI Server hostnames and a location from which to obtain them. For more information, see setProperties on page 8-17.
encodePassword
getProperties
init
invoke
setProperties
Call Reference
8-9
done Summary:
An EMXMLInvoker static method that stops the CONTROL-M/EM API services by breaking the connection with the Orbix CORBA processes.
Syntax public static void done() Parameters
None.
Return Codes
None.
See Also
Initializing and Stopping the CONTROL-M/EM API Services on page 4-15 init on page 8-13
8-10
encodePassword Summary:
An EMXMLInvoker static method that encodes a text string for use as a user password in the User Registration request.
Syntax public static String encodePassword(string password) Parameters
password. Text string, subject to all limitations that apply to a CONTROL-M/EM password.
Return Codes
Encoded string (the encoded CONTROL-M/EM password).

See Also
User Registration Request on page 9-98 For information on acceptable passwords, see the CONTROL-M Installation Guide
Call Reference
8-11
getProperties Summary:
Used to obtain the CONTROL-M/EM Global Alerts Server or GUI Server hostnames from the ctmem.properties file.
Syntax public Properties getProperties(); Parameters
None.
Return Codes Parameter
<host_of_the_GUI_Server>
Description
Hostname of the CONTROL-M/EM GUI Server. Default: com.bmc.ctmem.emapi.GSR.hostname Hostname of the Global Alerts Server. Default: com.bmc.ctmem.emapi.GAS.hostname Location of the XML .dtd (validation) files. Default: com.bmc.ctmem.emapi.XMLDATAPATH
<host_of_the_Alerts_Server>
<path_to_XML_data_files>
See Also
setProperties on page 8-17 Getting and Setting CONTROL-M/EM API Properties on page 6-6
8-12
init Summary:
An EMXMLInvoker static method that starts the CONTROL-M/EM API services and initializes the Orbix Object Request Broker (ORB) with default values or with values specified with its optional parameters. There are three prototypes. The init method must be run at program startup.
Prototype 1
This is the default implementation of init.

Syntax public static void init() Parameters
None.
Return Codes
None.
See Also
done on page 8-10 Initializing and Stopping the CONTROL-M/EM API Services on page 4-15
Call Reference
8-13
Prototype 2
Syntax public static void init(String[] args) Parameters
Return Codes
None.
See Also
done on page 8-10 Initializing and Stopping the CONTROL-M/EM API Services on page 4-15 Modifying Initialization Properties on page 6-1
8-14
Prototype 3
Syntax public static void init(String[] args, Properties props) Parameters
For a list of Orbix parameters suitable for use in args, see the manufacturers documentation. The props parameter (Properties) can contain Orbix ORB parameters, using the same options as in the command line that was passed as the first parameter (args).
Note
The Properties class is part of the java.util package.

Return Codes
None.
See Also
done on page 8-10 Initializing and Stopping the CONTROL-M/EM API Services on page 4-15 Modifying Initialization Properties on page 6-1
Call Reference
8-15
invoke Summary:
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.
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 Also
invoke on page 8-6 Chapter 9, Request Reference
8-16
setProperties Summary:
Used to specify the CONTROL-M/EM Global Alerts Server or GUI Server hostnames and the source from which to obtain them.
Syntax public void setProperties(Properties props); Parameters Parameter

<host_of_the_GUI_Server>
Description
Set to the hostname of the CONTROL-M/EM GUI Server. Default: com.bmc.ctmem.emapi.GSR.hostname Set to the hostname of the Global Alerts Server. Default: com.bmc.ctmem.emapi.GAS.hostname Location of the XML .dtd (validation) files. Default: com.bmc.ctmem.emapi.XMLDATAPATH
<host_of_the_Alerts_Server>
<path_to_XML_data_files>
Return Codes
None.
See Also
getProperties on page 8-12 Getting and Setting CONTROL-M/EM API Properties on page 6-6
Call Reference
8-17
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 will be sent to the specified CONTROL-M/EM Global Alerts Server. The GASComponent class uses the constructors listed in Table 8-4.
Table 8-4 GASComponent Constructors
Constructor
GASComponent (Prototype 1)
Description
Using this constructor, the request is sent to the Global Alerts Server hostname specified in the ctmemapi.properties file. For more information, see GASComponent (Prototype 1) on page 8-19. Using this constructor, the request is sent to the Global Alerts Server hostname specified with the hostname parameter. For more information, see GASComponent (Prototype 2) on page 8-20.
GASComponent (Prototype 2)
8-18
GASComponent (Prototype 1) Summary:

Using this constructor, the request is sent to the Global Alerts Server hostname specified under com.bmc.ctmem.emapi.GAS.hostname=<hostname> in the ctmemapi.properties file.
Syntax GASComponent(); Parameters
None.
Return Codes
None.
See Also
ComponentType Class on page 8-3 GASComponent (Prototype 2) on page 8-20 GSRComponent Class on page 8-21
Call Reference
8-19
GASComponent (Prototype 2) Summary:

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.

Return Codes
None.
See Also
ComponentType Class on page 8-3 GASComponent (Prototype 1) on page 8-19 GSRComponent Class on page 8-21
8-20
GSRComponent Class
Represents the GUI Server. When creating an instance of EMXMLInvoker (or EMBasicXMLInvoker) with a reference to a GSRComponent type, the request will be sent to the specified CONTROL-M/EM GUI Server. The GASComponent class uses the constructors listed in Table 8-4.
Table 8-5 GASComponent Constructors
Constructor
GSRComponent (Prototype 1)
Description
Using this constructor, the request is sent to the GUI Server hostname specified in the ctmemapi.properties file. For more information, see GSRComponent (Prototype 1) on page 8-22. Using this constructor, the request is sent to the GUI Server hostname specified with the hostname parameter. For more information, see GSRComponent (Prototype 2) on page 8-23.
GSRComponent (Prototype 2)
Call Reference
8-21
GSRComponent (Prototype 1) Summary:

Using this constructor, the request is sent to the GUI Server hostname specified under com.bmc.ctmem.emapi.GSR.hostname=<hostname> in the ctmemapi.properties file.
Syntax GSRComponent(); Parameters
None.
Return Codes
None.
See Also
ComponentType Class on page 8-3 GASComponent Class on page 8-18 GSRComponent (Prototype 2) on page 8-23
8-22
GSRComponent (Prototype 2) Summary:

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.

Return Codes
None.
See Also
ComponentType Class on page 8-3 GSRComponent (Prototype 1) on page 8-22 GASComponent Class on page 8-18
Call Reference
8-23
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 Table 8-6.
Table 8-6 InvokeException Class Methods
Method
getMajorCode
Description
Used to obtain the Major Code that identifies the error family to which an error belongs. For more information, see getMajorCode on page 8-25. Used 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. For more information, see getMinorCode on page 8-26. Used to obtain the text description of an error. For more information, see getReason on page 8-27.
getMinorCode
getReason
8-24
getMajorCode Summary:
Used to obtain the Major Code that identifies the error family to which an error belongs.
Syntax public int getMajorCode() Parameters
None
Return Codes
int. An integer that identifies the error family to which the error belongs.
See Also
getMinorCode on page 8-26 getReason on page 8-27 Appendix B, Error Codes and Exceptions
Call Reference
8-25
getMinorCode Summary:
Used 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() Parameters
None.
Return Codes
int. An integer that provides a unique identifier for the error in the family to which it belongs.
See Also
getMajorCode on page 8-25 getReason on page 8-27 Appendix B, Error Codes and Exceptions
8-26
getReason Summary:
Syntax public String getReason() Parameters
Used to obtain the text description of an error.
None.
Return Codes
String. This string is a text description of the error.

See Also
getMajorCode on page 8-25 getMinorCode on page 8-26 Appendix B, Error Codes and Exceptions
Call Reference
8-27
8-28
Request Reference
Each request that you can make using the CONTROL-M/Enterprise Manager API must be passed to CONTROL-M/EM as a string in XML format. Requests are listed alphabetically.
Table 9-1 Requests Listed in this Chapter
Request Type
Add/Delete Condition Request Change Alert Status Request Job Creation Request
Description
Adds or deletes Global conditions. Changes the status of an alert (for example, from not_noticed to handled). Creates a job processing or Group Scheduling table definition and inserts it into the Active Jobs file. Inserts a job or Group Scheduling table into the Active Jobs file immediately (force) or subject to scheduling criteria (order). Polls the Response repository in the CONTROL-M/EM GUI Server to receive completion confirmation from earlier job processing requests. Resets the user registration token timeout counter to zero. Tracks the progress of existing jobs in the CONTROL-M installation.
Order/Force Request
Polling Request
Timeout Reset Request Tracking Request
Request Reference
9-1
Table 9-1
Requests Listed in this Chapter
Request Type
User Registration Request User Unregistration Request
Description
Sends the username and password of the user to the target server component. This logs the user into CONTROL-M/EM and starts the session. Logs the user out of CONTROL-M/EM and ends the session.
The XML format for each request is described in this chapter, together with the information in Table 9-2.
Table 9-2 Request Reference Format
Topic
Description Request Format Response
Description
A brief description of the action specified in the request. Including the .dtd file, a table in which the elements of the .dtd file are described, and one or more examples of a finished XML document. The types of possible responses are described, as well as the format in which those responses must be received. Format instructions include the .dtd file, a table in which the elements of the .dtd file are described, and one or more examples of a finished XML document. Errors specific to the request type are described, as well as the format in which those responses must be received. Format instructions include the .dtd file, a table in which the elements of the .dtd file are described, and one or more examples of a finished XML document.
Errors
Parameter Names
Many XML elements in this chapter are CONTROL-M job parameters.
9-2
To create a successful request, particularly a Job Creation request or an Order or Force Job request, it is recommended to become familiar with CONTROL-M job parameters.
Tip
For details about CONTROL-M job parameters, see the CONTROL-M Job Parameter and Variable Reference Guide. 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 the index of the CONTROL-M Job Parameter and Variable Reference Guide. For example, to find information about the rerun_interval element (in the Job Creation request), search the Reference Guide index for rerun_interval. You will be directed to the Interval parameter.
Request Reference
9-3
Add/Delete Condition Request

Adds and deletes Global conditions.
Note
Both Add Condition and Delete Condition use the same .dtd (validation) file and share the same format.
Request
EMAPI_add_delete_condition.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:condition (ctmem:name, ctmem:odate)> <!ELEMENT ctmem:control_m (#PCDATA)> <!ELEMENT ctmem:message_package (ctmem:request)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED> <!ELEMENT ctmem:name (#PCDATA)> <!ELEMENT ctmem:odate (#PCDATA)> <!ELEMENT ctmem:request (ctmem:control_m, ctmem:condition)> <!ATTLIST ctmem:request ctmem:name CDATA #REQUIRED ctmem:user_token CDATA #REQUIRED>
9-4
Parameters
Table 9-3 Add/Delete Condition XML Parameters Description (Part 1 of 2)
Parameter
Description
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_add_delete_condition.dtd"> message_package Identifies the beginning and end of the request data package. Contains the xmlns:ctmem and version attributes. Is a wrapper for the request element. xmlns:ctmem=URL version (1.0) Location of the schema. version (1.0)
Example <ctmem:message_package xmlns:ctmem=http://www.bmc.com/ctmem/schema ctmem:version=1.0> </ctmem:message_package> request Type of request contained in the XML file. Contains the name and user_token attributes. Is a wrapper for the control_m and condition elements. name Name of the request type. Valid values: add_condition delete_condition Tracking ID assigned by the API. String.
user_token
Example <ctmem:request name=add_condition user_token=$tracking_id$> <ctmem:control_m>CTM_HQ</ctmem:control_m> <ctmem:condition> <ctmem:name>Cond_1</ctmem:name> <ctmem:odate>1231</ctmem:odate> </ctmem:condition> </ctmem:request> control_m Name of the CONTROL-M installation that will process the request. String.
Example: <ctmem:control_m>CTM_HQ</ctmem:control_m>
Request Reference
9-5
Table 9-3
Add/Delete Condition XML Parameters Description (Part 2 of 2)
Parameter
condition
Description
Condition description wrapper. Wrapper for the name and odate elements that identify the specific condition being added or deleted. Example <ctmem:condition> <ctmem:name>Cond_1</ctmem:name> <ctmem:odate>1231</ctmem:odate> </ctmem:condition>
name
Name of the condition to be added or deleted.
String.
<ctmem:name>Cond_1</ctmem:name> odate Order date of the condition . String. Valid values: mmdd STAT
Example: <ctmem:odate>1231</ctmem:odate>
Example
For sample XML strings, see Add Condition/Delete Condition Request on page A-2.
9-6
Responses
There are two possible responses to the requestone that is returned when a condition is added and another that is returned when a condition is deleted. The files are identical, apart from the following: The names of the .dtd files, which are listed in the XML-formatted string as SYSTEM="<dtd_file_name>" The add condition response .dtd file is EMAPI_add_conditionResponse.dtd The add condition response .dtd file is EMAPI_delete_conditionResponse.dtd The value for the ctmem:name element is dependent on the request to which the response string is returned: For an Add Condition response: add_condition For a Delete Condition response: delete_condition
EMAPI_add_conditionResponse.dtd and EMAPI_delete_conditionResponse.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:error_message (#PCDATA)> <!ELEMENT ctmem:error (ctmem:error_message)> <!ATTLIST ctmem:error ctmem:major CDATA #REQUIRED ctmem:minor CDATA #REQUIRED ctmem:severity CDATA #REQUIRED> <!ELEMENT ctmem:error_list (ctmem:error+)> <!ATTLIST ctmem:error_list ctmem:highest_severity CDATA #REQUIRED> <!ELEMENT ctmem:status (#PCDATA)> <!ELEMENT ctmem:response (ctmem:status, ctmem:error_list?)> <!ATTLIST ctmem:response ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:message_package (ctmem:response)> <!ATTLIST ctmem:message_package
Request Reference
9-7
xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED>
Parameters
Table 9-4 Add/Delete Condition Response XML Parameters Description (Part 1 of 3)
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_add_conditionResponse.dtd"> message_package Identifies the beginning and end of the response data package. Contains the xmlns:ctmem and version attributes. Is a wrapper for the response element. xmlns:ctmem=URL version (1.0) Location of the schema. version (1.0)
Example <ctmem:message_package xmlns:ctmem=http://www.bmc.com/ctmem/schema ctmem:version=1.0> </ctmem:message_package> response Type of response contained documented in the XML file. Contains the request_name attribute. Is a wrapper for the status and error-list elements. request_name Request type for which the response was generated. Valid values: add_condition delete_condition
Example <ctmem:response ctmem:name=add_condition> <ctmem:status>Error</ctmem:status> <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=404 ctmem:minor=2 ctmem:severity=Error> <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message> </ctmem:error> </ctmem:error_list> </ctmem:response>
9-8
Table 9-4
Add/Delete Condition Response XML Parameters Description (Part 2 of 3)
Parameter
status
Description
Description of message content (for example, Error).
Valid Values
String.
Example: <ctmem:status>Error</ctmem:status> error-list Begins and ends the list of all erors included in the XML file. Contained in the response element. Contains the highest_severity attribute. Wrapper for the one or more error elements. 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.
minor
severity
Example <ctmem:error ctmem:major=404 ctmem:minor=2 ctmem:severity=Error> <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message> </ctmem:error>
Request Reference
9-9
Table 9-4
Add/Delete Condition Response XML Parameters Description (Part 3 of 3)
Parameter
error_message
Description
Valid Values
Text description of the error. For more information, see Appendix B, Error Codes and Exceptions. String. Example: <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message>
Errors
See Add/Delete Condition Request Errors (Major Code 404) on page B-17.
9-10
Change Alert Status Request

Changes the status (for example, from not_noticed to handled) of an alert.
Request
EMAPI_change_alert_status.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:alert_id (#PCDATA)> <!ELEMENT ctmem:message_package (ctmem:request)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED > <!ELEMENT ctmem:request (ctmem:alert_id, ctmem:status)> <!ATTLIST ctmem:request ctmem:name CDATA #REQUIRED ctmem:user_token CDATA #REQUIRED > <!ELEMENT ctmem:status (#PCDATA)>
Parameters
Table 9-5 Change Alert Status XML Parameters Description
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_change_alert_status.dtd">
Request Reference
9-11
Table 9-5
Change Alert Status XML Parameters Description
Parameter
message_package
Description
Valid Values
Identifies the beginning and end of the response data package. Contains the xmlns:ctmem and version attributes. Is a wrapper for the request element. xmlns:ctmem=URL version (1.0) Location of the schema. version (1.0)
Example <ctmem:message_package xmlns:ctmem=http://www.bmc.com/ctmem/schema ctmem:version (1.0)> <ctmem:request name=change_alert_status user_token=$tracking_id$> <ctmem:alert_id>333444555</ctmem:alert_id> <ctmem:status>handle</ctmem:status> </ctmem:request> </ctmem:message_package> request Type of request contained in the XML file. Contains the name and user_token attributes. Is a wrapper for the alert_id and status elements. name Name of the request type. Valid values: change_alert_status Tracking ID assigned by the API. String.
user_token
Example <ctmem:request name=change_alert_status user_token=$tracking_id$> <ctmem:alert_id>333444555</ctmem:alert_id> <ctmem:status>handle</ctmem:status> </ctmem:request> alert_id The ID number of the alert. String. For more information, see the Alerts chapter of the CONTROL-M/Enterprise Manager API User Guide. Example: <ctmem:alert_id>12345</ctmem:alert_id> status Required status for the specified alert. Valid values: handled noticed not_noticed
9-12
Example
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_change_alert_status.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:request ctmem:name="change_alert_status" ctmem:user_token="$USER_TOKEN$"> <ctmem:alert_id>12345</ctmem:alert_id> <ctmem:status>handle</ctmem:status> </ctmem:request> </ctmem:message_package>
Response
EMAPI_change_alert_statusResponse.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:error_message (#PCDATA)> <!ELEMENT ctmem:error (ctmem:error_message)> <!ATTLIST ctmem:error ctmem:major CDATA #REQUIRED ctmem:minor CDATA #REQUIRED ctmem:severity CDATA #REQUIRED> <!ELEMENT ctmem:error_list (ctmem:error+)> <!ATTLIST ctmem:error_list ctmem:highest_severity CDATA #REQUIRED> <!ELEMENT ctmem:status (#PCDATA)> <!ELEMENT ctmem:response (ctmem:status, ctmem:error_list?)> <!ATTLIST ctmem:response ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:message_package (ctmem:response)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED>
Request Reference
9-13
Parameters
Table 9-6 Change Alert Status Response XML Parameters Description (Part 1 of 2)
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_change_alert_statusResponse.dtd"> message_package Identifies the beginning and end of the response data package. Contains the xmlns:ctmem and version attributes. Is a wrapper for the response element. xmlns:ctmem=URL version (1.0) Location of the schema. version (1.0)
Example <ctmem:message_package xmlns:ctmem=http://www.bmc.com/ctmem/schema ctmem:version=1.0> </ctmem:message_package> response Type of response contained documented in the XML file. Contains the request_name attribute. Is a wrapper for the status and error-list elements. request_name Request type for which the response was generated. Valid values: change_alert_status
Example <ctmem:response ctmem:name=change_alert_status> <ctmem:status>Error</ctmem:status> <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=408 ctmem:minor=2 ctmem:severity=Error> <ctmem:error_message>Invalid alert operation.</ctmem:error_message> </ctmem:error> </ctmem:error_list> </ctmem:response> status Description of message content (for example, Error). String.
Example: <ctmem:status>Error</ctmem:status>
9-14
Table 9-6
Change Alert Status Response XML Parameters Description (Part 2 of 2)
Parameter
error-list
Description
Valid Values
minor
severity
Example <ctmem:error ctmem:major=404 ctmem:minor=2 ctmem:severity=Error> <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message> </ctmem:error> error_message Text description of the error. For more information, see Appendix B, Error Codes and Exceptions. String. Example: <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message>
Request Reference
9-15
Errors
See Alerts Request Errors (Major Code 408) on page B-21.
9-16
Job Creation Request

Creates a job or Group Scheduling table and inserts it into the Active Jobs file. To creating a regular job: Specify all the parameters required for the job. Do not specify a value for the group_id parameter. Do not specify scheduling_group as the value for the task_type parameter.
To create a job in a Group Scheduling table: Indicate to which Group Scheduling table to associate the job, by doing the following: Specify the group_id value of the Group Scheduling table in the group_id parameter in the job specification, and Specify the name of the Group Scheduling table in the group parameter in the job specification. This value must be identical to the group parameter value in the Group Scheduling table specification. Do not specify scheduling_group for the task_type parameter. Specify all other parameters required for the job.
To create a Group Scheduling table: Specify scheduling_group as the value for the task_type parameter. Specify a name for the Group Scheduling table in the group parameter. Specify all other parameters required for the table. After the Group Scheduling table has been created, note the value of the group_id parameter. This value must be supplied for the group_id parameter of jobs that are associated with the Group Scheduling table.
Request Reference
9-17
Request
EMAPI_create_aj.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:action (#PCDATA)> <!ELEMENT ctmem:active_job (ctmem:job_name?, ctmem:mem_name?, ctmem:mem_lib?, ctmem:owner?, ctmem:task_type, ctmem:task_class, ctmem:application, ctmem:group, ctmem:odate?, ctmem:confirm_flag?, ctmem:order_table?, ctmem:order_library?, ctmem:max_wait?, ctmem:description?, ctmem:prevent_nct2?, ctmem:doc_member?, ctmem:doc_lib?, ctmem:time_from?, ctmem:time_until?, ctmem:rerun_interval?, ctmem:rerun_member?, ctmem:priority?, ctmem:critical?, ctmem:cyclic?, ctmem:auto_archive?, ctmem:sys_db?, ctmem:arch_max_days?, ctmem:arch_max_runs?, ctmem:rerun_max?, ctmem:over_lib?, ctmem:time_due_out?, ctmem:node_group?, ctmem:group_id?, ctmem:count_cyclic_from?, ctmem:reten_days?, ctmem:reten_gen?, ctmem:time_reference?, ctmem:time_zone?, ctmem:application_type?, ctmem:application_version?, ctmem:application_form?, ctmem:application_cm_version?, ctmem:multiagent?, ctmem:schedule_environment?, ctmem:system_affinity?, ctmem:request_nje?, ctmem:sysout_option?, ctmem:sysout_from_class?, ctmem:sysout_parameter?, ctmem:adjust_condition?, ctmem:command?, ctmem:autoedit_assignments?, ctmem:ctb_steps?, ctmem:in_conditions?, ctmem:control_resources?, ctmem:quantitative_resources?, ctmem:pipes?, ctmem:out_conditions?, ctmem:step_ranges?, ctmem:shouts?, ctmem:on_do_statements?)> <!ELEMENT ctmem:and_or (#PCDATA)> <!ELEMENT ctmem:application (#PCDATA)> <!ELEMENT ctmem:application_cm_version (#PCDATA)> <!ELEMENT ctmem:application_form (#PCDATA)> <!ELEMENT ctmem:application_type (#PCDATA)> <!ELEMENT ctmem:application_version (#PCDATA)> <!ELEMENT ctmem:auto_archive (#PCDATA)>
9-18
<!ELEMENT ctmem:autoedit_assignments (ctmem:autoedit_assignment*)> <!ELEMENT ctmem:autoedit_assignment (ctmem:name, ctmem:value)> <!ELEMENT ctmem:owner (#PCDATA)> <!ELEMENT ctmem:cc (#PCDATA)> <!ELEMENT ctmem:code (#PCDATA)> <!ELEMENT ctmem:command (#PCDATA)> <!ELEMENT ctmem:condition (#PCDATA)> <!ELEMENT ctmem:confirm (#PCDATA)> <!ELEMENT ctmem:control_m (#PCDATA)> <!ELEMENT ctmem:control_resources (ctmem:control_resource*)> <!ELEMENT ctmem:control_resource (ctmem:resource, ctmem:type)> <!ELEMENT ctmem:count_cyclic_from (#PCDATA)> <!ELEMENT ctmem:critical (#PCDATA)> <!ELEMENT ctmem:cyclic (#PCDATA)> <!ELEMENT ctmem:ctb_arguments (#PCDATA)> <!ELEMENT ctmem:ctb_name (#PCDATA)> <!ELEMENT ctmem:ctb_steps (ctmem:ctb_step*)> <!ELEMENT ctmem:ctb_step (ctmem:ctb_step_position, ctmem:ctb_type, ctmem:ctb_name, ctmem:ctb_arguments)> <!ELEMENT ctmem:ctb_step_position (#PCDATA)> <!ELEMENT ctmem:ctb_type (#PCDATA)> <!ELEMENT ctmem:date (#PCDATA)> <!ELEMENT ctmem:description (#PCDATA)> <!ELEMENT ctmem:destination (#PCDATA)> <!ELEMENT ctmem:do (ctmem:action, ctmem:parameter?, ctmem:from_class?)> <!ELEMENT ctmem:do_autoedit (ctmem:name, ctmem:value)> <!ELEMENT ctmem:do_cond (ctmem:condition, ctmem:date, ctmem:sign)> <!ELEMENT ctmem:do_ctbrule (ctmem:name, ctmem:parameter)> <!ELEMENT ctmem:do_forcejob (ctmem:job, ctmem:table, ctmem:odate, ctmem:dsn?)> <!ELEMENT ctmem:do_ifrerun (ctmem:confirm, ctmem:from_program_step?, ctmem:to_program_step?, ctmem:from_procedure_step?, ctmem:to_procedure_step?)> <!ELEMENT ctmem:do_mail (ctmem:to, ctmem:cc?, ctmem:subject, ctmem:message, ctmem:urgency)> <!ELEMENT ctmem:do_shout (ctmem:destination, ctmem:message, ctmem:urgency)>
Request Reference
9-19
<!ELEMENT ctmem:do_sysout (ctmem:option, ctmem:parameter, ctmem:from_class?)> <!ELEMENT ctmem:doc_member (#PCDATA)> <!ELEMENT ctmem:doc_lib (#PCDATA)> <!ELEMENT ctmem:dsn (#PCDATA)> <!ELEMENT ctmem:flag (#PCDATA)> <!ELEMENT ctmem:from_class (#PCDATA)> <!ELEMENT ctmem:from_procedure_step (#PCDATA)> <!ELEMENT ctmem:from_program_step (#PCDATA)> <!ELEMENT ctmem:group (#PCDATA)> <!ELEMENT ctmem:in_conditions (ctmem:in_condition*)> <!ELEMENT ctmem:in_condition (ctmem:condition, ctmem:date, ctmem:and_or)> <!ELEMENT ctmem:job (#PCDATA)> <!ELEMENT ctmem:job_name (#PCDATA)> <!ELEMENT ctmem:arch_max_days (#PCDATA)> <!ELEMENT ctmem:arch_max_runs (#PCDATA)> <!ELEMENT ctmem:confirm_flag (#PCDATA)> <!ELEMENT ctmem:max_wait (#PCDATA)> <!ELEMENT ctmem:mem_name (#PCDATA)> <!ELEMENT ctmem:mem_lib (#PCDATA)> <!ELEMENT ctmem:message (#PCDATA)> <!ELEMENT ctmem:message_package (ctmem:request)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED > <!ELEMENT ctmem:multiagent (#PCDATA)> <!ELEMENT ctmem:name (#PCDATA)> <!ELEMENT ctmem:node_group (#PCDATA)> <!ELEMENT ctmem:odate (#PCDATA)> <!ELEMENT ctmem:order_table (#PCDATA)> <!ELEMENT ctmem:order_library (#PCDATA)> <!ELEMENT ctmem:on_do_statements (ctmem:on_do_statement+)> <!ELEMENT ctmem:on_do_statement (ctmem:on_statements, ctmem:do_statements)> <!ELEMENT ctmem:on_statements (ctmem:on_statement+)> <!ELEMENT ctmem:do_statements (ctmem:do | ctmem:do_autoedit | ctmem:do_shout | ctmem:do_forcejob | ctmem:do_ctbrule | ctmem:do_sysout | ctmem:do_ifrerun | ctmem:do_cond | ctmem:do_mail)+>
9-20
<!ELEMENT ctmem:on_statement (ctmem:code, ctmem:statement?, ctmem:program_step?, ctmem:procedure_step?, ctmem:and_or?)> <!ELEMENT ctmem:option (#PCDATA)> <!ELEMENT ctmem:out_conditions (ctmem:out_condition*)> <!ELEMENT ctmem:out_condition ((ctmem:condition, ctmem:date, ctmem:sign))> <!ELEMENT ctmem:parameter (#PCDATA)> <!ELEMENT ctmem:pipes (ctmem:pipe*)> <!ELEMENT ctmem:pipe (ctmem:flag, ctmem:name)> <!ELEMENT ctmem:prevent_nct2 (#PCDATA)> <!ELEMENT ctmem:priority (#PCDATA)> <!ELEMENT ctmem:procedure_step (#PCDATA)> <!ELEMENT ctmem:program_step (#PCDATA)> <!ELEMENT ctmem:quantitative_resources (ctmem:quantitative_resource*)> <!ELEMENT ctmem:quantitative_resource (ctmem:resource, ctmem:quantity)> <!ELEMENT ctmem:quantity (#PCDATA)> <!ELEMENT ctmem:request (ctmem:control_m, ctmem:active_job)> <!ATTLIST ctmem:request ctmem:name CDATA #REQUIRED ctmem:user_token CDATA #REQUIRED ctmem:mode CDATA #IMPLIED > <!ELEMENT ctmem:request_nje (#PCDATA)> <!ELEMENT ctmem:rerun_interval (#PCDATA)> <!ELEMENT ctmem:rerun_max (#PCDATA)> <!ELEMENT ctmem:over_lib (#PCDATA)> <!ELEMENT ctmem:rerun_member (#PCDATA)> <!ELEMENT ctmem:resource (#PCDATA)> <!ELEMENT ctmem:reten_days (#PCDATA)> <!ELEMENT ctmem:reten_gen (#PCDATA)> <!ELEMENT ctmem:schedule_environment (#PCDATA)> <!ELEMENT ctmem:shouts (ctmem:shout*)> <!ELEMENT ctmem:shout (ctmem:when?, ctmem:time?, ctmem:destination, ctmem:message, ctmem:urgency)> <!ELEMENT ctmem:sign (#PCDATA)> <!ELEMENT ctmem:statement (#PCDATA)> <!ELEMENT ctmem:step_ranges (ctmem:step_range)> <!ELEMENT ctmem:step_range (ctmem:name, ctmem:from_program_step, ctmem:to_program_step, ctmem:from_procedure_step, ctmem:to_procedure_step)>
Request Reference
9-21
<!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT
ctmem:subject (#PCDATA)> ctmem:sys_db (#PCDATA)> ctmem:sysout_from_class (#PCDATA)> ctmem:sysout_option (#PCDATA)> ctmem:sysout_parameter (#PCDATA)> ctmem:adjust_condition (#PCDATA)> ctmem:system_affinity (#PCDATA)> ctmem:table (#PCDATA)> ctmem:group_id (#PCDATA)> ctmem:task_type (#PCDATA)> ctmem:task_class (#PCDATA)> ctmem:time (#PCDATA)> ctmem:time_due_out (#PCDATA)> ctmem:time_from (#PCDATA)> ctmem:time_reference (#PCDATA)> ctmem:time_until (#PCDATA)> ctmem:time_zone (#PCDATA)> ctmem:to (#PCDATA)> ctmem:to_procedure_step (#PCDATA)> ctmem:to_program_step (#PCDATA)> ctmem:type (#PCDATA)> ctmem:urgency (#PCDATA)> ctmem:value (#PCDATA)> ctmem:when (#PCDATA)>
Parameters
Table 9-7 Job Creation Request XML Parameters Description (Part 1 of 32)
Parameter
Description
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_create_aj.dtd">
9-22
Table 9-7
Job Creation Request XML Parameters Description (Part 2 of 32)
Parameter
message_package
Description
Indicates to CONTROL-M/EM the beginning and end of the Job Creation Request XML specification. Job Creation specifications are placed between the opening and closing messages_package tags. Contains the version and ctmem (schema) attributes. Wrapper for the request element. xmlns:ctmem version (1.0) Schema pathname or URL and filename. String. version (1.0)
Example <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema" ctmem:version (1.0)></ctmem:message_package> request Indicates to CONTROL-M/EM the beginning and end of the Job Creation request. Contains the name, user_token, and mode attributes. Wrapper for the control-m and one active_job elements. name Name of the API request. Mandatory. Valid value: create_aj The user token that was assigned during registration. String. Mandatory. When this attribute is specified, the XML format of the Create Job request file is validated by CONTROL-M/EM. The jobs specified in the file are NOT submitted to the Active Jobs file. Optional. Valid value: validate
user_token
mode
Example <ctmem:request ctmem:name="create_aj" ctmem:user_token="1234567" mode=validate> </ctmem:request> control-m Data center name. String. Mandatory. Example: <ctmem:control-m>CTM_NYC</ctmem:control-m>
Request Reference
9-23
Table 9-7
Parameter
active_job
Description
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. Example: <ctmem:active_job> ... </ctmem:active_job>
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 Group Scheduling table. Optional. Valid values: no (Dont ignore. Default.) yes (Ignore relevant prerequisite conditions) Contained in the active_job element. Example: <ctmem:adjust_condition>yes</ctmem:adjust_condition>
application
Name of the application to which the jobs group belongs. Used as a descriptive name for related groups of jobs. Contained in the active_job element. Example: <ctmem:application>APPL_1</ctmem:application>
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. Contained in the active_job element. Example <ctmem:application_cm_version>610</ctmem:application_cm_version>
application_form
Specifies a predefined set of external application parameters that will be displayed in the External Application panel of the CONTROL-M/EM Job Editing form. Specified together with the application_cm_version, application_type, and application_version elements. Contained in the active_job element. Example: <ctmem:application_form>SAP</ctmem:application_form>
application_type
Indicates the type of external application (for example, SAP or Oracle Applications) on which the external application job will run. Specified together with the application_cm_version, application_form, and application_version elements. Contained in the active_job element. Example: <ctmem:application_type>SAP</ctmem:application_type>
9-24
Table 9-7
Parameter
application_ version
Description
Indicates the version of the external application (for example, SAP or Oracle Applications) on which the external application job will run. Specified together with the application_cm_version, application_form, and application_type elements. Contained in the active_job element. Example: <ctmem:application_version>4.6</ctmem:application_version>
arch_max_days
Maximum number of days to retains the SYSDATA archive dataset for jobs that ended NOTOK. [OS/390 only] Contained in the active_job element. Example: <ctmem:arch_max_days>5</ctmem:arch_max_days>
arch_max_runs
Maximum number of job runs to retain the SYSDATA archive dataset for jobs that ended NOTOK. [OS/390 only] Contained in the active_job element. Example: <ctmem:arch_max_runs>10</ctmem:arch_max_runs>
auto_archive
Determines whether or not SYSDATA is to be archived. Contained in the active_job element. [OS/390 only] Valid values: yes no Contained in the active_job element. Example: <ctmem:auto_archive>Y</ctmem:auto_archive>
autoedit_ assignment
A single AutoEdit expression. Contained in the autoedit_assignments element. Wrapper for the name and value elements. Example <ctmem:autoedit_assignment> <ctmem:name>%%PARM1</ctmem:name> <ctmem:value>%%TIME+%%DATE</ctmem:value> </ctmem:autoedit_assignment> name Name of theAutoEdit variable.
Example: <ctmem:name>Job1</ctmem:name> value Value of the AutoEdit expression. Contained in the do_autoedit and autoedit_assignment elements.
Example: <ctmem:do_autoedit>%%@TIME</ctmem:do_autoedit>
Request Reference
9-25
Table 9-7
Parameter
autoedit_ assignments
Description
Wrapper for one or more autoedit_assignment elements. Contained in the active_job element. Example <ctmem:autoedit_assignments> <ctmem:autoedit_assignment> <ctmem:name>%%PARM1</ctmem:name> <ctmem:value>%%TIME+%%DATE</ctmem:value> </ctmem:autoedit_assignment> </ctmem:autoedit_assignments>
command
Command string supplied when the job Task Type (the task_type element) is Command. Optional. Contained in the active_job element. Example: <ctmem:command>dir</ctmem:command>
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. Contained in the active_job element. Example: <ctmem:confirm_flag>no</ctmem:confirm_flag>
control_resource
Beginning and end tags indicating a Control resource. Contained in the control_resources element. Wrapper for the resource and type elements. Example <ctmem:control_resource> <ctmem:resource>disk</ctmem:resource> <ctmem:type>shared</ctmem:type> </ctmem:control_resource> resource Name of the specified resource.
Example: <ctmem:resource>Disk</ctmem:resource> type Indicates job access to a Control resource. Valid values: exclusive - default shared
Example: <ctmem:control_resource>shared</ctmem:control_resource>
9-26
Table 9-7
Parameter
control_resources
Description
Beginning and end tags containing one or more Control resource specifications. Contained in the active_job element. Wrapper for one or more control_resource elements. Example <ctmem:control_resources> <ctmem:control_resource> <ctmem:resource>disk</ctmem:resource> <ctmem:type>shared</ctmem:type> </ctmem:control_resource> </ctmem:control_resources>
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 Contained in the active_job element. Example: <ctmem:count_cyclic_from>START</ctmem:count_cyclic_from>
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 Contained in the active_job element. Example: <ctmem:critical>yes</ctmem:critical>
Request Reference
9-27
Table 9-7
Parameter
ctb_step
Description
Specification for a single CTB Step parameter. CTB Step adds CONTROL-M/Analyzer steps as the first and/or last step of the execution of the job. Contained in the ctb_steps element. Wrapper for the ctb_name, ctb_step_position, ctb_type, and ctb_arguments elements. Example <ctmem:ctb_step> <ctmem:ctb_name>CHKCALC</ctmem:ctb_name> <ctmem:ctb_step_position>start</ctmem:ctb_step_position> <ctmem:ctb_arguments>%%ODATE</ctmem:ctb_arguments> <ctmem:ctb_type>rule</ctmem:ctb_type> </ctmem:ctb_step> ctb_arguments CONTROL-M/Analyzer argument.
Example: <ctmem:ctb_arguments>%%ODATE</ctmem:ctb_arguments> ctb_name Name of the CONTROL-M/Analyzer entity. Must be a valid name of a CONTROL-M/Analyzer rule or mission.
Example: <ctmem:ctb_name>CHKCALC</ctmem:ctb_name> ctb_step_position Indicates where to place the CONTROL-M/Analyzer step in the job. Contained in the ctb_step element.
Example: <ctmem:ctb_step_position>START</ctmem:ctb_step_position> ctb_type Type of CONTROL-M/Analyzer entity.
Example: <ctmem:ctb_type>RULE</ctmem:ctb_type> ctb_steps Contains one or more CTB Step parameter specifications. Contained in the active_job element. Wrapper for the ctb_step element. Example <ctmem:ctb_steps> <ctmem:ctb_step> <ctmem:ctb_name>CHKCALC</ctmem:ctb_name> <ctmem:ctb_step_position>start</ctmem:ctb_step_position> <ctmem:ctb_arguments>%%ODATE</ctmem:ctb_arguments> <ctmem:ctb_type>rule</ctmem:ctb_type> </ctmem:ctb_step> </ctmem:ctb_steps>
9-28
Table 9-7
Parameter
cyclic
Description
Indicates if a job is cyclic. Valid values: yes Cyclic job no Non-cyclic job Contained in the active_job element. Example: <ctmem:cyclic>yes</ctmem:cyclic>
description
Text description of the job. Contained in the active_job element. Example: <ctmem:description>Acct dept report</ctmem:description>
doc_lib
Name of the directory/library containing the job documentation file. Contained in the active_job element. Example: <ctmem:doc_lib>acctdocs</ctmem:doc_lib>
doc_member
Name of the file containing job documentation. Contained in the active_job element. Example: <ctmem:doc_member>jobdoc.txt</ctmem:doc_member>
group
Name of the group to which the job belongs. Used as a descriptive name for related groups of jobs. Contained in the active_job element. Example: <ctmem:group>Acct</ctmem:group>
group_id
Order ID of the group. Contained in the active_job element. Example: <ctmem:group_id>Unixnode_1</ctmem:group_id>
Request Reference
9-29
Table 9-7
Parameter
in_condition
Description
A single In condition. Wrapper for the condition, date, and and_or elements. Contained in the in_conditions element. Example <ctmem:in_condition> <ctmem:condition>Cond1</ctmem:condition> <ctmem:date>1501</ctmem:date> <ctmem:and_or>or</ctmem:and_or> </ctmem:in_condition> and_or Specifies the relationship between two successive items in a series. Optional. Valid values: and or
Example: <ctmem:and_or>or</ctmem:and_or> condition Condition name.
Example: <ctmem:condition>Cond1</ctmem:condition> date Specifies an order date for various condition formats.
Example: <ctmem:date>ODAT</ctmem:date> in_conditions Wrapper for all the In conditions in the job. Wrapper for the in_condition element. Contained in the active_job element. Example <ctmem:in_conditions> <ctmem:in_condition> <ctmem:condition>Cond1</ctmem:condition> <ctmem:date>1501</ctmem:date> <ctmem:and_or>or</ctmem:and_or> </ctmem:in_condition> <ctmem:in_condition> <ctmem:condition>Cond2</ctmem:condition> <ctmem:date>ODAT</ctmem:date> </ctmem:in_condition> <ctmem:in_conditions>
9-30
Table 9-7
Parameter
job_name
Description
Name of the job. Contained in the active_job element. Example: <ctmem:job_name>Job1</ctmem:job_name>
max_wait
Number of extra days (beyond the original scheduling date) that the job is allowed to remain in the Active Jobs file awaiting execution. Integer. Contained in the active_job element. Example: <ctmem:max_wait>5</ctmem:max_wait>
mem_lib
Name of the library/directory in which the job script resides. String. Contained in the active_job element. Example: <ctmem:mem_lib>MVS.MEM.LIB</ctmem:mem_lib>
mem_name
Name of the file that contains the job script. String. Contained in the active_job element. Example: <ctmem:mem_name>MEM1</ctmem:mem_name>
multiagent
When selected, broadcasts job submission details to all Agents within a specified Node Group. Not for OS/390. Optional. Valid values: yes run as multi-agent job no not run as multi-agent job. Default. Contained in the active_job element. Example: <ctmem:multiagent>yes</ctmem:multiagent>
node_group
Host name of a node group to which the job should be submitted. Not for OS/390. Contained in the active_job element. Example: <ctmem:node_group>NYAGENTS</ctmem:node_group>
odate
Original scheduling date of a job. Contained in the active_job element. Example: <ctmem:odate>ODAT</ctmem:odate>
Request Reference
9-31
Table 9-7
Parameter
on_do_statement
Description
An On statement can have one or more Do statements associated with it. The on_do_statement element is a container for a single On statement and all its associated Do statements. Contained in the on_do_statements element. Wrapper for the on_statements and do_statements elements. <ctmem:on_do_statement> <ctmem:on_statements> <ctmem:on_statement> <ctmem:statement>*</ctmem:statement> <ctmem:code>ok</ctmem:code> </ctmem:on_statement> </ctmem:on_statements> <ctmem:do_statements> <ctmem:do_cond> <ctmem:condition>cond1</ctmem:condition> <ctmem:date>odat</ctmem:date> <ctmem:sign>delete</ctmem:sign> </ctmem:do_cond> </ctmem:do_statements> </ctmem:on_do_statement>
on_do_statements
Container for all On and Do statements in the job processing definition. Contained in the active_job element. Wrapper for one or more on_do_statement elements. <ctmem:on_do_statements> <ctmem:on_do_statement> <ctmem:on_statements> <ctmem:on_statement> <ctmem:statement>*</ctmem:statement> <ctmem:code>ok</ctmem:code> </ctmem:on_statement> </ctmem:on_statements> <ctmem:do_statements> <ctmem:do_cond> <ctmem:condition>cond1</ctmem:condition> <ctmem:date>odat</ctmem:date> <ctmem:sign>delete</ctmem:sign> </ctmem:do_cond> </ctmem:do_statements> </ctmem:on_do_statement> </ctmem:on_do_statements>
9-32
Table 9-7
Parameter
order_table
Description
Default or dummy Scheduling table to which you indicate the job belongs. A Scheduling table is not necessary because jobs that are created with the CONTROL-M/EM API are inserted directly into the Active Jobs file. However, you may want to include a value for this parameter so that the job can be tracked during statistical analysis that uses Scheduling table as a criterion. Contained in the active_job element. Example: <ctmem:order_table></ctmem:order_table>
order_library
Default or dummy Scheduling table library in which Scheduling table documentation is said to be stored. A Scheduling table (and, by extension, a Scheduling table library) are not necessary because jobs that are created with the CONTROL-M/EM API are inserted directly into the Active Jobs file. However, you may want to include a value for this parameter so that the job can be tracked during statistical analysis that uses Scheduling table or Scheduling Table Library as criteria. This parameter is specified only for OS/390 jobs for which the order_table element was also specified. Contained in the active_job element. Example: <ctmem:order_library></ctmem:order_library>
Request Reference
9-33
Table 9-7
Parameter
out_condition
Description
Specificatin for a single Out condition. Contained in the out_conditions element. Wrapper for the condition, date, and sign elements. Example <ctmem:out_condition> <ctmem:condition>Cond5</ctmem:condition> <ctmem:date>1212</ctmem:date> <ctmem:sign>add</ctmem:sign> </ctmem:out_condition> condition Condition name. When specified, it is be accompanied by the other condition parameter element, date (and, optionally, by sign or and_or).
Example: <ctmem:date>ODAT</ctmem:date> sign Indicates whether to add or delete an Out condition Valid values: add delete
Example: <ctmem:sign>delete</ctmem:sign> out_conditions Container for all Out conditions specified in the job processing definition. Contained in the active_job element. Wrapper for one or more out_condition elements. Example <ctmem:out_conditions> <ctmem:out_condition> <ctmem:condition>Cond5</ctmem:condition> <ctmem:date>1212</ctmem:date> <ctmem:sign>add</ctmem:sign> </ctmem:out_condition> </ctmem:out_conditions> over_lib Name of the alternate job script library/directory. Contained in the active_job element. Example: <ctmem:over_lib>MVS.MEM2.LIB</ctmem:over_lib>
9-34
Table 9-7
Parameter
owner
Description
Owner (username) associated with the job. Contained in the active_job element. Example: <ctmem:owner>johnr</ctmem:owner>
pipe
Indicates a dataset to be replaced by a pipe with the same name. Used only if CONTROL-M/WorkLoad is installed. [For OS/390 jobs, only.] Contained in the pipes element. Wrapper for the name and flag elements. Example <ctmem:pipe> <ctmem:name>CTL.IVP.FILE</ctmem:name> <ctmem:flag>a</ctmem:flag> </ctmem:pipe> flag Valid values: yes no
Example: <ctmem:flag>no</ctmem:flag> 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)
Example: <ctmem:name>job1</ctmem:name> pipes Container for all pipe specifications in the job. Contained in the active_job element. Wrapper for one or more pipe elements. Example <ctmem:pipes> <ctmem:pipe> <ctmem:name>CTL.IVP.FILE</ctmem:name> <ctmem:flag>a</ctmem:flag> </ctmem:pipe> </ctmem:pipes>
Request Reference
9-35
Table 9-7
Parameter
prevent_nct2
Description
Prevents dataset cleanup before the original job run. [OS/390 only]. Optional. Valid values: no Does not prevent dataset cleanup. Default. yes Prevents dataset cleanup. Contained in the active_job element. Example: <ctmem:prevent_nct2>yes</ctmem:prevent_nct2>
priority
Indicates CONTROL-M job priority. String. Contained in the active_job element. Example: <ctmem:priority>aa</ctmem:priority>
quantitative_ resource
User-defined variable representing a resource in the CONTROL-M installation. Contained in the quantitative_resources element. Wrapper for the resource and quantity elements. Example <ctmem:quantitative_resource> <ctmem:resource>Disk</ctmem:resource> <ctmem:quantity>10</ctmem:quantity> </ctmem:quantitative_resource> quantity Amount of the specified quantitative resource.
Example: <ctmem:quantity>10</ctmem:quantity> resource Name of the specified resource.
Example: <ctmem:resource>disk</ctmem:resource> quantitative_ resources Container for the quantitative resources specified in the job. Contained in the active_job element. Wrapper for the quantitative_resource element. Example <ctmem:quantitative_resources> <ctmem:quantitative_resource> <ctmem:resource>disk</ctmem:resource> <ctmem:quantity>10</ctmem:quantity> </ctmem:quantitative_resource> </ctmem:quantitative_resources>
9-36
Table 9-7
Parameter
request_nje
Description
Specifies the node in the JES network on which the job is to execute. [OS/390 only] String. Contained in the active_job element. Example: <ctmem:request_nje>R23<ctmem:request_nje>
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. Contained in the active_job element. Example: <ctmem:rerun_interval>30D</ctmem:rerun_interval>
rerun_max
Specifies the maximum number of reruns that can be performed for the job. Integer. Valid values: 0-99. Contained in the active_job element. Example: <ctmem:rerun_max>50</ctmem:rerun_max>
rerun_member
Name of the JCL member to use when the job is automatically rerun. [OS/390 only] String. Optional. Contained in the active_job element. Example: <ctmem:rerun_member>filez</ctmem:rerun_member>
reten_days
Number of days to retain the job in the History Jobs file. [OS/390, only]. String. Contained in the active_job element. Example: <ctmem:reten_days>4</ctmem:reten_days>
reten_gen
Maximum number of generations of the job to keep in the History Jobs file.[OS/390, only]. String. Contained in the active_job element. Example: <ctmem:reten_gen>2</ctmem:reten_gen>
schedule_ environment
Indicates the JES2 workload management scheduling environment that is to be associated with the job. OS/390, only. String. Contained in the active_job element. Example: <ctmem:schedule_environment>schd2</ctmem:schedule_environment>
Request Reference
9-37
Table 9-7
Parameter
shout
Description
The Shout parameter indicates a message to be sent (shouted) to one or more specified destinations when certain conditions are met. Contained in the shouts element. Wrapper for the destination, message, time, urgency, and when elements. Example <ctmem:shout> <ctmem:when>not_ok</ctmem:when> <ctmem:time>+5</ctmem:time> <ctmem:destination>emuser</ctmem:destination> <ctmem:urgency>urgent</ctmem:urgency> <ctmem:message>Job ran long.</ctmem:message> </ctmem:shout> destination Recipient of a Shout message. Specified in both the Shout or the Do Shout parameters.
Example: <ctmem:destination>billk</ctmem:destination> message Text of the message. String.
Example: <ctmem:message>Computer down.</ctmem:message> time Time that the message is sent.
Example: <ctmem:time>1200</ctmem:time> urgency Indicates the severity of a mail or shout message. Valid values: regular (Default) urgent very_urgent
Example: <ctmem:urgency>urgent</ctmem:urgency> when Time that the Shout message was sent. Valid values: ok not_ok rerun late_submission late_time execution_time
Example: <ctmem:when>1430</ctmem:when>
9-38
Table 9-7
Parameter
shouts
Description
Wrapper for all shouts included in the job processing definition. Contained in the active_job element. Wrapper for one or more shout elements. Example <ctmem:shouts> <ctmem:shout> <ctmem:when>late_time</ctmem:when> <ctmem:time>+5</ctmem:time> <ctmem:destination>emuser</ctmem:destination> <ctmem:urgency>urgent</ctmem:urgency> <ctmem:message>Job ran long.</ctmem:message> </ctmem:shout> </ctmem:shouts>
Request Reference
9-39
Table 9-7
Parameter
step_range
Description
Specifies a range of steps within the steps of an On PGMST statement. Contained in the step_ranges element. Wrapper for the from_procedure_step, from_program_step, name, to_procedure_step, and to_program_step elements. Example <ctmem:step_range> <ctmem:name>range_a</ctmem:name> <ctmem:from_program_step>Step1<ctmem:from_program_step> <ctmem:to_program_step>Step6<ctmem:to_program_step> </ctmem:step_range> from_procedure_ step Procedure step (EXEC statement) that invokes a procedure from which the specified program step program is executed.
Example: <ctmem:from_procedure_step>+EVERY</ctmem:from_process_step> from_program_step Job step. The execution results of the program executed by the job step are checked against the specified codes criteria.
Example: <ctmem:from_program_step>+EVERY</ctmem:from_procedure_step> to_procedure_step Last procedure step in a range.
Example: <ctmem:to_procedure_step>Step5</ctmem:to_procedure_step> to_program_step Last program step in a range.
Example: <ctmem:to_program_step>Step4</ctmem:to_program_step>
9-40
Table 9-7
Parameter
step_ranges
Description
Contains all step_range definitions in the job. Contained in the active_job element. Wrapper for the step_range element. Example <ctmem:step_ranges> <ctmem:step_range> <ctmem:name>range_a</ctmem:name> <ctmem:from_program_step>Step1<ctmem:from_program_step> <ctmem:to_program_step>Step6<ctmem:to_program_step> </ctmem:step_range> <ctmem:step_range> <ctmem:name>range_b</ctmem:name> <ctmem:from_program_step>step1<ctmem:from_program_step> <ctmem:to_program_step>step8<ctmem:to_program_step> </ctmem:step_range> <ctmem:step_ranges>
sys_db
Indicates that a single dataset will be used for archiving the SYSDATA of all jobs until it is full, when another dataset will be started. [OS/390 only] Valid values: yes Single dataset created for the SYSDATA of each job run. no Separate dataset created for the SYSDATA of each job run. Contained in the active_job element. Example: <ctmem:sys_db>yes</ctmem:sys_db>
sysout_from_class
Limits the sysout handling operation to only sysouts from the specified class. [OS/390 only] Contained in the active_job element. Example: <ctmem:sysout_from_class>b</ctmem:sysout_from_class>
Request Reference
9-41
Table 9-7
Parameter
sysout_option
Description
Sysout Handling options. Optional. Valid values (non-OS/390): copy delete move release Valid values (non-OS/390): copy delete move release change_class Contained in the active_job element. Example: <ctmem:sysout_option>delete</ctmem:sysout_option>
sysout_parameter
Certain OPTION values require that you supply additional information (such as Release, NewDest). Contained in the active_job element. Example: <ctmem:sysout_parameter>sysfile.txt</ctmem:sysout_parameter>
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). Note: For OS/390 jobs only. Contained in the active_job element. Example: <ctmem:system_affinity>SYS3</ctmem:system_affinity>
task_class
CONTROL-D mission. Mandatory for CONTROL-D jobs. Valid values: distribution decollation Contained in the active_job element. Example: <ctmem:task_class>Decollation</ctmem:task_class>
9-42
Table 9-7
Parameter
task_type
Description
Type of the job (task) to be performed by CONTROL-M. job task detached external command dummy scheduling_group Contained in the active_job element. Example: <ctmem:task_type>Command</ctmem:task_type>
time_due_out
Time that the job is expected to finish. Contained in the active_job element. Example: <ctmem:time_due_out>1200</ctmem:time_due_out>
time_from
Indicates the earliest time for submitting the job. Contained in the active_job element. Example: <ctmem:time_from>1200</ctmem:time_from>
time_reference
Valid values: server adjust Example: <ctmem:time_reference>server</ctmem:time_reference>
time_until
Indicates the latest time for submitting the job. Contained in the active_job element. Example: <ctmem:time_until>1200</ctmem:time_until>
time_zone
Indicates the global time zone used to calculate the interval for time-related conditions. Contained in the active_job element. Example: <ctmem:time_zone>EST</ctmem:time_zone>
Request Reference
9-43
Table 9-7
Parameter
do_statements
Description
Contains one or more Do statements associated with specific On statements. Contained in the on_do_statement element. Wrapper for the do, do_autoedit, do_cond, do_ctbrule, do_forcejob. do_ifrerun, do_mail, do_shout, and do_sysout elements. Example <ctmem:do_statements> <ctmem:do_shout> <ctmem:destination>zivb</ctmem:destination> <ctmem:message>Call Accounting department.</ctmem:message> <ctmem:urgency>U</ctmem:urgency> </ctmem:do_shout> <ctmem:do> <ctmem:action>RERUN</ctmem:action> </ctmem:do> </ctmem:do_statements>
do
Modifies the status of the job based on criteria specified with the On and On Statement/Code parameters. Contained in the do_statements element. Wrapper for the action element. Example <ctmem:do> <ctmem:action>rerun</ctmem:action> </ctmem:do> action Action specified for a Do statement. Mandatory when a do element is specified. String. Optional. Valid values: ok not_ok rerun stop_cyclic
Example: <ctmem:action>ok</ctmem:action>
9-44
Table 9-7
Parameter
do_autoedit
Description
Assigns an AutoEdit variable when the On criteria are met. Contained in the do_statements element. Wrapper for the name and value elements. Example <ctmem:do_autoedit> <ctmem:name>%%PARM1</ctmem:name> <ctmem:value>%%DATE</ctmem:value> </ctmem:do_autoedit> 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)
Example: <ctmem:name>Job1</ctmem:name> value Value of the AutoEdit expression.
Example: <ctmem:do_autoedit>%%@TIME</ctmem:do_autoedit>
Request Reference
9-45
Table 9-7
Parameter
do_cond
Description
Assigns an In or Out condition when the On criteria are met. Contained in the do_statements element. Wrapper for the condition, date, and sign elements. Example <ctmem:do_cond> <ctmem:condition>Cond1</ctmem:condition> <ctmem:date>ODAT</ctmem:date> <ctmem:sign>DEL</ctmem:sign> </ctmem:do_cond> condition Condition name. When specified, it is be accompanied by the other condition parameter element, date (and, optionally, by sign or and_or). Wrapped in the in_condition and out_condition elements.
Example: <ctmem:date>ODAT</ctmem:date> sign Indicates whether to add or delete an Out condition Valid values: add delete
Example: <ctmem:sign>DEL</ctmem:sign> 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. Contained in the do_statements element. Wrapper for the name and parameter elements. Example <ctmem:do_ctbrule> <ctmem:name>GOVTBAL</ctmem:name> <ctmem:parameter>DOREPORT,10,%%ODATE</ctmem:parameter> <ctmem:do_ctbrule> name Name of the CONTROL-M/Analyzer rule.
Example: <ctmem:name>GOVTBAL</ctmem:name> parameter parameter contains arguments that are passed to the CONTROL-M/Analyzer rule.
Example: <ctmem:parameter>sysdoc.txt</ctmem:parameter>
9-46
Table 9-7
Parameter
do_forcejob
Description
Forces a specified job when the current job is performed. Contained in the do_statements element. Wrapper for the job, table, odate, and dsn elements. Note: The dsn element is for OS/390 jobs, only. Example <ctmem:do_forcejob> <ctmem:job>Job0</ctmem:job> <ctmem:odate>ODAT</ctmem:odate> <ctmem:table>Tbl1</ctmem:table> </ctmem:do_forcejob> dsn Name of the directory/library containing Scheduling table file. [OS/390 only]
Example: <ctmem:dsn>TBLDIR</ctmem:dsn> job Specifies the job name of the job that will be forced.
Example: <ctemem:job>Job1</ctmem:job> odate Original scheduling date of a job.
Example: <ctmem:odate>ODAT</ctmem:odate> table Name of the Scheduling table with which the job specified in do_forcejob is associated.
Example: <ctmem:table>Tbl_7</ctmem:table>
Request Reference
9-47
Table 9-7
Parameter
do_ifrerun
Description
Specifies job steps to be executed during rerun of a job. Only for networks using CONTROL-M/Restart. Contained in the do_statements element. Wrapper for the confirm, from_program_step, from_procedure_step, to_program_step, and to_procedure_step elements. Example <ctmem:do_ifrerun> <ctmem:from_program_step>step1</ctmem:from_program_step> <ctmem:to_program_step>step5</ctmem:to_program_step> <ctmem:confirm>1</ctmem:confirm> </ctmem:do_ifrerun> 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
Example: <ctmem:confirm>yes</ctmem:confirm> from_procedure_ step Procedure step (EXEC statement) that invokes a procedure from which the specified program step program is executed.
Example: <ctmem:from_procedure_step>+EVERY</ctmem:from_process_step> from_program_step Job step. The execution results of the program executed by the job step are checked against the specified codes criteria.
Example <ctmem:from_program_step>+EVERY</ctmem:from_procedure_step> to_procedure_step Last procedure step in a range.
Example <ctmem:to_procedure_step>Step5</ctmem:to_procedure_step> to_program_step Last program step in a range.
Example <ctmem:to_program_step>Step4</ctmem:to_program_step>
9-48
Table 9-7
Parameter
do_mail
Description
Contained in the do_statements element. Wrapper for the confirm, to, cc, subject, message, and urgency elements. Example <ctmem:do_mail> <ctmem:to>zivb</ctmem:to> <ctmem:cc>admin</ctmem:cc> <ctmem:subject>job failure</ctmem:subject> <ctmem:message>Call Accounting department.</ctmem:message> <ctmem:urgency>urgent</ctmem:urgency> </ctmem:do_mail> cc Optional additional address to which a Do Mail can be sent. Optional.
Example: <ctmem:cc>ziv@ziv.net</ctmem:cc> message Text of the message. String.
Example: <ctmem:message>Computer down.</ctmem:message> to Recipient of the shout message.
Example: <ctmem:to>billk</ctmem:to> subject Subject of the do_mail message.
Example: <ctmem:subject>Annual report printed.</ctmem:subject> urgency Indicates the severity of a mail or shout message. Valid values: regular (Default) urgent very_urgent (for do_shout and shout, only)
Example: <ctmem:urgency>urgent</ctmem:urgency>
Request Reference
9-49
Table 9-7
Parameter
do_shout
Description
Sends a shout message when the On criteria are met. Contained in the do_statements element. Wrapper for the confirm, destination, message, and urgency elements. Example <ctmem:do_shout> <ctmem:destination>zivb</ctmem:destination> <ctmem:message>Call Accounting department.</ctmem:message> <ctmem:urgency>urgent</ctmem:urgency> </ctmem:do_shout> destination Recipient of a Shout message. Specified in both the Shout or the Do Shout parameters.
Example: <ctmem:destination>billk</ctmem:destination> message Text of the message. String.
Example: <ctmem:message>Computer down.</ctmem:message> urgency Indicates the severity of a mail or shout message. Valid values: regular (Default) urgent very_urgent (for do_shout and shout, only)
Example: <ctmem:urgency>urgent</ctmem:urgency>
9-50
Table 9-7
Parameter
do_sysout
Description
Determines what to do with the sysout documentation when On criteria are met. Contained in the do_statements element. Wrapper for the confirm, option, parameter, and from_class elements. Example <ctmem:do_sysout> <ctmem:option>Copy</ctmem:option> <ctmem:parameter>sysdoc.txt</ctmem:parameter> <ctmem:from_class>J</ctmem:from_class> </ctmem:do_sysout> from_class Specifies the class of jobs whose sysouts are handled using the Do Sysout specifications of the job.
Example: <ctmem:from_class>J</ctmem:from_class> option Do Sysout parameter sysout handling options. Valid values: Release Delete Copy Move File NewDest ChangeClass Note: Copy and Move are not used with OS/390. File, NewDest, and ChangeClass are used only with OS/390.
Example: <ctmem:option>Copy</ctmem:option> parameter parameter contains additional sysout handling information. The type of information required is dependent on the value of the option element.
Example: <ctmem:parameter>sysdoc.txt</ctmem:parameter>
Request Reference
9-51
Table 9-7
Parameter
on_statement
Description
Specifies a statement and error code that determine when/if Do statements should be applied. Contained in the on_statements element. Wrapper for the code, statement, program_step, procedure_step, and and_or elements. <ctmem:on_statement> <ctmem:code>*</ctmem:code> <ctmem:statement>*</ctmem:statement> </ctmem:on_statement> and_or Specifies the relationship between two successive items in a series. Optional.
Example: <ctmem:and_or>or</ctmem:and_or> code Code value for the On Statement/Code parameter. Valid values: ok not_ok
Example: <ctmem:code>ok</ctmem:code> procedure_step Step in the procedure that triggers the On statement. String.
Example: <ctmem:procedure_step>STEP1</ctmem:procedure_step> program_step Step in the program that triggers the On statement. String.
Example: <ctmem:program_step>STEP1</ctmem:program_step> 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.
Example: <ctmem:statement>*</ctmem:statement>
9-52
Table 9-7
Parameter
on_statements
Description
Multiple On statements can be included in a job. The on_statements element contains all of the On statements in a single on_do_statement package. Contained in the on_do_statements element. Wrapper for one or more on_statement elements. <ctmem:on_statements> <ctmem:on_statement> <ctmem:code>ok</ctmem:code> <ctmem:statement>*</ctmem:statement> </ctmem:on_statement> <ctmem:on_statement> <ctmem:code>*</ctmem:code> <ctmem:statement>C****</ctmem:statement> </ctmem:on_statement> </ctmem:on_statements>
Example
Numerous Job Creation sample files are presented in Chapter , Request Format Examples.
Response
Responses to job and Group Scheduling table creation requests are sent in a format conforming to the standard described in the .dtd file below.
EMAPI_create_ajResponse.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:status (#PCDATA)> <!ELEMENT ctmem:error_message (#PCDATA)> <!ELEMENT ctmem:error (ctmem:error_message)> <!ATTLIST ctmem:error ctmem:major CDATA #REQUIRED ctmem:minor CDATA #REQUIRED ctmem:severity CDATA #REQUIRED >
Request Reference
9-53
<!ELEMENT ctmem:error_list (ctmem:error+)> <!ATTLIST ctmem:error_list ctmem:highest_severity CDATA #REQUIRED> <!ELEMENT ctmem:order_id (#PCDATA)> <!ELEMENT ctmem:rba (#PCDATA)> <!ELEMENT ctmem:mem_name (#PCDATA)> <!ELEMENT ctmem:job_name (#PCDATA)> <!ELEMENT ctmem:is_group (#PCDATA)> <!ELEMENT ctmem:ret_text (#PCDATA)> <!ELEMENT ctmem:job_data (ctmem:rba, ctmem:order_id, ctmem:mem_name?, ctmem:job_name?, ctmem:is_group, ctmem:ret_text?)> <!ELEMENT ctmem:job (ctmem:status, ctmem:job_data?, ctmem:error_list?)> <!ELEMENT ctmem:jobs (ctmem:job+)> <!ELEMENT ctmem:response_data (ctmem:status, ctmem:jobs?, ctmem:error_list?)> <!ATTLIST ctmem:response_data ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:response (ctmem:status, ctmem:response_data?, ctmem:jobs?, ctmem:error_list?)> <!ATTLIST ctmem:response ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:message_package (ctmem:response)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version CDATA #REQUIRED>
Parameters Parameter Description
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_create_ajResponse.dtd">
9-54
Parameter
message_package
Description
Indicates to CONTROL-M/EM the beginning and end of the Order/Force Request XML specification. Order and force specifications are placed between the opening and closing messages_package tags. Contains the ctmem attribute and the response element. xmlns:ctmem version Schema pathname or URL and filename. String. 1.0
Example <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema" ctmem:version=1.0> </ctmem:message_package> response Type of response contained documented in the XML file. Contains the request_name attribute. Wrapper for the status, error-list, response_data, and jobs elements. request_name Request type for which the response was generated. Valid value: create_aj
Example <ctmem:response ctmem:request_name=create_aj> </ctmem:response> response_data Describes the response and the jobs to which the response refers. Contains the request_name attribute. Wrapper for the status, jobs, and error-list elements. request_name Valid value: create_aj
Example <ctmem:response_data request_name = "order_force"> </ctmem:response_data> status Describes the condition of the element that contains it.(for example, Error). String. Contained in the response, response_data, and job elements. Example <ctmem:status>Error</ctmem:status>
Request Reference
9-55
Parameter
error-list
Description
Begins and ends the list of xxx errors. Contains the highest_severity attrbute. Wrapper for the one or more error elements. Note: error-list contains the errors reported for the response, response_data, and job elements. 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.
minor
severity
Example <ctmem:error ctmem:major=405 ctmem:minor=4 ctmem:severity=Error> <ctmem:error_message>No jobs were ordered. </ctmem:error_message> </ctmem:error> error_message Text description of the error. For more information, see Appendix B, Error Codes and Exceptions. String.
Example: <ctmem:error_message>No jobs were ordered.</ctmem:error_message>

9-56
Parameter
jobs
Description
Wrapper for one or more job elements. Contained in the response and response_data elements. Example:<ctmem:jobs></ctmem:jobs>
job
Tags that indicate a single job. Contqained in the jobs element. Wrapper for the status, error-list, and job_data elements. Example <ctmem:job> <ctmem:status>OK</ctmem:status> <ctmem:job_data> <ctmem:order_id>aa123</ctmem:order_id> <ctmem:mem_name>Mem0</ctmem:mem_name> <ctmem:job_name>Job0</ctmem:job_name> <ctmem:is_group>yes</ctmem:is_group> <ctmem:ret_text>"Job was ordered"</ctmem:ret_text> </ctmem:job_data> </ctmem:job>
job_data
Element that contains other elements (parameters) that describe the job. Wrapper for the is_group, order_id, mem_name, job_name, and ret_text elements. Example <ctmem:job_data> <ctmem:order_id>aa123</ctmem:order_id> <ctmem:mem_name>Mem0</ctmem:mem_name> <ctmem:job_name>Job0</ctmem:job_name> <ctmem:is_group>yes</ctmem:is_group> <ctmem:ret_text>"Job was ordered"</ctmem:ret_text> </ctmem:job_data>
mem_name
Name of the file that contains the job script. String. Contained in the job_data element. Example <ctmem:mem_name>myjob.bat</ctmem:mem_name>
order_id
Serial number assigned to the job by the CONTROL-M installation. String. Contained in the job_data element. Example: <ctmem:order_id>56643</ctmem:order_id>
job_name
Name of the job. String. Contained in the job_data element. Example: <ctmem:job_name>job33</ctmem:job_name>
Request Reference
9-57
Parameter
is_group
Description
Indicates whether the job is a member of a Group Scheduling table. Valid values: no (not a member of a Group Scheduling table) yes (member of a Group Scheduling table) Contained in the job_data element. Example: <ctmem:is_group>yes</ctmem:is_group>
ret_text
Text describing the job run. String. Contained in the job_data element. Example: <ctmem:ret_text>"Job was ordered"</ctmem:ret_text>
Errors
Job creation errors are described in Create Active Job Request Errors (Major Code 409) on page B-22.
9-58
Order/Force Request
Does the following operations with jobs and Group Scheduling tables: Order a job. The job is entered into the Active Jobs file only when its scheduling criteria are met. Force a job. The Job is entered into the Active Jobs file whether or not its scheduling criteria are met. Order or force a Group Scheduling table. All jobs in the table are ordered or forced.
The mandatory parameters for ordering a job differ from the mandatory parameters that are specified when ordering or forcing a Group Scheduling table. Optional parameters can be supplied for both jobs and Group Scheduling tables.
Note
Order and Force requests using the API are supported by CONTROL-M for OS/390 version 6.1.01 or later and by other CONTROL-M releases version 6.0.01 or later. This functionality is supported by CONTROL-M/EM version 6.1.01 or later.
Request Format
EMAPI_order_force.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:control_m (#PCDATA)> <!ELEMENT ctmem:force_it (#PCDATA)> <!ELEMENT ctmem:job_id (#PCDATA)> <!ELEMENT ctmem:job_name (#PCDATA)> <!ELEMENT ctmem:odate (#PCDATA)> <!ELEMENT ctmem:table_library (#PCDATA)>
Request Reference
9-59
<!ELEMENT ctmem:table_name (#PCDATA)> <!ELEMENT ctmem:autoedit_assignments (ctmem:autoedit_assignment+)> <!ELEMENT ctmem:autoedit_assignment (ctmem:name, ctmem:value)> <!ELEMENT ctmem:name (#PCDATA)> <!ELEMENT ctmem:value (#PCDATA)> <!ELEMENT ctmem:into_group (#PCDATA)> <!ELEMENT ctmem:group_id (#PCDATA)> <!ELEMENT ctmem:allow_dup (#PCDATA)> <!ELEMENT ctmem:scheduling_group_info (ctmem:into_group, ctmem:group_id?, ctmem:allow_dup?)> <!ELEMENT ctmem:message_package (ctmem:request)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED > <!ELEMENT ctmem:request (ctmem:force_it, ctmem:control_m, ctmem:job_id?, ctmem:job_name?, ctmem:table_name, ctmem:table_library?, ctmem:odate, ctmem:autoedit_assignments?, ctmem:scheduling_group_info?)> <!ATTLIST ctmem:request ctmem:name CDATA #REQUIRED ctmem:user_token CDATA #REQUIRED >
9-60
Parameters
Table 9-8 Order/Force XML Parameters Description
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_order_force.dtd"> message_package Indicates to CONTROL-M/EM the beginning and end of the Order/Force Request XML specification. Order and force specifications are placed between the opening and closing messages_package tags. Contains the version and ctmem (schema) attributes. xmlns:ctmem version (1.0) Schema pathname or URL and filename. String. version (1.0)
Example <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema" ctmem:version (1.0)></ctmem:message_package> request Indicates to CONTROL-M/EM the beginning and end of the Order/Force request. Contains the name and user_token attributes. Wrapper for the control_m, force_it, job_id, job_name, table_name, table_library, odate, autoedit_assignments, and scheduling_group_info elements. name Name of the API request. Valid value: order_force The user token that was assigned during registration. String.
user_token
Example <ctmem:request ctmem:name="order_force" ctmem:user_token="1234567"></ctmem:request> control_m Data center name. Mandatory for both jobs and Scheduling tables. String.
Example <ctmem:control_m>CTM_NYC</ctmem:control_m>
Request Reference
9-61
Table 9-8
Order/Force XML Parameters Description
Parameter
force_it
Description
Indicates whether the job is ordered or forced. Mandatory for both jobs and Scheduling tables.
Valid Values
no - orders job/table yes - forces job/table
Example: <ctmem:force_it>yes</ctmem:force_it> job_id Serial number of the job. Mandatory for jobs. Must be left empty for tables. String.
Example: <ctmem:job_id>1403</ctmem:job_id> job_name Name of the job. Mandatory for jobs. Must be left empty for tables. String.
Example: <ctmem:job_name>job33</ctmem:job_name> odate Enables you to order the job with a specific date. Mandatory for both jobs and Scheduling tables. Valid values: Numerical date ( yyyymmdd format) ODAT
Example: <ctmem:odate>20010424</ctmem:odate> table_library Scheduling table library. Optional for both jobs and Scheduling tables. String.
Example: <ctmem:table_library=juntbls></ctmem:table_library> table_name Name of the Scheduling table. Mandatory for both jobs and Scheduling tables. String.
Example: <ctmem:table_name>hrtb67</ctmem:table_name> autoedit_ assignments Container for the AutoEdit statements. Wrapper for one or more autoedit_assignment elements. Example: <ctmem:autoedit_assignments><ctmem:autoedit_assignments/> autoedit_ assignment Tag in which a single AutoEdit statement is placed. There can be multiple AutoEdit statements. Optional. Wrapper for the name and value elements.
9-62
Table 9-8
Order/Force XML Parameters Description
Parameter
name
Description
Name of the AutoEdit variable. Mandatory, if the autoedit_assighnment element is specified.
Valid Values
String.
Example: <ctmem:name>%%DATE</ctmem:name> value Value of the AutoEdit expression. String.
Example: <ctmem:value>311201</ctmem:value> scheduling_group _ info Tag that holds the descriptive information for the Group Scheduling table. Mandatory for jobs in Group Scheduling tables. Wrapper for the into_group, group_id, and allow_dup elements. Example <ctmem:scheduling_group_info> <ctmem:into_group>RECENT</ctmem:into_group> <ctmem:group_id>grp03</ctmem:group_id> <ctmem:allow_dup>1</ctmem:allow_dup> </ctmem:scheduling_group_info> into_group Indicates into which Group Scheduling table the job is placed. Optional for jobs. Not used for tables. RECENT NEW STANDALONE SELECTED order ID of a Group Scheduling table
Example: <ctmem:into_group>NEW</ctmem:into_group> group_id Serial number identifying the Group Scheduling table. Optional for jobs. Must be left empty for tables. String.
Example: <ctmem:group_id>grp03</ctmem:group_id> allow_dup Allows duplicate jobs in a Group Scheduling table. Optional for jobs. Must be left empty for tables (accepts default). Valid values: no - Not allowed yes - Allowed (default)
Example: <ctmem:allow_dup>1</ctmem:allow_dup>
Request Reference
9-63
Example
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_order_force.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:request ctmem:name="order_force" ctmem:user_token="$USER_TOKEN$"> <ctmem:force_it>yes</ctmem:force_it> <ctmem:control_m>mig</ctmem:control_m> <ctmem:job_id>1</ctmem:job_id> <ctmem:job_name>job33</ctmem:job_name> <ctmem:table_name>tbl2</ctmem:table_name> <ctmem:table_library/> <ctmem:odate>20010424</ctmem:odate> <ctmem:autoedit_assignments> <ctmem:autoedit_assignment> <ctmem:name>KUKU</ctmem:name> <ctmem:value>123</ctmem:value> </ctmem:autoedit_assignment> </ctmem:autoedit_assignments> <ctmem:scheduling_group_info> <ctmem:into_group>selected</ctmem:into_group> <ctmem:group_id>we433</ctmem:group_id> <ctmem:allow_dup>yes</ctmem:allow_dup> </ctmem:scheduling_group_info> </ctmem:request> </ctmem:message_package>
Responses
An Order/Force request made using the EMXMLInvoker (Native) API format returns a different response than a request made using the EMBasicXMLInvoker (Basic) API format:
9-64
An Order/Force request made using the EMXMLInvoker (Native) API requires manual polling. Therefore, the Order/Force reponse will initially contain a wrapper that reports on the status of the polling itself. Information about the result of the request itself is inside this wrapper. When an Order/Force request is made using the EMBasicXMLInvoker (Basic) API, polling is automatic. the wrapper that reports the status of the poll request is not included in the response. The response information is limited to the result of the request itself. This information is supplied by the CONTROL-M installation.
The .dtd file is the same in both cases. However, the parameters contained in the file differ somewhat. Parameters for Order/Force requests made using the EMXMLInvoker API are described in Table 9-9, Order/Force Response XML Parameters Description (Native API), on page 9-66. Parameters for Order/Force requests made using the EMBasicXMLInvoker API are described in Table 9-9, Order/Force Response XML Parameters Description (Native API), on page 9-66.
EMAPI_order_forceResponse.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:status (#PCDATA)> <!ELEMENT ctmem:error_message (#PCDATA)> <!ELEMENT ctmem:error (ctmem:error_message)> <!ATTLIST ctmem:error ctmem:major CDATA #REQUIRED ctmem:minor CDATA #REQUIRED ctmem:severity CDATA #REQUIRED > <!ELEMENT ctmem:error_list (ctmem:error+)> <!ATTLIST ctmem:error_list ctmem:highest_severity CDATA #REQUIRED > <!ELEMENT ctmem:order_id (#PCDATA)> <!ELEMENT ctmem:mem_name (#PCDATA)>
Request Reference
9-65
<!ELEMENT ctmem:job_name (#PCDATA)> <!ELEMENT ctmem:is_group (#PCDATA)> <!ELEMENT ctmem:ret_text (#PCDATA)> <!ELEMENT ctmem:job_data (ctmem:order_id, ctmem:mem_name?, ctmem:job_name?, ctmem:is_group?, ctmem:ret_text)> <!ELEMENT ctmem:job (ctmem:status, ctmem:job_data?, ctmem:error_list?)> <!ELEMENT ctmem:jobs (ctmem:job+)> <!ELEMENT ctmem:response_data (ctmem:status, ctmem:jobs?, ctmem:error_list?)> <!ATTLIST ctmem:response_data ctmem:request_name CDATA #REQUIRED > <!ELEMENT ctmem:response (ctmem:status, ctmem:response_data?, ctmem:error_list?)> <!ATTLIST ctmem:response ctmem:request_name CDATA #REQUIRED > <!ELEMENT ctmem:message_package (ctmem:response)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED>
Response parameters for an EMXMLInvoker (Native) Order/Force Request

Table 9-9 Order/Force Response XML Parameters Description (Native API)
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_order_forceResponse.dtd">
9-66
Table 9-9
Order/Force Response XML Parameters Description (Native API)
Parameter
message_package
Description
Valid Values
Indicates to CONTROL-M/EM the beginning and end of the Order/Force Request XML specification. Order and force specifications are placed between the opening and closing messages_package tags. Contains the ctmem attribute and the response element. xmlns:ctmem Schema pathname or URL and filename. String.
Example <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema"> </ctmem:message_package> response Type of response contained documented in the XML file. Contains the name attribute. Is a wrapper for the status, error-list, response_data elements. name Request type for which the response was generated. Valid value: poll
Example <ctmem:response ctmem:name=poll> <ctmem:status>Error</ctmem:status> <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=404 ctmem:minor=2 ctmem:severity=Error> <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message> </ctmem:error> </ctmem:error_list> </ctmem:response> status Describes the condition of the element that contains it.(for example, Error). String. Note: status is a descriptive element in the response, response_data, and job elements. Example: <ctmem:status>Error</ctmem:status>
Request Reference
9-67
Table 9-9
Parameter
error-list
Description
Valid Values
Begins and ends the list of xxx errors. Contains the highest_severity attrbute. Wrapper for the one or more error elements. Note: error-list contains the errors reported for the response, response_data, and job elements. 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.
minor
severity
Example <ctmem:error ctmem:major=405 ctmem:minor=4 ctmem:severity=Error> <ctmem:error_message>No jobs were ordered. </ctmem:error_message> </ctmem:error>
9-68
Table 9-9
Parameter
error_message
Description
Text description of the error. For more information, see Appendix B, Error Codes and Exceptions.
Valid Values
String.
<ctmem:error_message>No jobs were ordered.</ctmem:error_message> response_data Describes the response and the jobs to which the response refers. Contains the request_name attribute. Wrapper for the status, jobs, and error-list elements. request_name Valid value: order_force
Example <ctmem:response_data request_name = "order_force"> </ctmem:response_data> jobs Wrapper for one or more jobs described with job elements. Example: <ctmem:jobs></ctmem:jobs> job Beginning and end tags that indicate a single job. Wrapper for the status, error-list, and job_data elements. Example <ctmem:job> <ctmem:status>OK</ctmem:status> <ctmem:job_data> <ctmem:order_id>aa123</ctmem:order_id> <ctmem:mem_name>Mem0</ctmem:mem_name> <ctmem:job_name>Job0</ctmem:job_name> <ctmem:is_group>yes</ctmem:is_group> <ctmem:ret_text>"Job was ordered"</ctmem:ret_text> </ctmem:job_data> </ctmem:job> job_data Element that contains other elements (parameters) that describe the job. Wrapper for the is_group, order_id, mem_name, job_name, and ret_text elements. Example <ctmem:job_data> <ctmem:order_id>aa123</ctmem:order_id> <ctmem:mem_name>Mem0</ctmem:mem_name> <ctmem:job_name>Job0</ctmem:job_name> <ctmem:is_group>yes</ctmem:is_group> <ctmem:ret_text>"Job was ordered"</ctmem:ret_text> </ctmem:job_data>
Request Reference
9-69
Table 9-9
Parameter
mem_name
Description
Name of the file that contains the job script.
Valid Values
String.
Example: <:mem_name>myjob.bat</ctmem:mem_name> order_id Serial number assigned to the job by the CONTROL-M installation. String.
Example: <ctmem:order_id>56643</ctmem:order_id> job_name Name of the job. Mandatory. String.
Example: <ctmem:job_name>job33</ctmem:job_name> is_group Indicates whether the job is a member of a Group Scheduling table. Valid values: no (not a member of a Group Scheduling table) yes (member of a Group Scheduling table)
Example: <ctmem:is_group>yes</ctmem:is_group> ret_text Text describing the job run. String.
Example: <ctmem:ret_text>"Job was ordered"</ctmem:ret_text>
Example 1: One job was ordered successfully and one job has an error
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_order_forceResponse.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema"> <ctmem:response name="poll"> <ctmem:status>OK</ctmem:status> <ctmem:response_data request_name = "order_force"> <ctmem:status>OK</ctmem:status> <ctmem:jobs> <ctmem:job> <ctmem:status>OK</ctmem:status> job_data> <ctmem:order_id>aa123</ctmem:order_id> <ctmem:mem_name>Mem0</ctmem:mem_name>
9-70
<ctmem:job_name>Job0</ctmem:job_name> <ctmem:is_group>yes</ctmem:is_group> <ctmem:ret_text>"Job was ordered"</ctmem:ret_text> </job_data> </ctmem:job> <ctmem:job> <ctmem:status>ERROR</ctmem:status> <ctmem:error-list ctmem:highest_severity="Error" > <ctmem:error ctmem:major="32000" ctmem:minor="00001" ctmem:severity="Error" > <ctmem:error_message> Job "Job1". Security violation </ctmem:error_message> </ctmem:error> </ctmem:error-list> </ctmem:job> </ctmem:jobs> </ctmem:response_data> </ctmem:response> </ctmem:message_package>
Example 2: No Jobs were ordered <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_order_forceResponse.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema"> <ctmem:response name="poll"> <ctmem:status>OK</ctmem:status> <ctmem:response_data request_name = "order_force"> <ctmem:status>ERROR</ctmem:status> <ctmem:error-list ctmem:highest_severity="Error" > <ctmem:error ctmem:major="32000" ctmem:minor="00001" ctmem:severity="Error" > <ctmem:error_message> Scheduling table "TBL1". Security violation </ctmem:error_message> </ctmem:error> </ctmem:error-list> </ctmem:response_data>
Request Reference
9-71
</ctmem:response> </ctmem:message_package>
Response parameters for an EMBasicXMLInvoker (Basic) Order/Force Request

Table 9-10 Order/Force Response XML Parameters Description (Basic API)
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_order_forceResponse.dtd"> message_package Indicates to CONTROL-M/EM the beginning and end of the Order/Force Request XML specification. Order and force specifications are placed between the opening and closing messages_package tags. Contains the xmlns:ctmem attribute and the response element. xmlns:ctmem Schema pathname or URL and filename. String.
Example <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema"> </ctmem:message_package> response Type of response contained documented in the XML file. Contains the name attribute. Is a wrapper for the status, error-list, response_data elements. name Request type for which the response was generated. Valid values: order_force
Example <ctmem:response ctmem:name=poll> <ctmem:status>Error</ctmem:status> <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=404 ctmem:minor=2 ctmem:severity=Error> <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message> </ctmem:error> </ctmem:error_list> </ctmem:response>
9-72
Table 9-10
Order/Force Response XML Parameters Description (Basic API)
Parameter
status
Description
Valid Values
Describes the condition of the element that contains it.(for example, Error). String. Note: status is a descriptive element in the response and job elements. Example: <ctmem:status>Error</ctmem:status>
error-list
Begins and ends the list of xxx errors. Contains the highest_severity attrbute. Wrapper for the one or more error elements. Note: error-list contains the errors reported for the response and jobs elements. 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.
Example <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=404 ctmem:minor=2 ctmem:severity=Error> <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message> </ctmem:error> </ctmem:error_list>
Request Reference
9-73
Table 9-10
Parameter
error
Description
Valid Values
minor
severity
Example <ctmem:error ctmem:major=405 ctmem:minor=4 ctmem:severity=Error> <ctmem:error_message>No jobs were ordered. </ctmem:error_message> </ctmem:error> error_message Text description of the error. For more information, see Appendix B, Error Codes and Exceptions. String.
Example: <ctmem:error_message>No jobs were ordered.</ctmem:error_message> jobs Wrapper for one or more jobs described with job elements. Example: <ctmem:jobs></ctmem:jobs>
9-74
Table 9-10
Parameter
job
Description
Valid Values
Beginning and end tags that indicate a single job. Wrapper for the status, error-list, and job_data elements. Example <ctmem:job> <ctmem:status>OK</ctmem:status> <ctmem:job_data> <ctmem:order_id>aa123</ctmem:order_id> <ctmem:mem_name>Mem0</ctmem:mem_name> <ctmem:job_name>Job0</ctmem:job_name> <ctmem:is_group>yes</ctmem:is_group> <ctmem:ret_text>"Job was ordered"</ctmem:ret_text> </ctmem:job_data> </ctmem:job>
job_data
Element that contains other elements (parameters) that describe the job. Wrapper for the is_group, order_id, mem_name, job_name, and ret_text elements. Example <ctmem:job_data> <ctmem:order_id>aa123</ctmem:order_id> <ctmem:mem_name>Mem0</ctmem:mem_name> <ctmem:job_name>Job0</ctmem:job_name> <ctmem:is_group>yes</ctmem:is_group> <ctmem:ret_text>"Job was ordered"</ctmem:ret_text> </ctmem:job_data>
mem_name
Name of the file that contains the job script.
String.
Example: <ctmem:mem_name>myjob.bat</ctmem:mem_name> order_id Serial number assigned to the job by the CONTROL-M installation. String.
Example: <ctmem:order_id>56643</ctmem:order_id> job_name Name of the job. Mandatory. String.
Example: <ctmem:job_name>job33</ctmem:job_name>
Request Reference
9-75
Table 9-10
Parameter
is_group
Description
Indicates whether the job is a member of a Group Scheduling table.
Valid Values
Valid values: no (not a member of a Group Scheduling table) yes (member of a Group Scheduling table)
Example: <ctmem:is_group>yes</ctmem:is_group> ret_text Text describing the job run. String.
Example: <ctmem:ret_text>"Job was ordered"</ctmem:ret_text>
Errors
See the Table , Order/Force Request Errors (Major Code 405), on page B-18
9-76
Polling Request
Polls the response repository in the CONTROL-M/EM GUI Server to receive completion confirmation from earlier job processing requests. Polling must be initiated for confirmation of the following requests: Job Creation Order/Force Add/Delete Condition
The other requests do not require polling.
Request Format
EMAPI_poll.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:message_package (ctmem:request)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED > <!ELEMENT ctmem:request (ctmem:response_token)> <!ATTLIST ctmem:request ctmem:name CDATA #REQUIRED ctmem:user_token CDATA #REQUIRED > <!ELEMENT ctmem:response_token (#PCDATA)>
Request Reference
9-77
Parameters
Table 9-11 Polling Request XML Parameters Description
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_poll.dtd"> message_package Indicates to CONTROL-M/EM the beginning and end of the Polling XML specification. Order and force specifications are placed between the opening and closing message_package tags. Contains the xmlns:ctmem (schema) and version (1.0) attributes. Wrapper for the request element. xmlns:ctmem version (1.0) Path or URL to schema definition files. String. version (1.0)
Example <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema" ctmem:version=1.0"></ctmem:message_package> request Indicates to CONTROL-M/EM the beginning and end of the Polling answer. Contains the name and user_token attributes. Wrapper for the response_token element. name Name of the request type. Valid value: poll Serial number assigned to the user during registration. String.
user_token
Example <ctmem:request ctmem:name="poll" ctmem:user_token="1234567"> <ctmem:response_token>1234567</ctmem:response_token> </ctmem:request> response_token Tracking ID assigned by the API. String. Example: <ctmem:response_token>1234567</ctmem:response_token>
9-78
Example
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_poll.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema/" ctmem:version (1.0)> <ctmem:request ctmem:name="poll" ctmem:user_token="$USER_TOKEN$"> <ctmem:response_token>$RESPONSE_TOKEN$</ctmem:response _token> </ctmem:request> </ctmem:message_package>
Response
EMAPI_pollResponse.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:error_message (#PCDATA)> <!ELEMENT ctmem:error (ctmem:error_message)> <!ATTLIST ctmem:error ctmem:major CDATA #REQUIRED ctmem:minor CDATA #REQUIRED ctmem:severity CDATA #REQUIRED> <!ELEMENT ctmem:error_list (ctmem:error+)> <!ATTLIST ctmem:error_list ctmem:highest_severity CDATA #REQUIRED> <!ELEMENT ctmem:status (#PCDATA)> <!ELEMENT ctmem:response (ctmem:status, ctmem:error_list?)> <!ATTLIST ctmem:response ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:message_package (ctmem:response)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED>
Request Reference
9-79
Parameters
Table 9-12 Poll Response XML Parameters Description (Part 1 of 2)
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_pollResponse.dtd"> message_package Identifies the beginning and end of the response data package. Contains the xmlns:ctmem and version attributes. Is a wrapper for the response element. xmlns:ctmem=URL version (1.0) Location of the schema. version (1.0)
Example <ctmem:message_package xmlns:ctmem=http://www.bmc.com/ctmem/schema ctmem:version=1.0> </ctmem:message_package> response Type of response contained documented in the XML file. Contains the request_name attribute. Is a wrapper for the status and error-list elements. request_name Request type for which the response was generated. Valid values: poll
Example <ctmem:response ctmem:name=poll> <ctmem:status>EXEC</ctmem:status> <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=403 ctmem:minor=1 ctmem:severity=Error> <ctmem:error_message>Error: Invalid token supplied. </ctmem:error_message> </ctmem:error> </ctmem:error_list> </ctmem:response> status Description of message content (for example, Error). String.
Example <ctmem:status>Error</ctmem:status>
9-80
Table 9-12
Poll Response XML Parameters Description (Part 2 of 2)
Parameter
error-list
Description
Valid Values
minor
severity
Request Reference
9-81
Errors
See Poll Request Errors (Major Code 403) on page B-16.
9-82
Timeout Reset Request

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 users registration valid during lengthy sessions. For more information on the timeout element and the timeout counter, see User Registration Request on page 9-98.
Request Format
EMAPI_client_keep_alive.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:message_package (ctmem:request)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED > <!ELEMENT ctmem:request EMPTY> <!ATTLIST ctmem:request ctmem:name CDATA #REQUIRED ctmem:user_token CDATA #REQUIRED >
Request Reference
9-83
Parameters
Table 9-13 Timeout Reset Request XML Parameters Description
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_client_keep_alive.dtd"> message_package Indicates to CONTROL-M/EM the beginning and end of the Timeout Reset Request XML specification. Order and force specifications are placed between the opening and closing messages_package tags. Contains the version and ctmem (schema) attributes. Wrapper for one or more request elements. xmlns:ctmem version (1.0) Schema pathname or URL and filename. String. version (1.0)
Example <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema" ctmem:version="1.0"> </ctmem:message_package> request Indicates to CONTROL-M/EM the beginning and end of the Timeout Reset request. Contains the name and user_token attributes. name Name of the API request that you are performing. Valid value: client_keep_alive Serial identification number supplied to the user during registration. The user indicated by this number is the user. String.
user_token
Example <ctmem:request ctmem:name="client_keep_alive" ctmem:user_token="1234567"> </ctmem:request>
9-84
Example Reset the timeout interval for the user identified with token 1234567
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_client_keep_alive.dtd"> <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema" ctmem:version="1.0"> <ctmem:request ctmem:name="client_keep_alive" ctmem:user_token="1234567"> </ctmem:request> </ctmem:message_package>
Response
EMAPI_client_keep_aliveResponse.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:error_message (#PCDATA)> <!ELEMENT ctmem:error (ctmem:error_message)> <!ATTLIST ctmem:error ctmem:major CDATA #REQUIRED ctmem:minor CDATA #REQUIRED ctmem:severity CDATA #REQUIRED> <!ELEMENT ctmem:error_list (ctmem:error+)> <!ATTLIST ctmem:error_list ctmem:highest_severity CDATA #REQUIRED> <!ELEMENT ctmem:status (#PCDATA)> <!ELEMENT ctmem:user_token (#PCDATA)> <!ELEMENT ctmem:response (ctmem:status, ctmem:user_token?, ctmem:error_list?)> <!ATTLIST ctmem:response ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:message_package (ctmem:response)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED>
Request Reference
9-85
Parameters
Table 9-14 Timeout Reset Response XML Parameters Description (Part 1 of 3)
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_client_keep_aliveResponse.dtd"> message_package Identifies the beginning and end of the response data package. Contains the xmlns:ctmem and version attributes. Is a wrapper for the response element. xmlns:ctmem=URL version (1.0) Location of the schema. version (1.0)
Example <ctmem:message_package xmlns:ctmem=http://www.bmc.com/ctmem/schema ctmem:version=1.0> </ctmem:message_package> response Type of response contained documented in the XML file. Contains the request_name attribute. Is a wrapper for the status and error-list elements. request_name Request type for which the response was generated. Valid values: client_keep_alive
Example <ctmem:response ctmem:name=client_keep_alive> <ctmem:status>Error</ctmem:status> <ctmem:user_token>123456</ctmem: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:response> status Description of message content (for example, Error). String. Contained in the response element. Example <ctmem:status>Error</ctmem:status>
9-86
Table 9-14
Timeout Reset Response XML Parameters Description (Part 2 of 3)
Parameter
user_token
Description
Valid Values
Unique ID that identifies the user. String. Contained in the response element. Example <ctmem:user_token>123456</ctmem:user_token>
error-list
minor
severity
Example <ctmem:error ctmem:major=404 ctmem:minor=2 ctmem:severity=Error> <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message> </ctmem:error>
Request Reference
9-87
Table 9-14
Timeout Reset Response XML Parameters Description (Part 3 of 3)
Parameter
error_message
Description
Valid Values
Text description of the error. For more information, see Appendix B, Error Codes and Exceptions. String. <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message>
Errors
See CONTROL-M/EM API Java Client Errors (Major Code 500) on page B-23.
9-88
Tracking Request
Tracks the progress of existing jobs in the CONTROL-M installation.
Request
EMAPI_job_track.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:job (ctmem:control_m, ctmem:order_id)> <!ELEMENT ctmem:control_m (#PCDATA)> <!ELEMENT ctmem:order_id (#PCDATA)> <!ELEMENT ctmem:message_package (ctmem:request)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED > <!ELEMENT ctmem:jobs (ctmem:job+)> <!ELEMENT ctmem:request (ctmem:jobs)> <!ATTLIST ctmem:request ctmem:name CDATA #REQUIRED ctmem:user_token CDATA #REQUIRED >
Request Reference
9-89
Parameters
Table 9-15 Tracking Request XML Parameters Description (Part 1 of 2)
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_job_track.dtd"> Example <!DOCTYPE ctmem:message package SYSTEM "EMAPI_JobTrack.dtd"> message_package Indicates to CONTROL-M/EM the beginning and end of the Timeout Reset Request XML specification. Order and force specifications are placed between the opening and closing messages_package tags. Contains the version and ctmem (schema) attributes. Wrapper for one or more request elements. xmlns:ctmem version (1.0) Schema pathname or URL and filename. String. version (1.0)
Example <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema" ctmem:version="1.0"> </ctmem:message_package> request Indicates to CONTROL-M/EM the beginning and end of the Job Tracking request. Contains the name and user_token attributes. Wrapper for the jobs wrapper. name Name of the API request that you are performing. Valid value: job_track Serial identification number supplied to the user during registration. The user indicated by this number is the user. String.
user_token
Example <ctmem:request ctmem:name="job_track" ctmem:user_token="1234567"> </ctmem:request>
9-90
Table 9-15
Tracking Request XML Parameters Description (Part 2 of 2)
Parameter
jobs
Description
Valid Values
Indicates to CONTROL-M/EM the beginning and end of the jobs wrapper that contains the specifications for the jobs to be tracked. Mandatory. Contains no attributes. Wrapper for one or more job elements. Example <ctmem:jobs> <ctmem:job> <ctmem:control-m>CTM_LA</ctmem:control-m> <ctmem:order_id>0000df</ctmem:order_id> </ctmem:job> </ctmem:jobs>
job
Element that decribes a single job to be tracked. The job is described with two parameters: the CONTROL-M installation to which it belongs and by its unique order ID. Mandatory. Contains no attributes. Wrapper for the control-m and order_id elements. Example <ctmem:job> <ctmem:control-m>CTM_LA</ctmem:control-m> <ctmem:order_id>0000df</ctmem:order_id> </ctmem:job>
control-m
CONTROL-M installation to which the job belongs. String. Mandatory. Example: <ctmem:control-m>CTM_LA</ctmem:control-m>
order_id
Order ID of the job. String. Mandatory. Example: <ctmem:order_id>0000df</ctmem:order_id>
Example
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_job_track.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema/" ctmem:version="1.0">
Request Reference
9-91
<ctmem:request ctmem:name="job_track" ctmem:user_token="345345"> <ctmem:jobs> <ctmem:job> <ctmem:control_m>mig</ctmem:control_m> <ctmem:order_id>0000f</ctmem:order_id> </ctmem:job> <ctmem:job> <ctmem:control_m>mig</ctmem:control_m> <ctmem:order_id>000de</ctmem:order_id> </ctmem:job> <ctmem:job> <ctmem:control_m>omega</ctmem:control_m> <ctmem:order_id>0000d</ctmem:order_id> </ctmem:job> </ctmem:jobs> </ctmem:request> </ctmem:message_package>
Response
EMAPI_job_trackResponse.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:status (#PCDATA)> <!ELEMENT ctmem:error_message (#PCDATA)> <!ELEMENT ctmem:error (ctmem:error_message)> <!ATTLIST ctmem:error ctmem:major CDATA #REQUIRED ctmem:minor CDATA #REQUIRED ctmem:severity CDATA #REQUIRED> <!ELEMENT ctmem:error_list (ctmem:error+)> <!ATTLIST ctmem:error_list ctmem:highest_severity CDATA #REQUIRED> <!ELEMENT ctmem:control_m (#PCDATA)> <!ELEMENT ctmem:order_id (#PCDATA)> <!ELEMENT ctmem:job_status (#PCDATA)> <!ELEMENT ctmem:state_digits (#PCDATA)> <!ELEMENT ctmem:odate (#PCDATA)>
9-92
<!ELEMENT ctmem:job_data (ctmem:control_m, ctmem:order_id, ctmem:job_status?, ctmem:state_digits?, ctmem:odate?)> <!ELEMENT ctmem:job (ctmem:status, ctmem:job_data, ctmem:error_list?)> <!ELEMENT ctmem:jobs (ctmem:job+)> <!ELEMENT ctmem:response (ctmem:status, ctmem:jobs?, ctmem:error_list?)> <!ATTLIST ctmem:response ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:message_package (ctmem:response)> <!ATTLIST ctmem:message_package ctmem:version CDATA #REQUIRED>
Table 9-16
Tracking Request Response XML Parameters Description
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_job_trackResponse.dtd"> message_package Indicates to CONTROL-M/EM the beginning and end of the Order/Force Request XML specification. Order and force specifications are placed between the opening and closing messages_package tags. Contains the xmlns:ctmem attribute and the response element. xmlns:ctmem Schema pathname or URL and filename. String.
Example <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema"> </ctmem:message_package>
Request Reference
9-93
Table 9-16
Parameter
response
Description
Valid Values
Type of response contained documented in the XML file. Contains the request_name attribute. Is a wrapper for the status, error-list, and jobs elements. request_name Request type for which the response was generated. Valid values: job_track
Example <ctmem:response ctmem:name=job_track> <ctmem:status>Error</ctmem:status> <ctmem:error_list ctmem:highest_severity=Error> <ctmem:jobs></ctmem:jobs> </ctmem:error_list> </ctmem:response> status Describes the condition of the element that contains it.(for example, Error). String. Note: status is a descriptive element in the response and job elements. Example: <ctmem:status>Error</ctmem:status> error-list Begins and ends the list of xxx errors. Contains the highest_severity attrbute. Wrapper for the one or more error elements. Note: error-list contains the errors reported for the response and jobs elements. 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.
Example <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=406 ctmem:minor=1 ctmem:severity=Error> <ctmem:error_message>Job was not found in the last AJF. </ctmem:error_message> </ctmem:error> </ctmem:error_list>
9-94
Table 9-16
Parameter
error
Description
Valid Values
minor
severity
Example <ctmem:error ctmem:major=406 ctmem:minor=1 ctmem:severity=Error> <ctmem:error_message>Job was not found in the last AJF. </ctmem:error_message> </ctmem:error> error_message Text description of the error. For more information, see Appendix B, Error Codes and Exceptions. String.
Example: <ctmem:error_message>No jobs were ordered.</ctmem:error_message> jobs Wrapper for al job specifications in the response. Wrapper for one or more job elements. Contained in the response element. Example: <ctmem:jobs></ctmem:jobs>
Request Reference
9-95
Table 9-16
Parameter
job
Description
Valid Values
Beginning and end tags that indicate a single job. Wrapper for the status, error-list, and job_data elements. Example <ctmem:job> <ctmem:status>OK</ctmem:status> <ctmem:job_data> <ctmem:control_m>CTM_NYC</ctmem:control_m> <ctmem:order_id>aa123</ctmem:order_id> <ctmem:odate>1212</ctmem:odate> <ctmem:job_status>OK</ctmem:job_status> <ctmem:state_digits>yes</ctmem:state_digits> </ctmem:job_data> </ctmem:job>
job_data
Element that contains other elements (parameters) that describe the job. Wrapper for the control_m, order_id, job_status, state_digits, and odate elements. Example <ctmem:job_data> <ctmem:control_m>CTM_NYC</ctmem:control_m> <ctmem:order_id>aa123</ctmem:order_id> <ctmem:odate>1212</ctmem:odate> <ctmem:job_status>OK</ctmem:job_status> <ctmem:state_digits>yes</ctmem:state_digits> </ctmem:job_data>
control_m
String. Example: <ctmem:control_m>CTM_NYC</ctmem:control_m>
job_status
Name of the job. String. Example: <ctmem:job_status>OK</ctmem:job_status>
odate
Original Scheduling date of the job. String. Example: <ctmem:odate>1212</ctmem:odate>
order_id
Serial number assigned to the job by the CONTROL-M installation. String. Example: <ctmem:order_id>56643</ctmem:order_id>
state_digits Example <ctmem:state_digits>yes</ctmem:state_digits>
9-96
Errors
See Tracking Request Errors (Major Code 406) on page B-19.
Request Reference
9-97
User Registration Request

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 Format
EMAPI_register.dtd <?xml version="1.0" encoding="UTF-8"?>  <!ELEMENT ctmem:message_package (ctmem:request)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED > <!ELEMENT ctmem:request (ctmem:user_name, ctmem:password, ctmem:timeout?)> <!ATTLIST ctmem:request ctmem:name CDATA #REQUIRED > <!ELEMENT ctmem:user_name (#PCDATA)> <!ELEMENT ctmem:password (#PCDATA)> <!ELEMENT ctmem:timeout (#PCDATA)>
9-98
Parameters
Table 9-17 Registration Request XML Parameters Description
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_register.dtd"> message_package Indicates to CONTROL-M/EM the beginning and end of the Timeout Reset Request XML specification. Order and force specifications are placed between the opening and closing messages_package tags. Contains the version and ctmem (schema) attributes. Wrapper for one or more request elements. xmlns:ctmem version (1.0) Schema pathname or URL and filename. String. version (1.0)
Example <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema" ctmem:version="1.0"> </ctmem:message_package> request Indicates to CONTROL-M/EM the beginning and end of the Job Tracking request. Contains the name and user_token attributes. Wrapper for the user_name, password, and timeout elements. name Name of the API request that you are performing. Valid value: register Serial identification number supplied to the user during registration. The user indicated by this number is the user. String.
user_token
Example <ctmem:request ctmem:name="register" ctmem:user_token="1234567"> </ctmem:request>
Request Reference
9-99
Table 9-17
Registration Request XML Parameters Description
Parameter
user_name
Description
CONTROL-M/EM username of the person making the request. Example ctmem:user_name="emuser"
Valid Values
String.
password
CONTROL-M/EM user password of the person making the request. Note: This password must be sent as an encrypted string. Therefore, you must use the encodePassword method to encrypt the password prior making the User Registration request. For more information, see encodePassword on page 8-11. Example ctmem:password="empass"
String.
timeout
Indicates a length of time, in seconds, until the users current user token is automatically invalidated. Integer. Default: 720. Optional. Note: Use the Timeout Reset Request to restart the count from 0. For more information, see Timeout Reset Request on page 9-83. Example ctmem:timeout="3600"
Example
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_register.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:request ctmem:name="register" > <ctmem:user_name>ecsuser</ctmem:user_name> <ctmem:password>ecspass</ctmem:password> <ctmem:timeout>300</ctmem:timeout> </ctmem:request> </ctmem:message_package>
9-100
Response
EMAPI_registerResponse.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:error_message (#PCDATA)> <!ELEMENT ctmem:error (ctmem:error_message)> <!ATTLIST ctmem:error ctmem:major CDATA #REQUIRED ctmem:minor CDATA #REQUIRED ctmem:severity CDATA #REQUIRED> <!ELEMENT ctmem:error_list (ctmem:error+)> <!ATTLIST ctmem:error_list ctmem:highest_severity CDATA #REQUIRED> <!ELEMENT ctmem:status (#PCDATA)> <!ELEMENT ctmem:user_token (#PCDATA)> <!ELEMENT ctmem:response (ctmem:status, ctmem:user_token?, ctmem:error_list?)> <!ATTLIST ctmem:response ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:message_package (ctmem:response)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED>
Parameters
Table 9-18 User registration Response XML Parameters Description (Part 1 of 3)
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_registerResponse.dtd">
Request Reference
9-101
Table 9-18
User registration Response XML Parameters Description (Part 2 of 3)
Parameter
message_package
Description
Valid Values
Identifies the beginning and end of the response data package. Contains the xmlns:ctmem and version attributes. Is a wrapper for the response element. xmlns:ctmem=URL version (1.0) Location of the schema. version (1.0)
Example <ctmem:message_package xmlns:ctmem=http://www.bmc.com/ctmem/schema ctmem:version=1.0> </ctmem:message_package> response Type of response contained documented in the XML file. Contains the request_name attribute. Is a wrapper for the status and error-list elements. request_name Request type for which the response was generated. Valid values: register
Example <ctmem:response ctmem:name=register> <ctmem:status>Error</ctmem:status> <ctmem:user_token>123456</ctmem:user_token> <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:response> status Description of message content (for example, Error). String. Contained in the response element. Example <ctmem:status>Error</ctmem:status> user_token Unique ID that identifies the user. String. Contained in the response element. Example: <ctmem:user_token>123456</ctmem:user_token>
9-102
Table 9-18
User registration Response XML Parameters Description (Part 3 of 3)
Parameter
error-list
Description
Valid Values
Example <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> error Describes the error. Contains the major, minor, and severity attributes. Wrapper for the error_message element. major The error Major Code. An integer describing the family of errors to which the error belongs. For more information, see Appendix B, Error Codes and Exceptions. The error minor Code. An integer that is a unique ID for an error of this type. For more information, see Appendix B, Error Codes and Exceptions. The priority level assigned to the error by the CONTROL-M/EM API. String. For more information, see Appendix B, Error Codes and Exceptions.
minor
severity
Example <ctmem:error ctmem:major=407 ctmem:minor=3 ctmem:severity=Error> <ctmem:error_message>Register failed.</ctmem:error_message> </ctmem:error> error_message Text description of the error. For more information, see Appendix B, Error Codes and Exceptions. String. Example: <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message>
Request Reference
9-103
Errors
See Authorization Request Errors (Major Code 407) on page B-20.
9-104
User Unregistration Request

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 Format
EMAPI_unregister.dtd <?xml version="1.0" encoding="UTF-8"?>  <!ELEMENT ctmem:message_package (ctmem:request)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED > <!ELEMENT ctmem:request EMPTY> <!ATTLIST ctmem:request ctmem:name CDATA #REQUIRED ctmem:user_token CDATA #REQUIRED >
Parameters
Table 9-19 Unregistration Request XML Parameters Description
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_unregister.dtd">
Request Reference
9-105
Table 9-19
Unregistration Request XML Parameters Description
Parameter
<?xml ?>
Description
Valid Values
This is the first line of the XML file. It contains the version and encoding attributes. version The version of XML in use. In ENTERPRISE/CS version 6.0.01 and later, this is version 1.0. Valid value: 1.0. The character set used in the XML file. Valid value: UTF-8
encoding
Example: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE requesttype SYSTEM "dtdfilename"> This is the second line of the XML file. It identifies the file and specifies the .dtd file that is used for validation. The file contains two variables, requesttype and dtdfilename. It also includes the words !DOCTYPE and SYSTEM, which must be written in upper-case letters. requesttype Type of function that the current XML file performs. Valid value: ctmem:message_
package
dtdfilename The name of the .dtd file used to validate the XML file. Valid value: EMAPI_unregister.dtd Note: You can include the path to the .dtd file to enable your XML editor (if used) to validate the document as it is being written.
Example: <!DOCTYPE ctmem:message package SYSTEM "EMAPI_unregister.dtd">
9-106
Table 9-19
Unregistration Request XML Parameters Description
Parameter
message_package
Description
Valid Values
Indicates to CONTROL-M/EM the beginning and end of the Timeout Reset Request XML specification. Order and force specifications are placed between the opening and closing messages_package tags. Contains the version and ctmem (schema) attributes. Wrapper for one or more request elements. xmlns:ctmem version (1.0) Schema pathname or URL and filename. String. version (1.0)
Example <ctmem:message_package xmlns:ctmem="C:Project/ctmem/schema" ctmem:version="1.0"> </ctmem:message_package> request Indicates to CONTROL-M/EM the beginning and end of the Unregister request. Contains the name and user_token attributes. name Name of the API request that you are performing. Valid value: unregister Serial identification number supplied to the user during registration. The user indicated by this number is the user. String.
user_token
Example <ctmem:request ctmem:name="unregister" ctmem:user_token="1234567"> </ctmem:request>
Example
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_unregister.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0">
Request Reference
9-107
<ctmem:request ctmem:name="unregister" ctmem:user_token="1234567"></ctmem:request> </ctmem:message_package>
Response
EMAPI_unregisterResponse.dtd <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT ctmem:error_message (#PCDATA)> <!ELEMENT ctmem:error (ctmem:error_message)> <!ATTLIST ctmem:error ctmem:major CDATA #REQUIRED ctmem:minor CDATA #REQUIRED ctmem:severity CDATA #REQUIRED> <!ELEMENT ctmem:error_list (ctmem:error+)> <!ATTLIST ctmem:error_list ctmem:highest_severity CDATA #REQUIRED> <!ELEMENT ctmem:status (#PCDATA)> <!ELEMENT ctmem:user_token (#PCDATA)> <!ELEMENT ctmem:response (ctmem:status, ctmem:user_token?, ctmem:error_list?)> <!ATTLIST ctmem:response ctmem:request_name CDATA #REQUIRED> <!ELEMENT ctmem:message_package (ctmem:response)> <!ATTLIST ctmem:message_package xmlns:ctmem CDATA #IMPLIED ctmem:version (1.0) #REQUIRED>
9-108
Parameters
Table 9-20 User Unregistration Response XML Parameters Description (Part 1 of 3)
Parameter
Description
Valid Values
The first two lines of the XML request file for this API request contain information that specifies to the CONTROL-M/EM API the version of XML and the text encoding format being used, and the name of the .dtd file. These lines must appear exactly as follows: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message package SYSTEM "EMAPI_registerResponse.dtd"> message_package Identifies the beginning and end of the response data package. Contains the xmlns:ctmem and version attributes. Is a wrapper for the response element. xmlns:ctmem=URL version (1.0) Location of the schema. version (1.0)
Example <ctmem:message_package xmlns:ctmem=http://www.bmc.com/ctmem/schema ctmem:version=1.0> </ctmem:message_package> response Type of response contained documented in the XML file. Contains the request_name attribute. Is a wrapper for the status and error-list elements. request_name Request type for which the response was generated. Valid values: unregister
Example <ctmem:response ctmem:name=register> <ctmem:status>Error</ctmem:status> <ctmem:user_token>123456</ctmem:user_token> <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=407 ctmem:minor=4 ctmem:severity=Error> <ctmem:error_message>Unregister failed.</ctmem:error_message> </ctmem:error> </ctmem:error_list> </ctmem:response> status Description of message content (for example, Error). String. Contained in the response element. Example: <ctmem:status>Error</ctmem:status>
Request Reference
9-109
Table 9-20
User Unregistration Response XML Parameters Description (Part 2 of 3)
Parameter
user_token
Description
Valid Values
Unique ID that identifies the user. String. Contained in the response element. Example <ctmem:user_token>123456</ctmem:user_token>
error-list
Example <ctmem:error_list ctmem:highest_severity=Error> <ctmem:error ctmem:major=407 ctmem:minor=4 ctmem:severity=Error> <ctmem:error_message>Unregister failed.</ctmem:error_message> </ctmem:error> </ctmem:error_list> error Describes the error. Contains the major, minor, and severity attributes. Wrapper for the error_message element. major The error Major Code. An integer describing the family of errors to which the error belongs. For more information, see Appendix B, Error Codes and Exceptions. The error minor Code. An integer that is a unique ID for an error of this type. For more information, see Appendix B, Error Codes and Exceptions. The priority level assigned to the error by the CONTROL-M/EM API. String. For more information, see Appendix B, Error Codes and Exceptions.
minor
severity
Example <ctmem:error ctmem:major=407 ctmem:minor=4 ctmem:severity=Error> <ctmem:error_message>Unregister failed.</ctmem:error_message> </ctmem:error>
9-110
Table 9-20
User Unregistration Response XML Parameters Description (Part 3 of 3)
Parameter
error_message
Description
Valid Values
Text description of the error. For more information, see Appendix B, Error Codes and Exceptions. String. Example: <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message>
Errors
See Authorization Request Errors (Major Code 407) on page B-20.
Request Reference
9-111
9-112
Request Format Examples
Requests are submitted to the CONTROL-M/EM API as XML-formatted text strings. The text strings can be saved as plain-text files.
This chapter includes one or more examples for each of the more complex requests: Add Condition/Delete Condition Request Job Creation Request Order/Force Request
For instructions for how to create request strings and examples of the less complex requests, see Chapter 9, Request Reference.
A-1
Add Condition/Delete Condition Request

Example 1: Add a Condition to a CONTROL-M
An Add Condition request that adds global condition Cond01 to the CTM01 CONTROL-M installation.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_add_delete_condition.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:request ctmem:name="add_condition" ctmem:user_token="575668226"> <ctmem:control_m>CTM01</ctmem:control_m> <ctmem:condition> <ctmem:name>Cond01</ctmem:name> <ctmem:odate>ODATE</ctmem:odate> </ctmem:condition> </ctmem:request> </ctmem:message_package>
Example 2: Delete a Condition from a CONTROL-M

A Delete Condition request that removes the Cond01 global condition from the CTM01 CONTROL-M installation.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_add_delete_condition.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:request ctmem:name="delete_condition" ctmem:user_token="575668226"> <ctmem:control_m>CTM01</ctmem:control_m> <ctmem:condition> <ctmem:name>Cond02</ctmem:name> <ctmem:odate>ODATE</ctmem:odate> </ctmem:condition> </ctmem:request> </ctmem:message_package>
A-2
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.
<?xml version="1.0"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_create_aj.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema/" ctmem:version="1.0"> <ctmem:request ctmem:name="create_aj" ctmem:user_token="$USER_TOKEN$"> <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:task_type>command</ctmem:task_type> <ctmem:application>Confirm</ctmem:application> <ctmem:group>Confirm</ctmem:group> <ctmem:confirm_flag>yes</ctmem:confirm_flag> <ctmem:max_wait>0</ctmem:max_wait> <ctmem:prevent_nct2>no</ctmem:prevent_nct2> <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: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:command>ls -l</ctmem:command> </ctmem:active_job> </ctmem:request> </ctmem:message_package>
A-3
Example 2: Create a Cyclic Job

A Job Creation request that creates a single cyclic job that performs a command.
<?xml version="1.0"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_create_aj.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema/" ctmem:version="1.0"> <ctmem:request ctmem:name="create_aj" ctmem:user_token="$USER_TOKEN$"> <ctmem:control_m>ctm3-omega</ctmem:control_m> <ctmem:active_job> <ctmem:job_name>Cyc0</ctmem:job_name> <ctmem:mem_name>Cyc0</ctmem:mem_name> <ctmem:task_type>command</ctmem:task_type> <ctmem:application>Cyclic</ctmem:application> <ctmem:group>Cyclic</ctmem:group> <ctmem:confirm_flag>no</ctmem:confirm_flag> <ctmem:max_wait>0</ctmem:max_wait> <ctmem:prevent_nct2>no</ctmem:prevent_nct2> <ctmem:time_from>1100</ctmem:time_from> <ctmem:time_until>2300</ctmem:time_until> <ctmem:rerun_interval>00060M</ctmem:rerun_interval> <ctmem:critical>no</ctmem:critical> <ctmem:cyclic>yes</ctmem:cyclic> <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:command>ls -l</ctmem:command> </ctmem:active_job> </ctmem:request> </ctmem:message_package>
A-4
Example 3: Create a Job Including In and Out Conditions

A Job Creation request that creates a single job including In and Out conditions.
<?xml version="1.0"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_create_aj.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema/" ctmem:version="1.0"> <ctmem:request ctmem:name="create_aj" ctmem:user_token="$USER_TOKEN$"> <ctmem:control_m>ctm3-omega</ctmem:control_m> <ctmem:active_job> <ctmem:job_name>InCond0</ctmem:job_name> <ctmem:mem_name>InCond0</ctmem:mem_name> <ctmem:task_type>command</ctmem:task_type> <ctmem:application>InCond</ctmem:application> <ctmem:group>InCond</ctmem:group> <ctmem:confirm_flag>no</ctmem:confirm_flag> <ctmem:max_wait>0</ctmem:max_wait> <ctmem:prevent_nct2>no</ctmem:prevent_nct2> <ctmem:time_from>0800</ctmem:time_from> <ctmem:critical>no</ctmem:critical> <ctmem:cyclic>no</ctmem:cyclic> <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:command>ls -l</ctmem:command> <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> </ctmem:request> </ctmem:message_package>
A-5
Example 4: Create a Job that Requires Resources

A Job Creation request that creates a single job requiring Control and Quantitative resources.
<?xml version="1.0"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_create_aj.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema/" ctmem:version="1.0"> <ctmem:request ctmem:name="create_aj" ctmem:user_token="$USER_TOKEN$"> <ctmem:control_m>ctm3-omega</ctmem:control_m> <ctmem:active_job> <ctmem:job_name>Rsc0</ctmem:job_name> <ctmem:mem_name>Rsc0</ctmem:mem_name> <ctmem:task_type>dummy</ctmem:task_type> <ctmem:application>Resource</ctmem:application> <ctmem:group>Resource</ctmem:group> <ctmem:confirm_flag>no</ctmem:confirm_flag> <ctmem:max_wait>0</ctmem:max_wait> <ctmem:description>Job requiring resources.</ctmem:description> <ctmem:cyclic>no</ctmem:cyclic> <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: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:control_resource> <ctmem:resource>Time</ctmem:resource> <ctmem:type>shared</ctmem:type> </ctmem:control_resource> <ctmem:control_resource> <ctmem:resource>JJ4</ctmem:resource> <ctmem:type>shared</ctmem:type> </ctmem:control_resource> <ctmem:control_resource> <ctmem:resource>DE1a34</ctmem:resource> <ctmem:type>exclusive</ctmem:type> </ctmem:control_resource> <ctmem:control_resource> <ctmem:resource>CPU</ctmem:resource> <ctmem:type>shared</ctmem:type> </ctmem:control_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> </ctmem:request> </ctmem:message_package>
A-6
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 an AutoEdit variable.
<?xml version="1.0"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_create_aj.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema/" ctmem:version="1.0"> <ctmem:request ctmem:name="create_aj" ctmem:user_token="$USER_TOKEN$"> <ctmem:control_m>ctm3-omega</ctmem:control_m> <ctmem:active_job> <ctmem:job_name>DoSys0</ctmem:job_name> <ctmem:mem_name>DoSys0</ctmem:mem_name> <ctmem:task_type>command</ctmem:task_type> <ctmem:application>OnDo</ctmem:application> <ctmem:group>DoSys</ctmem:group> <ctmem:confirm_flag>no</ctmem:confirm_flag> <ctmem:max_wait>0</ctmem:max_wait> <ctmem:description>Job with On-Do statements.</ctmem:description> <ctmem:time_from>0900</ctmem:time_from> <ctmem:time_until>1100</ctmem:time_until> <ctmem:priority>Ab</ctmem:priority> <ctmem:critical>no</ctmem:critical> <ctmem:cyclic>no</ctmem:cyclic> <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:count_cyclic_from>end</ctmem:count_cyclic_from> <ctmem:command>ls -l</ctmem:command> <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> </ctmem:do_sysout> </ctmem:do_statements> </ctmem:on_do_statement> </ctmem:on_do_statements> </ctmem:active_job> </ctmem:request> </ctmem:message_package>
A-7
Example 6: Create a Job that Includes On-Do Statements

A Job Creation request that creates a single job including multiple On-Do statements.
<?xml version="1.0"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_create_aj.dtd"> <ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema/" ctmem:version="1.0"> <ctmem:request ctmem:name="create_aj" ctmem:user_token="$USER_TOKEN$"> <ctmem:control_m>ctm3-omega</ctmem:control_m> <ctmem:active_job> <ctmem:job_name>DoVAr0</ctmem:job_name> <ctmem:mem_name>DoVAr0</ctmem:mem_name> <ctmem:task_type>command</ctmem:task_type> <ctmem:application>OnDo</ctmem:application> <ctmem:group>DoSetVar</ctmem:group> <ctmem:confirm_flag>no</ctmem:confirm_flag> <ctmem:max_wait>0</ctmem:max_wait> <ctmem:description>Multiple On-Dos</ctmem:description> <ctmem:priority>Ab</ctmem:priority> <ctmem:critical>no</ctmem:critical> <ctmem:cyclic>no</ctmem:cyclic> <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:over_lib>JOBDOC</ctmem:over_lib> <ctmem:count_cyclic_from>end</ctmem:count_cyclic_from> <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:value>1234567890</ctmem:value> </ctmem:do_autoedit> </ctmem:do_statements> </ctmem:on_do_statement> </ctmem:on_do_statements> </ctmem:active_job> </ctmem:request> </ctmem:message_package>
A-8
Order/Force Request
Example 1: Order a Unix Job
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_order_force.dtd"><ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:request ctmem:name="order_force" ctmem:user_token="@UserToken@"> <ctmem:force_it>no</ctmem:force_it> <ctmem:control_m>UnixDc</ctmem:control_m><ctmem:job_id>2</ctmem:job_id> <ctmem:job_name>OrdSimJobU</ctmem:job_name> <ctmem:table_name>OrdSimJobU</ctmem:table_name> <ctmem:odate>20020522</ctmem:odate> </ctmem:request></ctmem:message_package>
Example 2: Force a Unix Job

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_order_force.dtd"><ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:request ctmem:name="order_force" ctmem:user_token="@UserToken@"> <ctmem:force_it>yes</ctmem:force_it> <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> <ctmem:odate>20010522</ctmem:odate> </ctmem:request></ctmem:message_package>
A-9
Example 3: Force a Unix Job into a Recent Group Scheduling Table

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_order_force.dtd"><ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:request ctmem:name="order_force" ctmem:user_token="@UserToken@"> <ctmem:force_it>yes</ctmem:force_it> <ctmem:control_m>UnixDc</ctmem:control_m> <ctmem:job_id>2</ctmem:job_id> <ctmem:job_name>FoInRecent</ctmem:job_name> <ctmem:table_name>FoInSGJobU</ctmem:table_name> <ctmem:odate>20010522</ctmem:odate> <ctmem:autoedit_assignments> <ctmem:autoedit_assignment> <ctmem:name>Recent</ctmem:name> <ctmem:value>1</ctmem:value> </ctmem:autoedit_assignment> <ctmem:autoedit_assignment> <ctmem:name>A</ctmem:name> <ctmem:value>1</ctmem:value> </ctmem:autoedit_assignment> <ctmem:autoedit_assignment> <ctmem:name>A</ctmem:name> <ctmem:value>2</ctmem:value> </ctmem:autoedit_assignment> </ctmem:autoedit_assignments><ctmem:scheduling_group_info> <ctmem:into_group>recent</ctmem:into_group> <ctmem:allow_dup>no</ctmem:allow_dup> </ctmem:scheduling_group_info> </ctmem:request></ctmem:message_package>
A-10
Example 4: Force a Unix Job into a Recent Group Scheduling Table while Allowing for Duplication
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_order_force.dtd"><ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:request ctmem:name="order_force" ctmem:user_token="@UserToken@"> <ctmem:force_it>yes</ctmem:force_it> <ctmem:control_m>UnixDc</ctmem:control_m> <ctmem:job_id>6</ctmem:job_id> <ctmem:job_name>FoInRecDup</ctmem:job_name> <ctmem:table_name>FoInSGJobU</ctmem:table_name> <ctmem:odate>20010522</ctmem:odate> <ctmem:autoedit_assignments> <ctmem:autoedit_assignment> <ctmem:name>RecentDup</ctmem:name> <ctmem:value>2</ctmem:value> </ctmem:autoedit_assignment> <ctmem:autoedit_assignment> <ctmem:name>A</ctmem:name> <ctmem:value>2</ctmem:value> </ctmem:autoedit_assignment> <ctmem:autoedit_assignment><ctmem:name>B</ctmem:name> <ctmem:value>3</ctmem:value> </ctmem:autoedit_assignment> </ctmem:autoedit_assignments> <ctmem:scheduling_group_info> <ctmem:into_group>recent</ctmem:into_group> <ctmem:allow_dup>yes</ctmem:allow_dup> </ctmem:scheduling_group_info> </ctmem:request> </ctmem:message_package>
A-11
Example 5: Force a Scheduling Table that Contains a Group Scheduling Table

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ctmem:message_package SYSTEM "EMAPI_order_force.dtd"><ctmem:message_package xmlns:ctmem="http://www.bmc.com/ctmem/schema" ctmem:version="1.0"> <ctmem:request ctmem:name="order_force" ctmem:user_token="@UserToken@"> <ctmem:force_it>yes</ctmem:force_it> <ctmem:control_m>UnixDc</ctmem:control_m> <ctmem:table_name>ForSGTblU</ctmem:table_name> <ctmem:odate>20010522</ctmem:odate> <ctmem:autoedit_assignments> <ctmem:autoedit_assignment> <ctmem:name>ForceUnixTblWithGST</ctmem:name> <ctmem:value>8</ctmem:value> </ctmem:autoedit_assignment> <ctmem:autoedit_assignment> <ctmem:name>A</ctmem:name> <ctmem:value>8</ctmem:value> </ctmem:autoedit_assignment> <ctmem:autoedit_assignment><ctmem:name>H</ctmem:name> <ctmem:value>9</ctmem:value> </ctmem:autoedit_assignment> </ctmem:autoedit_assignments> </ctmem:request> </ctmem:message_package>
A-12
Errors and exceptions may occur when the CONTROL-M/Enterprise Manager API is being used. Errors and exceptions can be divided into four broad 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 erroneous data in the XML request file. Errors and exceptions that are caused by CONTROL-M/EM or the CONTROL-M installation.
Note
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 your CONTROL-M/EM installation. Each error is composed of the following information: Major Code Integer that represents a family of related errors or exceptions.
B-1
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.
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 7-1. The severity levels that are supported by the CONTROL-M/EM API are listed in Table B-1.
Table B-1 Log Message Priority Levels (Part 1 of 2)
Level
FATAL
Description
Displays fatal error messages. Warning: 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 the CONTROL-M/EM API despite receiving a FATAL error, stop and restart the CONTROL-M/EM GUI Server and Global Alerts Server before performiong any more API actions. Displays messages for fatal and non-fatal errors. Displays warning messages and all error messages.
ERROR WARN
B-2
Table B-1
Log Message Priority Levels (Part 2 of 2)
Level
INFO DEBUG
Description
Displays system information, warnings, and all errors. Displays debugging information and all other priority messages.
B-3
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. Table B-2 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.
409
Table B-2
Error and Exception Major Codes (Part 1 of 2)
Code
000 100 200 300 300 301 302 400 401 403 404 405
Title
NULL Exception Low-level API Exceptions Parser Exceptions CONTROL-M Server Errors CONTROL-M Server Errors: Group1 CONTROL-M Server Errors: Group 2 CONTROL-M Server Errors: Group 3
For Error Descriptions, see

NULL Exception Errors (Major Code 000) on page B-6 Low-level API Exceptions (Major Code 100) on page B-7 Parser Exceptions (Major Code 200) on page B-8 Note: Category contains no individual errors. CONTROL-M/Server Errors: Group 1 (Major Code 300) on page B-9 CONTROL-M/Server Errors: Group 2 (Major Code 301) on page B-12 CONTROL-M/Server Errors: Group 3 (Major Code 302) on page B-14 Note: Category contains no individual errors. Generic Request Exceptions (Major Code 401) on page B-15 Poll Request Errors (Major Code 403) on page B-16 Add/Delete Condition Request Errors (Major Code 404) on page B-17 Order/Force Request Errors (Major Code 405) on page B-18
CONTROL-M/EM API
Request Exceptions Generic Request Exceptions Poll Request Add/Delete Condition Request Order/Force Request
B-4
Table B-2
Error and Exception Major Codes (Part 2 of 2)
Code
406 407 408 409 500 600
Title
Job Tracking Request Authorization Request Alerts Request Create Active Job Request
For Error Descriptions, see

Tracking Request Errors (Major Code 406) on page B-19 Authorization Request Errors (Major Code 407) on page B-20 Alerts Request Errors (Major Code 408) on page B-21 Create Active Job Request Errors (Major Code 409) on page B-22 CONTROL-M/EM API Java Client Errors (Major Code 500) on page B-23 Gateway Messages (Major Code 600) on page B-24
CONTROL-M/EM API
Java Client Gateway Messages
B-5
NULL Exception Errors (Major Code 000) Summary:

Table B-3
CONTROL-M/EM API has generated an undefined error.
NULL Exceptions
Minor Code
0
Severity
ERROR
Description
CONTROL-M/EM API has generated an undefined error.
B-6
Low-level API Exceptions (Major Code 100) Summary:

Errors generated due to a CONTROL-M/EM API initialization or request initialization failure.
Table B-4
Low Level API Exceptions
Minor Code
1 2 3 4 5 6
Severity
ERROR FATAL ERROR ERROR FATAL ERROR
Description
Error on preliminary parsing of the XML Catastrophic exception on server. Error: <value> Tag missing. Invalid Request. Request name: <value> Could not obtain response from repository. Undefined exception on server.
B-7
Parser Exceptions (Major Code 200) Summary:

Table B-5
Error occured when parsing an XML file.
Parser Exceptions
Minor Code
1 2 3 4
Severity
FATAL ERROR FATAL FATAL
Description
Parser Initialization Failure. Error while parsing XML: <value> Internal Parser Error: <value> Internal Parser Error: Undefined Exception
B-8
CONTROL-M/Server Errors: Group 1 (Major Code 300) Summary:

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

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

Table B-8
CONTROL-M Server Errors: Group 3
Minor Code
129 540 863
Severity
ERROR ERROR WARN
Description
User exit not loaded. Security exit not loaded. Security checking will be bypassed. The AJF is nearly full.
B-14
Generic Request Exceptions (Major Code 401) Summary:

Errors generated when CONTROL-M/EM cannot communicate with the CONTROL-M installation.
Table B-9
Generic Request Exceptions
Minor Code
1 2 3 4
Severity
ERROR ERROR ERROR ERROR
Description
Could not connect to Control-M. Invalid Control-M. Invalid response from Control-M. Internal Error: <value> .
B-15
Poll Request Errors (Major Code 403) Summary:

Table B-10
Errors generated when a Polling request fails.
Poll Request Errors
Minor Code
1
Severity
ERROR
Description
Error: Invalid token supplied.
B-16
Add/Delete Condition Request Errors (Major Code 404) Summary:

Errors generated when an Add Condition or Delete Condition request fails.
Table B-11
Add/Delete Condition Request
Minor Code
1 2 3 4 5 6 7 8 9 10 11 12 13
Severity
ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR
Description
Add/Delete condition failed (code %d). Add/Delete condition failed. Add/Delete condition aborted. Add/Delete condition timed out. Add condition failed. Add condition failed (code %d). Add condition failed, invalid option. Delete condition failed. Delete condition failed (code %d). Delete condition failed, invalid option. Conditions name is not valid. Conditions order date is not valid. Cannot Add/Delete condition, already in desired state.
B-17
Order/Force Request Errors (Major Code 405) Summary:

Table B-12
Errors generated when an Order request or Force request fails.
Order/Force Request Errors
Minor Code
1 2 3 4
Severity
ERROR ERROR ERROR ERROR
Description
Order request didnt pass validity checks. Error: <value> Group RBA not found for Group ID <value> . Order request failed in the server. No jobs were ordered.
B-18
Tracking Request Errors (Major Code 406) Summary:

Table B-13
Errors generated when a Tracking request fails.
Job Tracking Request Errors
Minor Code
1 2 3
Severity
ERROR ERROR ERROR
Description
Job was not found in the last AJF. Required Job information doesnt exist in the database Tracked Job failed in validity checks.
B-19
Authorization Request Errors (Major Code 407) Summary:

Table B-14
Errors generated when a registration or unregistration request fails.
Authorization Request Errors
Minor Code
1 2 3 4 5
Severity
ERROR ERROR ERROR ERROR ERROR
Description
Invalid user token. Invalid user name. Register failed. Unregister failed. User not authorized.
B-20
Alerts Request Errors (Major Code 408) Summary:

Table B-15
Errors generated when a Change Alert Status request fails.
Alerts Request Errors
Minor Code
1 2
Severity
ERROR ERROR
Description
Alert id is not valid. Invalid alert operation.
B-21
Create Active Job Request Errors (Major Code 409) Summary:

Table B-16
Errors generated when a Job Creation request fails.
Create Active Job Request Errors
Minor Code
1 2 3 4 5 6 7 8 9
Severity
ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR
Description
Create active job failed (code: %d). Create active job failed. Create active job failed, object is in use. Create active job failed, object not found. Create active job failed, invalid option. Create active job validation error: <value> . Scheduling group is not valid for this data-center version Failed to initialize job descriptor Create active job, invalid order date.
B-22
CONTROL-M/EM API Java Client Errors (Major Code 500) Summary:

Table B-17
Errors generated by the Java API.
CONTROL-M/EM API Java Client Errors
Minor Code
1 2 3 4 5 6 7 8 9 10 101 102 111 112 131 132 133 140 141
Severity
ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR
Description
Fatal error. Null XML document - nothing to do. Failed to establish connection with server - no server registered under this hostname. Failed to resolve server name - please check your hostname. Failed to establish connection with server - not a valid component type, check your hostname. failed resolving XMLInvoker interface. Failed to establish connection with server - check your connection with the locator. Failed to establish connection with - check your orbix configuration. Properties file not found. Failed to read properties file. Invoke timeout - no response after. Invoke request exited because a InterruptedException occurred. Response format is not valid. Response format is not valid. Cannot find tag. XML format is not valid. Request format is not valid. Cant find user token.
Undefined Exception on Parser.
B-23
Gateway Messages (Major Code 600) Summary:

Table B-18
Errors generated by the gateway.
Gateway Messages (Part 1 of 9)
Minor Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
Severity
ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR
Description
User Request timed out No network currently loaded No nodes match the Show Net parameters Net too large to be fully viewed. Some nodes will be missing Database login failed three times At least one state must be chosen At least one status must be chosen At least one task type must be chosen No events found for current net Field <value> Wrong Format: <value> Cannot load Active Network: No data center Field <value> is required Net Load aborted, probably not enough memory No nodes match the Load Net Parameters Error while reading job-record from database Nothing changed since last save Nothing changed Cannot save file <value> Confirm <value> for <value> Do you really want to quit <value> ? In a critical job, parameter Priority must begin with Field <value> contains an invalid value Field <value> must be between %d and %d Field Rerun Mem Cannot be used if field Task Type is Cyclic
B-24
Table B-18
Minor Code
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
Severity
ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR
Description
Field <value> has an invalid value starting at position: <value> Field <value> may not contain embedded spaces Cannot clear Demo Net <value> Cannot create Demo Net <value> Cannot copy Demo Net <value> Couldnt open user view Do you really want to erase the entire <value> Net <value> Do you really want to clear the entire <value> Net <value> Cannot append, Owner of <value> is <value> Cannot open <value> Missing file <value> Unable un-mount diskette in <value> Unable to mount diskette in <value> Incorrect path <value> Files downloaded from incompatible version <value> (should be <value>) Cannot open file <value> Missing <value> line Unknown line: <value> Cannot write to file <value> File <value> exists. Ok to overwrite ? Net <value> does not exist Copy from file to file not allowed Database job update failed Database select failed for resource events Database select failed for override table, simulation stopped No current net No nodes were found No more nodes were found Go Back ?
B-25
Table B-18
Minor Code
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
Severity
ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR
Description
No more nodes were found You are not authorized to perform this action If Field <value> (Days/Week days Calendar) begins with ALL then the rest of the parameter must be blank Field Days Calender is required if field <value> contains the value: <value> Field Week Calender is required if field <value> contains the value: <value> Field Days has an invalid value starting at position: <value>; There should be a comma there Discard changes made in form ? Change of calendar type destroys existing data. Proceed ? Change of data center platform destroys existing data. Proceed ? Data center unknown, please re-enter value Reading calendar failed - database problems Calendar is already in use by user <value>, try later Calendar write failed - database problems Unknown platform. Verification of data will default to MVS. Do you want to continue? Calendar was modified. Proceed with download ?" Calendar <value> was downloaded successfully from data center <value>" Calendar <value> was deleted successfully from data center <value>" Calendar is in use by user <value>, and cannot be deleted" Confirm Calendar Delete" Confirm Calendar Upload" Forced Calendar Upload will override calendar content in data center Proceed ?" You are not authorized to access the Calendar List window Filed <value> must be specified if field <value> is File, New Dest or Change Class
B-26
Table B-18
Minor Code
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100
Severity
ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR
Description
Attempt to enter conflicting conditions Field <value> may only be used with the Change Class option Field <value> is too long Field Sign may not be + if the ODATE field value is **** or $$$$ Unknown or disabled Platform! Form will be opend as MVS! In a critical job, field Priority must begin with * Field Command Line may be specified only if Task Type is Command Field should be %d char(s) long for this Sysout option Field <value> cannot be used if Task Type is <value> Field <value> cannot specify GENREAL or USER= Fields Parm and From Class must be specified if field Option is Change Class Field Parm must be specified if field Option is New Dest or File Field Confirmation Cal cannot be used with fields PDS Name or Minimum Field Months cannot be used with fields PDS Name, Minimum or Dates Field Dates cannot be used with parameters PDS Name, Minimum, Months, Days, or Days Calendar Field Dates cannot be used with fields Week Days, Weeks Days Calender Confirmation Cal If Field PDS Name is specified then Minimum must be specified and vice versa Field Priority must begin with * or an alphanumeric character Field Priority must begin with an alphanumeric character Field <value> is required if Task Type is:<value> A job with the same name already exists in this table If Field Retro is specified then PDS Name and Minimum cannot be used The fields Days and Week Days Calendar cannot both be specified The Field <value> must contain a numeric value or 0 Fields Rerun Mem and Max Rerun cannot be used if field Task Type is Cyclic
B-27
Table B-18
Minor Code
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
Severity
ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR
Description
Field Dates must be specified in format nnnn or nnnn,nnnn,... Scheduling table is already in use by user <value>, try later Scheduling table write failed - database problems Scheduling table should be uploaded before order/force Field <value> is required If Field <value> is *??????? Then field <value> must be blank Table was modified. Proceed with download ? Table was modified. Proceed with order ? Table was modified. Proceed with force ? Definition table <value> was downloaded successfully from data center <value> Definition table <value> was deleted successfully from data center <value> Confirm Table Delete Confirm Table Upload Forced Table Upload will override table content in data center Proceed ? You are not authorized to access the Scheduling Tables window Scheduling table is in use by user <value>, and cannot be deleted Field <value> must be blank if field <value> is OK or NOTOK or RERUN Communication with WS-Gateway stopped, all requests were canceled System Error in <value>: Command <value> failed; <value> No communication with WS-Gateway. Request cancelled <value> not possible, no communication with Gateway <value> not possible, Unknown data center <value> <value> not possible, data center <value> not available Communication with data center <value> down, all requests canceled Data center <value> is suspended (AJF is being formatted) Data center <value> is suspended (Download in Netgroup)
B-28
Table B-18
Minor Code
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
Severity
Description
Data center <value> is suspended (AJF is being formatted), all requests canceled Invalid event %c received from data center <value>. To ensure database integrity, WS-GTW stop/restart is recommended The host name be specified only for the TCP protocol The host name may contain only Alphanumerics and periods You must specify a communication protocol Specified communication protocol not supported on platform Control-R not supported on platform The Net Group field must contain two alpha numeric characters CONTROL-M must be 300 or 400 for MVS Incorrect CONTROL-M version specified for this platform Scheduling table read failed - database problems Please verify that all users have quit CONTROL-M/EM and that the WS-Gateway is down. Do you really want to quit CONTROL-M/Enterprise Manager Administration ? No Net Number of nodes in a row exceeds maximum of %d Cannot generate report due to insufficient memory Cannot print links: <value> Cannot print index: <value> Cannot do poster for routed net Job Report Fields saved. Please close and open the job report window New Field is empty Confirm delete No Loaded Networks Available Control Resources with <value> <value> cannot be <value> Quantitative Resources with <value> <value> cannot be <value>
B-29
Table B-18
Minor Code
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 173 174
Severity
Description
Field Author must be entered Order ID <value> not found Pattern <value> not found in text Pattern <value> appears only once in the text Problems searching for pattern <value> Alarm handling command ignored. User <value> is handling this alarm now Alarm handling command ignored. Internal error Download of calendar <value> canceled in gateway - calendar in use Download of calendar <value> canceled in gateway - Another download is currenlty in progress - Try later Upload of calendar <value> canceled in gateway Upload of calendar <value> canceled in gateway - calendar in use Upload of definitions table <value> canceled in gateway Upload of definitions table <value> canceled in gateway - table in use Download of definition table <value> canceled in gateway - table in use Download of definition table <value> canceled in gateway - Another download is currenlty in progress - Try later Definitions table deleted on data center but delete failed on workstation (rc 1) Definitions table deleted on data center but delete failed on workstation (rc 2) Calendar deleted on data center but delete failed on workstation (rc 2) Delete of definitions table <value> canceled in gateway - table in use Delete of calendar <value> canceled in gateway - calendar in use User request canceled in gateway, no answer from data center (time-out) Download of <value> canceled, no answer from data center (time-out) Download of <value> canceled in gateway Download canceled, no answer from data center (time-out) Download canceled in gateway
B-30
Table B-18
Minor Code
175 176 177 178 179 180 179 180 181 182 182 183 183 184 185 186 187 188 189 190 191 192 193 194 194 195
Severity
ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR
Description
Upload canceled in gateway Upload canceled (file transfer error (rcp) in gateway), consult system administrator Information request canceled in gateway, system error (fopen failed), consult system administrator Information request canceled (time-out) in gateway, no answer from data center Upload of <value> canceled (time-out), no answer from data center Upload of <value> canceled in gateway Upload canceled (time-out), no answer from data center Upload canceled in gateway No fields defined Field <value> not in table Field not in table Internal error on Field <value> Internal error on field Cannot print %d characters; Maximum of %d allowed Cannot print more than %d fields You are not authorized to load an active network <value> was not found in data center. Delete in workstation ? You are not authorized to access the Global Conditions window Definition table <value> was deleted only on workstation Calendar <value> was deleted only on workstation Internal error. Action failed Insert failed. Record with same key already exists. Record deleted in the meantime. Error message <value> Received from data center <value>. Error message received from data center. Field <value> is required if field <value> is defined
B-31
Table B-18
Minor Code
195 196 197 198 199 200 201 202 202 203 203 204
Severity
ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR ERROR
Description
Field required. Field <value> should be at most %d characters Field <value> may not contain the characters <value> Field <value> must be between <value> and <value> Field <value> should be empty Field <value> must be blank if field When is OK or NOTOK or RERUN Field <value> must be <value> No response to hartbeat check from data center: <value> No response to hartbeat check from data center. Unsuported version <value> of data center <value>. Check CTM installation Unsuported version of data center, check CTM installation. Not the smallest ISN for ordered/forced job
B-32
Glossary
Glossary
Active Jobs File
The Active Jobs file lists all jobs scheduled for submission in the current day. Each job in the Active Jobs file is not submitted until all conditions in the job processing definition for the job are satisfied. The Active Jobs file is in the CONTROL-M database. Alerts are messages that indicate important information for the CONTROL-M/Enterprise Manager (CONTROL-M/EM) user. These messages normally indicate when a problem or exception has occurred for a job controlled by CONTROL-M. All alerts are displayed in the Global Alert Client Alerts window. Software product that schedules, submits, tracks and follows up the execution of jobs in a specific installation. In certain releases, CONTROL-M functions are divided between two separate components: CONTROL-M/Server and CONTROL-M/Agent. Software product that provides a central point of control for CONTROL-M installations. CONTROL-M/EM provides the GUI that allows users to graphically view the status of job schedules and execution in CONTROL-M installations, to issue requests for additional information, to make changes in the Active Jobs file, and to handle problems. CONTROL-M/EM also passes global conditions among CONTROL-M installations.
Alert
CONTROL-M
CONTROL-M/ Enterprise Manager or CONTROL_M/EM
Glossary
CONTROL-M/EM GUI Server
Process that handles communication between CONTROL-M/EM GUI workstations and other components of CONTROL-M/EM. The CONTROL-M/EM Server executes database queries, calculations and procedures for each GUI, thereby lessening its workload and streamlining productivity by enabling data-sharing between GUIs. Multiple CONTROL-M/EM Servers can be installed in an CONTROL-M/EM environment. An architecture for creating, distributing, and managing program objects across distributed computers. The process that handles communication between CONTROL-M and CONTROL-M/EM. There are gateway processes on both the CONTROL-M platform and on the CONTROL-M/EM workstation. The process that identifies and distributes alerts between CONTROL-M installations and CONTROL-M/EM workstations. The Global Alerts Server connects to each CONTROL-M/EM gateway to receive alerts from CONTROL-M and transmit them to the CONTROL-M/EM GUIs. Java is an object-oriented programming language for use in a distributed computing environment. Set of user-defined parameters for each job which provide CONTROL-M with detailed instructions on processing the job. job processing definitions are organized into Scheduling tables. A flag representing a user-specified situation or condition. Submission of a job for execution can be made dependent upon the existence of one or more prerequisite conditions. Prerequisite conditions are recorded in the CONTROL-M/EM Conditions/Resources table. Text string returned by CONTROL-M/EM containing status information regarding the request for which it is returned.
CORBA
Gateway
Global Alerts Server
Java
Job Processing Definition
Prerequisite Conditions or Conditions
Response
Request
An action that is sent to CONTROL-M/EM from a remote location, using the CONTROL-M/EM API. Some requests are processed by CONTROL-M/EM; others are forwarded to CONTROL-M for processing. There are two broad types of requests: Requests that manage the transfer of information between the CONTROL-M/EM API and CONTROL-M/EM. Requests that contain actions that influence the CONTROL-M/EM active environment.
XML
Extensible Markup Language (XML) is a specification for designing markup languages used to organize information.
Glossary
Index
Index
Symbols
.dtd files.See validation files errors in changing status B-21 analyzing response strings 5-12 application runtime 7-11 Authorization request errors B-20
A
accessing Global Alerts Server 2-6 GUI Server 2-6 Orbix Locator 2-6 actions in CONTROL-M/EM API session 4-15 activating project 3-6 Add Condition request description 9-4 errors B-17 polling requirement 4-11 response 9-7 adding conditions 9-4 directory pathnames to CLASSPATH 2-6 advantages to EMBasicXMLInvoker 4-9 to EMXMLInvoker 4-11 alerts changing status 9-11
C
calls EMXMLInvoker 4-15 Change Alert Status request description 9-11 errors B-21 response 9-13 choosing a CONTROL-M/EM API class 4-7 classes choosing 4-7 ComponentType 8-3 EMBasicXMLInvoker 8-4 EMXMLInvoker 8-9 GASComponent 8-18 GSRComponent 8-21 in response strings 5-2 list 8-1 sample 3-3 CLASSPATH adding directory pathnames 2-6 omissions 7-6
Index
orbix2000.cfg file 6-5 troubleshooting 7-6 com.bmc.ctmem.emapi.XMLDATAPATH property 4-14 communication errors B-24 ComponentType class 8-3 conditions errors in adding B-17 errors in deleting B-17 configuration files 2-6 configuring CONTROL-M/EM API 3-1 differences between platforms 2-5 environment 7-6 log file 7-3 polling timeout 6-8 project environment 3-1 script 2-6 setPollRequestIntervalMilli 6-8 setPollRequestTimeoutMilli 6-8 CONTROL-M supported versions 2-1 CONTROL-M/EM internal errors B-9 primary subdirectories 2-4 CONTROL-M/EM API adding directory pathnames to CLASSPATH 2-6 configuration files 2-6 configuration script 2-6 configuring 3-1 how it works 1-2 importing into project 3-3 initializing 1-2 initializing services 4-15 mandatory program actions 4-1 operating system support 2-2 operations description 1-3 platform support 2-2 primary subdirectories 2-5
recommended users of this Guide 1-3 software requirements 2-1 stoppng services 4-15 support for CONTROL-M versions 2-1 supported CONTROL-M/EM components 1-2 uncompressing installation files 2-4 untarring installation files 2-4 CONTROL-M/EM API session flow of actions 4-15 starting and stopping services 4-15 CONTROL-M/EM component specifying in a request call 4-16, 4-21 CONTROL-M/EM password encoding 4-2 CONTROL-M/Enterprise Manager API. See CONTROL-M/EM API CONTROL-M/Enterprise Manager. See CONTROL-M/EM CONTROL-M/Server communication errors B-15 CONTROL-M/Server errors B-9, B-12 conventions,document xix CORBA advanced implementation 6-1 description 6-2 initializing processes 1-2 Orbix domain initialization failure 7-10 CORBA parameters passing to project 3-6 CORBA processes initializing 4-15 CORBA properties modifying 6-1 creating emapi_log.cfg file 7-2 EMXMLInvoker calls 4-15 EMXMLInvoker class request calls 4-15 Group Scheduling tables 9-17 jobs in Group Scheduling tables 9-17
regular jobs 9-17 XML strings 8-1 ctmemapi.properties 2-6 ctmemapi.properties file 3-2, 7-11 component hostnames 4-18, 4-22
E
emapi_env.bat file 3-2, 3-6 emapi_env.sh file 3-2, 3-6 emapi_log.cfg file 7-2 emapi-610-nt.zip file 2-4 emapi-admin.bat file 2-6 emapi-admin.sh file 2-6 emapi-configure file 2-6 emapi-configure.exe file 2-6 emapi-env.bat file 2-6 emapi-env.sh file 2-6 EMAPIMessages.txt file B-1 EMBasicXMLInvoker derived methods 8-4 description 8-4 invoking 4-23 response handling 4-7 when to use 4-9 EMXMLInvoker calls 4-15 derived methods 8-9 invoking 4-18 polling 4-20 polling requirement 4-11 response handling 4-7 when to use 4-11 encodePassword method 8-11 encoding with encodePassword method 8-11 encoding password in session 4-2 environment setting variables 3-6 solving problems 7-6 error codes list of Major Codes B-4 Major Code (defined) B-1 Minor Code (defined) B-2 reference B-4 ERROR severity level 7-3, B-2
D
DEBUG severity level 7-3, B-3 debugging severity levels 7-3, B-2 using Log4J 7-1 Delete Condition request description 9-4 errors B-17 polling requirement 4-11 response 9-7 deleting conditions 9-4 determining job status 5-1 location of validation files 4-14 polling status 5-1 request status 5-1 development environment 3-1 differences between EMBasicXMLInvoker and EMXMLInvoker 4-7 between the native and basic APIs 4-7 directories missing 7-6 of the CONTROL-M/EM API 2-5 disadvantages to EMBasicXMLInvoker 4-9 to EMXMLInvoker 4-11 document conventions xix done method primary listing 8-10 stopping API services 4-16
Index
errors Active Jobs file B-12 adding conditions B-17 application runtime 7-11 authorizations B-20 categories B-1 Change Alert Status request B-21 communication 7-11, B-24 conditions B-9 contents B-1 CONTROL-M/Server B-9, B-12 CONTROL-M/Server communication B-15 creating Group Scheduling tables B-22 creating jobs B-22 deleting conditions B-17 described in EMAPIMessages.txt file B-1 description 8-27, B-2 gateway B-24 Generic Request Exceptions B-15 hostnames 7-11 identifying 5-1 in XML format B-23 initializing Orbix domain 7-10 Java client B-23 Job Creation request B-22 Job Tracking request B-19 JVM parameters 7-7 Low-Level API Exceptions B-7 Major Code B-1 Minor Code B-2 NULL exceptions B-6 Order/Force request B-18 ordering jobs B-12 Parser Exceptions B-8 polling B-16 Registration request B-20 resources B-9 severity level 7-3, B-2
tracking jobs B-19 Unregistration request B-20 user name invalid B-20 user token invalid B-20 exceptions throwing 4-23 exceptions. See errors. executing CONTROL-M/EM API sessions 4-1 java commands 3-6 tracking requests with polling 4-20
F
FATAL severity level 7-3, B-2 fixing application runtime errors 7-11 CLASSPATH problems 7-6 communication errors 7-11 environment problems 7-6 JVM problems 7-7 Orbix domain initialization problems 7-10 forcing Group Scheduling tables 9-59 jobs 9-59 polling for response 9-65 formatting requests 4-1 response strings 5-2
G
GAS hostname 2-6 hostname as property 6-6 hostname errors 7-11 location 2-6 specifying in a request call 4-16
GASComponent prototype 1 8-19 prototype 2 8-20 GAScomponent specifying in a request call 4-21 GAScomponent class derived methods 8-18 GASComponent method 8-19 gateway errors B-24 Generic Request Exceptions B-15 getMajorCode method 8-25 getMinorCode method 8-26 getProperties method advanced use 6-6 defaults 6-6 description 8-12 getReason method 8-27 Group Scheduling tables creating 9-17 errors in creating B-22 GSRComponent prototype 1 8-22 prototype 2 8-23 GSRcomponent specifying in an XMLBasicInvoker request call 4-16 specifying in an XMLInvoker request call 4-21 GSRComponent class derived methods 8-21 GSRComponent method 8-22 GUI Server hostname 2-6 hostname as property 6-6 hostname errors 7-11 location 2-6
errors 7-11 recording in the ctmemapi.properties file 4-18, 4-22 specifying 2-6 specifying in a call 4-16
I
identifying errors 5-1 implementing Orbix ORB settings 7-10 import command 3-3 importing CONTROL-M/EM API into project 3-3 INFO severity level 7-3, B-3 init method modifying properties 6-1 primary listing 8-13 prototype 1 6-2, 8-13 prototype 2 6-3, 8-14 prototype 3 6-4, 8-15 prototypes 6-2 starting API services 4-15 troubleshooting 7-9 initializing CONTROL-M/EM API 1-2 CONTROL-M/EM API services 4-15 CORBA processes 1-2, 4-15 failure 7-10 Orbix processes 4-15 installation files uncompresssing 2-4 untarring 2-4 interpreting response strings 5-12 invalid user name B-20 invoke method primary listing 8-6, 8-16 string parameter 4-16, 4-21 throwing exceptions 4-23
Index 5
H
hostnames
InvokeException class derived methods 8-24 invokeException class error information 8-24 invoking EMBasicXMLInvoker how to 4-23 invoking EMXMLInvoker how to 4-18
advanced parameter configuration 7-7 parameter problems 7-7 passing parameters to project 3-6 requirement to run project 3-4 JVM requirement and support 2-3
L
Log4J logging mechanism 7-1 supported versions 7-1 log4J.jar file 7-1 logging category 7-2 configuring log file 7-3 default behavior 7-2 modifying behavior 7-2 parameters 7-2 using Log4J 7-1 logging off 9-105 logging on 9-98 Low-Level API Exceptions B-7
J
Java client errors B-23 Java classes role in API function 1-2 java command 3-6 Java Developers Kit. See JDK Java Runtime Environment. See JRE Java Virtual Machine. See JVM JAVA_HOME environment variable 2-3 JDK requirement and support 2-3 job determining status 5-1 Job Creation request description 9-17 determining parameter names 9-2 polling requirement 4-11 response 9-53 responses 9-17 Job Tracking request errors B-19 jobs creating 9-17 errors in creating B-22 errors in forcing B-18 errors in ordering B-12, B-18 parameter names 9-3 tracking 9-89 JRE requirement and support 2-3 JVM
6
M
mandatory program actions 4-1 methods Basic 1-2 done 4-16, 8-10 encodePassword 8-11 GASComponent 8-19 getMajorCode 8-25 getMinorCode 8-26 getProperties 6-6, 8-12 getReason primary listing 8-27 GSRComponent 8-22 init 4-15, 8-13 invoke 4-16, 4-21, 8-6 invoke (EMXMLInvoker) 8-16
Native 1-2 of the EMBasicXMLInvoker class 8-4 of the EMXMLInvoker class 8-9 of the GASComponent class 8-18 of the GSRComponent class 8-21 of the InvokeException class 8-24 setPollRequestIntervalMilli 8-7 setPollRequestIntervalMilli implementation 6-8 setPollRequestTimeoutMilli 8-8 setPollRequestTimeoutMilli implementation 6-8 setProperties 6-7, 8-17 modifying initialization properties 6-1 logging behavior 7-2 Orbix domain configuration file 7-10 project for use with the CONTROL-M/EM API 3-3 mySAP. See SAP
modifying properties 6-1 orbix2000.cfg file in CLASSPATH 6-5 specifying domain with ORB 7-10 specifying implementation 7-7 version support 2-3 orbix2000.cfg file 6-5 Order/Force request description 9-59 errors B-18 polling 9-65 polling requirement 4-11 response 9-64 ordering Group Scheduling tables 9-59 jobs 9-59 polling for response 9-65 outcome tracking 9-89
P
Parser Exceptions B-8 parsing response string 5-1 response strings 5-12 XML errors B-8 passing CORBA parameters to project 3-6 password encodePassword method 8-11 encoding 4-2 platform support 2-2 Poll request description 9-77 response 9-79 polling configuring timeout 6-8 determining status 5-1 errors B-16 for Order/Force requests 9-65 required with EMXMLInvoker 4-11 tracking ID 4-11
Index 7
N
null exceptions 7-6, B-6
O
Object Request Broker. See CORBA objects invoking using EMBasicXMLInvoker 4-23 invoking using EMXMLInvoker 4-19 operating system support 2-2 ORBconfig_domains_dir parameter 6-5 ORBdomain_name.cfg file 7-10 Orbix accessing Locator 2-6 domain initialization failure 7-10 initializing processes 4-15
with EMXMLInvoker 4-20 polling request errors B-16 post-installation configuration 3-1 preparing project environment 3-1 processing response strings 5-12 project modifying for use with the CONTROL-M/EM API 3-3 prepapring environment 3-1 running 3-6 properties com.bmc.ctmem.emapi.XMLDATAPAT H 4-14 errors B-23 getting 6-6 Global Alerts Server 2-6 GUI Server 2-6 modifying init 6-1 setting 6-6 prototypes done 4-16 GASComponent prototype 1 8-19 GASComponent prototype 2 8-20 getProperties method 6-6 GSRComponent prototype 1 8-22 GSRComponent prototype 2 8-23 init 4-15 init method 6-2 init prototype 1 6-2, 8-13 init prototype 2 6-3, 8-14 init prototype 3 6-4, 8-15 setPollRequestIntervalMilli method 6-9 setPollRequestTimeoutMilli method 6-9 setProperties method 6-7
R
receiving errors 5-1
8
job status 5-1 polling status 5-1 request status 5-1 registering users registration validity 9-83 with Registration request 9-98 Registration request description 9-98 encoding password 4-2 errors B-20 response 9-101 related publications xvi release notes xix request status determining 5-1 in response strings 5-2 requests sending 4-7 submitting 4-7 tracking with polling 4-20 resetting registration timeout 9-83 response handling 5-1 by class 4-7 response string 5-1 contents 5-2 formats 5-2 parsing 5-1, 5-12 parts 5-12 types 5-2 responses EMAPI_errorResponse 5-7 EMAPI_PollResponse 5-7 EMAPI_Response 5-11 EMAPI_TokenResponse 5-3 to Add Condition requests 9-7 to Change Alert Status request 9-13 to Delete Condition requests 9-7 to Job Creation request 9-53 to Order/Force request 9-64
to Poll request 9-79 to Registration request 9-101 to Timeout Reset request 9-85 to Tracking request 9-92 to Unregistration request 9-108 types 5-2 running java command 3-6 project 3-6 running environment 3-1
S
selecting a CONTROL-M/EM API class 4-7 component to process the request 4-16, 4-21 sending requests 4-7 setPollRequestIntervalMilli method configuring 6-8 default 6-9 primary listing 8-7 setPollRequestTimeoutMilli method configuring 6-8 default 6-9 primary listing 8-8 setProperties method primary listing 8-17 use 6-7 setting environmental variables 3-2, 3-6 severity levels DEBUG 7-3, B-3 ERROR 7-3, B-2 FATAL 7-3, B-2 INFO 7-3, B-3 WARN 7-3, B-2 software requirements CONTROL-M 2-1 CORBA implementation 2-3 JDK 2-3
JRE 2-3 JVM 2-3 operating system 2-2 Orbix 2-3 platform 2-2 solving application runtime errors 7-11 CLASSPATH problems 7-6 communication errors 7-11 environment problems 7-6 JVM problems 7-7 Orbix domain initialization problems 7-10 specifying component to process a request 4-16, 4-21 hostnames 2-6 Orbix ORB domain 7-10 starting CONTROL-M/EM API services 4-15 CORBA processes 4-15 Orbix processes 4-15 project 3-6 stopping CONTROL-M/EM API services 4-15 CORBA processes 4-15 Orbix processes 4-15 project 4-16 submitting requests 4-7 support CONTROL-M versions 2-1 JDK 2-3 JRE 2-3 JVM 2-3 operating systems 2-2
T
throwing exceptions 4-23 timeout
Index 9
configuration 6-8 resetting interval 9-83 Timeout Reset request description 9-83 response 9-85 token. See user token tracking ID 4-11 jobs 9-89 request execution 4-20 requests 4-20 tracking ID use with EMXMLInvoker 4-11 Tracking request description 9-89 response 9-92 troubleshooting application runtime errors 7-11 CLASSPATH problems 7-6 communication problems 7-11 JVM problems 7-7 Orbix domain initialization problems 7-10 types of responses 5-2
V
validation XML strings 4-14 validation files EMAPI_add_conditionResponse.dtd 9-7 EMAPI_add_delete_condition.dtd 9-4 EMAPI_change_alert_status.dtd 9-11 EMAPI_change_alert_statusResponse.dt d 9-13 EMAPI_client_keep_alive.dtd 9-83 EMAPI_client_keep_aliveResponse.dtd 9-85 EMAPI_create_ajResponse.dtd 9-53 EMAPI_delete_conditionResponse.dtd 9-7 EMAPI_ErrorResponse.dtd 5-7 EMAPI_job_track.dtd 9-89 EMAPI_job_trackResponse.dtd 9-92 EMAPI_order_force.dtd 9-59 EMAPI_poll.dtd 9-77 EMAPI_pollResponse.dtd 5-7, 9-79 EMAPI_register.dtd 9-98 EMAPI_registerResponse.dtd 9-101 EMAPI_RequestnameResponse 5-11 EMAPI_TokenResponse.dtd 5-3 EMAPI_unregister.dtd 9-105 EMAPI_unregisterResponse.dtd 9-108 location 4-14
U
understanding response strings 5-12 Unregistration request description 9-105 errors B-20 response 9-108 user registration 9-98 user token extracting 4-2 invalid B-20 resetting timeout interval 9-83 using CONTROL_M/EM API 4-1
W
WARN severity level 7-3, B-2
X
XML invalid format errors B-23
10
XML strings creating 8-1 parsing 4-2 parsing responses 5-12 validation 4-14 XMLDATAPATH 4-14 XMLstrings parsing errors B-8
Index
11
12
END USER LICENSE AGREEMENT NOTICE

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

*16458*

CM Enterprise Manager API Developers Guide

Încărcat de

Informații document

Descriere originală:

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

CM Enterprise Manager API Developers Guide

Încărcat de

Drepturi de autor:

Formate disponibile

CONTROL-M/Enterprise Manager API Developers Guide

June 20, 2002

Restricted Rights Legend

Contacting BMC Software

United States and Canada

Outside United States and Canada

Support Web Site

Support by Telephone or E-mail

Before Contacting BMC Software

BMC Software, Inc., Confidential and Proprietary Information

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

ComponentType Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Error Codes and Exceptions

BMC Software, Inc., Confidential and Proprietary Information

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

About This Book

BMC Software, Inc., Confidential and Proprietary Information

About This Book

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

About This Book

Online and Printed Books

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

The following conventions are used in this guide:

Menu => Option

BMC Software, Inc., Confidential and Proprietary Information

About This Book

[Option] Code Samples

One-Step Procedures Ellipsis

denotes one-step instructions.

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

How the CONTROL-M/EM API Works

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Who Should Use This Guide

BMC Software, Inc., Confidential and Proprietary Information

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

CONTROL-M Product Support

CONTROL-M/EM version 6.1.0x.

BMC Software, Inc., Confidential and Proprietary Information

The CONTROL-M/EM API is compatible with the following versions of CONTROL-M:

Platform and Operating System Support

Microsoft Windows Versions

Supported Database Servers

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Additional Software Support

BMC Software, Inc., Confidential and Proprietary Information

Compressed File Name