AIE Developer

BMC Atrium Integration Engine 7.1.
00
Adapter Development Kit Developers Guide
August 2007
www.bmc.com
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 INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA Telephone 713 918 8800 or 800 841 2031 Fax 713 918 8000
Outside United States and Canada

Telephone (01) 713 918 8800 Fax (01) 713 918 8000
If you have comments or suggestions about this documentation, contact Information Development by email at doc_feedback@bmc.com. Copyright 19992007 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. DB2 is a registered trademark of International Business Machines Corporation. IBM is a registered trademark of International Business Machines Corporation. ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. Oracle is a registered trademark of Oracle Corporation. 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 Legend

U.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.
Customer Support
You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer Support 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 at http://www.bmc.com/support_home. From this website, you can:
s s s s s s s
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 or send an email message to customer_support@bmc.com. (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 Software

Have the following information available so that Customer Support can begin working on your issue immediately:
s
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
s s s
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
Contents
Preface Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration Engine documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC Atrium CMDB documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 1 Understanding Integration Engine 11 11 12 12 12 14 17 18 19 20 20 21 21 22 22 23 24 25 27 28 28 28 29 31 31 33 34 34 35 35 36
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration Engine components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Exchange application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration Engine service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Request interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Development Kit interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The data transfer process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The initialization phase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The processing phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2 Understanding the development environment
Code requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compiler requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Description of installed files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Class library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter template files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample flat file adapter files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 3 Defining adapter rule syntax
Defining the rule syntax to describe a data value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration Engine reserved words for data value rule syntax . . . . . . . . . . . . . . . Defining the rule syntax to support queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring adapter initialization parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an adapter rule syntax list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
Chapter 4
Class library objects used by the adapter
39
Data exchange objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 CEIEDataExchangeDef object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 CQuery object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 List objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 CValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 CRowsOfValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 CListOfRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 CListOfRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Pointer objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 CRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 CQueryWithListOfRuleValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 CQueryWithRowsOfValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Adapter objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 dllmain object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 CQuery object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Chapter 5 Methods required by the adapter 51
Preparing the adapter template development environment . . . . . . . . . . . . . . . . . . . . . 52 Creating an adapter-derived CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . 54 Setting your adapter name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Implementing initialization methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Implementing database connection methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Implementing rule validation methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Getting and validating a CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Setting the data type of the value described in the CRule object . . . . . . . . . . . . . . 59 Renaming the CNewRule object in the adapter template . . . . . . . . . . . . . . . . . . . . 59 Implementing key list creation methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Creating a key list without a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Creating a key list with a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Implementing the data retrieval method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Implementing the data creation method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Implementing the data update method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Implementing data deletion methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Implementing transaction processing methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Implementing command support methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Developers Guide
Chapter 6
Packaging an adapter
69 70 70 71 71 71 72 72 72 73 75 76 76 77 77 77 78 79
Registering an adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registering an adapter on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registering an adapter on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Licensing an adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building an installer for the developed adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample data exchanges and data mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Documenting the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Test information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 7 Logging and debugging
Log and debug tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Recording log messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the CBaseAdapter object to record log events . . . . . . . . . . . . . . . . . . . . . . . . Recording debug events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the CBaseAdapter object to record debug events . . . . . . . . . . . . . . . . . . . . . Using the CRule object to record debug events . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix A Class library reference
CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 CBaseAdapter::CBaseAdapter (constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 CBaseAdapter::~CBaseAdapter (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 CBaseAdapter::CloseConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 CBaseAdapter::CreateNewQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 CBaseAdapter::CreateNewRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 CBaseAdapter::CreateQueryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 CBaseAdapter::CreateRuleValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 CBaseAdapter::DeleteRuleValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 CBaseAdapter::DoCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 CBaseAdapter::GetKeyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 CBaseAdapter::GetLicenseString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 CBaseAdapter::GetProductName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 CBaseAdapter::GetRuleAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 CBaseAdapter::GetRuleValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 CBaseAdapter::GetStatusMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 CBaseAdapter::Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 CBaseAdapter::OpenConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 CBaseAdapter::SetLogMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 CBaseAdapter::SetStatusMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 CBaseAdapter::StartTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 CBaseAdapter::StopTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 CBaseAdapter::SupportTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 CBaseAdapter::Terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 CBaseAdapter::UpdateRuleValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 CBaseAdapter::ValidateQualifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Contents
CEIEDataExchangeDef object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 CEIEDataExchangeDef::GetDataExchangeName . . . . . . . . . . . . . . . . . . . . . . . . . . 108 CEIEDataExchangeDef::GetFirstVenConfigParam. . . . . . . . . . . . . . . . . . . . . . . . . 109 CEIEDataExchangeDef::GetVenConfigParamAt . . . . . . . . . . . . . . . . . . . . . . . . . . 110 CEIEDataExchangeDef::GetVenConfigParamLength . . . . . . . . . . . . . . . . . . . . . . 111 CEIEDataExchangeDef::IsDirectionARDataIntoVendor . . . . . . . . . . . . . . . . . . . . 112 CEIEDataExchangeDef::IsDirectionVendorDataIntoAR . . . . . . . . . . . . . . . . . . . . 112 CRule object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 CRule::CRule (copy constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 CRule::~CRule (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 CRule::CRule (new rule constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 CRule::DeepClone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 CRule::GetContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 CRule::GetEIEDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 CRule::GetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 CRule::GetRuleString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 CRule::GetVenDataType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 CRule::IsValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 CRule::SetContainer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 CRule::SetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 CRule::SetRuleString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 CRule::SetValidity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 CRule::SetVenDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 CQuery object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 CQuery::CQuery (copy constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 CQuery::~CQuery (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 CQuery::CQuery (new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 CQuery::GetContainer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 CQuery::GetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 CQuery::GetQueryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 CQuery::IsValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 CQuery::SetContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 CQuery::SetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 CQuery::SetQueryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 CQuery::SetValidity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 CValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 CValue::CValue (copy constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 CValue::~CValue (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 CValue::CValue (empty constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 CValue::GetDecimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 CValue::GetInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 CValue::GetReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 CValue::GetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 CValue::GetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 CValue::GetType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 CValue::GetULong. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 CValue::IsNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 CValue::SetDecimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 CValue::SetInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 CValue::SetNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
8 Developers Guide
CValue::SetReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 CValue::SetString. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 CValue::SetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 CValue::SetULong . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 CValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 CRowsOfValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 CListOfRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 CListOfRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 CRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 CRuleWithValue::CRuleWithValue (constructor) . . . . . . . . . . . . . . . . . . . . . . . . . 147 CRuleWithValue::CRuleWithValue (copy constructor) . . . . . . . . . . . . . . . . . . . . 148 CRuleWithValue::~CRuleWithValue (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . 148 CRuleWithValue::GetRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 CRuleWithValue::GetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 CRuleWithValue::SetRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 CRuleWithValue::SetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 CQueryWithListOfRuleValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 CQueryWithListOfRuleValue::CQueryWithListOfRuleValue (copy constructor) . 152 CQueryWithListOfRuleValue::CQueryWithListOfRuleValue (destructor) . . . . 152 CQueryWithListOfRuleValue::CQueryWithListOfRuleValue (new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 CQueryWithListOfRuleValue::GetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 CQueryWithListOfRuleValue::GetRuleWithValueList . . . . . . . . . . . . . . . . . . . . . 155 CQueryWithListOfRuleValue::SetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 CQueryWithListOfRuleValue::SetRuleWithValueList . . . . . . . . . . . . . . . . . . . . . 156 CQueryWithRowsOfValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 CQueryWithRowsOfValue::CQueryWithRowsOfValue (copy constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 CQueryWithRowsOfValue::~CQueryWithRowsOfValue (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 CQueryWithRowsOfValue::CQueryWithRowsOfValue (new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 CQueryWithRowsOfValue::GetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 CQueryWithRowsOfValue::GetRowsOfValueList. . . . . . . . . . . . . . . . . . . . . . . . . 159 CQueryWithRowsOfValue::SetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 CQueryWithRowsOfValue::SetRowsOfValueList . . . . . . . . . . . . . . . . . . . . . . . . . 160 Index 163
Contents
10
Developers Guide
Preface
This manual describes how to build adapters that can transfer information between a BMC Remedy Action Request System (AR System) application and an external data store using BMC Atrium Integration Engine (Integration Engine) as the interface.
Audience
This guide is for developers who have a basic understanding of Integration Engine and want to build adapters that can exchange data between two data sources. Knowledge of C++ is essential. You must know how to retrieve data from the external data store and how to use the following BMC products: BMC Remedy Administrator BMC Remedy User BMC Remedy Import
Preface
11
BMC Atrium Integration Engine 7.1.00
Related documentation
This section describes the documentation available for Integration Engine, BMC Atrium Configuration Management Database (BMC Atrium CMDB), and AR System.
Integration Engine documents

The following table shows the Integration Engine documentation. Unless otherwise noted, softcopy documentation is available in the Docs directory of the product DVD, from the Electronic Product Distribution (EPD) site at http:// webapps.bmc.com/epd, and from the Support site at http://www.bmc.com/ support_home.
Title BMC Atrium Integration Engine 7.1.00 Administrators Guide Description Procedures describing how to install, define rules and queries, activate event-driven data exchanges, run and configure the Integration Engine service, log and debug, and to troubleshoot Integration Engine. Audience Format
Administrators Print and PDF
Users and BMC Atrium Integration Procedures describing how to create data Engine 7.1.00 Online Help exchanges and data mappings and to configure Administrators administrative options, available by clicking Help in the product interface. BMC Atrium Integration Combined index of all guides. Engine 7.1.00 Master Index BMC Atrium Integration Information about new features, open issues, Engine 7.1.00 Release Notes and resolved issues. BMC Atrium Integration Procedures and conceptual information about Engine 7.1.00 Users Guide creating data exchanges and data mappings. Everyone Everyone Users
Product Help (available from Help links after installed) Print and PDF Print and PDF Print and PDF
BMC Atrium CMDB documents

The following table shows BMC Atrium CMDB documentation. This documentation is available from the Support site at http://www.bmc.com/ support_home.
Title Document provides Audience Format
BMC Atrium CMDB 2.1.00 Hierarchical diagram of all classes in the Administrators Print and PDF Common Data Model Common Data Model (CDM) including unique Diagram attributes and applicable relationships BMC Atrium CMDB 2.1.00 Information about CMDB concepts and best IT leaders and Concepts and Best Practices practices for planning your BMC Atrium CMDB administrators Guide implementation Print and PDF
12
Developers Guide
Title BMC Atrium CMDB 2.1.00 Data Model Help
Document provides
Audience
Format
Administrators HTML Description and details of superclasses, (product DVD subclasses, attributes, and relationship classes only) for each class. Contains only information about the Common Data Model at first, but can be updated to include information about data model extensions you install.
BMC Atrium CMDB 2.1.00 Information about creating API programs, using Administrators Print and PDF Developers Reference Guide C and web services API functions and data and structures, and a list of error messages programmers BMC Atrium CMDB 2.1.00 Information about installing and configuring Installation and BMC Atrium CMDB, including permissions, Configuration Guide class definitions, reconciliation, and federation BMC Atrium CMDB 2.1.00 Javadoc API Help Information about Java classes, methods, and variables that integrate with BMC Atrium CMDB Administrators Print and PDF
Programmers
HTML (product DVD only)
Administrators Spreadsheet, Mapping Your Data to Mappings of common IT objects to the print and PDF BMC Atrium CMDB 2.1.00 appropriate class in which to store them, whether part of the Common Data Model or an Classes extension. Also includes information about further categorizing instances using key attributes. BMC Atrium CMDB 2.1.00 Combined index of all guides Master Index BMC Atrium CMDB 2.1.00 Online Help Everyone Print and PDF Product Help (available from Help links after installed) Print and PDF
Users and Help for using and configuring BMC Atrium CMDB, available by clicking Help in the product administrators interface Everyone
BMC Atrium CMDB 2.1.00 Information about new features, open issues, Release Notes and resolved issues BMC Atrium CMDB 2.1.00 Information about resolving issues with BMC Troubleshooting Guide Atrium CMDB components, including API, filter, and console error messages and their solutions.
Administrators Print and PDF , programmers, and BMC Support personnel Print and PDF
BMC Atrium CMDB 2.1.00 Information about using BMC Atrium CMDB, Users Users Guide including searching for and comparing CIs and relationships, relating CIs, viewing history, and launching federated data
Preface
13
AR System documents
The following table shows BMC Remedy AR System documentation. This documentation is available from the Support site at http://www.bmc.com/ support_home.
Title Description Audience Format PDF and Print
BMC Remedy Action Request Overview of AR System architecture and features Everyone System 7.1.00: Concepts with in-depth examples; includes information about other AR System products as well as a comprehensive glossary for the entire AR System documentation set. BMC Remedy Action Request Procedures for installing AR System System 7.1.00: Installing BMC Remedy Action Request Topics that are usually only learned when first System 7.1.00: Getting starting to use the system, including logging in, Started searching for objects, and so on. BMC Remedy Action Request Information about the components necessary to System 7.1.00: Form and build applications in AR System, including Application Objects applications, fields, forms, and views. BMC Remedy Action Request Overview of all the workflow information. System 7.1.00: Workflow Objects BMC Remedy Action Request Information about configuring AR System servers System 7.1.00: Configuring and clients, localizing, importing and exporting data, and archiving data. BMC Remedy Action Request Information about the mid tier, including mid tier System 7.1.00: Installing and installation and configuration, and web server Administering BMC Remedy configuration. Mid Tier
Administrators PDF and Print Everyone PDF and Print PDF and Print PDF and Print
Developers
Developers
Administrators PDF and Print Administrators PDF and Print
Administrators PDF and BMC Remedy Action Request Information about integrating AR System with external systems using plug-ins and other products, and Developers Print System 7.1.00: Integrating including LDAP, OLE, and ARDBC. with Plug-ins and ThirdParty Products BMC Remedy Action Request Server administration topics and technical essays System 7.1.00: Optimizing related to monitoring and maintaining AR System and Troubleshooting for the purpose of optimizing performance and troubleshooting problems. Administrators PDF and Print
BMC Remedy Action Request Database administration topics and rules related to Administrators PDF and System 7.1.00Database how AR System interacts with specific databases; Print Reference includes an overview of the data dictionary tables. BMC Remedy Action Request Server administration and procedures for System 7.1.00: Administering implementing a distributed AR System server BMC Remedy DSO environment with the BMC Remedy Distributed Server Option (DSO). BMC Remedy Action Request Flashboards administration and procedures for System 7.1.00: Administering creating and modifying flashboards and BMC Remedy Flashboards flashboards components to display and monitor AR System information. 14 Developers Guide Administrators PDF and Print
Administrators PDF and and Print Programmers
Title
Description
Audience
Format
BMC Remedy Action Request Information about AR System data structures, System 7.1.00: C API C API function calls, and OLE support. Reference BMC Remedy Action Request Quick reference to C API function calls. System 7.1.00: C API Quick Reference
Administrators PDF and and Print Programmers Administrators PDF and and Print Programmers
BMC Remedy Action Request Procedures for installing, configuring, and using the Administrators PDF and System 7.1.00: Administering BMC Remedy Email Engine. Print BMC Remedy Email Engine BMC Remedy Action Request List and expanded descriptions of AR System error Administrators PDF and System 7.1.00: messages. and Print Error Messages Programmers BMC Remedy Action Request Combined index of all books. System 7.1.00: Master Index Everyone PDF and Print PDF and Print
BMC Remedy Action Request Information about new features list, compatibility Everyone System 7.1.00: Release Notes lists, international issues, and open and fixed issues.
Preface
15
16
Developers Guide
Chapter
Understanding Integration Engine

The Integration Engine application allows you to transfer data between an external data store and AR System forms or BMC Atrium CMDB classes. You can use the included adapters for Microsoft SQL Server, Oracle, IBM DB2 UDB, XML, and flat files such as comma-separated value (CSV) files. You can also use the Integration Engine Adapter Development Kit to build your own adapters to meet your organizations specific needs. The following topics are provided: Overview (page 18) Integration Engine components (page 19) The data transfer process (page 22) Performance considerations (page 24)
Chapter 1
17
Overview
With Integration Engine, you can do scheduled bulk data transfers and eventbased integrations initiated by either side. You can also use Integration Engine for initial data load, incremental data transfers, and data synchronization. You can build links between BMC Remedy IT Service Management applications and Enterprise Resource Planning (ERP), Customer Relationship Management, Supply Chain Management, and other enterprise applications. For example, you can use Integration Engine to: 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 Management applications with corporate asset data stored in ERP applications. Synchronize IT data from a discovery application with BMC Atrium CMDB, where it can be reconciled with data from other sources to your production dataset. Figure 1-1 shows how you can transfer data in either direction: from an external data store to an AR System application or BMC Atrium CMDB class, or from an AR System application or BMC Atrium CMDB class to an external data store.
Figure 1-1: Overview of the data transfer process
AR System database External data store
Data object
BMC Atrium Integration Engine
AR System form
CMDB class
During the data transfer, Integration Engine identifies the records to be transferred and performs some or all of the following tasks, depending upon how you have configured your data exchange: Reads records Creates new records Updates records Deletes records
18
Developers Guide
Integration Engine components

Integration Engine has four main components: Data Exchange application (page 20) Integration Engine service (page 20) Event Request interface (page 21) Adapter Development Kit interface (page 21) Figure 1-2 shows how these components work with other Integration Engine components and related objects.
Figure 1-2: Integration Engine components
AR System database or BMC Atrium CMDB
Data Exchange application Application Pending form

AR System APIs CMDB APIs
BMC Atrium Integration Engine
Integration Engine service
Event Request interface (eiexfer)
Adapter Development Kit interface
DB2 adapter
Oracle adapter
SQL adapter
XML adapter
Flat File adapter
?
DB2 database Oracle SQL Server database database XML file Flat file
Other Other Other data store data store data store
Out-of-box adapters
Custom adapters (not included)
Chapter 1
19
Data Exchange application

The Data Exchange application is a group of AR System forms that is available from your AR System home page as the AIE Console link, and you use it to work with these integration objects: A data exchange is the object that you execute to move data with Integration Engine, and a single execution of a data exchange is called a data transfer. A data exchange specifies whether the external data store is the source or the target for a data transfer, which adapter is used, how to connect to the external data store, and the method used to execute the exchange. A data exchange 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 which data is transferred. A data mapping defines data to be transferred. It specifies the external file or database table and the AR System form or BMC Atrium CMDB class between which data is transferred, and defines the primary key that identifies a row of data on either side. A data mapping specifies the fields or attributes to be transferred from the source and maps them to fields or attributes in the target, and specifies any fields or attributes in the source that should be updated when a record in the target is created, updated, or deleted. A data mapping can limit the rows of data to be transferred from the source, updated in the target, and updated in the source by including queries for each of these things. You use a data mapping by associating it with a data exchange. The Data Exchange application also lets you perform the following configuration tasks: Define external data store connection parameters for multiple data exchanges simultaneously. Populate Integration Engine menus with the names of tables and columns from external data stores to simplify the process of creating data mappings. Specify the administrator user and online help path for the application. View the Integration Engine instances you defined at installation time and edit some settings for them. Display version numbers for Integration Engine and related products.
Integration Engine service

The Integration Engine service obtains the defined data exchange from the Data Exchange application and completes the transfer of data by communicating with the adapter specified in the data exchange definition. Adapters are software, either provided by BMC or custom built, that provides access to external data and responds to calls from Integration Engine during a data exchange.
20
Developers Guide
The Integration Engine service can connect to any Windows or UNIX AR System server. It does not need to reside on the same computer as the AR System server or the external data stores, but can be on any computer that is network-connected to both of these. The Integration Engine service runs as a client to the AR System server using the AR System application programming interface (API). For information about the AR System API, see BMC Remedy Action Request System 7.1.00: C API Reference.
Event Request interface

You can execute a data exchange on an event-driven basis using the Event Request interface. Each event-driven request is created as an entry in the Application Pending form on the AR Server where the Data Exchange application is installed. You create an event-driven request by directly creating an Application Pending entry, by using AR System workflow to create the entry, or by invoking the eiexfer utility. The Integration Engine service processes requests at a scheduled interval configured in the eie.cfg file, regardless of which method was used to create the requests. Optionally, the Integration Engine service can handle individual event requests immediately if you enter them through the eiexfer utility.
Adapter Development Kit interface

The Integration Engine Adapter Development Kit (ADK) contains all the components needed to create an adapter. You use the Integration Engine installer to install the ADK components. The ADK components are loaded during installation and placed in a subdirectory of the Integration Engine installation directory. The ADK contains: A class library that defines the interface between the Integration Engine service and an adapter. You can use the class library as a foundation for building your adapters. The class library includes a base adapter class and several supporting classes. The base adapter class implements basic functionality common to all adapters and declares virtual functions. An adapter template, which is a development environment that you can use to create 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 this directory outline the logical structure for the construction of an adapter with comments embedded as guidelines.
Chapter 1
21
A sample flat file adapter, which is an implementation of an adapter for a flat file database. The flat file adapter is a fully functional adapter that transfers data from AR System to a flat file and from a flat file to AR System. The sample adapter is included so you 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 determine what is installed from the Integration Engine installer. After an adapter is complete, you can package it with Integration Engine and then modify the Integration Engine installer to include your adapter.
The data transfer process

When you start Integration Engine, it locates data exchanges by reading entries in the Data Exchange application. When Integration Engine detects a data exchange, the Integration Engine service loads the adapter that is associated with that data exchange. The adapter needs to be licensed before you can run it. You can design the adapter to obtain a license that is specifically issued to it or get a license from a pool of available adapter licenses issued to Integration Engine. If the license comes from a pool of Integration Engine licenses, you can implement further license checking in the adapter to prevent unauthorized use of the adapter. If the adapter is not licensed, a log message is written to the EIE:Log form and the Integration Engine log file indicating that the adapter is not licensed. After the appropriate adapter is located and its license is verified, the adapter is loaded. After this point, there are two phases to a data transfer: the initialization phase where a data exchange is prepared to run, followed by the processing phase where data is transferred.
The initialization phase

The initialization phase prepares a data exchange to run. Data is not actually exchanged until the processing phase, which is described in the next section. In the initialization phase, the Integration Engine service:
a Loads data exchange rules.
The Integration Engine service loads all the rules defined in the Data Exchange application and prepares the C++ objects defined by the Adapter Developer Kit interface. The C++ objects contain the data exchange definition, the data mapping rules, and all adapter-defined configuration parameters and rules.
22
Developers Guide
The data transfer process
b Connects to data stores to validate rules.
The Integration Engine service connects to both the source and target data stores. An AR System form or BMC Atrium CMDB class can serve as either the source or the target. The Integration Engine service does not transfer data at this point, but a connection to both data stores is necessary to validate rules.
c Validates data exchange rules.
The Integration Engine service validates rules owned by Integration Engine. During validation, the Integration Engine service indicates if any errors or warnings were detected and if the rules are ready to be used in a data exchange. At the same time, the adapter is called to validate adapter-owned rules. During validation, the adapter indicates if any errors or warnings were detected and if the rules are ready to be used in a data exchange.
d Disconnects from data sources.
After the rules are validated, the Integration Engine service disconnects from both data sources.
e Starts a thread.
At the end of the initialization phase, the Integration Engine service starts a thread to manage the data exchange process.
The processing phase

In the processing phase, the transfer of data takes place. This phase begins when the data exchange is executed, which can be scheduled or event driven. During the processing phase, the Integration Engine service: Refreshes the data exchange. Before data is exchanged, the Integration Engine service checks the Data Exchange application to determine if any changes were made to the data exchange definition. If changes were made, the Integration Engine service updates the loaded data exchange with the new definition. Starts a separate thread for each data exchange. Each data exchange connects to data stores. The Integration Engine service connects to both the source and target data stores. The Integration Engine service communicates through the AR System API or BMC Atrium CMDB API to pull data out of and push data into those data stores, and through the ADK interface to pull data out of and push data into the external data store.
Chapter 1
23
Locates data to be exchanged. The Integration Engine service obtains a list of keys from AR System or BMC Atrium CMDB and asks the adapter to create a list of keys. The Integration Engine service converts the keys to a common data type (if necessary) and then sorts the keys to make sure that they are in the same order so the key lists can be compared. Transfers data. The Integration Engine service compares the keys and determines from the data exchange definition how new and existing records should be treated. The Integration Engine service decides on a key-by-key basis whether to create, update, or delete records. For each key, adapters can be called to read, write, update, or delete a record. Disconnects from data stores. After all keys are processed, the data transfer is considered complete. The Integration Engine service closes the connection to AR System or BMC Atrium CMDB and asks the adapter to close the connection to the external data store.
NOTE
The thread remains active, as does the adapter, unless the data exchange is deactivated in the Data Exchange application or the Integration Engine service is asked to terminate. In either of those events, the adapter .dll is released and the thread terminates.
Performance considerations
Performance considerations for Integration Engine are difficult to quantify because performance is affected by your network, AR System, the AR System server database, and the external data store load. It is difficult to predict the effect of a specific change on Integration Engine performance, but configuration considerations can influence it. While it is easy to add field mappings or extra rules for each field, remember that each item you add is compared against every record in your database. Seemingly minor additions could have major effects if many records are in your database. For example, if you have 1200 records in your database and the change you make adds an additional half-second to the run time for each record, the data transfer might take an additional 10 minutes to run.
24
Developers Guide
Getting started
Getting started
If you are new to BMC Atrium Integration Engine, you might be wondering where to start to get your first successful data transfer underway. After installing, here are the high-level steps you need to take. See the recommended area of the Integration Engine documentation for specific instructions on each.
To get started using Integration Engine

Step 1 Populate the database field menus for your external data stores using the rule
helpers in the Database Field Menus Console. This greatly simplifies the process of creating data mappings by allowing you to choose field names from a menu instead of manually typing them. For instructions, see the section Using the adapter rule helper utilities in the BMC Atrium Integration Engine 7.1.00 Administrators Guide.
Step 2 Create a data mapping to specify which data should be transferred and where it
should go. For instructions, see the appropriate chapter in the BMC Atrium Integration Engine 7.1.00 Users Guide: Chapter 3, Creating a data mapping for BMC Atrium CMDB CI classes, Chapter 4, Creating a data mapping for BMC Atrium CMDB relationship classes, or Chapter 5, Creating a data mapping for AR System forms.
Step 3 Create a data exchange to control the execution, direction, and other characteristics
of your data transfers. For instructions, see Chapter 2, Creating a data exchange, in the BMC Atrium Integration Engine 7.1.00 Users Guide. These three steps are sufficient to enable a simple data transfer. If you have a more complex situation, you might need to perform more configuration than this.
Chapter 1
25
26
Developers Guide
Chapter
Understanding the development environment

The ADK can reside on any system that meets the requirements of the development environment. The following topics are provided: Code requirements (page 28) Compiler requirements (page 28) Description of installed files (page 28)
Chapter 2
27
Code requirements
The following code requirements apply to all development platforms: The ADK class libraries are coded in Microsoft Visual C++ version 6.0. The code generation must be set to multithreaded.
Compiler requirements
The compiler requires the following environment: WindowsMust be compiled using Microsoft Visual C++ .NET 7.1, running on Windows 2003. UNIXMust be compiled with one of the following compilers: Solaris 8 or later - Sun C++ 5.6 or later HP-UX 11.0 - ANSI C++ A.03.60 / HP ANSI C A.03.60 IBM AIX 5.2 - Visual Age 6.0 Red Hat Enterprise Linux 3 - Gcc 3.2.3
Description of installed files

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
28
Developers Guide
Installing the ADK creates a series of directories under the <aie_install_dir>\devkit directory. If you installed in the default location, the directory structure is as shown in Table 2-1.
Table 2-1: Directory structure of the ADK Directory or file name <aie_install_dir>\devkit (Windows)
<aie_install_dir>/adk (UNIX) bin release example flat file template include lib Release Debug
Description Overall installation directory Binary files Sample adapters
Windows Yes Yes Yes Yes Yes Yes
UNIX Yes Yes No Yes Yes Yes Yes Yes No Yes
Header files required for ADK class Yes library ADK class library Yes Yes Yes
The files contained in each directory installed under the <aie_install_dir>\devkit directory are described 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 <aie_install_dir>\devkit\include directory contains header files, which are described in Table 2-2.
Table 2-2: ADK header files Header file
adapter.h adkclass.h adksprt.h
Description Defines the entry points for the adapter: InitializeAdapterDLL, TerminateAdapterDLL, CreateInstance, and DeleteInstance. Defines the adapter base class: CBaseAdapter. This class is the core component for all adapters. Defines the ADK support classes: CRule, CQuery, CValue, CValueList,
CRowsOfValueList, CListOfRule, CListOfRuleWithValue, CRuleWithValue, CQueryWithListOfRuleValue, CQueryWithRowsOfValue. It also includes the definitions
for data types and rule types.
Chapter 2
29
Table 2-2: ADK header files (Continued) Header file

dataexchdef.h eiedebug701.h eietrace701.h jaconv.h mbutil.h templates.h
Description Defines the class that provides adapter-specific parameters defined for each data exchange: CEIEDataExchangeDef. Defines the debug object used to record detailed information about a data exchange: CEIEDebug. Defines the base class for debug services: CEIETrace. Defines symbols for Japanese language. This is included in mbutil.h. BMC internationalization header file. Defines preprocessor symbols used by the ADK. The ADKCLASS_EXPORTS are defined in this header file.
Library file
The <aie_install_dir>\devkit\lib\release directory contains a library file that is described in Table 2-3. The Visual C++ project file is configured to point to the correct lib directory. The library names depend on the environment.
Table 2-3: ADK library file Library file
Release: adkclass71.lib Debug: adkclass71d.lib
Description Class library for the ADK. You should link this file with your adapter.
Binary file
The <aie_install_dir>\devkit\bin\release directory contains a binary file that is described in Table 2-4. The adkclass71.dll is required. The Visual C++ project file is configured to point to the correct bin directory.
Table 2-4: ADK adapter binary file Source file Description
Release: adkclass71.dll (Windows) Class library. Debug:adkclass71d.dll (Windows) adkclass.so.1 (UNIX)
30
Developers Guide
Adapter template files

The <aie_install_dir>\devkit\example\template directory contains the template files used to create adapters, which are described in Table 2-5.
Table 2-5: ADK adapter template files Template files
dllmain.cpp
Description Defines the entry points for the adapter template: InitializeAdapterDLL, TerminateAdapterDLL, CreateInstance, and DeleteInstance. Microsoft Visual C++ project file for building an adapter.
newadapter.vcproj
(Windows)
makefile.samp (UNIX) newadapter.sln
Microsoft Visual C++ project workspace for an adapter.
(Windows only)
newadpr.cpp newadpr.h Readme.txt
Adapter template skeleton of the CBaseAdapter class that implements the functions required by the ADK interface.
Defines the adapter template class. Standard Visual C++ readme file.
Sample flat file adapter files

The <aie_install_dir>\devkit\example\flatfile directory contains the sample flat file adapter files, which are described in Table 2-6.
Table 2-6: ADK sample flat file adapter files Sample files
dllmain.cpp ff.vcproj (Windows) makefile.samp (UNIX) ffadapter.sln
Description Defines the entry points for the sample : InitializeAdapterDLL, TerminateAdapterDLL, CreateInstance, and DeleteInstance. Microsoft Visual C++ project file for building the sample adapter. Microsoft Visual C++ project workspace for the sample adapter. Microsoft Visual C++ project file for building the sample adapter. Sample adapter implementation of Cflat fileAdapter, which implements the functions required by the ADK interface. Defines the sample adapter class. File manager for the flat file database used by the sample adapter. Defines the file manager for the flat file database. GetPrivateProfileString function implementation, which is not available on a UNIX platform using the standard library. GetPrivateProfileString function declaration. Project file you use to build an adapter binary. Helper functions used by the sample adapter.
(Windows only)
ffadapter.vcproj ffadpr.cpp ffadpr.h filemgr.cpp filemgr.h getprivate.cpp getprivate.h Makefile.unix misc.cpp
Chapter 2
31
Table 2-6: ADK sample flat file adapter files (Continued) Sample files
misc.h Readme.txt
Description Header file for helper functions defined in misc.cpp. Standard Visual C++ readme file.
32
Developers Guide
Chapter
Defining adapter rule syntax
Before building an adapter, you must define the rule syntax that your adapter will use. 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 illustrative purposes. You can substitute the CI Class Mapping Information window wherever the AR Mapping Information window is used because the Primary Key Mapping, the Data Field Mapping, the Response Field Mapping, and the Query tabs (and all their fields) behave identically on both windows. The following topics are provided: Defining the rule syntax to describe a data value (page 34) Defining the rule syntax to support queries (page 35) Configuring adapter initialization parameters (page 35) Creating an adapter rule syntax list (page 36)
Chapter 3 Defining adapter rule syntax
33
Defining the rule syntax to describe a data value

Integration Engine has its own rule syntax that is used to obtain data from AR System. Before you begin building an adapter, you must define the rule syntax that your adapter will use. You use this syntax in the Data Exchange application to describe the data that you want retrieved from the external data store. If your external data store includes tables and views, then organize your rule syntax using the concept of containers. A container can be a file, a table, or an entire data source. For ease of use, the Integration Engine service allows the separate definition of a rule container and an item within that container.
NOTE
For SQL Server databases, a container is a table, and the items in the container are columns. You define adapter rule syntax on the Data Field Mapping tab of the AR Mapping Information window. The rules that you specify there are provided to your adapter during a data transfer. The content of each of these rules is inspected before it is placed in the CRule object. See the BMC Atrium Integration Engine 7.1.00 Users Guide for more information about rule syntax.
Integration Engine reserved words for data value rule syntax

The Integration Engine rule syntax includes the following reserved words:
function| constant| process| targetprocess| sql| targetsql|
{ } (curly brackets) The Integration Engine service defines these words as a set of rules that it recognizes, and it takes action to support these rules. All other rules are passed directly to the adapter. You can use the words reserved for the Integration Engine service as a part of your adapter rule syntax. They must not, however, appear at the beginning of a line of adapter rule syntax. Other than that, the Integration Engine places no other restrictions on the syntax that you define for an adapter.
34
Developers Guide
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 used to 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. Two categories of queries are supported: Key queries limit the records transferred in a data transfer. The Integration Engine service provides 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 Integration Engine service provides row-level queries to your adapter when asking the adapter to update or delete a row of data.
NOTE
For the Integration Engine, $KEYLIST$ is a reserved word that has special properties when used in query syntax. See the BMC Atrium Integration Engine 7.1.00 Administrators Guide for more information about the $KEYLIST$ reserved word.
Configuring adapter initialization parameters

You must define database connection information needed to initialize your adapter. You define any adapter initialization parameters that are needed to start your adapter on the Connection Settings tab of the Data Exchanges Information window. The Integration Engine service reads all adapter initialization parameters and provides them to the adapter during initialization. Because these parameters are adapter-defined, they are not validated by Integration Engine.
35
Creating an adapter rule syntax list

The Data Exchange application provides an adapter rule syntax list, which allows users to select field names from the external data store when creating data mappings that use this adapter. The adapter rule syntax list is populated by specifying values on the EIE:VendorFieldNames window as shown in Figure 3-1.
Figure 3-1: EIE:VendorFieldNames window
When you create an installer for your adapter, it is helpful to populate the EIE:VendorFieldNames form during the installation process or provide a utility that can accomplish this task.
NOTE
If the rules in the adapter rule syntax list are fixed, it is less critical that you provide a utility to populate the EIE:VendorFieldNames window because you need to populate the list only once. Table 3-1 provides a description of each field on the EIE:VendorFieldNames window.
Table 3-1: EIE:VendorFieldNames window field descriptions Field name Vendor Application Table Name Description The Vendor Application field must contain the name of the adapter. Type the registered name of your adapter in this field. The Table Name field contains the name of the container for the field name. This value is used to populate the External Data Store field on the Main tab of the AR Mapping Information window, which lists all adapter-defined container names.
36
Developers Guide
Creating an adapter rule syntax list
Table 3-1: EIE:VendorFieldNames window field descriptions Field name Field Name Description The Field Name contains the rule syntax for a data element used in a data transfer. Field names are objects such as a column in a table. This field is used to populate the External Data Store Attributes list on the Primary Key Mapping and Data Field Mapping tabs. The field is also used to populate the External Data Store Fields list on the Response Field Mapping tab of the AR Mapping Information window. The Field Type field is not presently used in creating the adapter rule syntax list. The Field Data Type field specifies the data type for a data element in a data transfer, such as FILE_INT, FILE_FLOAT, and FILE_CHAR. The Is Row field is not presently used in creating the adapter rule syntax list.
Field Type Field Data Type Is Row
37
38
Developers Guide
Chapter

Class library objects, which fall into five categories, provide the services required by the Integration Engine to complete a data transfer. The objects are used to transmit information between the Integration Engine and the adapter.
NOTE
The AR Mapping Information window is used in many descriptions for illustrative purposes. You can substitute the CI Class Mapping Information window wherever the 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. The following topics are provided: Data exchange objects (page 40) Data objects (page 45) List objects (page 45) Pointer objects (page 46) Adapter objects (page 47)
Chapter 4
39
Data exchange objects

Data exchange objects are a group of objects that enable the adapter to initialize and communicate with the external data store. The Integration Engine 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 and parameters 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 and parameters 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 or event-driven only. The connection parameters for the external data store and AR System. The installation directory defined in the adapter registry key used by the Integration Engine service. The installation directory setting is obtained from the system registry on Windows. On UNIX, it is obtained from the eie.reg file. Figure 4-1 on page 41 shows the CEIEDataExchangeDef parameters on the Main tab of the Data Exchanges Information window that are provided to the adapter.
40
Developers Guide
Figure 4-1: Data Exchanges Information windowMain tab
Data exchange name
Direction of data exchange Boolean values
Figure 4-2 shows the CEIEDataExchangeDef parameters that are provided to the adapter from the Connection Settings tab of the Data Exchanges Information window.
NOTE
If your external data store type is a comma separated value (CSV) flat file or an XML flat file, then connection parameters do not appear on the Connection Settings tab.
Figure 4-2: Data Exchanges Information windowConnection Settings tab
Parameters
Parameter values
Chapter 4
41
CRule object
To complete a data transfer, the adapter uses CRule objects to define the data to be obtained. Each CRule object represents the definition of a single data value used in a 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 Integration Engine service obtains the adapter-defined rule syntax from the Data Exchange application. Rules that apply to the adapter are packaged in CRule objects and passed to the adapter both for validation and to define the data to be transferred. During the initialization phase, each CRule object is verified to make sure the rule correctly identifies an adapter data item. The data type must be set for the value that the CRule object represents. The data types are described in Table 4-1.
Table 4-1: Data types Data type
EIE_CHAR EIE_DATE EIE_DECIMAL EIE_INTEGER EIE_NULL EIE_REAL EIE_TIME EIE_TIME_OF_DAY EIE_ULONG
Description A null-terminated string that requires freeing allocated space. A NULL pointer of this type is equivalent to using AR_DATA_TYPE_NULL. A data type that maps to the AR System Date data type. A fixed-point decimal value. A 32-bit signed integer value. A NULL value. A 64-bit floating-point value. A UNIX-style date/time stamp (number of seconds since 00:00:00 UTC, January 1, 1970). A field type that maps to the AR System Time type field. A 32-bit unsigned integer value.
You create rules using the Primary Key Mapping, Data Field Mapping, and Response Field Mapping tabs on the AR Mapping Information window. The rules listed on the Primary Key Mapping tab specify the fields that uniquely identify a row of data. Each entry listed in the AR Form Fields table and the External Data Store Attributes table is packaged as an individual CRule object. The Integration Engine service provides the entries listed in the Mapped Fields table to the adapter as shown in Figure 4-3 on page 43.
42
Developers Guide
Figure 4-3: AR Mapping Information windowPrimary Key Mapping tab
This entry is passed to the adapter for use during a data transfer.
The rules listed on the Data Field Mapping tab of the AR Mapping Information window, 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 Store Attributes table is packaged as an individual CRule object. The Integration Engine service provides the entries listed in the Mapped Attributes table to the adapter.
Figure 4-4: AR Mapping Information windowData Field Mapping tab
These entries are passed to the adapter for use during a data transfer.
The rules listed on the Response Field Mapping tab of the AR Mapping Information window, shown in Figure 4-5 on page 44, specify the fields that are transferred in response to a record being added or updated during an exchange. Each entry listed in the AR Form Fields table and the External Data Store Fields table is packaged as an individual CRule object. The Integration Engine service provides the entries listed in the Mapped Attributes table to the adapter.
Chapter 4
43
Figure 4-5: AR Mapping Information windowResponse Field Mapping tab
These entries are passed to the adapter for use during a data transfer.
CQuery object
The CQuery object holds a query obtained from the Query tab of the AR Mapping Information window. The CQuery object is passed to methods in the CBaseAdapter object that use the query to determine which data to include in the data transfer. Figure 4-6 shows a CQuery object provided by the Integration Engine service to the adapter.
Figure 4-6: AR Mapping Information windowQuery tab
The Integration Engine service gives the CQuery object SALARY>200 to the adapter.
44
Developers Guide
Data objects
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 one Data object: CValue. The CValue object represents a single data value used in a data transfer. The CValue object is passed to the adapter when a value is supplied in function parameter lists. The CValue object is created by an adapter when a value is requested.
List objects
List objects are classes of objects that combine either multiple data objects, multiple data exchange objects, or both data objects and data exchange objects. List objects are grouped as lists when passed to the adapter as parameters. This class appears on the parameter list of the member functions. List objects are simple Visual C++ list objects that are defined in the standard Visual C++ library. The following class objects are list objects:
CValueList CRowsOfValueList CListOfRule CListOfRuleWithValue
CValueList object
The CValueList object represents the values of multiple fields or a row of data values. For example, keys can be composed of multiple field values. The ADK interface represents a key as a CValueList object. This key contains one or more CValue objects.
CRowsOfValueList object
The CRowsOfValueList object is a list of multiple CValueList objects. The CRowsOfValueList object represents the values of multiple groups of fields or multiple 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 the list of keys.
Chapter 4
45
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 the definition of a key as a CListOfRule object. Figure 4-7 shows a CListOfRule object.
Figure 4-7: AR Information windowData Field Mapping tab
The ADK interface represents the definition of a key as a CListOfRule object (a list of multiple CRule objects) such as CRule: FNAME, CRule: SALARY, and CRule: GENDOR.
CListOfRuleWithValue object
The CListOfRuleWithValue object is a list of multiple CRule objects and their associated CValue objects. That is, the CListOfRuleWithValue object contains the definition 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 its associated data object. This class appears on the parameter list of the member functions. The following class objects are pointer objects:
CRuleWithValue CQueryWithListOfRuleValue CQueryWithRowsOfValue
46
Developers Guide
Adapter objects
CRuleWithValue object
The CRuleWithValue object points to a CRule object. The CRuleWithValue object is passed to the adapter when a rule and its value are supplied in function parameter lists. Depending on the function being called, the CValue object can be initialized as an empty 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 is asked to supply a value, the CValue object is empty, and the adapter updates the object with the value obtained from the external data store.
CQueryWithListOfRuleValue object
The CQueryWithListOfRuleValue object points to a CQuery object and its associated CListOfRuleWithValue object. CQueryWithListOfRuleValue holds data values that are substituted in the query.
CQueryWithRowsOfValue object
The CQueryWithRowsOfValue object points to a CQuery object and the associated CRowsOfValueList object. CQueryWithRowsOfValue holds data values that are substituted in the query.
Adapter objects
Adapter objects are a class of objects used to define a data transfer. This class appears on the parameter list of the member functions. Four adapter objects define the classes and functions in the ADK. Of these, you must implement the following three adapter objects:
dllmain
The main adapter entry-point function

CBaseAdapter
The adapter object base class

CRule
The rule object, which defines a rule syntax that is used in a data transfer A fourth adapter object is optional:
CQuery
The query object, which is used to limit the data used in a data transfer The template adapter shipped with the ADK has these objects ready to implement. For more information, see Chapter 5, Methods required by the adapter.
Chapter 4
47
dllmain object
The main adapter entry-point function, dllmain, has the entry points that are called by the Integration Engine service to load and initialize an adapter object.
CBaseAdapter object
The CBaseAdapter object defines the adapter itself. This object provides the implementation of the ADK interface needed for the Integration Engine service to communicate with an adapter to complete a data transfer.
CRule object
The CRule object holds the rule syntax obtained from the Primary Key Mapping, Data Field Mapping, and Response Field Mapping tabs on the AR Mapping Information window. You must implement one method in this object, which allows the Integration Engine service to understand the type of data that the object is describing. By implementing this method, the Integration Engine service is able to determine the type of data that the adapter wants for the field that the rule describes. The Integration Engine service can then provide any needed data conversion.
CQuery object
A CQuery object holds a query obtained from the Query tab on the AR Mapping Information window. The CQuery object is passed to methods in the CBaseAdapter object that need to use the query to limit the data that is included in a data transfer. You can derive this class to provide support for query processing.
48
Developers Guide
Adapter objects
Chapter 4
49
50
Developers Guide
Chapter
Methods required by the adapter

Methods are required to build an adapter in the adapter template development environment. Code examples are provided for certain methods. An adapter is built in stages, each of which should be independently tested during development. The methods discussed in this section are described in detail in Appendix A, Class library reference. The methods are listed under the CBaseAdapter object.
NOTE
The AR Mapping Information window is used in many descriptions for illustrative purposes. You can substitute the CI Class Mapping Information window wherever the AR Mapping Information window is used because the Primary Key Mapping, the Data Field Mapping, the Response Field Mapping, and the Query tabs (and all their fields) behave identically on both windows. The following topics are provided: Preparing the adapter template development environment (page 52) Implementing initialization methods (page 55) Implementing database connection methods (page 56) Implementing rule validation methods (page 57) Implementing key list creation methods (page 60) Implementing the data retrieval method (page 63) Implementing the data creation method (page 64) Implementing the data update method (page 65) Implementing data deletion methods (page 66) Implementing transaction processing methods (page 67) Implementing command support methods (page 68)
Chapter 5 Methods required by the adapter
51
Preparing the adapter template development environment

The adapter template development environment is configured so you can begin building your adapter. To build an adapter, you must use three major objects in the adapter template: the dllmain.cpp object, the CBaseAdapter object, and the CRule object. The CQuery object is optional.
dllmain
The dllmain object has entry points that are called by the Integration Engine service to load and initialize an adapter object.
CBaseAdapter
The CBaseAdapter object is the adapter object itself. This object provides the implementation of the methods needed for the Integration Engine service to communicate with an adapter to complete a data transfer. These methods are illustrated in Figure 5-1 on page 53.
CRule
You must implement the DeepClone() method in this object. To allocate the new object, initialize it with the current field. By implementing this method, the Integration Engine service in multithreading mode can Deep Clone the Rule Objects without any memory issues for each thread.
CQuery
If you implement your own query class extended from the CQuery class, then you must implement DeepClone() method for this class. By implementing this method, the Integration Engine service in multithreading mode can DeepClone the query objects without any memory issues for each thread.
52
Developers Guide
Preparing the adapter template development environment
Figure 5-1: Sample interaction between Integration Engine and an adapter

BMC Atrium Integration Engine Adapter
Find a data exchange to be processed and verify that the adapter is registered.
1 2
Load the Adapter

Initialize the adapter InitializeAdapterDLL
Initialization Phase
Create a CBaseAdapter object Initialize the CBaseAdapter object For each configured rule: Get rule object Open database connection Get rule attributes Close database connection CreateNewRule OpenConnection GetRuleAttributes CloseConnection CreateInstance Initialize
CBaseAdapter
Processing Phase
Open database connection Create key list For each key in the list: Start transaction Get data values Stop transaction Close database connection StartTransaction GetRuleValues StopTransaction CloseConnection OpenConnection GetKeyList
Terminate Processing Phase

Clean up CBaseAdapter Remove CBaseAdapter object Clean up the adapter Terminate DeleteInstance TerminateAdapterDLL
Remove the Adapter

Initialize the adapter InitializeAdapterDLL
If you installed the ADK in the default location, the adapter template file, newadapter.sln, is located in one of the following directories: On Windows:
<aie_install_dir>\devkit\example\template
On UNIX:
<aie_install_dir>/adk/example/template
53
If you are using Visual Studio .Net, open the adapter template file, newadapter.sln. The adapter project in this file is prepared for development. All required header files and source files are included and all paths are set for required libraries and shared header files.
Creating an adapter-derived CBaseAdapter object

The main object for your adapter is the CBaseAdapter object, which implements the methods defined by the ADK interface. All adapters derive a class based on the CBaseAdapter object. The adapter provides a derived CBaseAdapter object that uses the class name CNewAdapter. You can change this to a name that is more meaningful to you.
To rename the CBaseAdapter object in the Adapter Template

1 Open the newadpr.h file.
This file is the header file that defines the adapter class.
2 Change all occurrences of CNewAdapter to the name you have chosen for your
adapter class.
3 Save your changes. 4 Close the newadpr.h file. 5 Open the newadpr.cpp file.
This file is the source code file where all methods in the adapter class are implemented.
6 Change all occurrences of CNewAdapter to the name you have chosen for your
adapter class.
7 Save your changes. 8 Close the newadpr.cpp file. 9 Open the dllmain.cpp file.
This file is the source code file where all adapter entry points are defined.
10 In the CreateInstance method, change CNewAdapter to the name you have chosen
for your class.

11 Save your changes. 12 Close the dllmain.cpp file.
54
Developers Guide
Implementing initialization methods
Setting your adapter name

The adapter template has a character string constant that is used to return a descriptive name for your adapter. The name is used by Integration Engine in log-file and debug messages to identify your adapter.
To set the character string used to identify your adapter

1 Pick a name to identify your adapter. 2 Open the newadpr.h file.
This is the header file that defines the adapter class.

3 Locate the following line of code:
#define PRODUCT_NAME "New Adapter"
4 Change "New Adapter" to the name that you have chosen for your adapter. 5 Save your changes. 6 Close the newadpr.h file. 7 Set the name of your adapter.dll file.
The adapter template generates a .dll name of newadpr.dll. You can change this name to the name of your choice. If you are using Visual C++, open the project settings and change all references of newadpr.dll to the name you have chosen for your .dll.
8 Build your adapter.
At this point, your adapter should be initialized to the name you have chosen. To verify that all references have been correctly modified, compile and link your adapter. You should not receive any error or warning messages. If any errors or warnings are listed, correct the errors before you continue.
Implementing initialization methods

The adapter is initialized in preparation for a data transfer: When an adapter is loaded. When a data exchange is modified. When an adapter is terminating or any time you have modified a data exchange, the adapter is called to clean up any resources used during the data transfer.
To initialize the adapter

1 Implement the Initialize method in your adapter object.
This method is called to prepare the adapter for a data transfer. This method is called once when the adapter is loaded. It is not called again unless you have modified the data exchange.
55
During the initialization phase, adapter configuration parameters defined on the Connection Settings tab of the Data Exchanges Information window are validated by this method. The return from the Initialize method is an integer value that indicates the success or failure of the functionality as shown in Table 5-1.
Table 5-1: Return values for connection methods Return values for connection methods
ADK_OK (0) ADK_WARNING (1) ADK_ERROR (2)
Description Returned if the method completed successfully. Returned if the method completed successfully, but a warning was written to the debug file. Returned if an error was detected.
2 Implement the Terminate method in your adapter object.
This method is called when a data exchange has changed or when the Integration Engine service is terminating. This method should free any resources needed for the definition of a data exchange. If this method is being called because a data exchange has changed, the Initialize and GetRuleAttributes methods are called to prepare the new definition. The return from the Terminate method is an integer value that indicates the success or failure of the functionality. Table 5-1 describes these return values.
NOTE
If any warnings or errors occur when the Initialize and Terminate methods are called during a data transfer, make sure they are recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
Implementing database connection methods

If your external data store is DB2, SQL Server, or Oracle, the Integration Engine service opens a connection to the database at the start of a data transfer and closes it when the data transfer completes.
To connect to the adapter data source

1 Implement the OpenConnection method in your adapter object.
This method enables your adapter to establish a connection to your external data store. The Integration Engine service calls OpenConnection at the start of a data transfer and CloseConnection when the data transfer finishes. The return from the OpenConnection method is an integer value that indicates the success or failure of the functionality. Table 5-1 describes these return values.
56
Developers Guide
Implementing rule validation methods
2 Implement the CloseConnection method in your adapter object.
In the CloseConnection method, your adapter must disconnect from your data source. The Integration Engine service calls OpenConnection at the start of a data transfer and CloseConnection at the end of the data transfer. Any resources necessary while a connection is open are freed by the CloseConnection method. The return from the CloseConnection method is an integer value that indicates the success or failure of the functionality. Table 5-1 on page 56 describes these return values.
NOTE
If any warnings or errors occur when the OpenConnection and CloseConnection methods are called during a data transfer, make sure they are recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
3 Build and test your adapter.
During this phase, you can test all the configuration parameters defined in the initialization phase. You should be able to see the debug file and make sure the debug instructions identify any errors in the external data store configuration and initialization of the adapter.

This section describes procedures you should complete to implement rule validation methods.
Getting and validating a CRule object

The initialization phase of a data transfer is intended to validate the rules of a data exchange. A data transfer cannot run until all rules are valid.
To get and validate a CRule object

1 Implement the CreateNewRule method in your adapter object.
This method returns the CRule object. The Integration Engine service calls this method to get a new object for each rule describing a data value. The Integration Engine service keeps these rule objects until a data exchange changes. The return from the CreateNewRule method is the new CRule object that you created.
2 Implement the GetRuleAttributes method in your adapter object.
57
This method is called with a list of CRule objects. Each object holds one of the adapter-defined rules from the Data Exchange application. GetRuleAttributes validates the rule syntax and sets the attributes for the list of rules passed to this method. Attributes are information such as the data type, the maximum length of the data, and any limits you might need during processing.
GetRuleAttributes
is called while a connection to the database is active.
If a warning or error is detected for any rule during validation, you should mark the CRule object as invalid. This is important as it allows the Integration Engine service to complete the rule validation process. Any methods owned by Integration Engine that have embedded adapter rules need to know if the rule object is valid. Recording errors also allows the Integration Engine service to create a detailed debug log that lists any rules that have errors. The following code sample shows the GetRuleAttributes method:
SetValidity(true); SetVenDataType( ...data type code and length); SetValidity(false); SetErrMsg(Rule not in container);
The return from the GetRuleAttributes method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
NOTE
If any warnings or errors occur when the CreateNewRule and GetRuleAttributes methods are called during a data transfer, make sure they are recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
At this point, your adapter has all the logic needed for validating the rules and identifying the data that is used in a data transfer. You can test all the rule validation based on the rule syntax that you defined in the initialization phase. You should be able to see the debug file and verify that your debug instructions identify any errors in the rule syntax for the adapter.
58
Developers Guide
Setting the data type of the value described in the CRule object
You should always validate your rule objects and also set the data type of those objects, which allows the Integration Engine service to exchange data of different data types.
To set the data type of the value described by the CRule object
1 Implement the GetEIEDataType method for each CRule object.
Set the data type of the adapter data object described by the CRule object to the Integration Engine data type code that most closely matches it. Do not attempt to decide how the field is used. Setting the data type information is critical to a successful data transfer. The data type identified by this method allows the Integration Engine service to exchange data in the correct format and provide any required data conversion to get the data into the correct data type. The return from the CRule::GetEIEDataType method is the data type.
Renaming the CNewRule object in the adapter template

The ADK interface base class for rule objects is CRule. The Integration Engine service encapsulates each rule entered on the AR Mapping Information window in a CRule object. The Adapter Template provides a derived CRule object that uses the class name CNewRule.
To rename the CNewRule object in the adapter template

1 Open the newadpr.h file.
This is the header file that defines the adapter class.

2 Change all occurrences of CNewRule to the name you have chosen for your adapter
class.
3 Save your changes. 4 Close the newadpr.h file. 5 Open the newadpr.cpp file.
This is the source code file where all methods in the adapter class are implemented.
6 Change all occurrences of CNewRule to the name you have chosen for your adapter
class.
7 Save your changes. 8 Close the newadpr.cpp file.
59
Implementing key list creation methods

The Integration Engine service manages a data transfer by obtaining a list of key values from both AR System and the adapter. The list of key values identifies the data that exists in the external data store and is used in the data transfer. A key is a ClistOfRule object, which is a list of one or more CRule objects. You can use the following types of lists of key value during a data transfer: A list of key values without a query When you create a list of key values without a query, it returns a list of all key values from the database. A list of key values with a query When you create a list of key values with a query, it returns a list of key values that meet a user-defined constraint. A list of key values with a query that supports the $KEYLIST$ reserved word When you create a list of key values with a query that supports the $KEYLIST$ reserved word, you allow adapter-defined queries to use $KEYLIST$. See the BMC Atrium Integration Engine 7.1.00 Administrators Guide for more information.
Creating a key list without a query

The adapter is responsible for obtaining a row of data that exists in the adapter database for a given key. The obtained row of data is a CValue object.
To obtain a list of key values for all records in a data source

1 Implement the GetKeyList method in your adapter object.
GetKeyList is called to obtain a list of key values that are used in a data transfer. The adapter is responsible for obtaining the list of key values from the database and adding each key value as a data row that is returned to Integration Engine for processing.
The following code sample shows the GetKeyList method:

// add the retrieved data values to the listOfKeys parameter for (each row returned) CValueList* pValueList = new CValueList; // This is a simple example that just returns character // values. All data types should be supported in a real case. int fieldIndex = 0; for (int i = 0; i < key.size(); i++) { CValue* pValue = new CValue; pValue->SetString( data at column i in returned row ); pValueList->push_back(pValue); }
60
Developers Guide
Implementing key list creation methods
listOfKeys.push_back(pValueList);
The return from the GetKeyList method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
NOTE
If any warnings or errors occur when the GetKeyList method is called during a data transfer, make sure it is recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
During this phase, you can test the logic for obtaining a list of key values. You should be able to see the debug file and verify that your debug instructions identify any errors in creating the list of key values.
Creating a key list with a query

The query syntax is adapter-defined on the Query tab of the AR Mapping Information window. The Integration Engine service obtains the query string and passes it to the adapter for validation and interpretation. The ADK interface base class for query objects is CQuery. The Integration Engine service encapsulates each query entered on the AR Mapping Information window in a CQuery object. The adapter template provides a CQuery object, and you can create a derived class from this object.
To create a derived CQuery object

1 Create a derived class from the CQuery object, change it to meet your needs, and
give the object a name that is meaningful to you.

2 Implement the CreateNewQuery method in your adapter object.
This method returns the CQuery object that you defined. The Integration Engine service calls this method to get a new object for each query used to limit the data used in a data transfer. The Integration Engine service keeps these query objects until a data exchange changes. The return from the CreateNewQuery method is the new CQuery object that you created.
3 Implement the ValidateQualifier method in your adapter object.
The Integration Engine service obtains the query defined on the Query tab of the AR Mapping Information window and passes it to the ValidateQualifier method for syntax validation.
ValidateQualifier
is not called while a connection to the database is active. If validation requires an open connection, you must establish the connection.
61
The return from the ValidateQualifier method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
To obtain a list of key values limited by a query

1 Implement the CreateQueryString method in your adapter object.
The qualifier string is obtained from the Query tab of the AR Mapping Information window or created using the CreateQueryString method. The return from the CreateQueryString method is the query string.
GetKeyList is called to obtain a list of key values that meet the query qualifications that you defined in your CQuery object. The list of key values is limited only to those values that meet the conditions defined in the CQuery object. The adapter adds each key value as a data row that is returned to Integration Engine for processing.
The return from the GetKeyList method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
NOTE
If any warnings or errors occur when the CreateQueryString and GetKeyList methods are called during a data transfer, make sure they are recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
During this phase, you can test the logic for obtaining a list of keys using a query to limit the data transfer. You should be able to see the debug file and verify that your debug instructions identify any errors in creating the key list.
To obtain a list of key values limited by $KEYLIST$

1 Update the ValidateQualifier method so that it understands the $KEYLIST$
reserved word. The return from the ValidateQualifier method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
When a query contains the $KEYLIST$ reserved word, the Integration Engine service provides the adapter with a list of key values to limit the data transfer. The adapter must use the list of supplied key values to limit the list of keys returned by the adapter during a GetKeyList call. The return from the GetKeyList method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
62
Developers Guide
Implementing the data retrieval method
NOTE
If any warnings or errors occur when the ValidateQualifier method is called during a data transfer, make sure it is recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
During this phase, you can test the logic for obtaining a list of keys. You can now test entering a query using the $KEYLIST$ reserved word to obtain the list of keys. You should be able to see the debug file and verify that your debug instructions identify any errors in creating the key list.
Implementing the data retrieval method

Data retrieval methods obtain data values that are defined for exchange with AR System or BMC Atrium CMDB. Retrieving records to read is the most basic functionality that an adapter must provide. The parameters passed to this method are arrays, with each array element representing a single data mapping in the data exchange being processed. The adapter is free to handle them as individual entities or regroup them as needed for best access to the adapter database.
To get records
1 Implement the GetRuleValues method in your adapter object.
returns the requested data values for a specific key using the rule syntax to determine which data is retrieved from the adapter data source. The adapter is called once for each key that is processed because GetRuleValues retrieves only one record each time it is called.
GetRuleValues
Two parameters are passed to this method: A key listed in the Data Store Field column of the Mapped Fields table on the Primary Key Mapping tab of the AR Mapping Information window and its corresponding data values The rule syntax for the fields in the Data Store Field column of the Mapped Fields table on the Data Field Mapping tab of the AR Mapping Information window The return from the GetRuleValues method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
63
NOTE
If any warnings or errors occur when the GetRuleValues method is called during a data transfer, make sure it is recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
During this phase, you can test the logic for obtaining data values. You should be able to see the debug file and verify that your debug instructions identify any errors in obtaining the data values.
Implementing the data creation method

The CreateRuleValue method enables you to create new rows in the adapter database. When the Integration Engine service determines that a record should be created in the adapter data source, this method is called. The parameters passed to this method are arrays, with each array element representing a single data mapping in the data exchange being processed. The adapter is free to handle them as individual entities or regroup them as needed for the best access to the adapter database.
To create records
1 Implement the CreateRuleValues method in your adapter object.
CreateRuleValues creates a new record in the adapter database. The adapter is called once for each key that is processed.
Two parameters are passed to this method: The rule syntax and the associated data values for the Mapped Fields table on the Primary Key Mapping tab of the AR Mapping Information window and the Data Store Field column in the Mapped Attributes table on the Data Field Mapping tab of the AR Mapping Information window The optional list of rule syntaxes from the Data Store Field column of the Mapped Attributes table on the Response Field Mapping tab of the AR Mapping Information window The return from the CreateRuleValues method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
NOTE
If any warnings or errors occur when the CreateRuleValues method is called during a data transfer, make sure it is recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
2 Build and test your adapter. 64 Developers Guide
Implementing the data update method
During this phase, you can test the logic for creating data values. You should be able to see the debug file and verify that your debug instructions identify any errors in creating the data values.
Implementing the data update method

The UpdateRuleValues method allows you to update data values that are defined for exchange with AR System and BMC Atrium CMDB. When the Integration Engine service determines that a record should be updated in the adapter data source, this method is called. The parameters passed to this method are arrays, with each array element representing a single data mapping in the data exchange that is processed. The adapter is free to handle them as individual entities or regroup them as needed for the best access to the adapter database.
To update records
1 Implement the UpdateRuleValues method in your adapter object.
UpdateRuleValues updates the adapter database for a specific key. The adapter is called once for each key that is processed.
Four parameters are passed to this method: A key listed in the Data Store Field column of the Mapped Fields table on the Primary Key Mapping tab of the AR Mapping Information window and its corresponding data values The rule syntax and the associated data values for the Mapped Fields table on the Primary Key Mapping tab of the AR Mapping Information window and the Data Store Field column in the Mapped Attributes table on the Data Field Mapping tab of the AR Mapping Information window The optional list of rule syntaxes from the Data Store Field column of the Mapped Attributes table on the Response Field Mapping tab of the AR Mapping Information window The optional update queries listed in the Target Row Query field on the Update Query tab on the Query tab of the AR Mapping Information window The return from the UpdateRuleValues method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
NOTE
If any warnings or errors occur when the UpdateRuleValues method is called during a data transfer, make sure it is recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
65
During this phase, you can test the logic for updating data values. You should be able to see the debug file and verify that your debug instructions identify any errors in updating the data values.
Implementing data deletion methods

The DeleteRuleValues method enables you to delete data rows in the adapter database. When the Integration Engine service determines that a record should be deleted in the adapter data source, this method is called.
NOTE
If the Data Exchange application is configured to mark a record for deletion rather than actually deleting it, the UpdateRuleValues method is called rather than the DeleteRuleValues method. The parameters passed to this method are arrays, with each array element representing a single data mapping in the data exchange that is processed. The adapter is free to handle them as individual entities or regroup them as needed for the best access to the adapter database.
To delete records
1 Implement the DeleteRuleValues method in your adapter object.
DeleteRuleValues deletes a record in the adapter database. The adapter is called once for each key that is processed.
Two parameters are passed to this method: A key listed in the Data Store Field column of the Mapped Fields table on the Primary Key Mapping tab of the AR Mapping Information window and its corresponding data values The optional delete queries listed in the Target Row Query field on the Delete Query tab (on the Query tab) of the AR Mapping Information window The return from the DeleteRuleValues method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
NOTE
If any warnings or errors occur when the DeleteRuleValues method is called during a data transfer, make sure it is recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
During this phase, you can test the logic for deleting data values. You should be able to see the debug file and verify that your debug instructions identify any errors in deleting the data values.
66
Developers Guide
Implementing transaction processing methods
Implementing transaction processing methods

Part of the data access process is providing support for transaction processing. A transaction is a wrapper around a data exchange for a single key. Transaction processing allows data access for a single key to be committed (saved) or rolled back (not saved). If the adapter supports transaction processing, the adapter is able to back out any changes made for a specific key, putting the data back to its original state prior to any changes. Support for this feature is optional but recommended.
To save or cancel a transaction

1 Implement the SupportTransaction method in your adapter object.
SupportTransaction
is called to determine if your adapter supports transaction
processing. The return from the SupportTransaction method is true if your adapter supports transaction processing and false if it does not. If this method returns false, go to Implementing command support methods on page 68.
2 Implement the StartTransaction method in your adapter object.
StartTransaction is called at the start of each transaction. When this method is called, the Integration Engine service starts to process a new key.
The return from the StartTransaction method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
3 Implement the StopTransaction method in your adapter object.
StopTransaction is called at the end of each transaction. If the commitChanges parameter is set to true, the changes for the key being processed are made permanent. If the commitChanges parameter is set to false, then any changes are not committed, and the adapter restores the data values to the state they were before the transaction started. This includes deleting records added by the transaction and restoring records deleted by the transaction.
If your database supports the concept of commit and rollback, transaction processing is simply a matter of issuing the commit or rollback command in the StopTransaction method. If not, a record of all changes to the data for an individual record must be maintained and restored if necessary. The return from the StopTransaction method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
NOTE
If any warnings or errors occur when the SupportTransaction, StartTransaction, and StopTransaction methods are called during a data transfer, make sure they are recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
67
During this phase, you can test the logic for implementing transaction processing. You should be able to see the debug file and verify that your debug instructions identify any errors in implementing transaction processing.
Implementing command support methods

You can use the DoCommand method to obtain data values outside the data transfer environment. Adapters can define commands that are run to obtain a data value. Commands do not obtain data values through the normal GetRuleValues mechanism. Rather, commands are stand-alone and must be run independently to obtain a data value. For example, an adapter can define a command to enable you to define an SQL SELECT statement to retrieve a data value that is outside the container being processed in the data transfer. This is useful in a situation where a key from an external data store is needed.
DoCommand
If your adapter supports the concept of commands, you must implement the method.
To handle commands
1 Implement the DoCommand method in your adapter object.
Implementing the DoCommand method requires interpreting the command passed as an input parameter and taking the appropriate action to obtain a data value. Implementation is based entirely on the rule syntax defined by the adapter. The DoCommand is designed to return a single data value, not an array of values. The return from the DoCommand method is an integer value that indicates the success or failure of the functionality. See Table 5-1 on page 56 for descriptions of the return values.
NOTE
If any warnings or errors occur when the DoCommand method is called during a data transfer, make sure it is recorded in the debug file by implementing the SetStatusMessage method. See Chapter 7, Logging and debugging, for more information.
During this phase, you can test the logic needed for running commands. You should be able to see the debug file and verify that your debug instructions identify any errors when running commands.
68
Developers Guide
Chapter
After you create an adapter, you must register and license it so you can use it with the Integration Engine. The following topics are provided: Registering an adapter (page 70) Licensing an adapter (page 71) Building an installer for the developed adapter (page 71) Sample data exchanges and data mappings (page 72) Documenting the adapter (page 72)
Chapter 6
69
Registering an adapter
Integration Engine works only with registered adapters. The Integration Engine service verifies that the adapter is registered before it is used in a data transfer. An adapter is registered with a name that uniquely identifies the adapter to Integration Engine. Adapter names can be any character string that is 64 characters or fewer in length and not already assigned to another adapter. When creating a data exchange, you select the name of the adapter to use from the External Data Store field on the Data Exchanges Information window as shown in Figure 6-1.
Figure 6-1: Data Exchanges Information windowMain tab
Select the registered name of the adapter here.
Registering an adapter on Windows

On Windows, adapters are registered in the Windows system registry. When the Integration Engine service is installed, the following key is created, allowing adapters to create registry entries:
HKEY_LOCAL_MACHINE\SOFTWARE\BMC Software\BMC Atrium Integration Engine\ Server_Name(Port)
Each adapter registry key contains two string values that are used by the Integration Engine service:
InstallDirspecifies the full path where your adapter.dll file (and possibly other resources) are installed. This path is provided to your adapter.
the full path and name of the adapter.dll file. This value is used by the Integration Engine service to locate and load the .dll used to complete the data transfer. Adapters can add anything else to this registry entry, but it is up to the adapter to retrieve the values. The Integration Engine service ignores them.
Adapterspecifies
70
Developers Guide
Licensing an adapter
Registering an adapter on UNIX

On UNIX, adapters are registered in your /etc/eie.reg file, which was created when the Integration Engine service was installed. The file allows the adapter to create registry entries, which look like this:
[Server_Name(Port)_AdapterName]Adapter:/service/bin/fileadpr.so.1 [Server_Name(Port)_AdapterName]InstallDir:/<aie_install_dir>/service
Each adapter registry key contains two string values that are used by the Integration Engine service:
InstallDirspecifies the full path where your adapter shared library (and possibly other resources) are installed. This path is provided to your adapter. Adapterspecifies
the full path and name of the adapter shared library. This value is used by the Integration Engine service to locate and load the shared library used to complete the data transfer.
Adapters can add anything else to this registry entry, but it is up to the adapter to retrieve the values. The Integration Engine service ignores them.
Licensing an adapter
You do not need a license to write and test adapters using the ADK. You must, however, license the adapter when you place the adapter into use in a production environment.
Building an installer for the developed adapter

When building an adapter, you should write an installer that populates the EIE:VendorConfiguration and EIE:VendorFieldNames forms during installation. Even though you can enter the data manually, automating the process reduces the potential for errors and makes the task of installing the adapter easier. See Configuring adapter initialization parameters on page 35 for information about importing data into the EIE:VendorConfiguration form. See Creating an adapter rule syntax list on page 36 for information about importing data into the EIE:VendorFieldNames form. In the Windows and UNIX environments, you must write your own installer.
Chapter 6
71
Removing adapters
You can remove an adapter completely from the Integration Engine environment using one of the following methods: Manually remove the entries made to the Windows registry or to the UNIX eie.reg file. Write a script to remove the entries made to the Windows registry or to the UNIX eie.reg file. You should include an adapter removal script on the same media used to package your adapter. If you use the Windows Add/Remove Programs utility to remove the Integration Engine service, the Windows registry entries are not removed. This protects any entries you make that are not related to the Integration Engine service or the adapter environment.
Sample data exchanges and data mappings

In addition to building an installer for your adapter, you should consider including sample data exchanges and data mappings. Sample data exchanges and data mappings demonstrate how to use your adapter. You should provide one or two sample data exchanges and data mappings with each adapter to illustrate different scenarios.
Documenting the adapter

After you have built an installer for your adapter, you should provide documentation for the administrators who use the adapter. Your documentation serves as an extension to the BMC Atrium Integration Engine 7.1.00 Administrators Guide. Your adapter documentation should include the following items: How to install the adapter Any platform or software dependencies The name of the adapter and the data source with which it integrates The problem the integration is trying to solve Sample integration scenarios to demonstrate the use of the adapter Descriptions of the sample data exchanges, which show how to resolve a scenario using the rule syntax defined for the adapter
72
Developers Guide
Documenting the adapter
Rule syntax, which must not use any Integration Engine reserved words Rule syntax to define data values Rule syntax to define queries Instructions for the use of any utilities provided for dynamically updating the EIE:VendorFieldNames and EIE:VendorConfiguration forms, or instructions on how to update these forms manually Any log or debug messages. For every log or debug message about error situations, explain what needs to be fixed. Troubleshooting tips Limitations or restrictions for using the adapter
Test information
You should provide the organization or individual supporting your adapter with the following information: Test plans that explain in detail the results of any quality assurance or stress testing that you did on your adapter Instructions for setting up a lab environment so the support organization can reproduce customer problems
Chapter 6
73
74
Developers Guide
Chapter
Logging and debugging
The Integration Engine provides logging and debugging facilities in the ADK to log and debug event tracing for adapters. The following topics are provided: Log and debug tracing (page 76) Recording log messages (page 76) Recording debug events (page 77)
Chapter 7 Logging and debugging
75
Log and debug tracing

With the ADK, you can enable log and debug event tracing in adapters. Loggingassists in the long-term management of data exchanges. The logging of events is controlled by the Logging parameter in the eie.cfg file. See the BMC Atrium Integration Engine 7.1.00 Administrators Guide for more information. Debuggingprovides a development and support tool that administrators can use to configure and test data exchanges. The tool provides detailed operational information to diagnose errors in a data transfer.
Recording log messages

Log messages provide helpful information about problems that prevent the adapter from running or being able to transfer data. All log events are recorded both in the Integration Engine log file and the EIE:Log form. All adapters share the logging facility, so it is important to record the name of the adapter from which the message originates. In addition, if the message is about a particular data exchange, you should specify the name of the data exchange.
NOTE
Integration Engine provides language translation for messages that the Integration Engine service records in the log. You are responsible for translating messages that the adapter records. Record any errors that prevent a data transfer from occurring. The log should include information about the following events: Failures that prevent the adapter from running Missing configuration or .dll files Errors in initializing interaction with the database, which can result from missing setup information or a connection failure Record enough information to identify the problem. If extensive detail is required to diagnose the problem, you can record the additional information in the debug file. You should, however, be careful not to over-document errors encountered during processing. It might not be necessary for an adapter to record certain log messages. Reasons for not recording information include: The Integration Engine service records its own messages in the log indicating major errors, and it provides translation of all log messages for internationalization. The log is shared by all data transfers. Overuse can cause it to grow at an accelerated rate, which makes it more difficult to locate information.
76
Developers Guide
Recording debug events
Using the CBaseAdapter object to record log events

Use the CBaseAdapter object method SetLogMessage to set log messages for the Integration Engine service. See CBaseAdapter::SetLogMessage on page 99 for more information about this method. This method records the string passed as a parameter to the log file and the EIE:Log form.
Recording debug events

Debug messages help administrators detect errors in a data transfer. The Integration Engine debug facilities trace all data mapping rule validation and data handling. Each data exchange has its own debug file. The file is assigned the name of the data exchange. For example, if your data exchange is named GetDiskDetail, the debug file is named getdiskdetail.dbg. Because each data exchange has its own file, events recorded in the debug file do not need to indicate the name of the data exchange that is processed. The Integration Engine service logs the order in which requests are processed. To enable the automatic recording of events, each CRule object maintains its own error status and error message. The Integration Engine service uses these status indicators and messages to determine if the rule is valid and also to record error messages in the debug file. The adapter can also record additional information in the debug file. The goal is to provide a debug file that is sufficiently detailed so administrators can use it to analyze and correct problems. Any errors that prevent a data transfer from taking place should be recorded. These errors include the following types: Errors in configuration parameters Specify the configuration parameter and the reason why it is an error. Identify syntax errors as well as missing configuration parameters. Errors during interaction with the database Record as much information as possible explaining why a connection to the database failed, or why a read/write action failed.
Using the CBaseAdapter object to record debug events

Use the CBaseAdapter object method SetStatusMessage to set debug messages for the Integration Engine service. See CBaseAdapter::SetStatusMessage on page 100 for more information about this method. This method records the string passed as a parameter to the debug file. It can also record the string with trace level as input parameters.
Chapter 7 Logging and debugging
77
Using the CRule object to record debug events

In addition to using the SetStatusMessage method to record messages in the debug file, the CRule object has a separate mechanism for recording errors. The CRule object records errors in rules. Rules are used by the Integration Engine service at several points during a data transfer. The CRule object checks the status of each rule at each of these points, and any associated error message is recorded in the debug file during the data transfer.
NOTE
It is critical that you use CRule object debug tracing to record errors in rules. Errors in rules can prevent a data transfer from taking place. If no error messages are provided in the debug file, administrators have no way of diagnosing why the data transfer failed. To activate the automatic debug event tracing for CRule objects, you should define the following methods:
CRule::SetValidity
(bool validity)Sets the validity of the rule. A true response indicates that the rule is valid. A false response indicates that the rule is invalid.
All adapters need to indicate the success or failure of rule validation when the method is called. This method is used to indicate the validation status. When this method is called with a return of false (indicating an error), SetErrMsg should also be called with a text description describing the cause of the error.
GetRuleAttributes CRule::SetErrMsg (char message)Sets an error message indicating why a rule
failed validation. All adapters need to indicate the success or failure of rule validation when the GetRuleAttributes method is called. The Integration Engine service places this text string in the debug file. The text of the message must contain enough information for administrators to determine the cause of the error. If the SetValidity method indicates that the rule is invalid and the SetErrMsg method is not used to provide a comprehensive error message, administrators have no way of knowing why the data transfer failed.
78
Developers Guide
Appendix
Class library reference
The class library is organized by object. Within each object, methods are listed alphabetically. A description, a prototype, input arguments, and return values are provided for each method.
NOTE
The AR Mapping Information window is used in many descriptions for illustrative purposes. You can substitute the CI Class Mapping Information window wherever the 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. The following topics are provided: CBaseAdapter object (page 80) CEIEDataExchangeDef object (page 108) CRule object (page 113) CQuery object (page 123) CValue object (page 131) CValueList object (page 143) CRowsOfValueList object (page 144) CListOfRule object (page 145) CListOfRuleWithValue object (page 146) CRuleWithValue object (page 147) CQueryWithListOfRuleValue object (page 152) CQueryWithRowsOfValue object (page 157)
Appendix A Class library reference
79
CBaseAdapter object
This section describes the methods for the CBaseAdapter object.
CBaseAdapter::CBaseAdapter (constructor)
Initializes the adapter object. Any adapter-specific initialization should be implemented by this method. It is always good practice to initialize any member variables in the constructor.
Required
Default implementation provided by base class.
Prototype
CBaseAdapter()
Input arguments
None
Return values
None
See also
CBaseAdapter::~CBaseAdapter (destructor)
CBaseAdapter::~CBaseAdapter (destructor)
Releases any resources acquired by the adapter object. Any adapter-specific resources should be released by this method.
Required
Prototype
CBaseAdapter::~CBaseAdapter()
Input arguments
None
80
Developers Guide
CBaseAdapter object
Return values
None
See also
CBaseAdapter::CBaseAdapter (constructor)
CBaseAdapter::CloseConnection
Disconnects from the adapter source. Any resources needed only for an open database connection can be released. The Integration Engine service calls OpenConnection when a connection to the external data store is needed. If an error or warning is detected, this method should record a text message with SetStatusMessage indicating the error. The message is intended to help users diagnose the cause of the problem. Messages are written to the debug file by calling the SetStatusMessage or AppendStatus methods in CBaseAdapter. If the call to SetStatusMessage shows a critical error, it is written to the log file. Be sure to limit what is written to the log file. See Chapter 7, Logging and debugging, for more information about what type of events should be recorded.
Required
Adapter must implement this method. No default implementation by base class.
Prototype
virtual int CloseConnection()
Input arguments
None
Return values
int
The response from this method is an integer value that shows success or failure: Return ADK_SUCCESS to show successful completion. Return ADK_WARNING to show warnings were issued but the method completed successfully. Return ADK_ERROR to show the method was unable to complete successfully. In the case of a warning or error, log and debug messages should help users diagnose the error. See Chapter 7, Logging and debugging, for more information about log and debug event tracing and error handling.
81
See also
CBaseAdapter::OpenConnection CBaseAdapter::SetStatusMessage
CBaseAdapter::CreateNewQuery
Returns a new CQuery object that was created using the input parameters supplied to this method.
Required
Adapter must implement this method. No default implementation by the base class.
Prototype
virtual CQuery*CBaseAdapter::CreateNewQuery( const char* pContainer=0, const char* pQueryString=0, int nQueryType=0)=0
Input arguments
pContainer
The name of the container specified in the Table Name field on Main tab of the AR Mapping Information window.
pQueryString
The query string obtained from the Query tab of the AR Mapping Information window.
nQueryType
The type of query this object represents. The query types are assigned as follows:
EIE_QUERY_LIMIT_KEYS = 0 EIE_QUERY_ROW_UPDATE = 1 EIE_QUERY_ROW_DELETE = 2
Return values
CQuery*
Returns a new CQuery object that was created using the input parameters supplied to this method.
See also
CQuery
82
Developers Guide
CBaseAdapter object
CBaseAdapter::CreateNewRule
Returns the adapter-derived rule definition object, which holds the definition of a single rule entered on the AR Mapping Information window. The rule is obtained from the Primary Key Mapping, Data Field Mapping, or the Response Field Mapping tabs of the AR Mapping Information window. The Integration Engine service calls this method to get the rule definition object. In this method, the adapter needs to create a new adapter-derived CRule object, passing the supplied parameters. The newly created object is returned for use by the Integration Engine service during a data transfer. The Integration Engine service deletes the object when it is no longer needed.
Required
Prototype
virtual CRule*CreateNewRule( const char*pContainer, const char*pRuleString)
Input arguments
pContainer
The name of the container where this rule resides. For AR System, a container is the AR System form name. For an adapter, this is the container specified in the Table Name field on the Main tab of the AR Mapping Information window.
pRuleString
The text of the rule entered by users on the AR Mapping Information window. The rule text comes from the Primary Key Mapping, Data Field Mapping, or Response Field Mapping tab of the AR Mapping Information window.
Return values
CRule*
The adapter-derived rule definition object, which is used by the Integration Engine service to hold the definition of a rule typed on the AR Mapping Information window.
See also
None
83
CBaseAdapter::CreateQueryString
Returns a query string using the passed parameters as input to format the query string. The query string is defined to show a search for a record that matches the values passed in the input parameters. The query must be formatted in the syntax that users would specify on the Query tab of the AR Mapping Information window.
NOTE
Sometimes, the Integration Engine must generate a query to support the data exchange configuration. This method is called by the Integration Engine so the adapter can generate a query that has the syntax that is supported by the adapter.
Required
Prototype
virtual const char*CBaseAdapter::CreateQueryString( CListOfRuleWithValue& key, const char* pContainer)
Input arguments
key
A list of CRule and associated CValue objects that are used in the query.
pContainer
The name of the container specified in the Table Name field on the Main tab of the AR Mapping Information window.
Return values
const char*
Returns a query string that was created using the input parameters supplied to this method.
See also
CQuery
84
Developers Guide
CBaseAdapter object
CBaseAdapter::CreateRuleValues
Creates a new record in the external data store. The adapter is called once for each key that is processed. The parameters passed to this method are arrays, with each array element representing a single data mapping in the data exchange that is processed. The adapter can handle them as individual entities or regroup them as needed for best access to the adapter database. This method is responsible for creating a new record in the database with the data values for fields defined in the valueUsedForCreate parameter and for getting the data values for the fields defined in the responseValue parameter. Each object in the valueUsedForCreate parameter contains a list of CRuleWithValue objects. Each CRuleWithValue object defines a single data value that is placed in the database. The rule was defined on the Data Field Mapping tab of the AR Mapping Information window. The CRuleWithValue object has a CRule object that defines the data value that is updated and a CValue object that has the value that is placed in the database. Each object in the responseValue parameter contains a list of CRuleWithValue objects. Each CRuleWithValue object defines a single data value that is obtained. The rule was defined on the Response Field Mapping tab of the AR Mapping Information window. The CRuleWithValue object has a CRule object that defines the data value that is obtained and a CValue object that is initialized to a null value. This method needs to update each CValue object with the value obtained from the database.
NOTE
If the adapter supports transaction processing, all changes to the database must be recorded so they can be removed if StopTransaction shows that the changes are not permanent. If any errors are detected while getting the data values, this method should call SetStatusMessage indicating the cause of the error, and return ADK_ERROR. The messages written to the debug file are intended to help users diagnose the cause of the error.
NOTE
You can define a data exchange with multiple data mappings. If multiple mappings are defined, one of the data mappings is designated as the main mapping. The GetKeyList method is called only to get a list of keys for the data mapping that has been designated as the main mapping. The key values in the key parameter are all set to the key values returned by the GetKeyList method.
Required
85
Prototype
virtual int CreateRuleValues( int num, CListOfRuleWithValue valueUsedForCreate[], CListOfRuleWithValue responseValue[])
Input arguments
valueUsedForCreate
The element in this array represents the data definition and an associated data value for a specific data mapping defined in the data exchange that is processed. Each data definition is defined in a CRule object and represents an entry on the Data Field Mapping tab of the AR Mapping Information window. Its associated value is a CValue object and is set to the value that is placed in the database. The container that holds the CRule and CValue objects is a CRuleWithValue object.
responseValue
Each element in this array represents the data definition and an associated data value for a specific data mapping defined in the data exchange that is processed. Each data definition is defined in a CRule object and represents an entry on the Response Field Mapping tab on the AR Mapping Information window. Its associated value is a CValue object that is initialized to a null value. The container that holds the CRule and CValue objects is a CRuleWithValue object.
num
This argument specifies the number of elements in the valueUsedForCreate and responseValue arrays. All arrays contain the same number of elements. Each element represents information from a single data mapping included in a data exchange. Data exchanges are defined with one or more data mappings. Each data mapping shares a common key definition but can reference a different table (AR System form or CMDB class). The information entered for each data mapping is maintained in its own array element.
Return values
int
The response from this method is an integer value that shows success or failure: Return ADK_SUCCESS to show successful completion. Return ADK_WARNING to show warnings were issued, but the method completed successfully. Return ADK_ERROR to show the method was unable to complete successfully. In the case of a warning or error, record log and debug messages help users diagnose the error. See Chapter 7, Logging and debugging, for more information about log and debug event tracing and error handling.
86
Developers Guide
CBaseAdapter object
See also
CBAseAdapter::GetRuleAttributes CBaseAdapter::SupportTransaction CBAseAdapter::StartTransaction CBaseAdapter::StopTransaction CListOfRuleWithValue CRule CRuleWithValue CValue
CBaseAdapter::DeleteRuleValues
Deletes the indicated record from the external data store. A record can be deleted if a key exists in the adapter database that does not exist in AR System. Each data exchange is configured to support or not support the deletion of records. If the data exchange is configured to support deleted records, any record that exists in the list of external data store records being processed in the data exchange that does not exist in the list of the AR System records is deleted. All deleted records are handled by this method. You can configure an optional query to limit which rows are deleted. If a delete query is configured on the Query tab of the AR Mapping Information window, this query is passed to that method in the deleteQualifier parameter. The adapter must verify if the query condition is met before proceeding with the deletion. If any errors are detected while deleting data values, this method should call to show the cause of the error and return ADK_ERROR. The messages written to the debug file are intended to help users diagnose the cause of the error.
SetStatusMessage
NOTE
If the adapter supports transaction processing, all records deleted from the external data store must be recorded so they can be restored if StopTransaction shows that the changes are not permanent.
Required
Adapter must implement this method. No default implementation by the base class.
Prototype
virtual int CBaseAdapter::DeleteRuleValues( int numItems, CListOfRuleWithValue key[], CQueryWithListOfRuleValue deleteQualifier[])=0
87
Input arguments
numItems
The number of elements in the key and deleteQualifier arrays. All arrays contain the same number of elements. Each element represents information from a single data mapping included in a data exchange. Data exchanges are defined with one or more data mappings. Each data mapping shares a common key definition but can reference a different object in the external data store. The information entered for each data mapping is maintained in its own array element.
key
Each element in this array represents the key definition and associated data values for a specific data mapping defined in the data exchange that is processed. Each key field is defined in a CRule object and its associated data value is set in a CValue object. The container that holds the CRule and CValue objects is a CRuleWithValue object.
deleteQualifier
This argument is a qualifier that determines if the record should be deleted. The qualifier is obtained from the Query tab of the AR Mapping Information window.
Return values
int
The response from this method is an integer value that shows success or failure: Return ADK_SUCCESS to show successful completion. Return ADK_WARNING to show warnings were issued, but the method completed successfully. Return ADK_ERROR to show the method was unable to complete successfully. In the case of a warning or error, record log and debug messages help users diagnose the error. See Chapter 7, Logging and debugging, for more information about log and debug event tracing and error handling.
See also
CBaseAdapter::ValidateQualifier CQueryWithListOfRule CRule CValue
88
Developers Guide
CBaseAdapter object
CBaseAdapter::DoCommand
Runs the specified command and returns the resulting value. If the adapter supports the sql| or process| command syntax, this method needs to be implemented.
Required
Prototype
virtual int DoCommand( char*commandType, char*command, CValue& resultValue)
Input arguments
commandType
The type of the command that is processed. The command is the rule entered for an sql|, targetsql|, process|, or targetprocess| command specified in a rule on the Data Field Mapping or Response Field Mapping tabs of the AR Mapping Information window. For sql| or targetsql|, this value is set to sql|. For process| or targetprocess|, this value is set to process|.
command
The command that is processed. The command is the rule specified for an sql|, targetsql|, process|, or targetprocess| command specified in a rule on the Data Field Mapping or Response Field Mapping tabs of the AR Mapping Information window. This parameter is the value following the pipe.
resultValue
A CValue object that is initialized as a null value and updated by this command to hold the data value obtained as a result of running the command.
Return values
int
The response from this method is an integer value that shows success or failure: Return ADK_SUCCESS to show successful completion. Return ADK_WARNING to show warnings were issued, but the method completed successfully. Return ADK_ERROR to show the method was unable to complete successfully. In the case of a warning or error, log and debug messages help users diagnose the error. See Chapter 7, Logging and debugging, for more information about log and debug event tracing and error handling,
89
See also
None
CBaseAdapter::GetKeyList
Gets a list of keys that are used in a data transfer. The definition of the key is a list of one or more CRule objects, each identifying a key value defined on the Primary Key Mapping tab of the AR Mapping Information window. The adapter is responsible for getting the list of keys from the external data store and adding each key as a data row in the rowOfKeys parameter. A data row is a simple list of CValue objects as defined by the CValueList object. The Integration Engine service initialized the rowOfKeys parameter before calling this method. The adapter just needs to add the keys to the list. For example, if the key is defined as two fields, an empID and department, the key parameter contains two CRule objects. The first CRule object defines the empID field, and the second defines the department field. The adapter asks the database for a list of all empID and department values that meet the constraint defined by the qualifier. Each obtained row is placed in the rowOfKeys parameter. Each row has a CValue object for the data obtained for the empID field, and a CValue object for the data obtained for the department field. An optional qualifier is passed to this method. If the qualifier is provided, the adapter limits the key values to only those that match the conditions specified by the qualifier string. The qualifier string is either obtained from the Query tab of the AR Mapping Information window or created by the CBaseAdapter::CreateQueryString method. If the qualifier string was obtained from the Query tab of the AR Mapping Information window, the CBaseAdapter::ValidateQualifier is called to verify that the qualifier string is valid. The $KEYLIST$ reserved word shows a list of keys supplied to this method that must be used to limit the key values obtained from the database. The qualifier passed to this method has $KEYLIST$ somewhere in the qualifier string. The qualifier string must be updated with the correct syntax in the place of the $KEYLIST$ reserved word that results in a qualifier that limits the data based on the listOfKeysToCheckFor parameter. For example, if the adapter database supports SQL syntax, and the qualifier string has EMPID in $KEYLIST$, the qualifier string is modified. If the listOfKeysToCheckFor parameter has the values 32515, 42514, 47642, and 76124, and the key is EMPID, the modified string query has:
EMPID in (32515, 42514, 47642, 76124)
If created by the CBaseAdapter::CreateQueryString method, the adapter creates the qualifier string. In this case, the Integration Engine service does not validate the qualifier string with CBaseAdapter::ValidateQualifier. Instead, the Integration Engine service expects the adapter to make sure the query is valid.
90
Developers Guide
CBaseAdapter object
If any errors are detected while creating the key list, this method should record detailed messages in the debug file by calling SetStatusMessage to indicate the cause of the error and return ADK_ERROR. The messages written to the debug file are intended to help users diagnose the cause of the error.
NOTE
The CBaseAdapter class has two GetKeyList methods, one that supports the $KEYLIST$ reserved word, and one that does not. This method does not require support for the $KEYLIST$ reserved word.
NOTE
You can create a data exchange with multiple data mappings. If multiple mappings are defined, one of the data mappings is designated as the main mapping. This method is called only to get a list of keys for the data mapping that has been designated as the main mapping. The data retrieval methods, GetRuleValues, UpdateRuleValues, and CreateRuleValues, are passed the key values obtained by this method as the key value for each defined data mapping.
Required
Prototype
virtual int GetKeyList( CListOfRule&key, CQueryWithRowsOfValue&qualifier, CRowsOfValuesList&rowOfKeys)
Input arguments
key
A key that contains a list of CRule objects, each identifying a key value defined on the Primary Key Mapping tab of the AR Mapping Information window.
qualifier
This optional parameter is a qualifier string to be used to limit the list of keys retrieved. The qualifier string is either to be obtained from the Query tab of the AR Mapping Information window, or created by the CBaseAdapter::CreateQueryString method. If no qualifier is present, this parameter is set to a null pointer.
rowOfKeys
The key values obtained by this method are added to this object. The Integration Engine service initializes this object to an empty list before calling this method. The adapter adds each key value obtained to this list. This parameter is a simple C++ list of CValueList objects. A CValueList object is a simple list of CValue objects.
91
Return values
int
The response from this method is an integer value that shows success or failure: Return ADK_SUCCESS to show successful completion. Return ADK_WARNING to show warnings were issued, but the method completed successfully. Return ADK_ERROR to show the method was unable to complete successfully. In the case of a warning or error, record log and debug messages to help the user diagnose the error. For more information about log and debug event tracing, and error handling, see Chapter 7, Logging and debugging.
See also
CBAseAdapter::CreateQueryString CBaseAdapter::ValidateQualifier CRowsOfValueList CValue CValueList
CBaseAdapter::GetLicenseString
A BMC Remedy internal method. The default implementation returns a null value unless the adapter is a licensed adapter owned by BMC.
Required
Adapter should not implement this method.
Prototype
virtual void GetLicenseString( unsigned longseed charlicstring)
Input arguments
seed
Seed used to encrypt the password.

licstring
Encrypted license string.
Return values
None
92
Developers Guide
CBaseAdapter object
See also
None
CBaseAdapter::GetProductName
Returns a character string that is the product name of the adapter. The product name is a short description used by the Integration Engine service to identify the adapter log and debug messages.
Required
Prototype
virtual int GetProductName()
Input arguments
None
Return values
const char*
The product name of the adapter.
See also
None
CBaseAdapter::GetRuleAttributes
Validates the rule syntax and sets the attributes for the list of rules passed to this method. Attributes are information such as the data type, the maximum length of the data, and any limits you might need during processing. It is important to set the data type to the Integration Engine data type code that most closely matches your own data type. Do not try to decide how the field is used. By setting the correct data type, any data conversion is more effective. See the CRule object for a definition of how to set the attributes and a list of the Integration Engine data type codes. Validation of the existence of the rule in the database should be included at this point. If the rule is not valid, mark the CRule object invalid by calling the SetErrMsg method with an error message indicating the problem. When the Integration Engine service detects a change to any rule in the data exchange, the Terminate method is called to free any resources, and this method is called to validate and set the attributes for the new set of rules.
Appendix A Class library reference 93
If an error or warning is detected for any rule, it is important to mark the CRule object as invalid and allow the Integration Engine service to complete the rule validation process. Any service-owned methods that have imbedded adapter rules need to know if the rule object is valid. Recording errors also allow the Integration Engine service to create a detailed debug log that shows any rules in error.
NOTE
is called while a connection to the database is active. There is no need to establish another database connection to get the rule information.
GetRuleAttributes
Required
Prototype
virtual int GetRuleAttributes( CListOfRule ArrayOfRuleList[])
Input arguments
ArrayOfRuleList[]
This parameter is an array of CListOfRule objects. Each CRule object defines a rule entered on the AR Mapping Information window. All adapter-owned rules are extracted and placed in this list. The list includes all rules from the Primary Key Mapping, Data Field Mapping, and Response Field Mapping tabs.
Return values
int
The response from this method is an integer value that shows success or failure: Return ADK_SUCCESS to show successful completion. Return ADK_WARNING to show warnings were issued, but the method completed successfully. Return ADK_ERROR to show the method was unable to complete successfully. In the case of a warning or error, record log and debug messages to help the user diagnose the error. For more information about log and debug event tracing, and error handling, see Chapter 7, Logging and debugging.
See also
CBaseAdapter::Terminate CBaseAdapter::SetStatusMessage CListOfRule
94
Developers Guide
CBaseAdapter object
CBaseAdapter::GetRuleValues
Returns the requested data values for a specific key value. The adapter is called once for each key to be processed. The parameters passed to this method are arrays, with each array element representing a single data mapping in the data exchange that is processed. The adapter is free to handle them as individual entities or regroup them as needed for the best access to the adapter database. This method is responsible for getting the data values for fields defined in the retrievedValue parameter and for the key defined in the key parameter. Each retrievedValue object contains a list of CRuleWithValue objects. Each CRuleWithValue object defines a single data value to be obtained. The CRuleWithValue object has a CRule object that defines the data value to be obtained and a CValue object that is initialized to a null value. This method needs to update each CValue object with the value obtained from the database. If any errors are detected while getting the data values, this method should record detailed messages in the debug file by calling SetStatusMessage indicating the cause of the error, and return ADK_ERROR. The messages written to the debug file are intended to help the user diagnose the cause of the error.
NOTE
You can create a data exchange with multiple data mappings. If multiple mappings are defined, one of the data mappings is designated as the main mapping. The GetKeyList is called only to get a list of keys for the data mapping that has been designated as the main mapping. The key values in the key parameter are all set to the key values returned by the GetKeyList method.
Required
Prototype
virtual int GetRuleValues( int num, CListOfRuleWithValue key[], CListOfRuleWithValue retrievedValue[])
Input arguments
key[]
95
retrievedValue[]
Each element in this array represents the data definition and an associated data value for a specific data mapping defined in the data exchange that is processed. Each data definition is defined in a CRule object and its associated value is a CValue object that is initialized to a null value. The container that holds the CRule and CValue objects is a CRuleWithValue object.
num
The number of elements in the key and retrievedValue arrays. Both arrays contain the same number of elements. Each element represents information from a single data mapping included in a data exchange. Data exchanges are defined with one or more data mappings. Each data mapping shares a common key definition but can reference a different table or AR System form. The information entered for each data mapping is maintained in its own array element.
Return values
int
The response from this method is an integer value that shows success or failure: Return ADK_SUCCESS to show successful completion. Return ADK_WARNING to show warnings were issued, but the method completed successfully. Return ADK_ERROR to show the method was unable to complete successfully. In the case of a warning or error, record log and debug messages to help the user diagnose the error. For more detailed information about log and debug event tracing, see Chapter 7, Logging and debugging.
See also
CBaseAdapter::GetRuleAttributes CListOfRuleWithValue CValue CRule CRuleWithValue
CBaseAdapter::GetStatusMessage
Returns all current messages created by SetStatusMessage. The Integration Engine service calls this method to get the character string when any CBaseAdapter methods indicate an error has taken place. The contents of the status message are placed in the EIE:Log if it is critical, and in only the debug file if it is not. Whether a message is critical is decided by the critical parameter set in SetStatusMessage.
Required
96
Developers Guide
CBaseAdapter object
Prototype
const char* GetStatusMessage()
Input arguments
None
Return values
const char*
Returns all current messages created by SetStatusMessage.
See also
CBaseAdapter::SetStatusMessage
CBaseAdapter::Initialize
Prepares the adapter for a data transfer. This includes validating the parameters defined on the Connection Settings tab of the Data Exchanges Information window. This method is called once for the data transfer. Integration Engine checks at the start of each scheduled exchange to see if the data exchange has been modified. If the definition has been modified, the Terminate method is called to free resources, and the Initialize method is called again. Any objects created by the Initialize method and needed by the adapter for the data transfer process should be kept until the Terminate method is called. At that point, the Integration Engine service is either shutting down the adapter, or it has detected a change to the exchange definition, and all objects should be freed in preparation for a new call to the Initialize method. If an error or warning is detected, this method should record a text message indicating the error. The message is intended to help the user diagnose the cause of the problem. If the error prevents an exchange from taking place, a message should be added to the Integration Engine log file. SetStatusMessage is called to record debug and log messages. If the call to SetStatusMessage shows a critical error, it is written to the log file. Be sure to limit what is written to the log. See Chapter 7, Logging and debugging, for details on what type of events should be recorded. Implement this method by calling CBaseAdapter::Initialize to set internal pointers to the data exchange created by the Integration Engine service.
97
Required
Prototype
virtual int initialize( CEIEDataExchangeDef* pExDef)
Input arguments
pExDef
A pointer to the data exchange created by the Integration Engine service. It contains the name of the data exchange as well as a list of external data store configuration parameters. This parameter is a CEIEDataExchangeDef object. This object can be saved for future reference. The Integration Engine service keeps this object until the data exchange changes. At that time, this method is called with a new CEIEDataExchangeDef object.
Return values
int
See also
CBaseAdapter::Terminate CBaseAdapter::SetStatusMessage
CBaseAdapter::OpenConnection
Establishes a connection to the external data store. The Integration Engine service calls CloseConnection when a connection to the external data store is no longer needed. If an error or warning is detected, this method should record a text message indicating the error. The message is intended to help the user diagnose the cause of the problem. Messages are written to the debug file by calling the SetStatusMessage or AppendStatus methods in CBaseAdapter. If the call to SetStatusMessage shows a critical error, it is written to the log file. Be sure to limit what is written to the log file. See Chapter 7, Logging and debugging, for details on what type of events should be recorded.
98
Developers Guide
CBaseAdapter object
Implement this method by first calling CBaseAdapter::Initialize to set internal pointers to the data exchange created by the Integration Engine service.
Required
Prototype
virtual int OpenConnection()
Input arguments
None
Return values
int
See also
CBaseAdapter::CloseConnection CBaseAdapter::SetStatusMessage
CBaseAdapter::SetLogMessage
Adds the text of this message to the Integration Engine service log. All log messages generated by Integration Engine are translated to the user language. The Integration Engine service does not translate status messages obtained from the adapter. The adapter developer must provide messages in the appropriate language.
Required
99
Prototype
void SetLogMessage const char*logMsg)
Input arguments
logMsg
A character string to be added to the Integration Engine service log.
Return values
None
See also
CBaseAdapter::SetStatusMessage CBaseAdapter::GetStatusMessage
CBaseAdapter::SetStatusMessage
SetStatusMessage(const char* Msg, int nTraceLevel),
This method supports two implementations. The first implementation, void adds the text of this message to the debug file for individual data exchanges with level information passed to the function. The second implementation, void SetStatusMessage(const char* errMsg), adds the text of this message to the debug file for individual data exchanges without level information. This method can be used by any other method in the CBaseAdapter object. The debug facility is intended as a development and support tool for administrators who are configuring and testing data exchanges. It provides detailed operational information to diagnose errors in a data exchange. Messages will be enabled or disabled depending on the current configured level for logging.
Required
Prototype
void SetStatusMessage(const char* Msg, int nTraceLevel) void SetStatusMessage(const char* errMsg)
or
NOTE
See the eiedebug.h file for the available values of the nTraceLevel field.
100
Developers Guide
CBaseAdapter object
Input arguments
Msg
A character string to be added to the debug file.

nTraceLevel
Value for TraceLevel defined in the adksprt.h file The message in debug will appear with the corresponding trace level string.
errMsg
A character string to be added to the debug file.
Return values
None
See also
CBaseAdapter::SetLogMessage CBaseAdapter::GetStatusMessage
CBaseAdapter::StartTransaction
Called at the start of each transaction. A transaction is a wrapper around the data exchange for a single key. If the adapter supports transaction processing, the adapter can back out any changes made for a specific key, putting the data back to its original state before any changes. Transactions are guaranteed to be for a single key only. When this method is called, the Integration Engine service starts to process a new key. StopTransaction was already called to terminate a transaction for the last key. In this method, perform any initialization needed to record changes that are made for the key to be processed. Until StopTransaction is called, all changes made to UpdateRuleValues and CreateRuleValues must be recorded.
Required
Prototype
virtual bool StartTransaction()
Input arguments
None
Appendix A
101
Return values
bool
true=transaction successfully starts; false=transaction does not start.
See also
CBaseAdapter::SupportTransaction CBaseAdapter::StopTransaction CBaseAdapter::UpdateRuleValues CBaseAdapter::CreateRuleValues
CBaseAdapter::StopTransaction
Called at the end of each transaction. A transaction is a wrapper around the data exchange for a single key. If the adapter supports transaction processing, the adapter can back out any changes made for a specific key, putting the data back to its original state before any changes. Transactions are guaranteed to be for a single key only. When this method is called, the Integration Engine service has completed processing for a specific key. If the parameter passed to this method shows the changes are to be committed (made permanent), the changes for the key being processed are to be left in the database. If the parameter shows the changes are not to be committed, the adapter must restore the original values. This includes deleting records added by the transaction. If the adapter database supports the concept of rollback and commit, the transaction processing is completed simply by issuing a rollback or commit command. If the adapter is manually recording changes, it is important to free any data obtained to maintain a record of the changes.
Required
Prototype
virtual bool StopTransaction( bool commitChanges)
Input arguments
commitChanges
This parameter shows if the changes are to be made permanent. If the parameter is set to true, the changes are to be made permanent. If the parameter is set to false, the database must be restored to the original values.
102
Developers Guide
CBaseAdapter object
Return values
None
See also
CBaseAdapter::SupportTransaction CBaseAdapter::StartTransaction
CBaseAdapter::SupportTransaction
Called to determine if the adapter supports transaction processing. A transaction is a wrapper around a data exchange for a single key. If the adapter supports transaction processing, it is indicating that it can back out changes made for a specific key, putting the data back to its original state before any changes. Transactions are guaranteed to be for a single key only. If your adapter supports transactions, return true. The StartTransaction method is called at the start of database interaction for an individual key, and StopTransaction is called when the changes to the key are finished. If your database supports the concept of rollback and commit, the transaction processing is simply a matter of issuing the rollback or commit command in the StopTransaction method.
Required
Prototype
virtual bool SupportTransaction()
Input arguments
None
Return values
bool
true=supports transactions; false=does not support transactions.
See also
CBaseAdapter::StartTransaction CBaseAdapter::StopTransaction
Appendix A
103
CBaseAdapter::Terminate
Responsible for freeing all resources brought in to initialize and validate the definition of a data exchange. This method is called when a data exchange has either changed or is no longer needed. Specifically, any resources brought in by Initialize, GetRuleAttributes, CreateQualifier, and ValidateQualifier need to be released. Those methods are called with information about a new data exchange. If an error or warning is detected, this method should record a text message indicating the error. The message is intended to help the user diagnose the cause of the problem. Messages are written to the debug file by calling the SetStatusMessage or AppendStatus methods in CBaseAdapter. If the call to SetStatusMessage shows a critical error, it is written to the log file. Be sure to limit what is written to the log file. See Chapter 7, Logging and debugging, for details on what type of events should be recorded.
Required
Prototype
virtual int terminate()
Input arguments
None
Return values
int
See also
CBaseAdapter::Initialize CBaseAdapter::GetRuleAttributes CBaseAdapter::ValidateQualifier CBaseAdapter::CreateQualifier CBaseAdapter::SetStatusMessage
104
Developers Guide
CBaseAdapter object
CBaseAdapter::UpdateRuleValues
Updates the external data store for a specific key. The adapter is called once for each key that is processed. The parameters passed to this method are arrays, with each array element representing a single data mapping in the data exchange that is processed. The adapter is free to handle them as individual entities or regroup them as needed for the best access to the adapter database. This method is responsible for updating the database with the data values for fields defined in the valueToUpdate parameter and for getting the data values for the fields defined in the responseValue parameter. This data is then provided to the key defined in the key parameter. Each object in the valueToUpdate parameter contains a list of CRuleWithValue objects. Each CRuleWithValue object defines a single data value to be updated in the database. The rule was defined on the Data Field Mapping tab of the AR Mapping Information window. The CRuleWithValue object has a CRule object that defines the data value to be updated and a CValue object that has the value to be placed in the database. Each object in the responseValue parameter contains a list of CRuleWithValue objects. Each CRuleWithValue object defines a single data value to be obtained. The rule was defined on the Response Field Mapping tab of the AR Mapping Information window. The CRuleWithValue object has a CRule object that defines the data value to be obtained and a CValue object that is initialized to a null value. This method needs to update each CValue object with the value obtained from the database. If any errors are detected while getting the data values, this method should record detailed messages in the debug file by calling SetStatusMessage indicating the cause of the error, and return ADK_ERROR. The messages written to the debug file are intended to help the user diagnose the cause of the error.
NOTE
You can create a data exchange with multiple data mappings. If multiple mappings are defined, one of the data mappings is designated the main mapping. The GetKeyList method is called only to get a list of keys for the data mapping that has been designated the main mapping. The key values in the key parameter are all set to the key values returned by the GetKeyList method.
Required
Prototype
virtual int UpdateRuleValues( int num, CListOfRuleWithValue key[], CListOfRuleWithValue valueToUpdate[], CListOfRuleWithValue responseValue[], CQueryWithListOfRuleValue updateQualifier[])
Appendix A
105
Input arguments
key[]
valueToUpdate[]
Each element in this array represents the data definition and an associated data value for a specific data mapping defined in the data exchange that is processed. Each data definition is defined in a CRule object and represents an entry on the Data Field Mapping tab on the AR Mapping Information window. Its associated value is a CValue object that is set to the value to be placed in the database. The container that holds the CRule and CValue objects is a CRuleWithValue object.
responseValue[]
Each element in this array represents the data definition and an associated data value for a specific data mapping defined in the data exchange that is processed. Each data definition is defined in a CRule object and represents an entry on the Response Field Mapping tab on the AR Mapping Information window. Its associated value is a CValue object that is initialized to a null value. The container that holds the CRule and CValue objects is a CRuleWithValue object.
num
The number of elements in the key, valueToUpdate, and responseValue arrays. All arrays contain the same number of elements. Each element represents information from a single data mapping included in a data exchange. Data exchanges are defined with one or more data mappings. Each data mapping shares a common key definition but can reference a different table or AR System form. The information entered for each data mapping is maintained in its own array element.
updateQualifier[]
Each element in this array represents a query used to determine if a record is to be updated. The qualifier is obtained from the Query tab of the AR Mapping Information window.
Return values
int
106 Developers Guide
CBaseAdapter object
See also
CBaseAdapter::GetRuleAttributes CBaseAdapter::SupportTransaction CBaseAdapter::StartTransaction CBaseAdapter::StopTransaction CValue CRule CRuleWithValue
CBaseAdapter::ValidateQualifier
Validates the rule syntax, verifying it is a valid query for limiting data access in the external data store. The qualifier is obtained from the Query tab on the AR Mapping Information window. If an error or warning is detected during the validation process, this method should record a text message with SetStatusMessage indicating the error, and return ADK_ERROR to show an error has been detected. It is important to return the error indicator to let the Integration Engine service know the qualifier is not valid. Query syntax errors prevent a data transfer from taking place. When the Integration Engine service detects a change to the qualifier in the data exchange, the Terminate method is called to free any resources. Then the ValidateQualifier method is called to validate and set the attributes for the new set of rules.
Required
NOTE
is not called while a connection to the database is active. If validation requires an open connection, you must establish the connection.
ValidateQualifier
Prototype
virtual int ValidateQualifier( const char* pQualifier)
Input arguments
pQualifier
A CQuery object to be validated. The CQuery object is obtained from the Query tab of the AR Mapping Information window.
Appendix A
107
Return values
int
See also
CBaseAdapter::Terminate CBaseAdapter::SetStatusMessage
This section describes the methods for the CEIEDataExchangeDef object.
CEIEDataExchangeDef::GetDataExchangeName
Returns the name of the data exchange that is processed. The data exchange name is the value from the Exchange Name field on the Main tab of the Data Exchanges Information window.
Required
Implemented by the CEIEDataExchangeDef class.
Prototype
string GetDataExchangeName ()
Input arguments
None
Return values
string
The response from this method is a string object that holds the name of the data exchange that is processed.
108
Developers Guide
See also
None
CEIEDataExchangeDef::GetFirstVenConfigParam
This method returns an external data store configuration parameter name-value pair. Integration Engine collects the adapters input parameters for an exchange by reading the entries on the Connection Settings tab of the Data Exchanges Information window. The CEIEDataExchangeDef class provides methods for retrieving the parameter values either by name or by relative position in the list of parameters. This method returns the parameter name and value for the first parameter in the list of external data store configuration parameters.
Required
Prototype
bool GetFirstVenConfigParam( string&name, string&value)
Input arguments
None
Return values
name
This string object is updated with the name of the first adapter input parameter in the list of parameters obtained from the Connection Settings tab of the Data Exchanges Information window for the data exchange this object defines.
value
This string object is updated with the value associated with the parameter specified in the name parameter. The value is obtained from the Connection Settings tab of the Data Exchanges Information window for the data exchange defined by this object. If the value is an encrypted value, this class takes care of decrypting the value before it is returned in this string object.
bool
The response from this method is a Boolean value that is set to true if the parameter is defined, and false if the parameter is not defined.
Appendix A
109
See also
CEIEDataExchangeDef::GetVenConfigParam CEIEDataExchangeDef::GetVenConfigParamAt CEIEDataExchangeDef::GetVenConfigParamLength
CEIEDataExchangeDef::GetVenConfigParamAt
Returns an external data store configuration parameter name-value pair. Integration Engine collects the adapters input parameters for an exchange by reading the entries on the Connection Settings tab of the Data Exchanges Information window. The CEIEDataExchangeDef class provides methods for retrieving the parameter values either by name or by relative position in the list of parameters. This method returns the parameter name and value based on an index indicating the relative position in the list of parameters to be returned. This is a zero-based index, where 0 is the first value in the list of parameters. The total number of parameters in the list is obtained by calling the GetVenConfigParamLength method for this class.
Required
Prototype
bool GetVenConfigParamAt( intn, string&name, string&value)
Input arguments
n
This integer value is the relative entry in the list of adapter input parameters obtained from the Connection Settings tab of the Data Exchanges Information window. This is a zero-based index, where 0 is the first value in the list of parameters. The total number of parameters in the list is obtained by calling the GetVenConfigParamLength method for this class.
Return values
name
This string object is updated with the name of the first adapter input parameter in the list of parameters obtained from the Connection Settings tab of the Data Exchanges Information window for the data exchange this object defines.
110
Developers Guide
value
This string object is updated with the value associated with the parameter specified in the name parameter. The value is obtained from the Connection Settings tab of the Data Exchanges Information window for the data exchange defined by this object. If the value is an encrypted value, this class takes care of decrypting the value before it is returned in this string object.
bool
The response from this method is a Boolean value that is set to true if the parameter is defined, and false if the parameter is not defined.
See also
CEIEDataExchangeDef::GetVenConfigParam CEIEDataExchangeDef::GetFirstVenConfigParam CEIEDataExchangeDef::GetVenConfigParamLength
CEIEDataExchangeDef::GetVenConfigParamLength
Returns the number of adapter input parameters defined on the Connection Settings tab of the Data Exchanges Information window. The CEIEDataExchangeDef class provides methods for retrieving the parameter values either by name or by relative position in the list of parameters. This method returns the total number of parameters in the list of parameters supplied for this data exchange.
Required
Prototype
unsigned int GetVenConfigParamLength()
Input arguments
None
Return values
unsigned int
The response from this method is an unsigned integer that shows the number of adapter input parameters that were obtained from the Connection Settings tab of the Data Exchanges Information window for the data exchange this object defines.
See also
CEIEDataExchangeDef::GetVenConfigParam CEIEDataExchangeDef::GetFirstVenConfigParam CEIEDataExchangeDef::GetVenConfigParamAt
Appendix A
111
CEIEDataExchangeDef::IsDirectionARDataIntoVendor
Shows the direction of the data flow in the configured data exchange. The direction of the data flow is obtained from the Direction field on the Main tab of the Data Exchanges Information window. A true response means that the data exchange is configured to transfer data from AR System into the external data store. A false response means that the data exchange is configured to transfer data from the external data store into AR System.
Required
Prototype
bool CEIEDataExchangeDef::IsDirectionARDataIntoVendor()
Input arguments
None
Return values
bool
Returns true if the data exchange is configured to transfer data from AR System to the external data store.
See also
CEIEDataExchangeDef::IsDirectionVendorDataIntoAR
CEIEDataExchangeDef::IsDirectionVendorDataIntoAR
Shows the data flow direction in the configured data exchange. The direction of the data flow is obtained from the Direction field on the Main tab of the Data Exchanges Information window. A true response means that the data exchange is configured to transfer data from the external data store into AR System. A false response means that the data exchange is configured to transfer data from AR System into the external data store.
Required
112
Developers Guide
CRule object
Prototype
bool CEIEDataExchangeDef::IsDirectionVendorDataIntoAR()
Input arguments
None
Return values
bool
Returns true if the data exchange is configured to transfer data from the external data store into AR System.
See also
CEIEDataExchangeDef::IsDirectionARDataIntoVendor
CRule object
This section describes the methods for the CRule object.
CRule::CRule (copy constructor)

Initializes this object using the contents of the CRule object passed as a parameter. A copy of the rule definition and associated attributes are initiated from the passed object.
Required
Implemented by the CRule class.
Prototype
CRule::CRule( const CRule& otherRule)
Input arguments
otherRule
A CRule object containing data values that are used to initialize this CRule object. All attributes and data associated with this value are used to initialize this object.
Return values
None
Appendix A
113
See also
CRule::~CRule (destructor)
Frees all resources for the CRule object.
Required
Prototype
CRule::~CRule()
Input arguments
None
Return values
None
See also
CRule::CRule (constructors)
CRule::CRule (new rule constructor)

Initializes a rule definition object and initializes the container to which it belongs. For AR System, a container is the AR System form name. For an adapter, this is the container specified in the Table Name field on the Main tab of the AR Mapping Information window.
Required
Prototype
CRule::CRule( const char*pContainer, const char* pRuleString)
114
Developers Guide
CRule object
Input arguments
pContainer
The name of the container where this rule resides. For AR System, a container is the AR System form name. For an adapter, this is the container specified in the Table Name field on the Main tab of the AR Mapping Information window.
pRuleString
The text of the rule entered by the user on the AR Mapping Information window. The rule text comes from the Primary Key Mapping, Data Field Mapping, or Response Field Mapping tab of the AR Mapping Information window.
Return values
None
See also
CRule::DeepClone
Returns the new object that was initialized using the current pointer.
Required
Prototype
CRule *CRule::DeepClone()
Input arguments
None
Return values
Return the pointer to the new allocated object as a pointer to the CRule object.
See also:
CRule
Appendix A
115
CRule::GetContainer
Returns the name of the container to which this rule belongs. For AR System, a container is the AR System form name. For an adapter, this is the container specified in the Table Name field on the Main tab of the AR Mapping Information window.
Required
Prototype
char* CRule::GetContainer()
Input arguments
None
Return values
char*
The name of the container where this rule resides. For AR System, a container is the AR System form name. For an adapter this is the container specified in the Table Name field on the Main tab of the AR Mapping Information window.
See also
CRule::SetContainer
CRule::GetEIEDataType
Returns the Integration Engine-defined data type that most closely matches the data type of values this rule represents. The CRule object allows the adapter to store its own type, but this method returns the closest Integration Engine-defined type. The data type returned by this method is the data type to which all associated CValue objects are set. Setting the correct data type allows Integration Engine to handle all necessary data conversions and set the data values to the appropriate type.
Required
Prototype
virtual DATATYPE GetEIEDataType ()
116
Developers Guide
CRule object
Input arguments
None
Return values
DATATYPE
The response from this method is an integer value that shows the data type associated with the value contained in the CValue object. DATATYPE is an Integration Engine-defined value that is set to one of the settings described in Table 4-1 on page 42.
See also
CValue::GetType CValue::SetType
CRule::GetErrMsg
Returns an error message indicating the reason this rule object is not valid.
Required
Prototype
char* CRule::GetErrMsg()
Input arguments
None
Return values
char*
An error message indicating the reason a rule failed validation. This should always have a value if CRule::IsValid returns false.
See also
CRule::IsValid CRule::SetValidity CRule::SetErrMsg CBaseAdapter::GetRuleAttributes
Appendix A
117
CRule::GetRuleString
Returns the text of the rule as it was entered by the user on the AR Mapping Information window.
Required
Prototype
char* CRule::GetRuleString()
Input arguments
None
Return values
char*
The text of the rule as it was entered by the user on the AR Mapping Information window.
See also
CRule::SetRuleString
CRule::GetVenDataType
Returns the data type code that was set by the adapter during rule validation. The data type code is set by calling the SetVenDataType method. This code has meaning only to the adapter. It defines the data type associated with this rule.
CBaseAdapter::GetRuleAttributes
This code is set by the adapter during rule validation in the method.
Required
Prototype
int CRule::GetVenDataType()
Input arguments
None
118
Developers Guide
CRule object
Return values
int
The adapter-defined data type code.
See also
CRule::SetVenDataType CBaseAdapter::GetRuleAttributes
CRule::IsValid
Returns a Boolean value that shows if the rule has passed validation and is ready for use. This code is set by the adapter during rule validation in the CBaseAdapter::GetRuleAttributes method.
Required
Prototype
bool CRule::IsValid()
Input arguments
None
Return values
bool
Indicates if the rule has passed validation and is ready for use. A true response shows the rule is valid. A false response shows the rule is invalid. GetErrMsg contains a message describing the cause of the error.
See also
CRule::SetValidity CRule::SetErrMsg CRule::GetErrMsg
Appendix A
119
CRule::SetContainer
Sets the name of the container to which this rule belongs. For AR System, a container is the AR System form name. For an adapter, this is the container specified in the Table Name field on the Main tab of the AR Mapping Information window. This code is set by the adapter during rule validation in the CBaseAdapter::GetRuleAttributes method.
Required
Prototype
CRule::SetContainer( const char*container)
Input arguments
container
The name of the container where this rule resides. For AR System, a container is the AR System form name. For an adapter this is the container specified in the Table Name field on the Main tab of the AR Mapping Information window.
Return values
None
See also
CRule::GetContainer
CRule::SetErrMsg
Sets an error message indicating why a rule failed validation. All adapters need to show the success or failure of rule validation using the GetRuleAttributes method. The Integration Engine service places this text string in the debug file, which is used by users to analyze data transfer problems. The text of the message should contain enough information for the user to determine the cause of the error.
Required
120
Developers Guide
CRule object
Prototype
void CRule::SetErrMsg( const char*msg)
Input arguments
msg
An error message indicating the reason that the rule failed validation. This should always be set if the rule validity is set to false. This message should contain enough information for the user to determine the cause of the error.
Return values
None
See also
CRule::IsValid CRule::SetValidity CRule::GetErrMsg CBaseAdapter::GetRuleAttributes
CRule::SetRuleString
Sets the text of the rule as it was entered by the user on the AR Mapping Information window.
Required
Prototype
void CRule::SetRuleString( const char*string)
Input arguments
string
The text of the rule as it was entered by the user on the Primary Key Mapping, Data Field Mapping, or Response Field Mapping tab of the AR Mapping Information window.
Return values
None
Appendix A
121
See also
CRule::GetRuleString
CRule::SetValidity
Sets the validity of the rule. A true response means the rule is valid. A false response means the rule is invalid. All adapters need to show the success or failure of rule validation using the GetRuleAttributes method. This method is used to show the validation status. When this method is called with false, which indicates an error, SetErrMsg should also be called with a text description of the cause of the error.
Required
Prototype
void CRule::SetValidity( boolv)
Input arguments
v
Indicates if the rule has passed validation and is ready for use. A true response means the rule is valid. A false response means the rule is invalid. GetErrMsg contains a message describing the cause of the error.
Return values
None
See also
CRule::IsValid CRule::SetErrMsg CRule::GetErrMsg CBaseAdapter::GetRuleAttributes
CRule::SetVenDataType
Sets adapter-defined data type code and optionally the maximum length of the data value that can be contained by this rule. The data type code shows the data type of the data this rule describes.
122
Developers Guide
CQuery object
The maximum length is optional and, if specified, shows the maximum length of the data value that can be contained by this rule. If a length is defined, the Integration Engine service truncates data values to this length. If not defined, no limit check or data truncation occurs.
Required
Prototype
void CRule::SetVenDataType( int vdtype, int length=0)
Input arguments
vdtype
The adapter-defined data type code. This code has meaning only to the adapter. It defines the data type associated with this rule.
length
The maximum length of an individual data value for this rule. The maximum length is optional and, if specified, shows the maximum length of the data value that can be contained by this rule. If a length is defined, the Integration Engine service truncates data values to this length. If not defined, no limit check or data truncation occurs.
Return values
None
See also
CRule::GetVenDataType CRule::GetVenDataLength CBaseAdapter::GetRuleAttributes
CQuery object
This section describes the methods for the CQuery object.
CQuery::CQuery (copy constructor)

Initializes this object using the contents of the CQuery object passed as a parameter. A copy of the query definition and associated attributes are initialized from the passed object.
Appendix A
123
Required
Implemented by the CQuery class. If this object is derived by an adapter and has added any attributes to the object, this method must be derived to add support to copy the new attributes.
Prototype
CQuery::CQuery( const CQuery & otherQuery)
Input arguments
otherQuery
A query object to be copied.
Return values
None
See also
C:Query::~CQuery (destructor)
CQuery::~CQuery (destructor)
Frees all resources for the CQuery object.
Required
Implemented by the CQuery class. If this object is derived by an adapter and has acquired any resources, this method must be derived to add support to free the resources.
Prototype
CQuery::~CQuery()
Input arguments
None
Return values
None
See also
CQuery::CQuery (new object constructor) CQuery::CQuery (copy constructor)
124
Developers Guide
CQuery object
CQuery::CQuery (new object constructor)

Initializes a query definition object based on the information obtained from the Query tab of the AR Mapping Information window.
Required
Implemented by the CQuery class.
Prototype
CQuery::CQuery( const char* pContainer=0, const char* pRuleString=0, const int queryType=0)
Input arguments
pContainer
The container name obtained from the Table Name field of the AR Mapping Information window.
pRuleString
The query string obtained from the Query tab of the AR Mapping Information window.
queryType
Type of query this object is defining. The query types supported are as follows:
EIE_QUERY_LIMIT_KEYS = 0 EIE_QUERY_ROW_UPDATE = 1 EIE_QUERY_ROW_DELETE = 2
Return values
None
See also
C:Query::~CQuery (destructor)
CQuery::GetContainer
Returns the container name associated with this query. The container name is obtained from the Table Name field defined on the Main tab of the AR Mapping Information window.
Required
Appendix A
125
Prototype
char* CQuery::GetContainer ()
Input arguments
None
Return values
char*
The name of the container used in the data mapping to which this query belongs. For AR System, a container is the AR System form name. For an adapter, this is the container specified in the Table Name field on the Main tab of the AR Mapping Information window.
See also
CQuery::SetContainer
CQuery::GetErrMsg
Returns an error message indicating the reason a query failed validation.
Required
Prototype
const char* CQuery::GetErrMsg ()
Input arguments
None
Return values
const char*
An error message indicating the reason a query failed validation. This should always have a value if CQuery::IsValid returns false.
See also
CQuery::SetValidity CQuery::IsValid CQuery::SetErrMsg
126
Developers Guide
CQuery object
CQuery::GetQueryString
Returns the text of the query as it was entered by the user on the Query tab of the AR Mapping Information window.
Required
Prototype
char* CQuery::GetQueryString ()
Input arguments
None
Return values
char*
The query string as it was entered by the user on the Query tab of the AR Mapping Information window.
See also
CQuery::SetQueryString
CQuery::IsValid
Returns a Boolean value that shows if the query has passed validation and is ready for use. The adapter sets the Boolean value by calling SetValidity with the true/false indications during query validation.
Required
Prototype
bool CQuery::IsValid ()
Input arguments
None
Appendix A
127
Return values
bool
Indicates if the query has passed validation and is ready for use. A true response means that the query is valid. A false response means that the query is invalid. GetErrMsg contains a message describing the cause of the error.
See also
CQuery::SetValidity CQuery::SetErrMsg CQuery::GetErrMsg
CQuery::SetContainer
Returns the container name associated with this query. The container name is obtained from the Table Name field defined on the Main tab of the AR Mapping Information window.
Required
Prototype
void CQuery::SetContainer ( const char* container)
Input arguments
container
The name of the container used in the data mapping to which this query belongs. For AR System, a container is the AR System form name. For an adapter, this is the container specified in the Table Name field on the Main tab of the AR Mapping Information window.
Return values
None
See also
CQuery::GetContainer
128
Developers Guide
CQuery object
CQuery::SetErrMsg
Sets an error message indicating the reason a query failed validation. If a query syntax fails, the adapter should call SetErrMsg.
Required
Prototype
void CQuery::SetErrMsg( const char* errorMessage)
Input arguments
errorMessage
An error message indicating the reason a query failed validation.
Return values
None
See also
CQuery::SetValidity CQuery::IsValid CQuery::GetErrMsg
CQuery::SetQueryString
Returns the text of the query as it was entered by the user on the Query tab of the AR Mapping Information window.
Required
Prototype
void CQuery::SetQueryString( const char* queryString)
Input arguments
queryString
The query string as it was entered by the user on the Query tab of the AR Mapping Information window.
Appendix A
129
Return values
None
See also
CQuery::GetQueryString
CQuery::SetValidity
Sets a Boolean value that shows if the query has passed validation and is ready for use.
Required
Prototype
void CQuery::SetValidity( bool m_valid)
Input arguments
bool
Indicates if the query has passed validation and is ready for use. A true response means that the query is valid. A false response means that the query is invalid. If a false response is set, SetErrMsg should also be called with a message describing why the query is not valid.
Return values
None
See also
CQuery::IsValid CQuery::SetErrMsg CQuery::GetErrMsg
130
Developers Guide
CValue object
CValue object
This section describes the methods for the CValue object.
CValue::CValue (copy constructor)

Initializes this object using the contents of the CValue object passed as a parameter. A copy of the data value and associated attributes are initiated from the passed object.
Required
Implemented by the CValue class.
Prototype
CValue::CValue( const CValue& other)
Input arguments
other
A CValue object containing data values that are used to initialize this CValue object. All attributes and data associated with this value are used to initialize this object.
Return values
None
See also
C:Value::~CValue (destructor)
CValue::~CValue (destructor)
Frees all resources allocated for the CValue object.
Required
Prototype
CValue::~CValue()
Appendix A
131
Input arguments
None
Return values
None
See also
CValue::CValue (constructors)
CValue::CValue (empty constructor)

Initializes a data value to a null data value.
Required
Prototype
CValue::CValue()
Input arguments
None
Return values
None
See also
CValue::~CValue (destructor)
CValue::GetDecimal
Returns the value associated with this object as a character representation of a decimal value. If this value has no associated data value, a blank string is returned. If this value is not defined as a decimal value, a simple reformatting is attempted, but no data conversion is supported. The c function sprintf is applied to the data value in this object if it is not defined as a decimal. Do not try to ask for time values as a decimal value.
132
Developers Guide
CValue object
Required
Prototype
const char* CValue::GetDecimal()
Input arguments
None
Return values
const char*
The decimal value assigned to this object.
See also
CValue::SetDecimal CValue::GetString CValue::CValue (copy constructor)
CValue::GetInt
Returns the value associated with this object as an integer value. If this value has no associated data value, a zero (0) is returned. If this value is not defined as an integer value, a simple reformatting is attempted, but no data conversion is supported. For example, if a string value has been set for this object, and a call to GetInt is made, the result is the value returned by the c function atol. If the string value is not a string representation of a number, unpredictable results occur.
Required
Prototype
long CValue::GetInt()
Input arguments
None
Appendix A
133
Return values
long
The integer value assigned to this object.
See also
CValue::GetInt CValue::GetString CValue::CValue (copy constructor)
CValue::GetReal
Returns the value associated with this object as a double value. If this value has no associated data value, a zero (0) is returned. If this value is not defined as a double value, a simple reformatting is attempted, but no data conversion is supported. For example, if a string value has been set for this object, and a call to GetReal is made, the result is the value returned by the c function atof. If the string value is not a string representation of a number, unpredictable results occur.
Required
Prototype
double CValue::GetReal()
Input arguments
None
Return values
double
The double value assigned to this object.
See also
CValue::SetReal CValue::GetString CValue::CValue (copy constructor)
134
Developers Guide
CValue object
CValue::GetString
Returns the value associated with this object as a character value. If this value has no associated data value, an empty string is returned. If this value is not defined as a string value, a simple reformatting is provided using the c function sprintf.
Required
Prototype
const char* CValue::GetString()
Input arguments
None
Return values
const char*
A character string representation of the data value associated with this object.
See also
CValue::SetString CValue::CValue (copy constructor)
CValue::GetTime
Returns the value associated with this object as a time value. If this value has no associated data value, or it is not defined as a time value, a zero (0) is returned. No data conversion or reformatting of data values is supported for this method. If you do not set the value as a time value, do not call this method to get a time value. If a call is made to GetTime, and the value stored in this object is not a time value, a zero (0) is returned.
Required
Prototype
long CValue::GetTime()
Appendix A
135
Input arguments
None
Return values
long
The time value assigned to this object. If this object is not defined as a time value, a zero (0) is returned.
See also
CValue::SetTime CValue::GetString CValue::CValue (copy constructor)
CValue::GetType
Returns the data type code for the data contained in this object. If this object has no associated data value, the data type shows an empty data value.
Required
Prototype
DATATYPE CValue::GetType()
Input arguments
None
Return values
DATATYPE
The response from this method is an integer value that shows the data type associated with the value contained in the CValue object. DATATYPE is an Integration Engine-defined value that is set to one of the settings described in Table 4-1 on page 42.
See also
CValue::SetType
136
Developers Guide
CValue object
CValue::GetULong
Returns the value associated with this object as an unsigned long value. If this value has no associated data value, a zero (0) is returned. If this value is not defined as an unsigned long value, a simple reformatting is attempted, but no data conversion is supported. For example, if a string value has been set for this object, and a call to GetULong is made, the result is the value returned by the c function atol. If the string value is not a string representation of a number, unpredictable results occur.
Required
Prototype
unsigned long CValue::GetULong()
Input arguments
None
Return values
unsigned long
The unsigned long value assigned to this object.
See also
CValue::IsNull
Returns a Boolean value that shows if the value contained in this object is null.
Required
Prototype
bool CValue::IsNull()
Appendix A
137
Input arguments
None
Return values
bool
Returns true if this object contains no data value.
See also
CValue::SetNull CValue::CValue (empty constructor)
CValue::SetDecimal
Sets the value associated with this object to the decimal value passed as a parameter. The data type is set to EIE_DECIMAL. If this value already contained a data value, the value is released.
Required
Prototype
void CValue::SetDecimal( const char* str)
Input arguments
str
The decimal value, in character format, to be placed in this object. It is saved in the format in which it is passed. No attempt at validation is performed.
Return values
None
See also
CValue::GetDecimal CValue::GetString CValue::CValue (copy constructor)
138
Developers Guide
CValue object
CValue::SetInt
Sets the value associated with this object to the integer value passed as a parameter. The data type is set to EIE_INTEGER. If this value already contained a data value, that value is released.
Required
Prototype
void CValue::SetInt( int i)
Input arguments
i
The integer value to be placed in this object.
Return values
None
See also
CValue::SetNull
Sets the value associated with this object to a null value. The data type is set to EIE_NULL. If this value already contained a data value, that value is released.
Required
Prototype
void CValue::SetNull()
Appendix A
139
Input arguments
i
The integer value to be placed in this object.
Return values
None
See also
CValue::IsNull CValue::GetString CValue::CValue (copy constructor)
CValue::SetReal
Sets the value associated with this object to the double value passed as a parameter. The data type is set to EIE_REAL. If this value already contained a data value, that value is released.
Required
Prototype
void CValue::SetReal( doubledbl)
Input arguments
dbl
The double value to be placed in this object.
Return values
None
See also
CValue::GetReal CValue::GetString CValue::CValue (copy constructor)
140
Developers Guide
CValue object
CValue::SetString
Sets the value associated with this object to the string value passed as a parameter. The data type is set to EIE_CHAR. If this value already contained a data value, that value is released.
Required
Prototype
void CValue::SetString( const char*str)
Input arguments
str
The character string value to be assigned to this object.
Return values
None
See also
CValue::GetString CValue::CValue (copy constructor)
CValue::SetTime
Sets the value associated with this object to the time value passed as a parameter. The data type is set to EIE_TIME. If this value already contained a data value, that value is released.
Required
Prototype
void CValue::SetTime( longtm)
Input arguments
tm
The time value to be placed in this object.

Return values
None
See also
CValue::GetTime CValue::GetString CValue::CValue (copy constructor)
CValue::SetULong
Sets the value associated with this object to the unsigned long value passed as a parameter. The data type is set to EIE_ULONG. If this value already contained a data value, that value is released.
Required
Prototype
void CValue::SetLong( unsigned longv)
Input arguments
v
The unsigned long value to be placed in this object.
Return values
None
See also
CValue::GetULong CValue::GetString CValue::CValue (copy constructor)
142
Developers Guide
CValueList object
CValueList object
A C++ list object that holds a list of pointers to CValue objects.
Required
Defined in adksprt.h.
Prototype
typedef list<CValue*> ADKCLASS_API CValueList; typedef CValueList::iterator ValueIter;
Input arguments
None
Return values
None
See also
CValue CRowsOfValueList
Example
Example of stepping through a list of CValue objects:
CValueList *pList for (ValueIter iter=pList->begin(); iter!=pList->end(); iter++) { CValue* pValue = *iter; // ........ }
Appendix A
143
CRowsOfValueList object
A C++ list object that holds a list of pointers to CValueList objects.
Required
Prototype
typedef list<CValueList*> ADKCLASS_API CRowsOfValueList; typedef CRowsOfValueList::iterator RowsOfValueIter;
Input arguments
None
Return values
None
See also
CValue CValueList
Example
CRowsOfValueList *pList for (RowsOfValueIter iter=pList->begin(); iter!=pList->end(); iter++) { CValueList* pValueList = *iter; // ........ }
144
Developers Guide
CListOfRule object
CListOfRule object
A C++ list object that holds a list of pointers to CRule objects.
Required
Prototype
typedef list<CRule*> ADKCLASS_API CListOfRule; typedef CListOfRule::iterator RuleIter;
Input arguments
None
Return values
None
See also
CValue CValueList
Example
CListOfRule *pList for (RuleIter iter=pList->begin(); iter!=pList->end(); iter++) { CRule* pRule = *iter; }
Appendix A
145
CListOfRuleWithValue object
A C++ list object that holds a list of pointers to CRuleWithValue objects.
Required
Prototype
typedef list<CRuleWithValue*> ADKCLASS_API CListOfRuleWithValue; typedef CListOfRuleWithValue::iterator RuleWithValueIter;
Input arguments
None
Return values
None
See also
CValue CValueList
Example
CListOfRuleWithValue *pList for (RuleWithValueIter iter=pList->begin(); iter!=pList->end(); iter++) { CRuleWithValue* pRuleWithValue = *iter; // ........ }
146
Developers Guide
This section describes the methods for the CRuleWithValue object.
CRuleWithValue::CRuleWithValue (constructor)
Initializes this object with the CRule object and CValue object supplied as input parameters. The constructor only saves the passed-in pointers, without making a copy of passed objects.
CRuleWithValue
is a container object that holds a CRule, which describes a data value in the adapter database, and CValue, the value itself.
Required
Implemented by the CRuleWithValue class.
Prototype
CRuleWithValue::CRuleWithValue( CRule*pRule, CValue*pvalue)
Input arguments
pRule
Pointer to a CRule object that defines a data value.

pvalue
Pointer to a CValue object that holds the data value associated with the CRule object.
Return values
None
See also
CRuleWithValue::~CRuleWithValue (destructor)
Appendix A
147
CRuleWithValue::CRuleWithValue (copy constructor)

Initializes this object with the contents of the CRuleWithValue object supplied as an input parameter.
CRuleWithValue
Required
Prototype
CRuleWithValue::CRuleWithValue( CRuleWithValue&otherRule)
Input arguments
otherRule
A CRuleWithValue object with contents that are used to initialize this object.
Return values
None
See also
Frees all resources for the CRuleWithValue object. This destructor does not destroy the CRule and CValue objects contained in the object. Such objects are not owned by CRuleWithValue, though they are pointed to by this method.
Required
Prototype
CRuleWithValue::~CRuleWithValue()
Input arguments
None
148
Developers Guide
Return values
None
See also
CRuleWithValue::CRuleWithValue (constructor) CRuleWithValue::CRuleWithValue (copy constructor)
CRuleWithValue::GetRule
Returns the CRule object that defines the field with a data value that is also contained by this object.
CRuleWithValue is a container object that holds a CRule, which describes a data value in the adapter database, and CValue, the value itself.
Required
Prototype
CRule*CRuleWithValue::GetRule()
Input arguments
None
Return values
None
See also
CRuleWithValue::SetRule CRuleWithValue::GetValue
Appendix A
149
CRuleWithValue::GetValue
Returns the CValue object that holds the data value contained in this object.
CRuleWithValue
Required
Prototype
CValue*CRuleWithValue::GetValue()
Input arguments
None
Return values
CValue
Pointer to a CValue object that holds the data value for this object.
See also
CRuleWithValue::GetValue CRuleWithValue::GetRule
CRuleWithValue::SetRule
Sets the CRule object that holds the definition of the data value to be contained in this object. is a container object that holds a CRule, which describes a data value in the adapter database, and CValue, the value itself. In this method, only the passed pointer is saved. No copy is created.
CRuleWithValue
Required
Prototype
void CRuleWithValue::SetRule( CRule*pRule)
150
Developers Guide
Input arguments
pRule
Pointer to a CRule object that holds the definition of the data value also contained in this object.
Return values
None
See also
CRuleWithValue::GetValue CRuleWithValue::GetRule
CRuleWithValue::SetValue
Sets the CValue object that holds the data value contained by this object. is a container object that holds a CRule, which describes a data value in the adapter database, and CValue, the value itself. This method saves the passed pointer. No copy is created.
CRuleWithValue
Required
Prototype
void CRuleWithValue::SetValue( CValue*pValue)
Input arguments
pValue
Pointer to a CValue object that holds the data value also contained in this object.
Return values
None
See also
CRuleWithValue::SetValue CRuleWithValue::GetRule
Appendix A
151
This section describes the methods for the CQueryWithListOfRuleValue object.
CQueryWithListOfRuleValue::CQueryWithListOfRuleValue (copy constructor)

Initializes this object using the contents of the CQueryWithListOfRuleValue object passed as a parameter. A new object is created and initialized from the passed object.
Required
Implemented by the CQueryWithListOfRuleValue class.
Prototype
CQueryWithListOfRuleValue:: CQueryWithListOfRuleValue( const CQueryWithListOfRuleValue & otherQuery)
Input arguments
otherQuery
The object to be copied to create this CQueryWithListOfRuleValue object.
Return values
None
See also
CQueryWithListOfRuleValue::CQueryWithListOfRuleValue (destructor)
CQueryWithListOfRuleValue::CQueryWithListOfRuleValue (destructor)
Frees all resources for the CQueryWithListOfRuleValue object.
Required
152
Developers Guide
Prototype
CQueryWithListOfRuleValue::~ CQueryWithListOfRuleValue()
Input arguments
None
Return values
None
See also
CQueryWithListOfRuleValue::~CQueryWithListOfRuleValue (new object constructor) CQueryWithListOfRuleValue::~CQueryWithListOfRuleValue (copy constructor)
CQueryWithListOfRuleValue::CQueryWithListOfRuleValue (new object constructor)

A container that holds a query object and a list of CRuleWithValue objects to be used when creating the query object. Some queries need data values that are used at runtime to expand the query syntax before it is used. The list of CRuleWithValue objects contains the list of data values needed. This method creates a new CQueryWithListOfRuleValue object.
Required
Prototype
CQueryWithListOfRuleValue:: CQueryWithListOfRuleValue( const CQuery* const CListOfRuleWithValue* pQuery, pRuleValues)
Input arguments
pQuery
The CQuery object to be stored in this object.
Appendix A
153
pRuleValues
A list of CRuleWithValue objects. Some queries need data values that are used at runtime to expand the query syntax before it is used. This parameter contains the list of data values needed.
Return values
None
See also
CQueryWithListOfRuleValue::~CQueryWithListOfRuleValue (destructor)
CQueryWithListOfRuleValue::GetQuery
Returns the CQuery object that was created using one of the queries defined on the Query tab of the AR Mapping Information window.
Required
Prototype
CQuery* CQueryWithListOfRuleValue::GetQuery()
Input arguments
None
Return values
CQuery*
The CQuery object that was created using one of the queries defined on the Query tab of the AR Mapping Information window.
See also
CQueryWithListOfRuleValue::GetRuleWithValueList CQueryWithListOfRuleValue::SetQuery
154
Developers Guide
CQueryWithListOfRuleValue::GetRuleWithValueList
Returns the list of CRuleWithValue objects that are needed to expand the query at runtime.
Required
Prototype
CListOfRuleWithValue* CQueryWithListOfRuleValue ::GetRuleWithValueList ()
Input arguments
None
Return values
CListOfRuleWithValue*
The list of CRuleWithValue objects that are needed to expand the query at runtime.
See also
CQueryWithListOfRuleValue::SetRuleWithValueList CQueryWithListOfRuleValue::SetQuery
CQueryWithListOfRuleValue::SetQuery
Sets the CQuery object that was created using one of the queries defined on the Query tab of the AR Mapping Information window.
Required
Prototype
void CQueryWithListOfRuleValue::SetQuery( CQuery* pQuery)
Input arguments
pQuery
Appendix A
155
Return values
None
See also
CQueryWithListOfRuleValue::SetRuleWithValueList
Sets the CListOfRuleWithValue object that holds data values to be substituted in the query.
Required
Prototype
void CQueryWico thListOfRuleValue:: SetRuleWithValueList( CListOfRuleWithValue* pRuleValueList)
Input arguments
pRuleValueList
The list of CRuleWithValue objects that holds the data values to be substituted in the query.
Return values
None
See also
156
Developers Guide
This section describes the methods for the CQueryWithRowsOfValue object.
CQueryWithRowsOfValue::CQueryWithRowsOfValue (copy constructor)

Initializes this object using the contents of the CQueryWithRowsOfValue object passed as a parameter. A new object is created and initialized from the passed object.
Required
Implemented by the CQueryWithRowsOfValue class.
Prototype
CQueryWithRowsOfValue::CQueryWithRowsOfValue( const CQueryWithRowsOfValue& otherObject)
Input arguments
otherObject
The CQueryWithRowsOfValue object to be copied.
Return values
None
See also
CQueryWithRowsOfValue::~CQueryWithRowsOfValue (destructor)
Frees all resources for the CQueryWithRowsOfValue object.
Required
Prototype
CQueryWithRowsOfValue::~CQueryWithRowsOfValue()
Appendix A
157
Input arguments
None
Return values
None
See also
CQueryWithRowsOfValue::CQueryWithRowsOfValue (new object constructor) CQueryWithRowsOfValue::CQueryWithRowsOfValue (copy object constructor)
CQueryWithRowsOfValue::CQueryWithRowsOfValue (new object constructor)

A container that holds a query object and a CRowsOfValue object to be used when creating the query object. Some queries need data values that are used at runtime to expand the query syntax before it is used. The list of CRowsOfValue objects contains the rows of data values needed. This method creates a new CQueryWithRowsOfValue object.
Required
Prototype
CQueryWithRowsOfValue::CQueryWithRowsOfValue( const CQuery* pQuery, const CRowsOfValueList* pValues)
Input arguments
pQuery
The CQuery object to be stored in this object.

pValues
Some queries need data values that are used at runtime to expand the query syntax before it is used. This parameter contains the CRowsOfValueList object with data values needed.
Return values
None
158 Developers Guide
See also
CQueryWithRowsOfValue::GetQuery
Required
Prototype
CQuery* CQueryWithRowsOfValue::GetQuery()
Input arguments
None
Return values
CQuery*
See also
CQueryWithRowsOfValue::GetRowsOfValueList CQueryWithRowsOfValue::SetQuery
CQueryWithRowsOfValue::GetRowsOfValueList
Required
Prototype
CRowsOfValueList* CQueryWithRowsOfValue:GetRowsOfValue()
Input arguments
None
Return values
CRowsOfValueList*
Returns the CRowsOfValueList object with the data values needed to expand the query with data values that are available at runtime.
See also
CQueryWithRowsOfValue::SetRowsOfValueList
CQueryWithRowsOfValue::SetQuery
Sets the CQuery object that was created using one of the queries defined on the Query tab of the AR Mapping Information window.
Required
Prototype
void CQueryWithRowsOfValue::SetQuery( CQuery* pQuery)
Input arguments
pQuery
Return values
None
See also
CQueryWithRowsOfValue::GetQuery
CQueryWithRowsOfValue::SetRowsOfValueList
Sets the CRowsOfValueList object needed to expand the query at runtime. Some queries need data values that are used at runtime to expand the query syntax before it is used. This parameter contains the CRowsOfValueList object with the data values needed object that was created to expand the query to limit the exchanged data.
160
Developers Guide
Required
Prototype
void CQueryWithRowsOfValue::SetRowsOfValue( CRowsOfValueList* pValueList)
Input arguments
pValueList
Some queries need data values that are used at runtime to expand the query syntax before it is used. This parameter contains the CRowsOfValueList object with the data values needed to expand the query.
Return values
None
See also
CQueryWithRowsOfValue::GetRowsOfValueList
Appendix A
161
162
Developers Guide
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
$KEYLIST$ reserved word 31, 35, 60
C
CBaseAdapter (constructor) method 80 CBaseAdapter (destructor) method 80 CBaseAdapter object description of 47 methods for 80 role in debugging 77 role in logging 77 use in building an adapter 5254 CEIEDataExchangeDef object, methods for 108 class library definition of 21 files installed 29, 30 CListOfRule object 46, 145 CListOfRuleWithValue object 46, 146 CloseConnection method description of 81 use in building an adapter 56 CNewAdapter object 54 CNewRule object 59 code requirements 28 command support methods required by adapter 68 compiler requirements 28 configuring adapter initialization parameters 35 constant| reserved word 34 container 34 CQuery (copy constructor) method 123 CQuery (destructor) method 124 CQuery (new object constructor) method 125 CQuery object description of 44, 48 methods for 123130 CQueryWithListOfRuleValue (copy constructor) method 152 CQueryWithListOfRuleValue (destructor) method 152 CQueryWithListOfRuleValue (new object constructor) method 153 CQueryWithListOfRuleValue object methods for 152156
A
adapter documenting 72 installer, building 71 licensing 71 registering 70 uninstalling 72 Adapter Development Kit code requirements 28 compiler requirements 28 debugging facilities 7778 files installed 28, 29, 31 logging facilities 7677 Adapter Development Kit interface 21 adapter initialization parameters, configuring 35 adapter licenses 22 Adapter object class 47 adapter rule syntax list, creating 36 Adapter string 70, 71 adapter template default location 53 definition of 21 files installed 31 preparing the development environment 54, 55 ADK_ERROR return value 56 ADK_OK return value 56 ADK_WARNING return value 56 AR System API documentation 21 audience for this book 11
B
BMC Atrium Integration Engine, introduction to 18 BMC Software, contacting 2 building an adapter installer 71
Index
163
CQueryWithRowsOfValue (copy constructor) method 157 CQueryWithRowsOfValue (destructor) method 157 CQueryWithRowsOfValue (new object constructor) method 158 CQueryWithRowsOfValue object description of 47 methods for 157161 CreateNewQuery method description of 82 use in building an adapter 61 CreateNewRule method description of 83 use in building an adapter 57 CreateQueryString method description of 84 use in building an adapter 62 CreateRuleValues method description of 85 use in building an adapter 64 creating an adapter rule syntax list 36 creating CBaseAdapter object 54 CRowsOfValueList object 45, 144 CRule (copy constructor) method 113 CRule (destructor) method 114 CRule (new rule constructor) method 114 CRule object description of 42, 47 methods for 113123 role in debugging 7778 CRuleWithValue (constructor) method 147 CRuleWithValue (copy constructor) method 148 CRuleWithValue (destructor) method 148 CRuleWithValue object description of 47 methods for 147 customer support 3 CValue (copy constructor) method 131 CValue (destructor) method 131 CValue (empty constructor) method 132 CValue object methods for 131, 142 CValueList object 45, 143 data transfer, direction of 18 data update methods required by adapter 65 data values, Integration Engine reserved words 34 database connection methods required by adapter 56 debugging facilities CBaseAdapter object, role of 77 CRule object, role of 7778 methods used 77, 78 overview 76 setting your adapter name 55 DeepClone method 115 default location of installed files for Adapter Development Kit 29 defining rule syntax data values 34 queries 35 DeleteRuleValues method description of 87 use in building an adapter 66 development environment code requirements 28 compiler requirements 28 directory structure 29 files installed 29, 31 preparing 5255 direction of data transfer 18 dllmain object description of 47 use in building an adapter 52, 54 DoCommand method description of 89 use in building an adapter 68 documentation, related 12 documenting an adapter 72
E
eie.reg file 71, 72 eiexfer utility, definition of 21 Event Request interface, definition of 21
F
files installed adapter template 31 class library 29, 30 default location 29 overview 28 sample flatfile adapter 31 function| reserved word 34
D
data creation methods required by adapter 64 data deletion methods required by adapter 66 Data Exchange application 20 data exchange, definition 20 Data object class 45 data retrieval methods required by adapter 63 164 Developers Guide
G
GetContainer method query 125 rule 116 GetDataExchangeName method 108 GetDecimal method 132 GetEIEDataType method description of 116 use in building an adapter 59 GetErrMsg method query 126 rule 117 GetFirstVenConfigParam method 109 GetInt method 133 GetKeyList method description of 90 use in building an adapter 6062 GetLicenseString method 92 GetProductName method 93 GetQuery method CQueryWithListOfRuleValue 154 CQueryWithRowsOfValue 159 GetQueryString method 127 GetReal method 134 GetRowsOfValueList method 159 GetRule method 149 GetRuleAttributes method description of 93 role in debugging 78 use in building an adapter 5657 GetRuleString method 118 GetRuleValues method description of 95 not used for commands 68 use in building an adapter 63 GetRuleWithValueList method 155 GetStatusMessage method 96 GetString method 135 GetTime method 135 GetType method 136 GetULong method 137 GetValue method 150 GetVenConfigParamAt method 110 GetVenConfigParamLength method 111 GetVenDataType method 118
I
implementing required methods command support 68 data creation 64 data deletion 66 data retrieval 63 data update 65 database connection 56 initialization 55 key list creation 60, 61 rule validation 57 transaction processing 67 initialization methods required by adapter 55 Initialization Phase role in building an adapter 5658 initialization phase overview 2223 Initialize method description of 97 use in building an adapter 55 installation control file 22 InstallDir string 70, 71 installed files adapter template 31 class library 30 default location 29 overview 28 sample flatfile adapter 31 installer for adapter, building 71 Integration Engine reserved words 31, 60 Integration Engine reserved words, data values 34 Integration Engine service language translation for log 76 overview 20 registering an adapter 70 IsDirectionARDataIntoVendor method 112 IsDirectionVendorDataIntoAR method 112 IsNull method 137 IsValid method query 127 rule 119
K
key 60 key list creation methods required by adapter to support $KEYLIST$ 60 with a query 60, 61 without a query 60 key queries 35 Index 165
H
header files installed 29
L
language translation for log file 76 library files installed 30 library. See class library licensing an adapter 22, 71 location of installed files 29 log messages, recording 76 logging facilities CBaseAdapter object, role of 77 language translation 76 overview 76 SetLogMessage method 77 setting your adapter name 55
Q
queries defining rule syntax for 35 key 60 key query 35 row-level query 35
R
Recording log messages 76 registering an adapter overview 70 Windows 70 related documentation 12 removing adapters 72 requirements code 28 compiler 28 row-level queries 35 rule syntax data values 34 Integration Engine reserved words 34 queries 35 reserved words, Integration Engine 31, 60 rule validation methods required by adapter 57
M
methods required to build adapter command support 68 data creation 64 data deletion 66 data retrieval 63 data update 65 database connection 56 initialization 55 rule validation 57 transaction processing 67 Microsoft Visual C++ 28
S
sample flatfile adapter definition of 22 files installed 31 SetContainer method query 128 rule 120 SetDecimal method 138 SetErrMsg method query 129 role in debugging 78 rule 120 SetInt method 139 SetLogMessage method description of 99 role in logging 77 SetNull method 139 SetQuery method CQueryWithListOfRuleValue 155 CQueryWithRowsOfValue 160 SetQueryString method 129 SetReal method 140 SetRowsOfValueList method 160 SetRule method 150
O
objects classes of 45, 47 descriptions of 42, 44, 45, 46, 47, 48, 143, 144, 145, 146 methods for 80, 108, 113123, 123130, 131, 142, 147, 152156, 157161 OpenConnection method description of 98 use in building an adapter 56
P
process| reserved word 34 processing phase 2324 product support 3
166
Developers Guide
SetRuleString method 121 SetRuleWithValueList method SetStatusMessage method description of 100 role in debugging 77 use in building an adapter 64, 65, 66, 67, 68 SetString method 141 SetTime method 141 setting your adapter name 55 SetULong method 142 SetValidity method query 130 role in debugging 78 rule 122 SetValue method 151 SetVenDataType method 122 sql| reserved word 34 StartTransaction method description of 101 use in building an adapter StopTransaction method description of 102 use in building an adapter support, customer 3 SupportTransaction method description of 103 use in building an adapter syntax. See rule syntax
156
V
ValidateQualifier method description of 107 use in building an adapter 6162
56, 57, 58, 61, 62, 63,
W
Windows Add/Remove Programs 72 registering an adapter 70 removing adapters 72 system registry 70, 72
67
67
67
T
targetprocess| reserved word 34 targetsql| reserved word 34 technical support 3 Terminate method description of 104 use in building an adapter 56 transaction processing methods required by adapter 67
U
uninstalling adapters 72 UNIX eie.reg file 71, 72 registering an adapter 71 removing adapters 72 UpdateRuleValues method description of 105 use in building an adapter 6566
Index
167
168
Developers Guide
*65296* *65296* *65296* *65296*
*69256*

AIE Developer

Încărcat de

Informații document

Descriere originală:

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

AIE Developer

Încărcat de

Drepturi de autor:

Formate disponibile

BMC Atrium Integration Engine 7.1.

Adapter Development Kit Developers Guide

Contacting BMC Software

United States and Canada

Outside United States and Canada

Restricted Rights Legend

Support by telephone or email

Before Contacting BMC Software

Class library objects used by the adapter

BMC Atrium Integration Engine 7.1.00

Integration Engine documents

Administrators Print and PDF

BMC Atrium CMDB documents

Title BMC Atrium CMDB 2.1.00 Data Model Help

HTML (product DVD only)

BMC Atrium Integration Engine 7.1.00

Administrators PDF and Print Administrators PDF and Print

Administrators PDF and and Print Programmers

BMC Atrium Integration Engine 7.1.00

Understanding Integration Engine

Understanding Integration Engine

BMC Atrium Integration Engine 7.1.00

BMC Atrium Integration Engine

Integration Engine components

Integration Engine components

AR System database or BMC Atrium CMDB

Data Exchange application Application Pending form

Integration Engine service

Event Request interface (eiexfer)

Adapter Development Kit interface

Flat File adapter

Other Other Other data store data store data store

Custom adapters (not included)

Understanding Integration Engine

BMC Atrium Integration Engine 7.1.00

Data Exchange application

Integration Engine service

Integration Engine components

Event Request interface

Adapter Development Kit interface

Understanding Integration Engine

BMC Atrium Integration Engine 7.1.00

The data transfer process

The initialization phase

The data transfer process

b Connects to data stores to validate rules.

The processing phase

Understanding Integration Engine

BMC Atrium Integration Engine 7.1.00

To get started using Integration Engine

Understanding Integration Engine

BMC Atrium Integration Engine 7.1.00

Understanding the development environment

Understanding the development environment

BMC Atrium Integration Engine 7.1.00

Description of installed files

Description of installed files

Description Overall installation directory Binary files Sample adapters

Windows Yes Yes Yes Yes Yes Yes

UNIX Yes Yes No Yes Yes Yes Yes Yes No Yes

Class library files

for data types and rule types.

Understanding the development environment