Post on 07-Aug-2018
transcript
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
1/146
www.bmc.com
BMC Atrium Integration Engine 7.6.04
Adapter Development KitDeveloper’s Guide
January 2011
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
2/146
If you have comments or suggestions about this documentation, contact Information Development by email at
doc_feedback@bmc.com.
Contacting BMC Software
You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain informationabout the company, its products, corporate offices, special events, and career opportunities.
United States and Canada
Address BMC SOFTWARE INC2101 CITYWEST BLVDHOUSTON TX 77042-2827USA
Telephone 713 918 8800 or800 841 2031
Fax 713 918 8000
Outside United States and Canada
Telephone (01) 713 918 8800 Fax (01) 713 918 8000
© Copyright 1999–2011 BMC Software, Inc.
BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered withthe U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMCtrademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All othertrademarks or registered trademarks are the property of their respective owners.
AIX, DB2, and IBM are trademarks or registered trademarks of International Business Machines Corporation in the UnitedStates, other countries, or both.
Linux is the registered trademark of Linus Torvalds.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of theirrespective owners.
UNIX is a registered trademark of The Open Group in the US and other countries.
BMC Software considers information included in this documentation to be proprietary and confidential. Your use of thisinformation is subject to the terms and conditions of the applicable End User License Agreement for the product and theproprietary and restricted rights notices included in this documentation.
Restricted Rights Legend
U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THECOPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by theU.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS
252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer isBMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to thisaddress.
mailto:doc_feedback@bmc.comhttp://www.bmc.com/mailto:doc_feedback@bmc.comhttp://www.bmc.com/
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
3/146
Customer Support
You can obtain technical support by using the Support page on the BMC Software website or by contacting CustomerSupport by telephone or email. To expedite your inquiry, please see “Before Contacting BMC Software.”
Support Website
You can obtain technical support from BMC Software 24 hours a day, 7 days a week athttp://www.bmc.com/support. From this website, you can:
Read overviews about support services and programs that BMC Software offers. Find the most current information about BMC Software products. Search a database for problems similar to yours and possible solutions. Order or download product documentation. Report a problem or ask a question. Subscribe to receive email notices when new product versions are released. Find worldwide BMC Software support center locations and contact information, including email addresses, fax
numbers, and telephone numbers.
Support by telephone or email
In the United States and Canada, if you need technical support and do not have access to the Web, call 800 537 1813 orsend an email message to customer_support@bmc.com. (In the Subject line, enterSupID:yourSupportContractID , such as SupID:12345.) Outside the United States and Canada, contact yourlocal support center for assistance.
Before Contacting BMC Software
Have the following information available so that Customer Support can begin working on your issue immediately:
Product information
— Product name— Product version (release number)— License number and password (trial or permanent)
Operating system and environment information
— Machine type— Operating system type, version, and service pack— System hardware configuration— Serial numbers— Related software (database, application, and communication) including type, version, and service pack or
maintenance level
Sequence of events leading to the problem
Commands and options that you used
Messages received (and the time and date that you received them)
— Product error messages— Messages from the operating system, such as file system full— Messages from related software
http://www.bmc.com/supportmailto:customer_support@bmc.commailto:customer_support@bmc.comhttp://www.bmc.com/support
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
4/146
License key and password information
If you have a question about your license key or password, contact Customer Support through one of the followingmethods:
E-mail customer_support@bmc.com. (In the Subject line, enter SupID:,such as SupID:12345.)
In the United States and Canada, call 800 537 1813. Outside the United States and Canada, contact your local supportcenter for assistance.
Submit a new issue at http://www.bmc.com/support.
mailto:customer_support@bmc.comhttp://www.bmc.com/supporthttp://www.bmc.com/supportmailto:customer_support@bmc.com
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
5/146
5
Contents
BMC Atrium Core documentation 11
Chapter 1 Understanding BMC Atrium Integration Engine 15
Overview of BMC Atrium Integration Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
BMC Atrium Integration Engine components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Data Exchange application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18AIE service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Event Request interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Adapter Development Kit interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Data transfer process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Initialization phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Processing phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Chapter 2 Understanding the development environment 25
Code requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Compiler requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Compiling an adapter template on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Description of installed files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Class library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Adapter template files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Sample flat file adapter files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Chapter 3 Defining the adapter rule syntax 31
Defining the rule syntax to describe a data value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Defining the rule syntax to support queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Configuring adapter initialization parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Creating an adapter rule syntax list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Chapter 4 Class library objects used by the adapter 37
Data exchange objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38CEIEDataExchangeDef object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40CQuery object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
6/146
6 Adapter Development Kit Developer’s Guide
Data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43List objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
CValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44CRowsOfValueList object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44CListOfRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
CListOfRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Pointer objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
CRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45CQueryWithListOfRuleValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45CQueryWithRowsOfValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Adapter objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46dllmain object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46CQuery object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Chapter 5 Methods required by the adapter 49Preparing the adapter template development environment . . . . . . . . . . . . . . . . . . . . . 50
Creating an adapter-derived CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . 52Setting your adapter name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Implementing initialization methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Implementing database connection methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Implementing rule validation methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Getting and validating a CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Setting the data type of the value described in the CRule object . . . . . . . . . . . . . . 57Renaming the CNewRule object in the adapter template . . . . . . . . . . . . . . . . . . . . 57
Implementing key list creation methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Creating a key list without a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Creating a key list with a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Implementing the data retrieval method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Implementing the data creation method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Implementing the data update method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Implementing data deletion methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Implementing transaction processing methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Implementing command support methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Chapter 6 Packaging an adapter 67
Registering an adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Licensing an adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Building an installer for the developed adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Removing adapters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Sample data exchanges and data mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Documenting the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Chapter 7 Logging and debugging 71
Log and debug tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Recording log messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Using the CBaseAdapter object to record log events . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
7/146
7
Recording debug events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Using the CBaseAdapter object to record debug events . . . . . . . . . . . . . . . . . . . . . 74Using the CRule object to record debug events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Appendix A Class library reference 75
CBaseAdapter object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76CBaseAdapter::CBaseAdapter (constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76CBaseAdapter::~CBaseAdapter (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76CBaseAdapter::CloseConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77CBaseAdapter::CreateNewQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78CBaseAdapter::CreateNewRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78CBaseAdapter::CreateQueryString. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79CBaseAdapter::CreateRuleValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80CBaseAdapter::DeleteRuleValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82CBaseAdapter::DoCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84CBaseAdapter::GetKeyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85CBaseAdapter::GetLicenseString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87CBaseAdapter::GetProductName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87CBaseAdapter::GetRuleAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87CBaseAdapter::GetRuleValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88CBaseAdapter::GetStatusMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91CBaseAdapter::Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91CBaseAdapter::OpenConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92CBaseAdapter::SetLogMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93CBaseAdapter::SetStatusMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94CBaseAdapter::StartTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94CBaseAdapter::StopTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95CBaseAdapter::SupportTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96CBaseAdapter::Terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96CBaseAdapter::UpdateRuleValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97CBaseAdapter::ValidateQualifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
CEIEDataExchangeDef object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101CEIEDataExchangeDef::GetDataExchangeName. . . . . . . . . . . . . . . . . . . . . . . . . . 101CEIEDataExchangeDef::GetFirstVenConfigParam . . . . . . . . . . . . . . . . . . . . . . . . 101CEIEDataExchangeDef::GetVenConfigParamAt . . . . . . . . . . . . . . . . . . . . . . . . . . 102CEIEDataExchangeDef::GetVenConfigParamLength . . . . . . . . . . . . . . . . . . . . . . 103CEIEDataExchangeDef::IsDirectionARDataIntoVendor. . . . . . . . . . . . . . . . . . . . 104CEIEDataExchangeDef::IsDirectionVendorDataIntoAR. . . . . . . . . . . . . . . . . . . . 104
CRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105CRule::CRule (copy constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105CRule::~CRule (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105CRule::CRule (new rule constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105CRule::DeepClone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106CRule::GetContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106CRule::GetEIEDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107CRule::GetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107CRule::GetRuleString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108CRule::GetVenDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108CRule::IsValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
8/146
8 Adapter Development Kit Developer’s Guide
CRule::SetContainer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109CRule::SetErrMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109CRule::SetRuleString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110CRule::SetValidity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110CRule::SetVenDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
CQuery object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112CQuery::CQuery (copy constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112CQuery::~CQuery (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112CQuery::CQuery (new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113CQuery::GetContainer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113CQuery::GetErrMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114CQuery::GetQueryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114CQuery::IsValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114CQuery::SetContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115CQuery::SetErrMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115CQuery::SetQueryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
CQuery::SetValidity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116CValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117CValue::CValue (copy constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117CValue::~CValue (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117CValue::CValue (empty constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117CValue::GetDecimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118CValue::GetInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118CValue::GetReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119CValue::GetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119CValue::GetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120CValue::GetType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
CValue::GetULong. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121CValue::IsNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121CValue::SetDecimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122CValue::SetInt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122CValue::SetNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123CValue::SetReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123CValue::SetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124CValue::SetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124CValue::SetULong . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
CValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125CRowsOfValueList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
CListOfRule object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126CListOfRuleWithValue object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127CRuleWithValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
CRuleWithValue::CRuleWithValue (constructor) . . . . . . . . . . . . . . . . . . . . . . . . . 127CRuleWithValue::CRuleWithValue (copy constructor). . . . . . . . . . . . . . . . . . . . . 128CRuleWithValue::~CRuleWithValue (destructor) . . . . . . . . . . . . . . . . . . . . . . . . . 128CRuleWithValue::GetRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129CRuleWithValue::GetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129CRuleWithValue::SetRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130CRuleWithValue::SetValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
CQueryWithListOfRuleValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
9/146
9
CQueryWithListOfRuleValue::CQueryWithListOfRuleValue(copy constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
CQueryWithListOfRuleValue::CQueryWithListOfRuleValue (destructor) . . . . 131CQueryWithListOfRuleValue::CQueryWithListOfRuleValue
(new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
CQueryWithListOfRuleValue::GetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132CQueryWithListOfRuleValue::GetRuleWithValueList . . . . . . . . . . . . . . . . . . . . . 133CQueryWithListOfRuleValue::SetQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133CQueryWithListOfRuleValue::SetRuleWithValueList . . . . . . . . . . . . . . . . . . . . . 133
CQueryWithRowsOfValue object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134CQueryWithRowsOfValue::CQueryWithRowsOfValue
(copy constructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134CQueryWithRowsOfValue::~CQueryWithRowsOfValue
(destructor) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134CQueryWithRowsOfValue::CQueryWithRowsOfValue
(new object constructor). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
CQueryWithRowsOfValue::GetQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135CQueryWithRowsOfValue::GetRowsOfValueList. . . . . . . . . . . . . . . . . . . . . . . . . 136CQueryWithRowsOfValue::SetQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136CQueryWithRowsOfValue::SetRowsOfValueList . . . . . . . . . . . . . . . . . . . . . . . . . 137
Index 139
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
10/146
10 Adapter Development Kit Developer’s Guide
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
11/146
BMC Atrium Core documentation 11
BMC Atrium Core documentation
This section describes the complete set of BMC Atrium Core documentation,including manuals, help systems, videos, and so on.
Unless otherwise noted, documentation is available free of charge on the BMCAtrium Core documentation media (DVD or Electronic Product Download bundle) and on the BMC Customer Support site, at http://www.bmc.com/
support.
To find this documentation on the BMC Customer Support site, choose ProductDocumentation > Supported Product A-Z List > BMC Atrium CMDB EnterpriseManager >7.6.04
Title Description Audience
Atrium Integrator 7.6.04User's Guide
Information about defining source and targetconnections, creating jobs and transformations,editing and monitoring jobs, and other AtriumIntegrator concepts.
Users who are responsiblefor setting up data transferintegrations betweenexternal data stores and
BMC Atrium CMDB.BMC Atrium CMDB 7.6.04
Administrator's GuideInformation about setting permissions, configuringfederation, modifying the data model, configuringan impact model, and other administrative tasks inBMC Atrium Configuration Management Database(BMC Atrium CMDB).
Configuration managers,application administrators,and asset analysts.
BMC Atrium CMDB 7.6.04Common Data ModelDiagram
Hierarchical diagram of all classes in the CommonData Model (CDM), including unique attributes andapplicable relationships.
Configuration managers,application administrators,and asset analysts.
BMC Atrium CMDB7.6.04 Data Model Help
Description and details of superclasses, subclasses,attributes, and relationship classes for each class.
Contains only information about the CDM at first, but you can update it to include information aboutdata model extensions that you install.
Note: This Help is provided in HTML and is availableon the BMC Atrium Core media. It is not availableon the BMC Customer Support site.
Configuration managers,application administrators,
and asset analysts.
http://www.bmc.com/supporthttp://www.bmc.com/supporthttp://www.bmc.com/supporthttp://www.bmc.com/support
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
12/146
12 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
BMC Atrium CMDB 7.6.04Data Modeling Guide
Best practices for using the classes that BMCprovides for BMC Atrium CMDB (both the CDMand extensions) to model complex business entities,focusing on the use of multiple related CIs to model
an entity rather than on general information about aclass or attribute.
Configuration managers,application administrators,and asset analysts.
BMC Atrium CMDB7.6.04 Javadoc Help
Information about Oracle Java classes, methods, andvariables that integrate with BMC Atrium CMDB.
Note: This Help is provided in HTML and is availableon the BMC Atrium Core media. It is not availableon the BMC Customer Support site.
Application programmers.
BMC Atrium CMDB 7.6.04Normalization andReconciliation Guide
Information about normalizing data in BMC AtriumCMDB and reconciling CIs from different dataproviders into a single production dataset.
Configuration managers,application administrators,and asset analysts.
BMC Atrium CMDB7.6.04 Online Help
Help for using and configuring BMC Atrium CMDB,including Atrium Integrator, BMC Atrium ProductCatalog, Reconciliation Engine, NormalizationEngine, and so on.
Note: This Help is provided in HTML and is availablethrough the Help links in the BMC Atrium CMDBuser interface. It is not available on the BMCCustomer Support site.
Configuration managers,application administrators,asset analysts, and usersthat work with CIs and needto understand therelationships that existwithin BMC Atrium CMDB.
BMC Atrium CMDB 7.6.04User's Guide
Information about using BMC Atrium CMDB,including searching for and comparing CIs andrelationships, relating CIs, viewing history, runningimpact simulations, and viewing federated data.
Users that work with CIsand need to understand therelationships that existwithin BMC Atrium CMDB.
BMC Atrium Core: TakingYour Data Into ProductionEnd to End
End-to-end high-level steps for bringing data intoBMC Atrium CMDB from a third-party source andmaking it available in your production dataset.
Note: This Flash video is available on the BMCAtrium Core media. It is not available on the BMCCustomer Support site.
Configuration managers,application administrators,and asset analysts.
BMC Atrium Core 7.6.04Compatibility Matrix
Information about the BMC Atrium Coreconfigurations that are expected to work together
based on design, testing, or general understandingof the interaction between products.
Note: Download the BMC Atrium Core 7.6.04Compatibility Matrix from the BMC CustomerSupport site at http://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=n.
Configuration managers,application administrators,and asset analysts.
Title Description Audience
http://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=nhttp://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=nhttp://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=nhttp://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=nhttp://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=nhttp://www.bmc.com/support/reg/remedy-compatibility-tables.html?c=n
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
13/146
BMC Atrium Core documentation 13
BMC Atrium Core 7.6.04Concepts and PlanningGuide
Information about CMDB concepts and high-levelsteps for planning and implementing BMC AtriumCore.
Anyone who wants to learnabout and understand BMCAtrium Core products,CMDBs in general, and the
functionality of BMCAtrium CMDB in particular.
IT leaders, configurationmanagers, applicationadministrators, and assetanalysts are some who will
benefit from thisinformation.
BMC Atrium Core 7.6.04Developer’s Reference Guide
Information about creating API programs using CAPI functions and data structures.
Application administratorsand programmers.
BMC Atrium Core 7.6.04
Installation Guide
Information about installing, upgrading, and
uninstalling BMC Atrium Core features.
Application administrators.
BMC Atrium Core 7.6.04 Master Index
Combined index of all guides. Everyone.
BMC Atrium Core 7.6.04Product Catalog and DMLGuide
Information about configuring the Product Catalogand DML, adding products, and creating aliases forproducts, manufacturers, and categorizations.
System administrators, ITmanagers, networkmanagers, and otherqualified personnel who arefamiliar with theircomputing and networkingenvironment.
BMC Atrium Core 7.6.04
Release Notes
Information about new features, known issues, and
other late-breaking topics.
Everyone.
BMC Atrium Core 7.6.04Troubleshooting Guide
Information about resolving issues with BMCAtrium Core components, including API, filter, andconsole error messages and their solutions.
Application administrators,programmers, and BMCSupport personnel.
BMC Atrium Core 7.6.04Web Services Help
Information about using BMC Atrium Core WebServices, including how to publish and findinterfaces in the Web Services Registry, set versions,disambiguate web services, configure securitypolicies and encryption, and use BMC Atrium CoreWeb Services data structures and operations.
Note: This Help is provided in HTML and is available
on the BMC Atrium Core media. It is not availableon the BMC Customer Support site.
Application administratorsand programmers.
BMC Atrium IntegrationEngine 7.6.04 ADKDeveloper's Guide
Information about how to build adapters that cantransfer information between an external data storeand either BMC Remedy AR System forms or BMCAtrium CMDB.
Developers who have a basic understanding of BMCAtrium Integration Engineand want to build adaptersthat can exchange data
between two data sources.
Title Description Audience
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
14/146
14 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
BMC Atrium IntegrationEngine 7.6.04 Online Help
Help for using and configuring BMC AtriumIntegration Engine.
Note: This Help is provided in HTML and is availablethrough the Help links in the BMC AtriumIntegration Engine user interface. It is notavailable on the BMC Customer Support site.
Users who are responsiblefor setting up data transferintegrations betweenexternal data stores and
either BMC Atrium CMDBor BMC RemedyAR System.
BMC Atrium IntegrationEngine 7.6.04 User's Guide
Information about creating data exchanges and datamappings, defining rules and queries, activatingevent-driven data exchanges, defining connectionsettings, and other BMC Atrium Integration Engineconcepts.
Users who are responsiblefor setting up data transferintegrations betweenexternal data stores andeither BMC Atrium CMDBor BMC RemedyAR System.
Mapping Your Data to
BMC Atrium CMDB 7.6.04Classes
Spreadsheet that maps common IT objects to the
appropriate class, whether part of the CDM or anextension. This spreadsheet also includesinformation about further categorizing instancesusing key attributes, and best practices for creatingnormalized relationships.
Configuration managers,
application administrators,and asset analysts.
Title Description Audience
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
15/146
Chapter 1 Understanding BMC Atrium Integration Engine 15
Chapter
1 Understanding BMC AtriumIntegration EngineThe BMC Atrium Integration Engine enables you to transfer data between anexternal data store and BMC Remedy Action Request System (BMC Remedy
AR System) forms or BMC Atrium Configuration Management Database (BMCAtrium CMDB) classes. You can use the included adapters for Microsoft SQLServer, Oracle®, IBM® DB2® Universal Database™, XML, and flat files such ascomma-separated value (CSV) files. You can also use the BMC Atrium IntegrationEngine Adapter Development Kit to build your own adapters to meet yourorganization’s specific needs.
Atrium Integrator replaces BMC Atrium Integration Engine. You can continueusing BMC Atrium Integration Engine for existing data mappings and exchanges, but BMC recommends that you use Atrium Integrator for all new data transfers.BMC Atrium Integration Engine will be deprecated in a future release.
The following topics are provided: Overview of BMC Atrium Integration Engine (page 16)
BMC Atrium Integration Engine components (page 17)
Data transfer process (page 20)
Performance considerations (page 22)
Getting started (page 23)
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
16/146
16 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
Overview of BMC Atrium Integration Engine
With BMC Atrium Integration Engine, you can schedule bulk data transfers andevent-based integrations initiated by either the source, target, or any other
application. You can also use BMC Atrium Integration Engine for initial data load,incremental data transfers, and data synchronization. You can build links betweenBMC Remedy IT Service Management (BMC Remedy ITSM) applications andEnterprise Resource Planning (ERP), Customer Relationship Management, SupplyChain Management, and other enterprise applications.
For example, you can use BMC Atrium Integration Engine to:
Synchronize IT data from a discovery application with BMC Atrium CMDB,where it can be reconciled with data from other sources to your productiondataset
Synchronize data from your Human Resources applications with employee data
in your BMC Remedy Service Desk application
Synchronize asset data tracked in BMC Remedy Asset Managementapplications with corporate asset data stored in ERP applications
Figure 1-1 shows how you can transfer data in either direction between an externaldata store and a BMC Remedy AR System application or BMC Atrium CMDBclass.
Figure 1-1: Overview of the data transfer process
During the data transfer, BMC Atrium Integration Engine identifies the records to
be transferred and performs some or all of the following tasks, depending uponhow you have configured your data exchange:
Reads records
Creates new records
Updates records
Deletes records
Data object
External data store
BMC Remedy AR System database
BMC Remedy
AR System
form
BMC Atrium
CMDB class
BMC Atrium Integration
Engine
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
17/146
Chapter 1 Understanding BMC Atrium Integration Engine 17
BMC Atrium Integration Engine components
BMC Atrium Integration Engine components
BMC Atrium Integration Engine has the following main components:
Data Exchange application (page 18)
AIE service (page 19)
Event Request interface (page 19)
Adapter Development Kit interface (page 19)
Figure 1-2 shows how these components work with other BMC Atrium IntegrationEngine components and related objects.
Figure 1-2: BMC Atrium Integration Engine components
? ? ?
Oracle database
SQL Server database
DB2 database
BMC Remedy AR Systemdatabase or BMC Atrium CMDB
Adapters provided by BMC Atrium Integration Engine
DB2 adapter
Oracle adapter
SQLadapter
XMLfile
XMLadapter
Flat file
Flat File adapter
Custom adapters (not included)
Application Pending form
Event Request interface (aiexfer)
Data Exchange application
AIE service
BMC Atrium Integration
Engine
Other data store
Other data store
Other data store
Adapter Development Kit interface
BMC Remedy AR System
APIs
BMC Atrium CMDB
APIs
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
18/146
18 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
Data Exchange application
The Data Exchange application is a group of BMC Remedy AR System forms thatis available from your BMC Remedy AR System home page as the AIE Consolelink. Use the data exchange application to work with the following integration
objects: A data exchange is the object that you execute to move data with BMC Atrium
Integration Engine, and a single execution of a data exchange is called a datatransfer. A data exchange specifies whether the external data store is the sourceor the target for a data transfer, which adapter is used, how to connect to theexternal data store, and the method used to execute the exchange. A dataexchange also specifies the conditions under which data is created, updated,and deleted.
You associate a data exchange with one or more data mappings to specify whichdata is transferred.
A data mapping defines data to be transferred. It specifies the external file ordatabase table and the BMC Remedy AR System form or BMC Atrium CMDBclass between which data is transferred, and defines the primary key thatidentifies a row of data on either side. A data mapping specifies the fields orattributes to be transferred from the source and maps them to fields or attributesin the target. It also specifies any fields or attributes in the source that should beupdated when a record in the target is created, updated, or deleted. A datamapping can limit the rows of data to be transferred from the source, updatedin the target, and updated in the source by including queries for each of theseoptions.
You use a data mapping by associating it with a data exchange.
The Data Exchange application also lets you perform the following configurationtasks:
Define external data store connection parameters for multiple data exchangessimultaneously.
Populate BMC Atrium Integration Engine menus with the names of tables andcolumns from external data stores to simplify the process of creating datamappings.
Specify the administrator user and online help path for the application.
View the BMC Atrium Integration Engine instances you defined at installationtime and edit some settings for them.
Display version numbers for BMC Atrium Integration Engine and relatedproducts.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
19/146
Chapter 1 Understanding BMC Atrium Integration Engine 19
BMC Atrium Integration Engine components
AIE service
The AIE service obtains the defined data exchange from the Data Exchangeapplication and completes the transfer of data by communicating with the adapterspecified in the data exchange definition. Adapters are software, either provided
by BMC or custom-built, that provide access to the external data and respond tocalls from BMC Atrium Integration Engine during a data exchange.
The AIE service can connect to any Microsoft Windows or UNIX® BMC RemedyAR System server. It does not need to reside on the same computer as the BMCRemedy AR System server or the external data stores, but can be on any computerthat is network-connected to both of these.
The AIE service runs as a client to the BMC Remedy AR System server using theBMC Remedy AR System application programming interface (API). Forinformation about the BMC Remedy AR System APIs, see the BMC Remedy ActionRequest System 7.6.04 C API Reference guide.
Event Request interface
You can execute a data exchange on an event-driven basis by using the EventRequest interface. Each event-driven request is created as an entry in theApplication Pending form on the BMC Remedy AR System server where the DataExchange application is installed. You create an event-driven request by directlycreating an Application Pending entry, by using BMC Remedy AR Systemworkflow to create the entry, or by invoking the aiexfer utility.
The AIE service processes requests at a scheduled interval configured in theaie.cfg file, regardless of which method was used to create the requests.
Optionally, the AIE service can handle individual event requests immediately ifyou enter them through the aiexfer utility.
Adapter Development Kit interface
The BMC Atrium Integration Engine Adapter Development Kit (ADK) contains allthe components needed to create an adapter. You use the BMC Atrium IntegrationEngine installer to install the ADK components. The ADK components are loadedduring installation and placed in a subdirectory of the BMC Atrium IntegrationEngine installation directory.
The ADK contains: A class library that defines the interface between the AIE service and an adapter.
You can use the class library as a foundation for building your adapters. Theclass library includes a base adapter class and several supporting classes. The base adapter class implements basic functionality common to all adapters anddeclares virtual functions.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
20/146
20 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
An adapter template, which is a development environment that you can use tocreate an adapter.
The ADK includes a template directory that houses the Microsoft Visual C++.NET files that you can use to construct the adapter. The files included in thisdirectory outline the logical structure for the construction of an adapter with
comments embedded as guidelines.
A sample flat file adapter, which is an implementation of an adapter for a flatfile database.
The flat file adapter is a fully functional adapter that transfers data from BMCRemedy AR System to a flat file and vice versa. A sample adapter is included soyou can use the code as an example of how to create your own adapters.
An installation control file to help build an installer for an adapter.
The installation control file is a configuration file that you can use to determinewhat is installed from the BMC Atrium Integration Engine installer.
After an adapter is complete, you can package it with BMC Atrium IntegrationEngine and then modify the BMC Atrium Integration Engine installer to includeyour adapter.
Data transfer process
When you start the AIE service, it locates data exchanges by reading entries in theData Exchange application. When BMC Atrium Integration Engine detects a dataexchange, the AIE service loads the adapter that is associated with that data
exchange.
A data transfer has two phases: the initialization phase, in which a data exchange isprepared to run, followed by the processing phase, in which the data is transferred.
Initialization phase
The initialization phase prepares a data exchange to run. The AIE service performsthe following tasks:
Step 1 Loads data exchange rules.
The AIE service loads all the rules defined in the Data Exchange application andprepares the C++ objects defined by the Adapter Developer Kit. The rules includethe data exchange definition, the data mapping rules, and all adapter-definedconfiguration parameters and rules.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
21/146
Chapter 1 Understanding BMC Atrium Integration Engine 21
Data transfer process
Step 2 Connects to data stores to validate rules.
The AIE service connects to both the source and target data stores. A BMC RemedyAR System form or BMC Atrium CMDB class can serve as either the source or thetarget.
The AIE service does not transfer data at this point, but a connection to both datastores is necessary to validate rules.
Step 3 Validates data exchange rules.
The AIE service validates rules owned by BMC Atrium Integration Engine. Duringvalidation, the AIE service indicates if any errors or warnings were detected and ifthe rules are ready to be used in a data exchange.
At the same time, the adapter is called to validate adapter-owned rules. Duringvalidation, the adapter indicates if any errors or warnings were detected and if therules are ready to be used in a data exchange.
Step 4 Disconnects from data sources.
After the rules are validated, the AIE service disconnects from both data sources.
Step 5 Starts a thread.
At the end of the initialization phase, the AIE service starts a thread to manage thedata exchange process.
During this phase, the BMC Atrium Integration Engine debug facilities record alldata exchange and data handling rules.
Processing phase
In the processing phase, the transfer of data takes place. This phase begins when adata exchange is executed, which can be scheduled or event driven.
During the processing phase, the AIE service performs the following tasks:
Step 1 Refreshes the data exchange.
Before data is exchanged, the AIE service checks the Data Exchange application todetermine if any changes were made to the data exchange definition. If changes
were made, the AIE service updates the loaded data exchange with the newdefinition.
Step 2 Starts a separate thread for each data exchange.
The AIE service connects to both the source and target data stores for each dataexchange. The AIE service communicates through the BMC Remedy AR SystemAPI or BMC Atrium CMDB API to pull data out of and push data into those datastores. The AIE service uses the adapter to pull data out of and push data into theexternal data store.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
22/146
22 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
Step 3 Locates data to be exchanged.
The AIE service obtains a list of keys from BMC Remedy AR System or BMCAtrium CMDB and prompts the adapter to create a list of keys. The AIE serviceconverts the keys to a common data type (if necessary) and then sorts the keys into
the same order so that it can compare the key lists.Step 4 Transfers data.
The AIE service compares the keys and determines from the data exchangedefinition how new and existing records should be treated. The AIE servicedecides on a key-by-key basis whether to create, update, or delete records. For eachkey, adapters can be called to read, write, update, or delete a record.
If during data transfer, the AIE service or the BMC Remedy AR System serverstops responding, BMC Atrium Integration Engine provides failover support forthe incomplete data exchanges. The next time the AIE service starts, the data
exchanges resume from the point they had stopped, thus avoiding repetition ofdata insertion.
Step 5 Disconnects from data stores.
After all keys are processed, the data transfer is considered complete. The AIEservice closes the connection to BMC Remedy AR System or BMC Atrium CMDBand prompts the adapter to close the connection to the external data store.
NOTE
The thread and adapter remain active, unless the data exchange is deactivated inthe Data Exchange application or the AIE service is terminated. In either of those
events, the adapter .dll is released and the thread terminates.
In this phase, the AIE service debug file shows all rules retrieved from the DataExchange application and the type of the data defined by the rule. The debug filealso identifies the success or failure of the data transfer and shows a detailed errormessage when any errors occur in the AIE service or in BMC Remedy AR System.
Performance considerations
Performance considerations for BMC Atrium Integration Engine are difficult toquantify because performance is affected by your network, BMC RemedyAR System, the BMC Remedy AR System server database, and the external datastore load. It is difficult to predict the effect of a specific change on BMC AtriumIntegration Engine performance, but configuration considerations can influence it.
Although it is easy to add field mappings or extra rules for each field, rememberthat each item you add is compared against every record in your database.Seemingly minor additions could have major effects if your database containsmany records. For example, if you have 1200 records in your database and thechange that you make adds an additional half-second to the run time for eachrecord, the data transfer might take an additional 10 minutes to run.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
23/146
Chapter 1 Understanding BMC Atrium Integration Engine 23
Getting started
However, you can use multiple instances, multiple sessions, and multithreading toincrease throughput and improve overall system performance. For moreinformation, see the BMC Atrium Integration Engine 7.6.04 User's Guide.
Getting startedThe following outline illustrate the high-level steps that you take to prepare fortransferring data. See the recommended area of the BMC Atrium IntegrationEngine documentation for specific instructions on each step.
NOTE
If you are working in a server group environment, make sure that you haveinstalled workflow binaries on all servers of the server group; otherwise the BMCAtrium Integration Engine workflow does not function. For more informationabout BMC Atrium Integration Engine working in a server group environment,see the BMC Atrium Integration Engine 7.6.04 User's Guide.
To get started using BMC Atrium Integration Engine
Step 1 Populate the database field menus for your external data stores using the rulehelpers in the Database Field Menus Console.
This greatly simplifies the process of creating data mappings by allowing you tochoose field names from a menu instead of manually typing them. Forinstructions, see the “Using the adapter rule helper utilities” section in the BMC Atrium Integration Engine 7.6.04 User's Guide.
Step 2 Create a data mapping to specify which data should be transferred and where itshould go.
For instructions, see the appropriate data mapping sections in the BMC AtriumIntegration Engine 7.6.04 User's Guide.
Step 3 Create a data exchange to control the execution, direction, and other characteristicsof your data transfers.
For instructions, see the data exchange section of the BMC Atrium IntegrationEngine 7.6.04 User's Guide.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
24/146
24 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
25/146
Chapter 2 Understanding the development environment 25
Chapter
2 Understanding thedevelopment environmentThe Adapter Development Kit (ADK) can reside on any system that meets therequirements of the development environment.
The following topics are provided:
Code requirements (page 26)
Compiler requirements (page 26)
Compiling an adapter template on UNIX (page 26)
Description of installed files (page 27)
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
26/146
26 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
Code requirements
The following code requirements apply to all development platforms:
The code generation must be set to multithreaded.
On Microsoft Windows, the ADK class libraries are coded in Microsoft VisualC++ .NET 2003.
Compiler requirements
This section provides a list of platforms and their compatible compilers that can beused for compiling an adapter.
The compiler requires the following platforms:
Windows—Must be compiled using Microsoft Visual C++ .NET 2003, runningon Windows 2003.
UNIX—Must be compiled with one of the following 64-bit compilers:
Sun™ Solaris™ 9 - Sun Studio™ 11 or later
HP-UX 11.11 - ANSI C++ A.03.73
HP-UX Itanium 11.23 ia64 - HP aCC++ Compiler C.05.55
IBM AIX® 5.3 - Visual Age 9.0
Linux® - GCC 4.2.1
Compiling an adapter template on UNIX
Use the following steps to compile an adapter template on a UNIX computer.
To compile an adapter template on UNIX
1 From the BMCAtriumIntegrationEngineInstallationDir/devkit/example/template directory, export the ADK environment variable to see theBMCAtriumIntegrationEngineInstallationDir/devkit directory.
2 Change the compilers for the respective environments in themakefile.unix.samp file as specified:
Solaris: Sun Studio 11
HP-UX 11.11: ANSI C++ A.03.73
HP-UX 11.23: HP aCC++ Compiler C.05.55
AIX: Visual Age 9.0
Linux: GCC 4.2.1
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
27/146
Chapter 2 Understanding the development environment 27
Description of installed files
3 Run the following commands from the command line for the respectiveenvironments.
Table 2-1: Commands to compile an adapter template on UNIX
Description of installed files
When you install the ADK, you install the following files:
Class library files
Header files
Library files
Binary files
Adapter template files
Sample flat file adapter files
Installation control file
Installing the ADK creates a series of directories under theBMCAtriumIntegrationEngineInstallationDir\devkit directory. If youinstalled in the default location, the directory structure is as shown in Table 2-2.
Operating system Command to compile an adapter template
Solaris gmake –f Makefile.unix.samp SOLARIS=1GETARCH=solsp64
HP-UX 11.11 gmake –f Makefile.unix.samp HPUX=1 GETARCH=hppa64
HP-UX 11.23 gmake –f Makefile.unix.samp HPUX=1 GETARCH=hpia64
AIX gmake –f Makefile.unix.samp AIX=1 GETARCH=aixp64
Linux gmake –f Makefile.unix.samp LINUX=1 GETARCH=lx64
Table 2-2: Directory structure of the ADK (part 1 of 2)
Directory or file name Description Windows UNIX
BMCAtriumIntegrationEngineInstallationDir\devkit (Windows)
BMCAtriumIntegrationEngineInstallati
onDir/adk (UNIX)
Overall installation directory Yes Yes
bin
release
Binary files Yes
Yes
Yes
No
example
flat file
template
Sample adapters Yes
Yes
Yes
Yes
Yes
Yes
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
28/146
28 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
The files contained in each directory installed under theBMCAtriumIntegrationEngineInstallationDir\devkit directory aredescribed in the sections that follow.
Class library files
There are three types of class library files:
Header files define all class library objects.
Library files provide all services used by the ADK.
Binary files support the sample flat file adapter.
Header files
The BMCAtriumIntegrationEngineInstallationDir\devkit\include directory contains header files, which are described in Table 2-3.
include Header files required for ADK classlibrary
Yes Yes
lib
Release
Debug
ADK class library Yes
Yes
Yes
Yes
No
Yes
Table 2-2: Directory structure of the ADK (part 2 of 2)
Directory or file name Description Windows UNIX
Table 2-3: ADK header files
Header file Description
adapter.h Defines the entry points for the adapter: InitializeAdapterDLL,TerminateAdapterDLL, CreateInstance, and DeleteInstance.
adkclass.h Defines the adapter base class: CBaseAdapter. This class is the core component for alladapters.
adksprt.h Defines the ADK support classes: CRule, CQuery, CValue, CValueList, CRowsOfValueList, CListOfRule, CListOfRuleWithValue,CRuleWithValue, CQueryWithListOfRuleValue, CQueryWithRowsOfValue. Italso includes the definitions for data types and rule types.
dataexchdef.h Defines the class that provides adapter-specific parameters defined for each data exchange:
CEIEDataExchangeDef.
eiedebug701.h Defines the debug object used to record detailed information about a data exchange:CEIEDebug.
eietrace701.h Defines the base class for debug services: CEIETrace.
jaconv.h Defines symbols for Japanese language. This is included in mbutil.h.
mbutil.h BMC internationalization header file.
templates.h Defines preprocessor symbols used by the ADK. The ADKCLASS_EXPORTS are defined inthis header file.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
29/146
Chapter 2 Understanding the development environment 29
Description of installed files
Library file
The BMCAtriumIntegrationEngineInstallationDir\devkit\lib\release directory contains a library file that is described in Table 2-4. The Visual C++project file is configured to point to the correct lib directory. The library names
depend on the environment.
Binary file
The BMCAtriumIntegrationEngineInstallationDir\devkit\bin\release directory contains a binary file that is described in Table 2-5. The adkclass76.dll
is required. The Visual C++ project file is configured to point to the correct bin directory.
Adapter template files
TheBMCAtriumIntegrationEngineInstallationDir\devkit\example\template directory contains the template files used to create adapters, which are describedin Table 2-6.
Table 2-4: ADK library file
Library file Description
Release: adkclass76.libDebug: adkclass76d.lib
Class library for the ADK. You should linkthis file with your adapter.
Table 2-5: ADK adapter binary file
Source file Description
Release: adkclass76.dll(Windows)Debug: adkclass76d.dll(Windows)adkclass.so.1 (UNIX)
Class library.
Table 2-6: ADK adapter template files (part 1 of 2)
Template files Description
dllmain.cpp Defines the entry points for the adapter template:InitializeAdapterDLL, TerminateAdapterDLL,CreateInstance, and DeleteInstance.
newadapter.vcproj (Windows)Makefile.unix.samp (UNIX)
Microsoft Visual C++ project file for building an adapter.
newadapter.sln(Windows only)
Microsoft Visual C++ project workspace for an adapter.
newadpr.cpp Adapter template skeleton of the CBaseAdapter class thatimplements the functions required by the ADK interface.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
30/146
30 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
Sample flat file adapter files
TheBMCAtriumIntegrationEngineInstallationDir\devkit\example\flatfile directory contains the sample flat file adapter files, which are described inTable 2-7.
newadpr.h Defines the adapter template class.
Readme.txt Standard Visual C++ readme file.
Table 2-6: ADK adapter template files (part 2 of 2)
Template files Description
Table 2-7: ADK sample flat file adapter files
Sample files Description
dllmain.cpp Defines the entry points for the sample: InitializeAdapterDLL,
TerminateAdapterDLL, CreateInstance, and DeleteInstance.Ffadapter.vcproj (Windows)Makefile.unix.samp (UNIX)
Microsoft Visual C++ project file for building the sample adapter.
ffadapter.sln(Windows only)
Microsoft Visual C++ project workspace for the sample adapter.
ffadapter.vcproj Microsoft Visual C++ project file for building the sample adapter.
ffadpr.cpp Sample adapter implementation of Cflat fileAdapter, which implements thefunctions required by the ADK interface.
ffadpr.h Defines the sample adapter class.filemgr.cpp File manager for the flat file database used by the sample adapter.
filemgr.h Defines the file manager for the flat file database.
getprivate.cpp GetPrivateProfileString function implementation, which is not available ona UNIX platform using the standard library.
getprivate.h GetPrivateProfileString function declaration.
Makefile.unix.sample Project file you use to build an adapter binary.
misc.cpp Helper functions used by the sample adapter.
misc.h Header file for helper functions defined in misc.cpp.
Readme.txt Standard Visual C++ readme file.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
31/146
Chapter 3 Defining the adapter rule syntax 31
Chapter
3 Defining the adapter rulesyntaxBefore building an adapter, you must define the rule syntax that your adapter willuse. The rule syntax describes the data to be retrieved from the external data store
and support queries, and collects information needed to initialize your adapter.
NOTE
The AR Mapping Information window is used in many descriptions for illustrativepurposes. You can substitute the CI Class Mapping Information window whereverthe AR Mapping Information window is used because the Primary Key Mapping,the Data Field Mapping, the Response Field Mapping, and the Query tabs (and alltheir fields) behave identically on both windows.
The following topics are provided:
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)
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
32/146
32 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
Defining the rule syntax to describe a datavalue
BMC Atrium Core has its own rule syntax that is used to obtain data from BMCRemedy AR System. Before you begin building an adapter, you must define therule syntax that your adapter will use. You use this syntax in the Data Exchangeapplication to describe the data that you want retrieved from the external datastore.
If your external data store includes tables and views, organize your rule syntaxusing the concept of containers. A container can be a file, a table, or an entire datasource. For ease of use, the AIE service allows the separate definition of a rulecontainer and an item within that container.
NOTE
For SQL Server databases, a container is a table, and the items in the container arecolumns.
You define adapter rule syntax on the Data Field Mapping tab of the AR MappingInformation window. The rules that you specify there are provided to youradapter during a data transfer. The content of each of these rules is inspected before it is placed in the CRule object. For more information about rule syntax, seethe BMC Atrium Integration Engine 7.6.04 User's Guide.
The BMC Atrium Core rule syntax includes the following reserved words:
function|
constant|
process|
targetprocess|
sql|
targetsql|
{ } (curly brackets)
The AIE service defines these reserved words as a set of rules that it recognizes,and it takes action to support these rules. All other rules are passed directly to theadapter.
You can use the words reserved for the AIE service as a part of your adapter rulesyntax.
NOTE
The reserved words must not appear at the beginning of a line of adapter rulesyntax. BMC Atrium Core places no other restrictions on the syntax that you definefor an adapter.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
33/146
Chapter 3 Defining the adapter rule syntax 33
Defining the rule syntax to support queries
Defining the rule syntax to support queries
You must define the rule syntax that you use to support queries. Queries are usedto limit the data that is transferred.
NOTE For databases that support SQL syntax, queries are supported by where clauses.
You define queries on the Query tab of a data mapping form. The followingcategories of queries are supported:
Key queries limit the records transferred in a data transfer. The AIE serviceprovides key queries to your adapter when asking the adapter for a list of keys.
Row-level queries limit the transfer of data on a row-by-row basis. The AIEservice provides row-level queries to your adapter when asking the adapter to
update or delete a row of data.
Configuring adapter initialization parameters
You must define the database connection information needed to initialize youradapter.
On the Connection Settings tab of the Data Exchanges Information window, youcan define any adapter initialization parameters that are needed to start youradapter.
The AIE service reads all adapter initialization parameters and provides them tothe adapter during initialization. Because these parameters are adapter-defined,they are not validated by BMC Atrium Core.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
34/146
34 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
Creating an adapter rule syntax list
The Data Exchange application provides an adapter rule syntax list, which allowsusers to select field names from the external data store when creating data
mappings that use this adapter. The adapter rule syntax list is populated byspecifying values on the AIE:VendorFieldNames window as shown in Figure 3-1.
Figure 3-1: AIE:VendorFieldNames window
When you create an installer for your adapter, it is helpful to populate theAIE:VendorFieldNames form during the installation process or provide a utilitythat can accomplish this task.
NOTE
If the rules in the adapter rule syntax list are fixed, it is less critical that you providea utility to populate the AIE:VendorFieldNames window because you need topopulate the list only once.
Table 3-1 provides a description of each field on the AIE:VendorFieldNames window.
Table 3-1: AIE:VendorFieldNames window field descriptions (part 1 of 2)
Field name Description
Vendor Application Must contain the name of the adapter. Enter the registered name of your adapter inthis field.
Table Name Contains the name of the container for the field name. This value is used to populate theExternal Data Store field on the Main tab of the AR Mapping Information window,which lists all adapter-defined container names.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
35/146
Chapter 3 Defining the adapter rule syntax 35
Creating an adapter rule syntax list
Field Name Contains the rule syntax for a data element used in a data transfer. Field names areobjects such as a column in a table. This field is used to populate the External Data StoreAttributes list on the Primary Key Mapping and Data Field Mapping tabs. This field is
also used to populate the External Data Store Fields list on the Response Field Mappingtab of the AR Mapping Information window.
Field Type Not presently used in creating the adapter rule syntax list.
Field Data Type Specifies the data type for a data element in a data transfer, such as FILE_INT,FILE_FLOAT, and FILE_CHAR.
Is Row Not presently used in creating the adapter rule syntax list.
Table 3-1: AIE:VendorFieldNames window field descriptions (part 2 of 2)
Field name Description
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
36/146
36 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
37/146
Chapter 4 Class library objects used by the adapter 37
Chapter
4 Class library objects used bythe adapterClass library objects, which fall into several categories, provide the servicesrequired by BMC Atrium Core to complete a data transfer. The objects are used to
transmit information between BMC Atrium Core and the adapter.
NOTE
The AR Mapping Information window is used in many descriptions for illustrativepurposes. You can substitute the CI Class Mapping Information window whereverthe AR Mapping Information window is used because the Primary Key Mapping,Data Field Mapping, Response Field Mapping, and Query tabs (and all their fields) behave identically on both windows.
The following topics are provided:
Data exchange objects (page 38)
Data objects (page 43)
List objects (page 43)
Pointer objects (page 45)
Adapter objects (page 46)
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
38/146
38 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
Data exchange objects
Data exchange objects are a group of objects that enable the adapter to initializeand communicate with the external data store. The AIE service creates data
exchange objects using information obtained from the Data Exchange application.The following class objects are data exchange objects:
CEIEDataExchangeDef
CRule
CQuery
CEIEDataExchangeDef object
The CEIEDataExchangeDef object provides certain connection settings andparameters to the adapter. The CEIEDataExchangeDef object is provided to the
adapter when the data transfer is initialized.
The CEIEDataExchangeDef object obtains the following connection settings andparameters for each data transfer:
The name of the data exchange.
The direction of the data exchange (for example, External Data into CMDB).
A Boolean value that indicates if the data exchange is schedule only orevent-driven only.
The connection parameters for the external data store and BMC Remedy
AR System. The installation directory defined in the adapter registry key used by the AIE
service. The installation directory setting is obtained from the system registry onWindows. On UNIX, a -y argument is used to provide the installation directorypath till the /service directory to the BMC Atrium Integration Engine binaries.The adapters reside in the service/bin directory.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
39/146
Chapter 4 Class library objects used by the adapter 39
Data exchange objects
Figure 4-1 shows the CEIEDataExchangeDef parameters on the Main tab of theData Exchanges Information window that are provided to the adapter.
Figure 4-1: Data Exchanges Information window—Main tab
Figure 4-2 shows the CEIEDataExchangeDef parameters that are provided to theadapter from the Connection Settings tab of the Data Exchanges Informationwindow.
Figure 4-2: Data Exchanges Information window—Connection Settings tab
NOTE
If your external data store type is a comma separated value (CSV) flat file or anXML flat file, connection parameters do not appear on the Connection Settings tab.
For more information about the Main and Connection Settings tab on the DataExchange Information window, see the BMC Atrium Integration Engine 7.6.04User's Guide.
Data exchange
name
Boolean
values
Direction of
data exchange
Parameters
Parameter
values
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
40/146
40 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
CRule object
To complete a data transfer, the adapter uses CRule objects to define the data to beobtained. Each CRule object represents the definition of a single data value used ina data transfer. The simplest form of a rule is a field name of a database table.
Each adapter must have its own rule syntax. The AIE service obtains the adapter-defined rule syntax from the Data Exchange application. Rules that apply to theadapter are packaged in CRule objects and passed to the adapter both forvalidation and to define the data to be transferred.
During the initialization phase, each CRule object is verified to make sure that therule correctly identifies an adapter data item. The data type must be set for thevalue that the CRule object represents. The data types are described in Table 4-1.
You create rules using the Primary Key Mapping, Data Field Mapping, and theResponse Field Mapping tabs on the AR Mapping Information window.
Table 4-1: Data types
Data type Description
EIE_CHAR A null-terminated string that requires freeing allocated space. ANULL pointer of this type is equivalent to usingAR_DATA_TYPE_NULL
EIE_DATE A data type that maps to the BMC Remedy AR System Date datatype
EIE_DECIMAL A fixed-point decimal value
EIE_INTEGER A 32-bit signed integer value
EIE_NULL A NULL value
EIE_REAL A 64-bit floating-point value
EIE_TIME A UNIX-style date/time stamp (number of seconds since 00:00:00
UTC, January 1, 1970)EIE_TIME_OF_DAY A field type that maps to the BMC Remedy AR System Time type
field
EIE_ULONG A 32-bit unsigned integer value
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
41/146
Chapter 4 Class library objects used by the adapter 41
Data exchange objects
The rules listed on the Primary Key Mapping tab specify the fields that uniquelyidentify a row of data. Each entry listed in the AR Form Fields table and theExternal Data Store Attributes table is packaged as an individual CRule object. TheAIE service provides the entries listed in the Mapped Fields table to the adapter asshown in Figure 4-3 on page 41.
Figure 4-3: AR Mapping Information window—Primary Key Mapping tab
The rules listed on the Data Field Mapping tab of the AR Mapping Informationwindow, shown in Figure 4-4, specify the fields that are transferred during a data
transfer. Each entry listed in the AR Form Fields table and the External Data StoreAttributes table is packaged as an individual CRule object. The AIE serviceprovides the entries listed in the Mapped Attributes table to the adapter.
Figure 4-4: AR Mapping Information window—Data Field Mapping tab
This entry is passed to
the adapter for use
during a data transfer.
These entries are
passed to the adapter
for use during a data
transfer.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
42/146
42 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
The rules listed on the Response Field Mapping tab of the AR MappingInformation window, shown in Figure 4-5, specify the fields that are transferred inresponse to a record being added or updated during an exchange. Each entry listedin the AR Form Fields table and the External Data Store Fields table is packaged asan individual CRule object. The AIE service provides the entries listed in the
Mapped Attributes table to the adapter.
Figure 4-5: AR Mapping Information window—Response Field Mapping tab
CQuery objectThe CQuery object holds a query obtained from the Query tab of the AR MappingInformation window. The CQuery object is passed to methods in theCBaseAdapter object that use the query to determine which data to include in thedata transfer.
These entries are
passed to the adapter
for use during a data
transfer.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
43/146
Chapter 4 Class library objects used by the adapter 43
Data objects
Figure 4-6 on page 43 shows a CQuery object provided by the AIE service to theadapter.
Figure 4-6: AR Mapping Information window—Query tab
Data objects
Data objects are a class of objects that enable the implementation of data transfers.
This class appears on the parameter list of the member functions. The ADK has oneData object: CValue.
The CValue object represents a single data value used in a data transfer. TheCValue object is passed to the adapter when a value is supplied in functionparameter lists. The CValue object is created by an adapter when a value isrequested.
List objects
List objects are classes of objects that combine either multiple data objects, multipledata exchange objects, or both data objects and data exchange objects. List objectsare grouped as lists when passed to the adapter as parameters. This class appearson the parameter list of the member functions.
List objects are simple Visual C++ list objects that are defined in the standardVisual C++ library.
The following class objects are list objects:
CValueList
CRowsOfValueList
The AIE service gives
the CQuery object
SALARY>200 to the
adapter.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
44/146
44 Adapter Development Kit Developer’s Guide
BMC Atrium Integration Engine 7.6.04
CListOfRule
CListOfRuleWithValue
CValueList object
The CValueList object represents the values of multiple fields or a row of datavalues. For example, keys can be composed of multiple field values. The ADKinterface represents a key as a CValueList object. This key contains one or moreCValue objects.
CRowsOfValueList object
The CRowsOfValueList object is a list of multiple CValueList objects. TheCRowsOfValueList object represents the values of multiple groups of fields ormultiple rows of data values. For example, when the adapter is called to create a
list of keys to be processed, the CRowsOfValueList object is used to represent thelist of keys.
CListOfRule object
The CListOfRule object is a list of multiple CRule objects. For example, a key can be composed of multiple fields. The ADK interface always represents thedefinition of a key as a CListOfRule object. Figure 4-7 shows a CListOfRule object.
Figure 4-7: AR Information window—Data Field Mapping tab
The ADK interface
represents the definition
of a key as a CListOfRule
object (a list of multipleCRule objects) such as
CRule: FNAME, CRule:
SALARY, and CRule:
GENDER.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Adapter Development Kit
45/146
Chapter 4 Class library objects used by the adapter 45
Pointer objects
CListOfRuleWithValue object
The CListOfRuleWithValue object is a list of multiple CRule objects and theirassociated CValue objects. That is, the CListOfRuleWithValue object contains thedefinition of the data as well as its value. The ADK interface uses this object on all
calls to get a record, create a new record, update a record, or delete a record.
Pointer objects
Pointer objects are a class of objects that point to a data transfer object and itsassociated data object. This class appears on the parameter list of the memberfunctions.
The following class objects are pointer objects:
CRuleWithValue
CQueryWithListOfRuleValue
CQueryWithRowsOfValue
CRuleWithValue object
The CRuleWithValue object points to a CRule object. The CRuleWithValue objectis passed to the adapter when a rule and its value are supplied in functionparameter lists.
Depending on the function being called, the CValue object can be initialized as anempty data value. With function calls, in which the value is passed to the adapter,the CValue object has a data value. With function calls in which the adapter isasked to supply a value, the CValue object is empty, and the adapter updates theobject with the value obtained from the external data store.
CQueryWithListOfRuleValue object
The CQueryWithListOfRuleValue object points to a CQuery object and itsassociated CListOfRuleWithValue object. CQueryWithListOfRuleValue holdsdata values that are substituted in the query.
CQueryWithRowsOfValue objectThe CQueryWithRowsOfValue object points to a CQuery object and the associatedCRowsOfValueList object. CQueryWithRowsOfValue holds data values that aresubstituted in the query.
8/20/2019 BMC Atrium Integration Engine 7.6.04 - AIE Ada