BMC Atrium Integration Engine 7.6.04

BMC Atrium Integration Engine 7.6.
04
Adapter Development Kit

Developers Guide
January 2011
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
(01) 713 918 8000
Fax
713 918 8000
Outside United States and Canada

Telephone
(01) 713 918 8800
If you have comments or suggestions about this documentation, contact Information Development by email at
doc_feedback@bmc.com.
Copyright 19992011 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.
AIX, DB2, and IBM are trademarks or registered trademarks of International Business Machines Corporation in the United
States, other countries, or both.
Linux is the registered trademark of Linus Torvalds.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their
respective owners.
UNIX is a registered trademark of The Open Group in the US and other countries.
BMC Software considers information included in this documentation to be proprietary and confidential. Your use of 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. From this website, you can:
Read overviews about support services and programs that BMC Software offers.
Find the most current information about BMC Software products.
Search a database for problems similar to yours and possible solutions.
Order or download product documentation.
Report a problem or ask a question.
Subscribe to receive email notices when new product versions are released.
Find worldwide BMC Software support center locations and contact information, including email addresses, fax
numbers, and telephone numbers.
Support by telephone or email

In the United States and Canada, if you need technical support and do not have access to the Web, call 800 537 1813 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:
Product information
Product name
Product version (release number)
License number and password (trial or permanent)
Operating system and environment information
Machine type
Operating system type, version, and service pack
System hardware configuration
Serial numbers
Related software (database, application, and communication) including type, version, and service pack or
maintenance level
Sequence of events leading to the problem
Commands and options that you used
Messages received (and the time and date that you received them)
Product error messages

Messages from the operating system, such as file system full
Messages from related software
License key and password information

If you have a question about your license key or password, contact Customer Support through one of the following
methods:
E-mail customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>,

such as SupID:12345.)
In the United States and Canada, call 800 537 1813. Outside the United States and Canada, contact your local support
center for assistance.
Submit a new issue at http://www.bmc.com/support.
Contents
BMC Atrium Core documentation
11
Chapter 1
15
Understanding BMC Atrium Integration Engine
Overview of BMC Atrium Integration Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

BMC Atrium Integration Engine components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Exchange application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AIE service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Event Request interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adapter Development Kit interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data transfer process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initialization phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Processing phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16
17
18
19
19
19
20
20
21
22
23
Chapter 2
25
Understanding the development environment
Code requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiler requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling an adapter template on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Description of installed files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adapter template files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample flat file adapter files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26
26
26
27
28
29
30
Chapter 3
31
Defining the adapter rule syntax
Defining the rule syntax to describe a data value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Defining the rule syntax to support queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring adapter initialization parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating an adapter rule syntax list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
32
33
33
34
Chapter 4
37
Class library objects used by the adapter
Data exchange objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CEIEDataExchangeDef object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CQuery object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
38
38
40
42
Data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
List objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
CValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
CRowsOfValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
CListOfRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
CListOfRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Pointer objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
CRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
CQueryWithListOfRuleValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
CQueryWithRowsOfValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Adapter objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
dllmain object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
CQuery object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Chapter 5
Methods required by the adapter
49
Preparing the adapter template development environment . . . . . . . . . . . . . . . . . . . . . 50

