cm enterprise manager api developers guide

310
CONTROL-M ® /Enterprise Manager API Developers Guide Version 6.1.01 June 20, 2002

Upload: luana-dantas

Post on 28-Oct-2015

136 views

Category:

Documents


1 download

TRANSCRIPT

Page 1: CM Enterprise Manager API Developers Guide

CONTROL-M®/Enterprise Manager API

Developers Guide

Version 6.1.01

June 20, 2002

Page 2: CM Enterprise Manager API Developers Guide

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 LegendU.S. GOVERNMENT RESTRICTED RIGHTS. UNPUBLISHED–RIGHTS 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 Outside United States and Canada

Address BMC Software, Inc.2101 CityWest Blvd.Houston TX 77042-2827

Telephone

Fax

(01) 713 918 8800

(01) 713 918 8000

Telephone 713 918 8800 or800 841 2031

Fax 713 918 8000

Page 3: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

iii

Customer SupportYou 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

Page 4: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

iv CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

• 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

Page 5: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Contents v

Contents

Contents

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Chapter 1 OverviewHow the CONTROL-M/EM API Works . . . . . . . . . . . . . . . . . . . . . . 1-2

Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2The APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Who Should Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Chapter 2 InstallationSoftware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

CONTROL-M Product Support . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Platform and Operating System Support . . . . . . . . . . . . . . . . . . 2-2Additional Software Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

Chapter 3 Configure the CONTROL-M/EM APIPreparing Your Project Environment . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Writing Your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Running Your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

Chapter 4 Creating Request CallsCONTROL-M/EM API Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Session Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3Deciding Which Class to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7

Response Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7XML String Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14

Using EMXMLInvoker Class Calls . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15Initializing and Stopping the CONTROL-M/EM API Services . 4-15

Page 6: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

vi CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Submitting a Request Using the EMXMLInvoker class . . . . . . .4-16Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20

Using EMBasicXMLInvoker Class Calls . . . . . . . . . . . . . . . . . . . . .4-21Submit a Request Using the EMBasicXMLInvoker class . . . . . .4-21

Chapter 5 Response HandlingResponse Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-2Response String Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-2

EMAPI_tokenResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-3EMAPI_PollResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-7EMAPI_errorResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-7EMAPI_<Requestname>Response . . . . . . . . . . . . . . . . . . . . .5-11

Interpreting Response Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-12Parts of a Response String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-12Analyzing a Response String . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-13

Chapter 6 Advanced Features and OptimizationModifying Initialization Properties . . . . . . . . . . . . . . . . . . . . . . . . . .6-1

Prototype 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-2Prototype 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-3Prototype 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-4

Getting and Setting CONTROL-M/EM API Properties . . . . . . . . . .6-6getProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-6setProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-7

Polling Interval Timeout Configuration . . . . . . . . . . . . . . . . . . . . . . .6-8setPollRequestIntervalMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-9setPollRequestTimeoutMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-9

Chapter 7 Diagnostics and TroubleshootingCONTROL-M/EM API Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1

Default Logging Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2Modifying Logging Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2

Environment Configuration Troubleshooting . . . . . . . . . . . . . . . . . .7-6CLASSPATH: Missing Libraries or Directories . . . . . . . . . . . . .7-6Java Virtual Machine Parameters . . . . . . . . . . . . . . . . . . . . . . . .7-7Orbix Domain Initialization Failure . . . . . . . . . . . . . . . . . . . . . .7-10

Application Runtime and Communication Troubleshooting . . . . . . .7-11

Chapter 8 Call ReferenceComponentType Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3

Page 7: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Contents vii

EMBasicXMLInvoker Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4invoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6setPollRequestIntervalMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7setPollRequestTimeoutMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8

EMXMLInvoker Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10encodePassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11getProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13invoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16setProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17

GASComponent Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18GASComponent (Prototype 1) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19GASComponent (Prototype 2) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20

GSRComponent Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21GSRComponent (Prototype 1) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22GSRComponent (Prototype 2) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23

InvokeException Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24getMajorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-25getMinorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26getReason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27

Chapter 9 Request ReferenceAdd/Delete Condition Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4

Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10

Change Alert Status Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16

Job Creation Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-53Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-58

Order/Force Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-59Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-59Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-64Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-76

Polling Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-77

Page 8: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

viii CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-77Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-79Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-82

Timeout Reset Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-83Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-83Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-85Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-88

Tracking Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-89Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-89Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-92Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-97

User Registration Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-98Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-98Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-101Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-104

User Unregistration Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-105Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-105Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-108Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-111

Appendix A Request Format ExamplesAdd Condition/Delete Condition Request . . . . . . . . . . . . . . . . . . . . A-2

Example 1: Add a Condition to a CONTROL-M . . . . . . . . . . . A-2Example 2: Delete a Condition from a CONTROL-M . . . . . . . A-2

Job Creation Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3Example 1: Create a Job Requiring Confirmation . . . . . . . . . . A-3Example 2: Create a Cyclic Job . . . . . . . . . . . . . . . . . . . . . . . . . A-4Example 3: Create a Job Including In and Out Conditions . . . . A-5Example 4: Create a Job that Requires Resources . . . . . . . . . . A-6Example 5: Create a Job that Includes On-Do Statements . . . . A-7Example 6: Create a Job that Includes On-Do Statements . . . . A-8

Order/Force Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9Example 1: Order a Unix Job . . . . . . . . . . . . . . . . . . . . . . . . . . A-9Example 2: Force a Unix Job . . . . . . . . . . . . . . . . . . . . . . . . . . A-9Example 3: Force a Unix Job into a ‘Recent’ Group Scheduling

Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10Example 4: Force a Unix Job into a ‘Recent’ Group Scheduling

Table while Allowing for Duplication . . . . . . . . . . . . . . . . . . A-11Example 5: Force a Scheduling Table that Contains a Group

Scheduling Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12

Page 9: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Contents ix

Appendix B Error Codes and ExceptionsSeverity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-2

Error Code Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-4NULL Exception Errors (Major Code 000) . . . . . . . . . . . . . . . .B-6Low-level API Exceptions (Major Code 100) . . . . . . . . . . . . . .B-7Parser Exceptions (Major Code 200) . . . . . . . . . . . . . . . . . . . . .B-8CONTROL-M/Server Errors: Group 1 (Major Code 300) . . . . .B-9CONTROL-M/Server Errors: Group 2 (Major Code 301) . . . . .B-12CONTROL-M/Server Errors: Group 3 (Major Code 302) . . . . .B-14Generic Request Exceptions (Major Code 401) . . . . . . . . . . . . .B-15Poll Request Errors (Major Code 403) . . . . . . . . . . . . . . . . . . . .B-16Add/Delete Condition Request Errors (Major Code 404) . . . . .B-17Order/Force Request Errors (Major Code 405) . . . . . . . . . . . . .B-18Tracking Request Errors (Major Code 406) . . . . . . . . . . . . . . . .B-19Authorization Request Errors (Major Code 407) . . . . . . . . . . . .B-20Alerts Request Errors (Major Code 408) . . . . . . . . . . . . . . . . . .B-21Create Active Job Request Errors (Major Code 409) . . . . . . . . .B-22CONTROL-M/EM API Java Client Errors (Major Code 500) . .B-23Gateway Messages (Major Code 600) . . . . . . . . . . . . . . . . . . . .B-24

Glossary

Index

Page 10: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

x CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Page 11: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Figures xi

Figures

Figures

Figure 1-1 CONTROL-M/EM API Flow Diagram . . . . . . . . . . . . . . . . . . . 1-3Figure 3-1 Sample Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Figure 4-1 Comparison of Request Methods. . . . . . . . . . . . . . . . . . . . . . . . 4-8Figure 4-2 EMBasicXMLInvoker Request Session . . . . . . . . . . . . . . . . . . 4-10Figure 4-3 EMXMLInvoker Request Session . . . . . . . . . . . . . . . . . . . . . . . 4-12Figure 4-4 EMXMLInvoker Polling Request Steps . . . . . . . . . . . . . . . . . . 4-13Figure 5-1 Order/Force Response Example . . . . . . . . . . . . . . . . . . . . . . . . 5-15Figure 7-1 emapi_log.cfg File Example with Default Parameters . . . . . . . 7-3Figure 7-2 RollingFileAppender Example Properties . . . . . . . . . . . . . . . . . 7-5

Page 12: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

xii CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Page 13: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Tables xiii

Tables

Tables

Table 2-1 Supported Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Table 2-2 Supported Database Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Table 2-3 CONTROL-M/EM API Compressed File Names . . . . . . . . . . . 2-4Table 2-4 CONTROL-M/EM API Primary Subdirectories . . . . . . . . . . . . 2-5Table 2-5 Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6Table 4-1 CONTROL-M/EM API (EMXMLInvoker) Use Flow . . . . . . . 4-3Table 4-2 Request Types Listed by Component Type . . . . . . . . . . . . . . . . 4-18Table 4-3 Polling Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20Table 4-4 Request Types Listed by Component Type . . . . . . . . . . . . . . . . 4-22Table 5-1 Response String Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Table 5-2 Token Response XML Parameters Description . . . . . . . . . . . . . 5-4Table 5-3 Error Response XML Parameters Description . . . . . . . . . . . . . 5-8Table 6-1 CONTROL-M/EM API Properties Parameters . . . . . . . . . . . . . 6-7Table 7-1 Log Message Priority Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3Table 8-1 CONTROL-M/EM API Classes . . . . . . . . . . . . . . . . . . . . . . . . 8-1Table 8-2 EMBasicXMLInvoker Methods. . . . . . . . . . . . . . . . . . . . . . . . . 8-4Table 8-3 EMXMLInvoker Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9Table 8-4 GASComponent Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18Table 8-5 GASComponent Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21Table 8-6 InvokeException Class Methods . . . . . . . . . . . . . . . . . . . . . . . . 8-24Table 9-1 Requests Listed in this Chapter . . . . . . . . . . . . . . . . . . . . . . . . . 9-1Table 9-2 Request Reference Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2Table 9-3 Add/Delete Condition XML Parameters Description . . . . . . . . 9-5Table 9-4 Add/Delete Condition Response XML Parameters Description 9-8Table 9-5 Change Alert Status XML Parameters Description . . . . . . . . . . 9-11Table 9-6 Change Alert Status Response XML Parameters Description. . 9-14Table 9-7 Job Creation Request XML Parameters Description . . . . . . . . . 9-22Table 9-8 Order/Force XML Parameters Description . . . . . . . . . . . . . . . . 9-61

Page 14: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

xiv CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Table 9-9 Order/Force Response XML Parameters Description (Native API) 9-66

Table 9-10 Order/Force Response XML Parameters Description (Basic API) 9-72

Table 9-11 Polling Request XML Parameters Description . . . . . . . . . . . . . 9-78Table 9-12 Poll Response XML Parameters Description . . . . . . . . . . . . . . . 9-80Table 9-13 Timeout Reset Request XML Parameters Description. . . . . . . . 9-84Table 9-14 Timeout Reset Response XML Parameters Description . . . . . . 9-86Table 9-15 Tracking Request XML Parameters Description . . . . . . . . . . . . 9-90Table 9-16 Tracking Request Response XML Parameters Description . . . . 9-93Table 9-17 Registration Request XML Parameters Description . . . . . . . . . 9-99Table 9-18 User registration Response XML Parameters Description. . . . . 9-101Table 9-19 Unregistration Request XML Parameters Description. . . . . . . . 9-105Table 9-20 User Unregistration Response XML Parameters Description . . 9-109Table B-1 Log Message Priority Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2Table B-2 Error and Exception Major Codes . . . . . . . . . . . . . . . . . . . . . . . B-4Table B-3 NULL Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-6Table B-4 Low Level API Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7Table B-5 Parser Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-8Table B-6 CONTROL-M/Server Errors: Group 1. . . . . . . . . . . . . . . . . . . . B-9Table B-7 CONTROL-M Server Errors: Group 2. . . . . . . . . . . . . . . . . . . . B-12Table B-8 CONTROL-M Server Errors: Group 3. . . . . . . . . . . . . . . . . . . . B-14Table B-9 Generic Request Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . B-15Table B-10 Poll Request Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-16Table B-11 Add/Delete Condition Request. . . . . . . . . . . . . . . . . . . . . . . . . . B-17Table B-12 Order/Force Request Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-18Table B-13 Job Tracking Request Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . B-19Table B-14 Authorization Request Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . B-20Table B-15 Alerts Request Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-21Table B-16 Create Active Job Request Errors. . . . . . . . . . . . . . . . . . . . . . . . B-22Table B-17 CONTROL-M/EM API Java Client Errors . . . . . . . . . . . . . . . . B-23Table B-18 Gateway Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-24

Page 15: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

About This Book xv

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.

NoteTo 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 Description

Chapter 1 OverviewDescribes what the CONTROL-M/EM API can do and how it works.

Chapter 2 InstallationDescribes thow to install the API fileson your computer.

Chapter 3 Configure the CONTROL-M/EM APIDescribes the how to configure the CONTROL-M/EM API for use in your projects.

Page 16: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

xvi CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Related DocumentationBMC 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.

Chapter 4 Creating Request CallsDescribes how to initialize the API and create requests to CONTROL-M/EM.

Chapter 5 Response HandlingDescribes the types of responses that are sent by CONTROL-M/EM and how to handle them in your project.

Chapter 6 Advanced Features and OptimizationDescribes advanced, optional procedures for further configuring use of the CONTROL-M/EM API.

Chapter 7 Diagnostics and TroubleshootingDescribes methods for identifying and resolving problems that may occur when using the CONTROL-M/EM API.

Chapter 8 Call ReferenceDescribes the classes and methods of the CONTROL-M/EM API calls.

Chapter 9 Request ReferenceDescribes how to format the XML request strings that are sent to CONTROL-M/EM.

Appendix A Request Format ExamplesPresents sample request files.

Appendix B Error Codes and ExceptionsDescribes the various return codes that can be displayed when using the CONTROL-M/EM API.

Chapter/Appendix Description

Page 17: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

About This Book xvii

• 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 site’s 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.

Page 18: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

xviii CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

• 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.

Page 19: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

About This Book xix

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:

The following conventions are used in this guide:

Abbreviation Description

CONTROL-M/EM CONTROL-M/Enterprise Manager

