bmc atrium integration engine 7.6.04 - aie adapter development kit

8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit

1/146

www.bmc.com

BMC Atrium Integration Engine 7.6.04

Adapter Development KitDeveloper’s Guide

January 2011


2/146

If you have comments or suggestions about this documentation, contact Information Development by email at

[email protected].

Contacting BMC Software

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

United States and Canada

Address BMC SOFTWARE INC2101 CITYWEST BLVDHOUSTON TX 77042-2827USA

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 1999–2011 BMC Software, Inc.

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

AIX, DB2, and IBM are trademarks or registered trademarks of International Business Machines Corporation in the UnitedStates, other countries, or both.

Linux is the registered trademark of Linus Torvalds.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of theirrespective owners.

UNIX is a registered trademark of The Open Group in the US and other countries.

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

Restricted Rights Legend

U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THECOPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by theU.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 isBMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to thisaddress.

mailto:[email protected]://www.bmc.com/mailto:[email protected]://www.bmc.com/


3/146

Customer Support

You can obtain technical support by using the Support page on the BMC Software website or by contacting CustomerSupport by telephone or email. To expedite your inquiry, please see “Before Contacting BMC Software.”

Support Website

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

Read overviews about support services and programs that BMC Software offers. Find the most current information about BMC Software products. Search a database for problems similar to yours and possible solutions. Order or download product documentation. Report a problem or ask a question. Subscribe to receive email notices when new product versions are released. Find worldwide BMC Software support center locations and contact information, including email addresses, fax

numbers, and telephone numbers.

Support by telephone or email

In the United States and Canada, if you need technical support and do not have access to the Web, call 800 537 1813 orsend an email message to [email protected]. (In the Subject line, enterSupID:yourSupportContractID , such as SupID:12345.) Outside the United States and Canada, contact yourlocal support center for assistance.

Before Contacting BMC Software

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

Commands and options that you used

Messages received (and the time and date that you received them)

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

http://www.bmc.com/supportmailto:[email protected]:[email protected]://www.bmc.com/support


4/146

License key and password information

If you have a question about your license key or password, contact Customer Support through one of the followingmethods:

E-mail [email protected]. (In the Subject line, enter SupID:,such as SupID:12345.)

In the United States and Canada, call 800 537 1813. Outside the United States and Canada, contact your local supportcenter for assistance.

Submit a new issue at http://www.bmc.com/support.

mailto:[email protected]://www.bmc.com/supporthttp://www.bmc.com/supportmailto:[email protected]


5/146

5

Contents

BMC Atrium Core documentation 11

Chapter 1 Understanding BMC Atrium Integration Engine 15

Overview of BMC Atrium Integration Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

BMC Atrium Integration Engine components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Data Exchange application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18AIE service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Event Request interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Adapter Development Kit interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Data transfer process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Initialization phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Processing phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 2 Understanding the development environment 25

Code requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Compiler requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Compiling an adapter template on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Description of installed files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Class library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Adapter template files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Sample flat file adapter files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Chapter 3 Defining the adapter rule syntax 31

Defining the rule syntax to describe a data value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Defining the rule syntax to support queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Configuring adapter initialization parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Creating an adapter rule syntax list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 4 Class library objects used by the adapter 37

Data exchange objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38CEIEDataExchangeDef object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40CQuery object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42


6/146

6 Adapter Development Kit Developer’s Guide

Data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43List objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

CValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44CRowsOfValueList object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44CListOfRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

CListOfRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Pointer objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

CRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45CQueryWithListOfRuleValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45CQueryWithRowsOfValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Adapter objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46dllmain object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46CQuery object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Chapter 5 Methods required by the adapter 49Preparing the adapter template development environment . . . . . . . . . . . . . . . . . . . . . 50

Creating an adapter-derived CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . 52Setting your adapter name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Implementing initialization methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Implementing database connection methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Implementing rule validation methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Getting and validating a CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Setting the data type of the value described in the CRule object . . . . . . . . . . . . . . 57Renaming the CNewRule object in the adapter template . . . . . . . . . . . . . . . . . . . . 57

Implementing key list creation methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Creating a key list without a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Creating a key list with a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Implementing the data retrieval method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Implementing the data creation method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Implementing the data update method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Implementing data deletion methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Implementing transaction processing methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Implementing command support methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Chapter 6 Packaging an adapter 67

Registering an adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Licensing an adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Building an installer for the developed adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Removing adapters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Sample data exchanges and data mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Documenting the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Chapter 7 Logging and debugging 71

Log and debug tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Recording log messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Using the CBaseAdapter object to record log events . . . . . . . . . . . . . . . . . . . . . . . . . . . 73


7/146

7

Recording debug events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Using the CBaseAdapter object to record debug events . . . . . . . . . . . . . . . . . . . . . 74Using the CRule object to record debug events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Appendix A Class library reference 75

CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76CBaseAdapter::CBaseAdapter (constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76CBaseAdapter::~CBaseAdapter (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76CBaseAdapter::CloseConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77CBaseAdapter::CreateNewQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78CBaseAdapter::CreateNewRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78CBaseAdapter::CreateQueryString. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79CBaseAdapter::CreateRuleValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80CBaseAdapter::DeleteRuleValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82CBaseAdapter::DoCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84CBaseAdapter::GetKeyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85CBaseAdapter::GetLicenseString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87CBaseAdapter::GetProductName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87CBaseAdapter::GetRuleAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87CBaseAdapter::GetRuleValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88CBaseAdapter::GetStatusMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91CBaseAdapter::Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91CBaseAdapter::OpenConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92CBaseAdapter::SetLogMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93CBaseAdapter::SetStatusMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94CBaseAdapter::StartTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94CBaseAdapter::StopTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95CBaseAdapter::SupportTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96CBaseAdapter::Terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96CBaseAdapter::UpdateRuleValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97CBaseAdapter::ValidateQualifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

CEIEDataExchangeDef object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101CEIEDataExchangeDef::GetDataExchangeName. . . . . . . . . . . . . . . . . . . . . . . . . . 101CEIEDataExchangeDef::GetFirstVenConfigParam . . . . . . . . . . . . . . . . . . . . . . . . 101CEIEDataExchangeDef::GetVenConfigParamAt . . . . . . . . . . . . . . . . . . . . . . . . . . 102CEIEDataExchangeDef::GetVenConfigParamLength . . . . . . . . . . . . . . . . . . . . . . 103CEIEDataExchangeDef::IsDirectionARDataIntoVendor. . . . . . . . . . . . . . . . . . . . 104CEIEDataExchangeDef::IsDirectionVendorDataIntoAR. . . . . . . . . . . . . . . . . . . . 104

CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105CRule::CRule (copy constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105CRule::~CRule (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105CRule::CRule (new rule constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105CRule::DeepClone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106CRule::GetContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106CRule::GetEIEDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107CRule::GetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107CRule::GetRuleString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108CRule::GetVenDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108CRule::IsValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108


8/146


CRule::SetContainer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109CRule::SetErrMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109CRule::SetRuleString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110CRule::SetValidity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110CRule::SetVenDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

CQuery object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112CQuery::CQuery (copy constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112CQuery::~CQuery (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112CQuery::CQuery (new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113CQuery::GetContainer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113CQuery::GetErrMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114CQuery::GetQueryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114CQuery::IsValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114CQuery::SetContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115CQuery::SetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115CQuery::SetQueryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

CQuery::SetValidity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116CValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117CValue::CValue (copy constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117CValue::~CValue (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117CValue::CValue (empty constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117CValue::GetDecimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118CValue::GetInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118CValue::GetReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119CValue::GetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119CValue::GetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120CValue::GetType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

CValue::GetULong. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121CValue::IsNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121CValue::SetDecimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122CValue::SetInt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122CValue::SetNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123CValue::SetReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123CValue::SetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124CValue::SetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124CValue::SetULong . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

CValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125CRowsOfValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

CListOfRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126CListOfRuleWithValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127CRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

CRuleWithValue::CRuleWithValue (constructor) . . . . . . . . . . . . . . . . . . . . . . . . . 127CRuleWithValue::CRuleWithValue (copy constructor). . . . . . . . . . . . . . . . . . . . . 128CRuleWithValue::~CRuleWithValue (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . 128CRuleWithValue::GetRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129CRuleWithValue::GetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129CRuleWithValue::SetRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130CRuleWithValue::SetValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

CQueryWithListOfRuleValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131


9/146

9

CQueryWithListOfRuleValue::CQueryWithListOfRuleValue(copy constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

CQueryWithListOfRuleValue::CQueryWithListOfRuleValue (destructor) . . . . 131CQueryWithListOfRuleValue::CQueryWithListOfRuleValue

(new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

CQueryWithListOfRuleValue::GetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132CQueryWithListOfRuleValue::GetRuleWithValueList . . . . . . . . . . . . . . . . . . . . . 133CQueryWithListOfRuleValue::SetQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133CQueryWithListOfRuleValue::SetRuleWithValueList . . . . . . . . . . . . . . . . . . . . . 133

CQueryWithRowsOfValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134CQueryWithRowsOfValue::CQueryWithRowsOfValue

(copy constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134CQueryWithRowsOfValue::~CQueryWithRowsOfValue

(destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134CQueryWithRowsOfValue::CQueryWithRowsOfValue

(new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

CQueryWithRowsOfValue::GetQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135CQueryWithRowsOfValue::GetRowsOfValueList. . . . . . . . . . . . . . . . . . . . . . . . . 136CQueryWithRowsOfValue::SetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136CQueryWithRowsOfValue::SetRowsOfValueList . . . . . . . . . . . . . . . . . . . . . . . . . 137

Index 139


10/146



11/146


BMC Atrium Core documentation

This section describes the complete set of BMC Atrium Core documentation,including manuals, help systems, videos, and so on.

Unless otherwise noted, documentation is available free of charge on the BMCAtrium Core documentation media (DVD or Electronic Product Download bundle) and on the BMC Customer Support site, at http://www.bmc.com/

support.

To find this documentation on the BMC Customer Support site, choose ProductDocumentation > Supported Product A-Z List > BMC Atrium CMDB EnterpriseManager >7.6.04

Title Description Audience

Atrium Integrator 7.6.04User's Guide

Information about defining source and targetconnections, creating jobs and transformations,editing and monitoring jobs, and other AtriumIntegrator concepts.

Users who are responsiblefor setting up data transferintegrations betweenexternal data stores and

BMC Atrium CMDB.BMC Atrium CMDB 7.6.04

Administrator's GuideInformation about setting permissions, configuringfederation, modifying the data model, configuringan impact model, and other administrative tasks inBMC Atrium Configuration Management Database(BMC Atrium CMDB).

Configuration managers,application administrators,and asset analysts.

BMC Atrium CMDB 7.6.04Common Data ModelDiagram

Hierarchical diagram of all classes in the CommonData Model (CDM), including unique attributes andapplicable relationships.


BMC Atrium CMDB7.6.04 Data Model Help

Description and details of superclasses, subclasses,attributes, and relationship classes for each class.

Contains only information about the CDM at first, but you can update it to include information aboutdata model extensions that you install.

Note: This Help is provided in HTML and is availableon the BMC Atrium Core media. It is not availableon the BMC Customer Support site.

Configuration managers,application administrators,

and asset analysts.

http://www.bmc.com/supporthttp://www.bmc.com/supporthttp://www.bmc.com/supporthttp://www.bmc.com/support


12/146



BMC Atrium CMDB 7.6.04Data Modeling Guide

Best practices for using the classes that BMCprovides for BMC Atrium CMDB (both the CDMand extensions) to model complex business entities,focusing on the use of multiple related CIs to model

an entity rather than on general information about aclass or attribute.


BMC Atrium CMDB7.6.04 Javadoc Help

Information about Oracle Java classes, methods, andvariables that integrate with BMC Atrium CMDB.

Note: This Help is provided in HTML and is availableon the BMC Atrium Core media. It is not availableon the BMC Customer Support site.

Application programmers.

BMC Atrium CMDB 7.6.04Normalization andReconciliation Guide

Information about normalizing data in BMC AtriumCMDB and reconciling CIs from different dataproviders into a single production dataset.


BMC Atrium CMDB7.6.04 Online Help

Help for using and configuring BMC Atrium CMDB,including Atrium Integrator, BMC Atrium ProductCatalog, Reconciliation Engine, NormalizationEngine, and so on.

Note: This Help is provided in HTML and is availablethrough the Help links in the BMC Atrium CMDBuser interface. It is not available on the BMCCustomer Support site.

Configuration managers,application administrators,asset analysts, and usersthat work with CIs and needto understand therelationships that existwithin BMC Atrium CMDB.

BMC Atrium CMDB 7.6.04User's Guide

Information about using BMC Atrium CMDB,including searching for and comparing CIs andrelationships, relating CIs, viewing history, runningimpact simulations, and viewing federated data.

Users that work with CIsand need to understand therelationships that existwithin BMC Atrium CMDB.

BMC Atrium Core: TakingYour Data Into ProductionEnd to End

End-to-end high-level steps for bringing data intoBMC Atrium CMDB from a third-party source andmaking it available in your production dataset.

Note: This Flash video is available on the BMCAtrium Core media. It is not available on the BMCCustomer Support site.


BMC Atrium Core 7.6.04Compatibility Matrix

Information about the BMC Atrium Coreconfigurations that are expected to work together

based on design, testing, or general understandingof the interaction between products.

Note: Download the BMC Atrium Core 7.6.04Compatibility Matrix from the BMC CustomerSupport site at http://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=n.



http://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=nhttp://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=nhttp://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=nhttp://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=nhttp://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=nhttp://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=n


13/146


BMC Atrium Core 7.6.04Concepts and PlanningGuide

Information about CMDB concepts and high-levelsteps for planning and implementing BMC AtriumCore.

Anyone who wants to learnabout and understand BMCAtrium Core products,CMDBs in general, and the

functionality of BMCAtrium CMDB in particular.

IT leaders, configurationmanagers, applicationadministrators, and assetanalysts are some who will

benefit from thisinformation.

BMC Atrium Core 7.6.04Developer’s Reference Guide

Information about creating API programs using CAPI functions and data structures.

Application administratorsand programmers.

BMC Atrium Core 7.6.04

Installation Guide

Information about installing, upgrading, and

uninstalling BMC Atrium Core features.

Application administrators.

BMC Atrium Core 7.6.04 Master Index

Combined index of all guides. Everyone.

BMC Atrium Core 7.6.04Product Catalog and DMLGuide

Information about configuring the Product Catalogand DML, adding products, and creating aliases forproducts, manufacturers, and categorizations.

System administrators, ITmanagers, networkmanagers, and otherqualified personnel who arefamiliar with theircomputing and networkingenvironment.

BMC Atrium Core 7.6.04

Release Notes

Information about new features, known issues, and

other late-breaking topics.

Everyone.

BMC Atrium Core 7.6.04Troubleshooting Guide

Information about resolving issues with BMCAtrium Core components, including API, filter, andconsole error messages and their solutions.

Application administrators,programmers, and BMCSupport personnel.

BMC Atrium Core 7.6.04Web Services Help

Information about using BMC Atrium Core WebServices, including how to publish and findinterfaces in the Web Services Registry, set versions,disambiguate web services, configure securitypolicies and encryption, and use BMC Atrium CoreWeb Services data structures and operations.

Note: This Help is provided in HTML and is available

on the BMC Atrium Core media. It is not availableon the BMC Customer Support site.

Application administratorsand programmers.

BMC Atrium IntegrationEngine 7.6.04 ADKDeveloper's Guide

Information about how to build adapters that cantransfer information between an external data storeand either BMC Remedy AR System forms or BMCAtrium CMDB.

Developers who have a basic understanding of BMCAtrium Integration Engineand want to build adaptersthat can exchange data

between two data sources.



14/146



BMC Atrium IntegrationEngine 7.6.04 Online Help

Help for using and configuring BMC AtriumIntegration Engine.

Note: This Help is provided in HTML and is availablethrough the Help links in the BMC AtriumIntegration Engine user interface. It is notavailable on the BMC Customer Support site.

Users who are responsiblefor setting up data transferintegrations betweenexternal data stores and

either BMC Atrium CMDBor BMC RemedyAR System.

BMC Atrium IntegrationEngine 7.6.04 User's Guide

Information about creating data exchanges and datamappings, defining rules and queries, activatingevent-driven data exchanges, defining connectionsettings, and other BMC Atrium Integration Engineconcepts.

Users who are responsiblefor setting up data transferintegrations betweenexternal data stores andeither BMC Atrium CMDBor BMC RemedyAR System.

Mapping Your Data to

BMC Atrium CMDB 7.6.04Classes

Spreadsheet that maps common IT objects to the

appropriate class, whether part of the CDM or anextension. This spreadsheet also includesinformation about further categorizing instancesusing key attributes, and best practices for creatingnormalized relationships.

Configuration managers,

application administrators,and asset analysts.



15/146


Chapter

1 Understanding BMC AtriumIntegration EngineThe BMC Atrium Integration Engine enables you to transfer data between anexternal data store and BMC Remedy Action Request System (BMC Remedy

AR System) forms or BMC Atrium Configuration Management Database (BMCAtrium CMDB) classes. You can use the included adapters for Microsoft SQLServer, Oracle®, IBM® DB2® Universal Database™, XML, and flat files such ascomma-separated value (CSV) files. You can also use the BMC Atrium IntegrationEngine Adapter Development Kit to build your own adapters to meet yourorganization’s specific needs.

Atrium Integrator replaces BMC Atrium Integration Engine. You can continueusing BMC Atrium Integration Engine for existing data mappings and exchanges, but BMC recommends that you use Atrium Integrator for all new data transfers.BMC Atrium Integration Engine will be deprecated in a future release.

The following topics are provided: Overview of BMC Atrium Integration Engine (page 16)

BMC Atrium Integration Engine components (page 17)

Data transfer process (page 20)

Performance considerations (page 22)

Getting started (page 23)


16/146



Overview of BMC Atrium Integration Engine

With BMC Atrium Integration Engine, you can schedule bulk data transfers andevent-based integrations initiated by either the source, target, or any other

application. You can also use BMC Atrium Integration Engine for initial data load,incremental data transfers, and data synchronization. You can build links betweenBMC Remedy IT Service Management (BMC Remedy ITSM) applications andEnterprise Resource Planning (ERP), Customer Relationship Management, SupplyChain Management, and other enterprise applications.

For example, you can use BMC Atrium Integration Engine to:

Synchronize IT data from a discovery application with BMC Atrium CMDB,where it can be reconciled with data from other sources to your productiondataset

Synchronize data from your Human Resources applications with employee data

in your BMC Remedy Service Desk application

Synchronize asset data tracked in BMC Remedy Asset Managementapplications with corporate asset data stored in ERP applications

Figure 1-1 shows how you can transfer data in either direction between an externaldata store and a BMC Remedy AR System application or BMC Atrium CMDBclass.

Figure 1-1: Overview of the data transfer process

During the data transfer, BMC Atrium Integration Engine identifies the records to

be transferred and performs some or all of the following tasks, depending uponhow you have configured your data exchange:

Reads records

Creates new records

Updates records

Deletes records

Data object

External data store

BMC Remedy AR System database

BMC Remedy

AR System

form

BMC Atrium

CMDB class

BMC Atrium Integration

Engine


17/146


BMC Atrium Integration Engine components


BMC Atrium Integration Engine has the following main components:

Data Exchange application (page 18)

AIE service (page 19)

Event Request interface (page 19)

Adapter Development Kit interface (page 19)

Figure 1-2 shows how these components work with other BMC Atrium IntegrationEngine components and related objects.

Figure 1-2: BMC Atrium Integration Engine components

? ? ?

Oracle database

SQL Server database

DB2 database

BMC Remedy AR Systemdatabase or BMC Atrium CMDB

Adapters provided by BMC Atrium Integration Engine

DB2 adapter

Oracle adapter

SQLadapter

XMLfile

XMLadapter

Flat file

Flat File adapter

Custom adapters (not included)

Application Pending form

Event Request interface (aiexfer)

Data Exchange application

AIE service

BMC Atrium Integration

Engine

Other data store

Other data store

Other data store

Adapter Development Kit interface

BMC Remedy AR System

APIs

BMC Atrium CMDB

APIs


18/146



Data Exchange application

The Data Exchange application is a group of BMC Remedy AR System forms thatis available from your BMC Remedy AR System home page as the AIE Consolelink. Use the data exchange application to work with the following integration

objects: A data exchange is the object that you execute to move data with BMC Atrium

Integration Engine, and a single execution of a data exchange is called a datatransfer. A data exchange specifies whether the external data store is the sourceor the target for a data transfer, which adapter is used, how to connect to theexternal data store, and the method used to execute the exchange. A dataexchange also specifies the conditions under which data is created, updated,and deleted.

You associate a data exchange with one or more data mappings to specify whichdata is transferred.

A data mapping defines data to be transferred. It specifies the external file ordatabase table and the BMC Remedy AR System form or BMC Atrium CMDBclass between which data is transferred, and defines the primary key thatidentifies a row of data on either side. A data mapping specifies the fields orattributes to be transferred from the source and maps them to fields or attributesin the target. It also specifies any fields or attributes in the source that should beupdated when a record in the target is created, updated, or deleted. A datamapping can limit the rows of data to be transferred from the source, updatedin the target, and updated in the source by including queries for each of theseoptions.

You use a data mapping by associating it with a data exchange.

The Data Exchange application also lets you perform the following configurationtasks:

Define external data store connection parameters for multiple data exchangessimultaneously.

Populate BMC Atrium Integration Engine menus with the names of tables andcolumns from external data stores to simplify the process of creating datamappings.

Specify the administrator user and online help path for the application.

View the BMC Atrium Integration Engine instances you defined at installationtime and edit some settings for them.

Display version numbers for BMC Atrium Integration Engine and relatedproducts.


19/146



AIE service

The AIE service obtains the defined data exchange from the Data Exchangeapplication and completes the transfer of data by communicating with the adapterspecified in the data exchange definition. Adapters are software, either provided

by BMC or custom-built, that provide access to the external data and respond tocalls from BMC Atrium Integration Engine during a data exchange.

The AIE service can connect to any Microsoft Windows or UNIX® BMC RemedyAR System server. It does not need to reside on the same computer as the BMCRemedy AR System server or the external data stores, but can be on any computerthat is network-connected to both of these.

The AIE service runs as a client to the BMC Remedy AR System server using theBMC Remedy AR System application programming interface (API). Forinformation about the BMC Remedy AR System APIs, see the BMC Remedy ActionRequest System 7.6.04 C API Reference guide.

Event Request interface

You can execute a data exchange on an event-driven basis by using the EventRequest interface. Each event-driven request is created as an entry in theApplication Pending form on the BMC Remedy AR System server where the DataExchange application is installed. You create an event-driven request by directlycreating an Application Pending entry, by using BMC Remedy AR Systemworkflow to create the entry, or by invoking the aiexfer utility.

The AIE service processes requests at a scheduled interval configured in theaie.cfg file, regardless of which method was used to create the requests.

Optionally, the AIE service can handle individual event requests immediately ifyou enter them through the aiexfer utility.

Adapter Development Kit interface

The BMC Atrium Integration Engine Adapter Development Kit (ADK) contains allthe components needed to create an adapter. You use the BMC Atrium IntegrationEngine installer to install the ADK components. The ADK components are loadedduring installation and placed in a subdirectory of the BMC Atrium IntegrationEngine installation directory.

The ADK contains: A class library that defines the interface between the AIE service and an adapter.

You can use the class library as a foundation for building your adapters. Theclass library includes a base adapter class and several supporting classes. The base adapter class implements basic functionality common to all adapters anddeclares virtual functions.


20/146



An adapter template, which is a development environment that you can use tocreate an adapter.

The ADK includes a template directory that houses the Microsoft Visual C++.NET files that you can use to construct the adapter. The files included in thisdirectory outline the logical structure for the construction of an adapter with

comments embedded as guidelines.

A sample flat file adapter, which is an implementation of an adapter for a flatfile database.

The flat file adapter is a fully functional adapter that transfers data from BMCRemedy AR System to a flat file and vice versa. A sample adapter is included soyou can use the code as an example of how to create your own adapters.

An installation control file to help build an installer for an adapter.

The installation control file is a configuration file that you can use to determinewhat is installed from the BMC Atrium Integration Engine installer.

After an adapter is complete, you can package it with BMC Atrium IntegrationEngine and then modify the BMC Atrium Integration Engine installer to includeyour adapter.

Data transfer process

When you start the AIE service, it locates data exchanges by reading entries in theData Exchange application. When BMC Atrium Integration Engine detects a dataexchange, the AIE service loads the adapter that is associated with that data

exchange.

A data transfer has two phases: the initialization phase, in which a data exchange isprepared to run, followed by the processing phase, in which the data is transferred.

Initialization phase

The initialization phase prepares a data exchange to run. The AIE service performsthe following tasks:

Step 1 Loads data exchange rules.

The AIE service loads all the rules defined in the Data Exchange application andprepares the C++ objects defined by the Adapter Developer Kit. The rules includethe data exchange definition, the data mapping rules, and all adapter-definedconfiguration parameters and rules.


21/146


Data transfer process

Step 2 Connects to data stores to validate rules.

The AIE service connects to both the source and target data stores. A BMC RemedyAR System form or BMC Atrium CMDB class can serve as either the source or thetarget.

The AIE service does not transfer data at this point, but a connection to both datastores is necessary to validate rules.

Step 3 Validates data exchange rules.

The AIE service validates rules owned by BMC Atrium Integration Engine. Duringvalidation, the AIE service indicates if any errors or warnings were detected and ifthe rules are ready to be used in a data exchange.

At the same time, the adapter is called to validate adapter-owned rules. Duringvalidation, the adapter indicates if any errors or warnings were detected and if therules are ready to be used in a data exchange.

Step 4 Disconnects from data sources.

After the rules are validated, the AIE service disconnects from both data sources.

Step 5 Starts a thread.

At the end of the initialization phase, the AIE service starts a thread to manage thedata exchange process.

During this phase, the BMC Atrium Integration Engine debug facilities record alldata exchange and data handling rules.

Processing phase

In the processing phase, the transfer of data takes place. This phase begins when adata exchange is executed, which can be scheduled or event driven.

During the processing phase, the AIE service performs the following tasks:

Step 1 Refreshes the data exchange.

Before data is exchanged, the AIE service checks the Data Exchange application todetermine if any changes were made to the data exchange definition. If changes

were made, the AIE service updates the loaded data exchange with the newdefinition.

Step 2 Starts a separate thread for each data exchange.

The AIE service connects to both the source and target data stores for each dataexchange. The AIE service communicates through the BMC Remedy AR SystemAPI or BMC Atrium CMDB API to pull data out of and push data into those datastores. The AIE service uses the adapter to pull data out of and push data into theexternal data store.


22/146



Step 3 Locates data to be exchanged.

The AIE service obtains a list of keys from BMC Remedy AR System or BMCAtrium CMDB and prompts the adapter to create a list of keys. The AIE serviceconverts the keys to a common data type (if necessary) and then sorts the keys into

the same order so that it can compare the key lists.Step 4 Transfers data.

The AIE service compares the keys and determines from the data exchangedefinition how new and existing records should be treated. The AIE servicedecides on a key-by-key basis whether to create, update, or delete records. For eachkey, adapters can be called to read, write, update, or delete a record.

If during data transfer, the AIE service or the BMC Remedy AR System serverstops responding, BMC Atrium Integration Engine provides failover support forthe incomplete data exchanges. The next time the AIE service starts, the data

exchanges resume from the point they had stopped, thus avoiding repetition ofdata insertion.

Step 5 Disconnects from data stores.

After all keys are processed, the data transfer is considered complete. The AIEservice closes the connection to BMC Remedy AR System or BMC Atrium CMDBand prompts the adapter to close the connection to the external data store.

NOTE

The thread and adapter remain active, unless the data exchange is deactivated inthe Data Exchange application or the AIE service is terminated. In either of those

events, the adapter .dll is released and the thread terminates.

In this phase, the AIE service debug file shows all rules retrieved from the DataExchange application and the type of the data defined by the rule. The debug filealso identifies the success or failure of the data transfer and shows a detailed errormessage when any errors occur in the AIE service or in BMC Remedy AR System.

Performance considerations

Performance considerations for BMC Atrium Integration Engine are difficult toquantify because performance is affected by your network, BMC RemedyAR System, the BMC Remedy AR System server database, and the external datastore load. It is difficult to predict the effect of a specific change on BMC AtriumIntegration Engine performance, but configuration considerations can influence it.

Although it is easy to add field mappings or extra rules for each field, rememberthat each item you add is compared against every record in your database.Seemingly minor additions could have major effects if your database containsmany records. For example, if you have 1200 records in your database and thechange that you make adds an additional half-second to the run time for eachrecord, the data transfer might take an additional 10 minutes to run.


23/146


Getting started

However, you can use multiple instances, multiple sessions, and multithreading toincrease throughput and improve overall system performance. For moreinformation, see the BMC Atrium Integration Engine 7.6.04 User's Guide.

Getting startedThe following outline illustrate the high-level steps that you take to prepare fortransferring data. See the recommended area of the BMC Atrium IntegrationEngine documentation for specific instructions on each step.

NOTE

If you are working in a server group environment, make sure that you haveinstalled workflow binaries on all servers of the server group; otherwise the BMCAtrium Integration Engine workflow does not function. For more informationabout BMC Atrium Integration Engine working in a server group environment,see the BMC Atrium Integration Engine 7.6.04 User's Guide.

To get started using BMC Atrium Integration Engine

Step 1 Populate the database field menus for your external data stores using the rulehelpers in the Database Field Menus Console.

This greatly simplifies the process of creating data mappings by allowing you tochoose field names from a menu instead of manually typing them. Forinstructions, see the “Using the adapter rule helper utilities” section in the BMC Atrium Integration Engine 7.6.04 User's Guide.

Step 2 Create a data mapping to specify which data should be transferred and where itshould go.

For instructions, see the appropriate data mapping sections in the BMC AtriumIntegration Engine 7.6.04 User's Guide.

Step 3 Create a data exchange to control the execution, direction, and other characteristicsof your data transfers.

For instructions, see the data exchange section of the BMC Atrium IntegrationEngine 7.6.04 User's Guide.


24/146




25/146


Chapter

2 Understanding thedevelopment environmentThe Adapter Development Kit (ADK) can reside on any system that meets therequirements of the development environment.

The following topics are provided:

Code requirements (page 26)

Compiler requirements (page 26)

Compiling an adapter template on UNIX (page 26)

Description of installed files (page 27)


26/146



Code requirements

The following code requirements apply to all development platforms:

The code generation must be set to multithreaded.

On Microsoft Windows, the ADK class libraries are coded in Microsoft VisualC++ .NET 2003.

Compiler requirements

This section provides a list of platforms and their compatible compilers that can beused for compiling an adapter.

The compiler requires the following platforms:

Windows—Must be compiled using Microsoft Visual C++ .NET 2003, runningon Windows 2003.

UNIX—Must be compiled with one of the following 64-bit compilers:

Sun™ Solaris™ 9 - Sun Studio™ 11 or later

HP-UX 11.11 - ANSI C++ A.03.73

HP-UX Itanium 11.23 ia64 - HP aCC++ Compiler C.05.55

IBM AIX® 5.3 - Visual Age 9.0

Linux® - GCC 4.2.1

Compiling an adapter template on UNIX

Use the following steps to compile an adapter template on a UNIX computer.

To compile an adapter template on UNIX

1 From the BMCAtriumIntegrationEngineInstallationDir/devkit/example/template directory, export the ADK environment variable to see theBMCAtriumIntegrationEngineInstallationDir/devkit directory.

2 Change the compilers for the respective environments in themakefile.unix.samp file as specified:

Solaris: Sun Studio 11

HP-UX 11.11: ANSI C++ A.03.73

HP-UX 11.23: HP aCC++ Compiler C.05.55

AIX: Visual Age 9.0

Linux: GCC 4.2.1


27/146


Description of installed files

3 Run the following commands from the command line for the respectiveenvironments.

Table 2-1: Commands to compile an adapter template on UNIX


When you install the ADK, you install the following files:

Class library files

Header files

Library files

Binary files

Adapter template files

Sample flat file adapter files

Installation control file

Installing the ADK creates a series of directories under theBMCAtriumIntegrationEngineInstallationDir\devkit directory. If youinstalled in the default location, the directory structure is as shown in Table 2-2.

Operating system Command to compile an adapter template

Solaris gmake –f Makefile.unix.samp SOLARIS=1GETARCH=solsp64

HP-UX 11.11 gmake –f Makefile.unix.samp HPUX=1 GETARCH=hppa64

HP-UX 11.23 gmake –f Makefile.unix.samp HPUX=1 GETARCH=hpia64

AIX gmake –f Makefile.unix.samp AIX=1 GETARCH=aixp64

Linux gmake –f Makefile.unix.samp LINUX=1 GETARCH=lx64

Table 2-2: Directory structure of the ADK (part 1 of 2)

Directory or file name Description Windows UNIX

BMCAtriumIntegrationEngineInstallationDir\devkit (Windows)

BMCAtriumIntegrationEngineInstallati

onDir/adk (UNIX)

Overall installation directory Yes Yes

bin

release

Binary files Yes

Yes

Yes

No

example

flat file

template

Sample adapters Yes

Yes

Yes

Yes

Yes

Yes


28/146



The files contained in each directory installed under theBMCAtriumIntegrationEngineInstallationDir\devkit directory aredescribed in the sections that follow.

Class library files

There are three types of class library files:

Header files define all class library objects.

Library files provide all services used by the ADK.

Binary files support the sample flat file adapter.

Header files

The BMCAtriumIntegrationEngineInstallationDir\devkit\include directory contains header files, which are described in Table 2-3.

include Header files required for ADK classlibrary

Yes Yes

lib

Release

Debug

ADK class library Yes

Yes

Yes

Yes

No

Yes

Table 2-2: Directory structure of the ADK (part 2 of 2)

Directory or file name Description Windows UNIX

Table 2-3: ADK header files

Header file Description

adapter.h Defines the entry points for the adapter: InitializeAdapterDLL,TerminateAdapterDLL, CreateInstance, and DeleteInstance.

adkclass.h Defines the adapter base class: CBaseAdapter. This class is the core component for alladapters.

adksprt.h Defines the ADK support classes: CRule, CQuery, CValue, CValueList, CRowsOfValueList, CListOfRule, CListOfRuleWithValue,CRuleWithValue, CQueryWithListOfRuleValue, CQueryWithRowsOfValue. Italso includes the definitions for data types and rule types.

dataexchdef.h Defines the class that provides adapter-specific parameters defined for each data exchange:

CEIEDataExchangeDef.

eiedebug701.h Defines the debug object used to record detailed information about a data exchange:CEIEDebug.

eietrace701.h Defines the base class for debug services: CEIETrace.

jaconv.h Defines symbols for Japanese language. This is included in mbutil.h.

mbutil.h BMC internationalization header file.

templates.h Defines preprocessor symbols used by the ADK. The ADKCLASS_EXPORTS are defined inthis header file.


29/146



Library file

The BMCAtriumIntegrationEngineInstallationDir\devkit\lib\release directory contains a library file that is described in Table 2-4. The Visual C++project file is configured to point to the correct lib directory. The library names

depend on the environment.

Binary file

The BMCAtriumIntegrationEngineInstallationDir\devkit\bin\release directory contains a binary file that is described in Table 2-5. The adkclass76.dll

is required. The Visual C++ project file is configured to point to the correct bin directory.

Adapter template files

TheBMCAtriumIntegrationEngineInstallationDir\devkit\example\template directory contains the template files used to create adapters, which are describedin Table 2-6.

Table 2-4: ADK library file

Library file Description

Release: adkclass76.libDebug: adkclass76d.lib

Class library for the ADK. You should linkthis file with your adapter.

Table 2-5: ADK adapter binary file

Source file Description

Release: adkclass76.dll(Windows)Debug: adkclass76d.dll(Windows)adkclass.so.1 (UNIX)

Class library.

Table 2-6: ADK adapter template files (part 1 of 2)

Template files Description

dllmain.cpp Defines the entry points for the adapter template:InitializeAdapterDLL, TerminateAdapterDLL,CreateInstance, and DeleteInstance.

newadapter.vcproj (Windows)Makefile.unix.samp (UNIX)

Microsoft Visual C++ project file for building an adapter.

newadapter.sln(Windows only)

Microsoft Visual C++ project workspace for an adapter.

newadpr.cpp Adapter template skeleton of the CBaseAdapter class thatimplements the functions required by the ADK interface.


30/146



Sample flat file adapter files

TheBMCAtriumIntegrationEngineInstallationDir\devkit\example\flatfile directory contains the sample flat file adapter files, which are described inTable 2-7.

newadpr.h Defines the adapter template class.

Readme.txt Standard Visual C++ readme file.

Table 2-6: ADK adapter template files (part 2 of 2)

Template files Description

Table 2-7: ADK sample flat file adapter files

Sample files Description

dllmain.cpp Defines the entry points for the sample: InitializeAdapterDLL,

TerminateAdapterDLL, CreateInstance, and DeleteInstance.Ffadapter.vcproj (Windows)Makefile.unix.samp (UNIX)

Microsoft Visual C++ project file for building the sample adapter.

ffadapter.sln(Windows only)

Microsoft Visual C++ project workspace for the sample adapter.

ffadapter.vcproj Microsoft Visual C++ project file for building the sample adapter.

ffadpr.cpp Sample adapter implementation of Cflat fileAdapter, which implements thefunctions required by the ADK interface.

ffadpr.h Defines the sample adapter class.filemgr.cpp File manager for the flat file database used by the sample adapter.

filemgr.h Defines the file manager for the flat file database.

getprivate.cpp GetPrivateProfileString function implementation, which is not available ona UNIX platform using the standard library.

getprivate.h GetPrivateProfileString function declaration.

Makefile.unix.sample Project file you use to build an adapter binary.

misc.cpp Helper functions used by the sample adapter.

misc.h Header file for helper functions defined in misc.cpp.

Readme.txt Standard Visual C++ readme file.


31/146


Chapter

3 Defining the adapter rulesyntaxBefore building an adapter, you must define the rule syntax that your adapter willuse. The rule syntax describes the data to be retrieved from the external data store

and support queries, and collects information needed to initialize your adapter.

NOTE

The AR Mapping Information window is used in many descriptions for illustrativepurposes. You can substitute the CI Class Mapping Information window whereverthe AR Mapping Information window is used because the Primary Key Mapping,the Data Field Mapping, the Response Field Mapping, and the Query tabs (and alltheir fields) behave identically on both windows.


Defining the rule syntax to describe a data value (page 32)

Defining the rule syntax to support queries (page 33)

Configuring adapter initialization parameters (page 33)

Creating an adapter rule syntax list (page 34)


32/146



Defining the rule syntax to describe a datavalue

BMC Atrium Core has its own rule syntax that is used to obtain data from BMCRemedy AR System. Before you begin building an adapter, you must define therule syntax that your adapter will use. You use this syntax in the Data Exchangeapplication to describe the data that you want retrieved from the external datastore.

If your external data store includes tables and views, organize your rule syntaxusing the concept of containers. A container can be a file, a table, or an entire datasource. For ease of use, the AIE service allows the separate definition of a rulecontainer and an item within that container.

NOTE

For SQL Server databases, a container is a table, and the items in the container arecolumns.

You define adapter rule syntax on the Data Field Mapping tab of the AR MappingInformation window. The rules that you specify there are provided to youradapter during a data transfer. The content of each of these rules is inspected before it is placed in the CRule object. For more information about rule syntax, seethe BMC Atrium Integration Engine 7.6.04 User's Guide.

The BMC Atrium Core rule syntax includes the following reserved words:

function|

constant|

process|

targetprocess|

sql|

targetsql|

{ } (curly brackets)

The AIE service defines these reserved words as a set of rules that it recognizes,and it takes action to support these rules. All other rules are passed directly to theadapter.

You can use the words reserved for the AIE service as a part of your adapter rulesyntax.

NOTE

The reserved words must not appear at the beginning of a line of adapter rulesyntax. BMC Atrium Core places no other restrictions on the syntax that you definefor an adapter.


33/146


Defining the rule syntax to support queries

Defining the rule syntax to support queries

You must define the rule syntax that you use to support queries. Queries are usedto limit the data that is transferred.

NOTE For databases that support SQL syntax, queries are supported by where clauses.

You define queries on the Query tab of a data mapping form. The followingcategories of queries are supported:

Key queries limit the records transferred in a data transfer. The AIE serviceprovides key queries to your adapter when asking the adapter for a list of keys.

Row-level queries limit the transfer of data on a row-by-row basis. The AIEservice provides row-level queries to your adapter when asking the adapter to

update or delete a row of data.

Configuring adapter initialization parameters

You must define the database connection information needed to initialize youradapter.

On the Connection Settings tab of the Data Exchanges Information window, youcan define any adapter initialization parameters that are needed to start youradapter.

The AIE service reads all adapter initialization parameters and provides them tothe adapter during initialization. Because these parameters are adapter-defined,they are not validated by BMC Atrium Core.


34/146



Creating an adapter rule syntax list

The Data Exchange application provides an adapter rule syntax list, which allowsusers to select field names from the external data store when creating data

mappings that use this adapter. The adapter rule syntax list is populated byspecifying values on the AIE:VendorFieldNames window as shown in Figure 3-1.

Figure 3-1: AIE:VendorFieldNames window

When you create an installer for your adapter, it is helpful to populate theAIE:VendorFieldNames form during the installation process or provide a utilitythat can accomplish this task.

NOTE

If the rules in the adapter rule syntax list are fixed, it is less critical that you providea utility to populate the AIE:VendorFieldNames window because you need topopulate the list only once.

Table 3-1 provides a description of each field on the AIE:VendorFieldNames window.

Table 3-1: AIE:VendorFieldNames window field descriptions (part 1 of 2)

Field name Description

Vendor Application Must contain the name of the adapter. Enter the registered name of your adapter inthis field.

Table Name Contains the name of the container for the field name. This value is used to populate theExternal Data Store field on the Main tab of the AR Mapping Information window,which lists all adapter-defined container names.


35/146


Creating an adapter rule syntax list

Field Name Contains the rule syntax for a data element used in a data transfer. Field names areobjects such as a column in a table. This field is used to populate the External Data StoreAttributes list on the Primary Key Mapping and Data Field Mapping tabs. This field is

also used to populate the External Data Store Fields list on the Response Field Mappingtab of the AR Mapping Information window.

Field Type Not presently used in creating the adapter rule syntax list.

Field Data Type Specifies the data type for a data element in a data transfer, such as FILE_INT,FILE_FLOAT, and FILE_CHAR.

Is Row Not presently used in creating the adapter rule syntax list.

Table 3-1: AIE:VendorFieldNames window field descriptions (part 2 of 2)

Field name Description


36/146




37/146


Chapter

4 Class library objects used bythe adapterClass library objects, which fall into several categories, provide the servicesrequired by BMC Atrium Core to complete a data transfer. The objects are used to

transmit information between BMC Atrium Core and the adapter.

NOTE

The AR Mapping Information window is used in many descriptions for illustrativepurposes. You can substitute the CI Class Mapping Information window whereverthe AR Mapping Information window is used because the Primary Key Mapping,Data Field Mapping, Response Field Mapping, and Query tabs (and all their fields) behave identically on both windows.


Data exchange objects (page 38)

Data objects (page 43)

List objects (page 43)

Pointer objects (page 45)

Adapter objects (page 46)


38/146



Data exchange objects

Data exchange objects are a group of objects that enable the adapter to initializeand communicate with the external data store. The AIE service creates data

exchange objects using information obtained from the Data Exchange application.The following class objects are data exchange objects:

CEIEDataExchangeDef

CRule

CQuery

CEIEDataExchangeDef object

The CEIEDataExchangeDef object provides certain connection settings andparameters to the adapter. The CEIEDataExchangeDef object is provided to the

adapter when the data transfer is initialized.

The CEIEDataExchangeDef object obtains the following connection settings andparameters for each data transfer:

The name of the data exchange.

The direction of the data exchange (for example, External Data into CMDB).

A Boolean value that indicates if the data exchange is schedule only orevent-driven only.

The connection parameters for the external data store and BMC Remedy

AR System. The installation directory defined in the adapter registry key used by the AIE

service. The installation directory setting is obtained from the system registry onWindows. On UNIX, a -y argument is used to provide the installation directorypath till the /service directory to the BMC Atrium Integration Engine binaries.The adapters reside in the service/bin directory.


39/146



Figure 4-1 shows the CEIEDataExchangeDef parameters on the Main tab of theData Exchanges Information window that are provided to the adapter.

Figure 4-1: Data Exchanges Information window—Main tab

Figure 4-2 shows the CEIEDataExchangeDef parameters that are provided to theadapter from the Connection Settings tab of the Data Exchanges Informationwindow.

Figure 4-2: Data Exchanges Information window—Connection Settings tab

NOTE

If your external data store type is a comma separated value (CSV) flat file or anXML flat file, connection parameters do not appear on the Connection Settings tab.

For more information about the Main and Connection Settings tab on the DataExchange Information window, see the BMC Atrium Integration Engine 7.6.04User's Guide.

Data exchange

name

Boolean

values

Direction of

data exchange

Parameters

Parameter

values


40/146



CRule object

To complete a data transfer, the adapter uses CRule objects to define the data to beobtained. Each CRule object represents the definition of a single data value used ina data transfer. The simplest form of a rule is a field name of a database table.

Each adapter must have its own rule syntax. The AIE service obtains the adapter-defined rule syntax from the Data Exchange application. Rules that apply to theadapter are packaged in CRule objects and passed to the adapter both forvalidation and to define the data to be transferred.

During the initialization phase, each CRule object is verified to make sure that therule correctly identifies an adapter data item. The data type must be set for thevalue that the CRule object represents. The data types are described in Table 4-1.

You create rules using the Primary Key Mapping, Data Field Mapping, and theResponse Field Mapping tabs on the AR Mapping Information window.

Table 4-1: Data types

Data type Description

EIE_CHAR A null-terminated string that requires freeing allocated space. ANULL pointer of this type is equivalent to usingAR_DATA_TYPE_NULL

EIE_DATE A data type that maps to the BMC Remedy AR System Date datatype

EIE_DECIMAL A fixed-point decimal value

EIE_INTEGER A 32-bit signed integer value

EIE_NULL A NULL value

EIE_REAL A 64-bit floating-point value

EIE_TIME A UNIX-style date/time stamp (number of seconds since 00:00:00

UTC, January 1, 1970)EIE_TIME_OF_DAY A field type that maps to the BMC Remedy AR System Time type

field

EIE_ULONG A 32-bit unsigned integer value


41/146



The rules listed on the Primary Key Mapping tab specify the fields that uniquelyidentify a row of data. Each entry listed in the AR Form Fields table and theExternal Data Store Attributes table is packaged as an individual CRule object. TheAIE service provides the entries listed in the Mapped Fields table to the adapter asshown in Figure 4-3 on page 41.

Figure 4-3: AR Mapping Information window—Primary Key Mapping tab

The rules listed on the Data Field Mapping tab of the AR Mapping Informationwindow, shown in Figure 4-4, specify the fields that are transferred during a data

transfer. Each entry listed in the AR Form Fields table and the External Data StoreAttributes table is packaged as an individual CRule object. The AIE serviceprovides the entries listed in the Mapped Attributes table to the adapter.

Figure 4-4: AR Mapping Information window—Data Field Mapping tab

This entry is passed to

the adapter for use

during a data transfer.

These entries are

passed to the adapter

for use during a data

transfer.


42/146



The rules listed on the Response Field Mapping tab of the AR MappingInformation window, shown in Figure 4-5, specify the fields that are transferred inresponse to a record being added or updated during an exchange. Each entry listedin the AR Form Fields table and the External Data Store Fields table is packaged asan individual CRule object. The AIE service provides the entries listed in the

Mapped Attributes table to the adapter.

Figure 4-5: AR Mapping Information window—Response Field Mapping tab

CQuery objectThe CQuery object holds a query obtained from the Query tab of the AR MappingInformation window. The CQuery object is passed to methods in theCBaseAdapter object that use the query to determine which data to include in thedata transfer.

These entries are

passed to the adapter

for use during a data

transfer.


43/146


Data objects

Figure 4-6 on page 43 shows a CQuery object provided by the AIE service to theadapter.

Figure 4-6: AR Mapping Information window—Query tab

Data objects

Data objects are a class of objects that enable the implementation of data transfers.

This class appears on the parameter list of the member functions. The ADK has oneData object: CValue.

The CValue object represents a single data value used in a data transfer. TheCValue object is passed to the adapter when a value is supplied in functionparameter lists. The CValue object is created by an adapter when a value isrequested.

List objects

List objects are classes of objects that combine either multiple data objects, multipledata exchange objects, or both data objects and data exchange objects. List objectsare grouped as lists when passed to the adapter as parameters. This class appearson the parameter list of the member functions.

List objects are simple Visual C++ list objects that are defined in the standardVisual C++ library.

The following class objects are list objects:

CValueList

CRowsOfValueList

The AIE service gives

the CQuery object

SALARY>200 to the

adapter.


44/146



CListOfRule

CListOfRuleWithValue

CValueList object

The CValueList object represents the values of multiple fields or a row of datavalues. For example, keys can be composed of multiple field values. The ADKinterface represents a key as a CValueList object. This key contains one or moreCValue objects.

CRowsOfValueList object

The CRowsOfValueList object is a list of multiple CValueList objects. TheCRowsOfValueList object represents the values of multiple groups of fields ormultiple rows of data values. For example, when the adapter is called to create a

list of keys to be processed, the CRowsOfValueList object is used to represent thelist of keys.

CListOfRule object

The CListOfRule object is a list of multiple CRule objects. For example, a key can be composed of multiple fields. The ADK interface always represents thedefinition of a key as a CListOfRule object. Figure 4-7 shows a CListOfRule object.

Figure 4-7: AR Information window—Data Field Mapping tab

The ADK interface

represents the definition

of a key as a CListOfRule

object (a list of multipleCRule objects) such as

CRule: FNAME, CRule:

SALARY, and CRule:

GENDER.


45/146


Pointer objects

CListOfRuleWithValue object

The CListOfRuleWithValue object is a list of multiple CRule objects and theirassociated CValue objects. That is, the CListOfRuleWithValue object contains thedefinition of the data as well as its value. The ADK interface uses this object on all

calls to get a record, create a new record, update a record, or delete a record.

Pointer objects

Pointer objects are a class of objects that point to a data transfer object and itsassociated data object. This class appears on the parameter list of the memberfunctions.

The following class objects are pointer objects:

CRuleWithValue

CQueryWithListOfRuleValue

CQueryWithRowsOfValue

CRuleWithValue object

The CRuleWithValue object points to a CRule object. The CRuleWithValue objectis passed to the adapter when a rule and its value are supplied in functionparameter lists.

Depending on the function being called, the CValue object can be initialized as anempty data value. With function calls, in which the value is passed to the adapter,the CValue object has a data value. With function calls in which the adapter isasked to supply a value, the CValue object is empty, and the adapter updates theobject with the value obtained from the external data store.

CQueryWithListOfRuleValue object

The CQueryWithListOfRuleValue object points to a CQuery object and itsassociated CListOfRuleWithValue object. CQueryWithListOfRuleValue holdsdata values that are substituted in the query.

CQueryWithRowsOfValue objectThe CQueryWithRowsOfValue object points to a CQuery object and the associatedCRowsOfValueList object. CQueryWithRowsOfValue holds data values that aresubstituted in the query.

8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Ada

bmc atrium integration engine 7.6.04 - aie adapter development kit

Documents