Creating an adapter-derived CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . 52
Setting your adapter name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Implementing initialization methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Implementing database connection methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Implementing rule validation methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Getting and validating a CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Setting the data type of the value described in the CRule object . . . . . . . . . . . . . . 57
Renaming the CNewRule object in the adapter template . . . . . . . . . . . . . . . . . . . . 57
Implementing key list creation methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Creating a key list without a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Creating a key list with a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Implementing the data retrieval method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Implementing the data creation method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Implementing the data update method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Implementing data deletion methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Implementing transaction processing methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Implementing command support methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Chapter 6
Packaging an adapter
67
Registering an adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Licensing an adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Building an installer for the developed adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Removing adapters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Sample data exchanges and data mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Documenting the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Chapter 7
Logging and debugging
71
Log and debug tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Recording log messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Using the CBaseAdapter object to record log events . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6
Adapter Development Kit Developers Guide
Recording debug events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Using the CBaseAdapter object to record debug events . . . . . . . . . . . . . . . . . . . . . 74
Using the CRule object to record debug events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Appendix A
Class library reference
75
CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
CBaseAdapter::CBaseAdapter (constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
CBaseAdapter::~CBaseAdapter (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
CBaseAdapter::CloseConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
CBaseAdapter::CreateNewQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
CBaseAdapter::CreateNewRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
CBaseAdapter::CreateQueryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
CBaseAdapter::CreateRuleValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
CBaseAdapter::DeleteRuleValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
CBaseAdapter::DoCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
CBaseAdapter::GetKeyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
CBaseAdapter::GetLicenseString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
CBaseAdapter::GetProductName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
CBaseAdapter::GetRuleAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
CBaseAdapter::GetRuleValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
CBaseAdapter::GetStatusMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
CBaseAdapter::Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
CBaseAdapter::OpenConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
CBaseAdapter::SetLogMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
CBaseAdapter::SetStatusMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
CBaseAdapter::StartTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
CBaseAdapter::StopTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
CBaseAdapter::SupportTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
CBaseAdapter::Terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
CBaseAdapter::UpdateRuleValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
CBaseAdapter::ValidateQualifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
CEIEDataExchangeDef object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
CEIEDataExchangeDef::GetDataExchangeName. . . . . . . . . . . . . . . . . . . . . . . . . . 101
CEIEDataExchangeDef::GetFirstVenConfigParam . . . . . . . . . . . . . . . . . . . . . . . . 101
CEIEDataExchangeDef::GetVenConfigParamAt . . . . . . . . . . . . . . . . . . . . . . . . . . 102
CEIEDataExchangeDef::GetVenConfigParamLength . . . . . . . . . . . . . . . . . . . . . . 103
CEIEDataExchangeDef::IsDirectionARDataIntoVendor . . . . . . . . . . . . . . . . . . . . 104
CEIEDataExchangeDef::IsDirectionVendorDataIntoAR . . . . . . . . . . . . . . . . . . . . 104
CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
CRule::CRule (copy constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
CRule::~CRule (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
CRule::CRule (new rule constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
CRule::DeepClone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
CRule::GetContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
CRule::GetEIEDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
CRule::GetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
CRule::GetRuleString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
CRule::GetVenDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
CRule::IsValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
7
CRule::SetContainer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
CRule::SetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
CRule::SetRuleString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
CRule::SetValidity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
CRule::SetVenDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
CQuery object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
CQuery::CQuery (copy constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
CQuery::~CQuery (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
CQuery::CQuery (new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
CQuery::GetContainer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
CQuery::GetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
CQuery::GetQueryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
CQuery::IsValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
CQuery::SetContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
CQuery::SetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
CQuery::SetQueryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
CQuery::SetValidity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
CValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
CValue::CValue (copy constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
CValue::~CValue (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
CValue::CValue (empty constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
CValue::GetDecimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
CValue::GetInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
CValue::GetReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
CValue::GetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
CValue::GetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
CValue::GetType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
CValue::GetULong. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
CValue::IsNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
CValue::SetDecimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
CValue::SetInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
CValue::SetNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
CValue::SetReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
CValue::SetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
CValue::SetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
CValue::SetULong . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
CValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
CRowsOfValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
CListOfRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
CListOfRuleWithValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
CRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
CRuleWithValue::CRuleWithValue (constructor) . . . . . . . . . . . . . . . . . . . . . . . . . 127
CRuleWithValue::CRuleWithValue (copy constructor) . . . . . . . . . . . . . . . . . . . . . 128
CRuleWithValue::~CRuleWithValue (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . 128
CRuleWithValue::GetRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
CRuleWithValue::GetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
CRuleWithValue::SetRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
CRuleWithValue::SetValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
CQueryWithListOfRuleValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
CQueryWithListOfRuleValue::CQueryWithListOfRuleValue
(copy constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CQueryWithListOfRuleValue::CQueryWithListOfRuleValue (destructor) . . . .
(new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CQueryWithListOfRuleValue::GetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CQueryWithListOfRuleValue::GetRuleWithValueList . . . . . . . . . . . . . . . . . . . . .
CQueryWithListOfRuleValue::SetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CQueryWithListOfRuleValue::SetRuleWithValueList . . . . . . . . . . . . . . . . . . . . .
CQueryWithRowsOfValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CQueryWithRowsOfValue::CQueryWithRowsOfValue
(copy constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CQueryWithRowsOfValue::~CQueryWithRowsOfValue
(destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
(new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CQueryWithRowsOfValue::GetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CQueryWithRowsOfValue::GetRowsOfValueList. . . . . . . . . . . . . . . . . . . . . . . . .
CQueryWithRowsOfValue::SetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CQueryWithRowsOfValue::SetRowsOfValueList . . . . . . . . . . . . . . . . . . . . . . . . .
Index
131
131
132
132
133
133
133
134
134
134
135
135
136
136
137
139
10
This section describes the complete set of BMC Atrium Core documentation,
including manuals, help systems, videos, and so on.
Unless otherwise noted, documentation is available free of charge on the BMC
Atrium Core documentation media (DVD or Electronic Product Download
bundle) and on the BMC Customer Support site, at http://www.bmc.com/
support.
To find this documentation on the BMC Customer Support site, choose Product
Documentation > Supported Product A-Z List > BMC Atrium CMDB Enterprise
Manager >7.6.04
Title
Description
Audience
Atrium Integrator 7.6.04

User's Guide
Information about defining source and target

connections, creating jobs and transformations,
editing and monitoring jobs, and other Atrium
Integrator concepts.
Users who are responsible

for setting up data transfer
integrations between
external data stores and
BMC Atrium CMDB.
BMC Atrium CMDB 7.6.04 Information about setting permissions, configuring Configuration managers,
Administrator's Guide
federation, modifying the data model, configuring application administrators,
an impact model, and other administrative tasks in and asset analysts.
BMC Atrium Configuration Management Database
(BMC Atrium CMDB).
BMC Atrium CMDB 7.6.04 Hierarchical diagram of all classes in the Common Configuration managers,
Common Data Model
Data Model (CDM), including unique attributes and application administrators,
Diagram
applicable relationships.
and asset analysts.
BMC Atrium CMDB
7.6.04 Data Model Help
Description and details of superclasses, subclasses,

attributes, and relationship classes for each class.
Contains only information about the CDM at first,
but you can update it to include information about
data model extensions that you install.
Configuration managers,
application administrators,
and asset analysts.
Note: This Help is provided in HTML and is available
on the BMC Atrium Core media. It is not available

on the BMC Customer Support site.
11
BMC Atrium Integration Engine 7.6.04
Title
Description
Audience
BMC Atrium CMDB 7.6.04 Best practices for using the classes that BMC
Data Modeling Guide
provides for BMC Atrium CMDB (both the CDM
and extensions) to model complex business entities, and asset analysts.
focusing on the use of multiple related CIs to model
an entity rather than on general information about a
class or attribute.
BMC Atrium CMDB
7.6.04 Javadoc Help
Information about Oracle Java classes, methods, and Application programmers.

variables that integrate with BMC Atrium CMDB.

BMC Atrium CMDB 7.6.04 Information about normalizing data in BMC Atrium Configuration managers,
Normalization and
CMDB and reconciling CIs from different data
Reconciliation Guide
providers into a single production dataset.
and asset analysts.
BMC Atrium CMDB
7.6.04 Online Help
Help for using and configuring BMC Atrium CMDB,

including Atrium Integrator, BMC Atrium Product
Catalog, Reconciliation Engine, Normalization
Engine, and so on.
asset analysts, and users
that work with CIs and need
to understand the
relationships that exist
through the Help links in the BMC Atrium CMDB
within BMC Atrium CMDB.
user interface. It is not available on the BMC
Customer Support site.
BMC Atrium CMDB 7.6.04 Information about using BMC Atrium CMDB,
User's Guide
including searching for and comparing CIs and
relationships, relating CIs, viewing history, running
impact simulations, and viewing federated data.
Users that work with CIs

and need to understand the
relationships that exist
within BMC Atrium CMDB.
BMC Atrium Core: Taking

Your Data Into Production
End to End
and asset analysts.
End-to-end high-level steps for bringing data into

BMC Atrium CMDB from a third-party source and
making it available in your production dataset.
Note: This Flash video is available on the BMC
Atrium Core media. It is not available on the BMC

Customer Support site.
BMC Atrium Core 7.6.04
Compatibility Matrix
Information about the BMC Atrium Core

configurations that are expected to work together
based on design, testing, or general understanding
of the interaction between products.
Note: Download the BMC Atrium Core 7.6.04
Compatibility Matrix from the BMC Customer

Support site at http://www.bmc.com/
support/reg/remedy-compatibilitytables.html?c=n.
12
and asset analysts.
Title
Description
Audience

Concepts and Planning
Guide
Information about CMDB concepts and high-level

steps for planning and implementing BMC Atrium
Core.
Anyone who wants to learn

about and understand BMC
Atrium Core products,
CMDBs in general, and the
functionality of BMC
Atrium CMDB in particular.
IT leaders, configuration
managers, application
administrators, and asset
analysts are some who will
benefit from this
information.

Information about creating API programs using C
Developers Reference Guide API functions and data structures.
Application administrators
and programmers.

Installation Guide
Information about installing, upgrading, and

uninstalling BMC Atrium Core features.
Application administrators.

Master Index
Combined index of all guides.
Everyone.

Product Catalog and DML
Guide
Information about configuring the Product Catalog System administrators, IT

and DML, adding products, and creating aliases for managers, network
managers, and other
products, manufacturers, and categorizations.
qualified personnel who are
familiar with their
computing and networking
environment.

Release Notes
Information about new features, known issues, and Everyone.

other late-breaking topics.

Troubleshooting Guide
Information about resolving issues with BMC

Application administrators,
Atrium Core components, including API, filter, and programmers, and BMC
console error messages and their solutions.
Support personnel.

Web Services Help
Information about using BMC Atrium Core Web

Application administrators
Services, including how to publish and find
and programmers.
interfaces in the Web Services Registry, set versions,
disambiguate web services, configure security
policies and encryption, and use BMC Atrium Core
Web Services data structures and operations.

BMC Atrium Integration
Engine 7.6.04 ADK
Developer's Guide
Information about how to build adapters that can

transfer information between an external data store
and either BMC Remedy AR System forms or BMC
Atrium CMDB.
Developers who have a

basic understanding of BMC
Atrium Integration Engine
and want to build adapters
that can exchange data
between two data sources.
13
Title
Description
Audience

through the Help links in the BMC Atrium
either BMC Atrium CMDB
Integration Engine user interface. It is not
or BMC Remedy
available on the BMC Customer Support site.
AR System.
BMC Atrium Integration Help for using and configuring BMC Atrium
Engine 7.6.04 Online Help Integration Engine.
BMC Atrium Integration

Information about creating data exchanges and data
Engine 7.6.04 User's Guide mappings, defining rules and queries, activating
event-driven data exchanges, defining connection
settings, and other BMC Atrium Integration Engine
concepts.

either BMC Atrium CMDB
or BMC Remedy
AR System.
Mapping Your Data to

Spreadsheet that maps common IT objects to the
BMC Atrium CMDB 7.6.04 appropriate class, whether part of the CDM or an
Classes
extension. This spreadsheet also includes
information about further categorizing instances
using key attributes, and best practices for creating
normalized relationships.
and asset analysts.
14
Chapter
Understanding BMC Atrium

Integration Engine
The BMC Atrium Integration Engine enables you to transfer data between an
external data store and BMC Remedy Action Request System (BMC Remedy
AR System) forms or BMC Atrium Configuration Management Database (BMC
Atrium CMDB) classes. You can use the included adapters for Microsoft SQL
Server, Oracle, IBM DB2 Universal Database, XML, and flat files such as
comma-separated value (CSV) files. You can also use the BMC Atrium Integration
Engine Adapter Development Kit to build your own adapters to meet your
organizations specific needs.
Atrium Integrator replaces BMC Atrium Integration Engine. You can continue
using BMC Atrium Integration Engine for existing data mappings and exchanges,
but BMC recommends that you use Atrium Integrator for all new data transfers.
BMC Atrium Integration Engine will be deprecated in a future release.
The following topics are provided:

Overview of BMC Atrium Integration Engine (page 16)

BMC Atrium Integration Engine components (page 17)
Data transfer process (page 20)
Performance considerations (page 22)
Getting started (page 23)
Chapter 1
15
Overview of BMC Atrium Integration Engine

With BMC Atrium Integration Engine, you can schedule bulk data transfers and
event-based integrations initiated by either the source, target, or any other
application. You can also use BMC Atrium Integration Engine for initial data load,
incremental data transfers, and data synchronization. You can build links between
BMC Remedy IT Service Management (BMC Remedy ITSM) applications and
Enterprise Resource Planning (ERP), Customer Relationship Management, Supply
Chain Management, and other enterprise applications.
For example, you can use BMC Atrium Integration Engine to:
Synchronize IT data from a discovery application with BMC Atrium CMDB,

where it can be reconciled with data from other sources to your production
dataset
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
Figure 1-1 shows how you can transfer data in either direction between an external
data store and a BMC Remedy AR System application or BMC Atrium CMDB
class.
Figure 1-1: Overview of the data transfer process
BMC Remedy AR System
database
External
data store
Data
object
BMC Atrium
Integration
Engine
BMC Remedy
AR System
form
BMC Atrium
CMDB class
During the data transfer, BMC Atrium 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
16
BMC Atrium Integration Engine components

BMC Atrium Integration Engine has the following main components:
Data Exchange application (page 18)

AIE service (page 19)
Event Request interface (page 19)
Adapter Development Kit interface (page 19)
Figure 1-2 shows how these components work with other BMC Atrium Integration
Engine components and related objects.
Figure 1-2: BMC Atrium Integration Engine components
BMC Remedy AR System

database or BMC Atrium CMDB
Data Exchange
application
Application
Pending form
BMC Remedy BMC Atrium
AR System
CMDB
APIs
APIs
BMC Atrium
Integration
Engine
AIE
service
Event Request
interface (aiexfer)
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
Adapters provided by BMC Atrium Integration Engine
Chapter 1
Other
Other
Other
data store data store data store
Custom adapters (not included)
17
Data Exchange application

The Data Exchange application is a group of BMC Remedy AR System forms that
is available from your BMC Remedy AR System home page as the AIE Console
link. Use the data exchange application to work with the following integration
objects:
A data exchange is the object that you execute to move data with BMC Atrium
Integration Engine, and a single execution of a data exchange is called a 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 BMC Remedy 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. It also 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
options.
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 BMC Atrium 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 BMC Atrium Integration Engine instances you defined at installation
time and edit some settings for them.
Display version numbers for BMC Atrium Integration Engine and related
products.
18
AIE service
The AIE 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 provide access to the external data and respond to
calls from BMC Atrium Integration Engine during a data exchange.
The AIE service can connect to any Microsoft Windows or UNIX BMC Remedy
AR System server. It does not need to reside on the same computer as the BMC
Remedy AR System server or the external data stores, but can be on any computer
that is network-connected to both of these.
The AIE service runs as a client to the BMC Remedy AR System server using the
BMC Remedy AR System application programming interface (API). For
information about the BMC Remedy AR System APIs, see the BMC Remedy Action
Request System 7.6.04 C API Reference guide.
Event Request interface

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

The BMC Atrium Integration Engine Adapter Development Kit (ADK) contains all
the components needed to create an adapter. You use the BMC Atrium Integration
Engine installer to install the ADK components. The ADK components are loaded
during installation and placed in a subdirectory of the BMC Atrium Integration
Engine installation directory.
The ADK contains:
A class library that defines the interface between the AIE service and an adapter.
You can use the class library as a foundation for building your adapters. 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.
Chapter 1
19
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.
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 BMC
Remedy AR System to a flat file and vice versa. A 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 BMC Atrium Integration Engine installer.
After an adapter is complete, you can package it with BMC Atrium Integration
Engine and then modify the BMC Atrium Integration Engine installer to include
your adapter.
Data transfer process

When you start the AIE service, it locates data exchanges by reading entries in the
Data Exchange application. When BMC Atrium Integration Engine detects a data
exchange, the AIE service loads the adapter that is associated with that data
exchange.
A data transfer has two phases: the initialization phase, in which a data exchange is
prepared to run, followed by the processing phase, in which the data is transferred.
Initialization phase
The initialization phase prepares a data exchange to run. The AIE service performs
the following tasks:
Step 1 Loads data exchange rules.
The AIE service loads all the rules defined in the Data Exchange application and
prepares the C++ objects defined by the Adapter Developer Kit. The rules include
the data exchange definition, the data mapping rules, and all adapter-defined
configuration parameters and rules.
20
Data transfer process
Step 2 Connects to data stores to validate rules.
The AIE service connects to both the source and target data stores. A BMC Remedy
AR System form or BMC Atrium CMDB class can serve as either the source or the
target.
The AIE service does not transfer data at this point, but a connection to both data
stores is necessary to validate rules.
Step 3 Validates data exchange rules.
The AIE service validates rules owned by BMC Atrium Integration Engine. During
validation, the AIE 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.
Step 4 Disconnects from data sources.
After the rules are validated, the AIE service disconnects from both data sources.
Step 5 Starts a thread.
At the end of the initialization phase, the AIE service starts a thread to manage the
data exchange process.
During this phase, the BMC Atrium Integration Engine debug facilities record all
data exchange and data handling rules.
Processing phase
In the processing phase, the transfer of data takes place. This phase begins when a
data exchange is executed, which can be scheduled or event driven.
During the processing phase, the AIE service performs the following tasks:
Step 1 Refreshes the data exchange.
Before data is exchanged, the AIE service checks the Data Exchange application to
determine if any changes were made to the data exchange definition. If changes
were made, the AIE service updates the loaded data exchange with the new
definition.
Step 2 Starts a separate thread for each data exchange.
The AIE service connects to both the source and target data stores for each data
exchange. The AIE service communicates through the BMC Remedy AR System
API or BMC Atrium CMDB API to pull data out of and push data into those data
stores. The AIE service uses the adapter to pull data out of and push data into the
external data store.
Chapter 1
21
Step 3 Locates data to be exchanged.
The AIE service obtains a list of keys from BMC Remedy AR System or BMC
Atrium CMDB and prompts the adapter to create a list of keys. The AIE service
converts the keys to a common data type (if necessary) and then sorts the keys into
the same order so that it can compare the key lists.
Step 4 Transfers data.
The AIE service compares the keys and determines from the data exchange
definition how new and existing records should be treated. The AIE 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.
If during data transfer, the AIE service or the BMC Remedy AR System server
stops responding, BMC Atrium Integration Engine provides failover support for
the incomplete data exchanges. The next time the AIE service starts, the data
exchanges resume from the point they had stopped, thus avoiding repetition of
data insertion.
Step 5 Disconnects from data stores.
After all keys are processed, the data transfer is considered complete. The AIE
service closes the connection to BMC Remedy AR System or BMC Atrium CMDB
and prompts the adapter to close the connection to the external data store.
NOTE
The thread and adapter remain active, unless the data exchange is deactivated in
the Data Exchange application or the AIE service is terminated. In either of those
events, the adapter .dll is released and the thread terminates.
In this phase, the AIE service debug file shows all rules retrieved from the Data
Exchange application and the type of the data defined by the rule. The debug file
also identifies the success or failure of the data transfer and shows a detailed error
message when any errors occur in the AIE service or in BMC Remedy AR System.
Performance considerations
Performance considerations for BMC Atrium Integration Engine are difficult to
quantify because performance is affected by your network, BMC Remedy
AR System, the BMC Remedy AR System server database, and the external data
store load. It is difficult to predict the effect of a specific change on BMC Atrium
Integration Engine performance, but configuration considerations can influence it.
Although 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 your database contains
many records. For example, if you have 1200 records in your database and the
change that 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.
22
Getting started
However, you can use multiple instances, multiple sessions, and multithreading to
increase throughput and improve overall system performance. For more
information, see the BMC Atrium Integration Engine 7.6.04 User's Guide.
Getting started
The following outline illustrate the high-level steps that you take to prepare for
transferring data. See the recommended area of the BMC Atrium Integration
Engine documentation for specific instructions on each step.
NOTE
If you are working in a server group environment, make sure that you have
installed workflow binaries on all servers of the server group; otherwise the BMC
Atrium Integration Engine workflow does not function. For more information
about BMC Atrium Integration Engine working in a server group environment,
see the BMC Atrium Integration Engine 7.6.04 User's Guide.
To get started using BMC Atrium Integration Engine

Step 1 Populate the database field menus for your external data stores using the 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 Using the adapter rule helper utilities section in the BMC
Atrium Integration Engine 7.6.04 User's Guide.
Step 2 Create a data mapping to specify which data should be transferred and where it
should go.
For instructions, see the appropriate data mapping sections in the BMC Atrium
Integration Engine 7.6.04 User's Guide.
Step 3 Create a data exchange to control the execution, direction, and other characteristics
of your data transfers.

For instructions, see the data exchange section of the BMC Atrium Integration
Engine 7.6.04 User's Guide.
Chapter 1
23
24
Chapter
Understanding the
development environment
The Adapter Development Kit (ADK) can reside on any system that meets the
requirements of the development environment.

Code requirements (page 26)

Compiler requirements (page 26)
Compiling an adapter template on UNIX (page 26)
Description of installed files (page 27)
Chapter 2
25
Code requirements
The following code requirements apply to all development platforms:
The code generation must be set to multithreaded.

On Microsoft Windows, the ADK class libraries are coded in Microsoft Visual
C++ .NET 2003.
Compiler requirements
This section provides a list of platforms and their compatible compilers that can be
used for compiling an adapter.
The compiler requires the following platforms:
WindowsMust be compiled using Microsoft Visual C++ .NET 2003, running

on Windows 2003.
UNIXMust be compiled with one of the following 64-bit compilers:

Sun Solaris 9 - Sun Studio 11 or later
HP-UX 11.11 - ANSI C++ A.03.73
HP-UX Itanium 11.23 ia64 - HP aCC++ Compiler C.05.55
IBM AIX 5.3 - Visual Age 9.0
Linux - GCC 4.2.1
Compiling an adapter template on UNIX

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

1 From the BMCAtriumIntegrationEngineInstallationDir/devkit/example/
template directory, export the ADK environment variable to see the
BMCAtriumIntegrationEngineInstallationDir/devkit directory.
2 Change the compilers for the respective environments in the
makefile.unix.samp file as specified:
Solaris: Sun Studio 11

HP-UX 11.11: ANSI C++ A.03.73
HP-UX 11.23: HP aCC++ Compiler C.05.55
AIX: Visual Age 9.0
Linux: GCC 4.2.1
26
Description of installed files
3 Run the following commands from the command line for the respective
environments.
Table 2-1: Commands to compile an adapter template on UNIX
Operating system Command to compile an adapter template
Solaris
gmake f Makefile.unix.samp SOLARIS=1

GETARCH=solsp64
HP-UX 11.11
gmake f Makefile.unix.samp HPUX=1 GETARCH=hppa64
HP-UX 11.23
gmake f Makefile.unix.samp HPUX=1 GETARCH=hpia64
AIX
gmake f Makefile.unix.samp AIX=1 GETARCH=aixp64
Linux
gmake f Makefile.unix.samp LINUX=1 GETARCH=lx64

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

Header files
Library files
Binary files
Adapter template files
Sample flat file adapter files
Installation control file
Installing the ADK creates a series of directories under the
BMCAtriumIntegrationEngineInstallationDir\devkit directory. If you
installed in the default location, the directory structure is as shown in Table 2-2.
Table 2-2: Directory structure of the ADK (part 1 of 2)
Directory or file name
Description
Windows
UNIX
BMCAtriumIntegrationEngineInstallati
onDir\devkit (Windows)
Overall installation directory
Yes
Yes
bin
release
Binary files
Yes
Yes
Yes
No
example
flat file
template
Sample adapters
Yes
Yes
Yes
Yes
Yes
Yes
BMCAtriumIntegrationEngineInstallati
onDir/adk (UNIX)
Chapter 2
27
Table 2-2: Directory structure of the ADK (part 2 of 2)

Directory or file name
Description
Windows
UNIX
include
Header files required for ADK class Yes

library
Yes
lib
Release
Debug
ADK class library
Yes
Yes
Yes
No
Yes
Yes
The files contained in each directory installed under the

BMCAtriumIntegrationEngineInstallationDir\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 BMCAtriumIntegrationEngineInstallationDir\devkit\include
directory contains header files, which are described in Table 2-3.
Table 2-3: ADK header files
Header file
Description
adapter.h
Defines the entry points for the adapter: InitializeAdapterDLL,

TerminateAdapterDLL, CreateInstance, and DeleteInstance.
adkclass.h
Defines the adapter base class: CBaseAdapter. This class is the core component for all
adapters.
adksprt.h
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.
dataexchdef.h Defines the class that provides adapter-specific parameters defined for each data exchange:
CEIEDataExchangeDef.
eiedebug701.h Defines the debug object used to record detailed information about a data exchange:
CEIEDebug.
eietrace701.h Defines the base class for debug services: CEIETrace.
jaconv.h
Defines symbols for Japanese language. This is included in mbutil.h.
mbutil.h
BMC internationalization header file.
templates.h
Defines preprocessor symbols used by the ADK. The ADKCLASS_EXPORTS are defined in
this header file.
28
Library file
The BMCAtriumIntegrationEngineInstallationDir\devkit\lib\release
directory contains a library file that is described in Table 2-4. The Visual C++
project file is configured to point to the correct lib directory. The library names
depend on the environment.
Table 2-4: ADK library file
Library file
Description
Release: adkclass76.lib
Debug: adkclass76d.lib
Class library for the ADK. You should link

this file with your adapter.
Binary file
The BMCAtriumIntegrationEngineInstallationDir\devkit\bin\release
directory contains a binary file that is described in Table 2-5. The adkclass76.dll
is required. The Visual C++ project file is configured to point to the correct bin
directory.
Table 2-5: ADK adapter binary file
Source file
Description
Release: adkclass76.dll
Class library.
(Windows)
Debug: adkclass76d.dll
(Windows)
adkclass.so.1 (UNIX)
Adapter template files

The
BMCAtriumIntegrationEngineInstallationDir\devkit\example\template
directory contains the template files used to create adapters, which are described
in Table 2-6.
Table 2-6: ADK adapter template files (part 1 of 2)
Template files
Description
dllmain.cpp
Defines the entry points for the adapter template:

InitializeAdapterDLL, TerminateAdapterDLL,
CreateInstance, and DeleteInstance.
newadapter.vcproj
(Windows)
Makefile.unix.samp
(UNIX)
Microsoft Visual C++ project file for building an adapter.
newadapter.sln
(Windows only)
Microsoft Visual C++ project workspace for an adapter.
newadpr.cpp
Adapter template skeleton of the CBaseAdapter class that

implements the functions required by the ADK interface.
Chapter 2
29
Table 2-6: ADK adapter template files (part 2 of 2)

Template files
Description
newadpr.h
Defines the adapter template class.
Readme.txt
Standard Visual C++ readme file.
Sample flat file adapter files

The
BMCAtriumIntegrationEngineInstallationDir\devkit\example\flatfile
directory contains the sample flat file adapter files, which are described in
Table 2-7.
Table 2-7: ADK sample flat file adapter files
Sample files
Description
dllmain.cpp
Defines the entry points for the sample: InitializeAdapterDLL,

TerminateAdapterDLL, CreateInstance, and DeleteInstance.
Microsoft Visual C++ project file for building the sample adapter.
Ffadapter.vcproj
(Windows)
Makefile.unix.samp
(UNIX)
ffadapter.sln
(Windows only)
Microsoft Visual C++ project workspace for the sample adapter.
ffadapter.vcproj
Microsoft Visual C++ project file for building the sample adapter.
ffadpr.cpp
Sample adapter implementation of Cflat fileAdapter, which implements the

functions required by the ADK interface.
ffadpr.h
Defines the sample adapter class.
filemgr.cpp
File manager for the flat file database used by the sample adapter.
filemgr.h
Defines the file manager for the flat file database.
getprivate.cpp
GetPrivateProfileString function implementation, which is not available on

a UNIX platform using the standard library.
getprivate.h
GetPrivateProfileString function declaration.
Makefile.unix.sample
Project file you use to build an adapter binary.
misc.cpp
Helper functions used by the sample adapter.
misc.h
Header file for helper functions defined in misc.cpp.
Readme.txt
Standard Visual C++ readme file.
30
Chapter
Defining the 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.

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

Defining the rule syntax to support queries (page 33)
Configuring adapter initialization parameters (page 33)
Creating an adapter rule syntax list (page 34)
Chapter 3
31
Defining the rule syntax to describe a data

value
BMC Atrium Core has its own rule syntax that is used to obtain data from BMC
Remedy 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, 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 AIE 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. For more information about rule syntax, see
the BMC Atrium Integration Engine 7.6.04 User's Guide.
The BMC Atrium Core rule syntax includes the following reserved words:

function|
constant|
process|
targetprocess|
sql|
targetsql|
{ } (curly brackets)
The AIE service defines these reserved words as a set of rules that it recognizes,
and it takes action to support these rules. All other rules are passed directly to the
adapter.
You can use the words reserved for the AIE service as a part of your adapter rule
syntax.
NOTE
The reserved words must not appear at the beginning of a line of adapter rule
syntax. BMC Atrium Core places no other restrictions on the syntax that you define
for an adapter.
32
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. The following
categories of queries are supported:
Key queries limit the records transferred in a data transfer. The AIE 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 AIE
service provides row-level queries to your adapter when asking the adapter to
update or delete a row of data.
Configuring adapter initialization parameters

You must define the database connection information needed to initialize your
adapter.
On the Connection Settings tab of the Data Exchanges Information window, you
can define any adapter initialization parameters that are needed to start your
adapter.
The AIE 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 BMC Atrium Core.
Chapter 3
33
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 AIE:VendorFieldNames window as shown in Figure 3-1.
Figure 3-1: AIE:VendorFieldNames window
When you create an installer for your adapter, it is helpful to populate the
AIE: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 AIE:VendorFieldNames window because you need to
populate the list only once.
Table 3-1 provides a description of each field on the AIE:VendorFieldNames
window.
Table 3-1: AIE:VendorFieldNames window field descriptions (part 1 of 2)
Field name
Description
Vendor Application
Must contain the name of the adapter. Enter the registered name of your adapter in
this field.
Table Name
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.
34
Creating an adapter rule syntax list
Table 3-1: AIE:VendorFieldNames window field descriptions (part 2 of 2)

Field name
Description
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. This field is
also used to populate the External Data Store Fields list on the Response Field Mapping
tab of the AR Mapping Information window.
Field Type
Not presently used in creating the adapter rule syntax list.
Field Data Type
Specifies the data type for a data element in a data transfer, such as FILE_INT,
FILE_FLOAT, and FILE_CHAR.
Is Row
Not presently used in creating the adapter rule syntax list.
Chapter 3
35
36
Chapter
Class library objects used by

the adapter
Class library objects, which fall into several categories, provide the services
required by BMC Atrium Core to complete a data transfer. The objects are used to
transmit information between BMC Atrium Core and the adapter.
NOTE
Data Field Mapping, Response Field Mapping, and Query tabs (and all their fields)
behave identically on both windows.

Data exchange objects (page 38)

Data objects (page 43)
List objects (page 43)
Pointer objects (page 45)
Adapter objects (page 46)
Chapter 4
37
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 AIE service creates data
exchange objects using information obtained from the Data Exchange application.
The following class objects are data exchange objects:
CEIEDataExchangeDef
CRule
CQuery
CEIEDataExchangeDef object
The CEIEDataExchangeDef object provides certain connection settings 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 BMC Remedy
AR System.
The installation directory defined in the adapter registry key used by the AIE
service. The installation directory setting is obtained from the system registry on
Windows. On UNIX, a -y argument is used to provide the installation directory
path till the /service directory to the BMC Atrium Integration Engine binaries.
The adapters reside in the service/bin directory.
38
Figure 4-1 shows the CEIEDataExchangeDef parameters on the Main tab of the
Data Exchanges Information window that are provided to the adapter.
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.
Figure 4-2: Data Exchanges Information windowConnection Settings tab
Parameters
Parameter
values
NOTE
If your external data store type is a comma separated value (CSV) flat file or an
XML flat file, connection parameters do not appear on the Connection Settings tab.
For more information about the Main and Connection Settings tab on the Data
Exchange Information window, see the BMC Atrium Integration Engine 7.6.04
User's Guide.
Chapter 4
39
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 AIE service obtains the adapterdefined 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 that 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
Description
EIE_CHAR
A null-terminated string that requires freeing allocated space. A

NULL pointer of this type is equivalent to using
AR_DATA_TYPE_NULL
EIE_DATE
A data type that maps to the BMC Remedy AR System Date data
type
EIE_DECIMAL
A fixed-point decimal value
EIE_INTEGER
A 32-bit signed integer value
EIE_NULL
A NULL value
EIE_REAL
A 64-bit floating-point value
EIE_TIME
A UNIX-style date/time stamp (number of seconds since 00:00:00

UTC, January 1, 1970)
EIE_TIME_OF_DAY
A field type that maps to the BMC Remedy AR System Time type
field
EIE_ULONG
A 32-bit unsigned integer value
You create rules using the Primary Key Mapping, Data Field Mapping, and the
Response Field Mapping tabs on the AR Mapping Information window.
40
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
AIE service provides the entries listed in the Mapped Fields table to the adapter as
shown in Figure 4-3 on page 41.
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 AIE 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.
Chapter 4
41
The rules listed on the Response Field Mapping tab of the AR Mapping
Information window, shown in Figure 4-5, 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 AIE service provides the entries listed in the
Mapped Attributes table to the adapter.
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.
42
Data objects
Figure 4-6 on page 43 shows a CQuery object provided by the AIE service to the
adapter.
Figure 4-6: AR Mapping Information windowQuery tab
The AIE service gives

the CQuery object
SALARY>200 to the
adapter.
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
Chapter 4
43
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.
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:
GENDER.
44
Pointer objects
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
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.
Chapter 4
45
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.
Table 4-2 describes the four adapter objects that define the classes and functions in
the ADK. Of these, you must implement the dllmain, CBaseAdapter, and CRule
adapter objects. The CQuery adapter object is optional.
Table 4-2: Adapter objects
Object
Description
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
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 Methods required by the adapter on page 49.
dllmain object
The main adapter entry-point function, dllmain, has the entry points that are
called by the AIE 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 AIE 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 a method in this object, which allows
the AIE service to understand the type of data that the object is describing. By
implementing this method, the AIE service is able to determine the type of data
that the adapter wants for the field that the rule describes. The AIE service can then
provide any needed data conversion.
46
Adapter objects
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.
Chapter 4
47
48
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 Class library
reference on page 75. The methods are listed under the CBaseAdapter object.
NOTE
the Data Field Mapping, the Response Field Mapping, and the Query tabs (and all
their fields) behave identically on both windows.

Preparing the adapter template development environment (page 50)

Implementing initialization methods (page 53)
Implementing database connection methods (page 55)
Implementing rule validation methods (page 56)
Implementing key list creation methods (page 58)
Implementing the data retrieval method (page 60)
Implementing the data creation method (page 61)
Implementing the data update method (page 62)
Implementing data deletion methods (page 63)
Implementing transaction processing methods (page 64)
Implementing command support methods (page 66)
Chapter 5 Methods required by the adapter
49
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.
Table 5-1: Adapter objects
50
Object
Description
dllmain
The dllmain object has entry points that are called by the AIE
service to load and initialize an adapter object.
CBaseAdapter
The CBaseAdapter object is the adapter object that provides the

implementation of the methods needed for the AIE service to
communicate with an adapter to complete a data transfer. These
methods are illustrated in Figure 5-1 on page 51.
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 AIE service can Deep Clone the
Rule Objects without any memory issues for each thread in the
multithreading mode.
CQuery
If you implement your own query class extended from the CQuery
class, you must implement the DeepClone() method for this
class. By implementing this method, the AIE service can
DeepClone the query objects without any memory issues for any
thread.
Preparing the adapter template development environment
Figure 5-1: Sample interaction between BMC Atrium Core and an adapter
BMC Atrium Integration Engine
Adapter
Find a data exchange to be processed and verify that the adapter is registered.
Load the Adapter

Initialize the adapter
InitializeAdapterDLL
Initialization Phase
Create a CBaseAdapter object
CreateInstance
Initialize the CBaseAdapter object
Initialize
CBaseAdapter
For each configured rule:
Get rule object
CreateNewRule
Open database connection
OpenConnection
Get rule attributes
GetRuleAttributes
Close database connection
CloseConnection
Processing Phase
Open database connection
OpenConnection
Create key list
GetKeyList
For each key in the list:

Start transaction
StartTransaction
Get data values
GetRuleValues
Stop transaction
StopTransaction
Close database connection
CloseConnection
Terminate
Processing Phase
Clean up CBaseAdapter
Terminate
Remove CBaseAdapter object
DeleteInstance
Clean up the adapter
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:
BMCAtriumIntegrationEngineInstallationDir\devkit\example\templat
e
On UNIX:
BMCAtriumIntegrationEngineInstallationDir/adk/example/template
51
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 CNewAdapter class name.
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.
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.

12 Close the dllmain.cpp file.
52
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 BMC Atrium Integration
Engine in log file and debug messages to identify your adapter.
To set the character string used to identify your adapter

1 Choose a name to identify your adapter.
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.
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 in the following
circumstances:
When an adapter is loaded

When a data exchange is modified
When an adapter is terminating or you have modified a data exchange, the adapter
is called to clean up any resources used during the data transfer.
53
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.
During the initialization phase, the 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-2.
Table 5-2: Return values for connection methods
Return values for connection methods
Description
ADK_OK (0)
Returned if the method completes successfully.
ADK_WARNING (1)
Returned if the method completes successfully,

but a warning is written to the debug file.
ADK_ERROR (2)
Returned if an error is detected.
2 Implement the Terminate method in your adapter object.
This method is called when a data exchange has changed or when the AIE 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-2 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 that they are recorded in the debug file by
implementing the SetStatusMessage method. For more information, see
Logging and debugging on page 71.
54
Implementing database connection methods
Implementing database connection methods

If your external data store is IBM DB2, SQL Server, or Oracle, the AIE 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 AIE service calls OpenConnection at the start of a data transfer and
CloseConnection when the data transfer finishes.
The return value from the OpenConnection method is an integer value that
indicates the success or failure of the functionality. Table 5-2 describes these return
values.
2 Implement the CloseConnection method in your adapter object.
In the CloseConnection method, your adapter must disconnect from your data
source. The AIE 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-2 on page 54 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 that they are recorded in the
debug file by implementing the SetStatusMessage method. For more
information, see Logging and debugging on page 71.
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 that
the debug instructions identify any errors in the external data store configuration
and initialization of the adapter.
55
Implementing rule validation methods

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 AIE service calls this method to get a
new object for each rule describing a data value. The AIE 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.
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 an error is detected for any rule during validation, you should mark
the CRule object as invalid. This is important as it allows the AIE service to
complete the rule validation process. Any methods owned by BMC Atrium
Integration Engine that have embedded adapter rules need to know if the rule
object is valid. Recording errors also allows the AIE 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-2 on page 54 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. For
more information, see Logging and debugging on page 71.
56
Implementing rule validation methods
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 rule validations
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.
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 AIE 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.
2 Set the data type of the adapter data object described by the CRule object to the
BMC Atrium Integration Engine data type code that most closely matches it.
NOTE
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 AIE 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. AIE 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

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.
5 Open the newadpr.cpp file.
This is the source code file where all methods in the adapter class are implemented.
57
6 Change all occurrences of CNewRule to the name you have chosen for your adapter
class.
8 Close the newadpr.cpp file.
Implementing key list creation methods

The AIE service manages a data transfer by obtaining a list of key values from both
BMC Remedy 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 queryWhen 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 queryWhen you create a list of key values with a
query, it returns a list of key values that meet a user-defined constraint.
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 BMC Atrium
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);
}
listOfKeys.push_back(pValueList);
58
Implementing key list creation methods
The return from the GetKeyList method is an integer value that indicates the
success or failure of the functionality. See Table 5-2 on page 54 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 that it is recorded in the debug file by implementing the
SetStatusMessage method. For more information, see Logging and debugging
on page 71.
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 AIE 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 AIE 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 AIE service calls this
method to get a new object for each query used to limit the data used in a data
transfer. The AIE 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 AIE 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.
The return from the ValidateQualifier method is an integer value that indicates
59
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.
2 Implement the GetKeyList method in your adapter object.
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 BMC Atrium
Integration Engine for processing.
The return from the GetKeyList method is an integer value that indicates the
the return values.
NOTE
If any warnings or errors occur when the CreateQueryString and GetKeyList
methods are called during a data transfer, make sure that they are recorded in the
debug file by implementing the SetStatusMessage method. For more
information, see Logging and debugging on page 71.
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.
Implementing the data retrieval method

Data retrieval methods obtain data values that are defined for exchange with BMC
Remedy 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.
60
Implementing the data creation method
To get records
1 Implement the GetRuleValues method in your adapter object.
GetRuleValues 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.
The following 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
the return values.
NOTE
If any warnings or errors occur when the GetRuleValues method is called during
a data transfer, make sure that it is recorded in the debug file by implementing the
on page 71.
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 AIE service determines that a record should be created in the
adapter data source, this method is called.
representing a single data mapping in the data exchange being processed. The
the best access to the adapter database.
61
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.

The rule syntax with the associated data values for:

The Mapped Fields table on the Primary Key Mapping tab of the AR Mapping
Information window
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
NOTE
If any warnings or errors occur when the CreateRuleValues method is called
during a data transfer, make sure that it is recorded in the debug file by
During this phase, you can test the logic for creating data values. You should be
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 BMC Remedy AR System and BMC Atrium CMDB. When the
AIE service determines that a record should be updated in the adapter data source,
this method is called.
representing a single data mapping in the data exchange that is processed. The
62
Implementing data deletion methods
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.

Primary Key Mapping tab of the AR Mapping Information window with its
The rule syntax with 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
NOTE
If any warnings or errors occur when the UpdateRuleValues method is called
During this phase, you can test the logic for updating data values. You should be
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 AIE 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.
63
representing a single data mapping in the data exchange that is processed. The
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.

Primary Key Mapping tab of the AR Mapping Information window and its
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
NOTE
If any warnings or errors occur when the DeleteRuleValues method is called
During this phase, you can test the logic for deleting data values. You should be
errors in deleting the data values.
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 before any changes. Support for this feature is optional but recommended.
64
Implementing transaction processing methods
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 the
Implementing command support methods on page 66.
2 Implement the StartTransaction method in your adapter object.
StartTransaction is called at the start of each transaction. When this method is
called, the AIE service starts processing a new key.

The return from the StartTransaction method is an integer value that indicates
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, any changes that are
made 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
NOTE
If any warnings or errors occur when the SupportTransaction,
StartTransaction, and StopTransaction methods are called during a data
transfer, make sure that they are recorded in the debug file by implementing the
on page 71.
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.
65
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.
If your adapter supports the concept of commands, you must implement the
DoCommand 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
the return values.
NOTE
If any warnings or errors occur when the DoCommand method is called during a
data transfer, make sure that it is recorded in the debug file by implementing the
on page 71.
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.
66
Chapter
After you create an adapter, you must license it so you can use it with BMC Atrium
Integration Engine.

Registering an adapter (page 68)

Licensing an adapter (page 68)
Building an installer for the developed adapter (page 69)
Removing adapters (page 69)
Sample data exchanges and data mappings (page 69)
Documenting the adapter (page 70)
Chapter 6
67
Registering an adapter
You do not need to register your adapters in BMC Atrium Integration Engine,
because no registry is maintained.
An adapter should have a name that uniquely identifies the adapter to BMC
Atrium Integration Engine. Adapter names can be any character string that is 64
characters or fewer in length and not already assigned to another adapter. You
must also add the adapter in the AIE:DataSourceApplicationInfo form.
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.
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.
68
Building an installer for the developed adapter
Building an installer for the developed adapter

When building an adapter, you should write an installer that populates the
AIE:VendorConfiguration and AIE: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.
For more information about importing data into the AIE:VendorConfiguration
form, see Configuring adapter initialization parameters on page 33. For more
information about importing data into the AIE:VendorFieldNames form, see
Creating an adapter rule syntax list on page 34.
In the Windows and UNIX environments, you must write your own installer.
Removing adapters
You can remove an adapter completely from the BMC Atrium Integration Engine
environment using one of the following methods:
Manually remove the entries made to the Windows registry or to the UNIX
service/bin directory.
Write a script to remove the entries made to the Windows registry or to the
UNIX service/bin directory.
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 AIE service,
the Windows registry entries are not removed. This protects any entries you make
that are not related to the AIE 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.
Chapter 6
69
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.6.04 User's 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
Rule syntax, which must not use any BMC Atrium 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
AIE:VendorFieldNames and AIE:VendorConfiguration forms, or
instructions on how to update these forms manually
Any log or debug message

For every log or debug message about errors, explain what needs to be fixed.
Troubleshooting tips
Limitations or restrictions for using the adapter
You should provide the organization or individual supporting your adapter with
the following test 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
70
Chapter
Logging and debugging
The BMC Atrium Integration Engine provides logging and debugging facilities in
the ADK to log and debug event tracing for adapters.

Log and debug tracing (page 72)

Recording log messages (page 72)
Using the CBaseAdapter object to record log events (page 73)
Recording debug events (page 73)
Chapter 7 Logging and debugging
71
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 aie.cfg file. For more
information, see the BMC Atrium Integration Engine 7.6.04 User's Guide.
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 BMC Atrium Integration Engine log file and the AIE: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
BMC Atrium Integration Engine provides language translation for messages that
the AIE 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 may be as follows:
The AIE 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.
72
Using the CBaseAdapter object to record log events
Using the CBaseAdapter object to record log

events
Use the CBaseAdapter object method SetLogMessage to set log messages for the
AIE service. For more information about this method, see
CBaseAdapter::SetLogMessage on page 93.
This method records the string passed as a parameter to the log file and the
AIE:Log form.
Recording debug events

Debug messages help administrators detect errors in a data transfer. The BMC
Atrium 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 AIE 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 AIE 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. Table 7-1 describes the errors types:
Table 7-1: Errors types
Type
Description
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.
Chapter 7 Logging and debugging
73
Using the CBaseAdapter object to record debug events

Use the CBaseAdapter object method SetStatusMessage to set debug messages
for the AIE service. For more information about this method, see
CBaseAdapter::SetStatusMessage on page 94.
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.
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 AIE 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.
IMPORTANT
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
GetRuleAttributes 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.
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 AIE 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.
74
Appendix
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
Data Field Mapping, Response Field Mapping, and Query tabs (and all their fields)
behave identically on both windows.

CBaseAdapter object (page 76)

CEIEDataExchangeDef object (page 101)
CRule object (page 105)
CQuery object (page 112)
CValue object (page 117)
CValueList object (page 125)
CRowsOfValueList object (page 126)
CListOfRule object (page 126)
CListOfRuleWithValue object (page 127)
CRuleWithValue object (page 127)
CQueryWithListOfRuleValue object (page 131)
CQueryWithRowsOfValue object (page 134)
Appendix A Class library reference
75
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
Return values
None
See also:
CBaseAdapter::CBaseAdapter (constructor)
76
CBaseAdapter object
CBaseAdapter::CloseConnection
Disconnects from the adapter source. Any resources needed only for an open
database connection can be released. The AIE 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. For more information about what type of events should be recorded, see
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 when warnings are issued but the
method completes successfully.
Return ADK_ERROR when the method is unable to complete
successfully.
If there is a warning or error, log and debug messages should
help users diagnose the error. For more information about log
and debug event tracing and error handling, see Logging and
debugging on page 71.
See also:
CBaseAdapter::OpenConnection
CBaseAdapter::SetStatusMessage
77
CBaseAdapter::CreateNewQuery
Returns a new CQuery object that was created using the input parameters supplied
to this method.
Required

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
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 AIE 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 AIE service during a data transfer. The AIE service deletes the object when it is
no longer needed.
78
Required

Prototype
virtual CRule*CreateNewRule(
const char*pContainer,
const char*pRuleString)
CBaseAdapter object
Input arguments
pContainer
The name of the container where this rule resides. For BMC
Remedy AR System, a container is the BMC Remedy 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
AIE service to hold the definition of a rule typed on the AR
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, BMC Atrium Integration Engine must generate a query to support the
data exchange configuration. This method is called by BMC Atrium Integration
Engine so that 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.
79
See also:
CQuery
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.
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.
80
Required

Protoype
virtual int CreateRuleValues(

int
num,
CListOfRuleWithValue valueUsedForCreate[],
CListOfRuleWithValue responseValue[])
CBaseAdapter object
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
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 (BMC
Remedy AR System form or BMC Atrium CMDB class). The
information entered for each data mapping is maintained in its
own array element.
Return values
int
success or failure:

Return ADK_WARNING when warnings are issued, but the
successfully.
If there is a warning or error, record log and debug messages
81
See also:
CBAseAdapter::GetRuleAttributes
CBaseAdapter::SupportTransaction
CBAseAdapter::StartTransaction
CBaseAdapter::StopTransaction
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 BMC Remedy
AR System.
You can configure a data exchange 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 BMC Remedy 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
SetStatusMessage 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.
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.
82
Required

implementation by the base class.
Prototype
virtual int CBaseAdapter::DeleteRuleValues(

int
numItems,
key[],
CQueryWithListOfRuleValue
deleteQualifier[])=0
CBaseAdapter object
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
Return values
int
success or failure:

method is completed successfully.
successfully.
See also:
CBaseAdapter::ValidateQualifier
CQueryWithListOfRule
CRule
CValue
83
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
success or failure:

Return ADK_WARNING when warnings were issued, but the
method is completed successfully.
successfully.
If there is a warning or error, log and debug messages help users
diagnose the error. For more information about log and debug
event tracing and error handling, see Logging and debugging
on page 71.
84
CBaseAdapter object
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 AIE service
initializes 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.
NOTE
You can create a data exchange with multiple data mappings. If multiple
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, pass 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)
85
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 AIE service initializes this object to an empty
list before calling this method. The adapter adds each key
value obtained in this list. This parameter is a simple C++
list of CValueList objects. A CValueList object is a
simple list of CValue objects.
Return values
int
The response from this method is an integer value that
shows success or failure:

Return ADK_ERROR when the method is unable to
complete successfully.
to help the user diagnose the error. For more information
about log and debug event tracing, and error handling, see
See also:
CBAseAdapter::CreateQueryString
CRowsOfValueList
CValue
CValueList
86
CBaseAdapter object
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
Used to encrypt the password.
licstring
Encrypted license string.
Return values
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 AIE 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.
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 BMC Atrium Integration Engine data type code that most
closely matches your own data type. 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 BMC Atrium 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 AIE 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.
87
If an error or warning is detected for any rule, it is important to mark the CRule
object as invalid and allow the AIE 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 AIE service to create a detailed
debug log that shows any rules in error.
NOTE
GetRuleAttributes is called while a connection to the database is active. There is
no need to establish another database connection to get the rule information.

Required
Adapter must implement this method. No default implementation

by base class.
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_WARNING when warnings are issued, but the method
completes successfully.
successfully.
If there is a warning or error, record log and debug messages to help
the user diagnose the error. For more information about log, debug
event tracing, and error handling, see Logging and debugging on
page 71.
See also:
CBaseAdapter::Terminate
CListOfRule
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.
88
CBaseAdapter object
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
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[])
89
Input arguments
key[]
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.
retrievedValue[]
Each element in this array represents the data definition and
an associated data value for a specific data mapping defined in
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
BMC Remedy AR System form. The information entered for
each data mapping is maintained in its own array element.
Return values
int
success or failure:

successfully.
If there is 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 Logging and
See also:
CValue
CRule
CRuleWithValue
90
CBaseAdapter object
CBaseAdapter::GetStatusMessage
Returns all current messages created by SetStatusMessage. The AIE service calls
this method to get the character string when any CBaseAdapter methods indicate
that an error has occurred. The contents of the status message are placed in the
AIE:Log file if it is critical, and only in the debug file if it is not critical. Whether a
message is critical is decided by the critical parameter set in
SetStatusMessage.
Required
Prototype
const char* GetStatusMessage()
Input arguments
None
Return values
const char*
Returns all current messages created by SetStatusMessage.
See also:
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. BMC Atrium 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 AIE 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 BMC Atrium 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. For details about
what type of events should be recorded, see Logging and debugging on page 71.
91
Implement this method by calling CBaseAdapter::Initialize to set internal

pointers to the data exchange created by the AIE service.
Required

Protoype
virtual int initialize(

CEIEDataExchangeDef* pExDef)
Input arguments
pExDef
A pointer to the data exchange created by the AIE 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 AIE service keeps this object until the data
exchange changes. At that time, this method is called with a new
CEIEDataExchangeDef object.
Return values
int
success or failure:

successfully.
about log and debug event tracing, see Logging and
See also:
CBaseAdapter::OpenConnection
Establishes a connection to the external data store. The AIE 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. For details about what type of events should be
recorded, see Logging and debugging on page 71.
92
CBaseAdapter object
Implement this method by first calling CBaseAdapter::Initialize to set

internal pointers to the data exchange created by the AIE service.
Required

by base class.
Prototype
virtual int OpenConnection()
Input arguments
None
Return values
int
success or failure:

successfully.
the user diagnose the error. For more detailed information about log
and debug event tracing, see Logging and debugging on page 71.
See also:
CBaseAdapter::CloseConnection
CBaseAdapter::SetLogMessage
Adds the text of this message to the AIE service log.
All log messages generated by BMC Atrium Integration Engine are translated to
the user language. The AIE service does not translate status messages obtained
from the adapter. The adapter developer must provide messages in the
appropriate language.
Required
Prototype
void SetLogMessage
const char*logMsg)
Input arguments
logMsg
A character string to be added to the AIE service log.
Return values
None
See also:
93
This method supports two implementations. The first implementation, void
SetStatusMessage(const char* Msg, int nTraceLevel), 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 are enabled or
disabled depending on the current configured level for logging.
Required
Prototype
void SetStatusMessage(const char* Msg, int

nTraceLevel) or
void SetStatusMessage(const char* errMsg)
Note: See the eiedebug.h file for the available values of the
nTraceLevel field.
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 appears 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::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.
94
CBaseAdapter object
When this method is called, the AIE 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
Return values
bool
true=transaction successfully starts; false=transaction does
not start.
See also:
CBaseAdapter::UpdateRuleValues
CBaseAdapter::CreateRuleValues
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 AIE 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

by base class.
Prototype
virtual bool StopTransaction(

bool commitChanges)
95
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.
Return values
None
See also:
This method is 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

by base class.
Prototype
virtual bool SupportTransaction()
Input arguments
None
Return values
bool
true=transaction successfully starts; false=transaction does not
start.
See also:
This method is 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.
96
CBaseAdapter object
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. For details about what type of events should be
recorded, see Logging and debugging on page 71.
Required

by base class.
Prototype
virtual int terminate()
Input arguments
None
Return values
int
success or failure:

successfully.
See also:
CBaseAdapter::Initialize
CBaseAdapter::CreateQualifier
CBaseAdapter::UpdateRuleValues
This method 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.
97
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 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
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.
98
Required

by base class.
Prototype
virtual int UpdateRuleValues(

int
num,
CListOfRuleWithValue key[],
CListOfRuleWithValue valueToUpdate[],
CListOfRuleWithValue responseValue[],
CQueryWithListOfRuleValue updateQualifier[])
CBaseAdapter object
Input arguments
key[]
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.
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 BMC
Remedy 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
Return values
int
or failure:

successfully.
about log and debug event tracing, see Logging and debugging
on page 71.
99
See also:
CValue
CRule
CRuleWithValue
This method 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
records a text message with SetStatusMessage indicating the error, and return
ADK_ERROR to show that an error has been detected. It is important to return the
error indicator to let the AIE service know the qualifier is not valid. Query syntax
errors prevent a data transfer from taking place.
When the AIE 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

by base class.
Note: ValidateQualifier is not called while a connection to the
database is active. If validation requires an open connection, you

must establish the connection.
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.
Return values
int
or failure:

successfully.
100
See also:
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.
CEIEDataExchangeDef::GetFirstVenConfigParam
This method returns an external data store configuration parameter name-value
pair. BMC Atrium 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)
Appendix A
101
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.
See also:
CEIEDataExchangeDef::GetVenConfigParam
CEIEDataExchangeDef::GetVenConfigParamAt
CEIEDataExchangeDef::GetVenConfigParamLength
This method returns an external data store configuration parameter name-value
pair. BMC Atrium 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.
102
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.
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:
This method 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.
Appendix A
103
See also:
CEIEDataExchangeDef::IsDirectionARDataIntoVendor
This method 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
BMC Remedy 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 BMC Remedy 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
BMC Remedy AR System to the external data store.
See also:
CEIEDataExchangeDef::IsDirectionVendorDataIntoAR
CEIEDataExchangeDef::IsDirectionVendorDataIntoAR
This method 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 BMC Remedy AR System. A false response means
that the data exchange is configured to transfer data from BMC Remedy
AR System into the external data store.
Required
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 BMC Remedy AR System.
See also:
CEIEDataExchangeDef::IsDirectionARDataIntoVendor
104
CRule object
CRule object
This section describes the methods for the CRule object.
CRule::CRule (copy constructor)

This method 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
See also:
CRule::~CRule (destructor)
This method 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)

This rule initializes a rule definition object and initializes the container to which it
belongs. For BMC Remedy AR System, a container is the BMC Remedy 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)
Appendix A
105
Input arguments
pContainer
The name of the container where this rule resides. For BMC
Remedy AR System, a container is the BMC Remedy 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
Return values
None
See also:
CRule::DeepClone
This method returns the new object that was initialized using the current pointer.
Required

by base class.
Prototype
CRule *CRule::DeepClone()
Input arguments
None
Return values
Returns the pointer to the new allocated object as a pointer to the

CRule object.
See also:
CRule
CRule::GetContainer
This method returns the name of the container to which this rule belongs. For BMC
Remedy AR System, a container is the BMC Remedy AR System form name. For
an adapter, this is the container specified in the Table Name field on the Main tab
Required
Prototype
char* CRule::GetContainer()
Input arguments
None
Return values
char*
The name of the container where this rule resides. For BMC Remedy
AR System, a container is the BMC Remedy AR System form name.
For an adapter this is the container specified in the Table Name field
106
CRule object
See also:
CRule::SetContainer
CRule::GetEIEDataType
This method returns the data type defined by BMC Atrium Integration Engine 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 data
type defined by BMC Atrium Integration Engine. 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 BMC Atrium Integration Engine to handle all necessary
data conversions and set the data values to the appropriate type.
Required

by base class.
Prototype
virtual DATATYPE GetEIEDataType ()
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 a BMC Atrium Integration Engine-defined value that is
set to one of the settings described in Table 4-1 on page 40.
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
Appendix A
107
CRule::GetRuleString
This method returns the text of the rule as it was entered by the user on the AR
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
This method 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.
This code is set by the adapter during rule validation in the
CBaseAdapter::GetRuleAttributes method.
Required
Prototype
int CRule::GetVenDataType()
Input arguments
None
Return values
int
The adapter-defined data type code.
See also:
CRule::SetVenDataType
CRule::IsValid
This method returns a Boolean value that shows if the rule has passed validation
and is ready for use.
108
Required
Prototype
bool CRule::IsValid()
CRule object
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
CRule::SetContainer
Sets the name of the container to which this rule belongs. For BMC Remedy
AR System, a container is the BMC Remedy AR System form name. For an
adapter, this is the container specified in the Table Name field on the Main tab of
Required
Prototype
CRule::SetContainer(
const char*container)
Input arguments
container
The name of the container where this rule resides. For BMC Remedy
AR System, a container is the BMC Remedy AR System form name.
For an adapter this is the container specified in the Table Name field
Return values
None
See also:
CRule::GetContainer
CRule::SetErrMsg
This method 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 AIE 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
Prototype
void CRule::SetErrMsg(
const char*msg)
Appendix A
109
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
CRule::SetRuleString
This method sets the text of the rule as it was entered by the user on the AR
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
See also:
CRule::GetRuleString
CRule::SetValidity
This method 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.
110
Required
Prototype
void CRule::SetValidity(
boolv)
CRule object
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
CRule::SetVenDataType
This method sets adapter-defined data type code. Optionally, you can also set 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.
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 AIE
service truncates data values to this length. If not defined, no limit check or data
truncation occurs.
Required
Prototype
void CRule::SetVenDataType(
intvdtype,
intlength=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 AIE 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
Appendix A
111
CQuery object
This section describes the methods for the CQuery object.
CQuery::CQuery (copy constructor)

This method 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.
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)
This method 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)
112
CQuery object
CQuery::CQuery (new object constructor)

The method 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
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
This method 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
Required
Prototype
char*
Input arguments
None
Return values
char*
CQuery::GetContainer ()
The name of the container used in the data mapping to which this
query belongs. For BMC Remedy AR System, a container is the BMC
Remedy 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
Appendix A
113
CQuery::GetErrMsg
This method returns an error message indicating the reason a query failed
validation.
Required
Prototype
const char*
Input arguments
None
Return values
const char*
CQuery::GetErrMsg ()
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
CQuery::GetQueryString
This method returns the text of the query as it was entered by the user on the Query
Required
Prototype
char*
Input arguments
None
Return values
char*
CQuery::GetQueryString ()
The query string as it was entered by the user on the Query tab of the
See also:
CQuery::SetQueryString
CQuery::IsValid
This method 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.
114
Required
Prototype
bool
CQuery::IsValid ()
CQuery object
Input arguments
None
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
This method 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
Required
Prototype
void
Input arguments
container
CQuery::SetContainer (
const char*
container)
The name of the container used in the data mapping to which this
query belongs. For BMC Remedy AR System, a container is the BMC
Remedy 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
CQuery::SetErrMsg
This method sets an error message indicating the reason a query failed validation.
If a query syntax fails, the adapter should call SetErrMsg.
Required
Prototype
void
Input arguments
errorMessage
CQuery::SetErrMsg(
const char*
errorMessage)
An error message indicating the reason a query failed validation.

Return values
None
Appendix A
115
See also:
CQuery::SetValidity
CQuery::IsValid
CQuery::GetErrMsg
CQuery::SetQueryString
This method returns the text of the query as it was entered by the user on the Query
Required
Prototype
void
Input arguments
queryString
CQuery::SetQueryString(
const char*
queryString)
The query string as it was entered by the user on the Query tab of the
Return values
None
See also:
CQuery::GetQueryString
CQuery::SetValidity
This method sets a Boolean value that shows if the query has passed validation and
is ready for use.
Required
Prototype
void
Input arguments
bool
CQuery::SetValidity(
bool
m_valid)
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
116
CValue object
CValue object
This section describes the methods for the CValue object.
CValue::CValue (copy constructor)

This method 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)
This method frees all resources allocated for the CValue object.
Required
Prototype
CValue::~CValue()
Input arguments
None
Return values
None
See also:
CValue::CValue (constructors)
CValue::CValue (empty constructor)

This method initializes a data value to a null data value.
Required
Prototype
CValue::CValue()
Input arguments
None
Return values
None
Appendix A
117
See also:
CValue::~CValue (destructor)
CValue::GetDecimal
This method 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 sprintf c function is applied to the data
value in this object if it is not defined as a decimal.
NOTE
Do not ask for time values as a decimal value.
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::GetInt
This method 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
Return values
long
The integer value assigned to this object.
118
CValue object
See also:
CValue::GetInt
CValue::GetString
CValue::GetReal
This method returns the value associated with this object as a double value.
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::GetString
This method 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
Appendix A
119
CValue::GetTime
This method 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()
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::GetType
This method 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 a value defined by BMC Atrium Integration Engine
that is set to one of the settings described in Table 4-1 on page 40.
See also:
CValue::SetType
120
CValue object
CValue::GetULong
This method returns the value associated with this object as an unsigned long
value.
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::GetInt
CValue::GetString
CValue::IsNull
This method returns a Boolean value that shows if the value contained in this
object is null.
Required
Prototype
bool CValue::IsNull()
Input arguments
None
Return values
bool
Returns true if this object contains no data value.
See also:
CValue::SetNull
CValue::CValue (empty constructor)
Appendix A
121
CValue::SetDecimal
This method 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::SetInt
This method 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 contains a data value, that value is released.
Required
Prototype
void CValue::SetInt(
inti)
Input arguments
i
The integer value to be placed in this object.
Return values
None
See also:
CValue::GetInt
CValue::GetString
122
CValue object
CValue::SetNull
This method sets the value associated with this object to a null value. The data type
is set to EIE_NULL.
Required
Prototype
void CValue::SetNull()
Input arguments
i
The integer value to be placed in this object.
Return values
None
See also:
CValue::IsNull
CValue::GetString
CValue::SetReal
This method sets the value associated with this object to the double value passed
as a parameter. The data type is set to EIE_REAL.
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
Appendix A
123
CValue::SetString
This method sets the value associated with this object to the string value passed as
a parameter. The data type is set to EIE_CHAR.
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::SetTime
This method sets the value associated with this object to the time value passed as
a parameter. The data type is set to EIE_TIME.
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
124
CValueList object
CValue::SetULong
This method sets the value associated with this object to the unsigned long value
passed as a parameter. The data type is set to EIE_ULONG.
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
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
v
The unsigned long value to be placed in this object.
Return values
None
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
125
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
Example

CRowsOfValueList *pList
for (RowsOfValueIter iter=pList->begin();
iter!=pList->end(); iter++)
{
CValueList* pValueList = *iter;
// ........
}
See also:
CValue
CValueList
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
Example

CListOfRule *pList
for (RuleIter iter=pList->begin(); iter!=pList>end(); iter++)
{
CRule* pRule = *iter;
}
126
See also:
CValue
CValueList
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
Example
CListOfRuleWithValue *pList
for (RuleWithValueIter iter=pList->begin();
iter!=pList->end(); iter++)
{
CRuleWithValue* pRuleWithValue = *iter;
// ........
}
See also:
CValue
CValueList
This section describes the methods for the CRuleWithValue object.
CRuleWithValue::CRuleWithValue (constructor)
This method 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.
Appendix A
127
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)
CRuleWithValue::CRuleWithValue (copy constructor)

This method initializes this object with the contents of the CRuleWithValue object
supplied as an input parameter.
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:
This method 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.
128
Required
Prototype
CRuleWithValue::~CRuleWithValue()
Input arguments
None
Return values
None
See also:
CRuleWithValue::CRuleWithValue (constructor)
CRuleWithValue::CRuleWithValue (copy constructor)
CRuleWithValue::GetRule
This method returns the CRule object that defines the field with a data value that
is also contained by this object.
Required
Prototype
CRule*CRuleWithValue::GetRule()
Input arguments
None
Return values
None
See also:
CRuleWithValue::SetRule
CRuleWithValue::GetValue
This method returns the CValue object that holds the data value contained in this
object.
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:
Appendix A
129
CRuleWithValue::SetRule
This method sets the CRule object that holds the definition of the data value to be
contained in this object.
value in the adapter database, and CValue, the value itself. In this method, only the
passed pointer is saved. No copy is created.

Required
Prototype
void CRuleWithValue::SetRule(
CRule*pRule)
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::SetValue
This method sets the CValue object that holds the data value contained by this
object.
value in the adapter database, and CValue, the value itself. This method saves the
passed pointer. No copy is created.

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
130
This section describes the methods for the CQueryWithListOfRuleValue object.
(copy constructor)
This method 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)
This method frees all resources for the CQueryWithListOfRuleValue object.
Required
Prototype
CQueryWithListOfRuleValue::~
CQueryWithListOfRuleValue()
Input arguments
None
Return values
None
See also:
CQueryWithListOfRuleValue::~CQueryWithListOfRuleValue
(new object constructor)
CQueryWithListOfRuleValue::~CQueryWithListOfRuleValue
(copy constructor)
Appendix A
131
This method is 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.
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
This method 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
132
This method 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
This method sets the CQuery object that was created using one of the queries
Required
Prototype
void CQueryWithListOfRuleValue::SetQuery(
CQuery*
pQuery)
Input arguments
pQuery
Return values
None
See also:
CQueryWithListOfRuleValue::SetRuleWithValueList
This method sets the CListOfRuleWithValue object that holds data values to be
substituted in the query.
Required
Prototype
void CQueryWico
thListOfRuleValue::
SetRuleWithValueList(
CListOfRuleWithValue*
Appendix A
pRuleValueList)
133
Input arguments
pRuleValueList
The list of CRuleWithValue objects that holds the data values to
be substituted in the query.
Return values
None
See also:
This section describes the methods for the CQueryWithRowsOfValue object.
(copy constructor)
This method 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)
CQueryWithRowsOfValue::~CQueryWithRowsOfValue
(destructor)
This method frees all resources for the CQueryWithRowsOfValue object.
134
Required
Prototype
CQueryWithRowsOfValue::~CQueryWithRowsOfValue()
Input arguments
None
Return values
None
See also:
(copy object constructor)
This method is a container that holds a query object and a CRowsOfValue object to
be used when creating the query object.
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
See also:
CQueryWithRowsOfValue::~CQueryWithRowsOfValue (destructor)
CQueryWithRowsOfValue::GetQuery
Required
Prototype
CQuery* CQueryWithRowsOfValue::GetQuery()
Input arguments
None
Return values
CQuery*
Appendix A
135
See also:
CQueryWithRowsOfValue::GetRowsOfValueList
CQueryWithRowsOfValue::SetQuery
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
This method sets the CQuery object that was created using one of the queries
Required
Prototype
void CQueryWithRowsOfValue::SetQuery(
CQuery*
pQuery)
Input arguments
pQuery
Return values
None
See also:
CQueryWithRowsOfValue::GetQuery
136
CQueryWithRowsOfValue::SetRowsOfValueList
This method sets the CRowsOfValueList object needed to expand the query at
runtime.
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.
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:
Appendix A
137
138
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
76
$KEYLIST$ reserved word 29
A
Adapter Development Kit
code requirements 26
compiler requirements 26
debugging facilities 73
files installed 27
interface 19
logging facilities 72, 73
adapter object class 46
adapter template
default location 51
definition of 20
files installed 29
preparing the development environment 52, 53
adapters
configuring initialization parameters 33
documenting 70
installers, building 69
licensing 68
registering 68
rule syntax list, creating 34
uninstalling 69
ADK_ERROR return value 54
ADK_OK return value 54
ADK_WARNING return value 54
AIE service
language translation for log 72
overview 19
aiexfer utility, definition of 19
B
BMC Atrium Integration Engine
introduction to 16
reserved words 29
BMC Atrium Integration Engine reserved words,

data values 32
BMC Remedy Action Request System (BMC Remedy
AR System), API documentation 19
BMC Software, contacting 2
building adapter installers 69
building adapters
connecting to the data source 77
building adapters, connecting to the data source 77
C
CBaseAdapter (constructor) method 76
CBaseAdapter (destructor) method 76
CBaseAdapter object
description of 46
methods for 76
role in debugging 74
role in logging 73
use in building adapters 50, 52
CEIEDataExchangeDef object, methods for 101
class library
definition of 19
files installed 28, 29
CListOfRule object 44, 126
CListOfRuleWithValue object 45, 127
CloseConnection method
description of 77
use in building adapters 55
CNewAdapter object 52
CNewRule object 57
command support methods required by adapter 66
compiling adapter templates on UNIX 26
constant| reserved word 32
container 32
CQuery (copy constructor) method 112
CQuery (destructor) method 112
CQuery (new object constructor) method 113
CQuery object
Index
139
CQuery object (continued)
description of 42, 47
methods for 112, 116
CQueryWithListOfRuleValue (copy constructor)
method 131
CQueryWithListOfRuleValue (destructor)
method 131
CQueryWithListOfRuleValue (new object
constructor) method 132
methods for 131
CQueryWithRowsOfValue (copy constructor)
method 134
CQueryWithRowsOfValue (destructor) method 134
CQueryWithRowsOfValue (new object constructor)
method 135
description of 45
methods for 134
CreateNewQuery method
description of 78
CreateNewRule method
description of 78
CreateQueryString method
description of 79
CreateRuleValues method
description of 80
creating CBaseAdapter object 52
CRowsOfValueList object 44, 126
CRule (copy constructor) method 105
CRule (destructor) method 105
CRule (new rule constructor) method 105
CRule object
description of 40, 46
methods for 105
CRuleWithValue (constructor) method 127
CRuleWithValue (copy constructor) method 128
CRuleWithValue (destructor) method 128
description of 45
methods for 127
customer support 3
CValue (copy constructor) method 117
CValue (destructor) method 117
CValue (empty constructor) method 117
CValue object, methods for 117, 125
CValueList object 44, 125
140
D
data creation methods required by adapter 61
data deletion methods required by adapter 63
Data Exchange application 18
data exchange, definition 18
Data object class 43
data retrieval methods required by adapter 60
data transfer, direction of 16
data update methods required by adapter 62
data values, Integration Engine reserved words 32
database connection methods required by adapter 55
debugging facilities
CBaseAdapter object, role of 74
CRule object, role of 73, 74
methods used 74
overview 72
setting your adapter name 53
DeepClone method 106
default location of installed files for Adapter
Development Kit 27
defining rule syntax
data values 32
queries 33
DeleteRuleValues method
description of 82
development environment
directory structure 27
files installed 27, 28, 29, 30
preparing 50
direction of data transfer 16
dllmain object
description of 46
DoCommand method
description of 84
documenting adapters 70
E
Event Request interface, definition of 19
F
files installed
adapter template 29
class library 28, 29
default location 27
files installed (continued)
overview 27
sample flat file adapter 30
function| reserved word 32
G
GetContainer method
query 113
rule 106
GetDataExchangeName method 101
GetDecimal method 118
GetEIEDataType method
description of 107
GetErrMsg method
query 114
rule 107
GetFirstVenConfigParam method 101
GetInt method 118
GetKeyList method
description of 85
GetLicenseString method 87
GetProductName method 87
GetQuery method
CQueryWithListOfRuleValue 132
CQueryWithRowsOfValue 135
GetQueryString method 114
GetReal method 119
GetRowsOfValueList method 136
GetRule method 129
GetRuleAttributes method
description of 87
GetRuleString method 108
GetRuleValues method
description of 88
not used for commands 66
GetRuleWithValueList method 133
GetStatusMessage method 91
GetString method 119
GetTime method 120
GetType method 120
GetULong method 121
GetValue method 129
GetVenConfigParamAt method 102
GetVenConfigParamLength method 103
GetVenDataType method 108
H
header files installed 28
I
implementing required methods
command support 66
data creation 61
data deletion 63
data retrieval 60
data update 62
database connection 55
initialization 53
key list creation 58, 59
rule validation 56
transaction processing 64
initialization methods required by adapter 53
initialization phase
overview 20
role in building adapters 54
Initialize method
description of 91
installation control file 20
installed files
adapter template 29
class library 29
default location 27
overview 27
sample flat file adapter 30
installers for adapters, building 69
IsDirectionARDataIntoVendor method 104
IsDirectionVendorDataIntoAR method 104
IsNull method 121
IsValid method
query 114
rule 108
K
key 58
key list creation methods required by adapter
with a query 58, 59
without a query 58
key queries 33
L
language translation for log file 72
library files installed 29
Index
141
library. See class library
licensing adapters 68
location of installed files 27
log messages, recording 72
logging facilities
CBaseAdapter object, role of 73
language translation 72
overview 72
SetLogMessage method 73
M
makefile.unix.samp file 26
methods required to build adapter
command support 66
data creation 61
data deletion 63
data retrieval 60
data update 62
database connection 55
initialization 53
rule validation 56
transaction processing 64
Microsoft Visual C++ 26
O
objects, classes of 43, 46
OpenConnection method
description of 92
P
process| reserved word 32
processing phase 21
product support 3
Q
queries
defining rule syntax for 33
key 58
key query 33
row-level query 33
R
Recording log messages 72
registering adapters
142
overview 68
Windows 68
removing adapters 69
requirements
code 26
compiler 26
row-level queries 33
rule syntax
BMC Atrium Integration Engine reserved
words 32
data values 32
queries 33
reserved words, BMC Atrium Integration
Engine 29
rule validation methods required by adapter 56
S
sample flat file adapter
definition of 20
files installed 30
SetContainer method
query 115
rule 109
SetDecimal method 122
SetErrMsg method
query 115
rule 109
SetInt method 122
SetLogMessage method
description of 93
role in logging 73
SetNull method 123
SetQuery method
CQueryWithListOfRuleValue 133
CQueryWithRowsOfValue 136
SetQueryString method 116
SetReal method 123
SetRowsOfValueList method 137
SetRule method 130
SetRuleString method 110
SetRuleWithValueList method 133
SetStatusMessage method
description of 94
SetString method 124
SetTime method 124
SetULong method 125
SetValidity method
query 116
rule 110
SetValue method 130
SetVenDataType method 111
sql| reserved word 32
StartTransaction method
description of 94
StopTransaction method
description of 95
support, customer 3
SupportTransaction method
description of 96
syntax. See rule syntax
system registry 69
T
targetprocess| reserved word 32
targetsql| reserved word 32
technical support 3
Terminate method
description of 96
transaction processing methods required by
adapter 64
U
uninstalling adapters 69
UNIX
UpdateRuleValues method
description of 97
V
ValidateQualifier method
description of 100
W
Windows
Add/Remove Programs 69
registering adapters 68
Index
143
144
*176791*
*176791*
*176791*
*176791*
*176791*

BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit

Transféré par

Informations du document

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit

Transféré par

Droits d'auteur :

Formats disponibles

BMC Atrium Integration Engine 7.6.

Adapter Development Kit

Contacting BMC Software

United States and Canada

BMC SOFTWARE INC

713 918 8800 or

(01) 713 918 8000

713 918 8000

Outside United States and Canada

(01) 713 918 8800

Restricted Rights Legend

Support by telephone or email

Before Contacting BMC Software

Operating system and environment information

Sequence of events leading to the problem

Commands and options that you used

Product error messages

License key and password information

E-mail customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>,

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

Understanding BMC Atrium Integration Engine

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

Understanding the development environment

Defining the adapter rule syntax

Defining the rule syntax to describe a data value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Class library objects used by the adapter

Data exchange objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Methods required by the adapter

Preparing the adapter template development environment . . . . . . . . . . . . . . . . . . . . . 50

Logging and debugging

Log and debug tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Adapter Development Kit Developers Guide

Recording debug events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Class library reference

Adapter Development Kit Developers Guide

Adapter Development Kit Developers Guide

BMC Atrium Core documentation

Atrium Integrator 7.6.04

Information about defining source and target

Users who are responsible

Description and details of superclasses, subclasses,

Note: This Help is provided in HTML and is available

on the BMC Atrium Core media. It is not available

BMC Atrium Core documentation

Information about Oracle Java classes, methods, and Application programmers.

on the BMC Atrium Core media. It is not available

Help for using and configuring BMC Atrium CMDB,

Users that work with CIs

BMC Atrium Core: Taking

End-to-end high-level steps for bringing data into

Atrium Core media. It is not available on the BMC

Information about the BMC Atrium Core

Compatibility Matrix from the BMC Customer

Adapter Development Kit Developers Guide

BMC Atrium Core 7.6.04

Information about CMDB concepts and high-level

Anyone who wants to learn

BMC Atrium Core 7.6.04

BMC Atrium Core 7.6.04

Information about installing, upgrading, and

BMC Atrium Core 7.6.04

Combined index of all guides.

BMC Atrium Core 7.6.04