Net CONTROL-M/EM Network

<home-directory> Directory in which CONTROL-M/EM is installed

<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>.

Menu => Option 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.

Page 20: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

xx CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

{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] Square brackets are used to enclose parameters that are optional.

Code Samples Format syntax, operating system terms, literal examples, and JCL scripts are presented in this typeface.

Boldface 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.

Italics Italic type is used to emphasize important terms. The titles of BMC Software product documentation are also displayed in italic type.

One-Step Procedures The symbol » denotes one-step instructions.

Ellipsis An ellipsis ( . . . ) indicates that you can repeat the preceding item or items as many times as necessary.

Option Symbol 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

Page 21: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Overview 1-1

1

Overview 1

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

Page 22: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

1-2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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)

Page 23: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Overview 1-3

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 GuideThe 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.

Page 24: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

1-4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Page 25: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Installation 2-1

2

Installation 2

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 RequirementsFor 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.

Page 26: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

2-2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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

ComponentMicrosoft Windows Versions Unix Platforms

API Client Component

• Windows NT 4.0 with service pack 6a

• Windows 2000 Professional

• Windows 2000 Server• Windows 2000 Advanced

Server

• 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 Unix Platforms

• Oracle Server versions 8.1.7, 9i• Sybase Adaptive Server versions

12, 12.5• MSSQL versions 7.0 and 2000

• Oracle Server versions 8.1.7, 9i• Sybase Adaptive Server versions

12, 12.5

Page 27: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Installation 2-3

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 Developer’s Kit (JDK) version 1.3 or the Java Runtime Environment (JRE) version 1.3 is installed on the computer hosting your project’s working directory.

• The JAVA_HOME environment variable points to the JDK (or JRE) directory/library on the computer hosting your project’s working directory.

NoteThe 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.

Page 28: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

2-4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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 Compressed File Name

Microsoft Windows emapi-610-nt.zip

Solaris emapi-610-sparc.tar

HP-UX emapi-610-hp11.tar

AIX emapi-610-aix.tar

Page 29: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Installation 2-5

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.

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.

Table 2-4 CONTROL-M/EM API Primary Subdirectories

Directory Description

emapi-610\iona 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

emapi-610\xmldata Contains the .dtd files that validate the xml-formatted request strings sent and received using the API.

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

emapi-610\classes Contains the API .jar files, including:

• emapi.jar– The API implementation files.• log4j.jar – Files used by the API logging facility.

Page 30: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

2-6 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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 libraryExecute ’configure -?’ for more details.Press any key to begin. [continue]:

Table 2-5 Configuration Files

Name Description

emapi-configure.exe(on Microsoft Windows)

emapi-configure(on Unix)

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.

emapi-env.bat(on Microsoft Windows)

emapi-env.sh(on Unix)

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.

ctmemapi.properties Contains the locations of:• CONTROL-M/EM GUI Server• Global Alerts Server• XMLDATAPATH propertyNote: This file is created by the emapi-configure(.exe) file when it is run.

emapi-admin.bat(on Microsoft Windows)

emapi-admin.sh(on Unix)

Starts an interactive utility for changing the hostnames of the CONTROL-M/EM GUI Server and Global Alerts Server.

Page 31: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Installation 2-7

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:

Page 32: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

2-8 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.”

Page 33: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Configure the CONTROL-M/EM API 3-1

3

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 EnvironmentPrior 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.

NoteYour 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.

Page 34: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

3-2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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 project’s working directory.

Page 35: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Configure the CONTROL-M/EM API 3-3

Writing Your ProjectCertain 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 componentComponentType gsr_comp = new GSRComponent();// Creates a new EMXMLInvoker instanceEMXMLInvoker 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.*;

Page 36: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

3-4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.

Page 37: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Configure the CONTROL-M/EM API 3-5

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.

Page 38: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

3-6 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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 project’s working directory.

Step 4 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>

Page 39: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Configure the CONTROL-M/EM API 3-7

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.

NoteThe command must be entered as a single line. It is divided here to fit on the page.

NoteOptionally, you can pass these parameters using one of the alternative methods are described in “Java Virtual Machine Parameters” on page 7-7.

Page 40: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

3-8 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Page 41: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-1

4

Creating Request Calls 4

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 SessionsThe 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.

Page 42: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

• 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.

Page 43: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-3

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 User Actions API Actions

1 Log inEnd user logs on to a remote computer to use a program that uses the CONTROL-M/EM API.

None.

2 User starts Client-Side ProgramEnd user starts the program.

Program startRequired action:• Initialize the API using the init method of the

EMBasicXMLInvoker class.Usage: Mandatory.

Page 44: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

3 User Logs in to CONTROL-M/EMEnd user must supply a username and password.

API (client side) sends Register request Required actions:• Encode password. Use the encodePassword

method.Usage: Mandatory, if the password was notalready encoded. Encoded strings can bereused.

• Submit Register request. Use the invoke method of the EMBasicXMLInvoker class, supplying the Register request string as a parameter.Usage: Mandatory.

4 None. CONTROL-M/EM returns responseRequired 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.

5 Submit request Required action:• User makes request that results

in a job being submitted to CONTROL-M/EM.Usage: Mandatory.

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.

6 None. CONTROL-M/EM returns responseRequired 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

7 None. API (client side) polls for answerRequired 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.

Table 4-1 CONTROL-M/EM API (EMXMLInvoker) Use Flow (Part 2 of 4)

Step User Actions API Actions

Page 45: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-5

8 None. CONTROL-M/EM returns responseRequired 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 requestUsage: Mandatory.

9 None. API (client side) processes responseRequired 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 requestUsage: Mandatory.

10 None. 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.

11 None. API (client side) processes responseRequired actions:• The program parses the response and notifies

the user of the outcome of the request.Usage: Mandatory.

Table 4-1 CONTROL-M/EM API (EMXMLInvoker) Use Flow (Part 3 of 4)

Step User Actions API Actions

Page 46: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-6 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

12 Submit request Required action:• User makes request.

Usage: Optional.

Repeat steps 5-11 for each request that requires polling.

13 User Logs off of CONTROL-M/EM API (client side) sends Unregister request Required actions:• Submit Unregister request. Use the invoke

method, supplying the Unregister request string as a parameter. The request includes the user token supplied in step 4.Usage: Mandatory.

14 None. CONTROL-M/EM returns responseRequired 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.

15 None. Program stop (Optional)Required action:• Stop the API using the done method.Usage: Mandatory, when the program is stopped.

Table 4-1 CONTROL-M/EM API (EMXMLInvoker) Use Flow (Part 4 of 4)

Step User Actions API Actions

Page 47: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-7

Deciding Which Class to UseThe EMXMLInvoker and EMBasicXMLInvoker classes can be used together in the same project. However, you must decide which class is most suitable for your purposes.

NoteThe 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.

Page 48: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-8 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Figure 4-1 Comparison of Request Methods

Page 49: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-9

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.

Page 50: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-10 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

EMBasicXMLInvoker Request Session Diagram

Figure 4-2 EMBasicXMLInvoker Request Session

Page 51: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-11

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.

Page 52: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-12 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.

Page 53: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-13

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.

Page 54: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-14 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.

NoteThe 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.

Page 55: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-15

Using EMXMLInvoker Class CallsThe 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.

NoteThe 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.

NoteThere are two additional init prototypes. They are described in “Modifying Initialization Properties” on page 6-1.

Prototype

public static void init()

Page 56: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-16 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.

Page 57: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-17

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.

Page 58: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-18 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

NoteIdentifying 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.

Table 4-2 Request Types Listed by Component Type

Request TypeGUI Server (GSRComponent)

Global Alerts Server (GASComponent)

Job Creation X

Order/Force X

Add/Delete Condition X

Alert Status Modification X

Polling X

User Registration X X

User Unregistration X X

Time-out Reset X X

Job Tracking X

Page 59: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-19

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 requestString xmlResponse;try{

xmlResponse = gsrComponent.invoke(xmlRequest);}catch(InvokeException ex){

// handle invoke failures}// handle xml response

NoteThe 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.

Page 60: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-20 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.

For more information about the polling request, see page 9-77.

Table 4-3 Polling Requirements

Polling Request Type

Required • Order/Force Request• Add/Delete Condition Request• Job Creation Request

Not Required • Polling Request• User Registration Request• User Unregistration Request• Time-out Reset Request• Alert Status Modification Request• Job Tracking Request

Page 61: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-21

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.

Page 62: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-22 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.

NoteIdentifying 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

Table 4-4 Request Types Listed by Component Type

Request TypeGUI Server (GSRComponent)

Global Alerts Server (GASComponent)

Job Creation X

Order/Force X

Add/Delete Condition X

Alert Status Modification

X

Polling X

User Registration X X

User Unregistration X X

Time-out Reset X X

Job Tracking X

Page 63: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Creating Request Calls 4-23

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 requestString xmlResponse;try{

xmlResponse = gsrComponent.invoke(xmlRequest);}catch(InvokeException ex){

// handle invoke failures}// handle xml response

NoteThe 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.

Page 64: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4-24 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Page 65: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Response Handling 5-1

5

Response Handling 5

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

Page 66: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

5-2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Response TypesAll 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.

Response String FormatsThe 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.

Table 5-1 Response String Types

Response Type Description

EMAPI_TokenResponse This response is sent following all requests that require polling.

EMAPI_PollResponse Informs you that your original request is being processed (status: EXEC).

EMAPI_<Requestname>Response The response that informs you of the outcome of your initial request.

EMAPI_errorResponse Used when any request you place returns an error.

Page 67: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Response Handling 5-3

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:errorctmem:major CDATA #REQUIREDctmem:minor CDATA #REQUIREDctmem: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:responsectmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:message_package (ctmem:response )><!ATTLIST ctmem:message_packagexmlns:ctmem CDATA #IMPLIEDctmem:version (1.0) #REQUIRED>

Page 68: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

5-4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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”

Location of the schema.

version (1.0) 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>

Page 69: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Response Handling 5-5

response_data 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>

Table 5-2 Token Response XML Parameters Description (Part 2 of 3)

Parameter Description Valid Values

Page 70: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

5-6 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

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>

Table 5-2 Token Response XML Parameters Description (Part 3 of 3)

Parameter Description Valid Values

Page 71: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Response Handling 5-7

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.”

Page 72: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

5-8 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

dtd

<?xml version="1.0" encoding="UTF-8"?><!ELEMENT ctmem:error_message (#PCDATA)><!ELEMENT ctmem:error (ctmem:error_message)><!ATTLIST ctmem:errorctmem:major CDATA #REQUIREDctmem:minor CDATA #REQUIREDctmem:severity CDATA #REQUIRED><!ELEMENT ctmem:error_list (ctmem:error+)><!ATTLIST ctmem:error_listctmem:highest_severity CDATA #REQUIRED><!ELEMENT ctmem:status (#PCDATA)><!ELEMENT ctmem:response (ctmem:status, ctmem:error_list?)><!ATTLIST ctmem:responsectmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:message_package (ctmem:response)><!ATTLIST ctmem:message_packagexmlns:ctmem CDATA #IMPLIEDctmem: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">

Page 73: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Response Handling 5-9

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”

Location of the schema.

version (1.0) 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>

Table 5-3 Error Response XML Parameters Description (Part 2 of 3)

Parameter Description Valid Values

Page 74: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

5-10 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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>

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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

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>

Table 5-3 Error Response XML Parameters Description (Part 3 of 3)

Parameter Description Valid Values

Page 75: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Response Handling 5-11

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.

Page 76: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

5-12 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Interpreting Response StringsA 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.

NoteSome 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.

Page 77: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Response Handling 5-13

• 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_datactmem: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

Page 78: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

5-14 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

• 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

Page 79: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Response Handling 5-15

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.

Page 80: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

5-16 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.

Page 81: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Response Handling 5-17

• 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.

Page 82: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

5-18 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Page 83: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Advanced Features and Optimization 6-1

6

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 PropertiesBefore 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.

NoteIf 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).

Page 84: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

6-2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.

Page 85: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Advanced Features and Optimization 6-3

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 application’s main. This enables you to control ORB initialization from outside the program.

NoteFor a list of Orbix parameters suitable for use in args, see the manufacturer’s documentation.

Code Example

public class HelloWorld {public static void main(String[] args) {

EMXMLInvoker.init(args);...

}}

Run Example

java HelloWorld -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.

Page 86: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

6-4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

• 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)

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 application’s main. This enables you to control ORB initialization from outside the program.

NoteFor a list of Orbix parameters suitable for use in args, see the manufacturer’s documentation.

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).

NoteThe 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);

Page 87: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Advanced Features and Optimization 6-5

...}

}

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).

NoteThis 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.

Page 88: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

6-6 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.

Page 89: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Advanced Features and Optimization 6-7

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}

Table 6-1 CONTROL-M/EM API Properties Parameters

Parameter Description

com.bmc.ctmem.emapi.GSR.hostname Set to the hostname of the CONTROL-M/EM GUI Server.

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

com.bmc.ctmem.emapi.XMLDATAPATH Set to the location of the XML .dtd (validation) files.

Page 90: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

6-8 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Polling Interval Timeout ConfigurationRequests 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.

NotesetPollRequestIntervalMilli 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

Page 91: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Advanced Features and Optimization 6-9

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.

Page 92: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

6-10 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Page 93: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Diagnostics and Troubleshooting 7-1

7

Diagnostics and Troubleshooting 7

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 LoggingThe 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.

Page 94: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

7-2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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).

Page 95: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Diagnostics and Troubleshooting 7-3

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.

NoteEach setting includes messages of that level and more critical levels.

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=ERRORlog4j.category.com.bmc.ctmem.emapi=ERROR, EMAPI_Appender

# set appender for EMAPIlog4j.appender.EMAPI_Appender=org.apache.log4j.RollingFileAppenderlog4j.appender.EMAPI_Appender.file=emapi.loglog4j.appender.EMAPI_Appender.append=truelog4j.appender.EMAPI_Appender.maxFileSize=50kb

Table 7-1 Log Message Priority Levels

Level Description

FATAL Displays fatal error messages.

