BMC Impact Integration Developerâ€™s Kit Web Services Server

www.bmc.com

BMC Impact Integration Developer’s Kit Web Services Server Developer Guide

Supporting

BMC Impact Integration Developer’s Kit v. 7.1BMC Impact Integration Web Services Server v. 7.1

January 2008

Contacting BMC Software

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

United States and Canada

Address BMC SOFTWARE INC2101 CITYWEST BLVDHOUSTON TX 77042-2827 USA

Telephone 713 918 8800 or800 841 2031

Fax 713 918 8000

Outside United States and Canada

Telephone (01) 713 918 8800 Fax (01) 713 918 8000

© Copyright 2003–2008 BMC Software, Inc.

BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners.

IBM and AIX are registered trademarks of International Business Machines Corporation.

Linux is the registered trademark of Linus Torvalds.

Java, Sun, JRE, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc., in the U.S. and several other countries.

UNIX is a registered trademark of The Open Group.

BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License Agreement for the product and the proprietary and restricted rights notices included in this documentation.

Restricted rights legendU.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX 77042-2827, USA. Any contract notices should be sent to this address.

http://www.bmc.com

Customer support

You can obtain technical support by using the BMC Software Customer Support website or by contacting Customer Support by telephone or e-mail. To expedite your inquiry, see “Before contacting BMC.”

Support website

You can obtain technical support from BMC 24 hours a day, 7 days a week at http://www.bmc.com/support_home. From this website, you can

■ read overviews about support services and programs that BMC offers■ find the most current information about BMC products■ search a database for issues similar to yours and possible solutions■ order or download product documentation■ download products and maintenance■ report an issue or ask a question■ subscribe to receive proactive e-mail alerts when new product notices are released■ find worldwide BMC support center locations and contact information, including e-mail addresses, fax numbers, and

telephone numbers

Support by telephone or e-mail

In the United States and Canada, if you need technical support and do not have access to the web, call 800 537 1813 or send an e-mail message to [email protected]. (In the subject line, enter SupID:<yourSupportContractID>, such as SupID:12345). Outside the United States and Canada, contact your local support center for assistance.

Before contacting BMC

Have the following information available so that Customer Support can begin working on your issue immediately:

■ product information

— product name— product version (release number)— license number and password (trial or permanent)

■ operating system and environment information

— machine type— operating system type, version, and service pack or other maintenance level such as PUT or PTF— system hardware configuration— serial numbers— related software (database, application, and communication) including type, version, and service pack or

maintenance level

■ sequence of events leading to the issue

■ commands and options that you used

■ messages received (and the time and date that you received them)

— product error messages— messages from the operating system, such as file system full— messages from related software

3

http://www.bmc.com/support_home

mailto:[email protected]

License key and password information

If you have questions about your license key or password, contact BMC as follows:

■ (USA or Canada) Contact the Order Services Password Team at 800 841 2031, or send an e-mail message to [email protected].

■ (Europe, the Middle East, and Africa) Fax your questions to EMEA Contracts Administration at +31 20 354 8702, or send an e-mail message to [email protected].

■ (Asia-Pacific) Contact your BMC sales representative or your local BMC office.

4 BMC Impact Integration Developer’s Kit Web Services Server Developer Guide



ContentsChapter 1 Introduction 13

BMC Impact Integration Developer’s Kit overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Overview to BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . 14

BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16WSDL file and SOAP messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Toolkits and client-side interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Features available to clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Compatible programming languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Features of the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18mcell.dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18WSCELL event listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Support overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Intended audience for web services APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 2 Installation 21

Installation package contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Supported operating systems and other resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Compatible web services toolkits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23OpenSSL compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Disk space requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Installing the web services server package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Installation directory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Setting environment variables under Microsoft Windows . . . . . . . . . . . . . . . . . . . 31Setting environment variables under Solaris, Linux, HP-UX, and AIX . . . . . . . . 32

Uninstalling the web services server package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 3 Configuration 37

Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38How to synchronize BMC II Web Services Server and BMC IM cell connections. .

38Troubleshooting tip: BMC II Web Services Server fails to reconnect . . . . . . . . . . 44Defining Propagate rules or event propagation policies for BMC IM cells . . . . . 45

Optional configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Configuring high availability cells for the BMC II Web Services Server . . . . . . . 51

Contents 5

Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Updating default port numbers post installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Configuring Attributes in the BMC II Web Services Server . . . . . . . . . . . . . . . . . . 57Modifying the default BMC II Web Services Server log . . . . . . . . . . . . . . . . . . . . . 58

Starting and stopping the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . 59Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Connecting to BMC II Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Installing multiple instances of the BMC II Web Services Server . . . . . . . . . . . . . . . . . 62

When to assign a unique server instance name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Administering the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 4 Securing web services 65

Secure Sockets Layer (SSL) security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Security implementation advisory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Compatible OpenSSL toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Guidelines for implementing SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Obtaining the OpenSSL source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67About certificate generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Generating the BMC II Web Services Server certificate (Microsoft Windows). . . 68Generating the BMC II Web Services server certificate (UNIX or Linux) . . . . . . . 69Replacing nonsecure transport parameters with SSL parameters in the

servercfg.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Chapter 5 Guidelines for choosing client interfaces 73

