CM Enterprise Manager API Developers Guide

Download CM Enterprise Manager API Developers Guide

Post on 28-Oct-2015

107 views

Category:

Documents

0 download

Embed Size (px)

TRANSCRIPT

<ul><li><p>CONTROL-M/Enterprise Manager API</p><p>Developers Guide</p><p>Version 6.1.01</p><p>June 20, 2002</p></li><li><p>Copyright 2002 BMC Software, Inc., as an unpublished work. All rights reserved.</p><p>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.</p><p>THE USE AND CONTENTS OF THIS DOCUMENTATION ARE GOVERNED BY THE SOFTWARE LICENSE AGREEMENT ENCLOSED AT THE BACK OF THIS DOCUMENTATION.</p><p>Restricted Rights LegendU.S. GOVERNMENT RESTRICTED RIGHTS. UNPUBLISHEDRIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure by the U.S. Government is subject to restrictions set forth in FAR Section 52.227-14 Alt. III (g)(3), FAR Section 52.227-19, DFARS 252.227-7014 (b), or DFARS 227.7202, as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.</p><p>Contacting BMC SoftwareYou 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. </p><p>United States and Canada Outside United States and CanadaAddress BMC Software, Inc.</p><p>2101 CityWest Blvd.Houston TX 77042-2827</p><p>Telephone</p><p>Fax</p><p>(01) 713 918 8800</p><p>(01) 713 918 8000Telephone 713 918 8800 or</p><p>800 841 2031</p><p>Fax 713 918 8000</p></li><li><p>BMC Software, Inc., Confidential and Proprietary Information</p><p>iii</p><p>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.</p><p>Support Web SiteYou 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, </p><p>fax numbers, and telephone numbers</p><p>Support by Telephone or E-mailIn 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.</p><p>Before Contacting BMC SoftwareBefore you contact BMC Software, have the following information available so that Customer Support can begin working on your problem immediately:</p><p> product information</p><p> product name product version (release number) license number and password (trial or permanent)</p><p> operating system and environment information</p><p> 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 </p><p>maintenance level</p></li><li><p>BMC Software, Inc., Confidential and Proprietary Information</p><p>iv CONTROL-M/Enterprise Manager Application Program Interface Developers Guide</p><p> sequence of events leading to the problem</p><p> commands and options that you used</p><p> 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 </p></li><li><p>BMC Software, Inc., Confidential and Proprietary Information</p><p>Contents v</p><p>Contents</p><p>Contents</p><p>About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv</p><p>Chapter 1 OverviewHow the CONTROL-M/EM API Works . . . . . . . . . . . . . . . . . . . . . . 1-2</p><p>Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2The APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2</p><p>Who Should Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3</p><p>Chapter 2 InstallationSoftware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1</p><p>CONTROL-M Product Support . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Platform and Operating System Support . . . . . . . . . . . . . . . . . . 2-2Additional Software Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3</p><p>Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4</p><p>Chapter 3 Configure the CONTROL-M/EM APIPreparing Your Project Environment . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Writing Your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Running Your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6</p><p>Chapter 4 Creating Request CallsCONTROL-M/EM API Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1</p><p>Session Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3Deciding Which Class to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7</p><p>Response Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7XML String Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14</p><p>Using EMXMLInvoker Class Calls . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15Initializing and Stopping the CONTROL-M/EM API Services . 4-15</p></li><li><p>BMC Software, Inc., Confidential and Proprietary Information</p><p>vi CONTROL-M/Enterprise Manager Application Program Interface Developers Guide</p><p>Submitting a Request Using the EMXMLInvoker class . . . . . . .4-16Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20</p><p>Using EMBasicXMLInvoker Class Calls . . . . . . . . . . . . . . . . . . . . .4-21Submit a Request Using the EMBasicXMLInvoker class . . . . . .4-21</p><p>Chapter 5 Response HandlingResponse Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-2Response String Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-2</p><p>EMAPI_tokenResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-3EMAPI_PollResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-7EMAPI_errorResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-7EMAPI_Response . . . . . . . . . . . . . . . . . . . . .5-11</p><p>Interpreting Response Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-12Parts of a Response String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-12Analyzing a Response String . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-13</p><p>Chapter 6 Advanced Features and OptimizationModifying Initialization Properties . . . . . . . . . . . . . . . . . . . . . . . . . .6-1</p><p>Prototype 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-2Prototype 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-3Prototype 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-4</p><p>Getting and Setting CONTROL-M/EM API Properties . . . . . . . . . .6-6getProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-6setProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-7</p><p>Polling Interval Timeout Configuration . . . . . . . . . . . . . . . . . . . . . . .6-8setPollRequestIntervalMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-9setPollRequestTimeoutMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-9</p><p>Chapter 7 Diagnostics and TroubleshootingCONTROL-M/EM API Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1</p><p>Default Logging Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2Modifying Logging Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2</p><p>Environment Configuration Troubleshooting . . . . . . . . . . . . . . . . . .7-6CLASSPATH: Missing Libraries or Directories . . . . . . . . . . . . .7-6Java Virtual Machine Parameters . . . . . . . . . . . . . . . . . . . . . . . .7-7Orbix Domain Initialization Failure . . . . . . . . . . . . . . . . . . . . . .7-10</p><p>Application Runtime and Communication Troubleshooting . . . . . . .7-11</p><p>Chapter 8 Call ReferenceComponentType Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3</p></li><li><p>BMC Software, Inc., Confidential and Proprietary Information</p><p>Contents vii</p><p>EMBasicXMLInvoker Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4invoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6setPollRequestIntervalMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7setPollRequestTimeoutMilli . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8</p><p>EMXMLInvoker Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10encodePassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11getProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13invoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16setProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17</p><p>GASComponent Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18GASComponent (Prototype 1) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19GASComponent (Prototype 2) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20</p><p>GSRComponent Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21GSRComponent (Prototype 1) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22GSRComponent (Prototype 2) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23</p><p>InvokeException Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24getMajorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-25getMinorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26getReason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27</p><p>Chapter 9 Request ReferenceAdd/Delete Condition Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4</p><p>Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10</p><p>Change Alert Status Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16</p><p>Job Creation Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-53Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-58</p><p>Order/Force Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-59Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-59Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-64Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-76</p><p>Polling Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-77</p></li><li><p>BMC Software, Inc., Confidential and Proprietary Information</p><p>viii CONTROL-M/Enterprise Manager Application Program Interface Developers Guide</p><p>Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-77Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-79Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-82</p><p>Timeout Reset Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-83Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-83Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-85Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-88</p><p>Tracking Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-89Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-89Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-92Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-97</p><p>User Registration Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-98Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-98Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-101Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-104</p><p>User Unregistration Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-105Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-105Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-108Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-111</p><p>Appendix A Request Format ExamplesAdd Condition/Delet...</p></li></ul>