ERROR Displays messages for fatal and non-fatal errors.

WARN Displays warning messages and all error messages.

INFO Displays system information, warnings, and all errors.

DEBUG Displays debugging information and all other priority messages.

Page 96: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

7-4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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:

Page 97: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Diagnostics and Troubleshooting 7-5

Figure 7-2 RollingFileAppender Example Properties

Code Description

file=emapi.log Indicates that the log output file is named emapi.log.

append=true Indicates that new information is added to the end of the log file.

maxFileSize=50kb Indicates that the maximum file of the log file is 50kb.

maxBackupIndex=2 Indicates the number of backups made (number of old log files saved).

layout=org.apache.log4j.SimpleLayout

Indicates the format for entries to the log file.

Page 98: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

7-6 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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

Page 99: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Diagnostics and Troubleshooting 7-7

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: Noat 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.:

Page 100: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

7-8 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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 project’s executable file.

Method 2

1. Create a file containing the following text:

org.omg.CORBA.ORBClass=com.iona.corba.art.artimpl.ORBImplorg.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");

Page 101: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Diagnostics and Troubleshooting 7-9

props.setProperty("org.omg.CORBA.ORBSingletonClass", "com.iona.corba.art.artimpl.ORBSingleton");EMXMLInvoker.init(args, props);

-or-

Call the init method without any parameters.

Page 102: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

7-10 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Orbix Domain Initialization Failure

Problem

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

NoteThis 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.

Page 103: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Diagnostics and Troubleshooting 7-11

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.

Page 104: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

7-12 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

• 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.

Page 105: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-1

8

Call Reference 8

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.

NoteThe 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 Description

ComponentType An abstract base class representing a CONTROL-M/EM component supported for use with the CONTROL-M/EM API. See page 8-3.

EMBasicXMLInvoker The EMBasicXMLInvoker class is inherited from the EMXMLInvoker class. See page 8-4.

EMXMLInvoker The primary class of the API. See page 8-9.

GASComponent The GASComponent class represents the Global Alerts Server (GAS). See page 8-18.

Page 106: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

GSRComponent The GASComponent class represents the CONTROL-M/EM GUI Server. See page 8-21.

InvokeException This class is used to process error feedback from CONTROL-M/EM. See page 8-24.

Table 8-1 CONTROL-M/EM API Classes

Class Description

Page 107: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-3

ComponentType ClassAn abstract base class representing a CONTROL-M/EM component supported for use with the CONTROL-M/EM API.

NoteThe 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.

Page 108: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

EMBasicXMLInvoker ClassThe 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 Description

done 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.

encodePassword 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.

getProperties 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.

init 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.

invoke 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.

Page 109: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-5

setPollRequestIntervalMilli

Determines the interval, in milliseconds, between automatic poll requests.For more information, see “setPollRequestIntervalMilli” on page 8-7.

setPollRequestTimeoutMilli

Determines the total time, in milliseconds, allotted for polling following a request.For more information, see “setPollRequestTimeoutMilli” on page 8-8.

setProperties 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.

Table 8-2 EMBasicXMLInvoker Methods (Part 2 of 2)

Method Description

Page 110: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-6 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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”

Page 111: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-7

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

Page 112: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-8 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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

Page 113: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-9

EMXMLInvoker ClassThe 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 Description

done 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.

encodePassword 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.

getProperties 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.

init 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.

invoke 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.

setProperties 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.

Page 114: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-10 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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

Page 115: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-11

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

Page 116: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-12 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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

See Also

• “setProperties” on page 8-17• “Getting and Setting CONTROL-M/EM API Properties” on page 6-6

Parameter Description

<host_of_the_GUI_Server> Hostname of the CONTROL-M/EM GUI Server.Default:com.bmc.ctmem.emapi.GSR.hostname

<host_of_the_Alerts_Server> Hostname of the Global Alerts Server.Default:com.bmc.ctmem.emapi.GAS.hostname

<path_to_XML_data_files> Location of the XML .dtd (validation) files.Default:com.bmc.ctmem.emapi.XMLDATAPATH

Page 117: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-13

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

Page 118: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-14 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Prototype 2

This init prototype enables you to include an array of strings representing a list of arguments.

Syntax

public static void init(String[] args)

Parameters

For a list of Orbix parameters suitable for use in args, see the manufacturer’s documentation.

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

Page 119: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-15

Prototype 3

This init prototype enables you to include an array of strings representing a list of arguments.

Syntax

public static void init(String[] args, Properties props)

Parameters

For a list of Orbix parameters suitable for use in args, see the manufacturer’s 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).

NoteThe 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

Page 120: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-16 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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”

Page 121: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-17

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

Return Codes

None.

See Also

• “getProperties” on page 8-12• “Getting and Setting CONTROL-M/EM API Properties” on page 6-6

Parameter Description

<host_of_the_GUI_Server> Set to the hostname of the CONTROL-M/EM GUI Server.Default:com.bmc.ctmem.emapi.GSR.hostname

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

<path_to_XML_data_files> Location of the XML .dtd (validation) files.Default:com.bmc.ctmem.emapi.XMLDATAPATH

Page 122: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-18 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

GASComponent ClassRepresents 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 Description

GASComponent (Prototype 1)

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.

GASComponent (Prototype 2)

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.

Page 123: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-19

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

Page 124: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-20 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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

Page 125: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-21

GSRComponent ClassRepresents 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 Description

GSRComponent (Prototype 1)

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.

GSRComponent (Prototype 2)

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.

Page 126: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-22 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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

Page 127: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-23

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

Page 128: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-24 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

InvokeException ClassThe 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 Description

getMajorCode 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.

getMinorCode 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.

getReason Used to obtain the text description of an error.For more information, see “getReason” on page 8-27.

Page 129: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-25

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”

Page 130: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-26 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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”

Page 131: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Call Reference 8-27

getReason

Summary: Used to obtain the text description of an error.

Syntax

public String getReason()

Parameters

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”

Page 132: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8-28 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Page 133: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-1

9

Request Reference 9

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 Description

Add/Delete Condition Request

Adds or deletes Global conditions.

Change Alert Status Request

Changes the status of an alert (for example, from not_noticed to handled).

Job Creation Request Creates a job processing or Group Scheduling table definition and inserts it into the Active Jobs file.

Order/Force Request Inserts a job or Group Scheduling table into the Active Jobs file immediately (force) or subject to scheduling criteria (order).

Polling Request Polls the Response repository in the CONTROL-M/EM GUI Server to receive completion confirmation from earlier job processing requests.

Timeout Reset Request

Resets the user registration token timeout counter to zero.

Tracking Request Tracks the progress of existing jobs in the CONTROL-M installation.

Page 134: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

The XML format for each request is described in this chapter, together with the information in Table 9-2.

Parameter Names

Many XML elements in this chapter are CONTROL-M job parameters.

User Registration Request

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.

User Unregistration Request

Logs the user out of CONTROL-M/EM and ends the session.

Table 9-2 Request Reference Format

Topic Description

Description A brief description of the action specified in the request.

Request Format

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.

Response 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 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.

Table 9-1 Requests Listed in this Chapter

Request Type Description

Page 135: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-3

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.

TipFor 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.

Page 136: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Add/Delete Condition RequestAdds and deletes Global conditions.

NoteBoth 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>

Page 137: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-5

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” Location of the schema.

version (1.0) 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

user_token Tracking ID assigned by the API.String.

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>

Page 138: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-6 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Example

For sample XML strings, see “Add Condition/Delete Condition Request” on page A-2.

condition 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>

Table 9-3 Add/Delete Condition XML Parameters Description (Part 2 of 2)

Parameter Description

Page 139: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-7

Responses

There are two possible responses to the request–one 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:errorctmem:major CDATA #REQUIREDctmem:minor CDATA #REQUIREDctmem:severity CDATA #REQUIRED><!ELEMENT ctmem:error_list (ctmem:error+)><!ATTLIST ctmem:error_listctmem:highest_severity CDATA #REQUIRED><!ELEMENT ctmem:status (#PCDATA)><!ELEMENT ctmem:response (ctmem:status, ctmem:error_list?)><!ATTLIST ctmem:responsectmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:message_package (ctmem:response)><!ATTLIST ctmem:message_package

Page 140: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-8 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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” Location of the schema.

version (1.0) 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>

Page 141: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-9

status Description of message content (for example, Error).

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.

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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

Example<ctmem:error ctmem:major=”404” ctmem:minor=”2” ctmem:severity=”Error”><ctmem:error_message>Add/Delete condition failed.</ctmem:error_message></ctmem:error>

Table 9-4 Add/Delete Condition Response XML Parameters Description (Part 2 of 3)

Parameter Description Valid Values

Page 142: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-10 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Errors

See “Add/Delete Condition Request Errors (Major Code 404)” on page B-17.

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>

Table 9-4 Add/Delete Condition Response XML Parameters Description (Part 3 of 3)

Parameter Description Valid Values

Page 143: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-11

Change Alert Status RequestChanges 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_packagexmlns:ctmem CDATA #IMPLIEDctmem:version (1.0) #REQUIRED><!ELEMENT ctmem:request (ctmem:alert_id, ctmem:status)><!ATTLIST ctmem:requestctmem:name CDATA #REQUIREDctmem: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">

Page 144: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-12 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

message_package 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” Location of the schema.

version (1.0) 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

user_token Tracking ID assigned by the API.String.

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

Table 9-5 Change Alert Status XML Parameters Description

Parameter Description Valid Values

Page 145: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-13

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:errorctmem:major CDATA #REQUIREDctmem:minor CDATA #REQUIREDctmem:severity CDATA #REQUIRED><!ELEMENT ctmem:error_list (ctmem:error+)><!ATTLIST ctmem:error_listctmem:highest_severity CDATA #REQUIRED><!ELEMENT ctmem:status (#PCDATA)><!ELEMENT ctmem:response (ctmem:status, ctmem:error_list?)><!ATTLIST ctmem:responsectmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:message_package (ctmem:response)><!ATTLIST ctmem:message_packagexmlns:ctmem CDATA #IMPLIEDctmem:version (1.0) #REQUIRED>

Page 146: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-14 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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”

Location of the schema.

version (1.0) 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>

Page 147: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-15

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>

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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

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>

Table 9-6 Change Alert Status Response XML Parameters Description (Part 2 of 2)

Parameter Description Valid Values

Page 148: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-16 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Errors

See “Alerts Request Errors (Major Code 408)” on page B-21.

Page 149: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-17

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.

Page 150: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-18 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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)>

Page 151: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-19

<!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)>

Page 152: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-20 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

<!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_packagexmlns:ctmem CDATA #IMPLIEDctmem: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)+>

Page 153: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-21

<!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:requestctmem:name CDATA #REQUIREDctmem:user_token CDATA #REQUIREDctmem: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)>

Page 154: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-22 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

<!ELEMENT ctmem:subject (#PCDATA)>

<!ELEMENT ctmem:sys_db (#PCDATA)><!ELEMENT ctmem:sysout_from_class (#PCDATA)><!ELEMENT ctmem:sysout_option (#PCDATA)><!ELEMENT ctmem:sysout_parameter (#PCDATA)><!ELEMENT ctmem:adjust_condition (#PCDATA)><!ELEMENT ctmem:system_affinity (#PCDATA)><!ELEMENT ctmem:table (#PCDATA)><!ELEMENT ctmem:group_id (#PCDATA)><!ELEMENT ctmem:task_type (#PCDATA)><!ELEMENT ctmem:task_class (#PCDATA)><!ELEMENT ctmem:time (#PCDATA)><!ELEMENT ctmem:time_due_out (#PCDATA)><!ELEMENT ctmem:time_from (#PCDATA)><!ELEMENT ctmem:time_reference (#PCDATA)><!ELEMENT ctmem:time_until (#PCDATA)><!ELEMENT ctmem:time_zone (#PCDATA)><!ELEMENT ctmem:to (#PCDATA)><!ELEMENT ctmem:to_procedure_step (#PCDATA)><!ELEMENT ctmem:to_program_step (#PCDATA)><!ELEMENT ctmem:type (#PCDATA)><!ELEMENT ctmem:urgency (#PCDATA)><!ELEMENT ctmem:value (#PCDATA)><!ELEMENT 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">

Page 155: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-23

message_package 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 Schema pathname or URL and filename.String.

version (1.0) 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

user_token The user token that was assigned during registration. String.Mandatory.

mode 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

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>

Table 9-7 Job Creation Request XML Parameters Description (Part 2 of 32)

Parameter Description

Page 156: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-24 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

active_job Specification for a single job. The parameters of the job are included as elements between the opening and closing active_job tags.• Contains no attributes.

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 – (Don’t 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 job’s 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 OracleApplications) Control Module (CM) that is installed in the CONTROL-Minstallation. 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 3 of 32)

Parameter Description

Page 157: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-25

application_version

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>

Table 9-7 Job Creation Request XML Parameters Description (Part 4 of 32)

Parameter Description

Page 158: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-26 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

autoedit_assignments

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>

Table 9-7 Job Creation Request XML Parameters Description (Part 5 of 32)

Parameter Description

Page 159: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-27

control_resources 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 6 of 32)

Parameter Description

Page 160: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-28 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

ctb_step 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 7 of 32)

Parameter Description

Page 161: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-29

cyclic 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 8 of 32)

Parameter Description

Page 162: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-30 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

in_condition 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 9 of 32)

Parameter Description

Page 163: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-31

job_name 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 10 of 32)

Parameter Description

Page 164: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-32 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

on_do_statement 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 11 of 32)

Parameter Description

Page 165: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-33

order_table 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 12 of 32)

Parameter Description

Page 166: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-34 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

out_condition 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:condition>Cond1</ctmem:condition>

date Specifies an order date for various condition formats.

Example: <ctmem:date>ODAT</ctmem:date>

sign Indicates whether to add or delete an Out conditionValid 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 13 of 32)

Parameter Description

Page 167: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-35

owner 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 14 of 32)

Parameter Description

Page 168: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-36 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

prevent_nct2 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 15 of 32)

Parameter Description

Page 169: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-37

request_nje 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 thejob. 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 16 of 32)

Parameter Description