Client components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Programming language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Available web services client features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Guidelines for building a client interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Preparing the WSDL source-code generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Generating the client proxy code (client stubs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Systinet WASP Server for C ++ toolkit sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76.NET C# toolkit sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Apache Axis toolkit sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Using the NO_INOUT operations to return single elements for the Axis toolkit 78Deciding which stub operations to use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Compiling the client code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Maximum number of open outgoing connections . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Implementing the send feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81How a send request is processed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Sequence of operations to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Implementing the query features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83How a query is processed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Sequence of operations to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84bmciiws_queryClassDefinitions: class definition array . . . . . . . . . . . . . . . . . . . . . . 86

Implementing the receive feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Selector choices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89


Polling interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Publish-subscribe interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Reliable versus non-reliable subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Polling client (non-reliable subscription) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Polling client (reliable subscription) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Listener client (reliable or non-reliable subscription) . . . . . . . . . . . . . . . . . . . . . . . 95Using multiple subscription calls (bmciiws_subscribe_reliable) . . . . . . . . . . . . . . 96Registering and receiving service component state change events . . . . . . . . . . . . 98Workaround: multiple clients and state change events. . . . . . . . . . . . . . . . . . . . . . 99

Implementing the Secure WASPC client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Appendix A BMC Impact Integration Web Services Server Administration 105

Starting server instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Selector file overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106How the BMC II Web Services Server reads selector files and parameters . . . . . . . 106Selector file description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Editing the selector file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Editing the supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Trace file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Editing the trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Editing the Integration mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Appendix B Error Messages and Codes 141

BMC II Web Services Server error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141BMC II C APIs and core communications errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Errors listed By error code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Error descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Core communications errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Errors listed by error code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Error descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Appendix C Sample Client Files 163

List of sample client files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Event Listener Web Services Description Language (WSDL) file . . . . . . . . . . . . . . . 165

Event listener server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Event dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Contents 7

Bindings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Listenercfg.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Adding SSL parameters to the listenercfg.xml file . . . . . . . . . . . . . . . . . . . . . . . . . 173

Index 175

Glossary 183


FiguresComponents of BMC Impact Integration Web Services . . . . . . . . . . . . . . . . . . . . . . . . 15mcell.dir example: BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40mcell.dir example: BMC IM cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40mcell.dir example: BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41mcell.dir example: BMC IM cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Event propagation: many instances to one server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Event propagation: many instances to many servers . . . . . . . . . . . . . . . . . . . . . . . . . . 47HA implementation scenario: primary cell server and web server on same system 52HA implementation scenario: primary cell server and web server on different

systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53HA implementation scenario for BPM and BMC II Web Services Server . . . . . . . . . 55servercfg.xml file: default declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Servercfg.xml with openSSL parameters added and transport section removed . . . 71Runtime directory folders for stub files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78bmciiws_queryClassDefinitions code sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Class definition array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Structure of message selector set file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Sample trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Dispatch Operations in EventListener.wsdl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Figures 9

TablesWasp library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Supported operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Tested compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Compatible toolkits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23UNIX distribution files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Directory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Location of mcell.dir Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39mcell.dir configurations for queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40mcell.dir configurations for sending events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40mcell.dir configurations for receiving events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Optional configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Default port numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Summary of Available Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Components that support a receive interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Event selectors for subscription requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89SIM_NOTIFICATION_REGISTRY message class: required slots . . . . . . . . . . . . . . . . 99Message selector set header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Message selector header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Message selector functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Message selector operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Keyword descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124BMC II C APIs Impact Integration Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Core Communications Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Sample client files: Systinet C++ queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Sample client files: Systinet C++ listener client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Sample client files: Axis Java implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Namespaces: EventListener.wsdl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Message Parts: Dispatch_Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Message Parts: DispatchList_Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Tables 11

C h a p t e r 1
1 Introduction
This chapter introduces the BMC Impact Integration Developer’s Kit and the BMC Impact Integration Web Services Server APIs. It describes the following topics:

BMC Impact Integration Developer’s Kit overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Overview to BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . 14

BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16WSDL file and SOAP messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Toolkits and client-side interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Features available to clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Compatible programming languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Features of the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18mcell.dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18WSCELL event listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Support overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Intended audience for web services APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 1 Introduction 13

BMC Impact Integration Developer’s Kit overview

BMC Impact Integration Developer’s Kit overview

The BMC Impact Integration Developer’s Kit (BMC II Developer’s Kit) enables developers to build applications that can integrate with BMC Impact Manager events and data.

The BMC II Developer’s Kit includes:

■ BMC Impact Integration C APIs—a toolkit that provides functions to interact with the BMC Impact Manager product and its components. This API can be used in C or C++ environments. These APIs offer developers the ability to quickly integrate and set up the bidirectional flow of events and data between their applications and the BMC Impact Manager product.

■ BMC II Web Services APIs—a toolkit that exposes an open-standards web services interface with which to implement loosely coupled BMC Impact Manager integrations, to build client applications that utilize BMC Impact Manager data, and to remotely access an BMC Impact Manager network through standard Web protocols. The web services interface is defined through the Web Services Description Language that serves as the contract between the web service and the client application.

These APIs offer developers the ability to quickly build integrations that share events and data with the BMC Impact Manager product or to display BMC Impact Integration information in Web-based applications.

Overview to BMC Impact Integration Web Services Server

The BMC Impact Integration (BMC II) Web Services Server APIs enable you, as a web services developer, to build a platform-independent web services client that exchanges events and data with a BMC Impact Manager instance.

NOTE The BMC Impact Integration Developer’s Kit does not include the BMC Impact Manager product. You must purchase this product separately or have it already installed.


Overview to BMC Impact Integration Web Services Server

Your web service client communicates with the BMC Impact Manager instance (cell) by connecting to the BMC II Web Services Server and accessing BMC II Web Services.

Figure 1 depicts the components of the BMC II Web Services Server and their interaction with a third-party client.

Figure 1 Components of BMC Impact Integration Web Services

The BMC Impact Integration Web Services Server package includes

■ XML to describe message content

■ Web Services Description Language (WSDL), an XML document that defines the data types, messages, operations, and binding protocol of this web service

■ Simple Object Access Protocol (SOAP) over HTTP as a transport mechanism between Impact Integration Web Services Server and Impact Integration Web Services client

■ a web services server that can process callbacks and forward events to subscribing clients through an event dispatcher

■ sample client code

NOTE The BMC Impact Integration Web Services Server APIs contains a pre-built web service. The web services developer is responsible for building the client.

NOTE The BMC II Web Services Server does not include a Universal Description Discovery, and Integration (UDDI) registry.


BMC Impact Integration Web Services Server

BMC Impact Integration Web Services Server

The BMC II Web Services Server is already programmed to exchange event information between your web service client and BMC Impact Manager cells.

The BMC II Web Services Server also supports listener libraries. This component enables a client to receive BMC Impact Manager events through callbacks.

The BMC II Web Services Server contains the Wasp library file of the Systinet™ WASP server. Table 1 lists the names and extensions of the library file in the different operating systems.

BMC II C APIs

The BMC II Web Services Server contains the runtime libraries of the BMC II C APIs.

WSDL file and SOAP messages

The BMC II Web Services Server package includes a static, read-only Web Service Descriptive Language file (.wsdl) called ImpactManager.wsdl. The ImpactManager.wsdl file is in XML format. It points to three schema definition files:

■ Event.xsd

■ BasicTypes.xsd

■ ImapiTypes.xsd

NOTE The current release of BMC II Web Services does not support the porting of the BMC II Web Services Server to other web servers.

Table 1 Wasp library files

Operating system Name of Wasp library file

Microsoft Windows waspc.dll

Solaris™ and Linux® libwasp.so.4

HP-UNIX libwasp.sl

AIX® libwasp.a


Toolkits and client-side interfaces

The BMC II Web Services Server exposes its APIs through its ImpactManager.wsdl file. It uses the document/literal style of SOAP messaging format to communicate with client programs.

Toolkits and client-side interfaces

To create a web service client, BMC recommends that you choose from among the compatible toolkits (see “Compatible web services toolkits” on page 23).

Use the toolkit that supports your programming language (C#, Java™, C++, and so forth) to process the ImpactManager.wsdl and generate the client-side stubs. These stubs contain classes and interfaces that are used by the client code. The stubs define how the methods or functions are called. When a client request is initiated, the toolkit serializes the call into a SOAP message and sends it to the server. The server deserializes the SOAP message into a format that the underlying Systinet libraries can understand and processes it accordingly.

Features available to clients

The BMC II Web Services Server APIs enable you to implement clients that use one or more of the following features:

■ sends events and data■ queries for events, data, class definitions, and service model information■ receives events through subscription requests and callbacks■ receives events through subscription requests and polling calls

The APIs let you customize your queries and subscription requests so that, for example, you can specify which data you want to retrieve and which events to receive.

NOTE See the BMC Impact Integration Developer’s Kit Web Services Server Reference Guide for a detailed description of the WSDL and schema definition files.

NOTE The BMC II Web Services Server uses encrypted communications. User authentication is not available.


Compatible programming languages

Compatible programming languages

You can build a client using the C++, C# , or Java programming language.

Features of the BMC II Web Services ServerThis section describes the BMC II Web Services Server’s unique requirement for the mcell.dir file, and it summarizes the different ways in which the BMC II Web Services Server handles client interfaces.

mcell.dir

After you install the BMC II Web Services Server, an mcell.dir file is generated with two default entries. In addition to the local cell entry, which most BMC Impact Manager users are familiar with, it also includes an entry for the event listener component called WSCELL. The following example shows the entries with the default port numbers.

In the standalone BMC II Web Services Server installation, the mcell.dir file is installed under the drive:\installDirectory\mcell or installDirectory/mcell directory.

WSCELL event listener

An essential component of the BMC II Web Services Server, the WSCELL is an event listener that accepts connections and messages from BMC Impact Manager instances. It is enabled when the BMC II Web Services Server starts. The WSCELL receives events and messages from BMC Impact Manager instances and stores them in a buffer. The BMC II Web Services Server receives the BMC Impact Manager events through the WSCELL event listener.

The WSCELL defaults to the local host system (IP address of 127.0.0.1) of the BMC II Web Services Server and listens for events on port number 19999.

For each BMC IM cell that sends events to the BMC II Web Services Server, you specify the WSCELL entry that identifies the server in the mcell.dir file of each sending cell. (See “How to synchronize BMC II Web Services Server and BMC IM cell connections” on page 38 for more information.)

cell local mc localhost:1828cell WSCELL mc 127.0.0.1:19999


Support overview

Support overviewYou request the BMC Impact Integration Developer’s Kit through the BMC Developer Network website at http://developer.bmc.com. To obtain general support information, such as finding out how to extend the tools in the kit and develop integration applications, you can go to the BMC Developer Connection. It provides developers with moderated peer support and offers a free, supportive Web site where you can get answers to your questions about developing integrations with the BMC Impact Manager product. For more information on joining, go to the BMC Developer Connection Web site at: http://devcon.bmc.com/.

If you have found a bug in the toolkit or an error in the documentation, please report it to BMC Customer Support. (See the Customer Support contact information in the front matter of this guide just after the title page.)

Intended audience for web services APIsThe audience of the web services APIs is experienced developers who are knowledgeable about web services technologies: XML; Simple Object Access Protocol (SOAP); Web Services Description Language (WSDL); and Universal Description and Discovery Interface (UDDI). The web services audience should be acquainted with BMC Impact Manager, but it does not need to be as familiar with the BMC Impact Manager product as does the C developer audience. The web services audience should have experience in

■ writing code in one or more programming languages■ building client applications for web services interfaces ■ working with client proxy code (client stubs)■ generating secure sockets layer (SSL) certificate requests

The audience of the web services APIs also includes systems or applications administrators who are responsible for managing the BMC Impact Manager environment. These administrators should be knowledgeable about BMC Impact Manager administrative tasks, especially the tasks of maintaining the configuration, trace, selector, and the mcell.dir files. The administrator should also be familiar with defining filter criteria that specify the events that pass to and from BMC Impact Manager. It would be helpful if the administrator were also familiar with web services.

NOTE At the time of publication, BMC intends to eventually migrate the content of the BMC Developer Connection website to the BMC Developer Network website at http://developer.bmc.com.


http://developer.bmc.com

http://devcon.bmc.com



Intended audience for web services APIs


C h a p t e r 2
2 Installation
This chapter presents the following topics:

Installation package contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Supported operating systems and other resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Compatible web services toolkits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23OpenSSL compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Disk space requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Installing the web services server package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Installation directory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Setting environment variables under Microsoft Windows . . . . . . . . . . . . . . . . . . . 31Setting environment variables under Solaris, Linux, HP-UX, and AIX . . . . . . . . 32

Uninstalling the web services server package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34


Installation package contents

Installation package contentsThe BMC II Web Services Server package consists of the following components:

■ server binaries and server executable■ configuration, selector, mapping, and mcell.dir files■ Web Services Description Language (WSDL) files and schema definition (XSD)

files■ runtime library files of the BMC II C APIs ■ sample client code

Supported operating systems and other resources

Table 2 lists the operating systems that are compatible with this release:

BMC IM support matrix

Table 3 lists the versions and features of BMC Impact Manager (BMC IM) that the BMC II Web Services Server supports. Versions 5.1 and later provide language support for Simplified Chinese, Traditional Chinese, Korean, and Japanese languages.

Table 2 Supported operating systems

Operating system Version or Service pack

Windows 2003 Server, 32-bit SP1

Red Hat Enterprise Linux Advanced Server (Intel, 32-bit) 3.0, 4.0

SUSE Linux Enterprise Server (Intel, 32-bit) 9.0, 10.0

Sun™ Solaris (SPARC) 9, 10

IBM® AIX (POWER) 5.2, 5.3

HP-UX (PA-RISC) 11i, v1, v2

Table 3 BMC IM support matrix (part 1 of 2)

BMC IM version Event and data exchange Service model queries Language support

5.1 Yes Yes Yes

5.1.01 Yes Yes Yes


Compilers

Compilers

You are free to choose your own compiler to build your client.

Refer to the following table for a list of compilers that the client sample code has been tested against.

Compatible web services toolkits

The BMC II Web Services Server package has been tested against and found compatible with the following web services toolkits:

OpenSSL compatibility

The BMC II Web Services Server is compatible with version 0.9.6 of OpenSSL.

7.0.x Yes Yes Yes

7.1 Yes Yes Yes

Table 4 Tested compilers

Platform Compiler

Microsoft Windows Microsoft Visual Studio, version 6.0

Linux GNU Complier Collection (GCC) 2.96

Solaris SPARCWorks CC 5.0

HP-UX HP aCC 3.3x

Table 5 Compatible toolkits

Vendor Toolkit

Systinet WASP Server for C++ 4.6

Microsoft Visual C# .NET 2003

Apache Axis 1_3, Axis 1_4

OpenSSL OpenSSL 0.9.6

Table 3 BMC IM support matrix (part 2 of 2)

BMC IM version Event and data exchange Service model queries Language support


Disk space requirements

Disk space requirementsThe BMC II Web Services Server package requires minimal disk space. For Windows-based systems, you need approximately 40 MB of disk space; for UNIX®-based systems, you need approximately 30 MB of disk space.

Installing the web services server package This section describes how to install the BMC II Web Services Server using the executable that you have downloaded from the BMC Developer Network (BMCDN) website at http://developer.bmc.com.

Your installation tasks consist of the following options:

■ defining an installation directory on the target system if not using the default ■ specifying port numbers for the BMC II Web Services Server and the WSCELL

event listener■ choosing which component or components (server, sample client code, or both) to

install■ installing the component files into the installation directory■ defining environment variables

This task describes how to install the BMC Impact Integration Web Services Server package on the following operating systems:

■ Windows■ Linux■ Solaris■ HP-UX■ AIX

NOTE The BMC II Web Services Server is also installed automatically with the v. 7.1 BMC Impact Solutions Installation package when you select the Enable Web Services for Event Integration check box. The BMC II Web Services Server is installed with the BMC Impact Administration Server.



Installing the web services server package

Before you begin

■ Uninstall any earlier version of the BMC Impact Integration Web Services Server. See “Uninstalling the web services server package” on page 34 for the procedure. Before uninstalling an earlier version, you may want to save any customized mcell.dir, iiws.conf, or iiws.selector files.

■ By default, the BMC II Web Services Server (by means of the HTTP transport server) and the WSCELL event listener connect to BMC IM cells through port numbers 6070 and 19999, respectively. To verify that these ports are available, perform the following procedure.

1. In a Command Prompt or in a terminal window, enter the following command:

netstat -a -n

It returns output that displays all connections and listening ports, together with their addresses and port numbers.

2. If the default ports are in use, determine which port numbers you will use and change the defaults when prompted to do so during the installation.

You can also change the port numbers after installation by editing the server configuration file. See “Updating default port numbers post installation” on page 55.

■ Windows users must install the package under an administrator account or an account with administrator privileges.

■ Linux, Solaris, HP-UX, and AIX users can install under a local account.

■ Know the location of your Java Runtime Environment (JRE™). The installation program tries to locate it in certain directories. If it does not find it, the installation program exits.

■ On UNIX platforms, you can enter the whereis command (for example, whereis java) to locate your Java home directory. Or you can use the find . | grep or a variation of the find command to locate the JRE. You should change directory to the Java home directory to make sure that it contains the JRE.

On UNIX platforms, to instruct the installation script to use a particular JRE, enter the following command:

./installScript -is:javahome /directoryPathToJRE

NOTE Linux, Solaris, HP-UX, and AIX users. The server connects through port number 6070 by default. If you intend to use a reserved port (port number 1024 or lower), you should install under the root account to ensure that you can access the selected reserved port.



■ On Windows platforms, you can verify your Java version by entering java -version from a Command Prompt window. You may need to edit your Windows PATH variable by adding the file path to your JRE in the Windows PATH definition. You may also need to define a Java_Home and a ClassPath system variable.

■ AIX users. Your AIX system requires the XLC runtime libraries 6.0.0.11. If your AIX system does not contain these libraries, you must download and install these libraries before trying to install the BMC II Web Services Server package.

To install the Web Services package on Microsoft Windows

1 Access the login page of the BMC Developer Network (BMCDN) website at http://developer.bmc.com.

2 After you log in, from the main menu choose Developer Centers => BMC Infrastructure Management.

You can navigate to the web page where you can download the toolkit or toolkit component that you want. Refer to the release notes of the Web Services Server component for the latest download instructions.

The MS Windows downloadable file is IIWS71_00.exe. It is a zipped file from which you must extract the setupwin32.exe file.

3 After you extract the files, double-click setupwin32.exe to launch the installation.

The InstallShield Wizard is opened, and the Welcome screen is displayed.

4 Click Next to continue. BMC Software—SDK License Agreement is displayed. For the text of this agreement, see the back matter in this guide.

5 Read the license agreement, and click the radio box to indicate that you accept the terms.

6 Click Next to continue. The installation directory window is displayed.

7 Perform any one of the following actions:

■ Accept the default directory in the Directory Name field.

■ Click Browse to search for another directory path on the file system

■ Enter a custom directory path in the Directory Name text field.

8 Click Next to continue. The next window asks that you enter the BMC II Web Services Server port number and the MCELL event listener port number. Accept the default port number values or specify your own.


https://webapps.bmc.com/epd/



9 Click Next to continue. The next window asks whether you want to install the BMC II Web Services as a system service. By default, it is installed as a system service. If you accept the default value, go to 10 on page 27.

Clear the check box if you intend to start the service manually. Skip to 11 on page 27.

10 Click Next to continue. Specify the name of the service. You can accept the default name (IIWS) or enter your own. If you have more than one BMC II Web Services Server installation of the same version on the host, enter a service name different from the existing service name.

11 Click Next to continue. Decide whether to choose a typical or a custom installation. The typical installation installs both the server and the sample client code in the specified installation directory. The custom installation option lets you choose to install the server, the sample client code, or both.

12 Click Next to continue. The summary window is displayed, showing your installation selections.

13 Click Install to start the installation process.

The program extracts the files and installs them in the specified installation directory. When the installation is complete, a window displays to tell you that the installation is successful or that the program encountered errors during installation.

14 Click Finish if the installation is successful. If the installation encountered errors, review the log file to locate the relevant error.

15 See “Installation directory contents” on page 29 to review the installation directory structure and contents, and see “Post-installation” on page 31 to decide your next step.

If you installed the server as a service (IIWS is the default name), the service is started automatically when the installation is complete.

To Install the Web Services package on Linux, Solaris, AIX, or HP-UX (X Window System)

If you are installing on a remote system, be sure the $DISPLAY variable is set to the remote host and that you have access to the X Window System on the remote host.

NOTE You can click Back to return to a previous window and change a selection.



Contact your system administrator if you have questions regarding instructions and command syntax for running X Window System.

1 Verify that the X Window System is running. If the X Window System is not running, enter the startup command.

2 Access the login page of the BMC Developer Network (BMCDN) website at http://developer.bmc.com.

3 After you log in, from the main menu choose Developer Centers => BMC Infrastructure Management.

You can navigate to the web page where you can download the toolkit or toolkit component that you want. Refer to the release notes of the Web Services Server component for the latest download instructions.

The UNIX or Linux downloadable file for the BMC II Web Services Server is IIWS71_00.tar.gz. The MS Windows downloadable file is IIWS71_00.exe. It is a zipped file that also contains the UNIX and Linux distribution files that you can deploy from a Windows system.

4 After you extract the files into the current working directory, locate and execute the appropriate distribution file for your operating system. See Table 6 on page 28.

5 Follow the online instructions in the InstallShield wizard. See “To install the Web Services package on Microsoft Windows” on page 26 for the sequence of installation windows.

If you choose to install the BMC II Web Services as a daemon, you must manually start the BMC II Web Services Server for its first-time startup. Thereafter it will run automatically in the background. See “Starting and stopping the BMC II Web Services Server” on page 59 for more information.

Table 6 UNIX distribution files

File name Operating system Command

setupaix.bin AIX ./setupaix.bin

setupHP11.bin HP-UX 11 ./setupHP11.bin

setupLinux.bin Linux ./setupLinux.bin

setupSolaris.bin Solaris ./setupSolaris.bin

NOTE You can omit the dot-slash (./) if the directory in which the distribution file resides is defined in your system’s $PATH variable.


https://webapps.bmc.com/epd/


Installation directory contents

To install the web services package on Linux, Solaris, HP-UX, or AIX (console option)

To install the web services package in a non-graphical mode, launch the installation using the console command. For example, if you are running the installation from a remote host and do not have access to the X Window System on the remote host, use the console command to launch the installation in non-graphical mode.

Contact your system administrator if you have questions regarding instructions and command syntax for running the console command.

1 Follow Steps 2 through 5 under “To Install the Web Services package on Linux, Solaris, AIX, or HP-UX (X Window System)” on page 27 to find and launch the installation script.

2 Follow the prompts in the installation script. You must accept the license agreement to proceed with the installation.


Table 7 on page 30 describes the directory contents of the installation package:

TIP Note the name of the installation directory. You will need to enter it later when you define environment variables.

NOTE You can omit the dot-slash (./) if the directory in which the distribution file resides is defined in the $PATH variable.



The installation directory also includes the following files:

■ log.txt – installation log file that is generated if errors are recorded during installation

■ removeservices.bat (Windows) or removedaemon.sh (UNIX) – used by the uninstall script when you uninstall the BMC II Web Services Server.

Table 7 Directory contents

Directory Description

bin contains the ImpactManager.wsdl file along with its accompanying schema definition files, library files, and the executable files for the web services server. UNIX users already have execute permissions on the server executable files.

cache maintains a record on the BMC II Web Services Server of persisted events that were requested by the client through the bmciiws_subscribe_reliable() operation. The cache director is empty until events are received. The size of the cache directory is controlled by the RecvBufferSize parameter defined in the iiws.conf file.

conf contains XML configuration files including those for the BMC II Web Services Server, http server, and openSSL components

locale contains the language support message catalog files and the iiws.load file. Do not modify these files.

mcell contains the default configuration, selector, and trace files that define the communication parameters between the C APIs and the BMC Impact Manager instances. It also contains the mcell.dir file, which identifies the

■ BMC Impact Manager instances that the BMC II Web Services component communicates with

■ name of the event listener (WSCELL) that connects with and receives events from BMC Impact Manager instances

openssl contains the script for generating the server OpenSSL certificate. It also includes a sample private key and a sample public key, along with self-signed trusted certificates that can be shared by client and server.

samples contains the sample client configuration files for C++, C#, and Java in waspc, .NET, and AXIS directories. It also includes the EventListener.wsdl and listenercfg.xml files, both of which are required to build a listener client.

The samples directory is not included in the BMC Portal installation of the BMC II Web Services Server.

_uninst uninstall directory containing the uninstaller executable and related files


Post-installation

Post-installationTo troubleshoot installation errors, refer to the output written to the InstallShield or terminal window.

If you are using Windows, go to “Setting environment variables under Microsoft Windows” on page 31. If you are using Solaris, Linux, HP-UX, or AIX, go to “Setting environment variables under Solaris, Linux, HP-UX, and AIX” on page 32.

Setting environment variables under Microsoft Windows

You can edit the system %PATH% environment variable to add the following directory links:

■ installDirectory■ installDirectory\bin

Before you begin

The exact steps for defining environment variables vary from one Windows operating system to another. Refer to your Windows documentation or online help for information on defining environment variables in your version of Windows.

To set environment variables (Windows)

1 Open the Environment Variables dialog box either from your desktop or from the Start menu

2 Under System Variables, select the %PATH% variable, and click Edit.

3 In the dialog box, add the following links to the path string: installDirectory; installDirectory\bin.

NOTE After you start the BMC II Web Services Server, log and tmp directories are created under the drive:\installDirectory or $installDirectory path. The log directory stores events on the BMC II Web Services Server during non-reliable subscription connections established by clients. The persist.dat file acts as a persistent buffer for outgoing events and the uniqueId.dat file acts as a counter for the events. The tmp directory stores a server log file.


Setting environment variables under Solaris, Linux, HP-UX, and AIX

Include the drive letter to specify the disk drive where the BMC Impact Integration Web Services Server package is installed, and use a trailing semicolon to separate entries.

For example, if the installDirectory is called imws, and the installation is on the C drive, your entries would appear as follows:

C:\imws\; C:\imws\bin

4 Click OK to close the dialog box and return to the Environment Variables dialog box. Continue to click OK in the succeeding dialog boxes to end the task.

Where to go from here

Go to Chapter 3, “Configuration,”to begin configuring the BMC II Web Services Server.


You can

■ add directory paths to the $PATH environment variable

You must add the library path to the

■ $LD_LIBRARY_PATH environment variable under Solaris and Linux

■ $SHLIB_PATH environment variable under HP-UX

■ $LIBPATH environment variable under AIX

To add directory paths to the $PATH

Open a terminal window, and enter the appropriate command syntax depending on your shell script:

NOTE You can define these variables in your .profile file under the Bourne or Korn shell, in your .cshrc file under C shell, or in your .bashrc file under Bash shell. You can source the file to set the variables.



Bourne, Korn, or Bash Shell

PATH=$PATH:/installDirectory:/installDirectory/bin;export PATH

C Shell

setenv PATH $PATH:installDirectory:installDirectory/bin

To define the $LD_LIBRARY_PATH variable (Solaris and Linux)

Open a terminal window, and enter the appropriate syntax for your shell:


LD_LIBRARY_PATH=/installDirectory/bin;export LD_LIBRARY_PATH

C Shell

setenv LD_LIBRARY_PATH /installDirectory/bin

To define the $SHLIB_PATH variable (HP-UX)



SHLIB_PATH=/installDirectory/bin;export SHLIB_PATH

C Shell

setenv SHLIB_PATH /installDirectory/bin

To define the $LIBPATH variable (AIX)



LIBPATH=/installDirectory/bin;export LIBPATH

C Shell

setenv LIBPATH /installDirectory/bin


Uninstalling the web services server package

Where to go from here

Go to Chapter 3, “Configuration” for information on how to configure your BMC II Web Services Server.


Before you begin

On UNIX platforms, ensure that the BMC II Web Services Server is stopped. On Windows platforms, remove the BMC II Web Services Server service by running the removeservice.bat file from a Command Prompt window. The removeservice.bat file is located in your BMC II Web Services Server installDirectory, from which you can execute it.

To uninstall the web services package on Microsoft Windows

1 From the task bar, choose Start => Settings => Control Panel.

2 In the Control Panel window, choose Add/Remove Programs.

3 In the Add/Remove Programs window, scroll down until you locate the Impact Integration Web Services entry.

4 Select the Impact Integration Web Services entry, and click Change/Remove.

The Uninstaller wizard is opened.

5 Click Next to continue.

6 Follow the prompts in the Uninstaller wizard.

NOTE The exact steps for uninstalling a product vary somewhat among the different supported Windows operating systems. This procedure describes the general steps that are true across all supported Windows operating systems.

NOTE If you have created multiple instances of the web services server or client on the same host and have changed their directory location to a folder outside the original installation directory, the Uninstaller is not going to remove the component. You have to delete the folder manually.



The next window lists the results of the operation, indicating whether the uninstallation is successful.

7 If successful, click Finish.

The components are removed from the specified installation directory.

8 Manually remove the remaining folders and files.

To uninstall the web services package on Linux, Solaris, HP-UX, or AIX

1 Change directory to the uninstall directory -uninst.

2 Run the following command:

./uninstaller.bin

3 Follow the steps as directed and manually remove any remaining files.

NOTE If you have created multiple instances of the web services server and placed them in different directory paths, you have to manually remove them also.


C h a p t e r 3
3 Configuration
This chapter describes both the required configuration tasks that enable your BMC II Web Services Server connection and the optional tasks, such as establishing high availability cells. It also describes basic operations, such as starting and stopping the server, and it provides an overview of administrative tasks.

Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38How to synchronize BMC II Web Services Server and BMC IM cell connections. .

38Troubleshooting tip: BMC II Web Services Server fails to reconnect . . . . . . . . . . 44Defining Propagate rules or event propagation policies for BMC IM cells . . . . . 45

Optional configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Configuring high availability cells for the BMC II Web Services Server . . . . . . . 51Configuring HA cells for BMC II Web Services Server in the BMC Performance

Manager environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Updating default port numbers post installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Configuring Attributes in the BMC II Web Services Server . . . . . . . . . . . . . . . . . . 57Modifying the default BMC II Web Services Server log . . . . . . . . . . . . . . . . . . . . . 58

Starting and stopping the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . 59Microsoft Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Connecting to BMC II Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Installing multiple instances of the BMC II Web Services Server . . . . . . . . . . . . . . . . . 62

When to assign a unique server instance name . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Administering the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64


Required configuration tasks

Required configuration tasksConfiguring the BMC II Web Services Server consists of the following required tasks:

How to synchronize BMC II Web Services Server and BMC IM cell connections

Both your BMC Impact Integration Web Services Server installation and its connected BMC Impact Manager instances reference their distinct versions of the mcell.dir files.

In the BMC Impact Integration Web Services Server installation, the mcell.dir file has two types of cell entries:

■ one for its WSCELL event listener ■ the other for any BMC IM cells with which it communicates

In the BMC Impact Manager instance, its mcell.dir file must specify

■ other cells that it connects with■ the WSCELL event listener entry of the BMC II Web Services Server to which it

sends or propagates events

Table 8 Required configuration tasks

Task Description Page

Synchronizing BMC II Web Services Server and BMC IM cell connections

To send events to or query against specific BMC Impact Manager instances, you must enter their cell data in the mcell.dir of the BMC II Web Services Server. To receive events from BMC IM cells, you must enter data about the WSCELL event listener in the mcell.dir file of each BMC Impact Manager instance that sends events to the server.

38

Defining Propagate rules or event propagation policies for BMC IM cells

To receive events (aside from state change events) from BMC IM cells, you must define Propagate rules or event propagation policies that specify the WSCELL entry of the BMC II Web Services Server.

Note: You do not need to define Propagate rules or event propagation policies to receive service component state change events. After you register the BMC II Web Services Server instance with the SIM cell, the cell automatically sends the state change events to the server. See “Registering and receiving service component state change events” on page 98 for more information.

45

NOTE You only need to add the WSCELL entry to the mcell.dir of the cell if it is sending events to the BMC II Web Services Server.



Table 9 on page 39 shows the default directory location of the mcell.dir file in the BMC Impact Manager and in BMC Impact Integration Web Services Server installations.

mcell.dir entries for multiple cells that comprise a service model

To ensure consistent communication among multiple cells containing components of a service model, BMC recommends that you make all cell entries uniform. That is, if a service model is published across cells A, B, C, and D, then the mcell.dir file of each cell should reference all cells in the model. For example, the mcell.dir file of cell A would contain the following entries:

Similarly, each subsequent cell’s mcell.dir would also reference the other cells in the service model.

mcell.dir configurations for different server implementations

You configure the mcell.dir files of the BMC II Web Services Server and its connected BMC IM cells differently depending on the purpose of the BMC II Web Services Server instance:

■ to query events, data, or a service model■ to send events■ to receive events

Queries

Table 10 on page 40 lists the mcell.dir configuration entries of a BMC II Web Services Server implementation that queries events, data, and the service model.

Table 9 Location of mcell.dir Files

Operating System BMC Impact Manager instanceBMC Impact Integration Web Services Server instance

Windows %MCELL_HOME%\etc drive:\installDirectory\mcell

Solaris, Linux, HP-UX, AIX

$MCELL_HOME/etc installDirectory/mcell

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell cellA MC myIMComputer:1828cell cellB MC myIMComputer1:1828cell cellC MC myIMComputer2:1828cell cellD MC myIMComputer3:1828



Figure 2 on page 40 depicts an example mcell.dir configuration of a BMC II Web Services Server that is used to query a service model which is distributed across three BMC IM cells. The mcell.dir file contains entries for all the cells that comprise the service model.

Figure 2 mcell.dir example: BMC II Web Services Server

Figure 3 on page 40 shows an example mcell.dir configuration of a cell that comprises part of the service model. The other cells in the service model are also included. The WSCELL entry denoting the BMC II Web Services Server is omitted because no events are being sent from the cell.

Figure 3 mcell.dir example: BMC IM cell

Sending events

Table 11 on page 40 lists the mcell.dir configuration entries of a BMC II Web Services Server implementation that sends events. The mcell.dir entries for both the BMC II Web Services Server and the BMC IM instances are identical to those of a query implementation.

Table 10 mcell.dir configurations for queries

Purpose of BMC II Web Services Server instance

mcell.dir entries: BMC II Web Services Server instance mcell.dir entries: BMC IM instances

To query events, data, or a service model

■ its local WSCELL entry■ the cell or cells that it

communicates with, including all cells that comprise a service model

■ the local cell entry■ all cells that it communicates

with, including all cells that comprise a service model

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell WSCELL MC myWSComputer:19999cell cellConnect MC myIMComputer:1828cell cellConnect 1 MC secondIMComputer:1828cell cellConnect 2 MC thirdIMComputer:1828

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell cellConnect MC myIMComputer:1828cell cellConnect 1 MC secondIMComputer:1828cell cellConnect 2 MC thirdIMComputer:1828

Table 11 mcell.dir configurations for sending events



To send events ■ its local WSCELL entry■ the cell or cells that it

communicates with, including all cells that comprise a service model


with, including all cells that comprise a service model



Receiving events

Table 12 on page 41 lists the mcell.dir configuration entries of a BMC II Web Services Server implementation that receives events. Whenever a BMC IM cell sends events to a BMC II Web Services Server instance, its mcell.dir must contain the WSCELL entry that points to the server that receives the events.

Figure 4 on page 41 continues with the example shown in Figure 2 on page 40, in which the mcell.dir of the BMC II Web Services Server contains the three cells that comprise the service model to which the server is connected. You can follow this example to list cells that the server

■ queries■ sends events to ■ receives events from

Figure 4 mcell.dir example: BMC II Web Services Server

Figure 5 on page 42 shows an example mcell.dir configuration of a cell that comprises part of the service model and which sends events to the BMC II Web Services Server. You must include the WSCELL entry to specify the server that receives the events.

Table 12 mcell.dir configurations for receiving events



To receive events, including state change events, from connected cells

■ its local WSCELL entry■ the cell or cells that it

communicates with, including all cells that comprise the service model

■ the WSCELL entry identifying the BMC II Web Services Server instance to which it is sending events


with, including all cells that comprise the service model

NOTE Except for state change events, you must define a Propagate rule or an event propagation policy for each cell from which the server receives events. See “Defining Propagate rules or event propagation policies for BMC IM cells” on page 45 and also for more information.




Figure 5 mcell.dir example: BMC IM cell

If your BMC II Web Services Server implementation serves multiple purposes, one of which is receiving events, then follow the mcell.dir examples for receiving events.

Before you begin

To verify whether the default port numbers are available, run the netstat -a -n command. See “Installing the web services server package” on page 24 for more information.

To add WSCELL entries to BMC IM mcell.dir files

Follow these steps if the cells are propagating events to the BMC II Web Services Server.

1 In a text editor, open the mcell.dir file of the BMC Impact Manager cell that is sending the events to the server.

The file is located under the drive:\MCELL_HOME\etc or MCELL_HOME/etc directory.

2 If the BMC IM cell is sending events to a single BMC II Web Services Server, add the WSCELL entry as shown in the following figure. Include the host name or IP address and the port number. The lookup combination of event listener name/host name/port number must be unique for each WSCELL instance.

3 If the cell is sending events to multiple BMC II Web Services Server instances, then add the corresponding WSCELL entries. Specify a unique combination of name, IP address (or host name), and port number for each WSCELL entry.


<Type> <Name> <EncryptionKey> <IPAddress:Port>cell cellConnect MC myIMComputer:1828cell WSCELL MC myWSComputer:19999



For example, if the server instances are on different systems, you can make the WSCELL entries as shown in the following figure:

Because each BMC II Web Services Server instance is on a different host system, you do not have to specify a distinct port number for each WSCELL event listener.

If the server instances are on the same system, your WSCELL entries might be written as in the following figure:

Because the server instances reside on the same system, the WSCELL entries must have a unique port number. See “To Change the Port Number of the WSCELL event listener” on page 57 for the procedure.

4 Save and close the file.

5 Restart the BMC Impact Manager cell.

6 Repeat Steps 1 through 5 in the mcell.dir file of each BMC Impact Manager instance that is sending events to the server.

7 To enable the BMC II Web Services Server to receive events from the connected cell, you must add a Propagate rule that specifies its WSCELL to the Knowledge Base (KB) of the BMC Impact Manager instance. See “Defining Propagate rules or event propagation policies for BMC IM cells” on page 45. Alternatively, you can add a Propagate policy through the BMC Impact Explorer GUI.

To add BMC Impact Manager instance entries to the BMC II Web Services Server’s mcell.dir file

For each BMC IM cell with which your BMC IM Web Services Server communicates, you must make a corresponding entry in the server’s mcell.dir file.

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell cellConnect MC myIMComputer:1828cell WSCELL MC myWSComputer:19999cell WSCELL1 MC secondWSComputer:19999cell WSCELL2 MC thirdWSComputer:19999

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell cellConnect MC myIMComputer:1828cell WSCELL MC myWSComputer:19999cell WSCELL1 MC myWSComputer:20000cell WSCELL2 MC myWSComputer:20001


Troubleshooting tip: BMC II Web Services Server fails to reconnect

1 In a text editor, open the mcell.dir file located under drive:\installDirectory\mcell or installDirectory/mcell.

2 Add the cell data for each BMC Impact Manager cell that you intend to connect to, as in the following example:

Guidelines

■ Do not change the local host IP address of 127.0.0.1 of the WSCELL entry in the mcell.dir file of the BMC II Web Services Server.

■ If you intend to query or communicate with a service model, include all cells that comprise the service model in the mcell.dir file.


4 Start or restart the server. If you have other configuration changes to make, you can start or restart the server when you are finished. See “Starting and stopping the BMC II Web Services Server” on page 59.

Troubleshooting tip: BMC II Web Services Server fails to reconnect

When you stop and restart the BMC II Web Services Server on UNIX platforms, the WSCELL event listener may fail to reconnect immediately through the listener port that is defined in the BMC II Web Services Server’s mcell.dir file. You will receive an error message similar to the following: Error: IIAPI: BMC-IDK012156E: Unable to setup server, 12:Service endpoint could not be bound. The cause of this error is that the UNIX operating system does not immediately release the port number after you stop the BMC II Web Services Server daemon.

To resolve this problem, you can either

■ wait a few minutes before you restart the BMC II Web Services Server; or

■ change the listener port number defined in the server’s mcell. dir file to some other available port

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell WSCELL MC 127.0.0.1:19999cell cellConnect MC myIMComputer:1828cell cellConnect1 MC myIMComputer1:1828cell cellConnect2 MC myIMComputer2:1828cell cellConnect3 MC myIMComputer3:1828



If you change the WSCELL port number entry in the server’s mcell.dir file, remember also to change it in the mcell.dir files of all cells that send events to the server.


To enable the BMC II Web Services Server to receive events from a BMC IM cell and pass the events on to a subscribing client, you must do one of the following:

■ add one or more Propagate rules to the KB of the BMC Impact Manager instance that is sending the events

■ define a event propagation policy in the BMC Impact Explorer that specifies the event criteria

The Propagate rule or event propagation policy specifies that the BMC Impact Manager instance sends events to the WSCELL event listener residing on the BMC II Web Services Server.

For example, if one WSCELL event listener is receiving events from three BMC Impact Manager instances, then each instance must specify a Propagate rule or an event propagation policy.

Figure 6 on page 46 depicts three BMC Impact Manager instances that are sending events to the WSCELL event listener. You define a Propagate rule or an event propagation policy for each instance, specifying the WSCELL event listener as the destination of the event.

NOTE You do not need to define a Propagate rule or event propagation policy to receive service component s state change events. See “Registering and receiving service component state change events” on page 98 for more information.



Figure 6 Event propagation: many instances to one server

If multiple WSCELL listeners are receiving events from multiple Impact Manager instances, then for each WSCELL listener you add a Propagate rule or specify an event propagation policy. Figure 7 on page 47 depicts this example.



Figure 7 Event propagation: many instances to many servers

In Figure 7, two BMC II Web Services Servers, Zebra and Giraffe, receive events from three BMC Impact Manager instances, all of which contain components of the same service model. Each instance must have a Propagate rule or an event propagation policy that specifies the WSCELL event listener or listeners that receive the events. In this example, each instance has to define a rule or policy for both servers. In addition, because all of the cells belong to the same service model, each cell’s mcell.dir file must list the other cells.

Example Propagate rules

This section describes sample Propagate rules and describes how to manually add a Propagate rule to the cell’s KB. Refer to the BMC Impact Solutions:Knowledge Base Development for additional information about Propagate rules. (For information on creating an event propagation policy, see the BMC Impact Solutions:Administration guide.)

TIP When defining your Propagate rule or event propagation policy, be sure to specify the name of the WSCELL entry exactly as it is defined in the mcell.dir file.



A Propagate rule might be written as follows:

If you are using the same selector criteria and sending the same events to multiple BMC II Web Services Servers (multiple WSCELL entries WSCELL and WSCELL1, for example), then your Propagate rule might look as follows:

If you are using different selector criteria to send different events to each BMC II Web Services Server, then you would write a different Propagate rule for each WSCELL. If you are sending different events to WSCELL and WSCELL1, your Propagate rules might look as follows:

You can add any valid Propagate rule to the KB of a BMC Impact Manager instance to propagate events to the BMC II Web Services Server.

The task of creating a Propagate rule includes the following procedures that you must perform in order:

1. Create the Propagate rule in a .mrl file.

2. Add the .mrl containing the Propagate rule to the .load file in the rules subdirectory of the BMC Impact Manager instance.

3. Compile the KB of the BMC Impact Manager instance.

4. Restart the BMC Impact Manager instance to initialize the change.

propagate to_WSCELL:EVENT ($EV)to WSCELL

END

propagate to_WSCELL:EVENT ($EV)to_all WSCELL, WSCELL1

END

propagate to_WSCELL:EVENT ($EV)to WSCELL

ENDpropagate to_WSCELL1:

EVENT ($EV)to WSCELL1

END



To create a Propagate rule

1 In a text editor, open an existing .mrl file, which you can find under the drive:\installDirectory\etc\cellName\kb\rules or installDirectory/etc/cellName/kb/rules directory.

2 Remove the text of the existing rule between the last comment symbol (#) and the END marker.

3 Add the new Propagate rule syntax to the file.

You can give the file any name and include comments. Your file would look similar to the following example.

4 Save the .mrl file, giving it a unique name and making sure that a .txt extension is not added.

5 After you create a Propagate rule in a .mrl file, add the .mrl file with the new Propagate rule to the .load file in the rules subdirectory. See the next procedure.

To add a Propagate rule to the .load file

1 In a text editor, open the .load file under the directory drive:\installDirectory\etc\cellName\kb\rules or installDirectory/etc/cellName/kb/rules.

2 Add the name of the .mrl file containing the new Propagate rule without the file extension.

#-------------------------------------------------------------#Impact Manager#Copyright 1998-2007 BMC Software, Inc. All rights reserved.#Filename : mc_wscell.mrl #-------------------------------------------------------------# This rule propagates events to the WSCELL residing on the# BMC II Web Services server.#propagate to_WSCELL:

EVENT ($EV)to WSCELL

END

NOTE You can add to the KB of the BMC Impact Manager instance any valid Propagate rule that propagates events to the WSCELL.



3 Save the .load file in the same directory, making sure that a .txt extension is not added.

4 After you add the .mrl file containing the new Propagate rule to the .load file, compile the KB of the BMC Impact Manager instance. See the following procedure.

To compile the Knowledge Base of the BMC Impact Manager Instance

1 In a Command Prompt or in a terminal window, change directory to drive:\installDirectory\etc\cellName\kb or installDirectory/etc/cellName/kb.

2 Enter the following command:

mccomp manifest.kb

The new Propagate rule is added to the KB of the BMC Impact Manager instance.

3 Next, restart the BMC Impact Manager Instance to initialize the change.

To restart the BMC Impact Manager instance in Microsoft Windows

1 In a Command Prompt window, enter the following command:

NET STOP mcell_cellName

2 Then enter the start command:

NET START mcell_cellName

To restart the BMC Impact Manager instance in Linux, Solaris, or HP-UX

1 In a terminal window, enter the following command:

mkill -n cellName

2 Then enter the start command:

mcell -n cellName


Optional configuration tasks

Optional configuration tasksYou can configure high availability cells for the BMC II Web Services Server to ensure a consistent connection in the event that the primary cell fails. The installation routine sets the default values for port numbers, server attributes, and log files. However, you can modify these values after installation. Table 13 on page 51 lists the optional configuration tasks.

Configuring high availability cells for the BMC II Web Services Server

To maximize availability, BMC recommends that you install your primary cell on one computer and your secondary cell on a different computer. Both primary and secondary cells should be installed and running on different images of the same operating system.

Your HA implementation can take many forms, but two likely ones are depicted in the following figures.

Table 13 Optional configuration tasks

Task Description Page

Configuring high availability cells for BMC II Web Services Server

You can configure two cells so that one acts as a secondary server to the primary one in case the primary server fails. In this way, the BMC II Web Services Server can communicate with a secondary cell server until the primary one returns online.

51

Configuring high availability cells for BMC II Web Services Server in the BPM environment

You can configure an HA pair to accommodate a primary and a backup web services server in the BMC Performance Manager (BPM) environment.

54

Updating default port numbers post installation

You can update these port numbers after installation if a port number conflict develops.

55

Configuring attributes in the BMC II Web Services Server

You can specify the values for certain server attributes. You can define the size of event queues if are using query or polling calls in your client.

57

Default logging This topic describes the different log files that the BMC II Web Services Server uses.

58

NOTE Refer to the BMC Impact Solutions: General Administration guide for detailed information about high availability (HA) implementation.



Figure 8 on page 52 shows a scenario in which the BMC II Web Services Server and the primary cell server of the HA pair are installed on the same system. The secondary cell server of the HA pair is installed on a second system.

In this scenario, because the cell both sends and receives events to and from the BMC II Web Services Server, both primary and secondary cell servers must have a WSCELL entry in their respective mcell.dir files. (If the cell servers were only receiving events from the BMC II Web Services Server, then they would not need the WSCELL entry.)

Figure 8 HA implementation scenario: primary cell server and web server on same system

Figure 9 on page 53 shows a scenario in which the BMC II Web Services Server and the primary cell server of the HA pair are installed on different systems. The secondary cell server of the HA pair is installed on a third system.



As in the previous scenario, the cell both sends and receives events to and from the BMC II Web Services Server. Consequently, both primary and secondary cell servers must have a WSCELL entry in their respective mcell.dir files.

Figure 9 HA implementation scenario: primary cell server and web server on different systems

Follow these guidelines to install and configure a primary and a secondary cell in an HA pair:

■ Be sure to install BMC Impact Manager on the two different computers that host the cell servers. They must be installed on the same operating system.


Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment

■ Use the BMC Impact Solutions installation routine to install the HA cells. When using the installation routine, the mcell.dir and mcell.conf files of the respective cells are updated automatically.

■ Configure the mcell.dir file of the BMC II Web Services Server to accommodate the HA cell configuration.

■ Restart the cell servers.

Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment

The same rules for configuring high availability cells for the BMC II Web Services Server also apply to the BMC Performance Manager (BPM) environment. BPM does add the extra feature of having a backup BMC II Web Services Server. Both the primary and backup web services servers connect to the same primary cell server. The HA configuration is specified in the mcell.dir files of the primary and secondary cell servers.

Figure 10 on page 55 depicts a recommended HA cell configuration where BPM has specified a primary and a backup web services server. Note that the cell does not have to reside on the same system as the web services server.



Figure 10 HA implementation scenario for BPM and BMC II Web Services Server


Table 14 lists the default port numbers that the BMC II Web Services Server uses. If these default ports are being used by another process, you must change the default port numbers so that the BMC II Web Services Server and client can communicate with each other and with connected BMC Impact Manager instances.

Table 14 Default port numbers

Component File

Default Port Number

HTTP transport server

Windows: drive:\installDirectory\conf\ servercfg.xml Solaris, Linux, HP-UX, AIX: installDirectory/conf/servercfg.xml

6070

WSCELL Windows: drive:\installDirectory\mcell\mcell.dirSolaris, Linux, HP-UX, AIX: installDirectory/mcell/mcell.dir

19999


The HTTP transport server, defined in the servercfg.xml file, specifies the port number through which the BMC II Web Services client exchanges request-response messages with the BMC II Web Services Server.

The WSCELL is described in “WSCELL event listener” on page 18. Each instance of the BMC II Web Services Server must have an associated WSCELL entry.

To Change the port number on the BMC Impact Integration Web Services Server

1 In a text editor, open the servercfg.xml file located under drive:\installDirectory\conf or installDirectory/conf.

Figure 11 on page 56 shows the default declaration of the servercfg.xml file. The port number attribute is highlighted in bold. The hts:port attribute specifies the default port number 6070 for the server port.

Figure 11 servercfg.xml file: default declaration

<waspc-config xmlns:wasp=”urn:WaspServer” xmlns:cppa=”urn:CppAdaptor” xmlns:sep=”urn:ServiceEndpoint”xmlns:svci=”urn:ServiceInstanceRepository”xmlns:trans=”urn:TransportRepository”><wasp:import ref=”serverbase.xml”/><trans:transport trans:class=”WASP_HTTPTransportServer”

trans:scheme=”server-http” xmlns:hts=”urn:HTTPTransportServer”hts:reuseCount=”15”hts:reuseTimeout=”30”hts:rwTimeout=”30”hts:acceptTimeout=”5”hts:chunked=”true”hts:port=”6070”hts:hostname=”$AUTO$”hts:dispatcher=”DefaultDispatcher”hts:singleThread=”0”hts:maxSpareThreads=”-1”hts:maxThreads=”-1” />



<sep:serviceEndpoint sep:dispatcherRef=”DefaultDispatcher” sep:adaptorRef=”DefaultCppAdaptor” cappa:wsdl=”/installDirectory/bin/ImpactManager.wsdl”

sep:url=”/imapi”><cppa:additionalWSDL cppa:url=”BasicTypes.xsd”

cppa:location=”BasicTypes.xsd”/><cppa:additionalWSDL cppa:url=”Event.xsd”

cppa:location=”Event.xsd”/><cppa:additionalWSDL cppa:url=”ImapiTypes.xsd”

cppa:location=”ImapiTypes.xsd”/><cppa:instance cppa:ref=”imapi”/>

</sep:serviceEndpoint>

Configuring Attributes in the BMC II Web Services Server

2 In the trans:transport element tag, change the value of the hts:port attribute to an available port number.



To Change the Port Number of the WSCELL event listener

1 In a text editor, open the mcell.dir file located under drive:\installDirectory\mcell or installDirectory/mcell.

2 Change the port number.

3 Save and close the mcell.dir file.


Configuring Attributes in the BMC II Web Services Server

You can configure the MaxResponseEventListSize attribute of a BMC II Web Services Server. This attribute defines the web service instance in the servercfg.xml file.

The MaxResponseEventListSize attribute is an absolute value of type int. It defines the maximum number of events that the server returns per polling request. This value can be different from the number of events that the client requests. The default value is 30. The recommended range of values is 20 to 100.

Update the attribute in the BMC II Web Services Server by changing the value in the servercfg.xml file.

<svci:serviceInstance svci:name=”imapi”svci:class=”IMWSimpl”svci:MaxReturnEventListSize=”30”svci:IIAPIConfigFile=”/installDirectory/mcell/iiws.conf”svci:IIAPISelectorFile=”/installDirectory/mcell/

iiws.selector”svci:IIWSInstanceName=”IIWS_Server”svci:MessageListenerCellName=”WSCELL”svci:ServerCacheDIR=”/installDirectory/cache”

</waspc-config>


Modifying the default BMC II Web Services Server log

To update attributes in the servercfg.xml File

1 Open the drive:\installDirectory\conf\servercfg.xml file or installDirectory/conf/servercfg.xml file in a text editor. Refer to Figure 11 on page 56.

2 Using the information in this section as a guide, modify the attribute values.

3 Save the file.


Modifying the default BMC II Web Services Server log

By default, the BMC II Web Services Server uses the installDirectory/mcell/trace.log or drive:\installDirectory\mcell\trace.log to record its activities. A BMC II Web Services Server administrator can modify the trace.log parameters such as log file name and directory location in the iiws.conf file found under

■ installDirectory/mcell/

■ drive:\installDirectory\mcell\

The administrator can change the default logging level in the iiws.trace file also found under the same directory path.

To modify the default log parameters

1 In a text editor, open the iiws.conf file. The trace parameters are contained in the following stanza, depicted in the following example:

2 Modify the configuration parameters. Refer to “Configuration file parameters” on page 123 for a description of the configuration parameters. Skip to Step 5 if you are done with your changes.

3 To change the level of logging detail, open the iiws.trace file. You can modify the default values, which are depicted in the following example:

Trace=YesTraceSrc=NoTraceConfigFileName=iiws.traceLocaleConfigFileName=C:\Program Files\BMC\IIWS/locale/iiws.loadTraceDefaultFileName=trace.logTraceFileSize=1024000TraceFileHistory=1TraceFileAppend=No


Starting and stopping the BMC II Web Services Server

4 Modify the file according to the instructions in the BMC Impact Solutions: General Administration guide. You can refer also to “Editing the trace configuration file” on page 138 for more information.

5 Restart the BMC II Web Services Server to initialize the changes.

Starting and stopping the BMC II Web Services Server

This section describes how to start and stop the BMC II Web Services Server automatically as a service or daemon process. It also describes how to start the server in a Command Prompt window under Windows and in a terminal window under UNIX.

Before you begin

Ensure that you have

■ updated your system variables as described in “Setting environment variables under Microsoft Windows” on page 31 and “Setting environment variables under Solaris, Linux, HP-UX, and AIX” on page 32.

Verify that

■ any BMC Impact Manager instances that you want to connect to are entered in the BMC II Web Services Server’s mcell.dir file under drive:\installDirectory\mcell or installDirectory/mcell

■ the BMC II Web Services Server’s WSCELL entry has been added to the mcell.dir file under drive:\installDirectory\etc or installDirectory/etc of each BMC Impact Manager installation from which you want to receive events

ALL ALL stderr ALL VERBOSE no

NOTE The BMC II Web Services Server temporarily keeps client-requested events in the drive:\installDirectory\log or installDirectory/log subdirectory for non-reliable subscriptions and in the drive:\installDirectory\cache or installDirectory/cache subdirectory for reliable subscriptions. The events remain in the log or cache folders until the client consumes them or the client unsubscribes from the server.


Microsoft Windows

Microsoft Windows

On Windows computers, if you install the BMC II Web Services Server as a service, the service is started automatically when the installation is complete. You can stop and restart the service through the Windows Control Panel. Under Services, locate the BMC II Web Services Server process name (iiws_IIWS, by default) in the list, right-click to open the pop-up menu, and choose the appropriate command.

If you do not install the BMC II Web Services Server as a service, you will need to start the server manually in the Command Prompt window.

The startup command requires that you specify only one parameter, the location of the server configuration file (servercfg.xml). You launch this server startup command from the \bin subdirectory of the installation directory: for example, drive:\installDirectory\bin.

To start the BMC II Web Services Server manually (Microsoft Windows)

1 In a Command Prompt window, change directory to drive:\installDirectory\bin.

2 Enter the following command string:

3 Leave the Command Prompt window open while the server is running.

The output documents the events, which match the selector criteria, that the BMC II Web Services Server receives from the BMC Impact Manager instance.

4 Issue the kill interrupt of the DOS shell to shut down the server. In Windows, it can be Ctrl+C.

UNIX

On UNIX platforms, if you install the BMC II Web Services Server as a daemon, the daemon startup script, IIWSServer, automatically sets the appropriate environment variables. The IIWSServer script is created in the /bin subdirectory (installDirectory/bin).

imserv -console drive:\installDirectory\conf\servercfg.xml

NOTE imserv is the name of the constant that defines the BMC II Web Services Server executable file.


UNIX

To start the server using the script

Depending on how you installed the BMC II Web Services Server package, you can start the server daemon under a local account or as root. In either case, you enter the following command from the /bin subdirectory:

If you have defined the installDirectory/bin path in the $PATH variable, you (or the administrator) can start the server daemon by entering IIWSServer start. The absolute path command is installDirectory/bin/IIWSServer start.

Enter an IIWSServer stop command in a new terminal window to shut down the server gracefully. (The $LD_LIBRARY_PATH variable must be set.)

To start the server using the executable

If you do not install the BMC II Web Services Server as a daemon, you can start the server as a daemon process or a console process. In either case, the startup commands require that you specify only two parameters:

■ the name that you want to give the process ■ the location of the server configuration file (servercfg.xml)

1 Change directory to the /bin subdirectory (installDirectory/bin).

cd installDirectory/bin

2 Enter the following command to start the server as a daemon process:

Or you enter this command to start the server as a console process:

3 Leave the terminal window open while the server is running.

4 To stop the service, enter Ctrl + C on the terminal window. Alternatively, you can retrieve the list of running processes using the ps -ef command, and then enter the kill command against the server’s PID to terminate the process.

./IIWSServer start

./IIWSServer stop

./imserv -start nameOfDaemonProcess installDirectory/conf/servercfg.xml

./imserv -console installDirectory/conf/servercfg.xml


Connecting to BMC II Web Services

Connecting to BMC II Web ServicesAfter you start the BMC II Web Services Server, you can connect to BMC II Web Services at the service endpoint, as defined by the URL

http://hostNameOfServer:portNumber/imapi

where hostNameOfServer identifies where the web services server instance is installed, portNumber identifies the HTTP port (the default is 6070), imapi is the name defined for this web service (you can define your own).

Installing multiple instances of the BMC II Web Services Server

Depending on your deployment strategy and performance loads, you may want to install and run multiple instances of the BMC II Web Services Server service on the same system or on different systems. For example, you can connect each service instance to different clients and BMC Impact Manager instances. A client can subscribe to different event types by connecting to different BMC II Web Services Servers.

To install another instance of the BMC II Web Services Server service, repeat the installation sequence that is appropriate for the platform. If you are installing an service instance on a different system, you can accept the default service name and port number values that the installation routine provides.

If you are installing an instance on the same system, follow these guidelines during the installation:

■ Assign a unique name to the service.■ Ensure that each service instance is assigned unique port numbers.

If a cell is sending events to multiple service instances, assign a unique WSCELL name to each instance in the cell’s mcell.dir file. Refer to “How to synchronize BMC II Web Services Server and BMC IM cell connections” on page 38 for more information.


When to assign a unique server instance name

When to assign a unique server instance name

When multiple servers have registered with the same cell to receive state change events, you must assign a unique server instance name to each server.

To assign a unique server instance name

1 In a text editor, open the servercfg.xml file located under drive:\installDirectory\conf or installDirectory/conf.

See “Updating default port numbers post installation” on page 55 for an example servercfg.xml file.

2 In the svci:IIWSInstanceName element tag, change the default entry to a unique value. For example, you can change it from

to



5 To enable the server instance to receive events, make the appropriate WSCELL entry in the mcell.dir file of the cell that is sending events. See “How to synchronize BMC II Web Services Server and BMC IM cell connections” on page 38 for more information.

NOTE The service instance name and the server instance name are distinct values. You define the service instance name or choose its default value as you are installing the BMC II Web Services Server.

After you install the server, it is automatically assigned the default server instance name IIWS_Server. You can change this configuration value by modifying the IIWSInstanceName configuration parameter in the servercfg.xml file.

svci:IIWSInstanceName="IIWS_Server" svci:MessageListenerCellName="WSCELL"

svci:IIWSInstanceName="IIWS_Server_1" svci:MessageListenerCellName="WSCELL_1"


Administering the BMC II Web Services Server

Administering the BMC II Web Services ServerAdministering the BMC II Web Services Server consists of typical server administration tasks and two tasks unique to the BMC II Web Services implementation: managing the selector file (iiws.selector) and the configuration file (iiws.conf). The Web Services server reads both files at startup. Both files are stored under drive:\installDirectory\mcell or installDirectory/mcell.

The selector file is crucial in determining which events the subscribing clients receive. When you are first setting up and practicing with the BMC II Web Services Server toolkit, you do not need to modify the default iiws.selector file. You can issue subscription requests that include the selector name Always matches for the $ClassName “Event”. Using this selector, your client receives all events propagating from the BMC Impact Manager instances. Later, as you define your client more carefully, you will probably want to modify the selector file.

The iiws.conf is preconfigured so that you do not have to modify the iiws.conf to run the BMC II Web Services Server. Later, as you learn more about your integration needs, you can modify the parameters in the configuration file.

Modifying the selector file is a task best performed by a BMC II Web Services Server administrator who has administered the BMC Impact Manager product. The same administrator can also manage the configuration file, updating the parameters as required.

The mcell directory also contains four supplemental selector files. You can enable one or more of these files to improve the speed and efficiency of event filtering between the BMC II Web Services Server and the cell. These selector files do their processing in the background and, unlike the iiws.selector file, are not loaded by the BMC II Web Services Server at startup.

For more information about the .selector and .conf files, see Appendix A, “BMC Impact Integration Web Services Server Administration.”

NOTE If the server instance is receiving state change events only, you do not need to add a Propagate rule or an event propagation policy. If it is to receive other events in addition to state change events, then you must add a corresponding Propagate rule or an event propagation policy to the KB of the sending cell. See “Defining Propagate rules or event propagation policies for BMC IM cells” on page 45 for the procedure.


C h a p t e r 4
4 Securing web services
This chapter presents guidelines on how to implement secure sockets layer (SSL) security on the BMC II Web Services Server. It is addressed to developers or security administrators who are knowledgeable about secure sockets layer (SSL) implementations.

This chapter describes the following topics:

Secure Sockets Layer (SSL) security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Security implementation advisory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Compatible OpenSSL toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Guidelines for implementing SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Obtaining the OpenSSL source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67About certificate generation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Generating the BMC II Web Services Server certificate (Microsoft Windows) . . 68Generating the BMC II Web Services server certificate (UNIX or Linux) . . . . . . . 69Replacing nonsecure transport parameters with SSL parameters in the

servercfg.xml file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Secure Sockets Layer (SSL) securityHyperText Transport Protocol (Secure) or HTTPS is a secure transport protocol layer. HTTPS is basically a secure version of HTTP that is implemented over a secure sockets layer (SSL) encrypted session. You use “https://” for HTTP URLs over SSL.

SSL encryption, which underlies HTTPS transport, relies on an exchange of trusted certificates between the sender and the receiver. In this case, the web services server and the client exchange certificates that guarantee the server and the client are who they say they are.


Security implementation advisory

The BMC II Web Services server supports HTTPS on all supported operating systems:

■ Microsoft Windows■ Linux■ Solaris■ HP-UX■ AIX

The BMC II Web Services server is not preconfigured with SSL. You can implement SSL on the supported operating systems by using the open source toolkit available through the OpenSSL Project at http://www.openssl.org/. The toolkit enables you to generate your certificates in PEM (privacy enhanced mail) format.

Security implementation advisory

Although the BMC II Web Services Server supports certain client security plug-in modules, it does not provide these modules in its package distribution. BMC does not guarantee that all versions of publicly available security modules are compatible with the BMC II Web Services Server.

Security implementation is the responsibility of the client developer. BMC Software assumes no responsibility for any losses or damages that may result.

Compatible OpenSSL toolkit

The BMC II Web Services Server package is compatible with version 0.9.6 of the OpenSSL toolkit.

Guidelines for implementing SSLThese guidelines summarize the main tasks of implementing SSL security.

Ensure that your BMC II Web Services client understands HTTPS transport.

■ For secure communication between the BMC II Web Services client and server in a development or testing environment, you should generate a self-signed public key and a self-signed private key using the generateOpenSSLServerCer.bat file or generateOpenSSLServerCert.sh script in this BMC II Web Services Server package.


http://www.openssl.org/

Obtaining the OpenSSL source files

For information about generating the keys, see “Generating the BMC II Web Services Server certificate (Microsoft Windows)” on page 68 or “Generating the BMC II Web Services server certificate (UNIX or Linux)” on page 69. Self-signed private keys are not recommended for production environments.

■ For secure communication in a production environment, you should obtain a signed certificate from a certificate authority. To obtain a specific certificate signed by a certificate authority for BMC II Web Services Server, generate a certificate signing request (CSR) and private key for the host system where the BMC II Web Services server resides. To generate these keys, you can download the open source toolkit available through the OpenSSL Project at http://www.openssl.org/.

■ When generating your CSR, remember to specify the correct common name for the server. The common name can be the host and domain name, or if the certificate is to used in an internal network, it can be one word or the name of the server. Store the private key in a server directory that contains trusted certificates.

■ Send the CSR to the certificate authority to obtain the trusted public key certification. You can send your CSR to a certificate authority in an email.

■ When you receive the certificate, store it in an appropriate directory on the BMC II Web Services server.

■ Enter the SSL parameters in the servercfg.xml file under %installDirectory%\conf or $installDirectory/conf. See “Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file” on page 70 for more information.

■ Make the trusted public key certificate available to clients through the BMC II Web Services connection during a secure SSL connection session. The client automatically stores the public key certificate for BMC II Web Services in a certificate directory. This certificate contains information that the client can verify, so it can trust the identity of the host to which it has connected. The certificate can also allow a client to send encrypted data to the server, data that only the server can decrypt.

■ If you generate your own certificate, unsigned by any certificate authority, for the BMC II Web Services server, then any client that wishes to make a secure communication must import the unsigned certificate into its directory of trusted certificates.

Obtaining the OpenSSL source files

You can go to http://www.openssl.org/source to download the appropriate distribution file. Extract the source files from the distribution file using the appropriate utility. Next, follow the instructions included in the download package on how to compile and generate the appropriate library files for your platform.


http://www.openssl.org/source

http://www.openssl.org

About certificate generation

Add the OpenSSL drive:\installDirectory\bin or installDirectory/bin to your PATH variable.

UNIX and Linux users should add the OpenSSL installDirectory/lib directory to the $LD_LIBRARY_PATH variable.

About certificate generation

The generateOpenSSLServerCer.bat file or generateOpenSSLServerCert.sh script in this BMC II Web Services Server package generates a self-signed certificate that you can use for development and testing. To accommodate a production environment, you should obtain a signed certificate from a certificate authority. For information on generating a certificate request and submitting it to a certificate authority, you can go to http://www.openssl.org/.

Generating the BMC II Web Services Server certificate (Microsoft Windows)

1 Copy the following OpenSSL library file

drive:\OpenSSLinstallDirectory\perl\5.8\Net_SSLeay\blib\arch\auto\Net\SSLeay\SSLeay.dll

to the drive:\installDirectory\bin directory of the BMC II Web Services Server.

2 Open a Command Prompt window, and run the BMC II Web Services Server %OpenSSLinstallDirectory%\openssl\generateOpenSSLServerCert.bat file.

This batch file generates a 1024 bit RSA private key and stores it in BMC II Web Services Server %installDirectory%\openssl\server-key.pem. It generates a server certificate and stores it under the %installDirectory%\openssl\certs directory path.

3 Update the drive:\installDirectory\conf\servercfg.xml file with the contents of the servercfg.security.xml file. See “Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file” on page 70 for more information.

NOTE If you receive any error messages, such as unable to write ‘random state’, report them to your developer or OpenSSL expert. Your server certificate has probably not been created.


http://www.openssl.org

Generating the BMC II Web Services server certificate (UNIX or Linux)

Generating the BMC II Web Services server certificate (UNIX or Linux)

1 Ensure that you have execute permission on the $installDirectory/share/waspc/openssl/generateOpenSSLServerCert.sh script file. If needed, run the chmod command from the appropriate directory, as in

chmod 755 generateOpenSSLServerCert.sh

2 Run the generateOpenSSLServerCert.sh script to generate the BMC II Web Services server certificate.

This script generates a 1024 bit RSA private key and stores it in BMC II Web Services Server $installDirectory/share/waspc/openssl/server-key.pem. It generates a server certificate and stores it under the $installDirectory/share/waspc/openssl/certs directory path.

3 Update the $installDirectory/conf/servercfg.xml file with the contents of the servercfg.security.xml file. See “Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file” on page 70 for more information.

NOTE You may need to copy the server certificate to the client system.

NOTE You may need to copy the server certificate to the client system.


Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file


After you obtain the server certificate, you need to instruct the BMC II Web Services server how to authenticate the certificate. You configure the BMC II Web Services server to use HTTPS transport by adding security parameters to the %installDirectory%\conf\servercfg.xml or $installDirectory/conf/servercfg.xml file. These security parameters are copied from either of these files:

■ %installDirectory%\conf\servercfg.security.xml

■ $installDirectory/conf/servercfg.security.xml

Once you copy the parameters, you must remove the transport section from the servercfg.xml file.

To replace nonsecure parameters with secure SSL parameters

1 Open the servercfg.xml file and the servercfg.security.xml file.

2 Copy the code contents of the servercfg.security.xml file and insert them into the servercfg.xml file just after the comment line that says .

3 Remove the following transport section from the servercfg.xml file:

4 Save the servercfg.xml file.

5 Restart the BMC II Web Services server. See “Starting and stopping the BMC II Web Services Server” on page 59.

<trans:transport trans:class=”WASP_HTTPTransportServer” trans:scheme=”server-http” xmlns:hts=”urn:HTTPTransportServer”hts:reuseCount=”15”hts:reuseTimeout=”30”hts:rwTimeout=”30”hts:acceptTimeout=”5”hts:chunked=”true”hts:port=”6070”hts:hostname=”$AUTO$”hts:dispatcher=”DefaultDispatcher”hts:singleThread=”0”hts:maxSpareThreads=”-1”hts:maxThreads=”-1” />

6 To verify that you can connect to the BMC II Web Services server in secure mode, open a browser and enter the following https URL:

https://hostName:6075/imapi

7 Click Yes in the Security Alert window. You should see the ImpactManager.wsdl displayed.

Figure 12 is an example of a Windows-based servercfg.xml file after the contents of the servercfg.security.xml file have been copied into it and the transport section removed. The section shown in boldface text is the contents of the servercfg.security.xml file. The example also uses the default server port number for a secure HTTPS connection, which is 6075.

The library file WASPOpenSSL.dll, referenced in this example, is for a Windows implementation. The library file libwasp_openssl.so is for Linux and Solaris implementations

Figure 12 Servercfg.xml with openSSL parameters added and transport section removed

<waspc-config xmlns:wasp=”urn:WaspServer” xmlns:cppa=”urn:CppAdaptor” xmlns:sep=”urn:ServiceEndpoint”xmlns:svci=”urn:ServiceInstanceRepository”xmlns:trans=”urn:TransportRepository”><wasp:import ref=”serverbase.xml”/><wasp:externalLibrary><wasp:path>WASPOpenSSL.dll</wasp:path><wasp:debugPath>WASPOpenSSLDbg.dll</wasp:debugPath></wasp:externalLibrary><trans:transport xmlns:hts="urn:HTTPTransportServer"xmlns:htssl="urn:HTTPSOpenSSLTransportServer" trans:class="WASP_HTTPSOpenSSLTransportServer" trans:scheme="server-https-openssl"hts:reuseCount="1"hts:reuseTimeout="30"hts:rwTimeout="30"hts:acceptTimeout="5"hts:chunked="true"hts:port="6075"hts:hostname="$AUTO$"hts:dispatcher="DefaultDispatcher"hts:singleThread="0"hts:maxSpareThreads="-1"><htssl:context htssl:class="WASP_OpenSSLContextFactoryImpl"

Contents from servercfg.security.xml file


xmlns:ssl="urn:OpenSSLContextFactory"ssl:certificateFile="openssl/server-cert.pem"ssl:privateKeyFile="openssl/server-key.pem"ssl:privateKeyPasswordFile="openssl/server-pass.txt"ssl:verify="no"><ssl:trustedDir>openssl/certs</ssl:trustedDir></htssl:context></trans:transport>

<sep:serviceEndpoint sep:dispatcherRef=”DefaultDispatcher” sep:adaptorRef=”DefaultCppAdaptor” cappa:wsdl=”/installDirectory/bin/ImpactManager.wsdl” sep:url=”/imapi”><cppa:additionalWSDL cppa:url=”BasicTypes.xsd” cppa:location=”BasicTypes.xsd”/><cppa:additionalWSDL cppa:url=”Event.xsd” cppa:location=”Event.xsd”/><cppa:additionalWSDL cppa:url=”ImapiTypes.xsd” cppa:location=”ImapiTypes.xsd”/><cppa:instance cppa:ref=”imapi”/></sep:serviceEndpoint><svci:serviceInstance svci:name=”imapi”svci:class=”IMWSimpl”svci:MaxReturnEventListSize=”30”svci:IIAPIConfigFile=”/installDirectory/mcell/iiws.conf”svci:IIAPISelectorFile=”/installDirectory/mcell/iiws.selector”svci:IIWSInstanceName=”IIWS_Server”svci:MessageListenerCellName=”WSCELL”svci:ServerCacheDIR=”/installDirectory/cache”</waspc-config>


C h a p t e r 5
5 Guidelines for choosing client interfaces
This chapter describes guidelines for choosing a web services client interface that is compatible with the BMC II Web Services server. BMC neither supports nor endorses a particular client interface. This chapter describes the following topics:

Client components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Programming language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Available web services client features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Guidelines for building a client interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Preparing the WSDL source-code generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Generating the client proxy code (client stubs). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Systinet WASP Server for C ++ toolkit sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76.NET C# toolkit sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Apache Axis toolkit sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Using the NO_INOUT operations to return single elements for the Axis toolkit 78Deciding which stub operations to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Compiling the client code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Maximum number of open outgoing connections . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Implementing the send feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81How a send request is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Sequence of operations to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Implementing the query features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83How a query is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Sequence of operations to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84bmciiws_queryClassDefinitions: class definition array. . . . . . . . . . . . . . . . . . . . . . 86

Implementing the receive feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Selector choices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Polling interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Publish-subscribe interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Reliable versus non-reliable subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Polling client (non-reliable subscription) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Polling client (reliable subscription) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Listener client (reliable or non-reliable subscription) . . . . . . . . . . . . . . . . . . . . . . . 95Using multiple subscription calls (bmciiws_subscribe_reliable) . . . . . . . . . . . . . . 96


Client components

Registering and receiving service component state change events . . . . . . . . . . . . 98Workaround: multiple clients and state change events . . . . . . . . . . . . . . . . . . . . . . 99

Implementing the Secure WASPC client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Client componentsWhen you build a client interface, you use these components:

■ the client source code that you generate using the WSDL code generator ■ the customized client code that you write

Programming language

You can use any programming language that is supported by web services and your toolkit of choice.

Available web services client featuresUsing the BMC Impact Integration Web Services APIs, you can program your web services client to

■ send events and data

■ query class definitions in the SIM IM cell

■ query service model component information stored in the SIM IM cell

■ query service model component impacts and their root cause

■ query dynamic data in the cell

■ query events

■ receive events through a polling or publish-subscribe interface


Guidelines for building a client interface

Guidelines for building a client interfaceThis section describes the steps that you must perform to build a web services client that is compatible with the BMC II Web Services server.

1. Determine that the type of client that you want to create:

2. Supply the path name of the ImpactManager.wsdl document to your toolkit’s WSDL source-code generator.

3. Using your toolkit’s WSDL source-code generator, compile the ImpactManager.wsdl document into the target source code, generating the source and header files of the client proxy code (client stubs) as a result.

4. Using the generated client proxy code as a basis, decide which functions to use in your client code.

5. Write the custom code for the selected client features.

6. Test the client.

Preparing the WSDL source-code generator

You must supply the path name of the ImpactManager.wsdl file to your toolkit’s source-code generator. The ImpactManager.wsdl is located by default under the %installDirectory%\bin or $installDirectory/bin directory. If the BMC II Web Services server is running, you can also open a browser and specify the Impact Integration Web Services URL: for example, http://hostname:port number/imapi/. (The default port number is 6070.)

The exact name and location of your WSDL source-code generator depends on your web services toolkit.

Generating the client proxy code (client stubs)

To obtain the client proxy code, compile the ImpactManager.wsdl using your toolkit’s WSDL source-code generator. Depending on your toolkit, you can run the source-code generator in its home directory or the directory of your choice. Some examples from different toolkits follow.

You can find the sample code under the %installationDirectory%\samples or $installationDirectory/samples directory path. You can also refer to Appendix C, “Sample Client Files,” for additional information.


Systinet WASP Server for C ++ toolkit sample

Systinet WASP Server for C ++ toolkit sample

Using the source-code generator in the Systinet WASP Server for C++ toolkit, you can enter a command string similar to the following:

C:\WASP-CPP-4.6-win-VC60-bin\bin>wsdlc %installDirectory%\bin\ImpactManager.wsdl ImpactManager

where ImpactManager is the name of the web services project.

You generate sets of files, including files that contain the client stub information, data types, and structures.

In the Systinet WASP Server for C++ toolkit, you generate three pairs of files, each consisting of a source and a header file. One pair is generated for the Impact Integration Web Services client; one for the server; and one for the data structures. These files are created in the directory from which you executed the WSDL source-code generator.

In the Systinet WASP Server for C++ Toolkit, the wsdlc utility generates the following stub files in its home directory:

.NET C# toolkit sample

Using the WSDL utility in the .NET C# toolkit, you can generate the client stubs from the URL that points to the BMC II Web Services WSDL: http://hostName:6070/imapi/.

To generate the client stubs, open a Visual Studio .NET Command Prompt window, navigate to the appropriate directory path, and enter the following command:

wsdl http://hostName:6070/imapi/

Component Source file name Header file name

Client projectName.cpp projectName.h

Server projectNameImpl.cpp projectNameImpl.h

Data structures projectNameStructs.cpp projectNameStructs.h

NOTE You must include the ending slash (/) after the service name imapi in the URL. Port number 6070 is the default port number of the BMC II Web Services server.


Apache Axis toolkit sample

Your output should look similar to the following text:

Writing file ‘C:\directoryPath\src\ImpactManager.cs’

Using the WSDL utility, you can also generate client stubs from the hardcopy WSDL and schema definition files. Open a Visual Studio .NET Command Prompt, navigate to the appropriate directory path, and enter a command string similar to the following example:

wsdl drive:\installDirectory\bin\ImpactManager.wsdl drive:\installDirectory\bin\BasicTypes.xsd drive:\installDirectory\bin\Event.xsd drive:\installDirectory\bin\ImapiTypes.xsd

You should receive the output Writing file ‘C:\directoryPath\src\ImpactManager.cs’.

In the .NET C# toolkit, you can also generate the client stub dynamically from within the .NET GUI.

1 Create a .NET project for the BMC II Web Services.

2 From the Project => Add Web Reference command, enter the URL that points to the BMC II Web Services WSDL: http://hostName:6070/imapi/.

3 In the C# source file, add the reference to the stub, for example, “using nameofproject.webreferencename;”.

Apache Axis toolkit sample

Under the installDirectory\samples\Axis folder, you can find in separate subfolders a series of Apache Axis Java programming examples for defining queries, sending events, and receiving events. Each example has its own ReadMe file that explains how to build and run it.

The ant_build.bat file, which is the build script, calls the wsdl-build.xml file to generate the Java stubs from the ImpactManager.wsdl. The stub code is located under the runtime directory of each sample. The ant_build.bat file also generates two jar files, which are copied under the lib subdirectory. The iiws-client-stub.jar is the jar file generated from the stub code, and the sample-name.jar file is generated from the sample code itself.

NOTE If you are generating the client stubs from the URL, you may receive schema validation errors before you receive the message that the ImpactManager.cs file is being written.


Using the NO_INOUT operations to return single elements for the Axis toolkit

You can find the stub files under the following runtime directory:

Figure 13 Runtime directory folders for stub files

Using the NO_INOUT operations to return single elements for the Axis toolkit

The ImpactManager.wsdl defines the following operations with the NO_INOUT extensions:

■ bmciiws_connect_NO_INOUT■ bmciiws_getEvents_NO_INOUT■ bmciiws_getQueryResult_NO_INOUT■ bmciiws_retrieveQueryResults_NO_INOUT

These NO_INOUT operations are modified versions of the original operations (bmciiws_connect, bmciiws_getEvents, and so forth), which return two response elements in their output. In their output, the NO_INOUT versions return a single structure instead of two elements. The NO_INOUT operations are designed to accommodate web service toolkits, such as Axis, that return only one element in their response message to a client request.

Deciding which stub operations to use

After you generate the client proxy code, review the output. You may need to edit the generated stub files.

Review the generated client proxy code to help you decide which operations to use in your client. The client files, which are generated from the ImpactManager.wsdl, describe how the toolkit invokes the functions or methods and their parameters in the target programming language.



These functions or methods are generated from the operations that are defined in the ImpactManager.wsdl. These operations are summarized in the following table:

NOTE Operations is a WSDL term. If you are programming in C/C++, substitute the term functions. If you are programming in Java, substitute the term methods.

Table 15 Summary of Available Operations (part 1 of 2)

Operation Description

bmciiws_getCellInfo to identify BMC Impact Manager instances that are connected to the BMC Impact Integration Web Services Server

bmciiws_connect to connect to a specified BMC Impact Manager instance

bmciiws_send to send a client event or data object to the specified BMC Impact Manager instance

bmciiws_getFilterNames to retrieve the available selector names to which the client can subscribe

bmciiws_subscribe to subscribe to a specified event selector for a particular client to receive events. If this is a listener client, then a callback is supplied. Otherwise, if this is a polling client, the callback is set to ““.

This operation is included for backwards compatibility with earlier versions of the BMC II Web Services Server toolkit. You should now use bmciiws_subscribe_reliable to initiate the subscription requests.

bmciiws_subscribe_reliable to enable a reliable subscription to a specified event selector for a particular client to receive events. (A listener client also supplies a callback URL.) If the Reliable indicator is set to False, then the subscription is considered non-reliable.

bmciiws_ack to enable a client that has a reliable subscription to send an acknowledgement to the BMC II Web Services server indicating that it has received the requested events. The BMC II Web Services Server removes the forwarded events from its cache subdirectory.

bmciiws_getEvents to request a specified number of events matching a defined event selector for a particular client. Used in polling calls

bmciiws_unsubscribe to unsubscribe from the specified event selector in the BMC Impact Manager instance

bmciiws_disconnect to disconnect from the BMC Impact Manager instance

bmciiws_queryEvents to query a specific BMC Impact Manager instance for events

bmciiws_queryData to query a specific BMC Impact Manager instance for data

bmciiws_queryEventByID to query a specific BMC Impact Manager instance for events matching a specified BMC Impact Manager event ID

bmciiws_queryDataByID to query a specific BMC Impact Manager instance for data objects matching a specified BMC Impact Manager data ID

bmciiws_queryEventsByDate to query a specific BMC Impact Manager instance for events that belong to specified class and that have occurred within a specified date range



bmciiws_queryComponent to query a specified component object to retrieve its component data attributes

bmciiws_queryComponentsByStatus to query service components that MC_SM_COMPONENT_STATUS values in the specified range and which belong to the specified base class or subclass

bmciiws_queryComponentStatus to query a component and return its status, as defined by its computed component status: status, self_status, computed_status, impact_status, and manual_status

bmciiws_queryComponentEvents to query service components for direct and impact events. You have the option of retrieving only impact events.

bmciiws_queryComponentsByCondition

to query for an array of service model components that match the special Master Rule Language (MRL) conditions. These conditions follow the syntax and conventions of the MRL where-clause selection criteria.

bmciiws_queryModelImpact to query for possible consumer components of the specified component ID

bmciiws_queryPossibleRootCause to query for a component or components that are the possible root cause of a specified component’s status

bmciiws_queryClassDefinitions to query a specific base class and its subclasses for the class and slot definitions or to query a specific class for its class definition and slot definitions

bmciiws_getQueryResultCount to obtain the total number of events or data objects that have been returned by the query

bmciiws_getQueryResult to obtain a specified number of events or data objects to satisfy the query

bmciiws_endQuery to end the query cycle and disconnect from the specified BMC Impact Manager instance

bmciiws_setMaintenanceMode to request to place a specified component in maintenance mode

bmciiws_setManualStatus to request to set a designated manual status on the specified component

bmciiws_registerStateChange to register your client with a BMC SIM cell to receive state change events

bmciiws_unregisterStateChange to remove the registration ID assigned to the request to receive state change events, thereby stopping your integration from receiving state change events

NOTE You can read the guidelines for building different types of clients to determine which operations you should use. See “Implementing the send feature” on page 81, “Listener client (reliable or non-reliable subscription)” on page 95, or “Implementing the receive feature” on page 88.

Table 15 Summary of Available Operations (part 2 of 2)

Operation Description


Compiling the client code

Review the generated source files that describe the data structures and their types. These structures and types are generated from the data types defined in the ImpactManager.wsdl and in the imported schema definition files. The generated source files describe how the toolkit uses the data structures and types in the target programming language.

Review any generated source files that describe how the toolkit uses the code in the target programming language on the BMC II Web Services server.

For additional information on the operations and data types as they are defined in the ImpactManager.wsdl, see the BMC Impact Integration Developer’s Kit Web Services Server Reference Guide.

Compiling the client code

When you compile your custom client code, include the source files for the client stub and for any data structure stub. Also include the header files if you are using the C/C++ language.

Maximum number of open outgoing connections

Your integration application is limited to a maximum number of 100 open outgoing connections per session to one or more BMC IM cells. The number of incoming connections is not limited.

Implementing the send featureAfter you generate the client stubs and write your client source code, you can compile the client code and the client stubs to enable your client to send events, data, or both. Typically, a web services client that only sends events and data relies on synchronous event processing, but depending on your choice of toolkit, asynchronous event processing may be supported.

NOTE If you are programming in the C/C++ language, the source-code generator also supplies header files (*.h).


How a send request is processed

How a send request is processed

The BMC II Web Services Server receives the client requests through default port 6070 or a specified port number. It processes the requests and calls the appropriate C API to pass the message to the specified BMC Impact Manager instance.

Sequence of operations to use

To enable a client to send events and data, call the following key operations in sequence:

1. bmciiws_connect

Before you send events, you must invoke the bmciiws_connect operation. When you invoke the bmciiws_connect operation, you register with the BMC II Web Services server and connect with a specified BMC Impact Manager instance. You indicate which buffering routine you want to use, and you specify a connection ID that serves as the request/response connection handler.

Because you are connecting to specific BMC Impact Manager instances, you must add the cell information (name, encryption key, host, and port number) to the mcell.dir file residing on the BMC II Web Services server. See “How to synchronize BMC II Web Services Server and BMC IM cell connections” on page 38 for more information.

2. bmciiws_send

Invoke the bmciiws_send operation to send an event or data object to the BMC Impact Manager specified in the bmciiws_connect operation. In the bmciiws_send operation, you specify the connection ID, the response timeout interval, and the message parameters.

If your client is an event provider, you can connect and continue to call the bmciiws_send operation repeatedly to send events.

3. Invoke the bmciiws_disconnect() operation to disconnect from the specified BMC Impact Manager instance and to unregister from the BMC II Web Services server.

EXAMPLE The WASP server for C++ toolkit supports asynchronous event processing for clients that send events.


Implementing the query features

Implementing the query featuresUsing the available query features, you can enable a client to

■ retrieve events, data objects, or both from a specific BMC IM instance ■ return component information about service model component instances that have

been published to a specific cell or to multiple cells

The service model component queries retrieve dynamic data that is stored in the cell’s memory and in files under the installDirectory/log/cellName or drive:\installDirectory\log\cellName directory. The service model queries can search for and return service model information that has been published to one or more cells.

■ retrieve service model class definitions from a specific BMC IM instance

The class definition query retrieves static class definition information stored in the BAROC files under the installDirectory/etc/cellName/kb/classes or the drive:\installDirectory\etc\cellName\kb\classes directory. See “bmciiws_queryClassDefinitions: class definition array” on page 86 for more information.

How a query is processed

After the client specifies the initial query and connects with a BMC Impact Manager instance, the BMC II Web Services Server responds with a result handle ID. The client returns the result handle ID with each query request in the query cycle. After receiving the result handle ID, the client sends a request to the server seeking the total number of events or data objects available to the query. The BMC II Web Services Server responds with the total count.

NOTE See the BMC Impact Integration Developer’s Kit Web Services Server Reference Guide for descriptions of these operations.

NOTE These service model queries retrieve component data that has already been published to the cell; they do not query the BMC® Atrium Configuration Management Database.



To complete the query, the client next requests a specified number of events or data objects, and the server responds with the specified number or at least the available number. The server response is the query result. To end the query cycle and disconnect from the BMC Impact Manager instance, the client sends a bmciiws_endQuery request.

When querying, the client does not need to invoke a specific connection or disconnection request. With each query request, the client establishes a connection with a specific BMC Impact Manager instance. With the bmciiws_endQuery request, the client disconnects from the BMC Impact Manager instance.

If you build an exclusive query client, you do not need to invoke subscription or polling calls. Also, you do not need to build Propagate rules or define event propagation policies to push events from BMC Impact Manager instances to the WSCELL event listener residing on the BMC II Web Services Server.


The query operations have their own connection protocol. You do not have to call the bmciiws_connect operation before calling a query. You establish a separate query connection when you call a query operation.

When building your queries, invoke the following key operations in sequence:

1. One of the queries listed in Table 15 on page 79.

Invoke the specific query operation first. In the specific query, you identify what you are querying for and specify the BMC Impact Manager instance to which you are connecting. A query ID is returned that is used to track all related queries in this sequence.

The client can invoke multiple queries simultaneously on the same BMC Impact Manager instance connection, subject to the maximum outgoing connection restriction of 100 open connections. The volume of event and data throughput can impact the performance of the web services server.

NOTE For the service model queries, you must enter a component ID as an input parameter. You can obtain component IDs from the service model view in the BMC Impact Explorer or from the return values of other queries, such as bmciiws_queryComponentsByCondition or bmciiws_queryComponentsByStatus.



See the BMC Impact Integration Developer’s Kit Web Services Reference Guide for more information about these query operations.

2. bmciiws_getQueryResultCount

The _getQueryResultCount call discovers the total number of events or data objects that are available to the query.

Invoke the bmciiws_getQueryResultCount to get the total number of events or data objects that the BMC II Web Services server has retrieved in response to the specific query. This query also sends the query ID obtained by the initial query request.

3. bmciiws_getQueryResult

The _getQueryResult call specifies the number of events or data objects of the total that the client wants to receive. The default value is set equal to 30. You can modify this value by changing the MaxResponseEventListSize parameter in the servercfg.xml file. See “Configuring Attributes in the BMC II Web Services Server” on page 57 for more information.

You can retrieve the entire range of results at once if the result count is not too large. You can ask to retrieve a specified number of results at one time. You can continue to retrieve the specified number in successive tries until you have retrieved all the results in the range.

You can also call the bmciiws_getQueryResult() operation to retrieve a specified number of events or data objects starting from a certain index point. For example, if the query result count is 50, in the bmciiws_getQueryResult() operation, you can specify a beginning point of 20 and indicate that you want to receive the next 10 events. You retrieve events 20 through 30. (This query also sends the query ID.)

You can invoke multiple bmiiws_getQueryResult() operations to retrieve all the event or data objects. Then invoke bmciiws_endQuery() to terminate the query cycle.

NOTE Reliable subscription does not apply to the query functions. If you lose a query connection, all query information is lost. You must reconnect by resending the query function.

TIP As a reminder, because you are connecting to specific BMC Impact Manager instances, you must add the cell information (name, encryption key, host, and port number) to the mcell.dir file residing on the BMC II Web Services server. See “How to synchronize BMC II Web Services Server and BMC IM cell connections” on page 38 for more information.


bmciiws_queryClassDefinitions: class definition array

4. bmciiws_endQuery

The _endQuery call notifies the BMC II Web Services Server to terminate the query cycle.

Invoke the bmciiws_endQuery operation to terminate the query cycle for this query. This operation sends only the query ID, which indicates to the web services server that the query is over.

The client must call the bmciiws_endQuery() operation to clean up the query context in the BMC II Web Services server, to clean up the memory cache, and to close the connection with the BMC Impact Manager instance.


The bmciiws_queryClassDefinitions operation returns a class definition array. You can review this description to see how the operation builds the array it returns.

This example, which is only for illustrative purposes, uses the following input parameter values for the bmciiws_queryClassDefinitions operation:

Using these parameters, the bmciiws_queryClassDefinitions operation returns the following information, which has been edited to illustrate the array structure.

NOTE See the BMC Impact Integration Developer’s Kit Web Services Reference Guide for descriptions of these operations.

Parameter Value

imname testcmdb

queryMode 0 (indicates that the BMCII_DATA_CLASSES are being queried)

baseClase BMC_AssetBase

className blank

classOnly 0 (indicates that the query includes the BMC_AssetBase class and its subclasses)



Figure 14 bmciiws_queryClassDefinitions code sample

This return can be depicted in a flat array as shown in Figure 15 on page 88.

CLASS NAME:: BMC_AssetBaseCHILDREN COUNT:: 5CHILD INDEX[0]:: 1CHILD INDEX[1]:: 2CHILD INDEX[2]:: 3CHILD INDEX[3]:: 4CHILD INDEX[4]:: 5CLASS PARENT INDEX:: -1SLOTS COUNT:: 26-----------------------------------------------SLOT NAME:: TypeSLOT REP.TYPE:: *SLOT FLAGS:: rkPdhSLOT DEFAULT VALUE:: null-----------------------------------------------SLOT NAME:: RoomSLOT REP.TYPE:: *SLOT FLAGS:: rkPdhLOT DEFAULT VALUE:: null...*********************************************************CLASS NAME:: BMC_GenericGroupCHILDREN COUNT:: 5CHILD INDEX[0]:: 6CHILD INDEX[1]:: 7CHILD INDEX[2]:: 8CHILD INDEX[3]:: 9CHILD INDEX[4]:: 10CLASS PARENT INDEX:: 0SLOTS COUNT:: 0*******************************************************CLASS NAME:: BMC_LogicalComponentCHILDREN COUNT:: 6CHILD INDEX[0]:: 11CHILD INDEX[1]:: 12CHILD INDEX[2]:: 13CHILD INDEX[3]:: 14CHILD INDEX[4]:: 15CHILD INDEX[5]:: 16CLASS PARENT INDEX:: 3SLOTS COUNT:: 2


Implementing the receive feature

Figure 15 Class definition array

The base class, BMC_AssetBase in this example, is assigned the parent index value -1. It has five child classes. The array of its children begins with point 0 and continues to the end of its child elements, which is point 5 in this example. The 26 slot definitions of the Slots Count belong to the class under the current focus, which is BMC_AssetBase.

The class BMC_GenericGroup has a parent index of 0, the origin point of BMC_AssetBase class’s array of children. The BMC_GenericGroup has 5 child classes, beginning with point 6 and continuing through 10. Its Slots Count is empty.

The class BMC_LogicalComponent has a parent index of 3, a child element from the BMC_AssetBase class’s array of children. The BMC_LogicalComponent has 6 child classes beginning with point 11 and continuing through 16. Its Slots Count is 2.

Using the bmciiws_queryClassDefinitions operation, you can extend your query to all classes in the class hierarchy of the BMC IM instance. When writing your client code, you should include a for loop in which you define your child index parameters.

Implementing the receive featureYou can build a client interface that receives events through polling calls or a publish-subscribe mechanism (event listener).

Table 16 on page 89 describes the essential components for a client interface that receives events.


Selector choices

Selector choices

Table 17 lists the three basic choices:

These selectors are defined in the iiws.selector file, located under installDirectory\IIWS\mcell. The BMC II Web Services Server loads the iiws.selector file by default because it is specified in the server configuration file, servercfg.xml, which is under installDirectory\IIWS\conf. For more information on the selector file and selector processing, see “Selector file overview” on page 106.

Table 16 Components that support a receive interface

Component Description

WSCELL The WSCELL is an event listener that the BMC II Web Services Server starts. Its function is to accept connections from BMC Impact Manager instances at default port number 19999.

Propagate rules or event propagation policies

To receive events from BMC Impact Manager instances, you must define Propagate rules or event propagation policies in the cell for the event types to be sent. The BMC Impact Manager instance sends events to the WSCELL event listener based on the rules or polices that you have defined.

Note: You do not need to define Propagate rules or event propagation policies to receive service component state change events only. See “Registering and receiving service component state change events” on page 98 for more information.

Subscription requests To receive events, your client interface must invoke subscription requests through the bmciiws_subscribe_reliable() operation. The parameters that the subscription requests pass depend on which client interface you choose, polling or publish-subscribe. You can elect to use reliable subscription (reliable is set to True) to guarantee event delivery.

Selectors Selectors define the criteria that determine which events your client receives. You specify a selector type in your subscription request.

Table 17 Event selectors for subscription requests

Selector name Description

Always matches allows you to receive (filters in) all new events from the specified BMC IM cell

Modifies allows you to receive only modified events from the cell

Everything allows you to receive both original and modified events


Polling interface

The BMC II Developer’s Kit C API also contains global selector files that you can enable. See “Supplemental message selector files” on page 121.

Polling interface

Consider using the polling interface when

■ port access is an issue■ a firewall separates networks across which you are communicating

The subscription request of a polling call contains the following parameters:

■ a selector that defines the event criteria of the event type which the client has subscribed to

■ a context ID that identifies the client which is making the subscription request

The context ID can be any string identifier that is unique to BMC II Web Services server.

■ a callback URL that is not used in the polling interface. You set to equal to null, using the conventions of the programming language, or to an empty string ““.

■ a Boolean Reliable parameter that you can set to True or False

The example in the following figure shows a non-reliable subscription request for a polling client.

Publish-subscribe interface

The publish-subscribe interface relies on an event listener server that has consistent port access to receive events. In your subscription request, you include a callback URL. The subscription request includes the following parameters:

■ selector name that identifies a selector which defines the event criteria of the event type that the client has subscribed to

■ a context ID that identifies the client which is making the subscription request

bmciiws_subscribe_reliable (filterName, context, callback URL, Reliable);bmciiws_subscribe_reliable (“Always matches”, “321”, “ “, “False”);


Reliable versus non-reliable subscription

■ a callback URL that identifies the event listener with whom the client has registered a callback

The example in the following figure shows a non-reliable subscription request for a publish-subscribe client. Use commas to separate the input arguments.

If you decide to use a publish-subscribe interface, see the EventListener.wsdl file contained in the %installDirectory%\Samples or $installDirectory/Samples subdirectory. You can extend the operations in the EventListener.wsdl, but do not modify the declarations or definitions. See Appendix C, “Sample Client Files” for more information.

Reliable versus non-reliable subscription

By using the bmciiws_subscribe_reliable operation, you can establish a persistent connection with the BMC II Web Services server and the underlying BMC II C API libraries. When it receives a reliable subscription request from a client, the BMC II Web Services server persists the events that it receives in response to the client’s subscription request in a cache directory (%installDirectory%\cache or $installDirectory/cache).

If your client sets the Reliable parameter to False, then the BMC II Web Services server stores events in the /log subdirectory under the name of the service. With a single-client connection, events are removed from the /log subdirectory after the BMC II Web Services server sends the events to the client.

Polling client (non-reliable subscription)

If your client uses non-reliable subscription, then the BMC II Web Services Server stores events in the /log subdirectory under the name of the service.

bmciiws_subscribe_reliable (filterName, context, callback URL, Reliable);bmciiws_subscribe_reliable (“Everything”, “123”, “http://listener:7070/EventListener”, “False”);

NOTE The bmciiws_subscribe_reliable operation uses a Boolean parameter to set its reliable mode. If you set the parameter to False, then bmciiws_subscribe_reliable acts the same as the bmciiws_subscribe operation.



When programming a client that receives events through non-reliable subscription and polling calls, invoke the following key operations in sequence:

1. bmciiws_subscribe_reliable (omit the callback URL parameter)

You do not need to initiate a connection call (bmciiws_connect) to invoke subscription requests and receive events through polling. For polling calls, when you invoke the bmciiws_subscribe_reliable operation, you specify the selector name that matches the events you want to receive and the client context ID. However, you set the callback URL of the event listener server as an empty string (““) or as null. Set the Reliable parameter to False.

When the BMC II Web Services server receives the subscription request without the callback URL, it automatically determines that it is a polling request. The BMC II Web Services server starts to build an event queue using the specified selector and client ID that it has received. The event queue resides on the server and buffers the events.

2. bmciiws_getEvents (the polling call)

Invoke the bmciiws_getEvents operation to specify the polling parameters.

In the request, the client specifies

■ the name of the selector as specified in the subscription call. The client is polling for events that match the selector criteria.

■ the client context ID (any string) that identifies the client making the polling request

■ a specified number of events that it wants to receive per polling call

The num_of_events parameter acts as both an input and output parameter. As an input parameter, it indicates how many events the integration client wants to poll for in each bmciiws_getEvents call. The BMC II Web Services Server compares this integer with the value of the configuration parameter MaxReturnEventListSize (default value = 20).

■ If the num_of_events value is greater than the MaxReturnEventListSize parameter value, then either the MaxReturnEventListSize parameter value is returned or the remaining number of events in the event pool, if the number is less than the MaxReturnEventListSize.

TIP Because each subscription request requires a specific selector name, you might first call the bmciiws_getFilterNames operation to identify the available selector names to which you can subscribe.



■ If the num_of_events value is less than the MaxReturnEventListSize parameter value, then the call returns up to but no more than the specified num_of_events value.

The example in the following figure shows an example of a bmciiws_getEvents_NO_INOUT operation, which returns a single structure and not two response elements. Otherwise, the operation works the same as the bmciiws_getEvents operation.

In the response, the web services server retrieves the matching events from the event queue and forwards them in array format to the client. The server returns either the specified number of events or the number that it is able to retrieve from the queue.

You can invoke multiple bmciiws_getEvents operations to retrieve all the available events. For each polling call per subscription, the client can specify a different number of events.

3. bmciiws_unsubscribe

Invoke the bmciiws_unsubscribe to close the polling cycle and stop receiving events for this subscription request.

When the client unsubscribes from a subscription, it sends the selector name and client context ID to the web services server. The subscription manager matches the selector name and context ID with the subscription and closes it. The program deletes the event queue from the server. All events in the $installDirectory/log or %installDirectory%\log subdirectory are removed.

To poll for events matching a different selector name, create a separate subscription call with the specified selector and then invoke the polling call (bmciiws_getEvents) with the new selector.

NOTE The number of requested events and the number of returned events can be two different values.

bmciiws_getEvents_NO_INOUT(filterName, clientId, eventCount);

bmciiws_getEvents_NO_INOUT(“Everything”, “321”, “20”);

TIP As a developer, you write the client code to handle the events. You can develop different polling scenarios. For example, you can invoke a polling call on a different thread to poll for different types of events.


Polling client (reliable subscription)

Polling client (reliable subscription)

You can choose to design a polling client that uses a reliable subscription request to maintain a persistent connection with the BMC II Web Services Server and the BMC II C API libraries. When it receives a reliable subscription request from a client, the BMC II Web Services Server persists the events that it receives in response to the client’s subscription request in a cache directory (drive:\installDirectory\cache or installDirectory/cache).

Use the reliable subscription operation to guarantee event delivery. The sequence is essentially the same as that of a non-reliable subscription, except that

1. the initial subscription call is bmciiws_subscribe_reliable with its reliable indicator set to True

2. the client must send an acknowledgement to the BMC II Web Services server in the form of the bmciiws_ack operation indicating that it has received the requested events.

To implement reliable subscription in a polling interface, use these operations in sequence:

1. bmciiws_subscribe_reliable

Set the Boolean parameter Reliable to True to indicate that your client is requesting guaranteed delivery.

If you are uncertain about which selector to specify, you can call bmciiws_getFilterNames first to view the list of available selectors.

2. bmciiws_getEvents

You can invoke multiple bmciiws_getEvents operations. For each bmciiws_getEvents request for which the client receives a response, you must call the bmciiws_ack operation to send an acknowledgement to the server.

3. bmciiws_ack

After the client receives the events it requested in the bmciiws_getEvents operation, it calls the bmciiws_ack operation to send the acknowledgement to the server. The server removes the forwarded events from its %installDirectory%\cache or $installDirectory/cache subdirectory, but retains the control file for the subscription request.

If the client does not send acknowledgments or stops polling, the cache subdirectory increases in size as the BMC II Web Services server continues to receive events.


Listener client (reliable or non-reliable subscription)


Call the bmciiws_unsubscribe operation to close the polling cycle and stop receiving events for this subscription request. All events in the %installDirectory%\cache or $installDirectory/cache subdirectory are removed, including the control file.

Listener client (reliable or non-reliable subscription)

Using a publish-subscribe interface, you can design a listener client that receives events through a custom event listener. The listener client registers a callback with its event listener. The callback implements an event handler. The client initiates a subscription request and sends it to the BMC II Web Services server.

To implement a listener client, you will need to use the sample EventListener.wsdl. See Appendix C, “Sample Client Files” for more information.

When programming a listener client, invoke the following key operations in sequence:

1. bmciiws_subscribe_reliable (include the callback URL parameter)

You do not need to initiate a connection call (bmciiws_connect) to invoke subscription requests and receive events. When you invoke the bmciiws_subscribe operation, specify the

■ selector name that matches the events you want to receive■ client context ID (any string) that identifies the client making the request■ callback URL of the event listener server that resides on the client■ Reliable parameter (True for reliable subscription, False for non-reliable)

NOTE See the BMC Impact Integration Developer’s Kit Web Services Server Reference Guide for descriptions of these polling operations.

TIP Just as a reminder, you can extend the operations in the EventListener.wsdl, but do not modify the declarations or definitions.


Using multiple subscription calls (bmciiws_subscribe_reliable)

When the WSCELL receives the event that matches the selector in the subscription request, it sends the event and client context ID to the event dispatcher of the BMC Impact Integration Web Services server.

The event dispatcher dispatches the events to the event listener specified by the callback URL in the subscription request of the requesting client. The listener invokes the callback and calls the registered event handler function to consume the event. As a developer, you write the event handler logic to manage the event.


To stop receiving events, invoke the bmciiws_unsubscribe operation for this subscription request.

If you are unsubscribing from a reliable subscription, all events in the cache subdirectory, including the control file, are removed.


Depending on the type of receive client you are building, you might want to invoke multiple subscription calls.

The client that receives events can invoke one or both of two types of subscription calls depending on whether the client is using a publish-subscribe interface or a polling interface:

TIP Because each subscription request requires a specific selector name, you might first call the bmciiws_getFilterNames operation to identify the available selector names to which you can subscribe.

NOTE If your listener client uses a reliable subscription request, the events that the BMC II Web Services Server receives are stored in the %installDirectory%\cache or $installDirectory/cache subdirectory with a unique control file. Once received, the events are automatically sent to the client based on the callback. (The listener client does not call the bmciiws_ack operation.) The events in the cache subdirectory are not removed, however. You can manually delete the contents of the cache subdirectory without unsubscribing from the request.

NOTE See the BMC Impact Integration Developer’s Kit Web Services Reference Guide for a description of the subscription operation, its parameters, and its messages.



■ In a publish-subscribe interface, the subscription contains the callback URL of its event listener server.

■ In a polling interface, the callback URL is a null value.

Multiple subscription calls must be unique to prevent the BMC II Web Services server from overwriting them. Each subscription call must have a unique combination of selector name and client context ID. Multiple subscriptions from a polling interface, from a publish-subscribe interface, or from a combined interface must be unique.

The two following examples of subscription calls originate from a combined interface:

Each calls a different selector name (“Always matches_MAJOR” or “Always matches_MINOR”) but from the same client context ID (“123”). These are considered unique calls, and the BMC II Web Services server will not overwrite one with the other.

Conversely, two subscription calls, each with a different client context ID, are considered unique even if they specify the same selector name. The following example shows two subscription calls originating from different client context IDs: one for a publish-subscribe interface and the other for a polling interface.

Although both calls specify the same selector (“Always matches”), they are unique calls because they contain different client context IDs (“789” and “123”). The BMC II Web Services server does not overwrite one with the other.

bmciiws_subscribe_reliable (filterName, context, callback URL, Reliable);bmciiws_subscribe_reliable (“Always matches”, “123”, “http://listener:7070/EventListener”, “False”);

bmciiws_subscribe_reliable (filterName, context, callback URL, Reliable);bmciiws_subscribe_reliable (“Always matches”, “123”, “”, “False”);

bmciiws_subscribe_reliable (“Always matches_Major”, “123”, “http://listener:7070/EventListener”, “False”);bmciiws_subscribe_reliable (“Always matches_MINOR”, “123”, ““, “False”);

bmciiws_subscribe_reliable (“Always matches”, “789”, “http://listener:7070/EventListener”, “False”);bmciiws_subscribe_reliable (“Always matches”, “123”, ““, “False”);


Registering and receiving service component state change events

The following example shows two subscription calls—one for a publish-subscribe interface, the other for a polling interface—that are not unique. Each call specifies the same client context ID and calls the same selector name.

In this example, the BMC II Web Services server would overwrite the earlier subscription call with the later one.

Registering and receiving service component state change events

Use the bmciiws_registerStateChange operation to register with a SIM cell to receive service component state change events. You do not need to add a Propagate rule or an event propagation policy just to receive state change events. The cell automatically sends the state change events to the WSCELL event listener specified in its mcell.dir file.

A C declaration of the bmciiws_registerStateChange() function would look similar to the following example:

SIM_cell refers to the cell to which you are connecting and from which you are requesting the state change events. WSCELL_eventlistener refers to the value of the WSCELL entry that specifies the BMC II Web Services Server which is registering with the cell to receive the events. changeType refers to one or more of the following service component change types that you want to receive:

■ bCompChange (component change)■ bCompDelete (component deletion)■ bRelChange (relationship change)■ bRelDelete (relationship deletion)■ bAll (component and relationship state changes)

The bmciiws_registerStateChange function() returns a registrationID from the BMC II Web Services Server that identifies and is associated with the request for state change events.

bmciiws_subscribe_reliable (“Always matches”, “123”, “http://listener:7070/EventListener”, “False”);bmciiws_subscribe_reliable (“Always matches”, “123”, ““, “False”);

string registrationID bmciiws_registerStateChange(string SIM_cell,string WSCELL_eventlistener, struct changeType);


Workaround: multiple clients and state change events

Use the registrationID when you call the bmciiws_unregisterStateChange() function, an example declaration of which is shown below:

Guidelines

Make sure that the value of the serverName parameter of bmciiws_registerStateChange matches that of the Name value of the WSCELL entry in the mcell.dir file of the cell from which you are requesting the state change events.

For example, the following code snippet is requesting that the SIM cell ABC send its state change events to the BMC II Web Services Server specified by the WSCELL entry myWSCELL:

The mcell.dir file of the SIM cell should have a corresponding WSCELL entry for the requesting BMC II Web Services Server.


If in your environment, multiple clients are requesting state change events from the same SIM cell or cells, you must send your registration request by defining and sending a separate data message. Do not use the bmciiws_registerStateChange operation.

When formulating your message, you specify values for the following slots in the SIM_NOTIFICATION_REGISTRY message class:

bmciiws_unregisterStateChange(string SIM_cell,stringregistrationId);

bmciiws_registerStateChange(“ABC”, myWSCELL, ...);

<Type><Name><EncryptionKey><IPAddress:Port>cellABCMCmyIMComputer:1828cellmyWSCELLMCmyWSComputer:19999

Table 18 SIM_NOTIFICATION_REGISTRY message class: required slots (part 1 of 2)

Slot Description

client_data only applies to version 7 or later of BMC Service Impact Manager. Specifies a unique name for this registration call.

clients denotes the value assigned to the WSCELL entry specifying the BMC II Web Services Server instance



The following example (generated from the .NET toolkit) shows how you can define the message:

requested_notifications indicates the type of service component state change that you want to receive. You can specify one or more of the following values:

■ COMPONENT_CHANGE■ COMPONENT_DELETE■ RELATIONSHIP_CHANGE■ RELATIONSHIP_DELETE

notification_mode indicates the notification mode

notifications_at_registration Boolean indicate that says whether a notification is sent upon registration

asset_filters a LIST_OF type that specifies the service components about which you want to receive state change events

//create a registration for state change events

/* * Create the data */::imapi::Event *event = new ::imapi::Event();event->NameValue_element = new ::imapi::NameValueArray(1);

event->NameValue_element->array[0] = new ::imapi::NameValue();event->NameValue_element->array[0]->name = "client_data";event->NameValue_element->array[0]->value = new ::imapi::Value();event->NameValue_element->array[0]->value->what = ::imapi::Value::tString_value;event->NameValue_element->array[0]->value->string_value = "example_register";event->NameValue_element->array[0]->value_type = ::imapi::DataType::STRING;

event->NameValue_element->array[1] = new ::imapi::NameValue();event->NameValue_element->array[1]->name = "clients";event->NameValue_element->array[1]->value = new ::imapi::Value();event->NameValue_element->array[1]->value->what = ::imapi::Value::tString_value;event->NameValue_element->array[1]->value->string_value = "[example_Server_name]";event->NameValue_element->array[1]->value_type = ::imapi::DataType::STRING;

//repeat the name-value definitions for each required slot

Table 18 SIM_NOTIFICATION_REGISTRY message class: required slots (part 2 of 2)

Slot Description


Implementing the Secure WASPC client

After you define the message, you send the registration as an event, an example of which is depicted in the following example:

Implementing the Secure WASPC clientUse this procedure to ensure secure communication between the BMC II Web Services server and client.

1 Make sure that BMC II Web Services server is running with SSL configured as described in Chapter 4, “Securing web services.”

2 Using the OpenSSL source files, create ssleay32.* and libeay32.* libraries according to your platform, as follows:

See “Obtaining the OpenSSL source files” on page 67 for more information about downloading OpenSSL source files.

3 Copy the library files to installDirectory/bin, according to your platform.

4 Modify the installDirectory/conf/client.xml file to include secure transport xml by removing the line <wasp:import ref="transport.xml and adding the line <wasp:import ref="transport_SSL.xml"/> as shown below:

//send the registration

WASP_VString id = test->impactManager->bmciiws_send(test->connection_id,event, 0,"SIM_NOTIFICATION_REGISTRY",::imapi::IMMessageType::MSG_TYPE_NEW_DATA, ee);

Platform Files

Windows ssleay32.dll and libeay32.dll

Solaris or Linux ssleay32.so and libeay32.so

HP-UX ssleay32.sl and libeay32.sl

AIX ssleay32.lib and libeay32.lib or

ssleay32.a and libeay32.a

<?xml version="1.0"?><waspc-config xmlns:scr="urn:StubConfigRepository" xmlns:wasp="urn:WaspServer"><wasp:import ref="transport.xml remove line <wasp:import ref="transport_SSL.xml"/> add line <wasp:import ref="transcoder.xml"/>


5 Copy installDirectory/conf/openssl-http-client.xml to installDirectory/conf/transport_SSL.xml.

6 Modify installDirectory/conf/transport_SSL.xml by removing the line <wasp:import ref="openssllib.xml"/>, as shown below:

<wasp:import ref="soapprotocol.xml"/> <wasp:import ref="header.xml"/> <wasp:import ref="serialization.xml"/> <wasp:import ref="deleter.xml"/> <wasp:import ref="interceptor.xml"/> <wasp:module wasp:class="WASP_StubConfigRepositoryImpl"/> <wasp:module wasp:class="WASP_SeparateThreadAsyncReceiptHandlerModule"/> <scr:stubConfig xmlns:scec="urn:StubConfigEntryContent" scec:xmlProtocolHandler="SOAP" scec:xmlProtocolDirectOutput="1" scec:outputXMLEncoding="UTF-8" scec:interceptor="DIMEInterceptor" /></waspc-config>

<?xml version="1.0"?>

<waspc-config xmlns:trans="urn:TransportRepository" xmlns:wasp="urn:WaspServer">

<wasp:import ref="openssllib.xml"/> remove line

 <wasp:module wasp:class="WASP_TransportRepositoryImpl"/>

<trans:transport trans:class="WASP_FileTransportClient" trans:scheme="file" xmlns:ftc="urn:FileTransportClient" ftc:extout=".out" />

<wasp:externalLibrary> <! Add line based on your operating system >  <wasp:path>WASPOpenSSL.dll</wasp:path> <! AIX > <wasp:path>libwasp_openssl.a</wasp:path> <! HP > <wasp:path>libwasp_openssl.sl</wasp:path> <! Linux or Solaris > <wasp:path>libwasp_openssl.so</wasp:path> </wasp:externalLibrary>


7 Save all your changes.

8 Start the BMC II Web Services Server if it not already running.

9 Run the client, substituting the secure server host name in the following URL:

https://serverHost:6075/imapi

<trans:transport xmlns:htc="urn:HTTPTransportClient" xmlns:htcssl="urn:HTTPSOpenSSLTransportClient" trans:class="WASP_HTTPSOpenSSLTransportClient" trans:scheme="https" htc:retryCount="10" htc:retryTime="100" htc:reuseCount="100" htc:reuseTimeout="30" htc:rwTimeout="30" htc:connTimeout="30" htc:http10="false" htc:chunked="false" > <htcssl:context htcssl:class="WASP_OpenSSLContextFactoryImpl" xmlns:ssl="urn:OpenSSLContextFactory" ssl:verify="yes"> <ssl:trustedDir><Insert proper location>openssl/certs</ssl:trustedDir> </htcssl:context> </trans:transport></waspc-config>


A p p e n d i x A
A BMC Impact Integration Web Services Server Administration
This appendix describes configuration files that affect how the underlying BMC APIs interact with the BMC Impact Manager instances to which they connect. This appendix tells how to update the selector file (*.selector), the configuration file (*.conf), and the trace file (*.trace). It provides a summary of the mcell.dir file.

This chapter is addressed primarily to the application administrator. The administrator should be familiar with the configuration files of BMC Impact Manager.

This appendix describes the following topics:

Starting server instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Selector file overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106How the BMC II Web Services Server reads selector files and parameters . . . . . . . 106Selector file description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Editing the selector file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Editing the supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Trace file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Editing the trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Editing the Integration mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139


Starting server instances

Starting server instancesThe web services server administrator is responsible for starting and maintaining the server. To launch the server, follow the instructions in “Starting and stopping the BMC II Web Services Server” on page 59.

Selector file overviewThe BMC Impact Integration APIs use the selector file to define groups of criteria (called selectors) that are used to identify and select messages which propagate from BMC Impact Manager instances. Messages that match all the criteria in a selector become available to the BMC Impact Integration Web Services’ publish-subscribe and polling mechanisms.

The selector file is a case-insensitive text file. The selector file is required for BMC Impact Integration Web Services’ clients that receive events from BMC Impact Manager instances.

A default selector file, iiws.selector, is stored under the mcell directory. Its file path is designated in the installDirectory/conf/servercfg.xml or drive:\installDirectory\conf \servercfg.xml file, as shown in the following example:

The BMC II Web Services Server loads this selector file automatically.

How the BMC II Web Services Server reads selector files and parameters

The BMC II Web Services Server uses selectors to match incoming events and to make them available to subscribing clients.

NOTE The selector file is not required for web service clients that only send events or data or that only launch queries.

svci:IIAPISelectorFile="C:\Program Files\BMC Software\ImpactIntegration Web Services/mcell/iiws.selector"


Selector file description

When programming the web service client, you specify the selector name to invoke in the subscription request (bmciiws_subscribe_reliable). The subscription call identifies the client and the selector name to the BMC II Web Services server. The BMC II Web Services server stores this information in a subscription table, in which selector entry names are mapped to specified client IDs.

During runtime, the BMC II Web Services server loads the selector file that the servercfg.xml file specifies. (Only one selector file is loaded per session.) The specified selector file applies to all the messages that propagate from all the BMC Impact Manager cells to which the server is connected.

Multiple clients can subscribe to the same selector entry in a web services session. Conversely, a single web service client can subscribe to different selectors in the same session by initiating multiple subscription calls, each specifying a different selector name.

As BMC Impact Manager events propagate to the BMC II Web Services server, the server accesses the specified selector file, which is loaded in memory. When a BMC Impact Manager message matches a selector parameter in the selector file, the server looks into the subscription table to get the clients that have invoked subscriptions with the matching selector parameter name. The server dispatches the event to all web service clients that have subscribed to the selector parameter name.

Selector file descriptionThe following topics describe the structure and content of message selector set files as implemented by the BMC II Developer’s Kit.

Characteristics

Message selector set files have the following characteristics:

NOTE Whenever a client subscribes to multiple selectors, it runs the risk of receiving duplicate messages from a cell. The same message can satisfy the different criteria specified by each selector name and be forwarded to the subscribing client.

NOTE When an incoming BMC Impact Manager event arrives, BMC II Web Services Server checks the event against all selectors in the selector set of the file. For each match of selector with event, it checks whether there is a subscription request from a subscribing web service client. It dispatches the event to each client that has a subscription with a matching selector entry.


Characteristics

■ Message selector set file criteria are not case sensitive.

■ The naming convention for message selector set files is integrationName.selector.

■ Message selector set file syntax is checked when the message selector set file is loaded. If the message selector set file contains problematic syntax, the BMC II C API bmcii_loadSelectorSet() function will fail.

■ The contents of a message selector set file comprise a message selector set. The message selector set can contain one or more message selectors. However, a message selector set file can contain only one message selector set.

■ Each message selector in a message selector set must have a unique name. However, different message selector sets can have message selectors with identical names.

■ When a message selector set file is called by the BMC II C API bmcii_matchSelectorSet() function, it is scanned from beginning to end. The selection process for the message stops the first time that a parameter in a message selector is matched to a parameter value in a message. Once a match is made, the remaining message selectors in a set are ignored.

If the bmcii_matchSelectorSetAll() function is called, the function continues to scan after a matching message selector is identified.

■ Because the message selector sets are scanned from beginning to end, the order of message selectors in a set and lines within a message selector are important to optimizing the matching process.

■ The $doselector function allows you to include message selectors and subselectors within a selector set. Message selectors and subselectors further refine the selector criteria.

■ The $doselector function invokes message subselectors.

■ The relationship between the criteria described in successive lines of a single stanza in a message selector is AND, unless otherwise indicated.

■ The message selector file supports the logical operators OR, AND, &&, and ||.

■ A message selector set can contain multiple stanzas of message selector criteria, nested one level deep. These multiple stanzas of message selector criteria are referred to as message selector groups. The logical relation between the groups can be expressed through an AND, OR, &&, or || connector.

■ Each line in a message selector contains only one message selector criterion.


Format

■ The message selector file supports the following comparison operators

■ greater-than (>)■ greater-than or equal to (>=)■ less-than (<)■ less-than or equal to (<=)

The message selector file supports these comparison operators for numerals only.

■ The message selector file supports the metaslot feature, which enables you to include information about the message. For example, you can use the metaslot to indicate the source of a message. You specify a metaslot by using the keyword metaslot, followed by a dot (.), to prefix the slot name: metaslot.classname=”EVENT”.

■ The message selector file supports required slots. A required slot keyword determines the required slot or slots in the message selector criteria. The message must have the specific required slot for it to match the message selector criteria.

The required slot keyword consists of the term reqdslot, followed by a dot (.), both of which you add as a prefix to the specific slot name: for example, reqdslot.msg=”TEXT”. To illustrate, if the message selector criteria specified that the slot msg is required (reqdslot.msg=”TEXT”), then a message that did not have the slot msg would fail the matching test.

The reqdslot keyword overrides the FailOnMissingSlot parameter when the latter is set equal to FALSE. That is, a message that does not have the designated required slot fails to meet the message selector criteria.

When the FailOnMissingSlot parameter is set equal to TRUE, the BMC II C APIs ignore the reqdslot keyword when they process the message to determine whether it meets the message selector criteria.

■ You can use the full range of regular expressions as values for message selector criteria. You can include any slots within the regular expression. The BMC II C APIs return the values of the slots at runtime. Within a regular expression, you can specify a slot with the keyword slot, followed by a dot (.): slot.host. The BMC II C APIs will return the value of host before sending the regular expression to the library.

Format

Figure 16 on page 110 depicts the structure of the message selector set file.


Format

Figure 16 Structure of message selector set file

Message selector set files must contain header information that describes the message selector set. The header information consists of

■ message selector set headers, described in “Message selector set header” on page 110

■ message selector headers, described in “Message selector header” on page 111

Message selector criteria are described in “Message selector criteria” on page 113.

Message selector set header

The message selector set header provides the entire set of message selectors in the file with identifying information and indicates whether the message selector set is enabled for use. A single message selector set header must precede all message selectors and their selector groups in the message selector set.

Table 19 on page 111 describes the required and optional message selector set header parameters that precede the message selectors in a set.


Format

Message selector header

A message selector header

■ provides each set of message selector criteria in the file with identifying information

■ indicates how some message selector features will be implemented■ indicates whether the specific message selector criteria, including any message

selector groups included within it, are enabled for use

Table 19 Message selector set header contents

Parameter Description Inclusion

SelectorSetName= name of the message selector set

Note: The SelectorSetName can be seen in the Trace file. Use this functionality to debug problems with a specific message selector set.

Required

FormatVersion= minimum version of the BMC II Web Services Server required to run the message selector using this file

Optional

Version= version number of the message selector set file, specified manually by the developer or integration end-user

Optional

ChangeDate= date when the file last changed, specified manually by the developer or integration end-user

Optional

Description= free-text description of the entire message selector set

Optional

Enable= specifies whether the message selector set (and all message selectors in it) are enabled for use

Valid values:

■ TRUE – enabled■ FALSE – disabled

Required

Figure 17 Sample message selector set header

SelectorSetName=testselectorFormatVersion=2Version=7.1ChangeDate=November 14, 2007Description=This file contains the event selector testsEnable=TRUE


Format

A message selector header must precede each collection of message selector criteria in the message selector set.

Table 20 on page 112 describes the required and optional message selector header parameters that precede each message selector.

Table 20 Message selector header contents

Parameter Description Inclusion

SelectorName= name of the message selector, used by the BMC II Web Services Server to identify the message selector that will be used in selection

The name must be unique within the message selector set.

Required

Description= free-text description of the message selector Optional

FailOnMissingSlot= indicates whether the match for the message selector fails if a slot specified in the message selector criteria is missing from the message

Valid values:

■ TRUE – the match for the message selector fails if a slot specified in the message selector is missing from the message

■ FALSE – missing slots cause the line to be ignored

If the message that is being examined does not include any of the slots that are being tested by the message selector, the comparison will never result in a match. This is true even when the parameter statement is FailOnMissingSlot=false.

If you use the reqdslot keyword in the message selector criteria, it is in effect only when FailOnMissingSlot is set equal to false.

Optional

IsSubSelector Indicates whether the message selector can be called only by the $doselector() function. Valid values are true or false.

Optional

Enable= specifies whether the message selector is enabled for use

Valid values:

■ TRUE – enabled■ FALSE – disabled

Required


Format

Message selector criteria

Each message selector in a message selector set is constructed of successive lines of comparison criteria. Each criterion is composed of a comparison expressed as an equation. Equation operators are listed in Table 22 on page 117.

Each line contains one criterion with an AND relationship implied between lines (unless otherwise indicated).

In addition, the message selector can consist of multiple groups of comparison criteria, each group related to the other through an AND, OR, ||, or && connector.

Format issues

Messages selector functions, which are internal to the message selector file, are described in Table 21 on page 114. Operators are described in Table 22 on page 117.

■ Each message selector in a set is enclosed in curly braces ({ }).

■ Message selector groups within a message selector are nested one level deep and also enclosed in curly braces. Do not nest message selector groups more than one level deep.

■ To the right of the operator is a slot, static text, or a function. On the left is a slot, regular expression, static text, or a function.

■ Explicit text that is used as a matching criterion must be enclosed in double-quotes (" ").

■ If a criterion fails but has an OR relationship with the following criterion, and that criterion is a match, then that criterion pair is a match.

■ The message selector functions scan each successive selector group in a message selector until it finds a match. Once they find a match, they stop searching.

■ The # symbol is used to comment out the rest of a line in a file. This symbol can be used to alter message selector functions, as well as conceal developer comments. When a line in a message selector is commented out, the selection function ignores it.

Figure 18 Sample message selector set header

SelectorName=EVENT_SELECTORDescription=Selectors for all events of class EVENTFailOnMissingSlot=falseIsSubSelector=trueEnable=TRUE


Format

Do not comment out whole message selectors or selector sets. Instead, set the Enable parameter of the message selector set header or the message selector header to FALSE to disable the message selector set or selector.

EXAMPLE The $functionName resolves a specified function and compares the results of that operation to a slot in the message: for example,

$ClassName = "SECURITY_ALERT"

The $ClassName function returns the class name of the message. The returned value is compared to the value to the right of the operator (in this case, the class name, SECURITY_ALERT). If the message class name is SECURITY_ALERT, then the test is successful.

Table 21 Message selector functions (part 1 of 4)

Function Description

$HostName specifies the host name of the computer on which the message selection program is running: for example, $HostName="MYCOMPUTER".

This function can also be inserted in the new message as a slot value: for example, "MYCOMPUTER"=$HostName. .

$ClassName class name of the source message. This function can also be inserted in the new message as a slot value to set the class value of a destination event.

Examples:

slot.imclass=$ClassName$ClassName="EVENT"

slot.slotname compares the value of slot.slotname in the message with the value specified to the right of the operator.

When the slot and the value are both present in the message, the criterion is considered a match.

Example: slot.severity = “Critical”


Format

$doselector calls additional message selectors or subselectors, either or both of which can be linked to or included with an overarching message selector

$doselector is used as a single criterion in the message selector or subselector.

$ClassName!="EVENTS"$doselector(security_sel)slot.status != "OPEN"

The message selector examines the message class to determine whether it is “EVENTS.” Then, the message is compared to the security_sel selector. If that comparison is completed successfully (all criteria matching), the comparison process continues processing using the original message selector.

Example of $doselector calling a subselector:

SelectorName=SELECTOR_ONEDescription=does some quick checks then calls the sub selectorFailOnMissingSlot=falseEnable=TRUE{slot.host="bob"$doselector(SELECTOR_SUB)}

SelectorName=SELECTOR_SUBDescription=makes sure it is not a test eventFailOnMissingSlot=falseEnable=TRUE{slot.msg!="This is a test"$Class!="EVENT"}

Note: For a message to be considered a match to a message selector, it must match all the criteria of the message selector, including the criteria of message selectors or subselectors called by the $doselector function.

$slotPresent specifies a slot name that must appear in the message that is being examined for the criterion to be a match

Example: $SlotPresent(slot.severity)

Unlike the slot.slotname criterion also described in this table, the value of the slot is not considered.




Format

$slotMissing specifies a slot name that must not appear in the message that is being examined for the criterion to be a match

Example: $SlotPresent(slot.severity)

Unlike the slot.slotname criterion also described in this table, the value of the slot is not considered.

$TimeT returns the number of seconds since January 1, 1970 in number format.

Examples:

mc_date=$TimeTSlot.mc_date=$TimeT

$Format similar to printf, uses %s to insert values into a string, expands \t and \n.

Note: %s is the only formatter available for $format.

Examples:

mc_origin=$format("%s:%s", slot.p_agent, slot.p_agent_port)$format("%s:%s", slot.p_agent, slot.p_agent_port)=mc_origin.

$LocalTime enables you to specify the local time using the same format parameters as strftime

Examples:

time=LocalTime("%I:%M:S%p")Slot.time=LocalTime("%I:%M:S%p")

$GmtTime enables you to specify GMT time using the same format as strftime

Examples:

time=$GmtTime("%I:%M:S%p)Slot.time=$GmtTime("%I:%M:S%p")

$subString extracts specified components of a string

Example: msg=$subString(slot.test, 0, 20)

where the first parameter (slot.test in the example) is the slot or string to divide; the second parameter (0 in example) is the index of the first character to include; and the third parameter (20 in example) is the number of characters to include.

$ToLower converts all of the characters in a string to lowercase

Example: mc_host=$ToLower(slot.hostname)

$ToUpper converts all of the characters in a string to upper case

Example: mc_domain=$ToUpper(slot.domain)




Format

Table 22 on page 117 describes the operators that can be used for comparison in a message selector set file.

$GetListValue retrieves the value at a specified location in a slot list

Example: note=GetListValue(slot.notes, 3)

where the first parameter (slot.notes in the example) is the slot to be examined from the source message and the second parameter (3) is the index of the value to be retrieved.

$IpFromName performs a domain name server (DNS) lookup for the host name associated with the specified IP address

Example: IP=$IpFromName("hostname.domain")

$HostFromIp performs a DNS lookup for the IP address associated with the specified host name

Example: mc_host=$HostFromIp(slot.srcIP)

Table 22 Message selector operators (part 1 of 3)

Operators Description

= for a match, the result to the left of the equals ( = ) operator must equal the result to the right of the operator

Example: $Slot.Test = “EVENTS”

!= for a match, the result to the left of the not equals ( != ) operator must not equal the result to the right of the operator

Example: $ClassName!="EVENT"

=~ regular expression operator

If the message that is being evaluated by the message selector contains the specified parameter and parameter value, a match is made.

Example: slot.severity=~"MAJ*."

The message selector file supports multiple regular expression operators and keywords.




Format

!=~ regular expression operator

If the regular expression fails to match, then the entire line succeeds. If the regular expression matches the value, then the line fails.

Example:

slot.severity!=~"MAJ~."

||OR

symbol and literal string, both of which specify an OR relationship between successive lines of message selector criteria or between successive message selector groups

Example: OR relationship between successive lines of criteria$HostName = “data301”||$HostName = “data400”

By default, AND relationships exist between successive lines of message selector criteria.

&&AND

symbol and literal string, both of which specify an AND relationship between successive lines of message selector criteria or between successive message selector groups

Example: AND relationship between message selector groups

{slot.Test=”EVENTS”slot.mc_host=”EVENTS”}AND{slot.Test=”EVENTS2”slot.mc_host=”EVENTS2”}

By default, AND relationships exist between successive lines of message selector criteria.




Format

Table 23 on page 120 describes message selector keywords that are prefixed to specific slots to indicate their function: metadata, required, or readable value. Remember to include the trailing dot (.) when prefixing the keyword to the slot name.

{ } indicates groups of alternate message selector criteria within an inidividual message selector. A group can be nested one level deep.

Example:

{

{slot.Test=”EVENTS”slot.mc_host=”EVENTS”}AND{slot.Test=”EVENTS2”slot.mc_host=”EVENTS2”}

}

> specifies a greater-than comparison. Used exclusively with numerical relationships

Example: slot.Test>10

>= specifies a greater-than or equal to comparison. Used exclusively with numerical relationships

Example: slot.Test>=11

< specifies a less-than comparison. Used exclusively with numerical relationships

Example: slot.Test<12

<= specifies a less-than or equal to comparison. Used exclusively with numerical relationships

Example: slot.Text<=11




Editing the selector file

Editing the selector file

1 If necessary, copy the iiws.selector file from the drive:\installDirectory\mcell or installDirectory/mcell directory to the working directory of your BMC II Web Services Server installation.

2 In a text editor, open the iiws.selector.

3 Modify the different file components—selector set header, selector header, selector content, and operators—as needed.

4 Save the file using the file name of your choice and the file extension .selector. If you change the name of the selector file, modify the server instance parameter svci:IIAPISelectorFile in the servercfg.xml file accordingly.

5 Ensure that the selector file can be read by the user under whose permissions the web services server is running.

Table 23 Keyword descriptions

Keyword Description

metaslot. designates a slot as a metaslot, which means a slot that provides information about the message. The keyword, followed by a dot, is prefixed to the slot name that it designates.

Example: metaslot.class_name="EVENT"

reqdslot. designates a slot as a required slot. If the FailOnMissingSlot parameter is set equal to FALSE and if the message does not contain the specified required slot, it will not pass the message selector criteria. If the FailOnMissingSlot parameter is set equal to TRUE, then the BMC II C APIs ignore the reqdslot indicator.

Example: reqdslot.msg="TEST"

slot. designates a readable slot value in regular expressions

slot.msg=~"event from slot.host"

The BMC II C APIs return the value of host before forwarding the regular expression to the expression library.

NOTE For additional information about selector files, see the BMC Impact Integration Developer’s Kit C API Developer Guide.


Supplemental message selector files

6 If the BMC II Web Services server is running, restart it to initialize the changes. See “Starting and stopping the BMC II Web Services Server” on page 59.

Supplemental message selector filesThe BMC II Developer’s Kit C API loads these four supplemental message selector files, each serving a different filtering purpose for incoming and outgoing events:

■ recvfilterin.selector■ recvfilterout.selector■ sendfilterin.selector■ sendfilterout.selector

On the BMC II Web Services Server side, these supplemental message selector files are stored under %installDirectory%\mcell or $installDirectory/mcell. By default, the filters contained in these files are turned off (Enable=FALSE). When you enable them and define the selectors, they are used in conjunction with the iiws.selector file to help filter events in or out.

All incoming and outgoing events that are sent or received by the BMC II Web Services Server are first scanned by the filters in these message selector files. These filters are global, applying to all events that are passed back and forth between the BMC II Web Services Server and the cell. If the incoming events are not rejected by the supplemental message selector files, then they are scanned by the filters in the BMC II Web Services Server’s iiws.selector file, which is specific to the client request.

Table 24 on page 121 describes in more detail the different message selector files.

Table 24 Supplemental message selector files

Direction Message selector file Description

Incoming events

recvfilterin.selector specifies the message selector criteria for accepting incoming events. If the incoming event does not match the message selector criteria, it is rejected automatically.

recvfilterout.selector specifies the message selector criteria for rejecting incoming messages. If the incoming event does not match the message selector criteria, it is passed on to be scanned by the message selector criteria in the integration’s selector file.


Editing the supplemental message selector files

Editing the supplemental message selector files

1 To enable any of the message selector files, open it in a text editor. The example below shows an excerpt from the recvfilterin.selector file:

2 For each selector set and each selector you wish to use, change the Enable parameter from FALSE to TRUE.

You can modify the selector criteria of each selector to accommodate your filtering requirements.

3 Save the modified selector file; do not change the file name.

Outgoing events

sendfilterin.selector specifies the message selector criteria for approving and passing on outgoing events. If the outgoing event does not match the message selector criteria, it is filtered out automatically.

sendfilterout.selector specifies the message selector criteria for rejecting outgoing events. If the outgoing event does not match the message selector criteria, it is passed to its destination.

## Selector Set information SelectorSetName=RECV_FILTER_INVersion=1FormatVersion=2ChangeDate=October 18, 2005Description=This file contains selectors for filtering in incoming eventsEnable=FALSE

SelectorName=BY_CLASSData=Description=This example will filter in based on class.FailOnMissingSlot=falseEnable=FALSE{$ClassName="EVENT"}

TIP Be sure to keep the selector criteria in the supplemental selector files consistent with the selector criteria that is defined in the iiws.selector file. You do not want to accidentally filter out events that your integration client wants to receive.

Table 24 Supplemental message selector files

Direction Message selector file Description


Configuration file


Configuration fileThe BMC II Web Services configuration file, iiws.conf, is a text file. The configuration file is stored in the drive:\installDirectory\mcell or installDirectory/mcell directory that resides on the BMC II Web Services Server. It is accessed at runtime by the BMC II Web Services server. Its file path is designated in the installDirectory/conf/servercfg.xml or drive:\installDirectory\conf \servercfg.xml file, as shown in the following example:

You can create several configuration files. You decide which one to load on the server to make available to the web service clients.

The configuration file contains parameters that:

■ specify whether the tracing facility is used, where the trace parameters file is located, where the sample log file that is created is located, and how that log file is maintained

■ determine how underlying BMC II C APIs operate

■ are required by your web services server

Configuration file parameters

Table 25 on page 124 lists and describes the configuration file parameters as implemented by the BMC II APIs.

svci:IIAPIConfigFile="C:\Program Files\BMC Software\ImpactIntegration Web Services\mcell\iiws.conf"

NOTE

co

It may be convenient for you to store additional parameters required by your web services server in the *.conf file. This is optional.

If you choose to do this, your web services server accesses these parameter values using the configuration functions described in the BMC Impact Integration Developer’s Kit C API Developer Guide.



The default iiws.conf contains a subset of these values, plus a unique configuration parameter value, DisableSlotListSet, which should always be set equal to Yes. This configuration parameter value enables the BMC II Web Services Server to process incoming messages that are enclosed within brackets as regular slot strings.

Table 25 Configuration file parameters (part 1 of 12)

Group Parameter Description

Impact Manager Instances

ServerDirectoryName path and name of the directory file (default file name: mcell.dir). Required.

BMC Software recommends that you store the mcell.dir file in the integration working directory or in the $MCELL_HOME/etc directory.

Notes:

■ The mcell.dir file contains a list of all BMC Impact Manager instances to which the integration can connect.

■ The integration can use the mcell.dir file supplied with the integration, or it can use the mcell.dir file of a BMC Impact Manager instance that is already installed on the same host.

ServerLocation specifies an individual IP address or host name that the server binds to



Connection Manager

ClientSourceIP static IP address that your integration can use when it is acting as a client (sending events). Optional.

ClientSourcePort port that your integration can use when it is acting as a client (sending events). Optional.

ConnectionSetupTimeOut maximum time, in seconds, that a CLI command attempts to establish a connection to a cell

If the connection with the cell cannot be completely established within this time frame, the command aborts.

Default: 10 seconds

Notes:

■ If the cell is busy with a database cleanup, it may be impossible to connect the CLI with the default values. A database cleanup has a duration limit defined by the EventDBCleanupDurationLimit option, with a default value of 30 seconds. With a default ConnectionSetupTimeOut of 10 seconds, the connection cannot be established within the first 20 seconds of a cleanup.

■ EventDBCleanupDurationLimit is described in the BMC Impact Solutions: General Administration guide.





Connection Manager (continued)

ConnectionPortRange specifies the range of ports to use for outgoing connections

For a cell, this applies to forward propagation. It is the port used on the client side (or on the propagating cell side). This is useful only to pass the event through firewalls with high restrictions. Most firewall configurations ignore source port information but require destination port information.

However, firewall configuration usually can restrict the source ports as well.

The default is (empty).

ConnectionPortReuse indicates whether or not the ports specified in ConnectionPortRange should be reused as much as possible

By default, the cell or CLI tries to reuse ports from the specified range, in the given order. When ConnectionPortReuse=No, for every new connection within the same session, the next free port from the specified range is used. Only when it reaches the end of the range will it restart at the beginning of the range.

Default=Yes

Encryption indicates whether communications are encrypted

Valid values:

■ No■ Yes (Default)

Message Propagation

MessageBufferKeepSent time, in seconds, to keep sent messages buffered while waiting for an answer

Default: 300 seconds

MessageBufferKeepWait time, in seconds, that messages are retained in the buffer while waiting for the connection to be established

Default: 3600 seconds (one hour)

MessageBufferSize maximum number of messages that can be stored in the message buffer. Optional.

Default: 2000 messages





Message Propagation (continued)

MessageBufferReconnectInterval period of time, in seconds, between attempts to connect to a BMC Impact Manager instance. Optional.

Default: 600 seconds

Notes:

■ The value of this parameter cannot be less than 60 seconds.

■ When a connection is established, the integration sends buffered messages that are designated for the BMC Impact Manager instance with which the connection is established.

For more information, refer to the BMC Impact Integration Developer’s Kit C API Developer Guide.

MessageBufferResendCount number of times to resend unanswered messages

Default: 1





Persistency Buffer Manager

PersistencyEnabled enables persistency, which specifies additional buffering parameters when the buffer mode is Default

Valid values:

■ No (Default)■ Yes

PersistencyLevel buffer mode used when the Default buffering mode is specified. This parameter is enabled only when the PersistencyEnabled parameter value is Yes. Optional.

Valid values:

■ None (Default)■ Low ■ High

Note: These values are case-sensitive and should be entered as shown here.

PersistencyFileName name of the file in which the buffered messages are stored

Default: log_directory\imgw-integrationName.dat [persist.dat]

PersistencyCleanupSizeThreshold

threshold size, in bytes, of the persistency file that activates garbage collection

PersistencyCleanupGarbageThreshold

threshold size, as a percentage of file size, of the persistency file that activates garbage collection

The default is 40 percent.

PersistencyDisconnectRemovesMessages

indicates whether messages written to the persistency file are deleted when the integration disconnects intentionally from a BMC Impact Manager instance

Valid values:

■ No (Default value)■ Yes

Note: The contents of the file are not deleted when the integration terminates unexpectedly.





Heartbeats HeartBeatInterval integer that indicates the number of seconds between heartbeats.

Default value: 30 seconds

The minimum value is 1 second. The configuration file does not define a maximum value.

EnableHeartBeats a Boolean indicator that determines whether the integration component uses the heartbeat signal. Valid values are

■ true/false■ yes/no

The entries are not case sensitive.

Receive buffer KeepRecvPersisted Boolean indicator that determines whether a message file persists when the associated message is removed from the message queue

Valid values are


The entries are not case sensitive. The default value is true or yes, indicating that the persistent file that contains a copy of the message remains after the message is removed from the queue.

When the integration is running in server mode and receives an incoming message (an event or a modify), it saves a copy of the message to a file. By default, the integration does not delete the message file until the integration calls the bmcii_freeMessage() function. If you set the KeepRecvPersisted parameter value to false or no, the integration deletes the message file when the message is removed from the queue.

ReceiveBufferDir the directory where receive buffer resides. The default is the log_directory

EnableRecvPersist Boolean indicator that shows whether the message file persists in the incoming buffer. The default is false, meaning that the message file is not persisted in the incoming buffer.





Receive buffer(continued)

DropAcks Boolean indicator (true/false, yes/no) that tells the receive buffer to retain or drop acknowledgments. The default is true. When the DropAcks is set to true, the integration application does not receive replies indicating that the request is a success. However, the integration application still receives cancellation notices and error messages.

Do not modify the default setting because the BMC II Web Services Server does not need to process acknowledgments. It operates more efficiently by not processing them.

RecvBufferSize number value that restricts the number of

■ events■ acknowledgements■ error messages■ cancellation notifications■ status notifications■ connection notifications

that are stored in their respective buffers and that are received from a cell (propagation), an mposter command, or another integration.

Note: These items are stored in two separate buffers. The RecvBufferSize value applies to each one. Events and modifies are stored in one buffer, while the acknowledgements, error messages, and notifications are stored in a second buffer.

The default value is 20,000. When the default or specified maximum value is reached in each buffer, the buffer discards the oldest item and begins to cycle the items as new ones are received. If you set the value to 0, then no restriction is placed on the size of either buffer.





Trace Parameters Trace flag that indicates whether tracing is enabled. Optional.

Valid values:

YES or ON– enable tracing

NO or OFF – disable tracing (Default)

TraceSrc when displaying a trace message, specifies whether to display the source code file name and line number where trace message originated. Optional.

Valid values:

YES or ON – display file name and line number

NO or OFF – no display of file name and line number

Note: Depending on the location of the trace message, the source may be in the integration or the BMC II Web Services Server code.

TraceTime Boolean indicator that says whether the date and time are appended to the trace file. The default value is YES. Valid values are

YES or ON – date and time are appended to the trace value

NO or OFF – date and time are not appended

TraceConfigFileName path and file name for the iiws.trace file. Required, if Trace=YES.

You can enter a hard-coded file path or use the substitution parameters described in “Editing the configuration file” on page 136.

TraceDefaultFileName default destination file (trace.log) to which trace messages are redirected from stderr, when the integration runs as a daemon or a service. Required, if Trace=YES.





Trace Parameters (continued)

TraceFileSize maximum size, in KB, of the trace messages file. Optional.

Valid values:

0 - No limit

n - size of file in KB

Note: BMC Software recommends that the value of this parameter be no less than 500 KB.

TraceFileHistory number of trace files to be kept in history. Each file numbered sequentially. Optional.

Valid values:

0 – No files kept. (Default)

n - number of files to keep

TraceFileAppend when the integration is restarted, specifies whether to append new trace messages to the existing message trace file. Optional.

Valid values:

YES or ON – appends new messages to the existing trace message file (Default)

NO or OFF - empties the current trace message file





Troubleshooting UseMemWatch Boolean indicator that activates a debug behaviors which determines whether the integration is passing bad data to the BMC II C APIs

Valid values are


The default value is false or no.

If you enable the UseMemWatch parameter, the BMC II C APIs maintain a list of valid memory that contains strings, string lists, messages, and replies. Any memory objects that the BMC II C APIs create and pass back to the integration are tracked and verified.

You can view any errors in the integration’s trace log.

The memory list created by the BMC II C APIs does not validate string values that are created by an integration.

DumpIncoming Boolean indicator that tells the integration whether to add incoming events to the trace file. The default is false.

Performance MinClientSleep For an integration that is defined as a client, this is a string value that determines the absolute minimum time for which the receive thread pauses during its processing.

The valid values are

■ 0 to 2000 milliseconds under Windows■ 1 to 2000 milliseconds on UNIX platforms

The default value is ten milliseconds on both platforms.

Note: If your client sends a large number of events in a continuous stream, you can consider increasing the MinClientSleep value so that the client can use more time to send events and the BMC IM cell can keep pace with the event processing.





Performance(continued)

MinSleep For an integration that is in server mode, this is a string value that determines the absolute minimum time for which the receive thread pauses during its processing.

The valid values are

■ 0 to 2000 milliseconds under Windows; default value is 0

■ 1 to 2000 milliseconds on UNIX platforms; default value is 1

MaxSleep string value that determines the upper range of the receive thread’s pause time

The valid values range from any value greater than the MinClientSleep or MinSleep value to 2000 milliseconds. The default value is 500 milliseconds.

MinQueryTimeout integer that specifies the absolute minimum time in milliseconds that the integration waits for a query result before it times out. The timeout period measures the time between responses from the cell. The default value is 2000 milliseconds (2 seconds).

For example, your query call requests 100 results. You receive the first 50 results without a delay equal to or greater than 2 seconds. However, you do not receive the next result within two seconds. Your integration then times out.

You can override this configuration parameter value in the query function bmcii_retrieveQueryResults by specifying a timeout value greater than the minimum specified by the MinQueryTimeout parameter. If the value is the same or lower, it is ignored.





Miscellaneous

UniqueIDFile overrides the default name and/or location of the uniqueID.dat file. Optional.

Notes:

■ The default location is the workingdir/log/instance_name/uniqueID.dat. The location and name of this file can be overridden.

■ To use this parameter, the integration must have permission to write to the uniqueID.dat file.

■ The value of this parameter in this file increments by one (1) before a new ID is assigned.

ServerAllInterfaces specifies whether a newly-created server binds to all available interfaces. Optional.

Valid values:

■ YES or ON – binds (Default)■ NO or OFF – does not bind

You use this parameter whenever you run the BMC II C APIs as a service. When running a as service, you bind to a specific port number where you receive all network traffic. If you have multiple Ethernet cards, you can say you want to bind to the same port on all of the Ethernet cards (interfaces). Alternatively, you can bind to a specific interface by binding to an IP address.

Note: For more information about binding and the ServerAllInterfaces cell configuration parameter, see the BMC Impact Solutions: General Administration guide.

LocaleConfigFileName directory path for language support where the catalog files and the .load file are located. The default is under the ./locale path: for example, installDirectory/IIWS/locale/iiws.load.




Editing the configuration file

Editing the configuration file

1 If necessary, copy the iiws.conf file from the drive:\installDirectory\mcell or installDirectory/mcell directory to the corresponding location of your web service server installation.

2 Using a text editor, open the iiws.conf file.

3 Modify the values of the required parameters and any optional parameters that you want to include (described in Table 25 on page 124).

4 Optional. Modify the file to include any optional BMC II Web Services server parameters that you want to use. Table 25 on page 124 lists these parameters.

5 Optional. Add any integration-specific configuration parameters (not directly related to BMC II Web Services) that you want to store with the BMC Impact Manager configuration data.

6 Save the file using the file name of your choice and the file extension .conf.

7 Ensure that the configuration file can be read by the user under whose permissions the web services server is running.

8 If you overrode the default location or name of the UniqueID.dat file, described in Table 25 on page 124, you must grant the web services server write access on the file.


NOTE You can use the following substitution parameters in the configuration (.conf) and trace (.trace) files:

%H – home directory%C – configuration directory%L – log file directory%T – temporary file directory%P – Integration name%N – Instance name

For more information about path value variables, see the BMC Impact Solutions: Administration guide.


Trace file

Trace fileA sample iiws.trace file is located under drive:\installDirectory\mcell or installDirectory/mcell. By default, the trace functionality is enabled in the installDirectory/conf/servercfg.xml or drive:\installDirectory\conf \servercfg.xml file, as shown in the following example:

The BMC II Web Services server writes its logging messages to the iiws.trace file.

Configure trace functionality as you would in a BMC Impact Manager product instance.

To set up tracing, you must modify:

■ the trace parameters in the iiws.conf file. For more information, see “Editing the configuration file” on page 136.

■ the trace configuration file. See “Editing the trace configuration file” on page 138.

For more information about the configuration files (*.conf and *.trace), see the BMC Impact Solutions: Administration guide.

Figure 19 on page 138 depicts a sample trace file.

svci:EnableTrace="1"


Editing the trace configuration file

Editing the trace configuration file

1 If necessary, copy the iiws.trace file from the drive:\installDirectory\mcell or installDirectory/mcell directory to the working directory of your BMC II Web Services Server installation.

2 In a text editor, open the iiws.trace.

3 Modify the file according to the instructions in the BMC Impact Solutions: Administration guide.

Figure 19 Sample trace configuration file

# BMC Impact Manager 3.2 # Cell trace configuration file # # Configuration: # This configuration mentions the destination for trace messages # on a module/level basis. It can also indicate destinations for # special tracing switches. # Each configuration line overrides any possible previous settings. # # Format of a configuration line: # Module Level Destination # Module SWITCH Switch Destination # Where # Module = name of module (see list 'Module' below) # Level = message level (see list 'Level' below) # Switch = switch name (see list 'Module Switch' below) # Destination = destination file name or predefined value # (see list 'Destination' below) # A wildcard can be specified for Module and for Level : # ALL or *

ALL ALL stderr ALL VERBOSE no

NOTE You can use the following substitution parameters in the .trace file.:

%H – home directory%C – configuration directory%L – Integration log file directory%T – Integration temporary file directory%P – Integration name%N – Instance name

For more information about path value variables, see the BMC Impact Solutions: Administration guide.


mcell.dir file

4 Save the file using the integrationName.trace naming convention.

5 Grant the integration account read access to the integrationName.trace file.

6 Ensure that the TraceConfigFileName parameter in the iiws.conf file points to the location in which you saved the integrationName.trace file.

7 Save the file using the file name of your choice and the file extension .trace.

8 Ensure that the trace file can be read by the user under whose permissions the BMC II Web Services Server is running.

9 Important. Ensure that the TraceConfigFileName parameter in the .conf file points to the location in which you saved the .trace file.

10 If the server is running, you must stop and restart it to make sure the configuration changes go into effect. For procedures for starting and stopping the sever, see “Starting and stopping the BMC II Web Services Server” on page 59.

mcell.dir fileThe mcell.dir file lists the identifying information for all BMC Impact Manager product instances (cells) and event receivers (WSCELL) to which your implementation can connect and communicate. It is used to look up a BMC Impact Manager product instance or web services server name and to determine its host, port, and encryption key.

Editing the Integration mcell.dir file

See “How to synchronize BMC II Web Services Server and BMC IM cell connections” on page 38 for the procedure for editing the respective mcell.dir files of the BMC Impact Manager instance and of the BMC II Web Services Server installation.

TIP In the configuration file, ensure that the ServerDirectoryName parameter points to the directory location of the mcell.dir file on the BMC II Web Services Server.


Editing the Integration mcell.dir file


A p p e n d i x B
B Error Messages and Codes
This appendix describes the BMC II Web Services error messages. It also describes the underlying BMC II C API error codes and BMC Impact Manager core communications error codes to which the Web Services messages refer.

BMC II Web Services Server error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141BMC II C APIs and core communications errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Errors listed By error code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Error descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Core communications errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Errors listed by error code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Error descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

BMC II Web Services Server error messagesBMC II Web Services generate the following text messages and return them to the web services client. Several of these text messages contain BMC II C API error codes (indicated in the text by the variable BMCII Error Code). When you see such an error code in the text, you can refer to corresponding error code in Table 26 on page 144. Then you can refer to a description of the BMC II C API error and a possible response under the heading “Error descriptions” on page 146.

Error <BMCII Error Code> connecting to cell, <Cell Name>

Explanation: A connection problem exists in the BMC II C API and is reflected in the bmciiws_connect call.

NOTE User responses and troubleshooting information for the BMC II Web Services error messages is provided through the BMC Software’s Developer Connection Web site at http://devcon.bmc.com/.


http://devcon.bmc.com

BMC II Web Services Server error messages

Error closing connection

Explanation: A disconnection problem exists in the BMC II C API and is reflected in the bmciiws_disconnect call.

Error: No name-value information in the event

Explanation: The web services server has received an empty event from the C API function in the bmciiws_send call.

Error creating message

Explanation: The BMC II C API function generated an error in creating a message to be sent to a cell in the bmciiws_send call.

Error creating message class and type

Explanation: The BMC II C API function generated an error in setting the message type to be sent to the cell in the bmciiws_send call.

Error <BMCII Error Code> setting slot

Explanation: The BMC II C API function generated an error in setting the slot name and value in the bmciiws_send call.

Error <BMCII Error Code> setting slot list <Index in the List>

Explanation: The BMC II C API function generated an error in setting the slot (list type) name-value in the bmciiws_send call.

Failed to send message to cell

Explanation: The BMC II C API failed to send the message to the cell in the bmciiws_send call.

Error getting selector names

Explanation: The BMC II C API failed to get selector names in the bmciiws_getFilterNames call.

The client context is not subscribed to the requested filter

Explanation: An invalid client context ID has been entered in the polling call bmciiws_getEvents to get events.

Error <BMCII Error Code> initiating query

Explanation: The BMC II C API generated an error when issuing the bmciiws_query call to a cell.


BMC II Web Services Server error messages

Error <BMCII Error Code> issuing query

Explanation: The BMC II C API generated an error when issuing the bmciiws_query call to a cell.

Invalid time error

Explanation: An incorrect date is entered in the query call bmciiws_queryByDate.

Invalid result handle

Explanation: The client has returned an invalid result handle to close the bmciiws_endQuery call.

Error cleaning up cell handles

Explanation: The BMC II C API generated an error in the bmciiws_endQuery call when cleaning up the query handle ID in the web services server.


Explanation: The client has provided an invalid result handle in the bmciiws_getQueryResultCount call.

Error retrieving result count for query

Explanation: The BMC II C API generated an error when retrieving the result count of the query call bmciiws_getQueryResultCount.

Invalid start index

Explanation: The client has supplied an invalid start index in the bmciiws_getQueryResult call.


Explanation: The client has supplied an invalid result handle in the bmciiws_getQueryResult call.

Result count not found

Explanation: The result count is unknown for fetching the query result in the bmciiws_getQueryResults call.

Invalid start index

Explanation: The client has requested a start index that is invalid or greater than the query result count in the bmciiws_getQueryResults call.


BMC II C APIs and core communications errors

Failed to retrieve query result

Explanation: The BMC II C API has failed to fetch a query result in the bmciiws_getQueryResult call.

BMC II C APIs and core communications errorsErrors with the BMCII prefix relate to all aspects of the BMC II C APIs, which are used to implement integrations with BMC Impact Manager instances. Core communication errors deal with the communications protocol between BMC Impact Manager cells. Core communication errors have the IM prefix and are described in “Core communications errors” on page 157.

Some BMCII errors serve the same purpose as certain IM errors. However, the integration generates only one error for an error-producing event. Which error is generated depends on internal BMC II C APIs processes and cannot be determined before the generation of the error.

Errors are listed numerically by error code and alphabetically by name. The alphabetic listing includes a description of each error.

Errors listed By error code

Table 26 on page 144 lists BMC II C APIs errors, arranged by error code.

Table 26 BMC II C APIs Impact Integration Error Codes (part 1 of 3)

Error Code Error Name Described on

0 BMCII_SUCCESS page 155

-102 BMCII_BAD_MESSAGE page 148

-104 BMCII_BAD_MALLOC page 147

-105 BMCII_BAD_SLOT_NAME page 150

-106 BMCII_BAD_SLOT_VALUE page 150

-107 BMCII_MEMORY_CORRUPTED_START page 153

-108 BMCII_MEMORY_CORRUPTED_END page 153

-110 BMCII_NOT_FOUND page 154

-111 BMCII_BAD_HEAD page 147

-112 BMCII_BAD_CLASS_NAME page 147

-113 BMCII_INDEX_OUT_OF_RANGE page 152

-114 BMCII_ERROR_WRONG_SLOT_TYPE page 151

-115 BMCII_BAD_PARAMETER page 149


Errors listed By error code

-116 BMCII_NEED_MORE_MEMORY page 154

-118 BMCII_END_DELIMITER page 150

-119 BMCII_ERR_MISSING_CONFIG page 151

-120 BMCII_ERR_BAD_FILE_OPEN page 151

-121 BMCII_BAD_CONFIG page 147

-122 BMCII_BAD_EVENT_CREATE page 147

-123 BMCII_BAD_HOST_PORT page 147

-124 BMCII_INVALID_SERVER_NAME page 153

-125 BMCII_ERR_LOST_CONNECT page 151

-130 BMCII_ERR_BAD_OBJECT_CREATE page 151

-131 BMCII_COMM_LOCK_NOT_INIT page 150

-132 BMCII_BAD_MESSAGE_TYPE page 148

-133 BMCII_BAD_SOCKETS_INIT page 150

-136 BMCII_ERR_BAD_FILE_NAME page 151

-137 BMCII_BAD_SELECTOR_HEADER page 149

-138 BMCII_BAD_SELECTOR_NAME page 149

-139 BMCII_NO_MORE page 154

-140 BMCII_BAD_SELECTOR_FILE_FORMAT page 149

-141 BMCII_UNKNOWN_FUNCTION page 156

-144 BMCII_BAD_MAP_FILE_FORMAT page 148

-145 BMCII_BAD_MAP_LINE page 148

-146 BMCII_BAD_SELECTOR_LINE page 149

-147 BMCII_BAD_MAP_HEADER page 148

-148 BMCII_BAD_MAP_NAME page 148

-149 BMCII_MESSAGE_CORRUPTED page 153

-150 BMCII_INVALID_FUNCTION_FORMAT page 152

-160 BMCII_UNKNOWN_SLOT_TYPE page 156

-161 BMCII_ALREADY_INITED page 146

-164 BMCII_FAILED_START_RECV page 151

-165 BMCII_ALREADY_RUNNING page 146

-166 BMCII_TIMED_OUT page 155

-169 BMCII_BAD_RECV_EVENT page 149

-170 BMCII_BAD_MUTEX page 148

-171 BMCII_MAPSET_DISABLED page 153

-172 BMCII_MAP_LOOP_DETECTED page 153

-173 BMCII_SELECTOR_LOOP_DETECTED page 155

-174 BMCII_INCOMPATIBLE_VERSION page 152

-175 BMCII_EMPTY_SLOT_NAME page 150




Error descriptions

Error descriptions

Each BMC II C APIs error is listed alphabetically, along with its description and any prescriptive information.

BMCII_ALREADY_INITED

Explanation: The bmcii_init3() function has been called after the BMC II C APIs have already been initialized.

User response: None. Calling bmcii_init3() more than once will not harm the integration (nor will it do anything positive, either).

BMCII_ALREADY_RUNNING

Explanation: The bmcii_startRecv function has been called after the Receive thread is already running.

User response: None. Calling bmcii_startRecv more than once will not affect Receive thread operation.

-177 BMCII_MUST_CALL_INIT page 154

-178 BMCII_NEED_LOCKS_FOR_THREAD page 154

-179 BMCII_UNKNOWN_TYPE page 156

-180 BMCII_MAP_DISABLED page 153

-181 BMCII_INVALID_CALL page 152

-182 BMCII_BAD_BAROC page 147

-185 BMCII_QUERY_REGISTRATION_FAILED page 155

-188 BMCII_NO_RESULT_YET page 154

-189 BMCII_BAD_PARSE page 149

-190 BMCII_REQUEST_OUT_OF_RANGE page 155

-191 BMCII_QUERY_ERROR page 155

-192 BMCII_QUERY_CONNECTION_DOWN page 155

-193 BMCII_ILLEGAL_QUERY page 152

-194 BMCII_EMPTY_MESSAGE page 150

-195 BMCII_FREED_NULL_POINTER page 152

-196 BMCII_CORRUPT_LIST page 150

-197 BMCII_TERM_CALLED page 155

-198 BMCII_MISSING_MOD_INFO page 154




Error descriptions

BMCII_BAD_BAROC

Explanation: The BAROC string that was passed to the BMC II C APIs using the bmcii_messageSetBaroc function is malformed and cannot be processed.

User response: Correct the BAROC string syntax.

BMCII_BAD_CLASS_NAME

Explanation: The class name is missing from an event or data message. The message information may be intended for a new message or as an attempt to overwrite an existing message.

User response: Set the message class name using either the bmcii_setMessageType or the bmcii_setMetaSlotValue function. Using the bmcii_setMetaSlotValue function is recommended.

BMCII_BAD_CONFIG

Explanation: The parameter specified in a configuration function call (bmcii_get_bool, bmcii_get_dir, bmcii_get_file, bmcii_get_num, or bmcii_get_string) is missing from the integration_name.conf file, or the parameter name was specified incorrectly in the function call.

User response: Update the integration_name.conf file with the correct parameter name or fix the integration code where the configuration function is specified.

BMCII_BAD_EVENT_CREATE

Explanation: The BMC II C APIs are unable to create an event message.

User response: See the trace log for information.

BMCII_BAD_HEAD

Explanation: The header of a BAROC string that was passed to the BMC II C APIs Impact Integration using the bmcii_messageSetBaroc function is malformed or missing. The string cannot be converted into a message.

User response: Correct the BAROC string syntax.

BMCII_BAD_HOST_PORT

Explanation: The host and/or port specified in one of the following functions is invalid or malformed: bmcii_connect, bmcii_setupServer, or bmcii_initQueryConnect.

User response: Check the trace log to ensure that the host name and port number are formatted correctly in the function call code.

BMCII_BAD_MALLOC

Explanation: No memory is available to the BMC II C APIs.

User response: Free existing system memory or add memory.


Error descriptions

BMCII_BAD_MAP_FILE_FORMAT

Explanation: There is an error in the specified map file.

User response: View the trace log for additional information. Correct the map file, if necessary. Rerun the function that called the map file.

BMCII_BAD_MAP_HEADER

Explanation: The header of one or more maps in the specified map file is missing or malformed.

User response: Correct the header in the map file and rerun the function that called the map file.

BMCII_BAD_MAP_LINE

Explanation: There is a syntax error in a line in the specified map file.

User response: View the trace log. It will specify the line that includes the error. Correct the map file. Rerun the function that called the map file.

BMCII_BAD_MAP_NAME

Explanation: The name of a map in the specified map file is missing or malformed.

User response: Correct the map name in the map file. Rerun the function that called the map file.

BMCII_BAD_MESSAGE_TYPE

Explanation: The message type specified in the message is not included in the message type enumeration.

User response: Ensure that the integration is using the correct version of the BMC II C APIs library. The specified message type may be supported by a version of the APIs that is not loaded.

BMCII_BAD_MESSAGE

Explanation: The message is corrupted or includes a null parameter.

User response: Check the integration code for invalid (null) values or a buffer overflow.

BMCII_BAD_MUTEX

Explanation: A mutex internal to the BMC II C APIs is invalid.

User response: Check for a buffer overflow. Report the problem to BMC Developer Connection.


Error descriptions

BMCII_BAD_PARAMETER

Explanation: The integration called a function that included an invalid parameter.

User response: Check the integration code.

BMCII_BAD_PARSE

Explanation: The BMC II C APIs are unable to parse the response from the BMC Impact Manager product instance.

User response: View the trace log for additional information. Report the problem to BMC Developer Connection.

BMCII_BAD_RECV_EVENT

Explanation: An internal event is invalid.

User response: Check for a buffer overflow. Report the problem to BMC Developer Connection.

BMCII_BAD_SELECTOR_FILE_FORMAT

Explanation: The specified selector set file contains an error.

User response: View the trace log for additional information. Correct the selector set file. Rerun the function that called the selector set file.

BMCII_BAD_SELECTOR_HEADER

Explanation: The header of one or more selectors in the specified selector set file is missing or malformed.

User response: Correct the header in the selector set file and rerun the function that called the selector set file.

BMCII_BAD_SELECTOR_LINE

Explanation: There is a syntax error in a line in the specified selector set file.

User response: View the trace log. It will specify the line that includes the error. Correct the selector set file. Rerun the function that called the selector set file.

BMCII_BAD_SELECTOR_NAME

Explanation: The name of a selector in the specified selector set file is missing or malformed.

User response: Correct the selector name in the selector set file. Rerun the function that called the selector set file.


Error descriptions

BMCII_BAD_SLOT_NAME

Explanation: The integration called a function that included a malformed or null slot name.

User response: Check and modify the integration code.

BMCII_BAD_SLOT_VALUE

Explanation: The message contains a slot with a null value or an empty string.


BMCII_BAD_SOCKETS_INIT

Explanation: Microsoft Windows only. Sockets are not initialized because the BMC II C APIs determine the socket library version. The version of Windows on the integration host is not supported.

User response: Verify that your integration is running only on OSes that are supported by the loaded version of the BMC II C APIs. For a list of supported OSes, see BMC Impact Integration Developer’s Kit C API Developer Guide.

BMCII_COMM_LOCK_NOT_INIT

Explanation: Internal error.

User response: Ensure that the bmcii_init3() function was called correctly.

BMCII_CORRUPT_LIST

Explanation: An internal list is corrupt.

User response: Check the log for additional information. Report the problem to BMC Developer Connection.

BMCII_EMPTY_MESSAGE

Explanation: Internal error. The result buffer is corrupt.

User response: Check the log for more information. Remove the current receive buffer file described in the log file. A new file will be created.

BMCII_EMPTY_SLOT_NAME

Explanation: A slot name in the message is set with an empty string.


BMCII_END_DELIMITER

Explanation: A BAROC string that the integration is formatting as a message is missing an END statement.

User response: Verify the string format. Modify it, if necessary.


Error descriptions

BMCII_ERR_BAD_FILE_NAME

Explanation: The bmcii_loadSelectorSet function specifies a null pointer or empty string for the selector set file name. This error message can also apply to map set files specified with the bmcii_loadMapSet function.


BMCII_ERR_BAD_FILE_OPEN

Explanation: The specified map set file (or selector set file) does not exist, or the integration does not have permission to access the specified file.

User response: Verify that the correct file name is specified in the integration code. Verify that the file exists in the location specified in the function call and that the file name is spelled correctly. Update the integration’s permissions for map and selector set files.

BMCII_ERR_BAD_OBJECT_CREATE

Explanation: Internal error. The BMC II C APIs are unable to create a required object.

User response: Check for a buffer overflow and appropriate the required memory resources. Report the problem to BMC Developer Connection.

BMCII_ERR_LOST_CONNECT

Explanation: The connection to the BMC Impact Manager product instance was broken while the integration was sending a message.

User response: Disconnect from the BMC Impact Manager product instance. Then, reestablish the connection and resend the message.

BMCII_ERR_MISSING_CONFIG

Explanation: The name and location of the mcell.dir file are not specified in the integration_name.conf configuration file.

User response: Check the integration_name.conf configuration file. Make any necessary corrections.

BMCII_ERROR_WRONG_SLOT_TYPE


User response: Report the problem to BMC Developer Connection.

BMCII_FAILED_START_RECV

Explanation: The bmcii_startRecvThread function failed to create a new Receive thread.


Error descriptions

User response: Check the logs and verify that the integration host computer supports POSIX or Windows native threads. Report the problem to BMC Developer Connection.

BMCII_FREED_NULL_POINTER

Explanation: An internal list is corrupt.

User response: Check the log for additional information. Report the problem to BMC Developer Connection.

BMCII_ILLEGAL_QUERY

Explanation: The query is not supported by the loaded version of the BMC II C APIs.

User response: For valid query types, see the BMC II C APIs product documentation.

BMCII_INCOMPATIBLE_VERSION

Explanation: The version of the structure passed by the bmcii_getFirstDirectoryInfo or bmcii_getNextDirectoryInfo function is not supported by the BMC II C APIs’ library in use.

User response: Verify that the Version field is set properly before calling either function. Alternately, ensure that the most current library version is being used by the BMC II C APIs.

BMCII_INDEX_OUT_OF_RANGE

Explanation: No more results are available in response to a request for the items in a list of values.

User response: This is not an error. Stop requesting additional values.

BMCII_INVALID_CALL

Explanation: Functions that must be called in a specific order were called out of order.

User response: Check the log and the integration code. Recall the functions in the correct order. For more information, refer to the function descriptions in the BMC Impact Integration Developer’s Kit C API Developer Guide or in the C API Reference Guide.

BMCII_INVALID_FUNCTION_FORMAT

Explanation: The map set (or selector set) specifies a function that includes one or more invalid parameters.

User response: Modify the map set file or selector set file to correct the problem.


Error descriptions

BMCII_INVALID_SERVER_NAME

Explanation: The cell name specified in the bmcii_connect, bmcii_serverSetup, or bmcii_queryInitConnect function is invalid.

User response: Check cell name specified in the function and in the mcell.dir file.

BMCII_MAP_DISABLED

Explanation: The map specified in the bmcii_translate function call is disabled.

User response: This is not an error. However, if the map was disabled unintentionally, enable it and rerun the bmcii_translate function.

BMCII_MAP_LOOP_DETECTED

Explanation: The $domap function is creating a loop in the map set.

User response: Correct the map set file to eliminate the loop.

BMCII_MAPSET_DISABLED

Explanation: The integration did not perform any translation operation because the specified map set was disabled. This error message does not necessarily describe an error, since disabling an entire map set is supported.

User response: If disabling the map set is intentional, no response is necessary. If the map set was disabled unintentionally, enable the map set and rerun the bmcii_translate function.

BMCII_MEMORY_CORRUPTED_END

Explanation: An internal structure is corrupt.


BMCII_MEMORY_CORRUPTED_START

Explanation: An internal structure is corrupt.


BMCII_MESSAGE_CORRUPTED

Explanation: The message that was passed to the BMC II C APIs is invalid or corrupt.

User response: Verify that the correct message was passed. Check for a buffer overflow. Report the problem to BMC Developer Connection.


Error descriptions

BMCII_MISSING_MOD_INFO

Explanation: The event modification that was sent did not include an mc_ueid ID or event handle to identify the event that was to be modified. The data modification that was sent did not include an mc_udid ID or data handle to identify the data object that was to be modified.

User response: Check the integration code to ensure that the required ID slots are included. Modify the message, if necessary.

BMCII_MUST_CALL_INIT

Explanation: The BMC II C APIs are not initialized. All Function calls (except for bmcii_getVersion) can be performed only after bmcii_init3() is called.

User response: Call the bmcii_init3() function and recall the failed function.

BMCII_NEED_LOCKS_FOR_THREAD

Explanation: The bmcii_start RecvThread function cannot create a thread because the UseLocks parameter is missing from the configuration file or is included but set to NO or OFF.

User response: Add the UseLocks parameter to the integration_name.conf configuration file and set it to ON. If UseLocks is already included in the file, change its value to ON.

BMCII_NEED_MORE_MEMORY

Explanation: Fatal error. Failure to allocate memory.

User response: Free existing system memory or add memory.

BMCII_NO_MORE

Explanation: There are no more items in the list.

User response: This is not an error. Stop calling the iterating function.

BMCII_NO_RESULT_YET

Explanation: A query result has not yet been returned.

User response: This is not an error. Recall bmcii_getQueryReply until the BMC Impact Manager product instance returns a reply.

BMCII_NOT_FOUND

Explanation: The requested item (such as a slot) does not exist.

User response: Check the integration code to verify that the requested item exists and is spelled correctly in the code.


Error descriptions

BMCII_QUERY_CONNECTION_DOWN

Explanation: The query connection was broken during the processing of a query.

User response: Reestablish the query connection and recall the failed query.

BMCII_QUERY_ERROR

Explanation: The BMC Impact Manager product instance returned an error.

User response: For more information, see the BMC Impact Manager product instance and integration logs.

BMCII_QUERY_REGISTRATION_FAILED

Explanation: Following an attempt to establish a query connection with a BMC Impact Manager product instance using the bmcii_initQueryConnect function, the BMC Impact Manager product instance returned an error and the connection failed.

User response: Check the log for more information.

BMCII_REQUEST_OUT_OF_RANGE

Explanation: The requested placeholder is not in the list.

User response: This is not an error. Stop calling the iterating function.

BMCII_SELECTOR_LOOP_DETECTED

Explanation: The $doselector function is creating a loop in the selector set.

User response: Correct the selector set file to eliminate the loop.

BMCII_SUCCESS

Explanation: The function call (specified by its return code) was successful. This is not an error. This code is returned for all successful function calls.

User response: None.

BMCII_TERM_CALLED

Explanation: The integration called a function after the BMC II C APIs were terminated.

User response: Re-initialize the BMC II C APIs and recall the required function. Examine the integration code and correct any problems.

BMCII_TIMED_OUT

Explanation: The timeout period specified in the function expired before any results were returned.


Error descriptions

User response: This is not an error. You can recall the function until the results are available.

BMCII_UNKNOWN_FUNCTION

Explanation: The loaded map set or selector set file specifies a BMC II C APIs function not supplied by the BMC II C APIs library in use.

User response: Check the map set or selector set file to ensure that the appropriate function is specified. Verify which version of the BMC II C APIs library is loaded to ensure compatibility.

BMCII_UNKNOWN_SLOT_TYPE



BMCII_UNKNOWN_TYPE

Explanation: The message type that is being passed to the message is unknown. This can happen when setting the message type with the bmcii_setMessageType function or setting META_MSG_TYPE using the bmcii_setMetaSlot function.

User response: In the integration code, check the parameter value being passed as the message type.


Core communications errors

Core communications errorsErrors with the IM prefix are core communications errors in the BMC II C APIs. Errors that are related to other aspects of the BMC II C APIs are described in “BMC II C APIs and core communications errors” on page 144.

Errors are listed by error code and alphabetically (starting on page 158). The alphabetic listing includes a description of each error.

Errors listed by error code

Table 27 lists BMC II C APIs core communications errors, arranged by error code.

Table 27 Core Communications Error Codes (part 1 of 2)


0 IM_ERR_NONE page 161

1 IM_ERR_UNINITIALIZED page 162

2 IM_ERR_INIT_CONFIG page 159

3 IM_ERR_TRACE_CONFIG page 162

4 IM_ERR_INIT_COMM_OUT page 158

5 IM_ERR_INIT_COMM_IN page 158

6 IM_ERR_INIT_MSGS page 159

7 IM_ERR_INIT_PORT_RANGE page 159

8 IM_ERR_INIT_CRYPT page 159

9 IM_ERR_NOTRANSPORT page 161

10 IM_ERR_NOENDPOINT page 161

11 IM_ERR_NOBIND page 160

12 IM_ERR_MEMFAULT page 160

13 IM_ERR_BAD_IP page 158

14 IM_ERR_BAD_LOCATION page 158

15 IM_ERR_NAME_LOOKUP page 160

16 IM_ERR_SVC_UP page 161

17 IM_ERR_SVC_DOWN page 161

18 IM_ERR_INVALID_CNC page 159

18 IM_ERR_INVALID_MSGTYPE page 159

20 IM_ERR_CONNECT page 158

21 IM_ERR_TIME_OUT page 161

22 IM_ERR_NOCONNECT page 160

23 IM_ERR_NOBUFFER page 160


Error descriptions

Error descriptions

Each core communications error is listed alphabetically and includes a description of the error and prescriptive information, if any is available.

IM_ERR_BAD_IP

Explanation: The IP address that was passed to the bmcii_connect, bmcii_initQueryConnect, or bmcii_setupServer function is invalid.

User response: Verify the correct IP address of the target BMC Impact Manager product instance, and ensure that the correct address is specified in your integration code.

IM_ERR_BAD_LOCATION

Explanation: The host name that was passed to the bmcii_connect, bmcii_initQueryConnect, or bmcii_setupServer function is invalid.

User response: Verify the host name of the target BMC Impact Manager product instance, and ensure that the correct name is specified in your integration code.

IM_ERR_CONNECT

Explanation: The integration’s attempt to connect to a BMC Impact Manager product instance (using bmcii_connect or bmcii_initQueryConnect) failed. The integration will not retry to reconnect.

User response: Check that the destination is defined correctly in the mcell.dir file and that the requested server is on destination computer.

IM_ERR_INIT_COMM_IN

Explanation: Initialization of the inbound communication module in the BMC II C APIs failed.

User response: Stop and restart the integration.

IM_ERR_INIT_COMM_OUT

Explanation: Initialization of the outbound communication module in the BMC II C APIs failed.

24 IM_ERR_NOCONTACT page 160

25 IM_ERR_SEND page 161

26 IM_ERR_MAX page 160

Table 27 Core Communications Error Codes (part 2 of 2)



Error descriptions

User response: Stop and restart the integration. Ensure that no other application is using the requested port.

IM_ERR_INIT_CONFIG

Explanation: The integration home directory, the path to the .conf configuration file or the contents of the configuration file is invalid.

User response: Verify that all integration code references to the integration home directory and to the .conf file are correct. Verify that the .conf file does not contain any errors.

IM_ERR_INIT_CRYPT

Explanation: The connection was made using an invalid encryption key.

User response: For information about using encryption, see the BMC Impact Integration Developer’s Kit Impact Integration C APIs Developer Guide.

IM_ERR_INIT_MSGS



IM_ERR_INIT_PORT_RANGE

Explanation: The port range specified with the ConnectionPortRange parameter in the .conf file is invalid.

User response: Specify a port range that is valid for the host operating system. For more information about the ConnectionPortRange parameter, see the BMC Impact Integration Developer’s Kit Impact Integration C APIs Developer Guide.

IM_ERR_INVALID_CNC

Explanation: The integration passed or received an invalid or closed connection handle. This error is displayed for connections initiated by the integration (acting in client mode) and connections directed to the integration (acting in server mode).

User response: Discard the connection handle that is currently in use: If the integration initiated the connection with the problematic handle, make a new connection attempt. A new handle is assigned. If the integration was acting as a server, continue listening for another connection request.

IM_ERR_INVALID_MSGTYPE




Error descriptions

IM_ERR_MAX



IM_ERR_MEMFAULT

Explanation: The BMC II C APIs cannot allocate memory.

User response: Do one or both of the following: free resources or stop and restart the integration. Also, check the integration code for memory leaks.

IM_ERR_NAME_LOOKUP

Explanation: Host name lookup failed.

User response: Check the entries in the mcell.dir file and/or check that the DNS service is working correctly.

IM_ERR_NOBIND

Explanation: The integration cannot start server mode using the specified port number. The port is being used by another application or is privileged.

User response: Check whether the port is in use. If the port is in use, specify that the integration use a different port or stop the application that is currently using the port. If port use is privileged, specify that the integration use a different port or run the integration as privileged user.

IM_ERR_NOBUFFER

Explanation: The message buffer is full.

User response: Increase the buffer size. Modify the value of the MessageBufferSize parameter in the .conf configuration file.

IM_ERR_NOCONNECT

Explanation: The integration sent a message containing the META_FAIL_IF_UNCONNECTED metaslot when no connection was established.


IM_ERR_NOCONTACT

Explanation: Currently, no connection is established to the message destination. The message will be buffered.

User response: Ensure the availability of the BMC Impact Manager product instance or integration to which the message is directed.


Error descriptions

IM_ERR_NOENDPOINT



IM_ERR_NONE

Explanation: No error.


IM_ERR_NOTRANSPORT

Explanation: The TCP/IP stack on the integration host is not available.

User response: Verify that the operating system recognizes the TCP/IP stack and that the appropriate adapters are available.

IM_ERR_SEND

Explanation: The connection attempt failed. This error is displayed for connections initiated by the integration (acting in client mode) and connections directed to the integration (acting in server mode).

User response: If the integration initiated the connection failed attempt, you can make an additional connection attempt. If the integration was acting as a server, continue listening for additional connection requests.

IM_ERR_SVC_DOWN

Explanation: The integration called the bmcii_stopServer function when server mode was not running.

User response: Check the integration code to determine why bmcii_stopServer was called two (or more) times.

IM_ERR_SVC_UP

Explanation: The integration called the bmcii_startServer when the integration was already in server mode.

User response: Check the integration code to determine why bmcii_startServer was called two (or more) times.

IM_ERR_TIME_OUT

Explanation: The timeout period expired for one of the functions that uses a timeout. This is a notice, not an error.

User response: None, unless you want to rerun the function that timed out.


Error descriptions

IM_ERR_TRACE_CONFIG

Explanation: The tracing configuration file (integration_name.trace) is missing, configured incorrectly, or described incorrectly in the integration code.

User response: Locate the file. Ensure that integration code includes the correct name and path to the file. Fix any errors that the file may contain.

IM_ERR_UNINITIALIZED




A p p e n d i x C
C Sample Client Files
This appendix describes the sample client files that are packaged with the BMC II Web Services Server installation. It describes the following topics

List of sample client files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Event Listener Web Services Description Language (WSDL) file . . . . . . . . . . . . . . . 165

Event listener server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Event dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Listenercfg.xml file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Adding SSL parameters to the listenercfg.xml file . . . . . . . . . . . . . . . . . . . . . . . . . 173

List of sample client filesThe BMC II Web Services Server installation includes sample files that you can find under the $installDirectory/samples or %installDirectory%\samples subdirectory. The following samples address Systinet C++ query implementations and can be found under the /waspc/test_query or \waspc\test_query subdirectory:

Table 28 Sample client files: Systinet C++ queries (part 1 of 2)

File name Description

string_util.cpp contains functions that work with string structures

string_util.h the accompanying header file for the sample code containing functions that work with string structures

test_func.cpp reads the test functions in the input file

test_imsw_api.txt example of input file in which test functions are specified


List of sample client files

Under the /waspc/test_events or \waspc\test_events subdirectory, you can find Systinet C++ client code for building a listener client.

You can find a sample .NET C# implementation under the .NET subdirectory. View the readme.txt file under the /.NET/TestIIWs or \.NET\TestIWs subdirectory to see which operations are implemented and how to launch the sample. You can refer to “.NET C# toolkit sample” on page 76 for more information.

You can find a sample Axis Java implementation under the Axis subdirectory.

You can refer to “Apache Axis toolkit sample” on page 77 for more information.

test_imws_api.cpp contains calls for specified BMC II Web Services functions such as tracing, client startup, cell connection, and so forth

test_imws_api.h the accompanying header file for these BMC II Web Services calls

test_util.cpp a script for testing specified BMC II Web Services functions

Table 29 Sample client files: Systinet C++ listener client


EventListener.wsdl exposes the dispatch operations that are required to build a listener client

listenercfg.xml listener client configuration file

client.cpp demonstrates how to subscribe to events through the EventListener.wsdl interface

Table 30 Sample client files: Axis Java implementations


dataQueries provides a programming demo that shows how to write a client which queries events, data, and service model components in the BMC IM cell

receiveEvents shows how to write a client that subscribes to and retrieve events from a BMC IM cell

sendEvents indicates how to send events to the BMC IM cell through BMC IM Web Services Server

wsdl contains the impactManager.wsdl and supplemental schema definition files

Table 28 Sample client files: Systinet C++ queries (part 2 of 2)



Event Listener Web Services Description Language (WSDL) file

Event Listener Web Services Description Language (WSDL) file

The BMC II Web Services package also contains an EventListener.wsdl file that exposes event dispatch operations, which a developer can access to build a custom event listener.

To invoke the dispatch operations in the EventListener.wsdl, you can use the toolkit of your choice, as long as it support event listener libraries. You can write your client in any programming language that is compatible with your toolkit.

The EventListener.wsdl exposes two event dispatch operations that accept one or more events. Using the dispatch operations, you can create your own event listener libraries to implement callbacks in a publish-subscribe scenario. You can write the event listener in any programming language that is supported by your toolkit.

Figure 20 on page 165 depicts how the dispatch operations are implemented in BMC II Web Services.

Figure 20 Dispatch Operations in EventListener.wsdl

NOTE In the current implementation of the BMC II Web Services server, the event dispatcher component only invokes the _dispatch operation. It does not invoke the _dispatchList operation.


Event listener server

Event listener server

Using the event listener libraries of your toolkit, you configure on the client an event listener server with a specific callback URL and port number. The client registers the callbacks, which contain the event handler logic, with the event listener server. When the event listener server receives an event, it dispatches it to a callback in the list of callbacks that it maintains. The callback invokes the event handler logic.

Event dispatcher

The BMC II Web Services Server starts the WSCELL message receiver and begins to receive events propagating from connected BMC Impact Manager instances. The BMC II Web Services Server checks the subscription manager for subscriber clients. The Web server determines the type of subscriber (polling or callback) based on the format of the subscription request. If the request contains a callback URL, then the subscription is for a callback client.

The server invokes an internal send() API call that the event dispatcher has exposed in behalf of the callback client.

The event dispatcher determines the callback URL of the event listener server from the client context. It then invokes one of the dispatch operations to send one or more events to the event listener server. The client manages the events based on the event handler logic that you have implemented.

Namespaces

The EventListener.wsdl declares the following namespace URIs.

Table 31 Namespaces: EventListener.wsdl

Type/Prefix Namespace

target http://blueprint.bmc.com/EventListener

default http://schemas.xmlsoap.org/wsdl/

xsd http://www.w3.org/2001/XMLSchema

event http://blueprint.bmc.com/Event

btypes http://blueprint.bmc.com/BasicTypes

soap http://schemas.xmlsoap.org/wsdl/soap/

wsdl http://schemas.xmlsoap.org/wsdl/


Data types

Data types

In the EventListener.wsdl, the data types enclose the schema definitions and the imported schema definition file Event.xsd.

The Event.xsd file defines the data types Event and ArrayOf_Event in its schema definition.

Messages

The EventListener.wsdl contains two asynchronous one-way messages: Dispatch_Request and DispatchList_Request. The Dispatch_Request carries a single event; the DispatchList_Request carries one or more events (an array of events).

Each request message has a corresponding HTTP-generated response that acknowledges the receipt of the request.

Dispatch_Request

The event dispatcher sends the Dispatch_Request message to the event listener to communicate a single event.

<wsdl:types><xsd:schema><xsd:import namespace=”http://blueprint.bmc.com/Event” schemaLocation=”Event.xsd”/></xsd:schema></wsdl:types>

<wsdl:message name=”Dispatch_Request”><wsdl:part name=”Event” element=”event:Event_element”/></wsdl:message>

Table 32 Message Parts: Dispatch_Request

Name Element/Type Description

Event event:Event_element complex type that specifies the name of a single event element which the event dispatcher sends as a request to the listener server. The event type extends the complex type ArrayOf_NameValue.


Operations

Dispatch_Response

The Dispatch_Response message is an acknowledgement and does not carry any content.

DispatchList_Request

The event dispatcher sends the DispatchList_Request message to the listener server to communicate one or more events (an array of events).

DispatchList_Response

The DispatchList_Response is an acknowledgement and carries no content.

Operations

dispatch

The event dispatcher on the web services server invokes the dispatch operation to send an event to a specified event listener on a specified client.

<wsdl:message name=”Dispatch_Response”/>

<wsdl:message name=”DispatchList_Request”><wsdl:part name=”ArrayofEvent_element” element=”event:EventArray_element”/></wsdl:message>

Table 33 Message Parts: DispatchList_Request

Name Element/Type Description

ArrayOfEvent_element event:EventArray_element complex type that specifies the name of one or more events that the event dispatcher sends to the listener server

<wsdl:message name=”DispatchList_Response”/>

<wsdl:operation name=”dispatch” parameterOrder=”Event”>wsdl:input message=”tns:Dispatch_Request”/></wsdl:operation>


Operations

Message

Parameter

dispatchList

The event dispatcher invokes the dispatchList operation to send one or more events to the specified event listener residing on the specified client.

Message

Name Type Description

tns:Dispatch_Request One way message sent by the event dispatcher to a specified listener server residing on a specified client. The message contains an event type to which the client has subscribed. The event dispatcher does not expect a response.

Name Direction Element Name Description

Event Out Event_element a complex type that extends the ArrayOf_NameValue type. It contains a single event.

NOTE While the dispatchList operation is exposed in the current implementation, the event dispatcher does not invoke the call.

<wsdl:operation name=”dispatchList” parameterOrder=“ArrayOfEvent_element”>wsdl:input message=”tns:DispatchList_Request”/></wsdl:operation>

Name Type Description

tns:DispatchList_Request One way message sent by the event dispatcher to a specified listener server residing on a specified client. The message contains one or more events to which the client has subscribed. The event dispatcher does not expect a response.


Bindings

Parameter

Bindings

The Event Listener binding is available through the SOAP message format. The SOAP messages are transmitted over the wire through the HTTP transport protocol. The style of the SOAP messages conforms to the conventions of XML documents. The EventListener.wsdl uses the document style for its SOAP bindings.

The following syntax describes how the Event Listener binding to the SOAP protocol is made available for transmission:

The message requests and responses are represented in literal formats. (The message requests are one-way messages, and the responses are acknowledgements only.)

When transmitted, the data are formatted based on the schema definitions referenced in the WSDL document. Encoding rules are not applied to the data. No fault messages are generated.

The soap:operation elements are depicted on page 170.

dispatch

Name Direction Element Name Description

ArrayOfEvent_element Out event:EventArray_element

complex type that specifies the name of one or more events that the event dispatcher sends to the listener server

<wsdl:binding name=”EventListener” type=”tns:EventListener”><soap: binding transport=”http://schemas.xmlsoap.org/soap/http” style=”document”/>

<wsdl:operation name=”dispatch”><soap:operation soapAction=”http://systinet.com/wsdl/EventListener#dispatch#KExOYW11VmFsdWVQYW1yczspVg==”style=”document”/><wsdl:input><soap:body use=”literal”/></wsdl:input><wsdl:output><soap:body use=”literal”/></wsdl:output></wsdl:operation>


Service

dispatch list

Service

The service element of the EventListener.wsdl is declared in the following figure:

When configuring the event listener server, you can specify the value of its soap:address location element on the web service client.

In the WASP Server for C++ toolkit implementation, the event listener server reads this value at runtime based on the values contained in the listenercfg.xml file, specifically the port number value. So if the listenercfg.xml file has its port attribute defined as 7070, then the EventListener.wsdl reveals the location as “7070”.

In other web services toolkit implementations, the toolkit’s specific startup process for its event listener server substitutes a corresponding value for the soap:address location element.

Message Part Use Schema Definition

Input literal tns:Dispatch_Request

Output literal none

<wsdl:operation name=”dispatchList”><soap:operation soapAction=”http://systinet.com/wsdl/EventListener#dispatchList#KFtMTmFtZvZhbHV1UGFpcnM7KVY==”style=”document”/><wsdl:input><soap:body use=”literal”/></wsdl:input><wsdl:output><soap:body use=”literal”/></wsdl:output></wsdl:operation>

Message Part Use Schema Definition

Input literal tns:DispatchList_Request

Output literal none

<wsdl:service name=”EventListener”><wsdl:port name=”EventListener” binding=”tns:EventListener”><soap:address location:”urn:unknown-location-uri”/></wsdl:port></wsdl:service>


Listenercfg.xml file

Listenercfg.xml fileThe default declaration of the listenercfg.xml file is shown below in the following figures. Note that the default client port number is 7070.

WARNING Do not modify the EventListener.wsdl or any of the schema definition files found in the same directory. Other toolkits generate WSDL files. When building the service, specify the EventListener.wsdl, not other generated WSDL files. Your code will not compile properly if you do not follow these directives.

<waspc-config xmlns:wasp="urn:WaspServer" xmlns:cppa=”urn:CppAdaptor” xmlns:sep=”urn:ServiceEndpoint” xmlns:svci=”urn:ServiceInstanceRepository”xmlns:trans=”urn:TransportRepository”><wasp:import ref="conf/serverbase.xml"/><trans:transport trans:class=”WASP_HTTPTransportServer”trans:scheme=”server-http” xmlns:hts=”urn:HTTPTransportServer”hts:reuseCount=”15”hts:reuseTimeout=”30”hts:rwTimeout=”30”hts:acceptTimeout=”5”hts:chunked=”true”hts:port=”7070”hts:hostname=”$AUTO$”hts:dispatcher=”DefaultDispatcher”hts:singleThread=”0”hts:maxSpareThreads=”-1”hts:maxThreads=”-1” /><sep:serviceEndpoint sep:dispatcherRef=”DefaultDispatcher” sep:adaptorRef=”DefaultCppAdaptor” cppa:wsdl=”EventListener.wsdl” sep:url=”/EventListener”><cppa:instance cppa ref=”EventListener”/></sep:serviceEndpoint><svci:serviceInstance svci:name”EventListener” svci:class=”EventListenerServer”/><waspc-config>


Adding SSL parameters to the listenercfg.xml file


In the %installDirectory%\samples or $installDirectory/samples subdirectory, you can find a listenercfg.security.xml file. It contains the required elements and attributes that you must incorporate within the listenercfg.xml file to enable security.

You can copy the text of the listenercfg.security.xml file into the listenercfg.xml to enable an SSL secure client. The sample client matches trusted certificates with those contained in the certs subdirectory of the server, as indicated by the trustedDir element: <ssl:trustedDir>openssl/certs</ssl:trustedDir>.

The following figure shows the listenercfg.xml file with SSL parameters, highlighted in bold, incorporated into it.

NOTE The library file WASPOpenSSL.dll, referenced in this example, is for a Windows implementation. The library file libwasp_openssl.so is for Linux and Solaris implementations.

<waspc-config xmlns:wasp="urn:WaspServer" xmlns:cppa=”urn:CppAdaptor” xmlns:sep=”urn:ServiceEndpoint” xmlns:svci=”urn:ServiceInstanceRepository”xmlns:trans=”urn:TransportRepository”><wasp:import ref="conf/serverbase.xml"/><trans:transport trans:class=”WASP_HTTPTransportServer”trans:scheme=”server-http” xmlns:hts=”urn:HTTPTransportServer”hts:reuseCount=”15”hts:reuseTimeout=”30”hts:rwTimeout=”30”hts:acceptTimeout=”5”hts:chunked=”true”hts:port=”7070”hts:hostname=”$AUTO$”hts:dispatcher=”DefaultDispatcher”hts:singleThread=”0”hts:maxSpareThreads=”-1”hts:maxThreads=”-1” /><wasp:externalLibrary><wasp:path>WASPOpenSSL.dll</wasp:path></wasp:externalLibrary><trans:transport xmlns:htc=”urn:HTTPTransportClient” xmlns:htcssl=”urn:HTTPSOpenSSLTransportClient”trans:class=”WASP_HTTPSOpenSSLTransportClient”trans:scheme=”https”htc:retryCount=”10”htc:retryTime=”100”htc:reuseCount=”100”



Restart the client after you save the file.

htc:reuseTimeout=”30”htc:rwTimeout=”30”htc:connTimeout=”30”htc:http10=”false”htc:chunked=”false”><htcssl:context htcssl:class=”WASP_OpenSSLContextFactoryImpl”xmlns:ssl=”urn:OpenSSLContextFactory” ssl:verify=”yes”><ssl:trustedDir>..openssl/certs</ssl:trustedDir></htcssl:context></trans:transport><sep:serviceEndpoint sep:dispatcherRef=”DefaultDispatcher” sep:adaptorRef=”DefaultCppAdaptor” cppa:wsdl=”EventListener.wsdl” sep:url=”/EventListener”><cppa:instance cppa ref=”EventListener”/></sep:serviceEndpoint><svci:serviceInstance svci:name”EventListener” svci:class=”EventListenerServer”/><waspc-config>


A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Index

Symbols$ClassName function 114$doselector function, description 115$Format function 116$function_name function 114$GmtTime function 116$HostName function 114$LD_LIBRARY_PATH 32$LocalTime function 116$MCELL_HOME 39$PATH 32$SHLIB_PATH 32$slotMissing function 116$slotPresent function 115$TimeT function 116%C substitution parameter 136, 138%H substitution parameter 136, 138%L substitution parameter 136, 138%MCELL_HOME% 39%N path value variable 136, 138%P substitution parameter 136, 138%PATH% 31%s 116%T substitution parameter 136, 138

Aadministration

BMC Impact Integration Web Services Server 64, 106editing iiws.conf file 136editing iiws.selector 120editing iiws.trace file 138iiws.conf file 123iiws.selector file 106iiws.trace file 137starting BMC Impact Integration Web Services Server

59API (Application Program Interface)

Basic C 16audience

presumed knowledge 105roles 105

BBAROC (Basic Recorder of Objects in C)

malformed string 147missing END statement error 150

Basic C APIsinitialization error 154relation to Web services 16

BMC Developer Connectiondescription 19

BMC Impact Integration Web Servicesasynchronous 82client programming 74security 66

BMC Impact Integration Web Services Serveradminstration 106BMC Impact Integration Developer’s Kit 105callbacks 16components 15guaranteed event delivery 89imserv 60installation package 22mcell.dir 17OpenSSL 23queries 82receiving events 88required configuration tasks 38selector processing 107send request 82servercfg.xml 57SOAP messaging 17starting 59subscription requests 89Systinet WASP server 16updating parameters 57WASP library files 16

BMC Impact Managerinvalid name 153returning query error 155

BMC Performance Manager 54BMC Software, contacting 2bmcii_connect function, invalid cell name 153bmcii_getFirstDirectoryInfo function, error 152bmcii_getNextDirectoryInfo function, error 152bmcii_init function, error calling 150

Index 175


bmcii_initQueryConnect function, failure 155bmcii_loadMapSet function, file name error 151bmcii_loadSelectorSet function, failure 108bmcii_loadSelectorSet function, file name error 151bmcii_queryInitConnect function, invalid cell name 153bmcii_serverSetup function, invalid cell name 153bmcii_setMessageType function, specifying unknown

message type 156bmcii_setMetaSlot function, specifying unknown message

type 156bmcii_startServer function, error 161bmcii_stopServer function, error 161buffering

bmciiws_connect 82buffer, maximum size 126corrupt buffer error 150full buffer error 160MessageBufferReconnectInterval parameter 127MessageBufferSize parameter 126messages 160overflow 148, 149, 153reconnect interval 127

Ccache directory 30callback URL 91, 97callbacks

description 95cells

invalid name error 153ChangeDate parameter, message selector set header 111class definition queries 83classes

missing class name 147classes, specifying in translation maps 114client code samples 30client context ID 90client proxy code

generating 75list of operations 78programming language 75sample source and header files 76toolkit implementation 81

ClientSourceIP configuration parameter 125ClientSourcePort configuration parameter 125compilers 23configuration

.iiws.conf file 123

.load file 49

.mrl file 49BMC Impact Integration Web Services Server 38defining propagate rules 49http-server.xml 56MaxResponseEventListSize parameter 57mcell.dir 38

176 BMC Impact Integration Developer’s Kit Web Serv

security 66servercfg.xml 57updating server parameters 57

configuration file (.conf file)missing configuration information 151

configuration file (iiws.conf file)editing 123, 136overview 123substitution parameters 136

configuration filesparameters 124substitution parameters 138TraceConfigFileName parameter 131

configuringconfiguration file parameters 124iiws.conf 124Trace parameter 131TraceConfigFileName parameter 131TraceDefaultFileName parameter 131TraceFileAppend parameter 132TraceFileHistory parameter 132TraceFileSize parameter 132TraceSrc parameter 131

connecting, maximum reconnect interval 127connection handles, invalid 159ConnectionPortRange configuration parameter 126ConnectionPortRange parameter, error 159ConnectionPortReuse configuration parameter 126connections

bmciiws_connect 82broken connect error 151broken query connection 155destination availability error 160error accepting 161error requesting 161failure due to META_FAIL_IF_UNCONNECTED

metaslot 160invalid handle 159TCP/IP not available 161

ConnectionSetupTimeOut configuration parameter 125custom event listener libraries

dispatch operations 165programming language 165

customer support 3

Ddata types, in EventListener.wsdl 167Description parameter

in message selector header 112in message selector set header 111

dispatchbindings 170operations 168, 169

Dispatch_Request, message 167dispatchList, operation 169

ices Server Developer Guide


DispatchList_Request, message 168dispatchList_Request, message 169

Eembedding message selectors 108Enable parameter

in message selector header 112in message selector set header 111

encryptionEncryption parameter 126

Encryption configuration parameter 126encryption, invalid key error 159environment variables

Microsoft Windows installation 31UNIX installation 32

errors (C API)$doselector loop 155bad function call order 152bad message 148bad message type 148bad or missing map header 148bad or missing selector header 149bad slot name 150bad slot value 150Basic C API errors 144broken connection 151broken query connection 155cannot find mcell.dir file 151corrupt buffer 150disabled map set 153failed query connection attempt 155functions called after termination 155initializing the Basic C APIs 154insufficient memory 147invalid cell name 153invalid function parameter 149invalid internal event 149invalid map set parameters 152invalid mutex 148invalid or corrupt message 153invalid or incorrect host or port 147invalid selector set parameters 152lists of C API error codes 144malformed BAROC string 147map disabled 153map set file name 151map set file syntax 148map set loop 153memory allocation 154message modification 154missing BAROC END statement 150missing class name 147missing event or data handle 154missing mc_ueid or mc_udid ID 154missing or bad map name 148

missing or bad selector name 149missing placeholder 155parameter missing from function 147receive thread cannot start 154response parsing 149returning for queries 155selector set file name 151selector set file syntax 149selector set loop 155starting receive thread 151success message 155supported library 156timeout expiration 155unable to create event message 147unable to create object 151unable to open file 151unknown message type 156unsupported query 152unsupported structure 152UseLocks setting 154

errors (core)bmcii_startServer function 161bmcii_stopServer function 161communications errors 157connecting 160connection failure 158ConnectionPortRange parameter 159full buffer 160inbound communication module 158invalid encryption key 159invalid host name 158invalid IP address 158invalid or misspelled paths 159memory allocation 160message destination not available 160META_FAIL_IF_UNCONNECTED metaslot 160no error 161outbound communication module 158port access 160port range 159starting server mode 161stopping server mode 161TCP/IP not available 161timeout expiration 161trace configuration file 162

errors (Web services)closing connection 142connecting to cell 141creating message type 142creating messages 142failed to get query result 144getting selector names 142incorrect date in query 143invalid client context ID 142invalid query handle 143invalid start index 143query call 142

Index 177


query handle cleanup 143receiving empty event 142sending message to cell 142setting slot name 142setting slot name-value 142unknown query result 143

event classeserror 149unable to create message 147

event dispatcher 165custom 166dispatch operations 166EventListener.wsdl 166messages 167operations 168

event handle, missing 154event listener 96event listener libraries

custom 165event dispatcher 96event listener server 96, 97

event listener servercustomizing 166EventListener.wsdl 166service element 171

event propagationdefining rules in KB 45example rule 48Propagate policy 43state change events 45subscription requests 89WSCELL event listener 43, 45, 89

EventListener.wsdldispatch operations 165

executable filesimserv 60

FFailOnMissingSlot message selector header parameter 112failure

matching 112selection 112

formatting%, using in message selectors 116error in map set file 148error in selector set file 149message selectors and message selector sets 110missing BAROC END statement error 150

FormatVersion parameter, in message selector set header 111

functions$ClassName 114$doselector 115$Format 116$function_name 114


$GmtTime 116$HostName 114$LocalTime 116$slotMissing 116$slotPresent 115$TimeT 116in message selectors 113slot.slotname 114

Gguaranteed event delivery 89

Hhigh availability cells

configuration 51configuration with BMC Performance Manager 54guidelines 53implementation scenarios 52

host name, invalid or incorrect 147host names, specifying in message selectors 114http-server.xml 56

Iiiws.conf file, editing 136iiws.conf, configuration parameters 124iiws.selector file 120iiws.trace file 138

modifying 139restarting the server 139

Impact Integration C APIsrelation to Web services 105

ImpactManager.wsdlclient proxy code 75introduced 16source-code generator 75

installationAIX runtime libraries 26compatible cells 22compatible OpenSSL 23compatible toolkits 23directory contents 29environment variables 31Java Runtime Environment 25Linux, Solaris, HP-UX, AIX (console) 29Linux, Solaris, HP-UX, AIX (X Window System) 27netstat command 25port verification 25prerequisite checks 25supported operating systems 22tested compilers 23uninstalling 34



Llibraries

Basic C API runtime 16custom event listener 165wrong map or selector set support 156

listenercfg.xml file 173locale directory 30localization, LocaleConfigFile 135loops

$doselector error 155error in map set 153error in selector set 155

Mmap header, bad or missing header 148map set files

name error 151syntax error 148

map setsdisabled 153invalid parameters 152library support error 156loop error 153

mapsdisabled 153missing or bad name 148syntax error 148

MaxResponseEventListSize parameter 57mc_udid ID, missing 154mc_ueid ID, missing 154mcell.dir

adding WSCELL event listener 42configuration 38description 17, 139directory location 30editing 139location 18WSCELL event listener 18

mcell.dir file 151memory

allocation error 160failure allocating 154leaks 160

message buffer capacity 126message propagation

MessageBufferKeepSent parameter 126MessageBufferKeepWait parameter 126MessageBufferReconnectInterval parameter 127MessageBufferResendCount parameter 127MessageBufferSize parameter 126parameters list 126

message selectorscharacteristics 107content 113

embedding 115embedding with $doselector 108file, characteristics 107formatting 110header requirement 112header sample 113message selector set header 110name 112operators 117parameters, header 112parameters, set header 111set header requirement 110set header sample 111sets, description 108sets, formatting 110sets, headers 110sets, naming 108slots, missing 112syntax rules 107time, specifying settings 116

message typeerror 148unkown 156

MessageBufferKeepSent 126MessageBufferKeepSent configuration parameter 126MessageBufferKeepWait configuration parameter 126MessageBufferReconnectInterval configuration parameter

description 127MessageBufferResendCount configuration parameter 127MessageBufferSize configuration parameter

description 126MessageBufferSize parameter, modifying 160messages

bad message type 148buffering 160corrupt buffer error 150corruption or null parameter 148error when modifying 154full buffer 160invalid connection handle 159invalid or corrupted 153missing class name 147unable to create 147unknown message type 156

mutex error 148

Nnamespaces

declared in EventListener.wsdl 166netstat command 25non-reliable subscription 91

Index 179


OOpenSSL

supported version 23operations

client proxy code 78sequence for polling client 92sequence for sending events 82

Pparameters

ChangeDate 111ClientSourceIP 125ClientSourcePort 125configuration file 124ConnectionPortRange 126ConnectionPortReuse 126ConnectionSetupTimeOut 125Description 111DropAcks 130DumpIncoming 133Enable 111, 112EnableRecvPersist 129Encryption 126FailOnMissingSlot 112FormatVersion 111KeepRecvPersisted 129LocaleConfigFile 135MaxSleep 134message selector set header list 111MessageBufferKeepWait 126MessageBufferReconnectInterval 127MessageBufferResendCount 127MessageBufferSize 126MinClientSleep 133MinSleep 134PersistencyCleanupGarbageThreshold 128PersistencyCleanupSizeThreshold 128PersistencyDisconnectRemoveMessages 128PersistencyEnabled 128PersistencyFileName 128PersistencyLevel 128ReceiveBufferDir 129SelectorHeader 112SelectorSetName 111ServerAllInterfaces 135ServerDirectoryName 124substitution parameters 138TraceConfigFileName 131TraceDefaultFileName 131TraceFileAppend 132TraceFileHistory 132TraceFileSize 132TraceSrc 131UniqueIdFile 135


UseMemWatch 133Version 111

parsing error 149paths

environment variables 31, 32invalid or misspelled 159

PersistencyCleanupGarbageThreshold configuration parameter 128

PersistencyCleanupSizeThreshold configuration parameter 128

PersistencyDisconnectRemoveMessages configuration parameter 128

PersistencyEnabled configuration parameter 128PersistencyFileName configuration parameters 128PersistencyLevel configuration parameter

description 128polling call

bmciiws_getEvents 92polling interface 94

callback URL 90, 97event queue 92list of operations 92MaxResponseEventListSize parameter 57subscription requests 90, 96unsubscribing, effects of 93

portsBMC Impact Integration Web Services Server 55changing 56, 57invalid or incorrect 147invalid range 159port range error 159privilege error 160use by other applications 160Web services server 82WSCELL event listener 18, 55

printf function 116product support 3Propagate policy 43propagate. See event propagationpublish-subscribe interface

callback URL 91, 97callbacks 95client 166event dispatcher 96event listener server 96subscription requests 95, 96

Qqueries

broken connection 155class definition 83description 82failed connection 155processing 83returning replies 154



service model 83unsupported 152

Rreceive thread

cannot start 154error 151

resourcesmemory allocation error 160memory allocation failure 154memory insufficient error 147

Ssecurity

certificate generation 66general guidelines 66responsibility of client developer 66SSL 65Web services server support 65

selector set filesloop error 155name error 151syntax error 149

selector setsinvalid parameters 152library support error 156loop error 155

SelectorName message selector header parameter 112selectors

iiws.selector file 120in subscription requests 90, 107missing or bad name 149overview 106syntax error 149with client context ID 97

selectorset_name.message selector file 108SelectorSetName message selector set header parameter

111send request processing 82server. See BMC Impact Integration Web Services ServerServerAllInterfaces configuration parameter 135servercfg.xml

file parameters 57updating 57

servercfg.xml filesecurity parameters 70

ServerDirectoryName configuration parameter 124service model queries 83slot.slotname function 114slots

bad name error 150bad slot value error 150bad value error 150

do not exist 154empty string for name 150in message selectors 113missing from message selectors 112null 150selecting, by value 114

SOAP (Simple Object Access Protocol) 15SOAP messaging 17sockets, initialization error 150source-code generator

client proxy code 75compiling ImpactManager.wsdl 75

state change events 45strftime 116strings

empty value in slot 150malformed BAROC 147

structures, unsupported 152subscription requests

bmciiws_subscribe 96callback URL 90, 97multiple 96overwriting by server 97, 98parameters 90polling interface 90, 96publish-subscribe interface 96selectors 90uniqueness 97

substitution parameters 138support, customer 3syntax

bad or missing map header 148bad or missing selector header 149bad slot name error 150bad slot value error 150error in selector set file 149map set file error 148selector set file error 149

Systinet WASP server 16

TTCP/IP, invalid IP address error 158technical support 3time, using in message selectors 116time_t, in message selector files 116timeout, expiration error 155, 161toolkits

Axis 23client proxy code 81OpenSSL 23stub generation 17Visual C#.NET 2003 23WASP Server for C++ 23

trace fileerror 162

Index 181


Trace parameter 131TraceConfigFileName configuration parameter 131TraceConfigFileName parameter 131TraceDefaultFileName configuration parameter 131TraceFileAppend configuration parameter 132TraceFileHistory configuration parameter 132TraceFileSize configuration parameter 132TraceSrc configuration parameter 131TraceSrc parameter 131tracing

parameters in BMC II C APIs configuration files 131TraceConfigFileName parameter 131TraceDefaultFileName parameter 131TraceFileAppend parameter 132TraceFileHistory parameter 132TraceFileSize parameter 132TraceSrc parameter 131

translationclass names, specifying 114host names, specifying 114

transport mechanism 15

Uuninstalling BMC Impact Integration Web Services Server

34uniqueID.dat 135UniqueIdFile configuration parameter 135UseLocks parameter, setting error 154using substitution parameters 138

VVersion, message selector set header parameter 111

WWasp library files 16Web service client

client code samples 30compatible toolkits 17interface types 89polling interface 94queries 83

Web services clientcallbacks 95client proxy code 78event listener server 96multiple subscription requests 96planning considerations 74polling interface 92programming language 74sending events and data 81summary of steps 75types 74


updating listenercfg.xml file with security 173Web services server

event dispatcher 96invalid name error 153overwriting subscription requests 97, 98security implementation 65

Web services. See BMC Impact Integration Web ServicesWSCELL event listener

adding to mcell.dir 42description 18event propagation 43, 45port 18

WSDL (Web Services Description Language)defined 15EventListener.wsdl 165ImpactManager.wsdl 16



Glossary

Note: The definitions of terms common to web services are derived from the W3C working draft Web Services Glossary at http://www.w3.org/TR/ws-gloss/. Copyright © 2004 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply. The definition of terms common to event distribution systems are derived from the online computing dictionaries at WhatIs.com and Foldoc.org.

$MCELL_HOMEThe UNIX platform environment variable that defines the home directory in which BMC Impact Manager product files reside. (It is also designated as installDirectory/.. .) Use this environment variable to find all product executables and configuration files. See also mcell.dir file and WSCELL.

%MCELL_ HOME%The Windows platform environment variable that defines the home directory in which BMC Impact Manager product files reside. (It is also designated as drive:\installDirectory.) Use this environment variable to find all product executables and configuration files. See also mcell.dir file and WSCELL.

.load fileA file that specifies the order in which a directory’s files are to be loaded and read by a BMC Impact Manager instance.

.map file See adapter map file.

.mrl fileA file that contains rule and collector definitions written in the Master Rule Language (MRL). Event and service management processing rules and collectors are stored in .mrl files and in compiled .wic files.

/etc/mcell On UNIX platforms, the directory that contains the setup_env.sh and setup_env.csh scripts, which set the environment variables used by the product software.

Glossary 183

http://www.w3.org/TR/ws-gloss


AAcknowledge

The event operation action that acknowledges the existence of an event. See also local action.

Acknowledged statusThe event status that results from an Acknowledge event operation action; it means that an operator has acknowledged the event's existence.

action1. Generally, a procedure that is invoked to produce a specific result. It can be a script or a call to an executable that is invoked automatically in response to an event, or it can be a manual intervention. Actions can be scheduled or immediately invoked locally or remotely.

2. In BMC Impact Manager, an executable that can be run by a cell. Actions are called in an Execute rule. Users can request the execution of actions in the BMC Impact Explorer. See also local action.

adapterA background process that audits data from various sources, evaluates it for specific conditions, and creates the corresponding events. Adapters also transform event data into the format understood by BMC Impact Manager.

adapter instanceAn adapter that is defined in the adapter configuration file. The definition is given a name and specifies an adapter type, such as a log file adapter.

adapter map fileA text file that defines the translation of a message between one event format and another. It is also known as a .map file.

administratorThe person responsible for administrative tasks within the product.

aliasSee service component alias.

APISee Application Program Interface (API).

Application Program Interface (API)A set of externalized functions that allow interaction with an application.

assetAn object instance in the BMC Atrium Configuration Management Database (BMC Atrium CMDB). There are two types of assets in the BMC Atrium CMDB: non-service components, such



as desks and other non-IT physical assets, and service components which are components that participate in the delivery of enterprise services.

asynchronous web servicesA message exchange pattern in which the sender and receive do not have to communicate at the same time in a precise sequence. For example, a request message can be stored and delivered at a later time. Neither sender nor receiver depends on the immediate completion of the request. Contrast with synchronous web services.

attributeA characteristic or property of an object, such as a common data model service model component class. An attribute may contain a value.

BBAROC Language

Basic Recorder of Objects in C. A structured language used to create and modify class definitions. A class definition is similar to a structure in the C programming language. The elements in a structure are called slots.

bindingsIn Web Services Description Language, the method that defines how SOAP messages are exchanged through an underlying protocol. They are a formal set of rules for carrying a SOAP message over a transport mechanism. In BMC II Web Services, the messages are communicated via SOAP over HTTP. See also SOAP encoding.

BMC Atrium CMDB Common Data Model (BMC Atrium CMDB CDM)An extensible schema that provides a unified representation of configuration items and their relationships to each other. It is used to store asset data (such as hardware information, service management information, and people information) and to provide a mechanism for linking that information to provide a complete view of how all assets are connected and can affect each other.

BMC Atrium CMDB Reconciliation EngineThe BMC Atrium CMDB application used to merge data from multiple sources, such as topology or configuration discovery, into a consistent dataset.

BMC Atrium Configuration Management Database (BMC Atrium CMDB)The database application that is the common datastore for asset, configuration management, and service model data in BMC Business Service Management products. It enables BMC products to share IT management and monitoring data and perform service management.

BMC Desktop Status Indicator (BMC DSI)An icon that appears in the desktop system tray of a computer to show the current status of an object being monitored by BMC Impact Portal. To view the status page of the monitored object, you double-click the icon.

Glossary 185


BMC Event Manager (BMC EM)A real-time event management product license package that provides event management, including event collection, correlation, enrichment, and integration. It enables IT operations staff to focus the proper resources on resolving the most critical events.

BMC II C APIsA collection of programming functions written in the C programming language that are designed to build applications which integrate with the BMC Impact Manager product by sharing events and data. The BMC II Web Services package includes the runtime library files of the BMC II C APIs.

BMC IISee BMC Impact Integration (BMC II) product.

BMC IMSee BMC Impact Manager (BMC IM).

BMC Impact Explorer (BMC IX)A console with which you can connect to any number of instances of BMC Impact Managers, examine the events stored in them, and perform event and service management activities.

BMC Impact Integration (BMC II) productAn interface that enables the synchronized, bidirectional flow of events and data between a BMC Impact Manager instance or instances and another BMC Software product or a specific third-party product.

BMC Impact Integration (BMC II) Web ServicesA web services client developer package that includes a built-in web service, a server, and a sample client. It enables web service client developers to build a client that can connect to and exchange events with the BMC Impact Manager network.

BMC Impact Manager (BMC IM)The BMC Impact product that provides automated event and service-impact management. It runs as a service on supported Windows platforms and as a daemon on UNIX platforms, and can be distributed throughout a networked enterprise and connected in various topologies to support IT goals.

BMC Impact Manager instanceAn installation of the BMC Impact Manager product on a host computer. Compare with cell.

BMC Impact Publishing ServerThe BMC Impact Portal service or daemon that obtains the service model from the BMC Atrium CMDB and publishes (distributes) it to the designated service impact management cell or cells.

BMC Impact PortalThe BMC Portal console module that you use to monitor the status of business services and their components. See also console module.



BMC Impact ReportingThe BMC Impact Solutions component that you use to create and view long-term reports.

BMC PortalA BMC licensed product that consists of the BMC Portal Server (infrastructure) and console modules, each of which deliver specific Business Service Management (BSM) functionality. The BMC Impact Portal is an example of a console module.

BMC Reporting FoundationThe base component on which BMC Software reporting systems and solutions are built.

BMC Service Impact Manager (BMC SIM)A real-time service impact management product license package that provides technologies for both service impact and event management (SIEM). BMC SIM identifies related applications and the underlying systems and databases of any software or infrastructure component and ties systems-level monitoring to the supported business services, enabling IT personnel to respond quickly to problems that threaten the delivery of business services.

Business Service Management (BSM)A dynamic method for connecting key business services to the IT systems that manage them. BSM enables users to understand and predict how technology changes will affect their business, and how changes in the business affect the IT infrastructure.

Ccallback interface

An abstract connection between the BMC II Web Services client and the event listener server component that resides on it. The callback interface enables the event listener to execute code on the client. The client registers callbacks with the event listener. When the event listener receives an event, it dispatches it to a callback.

Callbacks are implemented for BMC II Web Services clients that use the publish-subscribe model, not polling, to retrieve events from the BMC Impact Manager product network. See also push interface. Contrast with polling interface.

callback URLThe address or uniform resource locator of the event listener server that resides on the BMC II Web Services client. At runtime, the event listener server reads the callback URL from a configuration file that is specific to your web services toolkit.

cellThe event processing engine that collects, processes, and stores events within a BMC Impact Manager instance. Each cell uses the information in the associated Knowledge Base to identify the type of events to accept and how to process and distribute them. See also mcell.dir file.

Glossary 187


class1. A data storage element. In database terms, it relates to a table in a database or a form in the Remedy AR System.

2. In BMC Impact Manager, a BAROC-language data structure that defines a type of object used in BMC Impact Manager. A BAROC class is made up of data fields, called slots, that define its properties.

client context IDA string descriptor that identifies the name of the web services client. BMC II Web Services Server uses the client context ID with the selector name to determine which client receives events.

command line interface (CLI)A user interface in which you issue commands one at a time on a command line for automation or immediate execution. In BMC Impact Manager, you use the CLI in conjunction with a graphical user interface (GUI) to operate the product.

componentA logical or physical asset that is stored in the BMC Atrium CMDB. There are two types of assets in the BMC Atrium CMDB: non-service components, such as desks and other non-IT physical assets, and service components, which are components that participate in the delivery of business services.

component instanceA named component that represents an actual IT resource.

conditionA prerequisite that must exist or a qualification that must be met for selection or processing to take place, such as individual slot-value tests.

console moduleA product that plugs into the BMC Portal.

consumerAn entity that makes use of (“consumes”) a web service or, in an event distribution system, a programming object that subscribes to specific events. Contrast with provider.

Ddata class

A BAROC class that is a child of the base event class, DATA, and that defines a type of data.

datastoreA central place in which an aggregation of data is kept and maintained in an organized way.



data typeA representation of an abstract concept such as integer, time, date, and so forth. A data type consists of a literal representation, valid values, and defining characteristics. In XML schema, it can be built-in or user-derived. The types element of the Web Services Description Language identifies the data types available to the web service.

draft service modelA working version of the service model that contains both published and unpublished elements.

duplicate eventA subsequent occurrence of an event that has already been received, such as the second or later notification that a component is down. An event that has matching values for all the slots defined with the dup_detect=yes facet in the event class definition.You can use Regulate rules to detect and count duplicate events. See also facet.

dynamic collectorA special type of collector that, in response to events, can add or remove event collectors from the cell during runtime.

dynamic dataContextual reference data that is stored in a table in the repository (mc.db) and that can be updated during runtime. Administrators can use and manipulate dynamic data in the BMC Impact Manager Administration View.

EEnableTrace parameter

A configurable parameter in the BMC II Web Services Server that, when set to true, activates the server logging facility.

encryption keyThe seed encryption key. If the destination BMC Impact Manager or BMC Impact Integration product has a key value, all clients must encrypt their communications using the same key value.

endpointA specific location (uniform resource identifier) for accessing a web service using a specific protocol and data format. See also service.

enrichment1. The process of adding to or modifying the original event data to enhance it for problem management, service management, correlation, automation, notification, or reporting functions.

2. A type of policy.

Glossary 189


eventA structured message passed to and from cells in a BMC Impact environment. It is an instance of an event class.

event class1. A BAROC class that is a child of the base event class, CORE_EVENT, and that defines a type of event.

2. A category of events that you can create as a child of the base event class, CORE_EVENT, according to how you want the events to be handled by an event manager and what actions you want to be taken when the event occurs. Event classes may be inherited from parent objects, depending on the specific product. Event classes are inherited from parent objects in BMC Impact Manager.

event collectorAn event grouping whose content is defined by its collector rule. Event collectors are displayed in the BMC Impact Explorer and are defined in the BMC Impact Manager Knowledge Base. See also event collector rule.

event collector ruleA type of rule in the Knowledge Base that defines how events from a cell are organized and presented in the BMC Impact Explorer. Collector rules are written in Master Rule Language (MRL).

Event Condition Formula (ECF)The section of an MRL rule definition that specifies the conditions that an incoming event must meet to trigger evaluation of the rule during processing. For example: APP_MISSING_PROCESSES where [hostname: == ‘red1’,sub_origin: contains ‘System’] is an ECF. See Master Rule Language (MRL).

event dispatcherA software mechanism that resides on the BMC II Web Services Server. Functioning like a client, it dispatches events in the form of one-way request messages to the event listener server that resides on the BMC II Web Services client. It is used in publish-subscribe client implementations. See also event listener utility, event listener server, and event notification service.

event listener utilityA short-hand reference that describes the main components of an event listener library: the event dispatcher and the event listener server. Refers to publish-subscribe client implementations. See also event dispatcher, event listener server, and event notification service.

event listener serverA software mechanism that resides on the BMC II Web Services client. The client registers callbacks on the event listener server. The server listens for events that are sent from the event dispatcher residing on the BMC II Web Services Server. When an event is received, the server dispatches it to a callback in the list of callbacks that it maintains. Used in publish-subscribe



client implementations. See also event dispatcher, event listener utility, and event notification service.

event managementThe collection and correlation of events across an enterprise to enable IT operations to focus the proper resources on the most critical events.

event management policyOne of several generic rule types that perform actions against events that meet selection criteria specified in an associated event selector. Unlike manually written rules, event policies are defined interactively using the Event Management Policy Editor in the BMC Impact Explorer.

event notification serviceA BMC Software implementation of the Systinet WASP Server for C++ Toolkit event listener libraries. It is built into the BMC II Web Services package. The event listener libraries handle asynchronous event publication and subscription, and they are used in web services publish-subscribe client implementations. To use the built-in event notification service, you must use the Systinet WASP Server for C++ Toolkit and write the client code in the C++ or Java programming language. See also event dispatcher, event listener utility, and event listener server.

event propagationThe act of forwarding events and maintaining their synchronization among multiple BMC Impact Manager instances (cells).

event selectorThe filtering mechanism associated with an event policy that selects the events against which the event policy performs actions. An event selector contains one or more event selection criteria. Event selectors are defined interactively by using the BMC Impact Explorer. An event policy can use one or more event selectors.

EventListener.wsdl fileThe Web Services Description Language file that describes the event dispatch service which you can access to build your custom event listener utility that is specific to your web services toolkit. See also Web Services Description Language (WSDL).

Execute ruleAn event-processing rule that performs actions when a slot value changes in its event repository. Execute rules are evaluated during the Execute phase of event processing. Often, the resulting actions are internal actions, but you can use the execute primitive in a rule to call an external executable.

Glossary 191


Ffacet

In the BMC Impact Manager product, a specific attribute of a class slot that either controls the values that the slot can have or controls aspects of a class instance’s processing.

In XML, a single defining aspect of a value for a data type. It is characterized as fundamental, which defines the data type, or constraining, which restricts the values of a data type. See also data type.

fault messageIn Web Services Description Language, a SOAP (Simple Object Access Protocol) message that contains fault information related to a set of SOAP communication messages. The fault message indicates the reason why the SOAP communication failed.

field See attribute.

Filter ruleAn event-processing rule that determines whether a specific type of event should be passed as it is, subjected to further processing, or discarded during the Filter phase.

functionCode that executes an operation in a cell and returns a value. A function can be used as an expression within a rule or a policy and in alias formulas.

Ggateway

An integration that receives connections and events from BMC Impact Manager instances. A gateway can use a custom message format or custom message content (different slots).

gateway.export fileA special file that controls the propagation and synchronization of events to a BMC Impact Manager Integration product. The file is in the installDirectory/etc/ directory on UNIX platforms and in the drive:\installDirectory\etc\ directory on supported Windows platforms.

Hheartbeat

1. A periodic message sent between communicating objects to inform each object that the other is still active and accessible.

2. In BMC Impact Manager, a dynamic data object sent by a cell to monitor other cells to verify that they remain active and accessible.



heartbeat intervalThe time between heartbeats; the period of the heartbeat.

Iimpact

An assessed measure of the effect that an incident, fault, or other change will or may have on business operations or service levels.

ImpactManager.wsdlThe Web Services Description Language file that describes BMC II Web Services and enables you to access its operations. See also Web Services Description Language (WSDL).

impact eventAn event whose status is used in computing the status of its associated service component. By default, the status of all events associated with a service component are used to compute its status. However, you can exclude events if you wish.

impact propagationThe effect of an impact to a providing service component (provider) on the service components that use its services (consumers) as defined by an impact relationship. See also impact relationship.

impact relationshipA relationship between two service components in a service infrastructure in which a consumer component depends on a provider component to deliver some needed resource to it. Changes in status of the provider affect (has an impact on) the status of the consumer component.

imservThe name of the executable that launches the BMC II Web Services Server. By default, it is located in the drive:\installDirectory\bin or installDirectory/bin directory.

instance1. A specific object with specific attributes or characteristics that distinguish it from other items (members) of its class or type.

2. In BMC Impact Manager, an object that has specific attribute values and that was created using a class definition.

integration productSee BMC Impact Integration (BMC II) product.

Kkb directory

The default directory in which a BMC Impact Manager Knowledge Base is located. The directory and basic product definitions are created during installation.

Glossary 193


key slotA slot whose value is compared during searches.

Knowledge Base (KB) A collection of information that forms the intelligence of a BMC Impact Manager instance and enables it to process events and perform service-impact-management activities. This information includes event class definitions, Service-Model component definitions, record definitions, interface definitions, collector definitions, data associations, and processing rules.

Lload file

See .load file.

local actionAn executable that you can run directly from the BMC Impact Manager. Local actions are written in XML and are stored in the OS-specific subdirectory of the bin directory of the BMC Impact Manager cell Knowledge Base.

Mmanifest.kb

A central locator file that specifies the locations of the directories that make up a Knowledge Base. The manifest.kb file is used by the compiler to load the Knowledge Base source files for compilation.

Master Rule Language (MRL) A compact, declarative language used to define rules and collectors for processing and organizing events. Uncompiled rule and collector source files have a .mrl file extension.

MaxEventQueueSize parameterA configurable parameter for the BMC II Web Services Server that determines the maximum number of events that the server will cache in memory. This value is defined for the server and is not dependent on the number of connected clients or subscription calls. It is defined in the servercfg.xml file and is implemented for client polling requests.

MaxResponseEventListSize parameterA configurable parameter for the BMC II Web Services Server that defines the maximum number of events that the server returns per polling request. This value can be different from the number of events that the client requests. It is defined in the servercfg.xml file.

mccompThe BMC Impact Manager rules compiler. Rules are written in the Master Rule Language (MRL). The platform-independent compiler converts them to byte code that the cell can read and process.



mcell.conf fileThe configuration file that contains configuration options for a BMC Impact Manager instance (cell). It is in the installDirectory/etc/ directory on UNIX platforms and in the drive:\installDirectory\etc\ directory on supported Windows platforms.

mcell.dir fileThe file that lists the cells to which a product component can connect and communicate. The information for each cell includes: its name, its encryption key, and its host name and port number. This file is in the installDirectory/etc/ directory on UNIX platforms and in the drive:\installDirectory\etc\ directory on supported Windows platforms.

mcell.modify fileThe file that lists the slots that affect the mc_modification_date slot. When a specified slot is modified, the time stamp of the modification is reset in the mc_modification_date slot, so that slot is listed in mcell.modify.

mcell.trace fileThe configuration file that specifies the trace information about a BMC Impact Manager (cell) that should be recorded and the location to which it is written. It is in installDirectory/etc/ directory on UNIX platforms and in the drive:\installDirectory\etc\ directory on supported Windows platforms.

.mrl fileA file that contains rule and collector definitions written in the Master Rule Language (MRL). Event and service management processing rules and collectors are stored in .mrl files and in compiled .wic files.

mc_udidSee universal data identifier (mc_udid).

Nnamespace

In XML, a collection of element and attribute names and values that is stored in an XML document and accessed by its uniform resource identifier. The XML file that accesses the uniform resource identifier can incorporate the information that is stored in the document.

nodeA BMC Impact Manager instance that can receive only events originating on the local host system.

non-local actionA user-initiated action that does not execute on the user console host machine.

normalizationThe process of homogenizing event data into a common event format so that a standard set of event data is collected and reported regardless of the event source.

Glossary 195


notification1. A message, either detailed or concise, that contains information about a condition that triggered an alert state on a monitored element. An email message or SNMP trap that is sent when the program detects a problem that triggers an alert.

2. A type of policy.

Oobject class

In BMC Impact Solutions, a data structure that defines a type of object. An object class can be a BAROC-language data structure in a BMC Impact Manager cell Knowledge Base or a Common Data Model (CDM) data structure in the BMC Configuration Management Database. A class is made up of data fields, called attributes (slots) that define its properties. See also event class, object, and object hierarchy.

operationIn Web Services Description Language, a set of messages related to a single web service action.

Pphase (rule)

A specific stage of event processing. There are eight sequential phases to event processing and two nonsequential phases, each with a corresponding rule type.

policy class A BAROC class that is a child of the base data class POLICY and that defines a type of policy.

policy instanceA specific implementation of any of the types of event management policies. For example, you could have an instance of a blackout policy that defined blackout periods for holidays and another instance of the same policy that defined blackout periods for monthly maintenance.

polling interfaceAn abstract connection between a BMC II Web Services client and the server in which the client retrieves events from an event queue by invoking polling calls. See also pull interface. Contrast with callback interface.

portA specific communication channel in TCP/IP networking. Ports are identified by numbers. BMC Impact Manager communicates using the ports specified during installation.

port typeIn Web Services Description Language, a logical grouping of operations and their messages. It defines the public entry point for client applications.



portingThe process of translating or converting software to run in a different operating environment.

Propagate ruleAn event-processing rule that is used to forward events to other BMC Impact Managers in the managed domain. Propagate rules are evaluated during the Propagate phase of event processing.

propagated eventAn event that is forwarded from one cell to another cell or to an Integration product during the Propagate phase of event processing.

propagationSee event propagation.

providerAn entity that provides a service, such as a web service, or, in an event distribution system, a programming object that publishes events. Contrast with consumer.

publishIn an event distribution system, a provider action of making events and data available by sending messages to a space or node without specifying a specific destination. Contrast with subscribe.

pull interfaceA processing model in which the event consumer (the BMC II Web Services client) controls the event flow by requesting events from the provider through polling calls. The BMC II Web Services Server collects events in an event queue and waits for the client to initiate the request for events. See also polling interface. Contrast with push interface.

push interfaceA processing model in which the event provider (the BMC II Web Services Server) controls the pace of the event flow through the implementation of an event listener utility and callbacks. The message consumer (the BMC II Web Services client) waits to receive events that are published by the event provider (the BMC II Web Services Server). See also callback interface. Contrast with pull interface.

RRegulate rule

An event processing rule that processes repetitive (duplicate) events or events that occur with a specified frequency. With a Regulate rule, you can create a new event based on the detection of repetitive or frequent events. See also Regulate phase.

repositoryThe storage facility in which BMC Impact Manager event information is stored.

Glossary 197


root cause analysisThe process of monitoring events and correlating event data to identify the true cause of a problem.

ruleA conditional statement that, if determined to be true, executes actions. The cell evaluates events by comparing each event to a series of rules during event processing. Rules are grouped in phases that are processed one by one. The order in which rules are evaluated during a particular phase is based on the order in which they were loaded. When all the rules in one phase are evaluated, the cell moves to the next phase.

Sselector

A set of defining criteria that is used to match events. The criteria are defined in a text file with the file name extension of .selector. Within the file, the defining criteria are enclosed within braces. See also web services subscription selector.

servercfg.xml fileThe BMC II Web Services Server configuration file. It contains parameters, some of which are read at runtime, that determine the port number, event queue size, server log file, and other information. It is located in installDirectory/conf or drive:\installDirectory\conf.

serviceIn Web Services Description Language, a collection of endpoints. Each endpoint indicates a specific location for accessing a service using a specific protocol and data format. See also endpoint.

service component aliasA name that is assigned to a service component instance and used in associating an event type with the component instance. You add an alias to a service component instance’s definition in the Service Model Editor. A service component instance can have several different aliases to enable different event types to be associated with it.

slotAn attribute in a BAROC class definition. A class definition consists of one or more slots. Each slot has a data type and can have specific attributes, called facets, that can control the values that the slot can have or control aspects of a class instance’s processing. A class that is a subclass to another class inherits all the slots of the parent class.

SOAP encodingA set of rules for encoding data to conform to the SOAP data model of mapping non-XML based data to an XML representation. The encoding can be used to transmit data in SOAP message format. See also bindings.



source-code generatorA software tool that creates source code (client stubs) in a specified programming language from a Web Services Description Language file for a web service. See also stub.

SSLSecure Sockets Layer. A security protocol that manages the security of messages communicated on the Web. The Secure Sockets Layer lies between the transport mechanism layer (typically HTTP) and the underlying TCP layer. See also transport mechanism.

state change eventA generated event type that records changes in a component’s status. State change events never participate in component status computation.

stubA small program routine that acts as a substitute for a larger program routine. The stub accepts requests from one program and forwards them to another. The stub accepts the responses from the receiving program and passes them back to the program that made the request.

In BMC II Web Services, you use a source-code generator to generate client stubs from the Web Services Description Language File. See also source-code generator.

subscribeIn an event distribution system, a consumer action of registering to receive (subscribe to) specified events. Contrast with publish.

subscription tableA data table within the BMC II Web Services Server in which client context IDs are matched with selector names. Each subscription call invoked by a BMC II Web Services client contains a context ID that identifies the client and a selector name that indicates the types of events it requests. The subscription table enables the BMC II Web Services Server to send the requested events to the corresponding client.

synchronous web servicesA message exchange pattern in which the sender and receiver must interact in a precise sequence. For example, a sender submits a request message and cannot continue processing until it receives a response. Contrast with asynchronous web services.

Ttransport mechanism

An upper layer communications protocol for opening and closing communication requests across the Web. The transport mechanism runs on top of the underlying TCP/IP communication language. In web services, HTTP (Hypertext Transfer Protocol) is a standard transport mechanism for SOAP-encoded messages and is used by BMC II Web Services. See also SSL.

Glossary 199


UUDDI

Universal Description, Discovery, and Integration. A Web-based information registry where businesses can register information about the web services they offer. web services consumers can discover and invoke the web service from the registry. The registration of web service instances in UDDI registries is optional. BMC II Web Services is not registered in UDDI.

universal data identifier (mc_udid)A unique, system-generated value used to identify a specific service component instance. Each service component must have a value for the mc_udid attribute (slot). One use of the universal data identifier is in associating aliases to a service component instance.

WWASP Server for C++

A Systinet product that is a collection of runtime libraries which BMC II Web Services has adapted for use in its implementation of the BMC II Web Services Server, specifically the event listener libraries.

Web Services Description Language (WSDL)The standard XML-based language for describing web service interfaces and enabling consumers to access the web service electronically. A typical WSDL file is divided into sections that define data types, messages, operations, bindings, and services. The file exposes the type of data that is transmitted, the message pattern between parties, the function calls and parameters that can be invoked, the way each function call is communicated electronically, and the specific port address from which the service can be accessed. See also EventListener.wsdl file and imserv.

web services subscription selectorA special usage of a selector. A selector set used to match incoming messages that have propagated from BMC Impact Manager product instances. This selector makes the matching messages available to the subscribing web services client or clients. See also selector.

When clauseA part of MRL rule syntax for Abstract, Correlate, Execute, Propagate, and Timer rules. Events must first meet the selection criteria in the rule before the When clause is evaluated. Changes to slot values cause When clauses to be re-evaluated.



WSCELLA message receiver for the BMC II Web Services Server that functions as a listener. It accept connections from BMC Impact Manager instances at default port number 19999. It receives events and messages from BMC Impact Manager instances and stores them in a buffer.

The WSCELL entry is defined in the mcell.dir file of the BMC II Web Services Server. Each instance of the BMC II Web Services Server must have its unique WSCELL entry. To connect with the BMC Impact Manager network, you must also enter the WSCELL information in the mcell.dir file of BMC Impact Manager instance to which you are connecting. See also mcell.dir file.

Glossary 201

BMC SOFTWARE – SDK LICENSE AGREEMENT BY OPENING THE PACKAGE, INSTALLING, PRESSING “AGREE” OR “YES” OR USING THE BMC MODULES, THE ENTITY OR INDIVIDUALENTERING INTO THIS AGREEMENT AGREES TO BE BOUND BY THE FOLLOWING TERMS, IF YOU DO NOT AGREE WITH ANY OF THESE TERMS,DO NOT INSTALL OR USE THE BMC MODULES AND PROMPTLY RETURN THE BMC MODULES TO BMC. IF YOU REJECT THIS AGREEMENT YOUWILL NOT ACQUIRE ANY LICENSE TO USE THE BMC MODULES.

SCOPE OF AGREEMENT. This Agreement is between the entity or individual entering into this Agreement (“You”) and BMC Software, Inc. (“BMC”). ThisAgreement governs Your use of the BMC Modules, unless You agreed to a web-based license agreement with BMC when ordering the BMC Modules, inwhich case that web-based license agreement governs the use of the BMC Modules. As used herein, “Complementary Product” means any product of Youthat embeds or is dependent for execution upon a BMC Module.

LICENSE. BMC grants You a non-exclusive, non-transferable, personal license (“License”) for one person (the “Developer”) (a) to copy and operate the BMCModules for the sole purpose of designing, developing and testing Complementary Products, provided that You acknowledge and agree that the right ofembedding does not include a right of distribution, and (b) to copy and operate Complementary Products (including any BMC Modules embedded therein)solely for Your internal production purposes. You may not and agree not to: (i) copy the BMC Modules or the Complementary Products except as expresslypermitted in the immediately foregoing sentence, (ii) distribute, resell, rent or lease the BMC Modules or the Complementary Products, (iii) use the BMCModules for production purposes except as expressly permitted with respect to embedded BMC Modules in the immediately foregoing sentence, (iv)disassemble or reverse engineer any BMC Module, or decompile or otherwise attempt to derive any BMC Module source code from executable code, except tothe extent expressly permitted by applicable law despite this limitation, (v) release any information to any third parties on the functionality or performance ofthe BMC Modules without BMC's prior written consent, or (vi) provide a third party with the results of any functional evaluation, or benchmarking orperformance tests, without BMC's prior written approval. Additional usage restrictions may apply to certain third-party files or programs embedded in aBMC Module – applicable installation instructions or release notes may contain the relevant details. Notwithstanding anything in this Agreement to thecontrary, the licenses granted in this Agreement (A) do not grant You the right to use any BMC Module (such rights, if any, are granted under a separatelicense), (B) do not extend to any rights under any patents or patent applications under which BMC has any rights, and (C) do not extend to any use of theBMC Modules in combination with any product, service or software other than the Complementary Product for which it is registered and approved.

FEES. You agree to pay any shipping or handling fees associated with the BMC Modules. You are responsible for taxes, if any.

TERMINATION. This Agreement terminates automatically if You breach any of its terms. Either party may terminate this Agreement without cause on 30days prior written notice. Upon termination, You must uninstall the BMC Modules, and either certify their destruction or return them to BMC.

OWNERSHIP. BMC, or its affiliates or licensors, retains all right, title and interest in the BMC Modules and copies thereof, and any intellectual property,informational, industrial property and proprietary rights therein. BMC neither grants nor otherwise transfers any rights of ownership in the BMC Modules toYou. The BMC Modules are protected by applicable copyright, trade secret, patent and other intellectual and industrial property laws. As between You andBMC, You retain all right, title and interest in any intellectual property, information, industrial property and proprietary rights in the ComplementaryProducts, excluding and subject to those contained in the BMC Modules.

CONFIDENTIAL AND PROPRIETARY INFORMATION. The BMC Modules contain valuable confidential information and trade secrets of BMC. You maynot use the BMC Modules other than as specifically allowed under the license granted in this Agreement. You may not disclose the BMC Modules or any partthereof, to third parties, except that (i) You may disclose the BMC Modules or parts thereof to Developer if Developer has obligations of confidentiality whichare at least as protective of BMC’s confidential information and trade secrets as the provisions of this Agreement and if Developer’s use of the BMC Modulesis consistent with the terms of this Agreement, and (ii) if You use a Complementary Product internally for production purposes, You may disclose the BMCModules or parts thereof to its employees who are under obligations of confidentiality at least as protective of BMC’s confidential information and tradesecrets as the provisions of this Agreement, whose use of the BMC Modules is consistent with the terms of this Agreement, and who need to receive suchdisclosure in order to install, operate, support or maintain the Complementary BMC Modules. You agree to use all reasonable efforts to prevent theunauthorized use, copying, publication or dissemination of any BMC Module.

WARRANTY DISCLAIMER. THE BMC MODULES ARE PROVIDED “AS IS”, WITH ALL FAULTS. BMC, ITS AFFILIATES AND LICENSORSSPECIFICALLY DISCLAIM ALL WARRANTIES, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND QUIET ENJOYMENT. BMC DOES NOT WARRANT THAT THE OPERATION OFTHE BMC MODULES OR THE COMPLEMENTARY PRODUCTS WILL BE UNINTERRUPTED, VIRUS OR ERROR FREE, OR THAT THERE ARE NODEFECTS.

LIMITS ON BMC’S LIABILITY. IN NO EVENT WILL BMC, ITS AFFILIATES OR LICENSORS, BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL,PUNITIVE OR CONSEQUENTIAL DAMAGES RELATING TO OR ARISING OUT OF THIS AGREEMENT, THE BMC MODULES AND/OR ANYCOMPLEMENTARY PRODUCT (INCLUDING WITHOUT LIMITATION LOST PROFITS, LOST COMPUTER USAGE TIME, AND DAMAGE OR LOSS OFUSE OF DATA), EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, AND IRRESPECTIVE OF ANY NEGLIGENCE OF BMC OR WHETHERSUCH DAMAGES RESULT FROM A CLAIM ARISING UNDER TORT OR CONTRACT LAW. BMC’S LIABILITY FOR DIRECT DAMAGES IS LIMITED TOTHE GREATER OF (I) THE AMOUNT PAID BY YOU FOR THE LICENSE TO THE BMC MODULE, IF ANY, AND (II) $1000.

VERIFICATION. If requested by BMC, You will deliver to BMC written certification relating to Your use of the BMC Modules and/or the ComplementaryProducts in compliance with the terms of this Agreement. BMC may audit Your use of the BMC Modules and/or Complementary Products to confirm suchcompliance.

EXPORT CONTROLS. You will cooperate with BMC as reasonably necessary to ensure compliance with the laws and regulations of the United States and allother relevant countries, relating to exports and re-exports (“Export Laws”). You may not import, export, re-export or transfer, directly or indirectly, includingvia remote access, any part of the BMC Modules, or any other BMC information or technology, in violation of any such laws and regulations, or without anywritten governmental authorization required under applicable Export Laws. Neither the BMC Modules nor the underlying information or technology may bedownloaded or otherwise provided or made available, either directly or indirectly, (i) into Cuba, Iran, Libya, Sudan or any other country subject to U.S. tradesanctions, to individuals or entities controlled by such countries, or to nationals or residents of such countries other than nationals who are lawfully admittedpermanent residents of countries not subject to such sanctions; or (ii) to anyone on the U.S. Treasury Department’s list of Specially Designated Nationals andblocked persons or the U.S. Commerce Department’s Table of Denial Orders. BY OPENING THE PACKAGE, INSTALLING, PRESSING “AGREE” OR “YES”OR USING THE BMC MODULES, YOU AGREE TO THE FOREGOING AND REPRESENT AND WARRANT THAT YOU ARE NOT LOCATED IN, UNDERTHE CONTOL OF, OR A NATIONAL OR RESIDENT OF ANY SUCH COUNTRY OR ON ANY SUCH LIST.

DISPUTE RESOLUTION AND GOVERNING LAW. ANY CONTROVERSY OR CLAIM ARISING OUT OF THIS AGREEMENT, OR THE BREACH HEREOF,WILL BE SETTLED BY ARBITRATION ADMINISTERED BY THE AMERICAN ARBITRATION ASSOCIATION UNDER ITS COMMERCIALARBITRATION RULES IN HOUSTON, TEXAS IN ENGLISH. THE ARBITRATOR MUST FILE ALL FINDINGS WITHIN 30 DAYS AFTER THE FINALARBITRATION HEARING. JUDGMENT ON ANY AWARD RENDERED BY THE ARBITRATOR MAY BE ENTERED IN ANY COURT HAVINGJURISDICTION THEREOF. NOTHING CONTAINED IN THIS SECTION WILL LIMIT BMC'S ABILITY TO SEEK EQUITABLE RELIEF IN ANY COURT.THE PARTIES WILL ARBITRATE DISPUTES IN CONFIDENCE. THIS AGREEMENT WILL BE GOVERNED BY THE SUBSTANTIVE LAWS OF THE STATEOF TEXAS. CHOICE OF LAW RULES OF ANY JURISDICTION AND THE UNITED NATIONS CONVENTION ON CONTRACTS FOR THEINTERNATIONAL SALE OF GOODS WILL NOT APPLY.

U.S. GOVERNMENT RESTRICTED RIGHTS. UNPUBLISHED – RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use,duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013,DFARS 227.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer isBMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.

MISCELLANEOUS TERMS. This Agreement constitutes the entire agreement between You and BMC relating to the matters covered hereby, and supersedesany prior or contemporaneous negotiations or agreements, whether oral or written, concerning the BMC Modules and any related subject matter. ThisAgreement may be modified only in a mutually signed, whether in writing or electronic, agreement between You and BMC. Neither Developer nor You mayassign this Agreement or any rights granted by this Agreement to a successor, except in the event of merger, consolidation, or sale of all or substantially all ofYour assets. Should any provision of this Agreement be invalid, or unenforceable, the remainder of the provisions will remain in effect. The parties haveagreed that this Agreement and the documents related thereto be drawn up in the English language. Les parties exigent que la présente convention ainsi queles documents qui s’y rattachent soient rédigés en anglais.

BY OPENING THE PACKAGE, INSTALLING, PRESSING “AGREE” OR “YES” OR USING THE BMC MODULES, YOU ACKNOWLEDGE AND AGREETHAT YOUR AUTHORIZED REPRESENTATIVE HAS READ THIS AGREEMENT AND THAT YOU INTEND TO BE BOUND HEREBY, AS IF YOURAUTHORIZED REPRESENTATIVE HAD SIGNED THIS AGREEMENT IN WRITING. THE INDIVIDUAL EXECUTING THIS AGREEMENT WARRANTSTHAT HE OR SHE HAS THE AUTHORITY TO ACCEPT THE TERMS OF THIS AGREEMENT FOR YOU AND ON HIS OR HER OWN BEHALF.

Third-Party Product TermsThe following terms apply to third-party products that are included with or in a BMC Software product as described in the BMC Software, Inc., LicenseAgreement that is applicable to the BMC Software product.

OpenSSl LicenseCopyright (C) 1995 Tim Hudson ([email protected]) All rights reserved.

This package is documentation for the SSLeay implementation that was written by Eric Young ([email protected]). The documentation was written by TimHudson ([email protected]).

This documentation can be distributed free for commercial and non-commercial use as long as the following conditions are aheared to. The followingconditions apply to all the documentation found in this distribution. Copyright remains Tim Hudson's, and as such any Copyright notices in thedocumentation are not to be removed. If this documentation is used in a product, Tim Hudson should be given attribution as the author of thisdocumentation.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code and documentation must retain the copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this documentation must display the following acknowledgement: This documentation was written by Tim Hudson ([email protected])

THIS DOCUMENTATION IS PROVIDED BY TIM HUDSON ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITEDTO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALLTHE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIALDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; ORBUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THEPOSSIBILITY OF SUCH DAMAGE.

*86784**86784**86784**86784*

*86784*

BMC Impact Integration Developerâ€™s Kit Web Services Server

Documents

Transcript of BMC Impact Integration Developerâ€™s Kit Web Services Server