Page 170: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-38 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

shout 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 17 of 32)

Parameter Description

Page 171: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-39

shouts 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 18 of 32)

Parameter Description

Page 172: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-40 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

step_range 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 19 of 32)

Parameter Description

Page 173: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-41

step_ranges 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 20 of 32)

Parameter Description

Page 174: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-42 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

sysout_option 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 (inJES3).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>

Table 9-7 Job Creation Request XML Parameters Description (Part 21 of 32)

Parameter Description

Page 175: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-43

task_type 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 22 of 32)

Parameter Description

Page 176: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-44 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

do_statements 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 23 of 32)

Parameter Description

Page 177: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-45

do_autoedit 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 24 of 32)

Parameter Description

Page 178: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-46 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

do_cond 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:condition>Cond1</ctmem:condition>

date Specifies an order date for various condition formats.

Example: <ctmem:date>ODAT</ctmem:date>

sign Indicates whether to add or delete an Out conditionValid 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 25 of 32)

Parameter Description

Page 179: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-47

do_forcejob 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 26 of 32)

Parameter Description

Page 180: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-48 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

do_ifrerun 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 27 of 32)

Parameter Description

Page 181: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-49

do_mail • 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>[email protected]</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>

Table 9-7 Job Creation Request XML Parameters Description (Part 28 of 32)

Parameter Description

Page 182: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-50 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

do_shout 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 29 of 32)

Parameter Description

Page 183: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-51

do_sysout 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• ChangeClassNote: 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 30 of 32)

Parameter Description

Page 184: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-52 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

on_statement 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 31 of 32)

Parameter Description

Page 185: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-53

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:errorctmem:major CDATA #REQUIREDctmem:minor CDATA #REQUIREDctmem:severity CDATA #REQUIRED>

on_statements 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>

Table 9-7 Job Creation Request XML Parameters Description (Part 32 of 32)

Parameter Description

Page 186: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-54 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

<!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_datactmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:response (ctmem:status, ctmem:response_data?, ctmem:jobs?, ctmem:error_list?)><!ATTLIST ctmem:responsectmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:message_package (ctmem:response)><!ATTLIST ctmem:message_packagexmlns:ctmem CDATA #IMPLIEDctmem: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">

Page 187: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-55

message_package Indicates to CONTROL-M/EM the beginning and end of the Order/Force Request XML specification. Order and force specificationsare placed between the opening and closingmessages_package tags. • Contains the ctmem attribute and the response element.

xmlns:ctmem 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>

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>

Parameter Description

Page 188: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-56 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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, 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.

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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

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>

Parameter Description

Page 189: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-57

jobs 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>

Parameter Description

Page 190: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-58 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Errors

Job creation errors are described in “Create Active Job Request Errors (Major Code 409)” on page B-22.

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)

• 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>

Parameter Description

Page 191: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-59

Order/Force RequestDoes 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.

NoteOrder 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)>

Page 192: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-60 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

<!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_packagexmlns:ctmem CDATA #IMPLIEDctmem: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:requestctmem:name CDATA #REQUIREDctmem:user_token CDATA #REQUIRED>

Page 193: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-61

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 specificationsare placed between the opening and closingmessages_package tags. • Contains the version and ctmem (schema) attributes.

xmlns:ctmem Schema pathname or URL and filename.String.

version (1.0) 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

user_token The user token that was assigned during registration. String.

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>

Page 194: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-62 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

force_it Indicates whether the job is ordered or forced.Mandatory for both jobs and Scheduling tables.

• 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.

Table 9-8 Order/Force XML Parameters Description

Parameter Description Valid Values

Page 195: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-63

name Name of the AutoEdit variable.Mandatory, if the autoedit_assighnment element is specified.

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>

Table 9-8 Order/Force XML Parameters Description

Parameter Description Valid Values

Page 196: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-64 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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:

Page 197: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-65

• 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:errorctmem:major CDATA #REQUIREDctmem:minor CDATA #REQUIREDctmem:severity CDATA #REQUIRED><!ELEMENT ctmem:error_list (ctmem:error+)><!ATTLIST ctmem:error_listctmem:highest_severity CDATA #REQUIRED><!ELEMENT ctmem:order_id (#PCDATA)><!ELEMENT ctmem:mem_name (#PCDATA)>

Page 198: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-66 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

<!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_datactmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:response (ctmem:status, ctmem:response_data?, ctmem:error_list?)><!ATTLIST ctmem:responsectmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:message_package (ctmem:response)><!ATTLIST ctmem:message_packagexmlns: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">

Page 199: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-67

message_package Indicates to CONTROL-M/EM the beginning and end of the Order/Force Request XML specification. Order and force specificationsare placed between the opening and closingmessages_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>

Table 9-9 Order/Force Response XML Parameters Description (Native API)

Parameter Description Valid Values

Page 200: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-68 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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, 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.

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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

Example<ctmem:error ctmem:major=”405” ctmem:minor=”4” ctmem:severity=”Error”><ctmem:error_message>No jobs were ordered. </ctmem:error_message></ctmem:error>

Table 9-9 Order/Force Response XML Parameters Description (Native API)

Parameter Description Valid Values

Page 201: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-69

error_message Text description of the error. For more information, see Appendix B, “Error Codes and Exceptions.”

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>

Table 9-9 Order/Force Response XML Parameters Description (Native API)

Parameter Description Valid Values

Page 202: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-70 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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>

mem_name Name of the file that contains the job script.

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>

Table 9-9 Order/Force Response XML Parameters Description (Native API)

Parameter Description Valid Values

Page 203: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-71

<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>

Page 204: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-72 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

</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>

Page 205: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-73

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=”404” ctmem:minor=”2” ctmem:severity=”Error”> <ctmem:error_message>Add/Delete condition failed.</ctmem:error_message> </ctmem:error></ctmem:error_list>

Table 9-10 Order/Force Response XML Parameters Description (Basic API)

Parameter Description Valid Values

Page 206: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-74 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

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>

Table 9-10 Order/Force Response XML Parameters Description (Basic API)

Parameter Description Valid Values

Page 207: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-75

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>

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>

Table 9-10 Order/Force Response XML Parameters Description (Basic API)

Parameter Description Valid Values

Page 208: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-76 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Errors

See the Table , “Order/Force Request Errors (Major Code 405),” on page B-18

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>

Table 9-10 Order/Force Response XML Parameters Description (Basic API)

Parameter Description Valid Values

Page 209: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-77

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_packagexmlns:ctmem CDATA #IMPLIEDctmem:version (1.0) #REQUIRED><!ELEMENT ctmem:request (ctmem:response_token)><!ATTLIST ctmem:requestctmem:name CDATA #REQUIREDctmem:user_token CDATA #REQUIRED><!ELEMENT ctmem:response_token (#PCDATA)>

Page 210: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-78 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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 Path or URL to schema definition files. String.

version (1.0) 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

user_token Serial number assigned to the user during registration.String.

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>

Page 211: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-79

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:errorctmem:major CDATA #REQUIREDctmem:minor CDATA #REQUIREDctmem:severity CDATA #REQUIRED><!ELEMENT ctmem:error_list (ctmem:error+)><!ATTLIST ctmem:error_listctmem:highest_severity CDATA #REQUIRED><!ELEMENT ctmem:status (#PCDATA)><!ELEMENT ctmem:response (ctmem:status, ctmem:error_list?)><!ATTLIST ctmem:responsectmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:message_package (ctmem:response)><!ATTLIST ctmem:message_packagexmlns:ctmem CDATA #IMPLIEDctmem:version (1.0) #REQUIRED>

Page 212: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-80 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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”

Location of the schema.

version (1.0) 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>

Page 213: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-81

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>

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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

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>

Table 9-12 Poll Response XML Parameters Description (Part 2 of 2)

Parameter Description Valid Values

Page 214: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-82 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Errors

See “Poll Request Errors (Major Code 403)” on page B-16.

Page 215: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-83

Timeout Reset RequestWhen a CONTROL-M/EM API user registers with CONTROL-M/EM, the user receives a user token that is in effect for a limited period of time.

The Timeout Reset request resets the registration timeout counter to zero. Timeout Reset requests can be sent intermittently to keep a user’s registration valid during lengthy sessions.

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_packagexmlns:ctmem CDATA #IMPLIEDctmem:version (1.0) #REQUIRED><!ELEMENT ctmem:request EMPTY><!ATTLIST ctmem:requestctmem:name CDATA #REQUIREDctmem:user_token CDATA #REQUIRED>

Page 216: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-84 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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 Schema pathname or URL and filename. String.

version (1.0) 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

user_token Serial identification number supplied to the user during registration. The user indicated by this number is the user. String.

Example<ctmem:request ctmem:name="client_keep_alive" ctmem:user_token="1234567"></ctmem:request>

Page 217: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-85

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:errorctmem:major CDATA #REQUIREDctmem:minor CDATA #REQUIREDctmem:severity CDATA #REQUIRED><!ELEMENT ctmem:error_list (ctmem:error+)><!ATTLIST ctmem:error_listctmem: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:responsectmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:message_package (ctmem:response)><!ATTLIST ctmem:message_packagexmlns:ctmem CDATA #IMPLIEDctmem:version (1.0) #REQUIRED>

Page 218: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-86 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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”

Location of the schema.

version (1.0) 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>

Page 219: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-87

user_token Unique ID that identifies the user. String.• Contained in the response element.

Example <ctmem:user_token>123456</ctmem:user_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>

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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

Example<ctmem:error ctmem:major=”404” ctmem:minor=”2” ctmem:severity=”Error”><ctmem:error_message>Add/Delete condition failed.</ctmem:error_message></ctmem:error>

Table 9-14 Timeout Reset Response XML Parameters Description (Part 2 of 3)

Parameter Description Valid Values

Page 220: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-88 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Errors

See “CONTROL-M/EM API Java Client Errors (Major Code 500)” on page B-23.

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>

Table 9-14 Timeout Reset Response XML Parameters Description (Part 3 of 3)

Parameter Description Valid Values

Page 221: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-89

Tracking RequestTracks 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_packagexmlns:ctmem CDATA #IMPLIEDctmem:version (1.0) #REQUIRED>

<!ELEMENT ctmem:jobs (ctmem:job+)><!ELEMENT ctmem:request (ctmem:jobs)><!ATTLIST ctmem:requestctmem:name CDATA #REQUIREDctmem:user_token CDATA #REQUIRED>

Page 222: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-90 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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 Schema pathname or URL and filename. String.

version (1.0) 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

user_token Serial identification number supplied to the user during registration. The user indicated by this number is the user. String.

Example<ctmem:request ctmem:name="job_track" ctmem:user_token="1234567"></ctmem:request>

Page 223: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-91

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">

jobs 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>

Table 9-15 Tracking Request XML Parameters Description (Part 2 of 2)

Parameter Description Valid Values

Page 224: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-92 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

<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:errorctmem:major CDATA #REQUIREDctmem:minor CDATA #REQUIREDctmem:severity CDATA #REQUIRED><!ELEMENT ctmem:error_list (ctmem:error+)><!ATTLIST ctmem:error_listctmem: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)>

Page 225: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-93

<!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:responsectmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:message_package (ctmem:response)><!ATTLIST ctmem:message_packagectmem: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>

Page 226: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-94 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

response 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>

Table 9-16 Tracking Request Response XML Parameters Description

Parameter Description Valid Values

Page 227: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-95

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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

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>

Table 9-16 Tracking Request Response XML Parameters Description

Parameter Description Valid Values

Page 228: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-96 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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: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>

Table 9-16 Tracking Request Response XML Parameters Description

Parameter Description Valid Values

Page 229: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-97

Errors

See “Tracking Request Errors (Major Code 406)” on page B-19.

Page 230: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-98 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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"?><!--user register request--><!ELEMENT ctmem:message_package (ctmem:request)><!ATTLIST ctmem:message_packagexmlns:ctmem CDATA #IMPLIEDctmem:version (1.0) #REQUIRED><!ELEMENT ctmem:request (ctmem:user_name, ctmem:password, ctmem:timeout?)><!ATTLIST ctmem:requestctmem:name CDATA #REQUIRED><!ELEMENT ctmem:user_name (#PCDATA)><!ELEMENT ctmem:password (#PCDATA)><!ELEMENT ctmem:timeout (#PCDATA)>

Page 231: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-99

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 Schema pathname or URL and filename. String.

version (1.0) 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

user_token Serial identification number supplied to the user during registration. The user indicated by this number is the user. String.

Example<ctmem:request ctmem:name="register" ctmem:user_token="1234567"></ctmem:request>

Page 232: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-100 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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>

user_name CONTROL-M/EM username of the person making the request.

String.

Examplectmem:user_name="emuser"

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.

String.

Examplectmem:password="empass"

timeout Indicates a length of time, in seconds, until the user’s 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.

Examplectmem:timeout="3600"

Table 9-17 Registration Request XML Parameters Description

Parameter Description Valid Values

Page 233: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-101

Response

EMAPI_registerResponse.dtd

<?xml version="1.0" encoding="UTF-8"?><!ELEMENT ctmem:error_message (#PCDATA)><!ELEMENT ctmem:error (ctmem:error_message)><!ATTLIST ctmem:errorctmem:major CDATA #REQUIREDctmem:minor CDATA #REQUIREDctmem:severity CDATA #REQUIRED><!ELEMENT ctmem:error_list (ctmem:error+)><!ATTLIST ctmem:error_listctmem: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:responsectmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:message_package (ctmem:response)><!ATTLIST ctmem:message_packagexmlns:ctmem CDATA #IMPLIEDctmem: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">

Page 234: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-102 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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”

Location of the schema.

version (1.0) 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>

Table 9-18 User registration Response XML Parameters Description (Part 2 of 3)

Parameter Description Valid Values

Page 235: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-103

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=”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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

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>

Table 9-18 User registration Response XML Parameters Description (Part 3 of 3)

Parameter Description Valid Values

Page 236: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-104 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Errors

See “Authorization Request Errors (Major Code 407)” on page B-20.

Page 237: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-105

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"?><!--user unregister request--><!ELEMENT ctmem:message_package (ctmem:request)><!ATTLIST ctmem:message_packagexmlns:ctmem CDATA #IMPLIEDctmem:version (1.0) #REQUIRED><!ELEMENT ctmem:request EMPTY><!ATTLIST ctmem:requestctmem:name CDATA #REQUIREDctmem: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">

Page 238: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-106 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

<?xml ?> 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.

encoding The character set used in the XML file. Valid value: UTF-8

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.dtdNote: 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">

Table 9-19 Unregistration Request XML Parameters Description

Parameter Description Valid Values

Page 239: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-107

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">

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 Schema pathname or URL and filename. String.

version (1.0) 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

user_token Serial identification number supplied to the user during registration. The user indicated by this number is the user. String.

Example<ctmem:request ctmem:name="unregister" ctmem:user_token="1234567"></ctmem:request>

Table 9-19 Unregistration Request XML Parameters Description

Parameter Description Valid Values

Page 240: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-108 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

<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:errorctmem:major CDATA #REQUIREDctmem:minor CDATA #REQUIREDctmem:severity CDATA #REQUIRED><!ELEMENT ctmem:error_list (ctmem:error+)><!ATTLIST ctmem:error_listctmem: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:responsectmem:request_name CDATA #REQUIRED><!ELEMENT ctmem:message_package (ctmem:response)><!ATTLIST ctmem:message_packagexmlns:ctmem CDATA #IMPLIEDctmem:version (1.0) #REQUIRED>

Page 241: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-109

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”

Location of the schema.

version (1.0) 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>

Page 242: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-110 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

user_token Unique ID that identifies the user. String.• Contained in the response element.

Example <ctmem:user_token>123456</ctmem:user_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=”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.”

minor 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.”

severity The priority level assigned to the error by the CONTROL-M/EM API. String.For more information, see Appendix B, “Error Codes and Exceptions.”

Example<ctmem:error ctmem:major=”407” ctmem:minor=”4” ctmem:severity=”Error”><ctmem:error_message>Unregister failed.</ctmem:error_message></ctmem:error>

Table 9-20 User Unregistration Response XML Parameters Description (Part 2 of 3)

Parameter Description Valid Values

Page 243: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Reference 9-111

Errors

See “Authorization Request Errors (Major Code 407)” on page B-20.

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>

Table 9-20 User Unregistration Response XML Parameters Description (Part 3 of 3)

Parameter Description Valid Values

Page 244: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

9-112 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Page 245: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Format Examples A-1

A

Request Format Examples A

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.”

Page 246: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

A-2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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>

Page 247: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Format Examples A-3

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>

Page 248: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

A-4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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>

Page 249: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Format Examples A-5

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>

Page 250: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

A-6 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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>

Page 251: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Format Examples A-7

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>

Page 252: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

A-8 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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>

Page 253: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Format Examples A-9

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>

Page 254: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

A-10 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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>

Page 255: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Request Format Examples A-11

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>

Page 256: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

A-12 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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>

Page 257: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-1

B

Error Codes and Exceptions B

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.

NoteIn 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.

Page 258: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

• 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 Description

FATAL 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.

ERROR Displays messages for fatal and non-fatal errors.

WARN Displays warning messages and all error messages.

Page 259: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-3

INFO Displays system information, warnings, and all errors.

DEBUG Displays debugging information and all other priority messages.

Table B-1 Log Message Priority Levels (Part 2 of 2)

Level Description

Page 260: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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 Title For Error Descriptions, see

000 NULL Exception “NULL Exception Errors (Major Code 000)” on page B-6

100 Low-level API Exceptions “Low-level API Exceptions (Major Code 100)” on page B-7

200 Parser Exceptions “Parser Exceptions (Major Code 200)” on page B-8

300 CONTROL-M Server Errors Note: Category contains no individual errors.

300 CONTROL-M Server Errors: Group1

“CONTROL-M/Server Errors: Group 1 (Major Code 300)” on page B-9

301 CONTROL-M Server Errors: Group 2

“CONTROL-M/Server Errors: Group 2 (Major Code 301)” on page B-12

302 CONTROL-M Server Errors: Group 3

“CONTROL-M/Server Errors: Group 3 (Major Code 302)” on page B-14

400 CONTROL-M/EM API Request Exceptions

Note: Category contains no individual errors.

401 Generic Request Exceptions “Generic Request Exceptions (Major Code 401)” on page B-15

403 Poll Request “Poll Request Errors (Major Code 403)” on page B-16

404 Add/Delete Condition Request “Add/Delete Condition Request Errors (Major Code 404)” on page B-17

405 Order/Force Request “Order/Force Request Errors (Major Code 405)” on page B-18

Page 261: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-5

406 Job Tracking Request “Tracking Request Errors (Major Code 406)” on page B-19

407 Authorization Request “Authorization Request Errors (Major Code 407)” on page B-20

408 Alerts Request “Alerts Request Errors (Major Code 408)” on page B-21

409 Create Active Job Request “Create Active Job Request Errors (Major Code 409)” on page B-22

500 CONTROL-M/EM API Java Client

“CONTROL-M/EM API Java Client Errors (Major Code 500)” on page B-23

600 Gateway Messages “Gateway Messages (Major Code 600)” on page B-24

Table B-2 Error and Exception Major Codes (Part 2 of 2)

Code Title For Error Descriptions, see

Page 262: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-6 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

NULL Exception Errors (Major Code 000)

Summary: CONTROL-M/EM API has generated an undefined error.

Table B-3 NULL Exceptions

Minor Code Severity Description

0 ERROR CONTROL-M/EM API has generated an undefined error.

Page 263: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-7

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 Severity Description

1 ERROR Error on preliminary parsing of the XML

2 FATAL Catastrophic exception on server.

3 ERROR Error: <value> Tag missing.

4 ERROR Invalid Request. Request name: <value>

5 FATAL Could not obtain response from repository.

6 ERROR Undefined exception on server.

Page 264: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-8 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Parser Exceptions (Major Code 200)

Summary: Error occured when parsing an XML file.

Table B-5 Parser Exceptions

Minor Code Severity Description

1 FATAL Parser Initialization Failure.

2 ERROR Error while parsing XML: <value>

3 FATAL Internal Parser Error: <value>

4 FATAL Internal Parser Error: Undefined Exception

Page 265: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-9

CONTROL-M/Server Errors: Group 1 (Major Code 300)

Summary: Errors generated by the CONTROL-M installation.

Table B-6 CONTROL-M/Server Errors: Group 1 (Part 1 of 3)

Minor Code Severity Description

0 ERROR Internal Server Error on Control/M.

3 ERROR Control/M Error: <value> .

5 ERROR Storage allocaton failed for CTM/EM Gateway.

7 ERROR Cannot open conditions file.

9 ERROR Loading of Control-M Parameters failed.

18 ERROR Internal error on GETMEM.

19 ERROR DSN not in catalog.

20 ERROR DSN - dynamic allocation failed.

21 ERROR Internal error. Invalid request to CTMMEM.

22 ERROR Maximum number of members/lines in member exceeded.

23 ERROR Invalid return code from CTMMEM.

24 ERROR Error while processing directory of library.

25 ERROR Library operation failed.

40 ERROR Cannot open print file.

42 ERROR Open of IOA log file failed .

45 ERROR Internal Error on IOACND.

46 ERROR Invalid date format.

47 ERROR Cannot open synchronization file.

48 ERROR Internal Server Error on Control/M.

49 ERROR Internal Server Error on Control/M.

51 ERROR Cannot add the condition because it already exists.

52 ERROR Cannot add the condition because the condition file is full.

53 ERROR Cannot add the control resource because it already exists.

54 ERROR Cannot add the control resource because the resource file is full.

Page 266: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-10 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

55 ERROR Cannot delete the condition because it does not exist.

56 ERROR Cannot delete the quantitative resource because it is in use.

57 ERROR Cannot add the quantitative resource because the resource file is full.

58 ERROR Cannot add the quantitative resource because it already exists.

59 ERROR Cannot delete the quantitative resource because it does not exist.

60 ERROR Change command can only be issued against quantitative resources

61 ERROR Invalid value in sign field.

62 ERROR The value in a change command must be between 1-9999.

63 ERROR Cannot load module (internal error).

64 ERROR The requested table does not exist in the library.

70 ERROR The requested job does not exist in the given table.

87 ERROR Invalid date.

90 ERROR Table/Member doesn’t exist.

91 ERROR Table/Member already exists.

93 ERROR Invalid Group ID.

94 ERROR The ’NEWG’ order option is not supported in this version.

95 ERROR The group entity specified was not found in the AJF.

96 ERROR Failed to extract data from CTM/EM message.

97 ERROR Failed to delete records from table.

98 ERROR Insert into table failed.

99 ERROR Update table failed.

100 ERROR Failed to commit transaction.

101 ERROR The filed GROUP is mandatory for a group entity.

102 ERROR GROUP and JOBNAME should be the same for group entity.

103 ERROR GROUP and SCHEDTAB should be the same for group entity.

104 ERROR GROUP and SCHEDTAB should be specified.

105 ERROR The group specified does not exist in the database.

106 ERROR MEMLIB, CMDLINE, MEMNAME AND OVERLIB should not be specified.

Table B-6 CONTROL-M/Server Errors: Group 1 (Part 2 of 3)

Minor Code Severity Description

Page 267: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-11

107 ERROR Failed to allocate ISN.

108 ERROR No nodes found in node group.

109 ERROR Failed to get next node in node group.

110 ERROR Failed to setup application type for NODEGRP, MEMNAME and OVERLIB should not be specified.

111 ERROR Invalid ODATE.

Table B-6 CONTROL-M/Server Errors: Group 1 (Part 3 of 3)

Minor Code Severity Description

Page 268: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-12 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

CONTROL-M/Server Errors: Group 2 (Major Code 301)

Summary: Errors generated by the CONTROL-M installation.

Table B-7 CONTROL-M Server Errors: Group 2 (Part 1 of 2)

Minor Code Severity Description

501 INFO The job has been sucesfully ordered

502 ERROR Unabled to open the specified scheduling library.

506 ERROR Scheduling failed for member.

510 ERROR Scheduling member contains invalid data.

512 WARN Library should be compressed.

514 ERROR Job was not ordered. Reason: Insufficient storage.

515 ERROR Job contains too many cards.

516 ERROR Scheduling table error: First card is not a D statement.

517 ERROR The specified library is empty.

524 ERROR Ordering proccess has entered with errors.

525 ERROR Ordering proccess ended successfully.

526 ERROR Invalid data format.

528 INFO Job has been succesfully ordered.

531 ERROR Ordering process was canceled by an user exit.

532 ERROR Cannot open the CTM/EM active jobs file.

534 ERROR Cannot open the AJF - AJF is corrrupted, I/O error, or file is not really AJF.

535 ERROR Cannot order a job while AJF is being formatted.

536 ERROR Severe error in scheduling definition.

537 ERROR The job order contains more information than what the CTM/EM can handle.

548 ERROR The calendar specified in the job is either corrupted or invalid.

549 WARN CONTROL-R is not installed. IFRERUN statement ignored.

550 WARN CONTROL-R is not installed. SET statement ignored.

Page 269: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-13

166 ERROR The job contains a condition with a PREV/NEXT date that cannot be interpreted by CTM/EM.

169 INFO The CTM/EM has finished handling the request. No jobs were scheduled.

Table B-7 CONTROL-M Server Errors: Group 2 (Part 2 of 2)

Minor Code Severity Description

Page 270: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-14 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

CONTROL-M/Server Errors: Group 3 (Major Code 302)

Summary: Errors generated by the CONTROL-M installation.

Table B-8 CONTROL-M Server Errors: Group 3

Minor Code Severity Description

129 ERROR User exit not loaded.

540 ERROR Security exit not loaded. Security checking will be bypassed.

863 WARN The AJF is nearly full.

Page 271: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-15

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 Severity Description

1 ERROR Could not connect to Control-M.

2 ERROR Invalid Control-M.

3 ERROR Invalid response from Control-M.

4 ERROR Internal Error: <value> .

Page 272: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-16 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Poll Request Errors (Major Code 403)

Summary: Errors generated when a Polling request fails.

Table B-10 Poll Request Errors

Minor Code Severity Description

1 ERROR Error: Invalid token supplied.

Page 273: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-17

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 Severity Description

1 ERROR Add/Delete condition failed (code %d).

2 ERROR Add/Delete condition failed.

3 ERROR Add/Delete condition aborted.

4 ERROR Add/Delete condition timed out.

5 ERROR Add condition failed.

6 ERROR Add condition failed (code %d).

7 ERROR Add condition failed, invalid option.

8 ERROR Delete condition failed.

9 ERROR Delete condition failed (code %d).

10 ERROR Delete condition failed, invalid option.

11 ERROR Condition’s name is not valid.

12 ERROR Condition’s order date is not valid.

13 ERROR Cannot Add/Delete condition, already in desired state.

Page 274: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-18 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Order/Force Request Errors (Major Code 405)

Summary: Errors generated when an Order request or Force request fails.

Table B-12 Order/Force Request Errors

Minor Code Severity Description

1 ERROR Order request didn’t pass validity checks. Error: <value>

2 ERROR Group RBA not found for Group ID <value> .

3 ERROR Order request failed in the server.

4 ERROR No jobs were ordered.

Page 275: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-19

Tracking Request Errors (Major Code 406)

Summary: Errors generated when a Tracking request fails.

Table B-13 Job Tracking Request Errors

Minor Code Severity Description

1 ERROR Job was not found in the last AJF.

2 ERROR Required Job information doesn’t exist in the database

3 ERROR Tracked Job failed in validity checks.

Page 276: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-20 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Authorization Request Errors (Major Code 407)

Summary: Errors generated when a registration or unregistration request fails.

Table B-14 Authorization Request Errors

Minor Code Severity Description

1 ERROR Invalid user token.

2 ERROR Invalid user name.

3 ERROR Register failed.

4 ERROR Unregister failed.

5 ERROR User not authorized.

Page 277: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-21

Alerts Request Errors (Major Code 408)

Summary: Errors generated when a Change Alert Status request fails.

Table B-15 Alerts Request Errors

Minor Code Severity Description

1 ERROR Alert id is not valid.

2 ERROR Invalid alert operation.

Page 278: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-22 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Create Active Job Request Errors (Major Code 409)

Summary: Errors generated when a Job Creation request fails.

Table B-16 Create Active Job Request Errors

Minor Code Severity Description

1 ERROR Create active job failed (code: %d).

2 ERROR Create active job failed.

3 ERROR Create active job failed, object is in use.

4 ERROR Create active job failed, object not found.

5 ERROR Create active job failed, invalid option.

6 ERROR Create active job validation error: ’ <value> ’.

7 ERROR Scheduling group is not valid for this data-center version

8 ERROR Failed to initialize job descriptor

9 ERROR Create active job, invalid order date.

Page 279: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-23

CONTROL-M/EM API Java Client Errors (Major Code 500)

Summary: Errors generated by the Java API.

Table B-17 CONTROL-M/EM API Java Client Errors

Minor Code Severity Description

1 ERROR Fatal error.

2 ERROR Null XML document - nothing to do.

3 ERROR Failed to establish connection with server - no server registered under this hostname.

4 ERROR Failed to resolve server name - please check your hostname.

5 ERROR Failed to establish connection with server - not a valid component type, check your hostname.

6 ERROR failed resolving XMLInvoker interface.

7 ERROR Failed to establish connection with server - check your connection with the locator.

8 ERROR Failed to establish connection with - check your orbix configuration.

9 ERROR Properties file not found.

10 ERROR Failed to read properties file.

101 ERROR Invoke timeout - no response after.

102 ERROR Invoke request exited because a InterruptedException occurred.

111 ERROR Response format is not valid.

112 ERROR Response format is not valid. Cannot find tag.

131 ERROR XML format is not valid.

132 ERROR Request format is not valid.

133 ERROR Can’t find user token.

140 ERROR

141 ERROR Undefined Exception on Parser.

Page 280: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-24 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Gateway Messages (Major Code 600)

Summary: Errors generated by the gateway.

Table B-18 Gateway Messages (Part 1 of 9)

Minor Code Severity Description

1 ERROR User Request timed out

2 ERROR No network currently loaded

3 ERROR No nodes match the Show Net parameters

4 ERROR Net too large to be fully viewed. Some nodes will be missing

5 ERROR Database login failed three times

6 ERROR At least one state must be chosen

7 ERROR At least one status must be chosen

8 ERROR At least one task type must be chosen

9 ERROR No events found for current net

10 ERROR Field <value> Wrong Format: <value>

11 ERROR Cannot load Active Network: No data center

12 ERROR Field <value> is required

13 ERROR Net Load aborted, probably not enough memory

14 ERROR No nodes match the Load Net Parameters

15 ERROR Error while reading job-record from database

16 ERROR Nothing changed since last save

17 ERROR Nothing changed

18 ERROR Cannot save file <value>

19 ERROR Confirm <value> for <value>

20 ERROR Do you really want to quit <value> ?

21 ERROR In a critical job, parameter ’Priority’ must begin with

22 ERROR Field <value> contains an invalid value

23 ERROR Field <value> must be between %d and %d

24 ERROR Field Rerun Mem Cannot be used if field Task Type is Cyclic

Page 281: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-25

25 ERROR Field <value> has an invalid value starting at position: <value>

26 ERROR Field <value> may not contain embedded spaces

27 ERROR Cannot clear Demo Net <value>

28 ERROR Cannot create Demo Net <value>

29 ERROR Cannot copy Demo Net <value>

30 ERROR Couldn’t open user view

31 ERROR Do you really want to erase the entire <value> Net <value>

32 ERROR Do you really want to clear the entire <value> Net <value>

33 ERROR Cannot append, Owner of <value> is <value>

34 ERROR Cannot open <value>

35 ERROR Missing file <value>

36 ERROR Unable un-mount diskette in <value>

37 ERROR Unable to mount diskette in <value>

38 ERROR Incorrect path <value>

39 ERROR Files downloaded from incompatible version <value> (should be <value>)

40 ERROR Cannot open file <value>

41 ERROR Missing <value> line

42 ERROR Unknown line: <value>

43 ERROR Cannot write to file <value>

44 ERROR File <value> exists. Ok to overwrite ?

45 ERROR Net <value> does not exist

46 ERROR Copy from file to file not allowed

47 ERROR Database job update failed

48 ERROR Database select failed for resource events

49 ERROR Database select failed for override table, simulation stopped

50 ERROR No current net

51 ERROR No nodes were found

52 ERROR No more nodes were found Go Back ?

Table B-18 Gateway Messages (Part 2 of 9)

Minor Code Severity Description

Page 282: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-26 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

53 ERROR No more nodes were found

54 ERROR You are not authorized to perform this action

55 ERROR If Field <value> (Days/Week days Calendar) begins with ALL then the rest of the parameter must be blank

56 ERROR Field Days Calender is required if field <value> contains the value: <value>

57 ERROR Field Week Calender is required if field <value> contains the value: <value>

58 ERROR Field Days has an invalid value starting at position: <value>; There should be a comma there

59 ERROR Discard changes made in form ?

60 ERROR Change of calendar type destroys existing data. Proceed ?

61 ERROR Change of data center platform destroys existing data. Proceed ?

62 ERROR Data center unknown, please re-enter value

63 ERROR Reading calendar failed - database problems

64 ERROR Calendar is already in use by user <value>, try later

65 ERROR Calendar write failed - database problems

66 ERROR Unknown platform. Verification of data will default to MVS. Do you want to continue?

67 ERROR Calendar was modified. Proceed with download ?"

68 ERROR Calendar <value> was downloaded successfully from data center <value>"

69 ERROR Calendar <value> was deleted successfully from data center <value>"

70 ERROR Calendar is in use by user <value>, and cannot be deleted"

71 ERROR Confirm Calendar Delete"

72 ERROR Confirm Calendar Upload"

73 ERROR Forced Calendar Upload will override calendar content in data center Proceed ?"

74 ERROR You are not authorized to access the Calendar List window

75 ERROR Filed <value> must be specified if field <value> is File, New Dest or Change Class

Table B-18 Gateway Messages (Part 3 of 9)

Minor Code Severity Description

Page 283: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-27

76 ERROR Attempt to enter conflicting conditions

77 ERROR Field <value> may only be used with the Change Class option

78 ERROR Field <value> is too long

79 ERROR Field Sign may not be + if the ODATE field value is **** or $$$$

80 ERROR Unknown or disabled Platform! Form will be opend as MVS!

81 ERROR In a critical job, field Priority must begin with *

82 ERROR Field Command Line may be specified only if Task Type is Command

83 ERROR Field should be %d char(s) long for this Sysout option

84 ERROR Field <value> cannot be used if Task Type is <value>

85 ERROR Field <value> cannot specify GENREAL or USER=

86 ERROR Fields Parm and From Class must be specified if field Option is Change Class

87 ERROR Field Parm must be specified if field Option is New Dest or File

88 ERROR Field Confirmation Cal cannot be used with fields PDS Name or Minimum

89 ERROR Field Months cannot be used with fields PDS Name, Minimum or Dates

90 ERROR Field Dates cannot be used with parameters PDS Name, Minimum, Months, Days, or Days Calendar

91 ERROR Field Dates cannot be used with fields Week Days, Weeks Days Calender Confirmation Cal

92 ERROR If Field PDS Name is specified then Minimum must be specified and vice versa

93 ERROR Field Priority must begin with * or an alphanumeric character

94 ERROR Field Priority must begin with an alphanumeric character

95 ERROR Field <value> is required if Task Type is:<value>

96 ERROR A job with the same name already exists in this table

97 ERROR If Field Retro is specified then PDS Name and Minimum cannot be used

98 ERROR The fields Days and Week Days Calendar cannot both be specified

99 ERROR The Field <value> must contain a numeric value or 0

100 ERROR Fields Rerun Mem and Max Rerun cannot be used if field Task Type is Cyclic

Table B-18 Gateway Messages (Part 4 of 9)

Minor Code Severity Description

Page 284: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-28 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

101 ERROR Field Dates must be specified in format nnnn or nnnn,nnnn,...

102 ERROR Scheduling table is already in use by user <value>, try later

103 ERROR Scheduling table write failed - database problems

104 ERROR Scheduling table should be uploaded before order/force

105 ERROR Field <value> is required

106 ERROR If Field <value> is *??????? Then field <value> must be blank

107 ERROR Table was modified. Proceed with download ?

108 ERROR Table was modified. Proceed with order ?

109 ERROR Table was modified. Proceed with force ?

110 ERROR Definition table <value> was downloaded successfully from data center <value>

111 ERROR Definition table <value> was deleted successfully from data center <value>

112 ERROR Confirm Table Delete

113 ERROR Confirm Table Upload

114 ERROR Forced Table Upload will override table content in data center Proceed ?

115 ERROR You are not authorized to access the Scheduling Tables window

116 ERROR Scheduling table is in use by user <value>, and cannot be deleted

117 ERROR Field <value> must be blank if field <value> is OK or NOTOK or RERUN

118 ERROR Communication with WS-Gateway stopped, all requests were canceled

119 ERROR System Error in <value>: Command <value> failed; <value>

120 ERROR No communication with WS-Gateway. Request cancelled

121 ERROR <value> not possible, no communication with Gateway

122 ERROR <value> not possible, Unknown data center <value>

123 ERROR <value> not possible, data center <value> not available

124 ERROR Communication with data center <value> down, all requests canceled

125 ERROR Data center <value> is suspended (AJF is being formatted)

126 ERROR Data center <value> is suspended (Download in Netgroup)

Table B-18 Gateway Messages (Part 5 of 9)

Minor Code Severity Description

Page 285: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-29

127 ERROR Data center <value> is suspended (AJF is being formatted), all requests canceled

128 ERROR Invalid event %c received from data center <value>. To ensure database integrity, WS-GTW stop/restart is recommended

129 ERROR The host name be specified only for the TCP protocol

130 ERROR The host name may contain only Alphanumerics and periods

131 ERROR You must specify a communication protocol

132 ERROR Specified communication protocol not supported on platform

133 ERROR Control-R not supported on platform

134 ERROR The Net Group field must contain two alpha numeric characters

135 ERROR CONTROL-M must be 300 or 400 for MVS

136 ERROR Incorrect CONTROL-M version specified for this platform

137 ERROR Scheduling table read failed - database problems

138 ERROR Please verify that all users have quit CONTROL-M/EM and that the WS-Gateway is down.

139 ERROR Do you really want to quit CONTROL-M/Enterprise Manager Administration ?

140 ERROR No Net

141 ERROR Number of nodes in a row exceeds maximum of %d

142 ERROR Cannot generate report due to insufficient memory

143 ERROR Cannot print links: <value>

144 ERROR Cannot print index: <value>

145 ERROR Cannot do poster for routed net

146 ERROR Job Report Fields saved. Please close and open the job report window

147 ERROR New Field is empty

148 ERROR Confirm delete

149 ERROR No Loaded Networks Available

150 ERROR Control Resources with <value> <value> cannot be <value>

151 ERROR Quantitative Resources with <value> <value> cannot be <value>

Table B-18 Gateway Messages (Part 6 of 9)

Minor Code Severity Description

Page 286: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-30 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

152 ERROR Field Author must be entered

153 ERROR Order ID <value> not found

154 ERROR Pattern <value> not found in text

155 ERROR Pattern <value> appears only once in the text

156 ERROR Problems searching for pattern <value>

157 ERROR Alarm handling command ignored. User <value> is handling this alarm now

158 ERROR Alarm handling command ignored. Internal error

159 ERROR Download of calendar <value> canceled in gateway - calendar in use

160 ERROR Download of calendar <value> canceled in gateway - Another download is currenlty in progress - Try later

161 ERROR Upload of calendar <value> canceled in gateway

162 ERROR Upload of calendar <value> canceled in gateway - calendar in use

163 ERROR Upload of definitions table <value> canceled in gateway

164 ERROR Upload of definitions table <value> canceled in gateway - table in use

165 ERROR Download of definition table <value> canceled in gateway - table in use

166 ERROR Download of definition table <value> canceled in gateway - Another download is currenlty in progress - Try later

167 ERROR Definitions table deleted on data center but delete failed on workstation (rc 1)

168 ERROR Definitions table deleted on data center but delete failed on workstation (rc 2)

169 ERROR Calendar deleted on data center but delete failed on workstation (rc 2)

170 ERROR Delete of definitions table <value> canceled in gateway - table in use

171 ERROR Delete of calendar <value> canceled in gateway - calendar in use

172 ERROR User request canceled in gateway, no answer from data center (time-out)

173 ERROR Download of <value> canceled, no answer from data center (time-out)

174 ERROR Download of <value> canceled in gateway

173 ERROR Download canceled, no answer from data center (time-out)

174 ERROR Download canceled in gateway

Table B-18 Gateway Messages (Part 7 of 9)

Minor Code Severity Description

Page 287: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Error Codes and Exceptions B-31

175 ERROR Upload canceled in gateway

176 ERROR Upload canceled (file transfer error (rcp) in gateway), consult system administrator

177 ERROR Information request canceled in gateway, system error (fopen failed), consult system administrator

178 ERROR Information request canceled (time-out) in gateway, no answer from data center

179 ERROR Upload of <value> canceled (time-out), no answer from data center

180 ERROR Upload of <value> canceled in gateway

179 ERROR Upload canceled (time-out), no answer from data center

180 ERROR Upload canceled in gateway

181 ERROR No fields defined

182 ERROR Field <value> not in table

182 ERROR Field not in table

183 ERROR Internal error on Field <value>

183 ERROR Internal error on field

184 ERROR Cannot print %d characters; Maximum of %d allowed

185 ERROR Cannot print more than %d fields

186 ERROR You are not authorized to load an active network

187 ERROR <value> was not found in data center. Delete in workstation ?

188 ERROR You are not authorized to access the Global Conditions window

189 ERROR Definition table <value> was deleted only on workstation

190 ERROR Calendar <value> was deleted only on workstation

191 ERROR Internal error. Action failed

192 ERROR Insert failed. Record with same key already exists.

193 ERROR Record deleted in the meantime.

194 ERROR Error message <value> Received from data center <value>.

194 ERROR Error message received from data center.

195 ERROR Field <value> is required if field <value> is defined

Table B-18 Gateway Messages (Part 8 of 9)

Minor Code Severity Description

Page 288: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

B-32 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

195 ERROR Field required.

196 ERROR Field <value> should be at most %d characters

197 ERROR Field <value> may not contain the characters <value>

198 ERROR Field <value> must be between <value> and <value>

199 ERROR Field <value> should be empty

200 ERROR Field <value> must be blank if field When is OK or NOTOK or RERUN

201 ERROR Field <value> must be <value>

202 ERROR No response to hartbeat check from data center: <value>

202 ERROR No response to hartbeat check from data center.

203 ERROR Unsuported version <value> of data center <value>. Check CTM installation

203 ERROR Unsuported version of data center, check CTM installation.

204 ERROR Not the smallest ISN for ordered/forced job

Table B-18 Gateway Messages (Part 9 of 9)

Minor Code Severity Description

Page 289: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Glossary 1

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.

Alert 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.

CONTROL-M 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.

CONTROL-M/Enterprise Manager or CONTROL_M/EM

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.

Page 290: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

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.

CORBA An architecture for creating, distributing, and managing program objects across distributed computers.

Gateway 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.

Global Alerts Server 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 Java is an object-oriented programming language for use in a distributed computing environment.

Job Processing Definition

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.

Prerequisite Conditions or Conditions

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.

Response Text string returned by CONTROL-M/EM containing status information regarding the request for which it is returned.

Page 291: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Glossary 3

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.

Page 292: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Page 293: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Index 1

Index

Index

Symbols.dtd files.See validation files

Aaccessing

Global Alerts Server 2-6GUI Server 2-6Orbix Locator 2-6

actions in CONTROL-M/EM API session 4-15

activating project 3-6Add Condition request

description 9-4errors B-17polling requirement 4-11response 9-7

addingconditions 9-4directory pathnames to CLASSPATH

2-6advantages

to EMBasicXMLInvoker 4-9to EMXMLInvoker 4-11

alertschanging status 9-11

errors in changing status B-21analyzing response strings 5-12application runtime 7-11Authorization request errors B-20

Ccalls

EMXMLInvoker 4-15Change Alert Status request

description 9-11errors B-21response 9-13

choosing a CONTROL-M/EM API class 4-7classes

choosing 4-7ComponentType 8-3EMBasicXMLInvoker 8-4EMXMLInvoker 8-9GASComponent 8-18GSRComponent 8-21in response strings 5-2list 8-1sample 3-3

CLASSPATHadding directory pathnames 2-6omissions 7-6

Page 294: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

2 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

orbix2000.cfg file 6-5troubleshooting 7-6

com.bmc.ctmem.emapi.XMLDATAPATH property 4-14

communicationerrors B-24

ComponentType class 8-3conditions

errors in adding B-17errors in deleting B-17

configuration files 2-6configuring

CONTROL-M/EM API 3-1differences between platforms 2-5environment 7-6log file 7-3polling timeout 6-8project environment 3-1script 2-6setPollRequestIntervalMilli 6-8setPollRequestTimeoutMilli 6-8

CONTROL-M supported versions 2-1CONTROL-M/EM

internal errors B-9primary subdirectories 2-4

CONTROL-M/EM APIadding directory pathnames to

CLASSPATH 2-6configuration files 2-6configuration script 2-6configuring 3-1how it works 1-2importing into project 3-3initializing 1-2initializing services 4-15mandatory program actions 4-1operating system support 2-2operations description 1-3platform support 2-2primary subdirectories 2-5

recommended users of this Guide 1-3software requirements 2-1stoppng services 4-15support for CONTROL-M versions 2-1supported CONTROL-M/EM

components 1-2uncompressing installation files 2-4untarring installation files 2-4

CONTROL-M/EM API sessionflow of actions 4-15starting and stopping services 4-15

CONTROL-M/EM componentspecifying in a request call 4-16, 4-21

CONTROL-M/EM passwordencoding 4-2

CONTROL-M/Enterprise Manager API. See CONTROL-M/EM API

CONTROL-M/Enterprise Manager. See CONTROL-M/EM

CONTROL-M/Servercommunication errors B-15

CONTROL-M/Server errors B-9, B-12conventions,document xixCORBA

advanced implementation 6-1description 6-2initializing processes 1-2Orbix domain initialization failure 7-10

CORBA parameterspassing to project 3-6

CORBA processesinitializing 4-15

CORBA propertiesmodifying 6-1

creatingemapi_log.cfg file 7-2EMXMLInvoker calls 4-15EMXMLInvoker class request calls 4-15Group Scheduling tables 9-17jobs in Group Scheduling tables 9-17

Page 295: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Index 3

regular jobs 9-17XML strings 8-1

ctmemapi.properties 2-6ctmemapi.properties file 3-2, 7-11

component hostnames 4-18, 4-22

DDEBUG severity level 7-3, B-3debugging

severity levels 7-3, B-2using Log4J 7-1

Delete Condition requestdescription 9-4errors B-17polling requirement 4-11response 9-7

deleting conditions 9-4determining

job status 5-1location of validation files 4-14polling status 5-1request status 5-1

development environment 3-1differences

between EMBasicXMLInvoker and EMXMLInvoker 4-7

between the native and basic APIs 4-7directories

missing 7-6of the CONTROL-M/EM API 2-5

disadvantagesto EMBasicXMLInvoker 4-9to EMXMLInvoker 4-11

document conventions xixdone method

primary listing 8-10stopping API services 4-16

Eemapi_env.bat file 3-2, 3-6emapi_env.sh file 3-2, 3-6emapi_log.cfg file 7-2emapi-610-nt.zip file 2-4emapi-admin.bat file 2-6emapi-admin.sh file 2-6emapi-configure file 2-6emapi-configure.exe file 2-6emapi-env.bat file 2-6emapi-env.sh file 2-6EMAPIMessages.txt file B-1EMBasicXMLInvoker

derived methods 8-4description 8-4invoking 4-23response handling 4-7when to use 4-9

EMXMLInvokercalls 4-15derived methods 8-9invoking 4-18polling 4-20polling requirement 4-11response handling 4-7when to use 4-11

encodePassword method 8-11encoding

with encodePassword method 8-11encoding password in session 4-2environment

setting variables 3-6solving problems 7-6

error codeslist of Major Codes B-4Major Code (defined) B-1Minor Code (defined) B-2reference B-4

ERROR severity level 7-3, B-2

Page 296: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

4 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

errorsActive Jobs file B-12adding conditions B-17application runtime 7-11authorizations B-20categories B-1Change Alert Status request B-21communication 7-11, B-24conditions B-9contents B-1CONTROL-M/Server B-9, B-12CONTROL-M/Server communication

B-15creating Group Scheduling tables B-22creating jobs B-22deleting conditions B-17described in EMAPIMessages.txt file

B-1description 8-27, B-2gateway B-24Generic Request Exceptions B-15hostnames 7-11identifying 5-1in XML format B-23initializing Orbix domain 7-10Java client B-23Job Creation request B-22Job Tracking request B-19JVM parameters 7-7Low-Level API Exceptions B-7Major Code B-1Minor Code B-2NULL exceptions B-6Order/Force request B-18ordering jobs B-12Parser Exceptions B-8polling B-16Registration request B-20resources B-9severity level 7-3, B-2

tracking jobs B-19Unregistration request B-20user name invalid B-20user token invalid B-20

exceptionsthrowing 4-23

exceptions. See errors.executing

CONTROL-M/EM API sessions 4-1java commands 3-6tracking requests with polling 4-20

FFATAL severity level 7-3, B-2fixing

application runtime errors 7-11CLASSPATH problems 7-6communication errors 7-11environment problems 7-6JVM problems 7-7Orbix domain initialization problems

7-10forcing

Group Scheduling tables 9-59jobs 9-59polling for response 9-65

formattingrequests 4-1response strings 5-2

GGAS

hostname 2-6hostname as property 6-6hostname errors 7-11location 2-6specifying in a request call 4-16

Page 297: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Index 5

GASComponentprototype 1 8-19prototype 2 8-20

GAScomponentspecifying in a request call 4-21

GAScomponent classderived methods 8-18

GASComponent method 8-19gateway errors B-24Generic Request Exceptions B-15getMajorCode method 8-25getMinorCode method 8-26getProperties method

advanced use 6-6defaults 6-6description 8-12

getReason method 8-27Group Scheduling tables

creating 9-17errors in creating B-22

GSRComponentprototype 1 8-22prototype 2 8-23

GSRcomponentspecifying in an XMLBasicInvoker

request call 4-16specifying in an XMLInvoker request

call 4-21GSRComponent class

derived methods 8-21GSRComponent method 8-22GUI Server

hostname 2-6hostname as property 6-6hostname errors 7-11location 2-6

Hhostnames

errors 7-11recording in the ctmemapi.properties file

4-18, 4-22specifying 2-6specifying in a call 4-16

Iidentifying errors 5-1implementing

Orbix ORB settings 7-10import command 3-3importing CONTROL-M/EM API into

project 3-3INFO severity level 7-3, B-3init method

modifying properties 6-1primary listing 8-13prototype 1 6-2, 8-13prototype 2 6-3, 8-14prototype 3 6-4, 8-15prototypes 6-2starting API services 4-15troubleshooting 7-9

initializingCONTROL-M/EM API 1-2CONTROL-M/EM API services 4-15CORBA processes 1-2, 4-15failure 7-10Orbix processes 4-15

installation filesuncompresssing 2-4untarring 2-4

interpretingresponse strings 5-12

invalid user name B-20invoke method

primary listing 8-6, 8-16string parameter 4-16, 4-21throwing exceptions 4-23

Page 298: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

6 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

InvokeException classderived methods 8-24

invokeException classerror information 8-24

invoking EMBasicXMLInvokerhow to 4-23

invoking EMXMLInvokerhow to 4-18

JJava

client errors B-23Java classes

role in API function 1-2java command 3-6Java Developers Kit. See JDKJava Runtime Environment. See JREJava Virtual Machine. See JVMJAVA_HOME environment variable 2-3JDK requirement and support 2-3job

determining status 5-1Job Creation request

description 9-17determining parameter names 9-2polling requirement 4-11response 9-53responses 9-17

Job Tracking requesterrors B-19

jobscreating 9-17errors in creating B-22errors in forcing B-18errors in ordering B-12, B-18parameter names 9-3tracking 9-89

JRE requirement and support 2-3JVM

advanced parameter configuration 7-7parameter problems 7-7passing parameters to project 3-6requirement to run project 3-4

JVM requirement and support 2-3

LLog4J

logging mechanism 7-1supported versions 7-1

log4J.jar file 7-1logging

category 7-2configuring log file 7-3default behavior 7-2modifying behavior 7-2parameters 7-2using Log4J 7-1

logging off 9-105logging on 9-98Low-Level API Exceptions B-7

Mmandatory program actions 4-1methods

Basic 1-2done 4-16, 8-10encodePassword 8-11GASComponent 8-19getMajorCode 8-25getMinorCode 8-26getProperties 6-6, 8-12getReason primary listing 8-27GSRComponent 8-22init 4-15, 8-13invoke 4-16, 4-21, 8-6invoke (EMXMLInvoker) 8-16

Page 299: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Index 7

Native 1-2of the EMBasicXMLInvoker class 8-4of the EMXMLInvoker class 8-9of the GASComponent class 8-18of the GSRComponent class 8-21of the InvokeException class 8-24setPollRequestIntervalMilli 8-7setPollRequestIntervalMilli

implementation 6-8setPollRequestTimeoutMilli 8-8setPollRequestTimeoutMilli

implementation 6-8setProperties 6-7, 8-17

modifyinginitialization properties 6-1logging behavior 7-2Orbix domain configuration file 7-10project for use with the

CONTROL-M/EM API 3-3mySAP. See SAP

Nnull exceptions 7-6, B-6

OObject Request Broker. See CORBAobjects

invoking using EMBasicXMLInvoker 4-23

invoking using EMXMLInvoker 4-19operating system support 2-2ORBconfig_domains_dir parameter 6-5ORBdomain_name.cfg file 7-10Orbix

accessing Locator 2-6domain initialization failure 7-10initializing processes 4-15

modifying properties 6-1orbix2000.cfg file in CLASSPATH 6-5specifying domain with ORB 7-10specifying implementation 7-7version support 2-3

orbix2000.cfg file 6-5Order/Force request

description 9-59errors B-18polling 9-65polling requirement 4-11response 9-64

orderingGroup Scheduling tables 9-59jobs 9-59polling for response 9-65

outcome tracking 9-89

PParser Exceptions B-8parsing

response string 5-1response strings 5-12XML errors B-8

passing CORBA parameters to project 3-6password

encodePassword method 8-11encoding 4-2

platform support 2-2Poll request

description 9-77response 9-79

pollingconfiguring timeout 6-8determining status 5-1errors B-16for Order/Force requests 9-65required with EMXMLInvoker 4-11tracking ID 4-11

Page 300: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

8 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

with EMXMLInvoker 4-20polling request

errors B-16post-installation configuration 3-1preparing project environment 3-1processing response strings 5-12project

modifying for use with the CONTROL-M/EM API 3-3

prepapring environment 3-1running 3-6

propertiescom.bmc.ctmem.emapi.XMLDATAPAT

H 4-14errors B-23getting 6-6Global Alerts Server 2-6GUI Server 2-6modifying init 6-1setting 6-6

prototypesdone 4-16GASComponent prototype 1 8-19GASComponent prototype 2 8-20getProperties method 6-6GSRComponent prototype 1 8-22GSRComponent prototype 2 8-23init 4-15init method 6-2init prototype 1 6-2, 8-13init prototype 2 6-3, 8-14init prototype 3 6-4, 8-15setPollRequestIntervalMilli method 6-9setPollRequestTimeoutMilli method 6-9setProperties method 6-7

Rreceiving

errors 5-1

job status 5-1polling status 5-1request status 5-1

registering usersregistration validity 9-83with Registration request 9-98

Registration requestdescription 9-98encoding password 4-2errors B-20response 9-101

related publications xvirelease notes xixrequest status

determining 5-1in response strings 5-2

requestssending 4-7submitting 4-7tracking with polling 4-20

resettingregistration timeout 9-83

response handling 5-1by class 4-7

response string 5-1contents 5-2formats 5-2parsing 5-1, 5-12parts 5-12types 5-2

responsesEMAPI_errorResponse 5-7EMAPI_PollResponse 5-7EMAPI_Response 5-11EMAPI_TokenResponse 5-3to Add Condition requests 9-7to Change Alert Status request 9-13to Delete Condition requests 9-7to Job Creation request 9-53to Order/Force request 9-64

Page 301: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Index 9

to Poll request 9-79to Registration request 9-101to Timeout Reset request 9-85to Tracking request 9-92to Unregistration request 9-108types 5-2

runningjava command 3-6project 3-6

running environment 3-1

Sselecting

a CONTROL-M/EM API class 4-7component to process the request 4-16,

4-21sending requests 4-7setPollRequestIntervalMilli method

configuring 6-8default 6-9primary listing 8-7

setPollRequestTimeoutMilli methodconfiguring 6-8default 6-9primary listing 8-8

setProperties methodprimary listing 8-17use 6-7

setting environmental variables 3-2, 3-6severity levels

DEBUG 7-3, B-3ERROR 7-3, B-2FATAL 7-3, B-2INFO 7-3, B-3WARN 7-3, B-2

software requirementsCONTROL-M 2-1CORBA implementation 2-3JDK 2-3

JRE 2-3JVM 2-3operating system 2-2Orbix 2-3platform 2-2

solvingapplication runtime errors 7-11CLASSPATH problems 7-6communication errors 7-11environment problems 7-6JVM problems 7-7Orbix domain initialization problems

7-10specifying

component to process a request 4-16, 4-21

hostnames 2-6Orbix ORB domain 7-10

startingCONTROL-M/EM API services 4-15CORBA processes 4-15Orbix processes 4-15project 3-6

stoppingCONTROL-M/EM API services 4-15CORBA processes 4-15Orbix processes 4-15project 4-16

submitting requests 4-7support

CONTROL-M versions 2-1JDK 2-3JRE 2-3JVM 2-3operating systems 2-2

Tthrowing exceptions 4-23timeout

Page 302: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

10 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

configuration 6-8resetting interval 9-83

Timeout Reset requestdescription 9-83response 9-85

token. See user tokentracking

ID 4-11jobs 9-89request execution 4-20requests 4-20

tracking IDuse with EMXMLInvoker 4-11

Tracking requestdescription 9-89response 9-92

troubleshootingapplication runtime errors 7-11CLASSPATH problems 7-6communication problems 7-11JVM problems 7-7Orbix domain initialization problems

7-10types of responses 5-2

Uunderstanding response strings 5-12Unregistration request

description 9-105errors B-20response 9-108

user registration 9-98user token

extracting 4-2invalid B-20resetting timeout interval 9-83

using CONTROL_M/EM API 4-1

Vvalidation

XML strings 4-14validation files

EMAPI_add_conditionResponse.dtd 9-7EMAPI_add_delete_condition.dtd 9-4EMAPI_change_alert_status.dtd 9-11EMAPI_change_alert_statusResponse.dt

d 9-13EMAPI_client_keep_alive.dtd 9-83EMAPI_client_keep_aliveResponse.dtd

9-85EMAPI_create_ajResponse.dtd 9-53EMAPI_delete_conditionResponse.dtd

9-7EMAPI_ErrorResponse.dtd 5-7EMAPI_job_track.dtd 9-89EMAPI_job_trackResponse.dtd 9-92EMAPI_order_force.dtd 9-59EMAPI_poll.dtd 9-77EMAPI_pollResponse.dtd 5-7, 9-79EMAPI_register.dtd 9-98EMAPI_registerResponse.dtd 9-101EMAPI_RequestnameResponse 5-11EMAPI_TokenResponse.dtd 5-3EMAPI_unregister.dtd 9-105EMAPI_unregisterResponse.dtd 9-108location 4-14

WWARN severity level 7-3, B-2

XXML

invalid format errors B-23

Page 303: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

Index 11

XML stringscreating 8-1parsing 4-2parsing responses 5-12validation 4-14

XMLDATAPATH 4-14XMLstrings

parsing errors B-8

Page 304: CM Enterprise Manager API Developers Guide

BMC Software, Inc., Confidential and Proprietary Information

12 CONTROL-M/Enterprise Manager Application Program Interface Developers Guide

Page 305: CM Enterprise Manager API Developers Guide

END USER LICENSE AGREEMENTNOTICE

BY OPENING THE PACKAGE, INSTALLING, PRESSING "AGREE" OR "YES" OR USING THE PRODUCT, THE ENTITY ORINDIVIDUAL ENTERING INTO THIS AGREEMENT AGREES TO BE BOUND BY THE FOLLOWING TERMS. IF YOU DO NOTAGREE WITH ANY OF THESE TERMS, DO NOT INSTALL OR USE THE PRODUCT, PROMPTLY RETURN THE PRODUCT TOBMC OR YOUR BMC RESELLER, AND IF YOU ACQUIRED THE LICENSE WITHIN 30 DAYS OF THE DATE OF YOUR ORDERCONTACT 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 witha party. THIS AGREEMENT WILL APPLY TO THE PRODUCT, UNLESS (1) YOU AGREED TO A WEB BASED LICENSEAGREEMENT WITH BMC WHEN ORDERING THE PRODUCT, IN WHICH CASE THAT WEB BASED LICENSE AGREEMENTGOVERNS THE USE OF THE PRODUCT, OR (2) IF YOU DID NOT AGREE TO A WEB BASED LICENSE AGREEMENT WITH BMCWHEN ORDERING THE PRODUCT AND YOU HAVE A WRITTEN LICENSE AGREEMENT WITH BMC, THEN THAT WRITTENAGREEMENT GOVERNS THE USE OF THE PRODUCT. THE ELECTRONIC AGREEMENT PROVIDED WITH THE PRODUCT ASPART 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 electronictransmission, to You. Software includes computer files, enhancements, maintenance modifications, upgrades, updates, bug fixes, anderror 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 capacityrestrictions, such as tier limit, total allowed users, gigabyte limit, quantity of Software, and/or other capacity limitations regarding theSoftware. For licenses based on the power of a computer, You agree to use BMC’s current computer classification scheme, which isavailable 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 LicenseCapacity, 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 Youacquired 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 newsoftware programs for Your internal purposes or otherwise consistent with the License. BMC grants You a license to use theDocumentation 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 suchexpanded usage and Your payment of applicable fees. There is no additional warranty period or free support period for licenseupgrades.

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 BMC’s prior writtenapproval, unless prohibited by local law.

Page 306: CM Enterprise Manager API Developers Guide

TRIAL LICENSE. If, as part of the ordering process, the Product is provided on a trial basis, then these terms apply: (i) this licenseconsists solely of a non-exclusive, non-transferable evaluation license to operate the Software for the period of time specified from BMCor, if not specified, a 30 day time period ("Trial Period") only for evaluating whether You desire to acquire a capacity-based license tothe Product for a fee; and (ii) Your use of the Product is on an AS IS basis without any warranty, and BMC, ITS AFFILIATES ANDRESELLERS, AND LICENSORS DISCLAIM ANY AND ALL WARRANTIES (INCLUDING, WITHOUT LIMITATION, THE IMPLIEDWARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT) AND HAVE NOLIABILITY 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 Productautomatically expires. If You want to continue Your use of the Product beyond the Trial Period, contact BMC to acquire acapacity-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 mustuninstall 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 allintellectual property, informational, industrial property and proprietary rights therein. BMC neither grants nor otherwise transfers anyrights of ownership in the BMC Product to You. BMC Products are protected by applicable copyright, trade secret, and industrial andintellectual 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 BMCProducts and Support, including, without limitation, trade secret and proprietary information, and the structure and organization of theSoftware. You may not disclose the Confidential Information to third parties. You agree to use all reasonable efforts to prevent theunauthorized 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 Documentationfor a period of one year from the date of the order. This warranty shall not apply to any problems caused by software or hardware notsupplied by BMC or to any misuse of the Software.

EXCLUSIVE REMEDY. BMC’s entire liability, and Your exclusive remedy, for any defect in the Software during the warranty period orbreach of the warranty above shall be limited to the following: BMC shall use reasonable efforts to remedy defects covered by thewarranty or replace the defective Software within a reasonable period of time, or if BMC cannot remedy or replace such defective copyof the Software, then BMC shall refund the amount paid by You for the License for that Software. BMC’s obligations in this section areconditioned 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, ITSAFFILIATES AND LICENSORS SPECIFICALLY DISCLAIM ALL OTHER WARRANTIES, INCLUDING, WITHOUT LIMITATION, THEIMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. BMCDOES NOT WARRANT THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR FREE, OR THATALL 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 DAMAGEOR LOSS OF USE OF DATA), EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, AND IRRESPECTIVE OF ANYNEGLIGENCE OF BMC OR WHETHER SUCH DAMAGES RESULT FROM A CLAIM ARISING UNDER TORT OR CONTRACTLAW.

LIMITS ON LIABILITY. BMC’S AGGREGATE LIABILITY FOR DAMAGES IS LIMITED TO THE AMOUNT PAID BY YOU FOR THELICENSE 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 Youas 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 ofsupported versions of the Software, BMC provides bug fixes, patches or workarounds in order to cause that copy of the Software tooperate in substantial conformity with its then-current operating specifications; and (ii) BMC provides new releases or versions, so longas such new releases or versions are furnished by BMC to all other enrolled Support customers without additional charge. BMC mayrefuse to provide Support for any versions or releases of the Software other than the most recent version or release of such Softwaremade available by BMC. Either party may terminate Your enrollment in Support upon providing notice to the other at least 30 days priorto the next applicable Support anniversary date. If You re-enroll in Support, BMC may charge You a reinstatement fee of 1.5 times whatYou would have paid if You were enrolled in Support during that time period.

(b) Fees. The annual fee for Support is 20% of the Software’s 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.

Page 307: CM Enterprise Manager API Developers Guide

VERIFICATION. If requested by BMC, You agree to deliver to BMC periodic written reports, whether generated manually orelectronically, 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 Youhave underpaid fees, You agree to pay such underpaid fees. If the underpaid fees exceed 5% of the fees paid, then You agree to alsopay BMC’s 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 anyunderlying 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) inthe State of New York, if you acquired the License in the United States, Puerto Rico, or any country in Central or South America; (b) inthe Province of Ontario, if you acquired the License in Canada (subsections (a) and (b) collectively referred to as the "AmericasRegion"); (c) in Singapore, if you acquired the License in Japan, South Korea, Peoples Republic of China, Special AdministrativeRegion 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 ORALLEGED BREACH, SHALL BE DETERMINED BY BINDING ARBITRATION CONDUCTED IN ENGLISH. IF THE DISPUTE ISINITIATED IN THE AMERICAS REGION, THE ARBITRATION SHALL BE HELD IN NEW YORK, U.S.A., UNDER THE CURRENTCOMMERCIAL OR INTERNATIONAL, AS APPLICABLE, RULES OF THE AMERICAN ARBITRATION ASSOCIATION. IF THEDISPUTE 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 COUNTRYOUTSIDE 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 BEBORNE EQUALLY PENDING THE ARBITRATOR’S AWARD. THE AWARD RENDERED SHALL BE FINAL AND BINDING UPONTHE PARTIES AND SHALL NOT BE SUBJECT TO APPEAL TO ANY COURT, AND MAY BE ENFORCED IN ANY COURT OFCOMPETENT JURISDICTION. NOTHING IN THIS AGREEMENT SHALL BE DEEMED AS PREVENTING EITHER PARTY FROMSEEKING INJUNCTIVE RELIEF FROM ANY COURT HAVING JURISDICTION OVER THE PARTIES AND THE SUBJECT MATTEROF THE DISPUTE AS NECESSARY TO PROTECT EITHER PARTY’S CONFIDENTIAL INFORMATION, OWNERSHIP, OR ANYOTHER PROPRIETARY RIGHTS. ALL ARBITRATION PROCEEDINGS SHALL BE CONDUCTED IN CONFIDENCE, AND THEPARTY PREVAILING IN ARBITRATION SHALL BE ENTITLED TO RECOVER ITS REASONABLE ATTORNEYS’ FEES ANDNECESSARY 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 isdescribed 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 thiscommercial computer software and/or commercial computer software documentation subject to the terms of this Agreement asspecified in 48 C.F.R. 12.212 (Computer Software) and 12.211 (Technical Data) of the Federal Acquisition Regulations ("FAR") and itssuccessors. If acquired by or on behalf of any agency within the Department of Defense ("DOD"), the U.S. Government acquires thiscommercial computer software and/or commercial computer software documentation subject to the terms of this Agreement asspecified 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, includingsales, use, duty, tariffs, customs, withholding, property, value-added (VAT), and other similar federal, state or local taxes (other thantaxes based on BMC’s net income) imposed in connection with the Product and/or the Support. This Agreement constitutes the entireagreement between You and BMC and supersedes any prior or contemporaneous negotiations or agreements, whether oral, written ordisplayed electronically, concerning the Product and related subject matter. No modification or waiver of any provision hereof will beeffective unless made in a writing signed by both BMC and You. You may not assign or transfer this Agreement or a License to a thirdparty without BMC’s prior written consent. Should any provision of this Agreement be invalid or unenforceable, the remainder of theprovisions will remain in effect. The parties have agreed that this Agreement and the documents related thereto be drawn up in theEnglish language. Les parties exigent que la présente convention ainsi que les documents qui s’y rattachent soient rédigés en anglais.

SW EULA Int 030102

Page 308: CM Enterprise Manager API Developers Guide
Page 309: CM Enterprise Manager API Developers Guide

Notes

Page 310: CM Enterprise Manager API Developers Guide

�� ����� ����� ����� ���

*16458*